opencodekit 0.21.9 → 0.22.0

package/dist/template/.opencode/skill/debugging-and-error-recovery/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: debugging-and-error-recovery
+description: Guides root-cause debugging and safe recovery from failures. Use when tests fail, builds break, behavior is unexpected, or multiple fix attempts have not worked.
+version: 1.0.0
+tags: [debugging, workflow, verification]
+dependencies: [test-driven-development, verification-before-completion]
+agent_types: [worker, reviewer]
+tools: [bash, srcwalk_search, srcwalk_deps]
+---
+
+# Debugging & Error Recovery
+
+## Overview
+
+Random fixes create new bugs. Debugging must move from symptom to root cause to guarded fix.
+
+Core principle: reproduce, localize, reduce, fix, and guard before claiming resolution.
+
+## When to Use
+
+- Test, lint, typecheck, build, or runtime failure.
+- User reports a bug or unexpected behavior.
+- A previous fix failed.
+- Error crosses multiple layers or components.
+
+## When NOT to Use
+
+- Feature work with no failure signal; use `incremental-implementation`.
+- Pure research; use `source-driven-development`.
+
+## Workflow
+
+1. Read the full error and relevant logs.
+2. Reproduce the failure or state why it cannot be reproduced.
+3. Localize the failing layer: input, boundary, business logic, integration, environment.
+4. Reduce to the smallest failing case.
+5. Form one hypothesis and test it with one change or one diagnostic.
+6. Write a failing regression test when behavior can be tested.
+7. Fix the root cause, not only the symptom.
+8. Run the original reproduction and relevant regression checks.
+9. If three fix attempts fail, stop and escalate architecture/assumption risk.
+
+## Evidence Log
+
+For complex bugs, maintain a short log in the response or a debug artifact:
+
+```markdown
+## Symptoms
+- ...
+## Reproduction
+- ...
+## Hypotheses Eliminated
+- ...
+## Root Cause
+- ...
+## Fix and Guard
+- ...
+```
+
+## Common Rationalizations
+
+| Rationalization | Rebuttal |
+| --- | --- |
+| "This is probably the issue" | Probably is a hypothesis, not evidence. Test it minimally. |
+| "I'll patch the symptom now" | Symptom patches hide root causes and regress later. |
+| "Multiple fixes will save time" | You will not know which change mattered. |
+| "The test failure is unrelated" | Prove it with isolation before ignoring it. |
+| "One more attempt" | After three failed fixes, the model is wrong. Stop and rethink. |
+
+## Red Flags
+
+- Code changes before reproduction.
+- Fix proposed before reading the full error.
+- Same failure persists after two attempts.
+- New failures appear in different layers.
+- Regression test is skipped for a reproducible bug.
+- Success claimed without re-running the original failing scenario.
+
+## Verification
+
+- Original failure is reproduced or documented as non-reproducible.
+- Root cause is stated with evidence.
+- Regression test or guard exists when feasible.
+- Original scenario now passes.
+- Related tests/checks pass.
+
+## Skill Result Contract
+
+```xml
+<skill_result>
+  <skill>debugging-and-error-recovery</skill>
+  <status>success|partial|blocked|failure</status>
+  <evidence>Reproduction, root cause, fix, and verification commands</evidence>
+  <artifacts>Changed files, tests, debug notes</artifacts>
+  <risks>Non-reproducible behavior, missing regression test, or none</risks>
+</skill_result>
+```
+
+
+## Consolidated Debugging Workflow
+
+This is the canonical active debugging skill. It absorbs systematic-debugging while preserving root-cause discipline. Use root-cause-tracing as an advanced companion when the failure is deep in execution.
+
+Required posture:
+- reproduce or observe the failure before fixing;
+- state the hypothesis and evidence;
+- change one causal layer at a time;
+- verify the failure mode is gone;
+- record recovery actions and residual risk.

package/dist/template/.opencode/skill/deep-module-design/SKILL.md

@@ -0,0 +1,207 @@
+---
+name: deep-module-design
+description: Applies Ousterhout's deep module principles to code design — small interfaces, information hiding, pull complexity downward. Use when designing modules, refactoring shallow structures, or reviewing AI-generated code for structural quality.
+version: 1.0.0
+tags: [architecture, code-quality, ousterhout]
+dependencies: []
+agent_types: [planner, worker, reviewer]
+tools: [srcwalk_search, srcwalk_deps]
+---
+
+# Deep Module Design
+
+> Based on John Ousterhout's *A Philosophy of Software Design*
+
+## Overview
+
+A deep module has a **small interface relative to its implementation**. It provides significant functionality through a compact abstraction, hiding complexity from its callers. A shallow module has an **interface as complex as its implementation** — it wraps one small thing with ceremony, adding overhead without hiding anything.
+
+**Why this matters for AI agents:** AI coding tools generate code faster than humans can review. Shallow modules compound this problem — every AI pass can produce more tiny, shallow abstractions that increase cognitive load without reducing complexity. Deep modules constrain the AI: a small, stable interface limits the blast radius of AI-generated changes and makes verification tractable.
+
+> *"The most important technique for achieving deep modules is information hiding."* — Ousterhout
+
+## When to Use
+
+- Designing a new module, class, or API boundary
+- Reviewing code for structural quality (beyond just correctness)
+- Refactoring a codebase where changes are too expensive because interfaces are too complex
+- Working with AI agents that need tight, stable interfaces to produce reliable code
+- Any time you find yourself writing a class/method that just calls another class/method
+
+## When NOT to Use
+
+- Prototyping where the abstraction will change completely (use after stabilization)
+- Tiny utility functions that are inherently single-purpose and shallow by nature
+- Code that will be replaced within the sprint
+
+## Core Concept: Deep vs Shallow
+
+### Deep Module
+
+```
+┌─────────────────────────────────────┐
+│       COMPLEX IMPLEMENTATION        │
+│   (caching, retries, batching,      │
+│    connection pooling, fallbacks)    │
+│                                     │
+│   ┌─────────────────────────────┐   │
+│   │     SMALL INTERFACE         │   │
+│   │   get(key), set(key, val)   │   │
+│   └─────────────────────────────┘   │
+└─────────────────────────────────────┘
+```
+
+Example: Unix I/O (`open`, `read`, `write`, `close`). Five system calls hide filesystems, device drivers, disk scheduling, buffering, permissions, and network mounts. The interface has not changed in decades.
+
+### Shallow Module
+
+```
+┌─────────────────────┐
+│  SMALL IMPLEMENT.   │
+│  (just wraps one    │
+│   function call)    │
+│                     │
+│  ┌───────────────┐  │
+│  │ COMPLEX IFACE │  │
+│  │ many methods,  │  │
+│  │ many config    │  │
+│  │ options        │  │
+│  └───────────────┘  │
+└─────────────────────┘
+```
+
+Example: A "ParserFactory" that has one method `createParser(type)` which does a switch statement. The factory adds a class, an interface, and a registration mechanism — more surface area than the problem requires. Better to just call the parser directly or use a simple config object.
+
+### Self-Test
+
+Ask about ANY module you design or review:
+
+> "Can I understand this module's interface in 30 seconds?"
+> "Does the caller need to know implementation details to use it?"
+> "Is this module's API surface area proportional to the complexity it hides?"
+
+If the interface takes longer to learn than the implementation, the module is shallow — either deepen it or eliminate it.
+
+## Design Principles
+
+### 1. Information Hiding
+
+The most important technique for achieving deep modules. Every implementation detail that callers don't need to know about should be private, internal, or abstracted away.
+
+**Signs of information leakage:**
+- Configuration that callers must set but relates to internal behavior (buffer sizes, retry counts, thread pool sizes)
+- Methods that expose internal types (returning database rows, internal DTOs)
+- Callers constructing complex intermediate objects before calling your API
+
+**Fix:** Move the complexity inside. Default everything. Accept simple inputs.
+
+### 2. Pull Complexity Downward
+
+If a feature introduces complexity, handle it inside the module rather than pushing it to callers.
+
+| ❌ Pushed to caller | ✅ Pulled downward |
+|---|---|
+| Caller must handle retries, timeouts, and fallbacks | Module handles them internally |
+| Caller must format data correctly before passing | Module accepts raw data and transforms it |
+| Caller must manage connection lifecycle | Module manages pools transparently |
+
+> *"It is more important for a module to have a simple interface than a simple implementation."* — Ousterhout
+
+### 3. General-Purpose vs Special-Purpose
+
+General-purpose modules tend to be **deeper** because they solve a class of problems, not just one specific case. Special-purpose modules tend to be **shallower** because they're closely coupled to one use case.
+
+**Rule of thumb:** Design modules to solve general problems. A "UserRepository" is deep (CRUD + queries for any user need). A "GetUserForLoginHandler" is shallow (only handles one specific query) — better to have a general `getUser` method and let callers filter as needed.
+
+**Exception:** If the general-purpose interface would be significantly harder to understand, keep it special-purpose. Depth wins over generality.
+
+### 4. Different Layer, Different Abstraction
+
+Each layer of a system should provide a **different abstraction**. If two layers provide the same abstraction, one of them is redundant.
+
+**Red flag — pass-through methods:**
+```typescript
+// Layer 2: Service layer
+class UserService {
+  constructor(private repo: UserRepository) {}
+
+  // This is a pass-through — it adds nothing
+  getUser(id: string) {
+    return this.repo.findById(id);
+  }
+}
+```
+
+If a method does nothing except delegate with the exact same signature, it's a **pass-through method** — a sign the layer boundary is wrong. Either make the layer do something meaningful, or remove it.
+
+**Red flag — pass-through variables:**
+```typescript
+// Top-level handler
+function handleRequest(req, config) {
+  return processRequest(req, config);
+}
+
+// Middle layer
+function processRequest(req, config) {
+  return executeQuery(req, config);
+}
+
+// Bottom layer
+function executeQuery(req, config) {
+  return db.query(req, config);
+}
+```
+
+When the same variable (`config`) passes through multiple layers without being used by the middle layers, it's a **pass-through variable**. This couples all layers to the config shape. Fix: put config in a global context, or restructure so the middle layers don't need it.
+
+## Red Flag Catalog
+
+| Red Flag | What it looks like | Fix |
+|---|---|---|
+| **Shallow module** | Interface as complex as its implementation | Eliminate or merge into caller |
+| **Information leakage** | One module exposes types another module depends on | Move the types to a shared neutral location or hide them |
+| **Pass-through method** | Method just delegates with same signature | Remove the middle layer or make it add value |
+| **Pass-through variable** | Same data flows through many layers unused | Use a context object or restructure |
+| **Replicated code smell** | Same pattern appears across modules instead of once | Extract a deeper module that encapsulates the pattern |
+| **Configuration pollution** | Callers must configure internal behavior (buffer sizes, timeouts) | Auto-detect or default everything |
+| **Returning internal state** | API exposes DB rows, internal DTOs, or raw storage types | Map to public types at the boundary |
+| **Temporal coupling** | Methods must be called in a specific order not enforced by types | Design so invalid states are unrepresentable |
+
+## AI-Specific Applications
+
+Deep modules are especially valuable for AI-generated code:
+
+| Problem | Deep module solution |
+|---|---|
+| AI creates shallow wrappers every time it refactors | Eliminate or merge them — keep the abstraction layer count minimal |
+| AI introduces pass-through methods when adding layers | Spot them in review and remove — they add surface area without depth |
+| AI makes cascading changes because interfaces are too wide | Narrow interfaces — a small, stable surface limits blast radius |
+| AI generates inconsistent implementations across similar operations | Create one deep general-purpose module the AI can reuse instead of reimplementing |
+| AI hallucinates configuration options the module doesn't need | Remove configurability — deep modules default aggressively |
+
+## Verification
+
+- [ ] Every module's interface is easier to understand than its implementation
+- [ ] No pass-through methods (methods that just delegate with same signature)
+- [ ] No information leakage (callers don't depend on internal types)
+- [ ] No configuration that should be internalized
+- [ ] Different layers provide different abstractions
+- [ ] AI agents could safely use this module without reading its implementation
+
+## See Also
+
+- **code-review-and-quality** — Assess for shallow modules and information leakage during review
+- **api-and-interface-design** — Deep module principles applied to REST/API design
+- **code-cleanup** — Consolidate shallow modules during cleanup passes
+
+## Skill Result Contract
+
+```xml
+<skill_result>
+  <skill>deep-module-design</skill>
+  <status>success|partial|blocked|failure</status>
+  <evidence>Modules assessed, red flags found or cleared, depth ratio evaluated</evidence>
+  <artifacts>Files or modules reviewed/designed</artifacts>
+  <risks>Known shallow modules deferred, or none</risks>
+</skill_result>
+```

package/dist/template/.opencode/skill/git-workflow-and-versioning/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: git-workflow-and-versioning
+description: Use when making code changes that need safe git hygiene, atomic commits, branch strategy, versioning, changelog entries, or release preparation. Covers trunk-based development, commit-as-save-point discipline, and avoiding accidental unrelated changes.
+version: 1.0.0
+tags: [git, workflow, shipping]
+dependencies: []
+agent_types: [planner, worker, reviewer]
+tools: [bash]
+---
+
+# Git Workflow and Versioning
+
+## Overview
+
+Git workflow keeps changes reviewable, reversible, and shippable. Treat commits as verified save points, not dumping grounds.
+
+## When to Use
+
+- Any meaningful code change that may be committed, reviewed, or shipped.
+- Creating or finishing a feature branch.
+- Preparing release notes, version bumps, or changelog entries.
+- Splitting a large diff into safe review units.
+- Working in a dirty worktree where unrelated user changes may exist.
+
+## When NOT to Use
+
+- Read-only investigation with no file changes.
+- Throwaway local experiments that will be discarded before reporting.
+
+## Process
+
+1. Inspect worktree state before editing: `git status --short`.
+2. Identify unrelated changes and leave them untouched.
+3. Keep each change atomic: one intent, one reviewable diff, one verification story.
+4. Prefer trunk-based flow: short-lived branches, small PRs, frequent integration.
+5. Use commits as save points only after verification passes or after clearly labeling partial work.
+6. Scope staging to your files only; never use `git add .` in a mixed worktree.
+7. For versioning, update the smallest required surface: package version, changelog, migration note, release tag, or docs.
+8. Before shipping, confirm status, diff summary, verification evidence, and rollback path.
+
+## Common Rationalizations
+
+| Rationalization | Rebuttal |
+| --- | --- |
+| "I'll clean up the commit later." | Later cleanup often loses intent. Keep the diff clean while it is fresh. |
+| "This unrelated formatting is harmless." | It increases review noise and can hide real regressions. |
+| "One big commit is faster." | Small verified commits are easier to review, revert, bisect, and ship. |
+| "The worktree was already dirty." | Dirty worktrees require more discipline, not less. |
+
+## Red Flags
+
+- Staging broad paths without reviewing the diff.
+- Mixing feature work, refactors, formatting, and dependency updates.
+- Committing generated or cache files unintentionally.
+- Version bump without changelog or release rationale.
+- Claiming clean worktree without checking status.
+
+## Verification
+
+Before declaring git workflow complete, provide:
+
+- `git status --short` summary.
+- Diff or staged-file summary for touched files.
+- Verification commands and outcomes.
+- Commit/version/changelog action taken, or explicit reason none was needed.
+
+## Skill Result Contract
+
+```xml
+<skill_result>
+  <skill>git-workflow-and-versioning</skill>
+  <status>completed|blocked|skipped</status>
+  <artifacts>Branch, commit, changelog, version file, or none</artifacts>
+  <evidence>git status/diff summary and verification commands</evidence>
+  <risks>Unrelated worktree changes, uncommitted files, release risk, or none</risks>
+</skill_result>
+```

package/dist/template/.opencode/skill/grill-me/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: grill-me
+description: Adversarial interrogation of ideas before implementation — pushes on ambiguity, hidden assumptions, missing constraints, and hand-waving. Use when you have a rough idea, ADR, PRD, or spec that needs to survive scrutiny before code is written.
+version: 1.0.0
+tags: [planning, review, decision]
+dependencies: [brainstorming, spec-driven-development]
+agent_types: [planner, worker, reviewer]
+tools: []
+---
+
+# Grill Me — Adversarial Idea Interrogation
+
+> **Replaces** skipping straight from idea to implementation without pressure-testing the plan.
+> **Sits between** `brainstorming` (collaborative refinement) and `spec-driven-development` (formal spec/ADR creation).
+
+## When to Use
+
+- You have a rough idea that needs to be tested before implementation
+- You just finished brainstorming and need to find the flaws
+- You have an existing ADR, PRD, or spec that needs to be stress-tested
+- The agent (me) seems unclear about what to build and you want to surface that confusion
+
+## When NOT to Use
+
+- Requirements are already well-understood and the task is mechanical
+- You are already in implementation with a validated plan
+- The task is trivial (< 1 file, no decisions needed)
+- You need creative exploration (use `brainstorming` instead)
+
+## How This Is Different From Brainstorming
+
+| Brainstorming | Grill Me |
+|---|---|
+| Collaborative exploration | Adversarial interrogation |
+| "What do we need to build?" | "Why is this idea wrong or incomplete?" |
+| Generates options and approaches | Destroys weak options |
+| Asks clarifying questions | Asks challenging, uncomfortable questions |
+| Refines the idea | Tests if the idea survives scrutiny |
+| Output: a better design | Output: resolved uncertainties, killed bad ideas, hardened decisions |
+
+## Process
+
+### Phase 1: Surface the Idea
+
+Read the available context — the user's prompt, any existing docs, the repo structure, relevant code. Identify exactly what is being proposed. Restate it clearly so the human can correct any misunderstanding.
+
+### Phase 2: Interrogate
+
+Go after the idea systematically. Do not be polite. Do not assume the idea is sound. Push on:
+
+**Ambiguity**
+- Which terms in this description could mean different things to different people?
+- What's the actual scope boundary — what's explicitly in, what's explicitly out?
+- Can you point to a concrete example of the expected behavior?
+
+**Hidden assumptions**
+- What does this idea assume about the existing system?
+- What does it assume about user behavior, data quality, or failure modes?
+- What does it assume about team capacity, deployment timeline, or external dependencies?
+- What does it assume the human reviewer will accept without question?
+
+**Missing constraints**
+- What constraints are implicit but never stated?
+- Performance? Security? Backward compatibility? Error handling? Observability?
+- What existing patterns in the codebase constrain this design?
+- What deadlines or external commitments constrain the approach?
+
+**Hand-waving**
+- Where does the idea say "we'll figure that out later"?
+- Where are the "obviously" or "simply" or "just" statements? Those are hiding complexity.
+- What's the hardest part of this idea, and how does the current plan address it?
+- What would have to go wrong for this idea to fail, and how would we know?
+
+**Integration & blast radius**
+- What existing code would this touch?
+- What would break if this change were deployed?
+- What tests would need to change?
+- What documentation would become outdated?
+
+### Phase 3: Resolve
+
+For each question raised in Phase 2:
+
+1. Present the question to the human with a concrete example
+2. Let the human answer or make a decision
+3. Record the resolution
+4. Update any existing documents (ADR, PRD, spec) with the new information
+
+If the human cannot answer a question, flag it as a blocker — do not proceed to implementation until it's resolved.
+
+### Phase 4: Assess
+
+After all questions have been addressed:
+
+- **Is the idea clearly defined enough to proceed?** YES → recommend writing it up as an ADR or spec via `documentation-and-adrs` or `spec-driven-development`.
+- **Is the idea fundamentally flawed?** YES → say so directly. Explain why and suggest alternatives.
+- **Are there too many unresolved questions?** YES → recommend another brainstorming round or more research before committing to implementation.
+
+### Phase 5 (optional): Grill-with-Docs
+
+If you're working with an existing ADR, PRD, or spec document:
+
+1. Read the document(s) thoroughly
+2. Apply the same interrogation against the document content
+3. For each gap found, propose edits to the document
+4. Present the proposed edits to the human for approval
+5. Apply approved edits
+
+## Success Criteria
+
+The grilling is complete when:
+- Questions start repeating (you've exhausted the line of inquiry)
+- Added precision stops changing the plan (diminishing returns)
+- Every ambiguity, assumption, constraint gap, and hand-wave has been surfaced and either resolved or flagged as a blocker
+- You can state clearly: "this idea is ready for an ADR/spec" or "this idea should be killed/reworked"
+
+## Output
+
+Leave behind a clear summary of:
+- What was challenged and resolved
+- What decisions were made
+- What remains blocked or unresolved
+- Recommended next step (ADR, spec, more research, kill the idea)
+
+This summary becomes the input for the next phase (ADR writing or spec-driven-development).
+
+## Anti-Patterns
+
+- **Being too nice.** This is not a collaborative exploration — this is an adversarial review. If you're not making the human think hard, you're doing it wrong.
+- **Grilling during implementation.** Do this BEFORE any code is written. Once files change, the cost of finding a flaw is much higher.
+- **Grilling trivial tasks.** A one-line bugfix doesn't need this. Use judgment.
+- **Accepting "we'll fix it later."** If something is identified as risky, it needs a decision now or a clear blocker flag.
+- **Grilling without context.** Read the repo, understand the existing patterns, and ground your questions in actual code.
+
+## See Also
+
+- `brainstorming` — collaborative exploration (use before grilling)
+- `spec-driven-development` — formal spec writing (use after grilling)
+- `documentation-and-adrs` — recording decisions in ADR format
+- `development-lifecycle` — full phased workflow

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

@@ -31,21 +31,20 @@ dependencies: []
    - Run `memory-search` with task keywords before implementation.
    - Check recent handoffs when resuming interrupted work.
 2. **Calibrate (progressive disclosure)**
-   - Use search results as index.
-   - Fetch full entries only for relevant IDs (`memory-get`).
-   - Pull timeline context only when sequencing matters (`memory-timeline`).
+   - Use search results as index; `memory-search({ file: "..." })` for file access.
+   - Retrieve full observation details from search output.
 3. **Record (high-signal only)**
    - Create `observation` for decisions, bugfixes, patterns, warnings, or durable learnings.
    - Include searchable concepts and concrete file references.
 4. **Handoff (if session boundary)**
-   - Write a concise status note with completed work, blockers, and next steps using `memory-update` under `handoffs/`.
+   - Write a concise status note with completed work, blockers, and next steps using `observation`.
 
 ## What Goes Where
 
 | Store | Put Here | Avoid Here |
 | --- | --- | --- |
-| `observation` (SQLite) | Events: decisions, bugfixes, reusable patterns, warnings | Temporary notes, speculative ideas without evidence |
-| `memory-update` files | Durable docs: handoffs, research, project notes | Every minor runtime detail from a single debug run |
+| `observation` (SQLite) | Events: decisions, bugfixes, reusable patterns, warnings, handoffs | Temporary notes, speculative ideas without evidence |
+| `memory-search` by file | Durable docs: handoffs, research, project notes | Every minor runtime detail from a single debug run |
 | Auto pipeline | Captured messages + distillations (automatic) | Manual copying of full transcripts |
 
 ## Observation Quality Bar
@@ -66,7 +65,7 @@ If most answers are "no", skip creating the observation.
 | Storing transient debugging info as permanent observations | Pollutes search results with low-value noise | Keep transient info in session context; record only durable findings |
 | Creating observations for every small finding (signal-to-noise) | Important items get buried and retrieval quality drops | Batch minor notes; publish one distilled observation per meaningful outcome |
 | Not searching memory before creating duplicate observations | Produces conflicting/duplicated records | Run `memory-search` first; update/supersede existing records when appropriate |
-| Using `memory-update` for data that should be an observation | Durable events become hard to discover and rank | Use `observation` for events; reserve `memory-update` for document-style files |
+| Using `observation` with `file` param for document-style content | Document-style content should use `memory-search({ file: "..." })` for file access | Use `observation` for events; write to memory files when structured document storage is needed |
 
 ## Verification
 
@@ -114,9 +113,9 @@ 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
+memory-search({ file: "index" })             // Full observation catalog
+memory-search({ file: "compiled/auth" })      // Compiled article for "auth" concept
+memory-search({ file: "log" })                // Operation audit trail
 ```
 
 ## Validation Gate