opencodekit 0.9.0 → 0.9.2

package/README.md

@@ -24,22 +24,13 @@ A pre-configured OpenCode distribution featuring:
 ### Option 1: Using CLI (Recommended)
 
 ```bash
-# 1. Install CLI
-bun install -g opencodekit-cli
-# or use local version
-bun install
-bun run dev init
-
-# 2. Create new project
-ock init
-cd my-opencode-project
-
-# 3. Configure OpenCodeKit
-ock setup
-
-# 4. Explore
-ock agent list
-ock skill list
+# 1. Create new project with npx
+npx opencodekit init my-project
+cd my-project
+
+# 2. Or install globally
+npm install -g opencodekit
+ock init my-project
 ```
 
 **See [CLI.md](./CLI.md) for complete CLI documentation**
@@ -73,13 +64,12 @@ create test.txt with "Hello OpenCodeKit"
 
 ```
 build (Primary Orchestrator - 70% of work)
-  ├→ @plan (Complex planning ≥3 phases)
-  ├→ @code-auditor (Review + security + testing)
-  ├→ @oracle (Deep analysis, debugging, architecture review)
-  ├→ @librarian (Cross-repo GitHub search, framework internals)
-  ├→ @docs (Quick API documentation)
-  ├→ @finder (Fast codebase search)
-  ├→ @orchestrator (Multi-agent coordination)
+  ├→ @rush (Fast agent for simple tasks)
+  ├→ @planner (Complex planning ≥3 phases)
+  ├→ @review (Code review + security + debugging)
+  ├→ @scout (External research, library docs, GitHub patterns)
+  ├→ @explore (Fast codebase search)
+  ├→ @vision (UI/UX, mockups, visual analysis)
   └→ @general (Fallback)
 
 Background Plugins:
@@ -88,10 +78,10 @@ Background Plugins:
   • truncator (Dynamic output truncation)
 
 Supporting:
-  • 24 Skills (loaded via commands: 8 core, 7 stack, 9 specialized)
-  • 45+ Commands (workflow shortcuts, includes /handoff)
-  • 5 MCP Services (context7, exa, gkg, gh_grep, figma*) + augment-context-engine
-  • Custom Tools (memory-*, observation, ast-grep)
+  • 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-*)
   • Beads task tracking (`bd` CLI for multi-session workflows)
   • Manual Handoffs (clean phase transitions)
 ```
@@ -181,20 +171,21 @@ session({
 Is it a simple task?
   ✓ → Use build directly (70% of work)
 
+Need speed over depth?
+  ✓ → @rush (fast agent, same capabilities)
+
 Complex task (≥3 phases)?
-  ✓ → @plan (creates task ledger)
+  ✓ → @planner (creates implementation plan)
 
 Need research?
-  ✓ → @oracle (complex debugging/architecture)
-  ✓ → @librarian (cross-repo GitHub search)
-  ✓ → @docs (quick API reference)
-  ✓ → @finder (codebase search)
+  ✓ → @scout (library docs + GitHub patterns)
+  ✓ → @explore (codebase search)
 
 Quality gate before deployment?
-  ✓ → @code-auditor (security + review + test)
+  ✓ → @review (security + code review + debugging)
 
-5+ phases + 3+ agents?
-  ✓ → @orchestrator (progress tracking)
+UI/UX work?
+  ✓ → @vision (mockups, visual analysis, accessibility)
 
 Everything else?
   ✓ → @general (fallback)
@@ -226,15 +217,15 @@ Everything else?
 
 You've successfully set up OpenCodeKit when:
 
-- ✅ 10 agent files (.opencode/agent/\*.md)
+- ✅ Agent files in place (.opencode/agent/\*.md)
 - ✅ Build handles 70%+ directly
-- ✅ Commands work (45+ total, including `/handoff`)
-- ✅ Skills load via commands (24 skills: 8 core, 7 stack, 9 specialized)
+- ✅ Commands work (/commit, /pr, /design, /fix, /implement)
+- ✅ Skills load on-demand (30+ skills)
 - ✅ Delegation is clear (build → specialized subagents)
 - ✅ `/handoff` creates portable bundles (.opencode/memory/handoffs/)
-- ✅ MCP services configured (6 total: 5 enabled, 1 optional)
+- ✅ MCP services configured (context7, gh_grep + skill-embedded)
 - ✅ Background plugins active (enforcer, compactor, truncator)
-- ✅ Custom tools available (memory-\*, observation, ast-grep)
+- ✅ Custom tools available (memory-_, observation, ast-grep, lsp-_)
 - ✅ Environment variables set (.opencode/.env with API keys)
 
 ---
@@ -260,9 +251,10 @@ You've successfully set up OpenCodeKit when:
 
 ---
 
-**OpenCodeKit v0.3.0**  
+**OpenCodeKit v0.9.2**  
 **Architecture**: Two-layer (Memory + Beads + Git)  
-**New in v0.3.0**: Background plugins (enforcer, compactor, truncator) + ast-grep semantic code tool  
+**Package**: `npx opencodekit` to scaffold new projects  
+**New in v0.9.2**: 6 new LSP tools, `ock init --beads` flag, improved tool guidance  
 **Ready for**: Daily production use
 
-Enjoy your streamlined agent system with clean phase transitions! 🚀
+Enjoy your streamlined agent system with clean phase transitions!

package/dist/index.js

@@ -750,7 +750,7 @@ var cac = (name = "") => new CAC(name);
 // package.json
 var package_default = {
   name: "opencodekit",
-  version: "0.9.0",
+  version: "0.9.2",
   description: "CLI tool for bootstrapping and managing OpenCodeKit projects",
   type: "module",
   repository: {
@@ -3050,14 +3050,15 @@ async function editAutoupdate(configPath) {
 }
 
 // src/commands/init.ts
+import { execSync } from "node:child_process";
 import {
   existsSync as existsSync3,
   mkdirSync as mkdirSync2,
   readFileSync as readFileSync3,
-  writeFileSync as writeFileSync3,
-  readdirSync as readdirSync2
+  readdirSync as readdirSync2,
+  writeFileSync as writeFileSync3
 } from "node:fs";
-import { join as join3, dirname, basename } from "node:path";
+import { basename, dirname, join as join3 } from "node:path";
 import { fileURLToPath } from "node:url";
 var import_picocolors7 = __toESM(require_picocolors(), 1);
 var EXCLUDED_DIRS = [
@@ -3114,9 +3115,7 @@ async function copyDir(src, dest) {
       continue;
     const srcPath = join3(src, entry.name);
     const destPath = join3(dest, entry.name);
-    if (entry.isSymbolicLink()) {
-      continue;
-    } else if (entry.isDirectory()) {
+    if (entry.isSymbolicLink()) {} else if (entry.isDirectory()) {
       await copyDir(srcPath, destPath);
     } else {
       const content = readFileSync3(srcPath, "utf-8");
@@ -3178,7 +3177,28 @@ async function initCommand(options = {}) {
     process.exit(1);
   }
   s.stop("Done");
-  le(`cd .opencode && bun install`, "Next steps");
+  if (options.beads) {
+    const beadsDir = join3(targetDir, ".beads");
+    if (!existsSync3(beadsDir)) {
+      const bs = de();
+      bs.start("Initializing .beads/");
+      try {
+        execSync("bd init", { cwd: targetDir, stdio: "ignore" });
+        bs.stop("Beads initialized");
+      } catch {
+        mkdirSync2(beadsDir, { recursive: true });
+        writeFileSync3(join3(beadsDir, "config.yaml"), `# Beads configuration
+version: 1
+`);
+        writeFileSync3(join3(beadsDir, "issues.jsonl"), "");
+        writeFileSync3(join3(beadsDir, "metadata.json"), JSON.stringify({ created: new Date().toISOString() }, null, 2));
+        bs.stop("Beads initialized (manual)");
+      }
+    } else {
+      f2.info(".beads/ already exists");
+    }
+  }
+  le("cd .opencode && bun install", "Next steps");
   $e(import_picocolors7.default.green("Ready to code!"));
 }
 
@@ -3724,7 +3744,7 @@ var cli = cac("ock");
 cli.option("--verbose", "Enable verbose logging");
 cli.option("--quiet", "Suppress all output");
 cli.version(`${packageVersion}`);
-cli.command("init", "Initialize OpenCodeKit in current directory").option("--force", "Reinitialize even if already exists").action(initCommand);
+cli.command("init", "Initialize OpenCodeKit in current directory").option("--force", "Reinitialize even if already exists").option("--beads", "Also initialize .beads/ for multi-agent coordination").action(initCommand);
 cli.command("agent [action]", "Manage agents (list, add, view)").action(async (action) => {
   if (!action) {
     console.log(`

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

@@ -79,35 +79,80 @@ Specify depth when delegating to control tool call budget:
 
 ## Tool Priority
 
-**LSP tools → AST tools → Built-in tools**
+**LSP tools → AST-grep → Built-in tools**
 
-1. `lsp_rename`, `lsp_code_actions`, `lsp_organize_imports` - Semantic refactoring (LSP-based)
-2. `ast-grep` - Semantic code search/replace (AST-based)
-3. `grep`, `glob` - Pattern matching, file discovery
-4. `read`, `edit`, `write` - File operations
+1. **LSP tools** - Semantic code intelligence (10 tools)
+2. `ast-grep` - **Code search/replace** (functions, patterns, imports, hooks)
+3. `grep` - **Text search** (logs, config, non-code files, simple strings)
+4. `glob` - File discovery by name pattern
+5. `read`, `edit`, `write` - File operations
+
+### Choosing the Right Search Tool
+
+Ask yourself: **"Am I looking for code structure or just text?"**
+
+**Use `ast-grep` when you need to find:**
+
+- How a function is called → `pattern="fetchUser($$$)"`
+- Where a hook is used → `pattern="useState($$$)"`
+- Import statements → `pattern="import { $$ } from '$MOD'"`
+- Class definitions → `pattern="class $NAME { $$$ }"`
+- Try-catch blocks → `pattern="try { $$$ } catch ($E) { $$$ }"`
+
+**Use `grep` when you need to find:**
+
+- Error messages in logs → `pattern="FATAL|ERROR"`
+- Config values → `pattern="API_KEY"`
+- TODO comments → `pattern="TODO|FIXME"`
+- Text in markdown/docs → `pattern="deprecated"`
+
+**Use LSP tools when you need to:**
+
+- Understand what a symbol is → `lsp_hover`
+- Jump to where something is defined → `lsp_goto_definition`
+- Find all usages before refactoring → `lsp_find_references`
+- Rename across the entire codebase → `lsp_rename`
 
 **Rule**: Always `read` before `edit` to verify content.
 
-### LSP Tools Usage
+### LSP Tools (10 tools)
 
-Semantic refactoring via Language Server Protocol - smarter than text replacement:
+Semantic code intelligence via Language Server Protocol:
 
-```
-# Rename symbol across entire codebase
-lsp_rename(filePath, line, character, newName)
+**Navigation & Understanding:**
 
-# Get available refactorings at location
-lsp_code_actions(filePath, startLine, startCharacter, endLine, endCharacter)
+- `lsp_hover(filePath, line, character)` - Get type info and docs at cursor
+- `lsp_goto_definition(filePath, line, character)` - Jump to where symbol is defined
+- `lsp_find_references(filePath, line, character)` - Find all usages of a symbol
+- `lsp_document_symbols(filePath)` - Get file outline (classes, functions, etc.)
+- `lsp_workspace_symbols(query, filePath)` - Fuzzy search symbols across workspace
 
-# Clean up imports
-lsp_organize_imports(filePath)
-```
+**Diagnostics:**
+
+- `lsp_diagnostics(filePath, severity?)` - Get errors/warnings from language server
+
+**Refactoring:**
+
+- `lsp_rename(filePath, line, character, newName)` - Rename symbol across codebase
+- `lsp_code_actions(filePath, startLine, startChar, endLine, endChar)` - Get available refactorings
+- `lsp_code_action_apply(...)` - Apply a specific code action
+- `lsp_organize_imports(filePath)` - Clean up and sort imports
 
-**When to use LSP over manual edit:**
+**When to use each tool:**
 
-- Renaming functions, variables, classes → `lsp_rename` (updates all references)
-- Cleaning imports after refactoring → `lsp_organize_imports`
-- Exploring refactoring options → `lsp_code_actions`
+**"What type is this variable?"** → Use `lsp_hover` to see type signature without reading the entire definition file.
+
+**"Where is this function defined?"** → Use `lsp_goto_definition` to jump directly to source instead of grepping.
+
+**"What uses this function?"** → Use `lsp_find_references` before changing anything to see all call sites.
+
+**"What's in this file?"** → Use `lsp_document_symbols` for a quick outline without reading the entire file.
+
+**"Where is UserService defined?"** → Use `lsp_workspace_symbols` to fuzzy search across all files.
+
+**"Are there type errors?"** → Use `lsp_diagnostics` to check before running tests.
+
+**"Rename this function safely"** → Use `lsp_rename` to update all references automatically.
 
 **Caveat**: LSP tools modify files directly. Re-read files before further edits.
 
@@ -355,25 +400,6 @@ Call `bd_insights` for graph analysis showing bottlenecks and high-priority keys
 
 Get `bd_priority` recommendations for what to work on next based on graph analysis. Use `bd_diff` to compare issue changes between git revisions.
 
-### Quick Start
-
-```typescript
-// 1. Join workspace
-bd_init({ team: "project", role: "fe" });
-
-// 2. Get next task
-const task = bd_claim();
-
-// 3. Lock files before editing
-bd_reserve({ paths: ["src/auth.ts", "src/types.ts"] });
-
-// 4. Do the work...
-
-// 5. Complete and restart
-bd_done({ id: task.id, msg: "Implemented auth" });
-// RESTART SESSION
-```
-
 ### Rules
 
 - **Always `bd_init()` first** in any session using beads tools

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

@@ -186,7 +186,7 @@ ast-grep pattern="oldFunc($$$)" rewrite="newFunc($$$)" dryRun=true
 
 ## MCP Services
 
-**Enabled by default (4 total):**
+**Enabled by default (3 total):**
 
 1. **context7** - Up-to-date library documentation (37.6k+ libraries)
    - Requires: CONTEXT7_API_KEY
@@ -200,16 +200,19 @@ ast-grep pattern="oldFunc($$$)" rewrite="newFunc($$$)" dryRun=true
    - No API key needed (public service)
    - GitHub: https://github.com/Shachlan/grep.app-mcp
 
-**Optional (disabled by default):**
+**Skill-Embedded MCP (load on-demand):**
 
-4. **Framelink MCP for Figma** - Extract Figma layouts and design tokens
+4. **figma** - Extract Figma layouts and design tokens
    - Requires: FIGMA_API_KEY
-   - GitHub: https://github.com/GLips/Figma-Context-MCP (11.9k+ stars)
-   - Enable: Set `"Framelink MCP for Figma": { "enabled": true }` in opencode.json
+   - Use: `skill({ name: "figma" })` then `skill_mcp()`
 
 5. **playwright** - Browser automation for testing
    - No API key needed
-   - Use via skill: `skill({ name: "playwright" })` then `skill_mcp()`
+   - Use: `skill({ name: "playwright" })` then `skill_mcp()`
+
+6. **chrome-devtools** - DevTools for debugging and performance
+   - No API key needed
+   - Use: `skill({ name: "chrome-devtools" })` then `skill_mcp()`
 
 ---
 
@@ -326,7 +329,8 @@ fi
 
 ---
 
-**OpenCodeKit v0.7.0**  
+**OpenCodeKit v0.9.2**  
 **Architecture:** Two-Layer (Memory + Beads + Git)  
-**New in v0.7.0:** Native skill tool integration, Beads Village MCP, 27 skills, enhanced commands  
-**Last Updated:** December 30, 2025
+**New in v0.9.2:** 6 new LSP tools, `ock init --beads` flag, improved tool guidance  
+**Package:** `npx opencodekit` to scaffold new projects  
+**Last Updated:** January 2, 2026

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

@@ -47,9 +47,31 @@ Primary orchestrator. Execute-first. Autonomous task completion until resolved.
 ## Tool Priority
 
 1. **LSP tools** for semantic refactoring (rename, code actions, organize imports)
-2. **AST-Grep** for semantic code search/replace
-3. **Built-in tools** for pattern matching (grep, glob, read)
-4. **Bash** for running tests, builds, commands
+2. **AST-Grep** for code search/replace (functions, hooks, imports, patterns)
+3. **grep** for text search (logs, config, non-code files)
+4. **glob** for file discovery by name
+5. **Bash** for running tests, builds, commands
+
+### Choosing the Right Search Tool
+
+Ask yourself: **"Am I looking for code structure or just text?"**
+
+**Use `ast-grep` when you need to find:**
+
+- How a function is called → `pattern="fetchUser($$$)"`
+- Where a hook is used → `pattern="useState($$$)"`
+- Import statements → `pattern="import { $$ } from '$MOD'"`
+
+**Use `grep` when you need to find:**
+
+- Error messages, config values, TODO comments, text in docs
+
+**Use LSP tools when you need to:**
+
+- Understand what a symbol is → `lsp_hover`
+- Jump to where something is defined → `lsp_goto_definition`
+- Find all usages before refactoring → `lsp_find_references`
+- Rename across the entire codebase → `lsp_rename`
 
 ### LSP Tools
 
@@ -57,6 +79,22 @@ Use LSP tools for safe, semantic refactoring. Use `lsp_rename` to rename functio
 
 **Caveat**: LSP tools modify files directly. Re-read before further edits.
 
+### AST-Grep
+
+Semantic code search/replace - smarter than regex:
+
+```
+# Search patterns
+ast-grep pattern="console.log($$$)"                    # Find all console.log
+ast-grep pattern="async function $NAME($$$) { $$$ }"   # Find async functions
+ast-grep pattern="const [$S, $SET] = useState($$$)"    # Find React hooks
+
+# Replace (dry run first)
+ast-grep pattern="oldFunc($$$)" rewrite="newFunc($$$)" dryRun=true
+```
+
+**Pattern syntax**: `$NAME` = single node, `$$$` = zero or more nodes
+
 ## Anti-Hallucination
 
 **Before work:** Check bead spec if doing feature work (`bd show <id>`)

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

@@ -14,6 +14,7 @@ tools:
   todoread: false
   todowrite: false
   ast-grep*: true
+  lsp*: true
 ---
 
 # Explore Agent
@@ -26,6 +27,7 @@ File search specialist. Navigate and explore codebases efficiently.
 - Searching code with regex patterns
 - Reading and analyzing file contents
 - Semantic code search with AST-Grep
+- Understanding symbol types and definitions with LSP
 
 ## Guidelines
 
@@ -37,7 +39,19 @@ File search specialist. Navigate and explore codebases efficiently.
 
 ## Tool Priority
 
-**Use AST-Grep for semantic search, then fall back to built-in tools.**
+**LSP tools for understanding → AST-Grep for patterns → Built-in for text**
+
+### LSP Tools (Code Intelligence)
+
+**"What type is this?"** → Use `lsp_hover` to see type signature at a position.
+
+**"Where is this defined?"** → Use `lsp_goto_definition` to jump to source.
+
+**"What uses this?"** → Use `lsp_find_references` to find all call sites.
+
+**"What's in this file?"** → Use `lsp_document_symbols` for quick outline.
+
+**"Where is X defined in the codebase?"** → Use `lsp_workspace_symbols` to fuzzy search.
 
 ### AST-Grep (Semantic Search)
 
@@ -59,8 +73,8 @@ File search specialist. Navigate and explore codebases efficiently.
 
 ## Thoroughness Levels
 
-**Quick**: Single ast-grep or glob. Read 1-3 files. Return immediately.
+**Quick**: Single ast-grep, lsp_workspace_symbols, or glob. Read 1-3 files. Return immediately.
 
-**Medium**: AST-grep + grep verification. Check 2-3 naming conventions. Read 3-5 files.
+**Medium**: AST-grep + LSP verification. Check 2-3 naming conventions. Read 3-5 files. Use `lsp_find_references` to trace usage.
 
-**Very Thorough**: Comprehensive search across multiple terms and locations. Build dependency map. Report with file:line references.
+**Very Thorough**: Comprehensive search across multiple terms and locations. Use `lsp_find_references` to build dependency map. Report with file:line references.

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

@@ -18,6 +18,8 @@ tools:
   codesearch: true
   memory-read: true
   memory-update: true
+  ast-grep*: true
+  lsp*: true
 ---
 
 # Review Agent
@@ -30,6 +32,7 @@ Critical analysis: code review, debugging, security audit, refactoring decisions
 - Root cause analysis
 - Code quality assessment
 - Evidence-based recommendations
+- Understanding code with LSP tools
 
 ## Guidelines
 
@@ -69,9 +72,19 @@ bd create "[type]: [description]" -t bug -p [0-4] -d "[details, file:line]"
 
 ## Tool Priority
 
-**Codebase**: grep → ast-grep → read
-**Verification**: bash (tests, lint, type-check)
-**History**: `git log -p`, `git blame`
+**LSP tools for understanding → AST-grep for patterns → Built-in for verification**
+
+**"What type is this variable?"** → Use `lsp_hover` to understand without reading entire file.
+
+**"Where is this defined?"** → Use `lsp_goto_definition` to jump to source.
+
+**"What calls this function?"** → Use `lsp_find_references` to trace all usages.
+
+**"Are there type errors?"** → Use `lsp_diagnostics` before investigating runtime issues.
+
+**"Find this pattern across codebase"** → Use `ast-grep` for semantic code search.
+
+**Verification**: `bash` for tests, lint, type-check. `git log -p`, `git blame` for history.
 
 ## Execution Discipline
 

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

@@ -45,11 +45,21 @@ Fast execute-first agent. Speed over depth. Delegate anything complex.
 
 ## Tool Priority
 
-**LSP tools FIRST, then AST-Grep, then built-in tools.**
+1. **LSP tools** for semantic refactoring (rename, organize imports)
+2. **AST-Grep** for code search/replace (functions, hooks, imports)
+3. **grep** for text search (logs, config, non-code)
+4. **glob** for file discovery
 
-1. `lsp_rename`, `lsp_organize_imports` - Semantic refactoring
-2. `ast-grep` - Semantic code search/replace
-3. `grep`, `glob` - Text search, file patterns
+### Choosing the Right Search Tool
+
+Ask: **"Code structure or just text?"**
+
+- Code structure (functions, hooks, imports) → `ast-grep`
+- Text patterns (logs, config, docs) → `grep`
+- Understand symbol type → `lsp_hover`
+- Find definition → `lsp_goto_definition`
+- Find all usages → `lsp_find_references`
+- Rename across codebase → `lsp_rename`
 
 ### LSP Tools (Fast Refactoring)
 
@@ -57,6 +67,15 @@ Use `lsp_rename` to rename symbols across the codebase - faster than manual find
 
 **Caveat**: LSP tools modify files directly. Re-read before further edits.
 
+### AST-Grep (Semantic Search/Replace)
+
+```
+ast-grep pattern="console.log($$$)"                    # Find console.log
+ast-grep pattern="oldFunc($$$)" rewrite="newFunc($$$)" # Replace function calls
+```
+
+**Pattern syntax**: `$NAME` = single node, `$$$` = zero or more nodes
+
 ## Pre-Action Checks
 
 Before mutations (edit, write, delete):