clikit-plugin 0.2.47 → 0.3.0

package/dist/index.js

@@ -16267,6 +16267,11 @@ var DEFAULT_CONFIG = {
       active_only: true,
       ready_limit: 3,
       log: false
+    },
+    tilth_reading: {
+      enabled: true,
+      min_content_length: 1000,
+      log: false
     }
   }
 };
@@ -17401,6 +17406,108 @@ function getBeadsCompactionContext(projectDirectory, config2) {
   ].join(`
 `);
 }
+// src/hooks/tilth-reading.ts
+var DEFAULT_MIN_CONTENT_LENGTH = 1000;
+var tilthAvailabilityCache = null;
+function isTilthAvailable() {
+  if (tilthAvailabilityCache !== null)
+    return tilthAvailabilityCache;
+  try {
+    const result = Bun.spawnSync(["tilth", "--version"], {
+      stdout: "pipe",
+      stderr: "pipe"
+    });
+    tilthAvailabilityCache = result.exitCode === 0;
+  } catch {
+    tilthAvailabilityCache = false;
+  }
+  return tilthAvailabilityCache;
+}
+function shouldAttemptTilthForTool(toolName, toolInput) {
+  const normalized = toolName.toLowerCase();
+  if (!normalized.includes("read"))
+    return false;
+  const path9 = extractFilePath(toolInput);
+  return typeof path9 === "string" && path9.length > 0;
+}
+function extractFilePath(toolInput) {
+  for (const key of ["filePath", "file_path", "path", "file"]) {
+    const v = toolInput[key];
+    if (typeof v === "string" && v.length > 0)
+      return v;
+  }
+  return null;
+}
+function runTilth(filePath) {
+  const result = Bun.spawnSync(["tilth", filePath], {
+    stdout: "pipe",
+    stderr: "pipe"
+  });
+  if (result.exitCode !== 0) {
+    const stderr = result.stderr ? new TextDecoder().decode(result.stderr).trim() : "";
+    throw new Error(`tilth exited ${result.exitCode}: ${stderr}`);
+  }
+  return new TextDecoder().decode(result.stdout);
+}
+function applyTilthReading(filePath, original, config2) {
+  const minLen = config2?.min_content_length ?? DEFAULT_MIN_CONTENT_LENGTH;
+  if (original.length < minLen) {
+    return {
+      usedTilth: false,
+      tilthAvailable: false,
+      content: original,
+      outcome: "skipped"
+    };
+  }
+  if (!isTilthAvailable()) {
+    return {
+      usedTilth: false,
+      tilthAvailable: false,
+      content: original,
+      outcome: "tilth_unavailable"
+    };
+  }
+  try {
+    const enhanced = runTilth(filePath);
+    if (!enhanced || enhanced.trim().length === 0) {
+      return {
+        usedTilth: false,
+        tilthAvailable: true,
+        content: original,
+        outcome: "tilth_error",
+        error: "tilth returned empty output"
+      };
+    }
+    return {
+      usedTilth: true,
+      tilthAvailable: true,
+      content: enhanced,
+      outcome: "tilth_success"
+    };
+  } catch (err) {
+    return {
+      usedTilth: false,
+      tilthAvailable: true,
+      content: original,
+      outcome: "tilth_error",
+      error: err instanceof Error ? err.message : String(err)
+    };
+  }
+}
+function formatTilthLog(result, filePath) {
+  switch (result.outcome) {
+    case "tilth_success":
+      return `[CliKit:tilth-reading] Enhanced read via tilth: ${filePath}`;
+    case "tilth_unavailable":
+      return `[CliKit:tilth-reading] tilth not available, using read output: ${filePath}`;
+    case "tilth_error":
+      return `[CliKit:tilth-reading] tilth error (fallback to read): ${filePath} \u2014 ${result.error ?? "unknown error"}`;
+    case "skipped":
+      return `[CliKit:tilth-reading] Skipped (content below threshold): ${filePath}`;
+    default:
+      return `[CliKit:tilth-reading] ${result.outcome}: ${filePath}`;
+  }
+}
 // src/tools/cass-memory.ts
 import { execFile as execFile2 } from "child_process";
 import { promisify as promisify2 } from "util";
@@ -18452,6 +18559,27 @@ ${(content || "").trim()}`.trim();
           await hookErr("empty-message-sanitizer", error45, { tool: toolName });
         }
       }
+      if (pluginConfig.hooks?.tilth_reading?.enabled !== false) {
+        try {
+          const tilthConfig = pluginConfig.hooks?.tilth_reading;
+          const toolInput2 = getToolInput(input.args);
+          if (shouldAttemptTilthForTool(toolName, toolInput2)) {
+            const filePath = extractFilePath(toolInput2);
+            if (filePath) {
+              const result = applyTilthReading(filePath, toolOutputContent, tilthConfig);
+              if (result.usedTilth) {
+                toolOutputContent = result.content;
+                output.output = result.content;
+              }
+              if (tilthConfig?.log === true) {
+                await cliLog("info", formatTilthLog(result, filePath));
+              }
+            }
+          }
+        } catch (error45) {
+          await hookErr("tilth-reading", error45, { tool: toolName });
+        }
+      }
       if (pluginConfig.hooks?.truncator?.enabled !== false) {
         try {
           if (shouldTruncate(toolOutputContent, pluginConfig.hooks?.truncator)) {

package/memory/_templates/plan.md

@@ -116,12 +116,13 @@ Use this template when creating implementation plans.
 
 ## Execution Model
 
-- Workflow quick mode: `/create → /start → /ship → /verify`
-- Workflow deep mode: `/create → /research → /design → /start → /ship → /verify`
+- Workflow quick mode: `/create → /start → /verify → /ship`
+- Workflow deep mode: `/create → /research → /design → /start → /verify → /ship`
 - Execution unit: **Task Packet**
 - Source of truth: **Beads**
 - `/start`: execute + per-packet verify loop
 - `/verify`: pre-ship gate (all 4 checks, SHIP_READY verdict required before `/ship`)
+- `/ship`: commit + sync/push landed changes in the shared checkout; `/pr` is an explicit exception path
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clikit-plugin",
-  "version": "0.2.47",
+  "version": "0.3.0",
   "description": "OpenCode plugin — 7 agents, 15 commands, 22 skills, 10 hooks",
   "type": "module",
   "main": "./dist/index.js",
@@ -67,4 +67,4 @@
   "peerDependencies": {
     "bun": ">=1.0.0"
   }
-}
+}

package/skill/finishing-a-development-branch/SKILL.md

@@ -1,9 +1,11 @@
 ---
 name: finishing-a-development-branch
-description: Use when completing development work on a branch. Verify tests, present 4 options, execute choice with cleanup.
+description: Legacy compatibility skill. Finish work from the shared default-branch workspace: verify, sync, and land without worktrees or task branches.
 ---
 
-# Finishing a Development Branch
+# Finishing a Shared Workspace Session
+
+> Legacy skill name: `finishing-a-development-branch`
 
 ## Step 1 — Verify
 
@@ -13,41 +15,41 @@ npm test    # or project test command
 
 **If tests fail: STOP. Fix first. Never proceed with failing tests.**
 
-## Step 2 — Present Options
+## Step 2 — Confirm shared-workspace state
 
-```
-Branch [branch-name] ready. Choose:
-  1. MERGE    — merge to main, clean up
-  2. PR       — create pull request, keep branch
-  3. KEEP     — push branch, continue later
-  4. DISCARD  — delete branch and all changes
+```bash
+git branch --show-current     # expect: repo default branch (main/master/etc.)
+git status --short --branch   # confirm only intended changes are present
 ```
 
-## Step 3 — Execute
+If the branch is not the repo default branch, stop unless the user explicitly approved that branch.
 
-**MERGE**
-```bash
-git checkout main && git pull origin main
-git merge <branch> && git push origin main
-git branch -d <branch> && git worktree remove <path>
+## Step 3 — Present Options
+
+```
+Shared workspace on the default branch is ready. Choose:
+  1. LAND     — sync default branch, push, keep working from shared checkout
+  2. PAUSE    — leave local state in place and hand off
+  3. DISCARD  — revert local changes and return to a clean checkout
 ```
 
-**PR**
+## Step 4 — Execute
+
+**LAND**
 ```bash
-git push origin <branch>
-gh pr create --title "<title>" --body "<body>"
+git pull --rebase
+git push
 ```
 
-**KEEP**
+**PAUSE**
 ```bash
-git push origin <branch>
-# leave worktree intact
+/handoff
+# leave shared workspace state intact for the next session
 ```
 
 **DISCARD** — require typed confirmation: `"discard"`
 ```bash
-git checkout main
-git branch -D <branch> && git worktree remove <path>
+git restore --worktree --staged .
 ```
 
 ## Safety Rules
@@ -56,11 +58,11 @@ git branch -D <branch> && git worktree remove <path>
 |------|-------------|
 | Tests must pass | Block on failure |
 | DISCARD | Require typed `"discard"` to confirm |
-| Force push to main | Never |
-| Stale worktrees | Always clean up after merge/discard |
+| Force push to default branch | Never |
+| Shared workspace drift | Sync and inspect before landing |
 
 ## Red Flags
 
-- Merging without test verification
+- Landing without test verification
 - Discarding without confirmation
-- Leaving stale worktrees after merge
+- Creating a worktree or task branch just to finish the task

package/skill/ritual-workflow/SKILL.md

@@ -17,7 +17,7 @@ DISCOVER → PLAN → IMPLEMENT → VERIFY → COMPLETE
 | PLAN | User approves spec + plan |
 | IMPLEMENT | All planned tasks checked off |
 | VERIFY | typecheck + tests + lint + build all pass |
-| COMPLETE | PR merged / deployed |
+| COMPLETE | Changes landed on default branch / deployed |
 
 ## Command Map
 

package/skill/tilth-reading/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: tilth-reading
+description: Use when reading files, exploring codebases, or searching content. Tries tilth first for smart outline/section-aware reading; falls back to glob → read → grep if tilth is unavailable or fails.
+---
+
+# Tilth-first Reading
+
+When any task requires reading files or exploring a codebase, follow this priority chain — always try the higher-priority tool first, fall back only when blocked.
+
+## 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
+```
+
+## Workflow
+
+### Step 1 — Try tilth (always first)
+
+```bash
+# 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.
+
+**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.
+
+---
+
+### Step 2 — Fallback: read (full file content)
+
+Use when you need complete, unprocessed file content and tilth is not available.
+
+```
+read <path>
+```
+
+Use `read` with `offset` + `limit` to scope large files:
+```
+read <path> offset=<line> limit=<n>
+```
+
+---
+
+### Step 3 — Fallback: glob (file discovery)
+
+Use when you need to find files by pattern before reading.
+
+```
+glob pattern="**/*.ts" path="<dir>"
+glob pattern="**/SKILL.md"
+```
+
+Always narrow the pattern as much as possible — avoid `**/*` without extension filtering.
+
+---
+
+### Step 4 — Fallback: grep (content search)
+
+Use when you need to find symbols, usages, or patterns across files.
+
+```
+grep pattern="<regex>" include="*.ts" path="<dir>"
+```
+
+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 |
+
+---
+
+## Fallback Rules
+
+- **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").
+
+## Red Flags
+
+- Calling `read` on a large file (>500 lines) without first trying `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.
+
+## References
+
+- [Fallback flow detail](references/fallback-flow.md) — full decision tree, tilth availability check, error codes

package/skill/tilth-reading/references/fallback-flow.md

@@ -0,0 +1,123 @@
+# Tilth-reading: Fallback Flow Reference
+
+Full decision tree for the tilth-reading skill, including availability checks, error codes, and fallback triggers.
+
+---
+
+## Availability Check
+
+Before using tilth in a new session, verify it is available:
+
+```bash
+# Option A: local install
+tilth --version
+
+# Option B: via npx
+npx tilth --version
+```
+
+| Exit code | Meaning | Action |
+|-----------|---------|--------|
+| 0 | tilth available | Proceed with tilth |
+| 1 / non-zero | tilth error | Fall back immediately |
+| command not found | not installed | Fall back immediately |
+
+> Cache the availability result within a session — do not re-check on every file read.
+
+---
+
+## Full Decision Tree
+
+```
+Need to read / search files?
+│
+├─► tilth available?
+│    │
+│    ├─► YES
+│    │    │
+│    │    ├─► Known path + section target?
+│    │    │    └─► tilth <path> --section "…"
+│    │    │
+│    │    ├─► Known path, want smart summary/outline?
+│    │    │    └─► tilth <path>
+│    │    │
+│    │    ├─► Need to discover paths first?
+│    │    │    └─► glob → then tilth <each-path>
+│    │    │
+│    │    └─► Need to find symbol/pattern?
+│    │         └─► tilth <path> --section <heading>
+│    │             (or grep if heading unknown)
+│    │
+│    └─► NO / tilth errored
+│         │
+│         ├─► Need raw full file?  → read <path>
+│         ├─► Need file discovery? → glob pattern="…"
+│         └─► Need pattern search? → grep pattern="…"
+│
+└─► Combine fallbacks as needed:
+     glob (discover) → read (content) → grep (pattern)
+```
+
+---
+
+## Error Codes from tilth
+
+| Error | Cause | Fallback |
+|-------|-------|---------|
+| Binary file detected | file is not text | `read` (confirms binary) or skip |
+| Generated file skipped | auto-generated file | proceed, check `read` if needed |
+| File too large (>500KB) | outline only mode triggered | use tilth output (outline) or `read` with `offset`+`limit` |
+| Non-zero exit, stderr | any runtime error | fall back to `read` + `grep` |
+
+---
+
+## Tilth Flags Reference
+
+```bash
+tilth <path>                        # smart read: full or outline based on size
+tilth <path> --section 45-89        # line range
+tilth <path> --section "## Heading" # markdown heading
+```
+
+Key internal thresholds (from tilth source):
+- `TOKEN_THRESHOLD = 6000` — above this, tilth switches to outline mode
+- `FILE_SIZE_CAP = 500_000 bytes` — above this, outline only
+
+---
+
+## Fallback Chain Examples
+
+### Example 1: Explore an unfamiliar directory
+
+```
+1. glob pattern="src/**/*.ts"              # discover files
+2. tilth src/hooks/truncator.ts            # read key file (smart)
+3. tilth src/index.ts --section "tool.execute.after"  # targeted section
+```
+
+### Example 2: tilth unavailable
+
+```
+1. tilth --version                         # fails: not found
+2. glob pattern="src/**/*.ts"              # discover paths
+3. read src/hooks/truncator.ts             # full content
+4. grep pattern="shouldTruncate" include="*.ts"   # pattern search
+```
+
+### Example 3: Large file, want section only
+
+```
+1. tilth src/index.ts --section "## Phase 3"   # tilth sections it
+   (if unavailable)
+2. read src/index.ts offset=820 limit=60       # manual offset fallback
+```
+
+---
+
+## Combining with Other Skills
+
+| If also using | Note |
+|---------------|------|
+| `deep-research` | Use tilth-reading for local navigation; deep-research for external docs |
+| `source-code-research` | tilth-reading replaces raw `read` calls in that skill when tilth is available |
+| `systematic-debugging` | Use tilth --section to isolate the failing function before adding diagnostics |

package/skill/using-git-worktrees/SKILL.md

@@ -1,53 +1,55 @@
 ---
 name: using-git-worktrees
-description: Use when starting isolated development work. Creates isolated workspace on new branch via bd worktree, prevents dirty-state conflicts.
+description: Legacy compatibility skill. Despite the name, the current workflow uses one shared checkout on the repo default branch and does not create git worktrees.
 ---
 
-# Using Git Worktrees
+# Shared Workspace Development
 
-## Pre-conditions (verify before creating)
+> Legacy skill name: `using-git-worktrees`
 
-```bash
-git rev-parse --is-inside-work-tree  # must be inside a repo
-git status --porcelain               # must be clean — no uncommitted changes
-```
+This repository no longer uses git worktrees for routine agent execution.
 
-## Create Worktree
+## Policy
 
-```bash
-# Preferred: use bd (shares .beads/ database automatically)
-bd worktree create <issue-id>-<desc> --branch <type>/<issue-id>-<desc>
+- Work directly in the shared repository checkout
+- Stay on the repo default branch unless the user explicitly approves another branch
+- Do **not** create git worktrees
+- Do **not** create per-task branches to hide conflicts
+- Use Beads reservations to coordinate overlapping edits
+- Pull/rebase frequently so conflicts surface immediately
+
+## Start-of-task checks
 
-# Fallback: raw git
-git worktree add -b <branch> .worktrees/<branch>
+```bash
+git rev-parse --is-inside-work-tree  # must be inside a repo
+git branch --show-current            # expect: repo default branch (main/master/etc.)
+git status --short --branch          # inspect local state before editing
 ```
 
-## Branch Naming
+If overlapping local changes already touch your files, stop and coordinate — do not isolate the work in another workspace.
 
-```
-feature/<id>-<desc>   fix/<id>-<desc>   hotfix/<id>-<desc>
-refactor/<id>-<desc>  experiment/<id>-<desc>
-```
+## During execution
 
-## After Creating
+- Reserve files with `beads-village_reserve` before editing
+- Keep changes packet-sized and scoped to reserved files
+- Re-run `git status --short --branch` before commit/push to catch unexpected drift
+- If the tree is clean and you need the latest remote updates, sync with:
 
 ```bash
-cd .worktrees/<branch>
-npm install        # install deps
-npm test           # run baseline — must pass before any changes
+git pull --rebase
 ```
 
-## Cleanup
+## End-of-task sync
 
 ```bash
-bd worktree remove <name>    # preferred (cleans .beads redirect)
-git worktree prune           # clean stale refs
-git branch -d <branch>       # only after confirmed merge
+git status --short --branch
+git pull --rebase            # when safe and needed
+git push                     # publish landed changes after verification and sync
 ```
 
 ## Red Flags
 
-- Creating worktree with uncommitted changes
-- Skipping baseline test run
-- Using raw `git worktree add` without `bd` (loses beads database link)
-- Unclear branch names
+- Creating a git worktree or per-task branch for routine work
+- Editing reserved files without coordination
+- Letting local drift accumulate in the shared checkout
+- Using isolation to avoid dealing with real conflicts

package/src/agents/AGENTS.md

@@ -26,6 +26,20 @@ The three read-only specialists have distinct scopes — choose the right one:
 
 **Never call `@oracle` for something `@explore` or `@research` can answer.**
 
+## File Reading Strategy
+
+All agents that read files must follow the **tilth-first chain** (see `skill/tilth-reading/SKILL.md`):
+
+```
+1. tilth <path>           — smart read (full or outline based on size)
+2. read <path>            — fallback: raw full file content
+3. glob <pattern>         — fallback: file discovery
+4. grep <pattern>         — fallback: content pattern search
+```
+
+> The runtime hook (`tilth_reading`) automatically enhances `read` tool output via tilth.
+> Agents should call `tilth` directly for large files to get smart outlines before reading in full.
+
 ## Active Roles in Compressed Workflow
 
 Default active roles: