opencodekit 0.14.2 → 0.14.4

package/dist/index.js

@@ -750,7 +750,7 @@ var cac = (name = "") => new CAC(name);
 // package.json
 var package_default = {
   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/.background-tasks.json

@@ -1,96 +1,96 @@
 {
-  "tasks": {
-    "bg_1767973877335_d2ihzd": {
-      "taskId": "bg_1767973877335_d2ihzd",
-      "sessionId": "ses_45c8b89a4ffeuq5BxBRQv4wrwd",
-      "agent": "explore",
-      "prompt": "Find all agent definitions in this project. List the file paths and agent names.",
-      "started": 1767973890766,
-      "status": "cancelled"
-    },
-    "bg_1767973898236_s7kyjm": {
-      "taskId": "bg_1767973898236_s7kyjm",
-      "sessionId": "ses_45c8b37ffffeIMMtZrHruaRN7A",
-      "agent": "scout",
-      "prompt": "What is the latest version of @opencode-ai/sdk and what are its main features?",
-      "started": 1767973936815,
-      "status": "completed"
-    },
-    "bg_1767974743680_ppd6p1": {
-      "taskId": "bg_1767974743680_ppd6p1",
-      "sessionId": "ses_45c7e517bffeagStJem1UDrHNf",
-      "agent": "explore",
-      "prompt": "Find all TypeScript files in the .opencode/tool directory and list them.",
-      "started": 1767974756797,
-      "status": "completed",
-      "beadId": "opencodekit-template-ag8",
-      "autoCloseBead": true
-    },
-    "bg_1767974825480_mlpk5z": {
-      "taskId": "bg_1767974825480_mlpk5z",
-      "sessionId": "ses_45c7d11efffe9LnnUp1W2C7GiI",
-      "agent": "explore",
-      "prompt": "List all files in .opencode/agent directory",
-      "started": 1767974843970,
-      "status": "completed",
-      "beadId": "opencodekit-template-3k0",
-      "autoCloseBead": true
-    },
-    "bg_1767975003390_y1pliv": {
-      "taskId": "bg_1767975003390_y1pliv",
-      "sessionId": "ses_45c7a5afffferx20SjJEy782Ap",
-      "agent": "explore",
-      "prompt": "Count the number of markdown files in .opencode/command directory",
-      "started": 1767975020306,
-      "status": "completed",
-      "beadId": "opencodekit-template-0ch",
-      "autoCloseBead": true
-    },
-    "bg_1767975064912_8nvlh7": {
-      "taskId": "bg_1767975064912_8nvlh7",
-      "sessionId": "ses_45c796aa9ffeYEhEzxybXEuOfO",
-      "agent": "explore",
-      "prompt": "List files in .opencode/agent directory",
-      "started": 1767975078449,
-      "status": "completed",
-      "beadId": "opencodekit-template-ryg",
-      "autoCloseBead": true
-    },
-    "bg_1767982850780_sdkoc4": {
-      "taskId": "bg_1767982850780_sdkoc4",
-      "sessionId": "ses_45c029d22ffe7cWSSebxdvxIgL",
-      "agent": "explore",
-      "prompt": "Find all TypeScript files in the src/commands directory and list what each command does. This is a test of agent delegation.",
-      "started": 1767982870771,
-      "status": "completed"
-    },
-    "bg_1767984165033_jyv9bd": {
-      "taskId": "bg_1767984165033_jyv9bd",
-      "sessionId": "ses_45bee8f51ffeJ6B5L7AMik624S",
-      "parentSessionId": "ses_45c0ae526ffeQlmBlscyZMZALt",
-      "agent": "explore",
-      "prompt": "List all TypeScript files in .opencode/tool/ directory and briefly describe what each tool does. This is a test of sub-session linking.",
-      "started": 1767984193526,
-      "status": "completed"
-    },
-    "bg_1767984696916_qi0xa9": {
-      "taskId": "bg_1767984696916_qi0xa9",
-      "sessionId": "ses_45be671a7ffeXRL43PHImPBtCh",
-      "parentSessionId": "ses_45c0ae526ffeQlmBlscyZMZALt",
-      "agent": "explore",
-      "prompt": "Find all files in src/commands/ and list their exports. This is a test of the updated background tool.",
-      "started": 1767984719380,
-      "status": "completed",
-      "beadId": "bd-test-123"
-    },
-    "bg_1767985457040_uo3le4": {
-      "taskId": "bg_1767985457040_uo3le4",
-      "sessionId": "ses_45bdad86bffeZNUcXDi1wrSwxb",
-      "parentSessionId": "ses_45c0ae526ffeQlmBlscyZMZALt",
-      "agent": "explore",
-      "prompt": "List files in src/ directory. Quick test.",
-      "started": 1767985471066,
-      "status": "running"
-    }
-  }
-}
+	"tasks": {
+		"bg_1767973877335_d2ihzd": {
+			"taskId": "bg_1767973877335_d2ihzd",
+			"sessionId": "ses_45c8b89a4ffeuq5BxBRQv4wrwd",
+			"agent": "explore",
+			"prompt": "Find all agent definitions in this project. List the file paths and agent names.",
+			"started": 1767973890766,
+			"status": "cancelled"
+		},
+		"bg_1767973898236_s7kyjm": {
+			"taskId": "bg_1767973898236_s7kyjm",
+			"sessionId": "ses_45c8b37ffffeIMMtZrHruaRN7A",
+			"agent": "scout",
+			"prompt": "What is the latest version of @opencode-ai/sdk and what are its main features?",
+			"started": 1767973936815,
+			"status": "completed"
+		},
+		"bg_1767974743680_ppd6p1": {
+			"taskId": "bg_1767974743680_ppd6p1",
+			"sessionId": "ses_45c7e517bffeagStJem1UDrHNf",
+			"agent": "explore",
+			"prompt": "Find all TypeScript files in the .opencode/tool directory and list them.",
+			"started": 1767974756797,
+			"status": "completed",
+			"beadId": "opencodekit-template-ag8",
+			"autoCloseBead": true
+		},
+		"bg_1767974825480_mlpk5z": {
+			"taskId": "bg_1767974825480_mlpk5z",
+			"sessionId": "ses_45c7d11efffe9LnnUp1W2C7GiI",
+			"agent": "explore",
+			"prompt": "List all files in .opencode/agent directory",
+			"started": 1767974843970,
+			"status": "completed",
+			"beadId": "opencodekit-template-3k0",
+			"autoCloseBead": true
+		},
+		"bg_1767975003390_y1pliv": {
+			"taskId": "bg_1767975003390_y1pliv",
+			"sessionId": "ses_45c7a5afffferx20SjJEy782Ap",
+			"agent": "explore",
+			"prompt": "Count the number of markdown files in .opencode/command directory",
+			"started": 1767975020306,
+			"status": "completed",
+			"beadId": "opencodekit-template-0ch",
+			"autoCloseBead": true
+		},
+		"bg_1767975064912_8nvlh7": {
+			"taskId": "bg_1767975064912_8nvlh7",
+			"sessionId": "ses_45c796aa9ffeYEhEzxybXEuOfO",
+			"agent": "explore",
+			"prompt": "List files in .opencode/agent directory",
+			"started": 1767975078449,
+			"status": "completed",
+			"beadId": "opencodekit-template-ryg",
+			"autoCloseBead": true
+		},
+		"bg_1767982850780_sdkoc4": {
+			"taskId": "bg_1767982850780_sdkoc4",
+			"sessionId": "ses_45c029d22ffe7cWSSebxdvxIgL",
+			"agent": "explore",
+			"prompt": "Find all TypeScript files in the src/commands directory and list what each command does. This is a test of agent delegation.",
+			"started": 1767982870771,
+			"status": "completed"
+		},
+		"bg_1767984165033_jyv9bd": {
+			"taskId": "bg_1767984165033_jyv9bd",
+			"sessionId": "ses_45bee8f51ffeJ6B5L7AMik624S",
+			"parentSessionId": "ses_45c0ae526ffeQlmBlscyZMZALt",
+			"agent": "explore",
+			"prompt": "List all TypeScript files in .opencode/tool/ directory and briefly describe what each tool does. This is a test of sub-session linking.",
+			"started": 1767984193526,
+			"status": "completed"
+		},
+		"bg_1767984696916_qi0xa9": {
+			"taskId": "bg_1767984696916_qi0xa9",
+			"sessionId": "ses_45be671a7ffeXRL43PHImPBtCh",
+			"parentSessionId": "ses_45c0ae526ffeQlmBlscyZMZALt",
+			"agent": "explore",
+			"prompt": "Find all files in src/commands/ and list their exports. This is a test of the updated background tool.",
+			"started": 1767984719380,
+			"status": "completed",
+			"beadId": "bd-test-123"
+		},
+		"bg_1767985457040_uo3le4": {
+			"taskId": "bg_1767985457040_uo3le4",
+			"sessionId": "ses_45bdad86bffeZNUcXDi1wrSwxb",
+			"parentSessionId": "ses_45c0ae526ffeQlmBlscyZMZALt",
+			"agent": "explore",
+			"prompt": "List files in src/ directory. Quick test.",
+			"started": 1767985471066,
+			"status": "running"
+		}
+	}
+}

package/dist/template/.opencode/.ralph-state.json

@@ -1,12 +1,12 @@
 {
-  "active": false,
-  "sessionID": null,
-  "iteration": 0,
-  "maxIterations": 50,
-  "completionPromise": "<promise>COMPLETE</promise>",
-  "task": "",
-  "prdFile": null,
-  "progressFile": "progress.txt",
-  "startedAt": null,
-  "mode": "hitl"
-}
+	"active": false,
+	"sessionID": null,
+	"iteration": 0,
+	"maxIterations": 50,
+	"completionPromise": "<promise>COMPLETE</promise>",
+	"task": "",
+	"prdFile": null,
+	"progressFile": "progress.txt",
+	"startedAt": null,
+	"mode": "hitl"
+}

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

@@ -56,6 +56,23 @@ Tool results and user messages may include `<system-reminder>` tags. These conta
 - Keep responses concise
 - First output is ~70-80% right; refinement is expected, not failure
 
+## Progress Updates (Preamble Pattern)
+
+Before tool calls during multi-step work, send brief updates (8-12 words) to keep users informed:
+
+**Good examples:**
+
+- "Tests passing. Now updating the API handler."
+- "Found the bug in auth.ts:42. Fixing now."
+- "Linter clean. Running full test suite."
+
+**Bad examples:**
+
+- [radio silence for 2 minutes while working]
+- "I am now going to use the edit tool to modify the authentication service file..." (too verbose)
+
+Keep users in the loop without flooding them.
+
 ## Phase 0: Intent Gate
 
 Before ANY action on a new request, do two things.
@@ -198,7 +215,18 @@ Never leave code in a broken state. Never continue hoping random changes will wo
 
 ## Task Management
 
-- Use TodoWrite to track subtasks; update every 10-15 minutes
+Use TodoWrite to track subtasks with explicit status flow:
+
+```
+pending → in_progress → completed
+```
+
+**Rules:**
+
+- There should be exactly ONE `in_progress` task at a time
+- Complete current tasks before starting new ones
+- Mark tasks complete immediately after finishing (don't batch)
+- Update every 10-15 minutes during long sessions
 - Finish one subtask end-to-end before starting next
 - Create handoff via `/handoff <bead-id>` before context limit
 

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

@@ -42,6 +42,43 @@ Think, read, search, and delegate @explore/@scout agents to construct a well-for
 Tool results and user messages may include `<system-reminder>` tags. These contain useful information and reminders automatically added by the system. They bear no direct relation to the specific tool results or user messages in which they appear.
 </system-reminder>
 
+## When to Plan vs When to Execute
+
+**Use a plan when:**
+
+- Task is non-trivial and requires multiple actions over a long time horizon
+- There are logical phases or dependencies where sequencing matters
+- Work has ambiguity that benefits from outlining high-level goals
+- User asked for more than one thing in a single prompt
+- You need intermediate checkpoints for feedback and validation
+
+**Skip planning for:**
+
+- Simple single-step queries you can answer immediately
+- Padding simple work with filler steps
+- Trivial tasks where planning adds no value
+
+Don't over-plan. If user asks "fix the typo in line 42", just delegate to @build. No plan needed.
+
+---
+
+## Progress Updates (Preamble Pattern)
+
+Before tool calls during research, send brief updates (8-12 words) to keep users informed:
+
+**Good examples:**
+
+- "Explored the repo; now checking API route definitions."
+- "Config's looking tidy. Next up is editing helpers."
+- "Finished reviewing auth patterns. Chasing down error handling."
+
+**Bad examples:**
+
+- [radio silence for 30 seconds while agents run]
+- "I am now going to use the explore agent to search for patterns in the codebase..." (too verbose)
+
+---
+
 ## Enhanced Planning Workflow
 
 ### Phase 1: Initial Understanding
@@ -175,6 +212,62 @@ Final plan should include:
 
 **Always end with**: "Ready to proceed with this plan?"
 
+---
+
+## Plan Quality Examples
+
+**High-quality plans** (specific, actionable, verifiable):
+
+```
+1. Add CLI entry with file args
+2. Parse Markdown via CommonMark library
+3. Apply semantic HTML template
+4. Handle code blocks, images, links
+5. Add error handling for invalid files
+```
+
+```
+1. Define CSS variables for colors
+2. Add toggle with localStorage state
+3. Refactor components to use variables
+4. Verify all views for readability
+5. Add smooth theme-change transition
+```
+
+**Low-quality plans** (vague, no actionable steps):
+
+```
+1. Create CLI tool
+2. Add Markdown parser
+3. Convert to HTML
+```
+
+```
+1. Add dark mode toggle
+2. Save preference
+3. Make styles look good
+```
+
+The difference: high-quality plans have **specific implementation details** that can be verified. Low-quality plans are just restating the goal.
+
+---
+
+## TodoWrite Status Management
+
+When creating implementation plans that @build will execute, understand the status flow:
+
+```
+pending → in_progress → completed
+```
+
+**Rules:**
+
+- There should be exactly ONE `in_progress` step at a time
+- Complete current tasks before starting new ones
+- Mark steps complete immediately after finishing (don't batch)
+
+This helps @build track progress and helps users understand where work stands
+
 ## Specification Quality Checklist
 
 Before presenting plan:

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

@@ -113,6 +113,24 @@ Delegate immediately when you hit any of these:
 - First output is ~70-80% right; refinement is expected
 - Quick sanity check after changes (linter/type-check), but don't do full verification loops
 
+## Progress Updates (Preamble Pattern)
+
+Even at speed, brief updates (8-12 words) help users track what's happening:
+
+**Good examples:**
+
+- "Found it. Fixing the typo now."
+- "Config updated. Running quick lint check."
+- "Done. Delegating the rest to @build."
+
+Don't go silent during multi-file changes. One-liners are fine.
+
+## Ambition vs Precision
+
+**Greenfield code** (new files, new features): Be bold. Use modern patterns. Move fast.
+
+**Existing code** (modifications, fixes): Be surgical. Match existing style exactly. Don't refactor unrelated code—that's scope creep, delegate to @build.
+
 ## Challenge Obvious Problems
 
 Even at speed, don't blindly implement bad ideas. If you see an obvious problem with what the user is asking—something that will clearly break or contradict existing patterns—say so in one sentence and ask if they want to proceed anyway.

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/opencode.json

@@ -7,11 +7,11 @@
 		},
 		"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",
@@ -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": "`",
@@ -510,7 +514,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,7 @@
 	"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"
 	},

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/plugin/lsp.ts

@@ -222,7 +222,8 @@ export const Lsp: Plugin = async () => {
 		 * Injects LSP reminder when user mentions code files in their message
 		 * This catches intent BEFORE tools are executed
 		 */
-		"chat.message": async (_input, output) => {
+		"chat.message": async (input, output) => {
+			const { sessionID, messageID } = input;
 			const { message, parts } = output;
 
 			// Only process user messages
@@ -259,12 +260,16 @@ 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({
+			// Inject synthetic message part with all required fields
+			const partId = `lsp-nudge-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+			parts.push({
+				id: partId,
+				sessionID,
+				messageID: messageID || "",
 				type: "text",
 				text: nudgeText,
 				synthetic: true,
-			});
+			} as import("@opencode-ai/sdk").Part);
 		},
 
 		/**