opencodekit 0.13.2 → 0.14.0

package/dist/index.js

@@ -750,7 +750,7 @@ var cac = (name = "") => new CAC(name);
 // package.json
 var package_default = {
   name: "opencodekit",
-  version: "0.13.2",
+  version: "0.14.0",
   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 run build.ts && 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: {
@@ -802,7 +812,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

@@ -39,10 +39,19 @@ If yes → Delegate. If no → Execute directly.
 
 **Rule**: Always `read` before `edit`.
 
-1.  **LSP (Best)**: `lsp_lsp_document_symbols` (outline), `lsp_lsp_hover` (types), `lsp_lsp_goto_definition`.
-2.  **Structure**: `ast-grep` (Find functions/classes patterns)
-3.  **Search**: `grep` (Find text/TODOs)
-4.  **Files**: `glob` (Find files)
+1.  **LSP (Best)**: `lsp_lsp_document_symbols`, `lsp_lsp_goto_definition`. **Follow [LSP NAVIGATION AVAILABLE] nudges immediately.**
+2.  **Memory**: `memory-search` (Check past learnings), `repo-map` (Understand structure).
+3.  **Structure**: `ast-grep` (Find functions/classes patterns)
+4.  **Search**: `grep` (Find text/TODOs)
+5.  **Files**: `glob` (Find files)
+
+## Active Memory (The Brain)
+
+**Rule**: Use memory proactively, not just when asked.
+
+- **Start**: `memory-search` to find relevant context and code.
+- **Learn**: `observation` to save decisions, patterns, and gotchas.
+- **Act**: If you see an LSP Nudge, execute it. Don't wait.
 
 ## Beads (Task Tracking)
 

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

@@ -161,10 +161,106 @@ Plugins run automatically in every session:
 
 - **memory-read** - Load previous context, templates
 - **memory-update** - Save learnings, handoffs
-- **memory-search** - Search across all memory files
-- **observation** - Create structured observations
+- **memory-search** - Search across all memory files (keyword, semantic, hybrid)
+- **memory-index** - Rebuild vector store for semantic search
+- **memory-embed** - Generate embeddings using Ollama
+- **observation** - Create structured observations (auto-embedded)
 - **ast-grep** - Semantic code search/replace (AST-based)
 
+---
+
+## Semantic Memory Setup (Ollama)
+
+Semantic search requires Ollama running locally. Zero API keys needed.
+
+**Model:** `qwen3-embedding:0.6b` (639MB)
+
+- State-of-the-art quality (MTEB #1 for 8B version)
+- Code-aware (optimized for code retrieval)
+- Multilingual (100+ languages including Vietnamese)
+- 32K context, 1024 dimensions
+
+### Installation
+
+**macOS:**
+
+```bash
+brew install ollama
+```
+
+**Linux:**
+
+```bash
+curl -fsSL https://ollama.com/install.sh | sh
+```
+
+**Windows:**
+
+1. Download from https://ollama.com/download/windows
+2. Run the installer
+3. Ollama runs as a background service automatically
+
+### Setup
+
+```bash
+# Start Ollama (macOS/Linux - if not running as service)
+ollama serve
+
+# Pull embedding model (one-time, ~639MB)
+ollama pull qwen3-embedding:0.6b
+
+# Verify
+ollama list  # Should show qwen3-embedding:0.6b
+```
+
+**Linux:**
+
+```bash
+curl -fsSL https://ollama.com/install.sh | sh
+```
+
+**Windows:**
+
+1. Download from https://ollama.com/download/windows
+2. Run the installer
+3. Ollama runs as a background service automatically
+
+### Setup
+
+```bash
+# Start Ollama (macOS/Linux - if not running as service)
+ollama serve
+
+# Pull embedding model (one-time, ~274MB)
+ollama pull nomic-embed-text
+
+# Verify
+ollama list  # Should show nomic-embed-text
+```
+
+### Custom Host (Optional)
+
+If Ollama runs on a different machine:
+
+```bash
+export OLLAMA_HOST=http://192.168.1.100:11434
+```
+
+### Usage
+
+```bash
+# Rebuild vector index (after adding new observations)
+memory-index action=rebuild
+
+# Search with semantic similarity
+memory-search query="authentication patterns" mode=semantic
+
+# Hybrid search (keyword + semantic)
+memory-search query="auth" mode=hybrid
+```
+
+---
+
 ### AST-Grep Usage
 
 Semantic code operations - smarter than regex:

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

@@ -33,12 +33,35 @@ If `$ARGUMENTS` is a bead ID:
 
 Load constraints from `.beads/artifacts/<bead-id>/spec.md` if it exists.
 
-**Check for prior thinking:**
+**Check for prior thinking (Semantic Search):**
 
 ```typescript
-memory - search({ query: "[topic keywords]" });
+// Search for related ideas and past brainstorms
+memory -
+  search({
+    query: "[topic keywords]",
+    mode: "semantic",
+    limit: 5,
+  });
+
+// Find related observations
+memory -
+  search({
+    query: "[topic]",
+    mode: "semantic",
+    type: "observation",
+    limit: 3,
+  });
 ```
 
+Review findings for:
+
+- Previous brainstorms on similar topics
+- Related decisions and patterns
+- Ideas that were considered before
+
+If memory search fails (Ollama not running), continue without it.
+
 ## Phase 2: Set Boundaries
 
 Before brainstorming, establish:

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

@@ -166,17 +166,34 @@ Write `.beads/artifacts/$ARGUMENTS/review.md`:
 
 ## Record Learnings
 
-If you discovered patterns or gotchas worth remembering:
+If you discovered patterns, gotchas, or decisions worth remembering:
 
 ```typescript
 observation({
-  type: "learning",
-  title: "[concise title]",
-  content: "[what you learned]",
+  type: "learning", // or "pattern", "bugfix", "decision", "warning"
+  title: "[concise, searchable title]",
+  content: "[what you learned - be specific and actionable]",
   bead_id: "$ARGUMENTS",
+  files: "[affected files, comma-separated]",
+  concepts: "[keywords for semantic search]",
 });
 ```
 
+**This auto-embeds into the vector store** for future semantic search. Future `/start` and `/implement` commands will find this learning.
+
+**When to create observations:**
+
+- Discovered a non-obvious gotcha
+- Made a significant architectural decision
+- Found a pattern worth reusing
+- Hit a bug that others might hit
+
+**Skip observations for:**
+
+- Routine implementations
+- Well-documented patterns
+- Trivial fixes
+
 ## Output
 
 ```

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

@@ -46,6 +46,23 @@ git commit -m "WIP: $ARGUMENTS - [where you stopped]"
 
 Don't leave uncommitted work. The next session needs a clean starting point.
 
+## Record Key Learnings (Before Handoff)
+
+If you discovered important patterns or gotchas during this session:
+
+```typescript
+observation({
+  type: "learning", // or "pattern", "decision", "warning"
+  title: "[concise, searchable title]",
+  content: "[what you learned - specific and actionable]",
+  bead_id: "$ARGUMENTS",
+  files: "[affected files]",
+  concepts: "[keywords for semantic search]",
+});
+```
+
+**This auto-embeds** into the vector store. The next `/resume` will find it.
+
 ## Create The Handoff
 
 ```bash

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

@@ -98,6 +98,44 @@ search_session({ query: "$ARGUMENTS" });
 read_session({ session_reference: "last" });
 ```
 
+## Load Related Memory (Semantic Search)
+
+First, get a quick codebase overview:
+
+```typescript
+// Quick overview of relevant directories
+repo-map({ path: "src", format: "compact", maxDepth: 3 });
+```
+
+Then search for relevant patterns and learnings:
+
+```typescript
+// Find similar past work
+memory -
+  search({
+    query: "[task description from bead]",
+    mode: "semantic",
+    limit: 3,
+  });
+
+// Find related gotchas and patterns
+memory -
+  search({
+    query: "[technology/domain keywords]",
+    mode: "semantic",
+    type: "observation",
+    limit: 3,
+  });
+```
+
+**Review findings before implementation.** Past observations may contain:
+
+- Gotchas to avoid (save debugging time)
+- Patterns that worked well (reuse them)
+- Decisions already made (don't re-decide)
+
+If memory search fails (Ollama not running), continue without it.
+
 ## Parallel Subagent Research (if --parallel or complex task)
 
 **Delegation Pattern: Fire and Continue**

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

@@ -37,6 +37,38 @@ cat .beads/artifacts/$ARGUMENTS/research.md 2>/dev/null || echo "No research fou
 
 **If complexity > M and no research:** "Consider `/research $ARGUMENTS` first for better planning."
 
+## Check Memory First (Semantic Search)
+
+Before subagent research, check what we already know:
+
+```typescript
+// Find similar past plans
+memory -
+  search({
+    query: "[bead title/description]",
+    mode: "semantic",
+    type: "bead",
+    limit: 3,
+  });
+
+// Find related patterns and decisions
+memory -
+  search({
+    query: "[domain keywords]",
+    mode: "semantic",
+    type: "observation",
+    limit: 3,
+  });
+```
+
+Review findings for:
+
+- Similar plans that worked well (reuse structure)
+- Patterns and decisions already made
+- Gotchas to avoid in planning
+
+If memory search fails (Ollama not running), continue to subagent research.
+
 ---
 
 ## Phase 1: Parallel Subagent Research

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

@@ -17,6 +17,19 @@ You're gathering information before implementation. Find answers, document findi
 
 ## Load Context
 
+### Get Quick Codebase Overview
+
+First, understand the codebase structure:
+
+```typescript
+// Quick overview of relevant directories
+repo-map({ path: "src", format: "compact", maxDepth: 3 });
+```
+
+This helps identify relevant directories and files before diving deeper.
+
+### Load Bead Details
+
 !`bd show $ARGUMENTS`
 !`cat .beads/artifacts/$ARGUMENTS/spec.md`
 
@@ -29,14 +42,38 @@ Extract questions that need answering from spec.
 
 Extract the questions that need answering from the spec.
 
-## Check For Previous Research
+## Check Memory First (Semantic Search)
+
+Before hitting external sources, search what we already know:
 
 ```typescript
-search_session({ query: "[topic keywords]" });
-list_sessions({ project: "current", since: "this week", limit: 5 });
+// Search past research and observations on similar topics
+memory -
+  search({
+    query: "[research question/topic]",
+    mode: "semantic",
+    limit: 5,
+  });
+
+// Search for related gotchas and learnings
+memory -
+  search({
+    query: "[topic keywords]",
+    mode: "semantic",
+    type: "observation",
+    limit: 3,
+  });
 ```
 
-Don't duplicate work that's already been done.
+**If memory has high-confidence answers, you may skip external research.**
+
+Review findings for:
+
+- Previous research on this exact topic
+- Related patterns and decisions
+- Known gotchas to avoid
+
+If memory search fails (Ollama not running), continue to external sources.
 
 ## Source Priority
 
@@ -49,7 +86,26 @@ Don't duplicate work that's already been done.
 
 ## Research
 
-### Internal Codebase
+### Internal Codebase - Get Quick Overview
+
+First, generate a compact repository map to understand the codebase structure:
+
+```typescript
+// Quick overview of relevant directories
+repo-map({ path: "src", format: "compact", maxDepth: 3 });
+
+// For specific feature area
+repo-map({ path: "src/commands", format: "tree", maxDepth: 2 });
+```
+
+**Use repo-map 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
 
 ```typescript
 // Find similar patterns

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

@@ -71,6 +71,37 @@ Extract from session:
 - Where work stopped
 - Problems encountered
 
+## Load Related Memory (Semantic Search)
+
+Search for relevant observations and past work:
+
+```typescript
+// Find observations related to this bead
+memory -
+  search({
+    query: "$ARGUMENTS [bead title/description]",
+    mode: "semantic",
+    type: "observation",
+    limit: 5,
+  });
+
+// Find similar past work
+memory -
+  search({
+    query: "[bead description keywords]",
+    mode: "semantic",
+    limit: 3,
+  });
+```
+
+**Review findings** - past observations may contain:
+
+- Gotchas discovered during previous sessions
+- Decisions already made
+- Patterns that worked
+
+If memory search fails (Ollama not running), continue without it.
+
 ## Load Artifacts
 
 Read all available context:

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

@@ -172,6 +172,37 @@ list_sessions({ limit: 3 });
 
 Load context from previous work on this bead.
 
+## Load Related Memory (Semantic Search)
+
+Search for relevant past work and learnings before starting:
+
+```typescript
+// Find similar past work (semantic similarity)
+memory -
+  search({
+    query: "[task title/description from bead]",
+    mode: "semantic",
+    limit: 3,
+  });
+
+// Find related observations (gotchas, patterns, learnings)
+memory -
+  search({
+    query: "[task keywords]",
+    mode: "semantic",
+    type: "observation",
+    limit: 3,
+  });
+```
+
+**Review findings before diving in.** Past observations may contain:
+
+- Gotchas to avoid
+- Patterns that worked well
+- Decisions already made
+
+If memory search fails (Ollama not running), continue without it.
+
 ## Determine Next Step
 
 Based on task type and what exists:

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

@@ -340,7 +340,22 @@ bd list --status=closed --json | wc -l  # Check closed count
 
 **Best Practice (from Steve Yegge):** Run `bd cleanup` every few days to prevent database bloat.
 
-## Phase 10: Sync and Notify
+## Phase 10: Check Memory Health
+
+```typescript
+memory - index({ action: "status" });
+```
+
+If documents count is low or index is stale:
+
+```
+⚠️  Vector store may be stale.
+Run: memory-index rebuild
+```
+
+Optionally trigger background reindex if many observations were created recently.
+
+## Phase 11: Sync and Notify
 
 ```typescript
 

package/dist/template/.opencode/memory/project/conventions.md

@@ -85,6 +85,37 @@ Always protect these tools from auto-pruning:
 ]
 ```
 
+### Prompt Injection Pattern (Nudges)
+
+Use `chat.message` hook to inject prompts (nudges) based on user triggers:
+
+```typescript
+"chat.message": async (input, output) => {
+  const { message, parts } = output;
+  if (message.role !== "user") return;
+
+  // 1. Detect trigger keywords
+  const fullText = parts.map(p => p.text).join(" ");
+  if (!fullText.match(/trigger pattern/)) return;
+
+  // 2. Inject synthetic prompt
+  parts.push({
+    type: "text",
+    text: "━━━━━━━━\n[TRIGGER DETECTED]\nAction required: ...\n━━━━━━━━",
+    synthetic: true
+  });
+}
+```
+
+This transforms passive detection into active agent behavior (e.g., Memory plugin triggers).
+
+## Agent Behavior Rules
+
+### Active LSP Nudge
+
+When a tool output displays `[LSP NAVIGATION AVAILABLE]`, it means relevant code files were found.
+**Rule**: You MUST immediately execute the suggested `lsp_lsp_*` tool calls to retrieve code context without waiting for user instruction. This ensures you always have the latest code context for your implementation.
+
 ## Patterns to Avoid
 
 ### Anti-Pattern: Mixing LSP Systems