opencodekit 0.15.3 → 0.15.4

package/dist/index.js

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

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

@@ -10,47 +10,55 @@ Complexity is the enemy. Every rule here fights complexity.
 
 Everything else is guidelines, not laws.
 
+---
+
 ## Delegation
 
-**Rule**: Before any complex tool call, ask: "Can a specialist agent do this better?"
+**DO NOT execute complex tasks directly. Delegate if the work spans more than three files, requires digging into external documentation or APIs, needs a design review or debugging help for tricky failures, or ventures into territory you don't know well.**
+
+Before any complex tool call, pause and ask yourself: "Can a specialist agent do this better?" If the answer is yes, delegate. If no, proceed directly.
+
+When delegation makes sense, match the task to the right specialist. For small, well-defined tasks that touch only a few files, @general handles the job efficiently. When you need to search the codebase for patterns or understand how something works across multiple files, @explore is your tool. For external documentation, library APIs, or research into how frameworks work, @scout pulls the information you need. When you're reviewing code, auditing for bugs, or debugging complex failures, @review provides thorough analysis. Planning phases, architectural decisions, or design work benefit from @plan or @vision. And when you encounter images, PDFs, or diagrams that need content extracted through OCR or parsing, @looker handles the extraction cheaply and fast.
 
-- **Fast Tasks** → @general (small, well-defined, ≤3 files)
-- **Search/Docs** → @explore / @scout
-- **Review/Debug** → @review
-- **Plan/Design** → @plan / @vision
-- **Media Extraction** → @looker (images, PDFs, diagrams needing OCR/parsing)
+### When to use @looker versus @vision
 
-If yes → Delegate. If no → Execute directly.
+When you encounter media files, stop and ask yourself a simple question: "Do I need to extract content from this, or do I need judgment on how it looks?" The answer determines which specialist to call.
 
-### @vision vs @looker
+@looker handles pure extraction. It pulls content out of images, parses PDF documents, describes what diagram components contain, extracts table data, or transcribes handwritten notes. It's cheap using Gemini Flash, fast, and strictly read-only. Use it when you need to know what is inside the file. @vision handles design judgment. It evaluates how something looks, provides accessibility audits, reviews UI and UX choices, checks design system consistency, gives feedback on mockups, or detects anti-slop patterns. It's expensive using Gemini Pro, thorough, and opinionated. Use it when you need to know if something is good.
 
-When you encounter media files (images, PDFs, diagrams), ask: **"Do I need extraction or judgment?"**
+### Atomic Version
 
-**@looker** handles pure extraction—getting content OUT of media. Use it when you need to read what's inside: OCR text from images, parse PDF documents, describe diagram components, extract table data, or transcribe handwritten notes. Looker is cheap (Gemini Flash), fast, and read-only. It tells you WHAT is there.
+```
+DO NOT execute complex tasks directly.
+ASK: "Can a specialist agent do this better?"
+If yes → delegate. If no → execute directly.
+```
 
-**@vision** handles design judgment—evaluating HOW something looks. Use it when you need critique: accessibility audits, UI/UX reviews, design system consistency checks, mockup feedback, or anti-slop detection. Vision is expensive (Gemini Pro), thorough, and opinionated. It tells you if something is GOOD.
+---
 
 ## Question Tool
 
-**Rule**: Use `question` tool to gather user input when interpretation matters.
+**DO NOT proceed with implementation when interpretation matters.** When a request could reasonably be interpreted in multiple ways that lead to different implementations, ask for clarification before building something that doesn't match what the user wanted.
 
-### When to Use
+### When to use the question tool
 
-Use the question tool when ambiguous requests could lead to significantly different implementations—if "add auth" could mean OAuth, JWT, or session-based, ask before building the wrong thing. Use it when multiple valid approaches exist and user preference matters, like choosing between frameworks or patterns. Always ask before destructive operations like deleting branches, resetting hard, or force pushing. When user preferences affect the outcome—naming conventions, file structure, coding style—let them choose. For gathering multiple selections at once, use `multiple: true` to let users pick several options.
+Reach for the question tool when the request is ambiguous and could lead to significantly different outcomes. For example, if the user asks to "add auth" and that could mean OAuth, JWT, session-based authentication, or something else entirely, ask before building the wrong thing. Use it when multiple valid approaches exist and user preference matters deeply, such as choosing between frameworks, architectural patterns, or coding styles. Always ask before destructive operations like deleting branches, resetting hard, or force pushing to remote. When user preferences will affect naming conventions, file structure, or coding style, let them choose rather than assuming.
 
-### When NOT to Use
+### When NOT to use the question tool
 
-Skip the question tool for trivial decisions where any reasonable choice works. If you already have enough context from the conversation, just proceed. When you can make a sensible default, mention what you're doing and continue—don't stop for permission on every small choice. Subagents like explore, scout, and review should never ask questions; they report findings back to the leader agent who decides what to do.
+Skip the question tool for trivial decisions where any reasonable choice works equally well. If you already have enough context from the conversation to make a sensible call, make it and mention what you're doing rather than stopping for permission on every small choice. Subagents like explore, scout, and review should never ask questions during their work; they report findings back to the leader agent who then decides what action to take.
 
 ### Question Design
 
+When you do need to ask, structure the questions thoughtfully. Keep headers under twelve characters so they display cleanly. Limit the options to three or five at most, because more than that overwhelms users and makes decision-making harder. Write short, clear descriptions that explain the trade-off of each option rather than just describing what it is. Analyze each option against the user's context, project constraints, and industry best practices before recommending anything. Only add "(Recommended)" to the option that genuinely fits best based on your analysis. Place the recommended option first so users can quickly identify the optimal choice without reading everything. Don't try to cover every edge case in your options; the "Other" option exists for situations you didn't anticipate.
+
 ```typescript
 question({
   questions: [
     {
       header: "Auth Type", // Max 12 chars
       question: "Which authentication approach?",
-      multiple: false, // true for multi-select
+      multiple: false,
       options: [
         { label: "JWT (Recommended)", description: "Stateless, scalable" },
         { label: "Session-based", description: "Traditional, server-side" },
@@ -61,103 +69,227 @@ question({
 });
 ```
 
-**Design Rules:**
+### Atomic Version
+
+```
+DO NOT implement when interpretation is ambiguous.
+ASK the user to clarify.
+Limit options to 3-5. Recommend best option first.
+```
+
+---
+
+## Anti-Hallucination
 
-1. **Analyze before recommending**: Evaluate each option against the user's context, project constraints, and industry best practices. Only add "(Recommended)" to the option that genuinely fits best—don't default to the first option blindly.
+**DO NOT proceed without verification checkpoints.** Before you start any significant work, before you use any external link, and before you claim completion, verify what you need to verify.
+
+### The Three Blockers
+
+These are hard gates that must be passed before proceeding. First, DO NOT start major work without running `bd show <id>` to understand the task context. Understanding the task context enables everything that follows, so skipping this blocks your ability to work effectively. Second, DO NOT generate ANY URL yourself. If you need an external link, either the user provides it or you use @scout to fetch verified information. Guessing URLs leads to hallucinated documentation and broken references. Third, DO NOT claim completion without running `bd close <id>` to mark the task as done. Claiming work is finished without closing the task breaks the tracking system and loses context.
+
+### Verification chain
+
+Think of these checkpoints as a chain where each step enables the next. Running `bd show <id>` gives you task context, which enables you to proceed with confidence. Verifying links through fetch before using them enables you to trust your sources. Running `bd close <id>` marks you as complete and finalizes the state.
+
+### No guessing protocol
+
+Never generate URLs on your own. If the user provides a URL, fetch it to verify it exists and contains what they expect. If you need external information you don't have, use @scout or web search to find it rather than inventing something. If you cannot verify a link or piece of information, say explicitly "I cannot verify this" rather than guessing and potentially providing incorrect information to the user.
+
+### Atomic Version
+
+```
+DO NOT skip task context check.
+DO NOT guess URLs. Fetch first.
+DO NOT claim done without closing task.
+```
 
-2. **Put recommended first**: Place the analyzed best-practice option first with "(Recommended)" in the label so users can quickly identify the optimal choice.
+---
 
-3. **Keep it focused**: Limit to 3-5 options—more overwhelms users. Write short, clear descriptions that explain the tradeoff of each option.
+## Coding Philosophy
 
-4. **Don't over-specify**: Users can always select "Other" to provide custom input, so you don't need to cover every edge case.
+**DO NOT write code that violates these principles.** These constraints protect you and the user from common failure modes.
 
-## Anti-Hallucination (The Truth)
+### The Four Constraints
 
-- **Check First**: Run `bd show <id>` before starting major work.
-- **No Guessing**: Never generate URLs. Use only verified links.
-- **Land the Plane**: Close tasks when done (`bd close <id>`).
+First, DO NOT lie about understanding. If you don't understand what the user is asking for or how the code works, ask for clarification. Saying "I don't know" is far better than providing code or explanations that are wrong. The user would rather answer a question than deal with bugs caused by guessed assumptions.
 
-## Coding Philosophy (Grug Style)
+Second, DO NOT abstract prematurely. Wait until you've seen the same pattern at least three times before extracting it into an abstraction. Resist the urge to invent abstractions before the pattern exists. You'll save yourself from creating abstractions that don't quite fit and that become technical debt.
 
-1.  **Say No**: If you don't understand, ask. "I don't know" is better than a lie.
-2.  **No Premature Abstraction**: Don't abstract until you see the pattern 3 times.
-3.  **Break It Down**: Complex `if` conditions are bugs waiting to happen. Use named variables.
-    - _Bad_: `if (x && !y && (z || w))`
-    - _Good_: `const isValid = x && !y; const hasPermission = z || w; if (isValid && hasPermission)`
-4.  **Logs**: Log before and after state changes. Silent failures are the devil.
+Third, DO NOT write complex conditionals. If you find yourself writing conditions like `if (x && !y && (z || w))`, stop and refactor. Extract each condition into a named variable so the intent is clear. The bad example becomes good when you write: `const isValid = x && !y; const hasPermission = z || w; if (isValid && hasPermission)`. Named conditions are self-documenting and make bugs easier to find.
+
+Fourth, DO NOT skip logging. Log before state changes so you can trace the flow, and log after state changes so you can confirm what happened. Silent failures are the devil because they leave you with no information when things go wrong. The absence of logs makes debugging nearly impossible.
+
+### Atomic Version
+
+```
+DO NOT lie about understanding.
+DO NOT abstract until pattern appears 3x.
+DO NOT write complex conditionals without names.
+DO NOT skip logs around state changes.
+```
+
+---
 
 ## Tool Priority
 
-**Rule**: Always `read` before `edit`. Always `LSP` before `edit`.
+**DO NOT edit before completing the verification chain.** Editing without understanding the code leads to broken changes. Follow the chain from search to understanding, then edit.
+
+### The Chain
+
+The verification chain is: grep to find relevant text, read to see the file content, run all nine LSP operations to understand the code structure, search memory for relevant context, build understanding of what you're changing, and only then edit. Skipping any step in this chain is a violation.
+
+### LSP Operations (all nine are mandatory)
+
+Before you edit anything, you must run all nine LSP operations to understand what you're changing. Run `documentSymbol` to see the file structure and identify all functions, classes, and variables. Run `goToDefinition` to jump to where the symbol you're modifying is defined, so you understand its original implementation. Run `findReferences` to discover every usage of that symbol across the codebase, so you know what else might be affected. Run `hover` to get type information and documentation for the symbol. Run `goToImplementation` to find implementations of interfaces or abstract classes. Run `workspaceSymbol` to search for symbols across the entire workspace. Run `prepareCallHierarchy` to get the call hierarchy for the function you're working on. Run `incomingCalls` to discover what functions call this function. Run `outgoingCalls` to see what this function calls. Each operation reveals different information about your target, and skipping any of them means you're working with incomplete understanding.
 
-1.  **LSP (Best)**: Use ALL 9 operations. **MANDATORY before ANY edit.**
-    - `documentSymbol` - File structure (functions, classes, variables)
-    - `goToDefinition` - Jump to where symbol is defined
-    - `findReferences` - Find all usages of a symbol
-    - `hover` - Get type info and documentation
-    - `goToImplementation` - Find implementations of interface/abstract
-    - `workspaceSymbol` - Search symbols across entire workspace
-    - `prepareCallHierarchy` - Get call hierarchy item at position
-    - `incomingCalls` - Find what calls this function
-    - `outgoingCalls` - Find what this function calls
-2.  **Memory**: `memory-search` (Check past learnings)
-3.  **Structure**: `lsp` (Find symbols, definitions, references)
-4.  **Search**: `grep` (Find text/TODOs)
-5.  **Files**: `glob` (Find files)
+### Checkpoint protocol
 
-**LSP-First Workflow (HARD RULE):**
+After running LSP operations, verify you can answer these questions before editing. What symbol am I modifying and where is it defined? What else uses this symbol and could be affected by my changes? What functions call this function and what functions does this function call? What is the overall file structure and how does my target fit into it? Are there implementations of interfaces or abstract classes that I need to consider? If you cannot answer any of these questions, run more LSP operations until you can.
+
+### Memory checkpoint
+
+Before editing, also check memory for relevant context. Use `memory-search` to find past decisions, patterns, and gotchas related to your work. Use `memory-read` to review active project files that might affect what you're changing. Apply past learnings from memory before proceeding rather than repeating mistakes or ignoring existing patterns.
+
+### Tool priority order
+
+LSP operations are mandatory before any edit. Memory check comes next. Then structure understanding through symbols, definitions, and references. Search with grep for text patterns and TODOs. Finally, glob for file patterns when you need to find files by name.
+
+### Atomic Version
 
 ```
-grep/read → LSP → understand → THEN edit
+DO NOT edit before LSP (all 9 operations).
+DO NOT edit before memory search.
+DO NOT edit before you can explain what you're changing.
+
+Chain: grep → read → LSP(9) → memory → understand → edit
 ```
 
-Violations: `read → edit` or `grep → edit` without LSP = WRONG.
+---
+
+## Active Memory
+
+**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.
+
+### 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.
 
-## Active Memory (The Brain)
+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.
 
-**Rule**: Use memory proactively, not just when asked.
+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.
 
-- **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.
+### 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.
+
+### Atomic Version
+
+```
+DO NOT start without memory-search.
+DO NOT skip observation on decisions.
+DO NOT ignore LSP Nudges.
+```
+
+---
 
 ## Beads (Task Tracking)
 
-**Leader Only**: `build` and `plan` agents own the DB. Subagents read-only.
+**DO NOT work without task context. DO NOT claim completion without closing.** Task tracking keeps you honest about what you're working on and what you've finished.
+
+### Leader protocol for build and plan agents
+
+Only build and plan agents own the beads database. Subagents work read-only and report findings back to their leader. The leader follows this chain: run `bd ready` to find unblocked work, run `bd update <id> --status in_progress` to claim the task, do the editing work, run `bd close <id> --reason "..."` to mark it complete, run `bd sync` to push changes to git, and then restart the session. Skipping any step breaks the tracking flow.
+
+### Subagent protocol
+
+Subagents must not modify beads state. When a subagent needs task information, read it with `bd show <id>`. Report findings back to the leader agent rather than making decisions yourself. Let the leader agent update task status. This keeps the tracking system clean and ensures only one agent controls each task's state.
+
+### Checkpoints before claiming done
 
-- **Start**: `bd ready` → `bd update <id> --status in_progress`
-- **Work**: `bd update <id> --status in_progress` → Edit
-- **Finish**: `bd close <id> --reason "..."` → `bd sync` → **RESTART SESSION**
+Before you claim work is complete, verify these things have happened. You ran `bd update <id> --status in_progress` when you started. You completed the actual editing work. You ran `bd close <id> --reason "..."` with a meaningful reason explaining what you did. You ran `bd sync` to push the changes. If any of these are missing, the work is not done.
+
+### Atomic Version
+
+```
+DO NOT work without claiming task first.
+DO NOT claim done without closing task.
+DO NOT end session without syncing.
+```
+
+---
 
 ## Parallel Execution
 
-**Rule**: Fire research subagents in parallel, continue working, collect when needed.
+**DO NOT wait for sequential research when parallel is possible.** When you have multiple independent questions or unknowns, launch subagents in parallel and continue your own work while they run.
 
-For complex tasks with multiple unknowns, don't wait for sequential research. Launch parallel tasks using the built-in `task` tool:
+### When to use parallel execution
+
+Use parallel execution when you have multiple independent research questions that don't depend on each other's answers. Use it when a complex task touches unfamiliar code and you need both codebase patterns and external documentation to understand what you're dealing with. Use it when you have three or more unknowns that don't depend on each other. In all these cases, don't wait for one research task to finish before starting the next.
+
+### The pattern
+
+Launch parallel subagents using the task tool and continue working immediately. Results come back in the same message when both complete.
 
 ```typescript
-// Parallel Task tool calls (recommended)
-task({ subagent_type: "explore", prompt: "Find auth patterns..." }); // → runs in parallel
-task({ subagent_type: "scout", prompt: "Find JWT docs..." }); // → runs in parallel
+task({ subagent_type: "explore", prompt: "Find auth patterns..." }); // → parallel
+task({ subagent_type: "scout", prompt: "Find JWT docs..." }); // → parallel
 
 // Continue with implementation work immediately...
-// Results come back in same message (no manual collection needed)
+// Results come back in the same message
 ```
 
-**When to use parallel execution:**
+### When NOT to use parallel execution
 
-- Multiple independent research questions
-- Complex tasks touching unfamiliar code
-- Need both codebase patterns AND external docs
+Don't use parallel execution for simple, well-understood changes where one path is clear. Don't use it when tasks have sequential dependencies, where task B needs task A's output before it can start. Don't use it for quick fixes with a known approach where research isn't needed. Don't use it when you have only a single research question.
 
-**When NOT to use:**
+### Atomic Version
 
-- Simple, well-understood changes
-- Sequential dependencies (B needs A's output)
-- Quick fixes with known approach
+```
+DO NOT wait for sequential research.
+LAUNCH parallel subagents for independent questions.
+CONTINUE working while they run.
+```
+
+---
 
 ## Core Constraints
 
-- No sudo.
-- POSIX compatible (macOS/Linux).
-- Use absolute paths.
+These are hard limits that must never be violated. DO NOT run commands with sudo. DO NOT write code that only works on non-POSIX systems like Windows; keep everything compatible with macOS and Linux. DO NOT use relative paths; always use absolute paths for file operations.
+
+---
+
+## Complete Atomic Reference
+
+Use these summaries as quick reminders before starting different types of work.
+
+### Before any edit
+
+Before you edit anything, complete these steps: run all nine LSP operations, search memory for context, load task context, and build understanding of what you're changing. Only then edit.
+
+### Before any complex task
+
+Before you execute a complex task directly, check if you should delegate instead. Consider whether the task touches more than three files, requires external research, needs design review, or involves unfamiliar territory. If any of these are true, delegate to a specialist agent.
+
+### Before any implementation
+
+Before you start implementing, verify the requirements are clear. If interpretation is ambiguous or requirements are unclear, ask questions first rather than building the wrong thing.
+
+### Before claiming done
+
+Before you claim completion, verify these things: you ran `bd close <id>`, you ran `bd sync`, there are no pending LSP nudges, and you saved observations for any important decisions or patterns.
+
+---
+
+## Pattern: Constraint Chains
+
+Each rule enables the next one in a chain. Memory search enables LSP operations, which enable understanding, which enables editing. Understanding enables verification, which enables claiming done. Removing any constraint from the chain reduces effectiveness. All rules are synergistic and work together.
+
+---
+
+## Violation Protocol
+
+When you notice you've violated these rules, follow a simple protocol. Detect the deviation from the chain. Correct by returning to the last valid checkpoint. Log the violation using the `observation` tool so you remember what went wrong. Adjust your behavior for the next iteration to prevent the same violation.
+
+---
+
+_Rules derived from context-field research: inhibition beats instruction. "Do NOT X" creates blockers that must be resolved. "Do X" creates preferences that are ignored._

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

@@ -6,9 +6,13 @@ permission:
   write:
     "*": deny
     ".beads/artifacts/*/*.md": allow
+    ".opencode/memory/plans/*.md": allow
+    ".opencode/memory/project/*.md": allow
   edit:
     "*": deny
     ".beads/artifacts/*/*.md": allow
+    ".opencode/memory/plans/*.md": allow
+    ".opencode/memory/project/*.md": allow
   bash:
     "*": allow
     "rm*": deny

package/dist/template/.opencode/package.json

@@ -11,7 +11,7 @@
     "type-check": "tsc --noEmit"
   },
   "dependencies": {
-    "@opencode-ai/plugin": "1.1.19"
+    "@opencode-ai/plugin": "1.1.23"
   },
   "devDependencies": {
     "@types/node": "^25.0.3",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencodekit",
-	"version": "0.15.3",
+	"version": "0.15.4",
 	"description": "CLI tool for bootstrapping and managing OpenCodeKit projects",
 	"keywords": ["agents", "cli", "mcp", "opencode", "opencodekit", "template"],
 	"license": "MIT",