Agile Coordinator

Agile Coordinator

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

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.

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

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

Flags

---

Workflow Phases

Phase 1: Discovery

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

Phase 2: Planning

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

Phase 3: Execution

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

Phase 4: Merging

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

Phase 5: Verification

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

Phase 6: Persist Progress

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.

Phase 7: Summary

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

---

Worker Protocol

Workers are spawned using Claude Code's Task tool and run agile-workflow for their assigned task.

Worker Instruction Template

See templates/worker-instruction.md

Key requirements for workers: 1. Run agile-workflow with autonomous mode 2. Write progress to .coordinator/workers/{worker-id}/progress.json 3. Do NOT self-merge - signal ready-to-merge status instead 4. Handle all agile-workflow checkpoints automatically

Progress Tracking

Workers report progress via file system:

// .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:

{
  "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.

---

Failure Handling

See references/failure-handling.md for details.

---

Integration with 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

---

Anti-Patterns

AP1: Parallel Merges

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

AP2: Worker Self-Merge

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

AP3: No Verification

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

AP4: Skipping Documentation Updates

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

---

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%

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

Verification: PASSED

---

Integration Graph

Inbound (From Other Skills)

Outbound (To Other Skills)

Complementary Skills

---

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

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

Failure Handling

How the coordinator handles various failure scenarios.

Failure Categories

1. Worker Implementation Failure

Cause: Tests fail, build fails, or worker encounters error during implementation.

Detection:

• Worker progress file shows status: failed
• Worker progress file shows error: "..." field

Recovery Options:

Retry Limits: Max 2 retries per task before requiring human intervention.

2. Test Failure

Cause: Tests fail during worker implementation phase.

Detection:

• Worker logs show test failures
• npm test exits with non-zero code

Recovery:

• Worker should attempt to fix (up to 2 attempts)
• If worker cannot fix, mark as failed
• Coordinator offers retry with fresh context or skip

Example Worker Retry:

Attempt 1: 3 tests failing
Worker fixes test assertions
Attempt 2: 1 test still failing
Worker investigates root cause
Attempt 3: All tests pass

3. Build/Test Failure in Review

Cause: Tests or build fail after implementation complete.

Detection:

• Test suite fails during review phase
• Build fails during validation

Recovery:

• Worker should return to implementation phase
• Fix the issue, run tests locally
• Re-run review when tests pass
• If repeated failures, mark as failed

4. Merge Conflict

Cause: Branch cannot merge due to conflicts with main.

Detection:

• git merge fails with conflict markers
• git merge --squash fails with conflict error

Recovery Options:

See merge-coordination.md for details.

5. Verification Failure

Cause: Tests fail after all PRs merged.

Detection:

• npm test fails in verification phase
• Build fails in verification phase

Severity: HIGH - merged code may have regressions.

Recovery Options:

6. Infrastructure Failure

Cause: Git unavailable, network issues, disk full, etc.

Detection:

• Git commands fail with connection errors
• File system operations fail

Recovery:

• Retry with exponential backoff (1s, 2s, 4s)
• Max 3 retries before failing
• Preserve state for resume

Failure Recovery Flowchart

            FAILURE DETECTED
                  │
                  ▼
         ┌───────────────┐
         │ Categorize    │
         │ Failure       │
         └───────┬───────┘
                 │
    ┌────────────┼────────────┬────────────┐
    ▼            ▼            ▼            ▼
 Worker      Merge       Verify      Infra
 Failure     Conflict    Failure     Failure
    │            │            │            │
    ▼            ▼            ▼            ▼
┌────────┐  ┌────────┐  ┌────────┐  ┌────────┐
│ Retry? │  │ Auto-  │  │Revert? │  │ Retry  │
│ Skip?  │  │resolve?│  │        │  │ w/back │
│ Abort? │  │Manual? │  │        │  │ off    │
└────┬───┘  └────┬───┘  └────┬───┘  └────┬───┘
     │           │           │           │
     ▼           ▼           ▼           ▼
  Continue    Continue    Continue    Continue
  or Stop     or Stop     or Stop     or Stop

Graceful Degradation

Principle

When failures occur, preserve as much progress as possible.

Rules

1. Complete what you can: If one task fails, other independent tasks can continue 2. Never leave orphans: Clean up branches, worktrees on abort 3. Preserve state: Always save state before stopping 4. Clear communication: Tell user exactly what happened and options

Example: Partial Completion

Tasks: TASK-006, TASK-007, TASK-008

TASK-006: Completed, merged
TASK-007: Failed (tests not passing)
TASK-008: Not started

Coordinator response:
"TASK-006 completed successfully.
TASK-007 failed: 3 tests not passing.

Options:
[retry TASK-007] - Try again with fresh context
[skip to TASK-008] - Continue with remaining tasks
[stop] - Stop here (TASK-006 remains merged)"

Error Messages

Standard Error Display

╔════════════════════════════════════════════════════════════════╗
║  ERROR: [Category]                                             ║
╠════════════════════════════════════════════════════════════════╣
║                                                                 ║
║  Task: [TASK-ID] - [Title]                                     ║
║  Phase: [phase]                                                 ║
║  Error: [error message]                                         ║
║                                                                 ║
║  Details:                                                       ║
║  [relevant details, logs, file paths]                          ║
║                                                                 ║
║  Options:                                                       ║
║  [option1] - Description                                        ║
║  [option2] - Description                                        ║
║                                                                 ║
║  Progress so far:                                               ║
║  - TASK-006: completed (merged)                                 ║
║  - TASK-007: failed                                             ║
╚════════════════════════════════════════════════════════════════╝

Logging

What to Log

• Timestamp of failure
• Failure category
• Task and worker context
• Error message and stack trace (if available)
• Recovery action taken
• Outcome of recovery

Log Location

.coordinator/logs/
├── session-2026-01-20.log    # Session log
└── errors/
    └── TASK-007-failure.log  # Per-task error details

Log Format

[2026-01-20T10:25:00Z] ERROR worker-2 TASK-007 implementation
  Phase: implement
  Error: 3 tests failing in message-tools.test.ts
  Details: Expected array of 3, received array of 2
  Action: Offering retry

[2026-01-20T10:25:05Z] INFO user selected: retry

[2026-01-20T10:25:10Z] INFO spawning worker-3 for TASK-007 (retry 1)

Merge Coordination

How the coordinator manages merges to prevent conflicts.

Core Principle

All merges are sequential. Even in parallel execution mode, PRs are merged one at a time to main. This prevents merge conflicts and maintains a clean commit history.

Why Sequential Merges

The Problem with Parallel Merges

Scenario: Two PRs ready simultaneously

PR #1 (TASK-006)         PR #2 (TASK-007)
    │                         │
    ▼                         ▼
 merge to main            merge to main
    │                         │
    └─────────┬───────────────┘
              │
              ▼
        CONFLICT!

Both PRs were based on the same main.
When merged simultaneously, they may
modify the same files or have
incompatible changes.

Sequential Merge Solution

PR #1 (TASK-006)         PR #2 (TASK-007)
    │                         │
    ▼                         │ (waits)
 merge to main                │
    │                         │
    ▼                         ▼
main updated ────────► rebase PR #2
                              │
                              ▼
                        merge to main
                              │
                              ▼
                         main updated

No conflicts because each merge
happens on the latest main.

Merge Queue

The coordinator maintains a merge queue for branches ready to merge.

Queue Structure

{
  "merge_queue": [
    {
      "task_id": "TASK-006",
      "worker_id": "worker-1",
      "branch": "task/TASK-006-persistence",
      "added_at": "2026-01-20T10:15:00Z"
    },
    {
      "task_id": "TASK-007",
      "worker_id": "worker-2",
      "branch": "task/TASK-007-tests",
      "added_at": "2026-01-20T10:18:00Z"
    }
  ]
}

Queue Processing

While merge_queue not empty:
  1. Take first branch from queue
  2. git checkout main && git pull
  3. Attempt merge
  4. If success:
     - Remove from queue
     - Update worker status to completed
     - Delete feature branch
  5. If conflict:
     - Pause and alert user
     - Offer resolution options

Merge Execution

Squash Merge (Recommended)

# Ensure on latest main
git checkout main
git pull --rebase origin main

# Squash merge the feature branch
git merge --squash task/TASK-006-persistence

# Commit with task reference
git commit -m "feat(TASK-006): Persistent message status storage"

# Push to origin
git push origin main

# Delete feature branch
git branch -d task/TASK-006-persistence
git push origin --delete task/TASK-006-persistence

Regular Merge

# Ensure on latest main
git checkout main
git pull --rebase origin main

# Merge the feature branch
git merge --no-ff task/TASK-006-persistence

# Push to origin
git push origin main

# Delete feature branch
git branch -d task/TASK-006-persistence
git push origin --delete task/TASK-006-persistence

Conflict Handling

Detection

Conflicts are detected when:

• git merge fails with conflict markers
• git merge --squash fails with conflict error

Resolution Options

╔════════════════════════════════════════════════════════════════╗
║  MERGE CONFLICT: task/TASK-007-tests                           ║
╠════════════════════════════════════════════════════════════════╣
║                                                                 ║
║  Conflicting files:                                             ║
║  - src/mastra/schemas/message-status.ts                        ║
║  - src/mastra/services/message-processor.ts                    ║
║                                                                 ║
║  Options:                                                       ║
║  [resolve] - Attempt automatic resolution                       ║
║  [manual] - Exit for manual conflict resolution                 ║
║  [skip] - Skip this branch, continue with others                ║
║  [abort] - Stop merge process entirely                          ║
╚════════════════════════════════════════════════════════════════╝

Automatic Resolution

For simple conflicts, the coordinator can attempt:

# Checkout the feature branch
git checkout task/TASK-007-tests

# Rebase onto latest main
git rebase origin/main

# If conflicts during rebase:
# - For auto-generated files: accept theirs/ours
# - For code: use merge tool or abort

# After resolution, checkout main and merge
git checkout main
git merge --squash task/TASK-007-tests

Manual Resolution

If automatic resolution fails:

1. Coordinator pauses 2. User resolves conflicts manually 3. User pushes resolved changes 4. User signals coordinator to continue 5. Coordinator verifies CI passes 6. Coordinator completes merge

Rollback Procedures

Reverting a Single Merge

If verification fails after a merge:

# Find the merge commit
git log --oneline -5

# Revert the merge commit
git revert -m 1 <merge-commit-sha>

# Push the revert
git push origin main

Reverting Multiple Merges

If multiple merges need to be reverted:

# Option 1: Revert each in reverse order
git revert -m 1 <latest-merge>
git revert -m 1 <previous-merge>

# Option 2: Reset to known good state
git reset --hard <last-known-good-sha>
git push --force-with-lease origin main  # DANGEROUS

Best Practices

1. Always pull before merge: Ensure you have the latest main 2. Use squash merge: Creates cleaner history 3. Delete branches after merge: Prevents branch pollution 4. Run tests before merge: Ensure tests pass before merging 5. One merge at a time: Never attempt parallel merges 6. Keep merge queue visible: Log what's pending

State Tracking

How the coordinator maintains and persists its state.

State Machine

┌──────────┐
│   IDLE   │ ◄─────────────────────────────┐
└────┬─────┘                               │
     │ /agile-coordinator                  │
     ▼                                     │
┌────────────┐                             │
│ DISCOVERING│                             │
└────┬───────┘                             │
     │ tasks found                         │
     ▼                                     │
┌──────────┐                               │
│ PLANNING │                               │
└────┬─────┘                               │
     │ plan confirmed                      │
     ▼                                     │
┌───────────┐      ┌─────────┐            │
│ EXECUTING │─────►│ MERGING │            │
└────┬──────┘      └────┬────┘            │
     │ all complete     │ all merged      │
     │◄─────────────────┘                 │
     ▼                                     │
┌───────────┐                              │
│ VERIFYING │                              │
└────┬──────┘                              │
     │ verified                            │
     ▼                                     │
┌────────────┐                             │
│ SUMMARIZING│─────────────────────────────┘
└────────────┘

State File

Location: .coordinator/state.json

Full Schema

{
  "session_id": "coord-2026-01-20-abc123",
  "state": "EXECUTING",
  "started_at": "2026-01-20T10:00:00Z",
  "updated_at": "2026-01-20T10:25:00Z",

  "config": {
    "execution_mode": "sequential",
    "max_workers": 2,
    "autonomy_level": "autonomous",
    "reporting": "summary-only"
  },

  "tasks": {
    "queued": ["TASK-008"],
    "in_progress": ["TASK-007"],
    "completed": ["TASK-006"],
    "failed": []
  },

  "workers": [
    {
      "id": "worker-1",
      "task_id": "TASK-006",
      "status": "completed",
      "pr_number": 123,
      "commit": "abc123",
      "merged": true,
      "started_at": "2026-01-20T10:01:00Z",
      "completed_at": "2026-01-20T10:20:00Z"
    },
    {
      "id": "worker-2",
      "task_id": "TASK-007",
      "status": "in_progress",
      "pr_number": null,
      "commit": null,
      "merged": false,
      "started_at": "2026-01-20T10:21:00Z",
      "completed_at": null
    }
  ],

  "merge_queue": [123],

  "verification": {
    "status": null,
    "tests_total": null,
    "tests_passed": null,
    "build_status": null,
    "completed_at": null
  },

  "summary": null
}

State Transitions

IDLE → DISCOVERING

Triggered by: /agile-coordinator invocation

Actions: 1. Create .coordinator/ directory 2. Generate session_id 3. Initialize state.json 4. Read backlog for ready tasks

DISCOVERING → PLANNING

Triggered by: Tasks found in backlog

Actions: 1. Parse task metadata 2. Sort by priority 3. Check dependencies 4. Generate execution plan 5. Display checkpoint for confirmation

PLANNING → EXECUTING

Triggered by: User confirms plan (or auto-continue)

Actions: 1. Update config with flags 2. Initialize task queues 3. Spawn first worker(s)

EXECUTING → MERGING

Triggered by: Worker reports ready-to-merge

Actions: 1. Add PR to merge_queue 2. Execute merge 3. Update worker status 4. Return to EXECUTING if tasks remain

EXECUTING → VERIFYING

Triggered by: All tasks completed or in merge_queue empty

Actions: 1. Pull latest main 2. Run build 3. Run tests 4. Record results

VERIFYING → SUMMARIZING

Triggered by: Verification complete

Actions: 1. Generate summary report 2. Display to user 3. Cleanup state

SUMMARIZING → IDLE

Triggered by: Summary displayed

Actions: 1. Archive or remove .coordinator/ 2. Return to idle state

Resume from Interrupted Session

If the coordinator is interrupted, it can resume:

Detection

On /agile-coordinator invocation: 1. Check if .coordinator/state.json exists 2. If exists and state != IDLE: offer resume

Resume Prompt

Found interrupted session:
- Session: coord-2026-01-20-abc123
- State: EXECUTING
- Completed: TASK-006
- In Progress: TASK-007

Options:
[resume] Continue from where you left off
[restart] Start fresh (clears progress)
[abort] Stop and cleanup

Resume Actions

By state:

• DISCOVERING: Re-run discovery
• PLANNING: Show plan again for confirmation
• EXECUTING: Check worker progress, continue monitoring
• MERGING: Check merge status, continue queue
• VERIFYING: Re-run verification
• SUMMARIZING: Generate summary again

Cleanup

On Successful Completion

# Option 1: Archive
mv .coordinator .coordinator.archive.$(date +%s)

# Option 2: Remove
rm -rf .coordinator

On Abort

# Clean up any orphaned branches
git branch -D task/TASK-* 2>/dev/null || true

# Remove coordinator state
rm -rf .coordinator

Worker Management

How the coordinator spawns, monitors, and manages worker agents.

Spawning Workers

Workers are spawned using Claude Code's Task tool with the general-purpose subagent type.

Task Tool Invocation

Task({
  description: "Implement TASK-006",
  prompt: workerInstruction,
  subagent_type: "general-purpose"
})

Worker Instruction Structure

Each worker receives a prompt that includes:

1. Task Assignment: Which task to implement 2. Skill Invocation: Run agile-workflow for the task 3. Progress Reporting: Write to .coordinator/workers/{id}/progress.json 4. Merge Protocol: Don't self-merge, signal ready-to-merge instead 5. Checkpoint Behavior: Auto-continue at all agile-workflow checkpoints

See ../templates/worker-instruction.md for the full template.

Progress Monitoring

File-Based Communication

Workers cannot directly communicate with the coordinator or each other. Instead, they write progress to the file system:

.coordinator/
├── state.json                    # Coordinator state
└── workers/
    ├── worker-1/
    │   └── progress.json         # Worker 1 progress
    └── worker-2/
        └── progress.json         # Worker 2 progress

Progress File Format

{
  "worker_id": "worker-1",
  "task_id": "TASK-006",
  "status": "in_progress",
  "phase": "implement",
  "pr_number": null,
  "branch": "task/TASK-006-persistence",
  "commits": 0,
  "tests_passing": null,
  "last_update": "2026-01-20T10:15:00Z",
  "milestones": [
    {
      "phase": "started",
      "timestamp": "2026-01-20T10:00:00Z"
    },
    {
      "phase": "implement",
      "timestamp": "2026-01-20T10:05:00Z"
    }
  ],
  "error": null
}

Status Values

Phase Values

Polling Strategy

The coordinator polls worker progress files to track status:

Sequential Mode

While current_worker not complete:
  1. Check worker progress file
  2. If status changed: log milestone
  3. If failed: handle failure
  4. If ready-to-merge: proceed to merge
  5. Sleep 5 seconds

Parallel Mode

While any worker active:
  1. Check all worker progress files
  2. For each status change: log milestone
  3. For each failure: handle failure
  4. For each ready-to-merge: add to merge queue
  5. If workers < max and tasks remain: spawn next
  6. Sleep 5 seconds

Worker Lifecycle

SPAWNED
   │
   ▼
IMPLEMENTING ──────┐
   │               │ (if error)
   ▼               │
REVIEWING          │
   │               │
   ▼               │
PR_CREATED         │
   │               │
   ▼               │
AWAITING_CI ───────┤
   │               │
   ▼               │
READY_TO_MERGE     │
   │               │
   ▼               ▼
COMPLETED      FAILED

Handling Worker Completion

Successful Completion

When a worker reports ready-to-merge:

1. Log the milestone 2. Add PR to merge queue 3. If sequential: proceed to merge phase 4. If parallel: continue monitoring others

Worker Failure

When a worker reports failed:

1. Log the error details 2. Check error type (recoverable vs fatal) 3. Offer options: retry, skip, abort 4. If retry: spawn new worker with same task 5. If skip: move to next task 6. If abort: stop all workers, cleanup

Cleanup

After all tasks complete or on abort:

1. Remove .coordinator/workers/ directory 2. Update .coordinator/state.json to IDLE 3. Optionally remove .coordinator/ entirely

Summary Report Template

Template for the final orchestration summary. Replace {{variables}} with actual values.

---

Full Template

## Orchestration Summary

**Session**: {{SESSION_ID}}
**Started**: {{START_TIME}}
**Completed**: {{END_TIME}}
**Duration**: {{DURATION}}

---

### Configuration

| Setting | Value |
|---------|-------|
| Execution Mode | {{EXECUTION_MODE}} |
| Max Workers | {{MAX_WORKERS}} |
| Autonomy Level | {{AUTONOMY_LEVEL}} |

---

### Tasks Completed

{{#each COMPLETED_TASKS}}
#### {{TASK_ID}}: {{TASK_TITLE}}

- **Status**: Completed
- **Worker**: {{WORKER_ID}}
- **PR**: #{{PR_NUMBER}}
- **Commit**: {{COMMIT_SHA}}
- **Branch**: {{BRANCH_NAME}}
- **Duration**: {{TASK_DURATION}}

{{/each}}

---

### Tasks Failed

{{#if FAILED_TASKS}}
{{#each FAILED_TASKS}}
#### {{TASK_ID}}: {{TASK_TITLE}}

- **Status**: Failed
- **Worker**: {{WORKER_ID}}
- **Phase**: {{FAILED_PHASE}}
- **Error**: {{ERROR_MESSAGE}}
- **Attempts**: {{RETRY_COUNT}}

{{/each}}
{{else}}
None
{{/if}}

---

### Tasks Skipped

{{#if SKIPPED_TASKS}}
{{#each SKIPPED_TASKS}}
- {{TASK_ID}}: {{TASK_TITLE}} ({{SKIP_REASON}})
{{/each}}
{{else}}
None
{{/if}}

---

### Metrics

| Metric | Value |
|--------|-------|
| Tasks Attempted | {{TASKS_ATTEMPTED}} |
| Tasks Completed | {{TASKS_COMPLETED}} |
| Tasks Failed | {{TASKS_FAILED}} |
| Tasks Skipped | {{TASKS_SKIPPED}} |
| Workers Spawned | {{WORKERS_SPAWNED}} |
| PRs Created | {{PRS_CREATED}} |
| PRs Merged | {{PRS_MERGED}} |
| Commits | {{TOTAL_COMMITS}} |
| Tests Added | {{TESTS_ADDED}} |

---

### Verification

| Check | Status |
|-------|--------|
| Build | {{BUILD_STATUS}} |
| Tests | {{TEST_STATUS}} ({{TESTS_PASSED}}/{{TESTS_TOTAL}}) |
| Coverage | {{COVERAGE_PERCENT}}% |

**Verdict**: {{VERIFICATION_VERDICT}}

{{#if VERIFICATION_FAILURES}}
#### Failures

{{#each VERIFICATION_FAILURES}}
- {{TEST_FILE}}: {{FAILURE_MESSAGE}}
{{/each}}
{{/if}}

---

### Documentation Updates

| Update | Status |
|--------|--------|
{{#each COMPLETED_TASKS}}
| {{TASK_ID}} backlog epic file | {{EPIC_FILE_UPDATED}} |
{{/each}}
| Dependent tasks unblocked | {{DEPENDENTS_UNBLOCKED}} |
| Project status file (context/status.md) | {{PROJECT_STATUS_UPDATED}} |
| Documentation commit | {{DOCS_COMMIT_SHA}} |

{{#if DOCUMENTATION_SKIPPED}}
**WARNING**: Documentation updates were skipped for: {{DOCUMENTATION_SKIPPED_REASON}}
{{/if}}

---

### Backlog Status

| Status | Count |
|--------|-------|
| Completed (this session) | {{COMPLETED_THIS_SESSION}} |
| Ready | {{REMAINING_READY}} |
| In Progress | {{REMAINING_IN_PROGRESS}} |
| Total Backlog | {{TOTAL_BACKLOG}} |

---

### Next Steps

{{#if REMAINING_READY}}
Ready tasks remaining:
{{#each REMAINING_READY_TASKS}}
- {{TASK_ID}}: {{TASK_TITLE}} ({{PRIORITY}} priority)
{{/each}}

Run `/agile-coordinator` to continue.
{{else}}
All ready tasks have been implemented!

Next actions:
- Review completed PRs
- Groom backlog for new tasks
- Run `/agile-workflow --phase daily-evening` to wrap up
{{/if}}

---

Example: Filled Report

## Orchestration Summary

**Session**: coord-2026-01-20-abc123
**Started**: 2026-01-20T10:00:00Z
**Completed**: 2026-01-20T10:45:00Z
**Duration**: 45 minutes

---

### Configuration

| Setting | Value |
|---------|-------|
| Execution Mode | sequential |
| Max Workers | 2 |
| Autonomy Level | autonomous |

---

### Tasks Completed

#### TASK-006: Persistent Message Status Storage

- **Status**: Completed
- **Worker**: worker-1
- **PR**: #123
- **Commit**: 5cc6e36
- **Branch**: task/TASK-006-persistence
- **Duration**: 18 minutes

#### TASK-007: Add Unit and Integration Tests

- **Status**: Completed
- **Worker**: worker-2
- **PR**: #124
- **Commit**: 94750f0
- **Branch**: task/TASK-007-tests
- **Duration**: 22 minutes

---

### Tasks Failed

None

---

### Tasks Skipped

None

---

### Metrics

| Metric | Value |
|--------|-------|
| Tasks Attempted | 2 |
| Tasks Completed | 2 |
| Tasks Failed | 0 |
| Tasks Skipped | 0 |
| Workers Spawned | 2 |
| PRs Created | 2 |
| PRs Merged | 2 |
| Commits | 4 |
| Tests Added | 142 |

---

### Verification

| Check | Status |
|-------|--------|
| Build | PASSED |
| Tests | PASSED (142/142) |
| Coverage | 82% |

**Verdict**: VERIFIED

---

### Documentation Updates

| Update | Status |
|--------|--------|
| TASK-006 backlog epic file | Updated |
| TASK-007 backlog epic file | Updated |
| Dependent tasks unblocked | 0 tasks |
| Project status file (context/status.md) | Updated |
| Documentation commit | a1b2c3d |

---

### Backlog Status

| Status | Count |
|--------|-------|
| Completed (this session) | 2 |
| Ready | 0 |
| In Progress | 0 |
| Total Backlog | 8 |

---

### Next Steps

All ready tasks have been implemented!

Next actions:
- Review completed PRs
- Groom backlog for new tasks
- Run `/agile-workflow --phase daily-evening` to wrap up

Worker Instruction Template

Template for worker agent prompts. Replace {{variables}} with actual values.

---

Full Template

You are Worker {{WORKER_ID}}, assigned to implement {{TASK_ID}}.

## Task Assignment

**Task**: {{TASK_ID}} - {{TASK_TITLE}}
**Priority**: {{PRIORITY}}
**Size**: {{SIZE}}

Read the full task specification at:
`context/backlog/{{TASK_FILE}}`

## Your Mission

Complete the FULL implementation cycle for this task:

1. **Understand**: Read the task file for requirements and implementation plan
2. **Implement**: Follow TDD - write tests first, then implement
3. **Review**: Ensure code quality and test coverage
4. **Validate**: Run tests and verify build passes
5. **Signal**: Update your progress file when ready for merge

## Execution

Run the agile-workflow skill for your assigned task:

This executes the full implementation cycle

/agile-workflow --task {{TASK_ID}}

## Checkpoint Handling

Handle all agile-workflow checkpoints automatically:

| Checkpoint | Action |
|------------|--------|
| TASK_SELECTED | Continue (task is assigned to you) |
| IMPL_COMPLETE | Continue if tests pass; fix and retry if not |
| REVIEWS_DONE | Fix critical/high issues; defer medium/low |
| MERGE_READY | Signal ready, coordinator handles merge |
| MERGED | (Coordinator handles merge) |

## Progress Reporting

After each major phase, update your progress file:

**File**: `.coordinator/workers/{{WORKER_ID}}/progress.json`

{ "worker_id": "{{WORKER_ID}}", "task_id": "{{TASK_ID}}", "status": "in_progress", "phase": "implement", "pr_number": null, "branch": "task/{{TASK_ID}}-...", "last_update": "{{TIMESTAMP}}", "milestones": [], "error": null }

Update `status` to one of:
- `in_progress` - Still working
- `ready-to-merge` - PR created, CI passed, ready for merge
- `failed` - Encountered unrecoverable error

Update `phase` to reflect current phase:
- `started` → `implement` → `review` → `merge-prep` → `ready-to-merge`

## IMPORTANT: Merge Protocol

**DO NOT merge your branch yourself.**

When your implementation is complete and tests pass:
1. Update progress status to `ready-to-merge`
2. Stop and wait
3. The coordinator will handle the merge

This ensures sequential merges and prevents conflicts.

## Error Handling

If you encounter an unrecoverable error:
1. Update progress status to `failed`
2. Set the `error` field with a description
3. Stop execution

The coordinator will decide whether to retry or skip.

## Success Criteria

Your task is complete when:
- All tests pass
- Code reviews pass (no critical/high issues)
- Build succeeds
- Progress file shows `ready-to-merge`

BEGIN IMPLEMENTATION

---

Example: Filled Template

You are Worker worker-1, assigned to implement TASK-006.

## Task Assignment

**Task**: TASK-006 - Persistent Message Status Storage
**Priority**: medium
**Size**: medium

Read the full task specification at:
`context/backlog/TASK-006-persistent-message-status.md`

## Your Mission
...

---

Usage Notes

1. Replace all {{VARIABLE}} placeholders with actual values 2. The worker will execute autonomously once spawned 3. Progress file must be created/updated by the worker 4. Coordinator monitors progress file for status changes