opencodekit 0.21.10 → 0.23.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/development-lifecycle/SKILL.md

@@ -57,7 +57,7 @@ This skill orchestrates the complete feature development workflow, guiding you t
                                                                           └─────────────┘
 ```
 
-**Note:** Research (`/research <bead-id>`) can happen at any phase when you need external information or deeper codebase understanding. It's not a sequential step but a parallel activity.
+**Note:** Research (`/research <plan-id>`) can happen at any phase when you need external information or deeper codebase understanding. It's not a sequential step but a parallel activity.
 
 ## Phase 1: Ideation (brainstorming)
 
@@ -65,7 +65,7 @@ This skill orchestrates the complete feature development workflow, guiding you t
 
 - [ ] Load `brainstorming`
 - [ ] Validate design with user
-- [ ] Write `.beads/artifacts/<bead-id>/design.md`
+- [ ] Write `.opencode/artifacts/<slug>/design.md`
 
 **When:** You have a rough idea but need to explore and refine it.
 
@@ -81,7 +81,7 @@ This skill orchestrates the complete feature development workflow, guiding you t
 **Exit criteria:**
 
 - Design validated by user
-- Output: `.beads/artifacts/<bead-id>/design.md`
+- Output: `.opencode/artifacts/<slug>/design.md`
 
 **Template:** `.opencode/memory/_templates/design.md`
 
@@ -91,9 +91,9 @@ This skill orchestrates the complete feature development workflow, guiding you t
 
 ### Phase 2 Checklist
 
-- [ ] Confirm or create bead id
+- [ ] Confirm or create plan context
 - [ ] Ask clarifying questions
-- [ ] Write `.beads/artifacts/<bead-id>/prd.md`
+- [ ] Write `.opencode/artifacts/<slug>/spec.md`
 
 **When:** Design is validated, need formal requirements and task breakdown.
 
@@ -101,7 +101,7 @@ This skill orchestrates the complete feature development workflow, guiding you t
 
 **Process:**
 
-1. Confirm bead id (create if needed: `br create "Feature Name"`)
+1. Confirm or create plan context
 2. Ask clarifying questions (5-7 max)
 3. Explore codebase patterns and constraints
 4. Write PRD with machine-convertible Tasks section
@@ -109,7 +109,7 @@ This skill orchestrates the complete feature development workflow, guiding you t
 **Exit criteria:**
 
 - PRD with all sections completed
-- Output: `.beads/artifacts/<bead-id>/prd.md`
+- Output: `.opencode/artifacts/<slug>/spec.md`
 
 **Template:** `.opencode/memory/_templates/prd.md`
 
@@ -119,25 +119,25 @@ This skill orchestrates the complete feature development workflow, guiding you t
 
 ### Phase 3 Checklist
 
-- [ ] Read PRD from `.beads/artifacts/<bead-id>/prd.md`
-- [ ] Generate `.beads/artifacts/<bead-id>/prd.json`
-- [ ] Ensure `progress.txt` exists
+- [ ] Read PRD from `.opencode/artifacts/<slug>/spec.md`
+- [ ] Generate `.opencode/artifacts/tasks.json`
+- [ ] Ensure `.opencode/artifacts/progress.txt` exists
 
 **When:** PRD is complete, need executable task list.
 
-**Entry criteria:** PRD exists at `.beads/artifacts/<bead-id>/prd.md`.
+**Entry criteria:** PRD exists at `.opencode/artifacts/<slug>/spec.md`.
 
 **Process:**
 
 1. Read PRD and extract ## Tasks section
 2. Convert to JSON format with dependencies
-3. Create progress.txt for cross-iteration memory
+3. Create `.opencode/artifacts/progress.txt` for cross-iteration memory
 
 **Exit criteria:**
 
 - JSON task file created
 - Progress file initialized
-- Output: `.beads/artifacts/<bead-id>/prd.json`, `progress.txt`
+- Output: `.opencode/artifacts/tasks.json`, `.opencode/artifacts/progress.txt`
 
 ---
 
@@ -147,11 +147,11 @@ This skill orchestrates the complete feature development workflow, guiding you t
 
 - [ ] Create bite-sized tasks with exact file paths
 - [ ] Include TDD steps and verification commands
-- [ ] Write `.beads/artifacts/<bead-id>/plan.md`
+- [ ] Write `.opencode/artifacts/<slug>/plan.md`
 
 **When:** Tasks defined, need detailed implementation instructions.
 
-**Entry criteria:** Task list exists (prd.json or tasks.md).
+**Entry criteria:** Task list exists (tasks.json or tasks.md).
 
 **Process:**
 
@@ -163,7 +163,7 @@ This skill orchestrates the complete feature development workflow, guiding you t
 **Exit criteria:**
 
 - Detailed plan ready for execution
-- Output: `.beads/artifacts/<bead-id>/plan.md`
+- Output: `.opencode/artifacts/<slug>/plan.md`
 
 **Template:** `.opencode/memory/_templates/tasks.md` (for task structure reference)
 
@@ -179,7 +179,7 @@ This skill orchestrates the complete feature development workflow, guiding you t
 
 **When:** Plan is ready, time to build.
 
-**Entry criteria:** Plan exists at `.beads/artifacts/<bead-id>/plan.md`.
+**Entry criteria:** Plan exists at `.opencode/artifacts/<slug>/plan.md`.
 
 **Process:**
 
@@ -202,7 +202,7 @@ This skill orchestrates the complete feature development workflow, guiding you t
 
 - [ ] Identify verification commands
 - [ ] Run full verification suite
-- [ ] Only then claim completion and close bead
+- [ ] Only then claim completion
 
 **When:** Implementation complete, before claiming done.
 
@@ -219,7 +219,7 @@ This skill orchestrates the complete feature development workflow, guiding you t
 **Exit criteria:**
 
 - All verification commands pass with evidence
-- Bead can be closed: `br close <bead-id>`
+- All tasks verified complete
 
 ---
 
@@ -246,28 +246,9 @@ For small changes, you can skip early phases:
 
 ---
 
-## Beads Integration
-
-Every phase should operate within a bead context:
-
-```bash
-# Create bead for new feature
-br create "Feature Name"
-
-# Check current bead status
-br show <bead-id>
-
-# Update status as you progress
-br update <bead-id> --status in_progress
-
-# Close when complete
-br close <bead-id> --reason "All verification passed"
+---
 
-# Sync changes
-br sync --flush-only
-```
 
----
 
 ## Example Full Workflow
 
@@ -278,23 +259,23 @@ User: "I want to add a dark mode toggle"
    → skill({ name: "brainstorming" })
    → Questions about scope, triggers, persistence
    → Design decisions documented
-   → Output: .beads/artifacts/br-dark-mode/design.md
+   → Output: .opencode/artifacts/<slug>/design.md
 
 2. SPECIFICATION
    → skill({ name: "prd" })
    → Full PRD with requirements
    → Tasks section for conversion
-   → Output: .beads/artifacts/br-dark-mode/prd.md
+   → Output: .opencode/artifacts/<slug>/spec.md
 
 3. TASK CONVERSION
    → skill({ name: "prd-task" })
    → JSON task list with dependencies
-   → Output: .beads/artifacts/br-dark-mode/prd.json
+   → Output: .opencode/artifacts/tasks.json
 
 4. PLANNING
    → skill({ name: "writing-plans" })
    → Bite-sized implementation steps
-   → Output: .beads/artifacts/br-dark-mode/plan.md
+   → Output: .opencode/artifacts/<slug>/plan.md
 
 5. IMPLEMENTATION
    → skill({ name: "executing-plans" })
@@ -306,7 +287,7 @@ User: "I want to add a dark mode toggle"
    → Tests pass: ✓
    → Lint clean: ✓
    → Build succeeds: ✓
-   → br close br-dark-mode --reason "Dark mode implemented and verified"
+    → All gates pass: ✓
 ```
 
 ---
@@ -316,5 +297,5 @@ User: "I want to add a dark mode toggle"
 1. **Phase-appropriate skills:** Load the right skill for each phase
 2. **Evidence at every gate:** No phase transition without verification
 3. **Templates guide structure:** Use templates for consistent output
-4. **Beads track progress:** Every feature gets a bead
+4. **Plans track progress:** Every feature gets a plan
 5. **Skip only when appropriate:** Small changes can skip early phases

package/dist/template/.opencode/skill/gemini-large-context/SKILL.md

@@ -130,12 +130,12 @@ Assess test coverage:
 When researching within task boundaries:
 
 ```bash
-# 1. Include bead spec in context
-gemini -p "@src/ @.beads/artifacts/br-xxx/spec.md
+# 1. Include plan spec in context
+gemini -p "@src/ @.opencode/artifacts/$(cat .opencode/artifacts/.active)/spec.md
 Research implementations matching spec constraints"
 
-# 2. Save findings to bead artifacts
-# Write to .beads/artifacts/br-xxx/research.md
+# 2. Save findings to plan files
+# Write to .opencode/artifacts/$(cat .opencode/artifacts/.active)/research.md
 ```
 
 ### Delegating Large Research to Gemini

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>
+```