> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trytrellis.app/llms.txt
> Use this file to discover all available pages before exploring further.

# v0.5.0-beta.0

> 2026-04-20

**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`