opencodekit 0.15.20 → 0.16.0

package/dist/index.js

@@ -750,7 +750,7 @@ var cac = (name = "") => new CAC(name);
 // package.json
 var package_default = {
   name: "opencodekit",
-  version: "0.15.20",
+  version: "0.16.0",
   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",
@@ -3867,23 +3869,21 @@ var MODEL_PRESETS = {
       looker: "opencode/kimi-k2.5-free",
       vision: "opencode/kimi-k2.5-free",
       scout: "opencode/minimax-m2.1-free",
-      painter: "opencode/kimi-k2.5-free",
-      compaction: "opencode/kimi-k2.5-free"
+      painter: "opencode/kimi-k2.5-free"
     }
   },
   recommend: {
     model: "github-copilot/claude-opus-4.5",
     agents: {
       build: "github-copilot/claude-opus-4.5",
-      plan: "openai/gpt-5.2",
-      review: "openai/gpt-5.2-codex",
+      plan: "github-copilot/gpt-5.2-codex",
+      review: "github-copilot/gpt-5.2-codex",
       explore: "proxypal/gemini-3-flash-preview",
       general: "opencode/kimi-k2.5-free",
       looker: "proxypal/gemini-3-flash-preview",
       vision: "proxypal/gemini-3-pro-preview",
       scout: "opencode/kimi-k2.5-free",
-      painter: "proxypal/gemini-3-pro-image-preview",
-      compaction: "opencode/kimi-k2.5-free"
+      painter: "proxypal/gemini-3-pro-image-preview"
     }
   }
 };

package/dist/template/.opencode/AGENTS.md

@@ -16,6 +16,12 @@ Everything else is guidelines, not laws.
 
 ---
 
+## Skills vs Commands
+
+- Use **commands** for user-facing entrypoints (workflows and intent).
+- Use **skills** for reusable procedures and checklists.
+- If a command mostly repeats steps used elsewhere, move those steps into a skill.
+
 ## Core Constraints
 
 These are hard limits that must never be violated:
@@ -303,7 +309,7 @@ When tools fail or return unexpected results:
 
 1. **DO NOT** retry the same call more than twice
 2. Check fallback chains in agent documentation
-3. **Use Oracle for second opinion** on complex debugging
+3. **Use review agent for second opinion** on complex debugging
 4. If still stuck, ask user for guidance
 5. Log failures using `observation` tool for future reference
 
@@ -311,13 +317,13 @@ When tools fail or return unexpected results:
 
 ```
 Primary tool fails → Try alternative tool
-Alternative fails → Oracle for second opinion
+Alternative fails → Spawn review agent for second opinion
 Still stuck → Ask user
 ```
 
-### Oracle Tool
+### Review Agent (Second Opinion)
 
-Use `oracle` to get a second opinion from a different AI model (gpt-5.2-codex by default) for complex reasoning tasks.
+Use `review` (via Task) to get a second opinion on complex reasoning tasks.
 
 **When to use:**
 
@@ -326,17 +332,12 @@ Use `oracle` to get a second opinion from a different AI model (gpt-5.2-codex by
 - Getting alternative perspectives on tricky problems
 - Breaking out of reasoning ruts or confirmation bias
 
-**Modes:**
-
-- `validate`: Check if reasoning is sound (default)
-- `alternative`: Get completely different approaches
-- `critique`: Stress-test ideas for weaknesses
-- `brainstorm`: Expand and generate new possibilities
-
 ```typescript
-oracle({ question: "Is this the right approach?", context: "..." });
-oracle({ question: "Why is this failing?", mode: "critique" });
-oracle({ question: "What alternatives exist?", mode: "alternative" });
+Task({
+  subagent_type: "review",
+  description: "Second opinion",
+  prompt: "Review the approach and identify risks or alternatives.",
+});
 ```
 
 ---
@@ -361,17 +362,17 @@ Before you start implementing, verify the requirements are clear. If interpretat
 
 Before you claim completion, verify these things:
 
-1. **Run Oracle critique** on any significant code changes:
+1. **Run review agent** on any significant code changes:
 
    ```typescript
-   oracle({
-     question: "Is this solution overcomplicated? Could it be 10x simpler?",
-     mode: "critique",
-     context: "<summary of changes>",
+   Task({
+     subagent_type: "review",
+     description: "Critical review",
+     prompt: "Is this solution overcomplicated? Could it be 10x simpler?",
    });
    ```
 
-   If Oracle suggests simplification, implement it before proceeding.
+   If review suggests simplification, implement it before proceeding.
 
 2. You ran `bd close <id>` with a meaningful reason
 3. You ran `bd sync` to push changes

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

@@ -0,0 +1,351 @@
+---
+description: Leader agent for plan execution and parallel task coordination via Task tool.
+mode: primary
+temperature: 0.2
+steps: 50
+permission:
+  bash:
+    "*": allow
+    "git push*": ask
+    "rm -rf*": ask
+    "sudo*": ask
+  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.
+
+## Auto-Load Skills (Contextual)
+
+Load skills based on task context. DO NOT load all skills - only what's needed.
+
+### Always Load (Core)
+
+```typescript
+skill({ name: "beads" }); // Task tracking (always)
+skill({ name: "verification-before-completion" }); // Never skip verification
+```
+
+### Load Based on Artifacts
+
+```typescript
+// Check what exists in .beads/artifacts/<bead-id>/
+const artifacts = ls(".beads/artifacts/<bead-id>/");
+
+if (artifacts.includes("prd.md")) {
+  skill({ name: "prd-task" }); // PRD execution
+}
+
+if (!artifacts.includes("prd.md") && taskType === "feature") {
+  skill({ name: "prd" }); // PRD creation for features
+}
+
+if (artifacts.includes("plan.md")) {
+  skill({ name: "executing-plans" }); // Plan execution
+}
+```
+
+### Load Based on Task Type
+
+```typescript
+// Parallel work (3+ independent tasks)
+if (recommendedAgents > 1) {
+  skill({ name: "swarm-coordination" }); // Full swarm workflow
+  skill({ name: "beads-bridge" }); // Cross-session todos
+}
+
+// Debugging/bug fixes
+if (taskType === "bug") {
+  skill({ name: "systematic-debugging" }); // Debug workflow
+  skill({ name: "root-cause-tracing" }); // Trace to source
+}
+
+// Testing work
+if (taskTitle.includes("test") || taskType === "test") {
+  skill({ name: "test-driven-development" }); // TDD workflow
+  skill({ name: "testing-anti-patterns" }); // Avoid bad tests
+}
+
+// Frontend/UI work
+if (files.some((f) => f.includes("component") || f.endsWith(".tsx"))) {
+  skill({ name: "frontend-design" }); // UI patterns
+  skill({ name: "react-best-practices" }); // React optimization
+}
+
+// Git worktree needed
+if (flags.includes("--worktree") || taskType === "epic") {
+  skill({ name: "using-git-worktrees" }); // Isolated workspaces
+}
+```
+
+### Skill Loading Decision Table
+
+| Context                  | Skills to Load                                     |
+| ------------------------ | -------------------------------------------------- |
+| **Always**               | `beads`, `verification-before-completion`          |
+| **Has prd.md**           | `prd-task`                                         |
+| **Feature without PRD**  | `prd`                                              |
+| **Has plan.md**          | `executing-plans`                                  |
+| **3+ parallel tasks**    | `swarm-coordination`, `beads-bridge`               |
+| **Bug fix**              | `systematic-debugging`, `root-cause-tracing`       |
+| **Test work**            | `test-driven-development`, `testing-anti-patterns` |
+| **Frontend/UI**          | `frontend-design`, `react-best-practices`          |
+| **Epic or --worktree**   | `using-git-worktrees`                              |
+| **Before claiming done** | `requesting-code-review`                           |
+| **Finishing branch**     | `finishing-a-development-branch`                   |
+
+## Critical Constraints
+
+1. Read before edit; never edit unseen code.
+2. Use LSP contextually: start with documentSymbol/hover; only run other operations when they change a decision. Never run all 9 by default.
+3. Two-strike rule: after 2 failed attempts, stop and escalate.
+4. Run verification after each change (lint, typecheck, test).
+5. No hallucinated URLs; only use provided or verified links.
+6. 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: "Contextual LSP before edits (only required ops), 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/{agents → agent}/explore.md

@@ -2,7 +2,7 @@
 description: Fast codebase search specialist. Use this agent to find files by patterns, search code for keywords, or understand how the codebase works. Specify thoroughness level - "quick" for simple lookups, "medium" for moderate exploration, "very thorough" for comprehensive analysis.
 mode: subagent
 temperature: 0.1
-maxSteps: 25
+steps: 25
 tools:
   edit: false
   write: false

package/dist/template/.opencode/{agents → agent}/general.md

@@ -17,13 +17,63 @@ permission:
 
 You are the general subagent for fast, well-defined tasks on 1-3 files.
 
+## Minimal Skill Loading (Subagent Philosophy)
+
+**Subagents stay lean.** Unlike the build leader, you don't load full workflows.
+Only load skills that directly help execution:
+
+```typescript
+// ALWAYS: Verification is non-negotiable
+skill({ name: "verification-before-completion" });
+
+// CONDITIONAL: Only if delegation packet exists
+if (read(".beads/artifacts/<task-id>/delegation.md")) {
+  // Delegation packet has all context - follow it strictly
+  // No additional skills needed
+}
+
+// CONDITIONAL: Only if bug fix task
+if (taskType === "bug" || description.includes("fix")) {
+  skill({ name: "systematic-debugging" });
+}
+
+// CONDITIONAL: Only if test task
+if (taskType === "test" || description.includes("test")) {
+  skill({ name: "test-driven-development" });
+}
+```
+
+### Subagent Skill Rules
+
+| Rule                              | Why                                      |
+| --------------------------------- | ---------------------------------------- |
+| **NO** `beads` skill              | Subagents don't modify beads - read-only |
+| **NO** `swarm-coordination`       | Leader handles swarm, not workers        |
+| **NO** `prd` or `prd-task`        | PRD workflow is leader responsibility    |
+| **NO** `brainstorming`            | Subagents execute, don't design          |
+| **YES** `verification-*`          | Always verify before reporting done      |
+| **YES** `systematic-debugging`    | Only for bug fix tasks                   |
+| **YES** `test-driven-development` | Only for test tasks                      |
+
+### Trust the Delegation Packet
+
+If you received a delegation packet, it contains:
+
+- Expected outcome
+- Required tools
+- MUST DO / MUST NOT DO rules
+- Acceptance checks
+
+**Follow the packet strictly.** Don't load extra skills that override packet instructions.
+
 ## Critical Constraints
 
 1. Read before edit; never edit unseen code.
-2. Two-strike rule: after 2 failed attempts, stop and escalate.
-3. Bail on complexity: 4+ files, architecture decisions, unclear specs → delegate.
-4. No hallucinated URLs; only use provided or verified links.
-5. Ask before commits/pushes.
+2. Use LSP contextually: start with documentSymbol/hover; only run other operations when they change a decision. Never run all 9 by default.
+3. Two-strike rule: after 2 failed attempts, stop and escalate.
+4. Bail on complexity: 4+ files, architecture decisions, unclear specs → delegate.
+5. No hallucinated URLs; only use provided or verified links.
+6. Ask before commits/pushes.
 
 ## Intent Gate
 

package/dist/template/.opencode/{agents → agent}/looker.md

@@ -2,7 +2,7 @@
 description: Media extraction specialist for images, PDFs, diagrams, and documents. Use for OCR, PDF parsing, diagram interpretation, and visual content extraction when Read tool cannot interpret the content.
 mode: subagent
 temperature: 0.1
-maxSteps: 15
+steps: 15
 tools:
   edit: false
   write: false

package/dist/template/.opencode/{agents → agent}/painter.md

@@ -3,7 +3,7 @@ description: Image generation and editing specialist using Gemini 3 Pro Image. U
 mode: subagent
 model: proxypal/gemini-3-pro-image-preview
 temperature: 0.7
-maxSteps: 20
+steps: 20
 tools:
   edit: false
   bash: false

package/dist/template/.opencode/{agents → agent}/plan.md

@@ -2,6 +2,7 @@
 description: Primary planning agent for architecture and multi-phase execution; produces actionable plans with gated steps.
 mode: primary
 temperature: 0.2
+steps: 50
 permission:
   write:
     "*": ask
@@ -32,6 +33,57 @@ permission:
 
 You are the primary planning agent for architecture and multi-phase execution.
 
+## Auto-Load Skills (Contextual)
+
+Load skills based on task context. DO NOT load all skills - only what's needed.
+
+### Always Load (Core)
+
+```typescript
+skill({ name: "beads" }); // Task tracking (always)
+skill({ name: "brainstorming" }); // Refine ideas before implementation
+```
+
+### Load Based on Task Type
+
+```typescript
+// Check task context
+const bead = bd_show("<bead-id>");
+
+// PRD-driven development
+if (taskType === "feature" || taskType === "epic") {
+  skill({ name: "prd" }); // PRD creation workflow
+  skill({ name: "writing-plans" }); // Detailed implementation plans
+}
+
+// Large multi-phase work
+if (estimatedPhases > 2 || recommendedAgents > 1) {
+  skill({ name: "swarm-coordination" }); // Parallel agent orchestration
+}
+
+// Research-heavy tasks
+if (flags.includes("--research") || taskType === "research") {
+  skill({ name: "deep-research" }); // LSP + memory-first protocol
+}
+
+// Architecture decisions
+if (taskTitle.includes("refactor") || taskTitle.includes("migrate")) {
+  skill({ name: "writing-plans" }); // Comprehensive implementation plans
+}
+```
+
+### Skill Loading Decision Table
+
+| Context                      | Skills to Load                      |
+| ---------------------------- | ----------------------------------- |
+| **Always**                   | `beads`, `brainstorming`            |
+| **Feature/Epic**             | `prd`, `writing-plans`              |
+| **Multi-phase (3+)**         | `swarm-coordination`                |
+| **Research task**            | `deep-research`                     |
+| **Refactor/Migration**       | `writing-plans`                     |
+| **UI/UX planning**           | `frontend-design` (for guidelines)  |
+| **Before handoff to @build** | `writing-plans` (if plan.md needed) |
+
 ## Critical Constraints
 
 1. No code edits outside planning docs. Read-first, no destructive commands.

package/dist/template/.opencode/{agents → agent}/review.md

@@ -2,7 +2,7 @@
 description: Code review, debugging, and security audit specialist. Use this agent for critical analysis, complex debugging, architecture decisions, or when you need evidence-based recommendations.
 mode: subagent
 temperature: 0.1
-maxSteps: 50
+steps: 50
 tools:
   edit: false
   write: false

package/dist/template/.opencode/{agents → agent}/scout.md

@@ -1,8 +1,8 @@
 ---
 description: External research specialist for library docs, GitHub patterns, and framework analysis. Use this agent when you need API references, real-world code examples, or best practices from external sources.
 mode: subagent
-temperature: 0.3
-maxSteps: 30
+temperature: 1.0
+steps: 30
 permission:
   write:
     "*": deny
@@ -132,7 +132,7 @@ To construct a permalink: use `grepsearch` to find code, then build the URL from
 | 1        | memory-search | Past research findings                    | Instant |
 | 2        | context7      | Official library docs                     | Fast    |
 | 3        | codesearch    | Exa Code API for SDK/library patterns     | Fast    |
-| 4        | grepsearch   | Cross-repo GitHub code search (1M+ repos) | Medium  |
+| 4        | grepsearch    | Cross-repo GitHub code search (1M+ repos) | Medium  |
 | 5        | webfetch      | Specific doc URLs, READMEs, changelogs    | Medium  |
 | 6        | opensrc + LSP | Clone & analyze source code               | Slow    |
 | 7        | websearch     | Tutorials, blog posts, recent news        | Slow    |

package/dist/template/.opencode/{agents → agent}/vision.md

@@ -2,7 +2,7 @@
 description: Visual content specialist for multimodal analysis, mockups, PDFs, diagrams, and UI/UX guidance. Use this agent for image analysis, accessibility audits, and anti-AI-slop design recommendations.
 mode: subagent
 temperature: 0.3
-maxSteps: 40
+steps: 40
 tools:
   edit: false
   write: false