opencodekit 0.16.0 → 0.16.2

package/dist/index.js

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

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

@@ -16,6 +16,27 @@ Everything else is guidelines, not laws.
 
 ---
 
+## Trust Hierarchy
+
+**DO NOT search when instructions already exist.** Searching is expensive. Follow this order:
+
+1. **AGENTS.md** - Project-specific rules (this file or `./AGENTS.md`)
+2. **Memory** - Past decisions, patterns, gotchas (`memory-search`)
+3. **Project files** - `.opencode/memory/project/` (commands, conventions, tech-stack)
+4. **Codebase search** - Only if above sources are incomplete or wrong
+
+If instructions are incomplete or wrong, **update them** after finding the truth. Don't just use the correct info once—fix the source so future work benefits.
+
+### Atomic Version
+
+```
+DO NOT search when instructions exist.
+TRUST: AGENTS.md → memory → project files → search
+UPDATE instructions when you find errors.
+```
+
+---
+
 ## Skills vs Commands
 
 - Use **commands** for user-facing entrypoints (workflows and intent).
@@ -219,17 +240,51 @@ Chain: grep → read → LSP(9) → memory → understand → edit
 
 **DO NOT proceed without checking memory proactively.** Memory is your external brain. Use it before you start work, not just when someone asks you to.
 
+### Memory Architecture
+
+The memory system uses **SQLite + FTS5** as the single source of truth:
+
+```
+Write: observation() → SQLite only
+       memory-update() → SQLite only
+
+Read:  memory-search() → FTS5 full-text search (BM25 ranking)
+       memory-get() → Full observation details by ID
+       memory-read() → SQLite only
+       memory-timeline() → Chronological context around anchor
+```
+
 ### The Three Actions
 
-First, DO NOT start any significant work without checking memory. Run `memory-search` to find relevant context about the project, the user's preferences, and past decisions. Run `memory-read` for active files that contain information you need to remember. Checking memory before starting prevents you from forgetting important context that affects your work.
+First, DO NOT start any significant work without checking memory. Run `memory-search` to find relevant context using FTS5 full-text search. The search returns a **compact index** (50-100 tokens per result) for progressive disclosure. If you need full details, use `memory-get` with the observation ID.
+
+Second, DO NOT skip saving your own learnings. When you make decisions, discover patterns, or encounter gotchas, use the `observation` tool to save them immediately. Use the enhanced schema:
 
-Second, DO NOT skip saving your own learnings. When you make decisions, discover patterns, or encounter gotchas, use the `observation` tool to save them immediately. Capture the insight before you forget it. What you don't write down, you will lose.
+```typescript
+observation({
+  type: "decision", // decision, bugfix, feature, pattern, discovery, learning, warning
+  title: "Use JWT for auth",
+  narrative: "Why this decision was made...",
+  facts: "stateless, scalable", // Key facts (comma-separated)
+  concepts: "auth, jwt, security", // Keywords for search
+  confidence: "high", // high, medium, low
+});
+```
 
 Third, DO NOT ignore LSP nudges. If the system suggests running an LSP operation and you see that nudge, execute it immediately. Don't defer it and don't skip it. Nudges exist because something needs attention.
 
 ### Memory-start protocol
 
-At the start of any significant task, complete these three steps in order. First, run `memory-search` with relevant keywords to find context. Second, run `memory-read` on project files that might be relevant. Third, run `memory-read` on user preference files to remember what the user wants. Only after completing these steps should you proceed with the actual work.
+At the start of any significant task, complete these three steps in order. First, run `memory-search` with relevant keywords to find context (returns compact index). Second, run `memory-get` for any observations you need full details on. Third, run `memory-read` for handoffs, research, or template files. Only after completing these steps should you proceed with the actual work.
+
+### Progressive Disclosure Pattern
+
+Memory search intentionally returns **compact results** (50-100 tokens each) to avoid context bloat. Follow this pattern:
+
+1. `memory-search({ query: "auth" })` → Get compact index
+2. Identify relevant observation IDs from index
+3. `memory-get({ ids: "42,45" })` → Fetch full details only for what you need
+4. `memory-timeline({ anchor_id: 42 })` → See chronological context if needed
 
 ### Atomic Version
 
@@ -237,8 +292,35 @@ At the start of any significant task, complete these three steps in order. First
 DO NOT start without memory-search.
 DO NOT skip observation on decisions.
 DO NOT ignore LSP Nudges.
+
+Pattern: search → identify IDs → get details → proceed
 ```
 
+### Memory Maintenance
+
+For long-term storage health, use `memory-maintain` periodically:
+
+```bash
+# Check current status
+memory-maintain({ operation: "status" })
+
+# Full maintenance (archive >90 days, checkpoint WAL, vacuum)
+memory-maintain({ operation: "full" })
+
+# Preview what would be archived
+memory-maintain({ operation: "archive", older_than_days: 60, dry_run: true })
+```
+
+**Automatic maintenance** runs at session end:
+
+- FTS5 index optimization
+- WAL checkpoint (if WAL > 1MB)
+
+**Manual maintenance** (run monthly or when storage grows):
+
+- `archive`: Move old observations to archive table
+- `vacuum`: Defragment and reclaim space
+
 ---
 
 ## Beads (Task Tracking)
@@ -362,7 +444,25 @@ Before you start implementing, verify the requirements are clear. If interpretat
 
 Before you claim completion, verify these things:
 
-1. **Run review agent** on any significant code changes:
+1. **Run validation commands** (in order):
+
+   ```bash
+   # Type check (REQUIRED if TypeScript/JavaScript)
+   npm run typecheck  # or: bun run typecheck, tsc --noEmit
+
+   # Build (REQUIRED)
+   npm run build  # or: bun run build, cargo build, go build
+
+   # Test (REQUIRED if tests exist)
+   npm test  # or: bun test, cargo test, go test, pytest
+
+   # Lint (REQUIRED if linter configured)
+   npm run lint  # or: bun run lint, cargo clippy, golangci-lint
+   ```
+
+   Skip only if project lacks that script. Document missing scripts in `project/gotchas.md`.
+
+2. **Run review agent** on any significant code changes:
 
    ```typescript
    Task({
@@ -374,11 +474,12 @@ Before you claim completion, verify these things:
 
    If review suggests simplification, implement it before proceeding.
 
-2. You ran `bd close <id>` with a meaningful reason
-3. You ran `bd sync` to push changes
-4. There are no pending LSP nudges
-5. You saved observations for any important decisions or patterns
+3. You ran `bd close <id>` with a meaningful reason
+4. You ran `bd sync` to push changes
+5. There are no pending LSP nudges
+6. You saved observations for any important decisions or patterns
 
+**DO NOT skip validation commands.** Failed builds/tests after merge waste everyone's time.
 **DO NOT skip the Oracle critique for non-trivial changes.** This prevents bloated, overcomplicated solutions that could be 10x simpler.
 
 ---

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

@@ -1,8 +1,7 @@
 ---
 description: Create a specification for a bead using templates
 argument-hint: "<bead-id> [--prd] [--proposal]"
-agent: plan
-subtask: true
+agent: build
 ---
 
 # Create: $ARGUMENTS
@@ -22,8 +21,27 @@ Create structured artifacts for a bead using templates. This is the first step b
 ```typescript
 skill({ name: "beads" });
 skill({ name: "brainstorming" });
+skill({ name: "memory-system" });
 ```
 
+## Check Memory First
+
+Search for similar specs and patterns before creating:
+
+```typescript
+// Find similar past specs
+memory_search({ query: "[bead title/description]", limit: 3 });
+
+// Find related patterns and conventions
+memory_search({ query: "[domain keywords] spec requirements", limit: 3 });
+```
+
+Review findings for:
+
+- Similar specs that worked well (reuse structure)
+- Patterns and conventions already established
+- Gotchas to avoid in this domain
+
 ## Load Bead Context
 
 ```bash
@@ -89,7 +107,8 @@ question({
     },
     {
       header: "Users",
-      question: "Who will use this? (developers, end users, API consumers, etc.)",
+      question:
+        "Who will use this? (developers, end users, API consumers, etc.)",
       options: [
         { label: "Developers", description: "Internal tooling or API" },
         { label: "End users", description: "Customer-facing feature" },
@@ -232,6 +251,21 @@ Update bead with note:
 bd note $ARGUMENTS "Created spec.md with [N] requirements"
 ```
 
+## Record Learning (If Significant)
+
+If you discovered patterns or made decisions worth remembering:
+
+```typescript
+observation({
+  type: "pattern", // or "decision"
+  title: "[Domain] spec pattern for [type of feature]",
+  narrative: "When creating specs for [this type], include...",
+  concepts: "[domain keywords]",
+  bead_id: "$ARGUMENTS",
+  confidence: "medium",
+});
+```
+
 ---
 
 ## Output

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

@@ -11,8 +11,27 @@ subtask: true
 
 ```typescript
 skill({ name: "beads" });
+skill({ name: "memory-system" });
 ```
 
+## Check Memory First
+
+Search for existing design decisions and patterns:
+
+```typescript
+// Find similar design work
+memory_search({ query: "[component/page name] design UI", limit: 3 });
+
+// Find design system decisions
+memory_search({ query: "design system colors typography", limit: 3 });
+```
+
+Review findings for:
+
+- Existing aesthetic direction decisions
+- Color and typography choices already made
+- UI patterns that worked well
+
 ## Phase 1: Context Discovery
 
 Parse `$ARGUMENTS` to determine design task:
@@ -565,6 +584,22 @@ Before finalizing, verify design does NOT have ALL of these together:
 **Quick design:** Output inline, no save needed
 **Full design:** Save to `.opencode/memory/design/specs/[YYYY-MM-DD]-[topic].md`
 
+### Record Design Decisions
+
+For significant design choices, create an observation:
+
+```typescript
+observation({
+  type: "decision",
+  title: "Design direction for [component/page]",
+  narrative: "Chose [aesthetic direction] because [rationale]...",
+  facts: "[key design tokens, colors, typography choices]",
+  concepts: "design, ui, [component type], [aesthetic]",
+  bead_id: "$ARGUMENTS", // if applicable
+  confidence: "high",
+});
+```
+
 ### Create Implementation Tasks
 
 For component/page designs:

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

@@ -13,8 +13,23 @@ You're pausing work on a task. Save state so the next session can pick up cleanl
 ```typescript
 skill({ name: "beads" });
 skill({ name: "session-management" });
+skill({ name: "memory-system" });
 ```
 
+## Check Memory for Context
+
+Before creating handoff, search for related work:
+
+```typescript
+// Find previous handoffs and sessions for this bead
+memory_search({ query: "$ARGUMENTS handoff progress", limit: 3 });
+
+// Find related decisions and learnings
+memory_search({ query: "[bead description keywords]", limit: 3 });
+```
+
+Review findings to include relevant context in the handoff.
+
 ## Why Handoff?
 
 - Context window getting full

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

@@ -1,8 +1,7 @@
 ---
 description: Initialize project for AI-assisted development (creates AGENTS.md + memory files)
 argument-hint: "[--deep] [--skip-questions]"
-agent: plan
-subtask: true
+agent: build
 ---
 
 # Init: $ARGUMENTS
@@ -155,57 +154,49 @@ If the repo is large or keeps changing (monorepos especially), generate/refresh
 
 ## Phase 5: Populate Memory Files
 
-### .opencode/memory/user.md
+Read templates, then use `write` tool to create actual markdown files:
 
-```markdown
----
-purpose: User identity, preferences, communication style
-updated: [today]
----
-
-# User Profile
-
-## Identity
-
-- Name: [from git/questions]
-- Git contributor: [email/username]
-
-## Preferences
-
-- Communication: [terse/detailed]
-- Workflow: [auto-commit/ask-first]
-
-## Rules
-
-[from Phase 1]
+```typescript
+// 1. Read templates to understand structure
+read({ filePath: ".opencode/memory/_templates/user.md" });
+read({ filePath: ".opencode/memory/_templates/tech-stack.md" });
+
+// 2. Use WRITE tool to create/update actual markdown files
+// ⚠️ IMPORTANT: memory-update writes to SQLite, NOT markdown files!
+// Use write() for .md files, memory-update() for SQLite storage
+
+write({
+  filePath: ".opencode/memory/project/user.md",
+  content: "..." // Populated from Phase 1 answers
+});
+
+write({
+  filePath: ".opencode/memory/project/tech-stack.md",
+  content: "..." // Populated from Phase 2 detection
+});
 ```
 
-### .opencode/memory/project/tech-stack.md
-
-```markdown
----
-purpose: Tech stack, constraints, and integrations for AI context injection
-updated: [today]
----
+**Critical distinction:**
+- `write()` → Updates **markdown files** on disk
+- `memory-update()` → Writes to **SQLite database** (memory system)
 
-# Tech Stack
+### .opencode/memory/project/user.md
 
-## Framework & Language
+Populate from Phase 1 answers:
+- Identity (name, git contributor)
+- Communication preferences (terse/detailed)
+- Workflow preferences (auto-commit/ask-first)
+- Custom rules
 
-- **Framework:** [detected, e.g., Next.js 15]
-- **Language:** [detected, e.g., TypeScript]
-- **Runtime:** [detected, e.g., Node.js 22]
-
-## Key Dependencies
-
-- [detected from package.json/go.mod/etc.]
-
-## Key Constraints
+### .opencode/memory/project/tech-stack.md
 
-- [detected or ask user]
-```
+Populate from Phase 2 detection:
+- Framework & version
+- Language & runtime
+- Key dependencies with versions
+- Key constraints
 
-**Note:** AI discovers commands, architecture, conventions, and gotchas organically from the codebase and saves learnings via the `observation` tool. No need for static template files.
+**Note:** AI discovers commands, architecture, conventions, and gotchas organically and saves via `observation` tool.
 
 ## Phase 6: Initialize Beads (if requested)
 
@@ -260,8 +251,10 @@ Suggested next steps:
 ```
 ./AGENTS.md                              # Project-specific rules (created, <60 lines)
 .opencode/AGENTS.md                      # Global rules (untouched)
-.opencode/memory/user.md                 # User preferences (created)
-.opencode/memory/project/tech-stack.md   # Tech stack for context injection (created)
+.opencode/memory/_templates/user.md      # User template
+.opencode/memory/_templates/tech-stack.md # Tech stack template
+.opencode/memory/project/user.md         # User preferences (created from template)
+.opencode/memory/project/tech-stack.md   # Tech stack (created from template)
 .opencode/memory/observations/           # Learnings captured organically by AI
 [packages/*/AGENTS.md]                   # Subsystem rules (--deep, if requested)
 ```

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

@@ -24,6 +24,7 @@ skill({ name: "deep-research" });
 skill({ name: "executing-plans" });
 skill({ name: "writing-plans" });
 skill({ name: "subagent-driven-development" });
+skill({ name: "memory-system" });
 ```
 
 ```bash

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

@@ -11,8 +11,23 @@ agent: build
 ```typescript
 skill({ name: "beads" }); // Session protocol
 skill({ name: "verification-before-completion" });
+skill({ name: "memory-system" });
 ```
 
+## Check Memory for Related Context
+
+Search for related decisions and patterns:
+
+```typescript
+// Find related decisions and patterns for this work
+memory_search({ query: "$ARGUMENTS [feature keywords]", limit: 3 });
+
+// Find any gotchas related to this area
+memory_search({ query: "[affected files/modules] gotchas", limit: 2 });
+```
+
+Include relevant context from memory in PR description.
+
 ## Options
 
 - `--draft`: Create as draft PR (for WIP or early feedback)

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

@@ -28,6 +28,9 @@ skill({ name: "source-code-research" });
 
 // For swarm coordination (if parallel research needed)
 skill({ name: "swarm-coordination" });
+
+// For memory context
+skill({ name: "memory-system" });
 ```
 
 ## Delegation Strategy

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

@@ -13,6 +13,7 @@ You're picking up where a previous session left off. Recover context, verify sta
 ```typescript
 skill({ name: "beads" });
 skill({ name: "beads-bridge" }); // For cross-session recovery
+skill({ name: "memory-system" });
 ```
 
 ## Verify The Task Exists

package/dist/template/.opencode/command/review-codebase.md

@@ -11,8 +11,23 @@ subtask: true
 
 ```typescript
 skill({ name: "beads" });
+skill({ name: "memory-system" });
 ```
 
+## Check Memory for Context
+
+Search for existing patterns and gotchas before review:
+
+```typescript
+// Find related past reviews and findings
+memory_search({ query: "[path/module] review security", limit: 3 });
+
+// Find known gotchas for this area
+memory_search({ query: "[module keywords] gotchas patterns", limit: 3 });
+```
+
+Apply past learnings to the review - don't repeat known issues.
+
 ## Phase 1: Determine Scope
 
 Parse `$ARGUMENTS` to determine what to review:
@@ -205,3 +220,18 @@ Skip creating beads for Minor issues (just report them).
 - Vague feedback ("improve error handling" - WHERE? HOW?)
 - Skipping automated checks "to save time"
 - Not creating beads for real issues (they get forgotten)
+
+## Record Significant Findings
+
+For important findings worth remembering:
+
+```typescript
+observation({
+  type: "warning", // or "pattern", "bugfix"
+  title: "[Module] [Issue type] pattern detected",
+  narrative: "Found [issue] in [location], which can cause...",
+  facts: "[key facts about the issue]",
+  concepts: "[module], security, [issue keywords]",
+  confidence: "high",
+});
+```

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

@@ -18,8 +18,23 @@ skill({ name: "finishing-a-development-branch" });
 skill({ name: "receiving-code-review" });
 skill({ name: "swarm-coordination" });
 skill({ name: "beads-bridge" });
+skill({ name: "memory-system" });
 ```
 
+## Check Memory for Context
+
+Search for related patterns and gotchas before shipping:
+
+```typescript
+// Find related patterns and decisions
+memory_search({ query: "$ARGUMENTS [feature keywords]", limit: 3 });
+
+// Find gotchas for affected modules
+memory_search({ query: "[affected modules] gotchas", limit: 3 });
+```
+
+Apply past learnings to avoid known issues.
+
 ## Skill Routing
 
 - Use **systematic-debugging** when a gate fails and root cause is unclear.
@@ -154,3 +169,31 @@ If confirmed:
 bd close $ARGUMENTS --reason "Shipped: verification + review passed"
 bd sync
 ```
+
+## Record Learnings (On Completion)
+
+Before ending, capture what was learned:
+
+```typescript
+// Record significant decisions or patterns discovered
+observation({
+  type: "feature", // or "decision", "pattern"
+  title: "$ARGUMENTS: [brief description]",
+  narrative: "Implemented [feature]. Key approach: [summary]...",
+  facts: "[key implementation details]",
+  concepts: "[domain keywords], [tech stack]",
+  bead_id: "$ARGUMENTS",
+  files_modified: "[key files changed]",
+  confidence: "high",
+});
+
+// If encountered gotchas worth remembering
+observation({
+  type: "warning",
+  title: "[Gotcha discovered during $ARGUMENTS]",
+  narrative: "While implementing, discovered that...",
+  concepts: "[relevant keywords]",
+  bead_id: "$ARGUMENTS",
+  confidence: "high",
+});
+```

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

@@ -27,6 +27,7 @@ skill({ name: "beads" });
 skill({ name: "beads-bridge" }); // For cross-session todo coordination
 skill({ name: "prd" }); // PRD creation workflow
 skill({ name: "prd-task" }); // PRD to executable tasks conversion
+skill({ name: "memory-system" });
 ```
 
 ## Ensure Git Hooks Installed

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

@@ -11,9 +11,10 @@ subtask: true
 
 ```typescript
 skill({ name: "beads" });
+skill({ name: "memory-system" });
 ```
 
-Generate a comprehensive project status report covering tasks, sessions, git state, and system health.
+Generate a comprehensive project status report covering tasks, sessions, git state, memory health, and system health.
 
 ## Phase 1: Gather All State (Parallel)
 
@@ -250,6 +251,28 @@ Fri ██████████ 10
 
 ## Phase 5: Session Insights
 
+### Memory Health
+
+```typescript
+// Check memory system status
+memory_maintain({ operation: "status", older_than_days: 90, dry_run: false });
+```
+
+Display memory stats in dashboard:
+
+```
+MEMORY STATUS
+━━━━━━━━━━━━
+Observations:     [N] stored
+Database size:    [X] KB
+FTS Index:        ✓ Healthy
+Last search:      [timestamp]
+
+Recent learnings:
+• [Latest observation title] (type: decision)
+• [Latest observation title] (type: pattern)
+```
+
 ### Context Health
 
 ```typescript