opencodekit 0.20.7 → 0.20.8

package/dist/template/.opencode/skill/tilth-cli/SKILL.md

@@ -1,207 +0,0 @@
----
-name: tilth-cli
-description: AST-aware code navigation via tilth CLI. Use when subagents need structural code search, smart file reading, or codebase mapping — complements MCP tilth (which only the main agent can access).
-version: 2.0.0
-tags: [code-navigation, search, subagent]
-dependencies: []
----
-
-# tilth CLI for Subagents
-
-> **Why this exists:** tilth MCP tools (`tilth_tilth_search`, `tilth_tilth_read`, etc.) are only available to the main agent. Subagents cannot access MCP tools but CAN use Bash. This skill teaches subagents to call tilth directly from the command line.
-
-## When to Use
-
-- When subagents need structural code search (they cannot access tilth MCP tools)
-- When you need `--map` for codebase skeleton (CLI-only feature, not in MCP)
-- For any agent that has Bash access but not tilth MCP
-
-## When NOT to Use
-
-- Main agent should prefer tilth MCP tools — they have session dedup and hash-anchored editing
-- For trivial lookups where grep/read suffices
-
-## Prerequisites
-
-tilth must be available. Use `npx -y tilth` if not globally installed:
-
-```bash
-npx -y tilth <query> [options]
-```
-
-## How tilth CLI Works
-
-tilth has **one command** with **smart auto-detection**. Pass a query and it figures out what to do:
-
-| Query Pattern | Detection                        | Action                                                  |
-| ------------- | -------------------------------- | ------------------------------------------------------- |
-| `src/auth.ts` | File path (exists on disk)       | **Read file** — smart outline for large, full for small |
-| `handleAuth`  | Symbol name (camelCase, etc.)    | **Symbol search** — AST definitions + usages            |
-| `"*.test.ts"` | Glob pattern (contains `*`, `?`) | **File listing** — matched paths with token estimates   |
-| `"TODO fix"`  | Text (doesn't match above)       | **Text search** — literal content matches               |
-
-## Core Operations
-
-### 1. Read a File
-
-```bash
-npx -y tilth src/index.ts                      # Smart view (outline if large, full if small)
-npx -y tilth src/index.ts --full                # Force full content
-npx -y tilth src/index.ts --section 45-89       # Exact line range
-npx -y tilth src/index.ts --section "## Config" # By heading
-```
-
-Output: numbered lines (`N  content`). Large files get a structural outline; use `--section` to drill into specific ranges.
-
-### 2. Search for Symbols
-
-```bash
-npx -y tilth initCommand --scope src/           # Find definition + all usages
-npx -y tilth handleAuth --scope src/auth/       # Scoped to subdirectory
-npx -y tilth "sym1,sym2" --scope src/            # Multi-symbol search (max 5)
-```
-
-Returns: definitions first (with expanded source), then usages with context lines.
-
-### 3. Search for Text / Regex
-
-```bash
-npx -y tilth "TODO" --scope src/                # Literal text search
-npx -y tilth "version" --scope src/             # Finds all occurrences
-npx -y tilth --kind content "config" --scope src/  # Explicit content search
-npx -y tilth --kind regex "/TODO.*fix/" --scope src/  # Regex search
-```
-
-tilth auto-detects text vs symbol. Identifiers (camelCase, snake_case) → symbol search. Multi-word or quoted strings → text search. Use `--kind` to force a specific search mode.
-
-### 4. Find Callers
-
-```bash
-npx -y tilth --kind callers initCommand --scope src/  # Find all call sites
-```
-
-Uses SIMD-accelerated pre-filtering + tree-sitter AST parsing. More accurate than text grep for finding actual function calls vs. comments/strings.
-
-### 5. List Files (Glob)
-
-```bash
-npx -y tilth "*.test.ts" --scope src/           # List test files
-npx -y tilth "*.ts" --scope src/commands/       # List TS files in subdir
-```
-
-Returns: matched file paths with token size estimates.
-
-### 6. Blast-Radius Analysis (Deps)
-
-```bash
-npx -y tilth --deps src/utils/errors.ts         # What imports this file + what it imports
-npx -y tilth --deps src/commands/init.ts --scope src/  # Scoped dependency check
-```
-
-Shows imports (local + external) AND what other files call its exports, with symbol-level detail. Use before renaming/removing exports.
-
-### 7. Codebase Map (CLI-Only)
-
-```bash
-npx -y tilth --map --scope src/                 # Structural skeleton
-npx -y tilth --map --scope .                    # Whole project
-```
-
-Returns: directory tree with exported symbols per file. **CLI-only** — deliberately excluded from MCP (agents overuse it).
-
-## Available Flags
-
-| Flag                | Purpose                                  | Example                     |
-| ------------------- | ---------------------------------------- | --------------------------- |
-| `--scope <DIR>`     | Restrict search to directory             | `--scope src/`              |
-| `--section <RANGE>` | Line range or heading for file reads     | `--section 45-89`           |
-| `--full`            | Force full file content (skip outline)   | `--full`                    |
-| `--budget <N>`      | Max tokens in response                   | `--budget 2000`             |
-| `--json`            | Machine-readable JSON output             | `--json`                    |
-| `--map`             | Generate codebase structure map          | `--map --scope src/`        |
-| `--kind <TYPE>`     | Force search type: symbol/content/regex/callers | `--kind callers`     |
-| `--deps`            | Show blast-radius (imports + dependents) | `--deps src/file.ts`        |
-| `--expand <N>`      | Top N matches to show full source        | `--expand 3`                |
-
-## MCP vs CLI Comparison
-
-| Feature                               | MCP (main agent) | CLI (all agents)    |
-| ------------------------------------- | ---------------- | ------------------- |
-| Session dedup (`[shown earlier]`)     | Yes              | No                  |
-| Hash-anchored editing (`tilth_edit`)  | Yes              | No                  |
-| Blast-radius analysis (`--deps`)      | Yes              | Yes (v0.5.7+)       |
-| Multi-symbol search (`sym1,sym2`)     | Yes              | Yes (v0.5.7+)       |
-| `--kind` flag (content/regex/callers) | Yes              | Yes (v0.5.7+)       |
-| `--expand` control                    | Yes              | Yes (v0.5.7+)       |
-| `--map` codebase skeleton             | No               | Yes                 |
-| Subagent access                       | No (main only)   | Yes (any with Bash) |
-| Process overhead                      | Once (~17ms)     | Per call (~17ms)    |
-
-## Output Format Examples
-
-### File read (small file)
-
-```
-# src/config.ts (45 lines, ~380 tokens) [full]
-
-1  import { z } from 'zod';
-2  export const schema = z.object({
-...
-```
-
-### Symbol search
-
-```
-# Search: "initCommand" in src/ — 6 matches (2 definitions, 4 usages)
-
-### Definitions (2)
-## commands/init.ts:515-961 [definition]
-→ [515-961]  export async function initCommand(...)
-
-### Usages — same package (4)
-## index.ts:10 [usage]
-→ [10]   import { initCommand } from "./commands/init.js";
-```
-
-### Codebase map
-
-```
-# Map: src/ (depth 3)
-index.ts (~1214 tokens)
-commands/
-  init.ts: initCommand, detectMode, ...
-  upgrade.ts: checkVersion, upgradeCommand, ...
-utils/
-  errors.ts: resolveOpencodePath, showError, ...
-```
-
-## Usage Tips
-
-- **Search first, read second** — symbol search finds definitions AND shows expanded source
-- **Use `--section` for large files** — outline tells you line ranges; drill in with `--section 44-89`
-- **Use `--scope`** to narrow searches — avoids scanning irrelevant directories
-- **Use `--budget`** when you need concise output (limits token count)
-- **~17ms per call** — fast enough for interactive use, but avoid unnecessary repeated calls
-- **Use `--kind callers`** for precise call-site analysis instead of text grep
-- **Use `--deps`** before renaming or removing exports to check blast radius
-
-## Example Subagent Dispatch
-
-```typescript
-task({
-  subagent_type: "general",
-  prompt: `Use tilth CLI for code navigation (run via: npx -y tilth).
-
-Find the definition of \`initCommand\` and understand how it's called:
-  npx -y tilth initCommand --scope src/
-  npx -y tilth --kind callers initCommand --scope src/
-
-Check blast radius before editing:
-  npx -y tilth --deps src/commands/init.ts
-
-Then read the relevant file section:
-  npx -y tilth src/commands/init.ts --section 515-600
-
-[rest of task instructions]`,
-});
-```

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

@@ -1,299 +0,0 @@
----
-name: tool-priority
-description: Use when choosing between tools or need tool reference - covers LSP, search, swarm, memory, and research tools with correct syntax
-version: 1.0.0
-tags: [workflow, context]
-dependencies: []
----
-
-# Tool Priority Skill
-
-## When to Use
-
-- You need to decide which tool to use for a task or recall tool syntax
-- You are about to edit code and want the correct discovery/order of operations
-
-## When NOT to Use
-
-- You already know the exact tool and syntax required
-- The task is purely conceptual with no tool usage
-
-## Priority Order
-
-**LSP → Search → Swarm → Memory → File Operations**
-
-1. **LSP** - Semantic code intelligence (9 operations via unified tool)
-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.
-
-## Choosing the Right Tool
-
-Ask: **"Am I looking for semantic understanding or just text?"**
-
-### Code Understanding (Use LSP)
-
-The `lsp` tool provides 9 operations via a unified interface:
-
-| Need                 | Operation              | Example                                                                                                       |
-| -------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------- |
-| Type info at cursor  | `hover`                | `lsp({ operation: "hover", filePath: "src/file.ts", line: 42, character: 10 })`                               |
-| Jump to definition   | `goToDefinition`       | `lsp({ operation: "goToDefinition", filePath: "src/file.ts", line: 42, character: 10 })`                      |
-| Find all usages      | `findReferences`       | `lsp({ operation: "findReferences", filePath: "src/file.ts", line: 42, character: 10 })`                      |
-| File structure       | `documentSymbol`       | `lsp({ operation: "documentSymbol", filePath: "src/file.ts", line: 1, character: 1 })`                        |
-| Workspace search     | `workspaceSymbol`      | `lsp({ operation: "workspaceSymbol", filePath: "src/file.ts", line: 1, character: 1, query: "UserService" })` |
-| Find implementations | `goToImplementation`   | `lsp({ operation: "goToImplementation", filePath: "src/file.ts", line: 42, character: 10 })`                  |
-| Call hierarchy       | `prepareCallHierarchy` | `lsp({ operation: "prepareCallHierarchy", filePath: "src/file.ts", line: 42, character: 10 })`                |
-| Incoming calls       | `incomingCalls`        | `lsp({ operation: "incomingCalls", filePath: "src/file.ts", line: 42, character: 10 })`                       |
-| Outgoing calls       | `outgoingCalls`        | `lsp({ operation: "outgoingCalls", filePath: "src/file.ts", line: 42, character: 10 })`                       |
-
-**Critical**: Run ALL 9 LSP operations before editing. See AGENTS.md for the full checklist.
-
-### Text Search (Use grep)
-
-| Need              | Pattern          | Example                                    |
-| ----------------- | ---------------- | ------------------------------------------ |
-| Function calls    | `functionName\(` | `grep({ pattern: "fetchUser\(" })`         |
-| Import statements | `import.*from`   | `grep({ pattern: "import.*from.*react" })` |
-| Error messages    | `FATAL\|ERROR`   | `grep({ pattern: "ERROR\|FATAL" })`        |
-| TODO comments     | `TODO\|FIXME`    | `grep({ pattern: "TODO\|FIXME" })`         |
-| Hook usage        | `useState\(`     | `grep({ pattern: "useState\(" })`          |
-| Debug logs        | `console\.log`   | `grep({ pattern: "console\.log" })`        |
-
-### Load Skills (Use skill tool)
-
-Load specialized knowledge before starting work:
-
-```typescript
-// Essential skills for most work
-skill({ name: "verification-before-completion" });
-skill({ name: "test-driven-development" });
-
-// Domain-specific skills
-skill({ name: "beads" }); // Task tracking
-skill({ name: "beads-bridge" }); // Swarm coordination
-skill({ name: "swarm-coordination" }); // Parallel execution
-skill({ name: "frontend-design" }); // UI implementation
-skill({ name: "prd" }); // Requirements documents
-```
-
-### Parallel Execution (Use Task tool)
-
-Launch multiple subagents simultaneously:
-
-```typescript
-// Workers run in parallel when multiple Task calls in one message
-Task({
-  subagent_type: "explore",
-  description: "Find patterns",
-  prompt: `Find auth patterns in codebase...`,
-});
-
-Task({
-  subagent_type: "scout",
-  description: "Research docs",
-  prompt: `Research best practices for...`,
-});
-// Results return when both complete
-```
-
-**Subagent types**: `general`, `explore`, `scout`, `review`, `plan`
-
-### Swarm Coordination Tools
-
-| Tool      | Purpose                    | Key Operations                        |
-| --------- | -------------------------- | ------------------------------------- |
-| **swarm** | Unified swarm coordination | `plan`, `monitor`, `delegate`, `sync` |
-
-**swarm operations:**
-
-- `plan`: Task analysis (actions: analyze, classify, check, allocate)
-- `monitor`: Progress tracking (actions: progress_update, render_block, status, clear)
-- `delegate`: Create delegation packets for workers
-- `sync`: Beads ↔ OpenCode sync (actions: push, pull, create_shared, update_shared)
-
-### Memory Tools
-
-| Tool              | Purpose                   | When to Use                         |
-| ----------------- | ------------------------- | ----------------------------------- |
-| **memory-search** | Find past learnings       | "Have we solved this before?"       |
-| **memory-read**   | Load specific memory file | "What did we decide about X?"       |
-| **memory-update** | Save context              | "Document this for future sessions" |
-| **observation**   | Record decisions/patterns | "This is worth remembering"         |
-
-### Research Tools
-
-| 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
-// Step 1: Load skills
-skill({ name: "verification-before-completion" });
-skill({ name: "beads" });
-
-// Step 2: Find it (text search)
-grep({ pattern: "functionName", path: "src/" });
-
-// Step 3: Understand it (LSP - ALL 9 operations)
-lsp({ operation: "documentSymbol", filePath: "src/file.ts", line: 1, character: 1 });
-lsp({ operation: "goToDefinition", filePath: "src/file.ts", line: 42, character: 10 });
-lsp({ operation: "findReferences", filePath: "src/file.ts", line: 42, character: 10 });
-lsp({ operation: "hover", filePath: "src/file.ts", line: 42, character: 10 });
-// ... remaining 5 operations
-
-// Step 4: Check memory
-memory_search({ query: "auth patterns" });
-
-// Step 5: Read before edit
-read({ filePath: "/absolute/path/to/file.ts" });
-
-// Step 6: Modify
-edit({ filePath: "/absolute/path/to/file.ts", oldString: "...", newString: "..." });
-
-// Step 7: Verify
-bash({ command: "npm run typecheck && npm run lint" });
-```
-
-## Tool Comparison
-
-### grep vs LSP
-
-| Scenario           | Use                         | Why                                         |
-| ------------------ | --------------------------- | ------------------------------------------- |
-| "Find all X"       | `grep`                      | Fast text search, includes comments/strings |
-| "Where is X used?" | `lsp` with `findReferences` | Semantic, tracks actual code dependencies   |
-| "What type is X?"  | `lsp` with `hover`          | Type system intelligence                    |
-| "Find TODOs"       | `grep`                      | Text search across all files                |
-
-### When to Use What
-
-**Start with LSP when:**
-
-- Understanding code structure
-- Before any edit (ALL 9 operations)
-- Tracing dependencies
-- Getting type information
-
-**Start with grep when:**
-
-- Quick exploration ("are there any X?")
-- Finding error patterns, logs, configs
-- Searching across file types (JSON, YAML, etc.)
-
-**Use skill when:**
-
-- Starting any significant work
-- Need specialized knowledge
-- Following established patterns
-
-**Use Task when:**
-
-- Multiple independent research questions
-- Parallel implementation tasks
-- 3+ files need simultaneous work
-
-## Common Mistakes
-
-❌ **Wrong**: Edit without LSP
-
-```typescript
-// DON'T: Edit without understanding structure
-edit({ filePath: "src/file.ts", oldString: "...", newString: "..." });
-```
-
-✅ **Right**: LSP before edit
-
-```typescript
-// DO: Run all 9 LSP operations first
-lsp({ operation: "documentSymbol", filePath: "src/file.ts", line: 1, character: 1 });
-lsp({ operation: "goToDefinition", filePath: "src/file.ts", line: 10, character: 5 });
-// ... 7 more operations
-read({ filePath: "src/file.ts" });
-edit({ filePath: "src/file.ts", oldString: "...", newString: "..." });
-```
-
-❌ **Wrong**: Old LSP syntax
-
-```typescript
-// DON'T: This syntax doesn't exist
-lsp_lsp_hover((filePath = "src/file.ts"), (line = 42), (character = 10));
-```
-
-✅ **Right**: Correct LSP syntax
-
-```typescript
-// DO: Use operation parameter
-lsp({ operation: "hover", filePath: "src/file.ts", line: 42, character: 10 });
-```
-
-## Quick Reference
-
-```
-BEFORE EDITING:
-  lsp({ operation: "documentSymbol", ... })     → File structure
-  lsp({ operation: "goToDefinition", ... })     → Where defined
-  lsp({ operation: "findReferences", ... })     → All usages
-  lsp({ operation: "hover", ... })              → Type info
-  lsp({ operation: "goToImplementation", ... }) → Implementations
-  lsp({ operation: "prepareCallHierarchy", ... }) → Call hierarchy
-  lsp({ operation: "incomingCalls", ... })      → What calls this
-  lsp({ operation: "outgoingCalls", ... })      → What this calls
-  lsp({ operation: "workspaceSymbol", ... })    → Workspace search
-
-SEARCHING:
-  grep({ pattern: "...", path: "src/" })        → Text search
-  glob({ pattern: "**/*.ts" })                  → File discovery
-
-PARALLEL WORK:
-  Task({ subagent_type: "explore", ... })       → Parallel subagent
-  swarm({ operation: "sync", action: "push" }) → Sync to todos
-  swarm({ operation: "monitor", action: "progress_update" }) → Track progress
-
-RESEARCH:
-  context7({ operation: "resolve", libraryName: "..." })
-  context7({ operation: "query", libraryId: "...", topic: "..." })
-  websearch({ query: "..." })
-  Task({ subagent_type: "review", description: "Second opinion", prompt: "Review the approach." })
-
-MEMORY:
-  memory_search({ query: "..." })               → Find past learnings
-  observation({ type: "learning", ... })        → Record for future
-```