opencodekit 0.17.3 → 0.17.5

package/dist/index.js

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

package/dist/template/.opencode/.version

@@ -0,0 +1 @@
+0.17.5

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.