agile-coordinator

Agile Coordinator

协调多个工作 Agent，从待办事项中选取已梳理的任务并推进实施，负责分配任务、监控进度、协调合并和验证结果。

核心原则

负责协调，不负责实施。 协调器将任务分配给工作 Agent，监控其进度，协调合并并验证结果。工作 Agent 通过 agile-workflow 技能执行实际实施工作。

快速参考

适用场景

• 待办事项中有多个可立即开始实施的任务
• 希望自主批量执行开发工作
• 需要协调合并以避免冲突
• 希望跟踪多个任务的进度

调用

/agile-coordinator                    # Auto-discover and execute ready tasks
/agile-coordinator TASK-001 TASK-002  # Execute specific tasks
/agile-coordinator --dry-run          # Preview execution plan only
/agile-coordinator --parallel         # Run workers in parallel
/agile-coordinator --sequential       # Run workers one at a time (default)

标志

标志	说明	默认值
--sequential	一次执行一个任务	是
--parallel	并发执行任务	否
--max-workers N	最大并发工作 Agent 数量	2
--dry-run	显示计划但不执行	否
--autonomous	在所有检查点自动继续	是
--supervised	每个任务完成后暂停	否
--verbose	显示所有工作 Agent 更新	否
--summary-only	仅显示主要里程碑	是

---

工作流阶段

阶段 1：发现

读取待办事项，查找可开始实施的任务。

Actions:
1. Read context/backlog/ for task files
2. Filter to status: ready
3. Parse task metadata (priority, size, dependencies)
4. Sort by priority (high → medium → low)
5. Present findings

Output: List of ready tasks with metadata

阶段 2：规划

根据任务特征制定执行计划。

Actions:
1. Determine execution mode (sequential or parallel)
2. Check for task dependencies (A must complete before B)
3. Assign tasks to workers in priority order
4. Generate worker instructions

Output: Execution plan with task assignments

检查点：TASKS_DISCOVERED

• 显示：可执行任务和拟定的执行计划
• 自动继续：如果设置了 --autonomous 标志且找到任务
• 选项：continue、reorder、exclude [TASK-ID]、stop

阶段 3：执行

启动并监控工作 Agent。

For SEQUENTIAL mode:
  for each task in queue:
    1. Spawn worker with Task tool
    2. Worker runs agile-workflow for the task
    3. Monitor progress via file system
    4. When complete: proceed to merge phase
    5. On failure: handle error, decide continue/stop

For PARALLEL mode:
  1. Spawn workers up to max_workers
  2. Monitor all workers concurrently
  3. As workers complete: queue their branches for merge
  4. Spawn next worker if tasks remain
  5. Continue until all tasks processed

检查点：WORKER_COMPLETE（每个工作 Agent）

• 显示：工作 Agent 摘要、分支名称、下一步操作
• 自动继续：如果执行成功且设置了 --autonomous 标志
• 选项：continue、retry、skip、stop

阶段 4：合并

依次执行合并，以避免冲突。

Actions:
1. For each completed task in merge queue:
   a. git checkout main && git pull
   b. Merge branch (git merge --squash)
   c. Verify merge succeeded
   d. Delete feature branch
2. If conflict: pause and alert user

Output: All branches merged to main

阶段 5：验证

所有合并完成后，验证系统完整性。

Actions:
1. git checkout main && git pull --rebase
2. npm run build (verify build passes)
3. npm test (run full test suite)
4. Check for regressions
5. Generate verification report

Output: Verification status (PASSED/FAILED)

检查点：VERIFIED

• 显示：测试结果、构建状态
• 自动继续：如果所有测试均通过
• 选项：done、investigate、revert

阶段 6：保存进度

更新权威文档，以反映已完成的工作。

Actions:
1. For each completed task:
   a. Update task status in the backlog epic file (ready → complete)
   b. Recalculate epic-level progress (e.g., "22/28 complete" → "24/28 complete")
   c. Unblock dependent tasks (blocked → ready) if blockers are now satisfied
2. Update project status file (context/status.md):
   a. Current project phase
   b. Epic progress table
   c. Recently completed work
   d. Active/upcoming work summary
3. Commit and push documentation updates

Output: Backlog and project status files reflect actual progress

为何需要此阶段： 内部跟踪文件（.coordinator/state.json、工作 Agent 进度文件）仅限当前会话使用，且不会持久保存。待办事项中的史诗任务文件和项目状态才是持久的权威信息来源，人类和后续会话都会依赖这些信息。若缺少此阶段，已完成的任务在待办事项文件中仍会标记为“ready”——在一个真实案例中，22 个已合并的任务始终未在待办事项中更新。

阶段 7：摘要

生成完整的完成报告。

Output:
- Tasks completed with PR numbers and commits
- Metrics (workers spawned, PRs merged, tests added)
- Verification status
- Documentation updates applied
- Remaining backlog tasks

---

工作 Agent 协议

使用 Claude Code 的 Task 工具启动工作 Agent，并运行 agile-workflow 处理分配的任务。

工作 Agent 指令模板

参见 templates/worker-instruction.md

工作 Agent 的关键要求：

1. 以自主模式运行 agile-workflow
2. 将进度写入 .coordinator/workers/{worker-id}/progress.json
3. 不要自行合并，而是报告已准备好合并的状态
4. 自动处理所有 agile-workflow 检查点

进度跟踪

工作 Agent 通过文件系统报告进度：

// .coordinator/workers/worker-1/progress.json
{
  "worker_id": "worker-1",
  "task_id": "TASK-006",
  "status": "in_progress|completed|failed|ready-to-merge",
  "phase": "implement|review|merge-prep|merge-complete",
  "commit": null,
  "branch": "task/TASK-006-description",
  "last_update": "2026-01-20T10:15:00Z",
  "milestones": [
    {"phase": "implement", "timestamp": "..."},
    {"phase": "review", "timestamp": "..."}
  ]
}

---

状态跟踪

协调器在 .coordinator/state.json 中维护状态：

{
  "session_id": "coord-2026-01-20-abc123",
  "state": "EXECUTING",
  "config": {
    "execution_mode": "sequential",
    "autonomy_level": "autonomous"
  },
  "tasks": {
    "queued": ["TASK-008"],
    "in_progress": ["TASK-007"],
    "completed": ["TASK-006"],
    "failed": []
  },
  "workers": [...],
  "merge_queue": [],
  "verification": null
}

详情请参见 references/state-tracking.md。

---

故障处理

故障类型	检测方式	恢复方式
工作 Agent 失败	进度显示为 failed	提供重试、跳过或中止选项
测试失败	npm test 以非零状态码退出	工作 Agent 最多重试 2 次
合并冲突	git merge 失败	暂停并提醒用户
验证失败	合并后测试失败	提供调查或还原选项

详情请参见 references/failure-handling.md。

---

与 agile-workflow 集成

协调器会启动执行 agile-workflow 的工作者：

agile-coordinator (orchestrator)
    │
    ├── Worker 1 → agile-workflow --task TASK-006
    ├── Worker 2 → agile-workflow --task TASK-007
    └── Worker 3 → agile-workflow --task TASK-008

关键集成点：

• 工作者以自主模式运行 agile-workflow
• 协调器负责合并（工作者创建 PR，但不执行合并）
• 通过文件系统同步进度
• 所有合并完成后，协调器会运行验证

---

反模式

AP1：并行合并

模式：同时合并多个 PR 问题：产生合并冲突，损坏主分支 修复：始终按顺序合并，并在每次合并前拉取最新代码

AP2：工作者自行合并

模式：工作者合并自己的分支 问题：产生竞态条件，合并缺乏协调 修复：工作者发出准备合并的信号，由协调器执行合并

AP3：不进行验证

模式：跳过合并后的验证 问题：回归问题无法被发现 修复：合并完成后，始终运行完整测试套件

AP4：跳过文档更新

模式：依赖内部跟踪文件（.coordinator/state.json、工作者进度文件），但未将进度写入积压事项 Epic 文件和项目状态 问题：已完成的任务在积压事项中仍标记为“就绪”；项目状态过时；后续会话会看到错误状态，可能重复执行任务 修复：始终运行第 6 阶段（持久化进度），更新积压事项 Epic 文件、解除依赖任务的阻塞，并在生成摘要报告前更新项目状态

---

交互示例

User: /agile-coordinator

Coordinator: Discovering ready tasks...

Found 2 ready tasks:
1. TASK-006 - Persistent Message Status (medium priority, medium size)
2. TASK-007 - Add Unit Tests (high priority, large size)

Execution Plan:
- Mode: sequential
- Order: TASK-006 → TASK-007

Proceed? [continue/reorder/stop]

User: continue

Coordinator: Starting TASK-006...
[Spawns Worker 1]

**Milestone**: TASK-006 - Implementation complete, tests passing

Coordinator: Merging task/TASK-006-persistence...
**Milestone**: TASK-006 complete (commit abc123)

Coordinator: Starting TASK-007...
[Spawns Worker 2]

**Milestone**: TASK-007 - Implementation complete, tests passing

Coordinator: Merging task/TASK-007-tests...
**Milestone**: TASK-007 complete (commit def456)

Coordinator: Running verification...
- Build: PASSED
- Tests: 47/47 passing
- Coverage: 82%

## Summary
Tasks completed: 2
- TASK-006: merged (commit abc123)
- TASK-007: merged (commit def456)

Verification: PASSED

---

集成图

入站（来自其他技能）

来源技能	触发条件	操作
requirements-elaboration	任务已梳理	协调器可以执行
backlog manager	积压事项已就绪	协调器发现任务

出站（触发其他技能）

此操作	触发技能	用途
启动工作者	agile-workflow	任务实现
验证失败	research	调试调查

互补技能

技能	关系
agile-workflow	工作者执行此技能
context-network	管理此处读取的积压事项

---

设计约束

• 需要使用 Claude Code 的 Task 工具来启动工作者
• 工作者无法直接相互通信
• 使用文件系统协调进度
• 仅允许按顺序合并（禁用并行合并）
• 假设采用 context network 积压事项结构

你不会做的事

• 直接实现任务（由工作者完成）
• 并行合并分支（始终按顺序合并）
• 跳过验证（合并后始终进行验证）
• 跳过文档更新（始终将进度持久化到积压事项 Epic 文件和项目状态）
• 仅依赖内部跟踪文件作为事实来源（.coordinator/state.json 是临时文件）
• 未经用户同意，在发生严重故障后继续执行