metapi/.trellis/workflow.md

开发工作流

---

核心原则

1. 先规划再编码 — 在开始前先弄清楚要做什么
2. 注入规范而不是凭记忆 — 通过 hook/skill 注入指南，不要求 AI 依赖记忆
3. 持久化一切重要信息 — 研究、决策和经验都写入文件；对话会被压缩，文件不会
4. 增量开发 — 一次只处理一个任务
5. 记录经验 — 每个任务结束后，复盘并把新知识写回规范

---

Trellis 系统

开发者身份

首次使用时初始化你的身份：

python3 ./.trellis/scripts/init_developer.py <your-name>

该命令创建 .trellis/.developer（已加入 gitignore）和 .trellis/workspace//。

规范系统

.trellis/spec/ 存放按 package 和 layer 组织的编码规范。

• .trellis/spec///index.md — 规范入口，包含开发前检查和质量检查；具体规则位于它链接的 .md 文件中。
• .trellis/spec/guides/index.md — 跨 package 的思考指南。

python3 ./.trellis/scripts/get_context.py --mode packages   # 列出 package / layer

需要更新规范的时机：发现新的模式/约定、需要把 bug 预防措施写成规则，或形成新的技术决策。

任务系统

每个任务都在 .trellis/tasks/{MM-DD-name}/ 下拥有独立目录，包含 task.json、prd.md、可选的 design.md、可选的 implement.md、可选的 research/，以及供支持 sub-agent 的平台使用的上下文 manifest（implement.jsonl、check.jsonl）。

# 任务生命周期
python3 ./.trellis/scripts/task.py create "<title>" [--slug <name>] [--parent <dir>]
python3 ./.trellis/scripts/task.py start <name>          # 设置活动任务（可用时按 session 保存）
python3 ./.trellis/scripts/task.py current --source      # 显示活动任务及其来源
python3 ./.trellis/scripts/task.py finish                # 清除活动任务（触发 after_finish hook）
python3 ./.trellis/scripts/task.py archive <name>        # 移到 archive/{year-month}/
python3 ./.trellis/scripts/task.py list [--mine] [--status <s>]
python3 ./.trellis/scripts/task.py list-archive

# Code-spec 上下文（通过 JSONL 注入 implement/check agent）
# implement.jsonl / check.jsonl 在 task create 时为支持 sub-agent 的平台预置；
# 规划阶段需要时由 AI 填入真实的 spec + research 条目。
python3 ./.trellis/scripts/task.py add-context <name> <action> <file> <reason>
python3 ./.trellis/scripts/task.py list-context <name> [action]
python3 ./.trellis/scripts/task.py validate <name>

# 任务 metadata
python3 ./.trellis/scripts/task.py set-branch <name> <branch>
python3 ./.trellis/scripts/task.py set-base-branch <name> <branch>    # PR 目标分支
python3 ./.trellis/scripts/task.py set-scope <name> <scope>

# 层级（父任务/子任务）
python3 ./.trellis/scripts/task.py add-subtask <parent> <child>
python3 ./.trellis/scripts/task.py remove-subtask <parent> <child>

# 创建 PR
# 当前本地 task.py 不提供 create-pr；创建 PR 请按仓库既有流程手工执行。

使用 python3 ./.trellis/scripts/task.py --help 查看权威且最新的命令列表。

活动任务机制：task.py create 会创建任务目录，并在有 session identity 时自动设置当前 session 的活动任务指针，使规划 breadcrumb 立即生效。task.py start 写入相同指针（若已设置则幂等），并把 task.json.status 从 planning 切换为 in_progress。状态保存在 .trellis/.runtime/sessions/。如果 hook 输入、TRELLIS_CONTEXT_ID 或平台原生 session 环境中都没有 context key，task.py start 会提示并进入降级模式：仍切换 task.json.status，但不持久化 session 指针。task.py finish 删除当前 session 文件（不改变 status）。task.py archive 写入 status=completed，把目录移到 archive/，并删除仍指向该任务的运行时 session 文件。

工作区系统

在 .trellis/workspace// 下记录每个 AI session，便于跨 session 追踪。

• journal-N.md — session 日志。每个文件最多 2000 行；超出后自动创建 journal-(N+1).md。
• index.md — 个人索引（总 session 数、最近活动）。

python3 ./.trellis/scripts/add_session.py --title "会话标题" --commit "hash" --summary "会话摘要"

上下文脚本

python3 ./.trellis/scripts/get_context.py                            # 完整 session runtime
python3 ./.trellis/scripts/get_context.py --mode packages            # 可用 package / spec layer
python3 ./.trellis/scripts/get_context.py --mode phase --step <X.Y>  # 某个工作流步骤的详细指南

---

Phase Index

文档语言约定：Trellis 管理的开发文档默认使用简体中文，包括任务规划、设计、执行计划、研究记录、规范和会话日志。命令、路径、代码符号、配置字段、协议名及用户指定的原文保持规范拼写。已有英文历史文档和上游公共模板不要求批量回译；实际修改时，新增内容遵循 .trellis/spec/guides/documentation-language.md。

Phase 1: Plan    → 分类请求、取得创建任务的同意，然后写入规划文档
Phase 2: Execute → 仅在任务 status 为 in_progress 后实现
Phase 3: Finish  → 验证、更新规范、提交并收尾

[workflow-state:planning] 当前任务处于规划阶段（status=planning）。只做需求探索、仓库研究和文档整理：保持 prd.md 只写需求/约束/验收标准；复杂任务补齐 design.md、implement.md 和 research/；在 sub-agent dispatch 模式下整理 implement.jsonl/check.jsonl 的真实 spec/research 条目。完成规划后先取得用户的实现确认，再运行 python3 ./.trellis/scripts/task.py start <task-dir>；在此之前不要修改产品代码或声称任务已进入实现。 [/workflow-state:planning]

[workflow-state:planning-inline] 当前任务处于规划阶段，且 Codex dispatch_mode=inline：在主 session 中完成需求探索、源码研究、prd.md/design.md/implement.md/research/ 和 manifest 整理。status=planning 时不要实现产品代码；规划文档评审并取得用户确认后，才运行 python3 ./.trellis/scripts/task.py start <task-dir>。 [/workflow-state:planning-inline]

请求分流

• 简单问答或小任务：只询问本轮是否要创建 Trellis task。用户回答否时，本 session 跳过 Trellis。
• 复杂任务：询问是否允许创建 Trellis task 并进入规划阶段。用户回答否时，不做大范围 inline 实现；改为解释、澄清范围或建议拆小。
• 用户同意创建 task 不等于同意开始实现；仍必须先完成规划。

规划文档

• prd.md — 需求、约束和验收标准。不要在其中放技术设计或执行清单。
• design.md — 复杂任务的技术设计：边界、contract、数据流、权衡、兼容性、发布/回滚形态。
• implement.md — 复杂任务的执行计划：有序清单、验证命令、评审门和回滚点。
• implement.jsonl / check.jsonl — sub-agent 上下文使用的 spec/research manifest，不替代 implement.md。
• 轻量任务可以只有 prd.md；复杂任务在 task.py start 前必须有 prd.md、design.md 和 implement.md。

父子任务树

当一次请求包含多个可独立验证的交付物时，使用 parent task。父任务拥有源需求、任务地图、跨子任务验收标准和最终集成评审；除非父任务自身也有直接工作，否则不要把它作为实现目标。

子任务用于可以独立规划、实现、检查和归档的交付物。父子结构不是依赖系统：如果子任务 B 依赖子任务 A，必须在 B 的 prd.md / implement.md 中写明顺序，并让每个子任务的验收条件可测试。

使用 task.py create "