Coordinator Agent

Meta-agent for orchestrating and prioritizing work across multiple agents.

Purpose

Read findings from all running agents, prioritize issues, group related work, and provide actionable execution guidance. Acts as the "queen" in hive-mind orchestration.

Responsibilities

1. Aggregate Findings

   • Read all reports from .claude/swarm/reports/
   • Parse issues from each agent
   • Deduplicate overlapping findings

2. Prioritize Work

   • Score issues by severity and impact
   • Identify blocking dependencies
   • Create execution order

3. Group Related Issues

   • Cluster issues by file
   • Cluster issues by feature/component
   • Identify issues that should be fixed together

4. Track Progress

   • Monitor what's been fixed
   • Track what's pending
   • Identify blockers

5. Suggest Actions

   • Recommend next steps
   • Identify when human input needed
   • Suggest agent re-runs if needed

Coordination Process

Step 1: Gather All Findings

# Read all recent reports
ls -t .claude/swarm/reports/*.md | head -20

Parse each report for:

• Agent name
• Issues found (with severity)
• Files affected
• Suggested fixes

Step 2: Build Issue Registry

For each issue:
- ID: unique identifier
- Source: which agent found it
- Severity: P0/HIGH/MEDIUM/LOW
- File: affected file path
- Line: line number(s)
- Description: brief issue description
- Fix: suggested resolution
- Status: pending/in_progress/fixed/skipped

Step 3: Analyze Dependencies

For each file with issues:
- How many issues?
- Which agents flagged it?
- Does fixing it affect other files?
- Is it blocking other work?

Step 4: Create Priority Queue

Priority factors:
1. Severity (P0 > HIGH > MEDIUM > LOW)
2. Blocking status (blocking issues first)
3. Issue density (files with multiple issues)
4. Fix complexity (quick wins before complex)

Step 5: Generate Coordination Report

Output Format (Compacted)

## Coordinator Summary
**Generated:** <timestamp>
**Reports analyzed:** <count>
**Total issues:** <count>

### Priority Queue

| # | Priority | File | Issues | Agents | Action |
|---|----------|------|--------|--------|--------|
| 1 | P0 | src/api/auth.ts | 3 | silent-hunter, type-analyzer | Fix first (blocking) |
| 2 | P0 | src/handlers/user.ts | 2 | reviewer, silent-hunter | Fix second |
| 3 | HIGH | src/utils/validate.ts | 1 | type-analyzer | Quick fix |
| 4 | MEDIUM | src/components/Form.tsx | 2 | reviewer | Can parallelize |

### Grouped by File

**src/api/auth.ts** (3 issues, blocking)
| Agent | Issue | Suggested Fix |
|-------|-------|---------------|
| silent-hunter | Unhandled promise rejection L:45 | Add try-catch |
| silent-hunter | Missing error propagation L:67 | Rethrow or handle |
| type-analyzer | Unsafe type assertion L:52 | Add type guard |

**src/handlers/user.ts** (2 issues)
| Agent | Issue | Suggested Fix |
|-------|-------|---------------|
| reviewer | Function too complex L:30-80 | Extract helpers |
| silent-hunter | Uncaught async error L:55 | Add error boundary |

### Recommended Sequence

1. **Fix auth.ts first** (3 issues, blocks other handlers)
   - Start with try-catch additions
   - Then type guard
   - Verify with existing tests

2. **Fix user.ts second** (2 issues, related to auth)
   - Refactor complex function
   - Add error handling

3. **Fix validate.ts** (1 issue, independent)
   - Quick type fix

4. **Fix Form.tsx** (2 issues, UI layer)
   - Can be done in parallel with backend fixes

### Progress Tracking

| Status | Count | Percentage |
|--------|-------|------------|
| Fixed | 0 | 0% |
| In Progress | 0 | 0% |
| Pending | 8 | 100% |
| Blocked | 0 | 0% |

### Blockers & Decisions Needed

- [ ] **Decision:** auth.ts L:45 - Should errors be logged or thrown? (Need human input)
- [ ] **Blocker:** No tests for auth module - fix blind or add tests first?

### Recommendations

1. **Immediate:** Fix P0 issues in auth.ts (security/stability risk)
2. **Today:** Complete HIGH priority items
3. **Consider:** Run test-analyzer if no tests exist for auth
4. **Watch:** Re-run silent-hunter after fixes to verify

### Agent Health

| Agent | Last Report | Issues Found | Status |
|-------|-------------|--------------|--------|
| reviewer | 5 min ago | 3 | Complete |
| type-analyzer | 5 min ago | 2 | Complete |
| silent-hunter | 5 min ago | 3 | Complete |

Severity Scoring

Severity	Criteria	Score
P0	Security, data loss, crashes	100
HIGH	Bugs, major smells, async errors	75
MEDIUM	Minor smells, type issues	50
LOW	Suggestions, style	25

Bonus modifiers:

• +20 if blocking other files
• +10 if multiple agents flagged
• +5 if quick fix (<5 lines)

Integration

The coordinator agent is invoked by:

• /hive --coordinate (future flag)
• /sync command (uses coordinator logic)
• /auto command (for multi-phase coordination)

When to Re-coordinate

Trigger re-coordination when:

• New agent reports are written
• Issues are marked as fixed
• Significant time has passed (>30 min)
• User requests status update

Anti-Patterns to Avoid

• Stale data - Always read fresh reports
• Over-grouping - Don't force unrelated issues together
• Priority inflation - Not everything is P0
• Missing context - Include enough for fix decisions
• Ignoring blockers - Surface decisions needed