opencodekit 0.8.0 → 0.9.1

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.1**  
 **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.1**: Memory & Compaction plugin merge, session.start auto-load hook  
 **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.8.0",
+  version: "0.9.1",
   description: "CLI tool for bootstrapping and managing OpenCodeKit projects",
   type: "module",
   repository: {
@@ -764,7 +764,10 @@ var package_default = {
   bin: {
     ock: "dist/index.js"
   },
-  files: ["dist", "README.md"],
+  files: [
+    "dist",
+    "README.md"
+  ],
   scripts: {
     dev: "bun run src/index.ts",
     build: "bun build src/index.ts --outdir dist --target node && mkdir -p dist/template && rsync -av --exclude=node_modules --exclude=dist --exclude=.git --exclude=coverage --exclude=.next --exclude=.turbo --exclude=logs --exclude=package-lock.json .opencode/ dist/template/.opencode/",
@@ -776,7 +779,14 @@ var package_default = {
     lint: "biome check .",
     "lint:fix": "biome check --fix ."
   },
-  keywords: ["cli", "opencodekit", "template", "agents", "mcp", "opencode"],
+  keywords: [
+    "cli",
+    "opencodekit",
+    "template",
+    "agents",
+    "mcp",
+    "opencode"
+  ],
   author: "OpenCodeKit",
   license: "MIT",
   engines: {
@@ -799,7 +809,9 @@ var package_default = {
     "@types/node": "^22.10.1",
     typescript: "^5.7.2"
   },
-  trustedDependencies: ["@beads/bd"]
+  trustedDependencies: [
+    "@beads/bd"
+  ]
 };
 
 // src/commands/agent.ts

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

@@ -79,13 +79,12 @@ Specify depth when delegating to control tool call budget:
 
 ## Tool Priority
 
-**GKG tools → LSP tools → AST tools → Built-in tools**
+**LSP tools → AST tools → Built-in tools**
 
-1. `gkg_search_codebase_definitions`, `gkg_get_references`, `gkg_repo_map` - Find symbols, usages, API overview
-2. `lsp_rename`, `lsp_code_actions`, `lsp_organize_imports` - Semantic refactoring (LSP-based)
-3. `ast-grep` - Semantic code search/replace (AST-based)
-4. `grep`, `glob` - Pattern matching, file discovery
-5. `read`, `edit`, `write` - File operations
+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
 
 **Rule**: Always `read` before `edit` to verify content.
 

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

@@ -144,11 +144,9 @@ Memory (Permanent)     → Beads (Multi-session)    → Git (Audit Trail)
 
 Plugins run automatically in every session:
 
-| Plugin        | What it does                                                |
-| ------------- | ----------------------------------------------------------- |
-| **enforcer**  | OS notification when session idles with incomplete TODOs    |
-| **compactor** | Warns at 70%, 85%, 95% context usage - prevents rushed work |
-| **truncator** | Dynamic output truncation based on context remaining        |
+- **enforcer** - OS notification when session idles with incomplete TODOs
+- **compactor** - Warns at 70%, 85%, 95% context usage - prevents rushed work
+- **truncator** - Dynamic output truncation based on context remaining
 
 **Compactor thresholds**:
 
@@ -160,13 +158,11 @@ Plugins run automatically in every session:
 
 ## Custom Tools
 
-| Tool              | Purpose                                  |
-| ----------------- | ---------------------------------------- |
-| **memory-read**   | Load previous context, templates         |
-| **memory-update** | Save learnings, handoffs                 |
-| **memory-search** | Search across all memory files           |
-| **observation**   | Create structured observations           |
-| **ast-grep**      | Semantic code search/replace (AST-based) |
+- **memory-read** - Load previous context, templates
+- **memory-update** - Save learnings, handoffs
+- **memory-search** - Search across all memory files
+- **observation** - Create structured observations
+- **ast-grep** - Semantic code search/replace (AST-based)
 
 ### AST-Grep Usage
 
@@ -190,7 +186,7 @@ ast-grep pattern="oldFunc($$$)" rewrite="newFunc($$$)" dryRun=true
 
 ## MCP Services
 
-**Enabled by default (5 total):**
+**Enabled by default (3 total):**
 
 1. **context7** - Up-to-date library documentation (37.6k+ libraries)
    - Requires: CONTEXT7_API_KEY
@@ -204,17 +200,19 @@ ast-grep pattern="oldFunc($$$)" rewrite="newFunc($$$)" dryRun=true
    - No API key needed (public service)
    - GitHub: https://github.com/Shachlan/grep.app-mcp
 
-4. **gkg** - GitLab Knowledge Graph (local codebase semantic search)
-   - No API key needed (runs locally on port 27495)
-   - Docs: https://gitlab-org.gitlab.io/rust/knowledge-graph/
-   - Install: Follow https://gitlab-org.gitlab.io/rust/knowledge-graph/getting-started/install/
+**Skill-Embedded MCP (load on-demand):**
 
-**Optional (disabled by default):**
-
-5. **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: `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()`
 
 ---
 
@@ -331,7 +329,8 @@ fi
 
 ---
 
-**OpenCodeKit v0.7.0**  
+**OpenCodeKit v0.9.1**  
 **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.1:** Memory & Compaction plugin merge, session.start auto-load hook  
+**Package:** `npx opencodekit` to scaffold new projects  
+**Last Updated:** January 2, 2026

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

@@ -14,7 +14,6 @@ tools:
   webfetch: true
   websearch: true
   codesearch: true
-  gkg*: true
   ast-grep*: true
   lsp*: true
   context7*: true
@@ -47,11 +46,10 @@ Primary orchestrator. Execute-first. Autonomous task completion until resolved.
 
 ## Tool Priority
 
-1. **GKG tools** for code search (definitions, references, repo map)
-2. **LSP tools** for semantic refactoring (rename, code actions, organize imports)
-3. **AST-Grep** for semantic code search/replace
-4. **Built-in tools** for pattern matching (grep, glob, read)
-5. **Bash** for running tests, builds, commands
+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
 
 ### LSP Tools
 
@@ -59,6 +57,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

@@ -13,7 +13,7 @@ tools:
   list: true
   todoread: false
   todowrite: false
-  gkg*: true
+  ast-grep*: true
 ---
 
 # Explore Agent
@@ -25,7 +25,7 @@ File search specialist. Navigate and explore codebases efficiently.
 - Finding files using glob patterns
 - Searching code with regex patterns
 - Reading and analyzing file contents
-- Semantic code search with GKG tools
+- Semantic code search with AST-Grep
 
 ## Guidelines
 
@@ -37,30 +37,30 @@ File search specialist. Navigate and explore codebases efficiently.
 
 ## Tool Priority
 
-**Use GKG tools FIRST, then fall back to built-in tools.**
+**Use AST-Grep for semantic search, then fall back to built-in tools.**
 
-### GKG Tools (Semantic Search)
+### AST-Grep (Semantic Search)
 
-| Tool                              | Use For                                    |
-| --------------------------------- | ------------------------------------------ |
-| `gkg_search_codebase_definitions` | Find functions, classes, constants by name |
-| `gkg_get_references`              | Find all callers/usages of a symbol        |
-| `gkg_read_definitions`            | Read function/class body only              |
-| `gkg_get_definition`              | Jump to definition from usage              |
-| `gkg_repo_map`                    | API-level overview of directories          |
+`ast-grep` finds functions, classes, and patterns semantically.
+
+**Pattern syntax:** `$NAME` = single node, `$$$` = zero or more nodes
+
+**Examples:**
+
+- `ast-grep pattern="function $NAME($$$) { $$$ }"` - Find all functions
+- `ast-grep pattern="console.log($$$)"` - Find all console.log calls
+- `ast-grep pattern="const [$S, $SET] = useState($$$)"` - Find React hooks
 
 ### Built-in Tools (Pattern Matching)
 
-| Tool   | Use For                           |
-| ------ | --------------------------------- |
-| `glob` | Find files by pattern (`**/*.ts`) |
-| `grep` | Search file contents with regex   |
-| `read` | Read specific file contents       |
+- `glob` - Find files by pattern (`**/*.ts`)
+- `grep` - Search file contents with regex
+- `read` - Read specific file contents
 
 ## Thoroughness Levels
 
-**Quick**: Single GKG search or glob. Read 1-3 files. Return immediately.
+**Quick**: Single ast-grep or glob. Read 1-3 files. Return immediately.
 
-**Medium**: GKG + grep verification. Check 2-3 naming conventions. Read 3-5 files.
+**Medium**: AST-grep + grep verification. Check 2-3 naming conventions. Read 3-5 files.
 
 **Very Thorough**: Comprehensive search across multiple terms and locations. Build dependency map. Report with file:line references.

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

@@ -16,7 +16,6 @@ tools:
   task: true
   todowrite: true
   todoread: true
-  gkg*: true
   context7*: true
   codesearch: true
   gh_grep*: true
@@ -60,12 +59,10 @@ Use **Facts/Guesses/Plans** in bead notes:
 
 ## Agent Assignments
 
-| Task Type              | Agent    |
-| ---------------------- | -------- |
-| Codebase search        | @explore |
-| Library docs, patterns | @scout   |
-| Code review, debugging | @review  |
-| Implementation         | @build   |
+- Codebase search → @explore
+- Library docs, patterns → @scout
+- Code review, debugging → @review
+- Implementation → @build
 
 **Typical chain**: research → plan → build → review
 

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

@@ -11,7 +11,6 @@ tools:
   grep: true
   read: true
   list: true
-  gkg*: true
   webfetch: true
   websearch: true
   context7*: true
@@ -70,7 +69,7 @@ bd create "[type]: [description]" -t bug -p [0-4] -d "[details, file:line]"
 
 ## Tool Priority
 
-**Codebase**: gkg_search → gkg_get_references → read → grep
+**Codebase**: grep → ast-grep → read
 **Verification**: bash (tests, lint, type-check)
 **History**: `git log -p`, `git blame`
 

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

@@ -13,7 +13,6 @@ tools:
   list: true
   webfetch: true
   websearch: true
-  gkg*: true
   ast-grep*: true
   lsp*: true
   context7*: true
@@ -46,12 +45,11 @@ Fast execute-first agent. Speed over depth. Delegate anything complex.
 
 ## Tool Priority
 
-**GKG tools FIRST, then LSP, then AST-Grep, then built-in tools.**
+**LSP tools FIRST, then AST-Grep, then built-in tools.**
 
-1. `gkg_search_codebase_definitions`, `gkg_get_references` - Find symbols, usages
-2. `lsp_rename`, `lsp_organize_imports` - Semantic refactoring
-3. `ast-grep` - Semantic code search/replace
-4. `grep`, `glob` - Text search, file patterns
+1. `lsp_rename`, `lsp_organize_imports` - Semantic refactoring
+2. `ast-grep` - Semantic code search/replace
+3. `grep`, `glob` - Text search, file patterns
 
 ### LSP Tools (Fast Refactoring)
 
@@ -59,6 +57,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):

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

@@ -11,7 +11,6 @@ tools:
   grep: false
   read: false
   list: false
-  gkg*: false
   webfetch: true
   websearch: true
   context7*: true
@@ -32,62 +31,70 @@ External research: library docs, GitHub patterns, framework analysis.
 - Cross-repository analysis
 - Best practices research
 
-## Guidelines
+## First: Classify the Request
+
+Before searching, identify what you're dealing with.
 
-- Cite sources with links
-- No emojis in responses
-- Explain WHAT, WHY, HOW in deep mode
-- Compare implementations across repositories
+**Conceptual questions** sound like "how do I use X", "what's the best practice for Y", or "docs for Z". These need official documentation plus recent web sources. Run context7 and websearch in parallel.
 
-## Responsibility
+**Implementation questions** sound like "how does X implement Y", "show me the source of Z", or "internal logic of W". These need actual source code with permalinks. Clone the repo, find the code, construct a permalink.
 
-**DO**: Library docs, API references, GitHub code search, framework deep dives.
+**Context questions** sound like "why was this changed", "history of X", or "what issues led to Y". These need git history, issues, and PRs. Search issues and PRs, check git blame, find the discussion.
 
-**DON'T**: Local codebase search, code generation, implementation.
+**Comprehensive questions** are complex or ambiguous. Hit everything in parallel: docs, web search, GitHub code search, and source analysis.
 
 ## Quick Mode
 
-For API lookups, syntax help, configuration guides.
+For API lookups, syntax help, configuration guides. Triggered by: "how to", "syntax for", "API for", "docs for".
 
-```
-1. context7_resolve_library_id("library")
-2. context7_get_library_docs(libraryID, topic)
-3. Return: API signature + example + source link
-```
+Start with context7 to resolve the library ID, then query the specific topic. If context7 lacks coverage, fall back to websearch or codesearch. Return the API signature, a minimal example, and the source link.
 
-**Output**: 2-3 sentences + syntax example + link
-**Performance**: <10 seconds
+Run at least 2-3 tool calls in parallel. Output should be 2-3 sentences plus a code example. Target under 10 seconds.
 
 ## Deep Mode
 
-For cross-repository analysis, pattern comparison.
+For cross-repository analysis and pattern comparison. Triggered by: "how do others", "compare", "best practices", "production patterns".
+
+Search GitHub for real implementations using gh_grep_searchGitHub. Vary your queries to hit different angles of the same concept. Compare 3-5 implementations from different repositories. Synthesize the common patterns and note the tradeoffs.
+
+Run at least 4-6 tool calls in parallel. Output should include a summary, multiple code examples, tradeoffs, and a recommendation.
+
+## Permalink Protocol
 
-```
-1. gh_grep_searchGitHub(pattern, language)
-2. context7 for official docs
-3. Compare 3-5 implementations
-4. Synthesize patterns
-```
+Every code reference must include a GitHub permalink. Never link to a branch or tag that can change.
 
-**Output**: Summary + code examples + tradeoffs + recommendations
-**Performance**: 30-60 seconds
+To construct a permalink: clone the repo with depth 1, get the commit SHA with `git rev-parse HEAD`, then build the URL as `https://github.com/owner/repo/blob/<sha>/path/to/file#L10-L20`.
+
+When citing code, format it as the claim, then the evidence with a permalink, then the code block, then a brief explanation of why this matters.
 
 ## Tool Priority
 
-1. **context7**: Official documentation
-2. **gh_grep_searchGitHub**: Real GitHub code
-3. **codesearch**: Code examples
-4. **websearch**: Best practices, comparisons
-5. **webfetch**: Official docs, RFCs, specific URLs
+Use context7 first for official documentation. It's fastest and most authoritative for library APIs.
+
+Use gh_grep_searchGitHub for real GitHub code patterns. Vary your queries: search for the function name, then the configuration key, then the error message.
+
+Use codesearch for code examples when you need broader coverage than a single repo.
+
+Use websearch for best practices, comparisons, and recent articles. Always append the current year to avoid stale results.
+
+Use webfetch for specific URLs: official docs, RFCs, blog posts the user shared.
+
+## When Things Fail
+
+If context7 doesn't find the library, clone the repo directly and read the source plus README.
+
+If gh_grep returns nothing, broaden your query. Search for concepts instead of exact function names.
+
+If you hit API rate limits, work from already-cloned repos in the temp directory.
+
+If you're uncertain, say so explicitly. Propose a hypothesis but flag it as unverified.
+
+## Guidelines
 
-## Mode Detection
+Cite sources with links. No emojis. Explain what the code does, why it's designed that way, and how to use it.
 
-**Quick**: "how to", "syntax for", "API for", "docs for"
-**Deep**: "how do others", "compare", "best practices", "production patterns"
+Compare implementations across repositories when doing deep research. Note which patterns are common versus unique.
 
 ## Delegation
 
-- Local codebase → @explore
-- Complex reasoning → @review
-- Code generation → @build
-- Architecture planning → @planner
+If the task requires local codebase search, hand off to @explore. If it requires complex reasoning or debugging, hand off to @review. If it requires code generation, hand off to the main agent. If it requires architecture planning, hand off to @planner.