opencodekit 0.17.4 → 0.17.5

package/dist/index.js

@@ -759,7 +759,7 @@ var cac = (name = "") => new CAC(name);
 // package.json
 var package_default = {
   name: "opencodekit",
-  version: "0.17.4",
+  version: "0.17.5",
   description: "CLI tool for bootstrapping and managing OpenCodeKit projects",
   keywords: ["agents", "cli", "mcp", "opencode", "opencodekit", "template"],
   license: "MIT",

package/dist/template/.opencode/.version

@@ -0,0 +1 @@
+0.17.5

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

@@ -11,7 +11,7 @@
     "type-check": "tsc --noEmit"
   },
   "dependencies": {
-    "@opencode-ai/plugin": "1.1.62"
+    "@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/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" })

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

@@ -73,13 +73,74 @@ export default tool({
 	- Stores in SQLite with FTS5 index for fast search
 	- Supports enhanced schema: facts, subtitle, files_read/files_modified
 	
-	Example:
+	Confidence guidance:
+	- high: verified by tests, logs, or direct inspection (default)
+	- medium: likely, but not fully verified
+	- low: uncertain or speculative
+	
+	Type-specific examples:
+	decision
 	observation({
 	  type: "decision",
 	  title: "Use JWT for auth",
-	  narrative: "Decided to use JWT tokens because...",
-	  facts: "stateless, scalable, industry standard",
-	  concepts: "authentication, jwt, security",
+	  narrative: "Chose JWT for stateless auth across services.",
+	  facts: "stateless, scalable",
+	  concepts: "authentication, jwt",
+	  confidence: "high"
+	})
+	
+	bugfix
+	observation({
+	  type: "bugfix",
+	  title: "Fix null pointer on login",
+	  narrative: "Guarded optional user in src/auth.ts:42 to prevent crash.",
+	  files_modified: "src/auth.ts",
+	  concepts: "auth, null-check",
+	  confidence: "high"
+	})
+	
+	feature
+	observation({
+	  type: "feature",
+	  title: "Add CLI --dry-run",
+	  narrative: "Introduce dry-run mode to show planned changes without writing.",
+	  files_modified: "src/commands/init.ts",
+	  concepts: "cli, ux",
+	  confidence: "medium"
+	})
+	
+	pattern
+	observation({
+	  type: "pattern",
+	  title: "Use zod for input validation",
+	  narrative: "All command inputs validated with zod schemas before execute.",
+	  concepts: "validation, zod",
+	  confidence: "high"
+	})
+	
+	discovery
+	observation({
+	  type: "discovery",
+	  title: "Build copies .opencode/ to dist/template/",
+	  narrative: "Found rsync step in build.ts that bundles .opencode/.",
+	  files_read: "build.ts",
+	  confidence: "high"
+	})
+	
+	learning
+	observation({
+	  type: "learning",
+	  title: "Bun test respects --watch",
+	  narrative: "Observed bun test --watch keeps runner active during edits.",
+	  confidence: "medium"
+	})
+	
+	warning
+	observation({
+	  type: "warning",
+	  title: "Do not edit dist/ directly",
+	  narrative: "dist/ is built output and overwritten on build.",
+	  concepts: "build, generated",
 	  confidence: "high"
 	})`,
 	args: {

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

@@ -13,17 +13,25 @@ const execFileAsync = promisify(execFile);
 export default tool({
 	description: `Swarm orchestration for parallel task execution.
 
-Operations:
+Operations (choose by op):
 - plan: Analyze task for parallel execution
+  Examples:
+    swarm({ op: "plan", task: "Investigate auth failures", files: "src/auth.ts,src/api.ts" })
+    swarm({ op: "plan", task: "Refactor utils" })
 - monitor: Track worker progress
+  Examples:
+    swarm({ op: "monitor", team: "frontend", action: "status" })
+    swarm({ op: "monitor", team: "frontend", action: "update", worker_id: "w1", phase: "build", progress: 60, status: "working" })
 - delegate: Create delegation packet
+  Examples:
+    swarm({ op: "delegate", bead_id: "B-123", title: "Add caching", outcome: "Cache layer in place", checks: "lint,typecheck" })
+    swarm({ op: "delegate", bead_id: "B-123", outcome: "Bug fixed", must_do: "add test", must_not: "change API" })
 - sync: Bridge Beads tasks to OpenCode todos
+  Examples:
+    swarm({ op: "sync", action: "push", filter: "open" })
+    swarm({ op: "sync", action: "pull" })
 
-Usage:
-  swarm({ op: "plan", task: "..." })
-  swarm({ op: "monitor", team: "...", action: "status" })
-  swarm({ op: "delegate", bead_id: "...", outcome: "..." })
-  swarm({ op: "sync", action: "push" })`,
+Tip: Each example only applies when the matching op is used.`,
 
 	args: {
 		op: tool.schema

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencodekit",
-	"version": "0.17.4",
+	"version": "0.17.5",
 	"description": "CLI tool for bootstrapping and managing OpenCodeKit projects",
 	"keywords": ["agents", "cli", "mcp", "opencode", "opencodekit", "template"],
 	"license": "MIT",