opencodekit 0.15.16 → 0.15.19

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