swarm

What this skill does

# Swarm Pipeline

Ant-colony themed 6-phase development pipeline with Agent Teams delegate mode, dual-channel communication (file artifacts + SendMessage live coordination), dual-track parallel execution, adversarial review teams, and self-organizing task dispatch. The **command** (lead) creates a team with dependency-chain task graphs, spawns 3 teammates, then enters a **monitoring loop** that reads signal flags from state.json and performs dynamic TaskCreate calls. The **TeammateIdle hook** is the full task router for all phases. The **TaskCompleted hook** validates output, advances state, and evaluates the A4 verdict inline. Uses **ants plugin agents** (self-contained) driven by **ants plugin hooks**. No Codex MCP dependency.

## Key Architecture

- `pipeline: "swarm"` in state.json
- `plugin: "ants"` -- so ants hooks fire
- Other plugins' hooks silently exit (they check `plugin` field in state.json)
- All agents are `ants:*` prefixed -- they exist in the ants plugin
- **Agent Teams delegate mode** with Command-as-Active-Lead monitoring loop
- **Dual-channel communication**: files for persistent artifacts (hooks validate these), SendMessage for live coordination overlay
- Command creates team first (TeamCreate), then populates task graph (TaskCreate with blockedBy dependency chains)
- TeammateIdle hook routes idle teammates to next ready phase/task (hook-driven routing, not self-assignment from TaskList)
- TaskCompleted hook validates output, advances state, and sets signal flags
- Command monitoring loop reads signal flags and creates dynamic tasks (A3 workers, A5, loop-back). The command MUST NOT stop or exit during the monitoring loop -- a `<COMPLETION-GATE>` enforces polling until a terminal condition is met
- A4 verdict is evaluated **inline** by `handle_a3_arbiter()` in the TaskCompleted hook -- no separate agent dispatch
- State schema v6 with `phases`, `circuitBreaker`, `taskPool`, `teamName`, `teamCreated`, `teammateCount`, `taskGraphVersion`, signal flags (`needsA3Tasks`, `needsA5Tasks`, `needsLoopReset`, `needsPswarmReset`), `messages`, `planApproved`, `shutdown`, `webhookUrl`, `lintConfig`, `configSnapshot`, `compactMetadata`, `worktreePath`, and `webSearch` fields

## Dual-Channel Communication Model

The swarm pipeline uses two complementary communication channels. Both channels serve distinct purposes and work together -- neither replaces the other.

### File Channel (Persistent Artifacts)

Files are the **source of truth** for all phase outputs. Hooks validate that expected files exist and contain valid data before advancing state. Every phase gate checks files, not messages. File artifacts persist across compaction, loop-backs, and pswarm run boundaries.

### SendMessage Channel (Live Coordination Overlay)

SendMessage provides **real-time peer coordination** between teammates within a single Agent Teams session. It enables agents to share status updates, partial results, warnings, and coordination signals without writing intermediate files. SendMessage is ephemeral -- messages exist only within the current session context and are not persisted to disk or validated by hooks.

### Golden Rule

**Write the file FIRST, then SendMessage.** An agent must always write its output artifact to disk before sending any coordination message about it. This ensures that:
1. Hooks can validate the artifact immediately when TaskCompleted fires
2. If SendMessage delivery is delayed or lost, the file still exists for downstream consumers
3. The file channel remains the authoritative source of truth

### Channel Comparison

| Aspect | File Channel | SendMessage Channel |
|--------|-------------|---------------------|
| **Purpose** | Persistent phase artifacts, hook validation gates | Live coordination, status updates, partial result sharing |
| **Persistence** | Disk -- survives compaction, loop-backs, restarts | Ephemeral -- session context only |
| **Validation** | Hooks validate existence, format, content | No hook validation -- advisory only |
| **Latency** | Write + read from disk | Immediate in-session delivery |
| **Required for phase gates** | Yes -- hooks check files to advance state | No -- phase transitions never depend on messages |
| **Used by** | All 24 agents (every agent writes output files) | 16 agents (coordination overlay, see table below) |
| **Examples** | `A0-explore.md`, `A1-plan.md`, `A3-quality.json` | "Build track complete, starting quality review", "Worker 3 found API conflict in auth module" |

## Who Messages Whom (SendMessage)

Sixteen agents use SendMessage as a live coordination overlay alongside their file output. Messages are informational -- they accelerate coordination but are never required for phase gates.

| Phase | Sender | Recipient(s) | Message Content |
|-------|--------|-------------- |-----------------|
| A0 | explore-aggregator | team | Synthesis complete, summary of key findings |
| A1 | architect | team | Plan ready, task count, complexity estimate |
| A2 | blueprint-reviewer | team | Review verdict (approved/needs_revision), issue summary |
| A3 | worker (each) | team | Task completion notice, files changed, self-verification status |
| A3 | sentinel-correctness | review-arbiter | Review complete, critical/warning/info issue counts |
| A3 | sentinel-security | review-arbiter | Review complete, critical/warning/info issue counts |
| A3 | sentinel-perf | review-arbiter | Review complete, critical/warning/info issue counts |
| A3 | sentinel-style | review-arbiter | Review complete, critical/warning/info issue counts |
| A3 | guardian | team | Tests written, pass/fail counts |
| A3 | simplifier | team | Cleanup complete, changes applied summary |
| A3 | review-arbiter | team | Consolidated quality verdict, critical issue count |
| A3 | review-fixer | team | Fixes applied, files modified |
| A5 | nurse | drone | Documentation updated, files modified list |
| A5 | drone | team | Commit SHA, PR URL, ship status |
| A1 (sswarm) | plan-arbiter | team | Selected plan, merge strategy used |
| A2 (sswarm) | review-lead | team | Consolidated review verdict |

### Message Format Contract

Agents send plain-text summary messages via SendMessage. Messages are brief, human-readable coordination signals -- not structured JSON payloads. Each agent's Communication Protocol section defines its specific message format. Examples:

- Worker: `"Task T3 complete. Files modified: src/auth.ts. Self-verification: tests pass."`
- Sentinel: `"Sentinel correctness review complete. Found 0 critical, 2 warning, 5 info issues. Review at .agents/tmp/phases/loop-1/A3-review.sentinel-correctness.json"`
- Drone: `"Shipped. Commit: abc123. PR: https://... Files: 3 committed."`
- Architect: `"A1 plan complete. 5 tasks planned. Plan at .agents/tmp/phases/loop-1/A1-plan.md"`

### Agents WITHOUT SendMessage

Eight agents do not use SendMessage. Their communication is entirely file-based, with task dependency chains (blockedBy) ensuring consumers only run after producers complete:

| Agent | Rationale |
|-------|-----------|
| forager | Lightweight haiku scout -- writes temp file only, aggregator reads via blockedBy |
| cartographer | Writes temp file only, aggregator reads via blockedBy |
| queen | Legacy/edge-case agent -- not dispatched in standard pipeline flow |
| sentinel (deprecated) | Replaced by specialist sentinels; retained for v0.1 backward compatibility only |
| bug-scout | Debug pipeline only (D0) -- stateless, no Agent Teams context |
| solution-proposer | Debug pipeline only (D1) -- stateless, no Agent Teams context |
| solution-aggregator | Debug pipeline only (D2) -- stateless, no Agent Teams context |
| fix-worker | Debug pipeline only (D3) -- stateless, no Agent Teams context |

Note: forager and cartographer are excluded because they are high-volume, low-latency haiku/sonnet scouts whose only job is to write a temp file. The explore-aggregator reads their files via blockedBy dependency -- no live coordination adds value h