opencodekit 0.18.4 → 0.18.5

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

@@ -11,7 +11,7 @@
     "type-check": "tsc --noEmit"
   },
   "dependencies": {
-    "@opencode-ai/plugin": "1.2.20"
+    "@opencode-ai/plugin": "1.2.21"
   },
   "devDependencies": {
     "@types/node": "^25.3.0",

package/dist/template/.opencode/plugin/lib/memory-helpers.ts

@@ -1,13 +1,11 @@
 /**
  * Memory Plugin — Helpers
  *
- * Constants, compaction utilities, and tool formatting helpers.
+ * Constants, tool formatting helpers, and file utilities.
  * Pure functions — no plugin/closure dependencies.
  */
 
-import { Database } from "bun:sqlite";
-import { readdir, readFile, stat } from "node:fs/promises";
-import path from "node:path";
+import { readFile } from "node:fs/promises";
 import type { ObservationType } from "./memory-db.js";
 
 // ============================================================================
@@ -41,25 +39,10 @@ export const FILE_REF_PATTERNS = [
 	/(?:^|\s)(\.opencode\/\S+)/gm,
 ];
 
-// Compaction constants
-export const MAX_SESSION_CONTEXT_CHARS = 3000;
-export const MAX_PROJECT_FILES = 3;
-export const MAX_PROJECT_FILE_CHARS = 900;
-export const MAX_HANDOFF_CHARS = 2500;
-export const MAX_BEADS = 8;
-export const MAX_COMBINED_CONTEXT_CHARS = 10000;
-const BEADS_DB_READ_ATTEMPTS = 3;
-const BEADS_DB_RETRY_DELAY_MS = 500;
-
 // ============================================================================
-// Compaction Helpers
+// File Helpers
 // ============================================================================
 
-export function truncate(text: string, maxChars: number): string {
-	if (text.length <= maxChars) return text;
-	return `${text.slice(0, maxChars)}\n...[truncated]`;
-}
-
 export async function safeReadFile(filePath: string): Promise<string> {
 	try {
 		return await readFile(filePath, "utf-8");
@@ -68,115 +51,6 @@ export async function safeReadFile(filePath: string): Promise<string> {
 	}
 }
 
-export function renderSection(title: string, body: string): string {
-	if (!body.trim()) return "";
-	return `## ${title}\n${body.trim()}`;
-}
-
-export async function readProjectMemoryContext(
-	memoryDir: string,
-): Promise<string> {
-	const projectDir = path.join(memoryDir, "project");
-	let names: string[] = [];
-	try {
-		names = (await readdir(projectDir))
-			.filter((n) => n.endsWith(".md"))
-			.sort()
-			.slice(0, MAX_PROJECT_FILES);
-	} catch {
-		return "";
-	}
-
-	const chunks: string[] = [];
-	for (const name of names) {
-		const content = (await safeReadFile(path.join(projectDir, name))).trim();
-		if (!content) continue;
-		chunks.push(
-			`### ${name.replace(/\.md$/, "")}\n${truncate(content, MAX_PROJECT_FILE_CHARS)}`,
-		);
-	}
-	return chunks.join("\n\n");
-}
-
-export async function readLatestHandoff(handoffDir: string): Promise<string> {
-	let names: string[] = [];
-	try {
-		names = (await readdir(handoffDir)).filter((n) => n.endsWith(".md"));
-	} catch {
-		return "";
-	}
-	if (names.length === 0) return "";
-
-	const withMtime = await Promise.all(
-		names.map(async (name) => {
-			const fullPath = path.join(handoffDir, name);
-			try {
-				return { name, fullPath, mtimeMs: (await stat(fullPath)).mtimeMs };
-			} catch {
-				return { name, fullPath, mtimeMs: 0 };
-			}
-		}),
-	);
-	withMtime.sort((a, b) => b.mtimeMs - a.mtimeMs);
-	const latest = withMtime[0];
-	const content = (await safeReadFile(latest.fullPath)).trim();
-	if (!content) return "";
-	return `Source: ${latest.name}\n${truncate(content, MAX_HANDOFF_CHARS)}`;
-}
-
-function delay(ms: number): Promise<void> {
-	return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-export async function readInProgressBeads(directory: string): Promise<string> {
-	const dbPath = path.join(directory, ".beads", "beads.db");
-
-	for (let attempt = 0; attempt < BEADS_DB_READ_ATTEMPTS; attempt++) {
-		let db: Database | undefined;
-		try {
-			db = new Database(dbPath, { readonly: true });
-			const rows = db
-				.query<{ id: string; title: string }, [number]>(
-					"SELECT id, title FROM issues WHERE status = 'in_progress' ORDER BY updated_at DESC LIMIT ?",
-				)
-				.all(MAX_BEADS);
-			return rows.length > 0
-				? rows.map((r) => `- ${r.id}: ${r.title}`).join("\n")
-				: "";
-		} catch (error) {
-			const code = String((error as { code?: string } | undefined)?.code ?? "");
-			const message = String(
-				(error as { message?: string } | undefined)?.message ?? error,
-			);
-			const isRetryable =
-				code.includes("SQLITE_BUSY") ||
-				code.includes("SQLITE_LOCKED") ||
-				message.includes("SQLITE_BUSY") ||
-				message.includes("SQLITE_LOCKED");
-
-			if (isRetryable && attempt < BEADS_DB_READ_ATTEMPTS - 1) {
-				await delay(BEADS_DB_RETRY_DELAY_MS);
-				continue;
-			}
-
-			if (isRetryable) {
-				console.warn(
-					`[memory] Failed to read beads.db after ${BEADS_DB_READ_ATTEMPTS} attempts: ${message}`,
-				);
-			} else {
-				console.warn(
-					`[memory] Failed to read beads.db, continuing without bead context: ${message}`,
-				);
-			}
-			return "";
-		} finally {
-			db?.close();
-		}
-	}
-
-	return "";
-}
-
 // ============================================================================
 // Tool Helpers
 // ============================================================================

package/dist/template/.opencode/plugin/lib/memory-hooks.ts

@@ -14,7 +14,6 @@
  * - message.updated, message.removed, message.part.updated, message.part.removed
  */
 
-import path from "node:path";
 import { captureMessageMeta, captureMessagePart } from "./capture.js";
 import { manageContext } from "./context.js";
 import { curateFromDistillations } from "./curator.js";
@@ -25,23 +24,9 @@ import {
 	checkpointWAL,
 	getDatabaseSizes,
 	optimizeFTS5,
-	searchObservationsFTS,
 } from "./memory-db.js";
-import {
-	MAX_COMBINED_CONTEXT_CHARS,
-	MAX_SESSION_CONTEXT_CHARS,
-	readInProgressBeads,
-	readLatestHandoff,
-	readProjectMemoryContext,
-	renderSection,
-	safeReadFile,
-	truncate,
-} from "./memory-helpers.js";
 
 interface HookDeps {
-	memoryDir: string;
-	handoffDir: string;
-	directory: string;
 	showToast: (
 		title: string,
 		message: string,
@@ -51,7 +36,7 @@ interface HookDeps {
 }
 
 export function createHooks(deps: HookDeps) {
-	const { memoryDir, handoffDir, directory, showToast, log } = deps;
+	const { showToast, log } = deps;
 
 	return {
 		// ================================================================
@@ -167,52 +152,11 @@ export function createHooks(deps: HookDeps) {
 		// Receives: (input: { sessionID }, output: { context, prompt? })
 		// ================================================================
 		"experimental.session.compacting": async (
-			input: { sessionID?: string },
+			_input: { sessionID?: string },
 			output: { context: string[]; prompt?: string },
 		) => {
-			const sessionContext = truncate(
-				(await safeReadFile(path.join(memoryDir, "session-context.md"))).trim(),
-				MAX_SESSION_CONTEXT_CHARS,
-			);
-
-			const [projectContext, handoffContext] = await Promise.all([
-				readProjectMemoryContext(memoryDir),
-				readLatestHandoff(handoffDir),
-			]);
-
-			const beadsContext = await readInProgressBeads(directory);
-
-			// Add relevant observations for session
-			let knowledgeContext = "";
-			if (input.sessionID) {
-				try {
-					const recentObs = searchObservationsFTS("", { limit: 5 });
-					if (recentObs.length > 0) {
-						knowledgeContext = recentObs
-							.map((o) => `- [${o.type}] #${o.id}: ${o.title}`)
-							.join("\n");
-					}
-				} catch {
-					/* Non-fatal */
-				}
-			}
-
-			const combined = [
-				renderSection("Session Continuity", sessionContext),
-				renderSection("Active Beads", beadsContext),
-				renderSection("Previous Handoff", handoffContext),
-				renderSection("Recent Knowledge", knowledgeContext),
-				renderSection("Project Memory", projectContext),
-			]
-				.filter(Boolean)
-				.join("\n\n");
-
-			if (combined) {
-				output.context.push(
-					`## Session Context\n${truncate(combined, MAX_COMBINED_CONTEXT_CHARS)}\n`,
-				);
-			}
-
+			// No context injection here — the session is already at the
+			// model limit when compaction fires. Only append prompt guidance.
 			output.prompt = `${output.prompt ?? ""}
 
 <compaction_task>

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

@@ -73,9 +73,6 @@ export const MemoryPlugin: Plugin = async ({ client, directory }) => {
 
 	// Assemble hooks
 	const hooks = createHooks({
-		memoryDir,
-		handoffDir,
-		directory,
 		showToast,
 		log,
 	});

package/dist/template/.opencode/skill/agent-teams/SKILL.md

@@ -12,6 +12,8 @@ dependencies: []
 
 # Agent Teams - Multi-Agent Team Coordination
 
+> **Replaces** single-agent sequential work when tasks benefit from parallel research, review, or competing hypotheses
+
 ## When to Use
 
 - Parallel research, review, or competing approaches that need coordination
@@ -22,7 +24,6 @@ dependencies: []
 - Single-agent tasks or tightly coupled edits where coordination overhead is wasteful
 - Simple parallel work that can use fire-and-forget subagents instead
 
-
 ## Overview
 
 **Agent Teams = Lead + Teammates + Shared Task List + Messaging**
@@ -53,6 +54,15 @@ Need shared findings?               → Agent Teams
 Simple parallel execution?          → Subagents (Task tool)
 ```
 
+### Parallel Skill Selection
+
+| Scenario                                    | Use This Skill              |
+| ------------------------------------------- | --------------------------- |
+| 3+ independent bug investigations           | dispatching-parallel-agents |
+| Coordinated team (research + review + impl) | agent-teams                 |
+| Large plan with dependency graph            | swarm-coordination          |
+| 2 independent tasks                         | Just use 2 Task() calls     |
+
 ## When to Use
 
 - **Parallel research**: Multiple agents researching different aspects of a problem
@@ -251,3 +261,8 @@ Before dispatching a team:
 - [ ] Each task has acceptance criteria (verification commands)
 - [ ] Lead has a synthesis plan (how to integrate results)
 - [ ] Tasks are sized appropriately (5-6 per teammate max)
+
+## See Also
+
+- `dispatching-parallel-agents` — for independent debugging-focused parallel investigations
+- `swarm-coordination` — for dependency-aware large-plan execution

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

@@ -12,6 +12,7 @@ dependencies: []
 
 # Beads Workflow - Multi-Agent Task Coordination
 
+> **Replaces** ad-hoc task tracking with sticky notes, TODO comments, or mental checklists that lose state between sessions
 ## When to Use
 
 - Coordinating multi-session work with dependencies, blockers, or file locking needs
@@ -110,6 +111,22 @@ See: `references/MULTI_AGENT.md` for swarm tool usage and examples.
 5. **Write notes for future agents** - Assume zero conversation context
 6. **Claim file paths before editing** - Use reserve to declare ownership (multi-agent only)
 
+## Anti-Patterns
+
+| Anti-Pattern | Why It Fails | Instead |
+| --- | --- | --- |
+| Claiming a bead without reading its current state first (`br show`) | Misses dependencies, blockers, and prior context | Run `br show <id>` before `br update <id> --status in_progress` |
+| Closing a bead without verification evidence | Marks incomplete or broken work as done | Run verification commands and capture output before `br close` |
+| Working on blocked beads (dependencies not met) | Wastes time and causes out-of-order delivery | Use `br ready` and confirm dependencies in `br show <id>` |
+| Modifying bead state without user confirmation | Violates workflow expectations and can surprise collaborators | Ask before changing bead status, especially close/sync actions |
+| Using `br sync` without `--flush-only` (can cause conflicts) | May write unexpected state and increase sync conflict risk | Always use `br sync --flush-only` then commit `.beads/` manually |
+
+## Verification
+
+- **Before closing:** run verification commands, paste output as evidence
+- **After close:** `br show <id>` confirms `status=closed`
+- **After sync:** `git status` shows clean working tree
+
 ## File Path Claiming (Summary)
 
 Claim files before editing in multi-agent work using `br reserve <id> --files "..."`.
@@ -157,3 +174,8 @@ MAINTENANCE:
 - `references/MULTI_AGENT.md`
 - `references/FILE_CLAIMING.md`
 - `references/BEST_PRACTICES.md`
+
+## See Also
+
+- `verification-before-completion`
+- `beads-bridge`

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

@@ -8,6 +8,7 @@ dependencies: []
 
 # Brainstorming Ideas Into Designs
 
+> **Replaces** jumping straight to implementation without exploring alternatives, constraints, or edge cases
 ## When to Use
 
 - You have a rough idea that needs clarification into a design or spec
@@ -84,3 +85,30 @@ Start by understanding the current project context, then ask questions one at a
 - **Explore alternatives** - Always propose 2-3 approaches before settling
 - **Incremental validation** - Present design in sections, validate each
 - **Be flexible** - Go back and clarify when something doesn't make sense
+
+## Example Flow
+
+**User request**: "Add dark mode to the app"
+
+**Good brainstorming questions**:
+1. "Should dark mode be system-preference-aware, manual toggle, or both?"
+2. "Where does theme state live — CSS variables, React context, localStorage?"
+3. "Are there existing color tokens, or do we need to create a design token system?"
+4. "What about images/icons — do they need dark variants?"
+
+**Bad brainstorming** (jumping to solution):
+1. "I'll add a ThemeContext with useState and toggle button" ← skipped alternatives
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It Fails | Instead |
+| --- | --- | --- |
+| Asking questions the codebase can answer (search first) | Wastes turns and slows decisions; signals weak preparation | Do quick repo/docs lookup first, then ask only unresolved questions |
+| Brainstorming during mechanical/routine tasks | Adds overhead when execution is already clear | Skip to execution using the relevant implementation skill |
+| Generating 10+ alternatives without narrowing criteria | Creates analysis paralysis and no decision pressure | Present 2-3 viable options with explicit decision criteria |
+| Continuing to brainstorm after a clear direction emerges | Burns time and erodes momentum | Confirm direction, summarize decisions, transition to PRD/plan |
+
+## See Also
+
+- `writing-plans` - Turn validated direction into zero-ambiguity implementation tasks
+- `prd` - Capture behavioral requirements before implementation

package/dist/template/.opencode/skill/code-navigation/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: code-navigation
+description: Use when navigating unfamiliar code, tracing cross-file dependencies, or before editing — efficient code reading patterns that minimize tool calls and token waste
+version: 1.0.0
+tags: [workflow, code-quality, context]
+dependencies: []
+---
+
+# Code Navigation Skill
+
+## When to Use
+
+- Exploring an unfamiliar codebase or module
+- Tracing a function call across multiple files
+- Understanding blast radius before a breaking change
+- Planning edits that touch multiple files
+
+## When NOT to Use
+
+- Simple single-file edits where you already know the location
+- Reading config or documentation files
+
+## Core Principle
+
+> Collapse multiple tool calls into fewer, smarter ones. Every unnecessary read or search wastes tokens and turns.
+
+## Navigation Patterns
+
+### Pattern 1: Search First, Read Second
+
+**Wrong** (3-6 tool calls):
+```
+glob("*.ts") → read(file1) → "too big" → grep("functionName") → read(file2) → read(file3, section)
+```
+
+**Right** (1-2 tool calls):
+```
+grep("functionName", path: "src/") → read(exact_file, offset: line-10, limit: 30)
+```
+
+Start with search (grep, LSP findReferences) to locate, then read only what you need.
+
+### Pattern 2: Multi-Symbol Search
+
+When tracing a call chain (A calls B calls C), search for all symbols together:
+```
+grep({ pattern: "functionA|functionB|functionC", path: "src/" })
+```
+
+Or use LSP outgoingCalls to get the full call tree from a single point.
+
+### Pattern 3: Don't Re-Read What You've Already Seen
+
+**Anti-pattern**: Search returns full function body, then agent reads the same file again.
+
+If search results already show the code you need, work from that output. Only re-read when:
+- You need surrounding context (lines above/below the match)
+- You need the exact content for editing (verify before edit)
+- The search result was truncated
+
+### Pattern 4: Blast Radius Check (Before Breaking Changes)
+
+**WHEN**: Before renaming, removing, or changing the signature of an export.
+**SKIP**: When adding new code, fixing internal bugs, or reading.
+
+Steps:
+1. `lsp({ operation: "findReferences" })` — find all callers
+2. `lsp({ operation: "incomingCalls" })` — get the call hierarchy
+3. Review each caller to assess impact
+4. Plan edits from leaf callers inward (furthest dependencies first)
+
+### Pattern 5: Context Locality
+
+When editing a file, search results from the same directory/package are more likely relevant. Pass context when available:
+- In grep: use `path: "src/same-module/"` to scope
+- In LSP: operations are already file-scoped
+- In tilth: pass `context` param to boost nearby results
+
+### Pattern 6: Outline Before Deep Read
+
+For large files (>200 lines), get the structure first:
+```
+lsp({ operation: "documentSymbol", filePath: "src/large-file.ts", line: 1, character: 1 })
+```
+
+This gives you function names + line ranges. Then read only the section you need with `offset` and `limit`.
+
+### Pattern 7: Follow the Call Chain (Not the File Tree)
+
+**Wrong**: Read files top-to-bottom hoping to understand the flow.
+**Right**: Start from the entry point, follow function calls:
+
+```
+1. lsp({ operation: "goToDefinition" })   → find where it's defined
+2. lsp({ operation: "outgoingCalls" })     → what does it call?
+3. lsp({ operation: "goToDefinition" })    → follow the interesting callee
+```
+
+## With tilth MCP
+
+When tilth is available, it provides superior navigation:
+
+| Built-in Tool | tilth Equivalent | Advantage |
+|---|---|---|
+| `grep` + `read` | `tilth_search` (expand: 2) | Returns definitions with inline source — no second read needed |
+| `glob` | `tilth_files` | Adds token estimates per file |
+| `read` (large file) | `tilth_read` | Auto-outlines large files, shows structure |
+| `lsp(incomingCalls)` | `tilth_search(kind: "callers")` | Cross-language structural caller detection |
+| Manual tracing | `tilth_deps` | Shows imports + downstream callers before breaking changes |
+
+**IMPORTANT**: If tilth is available, prefer it over built-in grep/glob/read for code navigation. Tilth's expanded search results include full source — do NOT re-read files already shown in search output.
+
+## Cost Awareness
+
+Every tool call has a token cost. Efficient navigation means:
+- Fewer tool calls per task
+- Less context consumed by redundant reads
+- More budget available for actual implementation
+
+**Target**: Find and understand any symbol in ≤3 tool calls, not 6+.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---|---|
+| Read entire large file | Use outline first, then section read |
+| Search → read same code again | Work from search results directly |
+| Trace calls one-by-one | Multi-symbol search or outgoingCalls |
+| Explore randomly | Start from entry point, follow calls |
+| Forget to check blast radius | Always check before signature changes |

package/dist/template/.opencode/skill/condition-based-waiting/SKILL.md

@@ -8,6 +8,7 @@ dependencies: []
 
 # Condition-Based Waiting
 
+> **Replaces** arbitrary `sleep()` / `setTimeout()` calls and hardcoded delays that cause flaky tests and slow CI
 ## When to Use
 
 - Tests are flaky due to arbitrary delays or timing guesses
@@ -101,6 +102,12 @@ await new Promise((r) => setTimeout(r, 200)); // Then: wait for timed behavior
 2. Based on known timing (not guessing)
 3. Comment explaining WHY
 
+## Verification
+
+- **After applying:** run the previously flaky test 5+ times — should pass consistently
+- **Check:** no hardcoded sleep/delay values remain in the test file
+- **Measure:** test execution time should decrease (no wasted wait time)
+
 ## Real-World Impact
 
 From debugging session (2025-10-03):
@@ -109,3 +116,8 @@ From debugging session (2025-10-03):
 - Pass rate: 60% → 100%
 - Execution time: 40% faster
 - No more race conditions
+
+## See Also
+
+- `systematic-debugging`
+- `test-driven-development`