opencodekit 0.14.1 → 0.14.3

package/dist/template/.opencode/command/implement.md

@@ -55,6 +55,38 @@ bd ready --json | grep -q "$ARGUMENTS"
 
 → Work on ready subtasks instead: `/implement <subtask-id>`
 
+**Or execute READY subtasks in parallel:**
+
+```typescript
+// Get all READY subtasks for this epic
+// bd list --parent $ARGUMENTS --status=open --json
+
+// Fire all READY subtasks in parallel with beads integration
+background_start({
+  agent: "build",
+  prompt: `Execute bd-subtask1: [Subtask description]
+
+    Context: Part of epic $ARGUMENTS
+
+    Requirements:
+    - Complete all work items
+    - Run verification commands
+    - Commit with bead ID in message`,
+  beadId: "bd-subtask1",
+  autoCloseBead: true,
+  title: "subtask-1"
+})  // Fire more for each READY subtask...
+
+// Collect results - beads auto-close on success
+background_output({ taskId: "bg_..." })  // → beadClosed: true
+
+// Check newly unblocked subtasks
+bd ready  // → Next wave now READY
+
+// Cleanup
+background_cancel({ all: true })
+```
+
 ## Git State Check
 
 ```bash
@@ -156,36 +188,45 @@ If memory search fails (Ollama not running), continue without it.
 
 ## Parallel Subagent Research (if --parallel or complex task)
 
-**Delegation Pattern: Fire and Continue**
+**Delegation Pattern: Fire in Background, Collect When Needed**
 
-For complex tasks, launch research subagents in parallel before diving into code:
+For complex tasks, launch research subagents in background before diving into code:
 
 ```typescript
 // Codebase patterns - find similar implementations
-Task({
-  subagent_type: "explore",
+background_start({
+  agent: "explore",
   prompt: `For implementing $ARGUMENTS, find:
     1. Similar patterns in this codebase (grep/ast-grep)
     2. Related test files and testing patterns
     3. Configuration or setup requirements
     Return: File paths, code patterns, test approach`,
-  description: "Explore patterns for implementation",
-});
+  title: "explore-patterns",
+}); // → bg_123_abc
 
 // External best practices - library docs
-Task({
-  subagent_type: "scout",
+background_start({
+  agent: "scout",
   prompt: `Research best practices for $ARGUMENTS:
     1. Official documentation for libraries involved
     2. Common implementation patterns (Context7, GitHub)
     3. Known pitfalls or gotchas
     Return: Code examples, API usage, warnings`,
-  description: "Scout external docs",
-});
+  title: "scout-docs",
+}); // → bg_456_def
 
 // Continue working immediately - don't wait for results
+// Collect later with: background_output({ taskId: "bg_123_abc" })
 ```
 
+**Background Task Tools:**
+| Tool | Purpose |
+| ---- | ------- |
+| `background_start` | Fire subagent in background, returns task_id |
+| `background_output` | Collect results from completed task |
+| `background_list` | See all tasks and their status |
+| `background_cancel` | Cancel running tasks (single or all) |
+
 **Subagent Rules:**
 | Agent | Use For | Can Do | Cannot Do |
 | -------- | ------------------------------ | ---------------- | ---------------- |

package/dist/template/.opencode/command/new-feature.md

@@ -54,27 +54,29 @@ Before creating anything, understand the landscape.
 ### Parallel Subagent Research
 
 ```typescript
-// Fire both in parallel - planner is read-only
-Task({
-  subagent_type: "explore",
+// Fire both in background - collect results when needed
+background_start({
+  agent: "explore",
   prompt: `Research codebase for "${$ARGUMENTS}":
     1. Find similar implementations or patterns
     2. Identify likely affected directories
     3. Find existing tests in related areas
     4. Check for related beads (open or closed)
     Return: File paths, patterns, test locations, related beads`,
-  description: "Explore codebase for feature",
-});
+  title: "explore-codebase",
+}); // → bg_123_abc
 
-Task({
-  subagent_type: "scout",
+background_start({
+  agent: "scout",
   prompt: `Research best practices for "${$ARGUMENTS}":
     1. Industry patterns for this type of feature
     2. Library/framework recommendations
     3. Common pitfalls to avoid
     Return: Recommendations, code examples, warnings`,
-  description: "Scout best practices",
-});
+  title: "scout-practices",
+}); // → bg_456_def
+
+// Continue working - collect later with background_output()
 ```
 
 ### Check Existing Work
@@ -451,7 +453,63 @@ npm test
 
 ---
 
-## Phase 8: Sync and Report
+## Phase 8: Parallel Task Execution (Optional)
+
+If multiple tasks are READY (no blockers), execute them in parallel:
+
+```bash
+# Check what's ready
+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
+
+// Cleanup
+background_cancel({ all: true })
+```
+
+**Parallel 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
+
+---
+
+## Phase 9: Sync and Report
 
 ```bash
 bd sync

package/dist/template/.opencode/command/plan.md

@@ -73,31 +73,35 @@ If memory search fails (Ollama not running), continue to subagent research.
 
 ## Phase 1: Parallel Subagent Research
 
-Gather context before designing. Fire both in parallel:
+Gather context before designing. Fire both in background:
 
 ```typescript
 // Codebase patterns
-Task({
-  subagent_type: "explore",
+background_start({
+  agent: "explore",
   prompt: `For planning $ARGUMENTS, research the codebase:
     1. Find similar implementations or patterns
     2. Identify affected files and their structure
     3. Find related tests and testing patterns
     4. Check for potential conflicts with in-progress work
     Return: File paths, code patterns, test approach, conflicts`,
-  description: "Explore codebase for planning",
-});
+  title: "explore-for-plan",
+}); // → bg_123_abc
 
 // External best practices
-Task({
-  subagent_type: "scout",
+background_start({
+  agent: "scout",
   prompt: `Research implementation approaches for $ARGUMENTS:
     1. Best practices from official documentation
     2. Common patterns in open source projects
     3. Pitfalls and anti-patterns to avoid
     Return: Recommendations, code examples, warnings`,
-  description: "Scout best practices for planning",
-});
+  title: "scout-for-plan",
+}); // → bg_456_def
+
+// Collect when ready
+background_output({ taskId: "bg_123_abc" });
+background_output({ taskId: "bg_456_def" });
 ```
 
 **Continue working while subagents research.**
@@ -413,7 +417,52 @@ If issues detected after deployment:
 
 ---
 
-## Phase 7: Sync and Report
+## Phase 7: Parallel Task Execution (if --parallel)
+
+After creating hierarchy, execute READY tasks in parallel:
+
+```bash
+# Check what's ready to start
+bd ready --json
+```
+
+```typescript
+// Fire all READY tasks in parallel with beads integration
+for (const task of readyTasks) {
+  background_start({
+    agent: "build",
+    prompt: `Execute ${task.id}: ${task.title}
+
+      Context: Part of plan for $ARGUMENTS
+      Spec: See .beads/artifacts/$ARGUMENTS/plan.md
+
+      Requirements:
+      - Complete work items for this task
+      - Run verification commands from plan
+      - Commit with bead ID in message
+
+      Return: Changes made, verification results`,
+    beadId: task.id,
+    autoCloseBead: true,
+    title: `exec-${task.id}`
+  })
+}
+
+// Collect results
+for (const taskId of backgroundTaskIds) {
+  background_output({ taskId })  // → beadClosed: true
+}
+
+// Check newly unblocked tasks
+bd ready  // → Next wave of tasks now READY
+
+// Cleanup
+background_cancel({ all: true })
+```
+
+---
+
+## Phase 8: Sync and Report
 
 ```bash
 bd sync

package/dist/template/.opencode/command/ralph-loop.md

@@ -0,0 +1,97 @@
+---
+description: Start Ralph Wiggum autonomous loop for task completion
+argument-hint: "<task> [--prd <file>] [--max <iterations>] [--afk]"
+agent: build
+---
+
+# Ralph Wiggum Loop
+
+You are starting a Ralph Wiggum autonomous loop. This pattern enables you to work autonomously on a task list until completion.
+
+## Task
+
+$ARGUMENTS
+
+## Setup
+
+1. **Start the loop** by calling the `ralph-start` tool:
+
+```typescript
+ralph -
+  start({
+    task: "$1",
+    prdFile: "$2" || null, // Optional: PRD.md, tasks.md, etc.
+    progressFile: "progress.txt",
+    maxIterations: 50,
+    mode: "hitl", // or "afk" for autonomous
+  });
+```
+
+2. **Create progress.txt** if it doesn't exist:
+
+```markdown
+# Progress Log
+
+## Session Started: [date]
+
+### Completed Tasks
+
+(none yet)
+
+### Notes for Next Iteration
+
+- Starting fresh
+```
+
+## Loop Behavior
+
+After each iteration, the loop will automatically:
+
+1. Check if you output `<promise>COMPLETE</promise>`
+2. If yes → Loop ends, success!
+3. If no → Send continuation prompt for next iteration
+4. Repeat until completion or max iterations
+
+## Your Instructions
+
+For each iteration:
+
+1. **Review** the PRD/task list and progress file
+2. **Choose** the highest-priority incomplete task (YOU decide, not first in list)
+3. **Implement** ONE feature only (small steps prevent context rot)
+4. **Validate** with feedback loops:
+   - `npm run typecheck` (must pass)
+   - `npm run test` (must pass)
+   - `npm run lint` (must pass)
+5. **Commit** if all pass
+6. **Update** progress.txt with:
+   - Task completed
+   - Key decisions made
+   - Files changed
+   - Notes for next iteration
+
+## Exit Conditions
+
+Output `<promise>COMPLETE</promise>` when:
+
+- ALL tasks in the PRD are complete
+- ALL feedback loops pass
+- Code is committed
+
+The loop will also stop if:
+
+- Max iterations reached
+- You call `ralph-stop` tool
+- An error occurs
+
+## Best Practices
+
+- **Small steps**: One feature per iteration
+- **Quality over speed**: Never skip tests
+- **Explicit scope**: Vague tasks loop forever
+- **Track progress**: Update progress.txt every iteration
+- **Prioritize risk**: Hard tasks first, easy wins last
+
+## Start Now
+
+Call `ralph-start` with the task description to begin the loop.

package/dist/template/.opencode/command/start.md

@@ -169,33 +169,36 @@ cd .worktrees/$ARGUMENTS
 For complex tasks, gather context before diving in:
 
 ```typescript
-// Fire subagents in parallel - don't wait for results
-Task({
-  subagent_type: "explore",
+// Fire subagents in background - don't wait for results
+background_start({
+  agent: "explore",
   prompt: `Research codebase patterns for $ARGUMENTS:
     - Find similar implementations
     - Identify affected files
     - Note testing patterns used
     Return: File list, patterns found, testing approach`,
-  description: "Explore codebase for task",
-});
+  title: "explore-codebase",
+}); // → bg_123_abc
 
-Task({
-  subagent_type: "scout",
+background_start({
+  agent: "scout",
   prompt: `Research external docs for $ARGUMENTS:
     - API documentation for libraries involved
     - Best practices for the approach
     - Common pitfalls to avoid
     Return: Key findings, code examples, warnings`,
-  description: "Scout external resources",
-});
+  title: "scout-docs",
+}); // → bg_456_def
+
+// Collect later with: background_output({ taskId: "bg_123_abc" })
 ```
 
 **Subagent delegation rules:**
 
 - Subagents are **read-only** - they don't modify beads state
-- Results return to you (build agent) for integration
+- Results collected via `background_output({ taskId })` when ready
 - Use for research, not for implementation
+- Cleanup at session end: `background_cancel({ all: true })`
 
 ## Existing Artifacts
 

package/dist/template/.opencode/memory/{project/beads-workflow.md → beads-workflow.md}

@@ -426,6 +426,59 @@ git worktree remove .worktrees/bd-epic  # Cleanup worktree
 /finish bd-epic
 ```
 
+### Pattern 8: Ralph Wiggum Autonomous Loop
+
+For tasks that can run autonomously until completion. The agent loops until it outputs `<promise>COMPLETE</promise>` or hits max iterations.
+
+```
+/ralph-loop "Migrate all Jest tests to Vitest"
+# Or with PRD file:
+/ralph-loop "Complete PRD tasks" --prd PRD.md --max 50
+
+# Agent automatically:
+# 1. Picks highest-priority incomplete task
+# 2. Implements ONE feature
+# 3. Runs feedback loops (typecheck, test, lint)
+# 4. Commits if all pass
+# 5. Updates progress.txt
+# 6. Loops until <promise>COMPLETE</promise> or max iterations
+```
+
+**When to use Ralph:**
+
+| Scenario                  | Use Ralph? | Why                                  |
+| ------------------------- | ---------- | ------------------------------------ |
+| Test coverage improvement | ✅ Yes     | Clear success criteria, safe to loop |
+| Linting fixes             | ✅ Yes     | Deterministic, feedback-driven       |
+| Migration (Jest→Vitest)   | ✅ Yes     | Repetitive, well-defined end state   |
+| Feature implementation    | ⚠️ HITL    | Need oversight for design decisions  |
+| Architectural changes     | ❌ No      | Too risky for autonomous work        |
+| Vague "improve X" tasks   | ❌ No      | No clear completion criteria         |
+
+**Ralph + Beads Integration:**
+
+```bash
+# Create PRD from beads
+bd list --status=open --json > PRD.json
+
+# Start Ralph loop
+/ralph-loop "Complete all open tasks" --prd PRD.json
+
+# Ralph will work through tasks, you can:
+ralph-status   # Check progress
+ralph-stop     # Stop gracefully
+
+# After completion, sync beads
+bd sync
+```
+
+**Key constraints:**
+
+- ONE feature per iteration (prevents context rot)
+- MUST pass all feedback loops before commit
+- Small steps > large changes
+- Always cap iterations (never infinite loops)
+
 ## Agent Boundaries
 
 ### Leader Agents (Touch Beads)

package/dist/template/.opencode/memory/project/conventions.md

@@ -111,10 +111,60 @@ This transforms passive detection into active agent behavior (e.g., Memory plugi
 
 ## Agent Behavior Rules
 
-### Active LSP Nudge
+### MANDATORY LSP-First Workflow
 
-When a tool output displays `[LSP NAVIGATION AVAILABLE]`, it means relevant code files were found.
-**Rule**: You MUST immediately execute the suggested `lsp_lsp_*` tool calls to retrieve code context without waiting for user instruction. This ensures you always have the latest code context for your implementation.
+**HARD RULE**: Before editing ANY code file, you MUST use LSP tools first.
+
+```
+grep/read → LSP → understand → THEN edit
+```
+
+**After EVERY grep/glob/read that returns code files:**
+
+1. **IMMEDIATELY** call `lsp` with `documentSymbol` to understand file structure
+2. **IMMEDIATELY** call `lsp` with `findReferences` on symbols you'll modify
+3. **IMMEDIATELY** call `lsp` with `goToDefinition` to trace dependencies
+4. **USE** additional LSP operations as needed:
+   - `hover` - Get type info and documentation
+   - `goToImplementation` - Find implementations of interface/abstract
+   - `workspaceSymbol` - Search symbols across entire workspace
+   - `prepareCallHierarchy` - Get call hierarchy item at position
+   - `incomingCalls` - Find what calls this function
+   - `outgoingCalls` - Find what this function calls
+5. **ONLY THEN** proceed with edits
+
+**Example - The Correct Flow:**
+
+```
+User: "Fix the auth bug in src/auth.ts"
+
+# Step 1: Read the file
+read({ filePath: "src/auth.ts" })
+
+# Step 2: MANDATORY LSP (before ANY edit) - use ALL relevant operations
+lsp({ operation: "documentSymbol", filePath: "src/auth.ts", line: 1, character: 1 })
+lsp({ operation: "findReferences", filePath: "src/auth.ts", line: 42, character: 10 })
+lsp({ operation: "goToDefinition", filePath: "src/auth.ts", line: 42, character: 10 })
+lsp({ operation: "hover", filePath: "src/auth.ts", line: 42, character: 10 })
+lsp({ operation: "incomingCalls", filePath: "src/auth.ts", line: 42, character: 10 })
+lsp({ operation: "outgoingCalls", filePath: "src/auth.ts", line: 42, character: 10 })
+
+# Step 3: NOW you can edit
+edit({ filePath: "src/auth.ts", ... })
+```
+
+**Why This Matters:**
+
+- LSP gives you semantic understanding (types, references, call hierarchy)
+- grep/read only gives you text (no understanding of relationships)
+- Editing without LSP context leads to broken refactors
+
+**Violations:**
+
+- ❌ `read → edit` (WRONG - no LSP)
+- ❌ `grep → edit` (WRONG - no LSP)
+- ✅ `read → LSP → edit` (CORRECT)
+- ✅ `grep → read → LSP → edit` (CORRECT)
 
 ## Patterns to Avoid
 

package/dist/template/.opencode/opencode.json

@@ -7,11 +7,15 @@
 		},
 		"compaction": {
 			"description": "Session summarizer for context continuity across compactions",
-			"model": "opencode/big-pickle"
+			"model": "proxypal/gemini-2.5-flash"
 		},
 		"explore": {
 			"description": "Fast codebase search specialist",
-			"model": "opencode/grok-code"
+			"model": "proxypal/gemini-3-flash-preview"
+		},
+		"looker": {
+			"description": "Media extraction specialist for images, PDFs, diagrams",
+			"model": "proxypal/gemini-3-flash-preview"
 		},
 		"general": {
 			"disable": true
@@ -506,7 +510,7 @@
 		}
 	},
 	"share": "manual",
-	"small_model": "opencode/gpt-5-nano",
+	"small_model": "proxypal/gemini-2.5-flash-lite",
 	"tui": {
 		"diff_style": "auto",
 		"scroll_acceleration": {

package/dist/template/.opencode/package.json

@@ -12,7 +12,8 @@
 	"license": "ISC",
 	"dependencies": {
 		"@lancedb/lancedb": "^0.23.0",
-		"@opencode-ai/plugin": "1.1.8",
+		"@opencode-ai/plugin": "1.1.11",
+		"@opencode-ai/sdk": "^1.1.8",
 		"openai": "^6.15.0"
 	},
 	"devDependencies": {