opencodekit 0.14.2 → 0.14.4

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     |

package/dist/template/.opencode/tool/background.ts

@@ -66,7 +66,7 @@ function findBdPath(): string {
 				execSync(`test -x "${p}"`, { timeout: 1000 });
 				return p;
 			} catch {
-				continue;
+				// Try next path
 			}
 		}
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencodekit",
-	"version": "0.14.2",
+	"version": "0.14.4",
 	"description": "CLI tool for bootstrapping and managing OpenCodeKit projects",
 	"type": "module",
 	"repository": {

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

@@ -1,97 +0,0 @@
----
-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/plugin/handoff.ts

@@ -1,37 +0,0 @@
-/**
- * OpenCode Handoff Plugin
- * Injects the most recent handoff file into session compaction
- *
- * Workflow:
- * 1. User creates handoff markdown file in .opencode/memory/handoffs/
- * 2. Session compaction (Ctrl+K) includes handoff context
- * 3. New session resumes from previous state
- */
-
-import type { Plugin } from "@opencode-ai/plugin";
-
-export const HandoffPlugin: Plugin = async ({ $, directory }) => {
-	const HANDOFF_DIR = `${directory}/.opencode/memory/handoffs`;
-
-	return {
-		"experimental.session.compacting": async (_input, output) => {
-			// Find most recent handoff file
-			const result =
-				await $`ls -t ${HANDOFF_DIR}/*.md 2>/dev/null | head -1`.quiet();
-
-			if (!result.stdout) return;
-
-			const handoffPath = result.stdout.toString().trim();
-			const handoffContent = await $`cat ${handoffPath}`.text();
-
-			// Inject into compaction context
-			output.context.push(`
-## Previous Session Handoff
-
-${handoffContent}
-
-**IMPORTANT**: Resume work from where previous session left off.
-`);
-		},
-	};
-};

package/dist/template/.opencode/plugin/ralph-wiggum.ts

@@ -1,182 +0,0 @@
-/**
- * Ralph Wiggum Plugin for OpenCode
- *
- * Handles the session.idle event to continue the Ralph loop.
- * Tools are defined separately in .opencode/tool/ralph.ts
- *
- * Based on: https://ghuntley.com/ralph/
- */
-
-import fs from "node:fs/promises";
-import type { Plugin } from "@opencode-ai/plugin";
-
-const STATE_FILE = ".opencode/.ralph-state.json";
-const IDLE_DEBOUNCE_MS = 2000;
-let lastIdleTime = 0;
-
-interface RalphState {
-	active: boolean;
-	sessionID: string | null;
-	iteration: number;
-	maxIterations: number;
-	completionPromise: string;
-	task: string;
-	prdFile: string | null;
-	progressFile: string;
-	startedAt: number | null;
-	mode: "hitl" | "afk";
-}
-
-async function loadState(): Promise<RalphState | null> {
-	try {
-		const content = await fs.readFile(STATE_FILE, "utf-8");
-		return JSON.parse(content);
-	} catch {
-		return null;
-	}
-}
-
-async function saveState(state: RalphState): Promise<void> {
-	await fs.writeFile(STATE_FILE, JSON.stringify(state, null, 2));
-}
-
-async function resetState(): Promise<void> {
-	try {
-		await fs.unlink(STATE_FILE);
-	} catch {
-		// File doesn't exist, that's fine
-	}
-}
-
-export const RalphWiggum: Plugin = async ({ client }) => {
-	const log = async (
-		message: string,
-		level: "info" | "warn" | "error" = "info",
-	) => {
-		await client.app
-			.log({
-				body: { service: "ralph-wiggum", level, message },
-			})
-			.catch(() => {});
-	};
-
-	const showToast = async (
-		title: string,
-		message: string,
-		variant: "info" | "success" | "warning" | "error" = "info",
-	) => {
-		await client.tui
-			.showToast({
-				body: {
-					title: `Ralph: ${title}`,
-					message,
-					variant,
-					duration: variant === "error" ? 8000 : 5000,
-				},
-			})
-			.catch(() => {});
-	};
-
-	const buildContinuationPrompt = (state: RalphState): string => {
-		const prdRef = state.prdFile ? `@${state.prdFile} ` : "";
-		const progressRef = `@${state.progressFile}`;
-
-		return `
-${prdRef}${progressRef}
-
-## Ralph Wiggum Loop - Iteration ${state.iteration}/${state.maxIterations}
-
-You are in an autonomous loop. Continue working on the task.
-
-**Task:** ${state.task}
-
-**Instructions:**
-1. Review the PRD/task list and progress file
-2. Choose the highest-priority INCOMPLETE task
-3. Implement ONE feature/change only
-4. Run feedback loops: typecheck, test, lint
-5. Commit if all pass
-6. Update ${state.progressFile}
-7. If ALL tasks complete, output: ${state.completionPromise}
-
-**Constraints:** ONE feature per iteration. Quality over speed.
-`.trim();
-	};
-
-	const handleSessionIdle = async (sessionID: string): Promise<void> => {
-		const now = Date.now();
-		if (now - lastIdleTime < IDLE_DEBOUNCE_MS) return;
-		lastIdleTime = now;
-
-		const state = await loadState();
-		if (!state?.active || state.sessionID !== sessionID) return;
-
-		try {
-			const messagesResponse = await client.session.messages({
-				path: { id: sessionID },
-			});
-			const messages = messagesResponse.data || [];
-			const lastMessage = messages[messages.length - 1];
-
-			const lastText =
-				lastMessage?.parts
-					?.filter((p) => p.type === "text")
-					.map((p) => ("text" in p ? (p.text as string) : ""))
-					.join("") || "";
-
-			if (lastText.includes(state.completionPromise)) {
-				const duration = state.startedAt
-					? Math.round((Date.now() - state.startedAt) / 1000 / 60)
-					: 0;
-				await showToast(
-					"Complete!",
-					`Finished in ${state.iteration} iterations (${duration} min)`,
-					"success",
-				);
-				await log(`Loop completed in ${state.iteration} iterations`);
-				await resetState();
-				return;
-			}
-
-			state.iteration++;
-			if (state.iteration >= state.maxIterations) {
-				await showToast(
-					"Stopped",
-					`Max iterations (${state.maxIterations}) reached`,
-					"warning",
-				);
-				await log(`Max iterations reached: ${state.maxIterations}`, "warn");
-				await resetState();
-				return;
-			}
-
-			await saveState(state);
-
-			await client.session.prompt({
-				path: { id: sessionID },
-				body: {
-					parts: [{ type: "text", text: buildContinuationPrompt(state) }],
-				},
-			});
-
-			await log(`Iteration ${state.iteration}/${state.maxIterations}`);
-		} catch (error) {
-			await log(`Error in Ralph loop: ${error}`, "error");
-			await resetState();
-		}
-	};
-
-	return {
-		event: async ({ event }) => {
-			if (event.type === "session.idle") {
-				const sessionID = (event as { properties?: { sessionID?: string } })
-					.properties?.sessionID;
-				if (sessionID) {
-					await handleSessionIdle(sessionID);
-				}
-			}
-		},
-	};
-};
-
-export default RalphWiggum;