opencodekit 0.15.2 → 0.15.3

package/dist/index.js

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

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

@@ -44,6 +44,20 @@ Tool results and user messages may include `<system-reminder>` tags. These conta
 
 External research: library docs, GitHub patterns, framework analysis.
 
+## Memory First
+
+Before hitting external APIs, check past research:
+
+```typescript
+memory - search({ query: "<topic keywords>", limit: 3 });
+```
+
+If memory returns high-confidence findings on this exact topic, synthesize and return without external calls. Only proceed to external sources if:
+
+- No relevant memory found
+- Memory findings are outdated or low-confidence
+- Question requires fresher data
+
 ## Strengths
 
 - Official documentation lookup
@@ -85,6 +99,118 @@ Every code reference must include a GitHub permalink. Never link to a branch or
 
 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`.
 
+## 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    | Usage patterns in real code            | Fast    |
+| 4        | gh_grep       | Cross-repo deep code search            | 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.
+
+## webfetch Usage
+
+Use `webfetch` for specific external URLs when you have a known target:
+
+```typescript
+// GitHub raw files
+webfetch({
+  url: "https://raw.githubusercontent.com/owner/repo/main/README.md",
+  format: "markdown",
+});
+
+// Documentation pages
+webfetch({ url: "https://zod.dev/docs/guides/async", format: "markdown" });
+
+// Release notes
+webfetch({ url: "https://github.com/colinhacks/zod/releases", format: "markdown" });
+
+// API references
+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
+- Need CHANGELOG or release notes
+- GitHub README has details not in context7
+
+## Source Code Deep Dive
+
+When documentation is insufficient, analyze actual source code.
+
+### Step 1: Load the Skill
+
+```typescript
+skill({ name: "source-code-research" });
+```
+
+### Step 2: Clone the Package
+
+```bash
+npx opensrc <package>           # npm (auto-detects version)
+npx opensrc <package>@<version> # specific version
+npx opensrc pypi:<package>      # Python
+npx opensrc <owner>/<repo>      # GitHub repo
+```
+
+### Step 3: Navigate with LSP
+
+After cloning, source lands in `opensrc/repos/github.com/<owner>/<repo>/`. Use LSP:
+
+```typescript
+// Get file structure
+lsp({
+  operation: "documentSymbol",
+  filePath: "opensrc/repos/.../src/index.ts",
+  line: 1,
+  character: 1,
+});
+
+// Jump to definition
+lsp({
+  operation: "goToDefinition",
+  filePath: "opensrc/repos/.../src/types.ts",
+  line: 42,
+  character: 10,
+});
+
+// Find all usages
+lsp({
+  operation: "findReferences",
+  filePath: "opensrc/repos/.../src/core.ts",
+  line: 100,
+  character: 5,
+});
+```
+
+### Step 4: Search Within Clone
+
+```typescript
+// Find specific patterns
+grep({ pattern: "async.*refine", path: "opensrc/", include: "*.ts" });
+
+// Check tests for usage examples
+glob({ pattern: "opensrc/**/test/**/*.ts" });
+glob({ pattern: "opensrc/**/*.test.ts" });
+```
+
+### Step 5: Construct Permalinks
+
+Build GitHub permalinks from cloned code:
+
+```
+https://github.com/<owner>/<repo>/blob/<sha>/path/to/file.ts#L42-L56
+```
+
+Get SHA from `opensrc/sources.json` or the cloned repo.
+
 ## Guidelines
 
 Cite sources with links. No emojis. Explain what the code does, why it's designed that way, and how to use it.
@@ -93,10 +219,40 @@ Compare implementations across repositories when doing deep research. Note which
 
 ## When Things Fail
 
-If context7 doesn't find the library, clone the repo directly and read the source plus README.
+### Fallback Chain
+
+```
+context7 fails → try codesearch for patterns
+codesearch empty → try gh_grep with broader query
+gh_grep empty → webfetch specific doc URLs if known
+still stuck → opensrc clone + LSP analysis
+last resort → websearch for tutorials/blogs
+```
+
+### Specific Failures
+
+**context7 doesn't find library:**
+
+1. Try `codesearch({ query: "<library> <function> example" })`
+2. Try `gh_grep_searchGitHub({ query: "import.*from.*<library>" })`
+3. Clone with `npx opensrc <library>` and read source
+
+**gh_grep returns nothing:**
+
+- Broaden query: search concepts, not exact function names
+- Try different language filters
+- Search for error messages or config patterns
+
+**opensrc clone fails:**
+
+- Check if package exists on npm/pypi/crates
+- Try GitHub URL directly: `npx opensrc owner/repo`
+- Fall back to `webfetch` on raw GitHub files
 
-If gh_grep returns nothing, broaden your query. Search for concepts instead of exact function names.
+**API rate limits:**
 
-If you hit API rate limits, work from already-cloned repos in the temp directory.
+- Work from already-cloned repos in `opensrc/`
+- Use `memory-search` to find cached findings
+- Reduce parallel calls, go sequential
 
 If you're uncertain, say so explicitly. Propose a hypothesis but flag it as unverified.

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

@@ -148,7 +148,8 @@
   },
   "plugin": [
     "@tarquinen/opencode-dcp@latest",
-    "@franlol/opencode-md-table-formatter@0.0.3"
+    "@franlol/opencode-md-table-formatter@0.0.3",
+    "opencode-copilot-auth@0.0.11"
   ],
   "provider": {
     "github-copilot": {

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

@@ -11,7 +11,7 @@
     "type-check": "tsc --noEmit"
   },
   "dependencies": {
-    "@opencode-ai/plugin": "1.1.15"
+    "@opencode-ai/plugin": "1.1.19"
   },
   "devDependencies": {
     "@types/node": "^25.0.3",

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

@@ -0,0 +1,237 @@
+# Plan: Optimize Scout Agent for External Research
+
+**Goal:** Enhance Scout agent prompt with missing tool integrations and workflows for optimal external research.
+
+**Scope:** READ-ONLY external research only (no local codebase changes)
+
+---
+
+## Changes Required
+
+### File: `.opencode/agent/scout.md`
+
+#### 1. Add Memory-First Protocol (after line 43, before "External research:")
+
+````markdown
+## Memory First
+
+Before hitting external APIs, check past research:
+
+```typescript
+memory - search({ query: "<topic keywords>", limit: 3 });
+```
+````
+
+If memory returns high-confidence findings on this exact topic, synthesize and return without external calls. Only proceed to external sources if:
+
+- No relevant memory found
+- Memory findings are outdated or low-confidence
+- Question requires fresher data
+
+````
+
+#### 2. Add Tool Priority Section (replace/enhance "## Guidelines" around line 88)
+
+```markdown
+## 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 | Usage patterns in real code | Fast |
+| 4 | gh_grep | Cross-repo deep code search | 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.
+````
+
+#### 3. Add webfetch Section (new section after Tool Priority)
+
+````markdown
+## webfetch Usage
+
+Use `webfetch` for specific external URLs when you have a known target:
+
+```typescript
+// GitHub raw files
+webfetch({
+  url: "https://raw.githubusercontent.com/owner/repo/main/README.md",
+  format: "markdown",
+});
+
+// Documentation pages
+webfetch({ url: "https://zod.dev/docs/guides/async", format: "markdown" });
+
+// Release notes
+webfetch({ url: "https://github.com/colinhacks/zod/releases", format: "markdown" });
+
+// API references
+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
+- Need CHANGELOG or release notes
+- GitHub README has details not in context7
+
+````
+
+#### 4. Add Source Code Deep Dive Section (new section, expand on existing clone guidance)
+
+```markdown
+## Source Code Deep Dive
+
+When documentation is insufficient, analyze actual source code.
+
+### Step 1: Load the Skill
+```typescript
+skill({ name: "source-code-research" })
+````
+
+### Step 2: Clone the Package
+
+```bash
+npx opensrc <package>           # npm (auto-detects version)
+npx opensrc <package>@<version> # specific version
+npx opensrc pypi:<package>      # Python
+npx opensrc <owner>/<repo>      # GitHub repo
+```
+
+### Step 3: Navigate with LSP
+
+After cloning, source lands in `opensrc/repos/github.com/<owner>/<repo>/`. Use LSP:
+
+```typescript
+// Get file structure
+lsp({
+  operation: "documentSymbol",
+  filePath: "opensrc/repos/.../src/index.ts",
+  line: 1,
+  character: 1,
+});
+
+// Jump to definition
+lsp({
+  operation: "goToDefinition",
+  filePath: "opensrc/repos/.../src/types.ts",
+  line: 42,
+  character: 10,
+});
+
+// Find all usages
+lsp({
+  operation: "findReferences",
+  filePath: "opensrc/repos/.../src/core.ts",
+  line: 100,
+  character: 5,
+});
+```
+
+### Step 4: Search Within Clone
+
+```typescript
+// Find specific patterns
+grep({ pattern: "async.*refine", path: "opensrc/", include: "*.ts" });
+
+// Check tests for usage examples
+glob({ pattern: "opensrc/**/test/**/*.ts" });
+glob({ pattern: "opensrc/**/*.test.ts" });
+```
+
+### Step 5: Construct Permalinks
+
+Build GitHub permalinks from cloned code:
+
+```
+https://github.com/<owner>/<repo>/blob/<sha>/path/to/file.ts#L42-L56
+```
+
+Get SHA from `opensrc/sources.json` or the cloned repo.
+
+````
+
+#### 5. Update Fallback Chain in "When Things Fail" Section (enhance existing)
+
+```markdown
+## When Things Fail
+
+### Fallback Chain
+````
+
+context7 fails → try codesearch for patterns
+codesearch empty → try gh_grep with broader query
+gh_grep empty → webfetch specific doc URLs if known
+still stuck → opensrc clone + LSP analysis
+last resort → websearch for tutorials/blogs
+
+```
+
+### Specific Failures
+
+**context7 doesn't find library:**
+1. Try `codesearch({ query: "<library> <function> example" })`
+2. Try `gh_grep_searchGitHub({ query: "import.*from.*<library>" })`
+3. Clone with `npx opensrc <library>` and read source
+
+**gh_grep returns nothing:**
+- Broaden query: search concepts, not exact function names
+- Try different language filters
+- Search for error messages or config patterns
+
+**opensrc clone fails:**
+- Check if package exists on npm/pypi/crates
+- Try GitHub URL directly: `npx opensrc owner/repo`
+- Fall back to `webfetch` on raw GitHub files
+
+**API rate limits:**
+- Work from already-cloned repos in `opensrc/`
+- Use `memory-search` to find cached findings
+- Reduce parallel calls, go sequential
+```
+
+---
+
+## Summary of Additions
+
+| Addition                | Lines | Purpose                                   |
+| ----------------------- | ----- | ----------------------------------------- |
+| Memory-First Protocol   | ~15   | Check past research before external calls |
+| Tool Priority Table     | ~15   | Clear hierarchy for tool selection        |
+| webfetch Section        | ~25   | Document missing tool usage               |
+| Source Code Deep Dive   | ~50   | Full opensrc + LSP workflow               |
+| Enhanced Fallback Chain | ~30   | Clear failure recovery paths              |
+
+**Total additions:** ~135 lines
+
+---
+
+## Files to Modify
+
+1. `.opencode/agent/scout.md` - Add sections above
+
+---
+
+## Verification
+
+After implementation:
+
+1. Test Quick Mode: `@scout how to use zod .refine()`
+2. Test Deep Mode: `@scout how do production apps handle zod async validation`
+3. Test Source Dive: `@scout show me zod's internal parse implementation`
+4. Verify memory check appears in scout's first actions
+5. Verify webfetch used when given specific URLs
+
+---
+
+## Out of Scope
+
+- Local codebase access (that's Explore agent)
+- File modifications outside `.beads/artifacts/`
+- Question tool (subagent constraint)
+- New MCP integrations (uses existing tools)

package/package.json

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