Trellis v0.5.0 beta 版本测试！

历时多个迭代之后，Trellis v0.5.0 第一个可用 beta 正式上线！这是 0.4.0 GA 以来最大的一次架构换血，期待大家上手试试并反馈问题！

安装：

npm install -g @mindfoldhq/trellis@beta

从 0.4.x 升级：

trellis update --migrate

（--migrate 这次必须加，详见下文"强制迁移"）

1. Skill-first 架构

/start /continue /finish-work 以外的所有 Trellis 命令都变成 auto-triggered skill —— AI 看到合适的上下文会自己激活，不用你敲 /trellis:before-dev（另外 skill 本身也是可以由用户主动唤起触发的，所以更喜欢主动掌控节奏命令的用户仍旧可以继续使用原有流程）。5 个命令完成转换：

• before-dev / brainstorm / break-loop / check / update-spec

每个平台下，对应位置从 commands/<name>.md 迁移到 skills/trellis-<name>/SKILL.md。升级时有 65 条 rename migration 自动处理，用户本地改过的文件会在 confirm prompt 里让你选。

同时所有平台的命令和 skill 模板合并到单一源 packages/cli/src/templates/common/（3 个命令 + 5 个 skill）—— 以前 “A 平台更新了 B 平台没跟上” 的漂移问题一次性消除。

2. 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 也迁移到共享实现，删了 1435 行平台专有代码

同时我们移除了对 iflow 的支持（悲）

3. Workflow enforcement v2：每轮面包屑

新增 inject-workflow-state.py 共享 hook，每次你发消息触发一次（8 个平台的 UserPromptSubmit；OpenCode 走 Bun plugin 的 chat.message）。会注入一个 ~200 字节的 <workflow-state> 块，根据当前任务的 status 提示 AI 下一步该做什么，帮 AI 更稳地走完 plan → execute → finish 三阶段。

面包屑内容来自 workflow.md 里的 [workflow-state:STATUS] 标签块 —— fork 工作流的用户只需改一个 markdown 文件，不用碰 hook Python 代码。

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

Codex / Copilot / Gemini / Qoder（class-2）无法可靠地通过 hook 改写 sub-agent prompt（上游 bug 或架构限制）。这 4 个平台改走 pull-based prelude —— sub-agent 定义的最前面加一段指令，让 sub-agent 在第一轮自己 Read .current-task + prd.md + implement.jsonl。

Class-1 平台（Claude / Cursor / OpenCode / Kiro / CodeBuddy / Droid）继续走 hook 推送注入。两种路径都在共享基础设施里，以后新加平台挑一种就能用。

5. workflow.md：唯一的工作流 SoT

这次 0.5.0 最核心的重构 —— 把"Trellis 的工作流定义"收敛到 .trellis/workflow.md 一个 markdown 文件。

之前工作流行为分散在三处：hook Python 脚本里硬编码分支、configurator TypeScript 里的模板生成、命令 markdown 里的分步指令。想 fork 一份"我自己的工作流"得同时改三处才能自洽。

现在 workflow.md 是单一事实源（single source of truth）：

• Phase 定义：## Phase 1: Plan / ## Phase 2: Execute / ## Phase 3: Finish 三阶段 + 每阶段的 step 内容，AI 从这里读指令


• Skill routing 表：哪个场景用哪个 skill，改 workflow.md 就改路由


• Per-turn 面包屑内容：[workflow-state:no_task]...[/workflow-state:no_task] 标签块定义每个状态下 AI 该做什么


• task.py 16 个子命令的使用时机：lifecycle / context / metadata / hierarchy / PR 五组用途

Fork 工作流 = 改一个 markdown 文件。不用碰 Python、不用改 hook、不用重发包。自己团队想要"多一个 review phase"、“把 plan 拆成 A/B 两条分支”、“加一个 [workflow-state:blocked] 状态”？全在 workflow.md 里改。

workflow.md 本体也瘦身了（17 KB → 14 KB）：去掉重复段、task.py 命令表从 5 条扩到 16 条并加了 --help 指引。

同时我们引入 /continue 命令，配合上面的 workflow.md SoT + SessionStart 注入形成完整闭环。

让 ai 获取到当前的工作流进入到哪一步，以及下一步需要干什么（比如下一步应该 before-dev 还是 check 还是 update-spec），通过这个机制也可以让 ai 更好的进入 brainstorm 或者是创建 task 的流程，避免之前的 ai 跳步骤的情况（同时因为只维护唯一的 workflow 的 source of truth，也更方便大家魔改二开流程，不用费劲去各个地方修改脚本，文档）

6. SessionStart payload 重构：step 级 how-to 直接前置

每次开新 session，AI 读取的 SessionStart 块从 2.7 KB（只有 TOC + Phase Index）升级到 9.5 KB（内联 Phase 1/2/3 每个 step 的完整 how-to）。效果：

• 开场即上手：AI 不用再临时 lazy-load get_context.py --mode phase --step X.Y，step 级指令第一轮就在上下文里


• <workflow> 和 <guidelines> 一起瘦身：guidelines 从 10.9 KB 压到 4.6 KB（跨包 guides/index.md 保留内联，spec/<pkg>/<layer>/index.md 改成 paths-only；sub-agent 需要的具体 spec 走 jsonl 注入，主 agent 需要时按需读）


• 总 payload 控制在 16.7 KB，卡在 Claude Code additionalContext 的 ~20 KB 截断阈值下

加上每轮面包屑 hook（每个用户消息注入 <workflow-state> 块），AI 整个 session 的"当前该做什么"感知成本降到几乎 0。

7. /record-session 被 /finish-work 吸收

/trellis:record-session 命令移除了。它原本唯一的职责（写 session journal）现在是 /trellis:finish-work 的 Step 3，finish-work 同时覆盖 Quality Gate 和 Commit 提醒。如果你的 alias 或脚本引用了 record-session，请改成 finish-work。

8. 强制迁移 gate（–migrate 必加）

这是 breaking release，从 0.4.x 升级时 trellis update 会 exit 1 明确要求你加 --migrate：

✖ MIGRATION REQUIRED  Breaking changes between 0.4.0 → 0.5.0-beta.3 require --migrate.

  Run: trellis update --migrate

之前的行为是安静跳过 rename/delete 条目但仍然推进 .version 戳，留下"半迁移"状态（老路径和新模板并存）。新 gate 避免这种坑。

--dry-run 会绕过 gate，你可以先 trellis update --migrate --dry-run 预览。

8.1 config.yaml 里的 update.skip 自动 bypass（只有 breaking change 时会这样）

如果你在 .trellis/config.yaml 配了 update.skip（比如保护 .claude/commands/），之前升 breaking release 会卡在半迁移状态 —— 老命令留着、新命令不来。现在 gate 触发时 update.skip 会对三类操作全部 bypass：

• safe-file-delete（清理老文件）


• 新文件写入（比如 continue.md）


• 模板更新（比如 finish-work.md）

本地改过的文件仍由 “Modified by you” confirm prompt 保护，不会粗暴覆盖。顶部会有 ^-^ 黄色提示列出 bypass 的文件。

9. 大规模清理（126 条 safe-file-delete + 12 额外）

这版本移除了四类"已有更好替代"的老功能：

• iFlow 平台 —— CLI 已不再维护；整个 .iflow/ 目录移除


• Multi-agent pipeline（.trellis/scripts/multi_agent/ + worktree.yaml）—— 目前基本主流的 agent cli/ide 都有原生 worktree 支持了


• 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 写入的文件会被清。

10. 其他值得一提的改进

• Confirm prompt 重设计 —— 现在显示 What（这次 migration 做什么）+ Why prompted（为什么被 flag 成 modified，可以由 manifest 作者在 reason 字段里写版本特定的上下文）+ 每个选项的推荐场景和后果


• Backup 不再打包 .claude/worktrees/ / .cursor/worktrees/ / .gemini/worktrees/ —— 开了 worktree 后 backup 不会再膨胀到数百 MB


• SessionStart payload 从 2.7 KB 增至 9.5 KB，把 Phase 1/2/3 step body 内联进去 —— AI 一开场就有 step 级 how-to


• task.py 命令表从 5 条扩到 16 条（lifecycle / context / metadata / hierarchy / PR 分组）

v0.5.0 GA 的时间线预计看 beta 稳定性决定 —— 大的架构改动都在 beta.0 / beta.3 落地了，后续 beta 应该主要跑 bug 修复。

11. 后续 roadmap

• 加强 brainstorm 的规划，提问能力


• 对 tdd 流程提供可选模板


• 引入类似 plugin 的机制，让用户能接入自定义的外部流程