opencodekit 0.15.19 → 0.15.21

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

@@ -1,548 +0,0 @@
----
-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 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 - 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.
-
-## Overview
-
-**Swarm = Leader + Workers + Progress Tracking + Mailbox**
-
-- **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 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**:
-
-- "Does this plan have 3+ independent tasks?" → **YES** = Swarm
-- "Can multiple tasks run in parallel without conflicts?" → **YES** = Swarm
-- "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
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                         BUILD AGENT (Leader)                     │
-│  - Parses plan into tasks                                        │
-│  - Creates delegation packets                                    │
-│  - Spawns worker agents via Task tool                            │
-│  - Monitors mailbox for progress                                 │
-│  - Synthesizes final results                                     │
-└─────────────────────────────────────────────────────────────────┘
-         │                    │                    │
-         ▼                    ▼                    ▼
-┌─────────────┐      ┌─────────────┐      ┌─────────────┐
-│  WORKER-1   │      │  WORKER-2   │      │  WORKER-3   │
-│  (general)  │      │  (general)  │      │  (general)  │
-│             │      │             │      │             │
-│ - Read      │      │ - Read      │      │ - Read      │
-│   delegation│      │   delegation│      │   delegation│
-│ - Execute   │      │ - Execute   │      │ - Execute   │
-│ - Report    │      │ - Report    │      │ - Report    │
-└─────────────┘      └─────────────┘      └─────────────┘
-         │                    │                    │
-         └────────────────────┼────────────────────┘
-                              ▼
-                    ┌─────────────────┐
-                    │  SWARM MAILBOX  │
-                    │  (swarm-mail    │
-                    │   .jsonl)       │
-                    └─────────────────┘
-```
-
-## 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
-
-Extract independent tasks from the approved plan:
-
-```typescript
-// Read the plan
-const plan = read({ filePath: ".beads/artifacts/<bead-id>/plan.md" });
-
-// Identify parallelizable tasks
-// Tasks are parallel if they:
-// - 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
-
-For each task, create a delegation packet:
-
-```typescript
-swarm_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
-
-Use Task tool to spawn workers in parallel:
-
-```typescript
-// Multiple Task calls in one message run simultaneously
-Task({
-  subagent_type: "general",
-  description: "Execute task-1",
-  prompt: `Execute bead task-1: Implement auth service
-
-Read delegation packet at: .beads/artifacts/task-1/delegation.md
-
-Requirements:
-1. Follow all MUST DO constraints
-2. Avoid all MUST NOT DO items
-3. Run acceptance checks before claiming done
-4. Report completion via swarm-helper sendTeamMessage
-
-Team: plan-implementation
-Worker: worker-1`,
-});
-
-Task({
-  subagent_type: "general",
-  description: "Execute task-2",
-  prompt: `Execute bead task-2: Add user routes
-...same pattern...`,
-});
-
-Task({
-  subagent_type: "general",
-  description: "Execute task-3",
-  prompt: `Execute bead task-3: Create frontend forms
-...same pattern...`,
-});
-// All three run in parallel
-```
-
-### Step 4: Monitor Progress (Real-time TUI)
-
-Monitor with beautiful block UI and progress tracking:
-
-```typescript
-// 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,
-});
-
-// 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
-
-When all workers complete:
-
-1. Read their completion messages from mailbox
-2. Verify all acceptance checks passed
-3. Run full test suite
-4. Summarize what was accomplished
-5. Close the parent bead
-
-## 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_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",
-  message: "Starting: <task-title>",
-});
-```
-
-### 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
-# Run each check from the delegation packet
-npm run typecheck
-npm run lint
-npm test
-```
-
-### 5. Report Completion
-
-```typescript
-// 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",
-  message: "DONE: <task-title>. All checks passed. Changes: <summary>",
-});
-```
-
-## Mailbox Message Format
-
-Messages in `.beads/swarm-mail.jsonl`:
-
-```json
-{
-  "timestamp": "2025-01-27T10:30:00.000Z",
-  "team_name": "plan-implementation",
-  "from_worker": "worker-1",
-  "to_worker": "leader",
-  "message": "DONE: Implement auth service. All checks passed.",
-  "status": "unread"
-}
-```
-
-### Message Types
-
-| Type     | From   | To       | Purpose                     |
-| -------- | ------ | -------- | --------------------------- |
-| START    | worker | leader   | Worker beginning task       |
-| PROGRESS | worker | leader   | Intermediate update         |
-| BLOCKED  | worker | leader   | Worker needs help           |
-| DONE     | worker | leader   | Task completed successfully |
-| ERROR    | worker | leader   | Task failed                 |
-| HELP     | worker | worker-N | Request assistance          |
-| ASSIGN   | leader | worker   | New task assignment         |
-| SHUTDOWN | leader | all      | Graceful shutdown signal    |
-
-## Conflict Prevention
-
-### File Reservation
-
-Before workers start, leader reserves files:
-
-```typescript
-// Reserve files for each worker
-bd_reserve({
-  paths: ["src/auth/service.ts", "src/auth/types.ts"],
-  reason: "worker-1: auth service implementation",
-});
-```
-
-### Non-Overlapping Assignments
-
-Ensure workers don't edit same files:
-
-| Worker   | Assigned Files          |
-| -------- | ----------------------- |
-| worker-1 | src/auth/\*             |
-| worker-2 | src/routes/user/\*      |
-| worker-3 | src/components/forms/\* |
-
-## Error Handling
-
-### Worker Fails Acceptance Checks
-
-```typescript
-// Worker sends error message
-swarm_helper({
-  operation: "sendTeamMessage",
-  team_name: "plan-implementation",
-  from_worker: "worker-1",
-  to_worker: "leader",
-  message: "ERROR: typecheck failed. Issue: missing type for AuthToken",
-});
-```
-
-### Leader Response
-
-1. Read error from mailbox
-2. Decide: fix locally or reassign
-3. Either spawn fix-agent or adjust task
-
-### Worker Gets Blocked
-
-```typescript
-// Worker asks for help
-swarm_helper({
-  operation: "sendTeamMessage",
-  team_name: "plan-implementation",
-  from_worker: "worker-2",
-  to_worker: "leader",
-  message: "BLOCKED: Need auth service types. Waiting on worker-1.",
-});
-```
-
-## Graceful Shutdown
-
-Leader signals completion:
-
-```typescript
-// After all workers done
-swarm_helper({
-  operation: "sendTeamMessage",
-  team_name: "plan-implementation",
-  from_worker: "leader",
-  to_worker: "all",
-  message: "SHUTDOWN: All tasks complete. Final verification passed.",
-});
-```
-
-## When to Use Swarm vs Single Agent
-
-| Scenario                      | Approach     |
-| ----------------------------- | ------------ |
-| 1-2 file changes              | Single agent |
-| Sequential dependencies       | Single agent |
-| 3+ independent parallel tasks | Swarm        |
-| Cross-domain work (FE/BE/DB)  | Swarm        |
-| Time-sensitive parallel work  | Swarm        |
-
-## Integration with Beads
-
-Swarm works on top of Beads:
-
-1. **Plan creates beads** for each task
-2. **Leader claims parent** bead
-3. **Workers claim child** beads
-4. **Completion closes** beads via `bd_done()`
-
-```typescript
-// Leader workflow
-bd_claim(); // Gets parent task
-// ... spawn swarm ...
-// ... monitor completion ...
-bd_done({ id: "parent-task", msg: "Swarm completed all subtasks" });
-```
-
-## Quick Reference - Kimi K2.5 PARL Pattern
-
-```
-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. Report START: swarm_monitor({ operation: "progress_update", progress: 0, status: "working" })
-  3. Execute with constraints
-  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:
-  - 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 → 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
-2. **Delegation packets are contracts** - Workers follow them strictly
-3. **Mailbox for coordination** - All communication through swarm-mail
-4. **No file conflicts** - Reserve before spawning workers
-5. **Acceptance checks required** - Workers verify before reporting done
-6. **Graceful shutdown** - Leader waits for all workers, then shuts down