opencodekit 0.12.7 → 0.13.1

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

@@ -1,152 +1,59 @@
 # OpenCode Global Rules
 
-## Priority Hierarchy
+Complexity is the enemy. Every rule here fights complexity.
 
-1. Security constraints (always first)
-2. Anti-hallucination rule (overrides all except security)
-3. Delegation rules (check before tool calls)
-4. Skills check (native `skill` tool)
-5. User explicit requests
-6. Base prompt behaviors
-7. Global rules (this file)
-8. Project conventions (nested AGENTS.md files)
+## Priority (3 Levels Only)
 
-## Delegation
-
-**Check before any tool call. Delegate if task involves search or research.**
-
-- **@explore** - Code search: find, where is, search, how does X work, locate
-- **@scout** - External research: research, compare, docs for, API for, best practices
-- **@review** - Code review/debug: review, audit, debug, why broken, root cause
-- **@planner** - Architecture: design, architect, plan, structure, phases
-- **@vision** - UI/UX design: mockup, UI review, accessibility, aesthetics, visual
-
-**Execute directly**: Single-file edits, explicit commands, answering from loaded context.
-
-### Research Depth Levels
-
-- **quick** (~5-10 calls) - Simple lookup, single answer, API syntax
-- **medium** (~20-50 calls) - Moderate exploration, verify across files
-- **thorough** (~100+ calls) - Comprehensive analysis, dependency mapping
-
-## Anti-Hallucination
-
-- **Major features**: Check task exists (`bd show <id>`)
-- **Bug fixes/edits**: Proceed directly; document clearly
-- **Before commit**: Close task with reason (`bd close <id> --reason "..."`)
-- **Find work**: Use `bd ready` for unblocked tasks
-- **URLs**: Never generate or guess URLs. Only use URLs from user input, tool results, or verified documentation.
+1. **Security**: Never harvest credentials. Defensive only.
+2. **Anti-hallucination**: Check before big work. Never guess URLs.
+3. **User request**: Do what user asks, simplest way possible.
 
-## Interaction Modes
+Everything else is guidelines, not laws.
 
-| Mode                    | Triggers                                                         | Response                                             |
-| ----------------------- | ---------------------------------------------------------------- | ---------------------------------------------------- |
-| **Sounding Board**      | "Let's chat...", "Help me think...", "What are the tradeoffs..." | Ask questions, explore alternatives, don't implement |
-| **Execution** (default) | Direct requests                                                  | Take action, iterate on feedback                     |
-| **Uncertainty**         | "I'm not sure...", "What am I missing?"                          | Question assumptions, surface edge cases             |
-
-**Key insight**: First output is ~70-80% right. Refinement is expected, not failure.
+## Delegation
 
-## Universal Standards
+**Rule**: Before any complex tool call, ask: "Can a specialist agent do this better?"
 
-### Communication
+- **Search/Docs** → @explore / @scout
+- **Review/Debug** → @review
+- **Plan/Design** → @planner / @vision
 
-- Under 4 lines for typical responses
-- Brief preamble before big tool calls
-- Use `file:line_number` format for code references
-- No emojis unless explicitly requested
+If yes → Delegate. If no → Execute directly.
 
-### Execution
+## Anti-Hallucination (The Truth)
 
-- Batch independent tool calls (parallel)
-- Verify with tools; don't assume
-- Obey project AGENTS.md files (nested takes precedence)
-- TodoWrite BEFORE work; mark completed immediately
+- **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>`).
 
-### Security
+## Coding Philosophy (Grug Style)
 
-- Defensive security only
-- Refuse credential harvesting
-- Allow security analysis, detection rules, vulnerability explanations
+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.
 
 ## Tool Priority
 
-Load `skill tool-priority` for full LSP, ast-grep, and grep reference.
-
-**Quick reference**: LSP tools → ast-grep → grep → glob → read/edit/write
-
-| Need                                       | Tool              |
-| ------------------------------------------ | ----------------- |
-| Code structure (functions, hooks, imports) | `ast-grep`        |
-| Text search (logs, config, TODOs)          | `grep`            |
-| Type info, definitions, references         | `lsp_lsp_*` tools |
-| File discovery                             | `glob`            |
-
 **Rule**: Always `read` before `edit`.
 
-## Context Engineering
-
-Load `skill context-engineering` for context management principles.
-
-**Quick reference**:
-
-- Prefer `lsp_lsp_document_symbols` over reading entire files
-- Navigate AGENTS.md hierarchy (progressive disclosure)
-- Prune context aggressively; completed work doesn't need to stay loaded
-
-## Research Tools
-
-| Tool           | Use When                                 |
-| -------------- | ---------------------------------------- |
-| **context7**   | Library docs (try first)                 |
-| **websearch**  | Docs not in Context7, recent releases    |
-| **codesearch** | Real implementation patterns from GitHub |
-| **webfetch**   | Specific URL user provided               |
-
-## Error Handling
-
-- **Transient** (network, timeout): Retry 2x with backoff
-- **Rate limit**: Stop, report to user
-- **Logic error**: Change strategy, don't repeat
-- **Blocked by hook/CI**: Analyze error, adjust approach, retry once
-
-## Memory System
-
-Load `skill memory-system` for memory tools and update patterns.
-
-**Quick reference**: `memory-read`, `memory-update`, `memory-search`, `observation`
-
-## Session Management
-
-Load `skill session-management` for session tools and context thresholds.
-
-**Philosophy**: Short sessions (<150k tokens) beat long bloated ones.
-
-**Quick reference**: `list_sessions`, `read_session`, `search_session`, `summarize_session`
-
-## Beads Usage
-
-**Leader agents only**: Only `build` and `rush` use beads tools.
-**Subagents** (explore, scout, planner, review, vision): Do NOT touch beads.
-
-Load `skill beads` for full workflow, tool reference, and patterns.
-
-**Quick reference**:
+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)
 
-```
-bd_init() → bd_claim() → bd_reserve(paths) → [work] → bd_done(id, msg) → RESTART
-```
+## Beads (Task Tracking)
 
-**Rules**:
+**Leader Only**: `build` and `rush` agents own the DB. Subagents read-only.
 
-- Always `bd_init()` first in any session using beads tools
-- Reserve before edit to prevent conflicts
-- One task per session - restart after `bd_done()`
+- **Start**: `bd_init()` → `bd_claim()`
+- **Work**: `bd_reserve()` (Lock files!) → Edit
+- **Finish**: `bd_done()` → **RESTART SESSION**
 
 ## Core Constraints
 
-- No sudo
-- POSIX compatible (macOS/Linux)
-- Manual verification for config changes
-- No auto-documentation without request
-- Use absolute paths
+- No sudo.
+- POSIX compatible (macOS/Linux).
+- Use absolute paths.

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

@@ -91,6 +91,7 @@ GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json
 - **@planner** - Architecture, multi-phase coordination
 - **@scout** - External research (library docs + GitHub patterns)
 - **@review** - Code review + debugging + security audit
+- **@vision** - UI/UX design: mockup, UI review, accessibility, aesthetics, visual
 
 **Built-in (OpenCode):**
 
@@ -329,8 +330,8 @@ fi
 
 ---
 
-**OpenCodeKit v0.9.2**  
+**OpenCodeKit v0.13.1**  
 **Architecture:** Two-Layer (Memory + Beads + Git)  
-**New in v0.9.2:** 6 new LSP tools, `ock init --beads` flag, improved tool guidance  
+**New in v0.13.1:** Beads worktree integration, Epic→Task→Subtask hierarchy, parallel subagent delegation  
 **Package:** `npx opencodekit` to scaffold new projects  
-**Last Updated:** January 2, 2026
+**Last Updated:** January 8, 2026

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

@@ -2,6 +2,7 @@
 description: UI/UX visual design with aesthetic direction and code output
 argument-hint: "<component|page|system|'review'> [topic] [--direction:<aesthetic>] [--quick|--deep]"
 agent: vision
+subtask: true
 ---
 
 # Design: $ARGUMENTS

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

@@ -105,10 +105,37 @@ observation({
 
 If it's a gotcha worth remembering, update `project/gotchas.md`.
 
-## Commit & Sync
+## Complete
+
+If all verifications pass:
 
 ```bash
 git add <files>
+git status
+git diff --cached --stat
+```
+
+**Present to user:**
+
+```
+Fix Complete: $ARGUMENTS
+━━━━━━━━━━━━━━━━━━━━━━━
+
+Root cause: [brief]
+Changes: [files]
+Tests: Pass ✓
+
+Would you like me to:
+1. Commit these changes
+2. Show full diff first
+3. Skip commit (I'll review manually)
+```
+
+**Wait for user confirmation before committing.**
+
+If user confirms:
+
+```bash
 git commit -m "fix: [description]
 
 Root cause: [brief]

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

@@ -1,14 +1,21 @@
 ---
-description: Implement a bead - load context, make changes, verify
-argument-hint: "<bead-id>"
+description: Implement a bead - load context, delegate research, make changes, verify
+argument-hint: "<bead-id> [--parallel]"
 agent: build
 ---
 
 # Implement: $ARGUMENTS
 
-You're implementing a tracked task. Stay focused, verify as you go, hand off if you hit limits.
+You're implementing a tracked task. Stay focused, delegate research, verify as you go, hand off if you hit limits.
 
-## First: Load Context
+## Parse Arguments
+
+| Argument     | Default  | Description                               |
+| ------------ | -------- | ----------------------------------------- |
+| `<bead-id>`  | required | The bead to implement                     |
+| `--parallel` | false    | Run aggressive parallel subagent research |
+
+## First: Load Skills & Context
 
 ```typescript
 skill({ name: "beads" });
@@ -16,27 +23,54 @@ skill({ name: "test-driven-development" });
 skill({ name: "verification-before-completion" });
 ```
 
-Get the task details and check for messages:
+Get the task details and check hierarchy:
 
+```bash
+bd show $ARGUMENTS
+bd dep tree $ARGUMENTS 2>/dev/null || echo "No dependencies"
+bd list --status=in_progress  # See what else is active
 ```
-!`bd show $ARGUMENTS`
-!`bd list --status=in_progress`  # See what else is active
+
+Check for messages from other agents:
+
+```typescript
+bd - inbox({ n: 5, unread: true });
 ```
 
-Check git state. If dirty, ask whether to stash, commit, or continue:
+## Check Hierarchy Position
+
+Identify where this task sits:
+
+| Type      | Action                                      |
+| --------- | ------------------------------------------- |
+| `epic`    | Don't implement directly - work on subtasks |
+| `task`    | May implement or delegate to subtasks       |
+| `subtask` | Implement directly - this is leaf work      |
 
+**If this is an epic with subtasks:**
+
+```bash
+bd ready --json | grep -q "$ARGUMENTS"
 ```
-!`git status --porcelain`
-!`git branch --show-current`
+
+→ Work on ready subtasks instead: `/implement <subtask-id>`
+
+## Git State Check
+
+```bash
+git status --porcelain
+git branch --show-current
 ```
 
+If dirty, ask whether to stash, commit, or continue.
+
 Create a branch if not already on one for this task:
 
 ```bash
-git checkout -b $ARGUMENTS
+git checkout -b $ARGUMENTS 2>/dev/null || echo "Already on branch"
 ```
 
-Mark the task in progress:
+Mark the task in progress (if not already):
 
 ```bash
 bd update $ARGUMENTS --status in_progress
@@ -46,59 +80,163 @@ bd update $ARGUMENTS --status in_progress
 
 Check what context exists:
 
-```
-!`ls .beads/artifacts/$ARGUMENTS/ 2>/dev/null || echo "No artifacts"`
+```bash
+ls .beads/artifacts/$ARGUMENTS/ 2>/dev/null || echo "No artifacts"
 ```
 
-If `plan.md` exists, follow it step by step. If only `spec.md` exists, implement directly from requirements. If nothing exists, work from the bead description.
+| Found         | Action                               |
+| ------------- | ------------------------------------ |
+| `plan.md`     | Follow it step by step               |
+| `spec.md`     | Implement directly from requirements |
+| `research.md` | Use findings to guide implementation |
+| Nothing       | Work from bead description           |
 
 Check for previous session work:
 
 ```typescript
-list_sessions({ project: "current", limit: 3 });
-read_session({ session_reference: "last", project: "current" });
+search_session({ query: "$ARGUMENTS" });
+read_session({ session_reference: "last" });
+```
+
+## Parallel Subagent Research (if --parallel or complex task)
+
+**Delegation Pattern: Fire and Continue**
+
+For complex tasks, launch research subagents in parallel before diving into code:
+
+```typescript
+// Codebase patterns - find similar implementations
+Task({
+  subagent_type: "explore",
+  prompt: `For implementing $ARGUMENTS, find:
+    1. Similar patterns in this codebase (grep/ast-grep)
+    2. Related test files and testing patterns
+    3. Configuration or setup requirements
+    Return: File paths, code patterns, test approach`,
+  description: "Explore patterns for implementation",
+});
+
+// External best practices - library docs
+Task({
+  subagent_type: "scout",
+  prompt: `Research best practices for $ARGUMENTS:
+    1. Official documentation for libraries involved
+    2. Common implementation patterns (Context7, GitHub)
+    3. Known pitfalls or gotchas
+    Return: Code examples, API usage, warnings`,
+  description: "Scout external docs",
+});
+
+// Continue working immediately - don't wait for results
 ```
 
+**Subagent Rules:**
+| Agent | Use For | Can Do | Cannot Do |
+| -------- | ------------------------------ | ---------------- | ---------------- |
+| `explore`| Codebase search, patterns | Read, grep, glob | Edit, bd sync |
+| `scout` | External docs, best practices | Fetch, search | Edit, bd sync |
+| `review` | Code review, debugging | Read, analyze | Edit, bd sync |
+| `planner`| Architecture, decomposition | Read, plan | Edit, bd sync |
+
+**You (build agent) are the leader:**
+
+- Subagents return results to you
+- Only you modify files and update beads
+- Integrate subagent findings into your implementation
+
 ## Estimate Your Budget
 
 Look at the task complexity and set limits:
 
-- **Small** (~10 tool calls): Simple change, one file, clear path
-- **Medium** (~30 tool calls): Multiple files, some exploration needed
-- **Large** (~100 tool calls): Cross-cutting, needs research, checkpoint often
-- **XL**: Should be decomposed into smaller tasks first
+| Size   | Tool Calls | Scope                               |
+| ------ | ---------- | ----------------------------------- |
+| Small  | ~10        | Simple change, one file, clear path |
+| Medium | ~30        | Multiple files, some exploration    |
+| Large  | ~100       | Cross-cutting, needs checkpoints    |
+| XL     | Stop       | Decompose into subtasks first       |
+
+**If XL detected:**
+
+```
+This task is too large for a single session.
+Recommend: /plan $ARGUMENTS --create-beads
+```
 
-If you hit 80% of budget without finishing, create a handoff. Don't push past limits and produce garbage.
+If you hit 80% of budget without finishing, create a handoff. Don't push past limits.
+
+## Lock Files Before Editing
+
+For shared files or multi-agent coordination:
+
+```typescript
+bd - reserve({ paths: ["src/file-to-edit.ts"], ttl: 600 });
+```
+
+Release after completing edits:
+
+```typescript
+bd - release({ paths: ["src/file-to-edit.ts"] });
+```
 
 ## Do The Work
 
 Detect project type and know your verification commands:
 
-```
-!`ls package.json Cargo.toml pyproject.toml go.mod Makefile 2>/dev/null`
+```bash
+ls package.json Cargo.toml pyproject.toml go.mod Makefile 2>/dev/null
 ```
 
-Node/TypeScript: `npm test`, `npm run lint && npm run type-check`
-Rust: `cargo test`, `cargo clippy -- -D warnings`
-Python: `pytest`, `ruff check . && mypy .`
-Go: `go test ./...`, `golangci-lint run`
+| Project | Test Command    | Lint Command                        |
+| ------- | --------------- | ----------------------------------- |
+| Node/TS | `npm test`      | `npm run lint && npm run typecheck` |
+| Rust    | `cargo test`    | `cargo clippy -- -D warnings`       |
+| Python  | `pytest`        | `ruff check . && mypy .`            |
+| Go      | `go test ./...` | `golangci-lint run`                 |
 
 **Rules while implementing:**
 
-1. Read before edit. Always.
-2. Run verification after each logical change
-3. If something fails 3 times, stop and try a different approach
-4. Checkpoint commit after significant progress: `git commit -m "WIP: $ARGUMENTS - [step]"`
-5. If blocked on external dependency, create a new bead for it and move on
+1. **Read before edit.** Always.
+2. **Run verification** after each logical change
+3. **Delegate when stuck**: If blocked on understanding, launch `@explore` or `@scout`
+4. **Checkpoint** after significant progress: `git commit -m "WIP: $ARGUMENTS - [step]"`
+5. **Create child beads** for discovered subtasks:
+   ```bash
+   bd create "Discovered: [subtask]" -t subtask -p 2
+   bd dep add <new-id> $ARGUMENTS --type blocks
+   ```
+
+**Progress tracking** - every 10 tool calls:
 
-Track your progress. Every 10 tool calls, check: Am I on track? Should I checkpoint? Am I approaching budget?
+- Am I on track?
+- Should I checkpoint?
+- Am I approaching budget?
+- Need to delegate research?
+
+## Subtask Coordination (if parent task)
+
+If implementing a task with subtasks:
+
+```bash
+# Check which subtasks are ready
+bd ready --json | jq '.[] | select(.parent == "$ARGUMENTS")'
+
+# Work on ready subtasks in order
+# When subtask done:
+bd close <subtask-id> --reason "Completed: description"
+
+# Check if parent can close
+bd dep tree $ARGUMENTS
+```
+
+**Pattern: Complete subtasks before parent**
 
 ## Before Claiming Done
 
 Verify against success criteria in the spec:
 
-```
-!`cat .beads/artifacts/$ARGUMENTS/spec.md | grep -A 20 "Success Criteria"`
+```bash
+cat .beads/artifacts/$ARGUMENTS/spec.md | grep -A 20 "Success Criteria" || \
+cat .beads/artifacts/$ARGUMENTS/spec.md | grep -A 20 "Acceptance Criteria"
 ```
 
 Run each verification command. All must pass. No exceptions.
@@ -107,7 +245,7 @@ Run the full test suite one more time:
 
 ```bash
 # Whatever your project uses
-npm test && npm run type-check
+npm test && npm run typecheck
 ```
 
 ## Complete
@@ -126,9 +264,12 @@ git diff --cached --stat
 Implementation Complete: $ARGUMENTS
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
+Type: [epic/task/subtask]
 Tests: Pass ✓
 Changes: [files modified]
 
+Subtasks: [N completed / M total] (if applicable)
+
 Would you like me to:
 1. Commit these changes
 2. Show full diff first
@@ -144,10 +285,17 @@ git commit -m "$ARGUMENTS: [summary]"
 bd sync
 ```
 
-Suggest next step:
+Suggest next step based on hierarchy:
+
+| Situation            | Next Command                |
+| -------------------- | --------------------------- |
+| Subtask done         | `/implement <next-subtask>` |
+| All subtasks done    | `/finish <parent-task>`     |
+| Task done, no parent | `/finish $ARGUMENTS`        |
+| Need PR              | `/pr $ARGUMENTS`            |
 
 ```
-Next: /finish $ARGUMENTS
+Next: [recommended command]
 ```
 
 If gates fail, fix them. Don't proceed with broken code.
@@ -161,3 +309,11 @@ Hit budget limit or context getting too large? Create a handoff:
 ```
 
 Then start a fresh session. Don't grind past diminishing returns.
+
+## Release File Locks
+
+Before ending session:
+
+```typescript
+bd - release({ _: true }); // List and release all locks
+```