opencodekit 0.18.1 → 0.18.3

package/dist/template/.opencode/skill/swarm-coordination/SKILL.md

@@ -7,11 +7,22 @@ description: >
   and graceful shutdown patterns.
 version: "2.1.0"
 license: MIT
+tags: [agent-coordination, workflow]
+dependencies: [beads-bridge]
 ---
 
 # Swarm Coordination - Kimi K2.5 PARL Multi-Agent Execution
 
-Coordinate multiple agents working on independent tasks in parallel using Kimi K2.5 PARL (Parallel-Agent Reinforcement Learning) patterns.
+## When to Use
+
+- Implementing plans with 3+ independent tasks that can run in parallel
+- You need structured coordination, monitoring, and delegation across many agents
+
+## When NOT to Use
+
+- Single-task or tightly sequential work without parallelizable groups
+- Simple 1–2 file changes better handled by a single agent
+
 
 ## Overview
 
@@ -58,694 +69,6 @@ Coordinate multiple agents working on independent tasks in parallel using Kimi K
 - **Progress Visualization**: Real-time TUI with beautiful markdown blocks
 - **Dependency Graphs**: DAG-based task scheduling with critical path analysis
 
-## Architecture
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                         BUILD AGENT (Leader)                     │
-│  - Parses plan into tasks                                        │
-│  - Creates delegation packets                                    │
-│  - Spawns worker agents via Task tool                            │
-│  - Monitors progress via swarm tool                             │
-│  - Synthesizes final results                                     │
-└─────────────────────────────────────────────────────────────────┘
-          │                    │                    │
-          ▼                    ▼                    ▼
-┌─────────────┐      ┌─────────────┐      ┌─────────────┐
-│  WORKER-1   │      │  WORKER-2   │      │  WORKER-3   │
-│  (general)  │      │  (general)  │      │  (general)  │
-│             │      │             │      │             │
-│ - Read      │      │ - Read      │      │ - Read      │
-│   delegation│      │   delegation│      │   delegation│
-│ - Execute   │      │ - Execute   │      │ - Execute   │
-│ - Report    │      │ - Report    │      │ - Report    │
-└─────────────┘      └─────────────┘      └─────────────┘
-          │                    │                    │
-          └────────────────────┼────────────────────┘
-                               ▼
-                     ┌─────────────────┐
-                     │   RECONCILER    │
-                     │                 │
-                     │ - Watch CI      │
-                     │ - Detect broken │
-                     │ - Spawn fixes   │
-                     └─────────────────┘
-                               │
-                               ▼
-                     ┌─────────────────┐
-                     │  PROGRESS +     │
-                     │  TODO PERSIST   │
-                     └─────────────────┘
-```
-
-## Reconciler Agent Pattern (Self-Healing)
-
-The reconciler is the key to scaling beyond 50+ agents. Without reconciliation, broken builds cascade and the swarm collapses. The reconciler provides **continuous self-healing** by watching for failures and spawning targeted fix tasks.
-
-### When to Use Reconciler
-
-- **50+ agents** running in parallel → **REQUIRED**
-- **10-50 agents** → Recommended
-- **<10 agents** → Optional (leader can handle)
-
-### Reconciler Responsibilities
-
-1. **Watch CI/Build Status**: Monitor build gates continuously
-2. **Detect Failures**: Identify which worker caused the failure
-3. **Analyze Root Cause**: Determine if it's a merge conflict, test failure, or type error
-4. **Spawn Fix Tasks**: Create targeted fix tasks with context about what failed
-5. **Verify Fix**: Wait for fix to pass gates before continuing
-
-### Reconciler vs Leader
-
-| Aspect         | Leader                        | Reconciler                    |
-| -------------- | ----------------------------- | ----------------------------- |
-| Focus          | Orchestration, spawning       | Recovery, fixing              |
-| Runs           | At swarm start, between waves | Continuously during execution |
-| On failure     | Spawns workers                | Spawns fix tasks              |
-| Failure impact | Can't start work              | Wave can't complete           |
-
-### Implementing Reconciler
-
-The reconciler runs in a loop during swarm execution:
-
-```typescript
-// Reconciler runs in background during swarm execution
-async function runReconciler(teamName: string, buildCommand: string) {
-  while (swarmActive) {
-    // 1. Check build status
-    const status = await swarm({
-      operation: "monitor",
-      operation: "status",
-      team_name: teamName,
-    });
-    const stats = JSON.parse(status).summary;
-
-    // 2. If there are errors, investigate
-    if (stats.errors > 0) {
-      // 3. Get error details
-      const errors = await getWorkerErrors(teamName);
-
-      for (const error of errors) {
-        // 4. Analyze root cause
-        const cause = await analyzeError(error);
-
-        // 5. Spawn fix task
-        const fixBead = await br create({
-          title: `Fix: ${cause.summary}`,
-          type: "bug",
-          description: `Detected by reconciler: ${error.message}. Root cause: ${cause.rootCause}. Suggested fix: ${cause.suggestion}`,
-        });
-
-        // 6. Assign to targeted worker
-        await Task({
-          subagent_type: "general",
-          description: `Fix ${error.worker}`,
-          prompt: `Fix the error in ${error.file}.
-
-Error: ${error.message}
-Root cause: ${cause.rootCause}
-Suggested fix: ${cause.suggestion}
-
-Run: ${buildCommand}
-Verify: npm run typecheck && npm run lint`,
-        });
-      }
-    }
-
-    // Wait before next check
-    await sleep(30000); // Check every 30 seconds
-  }
-}
-```
-
-### Error Analysis Patterns
-
-The reconciler categorizes errors:
-
-| Error Type     | Detection                        | Fix Strategy                 |
-| -------------- | -------------------------------- | ---------------------------- |
-| Merge conflict | "CONFLICT" in output, git status | Re-base, resolve, force push |
-| Type error     | "typecheck failed"               | Fix types, run typecheck     |
-| Test failure   | "test failed", "expect" mismatch | Fix test or implementation   |
-| Lint error     | "lint failed", formatting issues | Run lint:fix                 |
-| Build error    | "build failed", bundler errors   | Fix imports, dependencies    |
-
-### Spawning Fix Tasks
-
-When the reconciler spawns a fix task, it includes:
-
-```typescript
-// Create fix task with full context
-await br create({
-  title: `Fix: ${error.type} in ${error.file}`,
-  type: "bug",
-  description: `## Error Detected
-- Worker: ${error.worker}
-- File: ${error.file}
-- Error: ${error.message}
-- Timestamp: ${error.timestamp}
-
-## Root Cause Analysis
-${cause.explanation}
-
-## Suggested Fix
-${cause.suggestion}
-
-## Verification
-Run: ${buildCommand}
-Must pass before wave can complete.`,
-});
-```
-
-### Reconciler in Wave Execution
-
-Add reconciler monitoring to each wave:
-
-```typescript
-// Execute wave with reconciler
-async function executeWaveWithReconciler(wave, teamName) {
-  // Start reconciler in background
-  const reconciler = runReconciler(teamName, "npm run typecheck && npm run lint");
-
-  // Execute workers in this wave
-  await Promise.all(wave.tasks.map(spawnWorker));
-
-  // Wait for all workers + reconciler to complete
-  await reconciler;
-
-  // Verify wave output before proceeding
-  await bash("npm run typecheck && npm run lint");
-}
-```
-
-### Example: Full Swarm with Reconciler
-
-```typescript
-// Full swarm execution with reconciler
-async function runSwarmWithReconciler(tasks, teamName) {
-  // 1. Analyze and create waves
-  const waves = createWaves(tasks);
-
-  // 2. Execute each wave with reconciler
-  for (const wave of waves) {
-    console.log(`Executing wave ${wave.number} with ${wave.tasks.length} tasks`);
-
-    // Start reconciler for this wave
-    const reconcilerPromise = runReconciler(teamName, "npm run typecheck && npm run lint");
-
-    // Spawn workers
-    await Promise.all(wave.tasks.map((task) => spawnWorker(task, teamName)));
-
-    // Wait for reconciler to finish fixing any errors
-    await reconcilerPromise;
-
-    // Verify wave output
-    const result = await bash("npm run typecheck && npm run lint");
-    if (!result.success) {
-      throw new Error(`Wave ${wave.number} failed gates`);
-    }
-
-    console.log(`Wave ${wave.number} complete`);
-  }
-}
-```
-
-## Drift Check After Each Wave
-
-After every wave completes and before starting the next, run a **drift check** to verify the codebase has not deviated from the intended state. Accumulated drift between waves is the primary cause of cascading failures in large swarms.
-
-**Drift** = any difference between actual codebase state and the plan's expected state at a wave boundary.
-
-### What to Check
-
-| Check             | Command                                            | Passing Condition              |
-| ----------------- | -------------------------------------------------- | ------------------------------ |
-| Build gates       | `npm run typecheck && npm run lint`                | Zero errors                    |
-| Unexpected files  | `git diff --name-only HEAD`                        | Only planned files modified    |
-| Missing artifacts | Verify expected files exist                        | All declared outputs present   |
-| Scope adherence   | Compare `git status` vs wave's declared file scope | No out-of-scope files modified |
-
-### Drift Check Protocol
-
-Run after every wave, before spawning the next:
-
-```typescript
-async function driftCheckAfterWave(wave: Wave, expectedFiles: string[]) {
-  console.log(`\n=== DRIFT CHECK: Wave ${wave.number} ===`);
-
-  // 1. Build gates must pass
-  const gates = await bash("npm run typecheck && npm run lint");
-  if (!gates.success) {
-    throw new Error(`Wave ${wave.number} drift: build gates failed\n${gates.output}`);
-  }
-
-  // 2. Detect unexpected file modifications
-  const changedFiles = await bash("git diff --name-only HEAD");
-  const actualFiles = changedFiles.output.trim().split("\n").filter(Boolean);
-  const unexpected = actualFiles.filter((f) => !expectedFiles.includes(f));
-
-  if (unexpected.length > 0) {
-    console.warn(`⚠️  Unexpected files modified in wave ${wave.number}:`);
-    unexpected.forEach((f) => console.warn(`  - ${f}`));
-  }
-
-  // 3. Verify declared artifacts exist
-  for (const artifact of wave.expectedArtifacts ?? []) {
-    const exists = await bash(`test -f ${artifact} && echo "ok" || echo "missing"`);
-    if (exists.output.trim() === "missing") {
-      throw new Error(`Wave ${wave.number} drift: expected artifact missing: ${artifact}`);
-    }
-  }
-
-  console.log(`✓ Drift check passed: Wave ${wave.number}`);
-}
-```
-
-### Integration in Wave Execution
-
-Call drift check between every wave:
-
-```typescript
-for (let i = 0; i < waves.length; i++) {
-  const wave = waves[i];
-  const reconciler = runReconciler(teamName, "npm run typecheck && npm run lint");
-
-  await Promise.all(wave.tasks.map((task) => spawnWorker(task, teamName)));
-  await reconciler;
-
-  // MANDATORY: Drift check before next wave
-  await driftCheckAfterWave(
-    wave,
-    wave.tasks.flatMap((t) => t.assignedFiles),
-  );
-
-  console.log(`✓ Wave ${i + 1}/${waves.length} complete and verified`);
-}
-```
-
-### Drift Response Protocol
-
-| Drift Type               | Severity | Action                                           |
-| ------------------------ | -------- | ------------------------------------------------ |
-| Build gate failure       | Critical | Stop swarm, run reconciler, fix before next wave |
-| Unexpected file modified | Warning  | Review change, revert if out of scope            |
-| Missing artifact         | Critical | Re-run failed worker task, verify output         |
-| Scope creep              | Warning  | Escalate to user if >3 unexpected files changed  |
-
-### When Drift Is Unrecoverable
-
-If drift check fails twice in a row on the same wave:
-
-1. **Stop the swarm** - don't start next wave
-2. **Report to user**: exact drift details, failing gate output, list of unexpected files
-3. **Rollback option**: use `git reset --hard <wave-N-start-tag>` (see `executing-plans` skill)
-4. **Never paper over drift** - proceeding with known drift compounds into cascading failure
-
-## Swarm Launch Flow - PARL Pattern (7 Steps)
-
-### Step 0: Task Analysis (Anti-Serial-Collapse + Dependency Graph)
-
-Analyze the user's actual task to determine optimal swarm strategy:
-
-```typescript
-// 1. Classify the task and build dependency graph
-const analysis = await swarm({
-  operation: "plan",
-  operation: "analyze",
-  task: "<user's request from input>",
-  files: "<detected files from glob/grep>",
-});
-
-// Returns:
-// - type: "search" | "batch" | "writing" | "sequential" | "mixed"
-// - recommended_agents: number
-// - phases: [{ name, role, agent_count, dependencies }]
-// - coupling: "high" | "medium" | "low"
-// - confidence: "high" | "medium" | "low"
-// - dependency_graph: { nodes, edges, critical_path, parallelizable_groups }
-
-const plan = JSON.parse(analysis);
-
-// 2. Check for serial collapse
-const check = await swarm({
-  operation: "plan",
-  operation: "check",
-  task: "<user's request>",
-  files: String(plan.file_count),
-  recommended_agents: plan.classification.recommended_agents,
-});
-
-// If serial collapse detected, force parallelization
-if (check.serial_collapse_detected) {
-  console.log(`⚠️ Serial collapse detected: ${check.warning_signs.join(", ")}`);
-  console.log(`✓ Adjusting to ${check.suggested_agents} agents`);
-}
-
-// 3. Use dependency graph for spawn ordering
-const { parallelizable_groups, critical_path } = plan.dependency_graph;
-console.log(`Critical path: ${critical_path.join(" → ")}`);
-console.log(`Parallel groups: ${parallelizable_groups.length}`);
-```
-
-### Step 1: Session Setup (Push Beads to Todos)
-
-Make Beads tasks visible to subagents:
-
-```typescript
-// Push Beads to OpenCode todos (subagents see via todoread)
-await swarm({ operation: "sync", operation: "push", filter: "open" });
-
-// Check for existing swarm state
-const status = await swarm({
-  operation: "monitor",
-  operation: "status",
-  team_name: "plan-implementation",
-});
-const stats = JSON.parse(status).summary;
-
-if (stats.total_workers > 0) {
-  console.log(`Found existing swarm with ${stats.total_workers} workers`);
-  // Render current progress
-  const ui = await swarm({
-    operation: "monitor",
-    operation: "render_block",
-    team_name: "plan-implementation",
-  });
-  console.log(ui);
-}
-```
-
-### Step 2: Create Delegation Packets
-
-For each task, create a delegation packet:
-
-```typescript
-swarm({
-  operation: "delegate",
-  bead_id: "task-1",
-  title: "Implement auth service",
-  expected_outcome: "Auth service with JWT tokens, tests pass",
-  required_tools: "read, grep, lsp, edit, bash",
-  must_do: "LSP before edits, run npm test after changes",
-  must_not_do: "No new dependencies, don't edit config files",
-  acceptance_checks: "typecheck: npm run typecheck, lint: npm run lint, test: npm test",
-  context: "See .beads/artifacts/task-1/spec.md for requirements",
-  write: true,
-});
-```
-
-### Step 3: Spawn Worker Agents (Using Dependency Groups)
-
-Use parallelizable_groups from dependency graph for proper ordering:
-
-```typescript
-// Spawn workers in dependency order
-for (const group of plan.dependency_graph.parallelizable_groups) {
-  // All tasks in this group can run in parallel
-  const spawnPromises = group.map((taskId) => {
-    const node = plan.dependency_graph.nodes.find((n) => n.id === taskId);
-    return Task({
-      subagent_type: "general",
-      description: `Execute ${taskId}`,
-      prompt: `Execute bead ${taskId}: ${node.content}
-
-Read delegation packet at: .beads/artifacts/${taskId}/delegation.md
-
-Files: ${node.assignedFiles.join(", ")}
-Phase: ${node.phase}
-Worker: ${node.worker}
-Team: plan-implementation
-
-Requirements:
-1. Follow all MUST DO constraints
-2. Avoid all MUST NOT DO items
-3. Run acceptance checks before claiming done
-4. Report progress via swarm monitor`,
-    });
-  });
-
-  // Wait for parallel group to complete before starting next
-  await Promise.all(spawnPromises);
-}
-```
-
-### Step 4: Monitor Progress (Real-time TUI + Persistence)
-
-Monitor with beautiful block UI, progress tracking, and auto-persistence:
-
-```typescript
-let allComplete = false;
-while (!allComplete) {
-  // Option A: Render beautiful TUI block
-  const ui = await swarm({
-    operation: "monitor",
-    operation: "render_block",
-    team_name: "plan-implementation",
-  });
-  console.log(ui); // Markdown block with tables, emojis, progress
-
-  // Option B: Get detailed status
-  const status = await swarm({
-    operation: "monitor",
-    operation: "status",
-    team_name: "plan-implementation",
-  });
-  const stats = JSON.parse(status).summary;
-  // Returns: total_workers, completed, working, errors, messages
-
-  // Check completion
-  allComplete = stats.completed === stats.total_workers;
-
-  if (!allComplete) {
-    // Wait before checking again
-    await new Promise((r) => setTimeout(r, 2000)); // Wait 2s
-  }
-}
-```
-
-### Step 5: Synthesize Results
-
-When all workers complete:
-
-```typescript
-// 1. Get final status
-const finalStatus = await swarm({
-  operation: "monitor",
-  operation: "status",
-  team_name: "plan-implementation",
-});
-
-// 2. Run full verification
-await bash("npm run typecheck && npm run lint && npm test");
-
-// 3. Pull completed todos back to Beads
-await swarm({ operation: "sync", operation: "pull" });
-
-// 4. Clear swarm data
-await swarm({ operation: "monitor", operation: "clear", team_name: "plan-implementation" });
-
-// 5. Close parent bead
-await bash("br close parent-task --reason 'Swarm completed all subtasks'");
-```
-
-## Dependency Graph Features
-
-The `swarm` tool's plan operation includes full dependency graph analysis:
-
-### Structure
-
-```typescript
-interface DependencyGraph {
-  nodes: TaskNode[]; // Individual tasks
-  edges: Edge[]; // Dependencies between tasks
-  critical_path: string[]; // Longest dependency chain
-  parallelizable_groups: string[][]; // Tasks that can run in parallel
-}
-
-interface TaskNode {
-  id: string;
-  content: string;
-  phase: string;
-  worker: string;
-  status: "pending" | "in_progress" | "completed";
-  priority: "high" | "medium" | "low";
-  blockedBy: string[]; // Tasks this depends on
-  blocks: string[]; // Tasks that depend on this
-  assignedFiles: string[]; // Files assigned to this task
-}
-```
-
-### Usage
-
-```typescript
-const analysis = await swarm({
-  operation: "plan",
-  operation: "analyze",
-  task: "Refactor API layer",
-  files: "src/api/users.ts,src/api/posts.ts,src/api/auth.ts",
-});
-
-const plan = JSON.parse(analysis);
-
-// Critical path shows the longest dependency chain
-// Focus attention here for optimal completion time
-console.log(`Critical path: ${plan.dependency_graph.critical_path.join(" → ")}`);
-
-// Parallelizable groups show which tasks can run simultaneously
-// Each group must complete before starting the next
-for (let i = 0; i < plan.dependency_graph.parallelizable_groups.length; i++) {
-  const group = plan.dependency_graph.parallelizable_groups[i];
-  console.log(`Wave ${i + 1}: ${group.join(", ")} (${group.length} parallel tasks)`);
-}
-```
-
-## Todo Persistence for Cross-Session Recovery
-
-## Delegation Packet Structure
-
-```markdown
-# Delegation Packet
-
-- TASK: task-1 - Implement auth service
-- EXPECTED OUTCOME: Auth service with JWT tokens, tests pass
-- REQUIRED TOOLS:
-  - read
-  - grep
-  - lsp
-  - edit
-  - bash
-- MUST DO:
-  - LSP before edits
-  - Run npm test after changes
-  - Follow existing code patterns
-- MUST NOT DO:
-  - No new dependencies
-  - Don't edit config files
-  - Don't modify shared utilities
-- ACCEPTANCE CHECKS:
-  - typecheck: npm run typecheck
-  - lint: npm run lint
-  - test: npm test
-- CONTEXT:
-  See .beads/artifacts/task-1/spec.md for requirements
-```
-
-## Worker Protocol (Updated with Progress Tracking)
-
-Workers follow this execution pattern:
-
-### 1. Read Delegation
-
-```typescript
-// First action: read the delegation packet
-read({ filePath: ".beads/artifacts/<task-id>/delegation.md" });
-```
-
-### 2. Announce Start with Progress
-
-```typescript
-await swarm({
-  operation: "monitor",
-  operation: "progress_update",
-  team_name: "plan-implementation",
-  worker_id: "worker-1",
-  phase: "explore", // or "generate", "reflect", etc.
-  progress: 0,
-  status: "working",
-  file: "src/api/users.ts", // current file being worked on
-});
-```
-
-### 3. Execute Task with Progress Updates
-
-Follow the MUST DO constraints. Avoid MUST NOT DO items. Use required tools only.
-
-Report progress every 25%:
-
-```typescript
-// At 25%, 50%, 75% completion
-await swarm({
-  operation: "monitor",
-  operation: "progress_update",
-  team_name: "plan-implementation",
-  worker_id: "worker-1",
-  phase: "explore",
-  progress: 25, // or 50, 75
-  status: "working",
-  file: "src/api/users.ts",
-});
-```
-
-### 4. Run Acceptance Checks
-
-```bash
-# Run each check from the delegation packet
-npm run typecheck
-npm run lint
-npm test
-```
-
-### 5. Report Completion
-
-```typescript
-// Mark as completed
-await swarm({
-  operation: "monitor",
-  operation: "progress_update",
-  team_name: "plan-implementation",
-  worker_id: "worker-1",
-  phase: "explore",
-  progress: 100,
-  status: "completed",
-  file: "src/api/users.ts",
-});
-```
-
-## Error Handling
-
-### Worker Fails Acceptance Checks
-
-Workers report failures via progress updates with error status:
-
-```typescript
-// Worker reports error via progress update
-await swarm({
-  operation: "monitor",
-  operation: "progress_update",
-  team_name: "plan-implementation",
-  worker_id: "worker-1",
-  phase: "explore",
-  progress: 75,
-  status: "error",
-  message: "typecheck failed: missing type for AuthToken",
-});
-```
-
-### Leader Response
-
-1. Check worker status via `swarm({ operation: "monitor", operation: "status" })`
-2. Review error details in progress entries
-3. Decide: fix locally or reassign to new worker
-
-### Worker Gets Blocked
-
-Workers should report blockers via progress updates:
-
-```typescript
-// Worker reports blocker via progress update
-await swarm({
-  operation: "monitor",
-  operation: "progress_update",
-  team_name: "plan-implementation",
-  worker_id: "worker-2",
-  phase: "explore",
-  progress: 50,
-  status: "blocked",
-  message: "Need auth service types from worker-1",
-});
-```
-
 ## When to Use Swarm vs Single Agent
 
 | Scenario                      | Approach     |
@@ -756,27 +79,6 @@ await swarm({
 | Cross-domain work (FE/BE/DB)  | Swarm        |
 | Time-sensitive parallel work  | Swarm        |
 
-## Integration with Beads
-
-Swarm works on top of Beads:
-
-1. **Session start**: `swarm sync push` to make tasks visible
-2. **Leader claims parent** bead
-3. **Workers claim child** beads (via delegation packets)
-4. **Progress tracked** via `swarm monitor progress_update`
-5. **Completion syncs** back via `swarm sync pull`
-6. **Close parent** bead with `br close`
-
-```typescript
-// Full integration workflow
-await swarm({ operation: "sync", action: "push" }); // Make Beads visible
-// ... spawn swarm ...
-await swarm({ operation: "monitor", action: "render_block", team_name: "..." }); // Monitor progress
-// ... monitor completion ...
-await swarm({ operation: "sync", action: "pull" }); // Sync completed back
-await bash("br close parent-task --reason 'Swarm completed'");
-```
-
 ## Quick Reference - Kimi K2.5 PARL Pattern
 
 ```
@@ -834,141 +136,6 @@ SHUTDOWN:
 - `monitor`: Progress tracking + visualization (actions: progress_update, render_block, status, clear)
 - `sync`: Beads ↔ OpenCode todos (actions: push, pull, create_shared, get_shared, update_shared, list_shared)
 
-## Tmux Integration (Visual Swarm Monitoring)
-
-Enable real-time visualization of swarm workers in separate tmux panes.
-
-### Setup
-
-1. Start OpenCode inside tmux:
-
-```bash
-tmux new -s opencode
-opencode
-```
-
-2. The tmux tool auto-detects when running inside tmux and uses these defaults:
-   - Layout: `main-vertical` (leader left, workers right)
-   - Main pane size: 60%
-   - Auto-cleanup: enabled
-
-### Detecting Tmux
-
-```typescript
-// Check if running inside tmux
-const status = await tmux({ operation: "detect" });
-const { available, inside_session } = JSON.parse(status);
-
-if (!inside_session) {
-  console.log("Tip: Run inside tmux for visual swarm monitoring");
-  console.log("Start with: tmux new -s opencode");
-}
-```
-
-### Spawning Worker Panes
-
-When spawning workers, create visual panes:
-
-```typescript
-// Before spawning worker via Task tool
-if (inside_session) {
-  // Create pane for this worker
-  const pane = await tmux({
-    operation: "spawn",
-    worker_id: "worker-1",
-    title: "Explorer: auth.ts",
-    size: 40, // 40% width
-  });
-
-  const { pane_id } = JSON.parse(pane);
-
-  // Send command to pane (optional - for visual feedback)
-  await tmux({
-    operation: "send",
-    pane_id,
-    command: `echo "🔍 Worker-1: Exploring auth.ts..."`,
-  });
-}
-
-// Spawn the actual worker
-await Task({
-  subagent_type: "general",
-  description: "Execute worker-1",
-  prompt: `...`,
-});
-```
-
-### Layout Options
-
-| Layout            | Description                           | Best For                      |
-| ----------------- | ------------------------------------- | ----------------------------- |
-| `main-vertical`   | Main pane left, workers stacked right | Default, good for 2-4 workers |
-| `main-horizontal` | Main pane top, workers below          | Wide monitors                 |
-| `tiled`           | Equal grid for all panes              | Many workers (5+)             |
-| `even-horizontal` | Equal width columns                   | 2-3 workers                   |
-| `even-vertical`   | Equal height rows                     | 2-3 workers                   |
-
-```typescript
-// Change layout dynamically
-await tmux({
-  operation: "layout",
-  layout: "tiled", // When many workers spawn
-});
-```
-
-### Monitoring Worker Output
-
-```typescript
-// Capture output from a worker's pane
-const output = await tmux({
-  operation: "capture",
-  pane_id: "%5",
-});
-
-// Check what the worker is doing
-console.log(JSON.parse(output).output);
-```
-
-### Cleanup
-
-```typescript
-// Kill specific pane when worker completes
-await tmux({
-  operation: "kill",
-  pane_id: "%5",
-});
-
-// Or cleanup all spawned panes at end of swarm
-await tmux({
-  operation: "cleanup",
-});
-```
-
-### User Commands
-
-| Action                  | Keys          |
-| ----------------------- | ------------- |
-| Switch to next pane     | `Ctrl+B →`    |
-| Switch to previous pane | `Ctrl+B ←`    |
-| Zoom current pane       | `Ctrl+B z`    |
-| Detach (keep running)   | `Ctrl+B d`    |
-| Reattach                | `tmux attach` |
-| List all panes          | `Ctrl+B w`    |
-
-### Watch Command
-
-Use `/swarm-watch` for real-time progress monitoring:
-
-```bash
-/swarm-watch my-swarm-team
-```
-
-This renders the beautiful TUI block and shows:
-
-- Worker progress percentages
-- Current files being worked on
-- Completion status
-
 ## Rules
 
 1. **Leader spawns, workers execute** - Clear role separation
@@ -983,81 +150,14 @@ This renders the beautiful TUI block and shows:
 10. **Use reconciler at scale** - Required for 50+ agents, recommended for 10+
 11. **Reconciler watches continuously** - Spawns fix tasks on detected failures
 
-## Tier Enforcement (Longshot Pattern)
-
-For multi-agent execution at scale (10+ agents), enforce explicit tier hierarchy. This is the Longshot pattern that enabled 200 agents to build Minecraft.
-
-### Tier System
-
-| Tier            | Role                  | Swarm Equivalent | Responsibility                                                 |
-| --------------- | --------------------- | ---------------- | -------------------------------------------------------------- |
-| **planner**     | Lead orchestrator     | Build agent      | Analyzes scope, decomposes into sub-tasks, coordinates workers |
-| **sub-planner** | Mid-level coordinator | N/A              | Takes planner output, further decomposes, assigns to workers   |
-| **worker**      | Execution agent       | Worker agents    | Executes assigned work, reports progress                       |
-
-### When Tiers Are Required
-
-- **<10 agents**: Optional - flat decomposition works
-- **10-50 agents**: Recommended - planner + workers
-- **50+ agents**: Required - planner + sub-planners + workers
-
-### Enforcing Tier Boundaries
-
-The swarm leader enforces tier boundaries:
-
-```typescript
-// Tier enforcement in swarm execution
-async function enforceTiers(waves, tierConfig) {
-  // Wave 1: Planner tasks only
-  const planners = waves.filter((w) => w.tier === "planner");
-  await executeWave(planners);
-
-  // Wave 2: Sub-planner tasks (if any)
-  const subPlanners = waves.filter((w) => w.tier === "sub-planner");
-  await executeWave(subPlanners);
-
-  // Wave 3+: Worker tasks
-  const workers = waves.filter((w) => w.tier === "worker");
-  await executeWave(workers);
-}
-```
-
-### Handoff Contracts Between Tiers
-
-Each tier must declare handoff contracts:
-
-```typescript
-// Planner declares what it produces for sub-planners
-const plannerHandoff = {
-  produces: [
-    { artifact: "docs/auth-design.md", format: "markdown" },
-    { artifact: "tasks/auth-tasks.json", format: "json" },
-  ],
-  consumedBy: ["sub-planner-auth"],
-};
-
-// Worker declares what it consumes from sub-planners
-const workerHandoff = {
-  consumes: [{ artifact: "tasks/auth-tasks.json", format: "json" }],
-  produces: [{ artifact: "src/auth/service.ts", format: "typescript" }],
-};
-```
-
-### Anti-Pattern: Flat Decomposition at Scale
-
-Without tiers, 20 agents get 20 flat tasks → chaos:
-
-- Workers step on each other
-- No coordination between related work
-- Merge conflicts everywhere
-- No clear ownership
-
-With tiers (Longshot pattern):
-
-```
-Lead Planner → Sub-planner A → Worker 1, 2, 3
-              → Sub-planner B → Worker 4, 5, 6
-              Sub-planner C → Worker 7, 8, 9
-```
-
-This mirrors real engineering orgs: lead → tech lead → IC. The architecture is the differentiator.
+## References
+
+- `references/architecture.md` - Swarm architecture diagram
+- `references/reconciler.md` - Reconciler pattern, error analysis, and fix task spawning
+- `references/drift-check.md` - Drift checks after each wave and recovery protocol
+- `references/launch-flow.md` - PARL swarm launch flow with step-by-step code
+- `references/dependency-graph.md` - Dependency graph structures and usage
+- `references/delegation-worker-protocol.md` - Delegation packet structure, worker protocol, and error handling
+- `references/integration-beads.md` - Swarm integration workflow with Beads
+- `references/tmux-integration.md` - Tmux monitoring setup and commands
+- `references/tier-enforcement.md` - Tier enforcement (Longshot pattern)