opencodekit 0.20.3 → 0.20.5

package/dist/index.js

@@ -20,7 +20,7 @@ var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 //#endregion
 //#region package.json
-var version = "0.20.3";
+var version = "0.20.5";
 
 //#endregion
 //#region src/utils/license.ts

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

@@ -216,19 +216,20 @@ For complex delegations, write context to a file instead of inlining it in the `
 ```typescript
 // ❌ Token-expensive: inlining large context
 task({
-  prompt: `Here is the full plan:\n${longPlanContent}\n\nImplement task 3...`
+  prompt: `Here is the full plan:\n${longPlanContent}\n\nImplement task 3...`,
 });
 
 // ✅ Token-efficient: reference by path
 // Write context file first:
-write('.beads/artifacts/<id>/worker-context.md', contextContent);
+write(".beads/artifacts/<id>/worker-context.md", contextContent);
 // Then reference it:
 task({
-  prompt: `Read the context file at .beads/artifacts/<id>/worker-context.md\n\nImplement task 3 as described in that file.`
+  prompt: `Read the context file at .beads/artifacts/<id>/worker-context.md\n\nImplement task 3 as described in that file.`,
 });
 ```
 
 Use this pattern when:
+
 - Context exceeds ~500 tokens
 - Multiple subagents need the same context
 - Plan content, research findings, or specs need to be passed to workers
@@ -274,12 +275,12 @@ For major tracked work:
 
 ### Token Budget
 
-| Phase             | Target  | Action                                     |
-| ----------------- | ------- | ------------------------------------------ |
-| Starting work     | <50k    | Load only essential AGENTS.md + task spec  |
+| Phase             | Target  | Action                                       |
+| ----------------- | ------- | -------------------------------------------- |
+| Starting work     | <50k    | Load only essential AGENTS.md + task spec    |
 | Mid-task          | 50-100k | Compress completed phases, keep active files |
 | Approaching limit | >100k   | Aggressive compression, sweep stale noise    |
-| Near capacity     | >150k   | Session restart with handoff               |
+| Near capacity     | >150k   | Session restart with handoff                 |
 
 ### DCP Commands
 
@@ -298,7 +299,7 @@ For major tracked work:
 
 ## Edit Protocol
 
-`str_replace` failures are the #1 source of LLM coding failures. When tilth MCP is available with `--edit`, prefer hash-anchored edits (see below). Otherwise, use structured edits:
+`str_replace` failures are the #1 source of LLM coding failures. Use the `edit` tool (str_replace) and `patch` tool as the **primary** editing method. Use `tilth_tilth_edit` (hash-anchored edits) only as a **fallback** when str_replace fails. For all edits, follow the structured edit flow:
 
 1. **LOCATE** — Use LSP tools (goToDefinition, findReferences) to find exact positions
 2. **READ** — Get fresh file content around target (offset: line-10, limit: 30)
@@ -332,7 +333,7 @@ Files over ~500 lines become hard to maintain and review. Extract helpers, split
 
 ### Hash-Anchored Edits (MCP)
 
-When tilth MCP is available with `--edit` mode, use hash-anchored edits for higher reliability:
+When tilth MCP is available with `--edit` mode, use hash-anchored edits as a **fallback** when str_replace fails:
 
 1. **READ** via `tilth_read` — output includes `line:hash|content` format per line
 2. **EDIT** via `tilth_edit` — reference lines by their `line:hash` anchor
@@ -383,6 +384,10 @@ memory-admin({ operation: "status" })
 memory-admin({ operation: "capture-stats" })
 memory-admin({ operation: "distill-now" })
 memory-admin({ operation: "curate-now" })
+memory-admin({ operation: "lint" })          # Duplicates, contradictions, stale, orphans
+memory-admin({ operation: "index" })         # Generate memory catalog
+memory-admin({ operation: "compile" })       # Concept-clustered articles
+memory-admin({ operation: "log" })           # Append-only operation audit trail
 ```
 
 ### Session Tools

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

@@ -23,42 +23,10 @@ You are OpenCode, the best coding agent on the planet.
 
 You are an interactive CLI tool that helps users with software engineering tasks. Use the instructions below and the tools available to you to assist the user.
 
-# Tone and style
-
-- Only use emojis if the user explicitly requests it. Avoid using emojis in all communication unless asked.
-- Your output will be displayed on a command line interface. Your responses should be short and concise. You can use GitHub-flavored markdown for formatting, and will be rendered in a monospace font using the CommonMark specification.
-- Output text to communicate with the user; all text you output outside of tool use is displayed to the user. Only use tools to complete tasks. Never use tools like Bash or code comments as means to communicate with the user during the session.
-- NEVER create files unless they're absolutely necessary for achieving your goal. ALWAYS prefer editing an existing file to creating a new file. This includes markdown files.
-
-# Professional objectivity
-
-Prioritize technical accuracy and truthfulness over validating the user's beliefs. Focus on facts and problem-solving, providing direct, objective technical info without any unnecessary superlatives, praise, or emotional validation.
-
-# Task Management
-
-You have access to the TodoWrite tools to help you manage and plan tasks. Use these tools VERY frequently to ensure that you are tracking your tasks and giving the user visibility into your progress.
-
-# Tool usage policy
-
-- When doing file search, prefer to use the Task tool in order to reduce context usage.
-- You should proactively use the Task tool with specialized agents when the task at hand matches the agent's description.
-- Use specialized tools instead of bash commands when possible, as this provides a better user experience. For file operations, use dedicated tools: Read for reading files instead of cat/head/tail, Edit for editing instead of sed/awk, and Write for creating files instead of cat with heredoc or echo redirection. Reserve bash tools exclusively for actual system commands and terminal operations that require shell execution.
-- You can call multiple tools in a single response. If you intend to call multiple tools and there are no dependencies between them, make all independent tool calls in parallel.
-- VERY IMPORTANT: When exploring the codebase to gather context or to answer a question that is not a needle query for a specific file/class/function, it is CRITICAL that you use the Task tool instead of running search commands directly.
-
 # Code References
 
 When referencing specific functions or pieces of code include the pattern `file_path:line_number` to allow the user to easily navigate to the source code location.
 
-# Web Research Tool Priority
-
-When fetching content from URLs (docs, READMEs, web pages):
-
-1. **`webclaw` MCP tools** (primary) — `scrape`, `crawl`, `batch`, `brand`. Handles 403s, bot protection, 67% fewer tokens.
-2. **`webfetch`** (fallback) — only if webclaw is unavailable or returns an error.
-
-Never use `webfetch` as first choice when webclaw MCP is connected.
-
 # Build Agent
 
 **Purpose**: Primary execution coordinator — you ship working code, not promises.  

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

@@ -29,20 +29,6 @@ permission:
 
 You are opencode, an interactive CLI tool that helps users with software engineering tasks. Use the instructions below and the tools available to you to assist the user.
 
-# Tone and style
-
-- You should be concise, direct, and to the point.
-- Your output will be displayed on a command line interface. Use GitHub-flavored markdown.
-- Only use emojis if the user explicitly requests it.
-
-# Tool usage
-
-- Prefer specialized tools over shell for file operations:
-  - Use Read to view files, Edit to modify files, and Write only when needed.
-  - Use Glob to find files by name and Grep to search file contents.
-- Use Bash for terminal operations (git, npm/pnpm, builds, tests, running scripts).
-- Run tool calls in parallel when neither call needs the other's output; otherwise run sequentially.
-
 # Planning Guidelines
 
 - Analyze requirements deeply before creating a plan

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

@@ -37,46 +37,6 @@ You are a read-only review agent. You output severity-ranked findings with file:
 
 ## Task
 
-Review proposed code changes and identify actionable bugs, regressions, and security issues.
-
-## Rules
-
-- Never modify files
-- Never run destructive commands
-- Prioritize findings over summaries
-- Flag only discrete, actionable issues
-- Every finding must cite concrete evidence (`file:line`) and impact
-
-## Triage Criteria
-
-Only report issues that meet all of these:
-
-1. Meaningfully affects correctness, performance, security, or maintainability
-2. Is introduced or made materially worse by the reviewed change
-3. Is fixable without requiring unrealistic rigor for this codebase
-4. Is likely something the author would actually want to fix
-
-## Output
-
-Structure:
-
-- Findings (ordered by severity: P0, P1, P2, P3)
-- Evidence (`file:line`)
-- Impact scenario
-- Overall Correctness
-
-# Review Agent
-
-**Purpose**: Quality guardian — you find bugs before they find users.
-
-> _"Verification isn't pessimism; it's agency applied to correctness."_
-
-## Identity
-
-You are a read-only review agent. You output severity-ranked findings with file:line evidence only.
-
-## Task
-
 Review proposed code changes and identify actionable bugs, regressions, and security issues that the author would likely fix.
 
 ## Rules

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

@@ -16,6 +16,8 @@ Create a bead, write its specification (PRD), claim it, set up the workspace, an
 
 ```typescript
 skill({ name: "beads" });
+skill({ name: "memory-grounding" });
+skill({ name: "workspace-setup" });
 skill({ name: "prd" }); // PRD template guidance
 skill({ name: "prd-task" }); // PRD → executable tasks (Phase 8)
 ```
@@ -56,14 +58,7 @@ skill({ name: "prd-task" }); // PRD → executable tasks (Phase 8)
 
 ### Memory Search
 
-Search memory for prior work on the same topic before creating a new bead:
-
-```typescript
-memory - search({ query: "<description keywords>" });
-memory - search({ query: "<description keywords>", type: "decision" });
-```
-
-If memory shows a related decision or completed bead, inform the user before proceeding.
+Follow the [memory-grounding](../skill/memory-grounding/SKILL.md) skill protocol. Focus on: duplicate bead detection, prior decisions.
 
 ### Bead List Check
 
@@ -218,61 +213,16 @@ br update $BEAD_ID --status in_progress
 
 ### Create Branch
 
-Ask user how to handle workspace:
+### Workspace Setup
 
-```typescript
-question({
-  questions: [
-    {
-      header: "Workspace",
-      question: "How do you want to set up the workspace?",
-      options: [
-        {
-          label: "Create feature branch (Recommended)",
-          description: "git checkout -b feat/<bead-id>-<title>",
-        },
-        {
-          label: "Use current branch",
-          description: "Work on current branch",
-        },
-        {
-          label: "Create worktree",
-          description: "Isolated git worktree for this bead",
-        },
-      ],
-    },
-  ],
-});
-```
-
-**If feature branch selected:**
-
-Map bead type to branch prefix:
+Follow the [workspace-setup](../skill/workspace-setup/SKILL.md) skill protocol.
 
-| Bead Type | Branch Prefix |
-| --------- | ------------- |
-| feature   | feat          |
-| bug       | fix           |
-| task      | task          |
-| epic      | epic          |
-
-Create the branch:
-
-```bash
-# Example: feat/br-42-add-auth
-git checkout -b $PREFIX/$BEAD_ID-$TITLE_SLUG
-```
-
-Slugify the title (lowercase, spaces to hyphens) and use the bead type to determine the prefix.
-
-**If worktree selected:**
+Additionally offer a "Create worktree" option:
 
 ```typescript
 skill({ name: "using-git-worktrees" });
 ```
 
-**If current branch:** Continue without branch creation.
-
 ## Phase 9: Convert PRD to Tasks
 
 Use `prd-task` skill to convert PRD markdown → executable JSON (`prd.json`).
@@ -295,8 +245,8 @@ br comments add $BEAD_ID "Created prd.md with [N] tasks, [M] success criteria"
 
 ## Related Commands
 
-| Need               | Command       |
-| ------------------ | ------------- |
-| Research first     | `/research`   |
-| Plan after spec    | `/plan <id>`  |
-| Implement and ship | `/ship <id>`  |
+| Need               | Command      |
+| ------------------ | ------------ |
+| Research first     | `/research`  |
+| Plan after spec    | `/plan <id>` |
+| Implement and ship | `/ship <id>` |

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

@@ -18,6 +18,7 @@ Create a detailed implementation plan with TDD steps. Optional deep-planning bet
 
 ```typescript
 skill({ name: "beads" });
+skill({ name: "memory-grounding" });
 skill({ name: "writing-plans" }); // TDD plan format
 ```
 
@@ -44,12 +45,7 @@ Before touching the PRD or planning anything, load what the codebase already kno
 
 ### Step 1: Search institutional memory
 
-```typescript
-// Search for past decisions, patterns, gotchas related to this work
-memory_search({ query: "<bead-title or feature keywords>", limit: 5 });
-memory_search({ query: "<key technical concept from bead>", type: "bugfix", limit: 3 });
-memory_read({ file: "handoffs/last" }); // Check last session context
-```
+Follow the [memory-grounding](../skill/memory-grounding/SKILL.md) skill protocol. Focus on: bugfixes, existing plans (ask user before overwriting).
 
 If relevant observations found: incorporate them directly into the plan. Don't re-solve solved problems.
 
@@ -132,7 +128,10 @@ question({
       header: "Discovery Level",
       question: "Suggested discovery level based on PRD complexity. Proceed?",
       options: [
-        { label: "Deep (Recommended for complex work)", description: "Level 2-3: spawn scout + explore agents" },
+        {
+          label: "Deep (Recommended for complex work)",
+          description: "Level 2-3: spawn scout + explore agents",
+        },
         { label: "Standard", description: "Level 1: quick doc lookup" },
         { label: "Skip research", description: "Level 0: I know the codebase" },
       ],
@@ -347,8 +346,8 @@ br comments add $ARGUMENTS "Created plan.md: Level [N] discovery, [X] waves, [Y]
 
 ## Related Commands
 
-| Need           | Command       |
-| -------------- | ------------- |
-| Create spec    | `/create`     |
-| Execute plan   | `/ship <id>`  |
-| Research first | `/research`   |
+| Need           | Command      |
+| -------------- | ------------ |
+| Create spec    | `/create`    |
+| Execute plan   | `/ship <id>` |
+| Research first | `/research`  |

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

@@ -10,6 +10,8 @@ agent: build
 
 ```typescript
 skill({ name: "beads" });
+skill({ name: "memory-grounding" });
+skill({ name: "verification-gates" });
 skill({ name: "verification-before-completion" });
 ```
 
@@ -28,14 +30,7 @@ git status --porcelain
 
 If uncommitted changes exist, ask whether to commit first.
 
-Run verification gates. Detect project type and use the appropriate commands:
-
-| Project Type    | Detect Via                    | Build            | Test            | Lint                          | Typecheck                             |
-| --------------- | ----------------------------- | ---------------- | --------------- | ----------------------------- | ------------------------------------- |
-| Node/TypeScript | `package.json`                | `npm run build`  | `npm test`      | `npm run lint`                | `npm run typecheck` or `tsc --noEmit` |
-| Rust            | `Cargo.toml`                  | `cargo build`    | `cargo test`    | `cargo clippy -- -D warnings` | (included in build)                   |
-| Python          | `pyproject.toml` / `setup.py` | —                | `pytest`        | `ruff check .`                | `mypy .`                              |
-| Go              | `go.mod`                      | `go build ./...` | `go test ./...` | `golangci-lint run`           | (included in build)                   |
+Follow the [verification-gates](../skill/verification-gates/SKILL.md) skill protocol. All gates must pass before creating the PR.
 
 Check `package.json` scripts, `Makefile`, or `justfile` for project-specific commands first — prefer those over generic defaults.
 
@@ -45,14 +40,7 @@ If any gate fails, stop. Fix errors first, then run `/pr` again.
 
 ### Memory Grounding
 
-Search memory for relevant decisions, known issues, and prior review findings:
-
-```typescript
-memory-search({ query: "$ARGUMENTS" });
-memory-search({ query: "<branch or feature keywords>", limit: 5 });
-```
-
-Include relevant findings in the PR description (e.g., architectural decisions, known limitations).
+Follow the [memory-grounding](../skill/memory-grounding/SKILL.md) skill protocol. Include relevant findings in the PR description.
 
 ### Git Context
 

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

@@ -14,6 +14,7 @@ Gather information before implementation. Find answers, document findings, stop
 
 ```typescript
 skill({ name: "beads" });
+skill({ name: "memory-grounding" });
 // For --thorough mode:
 skill({ name: "deep-research" });
 ```
@@ -66,17 +67,7 @@ Read PRD if it exists and extract questions that need answering.
 
 ### Memory Search (Required)
 
-Always search memory before spawning research agents:
-
-```typescript
-memory-search({ query: "$ARGUMENTS" });
-memory-search({ query: "<topic keywords>", limit: 10 });
-```
-
-If memory returns relevant findings, use them to:
-- Skip questions already answered
-- Narrow research scope to gaps only
-- Avoid contradicting prior decisions without justification
+Follow the [memory-grounding](../skill/memory-grounding/SKILL.md) skill protocol. Use findings to: skip already-answered questions, narrow scope to gaps only, avoid contradicting prior decisions without justification.
 
 ## Phase 2: Research
 
@@ -130,8 +121,8 @@ Report:
 
 ## Related Commands
 
-| Need          | Command       |
-| ------------- | ------------- |
-| Create + start | `/create`     |
-| Plan details  | `/plan <id>`  |
-| Pick up work   | `/ship <id>`  |
+| Need           | Command      |
+| -------------- | ------------ |
+| Create + start | `/create`    |
+| Plan details   | `/plan <id>` |
+| Pick up work   | `/ship <id>` |

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

@@ -12,6 +12,7 @@ Pick up where a previous session left off. Recover context, verify state, contin
 
 ```typescript
 skill({ name: "beads" });
+skill({ name: "memory-grounding" });
 ```
 
 ## Phase 1: Verify Task
@@ -33,11 +34,7 @@ If not on the right branch, check out the feature branch. If uncommitted changes
 
 ## Phase 3: Find Handoff
 
-Check for handoff notes in the memory system:
-
-```typescript
-memory_read({ file: "handoffs/$ARGUMENTS" });
-```
+Follow the [memory-grounding](../skill/memory-grounding/SKILL.md) skill protocol. Focus on: handoff file by bead ID, session history.
 
 If a handoff exists, it tells you:
 
@@ -46,12 +43,6 @@ If a handoff exists, it tells you:
 - What to do next
 - Any blockers
 
-Also search previous sessions:
-
-```typescript
-find_sessions({ query: "$ARGUMENTS" });
-```
-
 ## Phase 4: Load Artifacts
 
 Read all available context:

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

@@ -11,6 +11,7 @@ agent: review
 ```typescript
 skill({ name: "beads" });
 skill({ name: "requesting-code-review" });
+skill({ name: "verification-gates" });
 ```
 
 ## Determine Input Type
@@ -32,13 +33,13 @@ skill({ name: "requesting-code-review" });
 
 ## Available Tools
 
-| Tool         | Use When                                |
-| ------------ | --------------------------------------- |
-| `explore`    | Finding patterns in codebase, prior art |
-| `scout`      | External research, best practices       |
-| `lsp`        | Finding symbol definitions, references  |
-| `tilth_tilth_search` | Finding code patterns |
-| `codesearch` | Real-world usage examples               |
+| Tool                 | Use When                                |
+| -------------------- | --------------------------------------- |
+| `explore`            | Finding patterns in codebase, prior art |
+| `scout`              | External research, best practices       |
+| `lsp`                | Finding symbol definitions, references  |
+| `tilth_tilth_search` | Finding code patterns                   |
+| `codesearch`         | Real-world usage examples               |
 
 ## Phase 1: Gather Context
 
@@ -68,14 +69,7 @@ If bead provided, read `.beads/artifacts/$ID/prd.md` to review against spec.
 
 ## Phase 3: Automated Checks
 
-Detect project type and run the appropriate checks in parallel:
-
-| Project Type    | Detect Via                    | Build            | Test            | Lint                          | Typecheck                             |
-| --------------- | ----------------------------- | ---------------- | --------------- | ----------------------------- | ------------------------------------- |
-| Node/TypeScript | `package.json`                | `npm run build`  | `npm test`      | `npm run lint`                | `npm run typecheck` or `tsc --noEmit` |
-| Rust            | `Cargo.toml`                  | `cargo build`    | `cargo test`    | `cargo clippy -- -D warnings` | (included in build)                   |
-| Python          | `pyproject.toml` / `setup.py` | —                | `pytest`        | `ruff check .`                | `mypy .`                              |
-| Go              | `go.mod`                      | `go build ./...` | `go test ./...` | `golangci-lint run`           | (included in build)                   |
+Follow the [verification-gates](../skill/verification-gates/SKILL.md) skill protocol.
 
 Check `package.json` scripts, `Makefile`, or `justfile` for project-specific commands first — prefer those over generic defaults.
 

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

@@ -16,6 +16,8 @@ Execute PRD tasks, verify each passes, run review, close the bead.
 
 ```typescript
 skill({ name: "beads" });
+skill({ name: "memory-grounding" });
+skill({ name: "workspace-setup" });
 skill({ name: "verification-before-completion" });
 ```
 
@@ -38,27 +40,19 @@ skill({ name: "verification-before-completion" });
 
 ## Available Tools
 
-| Tool      | Use When                                  |
-| --------- | ----------------------------------------- |
-| `explore` | Finding patterns in codebase, prior art   |
-| `scout`   | External research, best practices         |
-| `lsp`     | Finding symbol definitions, references    |
-| `tilth_tilth_search` | Finding code patterns |
-| `task`    | Spawning subagents for parallel execution |
+| Tool                 | Use When                                  |
+| -------------------- | ----------------------------------------- |
+| `explore`            | Finding patterns in codebase, prior art   |
+| `scout`              | External research, best practices         |
+| `lsp`                | Finding symbol definitions, references    |
+| `tilth_tilth_search` | Finding code patterns                     |
+| `task`               | Spawning subagents for parallel execution |
 
 ## Phase 1: Guards
 
 ### Memory Grounding
 
-Search memory for context, prior decisions, and known issues before executing:
-
-```typescript
-memory-search({ query: "$ARGUMENTS" });
-memory-search({ query: "<bead title keywords>", limit: 5 });
-memory-read({ file: "handoffs/last" });
-```
-
-Use findings to avoid re-discovering known issues or repeating failed approaches.
+Follow the [memory-grounding](../skill/memory-grounding/SKILL.md) skill protocol. Focus on: failed approaches to avoid repeating.
 
 ### Bead Validation
 
@@ -85,44 +79,9 @@ br update $ARGUMENTS --status in_progress
 
 Then ask about workspace:
 
-```typescript
-question({
-  questions: [
-    {
-      header: "Workspace",
-      question: "How do you want to set up the workspace?",
-      options: [
-        {
-          label: "Create feature branch (Recommended)",
-          description: "git checkout -b feat/<bead-id>-<title>",
-        },
-        {
-          label: "Use current branch",
-          description: "Work on current branch",
-        },
-      ],
-    },
-  ],
-});
-```
-
-**If feature branch selected:**
-
-Map bead type to branch prefix:
-
-| Bead Type | Branch Prefix |
-| --------- | ------------- |
-| feature   | feat          |
-| bug       | fix           |
-| task      | task          |
-| epic      | epic          |
-
-```bash
-# Example: feat/br-42-add-auth
-git checkout -b $PREFIX/$BEAD_ID-$TITLE_SLUG
-```
+### Workspace Setup
 
-**If current branch:** Continue without branch creation.
+Follow the [workspace-setup](../skill/workspace-setup/SKILL.md) skill protocol.
 
 **If bead is already `in_progress`:** Skip this phase entirely.
 

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

@@ -27,6 +27,12 @@ updated: 2025-01-06
 - Language: TypeScript
 - Linter: oxlint
 
+## Editing Tool Preferences
+
+- **Primary**: `edit` tool (str_replace) and `patch` tool
+- **Secondary/Fallback**: `tilth_tilth_edit` (hash-anchored edits) — only when str_replace fails
+- **Reading/Search**: `tilth_tilth_read` and `tilth_tilth_search` are fine to use freely
+
 ## Rules to Always Follow
 
 - Run `npm run lint:fix` before any commit
@@ -34,5 +40,6 @@ updated: 2025-01-06
 - Don't modify dist/ directly (it's built output)
 - Ask before adding new dependencies
 - Ask before changing .opencode/ structure
+- Ask before schema changes (zod schemas, config shapes)
 - Never commit secrets or .env files
 - Never force push to main