opencodekit 0.14.1 → 0.14.2

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

@@ -13,6 +13,10 @@
 			"description": "Fast codebase search specialist",
 			"model": "opencode/grok-code"
 		},
+		"looker": {
+			"description": "Media extraction specialist for images, PDFs, diagrams",
+			"model": "proxypal/gemini-3-flash-preview"
+		},
 		"general": {
 			"disable": true
 		},

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

@@ -13,6 +13,7 @@
 	"dependencies": {
 		"@lancedb/lancedb": "^0.23.0",
 		"@opencode-ai/plugin": "1.1.8",
+		"@opencode-ai/sdk": "^1.1.8",
 		"openai": "^6.15.0"
 	},
 	"devDependencies": {

package/dist/template/.opencode/plugin/lsp.ts

@@ -0,0 +1,299 @@
+/**
+ * LSP Plugin - Active LSP Tool Enforcement
+ *
+ * Forces agents to actively use LSP tools when code files are detected.
+ * This is NOT a suggestion - agents MUST execute LSP operations immediately.
+ *
+ * Mechanism:
+ * 1. Hooks into grep/glob/read tool outputs (tool.execute.after)
+ * 2. Hooks into user messages mentioning code files (chat.message)
+ * 3. Injects MANDATORY LSP execution commands
+ * 4. Uses strong language to override agent tendencies to skip
+ *
+ * Based on oh-my-opencode's LSP forcing pattern.
+ */
+
+import type { Plugin } from "@opencode-ai/plugin";
+
+// File extensions that support LSP
+const LSP_SUPPORTED_EXTENSIONS = new Set([
+	".ts",
+	".tsx",
+	".js",
+	".jsx",
+	".py",
+	".go",
+	".rs",
+	".java",
+	".c",
+	".cpp",
+	".h",
+	".hpp",
+	".cs",
+	".rb",
+	".php",
+	".swift",
+	".kt",
+	".scala",
+	".lua",
+	".zig",
+	".vue",
+	".svelte",
+]);
+
+// Regex to extract file:line patterns from tool output
+const FILE_LINE_PATTERNS = [
+	// Standard grep output: path/file.ts:42: content
+	/^([^\s:]+\.(ts|tsx|js|jsx|py|go|rs|java|c|cpp|h|hpp|cs|rb|php|swift|kt|scala|lua|zig|vue|svelte)):(\d+):/gm,
+	// Just path with line: path/file.ts:42
+	/([^\s:]+\.(ts|tsx|js|jsx|py|go|rs|java|c|cpp|h|hpp|cs|rb|php|swift|kt|scala|lua|zig|vue|svelte)):(\d+)/g,
+	// Glob/list output with just paths
+	/^([^\s:]+\.(ts|tsx|js|jsx|py|go|rs|java|c|cpp|h|hpp|cs|rb|php|swift|kt|scala|lua|zig|vue|svelte))$/gm,
+];
+
+// Patterns that indicate user is asking about code
+const CODE_INTENT_PATTERNS = [
+	/\b(edit|modify|change|update|fix|refactor|add|remove|delete)\b.*\.(ts|tsx|js|jsx|py|go|rs)/i,
+	/\b(function|class|method|variable|type|interface)\s+\w+/i,
+	/\b(implement|create|build)\b.*\b(feature|component|module)/i,
+	/@[^\s]+\.(ts|tsx|js|jsx|py|go|rs)/i, // @file.ts mentions
+	/\b(src|lib|app|components?)\/[^\s]+\.(ts|tsx|js|jsx)/i, // Path patterns
+];
+
+interface FileMatch {
+	filePath: string;
+	line?: number;
+	character?: number;
+}
+
+function extractFileMatches(output: string): FileMatch[] {
+	const matches: FileMatch[] = [];
+	const seen = new Set<string>();
+
+	for (const pattern of FILE_LINE_PATTERNS) {
+		pattern.lastIndex = 0;
+
+		let match = pattern.exec(output);
+		while (match !== null) {
+			const filePath = match[1];
+			const line = match[3] ? Number.parseInt(match[3], 10) : undefined;
+
+			const key = `${filePath}:${line || 0}`;
+			if (!seen.has(key)) {
+				seen.add(key);
+				matches.push({
+					filePath,
+					line,
+					character: 1,
+				});
+			}
+
+			match = pattern.exec(output);
+		}
+	}
+
+	return matches.slice(0, 5);
+}
+
+function extractFilesFromUserMessage(text: string): string[] {
+	const files: string[] = [];
+	const seen = new Set<string>();
+
+	// Match @file.ts patterns
+	const atMentions = text.match(/@([^\s]+\.(ts|tsx|js|jsx|py|go|rs))/gi) || [];
+	for (const mention of atMentions) {
+		const file = mention.replace("@", "");
+		if (!seen.has(file)) {
+			seen.add(file);
+			files.push(file);
+		}
+	}
+
+	// Match path patterns like src/foo.ts
+	const pathPatterns =
+		text.match(
+			/\b(src|lib|app|components?)\/[^\s]+\.(ts|tsx|js|jsx|py|go|rs)/gi,
+		) || [];
+	for (const path of pathPatterns) {
+		if (!seen.has(path)) {
+			seen.add(path);
+			files.push(path);
+		}
+	}
+
+	return files.slice(0, 3);
+}
+
+function generateLspCommands(matches: FileMatch[]): string {
+	if (matches.length === 0) return "";
+
+	const commands: string[] = [];
+
+	for (const match of matches) {
+		if (match.line) {
+			// With line number - get definition and references
+			commands.push(
+				`lsp({ operation: "goToDefinition", filePath: "${match.filePath}", line: ${match.line}, character: ${match.character || 1} })`,
+			);
+			commands.push(
+				`lsp({ operation: "findReferences", filePath: "${match.filePath}", line: ${match.line}, character: ${match.character || 1} })`,
+			);
+			commands.push(
+				`lsp({ operation: "hover", filePath: "${match.filePath}", line: ${match.line}, character: ${match.character || 1} })`,
+			);
+		} else {
+			// Just file path - get document symbols
+			commands.push(
+				`lsp({ operation: "documentSymbol", filePath: "${match.filePath}", line: 1, character: 1 })`,
+			);
+		}
+	}
+
+	const uniqueCommands = [...new Set(commands)].slice(0, 6);
+
+	// AGGRESSIVE enforcement format - designed to force action
+	return `
+
+╔══════════════════════════════════════════════════════════════════════════════╗
+║  ⚡ LSP EXECUTION REQUIRED - DO NOT SKIP                                      ║
+╠══════════════════════════════════════════════════════════════════════════════╣
+║                                                                              ║
+║  Code files detected. You MUST execute these LSP operations NOW.             ║
+║  DO NOT proceed with edits until LSP context is retrieved.                   ║
+║                                                                              ║
+║  EXECUTE IMMEDIATELY (copy-paste ready):                                     ║
+║                                                                              ║
+${uniqueCommands.map((cmd) => `║  → ${cmd}`).join("\n")}
+║                                                                              ║
+╠══════════════════════════════════════════════════════════════════════════════╣
+║  WHY THIS IS MANDATORY:                                                      ║
+║  • grep/read show text, LSP shows semantic meaning                           ║
+║  • LSP provides accurate type info, definitions, call hierarchies            ║
+║  • Editing without LSP context leads to broken code                          ║
+║  • This is a HARD RULE, not a suggestion                                     ║
+╠══════════════════════════════════════════════════════════════════════════════╣
+║  WORKFLOW: grep/read → LSP → understand → THEN edit                          ║
+╚══════════════════════════════════════════════════════════════════════════════╝
+`;
+}
+
+function generateUserMessageNudge(files: string[]): string {
+	const lspCommands = files.map(
+		(f) =>
+			`lsp({ operation: "documentSymbol", filePath: "${f}", line: 1, character: 1 })`,
+	);
+
+	return `
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⚡ [LSP CONTEXT REQUIRED]
+
+Before making ANY changes to these files, you MUST first retrieve LSP context:
+
+${lspCommands.map((cmd) => `→ ${cmd}`).join("\n")}
+
+This is a HARD RULE. Do NOT guess about code structure.
+Workflow: READ file → LSP documentSymbol/hover → UNDERSTAND → THEN edit
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+`;
+}
+
+function shouldInjectNudge(toolName: string): boolean {
+	return ["grep", "glob", "read", "batch"].includes(toolName);
+}
+
+function hasCodeFiles(output: string): boolean {
+	for (const ext of LSP_SUPPORTED_EXTENSIONS) {
+		if (output.includes(ext)) return true;
+	}
+	return false;
+}
+
+function userMessageMentionsCode(text: string): boolean {
+	return CODE_INTENT_PATTERNS.some((pattern) => pattern.test(text));
+}
+
+export const Lsp: Plugin = async () => {
+	return {
+		name: "lsp",
+		version: "1.1.0",
+
+		/**
+		 * Hook: chat.message
+		 * Injects LSP reminder when user mentions code files in their message
+		 * This catches intent BEFORE tools are executed
+		 */
+		"chat.message": async (_input, output) => {
+			const { message, parts } = output;
+
+			// Only process user messages
+			if (message.role !== "user") return;
+
+			// Extract text from all parts
+			const fullText = parts
+				.filter((p) => p.type === "text")
+				.map((p) => ("text" in p ? p.text : ""))
+				.join(" ");
+
+			// Check if user is mentioning code files or asking about code
+			if (!userMessageMentionsCode(fullText)) return;
+
+			// Extract specific files mentioned
+			const files = extractFilesFromUserMessage(fullText);
+
+			// If files found, inject specific LSP commands
+			// If no specific files but code intent detected, inject general reminder
+			const nudgeText =
+				files.length > 0
+					? generateUserMessageNudge(files)
+					: `
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⚡ [LSP FIRST - HARD RULE]
+
+Code modification detected. Before editing:
+1. Use grep/glob to find relevant files
+2. Use READ to view the file
+3. Use LSP (documentSymbol, goToDefinition, findReferences) to understand structure
+4. ONLY THEN make edits
+
+Do NOT skip LSP. Editing without semantic context leads to broken code.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+`;
+
+			// Inject synthetic message part - cast to any for synthetic property
+			(parts as unknown[]).push({
+				type: "text",
+				text: nudgeText,
+				synthetic: true,
+			});
+		},
+
+		/**
+		 * Hook: tool.execute.after
+		 * Injects LSP commands after grep/glob/read returns code file results
+		 * This catches AFTER tools show code files
+		 */
+		"tool.execute.after": async (input, output) => {
+			const { tool: toolName } = input;
+			const result = output.output;
+
+			// Skip if not a search/read tool
+			if (!shouldInjectNudge(toolName)) return;
+
+			// Skip if no code files in output
+			if (typeof result !== "string" || !hasCodeFiles(result)) return;
+
+			// Extract file matches
+			const matches = extractFileMatches(result);
+			if (matches.length === 0) return;
+
+			// Generate LSP commands (not suggestions - COMMANDS)
+			const lspBlock = generateLspCommands(matches);
+			if (!lspBlock) return;
+
+			// Append mandatory LSP block to tool output
+			output.output = `${result}${lspBlock}`;
+		},
+	};
+};
+
+export default Lsp;