opencodekit 0.22.0 → 0.23.1

package/dist/template/.opencode/plans/swarm-protocol.md

@@ -1,123 +0,0 @@
-# Swarm Protocol (Beads-as-Board)
-
-## Goal
-
-Use `.beads/` as the single source of truth for task state + dependencies, while agents coordinate through structured artifacts (not freeform chatter) and verification gates.
-
-## Roles (Strict)
-
-- Lead: Owns scope, prioritization, and all Beads state transitions.
-- Planner: Turns intent into Beads tasks + dependency DAG; no code changes.
-- Worker: Executes exactly one claimed task; posts a structured report.
-- Verifier: Independently validates acceptance checks; blocks close on missing evidence.
-
-## Board = Beads
-
-Canonical state lives in `.beads/issues.jsonl` (tasks) and `.beads/artifacts/<id>/` (task artifacts).
-
-- Create tasks: `br create "Title" -p <1-3>`
-- See unblocked work: `br ready`
-- Inspect context: `br show <id>`
-- Claim work: `br update <id> --status=in_progress`
-- Close work: `br close <id> --reason="..."` then `br sync --flush-only`
-
-## Task Artifact Contract
-
-Every task MUST have `.beads/artifacts/<id>/spec.md`.
-
-Optional supporting files:
-
-- `.beads/artifacts/<id>/plan.md`: multi-step implementation plan, files touched, and gates
-- `.beads/artifacts/<id>/review.md`: verifier notes + evidence summary
-
-### spec.md (Minimum Template)
-
-- Context: why this exists
-- Scope: in / out
-- Constraints: MUST / MUST NOT (security, deps, dist/, etc.)
-- Acceptance Criteria: checkboxes, each with a verification method
-- Evidence Required: exact commands and expected signals (e.g. "typecheck command passes")
-
-#### Verification Defaults (Language-Agnostic)
-
-Do NOT assume npm/pnpm/pytest/etc. Prefer this pattern:
-
-- `typecheck`: `<command>`
-- `lint`: `<command>`
-- `test`: `<command>`
-- `build` (optional): `<command>`
-
-If the repository has a canonical list of commands, reference it (e.g. `.opencode/memory/project/commands.md`).
-
-Common stacks (examples only):
-
-| Stack   | typecheck                                  | lint                         | test                   |
-| ------- | ------------------------------------------ | ---------------------------- | ---------------------- |
-| Node/TS | `npm run typecheck` or `npm run typecheck` | `npm run lint`               | `vitest` or `npm test` |
-| Python  | `python -m mypy .`                         | `ruff check .`               | `pytest`               |
-| Go      | `go test ./...` (compile+test)             | `golangci-lint run`          | `go test ./...`        |
-| Rust    | `cargo check`                              | `cargo fmt --check` (format) | `cargo test`           |
-
-## Delegation Packet (Worker Input)
-
-Every delegated task MUST include the following envelope:
-
-- TASK: `<id> - <title>`
-- EXPECTED OUTCOME: measurable end state
-- REQUIRED TOOLS: e.g. `read`, `grep`, `lsp`, `bash`
-- MUST DO: e.g. LSP-before-edits, run typecheck, run lint
-- MUST NOT DO: e.g. no new deps, no dist/ edits, no git push
-- ACCEPTANCE CHECKS: list of commands + pass criteria
-- CONTEXT: links to `.beads/artifacts/<id>/spec.md` + relevant files
-
-### Helper Tool
-
-If available, use the custom tool `swarm-delegate` to generate (and optionally write) a delegation packet:
-
-```ts
-swarm -
-  delegate({
-    bead_id: "opencodekit-template-xyz",
-    expected_outcome: "<measurable end state>",
-    required_tools: "read, grep, lsp, bash",
-    must_do: "LSP before edits, run project verification commands",
-    must_not_do: "no new deps, don't edit dist/",
-    acceptance_checks: "typecheck: <command>, lint: <command>, test: <command>",
-    context: "See .beads/artifacts/<id>/spec.md",
-    write: true,
-  });
-```
-
-## Worker Report (Worker Output)
-
-Workers MUST respond with a structured report:
-
-- Result: done / blocked / needs replan
-- Changes: file list + what changed (with file references)
-- Verification: commands run + pass/fail summary
-- Risks/Notes: edge cases, follow-ups
-- Confidence: high / medium / low
-
-## Gates (Non-Negotiable)
-
-- Planning gate: `.beads/artifacts/<id>/spec.md` exists with acceptance criteria BEFORE implementation starts
-- Execution gate: worker provides verification evidence BEFORE close
-- Review gate (risk-based): verifier signs off in `review.md` BEFORE close
-
-## Replan Triggers
-
-Immediately stop execution and return to planning if:
-
-- Scope expands to 4+ files unexpectedly
-- Requirement ambiguity changes implementation choice
-- Two-strike tool failures
-- New dependency or `.opencode/` structure change would be needed
-
-## Lead Checklist
-
-1. `br ready` -> pick task -> `br show <id>`
-2. Ensure `.beads/artifacts/<id>/spec.md` has acceptance checks
-3. `br update <id> --status=in_progress`
-4. Delegate with the packet format
-5. Require worker report + evidence
-6. `br close <id> --reason="..."` + `br sync --flush-only`

package/dist/template/.opencode/skill/beads/SKILL.md

@@ -1,182 +0,0 @@
----
-name: beads
-description: >
-  Multi-agent task coordination using br (beads_rust) CLI. Use when work spans multiple
-  sessions, has dependencies, needs file locking, or requires agent coordination. Covers
-  claim/reserve/done cycle, dependency management, hierarchical decomposition, and session protocols.
-version: "2.0.0"
-license: MIT
-tags: [workflow, agent-coordination]
-dependencies: []
----
-
-# Beads Workflow - Multi-Agent Task Coordination
-
-> **Replaces** ad-hoc task tracking with sticky notes, TODO comments, or mental checklists that lose state between sessions
-
-## When to Use
-
-- Coordinating multi-session work with dependencies, blockers, or file locking needs
-- Running multi-agent work where tasks must persist across sessions and handoffs
-
-## When NOT to Use
-
-- Single-session, linear tasks tracked via TodoWrite
-- Quick changes with no dependencies or handoff needs
-
-## Overview
-
-**br (beads_rust) CLI** replaces the old `bd` (beads) CLI with a faster Rust implementation.
-
-**Key Distinction**:
-
-- **br CLI**: Multi-session work, dependencies, file locking, agent coordination
-- **TodoWrite**: Single-session tasks, linear execution, conversation-scoped
-
-**When to Use br vs TodoWrite**:
-
-- "Will I need this context in 2 weeks?" → **YES** = br
-- "Does this have blockers/dependencies?" → **YES** = br
-- "Multiple agents editing same codebase?" → **YES** = br
-- "Will this be done in this session?" → **YES** = TodoWrite
-
-**Decision Rule**: If resuming in 2 weeks would be hard without beads, use beads.
-
-## Essential Commands
-
-```bash
-br ready              # Show issues ready to work (no blockers)
-br list --status open # All open issues
-br show <id>          # Full issue details with dependencies
-br create --title "Fix bug" --type bug --priority 2 --description "Details here"
-br update <id> --status in_progress
-br close <id> --reason "Completed"
-br sync --flush-only  # Export to JSONL (then git add/commit manually)
-```
-
-## Hierarchy & Dependencies (Summary)
-
-- Beads supports up to 3 levels of hierarchy: Epic → Task → Subtask
-- Use hierarchy for multi-day, cross-domain, or multi-agent work
-- Dependencies unblock parallel work when parents close
-
-See: `references/HIERARCHY.md` and `references/DEPENDENCIES.md` for full details.
-
-## Session Protocol (Summary)
-
-**Start:** `br ready` → `br update <id> --status in_progress` → `br show <id>`
-
-**End:** `br close <id> --reason "..."` → `br sync --flush-only` → commit `.beads/` → restart session
-
-See: `references/SESSION_PROTOCOL.md` and `references/WORKFLOWS.md` for detailed steps and checklists.
-
-## Task Creation (Summary)
-
-Create tasks when work spans sessions, has dependencies, or is discovered mid-implementation (>2 min).
-
-```bash
-br create --title "Fix authentication bug" --priority 0 --type bug
-```
-
-See: `references/TASK_CREATION.md` for full examples and patterns.
-
-## Git Sync (Summary)
-
-`br` never runs git commands. Always `br sync --flush-only` and commit `.beads/` manually.
-
-See: `references/GIT_SYNC.md` for detailed flow and cleanup guidance.
-
-## Troubleshooting (Summary)
-
-- No ready tasks → `br list --status open`, check blockers via `br show <id>`
-- Sync failures → `br doctor`
-
-See: `references/TROUBLESHOOTING.md` for common issues and fixes.
-
-## Examples
-
-See: `references/EXAMPLES.md` for complete usage examples.
-
-## Multi-Agent Coordination (Summary)
-
-For parallel execution with multiple subagents, use the **swarm-coordination** skill.
-
-See: `references/MULTI_AGENT.md` for swarm tool usage and examples.
-
-## Rules
-
-1. **Check `br ready` first** - Find unblocked work before starting
-2. **Claim before editing** - `br update <id> --status in_progress`
-3. **One task per session** - Restart after `br close`
-4. **Always sync and commit** - `br sync --flush-only` then `git add .beads/ && git commit`
-5. **Write notes for future agents** - Assume zero conversation context
-6. **Claim file paths before editing** - Use reserve to declare ownership (multi-agent only)
-
-## Anti-Patterns
-
-| Anti-Pattern                                                        | Why It Fails                                                  | Instead                                                          |
-| ------------------------------------------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------- |
-| Claiming a bead without reading its current state first (`br show`) | Misses dependencies, blockers, and prior context              | Run `br show <id>` before `br update <id> --status in_progress`  |
-| Closing a bead without verification evidence                        | Marks incomplete or broken work as done                       | Run verification commands and capture output before `br close`   |
-| Working on blocked beads (dependencies not met)                     | Wastes time and causes out-of-order delivery                  | Use `br ready` and confirm dependencies in `br show <id>`        |
-| Modifying bead state without user confirmation                      | Violates workflow expectations and can surprise collaborators | Ask before changing bead status, especially close/sync actions   |
-| Using `br sync` without `--flush-only` (can cause conflicts)        | May write unexpected state and increase sync conflict risk    | Always use `br sync --flush-only` then commit `.beads/` manually |
-
-## Verification
-
-- **Before closing:** run verification commands, paste output as evidence
-- **After close:** `br show <id>` confirms `status=closed`
-- **After sync:** `git status` shows clean working tree
-
-## File Path Claiming (Summary)
-
-Claim files before editing in multi-agent work using `br reserve <id> --files "..."`.
-
-See: `references/FILE_CLAIMING.md` for the full protocol and examples.
-
-## Best Practices (Summary)
-
-- One task per session, then restart
-- File issues for work >2 minutes
-- Weekly `br doctor`, periodic `br cleanup --days 7`
-
-See: `references/BEST_PRACTICES.md` for maintenance and database health guidance.
-
-## Quick Reference
-
-```
-SESSION START:
-  br ready → br update <id> --status in_progress → br show <id>
-
-DURING WORK:
-  br create for discovered work (>2min)
-  br show <id> for context
-
-SESSION END:
-  br close <id> --reason "..." → br sync --flush-only → git add .beads/ && git commit → RESTART SESSION
-
-MAINTENANCE:
-  br doctor - weekly health check
-  br cleanup --days 7 - remove old issues
-```
-
-## References
-
-- `references/BOUNDARIES.md`
-- `references/RESUMABILITY.md`
-- `references/DEPENDENCIES.md`
-- `references/WORKFLOWS.md`
-- `references/HIERARCHY.md`
-- `references/SESSION_PROTOCOL.md`
-- `references/TASK_CREATION.md`
-- `references/GIT_SYNC.md`
-- `references/TROUBLESHOOTING.md`
-- `references/EXAMPLES.md`
-- `references/MULTI_AGENT.md`
-- `references/FILE_CLAIMING.md`
-- `references/BEST_PRACTICES.md`
-
-## See Also
-
-- `verification-before-completion`
-- `swarm-coordination`

package/dist/template/.opencode/skill/beads/references/BEST_PRACTICES.md

@@ -1,27 +0,0 @@
-# Best Practices
-
-## Daily/Weekly Maintenance
-
-| Task         | Frequency      | Command               | Why                                            |
-| ------------ | -------------- | --------------------- | ---------------------------------------------- |
-| Health check | Weekly         | `br doctor`           | Repairs database issues, detects orphaned work |
-| Cleanup      | Every few days | `br cleanup --days 7` | Keep DB under 200-500 issues for performance   |
-
-## Key Principles
-
-1. **Plan outside Beads first** - Use planning tools, then import tasks to beads
-2. **One task per session, then restart** - Fresh context prevents confusion
-3. **File lots of issues** - Any work >2 minutes should be tracked
-4. **"Land the plane" = PUSH** - `br sync --flush-only` + git commit/push, not "ready when you are"
-5. **Include issue ID in commits** - `git commit -m "Fix bug (br-abc)"`
-
-## Database Health
-
-```bash
-# Check database size
-br list --status all --json | wc -l
-
-# Target: under 200-500 issues
-# If over, run cleanup more aggressively:
-br cleanup --days 3
-```

package/dist/template/.opencode/skill/beads/references/BOUNDARIES.md

@@ -1,219 +0,0 @@
-# Boundaries: When to Use br vs TodoWrite
-
-Decision criteria for choosing between beads tools and TodoWrite.
-
-## The Core Question
-
-**"Could I resume this work after 2 weeks away?"**
-
-- If beads would help you resume → **use br**
-- If markdown skim would suffice → **TodoWrite is fine**
-
-## Decision Matrix
-
-### Use br for:
-
-**Multi-Session Work**
-
-- Strategic document development
-- Feature implementation across sessions
-- Bug investigation over time
-- Architecture design iterations
-
-**Complex Dependencies**
-
-- OAuth integration requiring DB, endpoints, frontend
-- Research with parallel investigation threads
-- Refactoring with dependencies between areas
-- Migration requiring sequential steps
-
-**Knowledge Work**
-
-- Architecture decisions requiring research
-- API design with multiple options
-- Performance optimization experiments
-- Documentation requiring system understanding
-
-**Side Quests**
-
-- Found better pattern during feature work
-- Noticed architectural issue while debugging
-- Identified improvement during code review
-- Edge case requiring research during tests
-
-**Multi-Agent Coordination**
-
-- Multiple agents editing same codebase
-- File locking needed
-- Cross-team communication
-
-### Use TodoWrite for:
-
-**Single-Session Tasks**
-
-- Implementing single function from spec
-- Fixing bug with known root cause
-- Adding unit tests for existing code
-- Updating documentation
-
-**Linear Execution**
-
-- Database migration with clear sequence
-- Deployment checklist
-- Code style cleanup
-- Dependency updates
-
-**Immediate Context**
-
-- User provides complete spec
-- Bug report with reproduction and fix
-- Refactoring with clear before/after
-- Config changes from preferences
-
-**Simple Tracking**
-
-- Breaking down implementation
-- Showing validation progress
-- Demonstrating systematic approach
-
-## Detailed Comparison
-
-| Aspect           | br CLI                            | TodoWrite              |
-| ---------------- | --------------------------------- | ---------------------- |
-| **Persistence**  | Git-backed, survives compaction   | Session-only           |
-| **Dependencies** | Graph-based, auto ready detection | Manual                 |
-| **File Locking** | Yes, prevents conflicts           | No                     |
-| **Multi-Agent**  | Yes, coordination tools           | No                     |
-| **Visibility**   | Background structure              | Visible in chat        |
-| **Best for**     | Complex, multi-session            | Simple, single-session |
-
-## Integration Patterns
-
-### Pattern 1: br as Strategic, TodoWrite as Tactical
-
-```
-br task: "Implement user authentication" (epic)
-  ├─ Child: "Create login endpoint"
-  ├─ Child: "Add JWT validation"  ← Currently working
-  └─ Child: "Implement logout"
-
-TodoWrite (for JWT validation):
-- [ ] Install JWT library
-- [ ] Create validation middleware
-- [ ] Add tests for expiry
-- [ ] Update docs
-```
-
-### Pattern 2: TodoWrite as Working Copy
-
-```
-Session start:
-- br ready gets "Add JWT validation"
-- br update <id> --status in_progress
-- Extract acceptance criteria into TodoWrite
-- Work through TodoWrite items
-- Update br notes as you learn
-- br close <id> when TodoWrite complete
-```
-
-### Pattern 3: Transition Mid-Session
-
-**From TodoWrite to br:**
-
-Trigger signals:
-
-- Discovering blockers or dependencies
-- Work won't complete this session
-- Finding side quests
-- Need to pause and resume later
-
-**How to transition:**
-
-```
-1. br create with current TodoWrite content
-2. Note: "Discovered multi-session work"
-3. Add dependencies as discovered
-4. Keep TodoWrite for current session
-5. Update br notes before session ends
-```
-
-## Common Mistakes
-
-### Mistake 1: TodoWrite for Multi-Session Work
-
-**What happens:**
-
-- Next session, forget what was done
-- Scroll history to reconstruct
-- Lose design decisions
-- Duplicate work
-
-**Solution:** Use br instead.
-
-### Mistake 2: br for Simple Linear Tasks
-
-**What happens:**
-
-- Overhead not justified
-- User can't see progress
-- Extra tool use for no benefit
-
-**Solution:** Use TodoWrite.
-
-### Mistake 3: Not Transitioning When Complexity Emerges
-
-**What happens:**
-
-- Start with TodoWrite
-- Discover blockers mid-way
-- Keep using TodoWrite despite poor fit
-- Lose context when session ends
-
-**Solution:** Transition to br when complexity appears.
-
-### Mistake 4: Creating Too Many br Issues
-
-**What happens:**
-
-- Every tiny task gets an issue
-- Database cluttered
-- Hard to find meaningful work
-
-**Solution:** Use 2-week test. Would br help after 2 weeks? If no, skip.
-
-## The Transition Point
-
-**Transition signals:**
-
-- "This is taking longer than expected"
-- "I've discovered a blocker"
-- "This needs more research"
-- "I should investigate X first"
-- "User might not continue today"
-- "Found three related issues"
-
-When you notice these: Create br issue, preserve context.
-
-## Summary Heuristics
-
-**Time horizon:**
-
-- Same session → TodoWrite
-- Multiple sessions → br
-
-**Dependency structure:**
-
-- Linear steps → TodoWrite
-- Blockers/prerequisites → br
-
-**Scope clarity:**
-
-- Well-defined → TodoWrite
-- Exploratory → br
-
-**Multi-agent:**
-
-- Single agent → Either
-- Multiple agents → br
-
-**When in doubt:** Use the 2-week test.

package/dist/template/.opencode/skill/beads/references/DEPENDENCIES.md

@@ -1,124 +0,0 @@
-# Dependency Types Guide
-
-Beads supports task dependencies for ordering work.
-
-## Overview
-
-Dependencies affect what work is "ready" - tasks with unmet dependencies won't appear in `br ready` results.
-
-## Creating Dependencies
-
-```bash
-br create --title "Implement API endpoint" --blocked-by setup-db
-# This task depends on setup-db completing first
-```
-
-## Dependency Patterns
-
-### Sequential Work
-
-```
-setup-db → implement-api → add-tests → deploy
-```
-
-Each task depends on the previous. `br ready` shows only the current step.
-
-### Parallel Then Merge
-
-```
-research-a ─┐
-research-b ─┼→ decision
-research-c ─┘
-```
-
-Multiple parallel tasks, then one that needs all of them.
-
-### Foundation First
-
-```
-setup ─┬→ feature-a
-       ├→ feature-b
-       └→ feature-c
-```
-
-One foundational task blocks multiple features.
-
-## Epic with Children
-
-```bash
-# Create epic
-br create --title "OAuth Integration" --type epic --priority 1
-# Returns: oauth-abc
-
-# Create children with parent
-br create --title "Setup credentials" --parent oauth-abc
-br create --title "Implement flow" --parent oauth-abc --blocked-by credentials
-br create --title "Add UI" --parent oauth-abc --blocked-by flow
-```
-
-## Automatic Unblocking
-
-When you close a task that's blocking others:
-
-```
-1. br close setup-db --reason "Schema created"
-2. Beads automatically updates: implement-api is now ready
-3. br ready returns implement-api
-4. No manual unblocking needed
-```
-
-## Common Mistakes
-
-### Using Dependencies for Preferences
-
-**Wrong:**
-
-```
-docs depends on feature  // "prefer to update docs after"
-```
-
-**Problem:** Documentation doesn't actually need feature complete.
-
-**Right:** Only use dependencies for actual blockers.
-
-### Wrong Direction
-
-**Wrong:**
-
-```bash
-br create --title "API" --blocked-by tests  # API depends on tests?
-```
-
-**Problem:** Usually tests depend on API, not the other way.
-
-**Right:** Think "X needs Y complete first" → X depends on Y.
-
-### Over-Using Dependencies
-
-**Problem:** Everything depends on everything. No parallel work possible.
-
-**Right:** Only add dependencies for actual technical blockers.
-
-## Decision Guide
-
-**Add dependency when:**
-
-- Task literally cannot start without other task complete
-- Code won't compile/run without prerequisite
-- Data/schema must exist first
-
-**Skip dependency when:**
-
-- Just a preference for order
-- Both can proceed independently
-- Just want to note relationship
-
-## Viewing Dependencies
-
-```bash
-br show <id>
-# Shows what blocks this task and what this task blocks
-
-br list --status open
-# Shows all open tasks, check dependencies in details
-```