opencodekit 0.15.12 → 0.15.14

package/dist/template/.opencode/plans/1768385996691-silent-wizard.md

@@ -38,7 +38,16 @@ If memory returns high-confidence findings on this exact topic, synthesize and r
 | Priority | Tool | Use Case | Speed |
 |----------|------|----------|-------|
 | 1 | memory-search | Past research findings | Instant |
-| 2 | context7 | Official library docs | Fast |
+| Priority | Tool | Use Case | Speed |
+|----------|------|----------|-------|
+| 1 | memory-search | Past research findings | Instant |
+| 2 | context7_resolve-library-id | Resolve library names to IDs | Fast |
+| 3 | context7_query-docs | Official library docs | Fast |
+| 4 | codesearch | Exa Code API for SDK/library patterns | Fast |
+| 5 | grep-search | Cross-repo GitHub code search | Medium |
+| 6 | webfetch | Specific doc URLs, READMEs, changelogs | Medium |
+| 7 | opensrc + LSP | Clone & analyze source code | Slow |
+| 8 | websearch | Tutorials, blog posts, recent news | Slow |
 | 3 | codesearch | Usage patterns in real code | Fast |
 | 4 | gh_grep | Cross-repo deep code search | Medium |
 | 5 | webfetch | Specific doc URLs, READMEs, changelogs | Medium |
@@ -76,7 +85,8 @@ webfetch({ url: "https://docs.example.com/api/authentication", format: "markdown
 **When to use:**
 
 - User provides a specific URL
-- context7 returns a doc link worth fetching
+- context7_resolve-library-id returns a library ID
+- context7_query-docs returns a doc link worth fetching
 - Need CHANGELOG or release notes
 - GitHub README has details not in context7
 

package/dist/template/.opencode/skill/deep-research/SKILL.md

@@ -0,0 +1,385 @@
+---
+name: deep-research
+description: >
+  Use when analyzing unfamiliar code, implementing complex features, or entering thorough research mode.
+  Provides structured LSP exploration (all 9 operations), memory-first protocol, and confidence-scored findings.
+  Integrates with scout agent deep mode and research command --thorough flag.
+version: "1.0.0"
+license: MIT
+---
+
+# Deep Research - Comprehensive Code Understanding
+
+Systematic methodology for thorough codebase exploration before implementation.
+
+## When to Use This Skill
+
+Use deep research when:
+
+- **Complex implementation**: Feature touches 3+ files or unfamiliar modules
+- **Thorough mode**: `/research <topic> --thorough` or scout deep mode
+- **Pre-edit understanding**: Before modifying code you don't fully understand
+- **Architecture exploration**: Understanding how systems connect
+- **Debugging**: Tracing behavior through multiple layers
+
+**Don't use when:**
+
+- Quick syntax lookup (use quick mode instead)
+- Well-understood code with obvious changes
+- Time-constrained fixes (accept lower confidence)
+
+## Core Protocol
+
+### Phase 1: Memory First (Skip External If Found)
+
+```typescript
+// Search past research on this topic
+memory_search({ query: "<topic keywords>", limit: 5 });
+
+// Check for related observations
+memory_search({ query: "<topic> gotchas patterns", limit: 3 });
+
+// Load relevant project context
+memory_read({ file: "project/architecture" });
+memory_read({ file: "project/gotchas" });
+```
+
+**Stop condition**: If memory returns high-confidence findings on this exact topic, synthesize and skip to documentation. Only proceed to exploration if:
+
+- No relevant memory found
+- Memory findings are outdated or incomplete
+- Question requires fresh analysis
+
+### Phase 2: LSP Exploration (Delegate to Explore Agent)
+
+**Delegate to explore agent** for comprehensive LSP analysis instead of manual operations:
+
+```typescript
+task({
+  subagent_type: "explore",
+  description: "LSP analysis of <target>",
+  prompt: `Very thorough LSP analysis of <symbol/module>.
+
+Target files:
+- src/path/to/file.ts
+- src/related/module.ts
+
+Questions to answer:
+1. What is the type signature of <symbol>?
+2. What calls this function? (incoming calls)
+3. What does this function call? (outgoing calls)
+4. Where is this symbol referenced across the codebase?
+5. Are there interface implementations to consider?
+
+Return structured findings with file:line references.`,
+});
+```
+
+The explore agent will run:
+
+- `documentSymbol` - File structure overview
+- `goToDefinition` - Symbol definitions
+- `findReferences` - All usages across codebase
+- `hover` - Type info and documentation
+- `workspaceSymbol` - Workspace-wide search
+- Call hierarchy (incoming/outgoing calls)
+
+**When to run LSP manually instead:**
+
+- Single symbol lookup (quick mode)
+- Explore agent unavailable
+- Need specific operation only
+
+### Phase 3: Pattern Discovery
+
+```typescript
+// Find similar patterns in codebase
+grep({ pattern: "<relevant pattern>", include: "*.ts" });
+
+// Locate related files
+glob({ pattern: "src/**/*<topic>*" });
+
+// Check tests for usage examples
+glob({ pattern: "**/*.test.ts" });
+grep({ pattern: "<function name>", include: "*.test.ts" });
+```
+
+### Phase 4: External Research (If Needed)
+
+Only if internal exploration doesn't answer the question:
+
+```typescript
+// Official docs
+context7_resolve_library_id({ libraryName: "<lib>" });
+context7_query_docs({ libraryId: "<id>", topic: "<specific question>" });
+
+// Real-world patterns
+codesearch({ query: "<API usage pattern>", tokensNum: 5000 });
+grep_search({ query: "<code pattern>", language: "TypeScript" });
+```
+
+## Confidence Levels
+
+Score every finding:
+
+| Level      | Criteria                                   | Action               |
+| ---------- | ------------------------------------------ | -------------------- |
+| **High**   | LSP confirmed + tests exist + docs match   | Proceed confidently  |
+| **Medium** | LSP confirmed but untested or undocumented | Proceed with caution |
+| **Low**    | Inference only, no LSP/test confirmation   | Verify before using  |
+| **None**   | Speculation without evidence               | Discard              |
+
+## Stop Conditions
+
+Stop research when ANY of these are true:
+
+- All questions answered with Medium+ confidence
+- Tool budget exhausted (~100 calls for thorough)
+- Last 5 tool calls yielded no new insights
+- Blocked and need human input
+
+## Tool Budget Guidelines
+
+| Mode     | Tool Calls | Use Case                           |
+| -------- | ---------- | ---------------------------------- |
+| Quick    | ~10        | Single question, syntax lookup     |
+| Default  | ~30        | Moderate exploration               |
+| Thorough | ~100+      | Comprehensive analysis, new domain |
+
+Track your tool count and stop at budget.
+
+## Output Template
+
+Document findings in structured format:
+
+```markdown
+# Deep Research: [Topic]
+
+**Mode:** thorough
+**Tool calls:** [N]
+**Duration:** [time]
+
+## Questions Addressed
+
+1. [Q1] → Answered (High confidence)
+2. [Q2] → Partial (Medium confidence)
+3. [Q3] → Unanswered (needs: [what would resolve])
+
+## LSP Findings
+
+### Symbol: [name]
+
+**Location:** `src/path/file.ts:42`
+**Type:** [type signature from hover]
+
+**Callers (incoming):**
+
+- `src/a.ts:10` - [context]
+- `src/b.ts:25` - [context]
+
+**Dependencies (outgoing):**
+
+- `src/utils.ts:15` - [what it calls]
+
+**References:** [N] usages across [M] files
+
+---
+
+## Pattern Analysis
+
+### Pattern 1: [Name]
+
+**Files:** `src/a.ts`, `src/b.ts`
+**Confidence:** High
+**Evidence:** [LSP + grep findings]
+
+[Description of pattern]
+
+---
+
+## Key Findings
+
+### [Finding 1]
+
+**Confidence:** High
+**Sources:** LSP goToDefinition, findReferences
+**Evidence:** `src/file.ts:42-56`
+
+[Finding with code evidence]
+
+---
+
+## Recommendations
+
+Based on LSP analysis:
+
+1. [Recommendation 1] - because [LSP evidence]
+2. [Recommendation 2] - because [pattern found]
+
+## Open Items
+
+- [Remaining question] - needs: [specific tool/info]
+```
+
+## Integration Points
+
+### Scout Agent Deep Mode
+
+When scout enters deep mode, load this skill:
+
+```typescript
+skill({ name: "deep-research" });
+```
+
+Scout then follows the protocol for external + internal analysis.
+
+### Research Command --thorough
+
+When `/research <topic> --thorough` is invoked:
+
+```typescript
+skill({ name: "deep-research" });
+// Follow full protocol with ~100 tool budget
+```
+
+### Pre-Edit Verification
+
+Before any complex edit:
+
+```typescript
+skill({ name: "deep-research" });
+// Run Phase 2 (LSP) on all symbols being modified
+// Proceed only when all 9 operations complete
+```
+
+## Workflow Example
+
+**Scenario:** Understanding authentication middleware before adding rate limiting.
+
+```typescript
+// Phase 1: Memory check
+memory_search({ query: "authentication middleware rate limiting" });
+memory_read({ file: "project/architecture" });
+
+// Phase 2: Delegate LSP exploration to explore agent
+task({
+  subagent_type: "explore",
+  description: "Analyze auth middleware",
+  prompt: `Very thorough LSP analysis of authentication middleware.
+
+Target: src/middleware/auth.ts
+
+Questions:
+1. What functions are exported from auth.ts?
+2. What calls the auth middleware? (incoming calls)
+3. What does it depend on? (outgoing calls)
+4. Are there existing rate limiting patterns?
+
+Return file:line references for all findings.`,
+});
+
+// Phase 3: Pattern discovery (parallel with Phase 2)
+grep({ pattern: "middleware", include: "*.ts" });
+grep({ pattern: "rateLimit", include: "*.ts" });
+glob({ pattern: "src/middleware/*.ts" });
+
+// Phase 4: External (if patterns unclear)
+context7_resolve_library_id({ libraryName: "express" });
+context7_query_docs({ libraryId: "/expressjs/express", topic: "middleware" });
+
+// Document findings
+write({
+  filePath: ".beads/artifacts/<id>/research.md",
+  content: "# Deep Research: Auth Middleware...",
+});
+```
+
+## Anti-Patterns
+
+### DON'T: Skip LSP Exploration
+
+```typescript
+// Bad: Reading file without LSP analysis
+read({ filePath: "src/auth.ts" });
+// Then immediately editing...
+
+// Good: Delegate to explore agent first
+task({
+  subagent_type: "explore",
+  description: "Analyze auth.ts",
+  prompt: "Very thorough LSP analysis of src/auth.ts...",
+});
+// Then edit with understanding
+```
+
+### DON'T: Ignore Memory
+
+```typescript
+// Bad: Jumping straight to exploration
+grep({ pattern: "auth", include: "*.ts" });
+
+// Good: Check memory first
+memory_search({ query: "authentication patterns" });
+// Only explore if memory doesn't answer
+```
+
+### DON'T: Mix Confidence Levels
+
+```typescript
+// Bad: Treating speculation as fact
+"This function definitely handles X"; // Without LSP verification
+
+// Good: Explicit confidence
+"Based on LSP findReferences (High confidence): This function is called from...";
+"Inference (Low confidence): This might also handle X, needs verification";
+```
+
+### DON'T: Exceed Budget Without Stopping
+
+```typescript
+// Bad: 150 tool calls on thorough mode
+// Keep going indefinitely...
+
+// Good: Track and stop
+// Tool call 95: Still finding new insights, continue
+// Tool call 100: Stopping at budget, documenting partial findings
+```
+
+## Success Criteria
+
+Research is complete when:
+
+- [ ] Memory checked before exploration
+- [ ] All 9 LSP operations run on target symbols
+- [ ] Confidence scores assigned to all findings
+- [ ] Tool budget respected
+- [ ] Findings documented with evidence
+- [ ] Open items listed with resolution paths
+
+## Quick Reference
+
+```
+PROTOCOL:
+1. Memory first → skip if found
+2. Delegate LSP to @explore (very thorough)
+3. Patterns → grep + glob (parallel)
+4. External → only if needed
+
+DELEGATION:
+task({ subagent_type: "explore", prompt: "Very thorough LSP analysis..." })
+
+CONFIDENCE:
+High = LSP + tests + docs
+Medium = LSP only
+Low = inference
+None = discard
+
+BUDGET:
+quick ~10 | default ~30 | thorough ~100
+
+STOP WHEN:
+- Questions answered (Medium+)
+- Budget exhausted
+- 5 calls with no new insights
+- Blocked on human input
+```

package/dist/template/.opencode/skill/source-code-research/SKILL.md

@@ -362,20 +362,20 @@ If opensrc doesn't work:
 
 Source code research complements other tools:
 
-| Method         | Best For                   | Source Code Adds               |
-| -------------- | -------------------------- | ------------------------------ |
-| **Context7**   | API docs, official guides  | Implementation details         |
-| **codesearch** | Usage patterns in the wild | Canonical implementation       |
-| **gh_grep**    | Real-world examples        | How library itself works       |
-| **Web search** | Tutorials, blog posts      | Ground truth from source       |
-| **Codebase**   | Project-specific patterns  | How dependencies actually work |
+| Method          | Best For                   | Source Code Adds               |
+| --------------- | -------------------------- | ------------------------------ |
+| **Context7**    | API docs, official guides  | Implementation details         |
+| **codesearch**  | Usage patterns in the wild | Canonical implementation       |
+| **grep_search** | Real-world examples        | How library itself works       |
+| **Web search**  | Tutorials, blog posts      | Ground truth from source       |
+| **Codebase**    | Project-specific patterns  | How dependencies actually work |
 
 **Recommended flow:**
 
 1. Context7 - Check official docs
 2. Codebase - Check existing usage
 3. **Source code** - If still unclear, fetch source
-4. codesearch/gh_grep - See how others use it
+4. codesearch/grep_search - See how others use it
 5. Web search - Last resort for context
 
 ## Cleanup

package/dist/template/.opencode/skill/tool-priority/SKILL.md

@@ -180,9 +180,11 @@ glob ["src/**/*.ts", "tests/**/*.ts"]
 
 ## Research Tools
 
-| Tool           | Use When                                                |
-| -------------- | ------------------------------------------------------- |
-| **context7**   | Library docs (try first). Fast, external APIs.          |
-| **websearch**  | Docs not in Context7, recent releases, troubleshooting. |
-| **codesearch** | Real implementation patterns from GitHub.               |
-| **webfetch**   | Specific URL user provided.                             |
+| Tool                            | Use When                                                |
+| ------------------------------- | ------------------------------------------------------- |
+| **context7_resolve-library-id** | Resolve library names to IDs (try first).               |
+| **context7_query-docs**         | Query official library documentation. Fast.             |
+| **websearch**                   | Docs not in Context7, recent releases, troubleshooting. |
+| **codesearch**                  | Real implementation patterns from GitHub.               |
+| **grep-search**                 | Cross-repo code patterns via grep.app.                  |
+| **webfetch**                    | Specific URL user provided.                             |

package/dist/template/.opencode/tool/context7-query-docs.ts

@@ -0,0 +1,89 @@
+import { tool } from "@opencode-ai/plugin";
+
+// Context7 API v2 - https://context7.com/docs/api-guide
+const CONTEXT7_API = "https://context7.com/api/v2";
+
+export default tool({
+	description: `Query library documentation from Context7 using a library ID.
+
+Use when:
+- You have a library ID (from context7_resolve_library_id)
+- Need specific documentation about a library feature
+- Looking for API reference, examples, or setup instructions
+
+Always resolve library name to ID first with context7_resolve_library_id!
+
+Examples:
+  context7_query_docs({ libraryId: "/reactjs/react.dev", topic: "hooks" })
+  context7_query_docs({ libraryId: "/vercel/next.js", topic: "middleware" })
+  context7_query_docs({ libraryId: "/microsoft/TypeScript", topic: "generics" })
+`,
+	args: {
+		libraryId: tool.schema
+			.string()
+			.describe(
+				"Library ID from context7_resolve_library_id (e.g., '/reactjs/react.dev')",
+			),
+		topic: tool.schema
+			.string()
+			.describe("Documentation topic or feature to search for"),
+	},
+	execute: async (args) => {
+		const { libraryId, topic } = args;
+
+		if (!libraryId || libraryId.trim() === "") {
+			return "Error: libraryId is required (use context7-resolve-library-id first)";
+		}
+
+		if (!topic || topic.trim() === "") {
+			return "Error: topic is required (e.g., 'hooks', 'setup', 'API reference')";
+		}
+
+		try {
+			// Query Context7 documentation - GET /api/v2/context
+			// Returns text format by default which is better for LLM consumption
+			const url = new URL(`${CONTEXT7_API}/context`);
+			url.searchParams.set("libraryId", libraryId);
+			url.searchParams.set("query", topic);
+
+			// Add API key if available (recommended for higher rate limits)
+			const apiKey = process.env.CONTEXT7_API_KEY;
+			const headers: HeadersInit = {
+				Accept: "text/plain",
+				"User-Agent": "OpenCode/1.0",
+			};
+
+			if (apiKey) {
+				headers.Authorization = `Bearer ${apiKey}`;
+			}
+
+			const response = await fetch(url.toString(), { headers });
+
+			if (!response.ok) {
+				if (response.status === 401) {
+					return `Error: Invalid CONTEXT7_API_KEY. Get a free key at https://context7.com/dashboard`;
+				}
+				if (response.status === 404) {
+					return `Error: Library not found: ${libraryId}\n\nUse context7-resolve-library-id first to find the correct ID.`;
+				}
+				if (response.status === 429) {
+					return `Error: Rate limit exceeded. Get a free API key at https://context7.com/dashboard for higher limits.`;
+				}
+				return `Error: Context7 API returned ${response.status}`;
+			}
+
+			const content = await response.text();
+
+			if (!content || content.trim() === "") {
+				return `No documentation found for "${topic}" in ${libraryId}.\n\nTry:\n- Simpler terms (e.g., "useState" instead of "state management")\n- Different topic spelling\n- Broader topics like "API reference" or "getting started"`;
+			}
+
+			return `# Documentation: ${topic} (${libraryId})
+
+${content}`;
+		} catch (error: unknown) {
+			const message = error instanceof Error ? error.message : String(error);
+			return `Error querying documentation: ${message}`;
+		}
+	},
+});

package/dist/template/.opencode/tool/context7-resolve-library-id.ts

@@ -0,0 +1,113 @@
+import { tool } from "@opencode-ai/plugin";
+
+// Context7 API v2 - https://context7.com/docs/api-guide
+const CONTEXT7_API = "https://context7.com/api/v2";
+
+interface LibraryInfo {
+	id: string;
+	title: string;
+	description?: string;
+	totalSnippets?: number;
+	trustScore?: number;
+	benchmarkScore?: number;
+	versions?: string[];
+}
+
+interface SearchResponse {
+	results: LibraryInfo[];
+}
+
+export default tool({
+	description: `Resolve a library name to its Context7 ID for documentation lookup.
+
+Use when:
+- You need to find the exact library ID format for a package
+- Starting a documentation search (get the ID first, then query docs)
+- Normalizing library names (e.g., "react" → "/reactjs/react.dev")
+
+Examples:
+  context7_resolve_library_id({ libraryName: "react" })
+  context7_resolve_library_id({ libraryName: "vue", query: "composition API" })
+  context7_resolve_library_id({ libraryName: "nextjs" })
+`,
+	args: {
+		libraryName: tool.schema
+			.string()
+			.describe(
+				"Library name to resolve (e.g., 'react', 'lodash', 'typescript')",
+			),
+		query: tool.schema
+			.string()
+			.optional()
+			.describe("Optional context for the search (improves relevance ranking)"),
+	},
+	execute: async (args) => {
+		const { libraryName, query = "documentation" } = args;
+
+		if (!libraryName || libraryName.trim() === "") {
+			return "Error: libraryName is required";
+		}
+
+		try {
+			// Query Context7 library search - GET /api/v2/libs/search
+			const url = new URL(`${CONTEXT7_API}/libs/search`);
+			url.searchParams.set("libraryName", libraryName);
+			url.searchParams.set("query", query);
+
+			// Add API key if available (recommended for higher rate limits)
+			const apiKey = process.env.CONTEXT7_API_KEY;
+			const headers: HeadersInit = {
+				Accept: "application/json",
+				"User-Agent": "OpenCode/1.0",
+			};
+
+			if (apiKey) {
+				headers.Authorization = `Bearer ${apiKey}`;
+			}
+
+			const response = await fetch(url.toString(), { headers });
+
+			if (!response.ok) {
+				if (response.status === 401) {
+					return `Error: Invalid CONTEXT7_API_KEY. Get a free key at https://context7.com/dashboard`;
+				}
+				if (response.status === 429) {
+					return `Error: Rate limit exceeded. Get a free API key at https://context7.com/dashboard for higher limits.`;
+				}
+				return `Error: Context7 API returned ${response.status}`;
+			}
+
+			const data = (await response.json()) as SearchResponse;
+			const libraries = data.results || [];
+
+			if (!libraries || libraries.length === 0) {
+				return `No libraries found matching: ${libraryName}\n\nTry:\n- Different library name\n- Check spelling\n- Use official package name`;
+			}
+
+			const formatted = libraries
+				.slice(0, 5)
+				.map((lib, i) => {
+					const desc = lib.description
+						? `\n   ${lib.description.slice(0, 100)}...`
+						: "";
+					const snippets = lib.totalSnippets
+						? ` (${lib.totalSnippets} snippets)`
+						: "";
+					const score = lib.benchmarkScore
+						? ` [score: ${lib.benchmarkScore}]`
+						: "";
+					return `${i + 1}. **${lib.title}** → \`${lib.id}\`${snippets}${score}${desc}`;
+				})
+				.join("\n\n");
+
+			return `Found ${libraries.length} libraries matching "${libraryName}":
+
+${formatted}
+
+**Next step**: Use \`context7-query-docs({ libraryId: "${libraries[0].id}", topic: "your topic" })\` to fetch documentation.`;
+		} catch (error: unknown) {
+			const message = error instanceof Error ? error.message : String(error);
+			return `Error resolving library: ${message}`;
+		}
+	},
+});