agile-coordinator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agile Coordinator

Orchestrates multiple worker agents to implement groomed tasks from the backlog, handling task assignment, progress monitoring, merge coordination, and verification.

编排多个Worker Agent来处理待办事项中已梳理的任务，负责任务分配、进度监控、合并协调以及结果验证。

Core Principle

核心原则

Coordinate, don't implement. The coordinator assigns tasks to workers, monitors their progress, coordinates merges, and verifies results. Workers execute the actual implementation via the

agile-workflow

skill.

**只协调，不执行。**协调器将任务分配给工作者，监控它们的进度，协调合并操作，并验证结果。工作者通过

agile-workflow

技能执行实际的任务实现。

Quick Reference

快速参考

When to Use

使用场景

Multiple ready tasks in the backlog need implementation
You want autonomous batch execution of development work
You need coordinated merges to avoid conflicts
You want progress tracking across multiple tasks

待办事项中有多个就绪任务需要执行
希望自主批量执行开发工作
需要协调合并操作以避免冲突
希望跟踪多个任务的进度

Invocation

调用方式

bash

/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)

bash

/agile-coordinator                    # 自动发现并执行就绪任务
/agile-coordinator TASK-001 TASK-002  # 执行指定任务
/agile-coordinator --dry-run          # 仅预览执行计划
/agile-coordinator --parallel         # 并行运行工作者
/agile-coordinator --sequential       # 依次运行工作者（默认）

Flags

标志参数

Flag	Description	Default
`--sequential`	Execute tasks one at a time	Yes
`--parallel`	Execute tasks concurrently	No
`--max-workers N`	Maximum concurrent workers	2
`--dry-run`	Show plan without executing	No
`--autonomous`	Auto-continue at all checkpoints	Yes
`--supervised`	Pause after each task completes	No
`--verbose`	Show all worker updates	No
`--summary-only`	Show major milestones only	Yes

标志	描述	默认值
`--sequential`	依次执行任务	是
`--parallel`	并发执行任务	否
`--max-workers N`	最大并发工作者数量	2
`--dry-run`	显示计划但不执行	否
`--autonomous`	在所有检查点自动继续	是
`--supervised`	每个任务完成后暂停	否
`--verbose`	显示所有工作者的更新信息	否
`--summary-only`	仅显示关键里程碑	是

Workflow Phases

工作流阶段

Phase 1: Discovery

阶段1：发现

Read the backlog to find tasks ready for implementation.

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

读取待办事项，找出可执行的就绪任务。

操作：
1. 读取context/backlog/目录下的任务文件
2. 筛选状态为ready的任务
3. 解析任务元数据（优先级、规模、依赖关系）
4. 按优先级排序（高→中→低）
5. 展示结果

输出：包含元数据的就绪任务列表

Phase 2: Planning

阶段2：规划

Create an execution plan based on task characteristics.

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

Checkpoint: TASKS_DISCOVERED

Display: Ready tasks and proposed execution plan
Auto-continue: If --autonomous flag and tasks found
Options:
```
continue
```
,
```
reorder
```
,
```
exclude [TASK-ID]
```
,
```
stop
```

根据任务特性创建执行计划。

操作：
1. 确定执行模式（串行或并行）
2. 检查任务依赖关系（任务A必须在任务B之前完成）
3. 按优先级顺序将任务分配给工作者
4. 生成工作者指令

输出：包含任务分配的执行计划

检查点：TASKS_DISCOVERED

显示内容：就绪任务和建议的执行计划
自动继续：如果设置了--autonomous标志且找到任务
选项：
```
continue
```
、
```
reorder
```
、
```
exclude [TASK-ID]
```
、
```
stop
```

Phase 3: Execution

阶段3：执行

Spawn and monitor worker agents.

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

Checkpoint: WORKER_COMPLETE (per worker)

Display: Worker summary, branch name, next action
Auto-continue: If successful and --autonomous
Options:
```
continue
```
,
```
retry
```
,
```
skip
```
,
```
stop
```

生成并监控Worker Agent。

串行模式：
  对队列中的每个任务：
    1. 使用Task工具生成工作者
    2. 工作者为该任务运行agile-workflow
    3. 通过文件系统监控进度
    4. 完成后：进入合并阶段
    5. 失败时：处理错误，决定继续/停止

并行模式：
  1. 生成最多max_workers个工作者
  2. 同时监控所有工作者
  3. 工作者完成后：将其分支加入合并队列
  4. 若还有任务，生成下一个工作者
  5. 持续处理直到所有任务完成

检查点：WORKER_COMPLETE（每个工作者完成时）

显示内容：工作者摘要、分支名称、下一步操作
自动继续：如果任务成功且设置了--autonomous
选项：
```
continue
```
、
```
retry
```
、
```
skip
```
、
```
stop
```

Phase 4: Merging

阶段4：合并

Execute merges sequentially to avoid conflicts.

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

按顺序执行合并以避免冲突。

操作：
1. 对合并队列中的每个已完成任务：
   a. git checkout main && git pull
   b. 合并分支（git merge --squash）
   c. 验证合并是否成功
   d. 删除功能分支
2. 若发生冲突：暂停并提醒用户

输出：所有分支已合并到main分支

Phase 5: Verification

阶段5：验证

Verify system integrity after all merges.

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)

Checkpoint: VERIFIED

Display: Test results, build status
Auto-continue: If all tests pass
Options:
```
done
```
,
```
investigate
```
,
```
revert
```

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

操作：
1. git checkout main && git pull --rebase
2. npm run build（验证构建是否通过）
3. npm test（运行完整测试套件）
4. 检查是否存在回归问题
5. 生成验证报告

输出：验证状态（PASSED/FAILED）

检查点：VERIFIED

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

Phase 6: Persist Progress

阶段6：持久化进度

Update source-of-truth documentation to reflect completed work.

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

Why this phase exists: Internal tracking (

.coordinator/state.json

, worker progress files) is session-scoped and ephemeral. The backlog epic files and project status are the persistent source of truth that humans and future sessions rely on. Without this phase, completed tasks remain marked "ready" in backlog files — in one real-world case, 22 merged tasks were never updated in the backlog.

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

操作：
1. 对每个已完成的任务：
   a. 更新待办事项史诗文件中的任务状态（ready → complete）
   b. 重新计算史诗级进度（例如："22/28完成" → "24/28完成"）
   c. 若依赖项已满足，解除相关阻塞任务的状态（blocked → ready）
2. 更新项目状态文件（context/status.md）：
   a. 当前项目阶段
   b. 史诗进度表
   c. 近期完成的工作
   d. 进行中/即将开展的工作摘要
3. 提交并推送文档更新

输出：待办事项和项目状态文件反映实际进度

此阶段的作用：内部跟踪文件（

.coordinator/state.json

、工作者进度文件）仅针对当前会话，是临时的。待办事项史诗文件和项目状态是持久化的权威数据源，供人工和未来会话使用。如果跳过此阶段，已完成的任务在待办事项文件中仍会标记为"ready"——在一个实际案例中，有22个已合并的任务从未在待办事项中更新状态。

Phase 7: Summary

阶段7：总结

Generate comprehensive completion report.

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

生成全面的完成报告。

输出内容：
- 已完成的任务及其PR编号和提交记录
- 指标（生成的工作者数量、合并的PR数量、新增的测试用例数量）
- 验证状态
- 已应用的文档更新
- 待办事项中剩余的任务

Worker Protocol

工作者协议

Workers are spawned using Claude Code's Task tool and run

agile-workflow

for their assigned task.

使用Claude Code的Task工具生成工作者，工作者为分配的任务运行

agile-workflow

。

Worker Instruction Template

工作者指令模板

See templates/worker-instruction.md

Key requirements for workers:

Run
```
agile-workflow
```
with autonomous mode

Write progress to

.coordinator/workers/{worker-id}/progress.json

Do NOT self-merge - signal ready-to-merge status instead
Handle all agile-workflow checkpoints automatically

查看templates/worker-instruction.md

工作者的核心要求：

以自主模式运行
```
agile-workflow
```

将进度写入

.coordinator/workers/{worker-id}/progress.json

不要自行合并分支——而是发出ready-to-merge状态信号
自动处理所有agile-workflow检查点

Progress Tracking

进度跟踪

Workers report progress via file system:

json

// .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": "..."}
  ]
}

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

json

// .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": "..."}
  ]
}

State Tracking

状态跟踪

The coordinator maintains state in

.coordinator/state.json

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
}

See references/state-tracking.md for details.

协调器在

.coordinator/state.json

中维护状态：

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。

Failure Handling

故障处理

Failure Type	Detection	Recovery
Worker fails	Progress shows `failed`	Offer retry, skip, or abort
Tests fail	npm test exits non-zero	Worker retries up to 2x
Merge conflict	git merge fails	Pause, alert user
Verification fails	Post-merge tests fail	Offer investigate or revert

See references/failure-handling.md for details.

故障类型	检测方式	恢复措施
工作者失败	进度显示 `failed`	提供重试、跳过或终止选项
测试失败	npm test返回非零值	工作者最多重试2次
合并冲突	git merge失败	暂停并提醒用户
验证失败	合并后测试失败	提供调查或回滚选项

详情请查看references/failure-handling.md。

Integration with agile-workflow

与agile-workflow的集成

The coordinator spawns workers that execute

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

Key integration points:

Workers run agile-workflow in autonomous mode
Coordinator handles merges (workers create PRs but don't merge)
Progress synced via file system
Coordinator runs verification after all merges

协调器生成执行

agile-workflow

的工作者：

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

核心集成点：

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

Anti-Patterns

反模式

AP1: Parallel Merges

AP1：并行合并

Pattern: Merging multiple PRs simultaneously Problem: Creates merge conflicts, corrupts main branch Fix: Always merge sequentially, pull before each merge

模式：同时合并多个PR 问题：导致合并冲突，损坏main分支 解决方法：始终按顺序合并，每次合并前拉取最新代码

AP2: Worker Self-Merge

AP2：工作者自行合并

Pattern: Workers merge their own branches Problem: Race conditions, uncoordinated merges Fix: Workers signal ready-to-merge, coordinator executes merges

模式：工作者合并自己的分支问题：竞态条件、未协调的合并 解决方法：工作者发出ready-to-merge信号，由协调器执行合并

AP3: No Verification

AP3：跳过验证

Pattern: Skipping post-merge verification Problem: Regressions go undetected Fix: Always run full test suite after merges complete

模式：跳过合并后的验证步骤问题：回归问题未被发现 解决方法：合并完成后始终运行完整测试套件

AP4: Skipping Documentation Updates

AP4：跳过文档更新

Pattern: Relying on internal tracking (

.coordinator/state.json

, worker progress files) without persisting to backlog epic files and project status Problem: Completed tasks remain marked "ready" in the backlog; project status stays stale; future sessions see incorrect state and may attempt duplicate work Fix: Always run Phase 6 (Persist Progress) to update backlog epic files, unblock dependent tasks, and update project status before generating the summary report

模式：仅依赖内部跟踪文件（

.coordinator/state.json

、工作者进度文件），而不更新待办事项史诗文件和项目状态问题：已完成的任务在待办事项中仍标记为"ready"；项目状态过时；未来会话会看到错误状态，可能导致重复工作 解决方法：在生成总结报告前，始终执行阶段6（持久化进度）以更新待办事项史诗文件、解除阻塞任务并更新项目状态

Example Interaction

示例交互

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%

用户: /agile-coordinator

协调器: 正在发现就绪任务...

找到2个就绪任务：
1. TASK-006 - 持久化消息状态（中等优先级，中等规模）
2. TASK-007 - 添加单元测试（高优先级，大规模）

执行计划：
- 模式：串行
- 顺序：TASK-006 → TASK-007

是否继续？[continue/reorder/stop]

用户: continue

协调器: 开始执行TASK-006...
[生成Worker 1]

**里程碑**：TASK-006 - 实现完成，测试通过

协调器: 合并task/TASK-006-persistence...
**里程碑**：TASK-006完成（提交abc123）

协调器: 开始执行TASK-007...
[生成Worker 2]

**里程碑**：TASK-007 - 实现完成，测试通过

协调器: 合并task/TASK-007-tests...
**里程碑**：TASK-007完成（提交def456）

协调器: 运行验证...
- 构建：PASSED
- 测试：47/47通过
- 覆盖率：82%

Summary

总结

Tasks completed: 2

TASK-006: merged (commit abc123)
TASK-007: merged (commit def456)

Verification: PASSED

---

已完成任务：2个

TASK-006：已合并（提交abc123）
TASK-007：已合并（提交def456）

验证状态：PASSED

---

Integration Graph

集成关系图

Inbound (From Other Skills)

入站（来自其他技能）

Source Skill	Trigger	Action
requirements-elaboration	Tasks groomed	Coordinator can execute
backlog manager	Backlog ready	Coordinator discovers tasks

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

Outbound (To Other Skills)

出站（触发其他技能）

This Action	Triggers Skill	For
Spawn worker	agile-workflow	Task implementation
Verification fails	research	Debug investigation

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

Complementary Skills

互补技能

Skill	Relationship
agile-workflow	Workers execute this skill
context-network	Manages backlog this reads

技能	关系
agile-workflow	工作者执行该技能
context-network	管理协调器读取的待办事项

Design Constraints

设计约束

Requires Claude Code's Task tool for spawning workers
Workers cannot directly communicate with each other
File system used for progress coordination
Sequential merges only (parallel merges disabled)
Assumes context network backlog structure

需要使用Claude Code的Task工具生成工作者
工作者之间无法直接通信
通过文件系统进行进度协调
仅支持顺序合并（并行合并已禁用）
假设使用context network待办事项结构

What You Do NOT Do

禁止操作

Implement tasks directly (workers do this)
Merge branches in parallel (always sequential)
Skip verification (always verify after merges)
Skip documentation updates (always persist progress to backlog epic files and project status)
Rely solely on internal tracking files as source of truth (
```
.coordinator/state.json
```
is ephemeral)
Continue after critical failures without user consent

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