sakibcc/obsidian-vault
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add documentation for the three-stage development workflow and CLI management strategy; create a new notes file for additional insights.

Browse Source
This commit is contained in:
yuxuanhui
2026-08-03 16:17:16 +08:00
parent 91861565bb
commit 6e0c5c35fc
14 changed files with 3122 additions and 61 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AI-RD-Workflow/40-workflows/trellis-matt/CN/AGENTS.md
+4 -2
View File
@@ -49,7 +49,7 @@
- Trellis 只管理 task 状态、planning artifacts、research、checkpoint、跨会话恢复和 archive。
- Matt 只提供当前阶段的工程方法；一个阶段只保留一个 method owner。
- Phase 1 不使用 `trellis-brainstorm`：主会话先基于证据形成 task artifacts，再用 `grill-with-docs` review spec。
- Phase 1 不使用 `trellis-brainstorm`：主会话先基于证据形成 task artifacts。普通 task 用 `grill-with-docs` review spec；已绑定并审批过的 Feishu Spec/Tickets 先做 source snapshot 一致性检查，只对 task 新增的 decision-bearing delta 使用 `grill-with-docs`。
- Phase 2 不使用原生 `trellis-implement`：由 `trellis-matt-implement` sub-agent 按已记录的 `standard|tdd` mode 执行；agent 不可用时由主会话按同一 mode fallback。
- Trellis 详细 phase、breadcrumb、恢复和归档命令以项目 `.trellis/workflow.md` 为准。
- 简单工作不建 task；项目没有 `.trellis/` 时不主动初始化，除非用户明确要求长期记录或初始化。
@@ -58,9 +58,11 @@
- Trellis task 的 `prd.md`、条件性的 `design.md` 和 `implement.md` 是 task-level spec source of truth。
- Planning artifacts 初稿应来自代码、测试、配置、文档和 task history 等证据。
- Feishu-bound task 的 Wiki Spec/Base Tickets 继续拥有产品需求、验收和关系事实；Trellis artifacts 只是执行 snapshot 与 task-local planning，不得成为第二份业务 Spec。
- 每个 Trellis implementation task 在 `prd.md` 的 `Testing Strategy` 记录 `Implementation Mode: standard|tdd`；默认 `standard`。
- 用户要求 `/tdd`、test-first、red-green-refactor、integration tests 或 reviewed spec 明确要求 TDD 时记录 `tdd`，并在进入执行前确认公开测试 seam。
- 使用 `grill-with-docs` 逐项 review 产品、范围、UX、兼容、风险、验收和关键设计决策。
- 未绑定外部已审批 Spec 时，使用 `grill-with-docs` 逐项 review 产品、范围、UX、兼容、风险、验收和关键设计决策。
- Feishu-bound task 若 snapshot 与已审批来源一致且没有新增决策，只做机械一致性检查；若 task-local planning 新增兼容、迁移、rollout/rollback、安全或执行顺序等决策，只 review delta；若改变产品需求、验收、Ticket 身份或 blocker 语义，先回写并重新批准 owning Feishu artifact。
- 一次只问一个问题；先查环境事实，只把真正属于用户的决策交给用户。
- 每个答案确认后立即同步回 owning Trellis artifact。
- `CONTEXT.md` 只保存稳定领域术语；ADR 只保存难以逆转、反直觉且经过真实取舍的决策，不复制 task spec。
AI-RD-Workflow/40-workflows/trellis-matt/CN/workflow.md
+27 -21
View File
@@ -28,7 +28,7 @@ Trellis 是控制面，不替代工程方法；Matt 是方法层，不拥有 tas
- 全局 `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-brainstorm` 和原生 `trellis-implement`。普通 Planning 使用 `grill-with-docs`；Feishu-bound task 先做 approved-source snapshot 检查，只对 decision-bearing delta 使用 `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`。
@@ -95,7 +95,7 @@ Trellis 是控制面，不替代工程方法；Matt 是方法层，不拥有 tas
Trellis 生命周期内有两个固定替换：
- Phase 1 不使用 `trellis-brainstorm`；先由主会话基于证据形成 planning artifacts，再用 `grill-with-docs` review 和压实 spec。
- Phase 1 不使用 `trellis-brainstorm`；先由主会话基于证据形成 planning artifacts。普通 task 再用 `grill-with-docs` review 和压实 spec；已审批的 Feishu-bound task 先验证 source snapshot，只 review 新增 delta。
- Phase 2 不使用原生 `trellis-implement`；派发 `trellis-matt-implement` 按已经 review 的 artifacts 执行适配后的 Matt implementation contract。
其他意图不要在本文件复制一份会过期的 Matt skill 清单。按以下顺序路由：
@@ -152,6 +152,8 @@ python3 ./.trellis/scripts/task.py list-archive
`prd.md` 不放详细技术设计和执行 checklist。`design.md` 解释技术形状与取舍。`implement.md` 记录有序步骤、验证命令、风险、rollback point 和当前 checkpoint。
Feishu-bound task 的 Wiki Spec/Base Tickets 继续拥有产品需求、验收、身份和关系事实。Trellis `prd.md`/`implement.md`保存可恢复的执行 snapshot 与 task-local planning：必须记录稳定 record IDs、来源更新时间/Wiki revision（可用时）、Ticket 集合和关系。它们不得静默覆盖飞书来源，也不得要求用户仅因内容被复制到 Trellis 就再次全文审批。
每个 Trellis implementation task 在 `prd.md` 中维护：
```markdown
@@ -214,7 +216,7 @@ Phase 3: Finish → verify, evaluate knowledge, optionally use VCS, archive and
| 简单、局部、根因明确 | 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 planning artifact review | 普通 task 用 `grill-with-docs`；Feishu-bound task 做 snapshot check，只对 delta 用 `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/` |
@@ -224,7 +226,7 @@ Phase 3: Finish → verify, evaluate knowledge, optionally use VCS, archive and
- 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.3 Review spec or source delta `[required · once]`
- 1.4 Activate or stop at planning boundary `[required · once]`
- 1.5 Planning completion criteria
@@ -237,11 +239,11 @@ Route by `AGENTS.md`; keep simple work inline. Main session is default. Create a
[/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.
Do not use `trellis-brainstorm`. Draft task artifacts, record `standard|tdd`, confirm public TDD seams when required, then review the full spec or only the approved-source delta as applicable before routing 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.
Draft task artifacts, record `standard|tdd`, confirm public TDD seams when required, and review the full spec or only the approved-source delta as applicable. Feishu-bound artifacts remain execution snapshots; unbound Trellis artifacts remain task-level truth.
[/workflow-state:planning-inline]
### Phase 2 summary
@@ -312,6 +314,7 @@ python3 ./.trellis/scripts/task.py create "<short title>" --slug <name>
6. 若实现 agent 需要固定读取某些 spec/research，把真实条目加入 `implement.jsonl`；不登记产品代码。没有额外 context 时允许保留 seed，由 agent 自行发现相关规范。
7. 每次重要结论形成后立即更新 owning artifact，避免只留在聊天里。
8. 暂不使用 `trellis-brainstorm`；开放决策和 TDD seam 留给 1.3 的 `grill-with-docs` 逐项 review。
9. Feishu-bound task 读取并记录最新 Spec/Ticket record IDs、更新时间、Wiki revision（可用时）、验收和 blocker 集，作为后续 snapshot/delta 比较基线；不把 copied source 当成新 Spec。
`prd.md` 至少包含：Goal、Background/Evidence、In Scope、Out of Scope、Requirements、Acceptance Criteria、Constraints、Open Decisions、Testing Strategy。
@@ -331,21 +334,24 @@ Research 规则：
Prototype 规则：代码从一开始就视为 throwaway；保留答案，不把原型未经重新设计直接并入产品实现。
#### 1.3 Review spec with `grill-with-docs` `[required · once]`
#### 1.3 Review spec or source delta `[required · once]`
显式加载 `grill-with-docs`，用它 review `prd.md`、条件性的 `design.md` 和 `implement.md`：
先判断 task 是否绑定已经过审批的 Feishu Spec/Tickets：
- **普通 task**：显式加载 `grill-with-docs`，review `prd.md`、条件性的 `design.md` 和 `implement.md`。
- **Feishu-bound，snapshot-only**：比较稳定 IDs、Base 更新时间、Wiki revision（可用时）、完整 Ticket 集、parent/blocker、验收和 task-local 文本。完全一致且没有新增决策时，只记录 `snapshot-only / No decision-bearing delta`，不重复全文 grilling。
- **Feishu-bound，delta-reviewed**：只把 task-local planning 新增或改变的兼容、迁移、rollout/rollback、安全、seam 或执行顺序等 decision-bearing delta 交给 `grill-with-docs`，确认后记录 delta 和来源版本。
- **source-revision-required**：若 task-local planning 改变产品行为、范围、验收、Ticket 身份、parent 或 blocker 语义，停止激活；先修订并批准 owning Wiki Spec/Base Tickets，再刷新 snapshot。
Review 时遵守：
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 复制任务细节。
2. 一次只问一个决定性问题，每题提供推荐答案和选择取舍。
3. 每个答案确认后立即同步到 owning artifact；产品/验收写回飞书来源，执行决策写入 Trellis。
4. `Implementation Mode: tdd` 时，按 `/tdd` 契约确认公开 interface/seam；未确认前不写测试、不进入 Phase 2。`standard` 不询问 TDD seam。
5. `CONTEXT.md` 只记录稳定领域术语；ADR 只记录难以逆转、反直觉且经过真实取舍的决策。
`grill-with-docs` 在平台上不可直接加载时，使用其等价组合：`grilling` + `domain-modeling`。
当用户确认已经达到 shared understanding 时，本步骤完成。这个确认是 spec review 的完成条件，不再额外增加一层 Trellis implementation approval。
`grill-with-docs` 在平台上不可直接加载时，使用其等价组合：`grilling` + `domain-modeling`。普通 task 在 shared understanding 后完成本步骤；Feishu-bound task 在 snapshot/delta disposition 已记录且无 unresolved delta 后完成。两者都不再增加额外的 Trellis implementation approval。
#### 1.4 Activate or stop at planning boundary `[required · once]`
@@ -365,7 +371,7 @@ Prototype 规则：代码从一开始就视为 throwaway；保留答案，不把
python3 ./.trellis/scripts/task.py start <task-dir>
```
原始实现请求加上 1.3 的 shared-understanding 确认已经构成实现授权；不再额外增加 Trellis planning approval。
原始实现请求加上 1.3 的 review completion（普通 task 的 shared understanding，或 Feishu-bound task 的有效 snapshot/delta disposition）已经构成实现授权；不再额外增加 Trellis planning approval。
Planning-only task 的 planning 产物本身就是交付物；完成并验证后可直接进入 3.5 归档，不必为了走形式而把它切到 `in_progress`。
@@ -381,7 +387,7 @@ Planning-only task 的 planning 产物本身就是交付物；完成并验证后
| research 结论已持久化（如有） | ✅ |
| `Testing Strategy` 已记录 `standard` 或 `tdd` | ✅ |
| `tdd` 模式的公开测试 seam 已由用户确认 | 条件性 ✅ |
| `grill-with-docs` review 已达到 shared understanding | ✅ |
| 普通 task 已达到 shared understanding；Feishu-bound task 已记录有效 snapshot/delta disposition | ✅ |
| 当前动作仍处于用户授权范围 | ✅ |
## Phase 2: Execute
@@ -540,8 +546,8 @@ Active task 存在时，先读取 `task.json`、artifacts 和 Current Checkpoint
| --- | --- |
| `planning`，`prd.md` 未收敛 | 1.1 |
| `planning`，存在技术未知项 | 1.2 |
| `planning`，artifacts 尚未通过 `grill-with-docs` review | 1.3 |
| `planning`，shared understanding 已确认 | 1.4；按用户原始意图 start 或停在 planning boundary |
| `planning`，普通 artifacts 尚未 review，或 Feishu snapshot/delta disposition 缺失/已失效 | 1.3 |
| `planning`，1.3 review completion 已满足 | 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 |
AI-RD-Workflow/40-workflows/trellis-matt/EN/AGENTS.md
+4 -3
View File
@@ -49,18 +49,19 @@ Handle the following directly without creating a Trellis task:
- Trellis manages only task state, planning artifacts, research, checkpoints, cross-session recovery, and archiving.
- Matt provides only the engineering method for the current phase. Keep exactly one method owner per phase.
- Do not use `trellis-brainstorm` in Phase 1. The main session first drafts task artifacts from evidence, then reviews the spec with `grill-with-docs`.
- Do not use `trellis-brainstorm` in Phase 1. The main session first drafts task artifacts from evidence. Review a normal task's spec with `grill-with-docs`; for an approved Feishu-bound Spec/Ticket set, verify source-snapshot equivalence and use `grill-with-docs` only for decision-bearing task-local deltas.
- Do not use the native `trellis-implement` in Phase 2. The `trellis-matt-implement` sub-agent executes the recorded `standard|tdd` mode; if the agent is unavailable, the main session falls back using the same mode.
- Follow the project's `.trellis/workflow.md` for detailed phases, breadcrumbs, recovery, and archive commands.
- Do not create a task for simple work. If the project has no `.trellis/`, do not initialize it unless the user explicitly asks for durable records or initialization.
## Planning Method
- A Trellis task's `prd.md` and conditional `design.md` and `implement.md` are the task-level source of truth for the spec.
- A Trellis task's `prd.md` and conditional `design.md` and `implement.md` are the task-level source of truth for an unbound task. For a Feishu-bound task, approved Wiki/Base artifacts remain the business source while Trellis stores an execution snapshot and task-local planning.
- Initial planning artifacts should come from evidence in code, tests, configuration, documentation, and task history.
- Every Trellis implementation task records `Implementation Mode: standard|tdd` under `Testing Strategy` in `prd.md`; `standard` is the default.
- Record `tdd` when the user requests `/tdd`, test-first, red-green-refactor, or integration tests, or when the reviewed spec explicitly requires TDD, and confirm public test seams before execution.
- Use `grill-with-docs` to review product, scope, UX, compatibility, risk, acceptance, and key design decisions one by one.
- When there is no approved external Spec, use `grill-with-docs` to review product, scope, UX, compatibility, risk, acceptance, and key design decisions one by one.
- If a Feishu-bound snapshot matches the approved sources and adds no decision, perform only a mechanical consistency check. Review only task-local compatibility, migration, rollout/rollback, security, or sequencing deltas. If planning changes product requirements, acceptance, Ticket identity, or blocker semantics, revise and re-approve the owning Feishu artifact first.
- Ask one question at a time. Investigate environmental facts first and ask the user only for decisions that genuinely belong to them.
- After each answer is confirmed, immediately synchronize it back to the owning Trellis artifact.
- `CONTEXT.md` stores only durable domain terminology. ADRs store only decisions that are hard to reverse, counterintuitive, and based on a real tradeoff; they must not duplicate the task spec.
AI-RD-Workflow/40-workflows/trellis-matt/EN/workflow.md
+27 -21
View File
@@ -28,7 +28,7 @@ At project level, this setup overrides `.trellis/workflow.md` and adds `.codex/a
- Global `AGENTS.md` and this document jointly own task routing. Trellis bundled skills must not override either one.
- Use `trellis-start` only to load context, phase, and spec indexes. Ignore its legacy task-consent and fixed skill routing.
- Do not call `trellis-brainstorm` or the native `trellis-implement`. Planning uses `grill-with-docs`; Trellis Phase 2 uses `trellis-matt-implement` to execute the Matt implementation contract adapted by this workflow.
- Do not call `trellis-brainstorm` or the native `trellis-implement`. Normal planning uses `grill-with-docs`; a Feishu-bound task first checks its approved-source snapshot and uses `grill-with-docs` only for decision-bearing deltas. Trellis Phase 2 uses `trellis-matt-implement` to execute the Matt implementation contract adapted by this workflow.
- Do not depend on the legacy route table in `trellis-continue`. Use this document's `Active Task Routing`.
- Do not call the legacy commit-first flow in `trellis-finish-work`. Run the `--no-commit` commands in section 3.5 directly.
- Even if a Codex hook's `<codex-mode>` banner shows Trellis sub-agent defaults, the explicit planning and implementation method selected here takes precedence. Never dispatch the native `trellis-implement`.
@@ -95,7 +95,7 @@ When the boundary is uncertain, prefer Matt in a single session first. Upgrade t
The Trellis lifecycle has two fixed substitutions:
- Phase 1 does not use `trellis-brainstorm`. The main session first drafts planning artifacts from evidence, then uses `grill-with-docs` to review and tighten the spec.
- Phase 1 does not use `trellis-brainstorm`. The main session first drafts planning artifacts from evidence. It then reviews and tightens a normal task's spec with `grill-with-docs`; an approved Feishu-bound task verifies its source snapshot and reviews only new deltas.
- Phase 2 does not use the native `trellis-implement`. Dispatch `trellis-matt-implement` to execute the adapted Matt implementation contract from the reviewed artifacts.
For other intents, do not copy a Matt skill list into this file where it can become stale. Route in this order:
@@ -152,6 +152,8 @@ python3 ./.trellis/scripts/task.py list-archive
Do not put detailed technical design or an execution checklist in `prd.md`. `design.md` explains the technical shape and tradeoffs. `implement.md` records ordered steps, verification commands, risks, rollback points, and the current checkpoint.
For a Feishu-bound task, the Wiki Spec/Base Tickets remain authoritative for product requirements, acceptance, identity, and relationships. Trellis `prd.md`/`implement.md` hold a recoverable execution snapshot and task-local planning: record stable record IDs, source update times/Wiki revision when available, the Ticket set, and relationships. They must not silently overwrite the Feishu sources or require a second full approval merely because approved content was copied into Trellis.
Every Trellis implementation task maintains this in `prd.md`:
```markdown
@@ -214,7 +216,7 @@ Phase 3: Finish → verify, evaluate knowledge, optionally use VCS, archive and
| Simple, local, root cause known | Inline; no task |
| Not simple but completable in one session | Select a Matt method from current skill `description` values |
| Explicit `/tdd`, test-first, red-green-refactor, or integration tests | `/tdd`; for Trellis, first record the mode and confirm public seams |
| Trellis planning artifact review | `grill-with-docs`; do not use `trellis-brainstorm` |
| Trellis planning artifact review | Normal task: `grill-with-docs`; Feishu-bound task: snapshot check and `grill-with-docs` only for deltas; do not use `trellis-brainstorm` |
| Trellis reviewed-spec implementation | `trellis-matt-implement`; do not use the native `trellis-implement`; use the main-session Matt fallback when unavailable |
| Diagnosis, review, architecture, or research | Select the narrowest match from current skill `description` values |
| Trellis state, recovery, or archive | This document's phases, `Active Task Routing`, and `.trellis/scripts/` |
@@ -224,7 +226,7 @@ Phase 3: Finish → verify, evaluate knowledge, optionally use VCS, archive and
- 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.3 Review spec or source delta `[required · once]`
- 1.4 Activate or stop at planning boundary `[required · once]`
- 1.5 Planning completion criteria
@@ -237,11 +239,11 @@ Route by `AGENTS.md`; keep simple work inline. Main session is default. Create a
[/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.
Do not use `trellis-brainstorm`. Draft task artifacts, record `standard|tdd`, confirm public TDD seams when required, then review the full spec or only the approved-source delta as applicable before routing 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.
Draft task artifacts, record `standard|tdd`, confirm public TDD seams when required, and review the full spec or only the approved-source delta as applicable. Feishu-bound artifacts remain execution snapshots; unbound Trellis artifacts remain task-level truth.
[/workflow-state:planning-inline]
### Phase 2 summary
@@ -312,6 +314,7 @@ If one request contains multiple independently verifiable deliverables, first cr
6. If the implementation agent must read specific specs or research, add real entries to `implement.jsonl`; do not register product code. When no extra context is needed, the seed may remain and the agent discovers relevant standards itself.
7. After every important conclusion, immediately update the owning artifact so that it does not live only in the conversation.
8. Do not use `trellis-brainstorm`. Leave open decisions and TDD seams for item-by-item review with `grill-with-docs` in step 1.3.
9. For a Feishu-bound task, record the latest Spec/Ticket record IDs, update times, Wiki revision when available, acceptance, and blocker set as the baseline for later snapshot/delta comparison. Do not treat copied source content as a new Spec.
At minimum, `prd.md` contains: Goal, Background/Evidence, In Scope, Out of Scope, Requirements, Acceptance Criteria, Constraints, Open Decisions, and Testing Strategy.
@@ -331,21 +334,24 @@ Research rules:
Prototype rule: treat prototype code as throwaway from the beginning. Keep the answer, but do not merge the prototype into the product implementation without redesigning it.
#### 1.3 Review spec with `grill-with-docs` `[required · once]`
#### 1.3 Review spec or source delta `[required · once]`
Explicitly load `grill-with-docs` and use it to review `prd.md` plus conditional `design.md` and `implement.md`:
First determine whether the task is bound to an already approved Feishu Spec/Ticket set:
1. Answer factual questions from environmental evidence first. Do not ask the user for facts that can be found in the repository.
2. Grill product, scope, UX, compatibility, risk, acceptance, and key design decisions one by one.
3. Ask one question at a time. Each question includes a recommended answer and the tradeoffs of alternative choices.
4. After each answer is confirmed, immediately synchronize it to the owning Trellis artifact.
5. When `Implementation Mode: tdd`, use the `/tdd` contract to confirm the public interface/seam to observe. Do not write tests or enter Phase 2 before confirmation. Do not ask about TDD seams in `standard` mode.
6. `CONTEXT.md` records only durable domain terminology. An ADR records only a decision that is hard to reverse, counterintuitive, and based on a real tradeoff.
7. Trellis artifacts remain the source of truth for the current task spec. Do not duplicate task details in the glossary or ADRs.
- **Normal task**: explicitly load `grill-with-docs` and review `prd.md` plus conditional `design.md` and `implement.md`.
- **Feishu-bound, snapshot-only**: compare stable IDs, Base update times, Wiki revision when available, the complete Ticket set, parent/blocker relationships, acceptance, and task-local text. If they match and add no decision, record `snapshot-only / No decision-bearing delta`; do not repeat full-text grilling.
- **Feishu-bound, delta-reviewed**: give `grill-with-docs` only the decision-bearing compatibility, migration, rollout/rollback, security, seam, or sequencing text that task-local planning added or changed. Record the confirmed delta and source version.
- **source-revision-required**: if task-local planning changes product behavior, scope, acceptance, Ticket identity, parent, or blocker semantics, stop activation. Revise and approve the owning Wiki Spec/Base Tickets first, then refresh the snapshot.
If `grill-with-docs` cannot be loaded directly on the platform, use the equivalent combination `grilling` + `domain-modeling`.
During review:
This step is complete when the user confirms shared understanding. That confirmation completes the spec review; do not add another Trellis implementation-approval layer.
1. Answer factual questions from environment evidence rather than asking the user.
2. Ask one decision-bearing question at a time and provide a recommended answer plus tradeoffs.
3. Sync each confirmed answer into the owning artifact immediately: product/acceptance decisions go back to Feishu; execution decisions go to Trellis.
4. When `Implementation Mode: tdd`, confirm the public interface/seam according to the `/tdd` contract. Do not write tests or enter Phase 2 before confirmation. `standard` does not ask for a TDD seam.
5. `CONTEXT.md` stores only stable domain vocabulary. ADRs store only decisions that are hard to reverse, surprising, and the result of a real tradeoff.
If `grill-with-docs` cannot be loaded directly on the platform, use the equivalent combination `grilling` + `domain-modeling`. A normal task completes this step at shared understanding; a Feishu-bound task completes it when the snapshot/delta disposition is recorded and no unresolved delta remains. Neither path adds another Trellis implementation approval.
#### 1.4 Activate or stop at planning boundary `[required · once]`
@@ -365,7 +371,7 @@ Start command:
python3 ./.trellis/scripts/task.py start <task-dir>
```
The original implementation request plus the shared-understanding confirmation in step 1.3 constitutes implementation authorization. Do not add another Trellis planning approval.
The original implementation request plus step 1.3 review completion—shared understanding for a normal task, or a valid snapshot/delta disposition for a Feishu-bound task—constitutes implementation authorization. Do not add another Trellis planning approval.
For a planning-only task, the planning artifacts are themselves the deliverable. Once completed and verified, the task may go directly to archive in step 3.5 without being moved to `in_progress` merely for formality.
@@ -381,7 +387,7 @@ For a planning-only task, the planning artifacts are themselves the deliverable.
| Research conclusions have been persisted, if any | ✅ |
| `Testing Strategy` records `standard` or `tdd` | ✅ |
| Public test seams have been confirmed by the user in `tdd` mode | Conditional ✅ |
| `grill-with-docs` review reached shared understanding | ✅ |
| Normal task reached shared understanding; Feishu-bound task has a valid recorded snapshot/delta disposition | ✅ |
| The current action remains within user authorization | ✅ |
## Phase 2: Execute
@@ -540,8 +546,8 @@ When an active task exists, first read `task.json`, its artifacts, and Current C
| --- | --- |
| `planning`, `prd.md` has not converged | 1.1 |
| `planning`, technical unknowns remain | 1.2 |
| `planning`, artifacts have not passed `grill-with-docs` review | 1.3 |
| `planning`, shared understanding has been confirmed | 1.4; start or stop at the planning boundary according to the user's original intent |
| `planning`, normal artifacts are unreviewed, or the Feishu snapshot/delta disposition is missing/stale | 1.3 |
| `planning`, step 1.3 review completion is satisfied | 1.4; start or stop at the planning boundary according to the user's original intent |
| `in_progress`, checkpoint points to unfinished implementation/diagnosis/review | 2.1 |
| `in_progress`, execution is complete but full-scope evidence is missing | 2.2 |
| `in_progress`, acceptance has been verified | 3.3 → conditional 3.4 → 3.5 |