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,124 @@
|
||||
# 全局 Agent 规则
|
||||
|
||||
以下是本机 Codex 的个人工作约定；系统、开发者、项目级 `AGENTS.md` 和当前用户明确要求始终优先。
|
||||
|
||||
## 个人偏好
|
||||
|
||||
- 默认使用简体中文；代码标识符、命令、配置键和路径保持原文。
|
||||
- 结论先行；以当前机器、仓库、会话和真实运行结果为准。
|
||||
- 默认做最小充分实现，不扩张范围，不覆盖、还原或提交用户已有改动。
|
||||
- 最终答复只保留结论、关键证据、实际验证、剩余风险和必要下一步。
|
||||
|
||||
## 授权边界
|
||||
|
||||
- 用户只要求回答、解释、分析、诊断、review 或规划时，只读检查并报告；不得修改产品代码或外部状态。
|
||||
- 用户明确要求修改、实现、构建或修复时，完成范围内本地改动和非破坏性验证，不重复索要实现确认。
|
||||
- 外部系统写入、发送、发布、破坏性操作、付费、权限变更和实质扩张范围前必须确认。
|
||||
- Review-only 只报告 findings；只有用户同时要求修复时才修改代码。
|
||||
- Diagnosis-only 交付根因、证据和建议；只有用户同时要求修复时才实现。
|
||||
- 没有直接验证证据时，不声称完成、通过、可提交或可合并。
|
||||
|
||||
## 任务分流
|
||||
|
||||
分流由本文件与项目 `.trellis/workflow.md` 共同决定，顺序如下：
|
||||
|
||||
1. 当前用户明确指定的 workflow 或 skill。
|
||||
2. 明确属于 Inline 的简单任务。
|
||||
3. 非简单但能在单会话完成的工程任务，使用当前最匹配的 Matt 方法。
|
||||
4. 已有 `.trellis/` 且任务需要跨会话、多项稳定决策、多交付物或 durable research 时，进入 Trellis 生命周期并在其中使用 Matt 方法。
|
||||
|
||||
### Inline
|
||||
|
||||
以下任务直接处理，不创建 Trellis task：
|
||||
|
||||
- 一轮可完成的问答、解释、代码阅读；
|
||||
- 局部配置、文案或单文件修改；
|
||||
- 根因明确的小修；
|
||||
- 影响范围窄、没有需要持久化的设计决策；
|
||||
- 当前上下文内可以完成最小验证。
|
||||
|
||||
### Matt
|
||||
|
||||
- 按当前可用 skill 的 `description` 路由，不在全局规则复制完整 skill 清单。
|
||||
- 用户明确点名且可用的 skill 优先；多个匹配时选范围最窄的一个。
|
||||
- 用户要求 `/tdd`、test-first、red-green-refactor 或 integration tests 时使用 `/tdd`，并先确认要测试的公开 seam。
|
||||
- 没有精确匹配时由主会话执行标准闭环：证据 → 决策/计划 → 执行 → 验证。
|
||||
- 所选 skill 的流程门禁有效，但不得扩大当前用户授权。
|
||||
|
||||
### Trellis + Matt
|
||||
|
||||
- Trellis 只管理 task 状态、planning artifacts、research、checkpoint、跨会话恢复和 archive。
|
||||
- Matt 只提供当前阶段的工程方法；一个阶段只保留一个 method owner。
|
||||
- Phase 1 不使用 `trellis-brainstorm`：主会话先基于证据形成 task artifacts，再用 `grill-with-docs` review spec。
|
||||
- Phase 2 不使用原生 `trellis-implement`：由 `trellis-matt-implement` sub-agent 按已记录的 `standard|tdd` mode 执行；agent 不可用时由主会话按同一 mode fallback。
|
||||
- Trellis 详细 phase、breadcrumb、恢复和归档命令以项目 `.trellis/workflow.md` 为准。
|
||||
- 简单工作不建 task；项目没有 `.trellis/` 时不主动初始化，除非用户明确要求长期记录或初始化。
|
||||
|
||||
## Planning 方法
|
||||
|
||||
- Trellis task 的 `prd.md`、条件性的 `design.md` 和 `implement.md` 是 task-level spec source of truth。
|
||||
- Planning artifacts 初稿应来自代码、测试、配置、文档和 task history 等证据。
|
||||
- 每个 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、兼容、风险、验收和关键设计决策。
|
||||
- 一次只问一个问题；先查环境事实，只把真正属于用户的决策交给用户。
|
||||
- 每个答案确认后立即同步回 owning Trellis artifact。
|
||||
- `CONTEXT.md` 只保存稳定领域术语；ADR 只保存难以逆转、反直觉且经过真实取舍的决策，不复制 task spec。
|
||||
- `grill-with-docs` wrapper 不可加载时，使用 `grilling` + `domain-modeling` 的等价组合。
|
||||
- 用户确认 shared understanding 后，视为 spec review 完成；不再增加独立的 Trellis implementation approval。
|
||||
|
||||
## Implementation 方法
|
||||
|
||||
- 以 review 完成的 Trellis artifacts 或当前 spec/tickets 作为实现输入。
|
||||
- Matt 单会话任务由主会话执行 implementation contract；Trellis Phase 2 由主会话派发 `trellis-matt-implement` 执行被委派的实现切片。
|
||||
- `trellis-matt-implement` 是 execution role，不在 sub-agent 内调用 Matt `/implement` wrapper；每个实现切片只有一个 method owner。
|
||||
- Dispatch prompt 必须包含 `Active task: <task-path>`、`Implementation mode: standard|tdd` 和 confirmed TDD seams；agent 按 `implement.jsonl`（如有真实条目）→ `prd.md` → `design.md`（如有）→ `implement.md`（如有）读取上下文。
|
||||
- `standard` 是默认模式：先完成最小、连贯的实现增量，再运行单测试文件、受影响 type-check 等窄反馈，并在行为存在后按需补充验收/回归测试。
|
||||
- `tdd` 只在用户触发且公开 seam 已确认时启用：显式加载 `/tdd`，按一个 failing behavioral test → 最小 green implementation 的 vertical slice 循环。
|
||||
- TDD seam 未确认或 `/tdd` 不可加载时返回 `blocked`，不得自行选择、推断或静默降级模式。
|
||||
- TDD red → green loop 内不做无关 refactor；refactor 留到主会话最终 review，之后重跑行为测试和完整适用验证。
|
||||
- 两种模式结束时都运行完整适用验证。
|
||||
- Sub-agent 不修改 Trellis task 状态、requirements 或 acceptance criteria，不执行 Git 写操作，也不派发其他 agent。
|
||||
- Sub-agent 返回后由主会话检查完整 diff、同步 checkpoint，并按当前可用 review skill 的 `description` 完成最终 review 和 acceptance；该 skill 明确要求并行时可以使用子 agent。
|
||||
- Matt `implement` 中无条件 commit 的步骤不适用；commit 仍由下方版本控制规则约束。
|
||||
|
||||
## Codex 执行方式
|
||||
|
||||
- 默认由主会话完成探索、规划、检查和验收；Trellis Phase 2 是明确例外，由当前 workflow 派发 `trellis-matt-implement` 完成实现切片。
|
||||
- 默认只派发一个 `trellis-matt-implement`；只有独立 child task 或写入范围完全分离时，才按 workflow/skill 的明确要求并行。
|
||||
- 不因为 Trellis 的默认 dispatch banner 自动派发原生 `trellis-implement`。
|
||||
- `trellis-matt-implement` 不可用、无法可靠加载 task context 或平台不支持 custom sub-agent 时，由主会话按已记录 mode fallback：`standard` 使用 Matt 适配契约，`tdd` 显式加载 `/tdd`。
|
||||
- 子 agent 只拥有被委派的窄任务；主会话负责范围、整合、验收和用户沟通。
|
||||
|
||||
## Spec 与经验提升
|
||||
|
||||
- 每个任务都可以判断是否产生了值得提升的知识，但默认不执行 promotion。
|
||||
- 只有知识稳定、可复用、已经验证且用户明确确认后，才写入 `.trellis/spec/`、全局规则、skill、hook、test、script 或跨项目知识库。
|
||||
- 未满足条件的内容保留在当前 task 的 design/research/retrospective，或在最终答复中列为 candidate。
|
||||
|
||||
## 工具与代码约定
|
||||
|
||||
- 搜索文件和文本优先使用 `rg` / `rg --files`。
|
||||
- 当前项目存在 `.codegraph/` 且任务涉及跨文件改动、重构、影响分析或调用链排查时，按项目约定优先使用 CodeGraph。
|
||||
- 查询 library、framework、SDK、API、CLI 或 cloud service 的当前行为时，使用项目指定的最新文档工具；本地版本和真实运行结果优先。
|
||||
- 编写函数、类或复杂逻辑时使用对应文档注释，说明参数、返回值、异常与设计原因。
|
||||
- 注释解释 Why，不逐行翻译代码；权限、安全和兼容边界旁添加显眼警告。
|
||||
|
||||
## 版本控制
|
||||
|
||||
- commit、push、PR 只在用户明确要求时执行，三者授权互不自动包含。
|
||||
- Trellis archive 和 journal 使用命令级 `--no-commit`；不依赖自动提交。
|
||||
- commit message 默认 `<type>(scope): <中文动词短语>`，不加句号。
|
||||
- commit 只包含本任务已确认归属的文件；不 amend，不静默包含用户或其他并行工作的改动。
|
||||
|
||||
## 最终答复
|
||||
|
||||
结论先行，按实际需要包含：
|
||||
|
||||
1. outcome；
|
||||
2. key evidence / changed files；
|
||||
3. verification actually run；
|
||||
4. remaining risks or blockers；
|
||||
5. necessary next step。
|
||||
|
||||
省略过程复述。未运行的验证必须明确写 `not run` 或说明阻塞原因。
|
||||
@@ -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 生效。
|
||||
@@ -0,0 +1,124 @@
|
||||
# Global Agent Rules
|
||||
|
||||
The following are my personal operating conventions for Codex on this machine. System instructions, developer instructions, project-level `AGENTS.md`, and the user's current explicit request always take precedence.
|
||||
|
||||
## Personal Preferences
|
||||
|
||||
- Use Simplified Chinese by default; keep code identifiers, commands, configuration keys, and paths unchanged.
|
||||
- Lead with the conclusion and rely on evidence from the current machine, repository, session, and actual command results.
|
||||
- Default to the minimum sufficient implementation. Do not expand scope or overwrite, revert, or commit the user's existing changes.
|
||||
- Keep the final response to the outcome, key evidence, verification actually performed, remaining risks, and any necessary next step.
|
||||
|
||||
## Authorization Boundaries
|
||||
|
||||
- When the user only asks for an answer, explanation, analysis, diagnosis, review, or plan, inspect in read-only mode and report the result. Do not modify product code or external state.
|
||||
- When the user explicitly asks to modify, implement, build, or fix something, complete the in-scope local changes and non-destructive verification without asking again for implementation approval.
|
||||
- Confirm before writing to an external system, sending or publishing anything, performing a destructive action, incurring a charge, changing permissions, or materially expanding scope.
|
||||
- Review-only work reports findings only. Modify code only when the user also asks for a fix.
|
||||
- Diagnosis-only work delivers the root cause, evidence, and recommendation. Implement a fix only when the user also asks for one.
|
||||
- Without direct verification evidence, do not claim that work is complete, passing, ready to commit, or ready to merge.
|
||||
|
||||
## Task Routing
|
||||
|
||||
Routing is jointly determined by this file and the project's `.trellis/workflow.md`, in the following order:
|
||||
|
||||
1. A workflow or skill explicitly requested by the user.
|
||||
2. Simple work that clearly belongs to Inline mode.
|
||||
3. Engineering work that is not simple but can be completed in one session, using the most appropriate current Matt method.
|
||||
4. When `.trellis/` exists and the work requires multiple sessions, several durable decisions, multiple deliverables, or durable research, enter the Trellis lifecycle and use Matt methods within it.
|
||||
|
||||
### Inline
|
||||
|
||||
Handle the following directly without creating a Trellis task:
|
||||
|
||||
- A question, explanation, or code-reading task that can be completed in one turn;
|
||||
- A local configuration, copy, or single-file change;
|
||||
- A small fix with a known root cause;
|
||||
- Work with a narrow impact and no design decision that needs to persist;
|
||||
- Work whose minimum verification can be completed in the current context.
|
||||
|
||||
### Matt
|
||||
|
||||
- Route by the `description` of currently available skills instead of copying a complete skill list into these global rules.
|
||||
- Prefer an available skill explicitly named by the user. If several skills match, choose the narrowest one.
|
||||
- Use `/tdd` when the user requests `/tdd`, test-first, red-green-refactor, or integration tests, and first confirm the public seams to test.
|
||||
- When there is no exact match, the main session performs the standard loop: evidence → decision/plan → execution → verification.
|
||||
- The selected skill's workflow gates remain in force, but must not expand the user's current authorization.
|
||||
|
||||
### Trellis + Matt
|
||||
|
||||
- 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 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.
|
||||
- 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.
|
||||
- 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.
|
||||
- If the `grill-with-docs` wrapper cannot be loaded, use the equivalent combination of `grilling` + `domain-modeling`.
|
||||
- Once the user confirms shared understanding, the spec review is complete. Do not add a separate Trellis implementation approval.
|
||||
|
||||
## Implementation Method
|
||||
|
||||
- Use reviewed Trellis artifacts or the current spec/tickets as implementation input.
|
||||
- For a single-session Matt task, the main session executes the implementation contract. In Trellis Phase 2, the main session dispatches `trellis-matt-implement` for the delegated implementation slice.
|
||||
- `trellis-matt-implement` is the execution role and does not call a Matt `/implement` wrapper inside the sub-agent; each implementation slice has exactly one method owner.
|
||||
- The dispatch prompt must contain `Active task: <task-path>`, `Implementation mode: standard|tdd`, and confirmed TDD seams. The agent reads context in this order: real `implement.jsonl` entries when present → `prd.md` → optional `design.md` → optional `implement.md`.
|
||||
- `standard` is the default: complete the smallest coherent implementation increment before narrow feedback such as a single test file or affected type-check, then add acceptance/regression tests as needed after the behavior exists.
|
||||
- Enable `tdd` only after a user trigger and confirmation of public seams: explicitly load `/tdd` and work in vertical slices of one failing behavioral test → minimum green implementation.
|
||||
- If TDD seams are unconfirmed or `/tdd` cannot be loaded, return `blocked`; never select, infer, or silently downgrade the mode.
|
||||
- Do not perform unrelated refactoring inside the TDD red → green loop. Refactor during the main session's final review, then rerun behavioral tests and all applicable full-scope verification.
|
||||
- Run all applicable full-scope verification at the end of either mode.
|
||||
- The sub-agent does not change Trellis task state, requirements, or acceptance criteria; perform Git writes; or dispatch other agents.
|
||||
- After the sub-agent returns, the main session inspects the complete diff, synchronizes the checkpoint, and performs final review and acceptance through the `description` of currently available review skills. Sub-agents may be used when that skill explicitly requires parallel work.
|
||||
- Any unconditional commit step in Matt `implement` does not apply. Commits remain governed by the version-control rules below.
|
||||
|
||||
## Codex Execution
|
||||
|
||||
- By default, the main session performs exploration, planning, checks, and acceptance. Trellis Phase 2 is an explicit exception: the current workflow dispatches `trellis-matt-implement` for the implementation slice.
|
||||
- Dispatch only one `trellis-matt-implement` by default. Use parallel agents only for independent child tasks or completely disjoint write scopes when explicitly required by the workflow/skill.
|
||||
- Do not automatically dispatch the native `trellis-implement` because of a Trellis default dispatch banner.
|
||||
- If `trellis-matt-implement` is unavailable, cannot load task context reliably, or the platform does not support custom sub-agents, the main session follows the recorded mode: use the adapted Matt contract for `standard`, or explicitly load `/tdd` for `tdd`.
|
||||
- A sub-agent owns only the narrow task delegated to it. The main session owns scope, integration, acceptance, and user communication.
|
||||
|
||||
## Spec and Learning Promotion
|
||||
|
||||
- Every task may evaluate whether it produced knowledge worth promoting, but promotion is not performed by default.
|
||||
- Write to `.trellis/spec/`, global rules, a skill, hook, test, script, or cross-project knowledge base only when the knowledge is durable, reusable, verified, and explicitly approved by the user.
|
||||
- Keep anything that does not meet those conditions in the current task's design, research, or retrospective, or list it as a candidate in the final response.
|
||||
|
||||
## Tool and Code Conventions
|
||||
|
||||
- Prefer `rg` / `rg --files` for file and text searches.
|
||||
- When the current project contains `.codegraph/` and the task involves cross-file changes, refactoring, impact analysis, or call-chain investigation, prefer CodeGraph as required by the project conventions.
|
||||
- When checking the current behavior of a library, framework, SDK, API, CLI, or cloud service, use the current-documentation tool required by the project. Prefer the locally installed version and actual runtime results.
|
||||
- When writing functions, classes, or complex logic, use the corresponding documentation-comment format and describe parameters, return values, exceptions, and design rationale.
|
||||
- Comments explain why, not a line-by-line translation of the code. Add prominent warnings beside permission, security, and compatibility boundaries.
|
||||
|
||||
## Version Control
|
||||
|
||||
- Commit, push, and PR actions require an explicit user request, and authorization for one does not imply authorization for another.
|
||||
- Trellis archive and journal commands use command-level `--no-commit`; do not rely on automatic commits.
|
||||
- Commit messages default to `<type>(scope): <Chinese verb phrase>` with no trailing period.
|
||||
- A commit contains only files confirmed to belong to the current task. Do not amend or silently include the user's changes or changes from parallel work.
|
||||
|
||||
## Final Response
|
||||
|
||||
Lead with the conclusion and include only what is needed:
|
||||
|
||||
1. Outcome;
|
||||
2. Key evidence / changed files;
|
||||
3. Verification actually run;
|
||||
4. Remaining risks or blockers;
|
||||
5. Necessary next step.
|
||||
|
||||
Omit a process recap. Any verification that was not run must be marked `not run` or accompanied by the reason it was blocked.
|
||||
@@ -0,0 +1,576 @@
|
||||
# Yuxuanhui Development Workflow
|
||||
|
||||
> Scope: projects where `.trellis/` has already been initialized.
|
||||
>
|
||||
> Design baseline: Trellis 0.6.8. This document can be used as a lightweight, single-file override for the project's `.trellis/workflow.md`.
|
||||
>
|
||||
> Customization contract reference: [Trellis official “Custom Workflow” documentation](https://docs.trytrellis.app/zh/advanced/custom-workflow).
|
||||
|
||||
## 0. Workflow Contract
|
||||
|
||||
### Instruction precedence
|
||||
|
||||
Higher-level instructions, the project `AGENTS.md`, and the user's current explicit request always take precedence. When a conflict occurs, do not use this workflow or a skill to expand the user's authorization.
|
||||
|
||||
### Three operating modes
|
||||
|
||||
| Mode | Owner | Use when | Persistence |
|
||||
| -------------- | ------------------------------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------- |
|
||||
| Inline | Main session | Simple, local, root cause known, and completable in one context | No Trellis task |
|
||||
| Matt | The currently matched engineering skill; otherwise the main session | Engineering work that is not simple but can still be completed in one session | Use existing project artifacts; no task is required |
|
||||
| Trellis + Matt | Trellis owns the lifecycle; the currently matched Matt skill owns the engineering method | Multiple sessions, several durable decisions, multiple deliverables, or explicit persistence | Task, planning artifacts, research, checkpoint, archive |
|
||||
|
||||
Trellis is the control plane and does not replace the engineering method. Matt is the method layer and does not own task state. Select exactly one workflow owner for each phase; do not stack multiple complete workflows. Trellis context loading, state writes, and archive actions do not count as a second method owner.
|
||||
|
||||
### Lightweight override policy
|
||||
|
||||
At project level, this setup overrides `.trellis/workflow.md` and adds `.codex/agents/trellis-matt-implement.toml`; the companion `AGENTS.md` may live globally or in the project. It does not require changes to `.trellis/config.yaml`, Codex hooks, or Trellis bundled skills. To prevent legacy entry points from taking control again, apply these override rules:
|
||||
|
||||
- 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 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`.
|
||||
- `trellis-matt-implement` is the Phase 2 execution role explicitly selected by this workflow; dispatch only one by default. Each implementation slice has exactly one method owner: either the `standard` Matt contract or explicit `/tdd`. Enable other sub-agents only when the user explicitly requests them or the currently selected Matt skill explicitly requires parallel work.
|
||||
|
||||
### Core principles
|
||||
|
||||
1. **Evidence before inference** — Rely on the current machine, repository, task files, diff, and actual command output.
|
||||
2. **Minimum sufficient work** — Complete the smallest sufficient scope requested by the user. Do not expand scope or overwrite existing user changes.
|
||||
3. **Persist only when useful** — Keep simple work in the session. Write only cross-session state, durable decisions, and reusable evidence to Trellis.
|
||||
4. **One lifecycle owner, one method owner** — Trellis manages state; each phase selects exactly one engineering method.
|
||||
5. **Verification before completion claims** — Without direct verification evidence, do not claim that work is complete, passing, ready to commit, or ready to merge.
|
||||
6. **No implicit external effects** — Confirm before external writes, sending, publishing, destructive actions, paid actions, permission changes, or material scope expansion.
|
||||
7. **No implicit promotion or version control** — Spec promotion, commit, push, and PR are never default finishing actions.
|
||||
|
||||
## 1. Request Routing
|
||||
|
||||
### Step A: Determine the user's authorized intent
|
||||
|
||||
| User intent | Default boundary |
|
||||
| --- | --- |
|
||||
| Answer, explain, analyze, diagnose, review, or plan | Inspect in read-only mode and report; do not modify product code or external state |
|
||||
| Modify, implement, build, or fix | Complete in-scope local changes and non-destructive verification; do not ask again for implementation approval |
|
||||
| External-system write, publish, destructive action, paid action, permission change, or material scope expansion | Confirm before execution |
|
||||
| Spec promotion | Perform only when the knowledge is durable, reusable, verified, and confirmed by the user |
|
||||
| Commit, push, or PR | Perform only when explicitly requested; authorization for one does not imply authorization for another |
|
||||
|
||||
When a read-only request enters Trellis, the task's own planning, research, and checkpoint artifacts may be written, but “record the analysis” must not be interpreted as “permission to fix the code.” A review-only request reports issues even when it finds them. Modify code only when the user also asks for a fix.
|
||||
|
||||
### Step B: Choose the lifecycle mode
|
||||
|
||||
#### Inline
|
||||
|
||||
Handle the work directly without creating a task when all relevant conditions are satisfied:
|
||||
|
||||
- A question, explanation, or code-reading task that can be completed in one turn;
|
||||
- A local configuration, copy, or single-file change;
|
||||
- A small fix with a known root cause;
|
||||
- A narrow impact with no design decision that needs long-term persistence;
|
||||
- Minimum verification that can be completed in the current context.
|
||||
|
||||
#### Matt without Trellis
|
||||
|
||||
When the task is not Inline but can still be completed in one healthy context and does not need several decisions to persist:
|
||||
|
||||
- Select the narrowest, most precise method from currently available skill `description` values;
|
||||
- Complete it in the main session unless the selected skill explicitly requires parallel agents;
|
||||
- Do not create a Trellis task merely to make the work appear formal.
|
||||
|
||||
#### Trellis + Matt
|
||||
|
||||
Enter the Trellis lifecycle when any of the following applies:
|
||||
|
||||
- The user explicitly asks for Trellis, durable records, or cross-session recovery;
|
||||
- The work is likely to span sessions or require handoff;
|
||||
- Two or more durable decisions will affect later implementation;
|
||||
- One request contains multiple independently verifiable deliverables;
|
||||
- Research, compatibility/migration plans, rollout/rollback plans, or important risks must persist;
|
||||
- An active task already matches the request.
|
||||
|
||||
When the boundary is uncertain, prefer Matt in a single session first. Upgrade to Trellis only when the work actually develops cross-session needs, independent deliverables, or durable decisions. On upgrade, record confirmed facts, decisions, remaining work, and verification evidence in the task, then continue without repeating completed work.
|
||||
|
||||
### Method selection details
|
||||
|
||||
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 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:
|
||||
|
||||
1. Prefer a currently available skill explicitly named by the user.
|
||||
2. Select `/tdd` when the user requests `/tdd`, test-first, red-green-refactor, or integration tests. A Trellis task must first persist `Implementation Mode: tdd` and confirm its public test seams.
|
||||
3. Otherwise, scan the `description` of current skills and match the actual intent of the current phase, such as requirements interrogation, spec/issue work, implementation, diagnosis, review, architecture, or research.
|
||||
4. If several skills match, select the narrowest one whose output best fits the current phase.
|
||||
5. Mandatory gates of the selected skill remain in force. If it explicitly requires parallel agents, sub-agents are permitted for that phase.
|
||||
6. If there is no exact match, the main session uses the standard loop: evidence → decision/plan → execution → verification.
|
||||
7. Do not call an unavailable or mismatched skill merely because it historically belonged to a Matt primary workflow.
|
||||
|
||||
`grill-with-docs` is currently an explicit-invocation skill. `trellis-matt-implement` is the Codex custom execution role selected by this workflow and does not call a Matt `/implement` wrapper inside the sub-agent. It follows the mode recorded in planning artifacts and never infers TDD:
|
||||
|
||||
- `standard` is the default method: complete a stable implementation increment, then run narrow checks and add tests as needed;
|
||||
- `tdd` is used only after a user trigger and confirmation of public seams: the sub-agent explicitly loads `/tdd` and works in vertical red → green slices.
|
||||
|
||||
When the corresponding capability is unavailable:
|
||||
|
||||
- The `grill-with-docs` fallback is `grilling` + `domain-modeling`;
|
||||
- The `trellis-matt-implement` fallback is the main session following the recorded mode: the Matt contract overridden by this workflow for `standard`, or an explicitly loaded `/tdd` for `tdd`. Neither mode performs implicit Git writes.
|
||||
|
||||
## 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` creates a task with `status=planning`. If a session identifier is available, it sets the session-scoped active task.
|
||||
- `start` changes the task to `in_progress`. It only indicates entry into the execution phase and does not expand user authorization.
|
||||
- `finish` only clears the current session pointer. It does not change task status or mean that the task is complete.
|
||||
- `archive --no-commit` writes `status=completed`, moves the task, and clears related session pointers without touching Git.
|
||||
- Always pass `--no-commit` explicitly to archive and journal commands, so changing the `session_auto_commit` default is unnecessary.
|
||||
- Treat `python3 ./.trellis/scripts/task.py --help` as the source of truth for CLI commands. Do not use subcommands absent from the actual help output.
|
||||
|
||||
### Planning artifacts
|
||||
|
||||
| Artifact | Rule |
|
||||
| --- | --- |
|
||||
| `prd.md` | Required for every Trellis task; records goals, facts, scope, constraints, acceptance criteria, open decisions, and implementation mode / TDD seams under `Testing Strategy` |
|
||||
| `design.md` | Required for cross-module work, contracts, compatibility, migration, security, rollout/rollback, or important technical tradeoffs |
|
||||
| `implement.md` | Required for multi-step, cross-session, or higher-risk work, or when the verification sequence must be explicit |
|
||||
| `research/*.md` | Store only research that affects decisions and must persist across sessions; one question per file, with sources and conclusions |
|
||||
| `implement.jsonl` | Optional context manifest for `trellis-matt-implement`; read real spec/research entries first, while a seed-only manifest allows the agent to discover relevant standards itself |
|
||||
| `check.jsonl` | This workflow does not use the native Trellis check sub-agent; keep the generated seed as-is without maintaining it |
|
||||
|
||||
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.
|
||||
|
||||
Every Trellis implementation task maintains this in `prd.md`:
|
||||
|
||||
```markdown
|
||||
## Testing Strategy
|
||||
|
||||
- Implementation Mode: standard | tdd
|
||||
- Confirmed TDD Seams: Not applicable | <confirmed public seams>
|
||||
```
|
||||
|
||||
`standard` is the default. Write `tdd` only when the user explicitly requests `/tdd`, test-first, red-green-refactor, or integration tests, or when the reviewed spec explicitly requires TDD. TDD execution cannot begin without at least one confirmed seam.
|
||||
|
||||
Every cross-session task must maintain a short checkpoint in `implement.md`:
|
||||
|
||||
```markdown
|
||||
## Current Checkpoint
|
||||
|
||||
- Last completed:
|
||||
- Evidence:
|
||||
- Next:
|
||||
- Blockers:
|
||||
```
|
||||
|
||||
The checkpoint records only the state needed for recovery, not a recap of the conversation.
|
||||
|
||||
### Parent / child tasks
|
||||
|
||||
Create a child task only when its deliverable can be planned, implemented, checked, and archived independently. Prefer narrow but complete vertical slices. A split by technical layer alone usually does not justify a child task.
|
||||
|
||||
```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>
|
||||
```
|
||||
|
||||
Parent-child relationships are not a dependency graph. Write blocking order explicitly in the child's `prd.md` or `implement.md`. The parent task owns source requirements, the task map, cross-child acceptance, and final integration. Activate next only the child that owns a real deliverable.
|
||||
|
||||
## 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
|
||||
|
||||
- When there is no active task, classify silently first. Do not ask process-only questions such as whether to create a Trellis task.
|
||||
- Start Inline and single-session Matt work directly.
|
||||
- When Trellis conditions are met, create the task automatically. An explicit user request to implement or fix already authorizes in-scope local implementation; do not ask again after planning.
|
||||
- When the user asks only for planning, review, or diagnosis, creating a task does not grant permission to modify product code.
|
||||
- If a product, scope, compatibility, risk, or acceptance decision still belongs to the user, ask only the single highest-value question and wait for the answer.
|
||||
- Respect an explicit request not to create a task. If the scope is no longer suitable for one session, narrow the deliverable or explain the risk of unreliable persistence.
|
||||
- If the project has no `.trellis/`, do not initialize it unless the user explicitly asks for durable records or initialization.
|
||||
|
||||
### Skill Routing
|
||||
|
||||
| User intent / phase | Route |
|
||||
| --- | --- |
|
||||
| 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 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/` |
|
||||
|
||||
### 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 the native `trellis-implement`. Dispatch one `trellis-matt-implement` with `Active task`, the 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: the adapted Matt contract for `standard`, `/tdd` for `tdd`. Dispatch neither the 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. Identify the user's authorization boundary first, then the lifecycle mode and current phase.
|
||||
2. Run required steps in order within a phase. Do not recreate artifacts that already exist and remain valid.
|
||||
3. If new evidence invalidates a requirement or design, return to Phase 1. Update the owning artifact before continuing.
|
||||
4. Each phase has one engineering-method owner. Another skill may run as a substep only when the current owner explicitly delegates to it.
|
||||
5. When a session approaches the context-quality boundary, update the task checkpoint before switching sessions. Do not continue by relying on a vague summary.
|
||||
6. When work upgrades from Inline/Matt to Trellis midstream, preserve existing evidence and results. Do not repeat completed steps.
|
||||
|
||||
## Phase 1: Plan
|
||||
|
||||
Goal: turn durable work into a recoverable, testable task without creating duplicate approval gates.
|
||||
|
||||
#### 1.0 Create or resume task `[required · once]`
|
||||
|
||||
Check the current task first:
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/task.py current --source
|
||||
```
|
||||
|
||||
- If the active task matches the request, read it and continue without creating another.
|
||||
- If the request does not meet Trellis conditions, leave the Trellis path and use Inline or Matt.
|
||||
- If the request meets Trellis conditions, create the task directly without asking for process consent.
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/task.py create "<short title>" --slug <name>
|
||||
```
|
||||
|
||||
Run only `create` here. Do not immediately and unconditionally run `start`. First record the user's original intent, evidence, and required planning artifacts clearly.
|
||||
|
||||
If one request contains multiple independently verifiable deliverables, first create a parent/child map. Do not split into child tasks merely because the work spans several files or layers; split only when a deliverable can be accepted independently.
|
||||
|
||||
#### 1.1 Draft planning artifacts from evidence `[required · repeatable]`
|
||||
|
||||
1. Read existing code, tests, configuration, documentation, specs, historical tasks, and Git state.
|
||||
2. Investigate questions the repository can answer directly instead of asking the user for facts.
|
||||
3. Distinguish confirmed facts, user intent, scope/risk decisions, technical unknowns, and explicit out-of-scope items.
|
||||
4. The main session first drafts `prd.md`, plus `design.md` and `implement.md` when their conditions apply.
|
||||
5. Record the mode under `Testing Strategy` in `prd.md`. Default to `standard`; record `tdd` when the user requests `/tdd`, test-first, red-green-refactor, or integration tests, or when the reviewed spec explicitly requires TDD, and list candidate public seams for confirmation.
|
||||
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.
|
||||
|
||||
At minimum, `prd.md` contains: Goal, Background/Evidence, In Scope, Out of Scope, Requirements, Acceptance Criteria, Constraints, Open Decisions, and Testing Strategy.
|
||||
|
||||
Before finishing, perform one convergence pass: remove duplicate facts and resolved questions while preserving every evidence anchor, constraint, decision, and acceptance mapping.
|
||||
|
||||
#### 1.2 Research / prototype / design inquiry `[optional · repeatable]`
|
||||
|
||||
Research only when the repository cannot directly answer a technical fact. Prototype only when a state model, business rule, or UI must be run or observed to make a decision. Choose the corresponding design method when the interface, seam, domain vocabulary, or architectural shape is itself the question.
|
||||
|
||||
Research rules:
|
||||
|
||||
- Prefer official documentation, standards, source code, and first-party APIs;
|
||||
- Use the current-documentation tool required by the project `AGENTS.md`;
|
||||
- For a Trellis task, write conclusions that affect implementation to `{TASK_DIR}/research/<topic>.md`;
|
||||
- Record sources, version/date, conclusions, scope of applicability, and unresolved risks;
|
||||
- Research supplies evidence; it does not make product decisions on behalf of the user.
|
||||
|
||||
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]`
|
||||
|
||||
Explicitly load `grill-with-docs` and use it to review `prd.md` plus conditional `design.md` and `implement.md`:
|
||||
|
||||
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.
|
||||
|
||||
If `grill-with-docs` cannot be loaded directly on the platform, use the equivalent combination `grilling` + `domain-modeling`.
|
||||
|
||||
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.4 Activate or stop at planning boundary `[required · once]`
|
||||
|
||||
Apply the authorization matrix:
|
||||
|
||||
| Situation | Action |
|
||||
| --- | --- |
|
||||
| The user explicitly requested implement/build/fix/change; artifacts are ready; no user decision remains open | Run `task.py start` and enter Phase 2 without asking again |
|
||||
| The user requested only plan/spec/review/diagnose | Stop at the authorization boundary; deliver the requested artifact or continue read-only execution without modifying product code |
|
||||
| The selected skill has an explicit human gate | Follow that gate |
|
||||
| The action involves external writes, destructive actions, payment, permissions, or material scope expansion | Confirm that action first |
|
||||
| The artifacts materially changed scope and the original authorization no longer covers it | Request direction first |
|
||||
|
||||
Start command:
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
#### 1.5 Planning completion criteria
|
||||
|
||||
| Condition | Required |
|
||||
| --- | :---: |
|
||||
| `prd.md` contains observable acceptance criteria | ✅ |
|
||||
| Repository-answerable facts have evidence | ✅ |
|
||||
| No blocking user decision remains | ✅ |
|
||||
| `design.md` exists when its conditions apply | ✅ |
|
||||
| `implement.md` exists with a checkpoint when its conditions apply | ✅ |
|
||||
| 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 | ✅ |
|
||||
| The current action remains within user authorization | ✅ |
|
||||
|
||||
## Phase 2: Execute
|
||||
|
||||
Goal: complete the authorized work through one explicit method and leave auditable evidence.
|
||||
|
||||
#### 2.1 Implement with `trellis-matt-implement` `[required · repeatable]`
|
||||
|
||||
Before execution:
|
||||
|
||||
1. Read `prd.md`, conditional `design.md` / `implement.md`, and relevant research.
|
||||
2. Run package/spec discovery and read the pre-development checklist and concrete standards for the affected area.
|
||||
3. Check `git status` and distinguish task changes, existing user changes, and unrelated parallel work.
|
||||
4. If the current project contains `.codegraph/` and the task involves cross-file changes, refactoring, impact analysis, or call-chain investigation, prefer CodeGraph as required by project `AGENTS.md`.
|
||||
5. Read `Testing Strategy` and accept only `standard` or `tdd`. If `tdd` has no confirmed seam, return to step 1.3; never select or infer TDD in Phase 2.
|
||||
6. Use `task.py current --source` to obtain the exact task path for the current session and confirm that the task matches the request and has `in_progress` status.
|
||||
7. Dispatch one `trellis-matt-implement`; never dispatch the native `trellis-implement`. The prompt must include the exact task path, mode, and 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` is the execution role and does not call a Matt `/implement` wrapper inside the sub-agent; each slice selects exactly one implementation method;
|
||||
- Read context in this order: real `implement.jsonl` entries → `prd.md` → conditional `design.md` → conditional `implement.md` → relevant project standards;
|
||||
- Treat the reviewed Trellis artifacts as the spec/tickets and make only the minimum sufficient implementation for the delegated slice;
|
||||
- Do not overwrite, revert, or commit the user's existing changes;
|
||||
- Follow project comment conventions for public functions, classes, and complex logic, explaining design rationale and critical boundaries;
|
||||
- `standard`: do not use TDD/test-first; complete a stable implementation increment before narrow checks, then add acceptance/regression tests as needed after the behavior exists;
|
||||
- `tdd`: explicitly load `/tdd` and work only at confirmed public seams in vertical slices of one failing behavioral test → minimum green implementation; if the skill is unavailable or a seam is missing, return `blocked` without silently degrading;
|
||||
- Do not perform unrelated refactoring inside the TDD red → green loop; return candidates to the main session for review in step 2.2;
|
||||
- In both modes, run all applicable full-scope verification at the end of the slice;
|
||||
- Do not change task state, requirements, scope, or acceptance criteria; perform Git writes; or dispatch another agent;
|
||||
- Self-review the complete delegated slice and return the implementation mode, confirmed seams, changed files, acceptance mapping, actual verification results, and remaining risks.
|
||||
|
||||
After the agent returns, the main session must inspect its report and the complete diff, then synchronize completed steps, verification evidence, next action, and blockers to the `implement.md` Current Checkpoint before entering step 2.2. A diagnosis-only or review-only task must not dispatch the implementation agent or modify product code as a convenience.
|
||||
|
||||
If the custom agent is unavailable, cannot obtain task context reliably, or the platform does not support custom sub-agents, the main session follows the recorded mode: use the adapted Matt fallback for `standard`, or explicitly load `/tdd` for `tdd`. Dispatch only one implementation agent by default; parallel execution is allowed only for independent child tasks or completely disjoint write scopes. Any commit still requires an explicit user request before entering step 3.4.
|
||||
|
||||
#### 2.2 Quality and acceptance check `[required · repeatable]`
|
||||
|
||||
The checking behavior depends on user intent:
|
||||
|
||||
- Implementation/fix task: fix in-scope issues found by checks, then rerun verification.
|
||||
- Review-only: report findings without modifying code.
|
||||
- Diagnosis-only: report the root cause, evidence, and recommendation without implementing a fix.
|
||||
|
||||
Every pass checks at least:
|
||||
|
||||
1. A mapping from the diff to each `prd.md` acceptance criterion;
|
||||
2. Applicable `.trellis/spec/` and project standards;
|
||||
3. Real acceptance commands for the affected area, such as lint, type-check, tests, build, or other checks;
|
||||
4. Cross-layer data flow, types, error propagation, compatibility, and regression impact when applicable;
|
||||
5. Checks not run and the reason.
|
||||
|
||||
The final pass must cover the entire task diff, not only the last patch. Record commands, exit results, and key output. When a tool was not actually run, record only `not run` or `blocked`, never `passed`.
|
||||
|
||||
When implementation mode is `tdd`, refactoring occurs only in this review stage. Rerun affected behavioral tests and all applicable full-scope verification afterward to ensure the green state remains intact.
|
||||
|
||||
If the selected review skill explicitly requires several independent review agents, that parallelism is an internal step of the Matt implementation method. If no skill matches or it cannot cover the current uncommitted diff, the main session directly reviews the complete diff. Do not stack `trellis-check` merely for formality.
|
||||
|
||||
#### 2.3 Roll back to the right phase `[on demand]`
|
||||
|
||||
- New evidence shows a requirement or acceptance criterion is wrong → return to Phase 1 and update `prd.md`.
|
||||
- The interface, compatibility, migration, or architectural shape is wrong → return to Phase 1 and update `design.md` and `implement.md`.
|
||||
- A technical fact is missing → return to research in step 1.2 and persist the conclusion.
|
||||
- The implementation drifted but the requirements remain correct → revert or correct only changes made by this task, then repeat step 2.1.
|
||||
- Never use destructive Git commands to clean the worktree or revert user changes whose ownership is uncertain.
|
||||
|
||||
## Phase 3: Finish
|
||||
|
||||
Goal: close the deliverable with evidence while keeping task records, knowledge promotion, and version control as three separate actions.
|
||||
|
||||
#### 3.2 Debug retrospective `[on demand]`
|
||||
|
||||
Run a retrospective only after repeated failures, multiple fixes for the same issue, an expensive detour, or difficulty establishing a feedback loop. Select the best-matched current diagnosis/learning method and record:
|
||||
|
||||
- The root cause;
|
||||
- Why early approaches failed;
|
||||
- Why the final evidence is trustworthy;
|
||||
- Candidate knowledge that could prevent similar issues.
|
||||
|
||||
A routine task summary does not trigger a retrospective.
|
||||
|
||||
#### 3.3 Knowledge promotion decision `[required · once]`
|
||||
|
||||
Always decide whether any knowledge is worth promoting, but do not modify `.trellis/spec/` or a cross-project knowledge base by default.
|
||||
|
||||
Candidate knowledge may be promoted only when all of the following are true:
|
||||
|
||||
1. Durable: it is not a one-off implementation detail or temporary workaround;
|
||||
2. Reusable: future tasks would take a different and better action because of it;
|
||||
3. Verified: supported by code, tests, documentation, or repeated evidence;
|
||||
4. User-confirmed: the user explicitly agrees to promote it into a spec, skill, hook, test, script, or cross-project pattern.
|
||||
|
||||
Without confirmation:
|
||||
|
||||
- It may remain in the current task's design, research, or retrospective;
|
||||
- It may be listed as a promotion candidate in the final response;
|
||||
- It must not be written automatically to `.trellis/spec/` or a canonical area of the personal knowledge base.
|
||||
|
||||
After the user confirms, use the currently available spec/compound-learning method and verify that the new rule matches current repository facts.
|
||||
|
||||
#### 3.4 Version-control actions `[on explicit request]`
|
||||
|
||||
Skip all Git write operations by default. Perform each action only when the user explicitly requests it:
|
||||
|
||||
- Commit: include only known changes from the current task; inspect dirty state and recent history first; group by logical unit; default message is `<type>(scope): <Chinese verb phrase>` with no trailing period; do not amend.
|
||||
- Push: perform only when the user explicitly requests a push. Commit authorization does not include push.
|
||||
- PR: create only when explicitly requested. Commit or push authorization does not include a PR.
|
||||
|
||||
Trellis never automatically commits a task archive or journal. The commands in section 3.5 always use `--no-commit` explicitly.
|
||||
|
||||
#### 3.5 Archive, journal and report `[required · once]`
|
||||
|
||||
First determine whether the task is genuinely complete: acceptance criteria are satisfied, required checks have direct evidence, and no blocker remains. Otherwise, update only the checkpoint and risks; do not archive.
|
||||
|
||||
Archive after completion:
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/task.py archive <task-dir> --no-commit
|
||||
```
|
||||
|
||||
Record the session:
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/add_session.py \
|
||||
--title "<title>" \
|
||||
--summary "<outcome, verification, remaining risk>" \
|
||||
--no-commit
|
||||
```
|
||||
|
||||
Command-level `--no-commit` ensures that both commands only write files and never stage, commit, or push, so `.trellis/config.yaml` does not need to change. Pass `--commit "<hashes>"` only when this task has already created a work commit at the user's explicit request. Otherwise omit the argument; never fabricate a hash.
|
||||
|
||||
The final response leads with the conclusion and keeps only:
|
||||
|
||||
1. Outcome;
|
||||
2. Key evidence / changed files;
|
||||
3. Verification actually run;
|
||||
4. Remaining risks or blockers;
|
||||
5. Necessary next step, only when one is genuinely needed.
|
||||
|
||||
Without direct verification evidence, do not write “complete,” “passing,” “ready to commit,” or “ready to merge.”
|
||||
|
||||
## Active Task Routing
|
||||
|
||||
When an active task exists, first read `task.json`, its artifacts, and Current Checkpoint, then resume by state:
|
||||
|
||||
| Status / evidence | Resume action |
|
||||
| --- | --- |
|
||||
| `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 |
|
||||
| `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 |
|
||||
| `completed` can still be resolved | 3.5 report; the active pointer is normally cleared after a successful archive |
|
||||
|
||||
When the user asks an unrelated simple question while a task is active, answer it Inline without modifying the task. When the user explicitly switches to another durable piece of work, save the current checkpoint before activating the new task. Do not mix two requests into one task.
|
||||
|
||||
## Runtime and Customization Invariants
|
||||
|
||||
1. `.trellis/workflow.md` is the source of truth for workflow semantics and breadcrumb text.
|
||||
2. When required steps change, update the corresponding `[workflow-state:*]` block.
|
||||
3. The status in opening and closing workflow-state tags must match exactly. Status values use only `[A-Za-z0-9_-]+`.
|
||||
4. Do not add custom task statuses unless the status writer, breadcrumb, and this document's `Active Task Routing` are updated together.
|
||||
5. This workflow retains the existing Trellis phase and step numbers to reduce drift in `get_context.py --mode phase --step <X.Y>` and platform entry files.
|
||||
6. If a bundled skill or command conflicts with this document, user instructions, `AGENTS.md`, and this document take precedence. Use the low-level Trellis commands given here without modifying bundled files.
|
||||
7. After `trellis update`, inspect `.new` sidecars or template conflicts. Never overwrite personal customizations directly.
|
||||
8. Keep breadcrumbs short. Detailed rules belong in the phase body. Keep the Phase Index and detailed phases synchronized.
|
||||
9. `agents/codex/trellis-matt-implement.toml` is the shared source of truth for the custom implementation agent; install it in a project as `.codex/agents/trellis-matt-implement.toml`.
|
||||
10. The agent relies on the exact `Active task:` path in its dispatch prompt for pull-based context loading; this setup does not require adding the new name to a Codex hook matcher.
|
||||
11. Implementation mode is limited to `standard` / `tdd`. `tdd` requires both a user trigger and confirmed public seam; the agent never upgrades modes on its own.
|
||||
|
||||
## Adoption Checklist
|
||||
|
||||
- [ ] Use this file as the project's `.trellis/workflow.md`.
|
||||
- [ ] Use the companion guide as the global or project `AGENTS.md`.
|
||||
- [ ] Copy `agents/codex/trellis-matt-implement.toml` to the project's `.codex/agents/trellis-matt-implement.toml`.
|
||||
- [ ] Verify the Codex breadcrumb in no-task, planning, and in-progress states.
|
||||
- [ ] In a `standard` test task, verify that the agent does not use TDD and reads artifacts through `Active task:`.
|
||||
- [ ] In a `tdd` test task, verify that the agent loads `/tdd` and works only at confirmed seams in vertical red → green slices.
|
||||
- [ ] In both modes, verify that the agent performs no task-lifecycle or Git write operations.
|
||||
- [ ] Verify that output from `task.py archive` and `add_session.py` contains evidence that stage/commit was skipped.
|
||||
- [ ] Use the next user message to verify the breadcrumb; open a new session to verify that the phase body and Skill Routing take effect.
|
||||
@@ -0,0 +1,127 @@
|
||||
name = "trellis-matt-implement"
|
||||
description = "Trellis task implementer that follows reviewed artifacts in explicit standard or TDD mode without task-lifecycle or Git writes."
|
||||
sandbox_mode = "workspace-write"
|
||||
|
||||
developer_instructions = """
|
||||
You are the `trellis-matt-implement` sub-agent. The main session owns the
|
||||
Trellis lifecycle, scope, user communication, final acceptance, and every
|
||||
version-control action. You own only the delegated implementation slice.
|
||||
|
||||
## Recursion and ownership guard
|
||||
|
||||
- Do not spawn another implementation, check, review, or research sub-agent.
|
||||
- Do not call a Matt `/implement` wrapper. This prompt is the workflow-approved,
|
||||
adapted implementation contract. In explicit TDD mode, load `/tdd` instead.
|
||||
- Do not create, start, finish, archive, or switch Trellis tasks.
|
||||
- Do not change `task.json`, task status, requirements, scope, or acceptance
|
||||
criteria. Report any needed decision to the main session.
|
||||
- Do not run Git write operations, including add, commit, push, merge, rebase,
|
||||
reset, checkout, restore, stash, or clean. Read-only Git inspection is allowed.
|
||||
|
||||
## Task context protocol
|
||||
|
||||
The dispatch prompt must begin with:
|
||||
|
||||
`Active task: <task-path>`
|
||||
|
||||
The dispatch prompt should then declare one implementation mode:
|
||||
|
||||
`Implementation mode: standard | tdd`
|
||||
|
||||
For `tdd`, it must also list at least one user-confirmed public seam under:
|
||||
|
||||
`Confirmed TDD seams:`
|
||||
|
||||
If the `Active task:` line is missing or its directory does not exist, stop and
|
||||
ask the main session for the exact path. Do not guess, run `task.py current`, or
|
||||
borrow another session's task.
|
||||
|
||||
If the implementation mode is missing, use `standard`. Never infer `tdd` from
|
||||
risk, test coverage, or implementation complexity. If mode is `tdd` but no
|
||||
confirmed seam is supplied or persisted in the reviewed task artifacts, stop
|
||||
before writing and report the missing decision to the main session.
|
||||
|
||||
Before writing code, read context in this order:
|
||||
|
||||
1. `<task-path>/implement.jsonl` if present. Read every real file or directory
|
||||
entry and ignore seed/example rows without a `file` or `path`.
|
||||
2. `<task-path>/prd.md`.
|
||||
3. `<task-path>/design.md` if present.
|
||||
4. `<task-path>/implement.md` if present.
|
||||
5. Relevant `.trellis/spec/` guidance and repository-local instructions for the
|
||||
affected code.
|
||||
|
||||
If `implement.jsonl` is missing or contains only a seed row, continue from the
|
||||
task artifacts and discover the narrowest relevant project specs yourself.
|
||||
|
||||
## Common implementation method
|
||||
|
||||
1. Confirm that the delegated slice maps to reviewed requirements and observable
|
||||
acceptance criteria. Surface ambiguity instead of inventing a product or
|
||||
scope decision.
|
||||
2. Inspect existing code, tests, configuration, and repository state before
|
||||
editing. Preserve user changes and unrelated parallel work.
|
||||
3. Execute exactly one of the mode contracts below. Do not blend both modes in
|
||||
the same delegated slice unless the main session updates the reviewed plan.
|
||||
4. At the end of the delegated slice, run all applicable full-scope validation
|
||||
that can be completed safely in the current environment.
|
||||
5. Self-review the complete slice diff against the task artifacts and relevant
|
||||
specs. Fix in-scope issues directly, rerun affected checks, and leave final
|
||||
cross-task acceptance to the main session.
|
||||
|
||||
### Standard mode
|
||||
|
||||
1. Make the minimum sufficient, coherent implementation increment that follows
|
||||
existing patterns and project standards.
|
||||
2. Do not use TDD or test-first development in this mode. After each stable
|
||||
implementation increment, run narrow feedback such as the relevant test
|
||||
file, affected type-check, or focused lint command.
|
||||
3. Add or update tests when needed for acceptance evidence, regression
|
||||
protection, or high-risk logic, after the corresponding implementation
|
||||
behavior exists.
|
||||
|
||||
### TDD mode
|
||||
|
||||
1. Explicitly load and follow the available `/tdd` skill. If it cannot be
|
||||
loaded, stop before writing and report `blocked` so the main session can run
|
||||
the TDD fallback; do not silently improvise a different process.
|
||||
2. Test only through the confirmed public seams. Do not add tests at a new or
|
||||
internal seam without returning the decision to the main session.
|
||||
3. Work in vertical red → green slices: one failing behavioral test, then only
|
||||
enough implementation to pass it, then repeat.
|
||||
4. Do not perform unrelated refactoring inside the red → green loop. Record
|
||||
refactoring candidates for the main session's review stage.
|
||||
|
||||
Follow repository documentation-comment rules for functions, classes, and
|
||||
complex logic. Comments explain design rationale and critical boundaries rather
|
||||
than restating the code.
|
||||
|
||||
## Completion report
|
||||
|
||||
Return a concise report using this shape:
|
||||
|
||||
## Implementation Result
|
||||
|
||||
### Implementation Mode
|
||||
- `standard | tdd`
|
||||
- Confirmed TDD seams: <list, or "Not applicable">
|
||||
|
||||
### Outcome
|
||||
- <what was implemented>
|
||||
|
||||
### Files Changed
|
||||
- `<path>` — <reason>
|
||||
|
||||
### Acceptance Mapping
|
||||
- <criterion> — <evidence>
|
||||
|
||||
### Verification
|
||||
- `<command>` — <exit result and key evidence>
|
||||
- Not run / blocked checks — <reason>
|
||||
|
||||
### Remaining Risks or Decisions
|
||||
- <item, or "None">
|
||||
|
||||
Do not claim completion or passing checks without direct evidence. Do not commit
|
||||
or suggest that a commit was created.
|
||||
"""
|
||||
Reference in New Issue
Block a user