opencodekit 0.21.10 → 0.23.0

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

@@ -1,244 +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,
-  and graceful shutdown patterns.
-version: "2.1.0"
-license: MIT
-tags: [agent-coordination, workflow]
-dependencies: [beads]
----
-
-# Swarm Coordination - Kimi K2.5 PARL Multi-Agent Execution
-
-> **Replaces** manual task-by-task execution of large plans — sequential bottleneck when tasks have no dependencies
-
-## 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
-
-**Swarm = Leader + Workers + Reconciler + Progress Tracking + Todo Persistence**
-
-- **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
-- **Reconciler**: Watches for CI failures, detects broken builds, auto-spawns fix tasks - this is the self-healing mechanism
-- **Progress Tracker (swarm-progress.jsonl)**: Real-time progress updates with TUI visualization
-- **Todo Persistence (swarm-todos.json)**: Cross-session recovery for interrupted swarms
-
-**Key Tools**:
-
-| Tool    | Purpose                    | When to Use          |
-| ------- | -------------------------- | -------------------- |
-| `swarm` | Unified swarm coordination | All swarm operations |
-
-**swarm operations:**
-
-- `plan`: Task classification & dependency graph (before spawning workers)
-- `delegate`: Create delegation packets (assigning work to workers)
-- `monitor`: Progress tracking + TUI visualization (during swarm execution)
-- `sync`: Sync Beads ↔ OpenCode todos (session start, cross-session)
-
-**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 tool**: Unified operations for planning, monitoring, delegation, and sync
-
-**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
-- **Dependency Graphs**: DAG-based task scheduling with critical path analysis
-
-## 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        |
-
-## Quick Reference - Kimi K2.5 PARL Pattern
-
-```
-SWARM LAUNCH (PARL):
-  0. SETUP: swarm({ operation: "sync", action: "push" })
-     → Make Beads visible to subagents
-  1. ANALYZE: swarm({ operation: "plan", action: "analyze", task: userRequest, files: detectedFiles })
-     → Get classification, phases, dependency_graph
-  2. CHECK: swarm({ operation: "plan", action: "check", ... })
-     → Detect/prevent serial collapse
-  3. DELEGATE: swarm({ operation: "delegate", ... })
-     → Create packets for each worker
-  4. SPAWN: Task({ subagent_type: "general" })
-     → Launch workers using parallelizable_groups order
-  5. MONITOR: swarm({ operation: "monitor", action: "render_block" })
-     → Real-time TUI progress
-  6. VERIFY: npm run typecheck && npm run lint && npm test
-  7. CLOSE: swarm({ operation: "sync", action: "pull" }) && br close <bead>
-
-WORKER EXECUTION:
-  1. Read delegation packet
-  2. Report START: swarm({ operation: "monitor", action: "progress_update", progress: 0, status: "working" })
-  3. Execute with constraints
-  4. Report PROGRESS (every 25%): swarm({ operation: "monitor", action: "progress_update", progress: 25/50/75 })
-  5. Run acceptance checks
-  6. Report DONE: swarm({ operation: "monitor", action: "progress_update", progress: 100, status: "completed" })
-
-COORDINATION:
-  - Progress: .beads/swarm-progress.jsonl (via swarm monitor)
-  - Delegation: .beads/artifacts/<id>/delegation.md (via swarm delegate)
-  - Analysis: swarm tool for classification + dependency graphs
-
-RECOVERY:
-  - Check: swarm({ operation: "monitor", action: "status" })
-  - Use shared task lists: swarm({ operation: "sync", action: "create_shared" })
-  - Continue with remaining workers
-
-SHUTDOWN:
-  - All workers done → swarm({ operation: "monitor", action: "clear" })
-  - Run full test suite
-  - swarm({ operation: "sync", action: "pull" })
-  - Close parent bead
-```
-
-## Tools Reference
-
-| Tool      | Purpose                    | Key Operations                        |
-| --------- | -------------------------- | ------------------------------------- |
-| **swarm** | Unified swarm coordination | `plan`, `monitor`, `delegate`, `sync` |
-
-**swarm operations:**
-
-- `plan`: Task analysis + dependency DAG (actions: analyze, classify, check, allocate)
-- `delegate`: Create delegation packets
-- `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)
-
-## Beads Integration
-
-### Session Start: Load Beads into Todos
-
-Make Beads tasks visible to subagents:
-
-```typescript
-// Push Beads to OpenCode todos
-const result = await swarm({
-  operation: "sync",
-  action: "push",
-  filter: "open", // or "in_progress", "all"
-});
-```
-
-### Session End: Sync Back to Beads
-
-```typescript
-// Pull completed todos back to Beads
-await swarm({ operation: "sync", action: "pull" });
-
-// Clear swarm state
-await swarm({
-  operation: "monitor",
-  action: "clear",
-  team_name: "api-refactor-swarm",
-});
-
-// Sync and commit
-await bash("br sync --flush-only");
-await bash("git add .beads/ && git commit -m 'close swarm'");
-```
-
-### Cross-Session Handoff
-
-For work spanning multiple sessions, use shared task lists:
-
-```typescript
-// Create shared list
-const list = await swarm({
-  operation: "sync",
-  action: "create_shared",
-  name: "api-refactor-swarm",
-  tasks: JSON.stringify([
-    { id: "task-1", content: "Refactor auth", status: "pending", priority: "high" },
-  ]),
-});
-
-// Resume in new session
-const shared = await swarm({
-  operation: "sync",
-  action: "get_shared",
-  list_id: "api-refactor-swarm",
-});
-```
-
-### Data Locations
-
-| Data Type         | Location                                        | Persistence   |
-| ----------------- | ----------------------------------------------- | ------------- |
-| Beads tasks       | `.beads/issues/*.md`                            | Git-backed    |
-| Swarm progress    | `.beads/swarm-progress.jsonl`                   | Session       |
-| Shared task lists | `~/.local/share/opencode/storage/shared-tasks/` | Cross-session |
-| OpenCode todos    | `~/.local/share/opencode/storage/todo/`         | Session       |
-
-## Rules
-
-1. **Leader spawns, workers execute** - Clear role separation
-2. **Delegation packets are contracts** - Workers follow them strictly
-3. **Progress tracking for coordination** - All status via swarm monitor progress updates
-4. **Non-overlapping assignments** - Ensure workers edit different files
-5. **Acceptance checks required** - Workers verify before reporting done
-6. **Persist periodically** - Enable cross-session recovery
-7. **Use dependency graph** - Spawn workers in parallelizable_groups order
-8. **Graceful shutdown** - Leader waits for all workers, syncs back to Beads
-9. **Use tmux for visibility** - Enable visual monitoring when available
-10. **Use reconciler at scale** - Required for 50+ agents, recommended for 10+
-11. **Reconciler watches continuously** - Spawns fix tasks on detected failures
-
-## Anti-Patterns
-
-| Anti-Pattern                                            | Why It Fails                                               | Instead                                                           |
-| ------------------------------------------------------- | ---------------------------------------------------------- | ----------------------------------------------------------------- |
-| Spawning agents for tasks with shared file dependencies | Workers block or overwrite each other, causing merge churn | Partition work by non-overlapping files/modules first             |
-| Not tracking agent completion status                    | Leader loses visibility; work appears done when it is not  | Require `monitor.progress_update` lifecycle (start/progress/done) |
-| Dispatching without pre-computed dependency graph       | Tasks run out of order, causing rework and serial fallback | Run `swarm plan` first and dispatch by `parallelizable_groups`    |
-| Using swarm for < 3 tasks (overhead not worth it)       | Coordination overhead exceeds execution savings            | Use a single agent or 2 direct `Task()` calls                     |
-
-## 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)
-
-## See Also
-
-- `agent-teams` — for coordinated multi-role collaboration beyond large plan execution
-- `dispatching-parallel-agents` — for lightweight parallel debugging of independent failures
-- `executing-plans` — for plan-driven execution when parallelism is moderate or bounded

package/dist/template/.opencode/skill/swarm-coordination/references/architecture.md

@@ -1,39 +0,0 @@
-# Swarm 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   │
-                     └─────────────────┘
-```

package/dist/template/.opencode/skill/swarm-coordination/references/delegation-worker-protocol.md

@@ -1,145 +0,0 @@
-# Delegation Packet Structure and Worker Protocol
-
-## 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",
-});
-```

package/dist/template/.opencode/skill/swarm-coordination/references/dependency-graph.md

@@ -1,50 +0,0 @@
-# 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)`);
-}
-```

package/dist/template/.opencode/skill/swarm-coordination/references/drift-check.md

@@ -1,90 +0,0 @@
-# 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

package/dist/template/.opencode/skill/swarm-coordination/references/integration-beads.md

@@ -1,20 +0,0 @@
-# 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'");
-```