opencodekit 0.15.21 → 0.16.1

package/dist/index.js

@@ -750,7 +750,7 @@ var cac = (name = "") => new CAC(name);
 // package.json
 var package_default = {
   name: "opencodekit",
-  version: "0.15.21",
+  version: "0.16.1",
   description: "CLI tool for bootstrapping and managing OpenCodeKit projects",
   keywords: ["agents", "cli", "mcp", "opencode", "opencodekit", "template"],
   license: "MIT",
@@ -3869,23 +3869,21 @@ var MODEL_PRESETS = {
       looker: "opencode/kimi-k2.5-free",
       vision: "opencode/kimi-k2.5-free",
       scout: "opencode/minimax-m2.1-free",
-      painter: "opencode/kimi-k2.5-free",
-      compaction: "opencode/kimi-k2.5-free"
+      painter: "opencode/kimi-k2.5-free"
     }
   },
   recommend: {
     model: "github-copilot/claude-opus-4.5",
     agents: {
       build: "github-copilot/claude-opus-4.5",
-      plan: "openai/gpt-5.2",
-      review: "openai/gpt-5.2-codex",
+      plan: "github-copilot/gpt-5.2-codex",
+      review: "github-copilot/gpt-5.2-codex",
       explore: "proxypal/gemini-3-flash-preview",
       general: "opencode/kimi-k2.5-free",
       looker: "proxypal/gemini-3-flash-preview",
       vision: "proxypal/gemini-3-pro-preview",
       scout: "opencode/kimi-k2.5-free",
-      painter: "proxypal/gemini-3-pro-image-preview",
-      compaction: "opencode/kimi-k2.5-free"
+      painter: "proxypal/gemini-3-pro-image-preview"
     }
   }
 };

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

@@ -16,6 +16,12 @@ Everything else is guidelines, not laws.
 
 ---
 
+## Skills vs Commands
+
+- Use **commands** for user-facing entrypoints (workflows and intent).
+- Use **skills** for reusable procedures and checklists.
+- If a command mostly repeats steps used elsewhere, move those steps into a skill.
+
 ## Core Constraints
 
 These are hard limits that must never be violated:
@@ -213,17 +219,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. Capture the insight before you forget it. What you don't write down, you will lose.
+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:
+
+```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
 
@@ -231,8 +271,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)
@@ -303,7 +370,7 @@ When tools fail or return unexpected results:
 
 1. **DO NOT** retry the same call more than twice
 2. Check fallback chains in agent documentation
-3. **Use Oracle for second opinion** on complex debugging
+3. **Use review agent for second opinion** on complex debugging
 4. If still stuck, ask user for guidance
 5. Log failures using `observation` tool for future reference
 
@@ -311,13 +378,13 @@ When tools fail or return unexpected results:
 
 ```
 Primary tool fails → Try alternative tool
-Alternative fails → Oracle for second opinion
+Alternative fails → Spawn review agent for second opinion
 Still stuck → Ask user
 ```
 
-### Oracle Tool
+### Review Agent (Second Opinion)
 
-Use `oracle` to get a second opinion from a different AI model (gpt-5.2-codex by default) for complex reasoning tasks.
+Use `review` (via Task) to get a second opinion on complex reasoning tasks.
 
 **When to use:**
 
@@ -326,17 +393,12 @@ Use `oracle` to get a second opinion from a different AI model (gpt-5.2-codex by
 - Getting alternative perspectives on tricky problems
 - Breaking out of reasoning ruts or confirmation bias
 
-**Modes:**
-
-- `validate`: Check if reasoning is sound (default)
-- `alternative`: Get completely different approaches
-- `critique`: Stress-test ideas for weaknesses
-- `brainstorm`: Expand and generate new possibilities
-
 ```typescript
-oracle({ question: "Is this the right approach?", context: "..." });
-oracle({ question: "Why is this failing?", mode: "critique" });
-oracle({ question: "What alternatives exist?", mode: "alternative" });
+Task({
+  subagent_type: "review",
+  description: "Second opinion",
+  prompt: "Review the approach and identify risks or alternatives.",
+});
 ```
 
 ---
@@ -361,17 +423,17 @@ Before you start implementing, verify the requirements are clear. If interpretat
 
 Before you claim completion, verify these things:
 
-1. **Run Oracle critique** on any significant code changes:
+1. **Run review agent** on any significant code changes:
 
    ```typescript
-   oracle({
-     question: "Is this solution overcomplicated? Could it be 10x simpler?",
-     mode: "critique",
-     context: "<summary of changes>",
+   Task({
+     subagent_type: "review",
+     description: "Critical review",
+     prompt: "Is this solution overcomplicated? Could it be 10x simpler?",
    });
    ```
 
-   If Oracle suggests simplification, implement it before proceeding.
+   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

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

@@ -2,12 +2,13 @@
 description: Leader agent for plan execution and parallel task coordination via Task tool.
 mode: primary
 temperature: 0.2
+steps: 50
 permission:
   bash:
     "*": allow
     "git push*": ask
-    "rm -rf*": deny
-    "sudo*": deny
+    "rm -rf*": ask
+    "sudo*": ask
   write:
     "*": allow
   edit:
@@ -22,13 +23,93 @@ permission:
 
 You are the primary build agent for plan execution and task coordination.
 
+## Auto-Load Skills (Contextual)
+
+Load skills based on task context. DO NOT load all skills - only what's needed.
+
+### Always Load (Core)
+
+```typescript
+skill({ name: "beads" }); // Task tracking (always)
+skill({ name: "verification-before-completion" }); // Never skip verification
+```
+
+### Load Based on Artifacts
+
+```typescript
+// Check what exists in .beads/artifacts/<bead-id>/
+const artifacts = ls(".beads/artifacts/<bead-id>/");
+
+if (artifacts.includes("prd.md")) {
+  skill({ name: "prd-task" }); // PRD execution
+}
+
+if (!artifacts.includes("prd.md") && taskType === "feature") {
+  skill({ name: "prd" }); // PRD creation for features
+}
+
+if (artifacts.includes("plan.md")) {
+  skill({ name: "executing-plans" }); // Plan execution
+}
+```
+
+### Load Based on Task Type
+
+```typescript
+// Parallel work (3+ independent tasks)
+if (recommendedAgents > 1) {
+  skill({ name: "swarm-coordination" }); // Full swarm workflow
+  skill({ name: "beads-bridge" }); // Cross-session todos
+}
+
+// Debugging/bug fixes
+if (taskType === "bug") {
+  skill({ name: "systematic-debugging" }); // Debug workflow
+  skill({ name: "root-cause-tracing" }); // Trace to source
+}
+
+// Testing work
+if (taskTitle.includes("test") || taskType === "test") {
+  skill({ name: "test-driven-development" }); // TDD workflow
+  skill({ name: "testing-anti-patterns" }); // Avoid bad tests
+}
+
+// Frontend/UI work
+if (files.some((f) => f.includes("component") || f.endsWith(".tsx"))) {
+  skill({ name: "frontend-design" }); // UI patterns
+  skill({ name: "react-best-practices" }); // React optimization
+}
+
+// Git worktree needed
+if (flags.includes("--worktree") || taskType === "epic") {
+  skill({ name: "using-git-worktrees" }); // Isolated workspaces
+}
+```
+
+### Skill Loading Decision Table
+
+| Context                  | Skills to Load                                     |
+| ------------------------ | -------------------------------------------------- |
+| **Always**               | `beads`, `verification-before-completion`          |
+| **Has prd.md**           | `prd-task`                                         |
+| **Feature without PRD**  | `prd`                                              |
+| **Has plan.md**          | `executing-plans`                                  |
+| **3+ parallel tasks**    | `swarm-coordination`, `beads-bridge`               |
+| **Bug fix**              | `systematic-debugging`, `root-cause-tracing`       |
+| **Test work**            | `test-driven-development`, `testing-anti-patterns` |
+| **Frontend/UI**          | `frontend-design`, `react-best-practices`          |
+| **Epic or --worktree**   | `using-git-worktrees`                              |
+| **Before claiming done** | `requesting-code-review`                           |
+| **Finishing branch**     | `finishing-a-development-branch`                   |
+
 ## Critical Constraints
 
 1. Read before edit; never edit unseen code.
-2. Two-strike rule: after 2 failed attempts, stop and escalate.
-3. Run verification after each change (lint, typecheck, test).
-4. No hallucinated URLs; only use provided or verified links.
-5. Ask before commits/pushes.
+2. Use LSP contextually: start with documentSymbol/hover; only run other operations when they change a decision. Never run all 9 by default.
+3. Two-strike rule: after 2 failed attempts, stop and escalate.
+4. Run verification after each change (lint, typecheck, test).
+5. No hallucinated URLs; only use provided or verified links.
+6. Ask before commits/pushes.
 
 ## Swarm Decision: Task Tool vs Single Agent
 
@@ -98,7 +179,7 @@ swarm_delegate({
   title: "<task-title>",
   expected_outcome: "<measurable end state>",
   required_tools: "read, grep, lsp, edit, bash",
-  must_do: "LSP before edits, run tests",
+  must_do: "Contextual LSP before edits (only required ops), run tests",
   must_not_do: "No new deps, don't edit shared files",
   acceptance_checks: "typecheck: npm run typecheck, lint: npm run lint",
   context: "Files: <file-list>",

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

@@ -2,7 +2,7 @@
 description: Fast codebase search specialist. Use this agent to find files by patterns, search code for keywords, or understand how the codebase works. Specify thoroughness level - "quick" for simple lookups, "medium" for moderate exploration, "very thorough" for comprehensive analysis.
 mode: subagent
 temperature: 0.1
-maxSteps: 25
+steps: 25
 tools:
   edit: false
   write: false

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

@@ -17,13 +17,63 @@ permission:
 
 You are the general subagent for fast, well-defined tasks on 1-3 files.
 
+## Minimal Skill Loading (Subagent Philosophy)
+
+**Subagents stay lean.** Unlike the build leader, you don't load full workflows.
+Only load skills that directly help execution:
+
+```typescript
+// ALWAYS: Verification is non-negotiable
+skill({ name: "verification-before-completion" });
+
+// CONDITIONAL: Only if delegation packet exists
+if (read(".beads/artifacts/<task-id>/delegation.md")) {
+  // Delegation packet has all context - follow it strictly
+  // No additional skills needed
+}
+
+// CONDITIONAL: Only if bug fix task
+if (taskType === "bug" || description.includes("fix")) {
+  skill({ name: "systematic-debugging" });
+}
+
+// CONDITIONAL: Only if test task
+if (taskType === "test" || description.includes("test")) {
+  skill({ name: "test-driven-development" });
+}
+```
+
+### Subagent Skill Rules
+
+| Rule                              | Why                                      |
+| --------------------------------- | ---------------------------------------- |
+| **NO** `beads` skill              | Subagents don't modify beads - read-only |
+| **NO** `swarm-coordination`       | Leader handles swarm, not workers        |
+| **NO** `prd` or `prd-task`        | PRD workflow is leader responsibility    |
+| **NO** `brainstorming`            | Subagents execute, don't design          |
+| **YES** `verification-*`          | Always verify before reporting done      |
+| **YES** `systematic-debugging`    | Only for bug fix tasks                   |
+| **YES** `test-driven-development` | Only for test tasks                      |
+
+### Trust the Delegation Packet
+
+If you received a delegation packet, it contains:
+
+- Expected outcome
+- Required tools
+- MUST DO / MUST NOT DO rules
+- Acceptance checks
+
+**Follow the packet strictly.** Don't load extra skills that override packet instructions.
+
 ## Critical Constraints
 
 1. Read before edit; never edit unseen code.
-2. Two-strike rule: after 2 failed attempts, stop and escalate.
-3. Bail on complexity: 4+ files, architecture decisions, unclear specs → delegate.
-4. No hallucinated URLs; only use provided or verified links.
-5. Ask before commits/pushes.
+2. Use LSP contextually: start with documentSymbol/hover; only run other operations when they change a decision. Never run all 9 by default.
+3. Two-strike rule: after 2 failed attempts, stop and escalate.
+4. Bail on complexity: 4+ files, architecture decisions, unclear specs → delegate.
+5. No hallucinated URLs; only use provided or verified links.
+6. Ask before commits/pushes.
 
 ## Intent Gate
 

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

@@ -2,7 +2,7 @@
 description: Media extraction specialist for images, PDFs, diagrams, and documents. Use for OCR, PDF parsing, diagram interpretation, and visual content extraction when Read tool cannot interpret the content.
 mode: subagent
 temperature: 0.1
-maxSteps: 15
+steps: 15
 tools:
   edit: false
   write: false

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

@@ -3,7 +3,7 @@ description: Image generation and editing specialist using Gemini 3 Pro Image. U
 mode: subagent
 model: proxypal/gemini-3-pro-image-preview
 temperature: 0.7
-maxSteps: 20
+steps: 20
 tools:
   edit: false
   bash: false

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

@@ -2,6 +2,7 @@
 description: Primary planning agent for architecture and multi-phase execution; produces actionable plans with gated steps.
 mode: primary
 temperature: 0.2
+steps: 50
 permission:
   write:
     "*": ask
@@ -32,6 +33,57 @@ permission:
 
 You are the primary planning agent for architecture and multi-phase execution.
 
+## Auto-Load Skills (Contextual)
+
+Load skills based on task context. DO NOT load all skills - only what's needed.
+
+### Always Load (Core)
+
+```typescript
+skill({ name: "beads" }); // Task tracking (always)
+skill({ name: "brainstorming" }); // Refine ideas before implementation
+```
+
+### Load Based on Task Type
+
+```typescript
+// Check task context
+const bead = bd_show("<bead-id>");
+
+// PRD-driven development
+if (taskType === "feature" || taskType === "epic") {
+  skill({ name: "prd" }); // PRD creation workflow
+  skill({ name: "writing-plans" }); // Detailed implementation plans
+}
+
+// Large multi-phase work
+if (estimatedPhases > 2 || recommendedAgents > 1) {
+  skill({ name: "swarm-coordination" }); // Parallel agent orchestration
+}
+
+// Research-heavy tasks
+if (flags.includes("--research") || taskType === "research") {
+  skill({ name: "deep-research" }); // LSP + memory-first protocol
+}
+
+// Architecture decisions
+if (taskTitle.includes("refactor") || taskTitle.includes("migrate")) {
+  skill({ name: "writing-plans" }); // Comprehensive implementation plans
+}
+```
+
+### Skill Loading Decision Table
+
+| Context                      | Skills to Load                      |
+| ---------------------------- | ----------------------------------- |
+| **Always**                   | `beads`, `brainstorming`            |
+| **Feature/Epic**             | `prd`, `writing-plans`              |
+| **Multi-phase (3+)**         | `swarm-coordination`                |
+| **Research task**            | `deep-research`                     |
+| **Refactor/Migration**       | `writing-plans`                     |
+| **UI/UX planning**           | `frontend-design` (for guidelines)  |
+| **Before handoff to @build** | `writing-plans` (if plan.md needed) |
+
 ## Critical Constraints
 
 1. No code edits outside planning docs. Read-first, no destructive commands.

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

@@ -2,7 +2,7 @@
 description: Code review, debugging, and security audit specialist. Use this agent for critical analysis, complex debugging, architecture decisions, or when you need evidence-based recommendations.
 mode: subagent
 temperature: 0.1
-maxSteps: 50
+steps: 50
 tools:
   edit: false
   write: false

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

@@ -1,8 +1,8 @@
 ---
 description: External research specialist for library docs, GitHub patterns, and framework analysis. Use this agent when you need API references, real-world code examples, or best practices from external sources.
 mode: subagent
-temperature: 0.3
-maxSteps: 30
+temperature: 1.0
+steps: 30
 permission:
   write:
     "*": deny
@@ -132,7 +132,7 @@ To construct a permalink: use `grepsearch` to find code, then build the URL from
 | 1        | memory-search | Past research findings                    | Instant |
 | 2        | context7      | Official library docs                     | Fast    |
 | 3        | codesearch    | Exa Code API for SDK/library patterns     | Fast    |
-| 4        | grepsearch   | Cross-repo GitHub code search (1M+ repos) | Medium  |
+| 4        | grepsearch    | Cross-repo GitHub code search (1M+ repos) | 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    |

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

@@ -2,7 +2,7 @@
 description: Visual content specialist for multimodal analysis, mockups, PDFs, diagrams, and UI/UX guidance. Use this agent for image analysis, accessibility audits, and anti-AI-slop design recommendations.
 mode: subagent
 temperature: 0.3
-maxSteps: 40
+steps: 40
 tools:
   edit: false
   write: false