opencodekit 0.20.2 → 0.20.4

package/dist/template/.opencode/skill/memory-system/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: memory-system
 description: Use when persisting learnings, loading previous context, or searching past decisions - covers memory file structure, tools, and when to update each file
-version: 1.1.0
+version: 1.2.0
 tags: [context, workflow]
 dependencies: []
 ---
@@ -78,6 +78,70 @@ After creating an observation: `memory-search` with relevant keywords should fin
 - For ongoing work, append to one handoff file per task/day instead of many tiny files.
 - Keep observation titles concrete and action-oriented.
 
+## Admin Operations
+
+The `memory-admin` tool supports these operations:
+
+### Core (existing)
+| Operation | Purpose |
+|---|---|
+| `status` | Storage stats, FTS5 health, pipeline counts |
+| `full` | Full maintenance cycle (archive + checkpoint + vacuum) |
+| `archive` | Archive observations older than N days |
+| `checkpoint` | Checkpoint WAL file |
+| `vacuum` | Vacuum database |
+| `migrate` | Import .opencode/memory/observations/*.md into SQLite |
+| `capture-stats` | Temporal message capture statistics |
+| `distill-now` | Force distillation for current session |
+| `curate-now` | Force curator run |
+
+### Knowledge Intelligence (new in v2.1)
+| Operation | Purpose |
+|---|---|
+| `lint` | Find duplicates, contradictions, stale/orphan observations |
+| `index` | Generate a structured catalog of all observations |
+| `compile` | Build concept-grouped articles from observation clusters |
+| `log` | View the append-only operation audit trail |
+
+Examples:
+```
+memory-admin({ operation: "lint" })
+memory-admin({ operation: "lint", older_than_days: 60 })
+memory-admin({ operation: "index" })
+memory-admin({ operation: "compile" })
+memory-admin({ operation: "log" })
+```
+
+### Reading Compiled Artifacts
+```
+memory-read({ file: "index" })             // Full observation catalog
+memory-read({ file: "compiled/auth" })      // Compiled article for "auth" concept
+memory-read({ file: "log" })                // Operation audit trail
+```
+
+## Validation Gate
+
+The `observation` tool now validates before storing:
+- **Exact duplicate** → rejected (returns duplicate ID + supersede hint)
+- **Near-duplicate** → stored with warning
+- **Contradiction** → stored with warning (for decisions sharing concepts)
+- **Low quality** → stored with warning (no narrative + no concepts)
+
+To update an existing observation, use `supersedes`:
+```
+observation({ type: "decision", title: "Use JWT", supersedes: "42", ... })
+```
+
+## Idle Pipeline
+
+During `session.idle`, the memory system automatically runs:
+1. Distill undistilled messages
+2. Curate observations from distillations
+3. Optimize FTS5 index
+4. Checkpoint WAL if large
+5. Compile concept articles (max 10)
+6. Regenerate memory index
+
 ## See Also
 
 - `context-management`

package/dist/template/.opencode/skill/minimalist-ui/SKILL.md

@@ -3,6 +3,19 @@ name: minimalist-ui
 description: Use INSTEAD OF design-taste-frontend when user requests clean, editorial, or minimalist aesthetics. Warm monochrome palette, typographic contrast, flat bento grids, muted pastels. No gradients, no heavy shadows.
 ---
 
+## When to Use
+
+- When the user requests clean, editorial, or minimalist aesthetics
+- For content-focused sites, blogs, or documentation pages
+- Instead of design-taste-frontend when warm monochrome and flat layouts are desired
+
+## When NOT to Use
+
+- When bold, attention-grabbing, or luxury visual design is requested
+- For data-heavy dashboards that need dense information display
+- When industrial-brutalist-ui or high-end-visual-design is a better fit
+
+
 # Protocol: Premium Utilitarian Minimalism UI Architect
 
 ## 1. Protocol Overview

package/dist/template/.opencode/skill/redesign-existing-projects/SKILL.md

@@ -3,6 +3,19 @@ name: redesign-existing-projects
 description: Use when upgrading an existing website or app's visual design to premium quality. Audits current design, identifies generic AI patterns, applies high-end standards without breaking functionality. MUST load before any design overhaul of existing projects.
 ---
 
+## When to Use
+
+- When upgrading an existing website or app's visual design to premium quality
+- Before any design overhaul of existing projects
+- When the current design has been identified as generic, template-looking, or AI-default
+
+## When NOT to Use
+
+- For greenfield projects (use frontend-design with an aesthetic overlay instead)
+- When the design is already polished and only minor tweaks are needed
+- For non-visual changes (performance, accessibility-only fixes)
+
+
 # Redesign Skill
 
 ## How This Works

package/dist/template/.opencode/skill/requesting-code-review/SKILL.md

@@ -1,9 +1,11 @@
 ---
 name: requesting-code-review
 description: Use when completing meaningful implementation work and needing a high-signal review pass before merge or release - dispatches scoped review agents, synthesizes findings, and routes follow-up actions by severity.
-version: 1.1.0
+version: 1.2.0
 tags: [workflow, code-quality, research]
 dependencies: []
+references:
+  - references/specialist-profiles.md
 ---
 
 # Requesting Code Review
@@ -90,7 +92,9 @@ Choose the smallest review depth that still covers the risk.
 
 - **targeted**: use 1-2 specific review prompts
 - **standard**: use security/correctness, tests/types, and completeness
-- **full**: use all 5 specialized review prompts
+- **full**: use all 5 specialized review prompts + specialist profiles from [references/specialist-profiles.md](references/specialist-profiles.md)
+
+For **standard** and **full** reviews, enhance dispatch prompts with specialist reviewer profiles (security, architecture, performance) and run an adversarial pass on findings. See [references/specialist-profiles.md](references/specialist-profiles.md) for the exact prompt additions and confidence thresholds.
 
 Do **not** dispatch 5 reviewers by reflex for every tiny change. That produces noise, not rigor.
 
@@ -395,3 +399,45 @@ Run `/compound` after resolving review findings to capture:
 - Newly discovered codebase conventions
 
 That turns review from a gate into a feedback loop.
+
+## Autofix Classification
+
+Every review finding should include a **fix category** that routes remediation. This prevents the user from manually triaging every finding.
+
+| Category       | Meaning                                          | Agent Action                              |
+| -------------- | ------------------------------------------------ | ----------------------------------------- |
+| `safe_auto`    | Zero-risk fix (formatting, unused imports, typos) | Fix immediately without asking            |
+| `gated_auto`   | Likely correct fix, but verify first              | Fix and show diff before committing       |
+| `manual`       | Requires human judgment or architectural decision | Report to user with context, don't touch  |
+| `advisory`     | Informational only, no action required            | Include in report, no remediation needed  |
+
+### Reviewer Output Format (Enhanced)
+
+Reviewers should return findings in this structure:
+
+```markdown
+### [SEVERITY]: [Title]
+
+- **File:** `path/to/file.ts:123`
+- **Category:** safe_auto | gated_auto | manual | advisory
+- **Issue:** [concrete description of the problem]
+- **Fix:** [specific fix if category is safe_auto or gated_auto]
+```
+
+### Classification Rules
+
+1. **safe_auto** — formatting, whitespace, unused imports, typo in comments, missing trailing newlines. Must not change behavior.
+2. **gated_auto** — missing null checks, error handling gaps, type narrowing fixes. Changes behavior but fix is clear and low-risk.
+3. **manual** — architectural concerns, API design questions, security decisions, breaking changes. Requires human context.
+4. **advisory** — "consider doing X", performance suggestions without evidence, alternative patterns. No action needed.
+
+### Post-Synthesis Routing
+
+After synthesizing all findings:
+
+1. **Apply all `safe_auto` fixes** immediately
+2. **Show `gated_auto` diffs** to user for approval before applying
+3. **Present `manual` findings** as a prioritized list for user decision
+4. **Append `advisory` findings** at the end of the report for reference
+
+This routing ensures trivial fixes don't block the review while keeping humans in the loop for judgment calls.

package/dist/template/.opencode/skill/requesting-code-review/references/specialist-profiles.md

@@ -0,0 +1,108 @@
+# Specialist Reviewer Profiles
+
+Use these profiles when dispatching review agents for **standard** or **full** depth reviews. Each profile focuses the reviewer on a specific domain, reducing noise and increasing finding quality.
+
+## Security Reviewer
+
+**Focus:** OWASP Top 10, auth/authz, data exposure, injection, secrets
+
+**Dispatch prompt addition:**
+
+```
+You are reviewing as a SECURITY SPECIALIST. Focus exclusively on:
+
+1. Authentication/authorization gaps (missing auth checks, privilege escalation)
+2. Injection vulnerabilities (SQL, XSS, command injection, path traversal)
+3. Secrets exposure (hardcoded tokens, API keys in source, logged credentials)
+4. Data validation gaps (missing input sanitization, unsafe deserialization)
+5. Insecure defaults (permissive CORS, missing rate limiting, debug mode)
+
+Ignore: Style, architecture, performance (other reviewers handle those).
+
+Confidence threshold: Only report findings with confidence >= 0.60.
+Below 0.60, include in a separate "Low Confidence / Investigate" section.
+```
+
+**When to use:** Always in standard and full reviews. Skip only for purely internal tools with no user input.
+
+---
+
+## Architecture Reviewer
+
+**Focus:** Coupling, SOLID principles, API design, dependency direction
+
+**Dispatch prompt addition:**
+
+```
+You are reviewing as an ARCHITECTURE SPECIALIST. Focus exclusively on:
+
+1. Coupling violations (circular deps, god modules, leaky abstractions)
+2. API contract issues (breaking changes, inconsistent error formats, missing versioning)
+3. Dependency direction violations (inner layers importing outer layers)
+4. Abstraction misuse (over-engineering, unnecessary indirection, premature abstraction)
+5. Pattern divergence (new code contradicts established codebase patterns)
+
+Rules:
+- Only flag architecture issues that will cause CONCRETE problems (maintenance cost, bugs, scaling)
+- "I would have done it differently" is NOT a finding
+- Preference for existing patterns over theoretically better ones
+
+Confidence threshold: Only report findings with confidence >= 0.60.
+```
+
+**When to use:** Full reviews only. Skip for small fixes, config changes, or documentation updates.
+
+---
+
+## Performance Reviewer
+
+**Focus:** Runtime efficiency, bundle size, database queries, memory
+
+**Dispatch prompt addition:**
+
+```
+You are reviewing as a PERFORMANCE SPECIALIST. Focus exclusively on:
+
+1. N+1 query patterns (loops that make DB/API calls)
+2. Missing memoization on expensive computations
+3. Unbounded data loading (no pagination, no limits)
+4. Bundle size regressions (large imports that could be lazy-loaded)
+5. Memory leaks (event listeners without cleanup, growing caches)
+
+Rules:
+- Only flag issues with MEASURABLE impact (not theoretical)
+- "This could be faster" without evidence is NOT a finding
+- Quantify impact where possible (e.g., "This runs N queries instead of 1")
+
+Confidence threshold: Only report findings with confidence >= 0.70.
+Performance findings below 0.70 are usually speculative — suppress them.
+```
+
+**When to use:** Full reviews only, and only when the change touches data-heavy paths, rendering, or database queries.
+
+---
+
+## Adversarial Pass
+
+After all specialist reviews complete, run an adversarial pass on the combined findings. This prevents false positives from making it into the final report.
+
+**Adversarial prompt:**
+
+```
+Review these findings from specialist reviewers. For EACH finding, challenge it from these angles:
+
+1. **False positive check**: Does this issue actually exist in the code, or did the reviewer misread context?
+2. **Severity inflation**: Is the severity appropriate, or is a CRITICAL actually a MINOR?
+3. **Codebase context**: Does the existing codebase already handle this elsewhere (middleware, framework, config)?
+4. **Cost-benefit**: Is the fix worth the effort, or is this pedantic?
+
+For each finding, output:
+- CONFIRMED (keep as-is)
+- DOWNGRADED (reduce severity, explain why)
+- REJECTED (false positive, explain why)
+
+Only CONFIRMED and DOWNGRADED findings should appear in the final report.
+Confidence threshold for rejection: >= 0.60 (be sure before removing a finding).
+```
+
+**When to use:** Full reviews with 3+ specialist reviewers. Reduces noise by ~30% based on typical review output.

package/dist/template/.opencode/skill/skill-creator/SKILL.md

@@ -154,3 +154,28 @@ Answer these questions:
 - [ ] **No XML-style tags**
 - [ ] **SKILL.md under 200 lines**
 - [ ] **All referenced files exist**
+
+## Recommended Sections for SKILL.md
+
+Beyond the required structure, include these sections when applicable:
+
+### `## Gotchas`
+
+Every skill should accumulate a Gotchas section over time. This is **failure-driven documentation** — each entry should trace to a specific failure encountered during real use.
+
+```markdown
+## Gotchas
+
+- **[Short description of what went wrong]** — [What the agent did wrong, why, and the fix]. Discovered [date or session reference].
+- **[Another failure]** — [Details]. Discovered [date].
+```
+
+**Rules for Gotchas:**
+
+1. Every entry must trace to an actual failure, not a hypothetical risk
+2. Include what the agent did, why it failed, and how to avoid it
+3. New entries are added when a skill causes a failure — the fix PR should include a gotcha entry
+4. Keep entries concise (1-3 sentences each)
+5. This section grows over time and is never cleared — it's the skill's scar tissue
+
+**Why this matters:** Skills without gotchas are untested skills. A skill with 5 gotchas has been battle-tested through 5 real failures and is structurally better than a pristine skill with zero. When a skill causes a failure, always ask: "Should this become a gotcha entry?"

package/dist/template/.opencode/skill/stitch-design-taste/SKILL.md

@@ -3,6 +3,19 @@ name: stitch-design-taste
 description: Use when generating DESIGN.md files for Google Stitch projects to enforce premium, anti-generic UI standards. Load BEFORE stitch skill when design quality matters. Stitch-specific only — do not use for general web projects.
 ---
 
+## When to Use
+
+- When generating DESIGN.md files for Google Stitch projects
+- Before loading the stitch skill when design quality matters
+- When enforcing premium, anti-generic UI standards in Stitch workflows
+
+## When NOT to Use
+
+- For general web projects not using Google Stitch
+- When the stitch project already has a satisfactory DESIGN.md
+- For non-UI Stitch operations (data, API, backend)
+
+
 # Stitch Design Taste — Semantic Design System Skill
 
 ## Overview

package/dist/template/.opencode/skill/verification-before-completion/SKILL.md

@@ -95,6 +95,52 @@ Skip any step = lying, not verifying
 | "Partial check is enough"               | Partial proves nothing |
 | "Different words so rule doesn't apply" | Spirit over letter     |
 
+## Diagnostic Failure Phrases
+
+These phrases are **automatic re-verification triggers**. If you catch yourself writing any of these (or semantic equivalents), STOP and run the actual verification command before continuing.
+
+### Completion Claims Without Evidence
+
+- "This should fix it"
+- "That should resolve the issue"
+- "The problem should be gone now"
+- "This will work"
+- "It's fixed"
+- "Everything looks good"
+- "We're all set"
+
+### Confidence Substitution
+
+- "I'm fairly certain this is correct"
+- "Based on my understanding, this works"
+- "This is straightforward enough"
+- "The logic is sound"
+- "This follows the pattern so it should be fine"
+
+### Deflection / Minimization
+
+- "It's just a minor change"
+- "Nothing else should be affected"
+- "The rest of the code is unchanged"
+- "This is a safe change"
+- "No side effects expected"
+
+### Post-Hoc Rationalization
+
+- "The error was probably just [X]"
+- "That failure was likely a fluke"
+- "It probably works in production"
+- "The test environment might be the issue"
+
+### False Completion
+
+- "All done!" / "Done!" / "Complete!"
+- "That takes care of everything"
+- "Ready for review" (without verification output)
+- "Committing now" (without verification output)
+
+**Rule:** If any of these phrases appear in your draft response, delete them and replace with actual verification command output. The phrase IS the signal that you're about to lie.
+
 ## Key Patterns
 
 **Tests:**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencodekit",
-	"version": "0.20.2",
+	"version": "0.20.4",
 	"description": "CLI tool for bootstrapping and managing OpenCodeKit projects",
 	"keywords": [
 		"agents",

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

@@ -1,79 +0,0 @@
----
-description: Lightweight runner for trivial shell, git, and filesystem operations
-mode: subagent
-temperature: 0.0
-permission:
-  bash:
-    "*": allow
-    "git push*": ask
-    "git commit*": ask
-    "git merge*": ask
-    "git reset*": ask
-    "rm*": ask
-    "sudo*": deny
-  write:
-    "*": deny
-  edit:
-    "*": deny
----
-
-You are OpenCode, the best coding agent on the planet.
-
-# Runner Agent
-
-**Purpose**: Execute trivial operations — scripts, git commands, file system ops. No code reasoning.
-
-## Identity
-
-You are the runner agent. You execute simple, well-defined operations quickly and reliably. You don't write code or make architectural decisions.
-
-## Model Guidance
-
-- Use the cheapest/fastest available model for execution tasks
-- Temperature: 0.0 (deterministic execution)
-
-## Capabilities
-
-- Run shell commands and scripts
-- Git operations (commit, push, pull, tag, branch, merge)
-- File system operations (move, copy, delete — with confirmation for destructive ops)
-- Run build/test/lint commands
-- Read command output and report results
-
-## Restrictions
-
-- **Never edit source code files** — delegate to general or build agent
-- **Never make architectural decisions** — escalate to plan agent
-- **No complex reasoning** — if a task requires understanding code logic, escalate
-- **No implementation work** — do not fix bugs or build features
-
-## When to Use
-
-- Simple shell commands
-- Git operations (commit, push, tag, merge)
-- Running build/test/lint scripts
-- File system operations (move, copy, delete with confirmation)
-
-## When NOT to Use
-
-- Code changes or refactors
-- Bug fixes or feature implementation
-- Tasks requiring code logic analysis
-- Architecture or design decisions
-
-## Rules
-
-1. Execute exactly what is requested — no improvisation
-2. Report command output faithfully — never fabricate
-3. Ask before destructive operations (delete, force push, reset)
-4. If a command fails, report the error — don't attempt creative fixes
-5. Stage specific files only — never `git add .`
-
-## Output Format
-
-For every operation:
-1. Show the command being run
-2. Show the output
-3. Confirm success or report failure
-
-Keep output minimal. No explanations unless something fails.

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

@@ -1,156 +0,0 @@
----
-description: Start working on a bead - claim it and prepare workspace
-argument-hint: "<bead-id> [--worktree]"
-agent: build
----
-
-# Start: $ARGUMENTS
-
-Claim a task and prepare workspace. Bridge between specification (`/create`) and implementation (`/ship`).
-
-> **Workflow:** `/create` → **`/start <id>`** → `/ship <id>`
->
-> ⛔ Bead MUST have `prd.md` (created via `/create`).
-
-## Load Skills
-
-```typescript
-skill({ name: "beads" });
-skill({ name: "prd-task" }); // PRD → executable tasks
-```
-
-## Parse Arguments
-
-| Argument     | Default  | Description                  |
-| ------------ | -------- | ---------------------------- |
-| `<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
-git status --porcelain
-git branch --show-current
-br list --status=in_progress
-```
-
-- If uncommitted changes: ask user to stash, commit, or continue
-- If other tasks in progress: warn before claiming another
-
-## Phase 2: Validate Specification
-
-```bash
-br show $ARGUMENTS
-```
-
-Read `.beads/artifacts/$ARGUMENTS/` to check what artifacts exist.
-
-Verify `prd.md` exists and has real content (not just placeholders). If missing or incomplete, tell user to run `/create` first.
-
-## Phase 3: Claim
-
-```bash
-br update $ARGUMENTS --status in_progress
-```
-
-## Phase 4: Prepare Workspace
-
-Ask user how to handle 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",
-        },
-        {
-          label: "Create worktree",
-          description: "Isolated git worktree for this bead",
-        },
-      ],
-    },
-  ],
-});
-```
-
-**If feature branch selected:**
-
-Map bead type to branch prefix:
-
-| 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:**
-
-```typescript
-skill({ name: "using-git-worktrees" });
-```
-
-**If current branch:** Continue without branch creation.
-
-## Phase 5: Convert PRD to Tasks
-
-If `prd.json` doesn't exist yet, use `prd-task` skill to convert PRD markdown → executable JSON.
-
-If `prd.json` already exists, show progress (completed/total tasks).
-
-## Phase 6: Report and Route
-
-Output:
-
-1. Bead type and status
-2. Branch name
-3. Workspace (main or worktree)
-4. Artifact status (prd.md validated, prd.json exists/created)
-5. Next step recommendation
-
-| State              | Next Command             |
-| ------------------ | ------------------------ |
-| Has prd.json       | `/ship $ARGUMENTS`       |
-| Epic with subtasks | `/start <first-subtask>` |
-| Complex task       | `/plan $ARGUMENTS`       |
-
-## Related Commands
-
-| Need                | Command      |
-| ------------------- | ------------ |
-| Create spec first   | `/create`    |
-| Plan implementation | `/plan <id>` |
-| Implement and ship  | `/ship <id>` |