baa-conductor

WORKFLOW.md

  1# 协作工作流
  2
  3这份文档定义多个 Codex 实例同时开发时的最小协作规则。
  4
  5## 1. 每个实例启动后要读什么
  6
  7按顺序阅读：
  8
  91. [`../DESIGN.md`](../DESIGN.md)
 102. [`TASK_OVERVIEW.md`](./TASK_OVERVIEW.md)
 113. 自己的活动任务卡，例如 `tasks/T-004-conductor-lease.md`
 12
 13## 2. 每个实例开始前要做什么
 14
 151. 在自己的任务卡里填写或更新：
 16   - `status`
 17   - `base_ref`
 18   - `updated_at`
 192. 建自己的 branch
 203. 建自己的 worktree
 214. 在新 worktree 中先执行依赖安装
 225. 只在 `write_scope` 内开发
 23
 24## 3. 每个实例开发时的规则
 25
 26- 只改自己的任务卡
 27- 不改别人的任务卡
 28- 不把聊天内容当作任务真相
 29- 不和其他任务共用 worktree
 30- 不随手改超出 `write_scope` 的文件
 31
 32如果确实需要越界：
 33
 34- 先在任务卡里记录原因
 35- 再由整合者决定是扩 scope 还是拆新任务
 36
 37## 4. 每个实例完成后要做什么
 38
 39任务完成后，必须在自己的任务卡中更新：
 40
 41- `status`
 42- `updated_at`
 43- `files_changed`
 44- `commands_run`
 45- `result`
 46- `risks`
 47- `next_handoff`
 48
 49## 5. 汇总规则
 50
 51- 各个 worker 只更新自己的任务卡
 52- 全局状态板由整合者更新
 53- 如果出现冲突，以任务卡和代码为准
 54- 已合入 `main` 的任务卡会被移到 `coordination/tasks/done/`
 55
 56## 6. 推荐的分支与 worktree 模式
 57
 58建议：
 59
 60```bash
 61git worktree add ../baa-conductor-T004 -b feat/T-004-conductor-lease main
 62cd ../baa-conductor-T004
 63npx --yes pnpm install
 64```
 65
 66对应关系：
 67
 68- 一个 task
 69- 一个 branch
 70- 一个 worktree
 71- 一个 owner
 72
 73## 7. 当前状态字段约定
 74
 75任务卡 frontmatter 的 `status` 统一使用：
 76
 77- `todo`
 78- `in_progress`
 79- `blocked`
 80- `review`
 81- `done`
 82
 83推荐最小规则：
 84
 85- 开始时：`todo -> in_progress`
 86- 遇阻塞时：改成 `blocked`
 87- 代码完成并已提交推送时：改成 `review`
 88- 整合确认完成后：改成 `done`
 89
 90## 8. 不再强制记录实例名
 91
 92为降低协作成本，当前阶段不强制记录：
 93
 94- `owner`
 95- 实例编号
 96- 长进度日志
 97
 98默认假设：
 99
100- 任务由整合者明确分配
101- 谁拿到任务，谁就改自己的任务卡状态
102- 分支名和 commit 已足够定位该任务的实际执行者
103
104## 9. 当前最小回写要求
105
106开始时最少改这几个字段：
107
108- `status`
109- `base_ref`
110- `updated_at`
111
112结束时最少补这些内容：
113
114- `status`
115- `updated_at`
116- `files_changed`
117- `commands_run`
118- `result`
119- `risks`
120- `next_handoff`