clikit-plugin 0.3.1 → 0.3.2

package/command/debug.md

@@ -30,8 +30,15 @@ Document:
 git log --oneline -10
 git diff HEAD~5
 
-# Search for related code
-Grep: [error pattern]
+# Read suspicious files — tilth-first
+bash: tilth <path>
+bash: tilth <path> --section "## SectionName"
+```
+
+```
+# Fallback reading
+read <path>     — full content (auto-enhanced by tilth hook)
+grep pattern="<error pattern>" include="*.ts"
 ```
 
 ### 3. Investigate
@@ -42,7 +49,7 @@ Hypothesis → Evidence → Verify → Repeat
 
 1. Form hypothesis about cause
 2. Predict what evidence would confirm/deny
-3. Gather evidence (grep, read, run, LSP)
+3. Gather evidence — **tilth-first**: `bash: tilth <path>` → `read` → `grep` → LSP
 4. If wrong, form new hypothesis
 
 ### 4. Root Cause Analysis (5 Whys)
@@ -78,14 +85,15 @@ pnpm typecheck
 
 ## Debugging Tools
 
-| Tool | Use For |
-|------|---------|
-| `Grep` | Find error patterns, related code |
-| `Read` | Examine suspicious files |
-| `Bash` | Run tests, check logs, git bisect |
-| `LSP` | Trace definitions, find references |
-| `ast_grep_search` | Find structural code patterns |
-| Oracle | Complex multi-layer analysis (escalation) |
+| Tool | Priority | Use For |
+|------|----------|---------|
+| `bash: tilth <path>` | **1st** | Smart read — outline or full, section targeting |
+| `Read` | 2nd (fallback) | Full file content (auto-enhanced by tilth hook) |
+| `LSP` | **1st for symbols** | Trace definitions, find references, diagnostics |
+| `Grep` | Fallback | Find patterns when tilth section can't isolate |
+| `Bash` | As needed | Run tests, check logs, git bisect |
+| `ast_grep_search` | As needed | Find structural code patterns |
+| Oracle | Escalation | Complex multi-layer analysis |
 
 ## Common Patterns
 

package/command/verify.md

@@ -9,7 +9,7 @@ You are the **Build Agent**. Execute the `/verify` command.
 
 `/verify` is a **deep audit**, not a mechanical checklist. Before running any command, you must deeply understand the codebase — read files, trace call chains, understand intent. Only then can you produce a meaningful review.
 
-Inspired by Amp's `deep` mode: **silently read and traverse the codebase first**, understand the full impact chain, then evaluate. Don't rush to output — correctness over speed.
+Inspired by Amp's `deep` mode: **silently read and traverse the codebase first** (tilth-first — smart outline before committing to full reads), understand the full impact chain, then evaluate. Don't rush to output — correctness over speed.
 
 `/start` performs a **per-packet** narrow-scope verify.
 `/verify` runs **deep comprehension + 4-gate check + reasoning-grade review** — full SHIP_READY verdict.
@@ -33,8 +33,21 @@ git log --oneline -5         # recent commit history
 
 ### 1.3 Trace the Impact Chain
 For each changed file:
-1. **Read the file** — understand its purpose, exports, contracts
-2. **Find callers** — what depends on this? (`grep`, `lsp_find_references`)
+1. **Read the file** — tilth-first for smart outline/section; fallback to `read`
+
+```bash
+# 1st choice — smart read (outline or full based on size)
+bash: tilth <path>
+bash: tilth <path> --section "## SectionName"   # section targeting
+```
+
+```
+# Fallback (tilth unavailable)
+read <path>               — full raw content (auto-enhanced by tilth hook)
+read <path> offset=X limit=N  — section targeting fallback
+```
+
+2. **Find callers** — what depends on this? (`lsp_find_references`, then `grep` as fallback)
 3. **Read tests** — what behavior is expected?
 4. **Identify blast radius** — what could break downstream?
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clikit-plugin",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "OpenCode plugin — 7 agents, 15 commands, 22 skills, 10 hooks",
   "type": "module",
   "main": "./dist/index.js",

package/skill/deep-research/SKILL.md

@@ -13,11 +13,15 @@ description: Use when exploring unfamiliar code or implementing complex features
 3. lsp_goto_definition → trace origins
 4. lsp_find_references → map all usages
 5. lsp_document_symbols → understand exports
-6. Incoming/outgoing call hierarchy → trace data flow
-7. Score each finding 1–10
-8. Save to memory/research/[topic]-findings.md
+6. bash: tilth <path>  → smart read (outline first, then section drill)
+   Fallback: read <path> (auto-enhanced) → grep (pattern search)
+7. Incoming/outgoing call hierarchy → trace data flow
+8. Score each finding 1–10
+9. Save to memory/research/[topic]-findings.md
 ```
 
+> **Step 6 — tilth-first reading:** for any file surfaced by LSP, use `bash: tilth <path>` to get a smart outline before reading in full. Use `--section` to drill into specific functions. Fall back to `read` + `grep` only when tilth is unavailable.
+
 ## Confidence Scoring
 
 | Score | Meaning |
@@ -52,6 +56,7 @@ Save to `.opencode/memory/research/[topic]-findings.md`:
 ## Red Flags
 
 - Skipping LSP — guessing structure instead of tracing it
+- Reading large files with `read` without trying `tilth` outline first
 - Not saving findings to memory (lost between sessions)
 - Asserting with confidence < 4 without flagging it
 

package/skill/source-code-research/SKILL.md

@@ -15,17 +15,35 @@ description: Use when API docs are insufficient. Go directly to package source t
 ## Protocol
 
 ```bash
-# 1. Locate source
-cat node_modules/<pkg>/package.json | grep -E '"main"|"types"|"source"'
-ls node_modules/<pkg>/src/
+# 1. Locate source — tilth-first
+bash: tilth node_modules/<pkg>/package.json
+bash: tilth node_modules/<pkg>/src/
 
-# 2. Read entry point
-cat node_modules/<pkg>/src/index.ts   # or index.js
+# Fallback: use grep/read only if tilth unavailable
+grep -E '"main"|"types"|"source"' node_modules/<pkg>/package.json
+```
+
+```bash
+# 2. Read entry point — tilth-first
+bash: tilth node_modules/<pkg>/src/index.ts
+bash: tilth node_modules/<pkg>/src/index.ts --section "## exports"
+
+# Fallback
+read node_modules/<pkg>/src/index.ts
+```
+
+```bash
+# 3. Read tests — tilth gives outline first for large test files
+bash: tilth node_modules/<pkg>/test/
+bash: tilth node_modules/<pkg>/__tests__/
 
-# 3. Read tests (best doc of real behavior)
-ls node_modules/<pkg>/test/  ||  ls node_modules/<pkg>/__tests__/
+# Fallback
+read node_modules/<pkg>/test/index.test.ts
 ```
 
+> **Tilth-first rule:** always try `bash: tilth <path>` before `read` or `cat`.
+> For large source files, tilth's outline mode shows all exports/functions before you commit to reading the full file.
+
 ## What to Look For
 
 | Question | Where |
@@ -62,6 +80,7 @@ Save to `.opencode/memory/research/[package]-internals.md`:
 - Not reading the tests
 - Assuming behavior from the function name
 - Ignoring error paths
+- Using `cat` or raw `read` on large files without tilth outline first
 
 ## References
 

package/src/agents/plan.md

@@ -34,10 +34,12 @@ beads-village_inbox(unread=true)           # check for blockers or messages
 beads-village_ls(status="ready")           # see what's already queued
 ```
 
-Then read memory context:
+Then read memory context — **tilth-first via `read` tool** (runtime hook auto-enhances):
 - `.opencode/memory/_digest.md` — session-start digest of prior observations
 - Any relevant `memory/specs/`, `memory/plans/`, `memory/research/` artifacts
 
+> You have `bash: false`. Use the `read` tool — it is automatically enhanced by the tilth runtime hook when tilth is available (smart outline/section mode). For large files, use `read` with `offset`+`limit` to target sections.
+
 ---
 
 ## Phase 1 — Intake & Classify
@@ -77,6 +79,9 @@ Ask only if the answer materially changes packet boundaries or acceptance criter
 **You are in read-only mode during this phase.**
 Delegate ALL codebase inspection to `@explore`. You do not have bash access — do not attempt to read files yourself.
 
+> `@explore` uses **tilth-first reading** (`bash: tilth` → `read` → `glob` → `grep`).
+> When delegating, let `@explore` choose the reading strategy — do not prescribe `grep` or `read` in your delegation prompt.
+
 Exploration checklist:
 - [ ] Codebase patterns — naming conventions, test locations, folder structure
 - [ ] Affected files — what currently exists that this plan will touch

package/src/agents/review.md

@@ -15,6 +15,8 @@ tools:
 permission:
   edit: deny
   bash:
+    "tilth*": allow
+    "npx tilth*": allow
     "git diff*": allow
     "git log*": allow
     "git show*": allow
@@ -98,7 +100,18 @@ Then:
 lsp_diagnostics <all-changed-files>
 ```
 
-Read each changed file in full.
+Read each changed file — **tilth-first**:
+
+```bash
+# 1st choice — smart read (outline or full based on size)
+bash: tilth <path>
+bash: tilth <path> --section "## SectionName"   # section targeting
+```
+
+```
+# Fallback (when tilth unavailable)
+read <path>         — full raw content (hook auto-enhances when tilth on PATH)
+```
 
 For spec/plan context: check `.opencode/memory/plans/` and `specs/`. If none exist, proceed without them — absence of a plan is not a blocker for review.
 

package/src/agents/vision.md

@@ -11,6 +11,8 @@ tools:
 permission:
   edit: allow
   bash:
+    "tilth*": allow
+    "npx tilth*": allow
     "npm run dev*": allow
     "pnpm dev*": allow
     "bun run dev*": allow
@@ -41,7 +43,22 @@ You are the Vision Agent — a design architect who turns prompts, sketches, and
 
 Build will provide design context when delegating to you (existing design system, CSS framework, component patterns). Use this context — do not delegate to other agents.
 
-If context is insufficient, use your own tools (glob, grep, read) to find:
+If context is insufficient, read existing code — **tilth-first**:
+
+```bash
+# 1st choice — smart read (outline or full)
+bash: tilth <path>
+bash: tilth <path> --section "## SectionName"
+```
+
+```
+# Fallback
+glob pattern="…"   — discover files
+read <path>        — full content (auto-enhanced by tilth hook)
+grep pattern="…"   — content search
+```
+
+Use to find:
 - CSS variables, theme config, design tokens
 - Existing component naming and prop patterns
 - package.json for CSS framework, component library, icons