opencodekit 0.15.12 → 0.15.14

package/README.md

@@ -80,8 +80,8 @@ Background Plugins:
 Supporting:
   • 30+ Skills (domain expertise loaded on-demand)
   • 26+ Commands (workflow shortcuts)
-  • 3 MCP Services (context7, exa, gh_grep) + skill-embedded MCPs
-  • Custom Tools (memory-*, observation, ast-grep, lsp-*)
+  • 3 MCP Services (context7, exa) + grep-search tool + skill-embedded MCPs
+  • Custom Tools (memory-*, observation, grep-search, lsp-*)
   • Beads task tracking (`bd` CLI for multi-session workflows)
   • Manual Handoffs (clean phase transitions)
 ```
@@ -223,9 +223,9 @@ You've successfully set up OpenCodeKit when:
 - ✅ Skills load on-demand (30+ skills)
 - ✅ Delegation is clear (build → specialized subagents)
 - ✅ `/handoff` creates portable bundles (.opencode/memory/handoffs/)
-- ✅ MCP services configured (context7, gh_grep + skill-embedded)
+- ✅ Tools configured (context7, grep-search + skill-embedded MCP)
 - ✅ Background plugins active (enforcer, compactor, truncator)
-- ✅ Custom tools available (memory-_, observation, ast-grep, lsp-_)
+- ✅ Custom tools available (memory-_, observation, grep-search, lsp-_)
 - ✅ Environment variables set (.opencode/.env with API keys)
 
 ---

package/dist/index.js

@@ -750,9 +750,16 @@ var cac = (name = "") => new CAC(name);
 // package.json
 var package_default = {
   name: "opencodekit",
-  version: "0.15.12",
+  version: "0.15.14",
   description: "CLI tool for bootstrapping and managing OpenCodeKit projects",
-  keywords: ["agents", "cli", "mcp", "opencode", "opencodekit", "template"],
+  keywords: [
+    "agents",
+    "cli",
+    "mcp",
+    "opencode",
+    "opencodekit",
+    "template"
+  ],
   license: "MIT",
   author: "OpenCodeKit",
   repository: {
@@ -762,7 +769,10 @@ var package_default = {
   bin: {
     ock: "dist/index.js"
   },
-  files: ["dist", "README.md"],
+  files: [
+    "dist",
+    "README.md"
+  ],
   type: "module",
   publishConfig: {
     access: "public",
@@ -806,7 +816,9 @@ var package_default = {
   engines: {
     bun: ">=1.3.2"
   },
-  trustedDependencies: ["@beads/bd"]
+  trustedDependencies: [
+    "@beads/bd"
+  ]
 };
 
 // src/commands/agent.ts

package/dist/template/.opencode/AGENTS.md

@@ -303,17 +303,42 @@ When tools fail or return unexpected results:
 
 1. **DO NOT** retry the same call more than twice
 2. Check fallback chains in agent documentation
-3. If still stuck, ask user for guidance
-4. Log failures using `observation` tool for future reference
+3. **Use Oracle for second opinion** on complex debugging
+4. If still stuck, ask user for guidance
+5. Log failures using `observation` tool for future reference
 
 ### Fallback Pattern
 
 ```
 Primary tool fails → Try alternative tool
-Alternative fails → Manual verification
+Alternative fails → Oracle for second opinion
 Still stuck → Ask user
 ```
 
+### Oracle Tool
+
+Use `oracle` to get a second opinion from a different AI model (gpt-5.2-codex by default) for complex reasoning tasks.
+
+**When to use:**
+
+- Validating architectural decisions before implementing
+- Cross-checking debugging hypotheses after 2 failed attempts
+- Getting alternative perspectives on tricky problems
+- Breaking out of reasoning ruts or confirmation bias
+
+**Modes:**
+
+- `validate`: Check if reasoning is sound (default)
+- `alternative`: Get completely different approaches
+- `critique`: Stress-test ideas for weaknesses
+- `brainstorm`: Expand and generate new possibilities
+
+```typescript
+oracle({ question: "Is this the right approach?", context: "..." });
+oracle({ question: "Why is this failing?", mode: "critique" });
+oracle({ question: "What alternatives exist?", mode: "alternative" });
+```
+
 ---
 
 ## Complete Atomic Reference

package/dist/template/.opencode/README.md

@@ -180,16 +180,19 @@ Plugins run automatically in every session:
 **Enabled by default (3 total):**
 
 1. **context7** - Up-to-date library documentation (37.6k+ libraries)
-   - Requires: CONTEXT7_API_KEY
-   - GitHub: https://github.com/upstash/context7
+   - Native tools: `context7_resolve_library_id()` and `context7_query_docs()`
+   - Requires: CONTEXT7_API_KEY (optional - public libraries work without it)
+   - Step 1: Resolve library name → `/libraryId`
+   - Step 2: Query docs with the libraryId
 
 2. **exa** - Web search + code context (3.3k+ repos)
    - Requires: EXA_API_KEY
    - GitHub: https://github.com/exa-labs/exa-mcp-server
 
-3. **gh_grep** - Search 1M+ public GitHub repositories
+3. **grep-search** - Search 1M+ public GitHub repositories via grep.app
+   - Native tool: `grep_search({ query: "...", language: [...] })`
    - No API key needed (public service)
-   - GitHub: https://github.com/Shachlan/grep.app-mcp
+   - Direct HTTP wrapper (no MCP overhead)
 
 **Skill-Embedded MCP (load on-demand):**
 

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

@@ -93,41 +93,131 @@ Run 2-3 tool calls in parallel.
 **Triggers:** "how do others", "compare", "best practices", "production patterns"
 **Target:** Summary, 3-5 code examples, tradeoffs, recommendation
 
-1. Search GitHub with gh_grep_searchGitHub (vary queries for different angles)
+1. Search GitHub with grep_search (vary queries for different angles)
 2. Compare 3-5 implementations from different repositories
 3. Synthesize common patterns
 4. Note tradeoffs and edge cases
 
+```typescript
+// Run 4-6 external tool calls in parallel
+// Adapt language filter based on research context
+grep_search({ query: "<pattern 1>" }); // No language filter = search all
+grep_search({ query: "<pattern 2>", language: "<relevant lang>" });
+codesearch({ query: "<API usage>", tokensNum: 5000 });
+context7_query_docs({ libraryId: "<id>", topic: "<feature>" });
+```
+
+**Language selection:** Match the language to what you're researching:
+
+- React/Next.js → `["TypeScript", "TSX", "JavaScript", "JSX"]`
+- Python libs → `["Python"]`
+- Rust crates → `["Rust"]`
+- Go packages → `["Go"]`
+- No filter → Search across all languages
+
+**Note:** Scout does NOT analyze internal codebase. If internal analysis is needed, the leader agent should delegate to @explore separately.
+
 Run 4-6 tool calls in parallel.
 
 ## Permalink Protocol
 
 Every code reference must include a GitHub permalink. Never link to a branch or tag that can change.
 
-To construct a permalink: use `gh_grep_searchGitHub` to find code, then build the URL from the repository and file path returned. Format: `https://github.com/owner/repo/blob/<sha>/path/to/file#L10-L20`.
+To construct a permalink: use `grep_search` to find code, then build the URL from the repository and file path returned. Format: `https://github.com/owner/repo/blob/<sha>/path/to/file#L10-L20`.
 
 ## Tool Priority (External Sources Only)
 
-| Priority | Tool                 | Use Case                                  | Speed   |
-| -------- | -------------------- | ----------------------------------------- | ------- |
-| 1        | memory-search        | Past research findings                    | Instant |
-| 2        | context7             | Official library docs                     | Fast    |
-| 3        | codesearch           | Exa Code API for SDK/library patterns     | Fast    |
-| 4        | gh_grep_searchGitHub | Cross-repo GitHub code search (1M+ repos) | Medium  |
-| 5        | webfetch             | Specific doc URLs, READMEs, changelogs    | Medium  |
-| 6        | opensrc + LSP        | Clone & analyze source code               | Slow    |
-| 7        | websearch            | Tutorials, blog posts, recent news        | Slow    |
+| Priority | Tool          | Use Case                                  | Speed   |
+| -------- | ------------- | ----------------------------------------- | ------- |
+| 1        | memory-search | Past research findings                    | Instant |
+| 2        | context7      | Official library docs                     | Fast    |
+| 3        | codesearch    | Exa Code API for SDK/library patterns     | Fast    |
+| 4        | grep_search   | Cross-repo GitHub code search (1M+ repos) | Medium  |
+| 5        | webfetch      | Specific doc URLs, READMEs, changelogs    | Medium  |
+| 6        | opensrc + LSP | Clone & analyze source code               | Slow    |
+| 7        | websearch     | Tutorials, blog posts, recent news        | Slow    |
 
 **Rule:** Exhaust faster tools before slower ones. Run tools in parallel when independent.
 
-## gh_grep_searchGitHub Tool
+## context7 Tools
+
+Use to access up-to-date library documentation (37.6k+ libraries).
+
+### Two-Step Process
+
+**Step 1: Resolve Library ID**
+
+```typescript
+context7_resolve_library_id({
+  libraryName: "react",              // Required - package/library name
+  query?: "hooks composition",        // Optional - search context
+  limit?: 5                           // Optional - max results (default: 5)
+})
+```
+
+Returns library IDs like `/facebook/react`, `/nodejs/node`, etc.
+
+**Step 2: Query Documentation**
+
+```typescript
+context7_query_docs({
+  libraryId: "/facebook/react",      // From resolve step
+  topic: "useState hook",             // What you want to know
+  maxTokens?: 8000                   // Optional - response size
+})
+```
+
+### Query Patterns
+
+**Good queries (specific features):**
+
+- `useState hook` - Find React useState documentation
+- `async/await` - Node.js async patterns
+- `type decorators` - TypeScript types and decorators
+- `setup instructions` - Getting started guides
+
+**Bad queries (too vague):**
+
+- `react` - Too broad
+- `best practices` - Not a feature
+- `how to use` - Natural language
+
+### Examples
+
+```typescript
+// Find React docs
+const reactId = context7_resolve_library_id({ libraryName: "react" });
+context7_query_docs({ libraryId: reactId, topic: "useEffect cleanup" });
+
+// Find TypeScript docs
+const tsId = context7_resolve_library_id({
+  libraryName: "typescript",
+  query: "types",
+});
+context7_query_docs({ libraryId: tsId, topic: "generic types" });
+
+// Find Node.js docs
+const nodeId = context7_resolve_library_id({ libraryName: "nodejs" });
+context7_query_docs({ libraryId: nodeId, topic: "streams API" });
+```
+
+### Failure Handling
+
+| Problem           | Solution                                       |
+| ----------------- | ---------------------------------------------- |
+| Library not found | Check exact name; try shorter/different names  |
+| No docs for topic | Broaden query - search parent concepts instead |
+| Empty results     | Try related terms or "API reference"           |
+| API error         | Verify CONTEXT7_API_KEY is set (optional)      |
+
+## grep_search Tool
 
 Use for cross-repository code search across 1M+ public GitHub repositories.
 
 ### Schema
 
 ```typescript
-gh_grep_searchGitHub({
+grep_search({
   query: string,              // Required - search pattern (literal code, not keywords)
   repo?: string,              // Optional - filter to specific repo (e.g., "vercel/ai")
   language?: string[],        // Optional - e.g., ["TypeScript", "TSX"]
@@ -157,22 +247,22 @@ gh_grep_searchGitHub({
 
 ```typescript
 // Basic repo search
-gh_grep_searchGitHub({ query: "batch_tool", repo: "anomalyco/opencode" });
+grep_search({ query: "batch_tool", repo: "anomalyco/opencode" });
 
 // With language filter
-gh_grep_searchGitHub({
+grep_search({
   query: "getServerSession",
   language: ["TypeScript", "TSX"],
 });
 
 // Regex pattern (multi-line)
-gh_grep_searchGitHub({
+grep_search({
   query: "(?s)useEffect\\(\\(\\) => {.*removeEventListener",
   useRegexp: true,
 });
 
 // Path filter for specific files
-gh_grep_searchGitHub({
+grep_search({
   query: "CORS(",
   language: ["Python"],
   matchCase: true,
@@ -184,7 +274,7 @@ gh_grep_searchGitHub({
 | Problem          | Solution                                         |
 | ---------------- | ------------------------------------------------ |
 | Empty results    | Broaden query - search concepts, not exact names |
-| MCP server error | Fall back to `codesearch` or `websearch`         |
+| API error        | Fall back to `codesearch` or `websearch`         |
 | Rate limited     | Reduce parallel calls, go sequential             |
 | Too many results | Add `language` or `path` filters                 |
 
@@ -224,7 +314,7 @@ webfetch({
 
 ## Source Code Deep Dive
 
-When documentation is insufficient, analyze actual source code.
+When documentation is insufficient, analyze actual **external library** source code.
 
 ### Step 1: Load the Skill
 
@@ -316,8 +406,8 @@ Structure your response as:
 
 ```
 context7 fails → try codesearch for patterns
-codesearch empty → try gh_grep_searchGitHub with broader query
-gh_grep_searchGitHub empty → webfetch specific doc URLs if known
+codesearch empty → try grep_search with broader query
+grep_search empty → webfetch specific doc URLs if known
 still stuck → opensrc clone + LSP analysis
 last resort → websearch for tutorials/blogs
 ```
@@ -327,10 +417,10 @@ last resort → websearch for tutorials/blogs
 **context7 doesn't find library:**
 
 1. Try `codesearch({ query: "<library> <function> example" })`
-2. Try `gh_grep_searchGitHub({ query: "import.*from.*<library>", language: ["TypeScript"] })`
+2. Try `grep_search({ query: "import.*from.*<library>", language: ["TypeScript"] })`
 3. Clone with `npx opensrc <library>` and read source
 
-**gh_grep_searchGitHub returns nothing:**
+**grep_search returns nothing:**
 
 - Broaden query: search concepts, not exact function names
 - Remove specific repo filter to search across all repos
@@ -339,9 +429,9 @@ last resort → websearch for tutorials/blogs
 - Search for error messages, config patterns, or import statements
 - Fall back to `codesearch` for conceptual queries
 
-**gh_grep_searchGitHub MCP error:**
+**grep_search API error:**
 
-- MCP server at `mcp.grep.app` may be temporarily down
+- The grep.app API may be temporarily unavailable
 - Fall back to `codesearch` for similar functionality
 - Use `opensrc` to clone specific repos and search locally
 - Try `websearch` as last resort
@@ -368,6 +458,6 @@ NO URL GUESSING: Only use URLs from tools or user input.
 CITE EVERYTHING: No claims without source links.
 
 Quick: context7 → codesearch → websearch (2-3 parallel calls)
-Deep: gh_grep (4-6 parallel calls) → compare 3-5 repos → synthesize
-Fallback: context7 → codesearch → gh_grep → webfetch → opensrc → websearch
+Deep: grep_search (4-6 parallel calls) → compare 3-5 repos → synthesize
+Fallback: context7 → codesearch → grep_search → webfetch → opensrc → websearch
 ```

package/dist/template/.opencode/command/research-ui.md

@@ -212,7 +212,7 @@ context7_resolve_library_id({
 });
 
 // Real-world implementations
-gh_grep_searchGitHub({
+grep_search({
   query: "[pattern to find]",
   language: ["TypeScript", "TSX"],
   path: "components/",

package/dist/template/.opencode/command/research.md

@@ -15,32 +15,55 @@ You're gathering information before implementation. Find answers, document findi
 - Default (~30 tool calls): Moderate exploration, verify patterns
 - `--thorough` (~100+ tool calls): Comprehensive analysis, new domain
 
-## Load Context
+## Load Skills Based on Depth
+
+```typescript
+// For --thorough mode, load the deep-research skill
+if (thorough) {
+  skill({ name: "deep-research" });
+}
+
+// For source code analysis
+skill({ name: "source-code-research" });
+```
+
+## Delegation Strategy
 
-### Get Quick Codebase Overview
+### Internal Codebase → @explore
 
-First, understand the codebase structure:
+Delegate LSP exploration to the explore agent:
 
 ```typescript
-// Quick overview of relevant directories
-lsp_lsp_document_symbols({ filePath: "src/index.ts", line: 1, character: 1 });
+task({
+  subagent_type: "explore",
+  description: "Analyze <module>",
+  prompt: `Very thorough LSP analysis of <target files>.
 
-// Find files by pattern
-glob({ pattern: "src/**/*.ts" });
+Questions:
+1. What functions/classes are exported?
+2. What are the incoming/outgoing calls?
+3. What patterns exist in this module?
+
+Return file:line references for all findings.`,
+});
 ```
 
-### Deep Dive
+### External Research → @scout (this agent)
 
-```typescript
-// Find similar patterns
-grep({ pattern: "<text pattern>", include: "*.ts" });
+Scout handles external sources (context7, grep_search, codesearch, etc.)
 
-// Understand types
-lsp_lsp_hover({ filePath: "<file>", line: N, character: N });
-lsp_lsp_find_references({ filePath: "<file>", line: N, character: N });
+### Parallel Execution
+
+Run internal and external research in parallel:
+
+```typescript
+// Launch both in parallel
+task({ subagent_type: "explore", prompt: "LSP analysis of..." });
+context7_resolve_library_id({ libraryName: "<lib>" });
+grep_search({ query: "<pattern>", language: "TypeScript" });
 ```
 
-This helps identify relevant directories and files before diving deeper.
+## Load Context
 
 ### Load Bead Details
 
@@ -62,21 +85,10 @@ Before hitting external sources, search what we already know:
 
 ```typescript
 // Search past research and observations on similar topics
-memory -
-  search({
-    query: "[research question/topic]",
-    mode: "semantic",
-    limit: 5,
-  });
+memory_search({ query: "[research question/topic]", limit: 5 });
 
 // Search for related gotchas and learnings
-memory -
-  search({
-    query: "[topic keywords]",
-    mode: "semantic",
-    type: "observation",
-    limit: 3,
-  });
+memory_search({ query: "[topic keywords] gotchas", limit: 3 });
 ```
 
 **If memory has high-confidence answers, you may skip external research.**
@@ -91,44 +103,32 @@ If memory search fails (Ollama not running), continue to external sources.
 
 ## Source Priority
 
-1. **Codebase patterns** (highest trust) - How does this project already do it?
+1. **Codebase patterns** (highest trust) - Delegate to @explore for LSP analysis
 2. **Official docs** (high trust) - What does the library documentation say?
 3. **Context7** (high trust) - API usage and examples
 4. **Source code** (high trust) - Library implementation (use `source-code-research` skill)
-5. **GitHub examples** (medium trust) - Real-world patterns via codesearch/gh_grep
+5. **GitHub examples** (medium trust) - Real-world patterns via codesearch/grep_search
 6. **Web search** (lower trust) - Only if tiers 1-5 don't answer
 
 ## Research
 
-### Internal Codebase - Get Quick Overview
+### Internal Codebase → Delegate to @explore
 
-First, understand codebase structure:
+**Do NOT run LSP manually.** Delegate to the explore agent:
 
 ```typescript
-// Quick overview of relevant directories
-glob({ pattern: "src/**/*.ts" });
-
-// Check file structure
-lsp_lsp_document_symbols({ filePath: "src/index.ts", line: 1, character: 1 });
-```
-
-**Use these tools when:**
-
-- Starting research on a new area of the codebase
-- Need to understand file organization before diving deep
-- Looking for relevant files to investigate
-- Want quick symbol overview for a directory
-
-### Deep Dive
+task({
+  subagent_type: "explore",
+  description: "Analyze codebase patterns",
+  prompt: `Very thorough analysis of [target area].
 
-```typescript
-// Find similar patterns
-ast - grep({ pattern: "<code pattern>" });
-grep({ pattern: "<text pattern>", include: "*.ts" });
+Questions:
+1. How does this project handle [pattern]?
+2. What are the existing conventions?
+3. Where are similar implementations?
 
-// Understand types
-lsp_lsp_hover({ filePath: "<file>", line: N, character: N });
-lsp_lsp_find_references({ filePath: "<file>", line: N, character: N });
+Return file:line references.`,
+});
 ```
 
 ### External Docs
@@ -155,20 +155,13 @@ npx opensrc pypi:<package>         # Python
 npx opensrc <owner>/<repo>         # GitHub repo
 ```
 
-```typescript
-// Then analyze the source
-glob({ pattern: "opensrc/**/src/**/*.ts" });
-grep({ pattern: "<function-name>", path: "opensrc/" });
-read({ filePath: "opensrc/repos/.../file.ts" });
-```
-
 **See:** `skill({ name: "source-code-research" })` for complete workflow.
 
 ### Code Examples
 
 ```typescript
 codesearch({ query: "<API usage pattern>", tokensNum: 5000 });
-gh_grep_searchGitHub({ query: "<code pattern>", language: ["TypeScript"] });
+grep_search({ query: "<code pattern>", language: "TypeScript" });
 ```
 
 ## Validate Findings
@@ -246,6 +239,7 @@ Research: $ARGUMENTS
 
 Depth: [quick|medium|thorough]
 Tool calls: [N]
+Delegations: [@explore for codebase, @scout for external]
 
 Questions:
 • [Q1] → Answered (High)

package/dist/template/.opencode/memory/observations/2026-01-28-decision-created-deep-research-skill-for-thorough.md

@@ -0,0 +1,29 @@
+---
+type: decision
+created: 2026-01-28T18:07:13.668Z
+confidence: high
+valid_until: null
+superseded_by: null
+concepts: ["deep-research", "skill", "LSP", "memory-first", "confidence-scoring", "scout-agent", "research-command"]
+files: [".opencode/skill/deep-research/SKILL.md"]
+---
+
+# 🎯 Created deep-research skill for thorough codebase analysis
+
+🟢 **Confidence:** high
+
+Created `.opencode/skill/deep-research/SKILL.md` to formalize extended research methodology.
+
+Key features:
+1. **Memory-first protocol** - Check past research before exploring
+2. **Full LSP exploration** - All 9 operations mandatory before edits
+3. **Confidence scoring** - High/Medium/Low/None for findings
+4. **Tool budgets** - quick (~10), default (~30), thorough (~100)
+5. **Stop conditions** - Clear criteria for when to stop research
+
+Integration points:
+- Scout agent loads this for deep mode
+- Research command uses for --thorough flag
+- Pre-edit verification workflow
+
+This enhances both scout.md and research.md without breaking changes.

package/dist/template/.opencode/memory/observations/2026-01-28-decision-gh-grep-mcp-wrapper-vs-native-grep-searc.md

@@ -0,0 +1,21 @@
+---
+type: decision
+created: 2026-01-28T16:59:35.621Z
+confidence: high
+valid_until: null
+superseded_by: null
+concepts: ["grep-search", "MCP", "native tool", "architecture", "best practices"]
+---
+
+# 🎯 gh-grep MCP wrapper vs native grep-search tool
+
+🟢 **Confidence:** high
+
+Created two implementations for GitHub code search:
+
+1. **Native tool** (.opencode/tool/grep-search.ts): TypeScript wrapper around grep.app API - WORKING ✅
+2. **MCP skill** (.opencode/skill/gh-grep/): Skill wrapper that calls uvx grep-mcp server - BROKEN ❌
+
+The MCP server has an argument parsing bug ('str' object has no attribute 'get') that prevents tool execution. Even the SKILL.md documentation admits: "Note: The MCP server (grep-mcp) may have bugs. The native grep_search tool is recommended."
+
+**Key insight**: We already documented the problem and recommended against the MCP approach. The native tool works perfectly and doesn't require external process dependencies.

package/dist/template/.opencode/memory/observations/2026-01-28-decision-oracle-tool-optimal-usage-patterns.md

@@ -0,0 +1,32 @@
+---
+type: decision
+created: 2026-01-28T18:51:45.226Z
+confidence: high
+valid_until: null
+superseded_by: null
+concepts: ["oracle", "second-opinion", "validation", "debugging", "architecture", "decision-making"]
+---
+
+# 🎯 Oracle tool optimal usage patterns
+
+🟢 **Confidence:** high
+
+Oracle tool should be used for:
+1. Validating architectural decisions BEFORE implementing
+2. Cross-checking debugging hypotheses when stuck
+3. Getting alternative perspectives on tricky problems
+4. Breaking out of reasoning ruts or confirmation bias
+
+Default model: gpt-5.2-codex (strong code understanding)
+Available models: gemini-3-pro-preview, gemini-claude-opus-4-5-thinking
+
+Modes:
+- validate: Check if reasoning is sound (default)
+- alternative: Get completely different approaches
+- critique: Stress-test ideas for weaknesses
+- brainstorm: Expand and generate new possibilities
+
+Integration points:
+- Use before major architectural decisions
+- Use when debugging complex failures (after 2 failed attempts)
+- Use in @review agent for code review validation