opencodekit 0.18.4 → 0.18.5

package/dist/template/.opencode/skill/systematic-debugging/SKILL.md

@@ -8,6 +8,8 @@ dependencies: []
 
 # Systematic Debugging
 
+> **Replaces** "shotgun debugging" — making random changes hoping something fixes the issue without understanding the cause
+
 ## When to Use
 
 - Test failures, production bugs, build breaks, or unexpected behavior
@@ -338,6 +340,15 @@ If you catch yourself thinking:
 | "I see the problem, let me fix it"           | Seeing symptoms ≠ understanding root cause.                             |
 | "One more fix attempt" (after 2+ failures)   | 3+ failures = architectural problem. Question pattern, don't fix again. |
 
+## Anti-Patterns
+
+| Anti-Pattern | Why It Fails | Instead |
+| --- | --- | --- |
+| Changing multiple things at once | You can’t isolate what actually fixed or broke behavior | Change one variable at a time and measure outcome |
+| Not reading the error message carefully | You skip direct clues (file, line, code, failing invariant) | Read the full error and stack trace before edits |
+| Assuming the bug is in the most recently changed code | Correlation bias hides older or shared-state causes | Trace actual data/control flow from symptom to source |
+| Skipping reproduction steps | Non-repro bugs encourage guessing and untestable fixes | Establish reliable repro steps, then verify fix against them |
+
 ## Quick Reference
 
 | Phase                 | Key Activities                                         | Success Criteria            |
@@ -379,3 +390,13 @@ From debugging sessions:
 - Random fixes approach: 2-3 hours of thrashing
 - First-time fix rate: 95% vs 40%
 - New bugs introduced: Near zero vs common
+
+## Verification
+
+- Confirm the fix: reproduce the original bug scenario — it must now succeed.
+- Regression check: run related tests to ensure fix didn't break adjacent behavior.
+
+## See Also
+
+- **root-cause-tracing** - Deep call-stack tracing to identify original trigger before fixing
+- **condition-based-waiting** - Stabilize timing/race-condition fixes with state-based waits

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

@@ -23,14 +23,15 @@ dependencies: []
 **LSP → Search → Swarm → Memory → File Operations**
 
 1. **LSP** - Semantic code intelligence (9 operations via unified tool)
-2. **grep** - Fast text search (logs, config, code patterns)
-3. **glob** - File discovery by name pattern
-4. **skill** - Load skills for specialized knowledge
-5. **task** - Parallel subagent execution
-6. **Swarm tool** - swarm (plan, monitor, delegate, sync operations)
-7. **Memory tools** - memory-search, memory-read, memory-update, memory-admin
-8. **Research tools** - context7, websearch, codesearch, grepsearch
-9. **read/edit/write** - File operations (always read before edit)
+2. **tilth** (MCP) - AST-aware code search + smart file reading. Replaces grep/glob/read for code navigation when available
+3. **grep** - Fast text search (logs, config, code patterns). Replaces bash rg/grep
+4. **glob** - File discovery by name pattern. Replaces bash find/ls
+5. **skill** - Load skills for specialized knowledge
+6. **task** - Parallel subagent execution
+7. **Swarm tool** - swarm (plan, monitor, delegate, sync operations)
+8. **Memory tools** - memory-search, memory-read, memory-update, memory-admin
+9. **Research tools** - context7, websearch, codesearch, grepsearch
+10. **read/edit/write** - File operations (always read before edit)
 
 **Golden Rule**: Always `read` before `edit` to verify content.
 
@@ -130,20 +131,37 @@ Task({
 
 ### Research Tools
 
-| Tool              | Purpose                      | When to Use             |
-| ----------------- | ---------------------------- | ----------------------- |
-| **context7**      | Library documentation lookup | API reference, examples |
-| **websearch**     | Recent info, troubleshooting | Docs not in Context7    |
-| **codesearch**    | Real implementation patterns | GitHub code examples    |
-| **grepsearch**    | Cross-repo patterns          | grep.app search         |
-| **webfetch**      | Specific URL content         | User-provided links     |
-| **review (Task)** | Second opinion               | Validate approach       |
+| Tool              | Purpose                                                         | When to Use             |
+| ----------------- | --------------------------------------------------------------- | ----------------------- |
+| **context7**      | Library documentation lookup. Replaces manual doc searching     | API reference, examples |
+| **websearch**     | Web search. Replaces browser for current info                   | Docs not in Context7    |
+| **codesearch**    | Code examples from GitHub. Replaces manual GitHub search        | Real-world patterns     |
+| **grepsearch**    | Cross-repo code patterns. Replaces browsing GitHub for examples | grep.app search         |
+| **webfetch**      | Fetch specific URL content. Replaces curl/browser               | User-provided links     |
+| **review (Task)** | Second opinion                                                  | Validate approach       |
 
 **context7 operations:**
 
 - `resolve`: Find library ID from name (e.g., "react" → "/reactjs/react.dev")
 - `query`: Get documentation for a library topic
 
+### With tilth MCP (When Available)
+
+tilth provides AST-aware code intelligence. When installed, prefer tilth tools over built-in equivalents:
+
+| Need            | Without tilth        | With tilth                      | Why tilth wins                                          |
+| --------------- | -------------------- | ------------------------------- | ------------------------------------------------------- |
+| Find symbol     | `grep` + `read`      | `tilth_search` (expand: 2)      | Returns definitions with inline source — no second read |
+| Read large file | `read` (full)        | `tilth_read`                    | Auto-outlines, shows structure; section drill-down      |
+| Find files      | `glob`               | `tilth_files`                   | Adds token estimates per file                           |
+| Find callers    | `lsp(incomingCalls)` | `tilth_search(kind: "callers")` | Cross-language, structural matching                     |
+| Blast radius    | Manual tracing       | `tilth_deps`                    | Shows imports + downstream callers automatically        |
+
+**WHEN to use tilth_deps**: Before renaming, removing, or changing the signature of an export.
+**SKIP**: When adding new code, fixing internal bugs, or just reading.
+
+**IMPORTANT**: Expanded tilth_search results include full source code — do NOT re-read files already shown in search output.
+
 ## Workflow Pattern
 
 ```typescript

package/dist/template/.opencode/skill/ui-ux-research/SKILL.md

@@ -1,131 +1,9 @@
 ---
-name: ui-ux-research
-description: Use when analyzing UI patterns across codebases, comparing design system implementations, auditing UI consistency, or understanding existing patterns before implementation
-version: 1.0.0
-tags: [design, research]
-dependencies: []
+description: "Merged into design-system-audit. Load that skill instead."
 ---
 
-# UI/UX Research Skill
+# UI/UX Research
 
-## When to Use
-
-- Analyzing UI patterns across large codebases
-- Comparing design system implementations
-- Auditing UI consistency
-- Understanding existing patterns before implementation
-
-## When NOT to Use
-
-- Single-file UI changes without broader pattern investigation.
-
-
-## Research Patterns
-
-### Find All UI Components
-
-```
-Analyze the components directory.
-List all UI components with their props interfaces.
-```
-
-### Audit Design System Consistency
-
-```
-Check design token usage consistency:
-- Colors
-- Spacing
-- Typography
-
-Identify inconsistencies and suggest consolidation.
-```
-
-### Compare UI Implementations
-
-```
-Compare layout patterns across pages.
-Identify inconsistencies and recommend standardization.
-```
-
-### Accessibility Audit
-
-```
-Audit components for WCAG compliance:
-- Color contrast
-- ARIA labels
-- Keyboard navigation
-
-Prioritize issues by severity.
-```
-
-### Responsive Design Review
-
-```
-Find all responsive breakpoints and media queries.
-Assess mobile-first compliance.
-Identify missing responsive considerations.
-```
-
-## Pattern Search Template
-
-```
-Has [PATTERN] been implemented?
-
-Show:
-1. Files containing the pattern
-2. Implementation approach
-3. Consistency across usages
-4. Potential improvements
-```
-
-**Common patterns to search:**
-
-- Dark mode toggle
-- Form validation
-- Loading states
-- Error boundaries
-- Toast notifications
-- Modal dialogs
-- Data tables
-
-## Integration with Beads
-
-For task-constrained research:
-
-1. Check bead spec constraints
-2. Research within those constraints
-3. Save findings to bead artifacts
-
-## Storage
-
-Save research findings to `.opencode/memory/design/research/`
-
-## Output Format
-
-```markdown
-## Research: [Topic]
-
-### Findings
-
-[Key discoveries]
-
-### Current Implementation
-
-[What exists]
-
-### Recommendations
-
-[What to improve]
-
-### Next Steps
-
-[Actionable items]
-```
-
-## Related Skills
-
-| After Research              | Use Skill             |
-| --------------------------- | --------------------- |
-| Need implementation         | `mockup-to-code`      |
-| Need aesthetic improvements | `frontend-design`     |
-| Need accessibility fixes    | `accessibility-audit` |
+> This skill has been merged into `design-system-audit` which now covers UI pattern analysis, design token auditing, and visual comparison.
+> 
+> Load `design-system-audit` instead.

package/dist/template/.opencode/skill/verification-before-completion/SKILL.md

@@ -132,6 +132,42 @@ Skip any step = lying, not verifying
 ❌ Trust agent report
 ```
 
+## Smart Verification
+
+The Iron Law demands evidence, but evidence should be gathered efficiently.
+
+### Incremental by Default
+
+Unless shipping or `--full` is passed, verify only what changed:
+
+- **Lint**: `oxlint <changed-files>` instead of linting the entire codebase
+- **Test**: `vitest run --changed` instead of running all tests
+- **Typecheck**: always full (type errors propagate across files)
+
+See the [Verification Protocol](./references/VERIFICATION_PROTOCOL.md) for exact commands.
+
+### Parallel Execution
+
+Run independent gates simultaneously to reduce wall-clock time:
+
+```
+Parallel: typecheck + lint → both must pass
+Sequential: test → build (ship only)
+```
+
+Total time = max(typecheck, lint) + test, not typecheck + lint + test.
+
+### Verification Cache
+
+If you just verified and nothing changed, don't re-verify:
+
+1. After gates pass, record a stamp in `.beads/verify.log`
+2. Before running gates, compare current state to last stamp
+3. If match → report cached PASS, skip redundant work
+4. Cache is always bypassed for `--full` and ship/release
+
+This matters when other commands need verification (e.g., closing beads, `/ship`). If you verified 30 seconds ago and made no changes, the cache lets you skip.
+
 ## Why This Matters
 
 From 24 failure memories:

package/dist/template/.opencode/skill/verification-before-completion/references/VERIFICATION_PROTOCOL.md

@@ -1,21 +1,69 @@
 # Verification Protocol
 
+## Default: Incremental Mode
+
+**Incremental is the default.** Only switch to full mode when:
+
+- `--full` flag is explicitly passed
+- Shipping/releasing (pre-merge, CI pipeline)
+- More than 20 files changed
+
+### Changed Files Detection
+
+```bash
+# Get changed files (uncommitted + staged + untracked)
+CHANGED=$({
+  git diff --name-only --diff-filter=d HEAD -- '*.ts' '*.tsx' '*.js' '*.jsx'
+  git ls-files --others --exclude-standard -- '*.ts' '*.tsx' '*.js' '*.jsx'
+} | sort -u)
+
+# If in a bead worktree, diff against the branch point:
+# CHANGED=$({
+#   git diff --name-only --diff-filter=d main...HEAD -- '*.ts' '*.tsx' '*.js' '*.jsx'
+#   git ls-files --others --exclude-standard -- '*.ts' '*.tsx' '*.js' '*.jsx'
+# } | sort -u)
+
+# Count for mode decision
+FILE_COUNT=$(echo "$CHANGED" | grep -c .)
+# > 20 files → switch to full mode automatically
+```
+
 ## Standard Gates
 
-Run these gates in parallel where possible:
+### Gate Execution Order
+
+```
+┌─────────────────────────────────────┐
+│  Parallel (run simultaneously)      │
+│  ┌─────────────┐ ┌───────────────┐  │
+│  │  Typecheck   │ │  Lint         │  │
+│  │  (always     │ │  (changed     │  │
+│  │   full)      │ │   files only) │  │
+│  └──────┬──────┘ └──────┬────────┘  │
+│         └───────┬───────┘           │
+│            both must pass           │
+├─────────────────────────────────────┤
+│  Sequential (after parallel passes) │
+│  ┌─────────────┐ ┌───────────────┐  │
+│  │  Test        │ │  Build        │  │
+│  │  (--changed  │ │  (ship/release│  │
+│  │   or full)   │ │   only)       │  │
+│  └─────────────┘ └───────────────┘  │
+└─────────────────────────────────────┘
+```
 
 ### Parallel Group (independent — run simultaneously)
 
 ```bash
-# Gate 1: Typecheck
+# Gate 1: Typecheck (always full — type errors propagate across files)
 npm run typecheck 2>&1 &
 PID_TC=$!
 
-# Gate 2: Lint (incremental when possible)
-# Full codebase:
-npm run lint 2>&1 &
-# Or incremental (changed files only):
-# npx oxlint $(git diff --name-only --diff-filter=d HEAD | grep -E '\.(ts|tsx|js|jsx)$')
+# Gate 2: Lint
+# Incremental (default): lint only changed files
+npx oxlint $CHANGED 2>&1 &
+# Full mode: lint everything
+# npm run lint 2>&1 &
 PID_LINT=$!
 
 wait $PID_TC $PID_LINT
@@ -24,44 +72,100 @@ wait $PID_TC $PID_LINT
 ### Sequential Group (depends on parallel group passing)
 
 ```bash
-# Gate 3: Tests (incremental when possible)
-# Full: npm test
-# Incremental: npx vitest --changed
-npm test
+# Gate 3: Tests
+# Incremental (default): only tests affected by changed files
+npx vitest run --changed
+# Full mode: run all tests
+# npm test
+
+# Gate 4: Build (only if shipping/releasing)
+# npm run build
+```
+
+### Gate Commands Summary
+
+| Gate      | Incremental (default)        | Full (`--full`)     | When              |
+| --------- | ---------------------------- | ------------------- | ----------------- |
+| Typecheck | `npm run typecheck`          | `npm run typecheck` | Always (parallel) |
+| Lint      | `npx oxlint <changed-files>` | `npm run lint`      | Always (parallel) |
+| Test      | `npx vitest run --changed`   | `npm test`          | Always            |
+| Build     | Skip                         | `npm run build`     | Ship/release only |
+
+## Verification Cache
+
+Avoid redundant verification when nothing changed since the last successful run.
+
+### Cache Protocol
+
+After all gates pass, record a verification stamp:
+
+```bash
+# Compute fingerprint: commit hash + full diff content + untracked files
+# This ensures the stamp changes on ANY code change (commit, edit, or new file)
+STAMP=$(printf '%s\n%s\n%s' \
+  "$(git rev-parse HEAD)" \
+  "$(git diff HEAD -- '*.ts' '*.tsx' '*.js' '*.jsx')" \
+  "$(git ls-files --others --exclude-standard -- '*.ts' '*.tsx' '*.js' '*.jsx' | xargs cat 2>/dev/null)" \
+  | shasum -a 256 | cut -d' ' -f1)
+
+echo "$STAMP $(date -u +%Y-%m-%dT%H:%M:%SZ) PASS" >> .beads/verify.log
+```
+
+### Skip Check (before running gates)
 
-# Gate 4: Build (only if shipping)
-npm run build
+```bash
+# Read last verification stamp
+LAST_STAMP=$(tail -1 .beads/verify.log 2>/dev/null | awk '{print $1}')
+
+# Recompute current fingerprint (same formula as recording)
+CURRENT_STAMP=$(printf '%s\n%s\n%s' \
+  "$(git rev-parse HEAD)" \
+  "$(git diff HEAD -- '*.ts' '*.tsx' '*.js' '*.jsx')" \
+  "$(git ls-files --others --exclude-standard -- '*.ts' '*.tsx' '*.js' '*.jsx' | xargs cat 2>/dev/null)" \
+  | shasum -a 256 | cut -d' ' -f1)
+
+if [ "$LAST_STAMP" = "$CURRENT_STAMP" ]; then
+  echo "Verification cached: no changes since last PASS"
+  # Skip gates — report cached result
+else
+  # Run gates normally
+fi
 ```
 
-## Incremental Mode
+### When Cache is Invalidated
+
+- Any file edited, staged, or committed since last verification
+- `--full` flag always bypasses cache
+- Manual `--no-cache` flag bypasses cache
+- Different bead context (bead ID changed)
 
-Use incremental mode when:
+### Agent Behavior
 
-- Only a few files changed (< 20 files)
-- Not shipping/releasing (pre-commit, mid-development)
+When another command needs verification (e.g., closing a bead, `/ship`):
 
-| Gate      | Full Command        | Incremental Command                        |
-| --------- | ------------------- | ------------------------------------------ |
-| Typecheck | `npm run typecheck` | `npm run typecheck` (always full — needed) |
-| Lint      | `npm run lint`      | `npx oxlint $(git diff --name-only HEAD)`  |
-| Test      | `npm test`          | `npx vitest --changed`                     |
-| Build     | `npm run build`     | Skip (only needed for ship/release)        |
+1. **Check cache first** — if clean, report `"Verification: cached PASS (no changes since <timestamp>)"`
+2. **If cache miss** — run incremental gates normally
+3. **Always record** — append to `verify.log` after successful run
+4. **Never skip on ship/release** — always run full mode regardless of cache
 
 ## Gate Results Format
 
 Report results as:
 
 ```text
-| Gate      | Status | Time   |
-|-----------|--------|--------|
-| Typecheck | PASS   | 2.1s   |
-| Lint      | PASS   | 0.8s   |
-| Test      | PASS   | 5.3s   |
-| Build     | SKIP   | —      |
+| Gate      | Status | Mode        | Time   |
+|-----------|--------|-------------|--------|
+| Typecheck | PASS   | full        | 2.1s   |
+| Lint      | PASS   | incremental | 0.3s   |
+| Test      | PASS   | incremental | 1.2s   |
+| Build     | SKIP   | —           | —      |
 ```
 
+Include the mode column so it's clear whether incremental or full was used.
+
 ## Failure Handling
 
 - If any gate fails, stop and fix before proceeding
 - Show the FULL error output for failed gates
 - After fixing, re-run ONLY the failed gate(s) + any downstream gates
+- Cache is NOT written on failure — next run will execute gates normally

package/dist/template/.opencode/skill/visual-analysis/SKILL.md

@@ -8,6 +8,8 @@ dependencies: []
 
 # Visual Analysis Skill
 
+> **Replaces** guessing at visual properties from code alone — direct inspection of rendered output for colors, layout, spacing, and typography
+
 ## When to Use
 
 - Analyzing UI mockups or screenshots
@@ -19,6 +21,12 @@ dependencies: []
 
 - Pure text/code review without any visual assets.
 
+## Workflow
+
+1. **Capture** — Get the image (screenshot, mockup, or user-provided)
+2. **Analyze** — Use vision agent to extract specific properties (colors as hex, font sizes, spacing in px/rem)
+3. **Compare** — Cross-reference extracted values against design tokens and existing CSS
+4. **Report** — List discrepancies with specific values and file locations
 
 ## Quick Mode
 
@@ -131,11 +139,16 @@ Output CSS/Tailwind structure.
 
 Save findings to `.opencode/memory/design/analysis/`
 
-## Related Skills
+## Anti-Patterns
+
+| Anti-Pattern                                                                   | Why It Fails                                                                 | Instead                                                                     |
+| ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| Describing layout vaguely ("looks good") instead of extracting specific values | Feedback is non-actionable and hard to validate                              | Report measurable values (hex, px/rem, font size/weight) with locations     |
+| Not comparing against existing design tokens                                   | Findings drift from system standards and create inconsistent recommendations | Map extracted values to tokens first, then flag true mismatches             |
+| Analyzing low-resolution screenshots (artifacts mislead analysis)              | Compression/noise causes false readings for spacing and color                | Request higher-resolution captures or zoomed crops before final conclusions |
+
+## See Also
 
-| Need                        | Skill                 |
-| --------------------------- | --------------------- |
-| Found accessibility issues  | `accessibility-audit` |
-| Need to implement design    | `mockup-to-code`      |
-| Want design tokens          | `design-system-audit` |
-| Need aesthetic improvements | `frontend-design`     |
+- `mockup-to-code`
+- `design-system-audit`
+- `accessibility-audit`

package/dist/template/.opencode/skill/writing-plans/SKILL.md

@@ -8,6 +8,7 @@ dependencies: []
 
 # Writing Plans
 
+> **Replaces** vague implementation plans that assume the engineer knows the codebase — produces zero-ambiguity plans with exact file paths and complete code examples
 ## When to Use
 
 - Design/PRD is complete and you need a detailed, step-by-step implementation plan
@@ -311,3 +312,9 @@ After saving the plan, offer execution choice:
 - **REQUIRED SUB-SKILL:** New session uses skill({ name: "executing-plans" })
 ```
 ````
+
+## See Also
+
+- `executing-plans` - Execute vetted plans in controlled batches with checkpoints
+- `prd` - Convert validated design into explicit behavioral requirements
+- `brainstorming` - Refine rough ideas and constraints before specification/planning

package/dist/template/.opencode/tool/context7.ts

@@ -22,7 +22,15 @@ interface SearchResponse {
  * Operations: resolve (find library ID), query (get docs)
  */
 export default tool({
-	description: `Context7 documentation lookup: resolve library IDs and query docs.
+	description: `Context7 documentation lookup: resolve library IDs and query docs. Replaces manual doc searching and outdated API guessing — use this for all library documentation needs.
+
+WHEN: Looking up library APIs, checking function signatures, finding usage examples.
+SKIP: Searching your own codebase (use grep/LSP), general web research (use websearch).
+
+Common mistakes:
+- DON'T search for internal project code (use grep/tilth instead)
+- DON'T guess library versions — always resolve first, then query
+- DON'T use for general web research (use websearch instead)
 
 Operations:
 - "resolve": Find library ID from name (e.g., "react" → "/reactjs/react.dev")

package/dist/template/.opencode/tool/grepsearch.ts

@@ -15,7 +15,15 @@ interface GrepResponse {
 }
 
 export default tool({
-	description: `Search real-world code examples from GitHub repositories via grep.app.
+	description: `Search real-world code examples from GitHub repositories via grep.app. Replaces asking "how do others use X?" — use this for finding production patterns and real-world API usage.
+
+WHEN: Implementing unfamiliar APIs, looking for production patterns, understanding library integrations.
+SKIP: Searching your own codebase (use grep/tilth), looking up docs (use context7), general research (use websearch).
+
+Common mistakes:
+- DON'T search for keywords like "react tutorial" — search for literal code: "useState("
+- DON'T use without language filter when searching common patterns
+- DON'T ignore the repo filter when you know which project to search
 
 Use when:
 - Implementing unfamiliar APIs - see how others use a library

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencodekit",
-	"version": "0.18.4",
+	"version": "0.18.5",
 	"description": "CLI tool for bootstrapping and managing OpenCodeKit projects",
 	"keywords": [
 		"agents",