opencodekit 0.12.2 → 0.12.4

package/dist/index.js

@@ -750,7 +750,7 @@ var cac = (name = "") => new CAC(name);
 // package.json
 var package_default = {
   name: "opencodekit",
-  version: "0.12.2",
+  version: "0.12.4",
   description: "CLI tool for bootstrapping and managing OpenCodeKit projects",
   type: "module",
   repository: {

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

@@ -1,64 +1,5 @@
 # OpenCode Global Rules
 
-## Constraint Awareness
-
-OpenCode operates at **Stage 5-6** of AI adoption:
-
-- **Stage 5** (Agentic Verification): Agents run tests and iterate autonomously
-- **Stage 6** (Multi-Agent Orchestration): Parallel workstreams with coordination
-
-**Current constraint**: Planning and specification quality. Implementation capacity is not the bottleneck—how well you specify requirements is.
-
-### Autonomous Duration
-
-The key metric: **How long can an agent work before losing the plot?**
-
-Extend autonomous duration by:
-
-- Binding tighter to intent (clear specs, constraints, invariants)
-- Providing systematic context (AGENTS.md hierarchy, memory files)
-- Verification loops (test → iterate → verify)
-
-### Greenfield vs Legacy
-
-- **Greenfield**: Simple context, fast prototypes, agents work well immediately
-- **Legacy**: Complex context, hidden invariants, "that one place you must not touch"
-
-Codebase complexity is a primary difficulty knob. Context is how you pay it down.
-
-### Context Engineering Principles
-
-**Three constraints on context:**
-
-1. **Blind spots cause hallucinations** - If agent doesn't see specific context, it fills gaps with generic training priors. You only get the behavior you load.
-2. **Everything influences everything** - Noise-to-signal ratio matters. Irrelevant files degrade ALL output quality.
-3. **Window is finite** - Performance degrades BEFORE hitting hard token limits. Curate the smallest, highest-signal slice.
-
-**Practical implications:**
-
-- Prefer `lsp_lsp_document_symbols` over reading entire files
-- Read specific line ranges, not whole documents
-- Navigate AGENTS.md hierarchy: root → subsystem → details (progressive disclosure)
-- Prune context aggressively; completed work doesn't need to stay loaded
-
-### Intent Layer Principles
-
-**What belongs in each AGENTS.md (Intent Node):**
-
-- **Purpose & Scope** - What this area does. What it explicitly DOESN'T do.
-- **Entry Points & Contracts** - Main APIs, invariants, "all X goes through Y"
-- **Usage Patterns** - Canonical examples: "To add a rule, follow this pattern..."
-- **Anti-patterns** - Negative examples: "Never call X directly; go through Y"
-- **Dependencies & Downlinks** - What it connects to, pointers to child AGENTS.md
-- **Pitfalls** - Things that repeatedly confused agents/humans
-
-**Key mechanics:**
-
-- **Hierarchical loading** - When a node loads, all ancestors load too (T-shaped view)
-- **Compression, not bloat** - Good nodes compress code; if node is 10k tokens for 20k code, you're adding weight
-- **Least Common Ancestor (LCA)** - Place shared knowledge at shallowest node covering all relevant paths
-- **Downlinks for discovery** - Point to related context without loading everything upfront
-
 ## Priority Hierarchy
 
 1. Security constraints (always first)
@@ -84,21 +25,10 @@ Codebase complexity is a primary difficulty knob. Context is how you pay it down
 
 ### Research Depth Levels
 
-Specify depth when delegating to control tool call budget:
-
 - **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
 
-**Examples**:
-
-```
-@explore (quick): Where is the auth middleware?
-@explore (thorough): How does the entire auth system work?
-@scout (quick): Syntax for React useEffect cleanup
-@scout (thorough): How do production apps handle auth refresh tokens?
-```
-
 ## Anti-Hallucination
 
 - **Major features**: Check task exists (`bd show <id>`)
@@ -109,76 +39,29 @@ Specify depth when delegating to control tool call budget:
 
 ## Interaction Modes
 
-### Sounding Board Mode
-
-Recognize when user wants discussion, not action. Trigger phrases:
-
-- "Let's chat for a second..."
-- "Help me think through this..."
-- "Before we write any code..."
-- "What are the tradeoffs of..."
-- "I'm torn between X and Y..."
-- "Play devil's advocate..."
-
-**Response**: Ask clarifying questions, surface tradeoffs, explore alternatives. Don't jump to implementation.
-
-### Execution Mode (Default)
-
-Take action. Produce output. Iterate based on feedback.
+| 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.
 
-### Generic + Specific Pattern
-
-For batch operations, combine generic goal with concrete example:
-
-```
-"Refactor all database queries to use parameterized statements.
-
-For example, this: db.execute(f"SELECT * FROM users WHERE id = {user_id}")
-Becomes: db.execute("SELECT * FROM users WHERE id = ?", [user_id])
-
-Find and fix all similar patterns."
-```
-
-The generic sets intent; the example sets format. Agent generalizes from example.
-
-### Inject Uncertainty
-
-When facing design decisions, don't just accept user framing as gospel. Question assumptions:
-
-- If user says "use SQLite for cache" → Ask about tradeoffs vs alternatives
-- If user provides a list → Ask if categories make sense, what's missing
-- If plan seems too simple → Surface edge cases they might not have considered
-
-Trigger uncertainty mode with phrases like:
-
-- "I think this should be... but I'm not sure that's right"
-- "My plan is X, but I'm second-guessing whether..."
-- "What am I missing here?"
-
 ## Universal Standards
 
 ### Communication
 
 - Under 4 lines for typical responses
 - Brief preamble before big tool calls
-- No explanation summaries unless asked
 - Use `file:line_number` format for code references
 - No emojis unless explicitly requested
-- Keep going until query resolved; don't ask to continue
 
 ### Execution
 
 - Batch independent tool calls (parallel)
 - Verify with tools; don't assume
 - Obey project AGENTS.md files (nested takes precedence)
-- Prioritize technical accuracy; disagree when necessary
-
-### Planning
-
 - TodoWrite BEFORE work; mark completed immediately
-- Verify assumptions with tools
 
 ### Security
 
@@ -188,337 +71,77 @@ Trigger uncertainty mode with phrases like:
 
 ## Tool Priority
 
-**LSP tools → AST-grep → Built-in tools**
-
-1. **LSP tools** - Semantic code intelligence (10 tools)
-2. `ast-grep` - **Code search/replace** (functions, patterns, imports, hooks)
-3. `grep` - **Text search** (logs, config, non-code files, simple strings)
-4. `glob` - File discovery by name pattern
-5. `read`, `edit`, `write` - File operations
-
-### Choosing the Right Search Tool
-
-Ask yourself: **"Am I looking for code structure or just text?"**
-
-**Use `ast-grep` when you need to find:**
-
-- How a function is called → `pattern="fetchUser($$$)"`
-- Where a hook is used → `pattern="useState($$$)"`
-- Import statements → `pattern="import { $$ } from '$MOD'"`
-- Class definitions → `pattern="class $NAME { $$$ }"`
-- Try-catch blocks → `pattern="try { $$$ } catch ($E) { $$$ }"`
-
-**Use `grep` when you need to find:**
-
-- Error messages in logs → `pattern="FATAL|ERROR"`
-- Config values → `pattern="API_KEY"`
-- TODO comments → `pattern="TODO|FIXME"`
-- Text in markdown/docs → `pattern="deprecated"`
-
-**Use LSP tools when you need to:**
-
-- Understand what a symbol is → `lsp_lsp_hover`
-- Jump to where something is defined → `lsp_lsp_goto_definition`
-- Find all usages before refactoring → `lsp_lsp_find_references`
-- Rename across the entire codebase → `lsp_lsp_rename`
+Load `skill tool-priority` for full LSP, ast-grep, and grep reference.
 
-**Rule**: Always `read` before `edit` to verify content.
+**Quick reference**: LSP tools → ast-grep → grep → glob → read/edit/write
 
-### LSP Tools (10 tools)
+| 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`            |
 
-Semantic code intelligence via Language Server Protocol. **Uses `lsp_lsp_*` prefix** (built-in experimental).
+**Rule**: Always `read` before `edit`.
 
-**Navigation & Understanding:**
+## Context Engineering
 
-- `lsp_lsp_hover(filePath, line, character)` - Get type info and docs at cursor
-- `lsp_lsp_goto_definition(filePath, line, character)` - Jump to where symbol is defined
-- `lsp_lsp_find_references(filePath, line, character)` - Find all usages of a symbol
-- `lsp_lsp_document_symbols(filePath)` - Get file outline (classes, functions, etc.)
-- `lsp_lsp_workspace_symbols(query, filePath)` - Fuzzy search symbols across workspace
+Load `skill context-engineering` for context management principles.
 
-**Diagnostics:**
+**Quick reference**:
 
-- `lsp_lsp_diagnostics(filePath, severity?)` - Get errors/warnings from language server
-
-**Refactoring:**
-
-- `lsp_lsp_rename(filePath, line, character, newName)` - Rename symbol across codebase
-- `lsp_lsp_code_actions(filePath, startLine, startChar, endLine, endChar)` - Get available refactorings
-- `lsp_lsp_code_action_apply(...)` - Apply a specific code action
-- `lsp_lsp_organize_imports(filePath)` - Clean up and sort imports
-
-**When to use each tool:**
-
-**"What type is this variable?"** → Use `lsp_lsp_hover` to see type signature without reading the entire definition file.
-
-**"Where is this function defined?"** → Use `lsp_lsp_goto_definition` to jump directly to source instead of grepping.
-
-**"What uses this function?"** → Use `lsp_lsp_find_references` before changing anything to see all call sites.
-
-**"What's in this file?"** → Use `lsp_lsp_document_symbols` for a quick outline without reading the entire file.
-
-**"Where is UserService defined?"** → Use `lsp_lsp_workspace_symbols` to fuzzy search across all files.
-
-**"Are there type errors?"** → Use `lsp_lsp_diagnostics` to check before running tests.
-
-**"Rename this function safely"** → Use `lsp_lsp_rename` to update all references automatically.
-
-**Caveat**: LSP tools modify files directly. Re-read files before further edits.
-
-### AST-Grep Usage
-
-Semantic code operations - smarter than regex:
-
-```bash
-# Search patterns
-ast-grep pattern="console.log($$$)"                    # Find all console.log
-ast-grep pattern="async function $NAME($$$) { $$$ }"   # Find async functions
-ast-grep pattern="const [$S, $SET] = useState($$$)"    # Find React hooks
-
-# Replace (dry run by default)
-ast-grep pattern="oldFunc($$$)" rewrite="newFunc($$$)" dryRun=true
-ast-grep pattern="fetch($URL)" rewrite="await fetch($URL)" dryRun=false
-```
-
-**Pattern syntax**: `$NAME` = single node, `$$$` = zero or more nodes
+- 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
 
-- **context7** - Library docs (try first). Fast, external APIs.
-- **websearch** - Docs not in Context7, recent releases, troubleshooting.
-- **codesearch** - Real implementation patterns from GitHub.
-- **webfetch** - Specific URL user provided.
+| 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 message, adjust approach, retry once. If still blocked, ask user to check hooks/config.
+- **Blocked by hook/CI**: Analyze error, adjust approach, retry once
 
 ## Memory System
 
-```
-.opencode/memory/
-  _templates/     # Task templates (prd, observation, session-summary)
-  handoffs/       # Phase transitions
-  research/       # Research findings
-  observations/   # Structured observations
-  project/        # Persistent project knowledge
-    commands.md       # Build, test, lint, deploy commands
-    conventions.md    # Code patterns, commit style, PR process
-    gotchas.md        # Footguns, edge cases, "don't forget this"
-    architecture.md   # Key modules, directory structure
-  user.md         # Identity, preferences, communication style
-```
-
-### Standard Memory Blocks
-
-- **project/commands.md** - Build/test/lint commands. Update when discovering new command.
-- **project/conventions.md** - Code patterns, style. Update when learning team pattern.
-- **project/gotchas.md** - Footguns, warnings. Update when hitting unexpected behavior.
-- **project/architecture.md** - Key modules, structure. Update when mapping new area.
-- **user.md** - Preferences, workflow. Update when learning user preference.
-
-### Explicit Memory Updates
-
-Don't rely on implicit learning. Explicitly persist:
-
-- Non-obvious project behavior → `project/gotchas.md`
-- User preferences discovered → `user.md`
-- New build/test commands → `project/commands.md`
-- Code patterns to follow → `project/conventions.md`
-
-### Memory Tools
-
-- **memory-read** - Load previous context, templates
-- **memory-update** - Save learnings, handoffs
-- **memory-search** - Search across all memory files
-- **observation** - Create structured observations
-
-### Observations
-
-Record important findings with structured metadata:
-
-```
-observation(
-  type: "decision",     # decision, bugfix, feature, pattern, discovery, learning, warning
-  title: "Use JWT auth",
-  content: "Decided to use JWT because...",
-  concepts: "auth, security",
-  files: "src/auth.ts",
-  bead_id: "bd-abc123"
-)
-```
-
-**When to create observations:**
-
-- Major architectural decisions
-- Bug root causes discovered
-- Patterns worth reusing
-- Gotchas and warnings for future
-
-### Memory Search
-
-Find past decisions, research, or handoffs:
-
-```
-memory-search(query: "authentication")
-memory-search(query: "bugfix", type: "observations")
-memory-search(query: "session", type: "handoffs")
-```
+Load `skill memory-system` for memory tools and update patterns.
 
-- Task tracking uses Beads (`bd` CLI)
+**Quick reference**: `memory-read`, `memory-update`, `memory-search`, `observation`
 
 ## Session Management
 
-**Philosophy**: Short sessions (<150k tokens) beat long bloated ones. Agents get worse with too much context. Cost is exponential.
-
-### Context Thresholds
-
-The environment monitors context usage and warns at these thresholds:
-
-- **70%** - Consolidate work; consider pruning irrelevant tool outputs
-- **85%** - Summarize findings and consider starting a new session
-- **95%** - Critical: prune context immediately or restart session
+Load `skill session-management` for session tools and context thresholds.
 
-### Session Tools
+**Philosophy**: Short sessions (<150k tokens) beat long bloated ones.
 
-**`list_sessions`** - Discover available sessions before reading
-
-```
-list_sessions(limit=10, project="current")           # Current project
-list_sessions(since="today")                          # Today's sessions
-list_sessions(project="all", since="yesterday")       # Cross-project
-```
-
-**`read_session`** - Pull context from previous session
-
-```
-read_session("last")                                  # Most recent
-read_session("2 ago", project="current")              # 2nd most recent
-read_session("today")                                 # Today's first session
-read_session("ses_abc123", focus="file changes")      # Specific aspect
-```
-
-**`search_session`** - Full-text search across sessions
-
-```
-search_session(query="auth bug")                      # Search all sessions
-search_session(query="OAuth", session_id="ses_abc")   # Search specific session
-search_session(query="error", limit=10)               # Limit results
-```
-
-Use to find past discussions, decisions, or work on a topic before starting new work.
-
-**`summarize_session`** - Generate AI summary of a session
-
-```
-summarize_session("ses_abc123")                       # Trigger AI summarization
-```
-
-Use before `read_session` to get a quick overview of what happened in a past session without loading full context.
-
-### When to Start New Session
-
-- Completing distinct task from `bd ready`
-- Token usage approaching 150k
-- Switching phases (implementation → review → testing)
-- After handoff (`/handoff <bead-id>`)
-
-### Session Workflow Pattern
-
-```
-Session 1: Implement feature X (80k tokens)
-  ↓ close, update memory
-Session 2: list_sessions() → read_session("last") → Refactor (60k tokens)
-  ↓
-Session 3: read_session("previous") → Add tests (90k tokens)
-  ↓
-Session 4: read_session refs → Final review (100k tokens)
-```
-
-**Result**: 4 fresh contexts vs 1 degraded 330k context. Better performance, lower cost.
-
-### Context Transfer
-
-Use all three:
-
-1. `read_session("last")` - Previous session work
-2. Git state - `git diff`, `git log` - Code changes
-3. Memory files - `.opencode/memory/*` - Persistent context
-4. Beads - `bd show <id>` - Task specs
-
-**Don't**: Carry everything forward. Extract what's needed, discard the rest.
+**Quick reference**: `list_sessions`, `read_session`, `search_session`, `summarize_session`
 
 ## Beads Usage
 
-**Session start**: `bd_doctor()` then `bd_claim()`
-**Session end**: Complete one bead fully before starting next
-**Weekly**: `bd_cleanup(days=7)` then `bd_sync()`
-
-**Philosophy**: Beads is execution, not planning. Plan elsewhere, track in Beads.
+**Leader agents only**: Only `build` and `rush` use beads tools.
+**Subagents** (explore, scout, planner, review, vision): Do NOT touch beads.
 
-## Beads Tools (Multi-Agent Coordination)
+Load `skill beads` for full workflow, tool reference, and patterns.
 
-Native plugin tools for task coordination and file locking between agents.
-
-### When to Use
-
-- **Multi-agent work**: Multiple agents on same codebase
-- **File conflict prevention**: Reserve files before editing
-- **Cross-workspace coordination**: FE/BE/Mobile agents communicating
-
-### Core Workflow
+**Quick reference**:
 
 ```
 bd_init() → bd_claim() → bd_reserve(paths) → [work] → bd_done(id, msg) → RESTART
 ```
 
-### Tool Reference
-
-**Lifecycle Tools**
-
-Start every session by calling `bd_init` with your team name and role. This registers you in the workspace and enables role-based task filtering. For example, `bd_init({ team: "project", role: "fe" })` joins as a frontend agent.
-
-Call `bd_claim` to get the next ready task assigned to your role. It auto-filters based on task tags matching your role and marks the task as in_progress.
-
-When work is complete, call `bd_done` with the task ID and completion message. This closes the task, releases all file reservations, and syncs with git. After `bd_done`, restart your session for fresh context.
-
-**Task Management Tools**
-
-Use `bd_add` to create new tasks for discovered work. Specify title, optional description, and priority (0=critical through 4=backlog). Use `bd_assign` to assign tasks to specific roles like fe, be, mobile, devops, or qa.
-
-Call `bd_ls` to list tasks filtered by status: open, closed, in_progress, ready, or all. Use `bd_show` with a task ID to get full details including description, notes, and history.
-
-**File Reservation Tools**
-
-Before editing any file, call `bd_reserve` with the file paths you need. This creates locks that prevent other agents from modifying the same files. Locks expire after 600 seconds by default.
-
-Call `bd_release` to unlock files early, or let `bd_done` release them automatically. Use `bd_reservations` to see all active locks across the workspace before editing.
-
-**Messaging Tools**
-
-Send messages with `bd_msg` using a subject and optional body. Set `to: "all"` for broadcast messages visible to all agents. Check incoming messages with `bd_inbox`, optionally filtering to unread only.
-
-**Status and Maintenance Tools**
-
-Call `bd_status` to get workspace overview including ready task count, in-progress tasks, and active locks. Use `bd_sync` to manually sync with git.
-
-Run `bd_cleanup` periodically to remove old closed issues. Use `bd_doctor` to check and repair database health.
-
-**Analysis Tools**
-
-Use `bd_blocked` to see tasks with unresolved dependencies. Use `bd_dep` with action "tree" to visualize dependency chains.
-
-Use `bd_diff` to compare issue changes between git revisions.
-
-### Rules
+**Rules**:
 
-- **Always `bd_init()` first** in any session using beads tools
-- **Reserve before edit** to prevent conflicts
-- **One task per session** - restart after `bd_done()`
-- **Use `bd_msg(to="all")`** for team-wide announcements
+- Always `bd_init()` first in any session using beads tools
+- Reserve before edit to prevent conflicts
+- One task per session - restart after `bd_done()`
 
 ## Core Constraints