agile-coordinator

アジャイルコーディネーター

複数のワーカーエージェントを調整し、バックログから整理されたタスクを実装します。タスクの割り当て、進捗の監視、マージの調整、検証を行います。

基本原則

調整に徹し、実装はしません。 コーディネーターはワーカーにタスクを割り当て、進捗を監視し、マージを調整して、結果を検証します。実際の実装は、ワーカーが 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	タスクを一度に1つずつ実行します	はい
--parallel	タスクを並行して実行します	いいえ
--max-workers N	同時に実行するワーカーの最大数	2
--dry-run	実行せずに計画を表示します	いいえ
--autonomous	すべてのチェックポイントで自動的に続行します	はい
--supervised	タスクの完了ごとに一時停止します	いいえ
--verbose	ワーカーの更新をすべて表示します	いいえ
--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：実行

ワーカーエージェントを起動して監視します。

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（ワーカーごと）

• 表示内容：ワーカーの概要、ブランチ名、次のアクション
• 自動続行：成功し、--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、ワーカーの進捗ファイル）はセッション単位で、一時的なものです。バックログのエピックファイルとプロジェクトのステータスは、人間や後続のセッションが参照する永続的な信頼できる情報源です。このフェーズがないと、完了したタスクがバックログファイルで「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

---

ワーカープロトコル

ワーカーは Claude Code の Task ツールを使って起動され、割り当てられたタスクについて agile-workflow を実行します。

ワーカー指示テンプレート

templates/worker-instruction.md を参照してください。

ワーカーの主な要件：

1. 自律モードで agile-workflow を実行する
2. 進捗を .coordinator/workers/{worker-id}/progress.json に書き込む
3. 自分でマージしない。代わりに、マージ可能な状態であることを通知する
4. agile-workflow のすべてのチェックポイントを自動的に処理する

進捗の追跡

ワーカーはファイルシステムを介して進捗を報告します。

// .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 を参照してください。

---

失敗への対処

失敗の種類	検出方法	復旧方法
ワーカーの失敗	進捗に failed と表示されます	再試行、スキップ、中止を提示します
テストの失敗	npm test がゼロ以外の終了コードを返します	ワーカーが最大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 を同時にマージする 問題：マージコンフリクトが発生し、main ブランチが破損します 対処：必ず順番にマージし、各マージの前に pull します

AP2：ワーカーによる自己マージ

パターン：ワーカーが自分のブランチをマージする 問題：競合状態や、調整されていないマージが発生します 対処：ワーカーがマージ可能であることを通知し、コーディネーターがマージを実行します

AP3：検証の未実施

パターン：マージ後の検証を省略する 問題：リグレッションが検出されません 対処：マージ完了後は、必ずテストスイート全体を実行します

AP4：ドキュメント更新の省略

パターン：バックログのエピックファイルやプロジェクトステータスに反映せず、内部トラッキング（.coordinator/state.json、ワーカーの進捗ファイル）だけに頼る 問題：完了したタスクがバックログで「ready」のままになります。プロジェクトステータスも古いままになり、後続のセッションで誤った状態が参照され、作業が重複する可能性があります 対処：必ずフェーズ 6（進捗の永続化）を実行し、サマリーレポートの生成前にバックログのエピックファイルを更新し、依存タスクのブロックを解除して、プロジェクトステータスを更新します

---

やり取りの例

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 のバックログ構造を前提としています

行わないこと

• タスクを直接実装する（実装はワーカーが行います）
• ブランチを並列にマージする（必ず順番に実行します）
• 検証を省略する（マージ後は必ず検証します）
• ドキュメントの更新を省略する（進捗は必ずバックログのエピックファイルとプロジェクトステータスに反映します）
• 内部トラッキングファイルだけを信頼できる情報源として扱う（.coordinator/state.json は一時的なものです）
• ユーザーの同意なく、重大な失敗の後も続行する