opencodekit 0.20.7 → 0.20.8

package/dist/template/.opencode/skill/code-search-patterns/SKILL.md

@@ -0,0 +1,253 @@
+---
+name: code-search-patterns
+description: Use when navigating unfamiliar code with search-first patterns, combining built-in/LSP navigation with tilth MCP (main agent) and tilth CLI (subagents)
+version: 1.0.0
+tags: [workflow, code-quality, context, subagent]
+dependencies: []
+---
+
+# Code Search Patterns
+
+Unified navigation skill for fast, low-waste code understanding across both execution modes:
+
+- **Main agent**: built-in tools + LSP + tilth MCP
+- **Subagents**: Bash + `npx -y tilth` CLI
+
+This skill merges practical navigation heuristics with concrete tool usage so you can locate behavior, trace impact, and edit safely with fewer calls.
+
+## When to Use
+
+- Exploring unfamiliar modules before editing
+- Tracing call chains across files and directories
+- Checking blast radius before signature/export changes
+- Dispatching subagents that need structural code navigation
+- Reducing token/tool-call waste during implementation
+
+## When NOT to Use
+
+- Trivial single-file edits where symbol location is already known
+- Pure docs/config reads with no dependency tracing
+- Tasks focused on external web research (use web research tools instead)
+
+## Core Principle
+
+> Collapse multiple tool calls into fewer, smarter ones. Every unnecessary read or search wastes tokens and turns.
+
+## Navigation Patterns
+
+### 1) Search First, Read Second
+
+Start with symbol/content search to find exact locations, then read only the needed slice.
+
+- **Good**: `search -> targeted read`
+- **Avoid**: `read many files -> search later`
+
+Use LSP (`findReferences`, `outgoingCalls`) or tilth search first; read deep only after narrowing scope.
+
+### 2) Multi-Symbol Search
+
+When flow spans multiple functions, query them together (`A,B,C`) instead of serial one-by-one lookups.
+
+- Faster call-chain reconstruction
+- Fewer repeated scans of the same files
+
+### 3) Don’t Re-Read What Search Already Returned
+
+If search output already includes definition body/context, proceed from it.
+Re-read only when you need:
+
+- exact edit anchors,
+- additional surrounding lines,
+- or untruncated content.
+
+### 4) Blast Radius Check (Before Breaking Changes)
+
+Before renaming/removing/changing signatures, inspect downstream impact first.
+
+- LSP: `findReferences`, `incomingCalls`
+- tilth: `tilth_tilth_deps` or `--deps`
+
+Then apply edits from dependents inward.
+
+### 5) Context Locality
+
+Prefer nearby package/module scope first.
+
+- built-in search: constrain `path`
+- tilth: pass `scope` / `context`
+
+Locality reduces irrelevant matches and token churn.
+
+### 6) Outline Before Deep Read
+
+For large files, inspect structure first (symbols/outline), then read only target sections.
+
+- LSP: `documentSymbol`
+- tilth read: smart outline by default, then section drill-in
+
+### 7) Follow Call Chain, Not File Tree
+
+Start at entry behavior and walk calls (`definition -> outgoing -> next definition`) instead of reading folders linearly.
+
+This exposes real execution flow with fewer reads.
+
+## tilth MCP (Main Agent)
+
+Use MCP variants when available in the main agent session:
+
+- `tilth_tilth_search`
+- `tilth_tilth_read`
+- `tilth_tilth_files`
+- `tilth_tilth_deps`
+
+### Built-in/LSP vs tilth MCP (when to choose which)
+
+| Need                    | Built-in / LSP                         | Prefer tilth MCP when                                       | Why tilth helps                     |
+| ----------------------- | -------------------------------------- | ----------------------------------------------------------- | ----------------------------------- |
+| Find symbols/usages     | `grep` / `lsp.findReferences`          | You want definitions + usages + expanded source in one call | Reduces search+read round trips     |
+| Read file content       | `read`                                 | File is large or you only need structure first              | Smart outline + section targeting   |
+| List candidate files    | `glob`                                 | You want quick glob results with token-aware relevance      | Faster triage for large directories |
+| Pre-change impact check | `lsp.incomingCalls` + manual follow-up | You need import + dependent view before breaking change     | Single blast-radius view via deps   |
+
+Guideline: if tilth MCP is active, use it as default for navigation; fall back to built-in/LSP when you need language-server-specific semantics or exact editor-position operations.
+
+## tilth CLI (Subagents)
+
+### Why this exists
+
+Subagents typically cannot call MCP tools directly. They can still use tilth through Bash:
+
+```bash
+npx -y tilth <query> [flags]
+```
+
+### Auto-detection
+
+| Query shape                       | Auto-detected action                 |
+| --------------------------------- | ------------------------------------ |
+| Existing file path (`src/foo.ts`) | Read file (smart outline/full)       |
+| Identifier (`initCommand`)        | Symbol search (definitions + usages) |
+| Glob (`*.test.ts`)                | List files                           |
+| Plain text / phrase               | Content search                       |
+
+Use `--kind` to force a specific mode when needed.
+
+### Core operations
+
+#### 1) Read file
+
+```bash
+npx -y tilth src/index.ts
+npx -y tilth src/index.ts --full
+npx -y tilth src/index.ts --section 45-89
+```
+
+#### 2) Search symbols
+
+```bash
+npx -y tilth initCommand --scope src/
+npx -y tilth "initCommand,detectMode" --scope src/
+```
+
+#### 3) Search text/regex
+
+```bash
+npx -y tilth --kind content "TODO" --scope src/
+npx -y tilth --kind regex "/TODO.*fix/" --scope src/
+```
+
+#### 4) Find callers
+
+```bash
+npx -y tilth --kind callers initCommand --scope src/
+```
+
+#### 5) List files
+
+```bash
+npx -y tilth "*.test.ts" --scope src/
+```
+
+#### 6) Blast radius / deps
+
+```bash
+npx -y tilth --deps src/commands/init.ts --scope src/
+```
+
+#### 7) Codebase map
+
+```bash
+npx -y tilth --map --scope src/
+```
+
+### Useful flags
+
+| Flag              | Purpose                        | Example                      |
+| ----------------- | ------------------------------ | ---------------------------- | ------------------- | ----------------- | ---------------- |
+| `--scope <dir>`   | Restrict scan area             | `--scope src/commands/`      |
+| `--section <range | heading>`                      | Targeted file slice          | `--section 120-180` |
+| `--full`          | Force full file output         | `--full`                     |
+| `--budget <n>`    | Limit output size              | `--budget 2000`              |
+| `--json`          | Machine-readable output        | `--json`                     |
+| `--map`           | Structural project skeleton    | `--map --scope src/`         |
+| `--kind <symbol   | content                        | regex                        | callers>`           | Force search mode | `--kind callers` |
+| `--deps <file>`   | Import/dependent blast radius  | `--deps src/utils/errors.ts` |
+| `--expand <n>`    | Expand top matches with source | `--expand 3`                 |
+
+### MCP vs CLI
+
+| Capability                   | MCP (main agent)                                   | CLI (subagents)                            |
+| ---------------------------- | -------------------------------------------------- | ------------------------------------------ |
+| Access mode                  | Tool call                                          | Bash command                               |
+| Session dedup/context carry  | Yes                                                | No                                         |
+| Hash-anchored edit flow      | Yes (via MCP edit tools)                           | No                                         |
+| Symbol/content/regex/callers | Yes                                                | Yes                                        |
+| Deps/blast-radius            | Yes                                                | Yes                                        |
+| Codebase map                 | Limited by toolset                                 | Yes (`--map`)                              |
+| Best for                     | Interactive main-agent navigation + edit workflows | Subagent discovery/exploration without MCP |
+
+### Example subagent dispatch
+
+```ts
+task({
+  subagent_type: "general",
+  prompt: `Use tilth CLI via Bash for navigation.
+
+1) Locate symbol and usages:
+npx -y tilth initCommand --scope src/
+
+2) Find callers:
+npx -y tilth --kind callers initCommand --scope src/
+
+3) Check blast radius before edits:
+npx -y tilth --deps src/commands/init.ts --scope src/
+
+4) Read only the relevant section:
+npx -y tilth src/commands/init.ts --section 500-620
+
+Then implement the requested change with minimal file edits.`,
+});
+```
+
+## Cost Awareness
+
+Navigation cost compounds quickly. Optimize for fewer, richer calls.
+
+- Prefer one structural search over multiple blind reads
+- Reuse search output; avoid duplicate reads of the same symbol body
+- Scope aggressively (`path`, `scope`) to cut noise
+- Use section reads for large files instead of full-file pulls
+
+Target heuristic: understand a symbol and its direct impact in **≤3 calls** whenever possible.
+
+## Common Mistakes
+
+| Mistake                                          | Better pattern                                                      |
+| ------------------------------------------------ | ------------------------------------------------------------------- |
+| Reading big files before locating symbol         | Search first, then section read                                     |
+| Re-reading code already shown in search output   | Work from returned snippet; re-read only if needed for edit anchors |
+| Serially tracing one function at a time          | Multi-symbol search + callers/deps                                  |
+| Ignoring blast radius before API/signature edits | Run references/incoming/deps first                                  |
+| Unscoped repository-wide search                  | Use `path`/`--scope` to localize                                    |
+| Using CLI defaults when mode is ambiguous        | Force with `--kind`                                                 |
+| Overusing `--full` on large files                | Outline first, then `--section`                                     |

package/dist/template/.opencode/skill/code-simplification/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: code-simplification
+description: Use when reducing code complexity, eliminating dead code, or refactoring for clarity — enforces measure-before-cutting discipline to prevent breaking changes disguised as cleanup
+version: 1.0.0
+tags: [code-quality, refactoring]
+dependencies: [verification-before-completion]
+---
+
+# Code Simplification
+
+> **Replaces** ad-hoc "cleanup" refactors that introduce bugs — enforces systematic simplification with verification at every step
+
+## When to Use
+
+- Code is harder to understand than it needs to be
+- Functions are too long (>50 lines), files are too large (>500 lines)
+- Dead code, unused imports, or unnecessary abstractions exist
+- You're asked to "clean up" or "simplify" a module
+- Complexity is making bugs harder to fix
+
+## When NOT to Use
+
+- The code works, is readable, and isn't blocking anything — leave it alone
+- You're implementing a new feature (use incremental-implementation instead)
+- The "simplification" is actually a rewrite with different behavior
+
+## Common Rationalizations
+
+| Rationalization                        | Rebuttal                                                                                 |
+| -------------------------------------- | ---------------------------------------------------------------------------------------- |
+| "This code is ugly, let me rewrite it" | Ugly but working > beautiful but broken. Simplify incrementally, not wholesale           |
+| "Nobody uses this, I'll delete it"     | Verify with grep/find-references FIRST. "Nobody uses this" is the #1 cause of breakage   |
+| "I'll simplify it while I'm in here"   | Mixing feature work with refactoring makes both harder to review and revert              |
+| "This abstraction isn't needed"        | Check if it serves a testing, extension, or boundary purpose before removing             |
+| "I can make this more elegant"         | Elegant for whom? Optimize for the next reader, not for cleverness                       |
+| "The tests will catch any issues"      | Tests cover known behavior. Simplification can change behavior in ways tests don't cover |
+
+## Overview
+
+Code simplification is the discipline of making code easier to understand and maintain WITHOUT changing its behavior. The key word is discipline — undisciplined simplification introduces bugs.
+
+**Core principle:** Measure complexity, simplify the worst offender, verify nothing broke, repeat.
+
+## The Process
+
+```
+1. MEASURE  — Identify what's actually complex (not just what feels complex)
+2. ISOLATE  — Pick ONE simplification target
+3. VERIFY   — Ensure tests exist for current behavior
+4. SIMPLIFY — Apply the smallest change that reduces complexity
+5. CONFIRM  — Run full verification to prove behavior is unchanged
+6. REPEAT   — Pick the next target
+```
+
+## Complexity Signals
+
+| Signal                | Threshold        | Action                                      |
+| --------------------- | ---------------- | ------------------------------------------- |
+| Function length       | >50 lines        | Extract helper functions                    |
+| File length           | >500 lines       | Split into modules                          |
+| Nesting depth         | >3 levels        | Flatten with early returns or extract       |
+| Parameter count       | >4 params        | Use an options object                       |
+| Cyclomatic complexity | >10 per function | Break into smaller functions                |
+| Dead code             | Any              | Remove after verifying with find-references |
+| Unused imports        | Any              | Remove (linter usually catches these)       |
+| Duplicate code        | 3+ copies        | Extract shared function                     |
+
+## Simplification Patterns
+
+### Extract Function
+
+```typescript
+// BEFORE: Long function with embedded logic
+function processOrder(order: Order) {
+  // 20 lines of validation
+  // 15 lines of pricing
+  // 10 lines of notification
+}
+
+// AFTER: Named steps
+function processOrder(order: Order) {
+  validateOrder(order);
+  const total = calculateTotal(order);
+  notifyCustomer(order, total);
+}
+```
+
+### Early Return (Flatten Nesting)
+
+```typescript
+// BEFORE: Deep nesting
+function getUser(id: string) {
+  if (id) {
+    const user = db.find(id);
+    if (user) {
+      if (user.active) {
+        return user;
+      }
+    }
+  }
+  return null;
+}
+
+// AFTER: Guard clauses
+function getUser(id: string) {
+  if (!id) return null;
+  const user = db.find(id);
+  if (!user) return null;
+  if (!user.active) return null;
+  return user;
+}
+```
+
+### Remove Dead Code
+
+```
+1. Search: grep/find-references for the symbol
+2. Verify: No callers exist (check tests too)
+3. Remove: Delete the code
+4. Confirm: All tests still pass
+```
+
+**NEVER assume code is dead without searching.** Check:
+
+- Direct calls
+- Dynamic references (string-based lookups, reflection)
+- Test-only usage
+- Configuration references
+
+### Inline Unnecessary Abstraction
+
+```typescript
+// BEFORE: Wrapper that adds nothing
+function getUserName(user: User): string {
+  return user.name;
+}
+
+// AFTER: Just use the property directly
+user.name;
+```
+
+Only inline if the abstraction doesn't serve a testing, boundary, or extension purpose.
+
+### Replace Conditional with Early Exit
+
+```typescript
+// BEFORE
+function handle(input: string) {
+  let result = "";
+  if (isValid(input)) {
+    result = transform(input);
+  } else {
+    throw new Error("Invalid");
+  }
+  return result;
+}
+
+// AFTER
+function handle(input: string) {
+  if (!isValid(input)) throw new Error("Invalid");
+  return transform(input);
+}
+```
+
+## What NOT to Simplify
+
+- **Working error handling** — even if verbose, it's there for a reason
+- **Compatibility shims** — they exist because something needs them
+- **Performance-critical paths** — "simpler" may mean "slower"
+- **Code with extensive test coverage pointing at specific behavior** — the tests document WHY it's complex
+- **Other people's current work** — don't simplify files with active PRs
+
+## Red Flags — STOP
+
+If you catch yourself:
+
+- Changing behavior while "simplifying"
+- Removing code without checking references first
+- Simplifying more than one thing per commit
+- "Cleaning up" files you weren't asked to touch
+- Making the code "more elegant" without a clear readability improvement
+
+**STOP.** Revert the current change and pick a smaller target.
+
+## Verification
+
+Before each simplification:
+
+```bash
+# Ensure tests exist for current behavior
+npm test -- --related [file]
+```
+
+After each simplification:
+
+```bash
+npm run typecheck
+npm run lint
+npm test
+```
+
+**If ANY test fails, the simplification changed behavior.** Either:
+
+1. The simplification is wrong — revert it
+2. The test is testing implementation details — fix the test, but document WHY
+
+## See Also
+
+- **incremental-implementation** — Build new features in slices; simplify afterward
+- **systematic-debugging** — When simplification reveals hidden bugs
+- **defense-in-depth** — When simplifying validation, ensure all layers still hold

package/dist/template/.opencode/skill/condition-based-waiting/SKILL.md

@@ -9,6 +9,7 @@ dependencies: []
 # Condition-Based Waiting
 
 > **Replaces** arbitrary `sleep()` / `setTimeout()` calls and hardcoded delays that cause flaky tests and slow CI
+
 ## When to Use
 
 - Tests are flaky due to arbitrary delays or timing guesses
@@ -19,6 +20,17 @@ dependencies: []
 - You are explicitly testing timing behavior (debounce, throttle, intervals)
 - A fixed, documented timeout is part of the requirement
 
+## Common Rationalizations
+
+| Rationalization                               | Rebuttal                                                                       |
+| --------------------------------------------- | ------------------------------------------------------------------------------ |
+| "50ms is plenty of time"                      | It's plenty on YOUR machine. CI runners under load disagree                    |
+| "The sleep worked in local testing"           | Local = fast SSD, idle CPU. CI = shared resources, variable latency            |
+| "Adding a waitFor is more complex than sleep" | A 5-line waitFor is simpler than debugging a flaky test 10 times               |
+| "This operation is always fast"               | "Always" until garbage collection, disk I/O, or network latency says otherwise |
+| "I'll increase the timeout if it flakes"      | Increasing timeouts slows the entire suite and masks the real problem          |
+| "It only fails sometimes"                     | "Sometimes" = race condition. Condition-based waiting eliminates it entirely   |
+
 ## Overview
 
 Flaky tests often guess at timing with arbitrary delays. This creates race conditions where tests pass on fast machines but fail under load or in CI.

package/dist/template/.opencode/skill/defense-in-depth/SKILL.md

@@ -20,14 +20,24 @@ dependencies: []
 - Simple, single-layer validation at an obvious entry point is enough
 - The issue is unrelated to invalid data or boundary checks
 
+## Common Rationalizations
+
+| Rationalization                                  | Rebuttal                                                                                                  |
+| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| "One validation at the entry point is enough"    | Different code paths, refactors, and mocks all bypass a single gate — each layer catches what others miss |
+| "This adds too much boilerplate"                 | Each validation is 2-3 lines. The bug it prevents costs hours of debugging                                |
+| "The caller already validates this"              | You don't control the caller. New callers won't know your assumptions                                     |
+| "Tests will catch it"                            | Tests run after the fact. Validation prevents the bug from existing                                       |
+| "This is an internal function, input is trusted" | Internal functions get called from new paths during refactors. Trust no input                             |
+
 ## Anti-Patterns
 
-| Anti-Pattern | Why It Fails | Instead |
-| --- | --- | --- |
-| Validating only at the entry point (trusting downstream) | Alternate paths and refactors bypass one gate | Add independent checks at each boundary |
-| Duplicating identical validation at every layer | Creates noise without improving safety | Tailor each layer to boundary-specific invariants |
-| Catching and swallowing errors silently | Hides failures and delays detection | Raise explicit errors with actionable context |
-| Mixing validation with business logic | Makes behavior hard to reason about and test | Keep validation checks explicit and separate from core logic |
+| Anti-Pattern                                             | Why It Fails                                  | Instead                                                      |
+| -------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------ |
+| Validating only at the entry point (trusting downstream) | Alternate paths and refactors bypass one gate | Add independent checks at each boundary                      |
+| Duplicating identical validation at every layer          | Creates noise without improving safety        | Tailor each layer to boundary-specific invariants            |
+| Catching and swallowing errors silently                  | Hides failures and delays detection           | Raise explicit errors with actionable context                |
+| Mixing validation with business logic                    | Makes behavior hard to reason about and test  | Keep validation checks explicit and separate from core logic |
 
 ## Overview