opencodekit 0.15.15 → 0.15.18

package/dist/template/.opencode/memory/observations/2026-01-30-discovery-kimi-k2-5-agent-swarm-architecture-patte.md

@@ -0,0 +1,45 @@
+---
+type: discovery
+created: 2026-01-30T05:46:18.057Z
+confidence: high
+valid_until: null
+superseded_by: null
+concepts: ["Kimi K2.5", "agent swarm", "PARL", "parallel execution", "task decomposition", "coordination mechanisms"]
+---
+
+# 💡 Kimi K2.5 Agent Swarm Architecture Patterns
+
+🟢 **Confidence:** high
+
+Comprehensive research completed on Kimi K2.5's agent swarm architecture and patterns. Key findings:
+
+## Core Architecture
+- **PARL (Parallel-Agent Reinforcement Learning)**: Training method using staged reward shaping to prevent "serial collapse"
+- **Orchestrator-Agent Model**: Central coordinator that decomposes tasks and manages sub-agents
+- **Critical Steps Metric**: Latency-focused evaluation inspired by parallel computation critical path
+- **Up to 100 sub-agents**: Dynamically instantiated frozen workers
+- **1,500 coordinated tool calls**: Maximum parallel workflow capacity
+
+## Task Decomposition Patterns
+1. **Research Tasks**: Creates specialized agents (AI Researcher, Physics Researcher, Fact Checker)
+2. **Dataset Creation**: Three-phase pipeline (generation → verification → calibration) 
+3. **Multimodal QA**: One-agent-per-item approach with separate coordinator
+4. **Writing Tasks**: Conservative single-agent allocation for tightly coupled work
+
+## Coordination Mechanisms
+- **Agent Modes**: Explore, Decompose, Generate, Reflect, Synthesize
+- **Dynamic Scheduling**: Reuses idle agents, manages bottlenecks
+- **Handoff Protocol**: Agents can pass work between each other
+- **Progress Tracking**: Visual interface shows individual agent status
+
+## Failure Handling
+- **Serial Collapse Prevention**: PARL's staged reward system (λaux anneals 0.1→0.0)
+- **Self-Correction**: Orchestrator monitors and adjusts strategy
+- **Verification First**: Quality control prioritized over raw throughput
+- **Computational Bottleneck**: Makes sequential execution impractical
+
+## Performance Results
+- **4.5x speed improvement** over single-agent for complex tasks
+- **80% reduction** in end-to-end runtime on workloads
+- **CriticalSteps metric**: Focuses on slowest path optimization
+- **Quality over Quantity**: May not honor exact agent count requests

package/dist/template/.opencode/memory/observations/2026-01-30-pattern-swarm-tools-architecture.md

@@ -0,0 +1,28 @@
+---
+type: pattern
+created: 2026-01-30T06:11:22.169Z
+confidence: high
+valid_until: null
+superseded_by: null
+concepts: ["swarm", "tools", "optimization", "architecture", "opencode"]
+---
+
+# 🔄 Swarm Tools Architecture
+
+🟢 **Confidence:** high
+
+Current swarm infrastructure has 5 separate tools:
+
+EXISTING:
+1. swarm-delegate.ts - Creates delegation packets for workers
+2. swarm-helper.ts - Mailbox coordination (getTeamStatus, sendTeamMessage)
+
+NEW (created):
+3. task-classifier.ts - Task analysis & classification
+4. progress-tracker.ts - Real-time progress UI
+5. swarm-orchestrator.ts - Anti-serial-collapse detection
+
+PLUGIN:
+6. swarm-enforcer.ts - Enforces Beads workflow via nudges
+
+Optimization opportunity: Merge overlapping functionality into 2-3 comprehensive tools that work together as a unified swarm system.

package/dist/template/.opencode/memory/research/opencode-mcp-bug-report.md

@@ -100,7 +100,7 @@ The bug is in **OpenCode's tool response handler**, not the MCP connection layer
 
 - `context7_resolve-library-id` - Native HTTP wrapper (works)
 - `context7_query-docs` - Native HTTP wrapper (works)
-- `grep-search` - Native HTTP wrapper (works)
+- `grepsearch` - Native HTTP wrapper (works)
 - `codesearch` (Exa Code API) - works
 - `websearch` (Exa Web Search) - works
 

package/dist/template/.opencode/opencode.json

@@ -3,42 +3,42 @@
   "agent": {
     "build": {
       "description": "Primary development agent with full codebase access",
-      "model": "opencode/big-pickle"
+      "model": "opencode/kimi-k2.5-free"
     },
     "compaction": {
       "description": "Session summarizer for context continuity across compactions"
     },
     "explore": {
       "description": "Fast codebase search specialist",
-      "model": "opencode/big-pickle"
+      "model": "opencode/kimi-k2.5-free"
     },
     "general": {
       "description": "General-purpose subagent for fast, well-defined tasks; delegates complexity quickly",
-      "model": "opencode/big-pickle"
+      "model": "opencode/kimi-k2.5-free"
     },
     "looker": {
       "description": "Media extraction specialist for images, PDFs, diagrams",
-      "model": "opencode/gpt-5-nano"
+      "model": "opencode/kimi-k2.5-free"
     },
     "painter": {
       "description": "Image generation and editing specialist using Gemini 3 Pro Image. Use for creating UI mockups, app icons, hero images, visual assets, and editing/redacting existing images",
-      "model": "opencode/gpt-5-nano"
+      "model": "opencode/kimi-k2.5-free"
     },
     "plan": {
       "description": "Primary planning agent for architecture and multi-phase execution",
-      "model": "opencode/big-pickle"
+      "model": "opencode/kimi-k2.5-free"
     },
     "review": {
       "description": "Code review, debugging, and security audit specialist",
-      "model": "opencode/big-pickle"
+      "model": "opencode/kimi-k2.5-free"
     },
     "scout": {
       "description": "External research specialist for library docs and patterns",
-      "model": "opencode/big-pickle"
+      "model": "opencode/kimi-k2.5-free"
     },
     "vision": {
       "description": "Visual content specialist for multimodal analysis and UI/UX guidance",
-      "model": "opencode/gpt-5-nano"
+      "model": "opencode/kimi-k2.5-free"
     }
   },
   "autoupdate": false,
@@ -149,7 +149,7 @@
       "url": "https://stitch.googleapis.com/mcp"
     }
   },
-  "model": "opencode/big-pickle",
+  "model": "opencode/kimi-k2.5-free",
   "permission": {
     "bash": {
       "*": "allow",
@@ -185,6 +185,34 @@
     "@franlol/opencode-md-table-formatter@0.0.3"
   ],
   "provider": {
+    "kimi-for-coding": {
+      "models": {
+        "k2p5": {
+          "limit": {
+            "context": 262144,
+            "output": 32768
+          },
+          "temperature": true,
+          "reasoning": true,
+          "tool_call": true,
+          "options": {
+            "reasoningEffort": "medium"
+          },
+          "variants": {
+            "high": {
+              "options": {
+                "reasoningEffort": "high"
+              }
+            },
+            "max": {
+              "options": {
+                "reasoningEffort": "max"
+              }
+            }
+          }
+        }
+      }
+    },
     "github-copilot": {
       "models": {
         "claude-haiku-4.5": {
@@ -860,7 +888,7 @@
   "tools": {
     "context7-query-docs": true,
     "context7-resolve-library-id": true,
-    "grep-search": true,
+    "grepsearch": true,
     "oracle": true
   },
   "tui": {
@@ -880,4 +908,4 @@
       ".DS_Store"
     ]
   }
-}
+}

package/dist/template/.opencode/package.json

@@ -11,7 +11,7 @@
     "type-check": "tsc --noEmit"
   },
   "dependencies": {
-    "@opencode-ai/plugin": "1.1.40"
+    "@opencode-ai/plugin": "1.1.44"
   },
   "devDependencies": {
     "@types/node": "^25.0.3",

package/dist/template/.opencode/plans/1768385996691-silent-wizard.md

@@ -44,7 +44,7 @@ If memory returns high-confidence findings on this exact topic, synthesize and r
 | 2 | context7_resolve-library-id | Resolve library names to IDs | Fast |
 | 3 | context7_query-docs | Official library docs | Fast |
 | 4 | codesearch | Exa Code API for SDK/library patterns | Fast |
-| 5 | grep-search | Cross-repo GitHub code search | Medium |
+| 5 | grepsearch | Cross-repo GitHub code search | Medium |
 | 6 | webfetch | Specific doc URLs, READMEs, changelogs | Medium |
 | 7 | opensrc + LSP | Clone & analyze source code | Slow |
 | 8 | websearch | Tutorials, blog posts, recent news | Slow |
@@ -186,7 +186,7 @@ last resort → websearch for tutorials/blogs
 
 **context7 doesn't find library:**
 1. Try `codesearch({ query: "<library> <function> example" })`
-2. Try `gh_grep_searchGitHub({ query: "import.*from.*<library>" })`
+2. Try `gh_grepsearchGitHub({ query: "import.*from.*<library>" })`
 3. Clone with `npx opensrc <library>` and read source
 
 **gh_grep returns nothing:**

package/dist/template/.opencode/{plugin → plugins}/copilot-auth.ts

@@ -49,6 +49,27 @@ function getUrls(domain: string) {
 
 const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
 
+// Rate limit handling configuration
+const RATE_LIMIT_CONFIG = {
+	maxRetries: 3,
+	baseDelayMs: 2000, // Start with 2 seconds
+	maxDelayMs: 30000, // Cap at 30 seconds
+};
+
+/**
+ * Calculate delay with exponential backoff and jitter
+ * Retries: 2s, 4s, 8s (with jitter)
+ */
+function calculateRetryDelay(attempt: number): number {
+	const exponentialDelay = RATE_LIMIT_CONFIG.baseDelayMs * Math.pow(2, attempt);
+	const jitter = Math.random() * 1000; // Add 0-1s random jitter
+	const delay = Math.min(
+		exponentialDelay + jitter,
+		RATE_LIMIT_CONFIG.maxDelayMs,
+	);
+	return Math.round(delay);
+}
+
 export const CopilotAuthPlugin: Plugin = async ({ client: _client }) => {
 	return {
 		auth: {
@@ -176,10 +197,60 @@ export const CopilotAuthPlugin: Plugin = async ({ client: _client }) => {
 						delete headers["x-api-key"];
 						delete headers["authorization"];
 
-						return fetch(input, {
-							...init,
-							headers,
-						});
+						// Retry logic with exponential backoff for rate limiting
+						let lastError: Error | undefined;
+						for (
+							let attempt = 0;
+							attempt <= RATE_LIMIT_CONFIG.maxRetries;
+							attempt++
+						) {
+							try {
+								const response = await fetch(input, {
+									...init,
+									headers,
+								});
+
+								// If we get a 429, retry with backoff
+								if (
+									response.status === 429 &&
+									attempt < RATE_LIMIT_CONFIG.maxRetries
+								) {
+									const delay = calculateRetryDelay(attempt);
+									console.log(
+										`[Copilot] Rate limited (429), retrying in ${delay}ms... (attempt ${attempt + 1}/${RATE_LIMIT_CONFIG.maxRetries})`,
+									);
+									await sleep(delay);
+									continue;
+								}
+
+								return response;
+							} catch (error) {
+								lastError = error as Error;
+
+								// Network errors might be transient, retry
+								if (attempt < RATE_LIMIT_CONFIG.maxRetries) {
+									const delay = calculateRetryDelay(attempt);
+									console.log(
+										`[Copilot] Request failed, retrying in ${delay}ms... (attempt ${attempt + 1}/${RATE_LIMIT_CONFIG.maxRetries})`,
+									);
+									await sleep(delay);
+									continue;
+								}
+								throw error;
+							}
+						}
+
+						// If we've exhausted all retries, throw the last error
+						if (lastError) {
+							throw new Error(
+								`[Copilot] Max retries (${RATE_LIMIT_CONFIG.maxRetries}) exceeded. Last error: ${lastError.message}`,
+							);
+						}
+
+						// This should not be reached, but just in case
+						throw new Error(
+							`[Copilot] Max retries (${RATE_LIMIT_CONFIG.maxRetries}) exceeded`,
+						);
 					},
 				};
 			},

package/dist/template/.opencode/{skill → skills}/deep-research/SKILL.md

@@ -115,7 +115,7 @@ context7_query_docs({ libraryId: "<id>", topic: "<specific question>" });
 
 // Real-world patterns
 codesearch({ query: "<API usage pattern>", tokensNum: 5000 });
-grep_search({ query: "<code pattern>", language: "TypeScript" });
+grepsearch({ query: "<code pattern>", language: "TypeScript" });
 ```
 
 ## Confidence Levels

package/dist/template/.opencode/{skill → skills}/source-code-research/SKILL.md

@@ -366,7 +366,7 @@ Source code research complements other tools:
 | --------------- | -------------------------- | ------------------------------ |
 | **Context7**    | API docs, official guides  | Implementation details         |
 | **codesearch**  | Usage patterns in the wild | Canonical implementation       |
-| **grep_search** | Real-world examples        | How library itself works       |
+| **grepsearch** | Real-world examples        | How library itself works       |
 | **Web search**  | Tutorials, blog posts      | Ground truth from source       |
 | **Codebase**    | Project-specific patterns  | How dependencies actually work |
 
@@ -375,7 +375,7 @@ Source code research complements other tools:
 1. Context7 - Check official docs
 2. Codebase - Check existing usage
 3. **Source code** - If still unclear, fetch source
-4. codesearch/grep_search - See how others use it
+4. codesearch/grepsearch - See how others use it
 5. Web search - Last resort for context
 
 ## Cleanup

package/dist/template/.opencode/{skill → skills}/swarm-coordination/SKILL.md

@@ -2,29 +2,33 @@
 name: swarm-coordination
 description: >
   Use when implementing plans with multiple independent tasks that can run in parallel.
-  Enables leader agents to spawn, coordinate, and monitor worker swarms. Covers delegation
-  packets, mailbox communication, task assignment, and graceful shutdown patterns.
-version: "1.0.0"
+  Enables leader agents to spawn, coordinate, and monitor worker swarms using Kimi K2.5 PARL patterns.
+  Covers task classification, anti-serial-collapse detection, delegation packets, progress tracking,
+  mailbox communication, and graceful shutdown patterns.
+version: "2.0.0"
 license: MIT
 ---
 
-# Swarm Coordination - Multi-Agent Parallel Execution
+# Swarm Coordination - Kimi K2.5 PARL Multi-Agent Execution
 
-Coordinate multiple agents working on independent tasks in parallel. Leader orchestrates, workers execute, mailbox communicates.
+Coordinate multiple agents working on independent tasks in parallel using Kimi K2.5 PARL (Parallel-Agent Reinforcement Learning) patterns.
 
 ## Overview
 
-**Swarm = Leader + Workers + Mailbox**
+**Swarm = Leader + Workers + Progress Tracking + Mailbox**
 
-- **Leader (build agent)**: Orchestrates the swarm - spawns workers, monitors progress, synthesizes results
-- **Workers (general agents)**: Execute independent tasks - read delegation, make changes, report back
+- **Leader (build agent)**: Orchestrates the swarm - analyzes tasks, spawns workers, monitors progress, synthesizes results
+- **Workers (general/explore/review/plan agents)**: Execute independent tasks - read delegation, make changes, report progress
+- **Progress Tracker (swarm-progress.jsonl)**: Real-time progress updates with TUI visualization
 - **Mailbox (swarm-mail.jsonl)**: Append-only log for coordination messages
 
 **Key Distinction**:
 
-- **Swarm**: Parallel execution of independent tasks from a plan
+- **Swarm**: Parallel execution of independent tasks with dynamic allocation
 - **Beads**: Task tracking and dependency management across sessions
 - **Task tool**: Spawning individual subagents for research/execution
+- **swarm-plan tool**: Task classification and anti-serial-collapse detection
+- **swarm-monitor tool**: Progress tracking and TUI visualization
 
 **When to Use Swarm Coordination**:
 
@@ -33,6 +37,13 @@ Coordinate multiple agents working on independent tasks in parallel. Leader orch
 - "Do I need to coordinate multiple agents?" → **YES** = Swarm
 - "Is this a single task or sequential dependency chain?" → **NO** = Single agent
 
+**Kimi K2.5 PARL Patterns**:
+
+- **Task Classification**: Auto-detect parallelization potential
+- **Anti-Serial-Collapse**: Prevent forced sequential execution
+- **Dynamic Allocation**: Conservative start, scale based on bottlenecks
+- **Progress Visualization**: Real-time TUI with beautiful markdown blocks
+
 ## Architecture
 
 ```
@@ -65,7 +76,41 @@ Coordinate multiple agents working on independent tasks in parallel. Leader orch
                     └─────────────────┘
 ```
 
-## Swarm Launch Flow (5 Steps)
+## Swarm Launch Flow - PARL Pattern (6 Steps)
+
+### Step 0: Task Analysis (NEW - Anti-Serial-Collapse)
+
+Analyze the user's actual task to determine optimal swarm strategy:
+
+```typescript
+// 1. Classify the task
+const analysis = await swarm_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"
+
+// 2. Check for serial collapse
+const check = await swarm_plan({
+  operation: "check",
+  task: "<user's request>",
+  files: String(analysis.file_count),
+  recommended_agents: analysis.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`);
+}
+```
 
 ### Step 1: Parse Plan into Tasks
 
@@ -80,6 +125,10 @@ const plan = read({ filePath: ".beads/artifacts/<bead-id>/plan.md" });
 // - Don't modify the same files
 // - Don't have sequential dependencies
 // - Can verify independently
+
+// Use swarm-plan classification to guide task breakdown
+const { type, recommended_agents, phases } = analysis.classification;
+console.log(`Task type: ${type}, Agents: ${recommended_agents}`);
 ```
 
 ### Step 2: Create Delegation Packets
@@ -139,17 +188,55 @@ Task({
 // All three run in parallel
 ```
 
-### Step 4: Monitor Progress
+### Step 4: Monitor Progress (Real-time TUI)
 
-Check mailbox for worker reports:
+Monitor with beautiful block UI and progress tracking:
 
 ```typescript
-swarm_helper({
-  operation: "getTeamStatus",
+// Option A: Render beautiful TUI block
+const ui = await swarm_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_monitor({
+  operation: "status",
+  team_name: "plan-implementation",
+});
+const stats = JSON.parse(status).summary;
+// Returns: total_workers, completed, working, errors, messages
+
+// Option C: Read mailbox messages
+const messages = await swarm_monitor({
+  operation: "mail_read",
   team_name: "plan-implementation",
   limit: 20,
 });
-// Returns messages from workers about progress
+
+// Monitor loop with live updates
+let allComplete = false;
+while (!allComplete) {
+  // Render TUI
+  const block = await swarm_monitor({
+    operation: "render_block",
+    team_name: "plan-implementation",
+  });
+  console.log(block);
+
+  // Check completion
+  const status = await swarm_monitor({
+    operation: "status",
+    team_name: "plan-implementation",
+  });
+  const stats = JSON.parse(status).summary;
+  allComplete = stats.completed === stats.total_workers;
+
+  if (!allComplete) {
+    await new Promise((r) => setTimeout(r, 2000)); // Wait 2s
+  }
+}
 ```
 
 ### Step 5: Synthesize Results
@@ -191,7 +278,7 @@ When all workers complete:
   See .beads/artifacts/task-1/spec.md for requirements
 ```
 
-## Worker Protocol
+## Worker Protocol (Updated with Progress Tracking)
 
 Workers follow this execution pattern:
 
@@ -202,22 +289,47 @@ Workers follow this execution pattern:
 read({ filePath: ".beads/artifacts/<task-id>/delegation.md" });
 ```
 
-### 2. Announce Start
+### 2. Announce Start with Progress
 
 ```typescript
-swarm_helper({
-  operation: "sendTeamMessage",
+await swarm_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
+});
+
+// Also send mail message
+await swarm_monitor({
+  operation: "mail_send",
   team_name: "plan-implementation",
   from_worker: "worker-1",
-  to_worker: "leader",
   message: "Starting: <task-title>",
 });
 ```
 
-### 3. Execute Task
+### 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_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
@@ -230,11 +342,22 @@ npm test
 ### 5. Report Completion
 
 ```typescript
-swarm_helper({
-  operation: "sendTeamMessage",
+// Mark as completed
+await swarm_monitor({
+  operation: "progress_update",
+  team_name: "plan-implementation",
+  worker_id: "worker-1",
+  phase: "explore",
+  progress: 100,
+  status: "completed",
+  file: "src/api/users.ts",
+});
+
+// Send completion message
+await swarm_monitor({
+  operation: "mail_send",
   team_name: "plan-implementation",
   from_worker: "worker-1",
-  to_worker: "leader",
   message: "DONE: <task-title>. All checks passed. Changes: <summary>",
 });
 ```
@@ -367,34 +490,54 @@ bd_claim(); // Gets parent task
 bd_done({ id: "parent-task", msg: "Swarm completed all subtasks" });
 ```
 
-## Quick Reference
+## Quick Reference - Kimi K2.5 PARL Pattern
 
 ```
-SWARM LAUNCH:
-  1. Parse plan → identify parallel tasks
-  2. Create delegation packets (swarm-delegate)
-  3. Spawn workers (Task tool, multiple in one message)
-  4. Monitor mailbox (swarm-helper getTeamStatus)
-  5. Synthesize results
+SWARM LAUNCH (PARL):
+  0. ANALYZE: swarm-plan({ operation: "analyze", task: userRequest, files: detectedFiles })
+     → Get classification, phases, agent count
+  1. CHECK: swarm-plan({ operation: "check", ... })
+     → Detect/prevent serial collapse
+  2. DELEGATE: swarm_delegate({ ... })
+     → Create packets for each worker
+  3. SPAWN: Task({ subagent_type: "general" })
+     → Launch workers in parallel
+  4. MONITOR: swarm_monitor({ operation: "render_block" })
+     → Real-time TUI progress
+  5. SYNC: Handle messages, resolve blockers
+  6. VERIFY: npm run typecheck && npm run lint && npm test
+  7. CLOSE: bd close <bead> --reason "..."
 
 WORKER EXECUTION:
   1. Read delegation packet
-  2. Announce start via mailbox
+  2. Report START: swarm_monitor({ operation: "progress_update", progress: 0, status: "working" })
   3. Execute with constraints
-  4. Run acceptance checks
-  5. Report completion via mailbox
+  4. Report PROGRESS (every 25%): swarm_monitor({ operation: "progress_update", progress: 25/50/75 })
+  5. Run acceptance checks
+  6. Report DONE: swarm_monitor({ operation: "progress_update", progress: 100, status: "completed" })
+  7. Send completion: swarm_monitor({ operation: "mail_send", message: "DONE: ..." })
 
 COORDINATION:
-  - Mailbox: .beads/swarm-mail.jsonl
-  - Delegation: .beads/artifacts/<id>/delegation.md
+  - Progress: .beads/swarm-progress.jsonl (via swarm-monitor)
+  - Mailbox: .beads/swarm-mail.jsonl (via swarm-monitor)
+  - Delegation: .beads/artifacts/<id>/delegation.md (via swarm-delegate)
+  - Analysis: swarm-plan tool for classification
   - File locks: bd_reserve() before spawning
 
 SHUTDOWN:
-  - All workers done → leader sends SHUTDOWN
+  - All workers done → swarm_monitor({ operation: "clear" })
   - Run full test suite
   - Close parent bead
 ```
 
+## New Tools Reference
+
+| Tool               | Purpose                       | Key Operations                                                    |
+| ------------------ | ----------------------------- | ----------------------------------------------------------------- |
+| **swarm-plan**     | Task analysis & orchestration | `analyze`, `classify`, `check`, `allocate`                        |
+| **swarm-delegate** | Create delegation packets     | `swarm_delegate({ ... })`                                         |
+| **swarm-monitor**  | Monitoring & coordination     | `progress_update`, `render_block`, `mail_send`, `status`, `clear` |
+
 ## Rules
 
 1. **Leader spawns, workers execute** - Clear role separation