feat: add frontend development guidelines and structure documentation
- Introduced API guidelines for interface contracts and request handling. - Added design tokens usage guidelines for consistent styling across the project. - Established DTO guidelines for defining request parameters and response data types. - Created frontend structure guidelines to clarify directory organization and code placement rules. - Compiled a comprehensive frontend development guideline document covering various aspects of the development process. - Implemented quality guidelines to ensure code maintainability and adherence to best practices.
This commit is contained in:
yuxuanhui
@@ -0,0 +1,576 @@
|
||||
# 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 生效。
|
||||
Reference in New Issue
Block a user