Swarm Coordination

Swarm Coordination

Multi-agent orchestration for parallel task execution. The coordinator breaks work into subtasks, spawns worker agents, monitors progress, and aggregates results.

MANDATORY: Swarm Mail

ALL coordination MUST use swarmmail_* tools. This is non-negotiable.

Swarm Mail is embedded (no external server needed) and provides:

• File reservations to prevent conflicts
• Message passing between agents
• Thread-based coordination tied to cells

When to Swarm

DO swarm when:

• Task touches 3+ files
• Natural parallel boundaries exist (frontend/backend/tests)
• Different specializations needed
• Time-to-completion matters

DON'T swarm when:

• Task is 1-2 files
• Heavy sequential dependencies
• Coordination overhead > benefit
• Tight feedback loop needed

Heuristic: If you can describe the task in one sentence without "and", don't swarm.

Worker Survival Checklist (MANDATORY)

Every swarm worker MUST follow these 9 steps. No exceptions.

// 1. INITIALIZE - Register with Swarm Mail
swarmmail_init({
  project_path: "/abs/path/to/project",
  task_description: "bead-id: Task description"
});

// 2. QUERY LEARNINGS - Check what past agents learned
hivemind_find({
  query: "task keywords domain",
  limit: 5
});

// 3. LOAD SKILLS - Get domain expertise
skills_list();
skills_use({ name: "relevant-skill" });

// 4. RESERVE FILES - Claim exclusive ownership
swarmmail_reserve({
  paths: ["src/assigned/**"],
  reason: "bead-id: What I'm working on",
  ttl_seconds: 3600
});

// 5. DO WORK
// ... implement changes ...

// 6. REPORT PROGRESS - Every 30min or at milestones
swarm_progress({
  project_key: "/abs/path/to/project",
  agent_name: "WorkerName",
  bead_id: "bd-123.4",
  status: "in_progress",
  message: "Auth service 80% complete, testing remaining",
  progress_percent: 80
});

// 7. CHECKPOINT - Before risky operations
swarm_checkpoint({
  bead_id: "bd-123.4",
  checkpoint_name: "pre-refactor",
  reason: "About to refactor auth flow"
});

// 8. STORE LEARNINGS - Capture what you discovered
hivemind_store({
  information: "OAuth refresh tokens need 5min buffer...",
  metadata: "auth, oauth, tokens"
});

// 9. COMPLETE - Auto-releases, records outcome
swarm_complete({
  project_key: "/abs/path/to/project",
  agent_name: "WorkerName",
  bead_id: "bd-123.4",
  summary: "Auth service implemented with JWT",
  files_touched: ["src/auth/service.ts", "src/auth/schema.ts"]
});

Why These Steps Matter:

If your subtask prompt doesn't include these steps, something is wrong with the coordinator.

Task Clarity Check (BEFORE Decomposing)

Before decomposing, ask: Is this task clear enough to parallelize?

Vague Task Signals (ASK QUESTIONS FIRST)

How to Clarify

The task "<task>" needs clarification before I can decompose it.

**Question:** [Specific question about scope/files/approach]

Options:
a) [Option A] - [trade-off]
b) [Option B] - [trade-off]
c) [Option C] - [trade-off]

I'd recommend (a) because [reason]. Which approach?

Rules:

• ONE question at a time (don't overwhelm)
• Offer 2-3 concrete options when possible
• Lead with your recommendation and why
• Wait for answer before asking next question

Clear Task Signals (PROCEED to decompose)

When in doubt, ask. A 30-second clarification beats a 30-minute wrong decomposition.

Coordinator Workflow

Phase 0: Socratic Planning (NEW - INTERACTIVE)

Before decomposing, engage with the user to clarify the task.

Swarm supports three interaction modes:

Default Flow (Full Socratic):

// 1. Analyze task for clarity
const signals = analyzeTaskClarity(task);

if (signals.needsClarification) {
  // 2. Ask ONE question at a time
  const question = generateClarifyingQuestion(signals);
  
  // 3. Offer 2-3 concrete options
  const options = generateOptions(signals);
  
  // 4. Lead with recommendation
  const recommendation = selectRecommendation(options);
  
  // 5. Present to user
  console.log(`
The task "${task}" needs clarification before I can decompose it.

**Question:** ${question}

Options:
a) ${options[0].description} - ${options[0].tradeoff}
b) ${options[1].description} - ${options[1].tradeoff}
c) ${options[2].description} - ${options[2].tradeoff}

I'd recommend (${recommendation.letter}) because ${recommendation.reason}. Which approach?
  `);
  
  // 6. Wait for answer, iterate if needed
  const answer = await getUserResponse();
  
  // 7. Ask next question if needed (ONE at a time)
  if (needsMoreClarification(answer)) {
    // Repeat with next question
  }
}

// 8. Proceed to decomposition once clear

Fast Mode (--fast):

• Skip all questions
• Use reasonable defaults based on task type
• Proceed directly to decomposition

Auto Mode (--auto):

• Zero interaction
• Heuristic-based decisions for all choices
• Use for batch processing or CI

Confirm Only (--confirm-only):

• Generate plan silently
• Show final CellTree
• Get yes/no only

Rules for Socratic Mode:

• ONE question at a time - don't overwhelm
• Offer concrete options - not open-ended
• Lead with recommendation - save user cognitive load
• Wait for answer - don't proceed with assumptions

Phase 1: Initialize Swarm Mail (FIRST)

// ALWAYS initialize first - registers you as coordinator
await swarmmail_init({
  project_path: "$PWD",
  task_description: "Swarm: <task summary>",
});

Phase 2: Knowledge Gathering (MANDATORY)

Before decomposing, query ALL knowledge sources:

// 1. Past learnings from this project
hivemind_find({ query: "<task keywords>", limit: 5 });

// 2. How similar tasks were solved before
hivemind_find({ query: "<task description>", limit: 5, collection: "sessions" });

// 3. Design patterns and prior art
pdf_brain_search({ query: "<domain concepts>", limit: 5 });

// 4. Available skills to inject into workers
skills_list();

Synthesize findings into shared_context for workers.

Phase 3: Decomposition (DELEGATE TO SUBAGENT)

⚠️ CRITICAL: Context Preservation Pattern

NEVER do planning inline in the coordinator thread. Decomposition work (file reading, Hivemind session searching, reasoning about task breakdown) consumes massive amounts of context and will exhaust your token budget on long swarms.

ALWAYS delegate planning to a swarm-planner subagent and receive only the structured CellTree JSON result back.

❌ Anti-Pattern (Context-Heavy):

// DON'T DO THIS - pollutes main thread context
const plan = await swarm_plan_prompt({ task, ... });
// ... agent reasons about decomposition inline ...
// ... context fills with file contents, analysis ...
const validation = await swarm_validate_decomposition({ ... });

✅ Correct Pattern (Context-Lean):

// 1. Create planning bead with full context
await hive_create({
  title: `Plan: ${taskTitle}`,
  type: "task",
  description: `Decompose into subtasks. Context: ${synthesizedContext}`,
});

// 2. Delegate to swarm-planner subagent
const planningResult = await Task({
  subagent_type: "swarm-planner",
  description: `Decompose task: ${taskTitle}`,
  prompt: `
You are a swarm planner. Generate a CellTree for this task.

## Task
${taskDescription}

## Synthesized Context
${synthesizedContext}

## Instructions
1. Use swarm_plan_prompt(task="...", max_subtasks=5)
2. Reason about decomposition strategy
3. Generate CellTree JSON
4. Validate with swarm_validate_decomposition
5. Return ONLY the validated CellTree JSON (no analysis, no file contents)

Output format: Valid CellTree JSON only.
  `,
});

// 3. Parse result (subagent already validated)
const beadTree = JSON.parse(planningResult);

// 4. Create epic + subtasks atomically
await hive_create_epic({
  epic_title: beadTree.epic.title,
  epic_description: beadTree.epic.description,
  subtasks: beadTree.subtasks,
});

Why This Matters:

• Main thread context stays clean - only receives final JSON, not reasoning
• Subagent context is disposable - gets garbage collected after planning
• Scales to long swarms - coordinator can manage 10+ workers without exhaustion
• Faster coordination - less context = faster responses when monitoring workers

Phase 4: File Ownership (CRITICAL RULE)

⚠️ COORDINATORS NEVER RESERVE FILES

This is a hard rule. Here's why:

// ❌ WRONG - Coordinator reserving files
swarmmail_reserve({
  paths: ["src/auth/**"],
  reason: "bd-123: Auth service implementation"
});
// Then spawns worker... who owns the files?

// ✅ CORRECT - Worker reserves their own files
// Coordinator includes file list in worker prompt
const prompt = swarm_spawn_subtask({
  bead_id: "bd-123.4",
  files: ["src/auth/**"],  // Files listed here
  // ...
});

// Worker receives prompt with file list
// Worker calls swarmmail_reserve themselves

Why This Pattern:

Coordinator Responsibilities:

1. Plan which files each worker needs (no overlap)
2. Include file list in worker prompt
3. Mediate conflicts if workers request different files
4. Never call swarmmail_reserve themselves

Worker Responsibilities:

1. Read assigned files from prompt
2. Reserve those files (step 4 of survival checklist)
3. Work exclusively on reserved files
4. Release via swarm_complete (automatic)

Phase 5: Spawn Workers

for (const subtask of subtasks) {
  const prompt = await swarm_spawn_subtask({
    bead_id: subtask.id,
    epic_id: epic.id,
    subtask_title: subtask.title,
    subtask_description: subtask.description,
    files: subtask.files,
    shared_context: synthesizedContext,
  });

  // Spawn via Task tool
  Task({
    subagent_type: "swarm-worker",
    prompt: prompt.worker_prompt,
  });
}

Phase 6: MANDATORY Review Loop (NON-NEGOTIABLE)

⚠️ AFTER EVERY Worker Returns, You MUST Complete This Checklist:

This is the quality gate that prevents shipping broken code. DO NOT skip this.

// ============================================================
// Step 1: Check Swarm Mail (Worker may have sent messages)
// ============================================================
const inbox = await swarmmail_inbox({ limit: 5 });
const message = await swarmmail_read_message({ message_id: N });

// ============================================================
// Step 2: Review the Work (Generate review prompt with diff)
// ============================================================
const reviewPrompt = await swarm_review({
  project_key: "/abs/path/to/project",
  epic_id: "epic-id",
  task_id: "subtask-id",
  files_touched: ["src/auth/service.ts", "src/auth/service.test.ts"]
});

// This generates a review prompt that includes:
// - Epic context (what we're trying to achieve)
// - Subtask requirements
// - Git diff of changes
// - Dependency status (what came before, what comes next)

// ============================================================
// Step 3: Evaluate Against Criteria
// ============================================================
// Ask yourself:
// - Does the work fulfill the subtask requirements?
// - Does it serve the overall epic goal?
// - Does it enable downstream tasks?
// - Type safety, no obvious bugs?

// ============================================================
// Step 4: Send Feedback (Approve or Request Changes)
// ============================================================
await swarm_review_feedback({
  project_key: "/abs/path/to/project",
  task_id: "subtask-id",
  worker_id: "WorkerName",
  status: "approved",  // or "needs_changes"
  summary: "LGTM - auth service looks solid",
  issues: "[]"  // or "[{file, line, issue, suggestion}]"
});

// ============================================================
// Step 5: ONLY THEN Continue
// ============================================================
// If approved:
//   - Close the cell
//   - Spawn next worker (if dependencies allow)
//   - Update swarm status
//
// If needs_changes:
//   - Worker gets feedback
//   - Worker retries (max 3 attempts)
//   - Review again when worker re-submits
//
// If 3 failures:
//   - Mark task blocked
//   - Escalate to human (architectural problem, not "try harder")

❌ Anti-Pattern (Skipping Review):

// Worker completes
swarm_complete({ ... });

// Coordinator immediately spawns next worker
// ⚠️ WRONG - No quality gate!
Task({ subagent_type: "swarm-worker", prompt: nextWorkerPrompt });

✅ Correct Pattern (Review Before Proceeding):

// Worker completes
swarm_complete({ ... });

// Coordinator REVIEWS first
swarm_review({ ... });
// ... evaluates changes ...
swarm_review_feedback({ status: "approved" });

// ONLY THEN spawn next worker
Task({ subagent_type: "swarm-worker", prompt: nextWorkerPrompt });

Review Workflow (3-Strike Rule):

1. Worker calls swarm_complete → Coordinator notified
2. Coordinator runs swarm_review → Gets diff + epic context
3. Coordinator evaluates against epic goals
4. If good: swarm_review_feedback(status="approved") → Task closed
5. If issues: swarm_review_feedback(status="needs_changes", issues=[...]) → Worker fixes
6. After 3 rejections → Task marked blocked (architectural problem, not "try harder")

Review Criteria:

• Does work fulfill subtask requirements?
• Does it serve the overall epic goal?
• Does it enable downstream tasks?
• Type safety, no obvious bugs?

Monitoring & Intervention:

// Check overall swarm status
const status = await swarm_status({ epic_id, project_key });

Phase 7: Aggregate & Complete

• Verify all subtasks completed
• Run final verification (typecheck, tests)
• Close epic with summary
• Release any remaining reservations
• Record outcomes for learning

await swarm_complete({
  project_key: "$PWD",
  agent_name: "coordinator",
  bead_id: epic_id,
  summary: "All subtasks complete",
  files_touched: [...],
});
await swarmmail_release(); // Release any remaining reservations
await hive_sync();

Context Survival Patterns (CRITICAL)

Long-running swarms exhaust context windows. These patterns keep you alive.

Pattern 1: Query Memory Before Starting

Problem: Repeating solved problems wastes tokens on rediscovery.

Solution: Query the hivemind FIRST.

// At swarm start (coordinator)
const learnings = await hivemind_find({
  query: "auth oauth tokens",
  limit: 5
});

// Include in shared_context for workers
const shared_context = `
## Past Learnings
${learnings.map(l => `- ${l.information}`).join('\n')}
`;

// At worker start (survival checklist step 2)
const relevantLearnings = await hivemind_find({
  query: "task-specific keywords",
  limit: 3
});

Why: 5 learnings (2k tokens) prevent rediscovering solutions (20k tokens of trial-and-error).

Pattern 2: Checkpoint Before Risky Operations

Problem: Failed experiments consume context without producing value.

Solution: Checkpoint before risky changes.

// Before refactoring
await swarm_checkpoint({
  bead_id: "bd-123.4",
  checkpoint_name: "pre-refactor",
  reason: "About to change auth flow structure"
});

// Try risky change...

// If it fails, restore and try different approach
await swarm_restore_checkpoint({
  bead_id: "bd-123.4",
  checkpoint_name: "pre-refactor"
});

When to Checkpoint:

Pattern 3: Store Learnings Immediately

Problem: Discoveries get lost in context churn.

Solution: Store learnings as soon as you discover them.

// ❌ WRONG - Wait until end
// ... debug for 30 minutes ...
// ... find root cause ...
// ... keep working ...
// ... forget to store learning ...

// ✅ CORRECT - Store immediately when discovered
// ... debug for 30 minutes ...
// ... find root cause ...
await hivemind_store({
  information: "OAuth refresh tokens need 5min buffer to avoid race conditions. Without buffer, token refresh can fail mid-request if expiry happens between check and use.",
  metadata: "auth, oauth, tokens, race-conditions"
});
// ... continue working with peace of mind ...

Trigger: Store a learning whenever you say "Aha!" or "That's why!".

Pattern 4: Progress Reports Trigger Auto-Checkpoints

Problem: Workers forget to checkpoint manually.

Solution: swarm_progress auto-checkpoints at milestones.

// Report progress at 25%, 50%, 75%
await swarm_progress({
  project_key: "/abs/path",
  agent_name: "WorkerName",
  bead_id: "bd-123.4",
  status: "in_progress",
  progress_percent: 50,  // Auto-checkpoint triggered
  message: "Auth service half complete"
});

Auto-checkpoint thresholds: 25%, 50%, 75%, 100% (completion).

Pattern 5: Delegate Heavy Research to Subagents

Problem: Reading 10+ files or doing deep Hivemind searches pollutes main thread.

Solution: Subagent researches, returns summary only.

// ❌ WRONG - Coordinator reads files inline
const file1 = await read("src/a.ts");  // 500 lines
const file2 = await read("src/b.ts");  // 600 lines
const file3 = await read("src/c.ts");  // 400 lines
// ... context now +1500 lines ...

// ✅ CORRECT - Subagent reads, summarizes
const summary = await Task({
  subagent_type: "explore",
  prompt: "Read src/a.ts, src/b.ts, src/c.ts. Summarize the auth flow in 3 bullet points."
});
// ... context +3 bullets, subagent context disposed ...

When to Delegate:

• Reading >3 files
• Multiple Hivemind searches
• Deep file tree exploration
• Analyzing large logs

Pattern 6: Use Summaries Over Raw Data

Problem: Full inboxes, file contents, search results exhaust tokens.

Solution: Summaries and previews only.

// ❌ WRONG - Fetch all message bodies
const inbox = await swarmmail_inbox({ include_bodies: true });

// ✅ CORRECT - Headers only, read specific messages
const inbox = await swarmmail_inbox({ limit: 5 });  // Headers only
if (inbox.urgent.length > 0) {
  const msg = await swarmmail_read_message({ message_id: inbox.urgent[0].id });
}

// ✅ BETTER - Summarize threads
const summary = await swarmmail_summarize_thread({ thread_id: "bd-123" });

Token Budget:

Context Survival Checklist

• Query the hivemind at start
• Checkpoint before risky operations
• Store learnings immediately when discovered
• Use swarm_progress for auto-checkpoints
• Delegate heavy research to subagents
• Use summaries over raw data
• Monitor token usage (stay under 150k)

If you're past 150k tokens, you've already lost. These patterns keep you alive.

Decomposition Strategies

Four strategies, auto-selected by task keywords:

See references/strategies.md for full details.

Communication Protocol

Workers communicate via Swarm Mail with epic ID as thread:

// Progress update
swarmmail_send({
  to: ["coordinator"],
  subject: "Auth API complete",
  body: "Endpoints ready at /api/auth/*",
  thread_id: epic_id,
});

// Blocker
swarmmail_send({
  to: ["coordinator"],
  subject: "BLOCKED: Need DB schema",
  body: "Can't proceed without users table",
  thread_id: epic_id,
  importance: "urgent",
});

Coordinator checks inbox regularly - don't let workers spin.

Intervention Patterns

Failure Recovery

Incompatible Outputs

Two workers produce conflicting results.

Fix: Pick one approach, re-run other with constraint.

Worker Drift

Worker implements something different than asked.

Fix: Revert, re-run with explicit instructions.

Cascade Failure

One blocker affects multiple subtasks.

Fix: Unblock manually, reassign dependent work, accept partial completion.

Anti-Patterns

Shared Context Template

## Project Context

- Repository: {repo}
- Stack: {tech stack}
- Patterns: {from pdf-brain}

## Task Context

- Epic: {title}
- Goal: {success criteria}
- Constraints: {scope, time}

## Prior Art

- Similar tasks: {from hivemind sessions}
- Learnings: {from hivemind}

## Coordination

- Active subtasks: {list}
- Reserved files: {list}
- Thread: {epic_id}

Swarm Mail Quick Reference

Swarm Review Quick Reference

Full Swarm Flow

// 1. Initialize Swarm Mail FIRST
swarmmail_init({ project_path: "$PWD", task_description: "..." });

// 2. Gather knowledge
hivemind_find({ query });
hivemind_find({ query, collection: "sessions" });
pdf_brain_search({ query });
skills_list();

// 3. Decompose
swarm_plan_prompt({ task });
swarm_validate_decomposition();
hive_create_epic();

// 4. Reserve files
swarmmail_reserve({ paths, reason, ttl_seconds });

// 5. Spawn workers (loop)
swarm_spawn_subtask();

// 6. Monitor
swarm_status();
swarmmail_inbox();
swarmmail_read_message({ message_id });

// 7. Complete
swarm_complete();
swarmmail_release();
hive_sync();

See references/coordinator-patterns.md for detailed patterns.

ASCII Art, Whimsy & Diagrams (MANDATORY)

We fucking LOVE visual flair. Every swarm session should include:

Session Summaries

When completing a swarm, output a beautiful summary with:

• ASCII art banner (figlet-style or custom)
• Box-drawing characters for structure
• Architecture diagrams showing what was built
• Stats (files modified, subtasks completed, etc.)
• A memorable quote or cow saying "ship it"

During Coordination

• Use tables for status updates
• Draw dependency trees with box characters
• Show progress with visual indicators

Examples

Session Complete Banner:

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃         🐝 SWARM COMPLETE 🐝                 ┃
┃                                              ┃
┃   Epic: Add Authentication                   ┃
┃   Subtasks: 4/4 ✓                            ┃
┃   Files: 12 modified                         ┃
┃                                              ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

Architecture Diagram:

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   INPUT     │────▶│  PROCESS    │────▶│   OUTPUT    │
└─────────────┘     └─────────────┘     └─────────────┘

Dependency Tree:

epic-123
├── epic-123.1 ✓ Auth service
├── epic-123.2 ✓ Database schema
├── epic-123.3 ◐ API routes (in progress)
└── epic-123.4 ○ Tests (pending)

Ship It:

    \   ^__^
     \  (oo)\_______
        (__)\       )\/\
            ||----w |
            ||     ||

    moo. ship it.

This is not optional. PRs get shared on Twitter. Session summaries get screenshot. Make them memorable. Make them beautiful. Make them fun.

Box-drawing characters: ─ │ ┌ ┐ └ ┘ ├ ┤ ┬ ┴ ┼ ━ ┃ ┏ ┓ ┗ ┛ Progress indicators: ✓ ✗ ◐ ○ ● ▶ ▷ ★ ☆ 🐝