opencodekit 0.14.3 → 0.14.5

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

@@ -61,9 +61,11 @@ bd ready --json | grep -q "$ARGUMENTS"
 // 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",
+// Fire all READY subtasks in parallel using Task tool
+// Multiple Task calls in one message run simultaneously
+Task({
+  subagent_type: "rush",
+  description: "Execute subtask 1",
   prompt: `Execute bd-subtask1: [Subtask description]
 
     Context: Part of epic $ARGUMENTS
@@ -71,20 +73,20 @@ background_start({
     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...
+    - Commit with bead ID in message
+    - Close the bead when done: bd close bd-subtask1 --reason "Completed: ..."`,
+});
 
-// Collect results - beads auto-close on success
-background_output({ taskId: "bg_..." })  // → beadClosed: true
+Task({
+  subagent_type: "rush",
+  description: "Execute subtask 2",
+  prompt: `Execute bd-subtask2: [Subtask description]
+    ...same pattern...`,
+});
 
+// Results available immediately after all complete
 // Check newly unblocked subtasks
 bd ready  // → Next wave now READY
-
-// Cleanup
-background_cancel({ all: true })
 ```
 
 ## Git State Check
@@ -188,44 +190,41 @@ If memory search fails (Ollama not running), continue without it.
 
 ## Parallel Subagent Research (if --parallel or complex task)
 
-**Delegation Pattern: Fire in Background, Collect When Needed**
+**Delegation Pattern: Parallel Task Calls**
 
-For complex tasks, launch research subagents in background before diving into code:
+For complex tasks, launch research subagents in parallel before diving into code.
+Multiple Task calls in a single message run simultaneously:
 
 ```typescript
 // Codebase patterns - find similar implementations
-background_start({
-  agent: "explore",
+Task({
+  subagent_type: "explore",
+  description: "Find codebase patterns",
   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`,
-  title: "explore-patterns",
-}); // → bg_123_abc
+});
 
 // External best practices - library docs
-background_start({
-  agent: "scout",
+Task({
+  subagent_type: "scout",
+  description: "Research best practices",
   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`,
-  title: "scout-docs",
-}); // → bg_456_def
+});
 
-// Continue working immediately - don't wait for results
-// Collect later with: background_output({ taskId: "bg_123_abc" })
+// Both run in parallel, results available immediately
 ```
 
-**Background Task Tools:**
+**Subagent 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) |
+| `Task` | Delegate to subagent, runs in parallel when multiple calls in one message |
 
 **Subagent Rules:**
 | Agent | Use For | Can Do | Cannot Do |

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

@@ -54,29 +54,29 @@ Before creating anything, understand the landscape.
 ### Parallel Subagent Research
 
 ```typescript
-// Fire both in background - collect results when needed
-background_start({
-  agent: "explore",
+// Run both in parallel - multiple Task calls in one message
+Task({
+  subagent_type: "explore",
+  description: "Explore codebase for feature",
   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`,
-  title: "explore-codebase",
-}); // → bg_123_abc
+});
 
-background_start({
-  agent: "scout",
+Task({
+  subagent_type: "scout",
+  description: "Research best practices",
   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`,
-  title: "scout-practices",
-}); // → bg_456_def
+});
 
-// Continue working - collect later with background_output()
+// Both run in parallel, results available immediately
 ```
 
 ### Check Existing Work

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

@@ -73,38 +73,36 @@ If memory search fails (Ollama not running), continue to subagent research.
 
 ## Phase 1: Parallel Subagent Research
 
-Gather context before designing. Fire both in background:
+Gather context before designing. Run both in parallel:
 
 ```typescript
-// Codebase patterns
-background_start({
-  agent: "explore",
+// Codebase patterns - run in parallel with scout
+Task({
+  subagent_type: "explore",
+  description: "Explore codebase for planning",
   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`,
-  title: "explore-for-plan",
-}); // → bg_123_abc
+});
 
-// External best practices
-background_start({
-  agent: "scout",
+// External best practices - run in parallel with explore
+Task({
+  subagent_type: "scout",
+  description: "Research implementation approaches",
   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`,
-  title: "scout-for-plan",
-}); // → bg_456_def
+});
 
-// Collect when ready
-background_output({ taskId: "bg_123_abc" });
-background_output({ taskId: "bg_456_def" });
+// Both run in parallel, results available immediately
 ```
 
-**Continue working while subagents research.**
+**Integrate findings into your plan.**
 
 ---
 

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

@@ -0,0 +1,41 @@
+---
+description: Start Ralph Wiggum autonomous loop for task completion
+argument-hint: "<task> [--prd <file>]"
+agent: build
+---
+
+# Ralph Wiggum Loop
+
+First, load the ralph skill for complete instructions:
+
+```typescript
+skill({ name: "ralph" });
+```
+
+## Task
+
+$ARGUMENTS
+
+## Quick Start
+
+1. **Load the skill** (above) to get full workflow instructions
+2. **Detect environment**: Check lock files to determine package manager
+3. **Create progress.txt**: Track completed tasks and notes
+4. **Start iterating**: Follow the loop pattern from the skill
+
+## The Loop (Summary)
+
+```
+Read PRD → Pick task → Implement ONE feature → Validate → Commit → Update progress → Repeat
+```
+
+Exit when ALL tasks complete by outputting:
+
+```
+<promise>COMPLETE</promise>
+```
+
+## See Also
+
+- Full instructions: `skill({ name: "ralph" })`
+- Skill location: `.opencode/skill/ralph/SKILL.md`

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

@@ -169,36 +169,35 @@ cd .worktrees/$ARGUMENTS
 For complex tasks, gather context before diving in:
 
 ```typescript
-// Fire subagents in background - don't wait for results
-background_start({
-  agent: "explore",
+// Run subagents in parallel - multiple Task calls in one message
+Task({
+  subagent_type: "explore",
+  description: "Explore codebase patterns",
   prompt: `Research codebase patterns for $ARGUMENTS:
     - Find similar implementations
     - Identify affected files
     - Note testing patterns used
     Return: File list, patterns found, testing approach`,
-  title: "explore-codebase",
-}); // → bg_123_abc
+});
 
-background_start({
-  agent: "scout",
+Task({
+  subagent_type: "scout",
+  description: "Research external docs",
   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`,
-  title: "scout-docs",
-}); // → bg_456_def
+});
 
-// Collect later with: background_output({ taskId: "bg_123_abc" })
+// Both run in parallel, results available immediately
 ```
 
 **Subagent delegation rules:**
 
 - Subagents are **read-only** - they don't modify beads state
-- Results collected via `background_output({ taskId })` when ready
+- Results returned immediately when all complete
 - Use for research, not for implementation
-- Cleanup at session end: `background_cancel({ all: true })`
 
 ## Existing Artifacts
 

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

@@ -77,7 +77,11 @@
 			"extensions": [".html", ".css", ".scss", ".sass", ".md", ".yaml", ".yml"]
 		}
 	},
-	"instructions": [".opencode/memory/user.md", ".opencode/memory/project/*.md"],
+	"instructions": [
+		".opencode/memory/user.md",
+		".opencode/memory/project/*.md",
+		".opencode/memory/observations/*.md"
+	],
 	"keybinds": {
 		"command_list": ";",
 		"leader": "`",

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

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

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

@@ -5,7 +5,8 @@
  * 1. Load session-context.md (CONTINUITY.md pattern)
  * 2. Load project memory files
  * 3. Inject beads in-progress state
- * 4. Append workflow-specific compaction rules
+ * 4. Load most recent handoff file for session resumption
+ * 5. Append workflow-specific compaction rules
  *
  * Session context format (agent-maintained via memory-update):
  * - Goal: What we're trying to achieve + success criteria
@@ -20,6 +21,7 @@ import type { Plugin } from "@opencode-ai/plugin";
 
 export const CompactionPlugin: Plugin = async ({ $, directory }) => {
 	const MEMORY_DIR = `${directory}/.opencode/memory`;
+	const HANDOFF_DIR = `${MEMORY_DIR}/handoffs`;
 
 	return {
 		"experimental.session.compacting": async (input, output) => {
@@ -69,8 +71,29 @@ export const CompactionPlugin: Plugin = async ({ $, directory }) => {
 				// Beads not available, skip
 			}
 
+			// 4. Load most recent handoff file (session continuity)
+			let handoffContext = "";
+			try {
+				const result =
+					await $`ls -t ${HANDOFF_DIR}/*.md 2>/dev/null | head -1`.quiet();
+				if (result.stdout) {
+					const handoffPath = result.stdout.toString().trim();
+					if (handoffPath) {
+						const handoffContent = await $`cat ${handoffPath}`.text();
+						handoffContext = `\n## Previous Session Handoff\n\n${handoffContent}\n\n**IMPORTANT**: Resume work from where previous session left off.`;
+					}
+				}
+			} catch {
+				// No handoff files, skip
+			}
+
 			// Inject all context - session context FIRST (most important)
-			const allContext = [sessionContext, beadsContext, memoryContext]
+			const allContext = [
+				sessionContext,
+				beadsContext,
+				handoffContext,
+				memoryContext,
+			]
 				.filter(Boolean)
 				.join("\n");
 

package/dist/template/.opencode/skill/ralph/SKILL.md

@@ -0,0 +1,300 @@
+---
+name: ralph
+description: Use when running autonomous agent loops for extended task completion without human intervention - handles PRD-driven development, migration tasks, or batch operations
+license: MIT
+compatibility: opencode
+metadata:
+  source: https://ghuntley.com/ralph/
+  category: automation
+  updated: 2026-01-10
+---
+
+# Ralph Wiggum - Autonomous Agent Loop
+
+A workflow pattern for extended autonomous work sessions where the agent iterates through tasks until completion.
+
+## When to Use
+
+- **PRD-driven development**: Work through a product requirements document task by task
+- **Migration tasks**: "Migrate all Jest tests to Vitest" - agent works until done
+- **Batch operations**: Process multiple files/components with the same pattern
+- **Away-from-keyboard work**: Let the agent work autonomously while you're away
+
+## When NOT to Use
+
+- Simple single-step tasks (just do them directly)
+- Tasks requiring frequent human decisions
+- Exploratory work where the goal isn't clear
+- Critical production changes (requires human oversight)
+
+## Quick Start
+
+Invoke the workflow with:
+
+```
+/ralph Migrate all Jest tests to Vitest --prd PRD.md
+```
+
+Or manually follow the loop pattern below.
+
+## The Loop Pattern
+
+```
+┌─────────────────────────────────────────────────┐
+│  1. Read PRD/task list + progress.txt           │
+│  2. Pick highest-priority incomplete task       │
+│  3. Implement ONE feature only                  │
+│  4. Run feedback: test → typecheck → lint       │
+│  5. If pass → commit + update progress.txt      │
+│  6. If all done → output <promise>COMPLETE      │
+│  7. Otherwise → repeat from step 1              │
+└─────────────────────────────────────────────────┘
+```
+
+## Using LSP Tools (Experimental)
+
+OpenCode provides LSP tools for code intelligence.
+
+### Available Operations
+
+```typescript
+// Understand file structure before editing
+lsp({
+  operation: "documentSymbol",
+  filePath: "src/auth.ts",
+  line: 1,
+  character: 1,
+});
+
+// Find where a symbol is defined
+lsp({
+  operation: "goToDefinition",
+  filePath: "src/auth.ts",
+  line: 42,
+  character: 10,
+});
+
+// Find all usages of a symbol (impact analysis)
+lsp({
+  operation: "findReferences",
+  filePath: "src/auth.ts",
+  line: 42,
+  character: 10,
+});
+
+// Get type info and documentation
+lsp({ operation: "hover", filePath: "src/auth.ts", line: 42, character: 10 });
+
+// Find implementations of interface/abstract
+lsp({
+  operation: "goToImplementation",
+  filePath: "src/types.ts",
+  line: 15,
+  character: 10,
+});
+
+// Search symbols across entire workspace
+lsp({
+  operation: "workspaceSymbol",
+  filePath: "src/index.ts",
+  line: 1,
+  character: 1,
+});
+
+// Call hierarchy analysis
+lsp({
+  operation: "prepareCallHierarchy",
+  filePath: "src/api.ts",
+  line: 20,
+  character: 5,
+});
+lsp({
+  operation: "incomingCalls",
+  filePath: "src/api.ts",
+  line: 20,
+  character: 5,
+});
+lsp({
+  operation: "outgoingCalls",
+  filePath: "src/api.ts",
+  line: 20,
+  character: 5,
+});
+```
+
+### LSP-First Workflow
+
+Before editing ANY file in the loop:
+
+```
+1. Read the file
+2. Use documentSymbol to understand structure
+3. Use findReferences to check impact
+4. Use hover for type info
+5. THEN make edits
+```
+
+This prevents breaking changes and ensures you understand the code before modifying it.
+
+## Smart Language Detection
+
+OpenCode auto-detects languages via LSP based on file extensions. Use this to determine the project type:
+
+### Primary Detection (File Extensions)
+
+| Language   | Extensions                    | LSP Server    |
+| ---------- | ----------------------------- | ------------- |
+| TypeScript | `.ts`, `.tsx`, `.mts`, `.cts` | typescript    |
+| JavaScript | `.js`, `.jsx`, `.mjs`, `.cjs` | typescript    |
+| Python     | `.py`, `.pyi`                 | pyright       |
+| Rust       | `.rs`                         | rust-analyzer |
+| Go         | `.go`                         | gopls         |
+| C/C++      | `.c`, `.cpp`, `.h`, `.hpp`    | clangd        |
+| Java       | `.java`                       | jdtls         |
+| C#         | `.cs`                         | csharp        |
+| Ruby       | `.rb`, `.rake`                | ruby-lsp      |
+| PHP        | `.php`                        | intelephense  |
+| Swift      | `.swift`                      | sourcekit-lsp |
+| Kotlin     | `.kt`, `.kts`                 | kotlin-ls     |
+| Elixir     | `.ex`, `.exs`                 | elixir-ls     |
+| Dart       | `.dart`                       | dart          |
+| Zig        | `.zig`                        | zls           |
+| Gleam      | `.gleam`                      | gleam         |
+| Lua        | `.lua`                        | lua-ls        |
+| Clojure    | `.clj`, `.cljs`, `.cljc`      | clojure-lsp   |
+| OCaml      | `.ml`, `.mli`                 | ocaml-lsp     |
+| Svelte     | `.svelte`                     | svelte        |
+| Vue        | `.vue`                        | vue           |
+| Astro      | `.astro`                      | astro         |
+
+### Secondary Detection (Lock Files → Package Manager)
+
+| Lock File           | Package Manager | Runtime |
+| ------------------- | --------------- | ------- |
+| `bun.lockb`         | Bun             | Bun     |
+| `yarn.lock`         | Yarn            | Node    |
+| `pnpm-lock.yaml`    | pnpm            | Node    |
+| `package-lock.json` | npm             | Node    |
+| `deno.json`         | Deno            | Deno    |
+| `Cargo.toml`        | Cargo           | Rust    |
+| `go.mod`            | Go Modules      | Go      |
+| `pyproject.toml`    | Poetry/pip      | Python  |
+| `Gemfile.lock`      | Bundler         | Ruby    |
+| `composer.lock`     | Composer        | PHP     |
+| `Package.swift`     | SwiftPM         | Swift   |
+| `mix.lock`          | Mix             | Elixir  |
+| `pubspec.lock`      | Pub             | Dart    |
+
+### Validation Commands by Language
+
+```bash
+# TypeScript/JavaScript (Bun)
+bun test && bun run typecheck && bun run lint
+
+# TypeScript/JavaScript (npm)
+npm test && npm run typecheck && npm run lint
+
+# TypeScript/JavaScript (Deno)
+deno test && deno check . && deno lint
+
+# Python
+pytest && ruff check . && mypy .
+
+# Rust
+cargo test && cargo check && cargo clippy --all-targets
+
+# Go
+go test ./... && go vet ./... && golangci-lint run
+
+# Ruby
+bundle exec rspec && bundle exec rubocop
+
+# PHP
+composer test && composer phpstan && composer phpcs
+
+# Swift
+swift test && swift build
+
+# Elixir
+mix test && mix credo && mix dialyzer
+
+# Dart
+dart test && dart analyze
+
+# Java (Maven)
+mvn test && mvn compile && mvn checkstyle:check
+
+# Java (Gradle)
+./gradlew test && ./gradlew check
+
+# C# (.NET)
+dotnet test && dotnet build && dotnet format --verify-no-changes
+```
+
+## Required Files
+
+### PRD File (Recommended)
+
+Create a `PRD.md` with clear task list:
+
+```markdown
+# Migration PRD
+
+## Tasks
+
+- [ ] Convert test-utils.test.js
+- [ ] Convert api.test.js
+- [ ] Update CI config
+- [ ] Remove Jest dependencies
+```
+
+### Progress File (Agent-maintained)
+
+Agent creates/updates `progress.txt`:
+
+```markdown
+# Progress Log
+
+## Session Started: 2026-01-10
+
+### Project: TypeScript with Bun
+
+### Commands: bun test | bun run typecheck | bun run lint
+
+### Completed Tasks
+
+- [x] test-utils.test.js - migrated, 12 tests passing
+- [x] api.test.js - migrated, 8 tests passing
+
+### Notes for Next Iteration
+
+- CI config needs Vitest runner update
+```
+
+## Completion Signal
+
+The loop ends when agent outputs:
+
+```
+<promise>COMPLETE</promise>
+```
+
+## Best Practices
+
+1. **Use LSP for detection**: Check file extensions, not just lock files
+2. **Small steps**: ONE feature per iteration (prevents context rot)
+3. **Quality gates**: Test, typecheck, lint MUST pass before commit
+4. **Prioritize risk**: Hard tasks first, easy wins last
+5. **Track progress**: Update progress.txt every iteration
+6. **Explicit scope**: Vague tasks loop forever
+7. **Graceful fallbacks**: If a command doesn't exist, skip and note it
+
+## Troubleshooting
+
+| Issue                | Solution                                    |
+| -------------------- | ------------------------------------------- |
+| Loop not progressing | Break task into smaller pieces              |
+| Tests failing        | Fix before continuing, don't skip           |
+| Context getting long | Summarize progress, restart session         |
+| Stuck on decision    | Note in progress.txt, ask user next session |
+| Unknown language     | Check file extensions against LSP table     |