# Yuxuanhui Development Workflow

> 适用范围：已经初始化 `.trellis/` 的项目。
>
> 设计基线：Trellis 0.6.8。本文可作为项目 `.trellis/workflow.md` 的轻量单文件覆盖版本。
>
> 定制契约参考：[Trellis 官方「定制 Workflow」](https://docs.trytrellis.app/zh/advanced/custom-workflow)。

## 0. Workflow Contract

### Instruction precedence

上层指令、项目 `AGENTS.md` 和用户当前明确要求始终优先。发生冲突时，不用 workflow 或 skill 扩大用户授权。

### Three operating modes

| Mode           | Owner                                | Use when                | Persistence                                         |
| -------------- | ------------------------------------ | ----------------------- | --------------------------------------------------- |
| Inline         | 主会话                                  | 简单、局部、根因明确、一个上下文内可完成    | 不创建 Trellis task                                    |
| Matt           | 当前匹配的工程 skill；无匹配时为主会话               | 非简单但仍可单会话完成的工程工作        | 使用现有项目产物，不强制创建 task                                 |
| Trellis + Matt | Trellis 管生命周期；当前匹配的 Matt skill 管工程方法 | 跨会话、多项稳定决策、多交付物或明确要求持久化 | task、planning artifacts、research、checkpoint、archive |

Trellis 是控制面，不替代工程方法；Matt 是方法层，不拥有 task 状态。一个阶段只选择一个方法 owner，禁止把多个完整 workflow 叠加执行。Trellis 的上下文加载、状态写入和归档动作不算第二个方法 owner。

### Lightweight override policy

本方案在项目侧覆盖 `.trellis/workflow.md`，并新增 `.codex/agents/trellis-matt-implement.toml`；配套 `AGENTS.md` 可放在全局或项目层。不要求修改 `.trellis/config.yaml`、Codex hooks 或 Trellis bundled skills。为避免旧入口重新接管流程，遵循以下覆盖规则：

- 全局 `AGENTS.md` 与本文共同拥有任务分流权；Trellis bundled skill 不得覆盖二者。
- `trellis-start` 只用于加载 context、phase 和 spec indexes；忽略其中旧的 task-consent 与固定 skill route。
- 不调用 `trellis-brainstorm` 和原生 `trellis-implement`。Planning 使用 `grill-with-docs`；Trellis Phase 2 使用 `trellis-matt-implement` 执行本工作流适配后的 Matt implementation contract。
- 不依赖 `trellis-continue` 的旧 route table；恢复逻辑以本文 `Active Task Routing` 为准。
- 不调用 `trellis-finish-work` 的旧 commit-first 流程；直接运行本文 3.5 的 `--no-commit` 命令。
- 即使 Codex hook 的 `<codex-mode>` banner 显示 Trellis sub-agent 默认值，本文对 planning/implementation 方法的明确选择优先：不得派发原生 `trellis-implement`。
- `trellis-matt-implement` 是本 workflow 明确选择的 Phase 2 execution role，默认只派发一个。每个实现切片的方法 owner 只能是 `standard` Matt contract 或显式 `/tdd` 之一；其他子 agent 仅在用户明确要求，或当前选中的 Matt skill 自身明确要求并行时启用。

### Core principles

1. **Evidence before inference** — 以当前机器、仓库、任务文件、diff 和真实命令输出为准。
2. **Minimum sufficient work** — 完成用户要求的最小充分范围，不顺手扩张，不覆盖用户已有改动。
3. **Persist only when useful** — 简单工作留在会话；跨会话状态、稳定决策和可复用证据才写入 Trellis。
4. **One lifecycle owner, one method owner** — Trellis 管状态；当前阶段只选择一个工程方法。
5. **Verification before completion claims** — 没有直接验证证据时，不声称完成、通过、可提交或可合并。
6. **No implicit external effects** — 外部写入、发送、发布、破坏性操作、付费、权限变更和实质扩张范围前必须确认。
7. **No implicit promotion or version control** — spec promotion、commit、push、PR 都不是默认收尾动作。

## 1. Request Routing

### Step A: Determine the user's authorized intent

| User intent | Default boundary |
| --- | --- |
| 回答、解释、分析、诊断、review、规划 | 只读检查并报告；不得修改产品代码或外部状态 |
| 修改、实现、构建、修复 | 完成范围内本地改动和非破坏性验证；不重复索要实现确认 |
| 外部系统写入、发布、破坏性操作、付费、权限变更、实质扩张范围 | 执行前确认 |
| spec promotion | 仅在知识稳定、可复用、已验证且用户确认后执行 |
| commit、push、PR | 仅在用户明确要求时执行；三者授权互不自动包含 |

只读请求进入 Trellis 时，可以写 task 自身的 planning/research/checkpoint 产物，但不得把“记录分析”解释成“允许修代码”。Review-only 请求即使发现问题也只报告；只有用户同时要求修复时才改。

### Step B: Choose the lifecycle mode

#### Inline

满足以下条件时直接处理，不创建 task：

- 一轮可完成的问答、解释或代码阅读；
- 局部配置、文案或单文件修改；
- 根因已经明确的小修；
- 影响范围窄、没有需要长期保存的设计决策；
- 最小验证能在当前上下文完成。

#### Matt without Trellis

不属于 Inline，但仍能在一个健康上下文内完成，且不需要持久化多项决策时：

- 按当前可用 skill 的 `description` 选择最窄、最精确的方法；
- 在主会话完成，除非所选 skill 自身明确要求并行 agent；
- 不为“显得正式”而创建 Trellis task。

#### Trellis + Matt

出现任一条件时进入 Trellis 生命周期：

- 用户明确要求使用 Trellis、长期记录或跨会话恢复；
- 工作很可能跨会话或需要 handoff；
- 存在两项及以上会影响后续实现的稳定决策；
- 一个请求包含多个可独立验证的交付物；
- 需要持久化 research、兼容/迁移方案、rollout/rollback 或重要风险；
- 当前已有匹配该请求的 active task。

若边界不确定，优先先用 Matt 单会话模式；只有在工作实际出现跨会话、独立交付物或持久决策需求时再升级为 Trellis。升级时把已确认事实、决策、剩余工作和验证证据写入 task，然后继续；不要从头重做。

### Method selection details

Trellis 生命周期内有两个固定替换：

- Phase 1 不使用 `trellis-brainstorm`；先由主会话基于证据形成 planning artifacts，再用 `grill-with-docs` review 和压实 spec。
- Phase 2 不使用原生 `trellis-implement`；派发 `trellis-matt-implement` 按已经 review 的 artifacts 执行适配后的 Matt implementation contract。

其他意图不要在本文件复制一份会过期的 Matt skill 清单。按以下顺序路由：

1. 用户明确点名且当前可用的 skill 优先。
2. 用户要求 `/tdd`、test-first、red-green-refactor 或 integration tests 时选择 `/tdd`；Trellis task 必须先持久化 `Implementation Mode: tdd` 并确认公开测试 seam。
3. 否则扫描当前可用 skill 的 `description`，匹配当前阶段的真实意图，例如需求拷问、spec/issue、实现、诊断、review、架构或 research。
4. 多个 skill 都匹配时，选择范围最窄、产物最贴近当前阶段的一个。
5. 所选 skill 的硬性门禁仍然有效；它明确要求并行 agent 时，视为允许该阶段使用子 agent。
6. 没有精确匹配时，由主会话采用标准闭环：证据 → 决策/计划 → 执行 → 验证。
7. 不得仅因为某个 skill 曾属于 Matt 的历史主流程，就调用当前不可用或不匹配的 skill。

`grill-with-docs` 当前属于显式调用型 skill；`trellis-matt-implement` 是本 workflow 选择的 Codex custom execution role，不在 sub-agent 内调用 Matt `/implement` wrapper。它按 planning artifact 中的模式执行且不得自行推断 TDD：

- `standard` 是默认方法：先完成稳定实现增量，再运行窄检查和按需补充测试；
- `tdd` 仅在用户触发且公开 seam 已确认时使用：sub-agent 显式加载 `/tdd`，按 vertical red → green slice 实施。

对应能力不可用时：

- `grill-with-docs` fallback 为 `grilling` + `domain-modeling`；
- `trellis-matt-implement` fallback 由主会话按已记录模式执行：`standard` 遵循本工作流覆盖后的 Matt contract；`tdd` 显式加载 `/tdd`。两种模式都不执行隐式 Git 写操作。

## 2. Trellis System

### Task lifecycle

```bash
python3 ./.trellis/scripts/task.py create "<title>" --slug <name>
python3 ./.trellis/scripts/task.py start <task-dir>
python3 ./.trellis/scripts/task.py current --source
python3 ./.trellis/scripts/task.py finish
python3 ./.trellis/scripts/task.py archive <task-dir> --no-commit
python3 ./.trellis/scripts/task.py list [--mine] [--status <status>]
python3 ./.trellis/scripts/task.py list-archive
```

- `create` 创建 `status=planning` 的 task；若会话标识可用，会设置 session-scoped active task。
- `start` 把 task 切到 `in_progress`；它只表示进入执行阶段，不扩大用户授权。
- `finish` 只清除当前会话指针，不改变 task status，也不表示任务完成。
- `archive --no-commit` 写入 `status=completed`、移动 task 并清除相关会话指针，但不得触碰 Git。
- 归档和 journal 始终显式传入 `--no-commit`，因此无需修改 `session_auto_commit` 默认值。
- 以 `python3 ./.trellis/scripts/task.py --help` 为 CLI 命令事实源；不要使用实际 help 中不存在的子命令。

### Planning artifacts

| Artifact | Rule |
| --- | --- |
| `prd.md` | 每个 Trellis task 必需；记录目标、事实、范围、约束、验收标准、开放决策，以及 `Testing Strategy` 中的 implementation mode / TDD seams |
| `design.md` | 跨模块、契约、兼容、迁移、安全、rollout/rollback 或存在重要技术取舍时需要 |
| `implement.md` | 多步骤、跨会话、风险较高或需要明确验证顺序时需要 |
| `research/*.md` | 只保存会影响决策且需要跨会话保留的研究；一题一文件，记录来源和结论 |
| `implement.jsonl` | `trellis-matt-implement` 的可选 context manifest；有真实 spec/research 条目时先读取，只有 seed 时允许由 agent 自行发现相关规范 |
| `check.jsonl` | 本 workflow 不使用原生 Trellis check sub-agent；保留生成的 seed 即可，不需要维护 |

`prd.md` 不放详细技术设计和执行 checklist。`design.md` 解释技术形状与取舍。`implement.md` 记录有序步骤、验证命令、风险、rollback point 和当前 checkpoint。

每个 Trellis implementation task 在 `prd.md` 中维护：

```markdown
## Testing Strategy

- Implementation Mode: standard | tdd
- Confirmed TDD Seams: Not applicable | <confirmed public seams>
```

`standard` 是默认值。只有用户明确要求 `/tdd`、test-first、red-green-refactor、integration tests，或已经 review 的 spec 明确要求 TDD 时才写 `tdd`；没有已确认 seam 时不得进入 TDD execution。

跨会话 task 的 `implement.md` 必须维护一个简短 checkpoint：

```markdown
## Current Checkpoint

- Last completed:
- Evidence:
- Next:
- Blockers:
```

Checkpoint 只记录恢复所需状态，不复述聊天过程。

### Parent / child tasks

只有当交付物能够独立规划、实现、检查和归档时才创建 child task。优先采用窄而完整的纵向切片；单纯按技术层横切通常不构成 child。

```bash
python3 ./.trellis/scripts/task.py create "<child title>" --slug <child> --parent <parent-dir>
python3 ./.trellis/scripts/task.py add-subtask <parent> <child>
python3 ./.trellis/scripts/task.py remove-subtask <parent> <child>
```

父子关系不是依赖图。阻塞顺序必须明确写在 child 的 `prd.md` 或 `implement.md`。父 task 管源需求、task map、跨 child 验收和最终集成；下一步只激活真正拥有交付物的 child。

## Phase Index

```text
Route:   Inline | Matt | Trellis + Matt
Phase 1: Plan    → persist evidence, decisions, acceptance and execution shape
Phase 2: Execute → perform only the actions authorized by the user's intent
Phase 3: Finish  → verify, evaluate knowledge, optionally use VCS, archive and report
```

### Request triage

- 无 active task 时先静默分类，不询问“要不要创建 Trellis task”这类纯流程问题。
- Inline 和 Matt 单会话工作直接开始。
- 满足 Trellis 条件时自动创建 task；用户明确要求实现/修复，已经同时授权范围内本地实现，不需要在 planning 结束后重复确认。
- 用户只要求规划、review 或诊断时，即使创建 task 也不获得产品代码修改授权。
- 若仍有用户拥有的产品、范围、兼容、风险或验收决策，只问一个最高价值问题并等待答案。
- 用户明确说“不建 task”时尊重；若范围已不适合单会话，缩小交付物或说明无法可靠持久化的风险。
- 项目不存在 `.trellis/` 时不得主动初始化，除非用户明确要求长期记录或初始化。

### Skill Routing

| User intent / phase | Route |
| --- | --- |
| 简单、局部、根因明确 | Inline；不创建 task |
| 非简单但单会话可完成 | 按当前 skill `description` 选择 Matt 方法 |
| 明确 `/tdd`、test-first、red-green-refactor 或 integration tests | `/tdd`；Trellis task 先记录 mode 并确认公开 seam |
| Trellis planning artifact review | `grill-with-docs`；不用 `trellis-brainstorm` |
| Trellis reviewed spec implementation | `trellis-matt-implement`；不用原生 `trellis-implement`；不可用时主会话执行 Matt fallback |
| 诊断、review、架构、research | 按当前 skill `description` 选择最窄匹配 |
| Trellis 状态、恢复、归档 | 本文 Phase、Active Task Routing 与 `.trellis/scripts/` |

### Phase 1 summary

- 1.0 Create or resume task `[required · once]`
- 1.1 Draft planning artifacts from evidence `[required · repeatable]`
- 1.2 Research / prototype / design inquiry `[optional · repeatable]`
- 1.3 Review spec with `grill-with-docs` `[required · once]`
- 1.4 Activate or stop at planning boundary `[required · once]`
- 1.5 Planning completion criteria

[workflow-state:no_task]
Route by `AGENTS.md`: Inline for simple work, Matt for single-session engineering, Trellis only for durable work. Do not ask task-consent questions.
[/workflow-state:no_task]

[workflow-state:no_task-inline]
Route by `AGENTS.md`; keep simple work inline. Main session is default. Create a task only for durable work; do not ask task-consent questions.
[/workflow-state:no_task-inline]

[workflow-state:planning]
Do not use `trellis-brainstorm`. Draft task artifacts, record `standard|tdd`, confirm public TDD seams when required, review with `grill-with-docs`, then route by the user's original intent.
[/workflow-state:planning]

[workflow-state:planning-inline]
Draft task artifacts, record `standard|tdd`, confirm public TDD seams when required, review with `grill-with-docs`, and sync decisions. Trellis artifacts remain task-level truth.
[/workflow-state:planning-inline]

### Phase 2 summary

- 2.1 Implement with `trellis-matt-implement` `[required · repeatable]`
- 2.2 Quality and acceptance check `[required · repeatable]`
- 2.3 Roll back to the right phase `[on demand]`

[workflow-state:in_progress]
Never dispatch native `trellis-implement`. Dispatch one `trellis-matt-implement` with `Active task`, recorded implementation mode, and confirmed TDD seams. After it returns, verify the full diff and update the checkpoint. Commit remains user-requested only.
[/workflow-state:in_progress]

[workflow-state:in_progress-inline]
Main session follows the recorded mode: adapted Matt contract for `standard`, `/tdd` for `tdd`. Dispatch neither native `trellis-implement` nor `trellis-matt-implement`. Commit only when explicitly requested.
[/workflow-state:in_progress-inline]

### Phase 3 summary

- 3.2 Debug retrospective `[on demand]`
- 3.3 Knowledge promotion decision `[required · once]`
- 3.4 Version-control actions `[on explicit request]`
- 3.5 Archive, journal and report `[required · once]`

[workflow-state:completed]
Archive and journal with `--no-commit`, then report outcome, verification and remaining risk. Never infer commit, push, PR or spec-promotion permission.
[/workflow-state:completed]

### Phase rules

1. 先识别用户授权边界，再识别 lifecycle mode 和当前 phase。
2. Phase 内按顺序执行 required steps；已有且仍有效的产物不重复生成。
3. 新证据推翻需求或设计时可以回到 Phase 1；回退后更新 owning artifact，再继续。
4. 一个阶段只有一个工程方法 owner。另一个 skill 只有在当前 owner 明确委托时才能作为子步骤运行。
5. 会话接近上下文质量边界时，先更新 task checkpoint，再切换会话；不要靠模糊摘要继续硬撑。
6. 工作中途从 Inline/Matt 升级到 Trellis 时，保留已有证据和结果，不重新执行已完成步骤。

## Phase 1: Plan

Goal：把 durable 工作变成可恢复、可验收的 task，同时不制造重复确认。

#### 1.0 Create or resume task `[required · once]`

先检查当前 task：

```bash
python3 ./.trellis/scripts/task.py current --source
```

- 当前 active task 与请求匹配：读取并继续，不新建。
- 请求不满足 Trellis 条件：退出 Trellis 路径，改走 Inline 或 Matt。
- 请求满足 Trellis 条件：直接创建 task，不询问流程性同意。

```bash
python3 ./.trellis/scripts/task.py create "<short title>" --slug <name>
```

这里只运行 `create`，不要紧接着无条件 `start`。先把用户原始意图、证据和必要 planning artifacts 写清楚。

若一个请求包含多个可独立验证交付物，先建立 parent/child map。不要仅因文件多或跨层就拆 child；交付物能独立验收才拆。

#### 1.1 Draft planning artifacts from evidence `[required · repeatable]`

1. 读取现有代码、测试、配置、文档、spec、历史 task 和 git 状态。
2. 把仓库可回答的问题直接查清，不反问用户事实。
3. 区分：已确认事实、用户意图、范围/风险决策、技术未知项、明确 out of scope。
4. 由主会话先形成 `prd.md`，并在触发条件成立时形成 `design.md`、`implement.md`。
5. 在 `prd.md` 的 `Testing Strategy` 记录 mode。默认 `standard`；用户要求 `/tdd`、test-first、red-green-refactor、integration tests 或 reviewed spec 明确要求 TDD 时记录 `tdd`，并列出待确认的公开 seam。
6. 若实现 agent 需要固定读取某些 spec/research，把真实条目加入 `implement.jsonl`；不登记产品代码。没有额外 context 时允许保留 seed，由 agent 自行发现相关规范。
7. 每次重要结论形成后立即更新 owning artifact，避免只留在聊天里。
8. 暂不使用 `trellis-brainstorm`；开放决策和 TDD seam 留给 1.3 的 `grill-with-docs` 逐项 review。

`prd.md` 至少包含：Goal、Background/Evidence、In Scope、Out of Scope、Requirements、Acceptance Criteria、Constraints、Open Decisions、Testing Strategy。

完成前做一次收敛检查：删除重复事实和已解决问题，保留所有证据锚点、约束、决策和验收映射。

#### 1.2 Research / prototype / design inquiry `[optional · repeatable]`

当技术事实无法由仓库直接回答时再 research；当状态模型、业务逻辑或 UI 必须运行/观察才能决策时才 prototype；当接口、seam、domain vocabulary 或架构形状是问题本身时选择对应设计方法。

Research 规则：

- 优先官方文档、标准、源码和一手 API；
- 按项目 `AGENTS.md` 使用指定的当前文档工具；
- 对 Trellis task，把会影响实现的结论写入 `{TASK_DIR}/research/<topic>.md`；
- 记录来源、版本/日期、结论、适用范围和未决风险；
- research 提供证据，不替用户作产品决策。

Prototype 规则：代码从一开始就视为 throwaway；保留答案，不把原型未经重新设计直接并入产品实现。

#### 1.3 Review spec with `grill-with-docs` `[required · once]`

显式加载 `grill-with-docs`，用它 review `prd.md`、条件性的 `design.md` 和 `implement.md`：

1. 先由环境证据回答事实问题，不把仓库可查事实反问用户。
2. 对产品、范围、UX、兼容、风险、验收和关键设计决策逐项 grilling。
3. 一次只问一个问题，每个问题提供推荐答案和不同选择的取舍。
4. 每个答案确认后立即同步到 owning Trellis artifact。
5. `Implementation Mode: tdd` 时，按 `/tdd` 契约确认要观察的公开 interface/seam；未确认前不写测试、不进入 Phase 2。`standard` 不询问 TDD seam。
6. `CONTEXT.md` 只记录稳定领域术语；ADR 只记录难以逆转、反直觉且经过真实取舍的决策。
7. Trellis artifacts 始终是当前 task 的 spec source of truth；不要让 glossary/ADR 复制任务细节。

`grill-with-docs` 在平台上不可直接加载时，使用其等价组合：`grilling` + `domain-modeling`。

当用户确认已经达到 shared understanding 时，本步骤完成。这个确认是 spec review 的完成条件，不再额外增加一层 Trellis implementation approval。

#### 1.4 Activate or stop at planning boundary `[required · once]`

按授权矩阵处理：

| Situation | Action |
| --- | --- |
| 用户明确要求 implement/build/fix/change；artifacts ready；无未决用户决策 | 直接运行 `task.py start` 并进入 Phase 2，不重复询问 |
| 用户只要求 plan/spec/review/diagnose | 停在授权边界；交付所请求产物或进入只读执行，不修改产品代码 |
| 所选 skill 自身有明确的人类门禁 | 遵循该门禁 |
| 涉及外部写入、破坏性操作、付费、权限、实质扩张 | 先确认对应动作 |
| artifacts 发生实质范围变化且原授权已不覆盖 | 先请求方向 |

启动命令：

```bash
python3 ./.trellis/scripts/task.py start <task-dir>
```

原始实现请求加上 1.3 的 shared-understanding 确认已经构成实现授权；不再额外增加 Trellis planning approval。

Planning-only task 的 planning 产物本身就是交付物；完成并验证后可直接进入 3.5 归档，不必为了走形式而把它切到 `in_progress`。

#### 1.5 Planning completion criteria

| Condition | Required |
| --- | :---: |
| `prd.md` 有可观察的 acceptance criteria | ✅ |
| 仓库可回答的事实已有证据 | ✅ |
| 阻塞性用户决策为空 | ✅ |
| `design.md` 在触发条件成立时存在 | ✅ |
| `implement.md` 在触发条件成立时存在并有 checkpoint | ✅ |
| research 结论已持久化（如有） | ✅ |
| `Testing Strategy` 已记录 `standard` 或 `tdd` | ✅ |
| `tdd` 模式的公开测试 seam 已由用户确认 | 条件性 ✅ |
| `grill-with-docs` review 已达到 shared understanding | ✅ |
| 当前动作仍处于用户授权范围 | ✅ |

## Phase 2: Execute

Goal：按一个明确方法完成被授权的工作，并留下可复核证据。

#### 2.1 Implement with `trellis-matt-implement` `[required · repeatable]`

执行前：

1. 读取 `prd.md`、条件性的 `design.md` / `implement.md`、相关 research。
2. 运行 package/spec discovery，读取受影响范围的 pre-development checklist 和具体规范。
3. 检查 `git status`，区分任务内改动、用户已有改动和无关并行工作。
4. 当前项目存在 `.codegraph/` 且任务属于跨文件改动、重构、影响分析或调用链排查时，按项目 `AGENTS.md` 优先使用 CodeGraph。
5. 读取 `Testing Strategy`：只接受 `standard` 或 `tdd`。`tdd` 缺 confirmed seam 时回到 1.3；不得在 Phase 2 自行选择或猜测 TDD。
6. 用 `task.py current --source` 取得当前会话的精确 task path，确认 task 与请求匹配且状态为 `in_progress`。
7. 派发一个 `trellis-matt-implement`；不得派发原生 `trellis-implement`。Dispatch prompt 必须带精确 task path、mode 和 seams：

```text
Active task: <task-path>
Implementation mode: <standard | tdd>
Confirmed TDD seams:
- <public seam, or Not applicable>
Implement only <delegated slice> from the reviewed task artifacts.
Do not change task state, dispatch another agent, or perform Git writes.
```

Agent contract：

- `trellis-matt-implement` 是 execution role，不在 sub-agent 内调用 Matt `/implement` wrapper；每个切片只能选择一种 implementation method；
- 按 `implement.jsonl` 真实条目 → `prd.md` → 条件性的 `design.md` → 条件性的 `implement.md` → 相关项目规范读取 context；
- 以已经 review 的 Trellis artifacts 作为 spec/tickets，只做被委派切片覆盖的最小充分实现；
- 不覆盖、还原或提交用户已有改动；
- 公开函数、类和复杂逻辑遵循项目注释规范，解释设计原因和关键边界；
- `standard`：不采用 TDD/test-first；先完成稳定实现增量，再运行相关单测试文件、受影响 type-check 等窄反馈，并按需在实现行为存在后补充验收/回归测试；
- `tdd`：必须显式加载 `/tdd`，只在 confirmed public seams 上按一个 failing behavior test → 最小 green implementation 的 vertical slice 循环；skill 不可加载或 seam 缺失时返回 `blocked`，不得自行降级；
- TDD red → green loop 内不做无关 refactor；把候选项交给主会话在 2.2 review 阶段处理；
- 两种模式都在切片结束时运行完整适用验证；
- 不修改 task 状态、requirements、scope 或 acceptance criteria，不执行 Git 写操作，不继续派发 agent；
- 完成后 self-review 整个被委派切片，并返回 implementation mode、confirmed seams、changed files、acceptance mapping、真实验证结果和剩余风险。

Agent 返回后，主会话必须检查报告和完整 diff，把已完成步骤、验证证据、下一步和 blocker 同步到 `implement.md` Current Checkpoint，再进入 2.2。诊断/review-only task 不得派发实现 agent 或因为“顺手”而修改产品代码。

若 custom agent 不可用、无法可靠获得 task context 或平台不支持 custom sub-agent，由主会话按已记录模式执行：`standard` 使用适配后的 Matt fallback，`tdd` 显式加载 `/tdd`。默认一次只派发一个实现 agent；只有独立 child task 或写入范围完全分离时才允许并行。任何 commit 仍只在用户明确要求后进入 3.4。

#### 2.2 Quality and acceptance check `[required · repeatable]`

检查方式取决于用户意图：

- 实现/修复任务：可以在范围内修复检查发现的问题，然后重跑验证。
- Review-only：只报告 findings，不修改。
- Diagnosis-only：报告根因、证据和建议，不实现修复。

每轮至少检查：

1. diff 与 `prd.md` acceptance criteria 的逐项映射；
2. 适用 `.trellis/spec/` 和项目规范；
3. 受影响范围的 lint、type-check、tests、build 或其他真实验收命令；
4. 跨层数据流、类型、错误传播、兼容和回归影响（如适用）；
5. 未运行的检查及原因。

最终一轮必须覆盖整个 task diff，而不是只检查最后一个 patch。记录命令、退出结果和关键输出；工具未实际运行时只能写 `not run` 或 `blocked`，不得写 `passed`。

若 implementation mode 为 `tdd`，refactor 只在本 review 阶段进行；完成后重跑受影响的行为测试和完整适用验证，确保 green 状态没有被破坏。

若所选 review skill 明确要求多个独立 review agent，则该并行是 Matt implementation method 的内部步骤。没有匹配或它无法覆盖当前未提交 diff 时，由主会话直接做完整 diff review；不要为形式再叠加 `trellis-check`。

#### 2.3 Roll back to the right phase `[on demand]`

- 新证据说明 requirement/acceptance 有误 → 回 Phase 1，更新 `prd.md`。
- 接口、兼容、迁移或架构形状有误 → 回 Phase 1，更新 `design.md` 和 `implement.md`。
- 缺技术事实 → 回 1.2 research，并持久化结论。
- 实现偏离但需求正确 → 只撤销或改正本任务自己造成的改动，再做 2.1。
- 不得用 destructive Git 命令清理工作树，不得还原无法确认归属的用户改动。

## Phase 3: Finish

Goal：用证据关闭交付物，区分任务记录、知识提升和版本控制三种不同动作。

#### 3.2 Debug retrospective `[on demand]`

只有出现重复失败、同一问题多次修复、昂贵绕路或难以建立反馈回路时才复盘。选择当前最匹配的 diagnosis/learning 方法，记录：

- 根因；
- 早期方案为何失败；
- 最终证据为何可信；
- 可以预防同类问题的候选知识。

普通任务总结不触发复盘。

#### 3.3 Knowledge promotion decision `[required · once]`

必须做“是否值得提升”的判断，但默认不修改 `.trellis/spec/` 或跨项目知识库。

候选知识只有同时满足以下条件才可 promotion：

1. 稳定：不是一次性实现细节或临时 workaround；
2. 可复用：未来任务会据此作出不同且更好的行动；
3. 已验证：有代码、测试、文档或重复证据支持；
4. 用户确认：明确同意把它提升为 spec、skill、hook、test、script 或跨项目 pattern。

未获确认时：

- 可以保留在当前 task 的 design/research/retrospective 中；
- 在最终答复中列为 promotion candidate；
- 不得自动写入 `.trellis/spec/` 或个人知识库的 canonical 区域。

用户确认后，选择当前可用的 spec/compound-learning 方法执行，并验证新增规则与当前仓库事实一致。

#### 3.4 Version-control actions `[on explicit request]`

默认跳过所有 Git 写操作。只有用户明确要求时才执行对应动作：

- commit：仅包含本任务已知改动；先检查 dirty state 和 recent history；按逻辑单元分组；默认 message 为 `<type>(scope): <中文动词短语>`，不加句号；不 amend。
- push：仅在明确要求 push 时执行；commit 授权不包含 push。
- PR：仅在明确要求创建 PR 时执行；commit/push 授权不包含 PR。

Trellis 不自动提交 task archive 或 journal；3.5 的命令始终显式使用 `--no-commit`。

#### 3.5 Archive, journal and report `[required · once]`

先判断 task 是否真的完成：acceptance criteria 已满足，必要检查已有直接证据，阻塞项为空；否则只更新 checkpoint 和风险，不 archive。

完成后归档：

```bash
python3 ./.trellis/scripts/task.py archive <task-dir> --no-commit
```

记录 session：

```bash
python3 ./.trellis/scripts/add_session.py \
  --title "<title>" \
  --summary "<outcome, verification, remaining risk>" \
  --no-commit
```

命令级 `--no-commit` 保证这两个命令只写文件，不 stage、commit 或 push，因此无需改动 `.trellis/config.yaml`。只有本次任务已经按用户明确要求生成 work commit 时，才额外传入 `--commit "<hashes>"`；否则省略该参数，不得伪造 hash。

最终答复结论先行，只保留：

1. outcome；
2. key evidence / changed files；
3. verification actually run；
4. remaining risks or blockers；
5. necessary next step（仅在确有必要时）。

没有直接验证证据时，不写“完成”“通过”“可提交”“可合并”。

## Active Task Routing

Active task 存在时，先读取 `task.json`、artifacts 和 Current Checkpoint，再按状态继续：

| Status / evidence | Resume action |
| --- | --- |
| `planning`，`prd.md` 未收敛 | 1.1 |
| `planning`，存在技术未知项 | 1.2 |
| `planning`，artifacts 尚未通过 `grill-with-docs` review | 1.3 |
| `planning`，shared understanding 已确认 | 1.4；按用户原始意图 start 或停在 planning boundary |
| `in_progress`，checkpoint 指向未完成实现/诊断/review | 2.1 |
| `in_progress`，执行完成但缺 full-scope evidence | 2.2 |
| `in_progress`，acceptance 已验证 | 3.3 → 条件性 3.4 → 3.5 |
| `completed` 仍可解析 | 3.5 report；正常 archive 后 active pointer 通常已清除 |

用户在 active task 中提出无关的简单问题时，可以 Inline 回答，不修改 task。用户明确切换到另一个 durable 工作时，先保存当前 checkpoint，再激活新 task；不要把两个需求混进同一 task。

## Runtime and Customization Invariants

1. `.trellis/workflow.md` 是 workflow 语义和 breadcrumb 文本的 source of truth。
2. 修改 required steps 时，同步更新对应 `[workflow-state:*]` block。
3. opening/closing workflow-state tag 的 status 必须完全相同；status 只使用 `[A-Za-z0-9_-]+`。
4. 不新增 custom task status，除非同时更新 status writer、breadcrumb 和本文 Active Task Routing。
5. 本 workflow 保留 Trellis 现有 Phase/step 编号，降低 `get_context.py --mode phase --step <X.Y>` 和 platform entry files 的漂移。
6. 若 bundled skill/command 与本文冲突，以用户指令、`AGENTS.md` 和本文为准；使用本文给出的底层 Trellis 命令，不修改 bundled 文件。
7. `trellis update` 之后检查 `.new` sidecar 或 template conflict，不得直接覆盖个人定制。
8. Breadcrumb 保持简短；详细规则放 Phase 正文。Phase Index 与详细 Phase 必须同步。
9. `agents/codex/trellis-matt-implement.toml` 是 custom implement agent 的共享 source of truth；项目安装位置为 `.codex/agents/trellis-matt-implement.toml`。
10. Agent 依赖 dispatch prompt 中的精确 `Active task:` 路径做 pull-based context loading；本方案不要求把新名称加入 Codex hook matcher。
11. Implementation mode 只允许 `standard` / `tdd`；`tdd` 必须同时存在用户触发和 confirmed public seam，agent 不得自行升级模式。

## Adoption Checklist

- [ ] 把本文件作为项目 `.trellis/workflow.md`。
- [ ] 把配套指引作为全局或项目 `AGENTS.md`。
- [ ] 把 `agents/codex/trellis-matt-implement.toml` 复制到项目 `.codex/agents/trellis-matt-implement.toml`。
- [ ] 用无 task、planning、in_progress 三种状态分别验证 Codex breadcrumb。
- [ ] 用 `standard` 测试 task 验证 agent 不运行 TDD，并通过 `Active task:` 读取 artifacts。
- [ ] 用 `tdd` 测试 task 验证 agent 只在 confirmed seam 上加载 `/tdd` 并执行 vertical red → green slices。
- [ ] 两种模式都验证 agent 不运行 task lifecycle 或 Git 写操作。
- [ ] 验证 `task.py archive` 和 `add_session.py` 输出包含跳过 stage/commit 的证据。
- [ ] 下一条用户消息验证 breadcrumb；新开会话验证 Phase 正文与 Skill Routing 生效。