opencodekit 0.15.13 → 0.15.14

package/dist/index.js

@@ -750,9 +750,16 @@ var cac = (name = "") => new CAC(name);
 // package.json
 var package_default = {
   name: "opencodekit",
-  version: "0.15.13",
+  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/agent/scout.md

@@ -98,6 +98,25 @@ Run 2-3 tool calls in parallel.
 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
@@ -295,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
 

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,7 +103,7 @@ 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)
@@ -100,35 +112,23 @@ If memory search fails (Ollama not running), continue to external sources.
 
 ## 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-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

package/dist/template/.opencode/memory/observations/2026-01-28-learning-ampcode-deep-mode-research-integration-w.md

@@ -0,0 +1,42 @@
+---
+type: learning
+created: 2026-01-28T18:03:19.579Z
+confidence: high
+valid_until: null
+superseded_by: null
+concepts: ["deep-mode", "ampcode", "scout", "research", "autonomous", "extended-thinking", "oracle"]
+---
+
+# 📚 AmpCode Deep Mode Research - Integration with Scout/Research
+
+🟢 **Confidence:** high
+
+## AmpCode Deep Mode Research (Jan 2026)
+
+### Key Concepts from AmpCode:
+1. **Three Modes**: smart (collaborative), rush (fast/cheap), deep (autonomous/extended thinking)
+2. **Deep Mode Behavior**: 5-15 minutes of silent reading before changes, uses GPT-5.2-Codex
+3. **Oracle Pattern**: Second opinion tool using reasoning model for complex decisions
+4. **Handoff**: Move context between modes/threads
+
+### How This Maps to OpenCodeKit:
+
+**Scout Agent** already has:
+- Quick Mode (~2-3 tool calls)
+- Deep Mode (~4-6 tool calls) - triggers on "how do others", "compare", "best practices"
+
+**Research Command** already has:
+- `--quick` (~10 tool calls)
+- Default (~30 tool calls)  
+- `--thorough` (~100+ tool calls)
+
+### Enhancement Opportunities:
+1. Add `--deep` flag to research that enforces extended LSP exploration before ANY findings
+2. Create oracle tool for "second opinion" on complex architectural decisions
+3. Add mode handoff commands: `/mode deep`, `/mode smart`
+4. Make thorough mode more autonomous (fewer check-ins)
+
+### AmpCode Insights to Adopt:
+- "Deep mode is lazy about verification" - sometimes useful to defer verification
+- "Requires clear problem definition upfront" - enforce problem statement template
+- "Goes off to solve problems alone, not pair program" - reduce chattiness in thorough mode

package/dist/template/.opencode/memory/observations/2026-01-28-pattern-research-delegation-pattern-explore-for-.md

@@ -0,0 +1,32 @@
+---
+type: pattern
+created: 2026-01-28T18:11:31.174Z
+confidence: high
+valid_until: null
+superseded_by: null
+concepts: ["delegation", "explore-agent", "scout-agent", "research-command", "LSP", "deep-research", "parallel-execution"]
+---
+
+# 🔄 Research delegation pattern: @explore for LSP, @scout for external
+
+🟢 **Confidence:** high
+
+Optimized scout.md and research.md to use proper delegation:
+
+**Delegation pattern:**
+- Internal codebase LSP analysis → delegate to @explore agent
+- External docs/GitHub patterns → @scout handles directly
+- Run both in parallel when possible
+
+**Key changes:**
+1. Scout agent loads deep-research skill for deep mode
+2. Research command loads deep-research skill for --thorough
+3. Both delegate LSP exploration to @explore instead of manual LSP calls
+4. Removed redundant manual LSP code examples
+5. Added parallel execution pattern for internal + external research
+
+**Why this is better:**
+- @explore is specialized for LSP with structured output
+- Reduces manual tool call overhead (9 LSP ops → 1 delegation)
+- Enables parallel research (codebase + external simultaneously)
+- Consistent methodology via deep-research skill