opencodekit 0.15.16 → 0.15.19

package/dist/template/.opencode/{command → commands}/implement.md

@@ -22,7 +22,7 @@ You're implementing a tracked task. Stay focused, delegate research, verify as y
 skill({ name: "beads" });
 skill({ name: "test-driven-development" });
 skill({ name: "verification-before-completion" });
-skill({ name: "swarm-coordination" }); // For swarm mode
+skill({ name: "swarm-coordination" }); // For swarm mode with Kimi K2.5 PARL patterns
 ```
 
 Get the task details and check hierarchy:
@@ -59,17 +59,39 @@ bd ready --json | grep -q "$ARGUMENTS"
 
 **Or use SWARM MODE for parallel execution (recommended for 3+ subtasks):**
 
-## Swarm Mode Execution (--swarm flag or auto-detect)
+## Swarm Mode Execution (--swarm flag or auto-detect with PARL)
 
-When the task has 3+ independent subtasks that can run in parallel, use swarm coordination:
+When the task has 3+ independent subtasks, use Kimi K2.5 PARL swarm coordination:
 
-### Step 1: Evaluate Swarm Eligibility
+### Step 0: Task Analysis (Anti-Serial-Collapse)
 
 ```typescript
-// Check if subtasks are parallelizable:
-// - Do they modify different files? → YES = parallel OK
-// - Are they sequentially dependent? → NO = parallel OK
-// - Are there 3+ independent tasks? → YES = swarm beneficial
+// 1. Analyze the actual task
+const subtasks = await getSubtasks($ARGUMENTS); // Get all subtask IDs
+const files = await getFilesForSubtasks(subtasks); // Detect relevant files
+
+const analysis = await swarm_plan({
+  operation: "analyze",
+  task: "Implement " + $ARGUMENTS + " with " + subtasks.length + " subtasks",
+  files: files.join(","),
+});
+
+// 2. Check for serial collapse
+const check = await swarm_plan({
+  operation: "check",
+  task: "Implement " + $ARGUMENTS,
+  files: String(subtasks.length),
+  recommended_agents: analysis.classification.recommended_agents,
+});
+
+if (check.serial_collapse_detected) {
+  console.log(`⚠️ Serial collapse detected: ${check.warning_signs.join(", ")}`);
+  console.log(`✓ Adjusting to ${check.suggested_agents} agents`);
+}
+
+// 3. Use classification to guide swarm setup
+const { type, recommended_agents, phases } = analysis.classification;
+console.log(`Task type: ${type}, Agents: ${recommended_agents}, Phases: ${phases.length}`);
 ```
 
 ### Step 2: Create Delegation Packets
@@ -120,10 +142,12 @@ Worker: worker-1
 
 ## Protocol
 1. Read delegation packet FIRST
-2. Announce start: swarm-helper sendTeamMessage
+2. Report START: swarm-monitor({ operation: "progress_update", team_name: "$ARGUMENTS-swarm", worker_id: "worker-<N>", phase: "<phase>", progress: 0, status: "working" })
 3. Execute following MUST DO / avoiding MUST NOT DO
-4. Run ALL acceptance checks
-5. Report completion: swarm-helper sendTeamMessage
+4. Report PROGRESS (every 25%): swarm-monitor({ operation: "progress_update", ...progress: 25/50/75, file: "current-file.ts" })
+5. Run ALL acceptance checks
+6. Report DONE: swarm-monitor({ operation: "progress_update", ...progress: 100, status: "completed" })
+7. Send completion: swarm-monitor({ operation: "mail_send", team_name: "$ARGUMENTS-swarm", from_worker: "worker-<N>", message: "DONE: <actual work completed>" })
 
 Report format:
 - DONE: <summary> (if successful)
@@ -146,25 +170,53 @@ Task({
 // Results available when all complete
 ```
 
-### Step 5: Monitor Progress
+### Step 5: Monitor Progress (Real-time TUI)
 
-Check mailbox for worker status:
+Monitor with beautiful block UI:
 
 ```typescript
-swarm_helper({
-  operation: "getTeamStatus",
+// Render beautiful TUI block
+const ui = await swarm_monitor({
+  operation: "render_block",
   team_name: "$ARGUMENTS-swarm",
-  limit: 20,
+});
+console.log(ui); // Markdown block with tables, emojis, progress
+
+// Check detailed status
+const status = await swarm_monitor({
+  operation: "status",
+  team_name: "$ARGUMENTS-swarm",
+});
+const stats = JSON.parse(status).summary;
+
+// Check mailbox for messages
+const messages = await swarm_monitor({
+  operation: "mail_read",
+  team_name: "$ARGUMENTS-swarm",
+  limit: 10,
 });
 ```
 
 ### Step 6: Handle Worker Reports
 
-| Message | Action                                  |
-| ------- | --------------------------------------- |
-| DONE    | Mark subtask complete, continue waiting |
-| ERROR   | Analyze, fix locally or respawn         |
-| BLOCKED | Resolve blocker, send guidance          |
+Parse messages from swarm-monitor mail_read:
+
+| Message Type | Detection                         | Action                                 |
+| ------------ | --------------------------------- | -------------------------------------- |
+| DONE         | msg.message starts with "DONE"    | Mark subtask complete, check progress  |
+| ERROR        | msg.message starts with "ERROR"   | Analyze, fix locally or respawn worker |
+| BLOCKED      | msg.message starts with "BLOCKED" | Resolve blocker, send guidance         |
+| PROGRESS     | status from progress_update       | Update TUI, check for bottlenecks      |
+
+```typescript
+// Example: Handle errors
+for (const msg of JSON.parse(messages)) {
+  if (msg.message?.startsWith("ERROR")) {
+    console.log(`Worker ${msg.from_worker} failed: ${msg.message}`);
+    // Respawn or fix
+  }
+}
+```
 
 ### Step 7: Final Verification
 
@@ -175,9 +227,16 @@ After all workers complete:
 npm run typecheck && npm run lint && npm test
 ```
 
-### Step 8: Close Epic
+### Step 8: Close Epic & Cleanup
 
 ```bash
+# Clear swarm data
+await swarm_monitor({
+  operation: "clear",
+  team_name: "$ARGUMENTS-swarm"
+});
+
+# Close the epic
 bd close $ARGUMENTS --reason "Swarm completed all subtasks: <summary>"
 ```
 

package/dist/template/.opencode/{command → commands}/new-feature.md

@@ -13,6 +13,7 @@ Create a complete feature track with Epic → Task → Subtask hierarchy, proper
 ```typescript
 skill({ name: "beads" });
 skill({ name: "brainstorming" });
+skill({ name: "swarm-coordination" }); // For parallel task execution with Kimi K2.5 PARL
 ```
 
 ## Parse Arguments
@@ -452,9 +453,11 @@ npm test
 
 ---
 
-## Phase 8: Parallel Task Execution (Optional)
+## Phase 8: Parallel Task Execution with Swarm (Kimi K2.5 PARL)
 
-If multiple tasks are READY (no blockers), execute them in parallel:
+If multiple tasks are READY (no blockers), execute them in parallel using swarm coordination:
+
+### Step 1: Analyze Tasks for Parallelization
 
 ```bash
 # Check what's ready
@@ -462,49 +465,112 @@ bd ready --json
 ```
 
 ```typescript
-// Fire all READY tasks in parallel with auto-close
-background_start({
-  agent: "build",
-  prompt: `Execute bd-xxx1: [Task 1 description]
-
-    Context: This is part of epic [epic-id] for $ARGUMENTS
-
-    Requirements:
-    - Complete all work items in the task spec
-    - Run verification commands
-    - Commit changes with bead ID in message
-
-    Return: Summary of changes, files modified, verification results`,
-  beadId: "bd-xxx1",
-  autoCloseBead: true,
-  title: "task-1-execution"
-})  // → bg_task1
-
-background_start({
-  agent: "build",
-  prompt: `Execute bd-xxx2: [Task 2 description]...`,
-  beadId: "bd-xxx2",
-  autoCloseBead: true,
-  title: "task-2-execution"
-})  // → bg_task2
-
-// Collect results when done
-background_output({ taskId: "bg_task1" })  // → beadClosed: true
-background_output({ taskId: "bg_task2" })  // → beadClosed: true
-
-// Check what's now unblocked
-bd ready  // → Tasks that were blocked by xxx1, xxx2 now READY
+// Get all READY tasks
+const readyTasks = await getReadyTasks($ARGUMENTS);
+
+// Analyze if swarm mode is beneficial
+const analysis = await swarm_plan({
+  operation: "analyze",
+  task: `Implement ${$ARGUMENTS} with ${readyTasks.length} parallel tasks`,
+  files: readyTasks.map((t) => t.files).join(","),
+});
+
+console.log(`Classification: ${analysis.classification.type}`);
+console.log(`Recommended agents: ${analysis.classification.recommended_agents}`);
+```
+
+### Step 2: Setup Swarm Coordination
+
+```typescript
+const teamName = `${$ARGUMENTS}-swarm-${Date.now()}`;
+
+// Create delegation packets for each READY task
+for (const task of readyTasks) {
+  swarm_delegate({
+    bead_id: task.id,
+    title: `Execute ${task.id}: ${task.title}`,
+    expected_outcome: "Task completed with verification passing",
+    required_tools: "read, grep, lsp, edit, bash",
+    must_do: "LSP before edits, run verification, report progress via swarm-monitor",
+    must_not_do: "No new deps, don't edit files outside task scope",
+    acceptance_checks: "typecheck: npm run typecheck, lint: npm run lint, test: npm test",
+    context: `Part of epic ${$ARGUMENTS}. Team: ${teamName}`,
+    write: true,
+  });
+}
+```
+
+### Step 3: Spawn Worker Swarm
+
+```typescript
+// Launch all workers in parallel
+for (const task of readyTasks) {
+  Task({
+    subagent_type: "build",
+    description: `Execute ${task.id}`,
+    prompt: `Execute bead ${task.id}: ${task.title}
+
+## Delegation
+Read: .beads/artifacts/${task.id}/delegation.md
+
+## Coordination
+Team: ${teamName}
+Worker: worker-${task.id}
+
+## Protocol
+1. Read delegation packet
+2. Report START: swarm-monitor({ operation: "progress_update", team_name: "${teamName}", worker_id: "worker-${task.id}", phase: "implement", progress: 0, status: "working" })
+3. Execute task
+4. Report PROGRESS (every 25%): swarm-monitor({ operation: "progress_update", ...progress: 25/50/75, file: "current-file.ts" })
+5. Run acceptance checks
+6. Report DONE: swarm-monitor({ operation: "progress_update", ...progress: 100, status: "completed" })
+7. Send completion: swarm-monitor({ operation: "mail_send", team_name: "${teamName}", from_worker: "worker-${task.id}", message: "DONE: ${task.title} completed" })
+8. Close bead: bd close ${task.id} --reason "Completed via swarm"`,
+  });
+}
+```
+
+### Step 4: Monitor with TUI
+
+```typescript
+// Monitor loop with beautiful UI
+let allComplete = false;
+while (!allComplete) {
+  // Render TUI block
+  const ui = await swarm_monitor({
+    operation: "render_block",
+    team_name: teamName
+  });
+  console.log(ui);
+
+  // Check status
+  const status = await swarm_monitor({
+    operation: "status",
+    team_name: teamName
+  });
+  const stats = JSON.parse(status).summary;
+
+  allComplete = stats.completed === stats.total_workers;
+
+  if (!allComplete) {
+    await new Promise(r => setTimeout(r, 3000));
+  }
+}
 
 // Cleanup
-background_cancel({ all: true })
+await swarm_monitor({ operation: "clear", team_name: teamName });
+
+// Check newly unblocked tasks
+bd ready  // → Tasks that were blocked now READY
 ```
 
-**Parallel Execution Rules:**
+**Swarm Execution Rules:**
 
 - Only fire tasks that are READY (no unresolved blockers)
-- Each background task gets its own build agent session
-- Beads auto-close on successful completion
-- Check `bd ready` after each batch to find newly unblocked tasks
+- Use `swarm-plan analyze` to determine optimal agent count
+- Workers report progress via `swarm-monitor progress_update`
+- Monitor with `swarm-monitor render_block` for TUI
+- Cleanup with `swarm-monitor clear` when done
 
 ---
 

package/dist/template/.opencode/{command → commands}/research.md

@@ -25,10 +25,30 @@ if (thorough) {
 
 // For source code analysis
 skill({ name: "source-code-research" });
+
+// For swarm coordination (if parallel research needed)
+skill({ name: "swarm-coordination" });
 ```
 
 ## Delegation Strategy
 
+### Step 1: Classify Research Task
+
+```typescript
+// Analyze if research benefits from parallelization
+const analysis = await swarm_plan({
+  operation: "analyze",
+  task: "Research " + $ARGUMENTS,
+  files: "<detected files or leave empty for external research>",
+});
+
+// For search-type research with multiple sources, use swarm
+if (analysis.classification.type === "search" && analysis.classification.recommended_agents > 1) {
+  console.log(`Research classified as ${analysis.classification.type}`);
+  console.log(`Recommended: ${analysis.classification.recommended_agents} parallel agents`);
+}
+```
+
 ### Internal Codebase → @explore
 
 Delegate LSP exploration to the explore agent:
@@ -52,15 +72,42 @@ Return file:line references for all findings.`,
 
 Scout handles external sources (context7, grepsearch, codesearch, etc.)
 
-### Parallel Execution
+### Parallel Execution (Swarm Mode for Research)
 
-Run internal and external research in parallel:
+For comprehensive research across multiple domains, use parallel agents:
 
 ```typescript
+// Option A: Simple parallel (2-3 agents)
 // Launch both in parallel
 task({ subagent_type: "explore", prompt: "LSP analysis of..." });
 context7_resolve_library_id({ libraryName: "<lib>" });
 grepsearch({ query: "<pattern>", language: "TypeScript" });
+
+// Option B: Swarm mode for complex multi-domain research
+// Use when researching 3+ different areas simultaneously
+const teamName = `research-${Date.now()}`;
+
+// Spawn research workers
+Task({
+  subagent_type: "explore",
+  description: "Research domain A",
+  prompt: `Research [domain A] for ${$ARGUMENTS}...
+Report via swarm-monitor: progress_update + mail_send to team ${teamName}`,
+});
+
+Task({
+  subagent_type: "scout",
+  description: "Research domain B",
+  prompt: `Research [domain B] for ${$ARGUMENTS}...
+Report via swarm-monitor: progress_update + mail_send to team ${teamName}`,
+});
+
+// Monitor progress
+const ui = await swarm_monitor({
+  operation: "render_block",
+  team_name: teamName,
+});
+console.log(ui);
 ```
 
 ## Load Context

package/dist/template/.opencode/memory/observations/2026-01-29-decision-copilot-auth-plugin-rate-limit-handling.md

@@ -0,0 +1,27 @@
+---
+type: decision
+created: 2026-01-29T14:26:09.644Z
+confidence: high
+valid_until: null
+superseded_by: null
+concepts: ["copilot", "claude", "rate-limit", "retry", "exponential-backoff", "anthropic-sdk", "reasoning"]
+files: [".opencode/plugin/copilot-auth.ts"]
+---
+
+# 🎯 Copilot Auth Plugin Rate Limit Handling
+
+🟢 **Confidence:** high
+
+Implemented retry logic with exponential backoff for Copilot auth plugin to handle 429 rate limit errors while preserving Claude reasoning support.
+
+Changes made to .opencode/plugin/copilot-auth.ts:
+1. Added RATE_LIMIT_CONFIG with maxRetries: 3, baseDelayMs: 2000, maxDelayMs: 30000
+2. Added calculateRetryDelay() function with exponential backoff + jitter
+3. Wrapped fetch() call in retry loop that handles:
+   - HTTP 429 (Too Many Requests) with automatic retry
+   - Network errors with automatic retry
+   - Console logging for debugging retry attempts
+
+Retry delays: ~2s, ~4s, ~8s (with random jitter)
+
+This allows using Claude Opus 4.5 and Haiku 4.5 with reasoning support through Anthropic SDK while gracefully handling rate limit issues instead of failing immediately.

package/dist/template/.opencode/memory/observations/2026-01-29-decision-spec-driven-approach-for-opencodekit.md

@@ -0,0 +1,21 @@
+---
+type: decision
+created: 2026-01-29T15:07:22.755Z
+confidence: high
+valid_until: null
+superseded_by: null
+concepts: ["spec-driven", "code-generation", "agent-prompts", "templates", "testing"]
+---
+
+# 🎯 Spec-driven approach for OpenCodeKit
+
+🟢 **Confidence:** high
+
+After analyzing the 'no-code library' article, decided NOT to apply spec-driven generation to agent prompts themselves (too non-deterministic for production). Instead, adopt these principles:
+
+1. Specs-first design for agent prompts - define expected behavior clearly
+2. Portable test cases for CLI integration tests (language-agnostic YAML)
+3. Generated scaffolding/templates for the `init` command to create OpenCode projects
+4. Keep agent prompts as actual code for determinism and version control
+
+Key insight: Specs are the primary artifact for utilities/scaffolding, but code is primary for core agent behavior.

package/dist/template/.opencode/memory/observations/2026-01-30-decision-github-copilot-claude-routing-keep-disab.md

@@ -0,0 +1,32 @@
+---
+type: decision
+created: 2026-01-30T15:07:59.081Z
+confidence: high
+valid_until: null
+superseded_by: null
+concepts: ["github-copilot", "claude", "anthropic-sdk", "reasoning", "api-routing"]
+files: [".opencode/plugins/copilot-auth.ts"]
+---
+
+# 🎯 GitHub Copilot Claude routing: Keep disabled for stability
+
+🟢 **Confidence:** high
+
+Claude routing through Anthropic SDK is currently disabled in copilot-auth.ts (commit f7aabde). This decision was made because:
+
+1. **Problem**: Enabling Claude routing to use `@ai-sdk/anthropic` with `/v1` endpoint causes "Not Found: 404" errors
+2. **Root cause**: GitHub Copilot's API likely doesn't support the native Anthropic `/v1/messages` endpoint for Claude models through this integration
+3. **Solution**: Keep all models using `@ai-sdk/github-copilot` (OpenAI-compatible `/v1/chat/completions`)
+4. **Trade-off**: All models work, but Claude models don't get native Anthropic SDK optimizations or reasoning features through the `/v1` gateway
+
+To enable reasoning in the future, would need to:
+- Research if GitHub Copilot supports a different endpoint for reasoning
+- Check if there's a separate gateway URL for reasoning models
+- Verify with GitHub Copilot API documentation
+
+Current working configuration (commit f7aabde):
+- All models use `@ai-sdk/github-copilot`
+- All models use `/v1/chat/completions` (OpenAI-compatible)
+- Claude models work but don't have reasoning enabled
+
+File: .opencode/plugins/copilot-auth.ts (lines 93-100)

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.