opencodekit 0.17.2 → 0.17.4

package/dist/index.js

@@ -759,7 +759,7 @@ var cac = (name = "") => new CAC(name);
 // package.json
 var package_default = {
   name: "opencodekit",
-  version: "0.17.2",
+  version: "0.17.4",
   description: "CLI tool for bootstrapping and managing OpenCodeKit projects",
   keywords: ["agents", "cli", "mcp", "opencode", "opencodekit", "template"],
   license: "MIT",

package/dist/template/.opencode/AGENTS.md

@@ -132,6 +132,48 @@ For major tracked work:
 - Use available tools to remove noise
 - Persist important decisions and state to memory
 
+### Token Budget
+
+| Phase             | Target  | Action                                     |
+| ----------------- | ------- | ------------------------------------------ |
+| Starting work     | <50k    | Load only essential AGENTS.md + task spec  |
+| Mid-task          | 50-100k | Distill completed reads, keep active files |
+| Approaching limit | >100k   | Aggressive distill, prune remaining noise  |
+| Near capacity     | >150k   | Session restart with handoff               |
+
+### Tools
+
+- `distill` — Extract key info from tool outputs, then remove raw output (preferred)
+- `prune` — Remove tool outputs entirely (noise only, no preservation)
+
+### Rules
+
+1. **Distill at turn START** — not end (you know what's needed)
+2. **Batch operations** — accumulate candidates before acting
+3. **Protected content** — AGENTS.md, .opencode/, .beads/, config files
+
+---
+
+## Edit Protocol
+
+`str_replace` failures are the #1 source of LLM coding failures. Use structured edits:
+
+1. **LOCATE** — Use LSP tools (goToDefinition, findReferences) to find exact positions
+2. **READ** — Get fresh file content around target (offset: line-10, limit: 30)
+3. **VERIFY** — Confirm expected content exists before editing
+4. **EDIT** — Include 2-3 unique context lines before/after
+5. **CONFIRM** — Read back to verify edit succeeded
+
+### File Size Guidance
+
+| Size          | Strategy                          |
+| ------------- | --------------------------------- |
+| < 100 lines   | Full rewrite often easier         |
+| 100-400 lines | Structured edit with good context |
+| > 400 lines   | Strongly prefer structured edits  |
+
+**Use the `structured-edit` skill for complex edits.**
+
 ---
 
 ## Output Style

package/dist/template/.opencode/agent/explore.md

@@ -35,6 +35,14 @@ Find relevant files, symbols, and usage paths quickly for the caller.
 - Prefer semantic lookup (LSP) before broad text search when it improves precision
 - Stop when you can answer with concrete evidence or when additional search only repeats confirmed paths
 
+## Before You Explore
+
+- **Be certain**: Only explore what's needed for the task at hand
+- **Don't over-explore**: Stop when you have enough evidence to answer
+- **Use LSP first**: Start with goToDefinition/findReferences before grep
+- **Stay scoped**: Don't explore files outside the task scope
+- **Cite evidence**: Every finding needs file:line reference
+
 ## Workflow
 
 1. Discover candidate files with `glob` or `workspaceSymbol`

package/dist/template/.opencode/agent/scout.md

@@ -45,6 +45,14 @@ Find trustworthy external references quickly and return concise, cited guidance.
 - Cite every non-trivial claim
 - Prefer high-signal synthesis over long dumps
 
+## Before You Scout
+
+- **Verify memory first**: Always check memory-search before external research
+- **Use source hierarchy**: Official docs > source code > maintainer articles > community posts
+- **Don't over-research**: Stop when you have medium+ confidence
+- **Cite everything**: Every claim needs a source
+- **Synthesize don't dump**: Return recommendations, not raw facts
+
 ## Source Quality Hierarchy
 
 Rank sources in this order:

package/dist/template/.opencode/command/create.md

@@ -26,7 +26,29 @@ skill({ name: "prd" }); // PRD template guidance
 | `<description>` | required      | What to build/fix (quoted string)  |
 | `--type`        | auto-detected | Override: epic, feature, task, bug |
 
----
+## Determine Input Type
+
+| Input Type  | Detection            | Action                        |
+| ----------- | -------------------- | ----------------------------- |
+| Quoted text | `"description here"` | Create PRD from description   |
+| Short form  | Simple string        | Ask for more detail if needed |
+| `--type`    | Flag provided        | Use provided type             |
+
+## Before You Create
+
+- **Be certain**: Only create beads you're confident have clear scope
+- **Don't over-spec**: If the description is vague, ask clarifying questions first
+- **Check duplicates**: Always run Phase 1 duplicate check
+- **No implementation**: This command creates specs only, don't write code
+- **Verify PRD**: Before saving, verify all sections are filled (no placeholders)
+
+## Available Tools
+
+| Tool      | Use When                                     |
+| --------- | -------------------------------------------- |
+| `explore` | Finding patterns in codebase, affected files |
+| `scout`   | External research, best practices            |
+| `br`      | Creating and managing beads                  |
 
 ## Phase 1: Duplicate Check
 

package/dist/template/.opencode/command/plan.md

@@ -28,6 +28,14 @@ skill({ name: "writing-plans" }); // TDD plan format
 | `<bead-id>`      | required | The bead to plan                  |
 | `--create-beads` | false    | Create child beads for each phase |
 
+## Before You Plan
+
+- **Be certain**: Only create tasks you're confident about
+- **Don't over-plan**: If the PRD is clear, trust it
+- **Budget context**: Target ~50% context per execution
+- **Split signals**: Create child beads for complex work
+- **Vertical slices**: Each task should cover one feature end-to-end
+
 ## Phase 1: Guards
 
 ```bash

package/dist/template/.opencode/command/research.md

@@ -28,6 +28,32 @@ skill({ name: "deep-research" });
 
 Default depth: ~30 tool calls for moderate exploration.
 
+## Determine Input Type
+
+| Input Type | Detection                   | Action                            |
+| ---------- | --------------------------- | --------------------------------- |
+| Bead ID    | Matches `br-xxx` or numeric | Research within that bead context |
+| Topic      | String                      | Standalone research               |
+
+## Before You Research
+
+- **Be certain**: Only research what you need for implementation
+- **Don't over-research**: Stop when you have enough to proceed
+- **Use source priority**: Codebase → Docs → Source → GitHub → Web
+- **Verify confidence**: Medium+ confidence required before stopping
+- **Document findings**: Write to research.md for beads, report for topics
+
+## Available Tools
+
+| Tool         | Use When                        |
+| ------------ | ------------------------------- |
+| `explore`    | Codebase patterns, LSP analysis |
+| `scout`      | External docs, best practices   |
+| `context7`   | Official API references         |
+| `opensrc`    | Package source code inspection  |
+| `codesearch` | Real-world usage examples       |
+| `grepsearch` | GitHub code search              |
+
 ## Phase 1: Load Context
 
 If argument is a bead ID:

package/dist/template/.opencode/command/review-codebase.md

@@ -13,7 +13,49 @@ skill({ name: "beads" });
 skill({ name: "requesting-code-review" });
 ```
 
-## Phase 1: Determine Scope
+## Determine Input Type
+
+| Input Type            | Detection                    | Action                     |
+| --------------------- | ---------------------------- | -------------------------- |
+| No arguments          | Default                      | Review uncommitted changes |
+| Commit hash (40-char) | SHA pattern                  | `git show <hash>`          |
+| Branch name           | String, not matching above   | `git diff main...HEAD`     |
+| PR URL/number         | Contains "github.com" or "#" | `gh pr diff`               |
+
+## Before You Review
+
+- **Be certain**: Only flag issues you can verify with tools
+- **Don't invent problems**: If an edge case isn't specified, don't flag it
+- **Don't be a zealot about style**: Unless it violates project conventions, don't flag
+- **Review the changes**: Don't review pre-existing code that wasn't modified
+- **Investigate first**: If unsure, use explore/scout agents before flagging
+
+## Available Tools
+
+| Tool         | Use When                                |
+| ------------ | --------------------------------------- |
+| `explore`    | Finding patterns in codebase, prior art |
+| `scout`      | External research, best practices       |
+| `lsp`        | Finding symbol definitions, references  |
+| `grep`       | Finding code patterns                   |
+| `codesearch` | Real-world usage examples               |
+
+## Phase 1: Gather Context
+
+```bash
+git status --short
+git diff --cached  # staged
+git diff           # unstaged
+```
+
+For each changed file:
+
+- Read the full file to understand context
+- Don't rely on diff alone — code that looks wrong in isolation may be correct
+
+If bead provided, read `.beads/artifacts/$ID/prd.md` to review against spec.
+
+## Phase 2: Determine Scope
 
 | Input                    | Scope                 | How to Get Code           |
 | ------------------------ | --------------------- | ------------------------- |

package/dist/template/.opencode/command/ship.md

@@ -19,39 +19,32 @@ skill({ name: "beads" });
 skill({ name: "verification-before-completion" });
 ```
 
-## Deviation Rules (Auto-Fix Without Permission)
-
-While executing, you WILL discover work not in the plan. Apply these rules automatically:
-
-**RULE 1: Auto-fix bugs** (broken behavior, errors, logic issues)
-
-- Wrong queries, type errors, null pointer exceptions
-- Fix inline → verify → continue task
-
-**RULE 2: Auto-add missing critical functionality** (validation, auth, error handling)
-
-- Missing input validation, no auth on protected routes
-- No error handling, missing null checks
-- These are correctness requirements, not features
-
-**RULE 3: Auto-fix blocking issues** (missing deps, wrong types, broken imports)
-
-- Missing dependency, wrong types, broken imports
-- Missing env var, DB connection error
-- Fix to unblock task completion
-
-**RULE 4: ASK about architectural changes** (new tables, library switches, major refactors)
-
-- New DB table (not column), major schema changes
-- Switching libraries/frameworks, changing auth approach
-- Breaking API changes, new infrastructure
-- STOP → report to user with: what found, proposed change, impact
-
-**Rule Priority:**
-
-1. Rule 4 applies → STOP (user decision required)
-2. Rules 1-3 apply → Fix automatically, track deviation
-3. Genuinely unsure → Treat as Rule 4 (ask)
+## Determine Input Type
+
+| Input Type | Detection                   | Action                     |
+| ---------- | --------------------------- | -------------------------- |
+| Bead ID    | Matches `br-xxx` or numeric | Ship that bead             |
+| Path       | File/directory path         | Not supported for ship     |
+| `all`      | Keyword                     | Ship all in_progress beads |
+
+## Before You Ship
+
+- **Be certain**: Only ship if all tasks pass verification
+- **Don't skip gates**: Build, test, lint, typecheck are non-negotiable
+- **Run the review**: Always spawn review agent before closing
+- **Verify goals**: Tasks completing ≠ goals achieved (use goal-backward verification)
+- **Commit before close**: Per-task commits required, don't ship without git history
+- **Ask before closing**: Never close bead without user confirmation
+
+## Available Tools
+
+| Tool      | Use When                                  |
+| --------- | ----------------------------------------- |
+| `explore` | Finding patterns in codebase, prior art   |
+| `scout`   | External research, best practices         |
+| `lsp`     | Finding symbol definitions, references    |
+| `grep`    | Finding code patterns                     |
+| `task`    | Spawning subagents for parallel execution |
 
 ## Phase 1: Guards
 

package/dist/template/.opencode/command/start.md

@@ -26,6 +26,21 @@ skill({ name: "prd-task" }); // PRD → executable tasks
 | `<bead-id>`  | required | The bead to start            |
 | `--worktree` | false    | Create isolated git worktree |
 
+## Determine Input Type
+
+| Input Type | Detection                   | Action                  |
+| ---------- | --------------------------- | ----------------------- |
+| Bead ID    | Matches `br-xxx` or numeric | Start that bead         |
+| Path       | File/directory path         | Not supported for start |
+
+## Before You Start
+
+- **Be certain**: Only start beads with valid PRD (check Phase 2)
+- **Check workspace**: Don't start if uncommitted changes exist (Phase 1)
+- **One task at a time**: Warn if other tasks in progress
+- **Validate spec**: Verify prd.md exists and has real content
+- **Ask about workspace**: Let user choose branch/worktree strategy
+
 ## Phase 1: Pre-flight
 
 ```bash

package/dist/template/.opencode/command/status.md

@@ -23,7 +23,29 @@ Quick project status dashboard. Runs read-only commands and reports state.
 skill({ name: "beads" });
 ```
 
----
+## Determine Input Type
+
+| Input Type   | Detection     | Action              |
+| ------------ | ------------- | ------------------- |
+| No arguments | Default       | Show full dashboard |
+| `--git`      | Flag provided | Git state only      |
+| `--sessions` | Flag provided | Sessions only       |
+
+## Before You Status
+
+- **Be certain**: This is a read-only command, no changes are made
+- **Use actual data**: Don't invent data, use real command output
+- **No modifications**: Don't create beads or modify state from status
+- **Single recommendation**: Only suggest ONE next action
+
+## Available Tools
+
+| Tool            | Use When                          |
+| --------------- | --------------------------------- |
+| `br`            | Task status and stats             |
+| `git`           | Git state and history             |
+| `list_sessions` | Recent sessions                   |
+| `action-queue`  | Pending approvals and ready tasks |
 
 ## Phase 1: Gather State (Parallel)
 

package/dist/template/.opencode/command/verify.md

@@ -23,6 +23,21 @@ skill({ name: "verification-before-completion" });
 | `--quick`   | false    | Gates only, skip coherence check |
 | `--fix`     | false    | Auto-fix lint/format issues      |
 
+## Determine Input Type
+
+| Input Type | Detection                   | Action                              |
+| ---------- | --------------------------- | ----------------------------------- |
+| Bead ID    | Matches `br-xxx` or numeric | Check implementation vs PRD in bead |
+| Path       | File/directory path         | Verify that specific path           |
+| `all`      | Keyword                     | Verify all in-progress work         |
+
+## Before You Verify
+
+- **Be certain**: Only flag issues you can verify with tools
+- **Don't invent problems**: If an edge case isn't in the PRD, don't flag it
+- **Run the gates**: Build, test, lint, typecheck are non-negotiable
+- **Use project conventions**: Check `package.json` scripts first
+
 ## Phase 1: Gather Context
 
 ```bash
@@ -32,6 +47,12 @@ ls .beads/artifacts/$ARGUMENTS/
 
 Read the PRD and any other artifacts (plan.md, research.md, design.md).
 
+**Verify guards:**
+
+- [ ] Bead is `in_progress`
+- [ ] `prd.md` exists
+- [ ] You have read the full PRD
+
 ## Phase 2: Completeness
 
 Extract all requirements/tasks from the PRD and verify each is implemented:

package/dist/template/.opencode/dcp.jsonc

@@ -1,82 +1,83 @@
 {
-  "$schema": "https://raw.githubusercontent.com/Opencode-DCP/opencode-dynamic-context-pruning/master/dcp.schema.json",
-  "enabled": true,
-  "debug": false,
-  // "minimal" shows prune activity without noise; "detailed" shows token counts
-  "pruneNotification": "detailed",
-  // "chat" (in-conversation) or "toast" (system notification)
-  "pruneNotificationType": "toast",
-  // Commands: /dcp context, /dcp stats, /dcp sweep
-  "commands": {
-    "enabled": true,
-    // Protect these from /dcp sweep
-    "protectedTools": ["observation", "memory-update", "memory-search"],
-  },
-  "turnProtection": {
-    "enabled": true,
-    "turns": 4,
-  },
-  // Protected file patterns - never auto-prune reads of these files
-  "protectedFilePatterns": [
-    "**/.env*",
-    "**/AGENTS.md",
-    "**/.opencode/**",
-    "**/.beads/**",
-    "**/package.json",
-    "**/tsconfig.json",
-    "**/biome.json",
-  ],
-  "tools": {
-    "settings": {
-      "nudgeEnabled": true,
-      "nudgeFrequency": 10,
-      // v2.0.1: percentage support - 90% of model's 128k context
-      "contextLimit": 200000,
-      // Protect state-modifying and critical workflow tools
-      // LSP excluded: ephemeral exploration, prune after understanding
-      "protectedTools": [
-        "write",
-        "edit",
-        "memory-update",
-        "observation",
-        "skill",
-        "skill_mcp",
-        "task",
-        "batch",
-        "todowrite",
-        "todoread",
-      ],
-    },
-    // v2.0.0: permission model - "allow", "ask", or "deny"
-    "prune": {
-      "permission": "allow",
-    },
-    "distill": {
-      "permission": "allow",
-      "showDistillation": false,
-    },
-    "compress": {
-      // v2.1.1: compress enabled with improved boundary matching
-      "permission": "allow",
-      "showCompression": true,
-    },
-  },
-  "strategies": {
-    // Dedup = zero LLM cost, high impact - always enable
-    "deduplication": {
-      "enabled": true,
-      "protectedTools": [],
-    },
-    // Supersede writes = zero cost, removes redundant write inputs after read
-    // Note: default changed to false in beta, we explicitly enable
-    "supersedeWrites": {
-      "enabled": true,
-    },
-    // Purge error inputs after N turns
-    "purgeErrors": {
-      "enabled": true,
-      "turns": 4,
-      "protectedTools": [],
-    },
-  },
+	"$schema": "https://raw.githubusercontent.com/Opencode-DCP/opencode-dynamic-context-pruning/master/dcp.schema.json",
+	"enabled": true,
+	"debug": false,
+	// "minimal" shows prune activity without noise; "detailed" shows token counts
+	"pruneNotification": "detailed",
+	// "chat" (in-conversation) or "toast" (system notification)
+	"pruneNotificationType": "toast",
+	// Commands: /dcp context, /dcp stats, /dcp sweep
+	"commands": {
+		"enabled": true,
+		// Protect these from /dcp sweep
+		"protectedTools": ["observation", "memory-update", "memory-search"]
+	},
+	"turnProtection": {
+		"enabled": true,
+		"turns": 4
+	},
+	// Protected file patterns - never auto-prune reads of these files
+	"protectedFilePatterns": [
+		"**/.env*",
+		"**/AGENTS.md",
+		"**/.opencode/**",
+		"**/.beads/**",
+		"**/package.json",
+		"**/tsconfig.json",
+		"**/biome.json"
+	],
+	"tools": {
+		"settings": {
+			"nudgeEnabled": true,
+			"nudgeFrequency": 10,
+			// v2.0.1: percentage support - 80% of model's context (most models = 128k)
+			"contextLimit": "80%",
+			// Protect state-modifying and critical workflow tools
+			// LSP excluded: ephemeral exploration, prune after understanding
+			"protectedTools": [
+				"write",
+				"edit",
+				"memory-update",
+				"observation",
+				"skill",
+				"skill_mcp",
+				"task",
+				"batch",
+				"todowrite",
+				"todoread"
+			]
+		},
+		// v2.0.0: permission model - "allow", "ask", or "deny"
+		"prune": {
+			"permission": "allow"
+		},
+		"distill": {
+			"permission": "allow",
+			"showDistillation": false
+		},
+		"compress": {
+			// v2.1.1: compress can have boundary matching issues - use ask for safety
+			"permission": "ask",
+			"showCompression": false
+		}
+	},
+	// Auto strategies - TOP LEVEL, not under tools
+	"strategies": {
+		// Dedup = zero LLM cost, high impact - always enable
+		"deduplication": {
+			"enabled": true,
+			"protectedTools": []
+		},
+		// Supersede writes = zero cost, removes redundant write inputs after read
+		// Note: default changed to false in beta, we explicitly enable
+		"supersedeWrites": {
+			"enabled": true
+		},
+		// Purge error inputs after N turns
+		"purgeErrors": {
+			"enabled": true,
+			"turns": 4,
+			"protectedTools": []
+		}
+	}
 }

package/dist/template/.opencode/memory/project/gotchas.md

@@ -1,12 +1,48 @@
 ---
 purpose: Footguns, edge cases, and warnings discovered during development
-updated: 2026-02-04
+updated: 2026-02-12
 ---
 
 # Gotchas
 
 Track unexpected behaviors, edge cases, and warnings here. Update when you hit something surprising.
 
+## LLM Coding (Harness Problem)
+
+The edit tool (`str_replace`) is the #1 source of failures in LLM coding. Models fail at reproducing content with exact whitespace/encoding, not at understanding tasks.
+
+### Edit Tool Failures
+
+- **Whitespace mismatch** — Tabs vs spaces, trailing spaces, line endings (CRLF vs LF)
+- **Content changed** — File modified since last read
+- **Multiple matches** — Same string appears twice, edit fails
+- **Stale context** — Editing from memory instead of fresh read
+
+### Mitigation Strategies
+
+1. **Always read fresh** before editing — no assumptions
+2. **Use LSP tools** to locate symbols precisely (goToDefinition, findReferences)
+3. **Include unique context** — 2-3 lines before/after for uniqueness
+4. **Prefer smaller files** — <400 lines reduces edit complexity
+5. **Verify after edit** — read back to confirm success
+
+### File Size Guidance
+
+| Size          | Strategy                                   |
+| ------------- | ------------------------------------------ |
+| < 100 lines   | Full rewrite often easier than str_replace |
+| 100-400 lines | Structured edit with good context          |
+| > 400 lines   | Strongly prefer structured edits           |
+
+**Use the `structured-edit` skill for reliable edits.**
+
+### Context Hygiene
+
+- Distill large tool outputs immediately after use
+- Prune irrelevant reads before proceeding
+- Token budget: <50k start → 50-100k mid → >150k restart session
+- Subagent outputs can leak tokens — be aggressive about distilling
+
 ## OpenCode Config
 
 - **`compaction` key invalid**: Not in official schema at opencode.ai/config.json. Remove if present.

package/dist/template/.opencode/opencode.json

@@ -3,18 +3,18 @@
 	"agent": {
 		"build": {
 			"description": "Primary development agent with full codebase access",
-			"model": "opencode/kimi-k2.5-free"
+			"model": "opencode/minimax-m2.5-free"
 		},
 		"compaction": {
 			"description": "Session summarizer for context continuity across compactions"
 		},
 		"explore": {
 			"description": "Fast codebase search specialist",
-			"model": "opencode/minimax-m2.1-free"
+			"model": "opencode/minimax-m2.5-free"
 		},
 		"general": {
 			"description": "General-purpose subagent for fast, well-defined tasks; delegates complexity quickly",
-			"model": "opencode/kimi-k2.5-free"
+			"model": "opencode/minimax-m2.5-free"
 		},
 		"looker": {
 			"description": "Media extraction specialist for images, PDFs, diagrams",
@@ -34,7 +34,7 @@
 		},
 		"scout": {
 			"description": "External research specialist for library docs and patterns",
-			"model": "opencode/minimax-m2.1-free"
+			"model": "opencode/kimi-k2.5-free"
 		},
 		"vision": {
 			"description": "Visual content specialist for multimodal analysis and UI/UX guidance",
@@ -156,6 +156,30 @@
 		"@franlol/opencode-md-table-formatter@0.0.3"
 	],
 	"provider": {
+		"modal": {
+			"options": {
+				"baseURL": "https://api.us-west-2.modal.direct/v1",
+				"apiKey": "{env:MODAL_API_KEY}"
+			},
+			"name": "Modal",
+			"models": {
+				"zai-org/GLM-5-FP8": {
+					"name": "GLM-5",
+					"reasoning": true,
+					"options": {
+						"reasoningEffort": "high",
+						"reasoningSummary": "true",
+						"temperature": 1,
+						"top_k": 40,
+						"top_p": 0.95,
+						"maxOutputTokens": 131072,
+						"thinking": {
+							"type": "enabled"
+						}
+					}
+				}
+			}
+		},
 		"github-copilot": {
 			"models": {
 				"claude-haiku-4.5": {
@@ -997,7 +1021,7 @@
 					"options": {
 						"reasoningEffort": "high",
 						"reasoningSummary": "true",
-						"temperature": 1.0,
+						"temperature": 1,
 						"top_k": 40,
 						"top_p": 0.95,
 						"maxOutputTokens": 131072,

package/dist/template/.opencode/package.json

@@ -11,7 +11,7 @@
     "type-check": "tsc --noEmit"
   },
   "dependencies": {
-    "@opencode-ai/plugin": "1.1.60"
+    "@opencode-ai/plugin": "1.1.62"
   },
   "devDependencies": {
     "@types/node": "^25.1.0",

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

@@ -1,20 +1,47 @@
 ---
 name: context-management
-description: Use when context is growing large, needing to prune/distill tool outputs, or managing conversation size - covers distill and prune tools with context budgets
+description: Use when context is growing large, needing to prune/distill tool outputs, or managing conversation size - covers DCP slash commands and context budgets
 ---
 
 # Context Management
 
-Manage conversation context to prevent degradation. Uses distill and prune tools.
+Manage conversation context to prevent degradation. Uses DCP plugin.
 
-## The Two Tools
+## DCP Integration
 
-| Tool      | Purpose                       | When to Use                              |
-| --------- | ----------------------------- | ---------------------------------------- |
-| `distill` | Extract key info, then remove | Large outputs with valuable details      |
-| `prune`   | Remove tool outputs (no save) | Noise, irrelevant reads, superseded info |
+This project uses the **DCP (Dynamic Context Pruning)** plugin. Prefer slash commands over tool calls for better reliability.
 
-**Distill is the favored tool.** It preserves knowledge while freeing context. Prune is for pure noise removal.
+### Slash Commands (Recommended)
+
+| Command                 | Purpose                                  | When to Use                         |
+| ----------------------- | ---------------------------------------- | ----------------------------------- |
+| `/dcp compress [focus]` | Collapse conversation range into summary | Phase complete, research done       |
+| `/dcp sweep [count]`    | Prune all tools since last user message  | Cleanup noise, quick prune          |
+| `/dcp distill [focus]`  | Distill key findings before removing     | Large outputs with valuable details |
+| `/dcp context`          | Show token breakdown by category         | Check context usage                 |
+| `/dcp stats`            | Show cumulative pruning stats            | Review efficiency                   |
+
+### Tool Calls (Fallback)
+
+Use tool calls when slash commands aren't suitable:
+
+| Tool       | Purpose                       | When to Use                              |
+| ---------- | ----------------------------- | ---------------------------------------- |
+| `distill`  | Extract key info, then remove | Large outputs with valuable details      |
+| `prune`    | Remove tool outputs (no save) | Noise, irrelevant reads, superseded info |
+| `compress` | Collapse conversation range   | When slash command fails                 |
+
+**Note:** Compress tool has boundary matching issues. Prefer `/dcp compress` slash command.
+
+## DCP Auto-Strategies
+
+DCP runs these automatically (zero LLM cost):
+
+- **Deduplication** — removes duplicate tool calls (same tool + same args)
+- **Supersede Writes** — removes write inputs when file is later read
+- **Purge Errors** — removes errored tool inputs after 4 turns
+
+You don't need to manually prune these.
 
 ## When to Evaluate
 
@@ -94,8 +121,15 @@ Auto-protected from pruning:
 ## Quick Reference
 
 ```
-DISTILL: Save + remove → distill({ targets: [{ id, distillation }] })
-PRUNE:   Remove noise  → prune({ ids: [...] })
+DCP SLASH COMMANDS (preferred):
+/dcp compress [focus]  → Collapse range into summary
+/dcp distill [focus]   → Distill key findings
+/dcp sweep [count]     → Prune all since last user
+/dcp context           → Show token breakdown
+
+TOOL CALLS (fallback):
+distill({ targets: [{ id, distillation }] })
+prune({ ids: [...] })
 
 BUDGET: <50k start → 50-100k mid → >100k distill → >150k restart
 TIMING: Manage at turn START, not turn END

package/dist/template/.opencode/skill/obsidian/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: obsidian
+description: Use when working with Obsidian vault via MCP - read/write notes, search, tag management, and vault operations
+mcp:
+  server: @mauricio.wolff/mcp-obsidian
+  args: ["{env:OBSIDIAN_VAULT_PATH}"]
+---
+
+# Obsidian Vault (MCP)
+
+MCP server for safe Obsidian vault access. Read/write notes, search, manage tags.
+
+## Available Tools
+
+### Read Operations
+
+| Tool                  | Purpose                           | Arguments                                         |
+| --------------------- | --------------------------------- | ------------------------------------------------- |
+| `read_note`           | Read note with parsed frontmatter | `path`, `prettyPrint`                             |
+| `read_multiple_notes` | Batch read (max 10)               | `paths[]`, `includeContent`, `includeFrontmatter` |
+| `get_frontmatter`     | Extract only frontmatter          | `path`                                            |
+| `get_notes_info`      | Get metadata without content      | `paths[]`                                         |
+| `list_directory`      | List files and directories        | `path`                                            |
+
+### Write Operations
+
+| Tool                 | Purpose                               | Arguments                                |
+| -------------------- | ------------------------------------- | ---------------------------------------- |
+| `write_note`         | Write note (overwrite/append/prepend) | `path`, `content`, `frontmatter`, `mode` |
+| `update_frontmatter` | Update frontmatter only               | `path`, `frontmatter`, `merge`           |
+| `delete_note`        | Delete note (requires confirmation)   | `path`, `confirmPath`                    |
+| `move_note`          | Move/rename note                      | `oldPath`, `newPath`, `overwrite`        |
+
+### Search & Tags
+
+| Tool           | Purpose                       | Arguments                                              |
+| -------------- | ----------------------------- | ------------------------------------------------------ |
+| `search_notes` | Search by content/frontmatter | `query`, `limit`, `searchContent`, `searchFrontmatter` |
+| `manage_tags`  | Add/remove/list tags          | `path`, `operation`, `tags[]`                          |
+
+## Write Modes
+
+| Mode        | Description                           |
+| ----------- | ------------------------------------- |
+| `overwrite` | Replace entire file content (default) |
+| `append`    | Add content to end of file            |
+| `prepend`   | Add content to beginning of file      |
+
+## Usage Examples
+
+### Read Notes
+
+```typescript
+// Read a single note
+skill_mcp({
+  skill_name: "obsidian",
+  tool_name: "read_note",
+  arguments: '{"path": "projects/project-ideas.md"}',
+});
+
+// Read multiple notes
+skill_mcp({
+  skill_name: "obsidian",
+  tool_name: "read_multiple_notes",
+  arguments: '{"paths": ["note1.md", "note2.md"], "includeContent": true}',
+});
+
+// List directory
+skill_mcp({
+  skill_name: "obsidian",
+  tool_name: "list_directory",
+  arguments: '{"path": "Projects"}',
+});
+```
+
+### Write Notes
+
+```typescript
+// Create new note (overwrite)
+skill_mcp({
+  skill_name: "obsidian",
+  tool_name: "write_note",
+  arguments: `{
+    "path": "meeting-notes.md",
+    "content": "# Team Meeting\\n\\n## Agenda\\n- Project updates",
+    "frontmatter": {"title": "Team Meeting", "date": "2025-02-13", "tags": ["meetings", "team"]},
+    "mode": "overwrite"
+  }`,
+});
+
+// Append to existing note
+skill_mcp({
+  skill_name: "obsidian",
+  tool_name: "write_note",
+  arguments:
+    '{"path": "daily-log.md", "content": "\\n\\n## 3:00 PM\\n- Completed review", "mode": "append"}',
+});
+```
+
+### Search & Tags
+
+```typescript
+// Search notes
+skill_mcp({
+  skill_name: "obsidian",
+  tool_name: "search_notes",
+  arguments: '{"query": "machine learning", "limit": 5, "searchContent": true}',
+});
+
+// Add tags
+skill_mcp({
+  skill_name: "obsidian",
+  tool_name: "manage_tags",
+  arguments: '{"path": "research-notes.md", "operation": "add", "tags": ["important", "ai"]}',
+});
+
+// List tags
+skill_mcp({
+  skill_name: "obsidian",
+  tool_name: "manage_tags",
+  arguments: '{"path": "research-notes.md", "operation": "list"}',
+});
+```
+
+### Delete (Safe)
+
+```typescript
+// Delete requires confirmation (both paths must match)
+skill_mcp({
+  skill_name: "obsidian",
+  tool_name: "delete_note",
+  arguments: '{"path": "old-draft.md", "confirmPath": "old-draft.md"}',
+});
+```
+
+## Configuration
+
+### Environment Variable
+
+Set your vault path:
+
+```bash
+export OBSIDIAN_VAULT_PATH="/path/to/your/obsidian/vault"
+```
+
+Or configure in opencode.json:
+
+```json
+{
+  "mcp": {
+    "obsidian": {
+      "command": "npx",
+      "args": ["@mauricio.wolff/mcp-obsidian", "/path/to/vault"]
+    }
+  }
+}
+```
+
+## Security
+
+- Path traversal protection: prevents access outside vault
+- Auto-excludes: `.obsidian`, `.git`, `node_modules`
+- Frontmatter validation: blocks dangerous objects
+- Confirmation required for deletions
+
+## Common Use Cases
+
+| Task                 | Tool             | Example                                                                       |
+| -------------------- | ---------------- | ----------------------------------------------------------------------------- |
+| List vault files     | `list_directory` | `list_directory({ path: "" })`                                                |
+| Read specific note   | `read_note`      | `read_note({ path: "tasks/project.md" })`                                     |
+| Create/update note   | `write_note`     | `write_note({ path: "new.md", content: "...", mode: "overwrite" })`           |
+| Search notes         | `search_notes`   | `search_notes({ query: "API", limit: 10 })`                                   |
+| Add tags             | `manage_tags`    | `manage_tags({ path: "note.md", operation: "add", tags: ["urgent"] })`        |
+| Append to daily note | `write_note`     | `write_note({ path: "daily/2025-02-13.md", content: "...", mode: "append" })` |
+
+## Tips
+
+- Use `prettyPrint: true` for debugging, `false` (default) for production
+- Batch reads with `read_multiple_notes` (max 10)
+- Search supports content and frontmatter filtering
+- Frontmatter is auto-parsed on read

package/dist/template/.opencode/skill/obsidian/mcp.json

@@ -0,0 +1,22 @@
+{
+	"obsidian": {
+		"command": "npx",
+		"args": ["-y", "@mauricio.wolff/mcp-obsidian", "{env:OBSIDIAN_VAULT_PATH}"],
+		"env": {
+			"OBSIDIAN_VAULT_PATH": "{env:OBSIDIAN_VAULT_PATH}"
+		},
+		"includeTools": [
+			"read_note",
+			"read_multiple_notes",
+			"get_frontmatter",
+			"get_notes_info",
+			"list_directory",
+			"write_note",
+			"update_frontmatter",
+			"delete_note",
+			"move_note",
+			"search_notes",
+			"manage_tags"
+		]
+	}
+}

package/dist/template/.opencode/skill/structured-edit/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: structured-edit
+description: Use when editing files to reduce str_replace failures - combines LSP location with read-verify-edit pattern for reliable edits
+---
+
+# Structured Edit Protocol
+
+## Overview
+
+The `str_replace` edit tool is the #1 source of failures in LLM coding. Models reproduce content with subtle differences (whitespace, encoding, line endings) causing "string not found" errors.
+
+**Core principle:** Don't guess content — locate, read, verify, then edit.
+
+## Why This Exists
+
+`str_replace` failures happen when:
+
+| Cause                | Example                                    |
+| -------------------- | ------------------------------------------ |
+| Whitespace mismatch  | Tabs vs spaces, trailing spaces            |
+| Content changed      | File modified since last read              |
+| Multiple matches     | Same string appears twice in file          |
+| Encoding differences | Line endings (CRLF vs LF), invisible chars |
+| Stale context        | Editing from memory instead of fresh read  |
+
+**Result:** Wasted tokens on retries, frustrated developers, broken workflows.
+
+## The Protocol
+
+### Step 1: LOCATE
+
+Use LSP to find exact positions instead of guessing:
+
+```typescript
+// Find where a function is defined
+lsp({ operation: "goToDefinition", filePath, line, character });
+
+// Find all references to a symbol
+lsp({ operation: "findReferences", filePath, line, character });
+
+// Get all symbols in a file
+lsp({ operation: "documentSymbol", filePath, line: 1, character: 1 });
+
+// Search for symbol across workspace
+lsp({ operation: "workspaceSymbol", filePath, line: 1, character: 1 });
+```
+
+### Step 2: READ
+
+Get fresh file content at the located position:
+
+```typescript
+// Read context around target line
+read({ filePath, offset: line - 10, limit: 30 });
+```
+
+**Always include context** — don't just read the target line.
+
+### Step 3: VERIFY
+
+Confirm expected content exists at the location:
+
+```typescript
+// Check that what you expect is actually there
+if (!content.includes(expectedSubstring)) {
+  // STOP — investigate before proceeding
+}
+```
+
+### Step 4: EDIT
+
+Apply minimal, scoped change with unique context:
+
+```typescript
+// Include enough surrounding lines for uniqueness
+edit({
+  filePath,
+  oldString: "  // unique context before\n  targetLine\n  // unique context after",
+  newString: "  // unique context before\n  modifiedLine\n  // unique context after",
+});
+```
+
+**Guidelines:**
+
+- Include 2-3 lines before/after for uniqueness
+- Never use just the target line
+- Keep oldString minimal but unique
+
+### Step 5: CONFIRM
+
+Verify the edit succeeded:
+
+```typescript
+// Read back the modified section
+read({ filePath, offset: line - 5, limit: 15 });
+
+// Confirm content matches intent
+```
+
+## Red Flags — STOP
+
+If you catch yourself:
+
+- Editing without reading first
+- Assuming content hasn't changed
+- Using large multi-line oldString values
+- Skipping the verify step
+- Guessing line numbers without LSP
+
+**STOP.** Return to Step 1.
+
+## Best Practices
+
+### File Size Matters
+
+From research on the "harness problem":
+
+| File Size     | Strategy                                   |
+| ------------- | ------------------------------------------ |
+| < 100 lines   | Full rewrite often easier than str_replace |
+| 100-400 lines | Structured edit with good context          |
+| > 400 lines   | Strongly prefer structured edits           |
+
+**Prefer smaller files** — composition over monoliths.
+
+### Unique Context Selection
+
+```typescript
+// BAD: Non-unique, whitespace-sensitive
+oldString: "return result;";
+
+// GOOD: Unique with surrounding context
+oldString: "  // Calculate final value\n  const result = compute(input);\n  return result;";
+```
+
+### When to Use LSP vs Direct
+
+| Scenario                  | Approach              |
+| ------------------------- | --------------------- |
+| Finding function/class    | LSP goToDefinition    |
+| Finding all usages        | LSP findReferences    |
+| Modifying specific symbol | LSP + structured edit |
+| Large refactoring         | Consider full rewrite |
+| Simple one-line change    | Direct edit OK        |
+
+## Integration with Other Skills
+
+**Use with:**
+
+- `verification-before-completion` — Always verify edits succeeded
+- `systematic-debugging` — When edit failures indicate deeper issues
+- `defense-in-depth` — Add validation after structural changes
+
+## Quick Reference
+
+```
+LOCATE  → lsp({ operation: "goToDefinition" | "findReferences", ... })
+READ    → read({ filePath, offset: line-10, limit: 30 })
+VERIFY  → Check expected content exists
+EDIT    → edit({ oldString: "...unique context...", newString: "..." })
+CONFIRM → read() again to verify success
+```
+
+## The Bottom Line
+
+**Don't trust your memory. Don't guess content. Locate, read, verify, edit, confirm.**
+
+This protocol eliminates the #1 source of LLM coding failures.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencodekit",
-	"version": "0.17.2",
+	"version": "0.17.4",
 	"description": "CLI tool for bootstrapping and managing OpenCodeKit projects",
 	"keywords": ["agents", "cli", "mcp", "opencode", "opencodekit", "template"],
 	"license": "MIT",