> ## 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.6.4

> 2026-06-22

补丁版本，包含两个独立的 bug 修复：Kiro 主会话现在能确定性地激活工作流；四个 `agentCapable && !hasHooks` 平台（Codex、ZCode、OpenCode、Reasonix）终于能产出 `trellis-start`。运行 `trellis update` 刷新即可，无需 `--migrate`。

## Bug Fixes

### `agentCapable && !hasHooks` 平台缺失 `trellis-start`

`packages/cli/src/configurators/shared.ts` 里的 `filterCommands(ctx)` 当 `ctx.agentCapable` 为真时无条件过滤掉 `start`。其前提——agent-capable 平台必然有 SessionStart 类 hook 自动注入开场上下文——对 **Codex、ZCode、OpenCode、Reasonix** 不成立，这四个平台没有这类 hook。结果：用户没有任何方式加载工作流上下文（既没有 `/trellis:start` 命令，也没有 `trellis-start` skill）。

修复方式是把条件收紧为 `agentCapable && hasHooks`。标准的 `resolveAllAsSkillsNeutral` / `resolveCommands` 路径现在能在这四个平台上自然产出 `trellis-start`。

Codex 在 0.5.5 引入的一次性补丁 helper `resolveCodexTrellisStartSkill` 及其在 `configurators/codex.ts` 与 `configurators/index.ts` 的两处调用一并删除。Codex 的产物与之前 helper 写出的版本**逐字节一致**（同一模板 `common/commands/start.md`、同一 resolver、同一 wrapper），所以 `trellis update` 不会误报 user-modified。

触发源：外部用户反馈 `trellis init --zcode` 之后既没有 `/trellis:start` 也没有 `trellis-start`。

### `workflow.md` 平台矩阵缺少 ZCode 与 Reasonix

`packages/cli/src/templates/trellis/workflow.md` 共 13 个编辑点：

* **B1 / B3 / B5 / B7 / B12**（Active Task Routing、Phase 1.2 Research、Phase 1.3 Configure context、Phase 1.5 Completion criteria、Phase 2.2 Quality check）—— 在 sub-agent dispatch 平台列表中加入 `ZCode, Reasonix`。
* **B9**（Phase 2.1 implement，class-2 pull-based）—— `[codex-sub-agent]` → `[codex-sub-agent, ZCode, Reasonix]`。这两个平台都需要 codex-sub-agent block 已经强制的 `Active task:` 前缀。
* **Line 186** —— Phase Index 段的散文枚举追加 `, ZCode, Reasonix`。
* **B8 保持不变** —— 其正文写"platform hook/plugin auto-handles"，这对 pull-based 平台不成立，因此 ZCode 与 Reasonix 显式排除在外。

### Kiro 主会话工作流注入

0.6.4 之前的 Kiro 项目没有确定性的 Trellis 激活机制。三个 sub-agent JSON 注册了 `agentSpawn` hook，但主会话没有任何自有 hook，工作流根本不会启动。

支撑原始接线的"Kiro 只支持 `agentSpawn`"假设是错的。Kiro CLI 暴露了 `userPromptSubmit` 和 `agentSpawn`；IDE 也有基于文件的 `.kiro.hook`（`promptSubmit`）。0.6.4 把这两条都接上了：

* **`.kiro/agents/trellis.json`**（新增主 agent）：`userPromptSubmit` → `inject-workflow-state.py`，`agentSpawn` → `session-start.py`，`workflow.md` 声明为永远加载的资源。
* **`.kiro/hooks/trellis-workflow-state.kiro.hook`**（新增 IDE hook）：`promptSubmit` → `runCommand`。
* **`inject-workflow-state.py` + `session-start.py`** 新增隔离的 `platform == "kiro"` 分支，直接输出纯文本到 stdout（Kiro 把它加入上下文；不需要 `hookSpecificOutput` 信封）。通过 `KIRO_PROJECT_DIR` 环境变量或 `.kiro` 脚本路径识别。其他平台逐字节不变（新增隔离测试）。
* **`SHARED_HOOKS_BY_PLATFORM.kiro`** 加入 `session-start.py` 与 `inject-workflow-state.py`。

三个 sub-agent（`trellis-{implement,check,research}.json`）保持原本的 `agentSpawn → inject-subagent-context.py` 接线不变。

纯 stdout 进上下文这一契约，以及 IDE `runCommand` 的 stdout 注入行为，依据 Kiro 官方文档；真机验证仍在 pending。遇到问题的用户可以退回 `askAgent` + 静态 steering。

## Upgrade

```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```

无需 `--migrate`。

* **Kiro** 用户：`update` 会写入新的主会话 agent（`.kiro/agents/trellis.json`）、IDE hook（`.kiro/hooks/trellis-workflow-state.kiro.hook`）以及共享的 hook 脚本。
* **ZCode / OpenCode / Reasonix** 用户：`update` 会写入此前缺失的 `trellis-start` skill / `/trellis:start` 命令。
* **Codex** 用户：行为无可观测变化。`trellis-start` 现在通过标准路径产出（而不是 helper），但文件字节完全一致。