opencodekit 0.17.3 → 0.17.5

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

@@ -11,7 +11,7 @@
     "type-check": "tsc --noEmit"
   },
   "dependencies": {
-    "@opencode-ai/plugin": "1.1.60"
+    "@opencode-ai/plugin": "1.1.65"
   },
   "devDependencies": {
     "@types/node": "^25.1.0",

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

@@ -7,7 +7,67 @@ import type { Plugin } from "@opencode-ai/plugin";
 import { tool } from "@opencode-ai/plugin/tool";
 
 export const SessionsPlugin: Plugin = async ({ client }) => {
+	const getProjectContext = () =>
+		"Project context: OpenCodeKit CLI repo; sessions often mention .opencode/ plugins, commands, memory rules, beads IDs, and Bun/TypeScript constraints.";
+
+	const getBestPractices = () =>
+		"Best practices: Prefer recent sessions, keep queries focused, and reference exact file paths or IDs found in the session.";
+
 	return {
+		"tool.definition": async (input, output) => {
+			const toolID = input.toolID;
+			const projectContext = getProjectContext();
+			const commonBestPractices = getBestPractices();
+
+			switch (toolID) {
+				case "list_sessions": {
+					output.description = `${output.description}
+
+${projectContext}
+${commonBestPractices}
+
+Recent session examples:
+list_sessions({ since: "this week", limit: 5 })
+list_sessions({ since: "yesterday", limit: 3 })`;
+					break;
+				}
+				case "read_session": {
+					output.description = `${output.description}
+
+${projectContext}
+Best practices: Use "last" for most recent context; add a short focus keyword (e.g., "sessions", "plugin", "beads") to reduce noise.
+
+Recent session examples:
+read_session({ session_reference: "last" })
+read_session({ session_reference: "last", focus: "sessions plugin" })`;
+					break;
+				}
+				case "search_session": {
+					output.description = `${output.description}
+
+${projectContext}
+Best practices: Start with 1-2 specific keywords, then read the top match for full context.
+
+Recent session examples:
+search_session({ query: "sessions plugin", limit: 5 })
+search_session({ query: ".opencode", limit: 5 })`;
+					break;
+				}
+				case "summarize_session": {
+					output.description = `${output.description}
+
+${projectContext}
+Best practices: Summarize long sessions only after confirming the ID from list_sessions; check back later for the generated summary.
+
+Recent session examples:
+summarize_session({ session_id: "abc123" }) // from list_sessions
+summarize_session({ session_id: "def456" })`;
+					break;
+				}
+				default:
+					break;
+			}
+		},
 		tool: {
 			list_sessions: tool({
 				description: `List OpenCode sessions with metadata.

package/dist/template/.opencode/plugin/skill-mcp.ts

@@ -338,7 +338,53 @@ export const SkillMcpPlugin: Plugin = async ({ directory }) => {
 		state.clients.clear();
 	}
 
+	function buildLoadedMcpDetails(): {
+		summary: string;
+		examples: string;
+	} {
+		const loadedEntries = Array.from(state.loadedSkills.entries());
+		if (loadedEntries.length === 0) {
+			return {
+				summary:
+					"Loaded MCP skills: (none). Load a skill with MCP config via skill() before using this tool.",
+				examples:
+					'Examples:\n- skill("playwright")\n- skill_mcp(skill_name="playwright", list_tools=true)',
+			};
+		}
+
+		const summaryLines = ["Loaded MCP skills and servers:"];
+		const examples: string[] = [];
+		for (const [skillName, config] of loadedEntries) {
+			const serverNames = Object.keys(config);
+			summaryLines.push(`- ${skillName}: ${serverNames.join(", ")}`);
+
+			const serverHint =
+				serverNames.length > 1 ? `, mcp_name="${serverNames[0]}"` : "";
+			examples.push(
+				`- skill_mcp(skill_name="${skillName}", list_tools=true${serverHint})`,
+			);
+		}
+
+		return {
+			summary: summaryLines.join("\n"),
+			examples: `Examples:\n${examples.slice(0, 3).join("\n")}`,
+		};
+	}
+
 	return {
+		"tool.definition": async (input, output) => {
+			const toolID = input.toolID;
+			if (toolID === "skill_mcp") {
+				const details = buildLoadedMcpDetails();
+				output.description = `${output.description}\n\n${details.summary}\n\n${details.examples}`;
+			}
+			if (toolID === "skill_mcp_status") {
+				output.description = `${output.description}
+
+Connection status: Shows currently active MCP server connections from skill-embedded MCP servers.
+Example: skill_mcp_status({})`;
+			}
+		},
 		tool: {
 			skill_mcp: tool({
 				description: `Invoke MCP tools from skill-embedded MCP servers.
@@ -399,6 +445,8 @@ The skill must be loaded first via the skill() tool to register its MCP config.`
 						});
 					}
 
+					state.loadedSkills.set(skill_name, mcpConfig);
+
 					// Determine which MCP server to use
 					const serverNames = Object.keys(mcpConfig);
 					const targetServer = mcp_name || serverNames[0];

package/dist/template/.opencode/skill/context-management/SKILL.md

@@ -1,20 +1,47 @@
 ---
 name: context-management
-description: Use when context is growing large, needing to prune/distill tool outputs, or managing conversation size - covers distill and prune tools with context budgets
+description: Use when context is growing large, needing to prune/distill tool outputs, or managing conversation size - covers DCP slash commands and context budgets
 ---
 
 # Context Management
 
-Manage conversation context to prevent degradation. Uses distill and prune tools.
+Manage conversation context to prevent degradation. Uses DCP plugin.
 
-## The Two Tools
+## DCP Integration
 
-| Tool      | Purpose                       | When to Use                              |
-| --------- | ----------------------------- | ---------------------------------------- |
-| `distill` | Extract key info, then remove | Large outputs with valuable details      |
-| `prune`   | Remove tool outputs (no save) | Noise, irrelevant reads, superseded info |
+This project uses the **DCP (Dynamic Context Pruning)** plugin. Prefer slash commands over tool calls for better reliability.
 
-**Distill is the favored tool.** It preserves knowledge while freeing context. Prune is for pure noise removal.
+### Slash Commands (Recommended)
+
+| Command                 | Purpose                                  | When to Use                         |
+| ----------------------- | ---------------------------------------- | ----------------------------------- |
+| `/dcp compress [focus]` | Collapse conversation range into summary | Phase complete, research done       |
+| `/dcp sweep [count]`    | Prune all tools since last user message  | Cleanup noise, quick prune          |
+| `/dcp distill [focus]`  | Distill key findings before removing     | Large outputs with valuable details |
+| `/dcp context`          | Show token breakdown by category         | Check context usage                 |
+| `/dcp stats`            | Show cumulative pruning stats            | Review efficiency                   |
+
+### Tool Calls (Fallback)
+
+Use tool calls when slash commands aren't suitable:
+
+| Tool       | Purpose                       | When to Use                              |
+| ---------- | ----------------------------- | ---------------------------------------- |
+| `distill`  | Extract key info, then remove | Large outputs with valuable details      |
+| `prune`    | Remove tool outputs (no save) | Noise, irrelevant reads, superseded info |
+| `compress` | Collapse conversation range   | When slash command fails                 |
+
+**Note:** Compress tool has boundary matching issues. Prefer `/dcp compress` slash command.
+
+## DCP Auto-Strategies
+
+DCP runs these automatically (zero LLM cost):
+
+- **Deduplication** — removes duplicate tool calls (same tool + same args)
+- **Supersede Writes** — removes write inputs when file is later read
+- **Purge Errors** — removes errored tool inputs after 4 turns
+
+You don't need to manually prune these.
 
 ## When to Evaluate
 
@@ -94,8 +121,15 @@ Auto-protected from pruning:
 ## Quick Reference
 
 ```
-DISTILL: Save + remove → distill({ targets: [{ id, distillation }] })
-PRUNE:   Remove noise  → prune({ ids: [...] })
+DCP SLASH COMMANDS (preferred):
+/dcp compress [focus]  → Collapse range into summary
+/dcp distill [focus]   → Distill key findings
+/dcp sweep [count]     → Prune all since last user
+/dcp context           → Show token breakdown
+
+TOOL CALLS (fallback):
+distill({ targets: [{ id, distillation }] })
+prune({ ids: [...] })
 
 BUDGET: <50k start → 50-100k mid → >100k distill → >150k restart
 TIMING: Manage at turn START, not turn END

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

@@ -0,0 +1,182 @@
+---
+name: obsidian
+description: Use when working with Obsidian vault via MCP - read/write notes, search, tag management, and vault operations
+mcp:
+  server: @mauricio.wolff/mcp-obsidian
+  args: ["{env:OBSIDIAN_VAULT_PATH}"]
+---
+
+# Obsidian Vault (MCP)
+
+MCP server for safe Obsidian vault access. Read/write notes, search, manage tags.
+
+## Available Tools
+
+### Read Operations
+
+| Tool                  | Purpose                           | Arguments                                         |
+| --------------------- | --------------------------------- | ------------------------------------------------- |
+| `read_note`           | Read note with parsed frontmatter | `path`, `prettyPrint`                             |
+| `read_multiple_notes` | Batch read (max 10)               | `paths[]`, `includeContent`, `includeFrontmatter` |
+| `get_frontmatter`     | Extract only frontmatter          | `path`                                            |
+| `get_notes_info`      | Get metadata without content      | `paths[]`                                         |
+| `list_directory`      | List files and directories        | `path`                                            |
+
+### Write Operations
+
+| Tool                 | Purpose                               | Arguments                                |
+| -------------------- | ------------------------------------- | ---------------------------------------- |
+| `write_note`         | Write note (overwrite/append/prepend) | `path`, `content`, `frontmatter`, `mode` |
+| `update_frontmatter` | Update frontmatter only               | `path`, `frontmatter`, `merge`           |
+| `delete_note`        | Delete note (requires confirmation)   | `path`, `confirmPath`                    |
+| `move_note`          | Move/rename note                      | `oldPath`, `newPath`, `overwrite`        |
+
+### Search & Tags
+
+| Tool           | Purpose                       | Arguments                                              |
+| -------------- | ----------------------------- | ------------------------------------------------------ |
+| `search_notes` | Search by content/frontmatter | `query`, `limit`, `searchContent`, `searchFrontmatter` |
+| `manage_tags`  | Add/remove/list tags          | `path`, `operation`, `tags[]`                          |
+
+## Write Modes
+
+| Mode        | Description                           |
+| ----------- | ------------------------------------- |
+| `overwrite` | Replace entire file content (default) |
+| `append`    | Add content to end of file            |
+| `prepend`   | Add content to beginning of file      |
+
+## Usage Examples
+
+### Read Notes
+
+```typescript
+// Read a single note
+skill_mcp({
+  skill_name: "obsidian",
+  tool_name: "read_note",
+  arguments: '{"path": "projects/project-ideas.md"}',
+});
+
+// Read multiple notes
+skill_mcp({
+  skill_name: "obsidian",
+  tool_name: "read_multiple_notes",
+  arguments: '{"paths": ["note1.md", "note2.md"], "includeContent": true}',
+});
+
+// List directory
+skill_mcp({
+  skill_name: "obsidian",
+  tool_name: "list_directory",
+  arguments: '{"path": "Projects"}',
+});
+```
+
+### Write Notes
+
+```typescript
+// Create new note (overwrite)
+skill_mcp({
+  skill_name: "obsidian",
+  tool_name: "write_note",
+  arguments: `{
+    "path": "meeting-notes.md",
+    "content": "# Team Meeting\\n\\n## Agenda\\n- Project updates",
+    "frontmatter": {"title": "Team Meeting", "date": "2025-02-13", "tags": ["meetings", "team"]},
+    "mode": "overwrite"
+  }`,
+});
+
+// Append to existing note
+skill_mcp({
+  skill_name: "obsidian",
+  tool_name: "write_note",
+  arguments:
+    '{"path": "daily-log.md", "content": "\\n\\n## 3:00 PM\\n- Completed review", "mode": "append"}',
+});
+```
+
+### Search & Tags
+
+```typescript
+// Search notes
+skill_mcp({
+  skill_name: "obsidian",
+  tool_name: "search_notes",
+  arguments: '{"query": "machine learning", "limit": 5, "searchContent": true}',
+});
+
+// Add tags
+skill_mcp({
+  skill_name: "obsidian",
+  tool_name: "manage_tags",
+  arguments: '{"path": "research-notes.md", "operation": "add", "tags": ["important", "ai"]}',
+});
+
+// List tags
+skill_mcp({
+  skill_name: "obsidian",
+  tool_name: "manage_tags",
+  arguments: '{"path": "research-notes.md", "operation": "list"}',
+});
+```
+
+### Delete (Safe)
+
+```typescript
+// Delete requires confirmation (both paths must match)
+skill_mcp({
+  skill_name: "obsidian",
+  tool_name: "delete_note",
+  arguments: '{"path": "old-draft.md", "confirmPath": "old-draft.md"}',
+});
+```
+
+## Configuration
+
+### Environment Variable
+
+Set your vault path:
+
+```bash
+export OBSIDIAN_VAULT_PATH="/path/to/your/obsidian/vault"
+```
+
+Or configure in opencode.json:
+
+```json
+{
+  "mcp": {
+    "obsidian": {
+      "command": "npx",
+      "args": ["@mauricio.wolff/mcp-obsidian", "/path/to/vault"]
+    }
+  }
+}
+```
+
+## Security
+
+- Path traversal protection: prevents access outside vault
+- Auto-excludes: `.obsidian`, `.git`, `node_modules`
+- Frontmatter validation: blocks dangerous objects
+- Confirmation required for deletions
+
+## Common Use Cases
+
+| Task                 | Tool             | Example                                                                       |
+| -------------------- | ---------------- | ----------------------------------------------------------------------------- |
+| List vault files     | `list_directory` | `list_directory({ path: "" })`                                                |
+| Read specific note   | `read_note`      | `read_note({ path: "tasks/project.md" })`                                     |
+| Create/update note   | `write_note`     | `write_note({ path: "new.md", content: "...", mode: "overwrite" })`           |
+| Search notes         | `search_notes`   | `search_notes({ query: "API", limit: 10 })`                                   |
+| Add tags             | `manage_tags`    | `manage_tags({ path: "note.md", operation: "add", tags: ["urgent"] })`        |
+| Append to daily note | `write_note`     | `write_note({ path: "daily/2025-02-13.md", content: "...", mode: "append" })` |
+
+## Tips
+
+- Use `prettyPrint: true` for debugging, `false` (default) for production
+- Batch reads with `read_multiple_notes` (max 10)
+- Search supports content and frontmatter filtering
+- Frontmatter is auto-parsed on read

package/dist/template/.opencode/skill/obsidian/mcp.json

@@ -0,0 +1,22 @@
+{
+	"obsidian": {
+		"command": "npx",
+		"args": ["-y", "@mauricio.wolff/mcp-obsidian", "{env:OBSIDIAN_VAULT_PATH}"],
+		"env": {
+			"OBSIDIAN_VAULT_PATH": "{env:OBSIDIAN_VAULT_PATH}"
+		},
+		"includeTools": [
+			"read_note",
+			"read_multiple_notes",
+			"get_frontmatter",
+			"get_notes_info",
+			"list_directory",
+			"write_note",
+			"update_frontmatter",
+			"delete_note",
+			"move_note",
+			"search_notes",
+			"manage_tags"
+		]
+	}
+}

package/dist/template/.opencode/skill/structured-edit/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: structured-edit
+description: Use when editing files to reduce str_replace failures - combines LSP location with read-verify-edit pattern for reliable edits
+---
+
+# Structured Edit Protocol
+
+## Overview
+
+The `str_replace` edit tool is the #1 source of failures in LLM coding. Models reproduce content with subtle differences (whitespace, encoding, line endings) causing "string not found" errors.
+
+**Core principle:** Don't guess content — locate, read, verify, then edit.
+
+## Why This Exists
+
+`str_replace` failures happen when:
+
+| Cause                | Example                                    |
+| -------------------- | ------------------------------------------ |
+| Whitespace mismatch  | Tabs vs spaces, trailing spaces            |
+| Content changed      | File modified since last read              |
+| Multiple matches     | Same string appears twice in file          |
+| Encoding differences | Line endings (CRLF vs LF), invisible chars |
+| Stale context        | Editing from memory instead of fresh read  |
+
+**Result:** Wasted tokens on retries, frustrated developers, broken workflows.
+
+## The Protocol
+
+### Step 1: LOCATE
+
+Use LSP to find exact positions instead of guessing:
+
+```typescript
+// Find where a function is defined
+lsp({ operation: "goToDefinition", filePath, line, character });
+
+// Find all references to a symbol
+lsp({ operation: "findReferences", filePath, line, character });
+
+// Get all symbols in a file
+lsp({ operation: "documentSymbol", filePath, line: 1, character: 1 });
+
+// Search for symbol across workspace
+lsp({ operation: "workspaceSymbol", filePath, line: 1, character: 1 });
+```
+
+### Step 2: READ
+
+Get fresh file content at the located position:
+
+```typescript
+// Read context around target line
+read({ filePath, offset: line - 10, limit: 30 });
+```
+
+**Always include context** — don't just read the target line.
+
+### Step 3: VERIFY
+
+Confirm expected content exists at the location:
+
+```typescript
+// Check that what you expect is actually there
+if (!content.includes(expectedSubstring)) {
+  // STOP — investigate before proceeding
+}
+```
+
+### Step 4: EDIT
+
+Apply minimal, scoped change with unique context:
+
+```typescript
+// Include enough surrounding lines for uniqueness
+edit({
+  filePath,
+  oldString: "  // unique context before\n  targetLine\n  // unique context after",
+  newString: "  // unique context before\n  modifiedLine\n  // unique context after",
+});
+```
+
+**Guidelines:**
+
+- Include 2-3 lines before/after for uniqueness
+- Never use just the target line
+- Keep oldString minimal but unique
+
+### Step 5: CONFIRM
+
+Verify the edit succeeded:
+
+```typescript
+// Read back the modified section
+read({ filePath, offset: line - 5, limit: 15 });
+
+// Confirm content matches intent
+```
+
+## Red Flags — STOP
+
+If you catch yourself:
+
+- Editing without reading first
+- Assuming content hasn't changed
+- Using large multi-line oldString values
+- Skipping the verify step
+- Guessing line numbers without LSP
+
+**STOP.** Return to Step 1.
+
+## Best Practices
+
+### File Size Matters
+
+From research on the "harness problem":
+
+| File Size     | Strategy                                   |
+| ------------- | ------------------------------------------ |
+| < 100 lines   | Full rewrite often easier than str_replace |
+| 100-400 lines | Structured edit with good context          |
+| > 400 lines   | Strongly prefer structured edits           |
+
+**Prefer smaller files** — composition over monoliths.
+
+### Unique Context Selection
+
+```typescript
+// BAD: Non-unique, whitespace-sensitive
+oldString: "return result;";
+
+// GOOD: Unique with surrounding context
+oldString: "  // Calculate final value\n  const result = compute(input);\n  return result;";
+```
+
+### When to Use LSP vs Direct
+
+| Scenario                  | Approach              |
+| ------------------------- | --------------------- |
+| Finding function/class    | LSP goToDefinition    |
+| Finding all usages        | LSP findReferences    |
+| Modifying specific symbol | LSP + structured edit |
+| Large refactoring         | Consider full rewrite |
+| Simple one-line change    | Direct edit OK        |
+
+## Integration with Other Skills
+
+**Use with:**
+
+- `verification-before-completion` — Always verify edits succeeded
+- `systematic-debugging` — When edit failures indicate deeper issues
+- `defense-in-depth` — Add validation after structural changes
+
+## Quick Reference
+
+```
+LOCATE  → lsp({ operation: "goToDefinition" | "findReferences", ... })
+READ    → read({ filePath, offset: line-10, limit: 30 })
+VERIFY  → Check expected content exists
+EDIT    → edit({ oldString: "...unique context...", newString: "..." })
+CONFIRM → read() again to verify success
+```
+
+## The Bottom Line
+
+**Don't trust your memory. Don't guess content. Locate, read, verify, edit, confirm.**
+
+This protocol eliminates the #1 source of LLM coding failures.

package/dist/template/.opencode/tool/action-queue.ts

@@ -237,10 +237,15 @@ Returns a consumable queue with:
 - ready tasks
 - idle workers
 
-Operations:
-- status: Read last stored queue snapshot
-- refresh: Recompute queue from Beads + swarm progress and store snapshot
-- clear: Clear stored queue snapshot`,
+Operations with context-aware hints:
+- status: Read last stored queue snapshot. Use for quick checks or when you just refreshed and want a stable view without re-scanning.
+- refresh: Recompute queue from Beads + swarm progress and store snapshot. Use when work has changed (new beads, workers progressed, approvals resolved) or when status shows stale counts.
+- clear: Clear stored queue snapshot. Use when you want to force a clean slate before a fresh refresh or when stale data is confusing the queue view.
+
+Examples:
+- You see pending approvals but know they were resolved: run refresh to rebuild from live worker progress.
+- You want a quick glance during a long session: run status to reuse the last snapshot.
+- You suspect the snapshot is corrupted or out of date: run clear, then refresh to rebuild from scratch.`,
 	args: {
 		op: tool.schema
 			.enum(["status", "refresh", "clear"])

package/dist/template/.opencode/tool/memory-search.ts

@@ -188,18 +188,23 @@ function formatFallbackResults(
 }
 
 export default tool({
-	description: `Search observations using FTS5 full-text search.
+	description: `Search memory across observations and markdown archives.
 	
 	Purpose:
-	- Fast, ranked search across all observations in SQLite
+	- Fast, ranked search across all observations in SQLite (when FTS5 is available)
 	- Returns compact index (~50-100 tokens per result) for progressive disclosure
 	- Use memory-get for full details after identifying relevant observations
 	
-	Search modes:
-	- "observations" (default): Search SQLite with FTS5 ranking
-	- "handoffs", "research", "templates": Search specific markdown directories
-	- "beads": Search .beads/artifacts
-	- "all": Search everything (SQLite + markdown files)
+	FTS5 availability:
+	- Auto-detected at runtime; if unavailable, observation searches fall back to file scan
+	
+	Search modes and hints:
+	- "observations" (default): Best for decisions, bugs, learnings; uses FTS5 ranking when available
+	- "handoffs": Use for past session handoffs and summaries
+	- "research": Use for research notes and external findings
+	- "templates": Use for memory templates and boilerplate references
+	- "beads": Use for task artifacts in .beads/artifacts
+	- "all": Use when you are unsure where info lives; searches SQLite + markdown + beads
 	
 	Example:
 	memory-search({ query: "authentication" })