clikit-plugin 0.3.3 → 0.3.5

package/memory/_digest.md

@@ -1,6 +1,6 @@
 # Memory Digest
 
-> Auto-generated on 2026-03-18. Read-only reference for agents.
+> Auto-generated on 2026-03-19. Read-only reference for agents.
 > Source: `.opencode/memory/memory.db`
 
 *No observations found in memory database.*

package/memory/project/gotchas.md

@@ -0,0 +1,102 @@
+# Project Gotchas
+
+> Lessons learned and known pitfalls for this project. Updated as issues are discovered.
+
+---
+
+## DCP Beta (`@tarquinen/opencode-dcp@beta`)
+
+### Single compress tool — no prune, no distill
+
+DCP beta ships with **one tool: `compress`**. The old 3-tool system (`distill`, `compress`, `prune`) is gone.
+
+```
+❌ /dcp prune     → does not exist in beta
+❌ /dcp distill   → does not exist in beta
+✅ /dcp compress  → the only compression tool
+✅ /dcp sweep     → aggressive compress variant
+✅ /dcp stats     → token breakdown
+✅ /dcp context   → full context breakdown
+```
+
+If you encounter guidance mentioning `prune` or `distill`, it is outdated.
+
+---
+
+### Config location
+
+DCP reads config in this priority order (highest last):
+
+1. `~/.config/opencode/dcp.jsonc` (global)
+2. `$OPENCODE_CONFIG_DIR/dcp.jsonc` (if env set)
+3. `.opencode/dcp.jsonc` ← **project level, highest priority**
+
+DCP's own code lives at: `~/.cache/opencode/node_modules/@tarquinen/opencode-dcp/`  
+Do not edit files there — they get overwritten on reinstall.
+
+---
+
+### Auto-protected tools
+
+DCP will **never** prune output from these tools (hardcoded in beta):
+
+| Tool | Reason protected |
+|------|-----------------|
+| `task` | Subagent results are always critical |
+| `skill` | Skill content must persist for active use |
+| `todowrite` | In-session task state |
+| `todoread` | In-session task state |
+| `compress` | DCP's own operations |
+| `batch` | Batched tool call containers |
+| `plan_enter` | Plan mode boundary markers |
+| `plan_exit` | Plan mode boundary markers |
+
+These are also listed in `.opencode/dcp.jsonc → protectedToolNames`.
+
+---
+
+### Nudge configuration
+
+Current project config (`.opencode/dcp.jsonc`):
+
+```jsonc
+"nudgeFrequency": 5,           // suggest after every 5 iterations
+"iterationNudgeThreshold": 15, // become more insistent after 15 iterations
+"nudgeForce": "soft"           // suggests, does not force auto-compress
+```
+
+- `nudgeForce: "soft"` = DCP nudges but **you** trigger compress.  
+- If you want DCP to auto-compress: change to `"nudgeForce": "auto"` (not recommended for default).
+
+---
+
+### Reduced cache invalidation
+
+Beta has reduced cache invalidation compared to v2. This improves performance but means:
+- Config changes in `dcp.jsonc` may not take effect until OpenCode restarts.
+- If compress behavior seems wrong after config edit → restart OpenCode.
+
+---
+
+### compress.permission: "ask"
+
+Default config uses `"permission": "ask"` — DCP will prompt before compressing.  
+If you want silent auto-compress: change to `"permission": "auto"`.
+
+Avoid `"permission": "deny"` unless debugging — it disables all compression.
+
+---
+
+### Installing alongside CliKit
+
+DCP beta is installed automatically by CliKit when you run:
+
+```bash
+bun x clikit-plugin install
+```
+
+This adds **both** entries to `opencode.json`:
+- `clikit-plugin@latest`
+- `@tarquinen/opencode-dcp@beta`
+
+Restart OpenCode after install to activate.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "clikit-plugin",
-  "version": "0.3.3",
-  "description": "OpenCode plugin — 7 agents, 15 commands, 22 skills, 10 hooks",
+  "version": "0.3.5",
+  "description": "OpenCode plugin — 7 agents, 15 commands, 25 skills, 10 hooks",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -30,9 +30,8 @@
     "lint": "tsc --noEmit",
     "prepublishOnly": "bun run clean && bun run build",
     "postpublish": "rm -rf ~/.cache/opencode/node_modules/clikit-plugin && rm -f ~/.cache/opencode/bun.lock && echo '✓ Cleared OpenCode plugin cache — next start will install fresh'",
-    "test": "bun test",
     "typecheck": "tsc --noEmit",
-    "verify": "bun run lint && bun run test && bun run build",
+    "verify": "bun run lint && bun run build",
     "dev": "bun run build --watch"
   },
   "keywords": [

package/skill/compaction/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: compaction
+description: Use when preparing for context compaction or session compression. Compress-first patterns with DCP beta. Replaces legacy prune/distill guidance.
+---
+
+# Compaction (Compress-First)
+
+## What Changed in DCP Beta
+
+| Old (v2 / legacy) | New (beta) |
+|-------------------|-----------|
+| `/dcp distill` | Removed |
+| `/dcp prune` | Removed |
+| `/dcp compress` | ✅ The single compress tool |
+| 3-tool system | Single `compress` tool |
+
+**If you see guidance referencing `distill` or `prune`, it is outdated. Use `compress` instead.**
+
+## Compress-First Workflow
+
+### Before starting a long task
+```
+/dcp stats       # baseline token state
+```
+
+### Mid-task (when yellow zone)
+```
+/dcp compress    # consolidate — DCP will ask permission
+```
+
+### End of heavy task
+```
+/dcp sweep       # aggressive final compression before /handoff
+/dcp stats       # verify savings
+```
+
+## When Compaction Happens
+
+OpenCode triggers its own internal compaction (`experimental.session.compacting`) at high context usage. DCP runs *before* that threshold with `/dcp compress` to prevent reaching it.
+
+**Priority order:**
+1. `/dcp compress` — DCP-level (smart, preserves task state)
+2. OpenCode internal compaction — last resort (less targeted)
+
+## Beads State is Protected
+
+The `beads-context` hook injects Beads task state into every compaction event. Even after compression, agents will still see:
+- Current in-progress issue
+- Blocked issues
+- Ready tasks
+
+This is automatic — no extra action needed.
+
+## Compaction Checklist
+
+Before compressing:
+- [ ] Any critical output still needed? Copy key parts to `memory/` first
+- [ ] Active Beads task ID noted? (will be preserved automatically)
+- [ ] Currently in the middle of a multi-file edit? Finish the file first, then compress
+
+After compressing:
+- [ ] Run `/dcp stats` to verify savings
+- [ ] Continue task normally
+
+## Anti-patterns
+
+- ❌ Waiting until red zone (> 80%) — compress early, compress often
+- ❌ Using prune/distill commands — they do not exist in beta
+- ❌ Compressing during an active `multiedit` or write batch — finish writes first

package/skill/context-engineering/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: context-engineering
+description: Use when designing how information should flow through context — what to include, exclude, protect, and compress. DCP beta compress-only model.
+---
+
+# Context Engineering (DCP Beta)
+
+## Model
+
+DCP beta: **single compress tool** at `@tarquinen/opencode-dcp@beta`.  
+There is no `distill` or `prune`. All context reduction goes through `compress`.
+
+## Layers of Context Control
+
+```
+Session start    → beads-context hook injects task state
+                 → memory-digest hook injects project observations
+Mid-session      → /dcp compress (DCP) + truncator hook (output limits)
+Session end      → /dcp sweep + /handoff (disk persistence)
+Compaction event → OpenCode internal + beads-context preservation
+```
+
+## What to Keep vs. Compress
+
+| Content | Strategy |
+|---------|----------|
+| Current task (Beads state) | **Always keep** — auto-protected |
+| Skill content just loaded | Keep until task using it is done |
+| Subagent results (`task` tool) | **Always keep** — auto-protected |
+| Repeated tool outputs (same file read multiple times) | Compress — DCP deduplication handles this |
+| Error traces from resolved issues | Compress — DCP `purgeErrors` strategy |
+| Old superseded file writes | Compress — DCP `supersedeWrites` strategy |
+
+## DCP Strategies Reference
+
+| Strategy | What it removes | Default |
+|----------|----------------|---------|
+| `deduplication` | Repeated identical tool outputs | enabled |
+| `supersedeWrites` | Earlier versions of the same file write | enabled |
+| `purgeErrors` | Tool errors older than N turns | enabled (4 turns) |
+
+## Protecting Critical Context
+
+Add to `.opencode/dcp.jsonc` → `protectedToolNames` to prevent DCP from compressing specific tool outputs:
+
+```jsonc
+"protectedToolNames": [
+  "task", "skill", "todowrite", "todoread",
+  "compress", "batch", "plan_enter", "plan_exit"
+]
+```
+
+Default protected tools are set in `.opencode/dcp.jsonc`. Do not remove them.
+
+## Token Budget Signals
+
+Watch for DCP nudges — when `nudgeFrequency: 5` is hit, DCP will suggest compression.  
+At `iterationNudgeThreshold: 15`, it becomes more insistent (still `soft` force — not automatic).
+
+## Common Patterns
+
+### Pattern 1: Long research task
+```
+Start → /dcp stats (baseline)
+→ multiple @research / @explore calls
+→ context yellow → /dcp compress
+→ continue
+→ done → /dcp sweep (cleanup)
+```
+
+### Pattern 2: Multi-packet implementation
+```
+Before each new packet → /dcp stats
+→ if > 55% → /dcp compress before starting packet
+→ complete packet → evidence bundle
+→ repeat
+```
+
+### Pattern 3: Session handoff
+```
+Task complete or blocked
+→ /dcp compress (reduce context noise)
+→ /handoff (persist state to disk)
+→ beads-village_done or leave open
+→ end session
+```
+
+## Anti-patterns
+
+- ❌ Referencing `/dcp prune` or `/dcp distill` — removed in beta
+- ❌ Expecting automatic compression — `permission: "ask"` means DCP waits for approval
+- ❌ Loading large skill files repeatedly — load once, reference by name after
+- ❌ Ignoring DCP nudges — they are signals, not noise

package/skill/context-management/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: context-management
+description: Use when context is growing large or you need to decide how to handle token pressure. Compress-first workflow with DCP beta.
+---
+
+# Context Management (DCP Beta)
+
+## Core Principle
+
+DCP beta uses a **single `compress` tool**. There is no `prune` or `distill`.  
+When context pressure builds: **compress first, then handoff if needed**.
+
+## Context Pressure Thresholds
+
+| Level | Context % | Action |
+|-------|-----------|--------|
+| 🟢 Green | < 40% | Normal — no action needed |
+| 🟡 Yellow | 40–65% | Run `/dcp stats` to inspect; offload non-critical findings to `memory/` |
+| 🟠 Orange | 65–80% | Run `/dcp compress` before continuing; consider `/handoff` if complex work remains |
+| 🔴 Red | > 80% | Run `/dcp sweep` immediately, write `/handoff`, end session |
+
+## DCP Commands
+
+```
+/dcp stats       # Token breakdown and savings summary
+/dcp context     # Full context breakdown by source
+/dcp compress    # Compress context (asks permission first by default)
+/dcp sweep       # Aggressive compression for critical-level pressure
+```
+
+## Decision Flow
+
+```
+Context pressure detected?
+   │
+   ├── Yellow → /dcp stats → is it tool output noise? → /dcp compress
+   │
+   ├── Orange → /dcp compress → continue task → if still growing → /handoff
+   │
+   └── Red    → /dcp sweep → /handoff → end session
+```
+
+## What DCP Protects (auto-protected tools)
+
+DCP will **never** prune output from these tools:
+
+- `task` — subagent results
+- `skill` — skill loads
+- `todowrite` / `todoread` — in-session task state
+- `compress` — DCP's own operations
+- `batch` — batched tool calls
+- `plan_enter` / `plan_exit` — plan mode boundaries
+
+## Rules
+
+- ✅ Compress when context > 65%
+- ✅ Use `/dcp stats` proactively — do not wait until red
+- ✅ Combine with `session-management` skill for handoff triggers
+- ❌ Do NOT run `/dcp prune` or `/dcp distill` — unsupported in beta
+- ❌ Do NOT let context hit 90%+ without `/dcp sweep` + `/handoff`
+
+## Config Reference
+
+Project-level config: `.opencode/dcp.jsonc`
+
+Key settings:
+- `compress.permission: "ask"` — DCP prompts before compressing
+- `nudgeFrequency: 5` — nudge after every 5 iterations
+- `iterationNudgeThreshold: 15` — force nudge after 15 iterations
+- `nudgeForce: "soft"` — suggests, does not force

package/dist/beads-context.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=beads-context.test.d.ts.map

package/dist/beads-context.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"beads-context.test.d.ts","sourceRoot":"","sources":["../src/beads-context.test.ts"],"names":[],"mappings":""}

package/dist/cli.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=cli.test.d.ts.map

package/dist/cli.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"cli.test.d.ts","sourceRoot":"","sources":["../src/cli.test.ts"],"names":[],"mappings":""}

package/dist/clilog.test.d.ts

@@ -1,12 +0,0 @@
-/**
- * Integration test: cliLog + hookErr route through client.app.log
- *
- * Validates that:
- *  1. cliLog() calls ctx.client.app.log with correct shape
- *  2. hookErr() calls ctx.client.app.log with level="error" and formatted message
- *  3. showToast() calls ctx.client.tui.showToast with correct shape
- *  4. When client.app.log throws, cliLog falls back to console.error (doesn't rethrow)
- *  5. Toast failures don't break hook flow (returns false, doesn't throw)
- */
-export {};
-//# sourceMappingURL=clilog.test.d.ts.map

package/dist/clilog.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"clilog.test.d.ts","sourceRoot":"","sources":["../src/clilog.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/dist/config.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=config.test.d.ts.map

package/dist/config.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"config.test.d.ts","sourceRoot":"","sources":["../src/config.test.ts"],"names":[],"mappings":""}

package/dist/hooks/tilth-reading.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=tilth-reading.test.d.ts.map

package/dist/hooks/tilth-reading.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"tilth-reading.test.d.ts","sourceRoot":"","sources":["../../src/hooks/tilth-reading.test.ts"],"names":[],"mappings":""}