安装：
npm install -g @mindfoldhq/trellis
从 0.4.x 升级：
trellis update --migrate
（--migrate 必须加 —— breaking-change gate 会拦下没加的，详见下文"迁移流程"）
1. /start 不再是必需入口
之前每次会话开始需要 /start 加载 Trellis 上下文，再开始描述需求。现在直接自然语言描述需求就进入 Trellis 工作流，无需手动启动命令。
如果习惯先手动 start 一下再开始对话，现在 /trellis:continue 直接替代 /start 当起手命令；不放心也可以 /trellis:continue 需求是 xxx 。
2. Skill-first 架构
/start /continue /finish-work 以外的所有 Trellis 命令都变成 auto-triggered skill —— AI 看到合适的上下文会自己激活，不用你敲命令（喜欢主动节奏的用户也能继续主动唤起）。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 平台没跟上" 的漂移问题一次性消除。
3. workflow.md 是工作流唯一的源
这次最核心的重构：把工作流定义收敛到 .trellis/workflow.md 一个 markdown 文件。
之前工作流行为分散在三处：hook Python 脚本里硬编码、TS configurator 模板生成、命令 markdown 里的指令。想 fork 一份"我自己的工作流"得同时改三处才能自洽。
现在 workflow.md 是唯一事实源：Phase 1/2/3 step 内容、[workflow-state:STATUS] 面包屑标签块、Skill routing 表、task.py 16 个子命令参考。现在想修改工作流只需要改一个 markdown 文件即可。
4. /trellis:continue 命令：单任务内的 continue ，消除工作流学习成本
注意：/trellis:continue 不是跨任务的，是单个任务内的 continue 。它消除了用户对 Trellis 工作流的学习成本。
之前：用户得自己记住每一步该调哪个 slash 命令，比如 brainstorm 写 PRD → 讨论 → 让 AI 写 implement.jsonl → 调 sub-agent → check → check-cross-layer → finish-work → record-session。
现在：
- 自然语言对话进入 brainstorm 状态、创建 task
- AI 跟你确认 PRD ，你 ok 就输入
continue - AI 知道下一步是填充
implement.jsonl，填完再确认 - 你
/trellis:continue：AI 知道下一步是跑 implement + check - 你
/trellis:continue：AI 知道该update-spec - 你
/trellis:continue：AI 知道该 commit + finish-work
用户只需要自然语言 + 一路 continue就可以直接使用 trellis 工作流。底层是 /continue 读 task.json.status + artifact 状态（prd.md / implement.jsonl curation ）查表，通过 get_context.py --mode phase --step X.X 加载具体 step 的 how-to 。
5. 多窗口并行不再互相覆盖
active-task 指针从全局 .trellis/.current-task 文件改成 per-session .trellis/.runtime/sessions/<context-key>.json。多窗口并行时每个窗口独立 active task ，不再互相覆盖。
各平台的 session-key 来源：Claude Code 走 CLAUDE_ENV_FILE、Codex 用 CODEX_SESSION_ID / CODEX_THREAD_ID、Cursor 用 beforeShellExecution ticket 、OpenCode 走 Bash 前缀、Pi 注入 nested 进程。
6. Joiner onboarding：新开发者克隆 Trellis 项目自动生成入门任务
trellis init 三分支判定（基于 .trellis/ × .trellis/.developer 的存在状态）：
- 无
.trellis/→ Creator bootstrap（原有路径） .trellis/存在 + 无.developer→ Joiner（新）：自动生成00-join-<slug>任务- 都存在 → no-op
7. 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 的支持（悲）
8. Sub-agent 上下文注入
Codex / Copilot / Gemini / Qoder （ class-2 ）无法可靠地通过 hook 改写 sub-agent prompt （上游 bug 或架构限制）。这 4 个平台只能通过在 sub-agent 定义最前面加一段指令，让 sub-agent 第一轮自己 Read prd.md 和 implement.jsonl。
其它平台（ Claude / Cursor / OpenCode / Kiro / CodeBuddy / Droid ）继续走 hook 注入。
9. 每轮工作流面包屑
新增 inject-workflow-state.py 共享 hook ，每次用户消息触发一次（ 8 个平台的 UserPromptSubmit； OpenCode 走 Bun plugin 的 chat.message）。注入一个 ~200 字节的 <workflow-state> 块，根据 task.json.status 提示 AI 下一步该做什么。
面包屑内容来自 workflow.md 的 [workflow-state:STATUS] 标签块，所以魔改工作流的只需改一个 markdown 文件，不用碰 hook Python 代码。
10. SessionStart payload 重构
每次开新 session ，AI 读取的 SessionStart 块从 2.7 KB （只有 TOC + Phase Index ）升级到 9.5 KB （内联 Phase 1/2/3 每个 step 的完整 how-to ）。<guidelines> 同时从 10.9 KB 压到 4.6 KB （ spec layer index 改成 paths-only ）。总 payload 16.7 KB ，卡在 Claude Code additionalContext 的 ~20 KB 截断阈值下。
效果：AI 不用再临时 lazy-load get_context.py --mode phase --step X.Y，step 级指令第一轮就在上下文里。
11. 迁移与升级流程改进
行为 0.5.0 之前 0.5.0 Breaking-change gate 静默半迁移trellis update exit 1 ，要求加 --migrate
breaking 时 config.yaml 的 update.skip
半迁移状态（老路径留、新模板没写）
自动 bypass：safe-file-delete / 新文件 / 模板更新
Confirm prompt
通用 "Modified by you, [k]eep / [r]eplace?"
展示 What + Why prompted（ per-entry reason） + 每个选项的推荐
Backup 内容
包含 .claude/worktrees/ 等（可能数百 MB ）
排除
--dry-run 仍然绕过 gate ，可以先预览迁移计划。
12. 大规模清理（ 138 条 safe-file-delete ）
这版本移除了四类"已有更好替代"的老功能：
- iFlow 平台 —— CLI 已不再维护
- Multi-agent pipeline（
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/planagent （被 skill routing 取代）
13. Codex 用户须知
已修（ rc.5 ）：.codex/config.toml 默认开启 multi_agent_v2，min_wait_timeout_ms = 480000（ 8 分钟）wait() 超时下限 —— 阻止父线程频繁轮询子 agent 。需要 Codex CLI ≥ v0.128.0，旧版会报 untagged enum FeatureToml in features.multi_agent_v2。
Codex 上游限制（ Trellis 侧无法修复）：
- Hook context 渲染在终端（#191）—— 每轮对话都把 SessionStart hook 的 context 打印到终端，目前没有开关关闭（用 Codex desktop app 可以避免）
- Sub-agent 启动可能卡在 MCP server 上 —— 等某个慢/失败的 MCP 永远不返回，从
multi_agent_v1时期就有，v2仍未修复
doc： https://docs.trytrellis.app/zh repo: https://github.com/mindfold-ai/Trellis