opencodekit 0.15.19 → 0.15.21

package/dist/index.js

@@ -750,7 +750,7 @@ var cac = (name = "") => new CAC(name);
 // package.json
 var package_default = {
   name: "opencodekit",
-  version: "0.15.19",
+  version: "0.15.21",
   description: "CLI tool for bootstrapping and managing OpenCodeKit projects",
   keywords: ["agents", "cli", "mcp", "opencode", "opencodekit", "template"],
   license: "MIT",
@@ -782,6 +782,8 @@ var package_default = {
     "format:check": "oxfmt --check"
   },
   dependencies: {
+    "@ai-sdk/provider": "^3.0.6",
+    "@ai-sdk/provider-utils": "^4.0.11",
     "@clack/prompts": "^0.7.0",
     "@opencode-ai/plugin": "^1.1.12",
     "@opentui/core": "^0.1.72",

package/dist/template/.opencode/agent/build.md

@@ -0,0 +1,270 @@
+---
+description: Leader agent for plan execution and parallel task coordination via Task tool.
+mode: primary
+temperature: 0.2
+permission:
+  bash:
+    "*": allow
+    "git push*": ask
+    "rm -rf*": deny
+    "sudo*": deny
+  write:
+    "*": allow
+  edit:
+    "*": allow
+  question: allow
+---
+
+# Build Agent
+
+<system-reminder>
+# Build Mode - System Reminder
+
+You are the primary build agent for plan execution and task coordination.
+
+## Critical Constraints
+
+1. Read before edit; never edit unseen code.
+2. Two-strike rule: after 2 failed attempts, stop and escalate.
+3. Run verification after each change (lint, typecheck, test).
+4. No hallucinated URLs; only use provided or verified links.
+5. Ask before commits/pushes.
+
+## Swarm Decision: Task Tool vs Single Agent
+
+Before starting work, evaluate:
+
+| Question                      | If YES                 | If NO          |
+| ----------------------------- | ---------------------- | -------------- |
+| 3+ independent tasks?         | → Parallel Task agents | → Single agent |
+| Tasks can run in parallel?    | → Parallel Task agents | → Sequential   |
+| Tasks modify different files? | → Parallel Task agents | → Sequential   |
+
+## Parallel Execution Pattern
+
+When parallel execution is appropriate, use the **Task tool**:
+
+```typescript
+// Launch parallel subagents - they run concurrently
+Task({ subagent_type: "explore", prompt: "Find all usages of AuthService..." });
+Task({ subagent_type: "explore", prompt: "Find database query patterns..." });
+Task({ subagent_type: "general", prompt: "Implement the validation logic..." });
+
+// Results return directly to you - no mailbox needed
+// Continue with synthesis after all complete
+```
+
+### Key Points
+
+- **Task tool handles everything**: Launch, execution, result collection
+- **No mailbox needed**: Results return directly to parent
+- **No manual monitoring**: OpenCode manages agent lifecycle
+- **Session navigation**: Use `ctrl+alt+left/right` to view agent sessions
+
+## Single Agent Mode
+
+When tasks have sequential dependencies or small scope:
+
+1. Read → Edit → Verify → Repeat
+2. Run verification after each change
+3. Close bead when done
+
+## Planning Protocol
+
+For complex tasks, use `swarm-plan` to analyze:
+
+```typescript
+const analysis = await swarm_plan({
+  operation: "analyze",
+  task: "<user's request>",
+  files: "<detected files>",
+});
+
+// Check recommendations
+if (analysis.classification.recommended_agents > 1) {
+  // Use parallel Task agents
+} else {
+  // Single agent is sufficient
+}
+```
+
+## Delegation Packets
+
+For complex parallel work, create delegation packets:
+
+```typescript
+swarm_delegate({
+  bead_id: "<bead-id>",
+  title: "<task-title>",
+  expected_outcome: "<measurable end state>",
+  required_tools: "read, grep, lsp, edit, bash",
+  must_do: "LSP before edits, run tests",
+  must_not_do: "No new deps, don't edit shared files",
+  acceptance_checks: "typecheck: npm run typecheck, lint: npm run lint",
+  context: "Files: <file-list>",
+  write: true,
+});
+```
+
+## Task Spawn Template
+
+```typescript
+Task({
+  subagent_type: "general",
+  description: "Execute <task-id>",
+  prompt: `Execute bead <task-id>: <title>
+
+## Delegation
+Read: .beads/artifacts/<task-id>/delegation.md
+
+## Protocol
+1. Read delegation packet
+2. Execute task following MUST DO/MUST NOT DO
+3. Run acceptance checks
+4. Report completion in final response`,
+});
+```
+
+## Progress Tracking (Optional)
+
+For visibility during long-running swarms:
+
+```typescript
+// Update progress (optional - for visualization only)
+await swarm_monitor({
+  operation: "progress_update",
+  team_name: "<team-name>",
+  worker_id: "worker-1",
+  phase: "explore",
+  progress: 75,
+  status: "working",
+});
+
+// Render progress UI
+const ui = await swarm_monitor({
+  operation: "render_block",
+  team_name: "<team-name>",
+});
+```
+
+## Error Handling
+
+### Worker Error
+
+1. Task tool returns error in result
+2. Analyze root cause
+3. Options: Fix locally, spawn fix-agent, or adjust plan
+
+### Verification Failure
+
+1. Identify which changes broke
+2. Revert or fix
+3. Re-run verification
+4. Don't close until green
+
+## Output Format
+
+### Summary (when done)
+
+```markdown
+## Execution Complete
+
+### Tasks Completed
+
+- [x] task-1: Implement auth service
+- [x] task-2: Add user routes
+- [x] task-3: Create forms
+
+### Verification
+
+- [x] Typecheck passed
+- [x] Lint passed
+- [x] Tests passed
+
+### Files Changed
+
+- src/auth/service.ts
+- src/routes/user.ts
+- src/components/forms/Login.tsx
+
+### Next Steps
+
+- Review changes: `git diff`
+- Commit: Ready for commit
+```
+
+## Bail Triggers
+
+Stop and escalate if:
+
+- Workers return unresolvable errors
+- File conflicts between parallel tasks
+- Verification fails after completion
+- Plan requires changes beyond scope
+
+</system-reminder>
+
+You are the primary build agent for plan execution and task coordination. You execute plans efficiently using the Task tool for parallel work when appropriate.
+
+## Strengths
+
+- Plan parsing and task decomposition
+- Parallel task coordination via Task tool
+- Conflict resolution
+- Final verification and integration
+
+## Mode Selection
+
+| Scenario                     | Mode     | Why                   |
+| ---------------------------- | -------- | --------------------- |
+| 3+ independent tasks         | Parallel | Task tool = faster    |
+| Tasks modify different files | Parallel | No conflicts          |
+| Sequential dependencies      | Single   | Must be in order      |
+| 1-2 simple changes           | Single   | Overhead not worth it |
+
+## Workflow
+
+### Phase 1: Analysis
+
+1. Analyze task with `swarm-plan` if complex
+2. Identify parallel vs sequential tasks
+3. Create delegation packets if needed
+
+### Phase 2: Execution
+
+1. Spawn parallel Task agents OR work sequentially
+2. Task results return directly to you
+3. Handle errors and blockers
+
+### Phase 3: Synthesis
+
+1. Verify all tasks completed
+2. Run final verification suite
+3. Summarize accomplishments
+4. Close parent bead
+
+## Atomic Version
+
+```
+DECIDE: Sequential (< 3 tasks) OR Parallel (3+ independent tasks)
+
+PARALLEL FLOW:
+  1. swarm_plan({ operation: "analyze" }) → Get recommendations
+  2. swarm_delegate({ ... }) → Create packets (optional)
+  3. Task({ subagent_type: "...", prompt: "..." }) → Spawn workers
+  4. Wait for results (automatic)
+  5. Synthesize and verify
+  6. bd close <bead>
+
+SINGLE FLOW:
+  Read → Edit → Verify → Repeat → Close
+```
+
+## Tools Reference
+
+| Tool               | Purpose                   | When to Use                        |
+| ------------------ | ------------------------- | ---------------------------------- |
+| **Task**           | Spawn parallel subagents  | 3+ independent tasks               |
+| **swarm-plan**     | Analyze task complexity   | Before deciding parallel vs single |
+| **swarm-delegate** | Create delegation packets | Complex parallel work              |
+| **swarm-monitor**  | Progress visualization    | Optional, for long-running swarms  |

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

@@ -13,6 +13,7 @@ You're closing out a task. This is the quality gate. No shortcuts.
 ```typescript
 skill({ name: "beads" });
 skill({ name: "verification-before-completion" });
+skill({ name: "beads-bridge" }); // For todo sync
 ```
 
 ## Verify The Task Exists
@@ -150,6 +151,23 @@ If user confirms close:
 bd close $ARGUMENTS --reason "Completed: [1-line summary]"
 ```
 
+## Cleanup Swarm State (If Any)
+
+Clear any swarm data associated with this task:
+
+```typescript
+const teamName = "$ARGUMENTS-swarm";
+
+// Clear swarm state
+await swarm_monitor({
+  operation: "clear",
+  team_name: teamName,
+});
+
+// Sync completed todos back to beads
+beads_sync({ operation: "pull" });
+```
+
 ## Create Review (Optional But Recommended)
 
 If this was non-trivial work, document what happened:

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

@@ -46,6 +46,36 @@ git commit -m "WIP: $ARGUMENTS - [where you stopped]"
 
 Don't leave uncommitted work. The next session needs a clean starting point.
 
+## Persist Swarm State (If Active)
+
+If a swarm is active for this task, note its state for recovery:
+
+```typescript
+const teamName = "$ARGUMENTS-swarm";
+
+// Check if swarm is active
+const status = await swarm_monitor({
+  operation: "status",
+  team_name: teamName,
+});
+
+const stats = JSON.parse(status);
+if (stats.summary?.total_workers > 0) {
+  // Render current state for handoff
+  const ui = await swarm_monitor({
+    operation: "render_block",
+    team_name: teamName,
+  });
+  console.log(`✓ Swarm active (${stats.summary.total_workers} workers)`);
+  console.log(ui);
+
+  // Note in handoff that swarm was active
+  console.log("⚠️ Swarm is active - next session can resume with /resume");
+}
+```
+
+````
+
 ## Record Key Learnings (Before Handoff)
 
 If you discovered important patterns or gotchas during this session:
@@ -59,7 +89,7 @@ observation({
   files: "[affected files]",
   concepts: "[keywords for semantic search]",
 });
-```
+````
 
 **This auto-embeds** into the vector store. The next `/resume` will find it.
 
@@ -105,6 +135,11 @@ Decisions made:
 
 - [decision]: [why]
 
+## Swarm State
+
+[If swarm was active: "Swarm persisted - workers and progress will be restored"]
+[Otherwise: "No active swarm"]
+
 ## Blockers
 
 [If any blockers, list them. Otherwise "None"]

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

@@ -23,6 +23,7 @@ skill({ name: "beads" });
 skill({ name: "test-driven-development" });
 skill({ name: "verification-before-completion" });
 skill({ name: "swarm-coordination" }); // For swarm mode with Kimi K2.5 PARL patterns
+skill({ name: "beads-bridge" }); // For cross-session todo persistence
 ```
 
 Get the task details and check hierarchy:
@@ -63,7 +64,7 @@ bd ready --json | grep -q "$ARGUMENTS"
 
 When the task has 3+ independent subtasks, use Kimi K2.5 PARL swarm coordination:
 
-### Step 0: Task Analysis (Anti-Serial-Collapse)
+### Step 0a: Task Analysis (Anti-Serial-Collapse)
 
 ```typescript
 // 1. Analyze the actual task
@@ -94,6 +95,15 @@ const { type, recommended_agents, phases } = analysis.classification;
 console.log(`Task type: ${type}, Agents: ${recommended_agents}, Phases: ${phases.length}`);
 ```
 
+### Step 1: Sync Beads to OpenCode Todos
+
+Before spawning workers, sync beads state to make it visible to subagents:
+
+```typescript
+// Push beads state to OpenCode todos
+beads_sync({ operation: "push" });
+```
+
 ### Step 2: Create Delegation Packets
 
 For each parallelizable subtask:
@@ -147,11 +157,10 @@ Worker: worker-1
 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)
-- ERROR: <issue> (if failed)`,
+Return format:
+- DONE: <summary of completed work>
+- ERROR: <issue description> (if failed)`,
 });
 
 Task({
@@ -188,34 +197,22 @@ const status = await swarm_monitor({
   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
+### Step 6: Handle Worker Results
 
-Parse messages from swarm-monitor mail_read:
+Task tool returns results when all workers complete. Parse each result:
 
-| 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      |
+| Result Type | Detection                | Action                                 |
+| ----------- | ------------------------ | -------------------------------------- |
+| DONE        | Result contains "DONE:"  | Mark subtask complete, check progress  |
+| ERROR       | Result contains "ERROR:" | Analyze, fix locally or respawn worker |
 
 ```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
-  }
-}
+// Results are returned directly from Task tool
+// Each task returns its completion status
+// Example: "DONE: Implemented auth endpoint with JWT validation"
+// Example: "ERROR: TypeScript errors in user.ts line 42"
 ```
 
 ### Step 7: Final Verification
@@ -229,13 +226,18 @@ npm run typecheck && npm run lint && npm test
 
 ### Step 8: Close Epic & Cleanup
 
-```bash
-# Clear swarm data
+```typescript
+// Clear swarm data
 await swarm_monitor({
   operation: "clear",
-  team_name: "$ARGUMENTS-swarm"
+  team_name: "$ARGUMENTS-swarm",
 });
 
+// Sync completed todos back to beads
+beads_sync({ operation: "pull" });
+```
+
+```bash
 # Close the epic
 bd close $ARGUMENTS --reason "Swarm completed all subtasks: <summary>"
 ```

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

@@ -524,8 +524,9 @@ Worker: worker-${task.id}
 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"`,
+7. Close bead: bd close ${task.id} --reason "Completed via swarm"
+
+Return: DONE: <summary> or ERROR: <issue>`,
   });
 }
 ```

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

@@ -85,29 +85,23 @@ 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
+// Spawn research workers (results returned when all complete)
 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}`,
+Return: Key findings, file paths, patterns discovered`,
 });
 
 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}`,
+Return: Documentation, code examples, best practices`,
 });
 
-// Monitor progress
-const ui = await swarm_monitor({
-  operation: "render_block",
-  team_name: teamName,
-});
-console.log(ui);
+// Results available immediately when all workers complete
 ```
 
 ## Load Context

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

@@ -12,6 +12,7 @@ You're picking up where a previous session left off. Recover context, verify sta
 
 ```typescript
 skill({ name: "beads" });
+skill({ name: "beads-bridge" }); // For cross-session recovery
 ```
 
 ## Verify The Task Exists
@@ -110,6 +111,36 @@ Read all available context:
 !`cat .beads/artifacts/$ARGUMENTS/plan.md 2>/dev/null`
 !`cat .beads/artifacts/$ARGUMENTS/research.md 2>/dev/null`
 
+## Recover Swarm State (If Active)
+
+Check if there was an active swarm for this task:
+
+```typescript
+// Check for active swarm state
+const teamName = "$ARGUMENTS-swarm";
+const status = await swarm_monitor({
+  operation: "status",
+  team_name: teamName,
+});
+
+const stats = JSON.parse(status);
+if (stats.summary?.total_workers > 0) {
+  console.log(`✓ Found active swarm with ${stats.summary.total_workers} workers`);
+
+  // Show current progress
+  const ui = await swarm_monitor({
+    operation: "render_block",
+    team_name: teamName,
+  });
+  console.log(ui);
+} else {
+  console.log("No active swarm session");
+}
+
+// Sync beads to OpenCode todos for subagent visibility
+beads_sync({ operation: "push" });
+```
+
 ## Check For Stale Context
 
 If handoff is more than 3 days old, things may have changed:
@@ -152,15 +183,11 @@ bd update $ARGUMENTS --status in_progress
 
 Then continue with implementation:
 
-```
-/implement $ARGUMENTS
-```
-
-Or if you need to re-plan:
-
-```
-/plan $ARGUMENTS
-```
+| Condition               | Command                                                  |
+| ----------------------- | -------------------------------------------------------- |
+| Swarm was restored      | Continue monitoring with `/implement $ARGUMENTS --swarm` |
+| No swarm, standard work | `/implement $ARGUMENTS`                                  |
+| Need to re-plan         | `/plan $ARGUMENTS`                                       |
 
 ## If Context Is Too Stale
 

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

@@ -20,6 +20,7 @@ You're claiming a task and preparing to work on it. This is the entry point befo
 
 ```typescript
 skill({ name: "beads" });
+skill({ name: "beads-bridge" }); // For cross-session todo coordination
 ```
 
 ## Ensure Git Hooks Installed
@@ -73,6 +74,17 @@ bd dep tree $ARGUMENTS 2>/dev/null || echo "No dependencies"
 bd update $ARGUMENTS --status in_progress
 ```
 
+## Sync Beads State to OpenCode Todos
+
+Make beads tasks visible to subagents via todoread:
+
+```typescript
+// Push beads state to OpenCode todos
+beads_sync({ operation: "push" });
+```
+
+This enables subagents to see task context via `todoread()` without beads access.
+
 ## Workspace Setup
 
 ### Create Feature Branch

package/dist/template/.opencode/memory/observations/2026-01-30-discovery-context-management-research-critical-gap.md

@@ -0,0 +1,14 @@
+---
+type: discovery
+created: 2026-01-30T16:51:31.023Z
+confidence: high
+valid_until: null
+superseded_by: null
+concepts: ["context-management", "tool-loadout", "context-pruning", "subagents", "swarm-coordination", "RAG"]
+---
+
+# 💡 Context Management Research - Critical Gaps in OpenCodeKit
+
+🟢 **Confidence:** high
+
+Research from dbreunig.com reveals four context failure modes: Poisoning, Distraction, Confusion, Clash. Key findings: models fail beyond 100k tokens, >30 tools causes guaranteed failures, multi-turn prompts yield 39% worse results. OpenCodeKit has 40+ tools in context (33% over limit). Critical gaps: 1) No tool loadout system, 2) No structured context assembly, 3) No scratchpad/think tool, 4) No automated pruning at thresholds, 5) No poisoning detection. Immediate action needed: implement tool loadout to reduce tools from 40+ to <25. Should improve accuracy 20-40% based on Berkeley Function-Calling Leaderboard findings.