opencodekit 0.20.6 → 0.20.8

package/dist/index.js

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

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

@@ -22,6 +22,20 @@ When instructions conflict:
 
 1. **Security** — never expose or invent credentials
 2. **Anti-hallucination** — verify before asserting; if context is missing, prefer lookup over guessing; if you must proceed without full context, label assumptions explicitly and choose a reversible action
+
+### Source Hierarchy
+
+When verifying facts or API usage, rank sources by authority:
+
+| Tier                  | Source                                                       | Trust Level                           |
+| --------------------- | ------------------------------------------------------------ | ------------------------------------- |
+| **1 (Authoritative)** | Official documentation, type definitions, source code        | High — use directly                   |
+| **2 (Supportive)**    | Official blog posts, changelogs, web standards specs         | Medium — cross-reference              |
+| **3 (Contextual)**    | Browser compat tables, release notes, migration guides       | Medium — verify currency              |
+| **4 (Unreliable)**    | Stack Overflow, blog posts, AI-generated docs, training data | Low — never cite without verification |
+
+If a source from Tier 4 conflicts with Tier 1-2, the higher tier wins. If Tier 1-2 sources conflict with each other, state the conflict explicitly.
+
 3. **User intent** — do what was asked, simply and directly
 4. **Agency preservation** — "likely difficult" ≠ "impossible" ≠ "don't try"
 5. This `AGENTS.md`
@@ -45,6 +59,7 @@ If a newer user instruction conflicts with an earlier one, follow the newer inst
 - Stay in scope; no speculative refactors
 - Read files before editing
 - Delegate when work is large, uncertain, or cross-domain
+- When you notice something that should be improved but isn't part of the current task, log it as **"NOTICED BUT NOT TOUCHING: [description]"** and continue with the current task. This makes scope-creep visible and auditable without derailing the work.
 
 ### Simplicity First
 
@@ -318,6 +333,39 @@ For major tracked work:
 - **Agent prompts** stay role-focused; don't duplicate long checklists
 - **Load skills on demand**, not by default
 
+### Intent → Skill Mapping
+
+When user intent is clear, load the appropriate skills:
+
+| Intent                    | Phase          | Skills to Load                                                                     |
+| ------------------------- | -------------- | ---------------------------------------------------------------------------------- |
+| "Build a feature"         | Define → Build | `prd` → `writing-plans` → `incremental-implementation` + `test-driven-development` |
+| "Fix a bug"               | Verify         | `systematic-debugging` → `root-cause-tracing`                                      |
+| "Review code"             | Review         | `receiving-code-review` or `requesting-code-review`                                |
+| "Simplify / refactor"     | Review         | `code-simplification`                                                              |
+| "Ship it"                 | Ship           | `verification-before-completion` → `finishing-a-development-branch`                |
+| "Plan this"               | Plan           | `brainstorming` → `prd` → `writing-plans`                                          |
+| "Execute a plan"          | Build          | `executing-plans` + `subagent-driven-development`                                  |
+| "Debug flaky tests"       | Verify         | `condition-based-waiting` + `systematic-debugging`                                 |
+| "Debug in browser"        | Verify         | `chrome-devtools` or `playwright`                                                  |
+| "Write / fix tests"       | Verify         | `test-driven-development` + `testing-anti-patterns`                                |
+| "Build UI"                | Build          | `frontend-design` + `design-taste-frontend`                                        |
+| "Build UI from mockup"    | Build          | `mockup-to-code` + `frontend-design`                                               |
+| "Redesign existing UI"    | Build          | `redesign-existing-projects` + `design-taste-frontend`                             |
+| "Review UI / UX"          | Review         | `web-design-guidelines` + `visual-analysis` + `accessibility-audit`                |
+| "Audit accessibility"     | Verify         | `accessibility-audit`                                                              |
+| "Build React / Next.js"   | Build          | `react-best-practices` + `frontend-design`                                         |
+| "Research X"              | Define         | `deep-research` or `opensrc`                                                       |
+| "Design an API"           | Build          | `api-and-interface-design` + `documentation-and-adrs`                              |
+| "Set up CI/CD"            | Ship           | `ci-cd-and-automation` + `verification-gates`                                      |
+| "Deploy app"              | Ship           | `vercel-deploy-claimable`                                                          |
+| "Deprecate / migrate"     | Ship           | `deprecation-and-migration` + `incremental-implementation`                         |
+| "Write docs / record ADR" | Define         | `documentation-and-adrs`                                                           |
+| "Optimize performance"    | Verify         | `performance-optimization`                                                         |
+| "Harden security"         | Verify         | `security-and-hardening` + `defense-in-depth`                                      |
+| "Verify before merge"     | Ship           | `reconcile` + `verification-gates`                                                 |
+| "Create a skill"          | Build          | `skill-creator` + `writing-skills`                                                 |
+
 ---
 
 ## Context Management

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

@@ -92,6 +92,7 @@ Every diff you produce must meet these standards:
 - **Strong typing** — no `as any`, no `@ts-ignore` unless documented with a reason
 - **Reuse existing interfaces** — extend or compose existing types before creating new ones
 - **Minimal tests** — if the file you're editing has adjacent tests, add coverage for your change
+
 ## Ritual Structure
 
 Each task follows a five-phase ritual. Constraints create the container; the ritual transforms intent into output.
@@ -181,9 +182,9 @@ Load contextually when needed:
 | Debug/bug work         | `systematic-debugging`, `root-cause-tracing`               |
 | Test-heavy work        | `test-driven-development`, `testing-anti-patterns`         |
 | UI work                | `frontend-design`, `react-best-practices`                  |
-| Parallel orchestration | `swarm-coordination`, `beads-bridge`                       |
+| Parallel orchestration | `swarm-coordination`                                       |
 | Before completion      | `requesting-code-review`, `finishing-a-development-branch` |
-| Codebase exploration   | `code-navigation`                                          |
+| Codebase exploration   | `code-search-patterns`                                     |
 
 ## Execution Mode
 

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

@@ -43,20 +43,20 @@ Find relevant files, symbols, and usage paths quickly for the caller.
 
 ## Tools — Use These for Local Code Search
 
-**Prefer tilth CLI** (`npx -y tilth`) for symbol search and file reading — it combines grep + tree-sitter + cat into one call. See `tilth-cli` skill for full syntax.
-
-| Tool | Use For | Example |
-|------|---------|--------|
-| `tilth` (symbol) | AST-aware symbol search (definitions + usages) | `npx -y tilth handleAuth --scope src/` |
-| `tilth` (read) | Smart file reading with outline for large files | `npx -y tilth src/auth.ts --section 44-89` |
-| `tilth` (glob) | Find files by pattern with token estimates | `npx -y tilth "*.test.ts" --scope src/` |
-| `tilth` (map) | Codebase structural overview | `npx -y tilth --map --scope src/` |
-| `grep` | Find text/regex patterns in files | `grep(pattern: "PatchEntry", include: "*.ts")` |
-| `glob` | Find files by name/pattern | `glob(pattern: "src/**/*.ts")` |
-| `lsp` (goToDefinition) | Jump to symbol definition | `lsp(operation: "goToDefinition", filePath: "...", line: N, character: N)` |
-| `lsp` (findReferences) | Find all usages of a symbol | `lsp(operation: "findReferences", ...)` |
-| `lsp` (hover) | Get type info and docs | `lsp(operation: "hover", ...)` |
-| `read` | Read file content | `read(filePath: "src/utils/patch.ts")` |
+**Prefer tilth CLI** (`npx -y tilth`) for symbol search and file reading — it combines grep + tree-sitter + cat into one call. See `code-search-patterns` skill for full syntax.
+
+| Tool                   | Use For                                         | Example                                                                    |
+| ---------------------- | ----------------------------------------------- | -------------------------------------------------------------------------- |
+| `tilth` (symbol)       | AST-aware symbol search (definitions + usages)  | `npx -y tilth handleAuth --scope src/`                                     |
+| `tilth` (read)         | Smart file reading with outline for large files | `npx -y tilth src/auth.ts --section 44-89`                                 |
+| `tilth` (glob)         | Find files by pattern with token estimates      | `npx -y tilth "*.test.ts" --scope src/`                                    |
+| `tilth` (map)          | Codebase structural overview                    | `npx -y tilth --map --scope src/`                                          |
+| `grep`                 | Find text/regex patterns in files               | `grep(pattern: "PatchEntry", include: "*.ts")`                             |
+| `glob`                 | Find files by name/pattern                      | `glob(pattern: "src/**/*.ts")`                                             |
+| `lsp` (goToDefinition) | Jump to symbol definition                       | `lsp(operation: "goToDefinition", filePath: "...", line: N, character: N)` |
+| `lsp` (findReferences) | Find all usages of a symbol                     | `lsp(operation: "findReferences", ...)`                                    |
+| `lsp` (hover)          | Get type info and docs                          | `lsp(operation: "hover", ...)`                                             |
+| `read`                 | Read file content                               | `read(filePath: "src/utils/patch.ts")`                                     |
 
 **NEVER** use `websearch`, `webfetch`, or `codesearch` — those search the internet, not your project.
 **NEVER** modify files or run destructive commands — bash is for tilth CLI and read-only operations only.

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

@@ -157,7 +157,7 @@ Before claiming task done:
 4. Run validation (lint/typecheck/tests as applicable)
 5. Report changed files with `file:line` references
 
-**Code navigation:** Use tilth CLI for AST-aware search when available — see `tilth-cli` skill for syntax. Prefer `npx -y tilth <symbol> --scope <dir>` over grep for symbol definitions.
+**Code navigation:** Use tilth CLI for AST-aware search when available — see `code-search-patterns` skill for syntax. Prefer `npx -y tilth <symbol> --scope <dir>` over grep for symbol definitions.
 
 ## Progress Updates
 

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

@@ -386,7 +386,7 @@ When planning under constraint:
 4. **Release**: Write actionable plan with exact file paths, commands, and verification
 5. **Reset**: End with a concrete next command (`/ship <id>`, `/start <child-id>`, etc.)
 
-**Code navigation:** Use tilth CLI for AST-aware search and `--map` for structural overview — see `tilth-cli` skill.
+**Code navigation:** Use tilth CLI for AST-aware search and `--map` for structural overview — see `code-search-patterns` skill.
 
 ## Output
 

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

@@ -178,7 +178,7 @@ return <div>No messages</div>  // State exists but not used
 3. For each finding: explain why, when it happens, and impact
 4. If no qualifying findings exist, say so explicitly
 
-**Code navigation:** Use tilth CLI for AST-aware symbol search when tracing cross-file dependencies — see `tilth-cli` skill. Prefer `npx -y tilth <symbol> --scope <dir>` over grep for understanding call chains.
+**Code navigation:** Use tilth CLI for AST-aware symbol search when tracing cross-file dependencies — see `code-search-patterns` skill. Prefer `npx -y tilth <symbol> --scope <dir>` over grep for understanding call chains.
 
 ## Output
 

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

@@ -71,7 +71,6 @@ Route by need:
 | Mockup-to-implementation mapping              | `mockup-to-code`      |
 | Distinctive UI direction / anti-slop guidance | `frontend-design`     |
 | Figma design data (read/write via MCP)        | `figma-go`            |
-| OpenPencil design-as-code workflow            | `pencil`              |
 | Brand identity extraction from URLs           | `webclaw`             |
 
 ### Taste-Skill Variants (installed)
@@ -108,14 +107,6 @@ If Figma is available, request MCP access via `figma-go` and ground feedback in
 2. Use `figma-go` to pull `get_design_context` or `get_node`
 3. Reference node IDs in findings for traceability
 
-## OpenPencil Workflow (when no Figma)
-
-If design must be created or iterated quickly, use OpenPencil via the legacy `pencil` skill:
-
-1. Create/modify `.op` via `op` CLI
-2. Export PNGs or code for review
-3. Provide audit with node-level critique where possible
-
 ## Brand Extraction Workflow (when auditing existing sites)
 
 Use `webclaw` MCP to extract brand identity from live sites:

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

@@ -8,10 +8,17 @@ agent: build
 
 Capture what was learned. This is the flywheel step — each cycle makes the next cycle faster.
 
-> **Workflow:** `/plan` → `/ship` → `/review` → **`/compound`** → `/pr`
+> **Workflow:** `/plan` → `/ship` → **`/compound`** → `/pr`
 >
 > Run after every completed task, review, or PR merge. The value compounds over time.
 
+## Load Skills
+
+```typescript
+skill({ name: "memory-system" });
+skill({ name: "verification-before-completion" });
+```
+
 ## What This Does
 
 Extracts learnings from the just-completed work and stores them as structured observations in memory,
@@ -47,7 +54,7 @@ For each finding, assign a type:
 | `pattern`   | A reusable approach confirmed to work in this codebase     | "Always use X pattern for Y type of component"  |
 | `bugfix`    | A non-obvious bug and its root cause                       | "Bun doesn't support X, use Y instead"          |
 | `decision`  | An architectural or design choice with rationale           | "Chose JWT over sessions because..."            |
-| `gotcha`    | A footgun, constraint, or thing that looks wrong but isn't | "Don't modify dist/ directly, build overwrites" |
+| `warning`   | A footgun, constraint, or thing that looks wrong but isn't | "Don't modify dist/ directly, build overwrites" |
 | `discovery` | A non-obvious fact about the codebase or its dependencies  | "Build copies .opencode/ to dist/template/"     |
 | `warning`   | Something that will break if not followed                  | "Always run lint:fix before commit"             |
 
@@ -60,19 +67,60 @@ For each learning worth keeping, create an observation:
 
 ```typescript
 observation({
-  type: "pattern", // or bugfix, decision, gotcha, discovery, warning
+  type: "pattern", // or bugfix, decision, discovery, warning, learning
   title: "[Concise, searchable title — what someone would search for]",
   narrative: "[What happened, why it matters, how to apply it]",
   facts: "[comma, separated, key, facts]",
   concepts: "[searchable, keywords, for, future, retrieval]",
   files_modified: "[relevant/file.ts if applicable]",
   confidence: "high", // high=verified, medium=likely, low=speculative
+  // ByteRover-inspired quality fields:
+  subtitle: "[One-line semantic summary — WHY this matters for future work]",
 });
 ```
 
 **Minimum viable:** title + narrative. Everything else is bonus.
 
-## Phase 4: Check AGENTS.md / Skill Updates
+**Quality enrichment:** Add `subtitle` (WHY it matters) for high-impact observations. Skip for routine findings.
+
+## Phase 4: Structural Loss Prevention
+
+When superseding an older observation, prevent accidental knowledge loss.
+
+**Trigger:** Only runs when `supersedes: "ID"` is set on a new observation.
+
+### Step 1: Read the old observation
+
+```typescript
+const old = memory_get({ ids: "<superseded-id>" });
+```
+
+### Step 2: Detect structural loss
+
+Compare the new observation against the old one:
+
+| Field            | Loss Detection                                                  |
+| ---------------- | --------------------------------------------------------------- |
+| `facts`          | Old facts not present in new facts (comma-separated comparison) |
+| `concepts`       | Old concepts not present in new concepts                        |
+| `narrative`      | New narrative significantly shorter than old (< 50% length)     |
+| `files_modified` | Old file paths not present in new list                          |
+
+### Step 3: Auto-merge if loss detected
+
+- **Array fields** (facts, concepts): Union merge — keep all old items, add new items, deduplicate
+- **Scalar fields** (narrative): If new is shorter, append `\n\n[Preserved from superseded observation #ID:]\n` + old narrative section
+- **File paths**: Union merge all paths
+
+### Step 4: Flag for review if high-impact
+
+If the old observation had `confidence: "high"` and the new one has `confidence: "medium"` or `confidence: "low"`, flag with a warning:
+
+> ⚠️ Confidence downgrade detected: superseding a high-confidence observation (#ID) with lower confidence. Verify this is intentional.
+
+**Principle:** Knowledge should accumulate, not be replaced. Merging is safer than overwriting.
+
+## Phase 5: Check AGENTS.md / Skill Updates
 
 Ask: does this learning belong as a permanent rule?
 
@@ -88,18 +136,18 @@ If MAYBE (it's a pattern, not a rule):
 
 **Rule:** AGENTS.md changes require user confirmation. Observations are automatic.
 
-## Phase 5: Update Living Documentation
+## Phase 6: Update Living Documentation
 
 Check if the shipped work changed architecture, APIs, conventions, or tech stack. If so, update the relevant project docs.
 
 **Check each:**
 
-| Doc | Update When | What to Update |
-| --- | --- | --- |
-| `tech-stack.md` | New dependency added, build tool changed, runtime updated | Dependencies list, build tools, constraints |
-| `project.md` | Architecture changed, new key files, success criteria met | Architecture section, key files table, phase status |
-| `gotchas.md` | New footgun discovered, constraint found | Add the gotcha with context |
-| `AGENTS.md` (project) | New convention established, boundary rule needed | Boundaries, gotchas, code example sections |
+| Doc                   | Update When                                               | What to Update                                      |
+| --------------------- | --------------------------------------------------------- | --------------------------------------------------- |
+| `tech-stack.md`       | New dependency added, build tool changed, runtime updated | Dependencies list, build tools, constraints         |
+| `project.md`          | Architecture changed, new key files, success criteria met | Architecture section, key files table, phase status |
+| `gotchas.md`          | New footgun discovered, constraint found                  | Add the gotcha with context                         |
+| `AGENTS.md` (project) | New convention established, boundary rule needed          | Boundaries, gotchas, code example sections          |
 
 ```typescript
 // Check what changed
@@ -110,7 +158,8 @@ memory_update({ file: "project/gotchas", content: "...", mode: "append" });
 ```
 
 **Rule:** Only update docs when the change is structural (new pattern, new dep, new constraint). Don't update for routine bug fixes or small features. Ask user before modifying `AGENTS.md`.
-## Phase 6: Search for Related Past Observations
+
+## Phase 7: Search for Related Past Observations
 
 ```typescript
 // Check if this updates or supersedes an older observation
@@ -128,24 +177,48 @@ observation({
 });
 ```
 
-## Phase 7: Output Summary
+## Phase 8: Output Summary
 
-Report what was codified:
+Present extracted learnings for user review before finalizing:
 
 ```
-## Compound Summary
+## Compound Review
 
 **Work reviewed:** [brief description]
-**Learnings captured:** [N] observations
+**Learnings extracted:** [N] observations
+
+| # | Type | Title | Impact | Action |
+|---|------|-------|--------|--------|
+| 1 | pattern | ... | high | ✅ Store |
+| 2 | warning | ... | medium | ✅ Store |
+| 3 | bugfix | ... | low | ⏭️ Skip (routine) |
+```
+
+```typescript
+question({
+  questions: [
+    {
+      header: "Approve Learnings",
+      question: "Review extracted learnings. Store all approved observations?",
+      options: [
+        { label: "Store all (Recommended)", description: "Persist all marked ✅" },
+        { label: "Let me adjust", description: "I'll modify before storing" },
+        { label: "Skip compound", description: "Nothing worth persisting" },
+      ],
+    },
+  ],
+});
+```
+
+**After approval:** Store observations and report final summary:
 
-| # | Type      | Title                        | Concepts               |
-|---|-----------|------------------------------|------------------------|
-| 1 | pattern   | ...                          | auth, jwt              |
-| 2 | gotcha    | ...                          | node, build            |
-| 3 | bugfix    | ...                          | typecheck, strict-mode |
+```
+## Compound Summary
 
+**Observations stored:** [N]
+**Superseded:** [N] older observations updated
 **AGENTS.md updates suggested:** [yes/no - describe if yes]
-**Next recommended:** /pr  (or /plan <next-bead-id>)
+**Next recommended:** /pr (or /plan <next-bead-id>)
 ```
 
 ## When Nothing to Compound
@@ -158,9 +231,10 @@ Don't force observations. Quality over quantity.
 
 ## Related Commands
 
-| Need                   | Command   |
-| ---------------------- | --------- |
-| Full chain             | `/lfg`    |
-| Review before compound | `/review` |
-| Ship the work          | `/ship`   |
-| Create PR              | `/pr`     |
+| Need            | Command            |
+| --------------- | ------------------ |
+| Full chain      | `/lfg`             |
+| Review codebase | `/review-codebase` |
+| Ship the work   | `/ship`            |
+| Curate memory   | `/curate`          |
+| Create PR       | `/pr`              |