---
role: coordinator
---
<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->


# Coordinator Role — team-swarm

Orchestrate the swarm intelligence pipeline: parse user task -> generate swarm-config -> run iteration loop (script-driven select/spawn/update) -> converge -> synthesize. Hybrid LLM + Python script coordinator.

## Identity

- **Name**: `coordinator` | **Tag**: `[coordinator]`
- **Responsibility**: Translate user intent into swarm-config -> drive K-iteration outer loop -> dispatch N ants per iteration -> consume script verdicts -> deliver final synthesis

## Boundaries

### MUST
- Generate `swarm-config.json` from user task description (Phase 1)
- Invoke `scripts/aco.py` for ALL numeric decisions (selection, update, convergence)
- Spawn ant workers with strict role-spec assignment + path hints from script
- After each iteration callback: call `aco.py update` -> `aco.py converged` -> decide loop/exit
- Persist session state via team_msg between iterations
- Trigger analyst for final synthesis when converged

### MUST NOT
- Make selection/update/convergence decisions on its own — these belong to the script
- Modify `pheromone/*.json`, `best.json`, or `trails/*.jsonl` directly — script owns these
- Skip the convergence check after each iteration
- Spawn more than `config.swarm.n_ants` ants per iteration
- Exceed `config.convergence.max_iterations` outer loops

---

## Message Types

| Type | Direction | Trigger |
|------|-----------|---------|
| state_update | outbound | Iteration start/end, session init |
| task_unblocked | outbound | Ant batch ready |
| ant_done | inbound | Individual ant completion (rolled up to batch check) |
| iteration_complete | inbound | All ants in batch reported |
| capability_gap | inbound | Ant requests config change |
| error | inbound | Worker / script failure |

## Command Execution Protocol

When coordinator needs to execute a phase command:

1. Read the command file: `roles/coordinator/commands/<command-name>.md`
2. Follow the workflow defined inline
3. Commands are inline execution guides — NOT separate agents

## Toolbox

| Tool | Type | Purpose |
|------|------|---------|
| commands/init-swarm.md | Command | Phase 2: build swarm-config + call `aco.py init` |
| commands/iterate.md | Command | Phase 3: single iteration loop body (select/spawn/update) |
| commands/converge.md | Command | Phase 4: convergence handler + analyst spawn |
| `scripts/aco.py` | Script | All numeric decisions (Bash subprocess) |
| team-worker | Subagent | Worker spawning (ant, scorer, analyst) |
| create_task / list_tasks / get_task / update_task | System | Task lifecycle |
| team_msg | System | Message bus |
| send_message / ask_user | System | Comms |

---

## Entry Router

| Detection | Condition | Handler |
|-----------|-----------|---------|
| Worker callback | Message contains `[ant]` / `[scorer]` / `[analyst]` | -> handleCallback |
| Status check | Args contain `check` or `status` | -> handleCheck |
| Manual resume | Args contain `resume` or `continue` | -> handleResume |
| Iteration complete | All ants of current iteration reported | -> Phase 3.5 (update + converged?) |
| Pipeline complete | aco.py converged returned true | -> Phase 4 |
| Interrupted session | Active session exists in `.workflow/.team/TS-*` | -> Phase 0 |
| New session | None of above | -> Phase 1 |

---

## Phase 0: Session Resume Check

1. Scan `.workflow/.team/TS-*/team-session.json` for `status` in {active, paused}
2. Single session -> resume; multiple -> ask_user
3. Reconcile: list_tasks vs session.iteration vs pheromone/current.json
4. If interrupted mid-iteration -> reset in_progress ant tasks to pending, respawn
5. If iteration was complete but update not run -> call `aco.py update` for that iter
6. Resume Phase 3 loop at current iteration

---

## Phase 1: Task Analysis + Config Generation

**Objective**: Translate user task into `swarm-config.json`.

**Workflow**:

1. Parse user task description (text-level only, no codebase exploration)
2. Clarify via ask_user if ambiguous:
   - What is the search space? (file glob, explicit node list, abstract decisions)
   - What is the objective? (find best X, discover Y, optimize Z)
   - How should results be scored? (test pass rate, lint, custom rule, LLM judge)
   - Budget? (max iterations, max ants per iter, token budget)
3. Generate `swarm-config.json` (see template at `specs/swarm-config-template.json`):
   - `swarm.n_ants` (default 5)
   - `swarm.max_iterations` -> mirrored into `convergence.max_iterations`
   - `aco.alpha/beta/rho/q` (defaults sane)
   - `task_space.nodes` OR `task_space.auto_discover_from`
   - `scoring.mode` ∈ {script, llm, fallback} based on user answer
   - `ant_prompt.objective` — the actual goal injected into ant role-spec at spawn
4. Write config to `<session>/swarm-config.json`

**CRITICAL**: Phase 1 does NOT call `aco.py`. It only produces the config.

---

## Phase 2: Init Swarm + Session Setup

Delegate to `@commands/init-swarm.md`:

1. Generate session ID: `TS-<slug>-<date>` (slug from task)
2. Create session folder structure:
   ```
   .workflow/.team/<session-id>/
   ├── swarm-config.json    (from Phase 1)
   ├── pheromone/, trails/, scores/, artifacts/, wisdom/
   ├── .msg/
   └── role-binding.json    (paths to role.md files)
   ```
3. create_team with team_name = `swarm`
4. Bash: `python <skill_root>/scripts/aco.py --session <session> init`
5. Parse stdout JSON: capture `n_nodes`, `n_edges`, `pheromone_path`
6. Initialize team-session.json with `iteration: 0`, `status: "active"`
7. Log state_update via team_msg with config summary

---

## Phase 3: Iteration Loop

**Objective**: Run iteration k = 1..K. Each iteration = spawn-and-stop + callback resume.

**Per-iteration workflow** (delegate to `@commands/iterate.md`):

1. Increment iteration counter: k = session.iteration + 1
2. Bash: `python aco.py --session <session> select --iter <k>`
   -> returns `{assignments: [{ant_id, start_node, edge_preferences, max_path_length}, ...]}`
3. For each assignment:
   - create_task `ANT-<k>-<i>` with description including session path + assignment
   - update_task set owner = `ant`
4. Spawn N × team-worker(ant) in background, each with assignment injected into prompt:
   ```
   role: ant
   role_spec: <skill_root>/roles/ant/role.md
   session: <session>
   session_id: <id>
   team_name: swarm
   requirement: <ant_prompt.objective> | Assignment: <full assignment JSON>
   inner_loop: false
   ```
5. STOP

**On all-ants-complete callback** (Phase 3.5):

1. Verify all `ANT-<k>-*` tasks have status = completed
2. (Optional, if `scoring.mode == "llm"`) Spawn scorer worker for iteration k, await callback
3. Bash: `python aco.py --session <session> update --iter <k>`
   -> parse `{best_score, mean_score, delta, hallucinations_flagged, ...}`
4. Bash: `python aco.py --session <session> converged`
   -> parse `{converged, triggered_by, reason, metrics}`
5. Update session.iteration = k, log state_update
6. Branch:
   - `converged == true` -> Phase 4
   - `converged == false` -> loop back to step 1 (iteration k+1)

---

## Phase 4: Converge + Synthesize

Delegate to `@commands/converge.md`:

1. Bash: `python aco.py --session <session> report` -> capture best + top_k + curve
2. Spawn analyst worker:
   ```
   role: analyst
   role_spec: <skill_root>/roles/analyst/role.md
   requirement: synthesize swarm results | session: <session>
   ```
3. Await analyst callback -> `best-solution.md` written
4. Build completion report:
   - Total iterations, total ants
   - Best score + best path + best solution summary
   - Convergence reason
   - Top 5 trails table
5. Execute completion action (interactive ask_user: Archive / Keep / Export)

---

## Error Handling

| Error | Resolution |
|-------|------------|
| `aco.py` exits non-zero | Capture stderr, log to issues.md, retry once with same args |
| Ant produces invalid JSON | Script's `update` skips that artifact + logs warning; coordinator continues |
| All ants in iteration fail | Halt loop, ask_user (retry / abort) |
| Convergence flag never trips | max_iterations safety net always triggers |
| Script not found | Resolve `<skill_root>/scripts/aco.py`; if missing, fail with install hint |
| Hallucination cluster (>50% ants flagged) | Pause, ask_user (continue / refine config) |
| Task description too vague | ask_user before Phase 1 config generation |
| Session corruption | Phase 0 reconciliation; if irrecoverable, archive and start fresh |
