opencodekit 0.22.0 → 0.23.1

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

@@ -1,45 +0,0 @@
-# Examples
-
-## Example 1: Standard Session
-
-```bash
-# 1. Find and claim work
-br ready
-br update auth-123 --status in_progress
-
-# 2. Get context
-br show auth-123
-
-# 3. Do the work...
-# [implementation]
-
-# 4. Complete and sync
-br close auth-123 --reason "Login form with validation, hooks for auth state"
-br sync --flush-only
-git add .beads/
-git commit -m "close auth-123"
-# RESTART SESSION
-```
-
-## Example 2: Discovered Work
-
-```bash
-# Working on task, found more work
-br create --title "Fix edge case in validation" --type bug --priority 1 \
-  --description "Empty strings bypass email check - discovered while implementing login"
-# Continue current task, new task tracked for later
-```
-
-## Example 3: Creating Dependencies
-
-```bash
-# Create tasks with dependencies
-br create --title "Setup database" --type task --priority 1
-# Returns: setup-db
-
-br create --title "Implement API" --type task --priority 2 --blocked-by setup-db
-# Returns: impl-api (blocked until setup-db closes)
-
-br create --title "Add tests" --type task --priority 2 --blocked-by impl-api
-# Returns: add-tests
-```

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

@@ -1,101 +0,0 @@
-# File Path Claiming (Multi-Agent Safety)
-
-At multi-agent scale, agents editing the same files cause merge conflicts. File path claiming prevents this by making ownership explicit before any edit happens.
-
-## When to Use
-
-- **Single agent**: Optional — no conflicts possible
-- **2-10 agents**: Recommended for files touched by multiple tasks
-- **10+ agents**: Required — every file must be claimed before editing
-
-## The Claim/Edit/Release Cycle
-
-```bash
-# 1. CLAIM: Declare intent to edit before touching the file
-br reserve <bead-id> --files "src/auth/service.ts,src/auth/types.ts"
-# → Marks files as owned by this bead
-# → Other agents see the reservation and must wait
-
-# 2. EDIT: Make your changes
-# (edit files as normal)
-
-# 3. VERIFY: Run gates before releasing
-npm run typecheck && npm run lint
-
-# 4. CLOSE: Release ownership when done
-br close <bead-id> --reason "Auth service implemented. Gates passed."
-# → Ownership released automatically on close
-```
-
-## File Claiming Checklist
-
-- [ ] Check for conflicts: `br list --status in_progress --json | jq '.[].reserved_files'`
-- [ ] Reserve files before editing: `br reserve <id> --files "..."`
-- [ ] Run gates before closing: `npm run typecheck && npm run lint`
-- [ ] Close bead to release ownership
-
-## Checking for Conflicts Before Claiming
-
-Before claiming, check if another bead already owns the file:
-
-```bash
-# See all reserved files across active beads
-br list --status in_progress --json | jq '.[].reserved_files'
-
-# If conflict detected:
-# → Wait for the other bead to close
-# → Or coordinate with the agent owning that bead
-```
-
-## Claiming in Delegation Packets
-
-Workers MUST declare file claims in their delegation packet:
-
-```markdown
-# Delegation Packet
-
-- TASK: task-1 - Implement auth service
-- FILES TO CLAIM BEFORE EDITING:
-  - src/auth/service.ts
-  - src/auth/types.ts
-  - src/auth/middleware.ts
-- MUST NOT EDIT (owned by other tasks):
-  - src/db/schema.ts (owned by task-0)
-  - src/config.ts (owned by task-2)
-```
-
-## Conflict Resolution Protocol
-
-When two agents want the same file:
-
-| Scenario                             | Resolution                                      |
-| ------------------------------------ | ----------------------------------------------- |
-| File not claimed                     | Claim it and proceed                            |
-| File claimed by completed bead       | Safe to claim (no active owner)                 |
-| File claimed by in_progress bead     | Wait for bead to close, then claim              |
-| Urgent: same file, different workers | Escalate to lead agent to split the file change |
-
-## Anti-Pattern: Claiming After Editing
-
-```bash
-# WRONG — edit first, claim after → conflict already happened
-edit src/auth/service.ts
-br reserve bead-1 --files "src/auth/service.ts"
-
-# RIGHT — claim first, then edit
-br reserve bead-1 --files "src/auth/service.ts"
-edit src/auth/service.ts
-```
-
-## Quick Reference: File Claiming
-
-```
-BEFORE EDITING (multi-agent):
-  br reserve <id> --files "src/file.ts"
-
-CHECK OWNERSHIP:
-  br list --status in_progress --json | jq '.[].reserved_files'
-
-RELEASE:
-  br close <id> --reason "..."  ← auto-releases files
-```

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

@@ -1,25 +0,0 @@
-# Git Sync
-
-## Manual Sync (Non-Invasive)
-
-**Important:** `br` never executes git commands. You must manually commit changes.
-
-```bash
-# Export changes to JSONL
-br sync --flush-only
-
-# Then manually commit
-git add .beads/
-git commit -m "sync beads"
-git push
-```
-
-**Use when**: End of session, before handoff, after major progress.
-
-## Cleanup Old Issues
-
-```bash
-br cleanup --days 7
-```
-
-Removes closed issues older than N days. Run weekly.

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

@@ -1,71 +0,0 @@
-# Hierarchical Structure: Epic → Task → Subtask
-
-Beads supports up to 3 levels of hierarchy using hierarchical IDs:
-
-```
-br-a3f8        (Epic - parent feature)
-├── br-a3f8.1  (Task - first child)
-├── br-a3f8.2  (Task - second child)
-│   ├── br-a3f8.2.1  (Subtask - child of .2)
-│   └── br-a3f8.2.2  (Subtask - child of .2)
-└── br-a3f8.3  (Task - third child)
-```
-
-## When to Decompose
-
-| Scenario                     | Structure                            |
-| ---------------------------- | ------------------------------------ |
-| Bug fix, config change       | Single bead                          |
-| Small feature (1-2 files)    | Single bead                          |
-| Feature crossing FE/BE       | Epic + tasks by domain               |
-| New system/service           | Epic + tasks by component            |
-| Multi-day work               | Epic + tasks for parallelization     |
-| Work needing multiple agents | Epic + tasks (agents claim children) |
-
-## Creating Hierarchical Beads
-
-```bash
-# Step 1: Create Epic (parent)
-br create --title "User Authentication System" --type epic --priority 1 \
-  --description "Complete auth with OAuth, sessions, and protected routes"
-# Returns: br-a3f8
-
-# Step 2: Create child tasks with parent
-br create --title "Database schema for auth" --type task --priority 2 \
-  --parent br-a3f8 --description "Create user and session tables"
-# Returns: br-a3f8.1  ← Hierarchical ID!
-
-# Step 3: Create dependent tasks
-br create --title "OAuth integration" --type task --priority 2 \
-  --parent br-a3f8 --blocked-by br-a3f8.1
-# Returns: br-a3f8.2
-```
-
-## Parallel Execution with Dependencies
-
-```
-br-a3f8.1 [Database] ──┬──> br-a3f8.2 [Backend] ──┐
-     (READY)           │                          │
-                       │                          ▼
-                       └──> br-a3f8.3 [Frontend]  br-a3f8.5 [Testing]
-                       │         │                     ▲
-                       └──> br-a3f8.4 [Docs] ──────────┘
-
-Parallel tracks:
-• Agent 1 (backend): .1 → .2
-• Agent 2 (frontend): wait for .1, then .3
-• Agent 3 (qa): wait for .2 and .3, then .5
-```
-
-**Key insight**: After br-a3f8.1 completes, .2, .3, and .4 all become READY simultaneously. Multiple agents can claim them in parallel.
-
-## Querying Hierarchy
-
-```bash
-# See all open issues
-br list --status open
-
-# See ready work (unblocked tasks)
-br ready
-# Returns tasks where all dependencies are closed
-```

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

@@ -1,40 +0,0 @@
-# Multi-Agent Coordination (Swarm Mode)
-
-For parallel execution with multiple subagents, use the **swarm-coordination** skill:
-
-```typescript
-skill({ name: "swarm-coordination" });
-```
-
-**swarm-coordination** provides (via unified `swarm` tool):
-
-- `swarm({ operation: "sync" })` - Sync Beads tasks to OpenCode todos for subagent visibility
-- `swarm({ operation: "monitor" })` - Real-time progress tracking and visualization
-- `swarm({ operation: "plan" })` - Task classification and dependency analysis
-- `swarm({ operation: "delegate" })` - Create delegation packets for workers
-
-**When to use beads vs swarm-coordination:**
-
-| Scenario                       | Use                                    |
-| ------------------------------ | -------------------------------------- |
-| Single agent, linear work      | `beads` skill only                     |
-| Multiple agents in parallel    | `swarm-coordination` + `beads`         |
-| Need subagents to see tasks    | `swarm-coordination` (swarm sync push) |
-| Track worker progress visually | `swarm-coordination` (swarm monitor)   |
-
-**Example swarm workflow:**
-
-```typescript
-// 1. Push beads to OpenCode todos (subagents can see via todoread)
-swarm({ operation: "sync", action: "push" });
-
-// 2. Spawn workers in parallel using Task tool
-Task({ subagent_type: "general", description: "Worker 1", prompt: "..." });
-Task({ subagent_type: "general", description: "Worker 2", prompt: "..." });
-
-// 3. Monitor progress
-swarm({ operation: "monitor", action: "render_block", team_name: "my-swarm" });
-
-// 4. Pull completed work back to beads
-swarm({ operation: "sync", action: "pull" });
-```

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

@@ -1,177 +0,0 @@
-# Making Tasks Resumable Across Sessions
-
-## When Resumability Matters
-
-**Use enhanced notes for:**
-
-- Multi-session features with API integration
-- Complex algorithms requiring code examples
-- Features with specific output format requirements
-- Work with undocumented APIs
-
-**Skip for:**
-
-- Simple bug fixes with clear scope
-- Well-understood patterns (CRUD, etc.)
-- Single-session tasks
-- Work with obvious criteria
-
-**The test:** Would a fresh agent (or you after 2 weeks) struggle to resume from the notes alone? If yes, add detail.
-
-## Anatomy of Resumable Notes
-
-### Minimal (Always Include)
-
-```
-COMPLETED: What's done
-IN PROGRESS: Current state
-NEXT: Concrete next step
-```
-
-### Enhanced (Complex Work)
-
-````
-COMPLETED: Specific deliverables
-IN PROGRESS: Current state + what's working
-NEXT: Concrete next step (not "continue")
-BLOCKERS: What's preventing progress
-KEY DECISIONS: Important context with rationale
-
-WORKING CODE:
-```python
-# Tested code that works
-result = api.query(fields='importFormats')
-# Returns: {'text/markdown': ['application/vnd.google-apps.document']}
-````
-
-DESIRED OUTPUT:
-
-```markdown
-# Example of what output should look like
-
-Actual structure, not just "return markdown"
-```
-
-````
-
-## Example: Before vs After
-
-### Not Resumable
-
-```
-Title: Add dynamic capabilities
-Notes: Working on it. Made some progress.
-````
-
-**Problem:** Future agent doesn't know:
-
-- Which API endpoints to call
-- What responses look like
-- What format to return
-
-### Resumable
-
-````
-Title: Add dynamic capabilities resources
-
-Notes:
-COMPLETED: API connection verified. Query working.
-IN PROGRESS: Formatting response as markdown.
-NEXT: Add caching for API responses.
-
-WORKING CODE:
-```python
-service = build('drive', 'v3', credentials=creds)
-about = service.about().get(fields='importFormats').execute()
-# Returns dict with 49 entries
-````
-
-DESIRED OUTPUT:
-
-```markdown
-# Drive Import Formats
-
-- **text/markdown** → Google Docs
-- text/plain → Google Docs
-```
-
-KEY DECISION: Using live API query because text/markdown support (July 2024) not in static docs.
-
-```
-
-**Result:** Fresh agent can:
-1. See working API code
-2. Understand response structure
-3. Know desired output format
-4. Implement with context
-
-## When to Add Detail
-
-**During task creation:**
-- Already have working code? Include it.
-- Clear output format? Show example.
-
-**During work:**
-- Got API working? Add to notes.
-- Discovered important context? Document it.
-- Made key decision? Explain rationale.
-
-**Session end:**
-- If resuming will be hard, add implementation guide.
-- If obvious, skip it.
-
-## Anti-Patterns
-
-### Over-Documenting Simple Work
-
-```
-
-Title: Fix typo in README
-Notes: IMPLEMENTATION GUIDE
-WORKING CODE: Open README.md, change "teh" to "the"...
-
-```
-
-**Problem:** Wastes tokens on obvious work.
-
-### Vague Progress
-
-```
-
-Notes: Made progress. Will continue later.
-
-```
-
-**Problem:** No context for resumption.
-
-### Raw Data Dumps
-
-```
-
-API RESPONSE:
-{giant unformatted JSON blob spanning 100 lines}
-
-```
-
-**Problem:** Hard to read. Extract relevant parts.
-
-### Right Balance
-
-```
-
-API returns dict with 49 entries. Examples:
-
-- 'text/markdown': ['application/vnd.google-apps.document']
-- 'text/plain': ['application/vnd.google-apps.document']
-
-```
-
-## The Principle
-
-Help your future self (or next agent) resume without rediscovering everything.
-
-Write notes as if explaining to someone with:
-- Zero conversation context
-- No memory of previous sessions
-- Only the task description and notes
-```

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

@@ -1,61 +0,0 @@
-# Session Start Protocol
-
-**Every session, follow these steps:**
-
-## Session Start Checklist
-
-- [ ] Run `br ready` to find unblocked work
-- [ ] If none, run `br list --status open` to see all open tasks
-- [ ] Claim the task: `br update <id> --status in_progress`
-- [ ] Load context: `br show <id>`
-
-## Step 1: Find Ready Work
-
-```bash
-br ready
-```
-
-Returns highest priority task with no blockers.
-
-If no tasks returned, check all open work:
-
-```bash
-br list --status open
-```
-
-## Step 2: Claim Task
-
-```bash
-br update <id> --status in_progress
-```
-
-## Step 3: Get Full Context
-
-```bash
-br show <id>
-```
-
-Shows full description, dependencies, notes, history.
-
-## Step 4: Do the Work
-
-Implement the task, adding notes as you learn.
-
-## Step 5: Complete and Sync
-
-```bash
-br close <id> --reason "Implemented auth with JWT tokens"
-br sync --flush-only
-git add .beads/
-git commit -m "sync beads"
-# RESTART SESSION - fresh context
-```
-
-Always restart session after closing a task. One task per session.
-
-## Session End Checklist
-
-- [ ] Close the bead with a clear reason: `br close <id> --reason "..."`
-- [ ] Sync Beads to JSONL: `br sync --flush-only`
-- [ ] Commit `.beads/` changes manually
-- [ ] Restart session (fresh context)

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

@@ -1,38 +0,0 @@
-# Task Creation
-
-## When to Create Tasks
-
-Create tasks when:
-
-- User mentions tracking work across sessions
-- User says "we should fix/build/add X"
-- Work has dependencies or blockers
-- Discovered work while implementing (>2 min effort)
-
-## Basic Task Creation
-
-```bash
-br create --title "Fix authentication bug" --priority 0 --type bug
-# Priority: 0=critical, 1=high, 2=normal, 3=low, 4=backlog
-# Types: task, bug, feature, epic, chore
-```
-
-## With Description
-
-```bash
-br create --title "Implement OAuth" --type feature --priority 1 \
-  --description "Add OAuth2 support for Google, GitHub. Use passport.js."
-```
-
-## Epic with Children
-
-```bash
-# Create parent epic
-br create --title "Epic: OAuth Implementation" --priority 0 --type epic
-# Returns: oauth-abc
-
-# Create child tasks with parent
-br create --title "Research OAuth providers" --priority 1 --parent oauth-abc
-br create --title "Implement auth endpoints" --priority 1 --parent oauth-abc
-br create --title "Add frontend login UI" --priority 2 --parent oauth-abc
-```

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

@@ -1,38 +0,0 @@
-# Error Handling
-
-## Common Issues
-
-**No ready tasks**
-
-- Run `br list --status open` to see all tasks
-- Some may be blocked - check dependencies with `br show <id>`
-
-**Sync failures**
-
-- Run `br doctor` to repair database
-- Check git remote access
-
-## Database Lock / WAL Conflicts
-
-**Symptoms:**
-
-- `SQLITE_BUSY` or `SQLITE_LOCKED` errors when reading beads
-- Stale `.beads/beads.db-wal` or `.beads/beads.db-journal` files after agent crash
-
-**Cause:**
-Agent interruption during bead operations can leave WAL/journal files in an inconsistent state.
-
-**Fix:**
-
-1. Ensure no agents are actively writing to beads.db
-2. Remove stale lock files:
-   ```bash
-   rm -f .beads/beads.db-wal .beads/beads.db-journal
-   ```
-3. Run `br sync --flush-only` to rebuild from JSONL source of truth
-4. Verify: `br ready` should work without errors
-
-**Prevention:**
-
-- The memory plugin now retries bead.db reads automatically (3 attempts, 500ms delay)
-- If persistent, check for zombie agent processes: `ps aux | grep opencode`