opencodekit 0.12.2 → 0.12.3

package/dist/template/.opencode/skill/context-engineering/SKILL.md

@@ -0,0 +1,94 @@
+---
+description: Use when managing context window, deciding what to load/prune, or understanding AI adoption stages - covers constraint awareness and intent layer principles
+---
+
+# Context Engineering Skill
+
+## AI Adoption Stages
+
+OpenCode operates at **Stage 5-6**:
+
+- **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
+
+| Type           | Context                    | Agent Performance             |
+| -------------- | -------------------------- | ----------------------------- |
+| **Greenfield** | Simple, fast prototypes    | Works well immediately        |
+| **Legacy**     | Complex, hidden invariants | Needs careful context loading |
+
+Codebase complexity is a primary difficulty knob. Context is how you pay it down.
+
+## Three Context Constraints
+
+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
+
+| Instead of              | Do This                                               |
+| ----------------------- | ----------------------------------------------------- |
+| Reading entire files    | Use `lsp_lsp_document_symbols` for outline            |
+| Loading whole documents | Read specific line ranges                             |
+| Flat file loading       | Navigate AGENTS.md hierarchy (progressive disclosure) |
+| Keeping completed work  | Prune context aggressively                            |
+
+## Intent Layer Principles
+
+### What Belongs in Each AGENTS.md
+
+- **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
+
+| Principle                       | Meaning                                                       |
+| ------------------------------- | ------------------------------------------------------------- |
+| **Hierarchical loading**        | When a node loads, all ancestors load too (T-shaped view)     |
+| **Compression, not bloat**      | Good nodes compress code; 10k tokens for 20k code adds weight |
+| **Least Common Ancestor (LCA)** | Place shared knowledge at shallowest node covering all paths  |
+| **Downlinks for discovery**     | Point to related context without loading everything upfront   |
+
+## Context Budget Guidelines
+
+| Phase             | Target Context | Action                                    |
+| ----------------- | -------------- | ----------------------------------------- |
+| Starting work     | <50k tokens    | Load only essential AGENTS.md + task spec |
+| Mid-task          | 50-100k tokens | Prune completed reads, keep active files  |
+| Approaching limit | >100k tokens   | Aggressive pruning, extract key findings  |
+| Near capacity     | >150k tokens   | Consider session restart with handoff     |
+
+## Anti-Patterns
+
+❌ Loading "everything that might be relevant"
+❌ Keeping old file reads after editing complete
+❌ Reading entire files when you only need a function
+❌ Ignoring AGENTS.md hierarchy (loading leaf without ancestors)
+
+## Best Practices
+
+✅ Start with minimum viable context
+✅ Use LSP tools for targeted information
+✅ Prune after each completed sub-task
+✅ Trust AGENTS.md hierarchy for discovery
+✅ Extract findings before pruning valuable reads

package/dist/template/.opencode/skill/memory-system/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: memory-system
+description: Use when persisting learnings, loading previous context, or searching past decisions - covers memory file structure, tools, and when to update each file
+---
+
+# Memory System
+
+Persistent context that survives across sessions.
+
+## Directory Structure
+
+```
+.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
+
+| File                      | Purpose                  | Update When                 |
+| ------------------------- | ------------------------ | --------------------------- |
+| `project/commands.md`     | Build/test/lint commands | Discovering new command     |
+| `project/conventions.md`  | Code patterns, style     | Learning team pattern       |
+| `project/gotchas.md`      | Footguns, warnings       | Hitting unexpected behavior |
+| `project/architecture.md` | Key modules, structure   | Mapping new area            |
+| `user.md`                 | Preferences, workflow    | 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 or templates:
+
+```typescript
+memory - read({ file: "project/commands" }); // Load commands
+memory - read({ file: "_templates/prd" }); // Load PRD template
+memory - read({ file: "handoffs/bd-abc123" }); // Load specific handoff
+```
+
+### memory-update
+
+Save learnings or handoffs:
+
+```typescript
+memory -
+  update({
+    file: "project/gotchas",
+    content: "### New Gotcha\n\nDescription...",
+    mode: "append", // or "replace"
+  });
+```
+
+### memory-search
+
+Find past decisions, research, or handoffs:
+
+```typescript
+memory - search({ query: "authentication" });
+memory - search({ query: "bugfix", type: "observations" });
+memory - search({ query: "session", type: "handoffs" });
+```
+
+## Observations
+
+Record important findings with structured metadata:
+
+```typescript
+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
+
+## Best Practices
+
+1. **Read before work** - Check relevant memory files at session start
+2. **Update during work** - Don't wait until end; persist incrementally
+3. **Be specific** - Include file paths, function names, concrete examples
+4. **Keep it actionable** - Future agents should know what to do with the info

package/dist/template/.opencode/skill/session-management/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: session-management
+description: Use when context is growing large, switching tasks, or needing previous session context - covers thresholds, session tools, and workflow patterns
+---
+
+# 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:
+
+| Threshold | Action                                                     |
+| --------- | ---------------------------------------------------------- |
+| **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     |
+
+## Session Tools
+
+### list_sessions
+
+Discover available sessions before reading:
+
+```typescript
+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:
+
+```typescript
+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:
+
+```typescript
+search_session({ query: "auth bug" }); // Search all sessions
+search_session({ query: "OAuth", session_id: "ses_abc" }); // 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:
+
+```typescript
+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 available sources:
+
+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.
+
+## Pruning Strategy
+
+When context grows large:
+
+1. **Discard** completed task outputs (read files you won't edit again)
+2. **Extract** key findings before discarding research
+3. **Summarize** complex investigations into memory files
+4. **Restart** session if above 85% and work is at a natural break
+
+## Anti-Patterns
+
+- ❌ Running until context limit forces restart
+- ❌ Carrying all previous reads forward "just in case"
+- ❌ Not using memory files for cross-session persistence
+- ❌ Re-reading the same files every session instead of extracting key info

package/dist/template/.opencode/skill/tool-priority/SKILL.md

@@ -0,0 +1,115 @@
+---
+description: Use when choosing between search tools (LSP, ast-grep, grep, glob) or need tool reference - covers when to use each tool and detailed syntax
+---
+
+# Tool Priority Skill
+
+## Priority Order
+
+**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
+
+**Rule**: Always `read` before `edit` to verify content.
+
+## Choosing the Right Tool
+
+Ask: **"Am I looking for code structure or just text?"**
+
+| Need              | Tool                      | Example                               |
+| ----------------- | ------------------------- | ------------------------------------- |
+| Function calls    | `ast-grep`                | `pattern="fetchUser($$$)"`            |
+| Hook usage        | `ast-grep`                | `pattern="useState($$$)"`             |
+| Import statements | `ast-grep`                | `pattern="import { $$ } from '$MOD'"` |
+| Error messages    | `grep`                    | `pattern="FATAL\|ERROR"`              |
+| Config values     | `grep`                    | `pattern="API_KEY"`                   |
+| TODO comments     | `grep`                    | `pattern="TODO\|FIXME"`               |
+| Symbol type info  | `lsp_lsp_hover`           | Type signature at cursor              |
+| Definition jump   | `lsp_lsp_goto_definition` | Source location                       |
+| All usages        | `lsp_lsp_find_references` | Before refactoring                    |
+| Safe rename       | `lsp_lsp_rename`          | All references updated                |
+
+## LSP Tools Reference
+
+Semantic code intelligence via Language Server Protocol. **Uses `lsp_lsp_*` prefix** (built-in experimental).
+
+### Navigation & Understanding
+
+| Tool                                                 | Purpose                               | When to Use                       |
+| ---------------------------------------------------- | ------------------------------------- | --------------------------------- |
+| `lsp_lsp_hover(filePath, line, character)`           | Type info and docs at cursor          | "What type is this variable?"     |
+| `lsp_lsp_goto_definition(filePath, line, character)` | Jump to where symbol is defined       | "Where is this function defined?" |
+| `lsp_lsp_find_references(filePath, line, character)` | Find all usages of a symbol           | "What uses this function?"        |
+| `lsp_lsp_document_symbols(filePath)`                 | File outline (classes, functions)     | "What's in this file?"            |
+| `lsp_lsp_workspace_symbols(query, filePath)`         | Fuzzy search symbols across workspace | "Where is UserService defined?"   |
+
+### Diagnostics
+
+| Tool                                       | Purpose                              | When to Use              |
+| ------------------------------------------ | ------------------------------------ | ------------------------ |
+| `lsp_lsp_diagnostics(filePath, severity?)` | Errors/warnings from language server | "Are there type errors?" |
+
+### Refactoring
+
+| Tool                                                                     | Purpose                       | When to Use                        |
+| ------------------------------------------------------------------------ | ----------------------------- | ---------------------------------- |
+| `lsp_lsp_rename(filePath, line, character, newName)`                     | Rename symbol across codebase | "Rename this function safely"      |
+| `lsp_lsp_code_actions(filePath, startLine, startChar, endLine, endChar)` | Get available refactorings    | "What refactorings are available?" |
+| `lsp_lsp_code_action_apply(...)`                                         | Apply a specific code action  | Execute chosen refactoring         |
+| `lsp_lsp_organize_imports(filePath)`                                     | Clean up and sort imports     | "Fix imports"                      |
+
+**Caveat**: LSP tools modify files directly. Re-read files before further edits.
+
+## AST-Grep Reference
+
+Semantic code operations - smarter than regex.
+
+### Pattern Syntax
+
+- `$NAME` - Matches any single AST node (identifier, expression, etc.)
+- `$$$` - Matches zero or more nodes (for arguments, statements, etc.)
+
+### Search Examples
+
+```bash
+# Find all console.log calls
+ast-grep pattern="console.log($$$)"
+
+# Find async functions
+ast-grep pattern="async function $NAME($$$) { $$$ }"
+
+# Find React hooks
+ast-grep pattern="const [$S, $SET] = useState($$$)"
+
+# Find try-catch blocks
+ast-grep pattern="try { $$$ } catch ($E) { $$$ }"
+
+# Find class definitions
+ast-grep pattern="class $NAME { $$$ }"
+
+# Find import statements
+ast-grep pattern="import { $$ } from '$MOD'"
+```
+
+### Replace Examples
+
+```bash
+# Rename function (dry run)
+ast-grep pattern="oldFunc($$$)" rewrite="newFunc($$$)" dryRun=true
+
+# Add await (apply)
+ast-grep pattern="fetch($URL)" rewrite="await fetch($URL)" dryRun=false
+```
+
+## Research Tools
+
+| Tool           | Use When                                                |
+| -------------- | ------------------------------------------------------- |
+| **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.                             |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencodekit",
-	"version": "0.12.2",
+	"version": "0.12.3",
 	"description": "CLI tool for bootstrapping and managing OpenCodeKit projects",
 	"type": "module",
 	"repository": {