跳转到主要内容
Skill-first 架构 + 全员 hooks。 0.5 的第一个预览版同时重塑两件事：模板的组织方式（单一源，N 份输出）和 AI 遵守 workflow 的方式（每轮 hook，不再是会话首次注入）。并做了自 0.4.0 以来最大的一次清理 —— iFlow 平台、multi-agent pipeline、Ralph Loop、dispatch/debug/plan sub-agent、6 个退役命令全部移除。

​
Skill-first 模板架构

命令和 skill 现在统一放在 packages/cli/src/templates/common/（3 个命令 + 5 个 skill），作为单一事实源。13 个平台都从 common/ 经由各自的 adapter 派生。彻底消除了以前”同一内容在 N 个平台各存一份”造成的漂移 —— 以前某些命令在 A 平台更新了但 B 平台没更新的情况不再出现。 两个可复用 helper：
  • createTemplateReader()（在 template-utils.ts）—— 工厂函数，6 个平台模板模块共用，替换掉之前各自的 readFileSync 样板代码。用 fileURLToPath 正确处理带空格 / Windows 路径。
  • writeSharedHooks() + writeAgents() + writeSkills()（在 configurators/shared.ts）—— 三行调用完成 configurator 的 hook / agent / skill 输出，不再需要各自写文件拷贝循环。

​
7 个新平台升级到 agent-capable

Qoder、CodeBuddy、Factory Droid、Cursor、Gemini CLI、Kiro、GitHub Copilot 从”仅命令”升级到完整的 agent-capable 平台。每个平台都配齐：
  • Sub-agent 定义（implement / check / research），使用各平台的原生格式
  • Hook 配置基于 shared-hooks/ Python 脚本（session-start、inject-subagent-context、statusline），单一实现 + 跨平台输出 adapter
Claude Code 的 hook 也迁移到共享 hook，删除了 1,435 行平台专有实现，其中包含积累多版本的死代码（AGENT_DEBUG、spec.jsonl/research.jsonl 读取、硬编码的 check-cross-layer.md 引用）。

​
Sub-agent 上下文注入：class-1 hook vs class-2 pull-based

Codex、Copilot、Gemini、Qoder（class-2）无法可靠地通过 hook 改写 sub-agent prompt：
  • Codex PreToolUse 只对 Bash 触发；CollabAgentSpawn 未实现（#15486）
  • Copilot preToolUse 对 sub-agent 无效（#2392 / #2540）
  • Gemini BeforeTool 看不到调用方上下文（#18128）
  • Qoder 没有 Task tool + context isolation
这 4 个平台改走 pull-based prelude：sub-agent 定义的最前面加一段指令，让 sub-agent 在第一轮自己 Read .current-task + prd.md + implement.jsonl/check.jsonl。Class-1 平台（Claude / Cursor / OpenCode / Kiro / CodeBuddy / Droid）继续走 hook 推送注入。两种路径都在共享基础设施里（applyPullBasedPreludeMarkdown / applyPullBasedPreludeToml），以后加平台挑一种就能用。

​
Workflow enforcement v2：每轮面包屑 hook

新增 inject-workflow-state.py 共享 hook，每次用户发消息触发（8 平台的 UserPromptSubmit；OpenCode Bun plugin 的 chat.message）。注入 ~200 字节的 <workflow-state> 块，根据当前任务的 status 提示 AI 下一步该做什么。 面包屑内容来自 workflow.md 里的 [workflow-state:STATUS]...[/workflow-state:STATUS] 区块 —— fork 工作流的用户只需改一个 markdown 文件，不用碰 hook Python 代码。覆盖 4 种状态：no_task / planning / in_progress / completed。自定义带连字符的状态（in-review、blocked-by-team）也能识别（STATUS 正则 [A-Za-z0-9_-]+）。未知状态输出通用 fallback，而不是静默退出 —— hook 绝不会把对话”漏过”。 三档容错（workflow.md 缺失 → tag 部分缺 → status 未知），hook 不会崩。 Kiro 是唯一降级的平台：它的 agentSpawn 只针对单 sub-agent 生命周期，上游没有主会话 per-turn 的等价入口。Sub-agent 上下文注入还在工作；每轮面包屑等上游支持。

​
SessionStart payload 重构

SessionStart 的 <workflow> 块从 2.7 KB 增至 9.5 KB，inline 了 Phase 1/2/3 每个 step 的详细内容 —— AI 一开场就有 step 级 how-to，不再需要 lazy-load get_context.py --mode phase --step X.Y。腾出空间来自 <guidelines> 的精简（10.9 KB → 4.6 KB）：跨包 guides/index.md 仍然内联，但其它 spec/<pkg>/<layer>/index.md 只列路径。理由：sub-agent 通过 jsonl 注入拿到具体 spec，主 agent 需要细节时按需读。 Session-start 总 payload：16.7 KB —— 在 Claude Code 的 ~20 KB additionalContext 截断阈值下。 workflow.md 本体从 17 KB 瘦到 14 KB：改为纯英文（原先中英混排），去掉 What is Trellis 介绍、File Structure 目录树、和别处重复的 Best Practices 段，task.py 命令表从 5 条扩到 16 条（按 PR #169 的 lifecycle / context / metadata / hierarchy / PR 分组），并加了 --help 指引以便未来扩展时命令表不用同步更新。

​
大规模清理（126 条 safe-file-delete 迁移）

本版本移除四类”已有更好替代”的老功能：
  • iFlow 平台 —— CLI 已不再维护；整个 .iflow/ 目录和模板源移除
  • Multi-agent pipeline（.trellis/scripts/multi_agent/ + worktree.yaml）—— 主流 CLI 都有原生 worktree 支持，Trellis 不需要再自己实现
  • Ralph Loop hook（ralph-loop.py）—— SubagentStop + exit-code-2 强制跨平台不可移植；check sub-agent 自己的修复循环已经足够
  • 6 个命令 + 3 个 sub-agent —— parallel（被原生 worktree 取代）、onboard / create-command / integrate-skill（使用率低）、check-cross-layer（合并进 check）、record-session（被 /finish-work 吸收）；dispatch / debug / plan agent（被 skill routing 取代）
所有清理都做 hash 校验：如果你本地改过这些文件就保留并警告；只有原版 Trellis 写入的文件会被删。126 条 safe-file-delete 条目覆盖全部 13 平台（allowed_hashes 从历史 git 版本中提取，确保任何 0.3.x / 0.4.x 版本的用户都能干净迁移）。

​
Command → Skill 迁移（新增 80 条 manifest）

5 个不再由用户手动触发的 skill（before-dev / brainstorm / break-loop / check / update-spec）在所有平台下都移动到 <platform>/skills/trellis-<name>/SKILL.md。如果不做迁移，用户从 0.4.x 升上来就会出现旧命令文件和新 skill 文件同时存在。manifest 完整处理：
  • 65 条 rename（13 平台 × 5 命令）—— 用 mv 保留用户本地改动，再由后续 template-write prompt 让用户选择（不粗暴直接删）
  • 3 条 rename 处理 skill-only 平台（.kiro / .qoder / .agents 共享层）的 finish-work —— 也加上 trellis- 前缀
  • 10 条 safe-file-delete 清理老版 start 命令（agent-capable + skill-only 平台）—— session-start hook 已替代该命令
  • 2 条 safe-file-delete 移除老 improve-ut（.agent/workflows/ + .agents/skills/）
MigrationItem 新增 reason? 字段 —— 版本特定的上下文（比如”0.4.0 init 漏写这个路径的 hash，导致未改过的文件也显示 modified”）由 manifest 作者就地写入，在 confirm prompt 里渲染。不再把版本相关的硬编码塞进 update.ts 里慢慢烂掉。

​
breaking 版本现在强制 --migrate

如果项目当前版本到最新 CLI 之间跨越了 breaking: true + recommendMigrate: true 的 manifest，trellis update 会 exit 1 并明确提示用户加 --migrate。之前的行为是：安静跳过 rename/delete 条目但仍然推进 .version 戳，留下”半迁移”状态（老路径和新模板并存）。--dry-run 会绕过这个 gate，方便先预览。

​
Confirm prompt 重设计

当文件 hash 不匹配需要确认时，交互 prompt 现在显示：
  1. What —— 这条迁移在做什么（取自 manifest 的 description）
  2. Why prompted —— 每条的 reason（manifest 里写），没有就退化成通用文案
  3. 每个选项（Backup / Rename / Skip）的推荐使用场景 + 后果提示（比如 skip 会留下旧路径，未来 update 还会反复 flag）
默认选项从 skip 改为 backup-rename —— 一路 Enter 不会丢用户修改也不会留孤儿文件。

​
Bug 修复

  • Backup 不再打包平台 worktree 目录。 createFullBackup 排除任何 /worktrees/ 或 /worktree/ 路径，所以 Claude Code 的 .claude/worktrees/、Cursor 的 .cursor/worktrees/、Gemini CLI 的 .gemini/worktrees/ 不会在每次 trellis update 时都被重复快照（用户开了 worktree 后，原来一次 backup 可能轻松膨胀到数百 MB）。
  • copy-templates build 步骤残留旧模板。 build 链加上 clean（clean && tsc && copy-templates），src/ 里删掉的模板不会在 dist/ 残留、被打包发到 npm。修复前 safe-file-delete 会和 dist 里的旧模板反复打架：刚删就又被重写回去。

​
其它值得一提的改动

  • task.py create 不再写 legacy 的 current_phase / next_action 字段。FP 分析结论：workflow.md 里的 Phase N.M 是文档分层，不是运行时状态 —— task.json.status 才是任务级状态的单一事实源。
  • inject-subagent-context.py 的 update_current_phase() 函数删除 —— 它在每次 Task spawn 时回写 legacy current_phase，悄悄撤销了声明的废弃。
  • Codex hook 集成：configureCodex 现在自动写入 shared-hooks（之前跳过了）；trellis init --codex 在 stderr 打印警告提醒用户在 ~/.codex/config.toml 里设置 features.codex_hooks = true。
  • get_context.py --mode phase（不带 --step）返回 Phase Index + Phase 1/2/3 所有 step body（以前只有 Phase Index）—— 这样 agent-less 平台（Kilo / Antigravity / Windsurf）手动跑 /start 时拿到的内容和 hook 平台一致。
  • Hook 路径 CWD 稳健性（部分）：inject-workflow-state.py 从 CWD 向上查找 .trellis/，修复了该 hook 在子目录 / submodule 里 CWD 漂移的问题。所有 hook 的完整覆盖留到 beta 之后的 task。

​
Spec 文档更新

  • platform-integration.md —— 新章节：Workflow State Injection（每轮面包屑）、Subagent Context Injection: Hook-based vs Pull-based、Guidelines: Paths-only vs Inline、Per-Turn Hook 设计原则（不要静默退出）
  • quality-guidelines.md —— 新章节：Schema 字段废弃时要审计所有 writer（来自一次 Codex cross-review：cmd_create 删了字段但 hook 每次 spawn 还在回写）
  • workflow.md —— 完整英文化；结构精简；task.py 16 子命令表
  • directory-structure.md + script-conventions.md —— multi-agent 相关引用移除

​
测试

595 个 tests 全过，lint + typecheck 全绿。本周期共新加 41 个 tests：workflow-state per-turn 面包屑（7 个 case）、Phase Index 扩容、paths-only guidelines、update_current_phase 删除回归、UserPromptSubmit 平台接线 invariant、breaking-change gate（3 个 case：拦截 / dry-run 放行 / --migrate 放行）、0.5.0-beta.0 manifest 形状（65 条覆盖 / 各平台路径 invariant / breaking + recommendMigrate flag）、worktree backup 排除（12 个 case：各平台 worktree 惯例 + 用户数据 + 边界情况）。

​
延后到后续 beta / rc

  • Kiro agentSpawn hook 输出格式在真实环境验证
  • Cursor / CodeBuddy / Droid sub-agent hook 注入真实环境测试
  • 所有 hook 的完整 CWD 稳健性（含 Windows cmd / PowerShell）
  • Submodule / 微服务仓库的父子 Trellis 配置（issue #172）

​
迁移

跑 trellis update --migrate（本次 --migrate 必加 —— 68 条 rename 条目不加这个 flag 不会执行，新的 gate 也会 exit 1 提醒加上）。然后 138 条 safe-file-delete 会执行。你本地改过的文件会保留并给警告；只有原版 Trellis 写入的文件会被清理。想先预览可以先跑 trellis update --migrate --dry-run。 /trellis:record-session 用户： 这个命令被移除了。它原本唯一的职责（调 add_session.py 写 session journal）现在是 /trellis:finish-work 的 Step 3，同时 finish-work 还覆盖了 Quality Gate 和 Commit 提醒。如果你的 alias 或脚本引用了 record-session，请改成 finish-work。 Codex 用户： 在 ~/.codex/config.toml 里设置 features.codex_hooks = true 来启用 SessionStart + UserPromptSubmit 面包屑注入。不设置 flag 的话 hooks.json 会被 Codex 静默忽略。 iFlow 用户： .iflow/ 目录会被移除。如果想保留，先拷出来再跑 update。 安装：npm install -g @mindfoldhq/trellis@beta