clikit-plugin 0.3.0 → 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.0",
+  "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/skill/tilth-reading/SKILL.md

@@ -10,43 +10,60 @@ When any task requires reading files or exploring a codebase, follow this priori
 ## Priority Chain
 
 ```
-1. tilth      → smart, outline-aware, section-targeted reading
-2. read       → raw file content (fallback for full-file needs)
-3. glob       → fallback when you need to discover file paths
-4. grep       → fallback when you need to search content patterns
+1. bash: tilth <path>    → smart, outline-aware, section-targeted reading
+2. read <path>           → raw file content (auto-enhanced by hook when tilth available)
+3. glob <pattern>        → fallback when you need to discover file paths
+4. grep <pattern>        → fallback when you need to search content patterns
 ```
 
+## Two Paths — Know Which to Use
+
+| Situation | How to invoke tilth |
+|-----------|-------------------|
+| Want smart full read or outline | `bash: tilth <path>` |
+| Want a specific section or heading | `bash: tilth <path> --section "## Heading"` |
+| Want a line range | `bash: tilth <path> --section 45-89` |
+| Tilth unavailable or bash not permitted | `read <path>` (hook auto-enhances when possible) |
+| Need to discover paths first | `glob pattern="…"` |
+| Need content pattern search | `grep pattern="…"` |
+
+> **Runtime hook:** the `tilth_reading` hook already enhances `read` tool output via tilth when tilth is on PATH.  
+> So `read` alone is often sufficient for full-file reads — use explicit `bash: tilth` when you need section targeting or outline-only mode.
+
 ## Workflow
 
-### Step 1 — Try tilth (always first)
+### Step 1 — Try tilth via bash (always first for large/unknown files)
 
 ```bash
+# Check tilth is available (cache result — don't repeat every call)
+tilth --version
+
 # Read a whole file (smart: outline or full depending on size)
 tilth <path>
 
-# Read a specific section by line range
-tilth <path> --section 45-89
-
 # Read a specific section by markdown heading
 tilth <path> --section "## Installation"
-```
 
-**Tilth is available if:** `npx tilth --version` exits 0, or a local `tilth` binary is on PATH.
+# Read a specific section by line range
+tilth <path> --section 45-89
+```
 
 **When tilth succeeds:** use its output directly. Do not duplicate with `read`.
 
-**When tilth fails or is unavailable:** immediately fall back — do not retry tilth for the same path.
+**When tilth fails or is unavailable:** fall back immediately — do not retry tilth for the same path.
 
 ---
 
-### Step 2 — Fallback: read (full file content)
+### Step 2 — Fallback: read (full file content, hook-enhanced)
 
-Use when you need complete, unprocessed file content and tilth is not available.
+Use when tilth bash is unavailable or you need raw content.
 
 ```
 read <path>
 ```
 
+The `tilth_reading` runtime hook automatically runs tilth on the output when available.
+
 Use `read` with `offset` + `limit` to scope large files:
 ```
 read <path> offset=<line> limit=<n>
@@ -81,13 +98,13 @@ Combine with `glob` results when searching a pre-discovered set of files.
 
 ## Decision Table
 
-| Need | Tool |
-|------|------|
-| Read a known file, outline/section | `tilth` |
-| Read a known file, need full raw content | `tilth` → `read` |
-| Find files matching a name/extension pattern | `tilth` → `glob` |
-| Search for a symbol/pattern across files | `tilth` → `grep` |
-| tilth unavailable or errored | `read` + `glob` + `grep` as needed |
+| Need | Primary | Fallback |
+|------|---------|---------|
+| Read known file — smart outline | `bash: tilth <path>` | `read <path>` |
+| Read known file — specific section | `bash: tilth <path> --section "…"` | `read <path> offset=X limit=N` |
+| Discover file paths | `glob pattern="…"` | — |
+| Search content patterns | `bash: tilth <path>` then `grep` | `grep pattern="…"` |
+| tilth unavailable / bash denied | `read <path>` | `glob` + `grep` |
 
 ---
 
@@ -96,14 +113,14 @@ Combine with `glob` results when searching a pre-discovered set of files.
 - **Never use `read` + `tilth` for the same path** — pick one.
 - **Never use `glob` when you already know the path** — call `read`/`tilth` directly.
 - **Never call `grep` for something `tilth --section` can already isolate.**
-- **Log fallback reason** when possible (e.g. "tilth not found, using read").
+- **Never assume bash: tilth works** — verify permission first (`tilth*: allow` in agent frontmatter).
 
 ## Red Flags
 
-- Calling `read` on a large file (>500 lines) without first trying `tilth` — tilth's outline mode saves context.
+- Calling `read` on a large file (>500 lines) without first trying `bash: tilth` — tilth's outline mode saves context.
 - Using `grep` to extract a known section — use `tilth --section` instead.
-- Ignoring tilth exit code and retrying without fallback.
-- Calling `glob` to discover a path you already know.
+- Agent has `bash: "*": deny` without `tilth*: allow` — tilth is silently blocked; fallback to `read`.
+- Assuming `read` is not enhanced — the hook runs tilth on `read` output automatically.
 
 ## References
 

package/src/agents/build.md

@@ -201,15 +201,24 @@ The `files_in_scope` field is the execution boundary — read it first.
 
 **File reading: load `tilth-reading` skill — tilth first, fallback to read/glob/grep.**
 
+```bash
+# 1st choice: smart outline-aware read (bash tool)
+tilth <path>
+tilth <path> --section "## Heading"   # section by heading
+tilth <path> --section 45-89          # section by line range
+```
+
 ```
-tilth <path>                         # 1st choice: smart outline-aware read
-tilth <path> --section "## Heading"  # section-targeted read
-read <path>                          # fallback: full raw content
-glob + grep                          # fallback: discovery + pattern search
+# Fallback: use these tools when tilth unavailable or fails
+read <path>                           # full raw content
+glob + grep                           # discovery + pattern search
 ```
 
-> The runtime hook already enhances `read` output via tilth automatically.
-> For large files (>500 lines), call `tilth` directly before `read` to get the outline first.
+> **Two paths available:**
+> - **Automatic:** `read` tool output is already enhanced by the tilth runtime hook when tilth is available.
+> - **Explicit:** call `bash: tilth <path>` for section-targeted reads or outline-only mode.
+>
+> For large files (>500 lines), prefer explicit `tilth` via bash to get an outline first.
 
 Use LSP tools to understand the code before touching it:
 

package/src/agents/explore.md

@@ -19,6 +19,8 @@ tools:
 permission:
   edit: deny
   bash:
+    "tilth*": allow
+    "npx tilth*": allow
     "git log*": allow
     "git blame*": allow
     "git show*": allow
@@ -56,17 +58,24 @@ Work from precise to broad. **Stop when the answer is found** — do not over-ex
 
 ### Reading priority (load `tilth-reading` skill before heavy file work)
 
-When reading files, follow the tilth-first chain:
+When reading files, use `bash: tilth` first — it is now allowed in your bash permissions.
 
+```bash
+# 1st choice — bash tool (allowed: tilth* and npx tilth*)
+bash: tilth <path>
+bash: tilth <path> --section "## Heading"
+bash: tilth <path> --section 45-89
 ```
-1. tilth <path>                          — smart read (full or outline)
-2. tilth <path> --section "## Heading"  — section-targeted
-3. read <path>                           — fallback: full raw content
-4. glob + grep                           — fallback: discovery + pattern search
+
+```
+# Fallback tools (when tilth unavailable or bash fails)
+read <path>        — full raw content (hook auto-enhances via tilth when available)
+glob <pattern>     — file discovery
+grep <pattern>     — content search
 ```
 
-> The runtime hook automatically enhances `read` output via tilth when available.
-> For large files (>500 lines), prefer `tilth` directly to get an outline before committing to full read.
+> `tilth` is permitted via `bash` in your frontmatter (`tilth*: allow`).
+> Use it for any file that may be large (>200 lines) or where section targeting helps.
 
 ### Search priority table
 
@@ -75,9 +84,10 @@ When reading files, follow the tilth-first chain:
 | 1 | Symbol definitions, type signatures | `lsp_workspace_symbols`, `lsp_goto_definition`, `lsp_hover` |
 | 2 | File structure, file listing | `glob` (pattern), `read` (directory listing) |
 | 3 | All call sites / usages | `lsp_find_references` |
-| 4 | File content — known path | `tilth <path>` → `read <path>` (fallback) |
-| 5 | Text pattern across files | `grep` (dedicated tool, not bash) |
-| 6 | Recent changes, authorship | `bash: git log`, `git blame`, `git show`, `git diff` |
+| 4 | File content — known path | `bash: tilth <path>` → `read <path>` (fallback) |
+| 5 | File section — known heading/range | `bash: tilth <path> --section "…"` |
+| 6 | Text pattern across files | `grep` (dedicated tool, not bash) |
+| 7 | Recent changes, authorship | `bash: git log`, `git blame`, `git show`, `git diff` |
 
 **Prefer LSP over text search for symbols.** `lsp_find_references` returns all usages with zero false positives; text grep may miss renamed or aliased identifiers.
 

package/src/agents/oracle.md

@@ -21,6 +21,8 @@ tools:
 permission:
   edit: deny
   bash:
+    "tilth*": allow
+    "npx tilth*": allow
     "git log*": allow
     "git blame*": allow
     "git show*": allow
@@ -95,20 +97,29 @@ If the request is ambiguous, state your interpretation assumption at the top —
 
 ## Phase 2 — Gather Local Evidence
 
-Use **LSP tools first**, then `tilth`/`read`/`glob`/`grep`, then git history last.
+Use **LSP tools first**, then `bash: tilth`/`read`/`glob`/`grep`, then git history last.
 
-> Load the `tilth-reading` skill for file reading. Priority: `tilth <path>` → `read` (fallback) → `glob` + `grep` (fallback).
-> The runtime hook enhances `read` output via tilth automatically when tilth is available.
+> Load the `tilth-reading` skill for file reading.
+> `tilth` is permitted via bash (`tilth*: allow` in your frontmatter).
+> Priority: `bash: tilth <path>` → `read` (auto-enhanced fallback) → `glob` + `grep`.
+
+```bash
+# Explicit tilth for outline or section (allowed via bash permissions)
+bash: tilth <path>
+bash: tilth <path> --section "## SectionName"
+bash: tilth <path> --section 45-89
+```
 
 | Priority | What to find | Tools |
 |----------|-------------|-------|
 | 1 | Symbol definitions, type signatures, current design | `lsp_workspace_symbols`, `lsp_goto_definition`, `lsp_hover` |
 | 2 | All callers / consumers of affected code | `lsp_find_references` |
 | 3 | Structural patterns, coupling, duplication | `ast_grep_search`, `grep` |
-| 4 | File content — smart read (outline or full) | `tilth <path>` → `read <path>` (fallback) |
-| 5 | File structure, scope of change | `glob`, directory listing via `read` |
-| 6 | Recent changes, authorship, regression risk | `bash: git log`, `git blame`, `git diff` |
-| 7 | Type errors, lint issues in affected scope | `lsp_diagnostics` |
+| 4 | File content — smart read (outline or full) | `bash: tilth <path>` → `read <path>` (fallback) |
+| 5 | File section — targeted by heading or range | `bash: tilth <path> --section "…"` |
+| 6 | File structure, scope of change | `glob`, directory listing via `read` |
+| 7 | Recent changes, authorship, regression risk | `bash: git log`, `git blame`, `git diff` |
+| 8 | Type errors, lint issues in affected scope | `lsp_diagnostics` |
 
 **Stop when you have enough evidence to make a well-grounded recommendation.** Do not over-read beyond what the decision requires.
 

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