opencodekit 0.21.9 → 0.22.0

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

@@ -1,253 +0,0 @@
----
-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

@@ -1,211 +0,0 @@
----
-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/context-condensation/SKILL.md

@@ -1,149 +0,0 @@
----
-name: context-condensation
-description: Use when context is approaching budget limits and you need to compress, OR when handing off to another session. Provides the explicit keep/drop rubric for what survives compression — preserve goals, progress, critical files, failing tests; drop exploration noise and resolved threads. Pairs with `/dcp compress` and `/handoff`. Adapted from OpenHands context-condensation, Manus context engineering, HumanLayer backpressure.
----
-
-# Context Condensation
-
-> Compression is not deletion — it is **selection of what survives**. The wrong selection makes the agent restart from zero. This skill defines what to keep.
-
-## When to Use
-
-- Context >100k tokens and growing
-- Phase boundary reached (research done, ready to implement)
-- Handing off to a new session via `/handoff`
-- A subagent returns large output you need to integrate
-- After `/dcp compress` ran but you still feel context drift
-
-## Core Principle: 4 Tiers of Survival
-
-Every conversation chunk falls into one of four tiers. Compress accordingly.
-
-| Tier | Content                                                  | Action                  |
-| ---- | -------------------------------------------------------- | ----------------------- |
-| 1    | Goal, constraints, user-stated requirements              | **Preserve verbatim**   |
-| 2    | Critical state — failing tests, current bug, open files  | **Preserve as summary** |
-| 3    | Decisions made, alternatives rejected, why               | **Preserve as 1-liner** |
-| 4    | Exploration noise — failed greps, dead ends, raw outputs | **Drop entirely**       |
-
-## Keep List (Always)
-
-Compress around these — never drop:
-
-- **The user's literal request.** Direct quote when short. Paraphrase only when long, and label as paraphrase.
-- **Active failures.** Current error message, failing test name + reason, open bug. Tells the next agent what's broken.
-- **Decisions + rationale.** "Chose JWT over sessions because [reason]." One line each. Future agents inherit the why.
-- **File paths currently being edited.** Exact paths, not "the auth file".
-- **Verification status.** Last typecheck/lint/test result with timestamp.
-- **Open questions for the user.** Questions awaiting human input.
-- **Constraints discovered mid-task.** "User can't add new deps", "DB is read-only in this env".
-
-## Drop List (Aggressive)
-
-Compress these to a single line or remove entirely:
-
-- **Resolved exploration.** Found the file? Drop the 5 greps that led there.
-- **Tool output noise.** Full directory listings, `ls` outputs, package install logs. Keep only the relevant filename.
-- **Verbose reasoning.** Your own multi-paragraph thinking that ended in one decision. Keep the decision.
-- **Acknowledgments.** "Got it", "I'll do that next" — pure social filler.
-- **Failed attempts that taught nothing.** If a wrong approach added no information, drop it. Keep failures that revealed a constraint.
-- **Sub-agent self-reports.** Keep the result + verification, drop the agent's narrative summary (Worker Distrust Protocol — don't trust the prose).
-- **Old plans you've since revised.** Keep only the current plan.
-
-## Failure Preservation Rule
-
-> **Useful failures stay. Useless failures go.**
-
-A failure is **useful** if it:
-
-- Revealed a constraint ("can't use `mv` on this filesystem")
-- Eliminated a hypothesis ("the bug is not in the parser")
-- Showed a trap that another agent would re-fall into
-
-A failure is **useless** if it:
-
-- Was a typo / fat-finger fixed immediately
-- Was a tool-call format error with no semantic content
-- Was an obvious dead end no agent would repeat
-
-**Manus rule** (from "Context Engineering for AI Agents: Lessons from Building Manus"): keep useful failures **in-context** as warnings. Don't compress to "encountered errors then succeeded" — that loses the warning.
-
-## Condensation Triggers (Beyond Token Count)
-
-Token count is one trigger. These are the others:
-
-| Trigger                               | Action                                          |
-| ------------------------------------- | ----------------------------------------------- |
-| Phase boundary (research → implement) | Compress all of research phase to summary       |
-| Subagent returns >2k tokens           | Compress immediately, keep result + evidence    |
-| Same question asked twice in session  | Indicates context drift — compress aggressively |
-| Plan revised                          | Drop old plan completely                        |
-| Conversation feels "lost"             | Compress; restart from goal + current state     |
-
-## The Handoff Variant
-
-When compressing for `/handoff` (different session, different agent will pick up), be **even more selective**:
-
-- Preserve everything in Keep List
-- Add a **`## Next Step`** with the literal next action
-- Add a **`## Don't Re-Discover`** with traps already mapped
-- Drop everything else
-
-Handoff format:
-
-```markdown
-## Goal
-
-[user's literal request]
-
-## Status
-
-- Done: [list of completed items with file:line]
-- In progress: [current task]
-- Blocked: [what's blocking, what was tried]
-
-## Critical State
-
-- Open files: [paths]
-- Last verification: [command + result + timestamp]
-- Active failures: [error / failing test]
-
-## Decisions Made
-
-- [one-liner] → [one-line rationale]
-
-## Don't Re-Discover
-
-- [trap 1]: [why]
-- [trap 2]: [why]
-
-## Next Step
-
-[literal next action — copy-pastable command or description]
-```
-
-## Anti-Patterns
-
-- **"Let me summarize what we did so far..."** in every response — you're re-summarizing instead of compressing once at boundaries
-- **Dropping the goal during compression** — the worst failure mode; the next agent has no anchor
-- **Keeping all failures** — context fills with noise, real signals get buried
-- **Lossy paraphrase of user request** — when in doubt, quote verbatim
-- **Compressing during active edits** — wait for atomic step to finish
-
-## Integration
-
-- **Before `/dcp compress`:** Use this rubric to decide what your `summary` field should contain
-- **In `/handoff`:** This skill defines the handoff format
-- **After subagent return:** Apply Drop List to the agent's narrative, keep result + verification only
-- **In long sessions:** Re-read your own context every ~30 messages and apply the rubric
-
-## Output
-
-When you condense, briefly state what survived and what dropped:
-
-```
-Compressed messages 12-34. Kept: goal, 3 decisions, current failure (auth.ts:42 null deref).
-Dropped: 5 file searches, 2 abandoned approaches, dir listings.
-```
-
-This makes the compression auditable. The user (or next agent) can challenge what got cut.

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

@@ -1,69 +0,0 @@
----
-name: context-initialization
-description: Initialize project context files from templates. Creates on-demand planning files (roadmap.md, state.md) and updates auto-injected project.md.
-version: 2.0.0
-tags: [context, workflow]
-dependencies: []
----
-
-# Context Initialization
-
-## When to Use
-
-- When initializing project context files (project.md, roadmap.md, state.md) from templates.
-- project.md is auto-injected into every prompt; roadmap.md and state.md are on-demand.
-
-## When NOT to Use
-
-- When context files already exist and only need minor manual edits.
-
-## Process
-
-### 1. Verify Templates
-
-```typescript
-tilth_tilth_files({ pattern: "*.md", scope: ".opencode/memory/_templates" });
-// Required templates: project.md, roadmap.md, state.md
-```
-
-Stop if missing.
-
-### 2. Gather Input
-
-Ask 5 questions:
-
-1. Project vision
-2. Success criteria
-3. Target users
-4. Phases
-5. Current phase
-
-Skip if `--skip-questions` flag set.
-
-### 3. Create Files
-
-**project.md** (auto-injected — keep concise)
-
-- Read template via `Read({ filePath: ".opencode/memory/_templates/project.md" })`
-- Fill with answers
-- Write via `memory-update({ file: "project/project", content: ..., mode: "replace" })`
-
-**roadmap.md** (on-demand — access via `memory-read({ file: "project/roadmap" })`)
-
-- Read template
-- Parse phases into table
-- Write via `memory-update({ file: "project/roadmap", content: ..., mode: "replace" })`
-
-**state.md** (on-demand — access via `memory-read({ file: "project/state" })`)
-
-- Read template
-- Set initial state
-- Write via `memory-update({ file: "project/state", content: ..., mode: "replace" })`
-
-### 4. Verify
-
-```typescript
-tilth_tilth_files({ pattern: "*.md", scope: ".opencode/memory/project" });
-```
-
-Report created files with their injection status (auto-injected vs on-demand).