opencodekit 0.18.1 → 0.18.2

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

@@ -6,13 +6,21 @@ description: >
   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
 
-Graph-based task tracker with file locking for multi-agent coordination. Persists across sessions.
+## When to Use
 
-**Note:** `br` (beads_rust) is non-invasive and never executes git commands. After `br sync --flush-only`, you must manually run `git add .beads/ && git commit`.
+- 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
 
@@ -44,302 +52,54 @@ br close <id> --reason "Completed"
 br sync --flush-only  # Export to JSONL (then git add/commit manually)
 ```
 
-## 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
-```
-
-### Dependency Types
-
-Beads supports four dependency types:
-
-| Type              | Meaning                   | Use Case            |
-| ----------------- | ------------------------- | ------------------- |
-| `blocks`          | Task A blocks Task B      | Sequential work     |
-| `related`         | Tasks are connected       | Cross-references    |
-| `parent-child`    | Hierarchy (via `parent:`) | Epic → Task         |
-| `discovered-from` | Found during work         | New work discovered |
-
-### 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
-```
-
-## Session Start Protocol
-
-**Every session, follow these steps:**
-
-### 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
+## Hierarchy & Dependencies (Summary)
 
-```bash
-br update <id> --status in_progress
-```
+- 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
 
-### Step 3: Get Full Context
+See: `references/HIERARCHY.md` and `references/DEPENDENCIES.md` for full details.
 
-```bash
-br show <id>
-```
+## Session Protocol (Summary)
 
-Shows full description, dependencies, notes, history.
+**Start:** `br ready` → `br update <id> --status in_progress` → `br show <id>`
 
-### Step 4: Do the Work
+**End:** `br close <id> --reason "..."` → `br sync --flush-only` → commit `.beads/` → restart session
 
-Implement the task, adding notes as you learn.
+See: `references/SESSION_PROTOCOL.md` and `references/WORKFLOWS.md` for detailed steps and checklists.
 
-### Step 5: Complete and Sync
+## Task Creation (Summary)
 
-```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.
-
-## 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
+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
-# 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
-```
-
-## Git Sync
-
-### Manual Sync (Non-Invasive)
-
-**Important:** `br` never executes git commands. You must manually commit changes.
+See: `references/TASK_CREATION.md` for full examples and patterns.
 
-```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
-```
+## Git Sync (Summary)
 
-Removes closed issues older than N days. Run weekly.
+`br` never runs git commands. Always `br sync --flush-only` and commit `.beads/` manually.
 
-## Error Handling
+See: `references/GIT_SYNC.md` for detailed flow and cleanup guidance.
 
-### Common Issues
+## Troubleshooting (Summary)
 
-**No ready tasks**
+- No ready tasks → `br list --status open`, check blockers via `br show <id>`
+- Sync failures → `br doctor`
 
-- 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
+See: `references/TROUBLESHOOTING.md` for common issues and fixes.
 
 ## 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
-```
-
-## Multi-Agent Coordination (Swarm Mode)
-
-For parallel execution with multiple subagents, use the **beads-bridge** skill:
+See: `references/EXAMPLES.md` for complete usage examples.
 
-```typescript
-skill({ name: "beads-bridge" });
-```
-
-**beads-bridge** 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 beads-bridge:**
-
-| Scenario                       | Use                              |
-| ------------------------------ | -------------------------------- |
-| Single agent, linear work      | `beads` skill only               |
-| Multiple agents in parallel    | `beads-bridge` + `beads`         |
-| Need subagents to see tasks    | `beads-bridge` (swarm sync push) |
-| Track worker progress visually | `beads-bridge` (swarm monitor)   |
+## Multi-Agent Coordination (Summary)
 
-**Example swarm workflow:**
+For parallel execution with multiple subagents, use the **beads-bridge** skill.
 
-```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" });
-```
+See: `references/MULTI_AGENT.md` for swarm tool usage and examples.
 
 ## Rules
 
@@ -350,128 +110,19 @@ swarm({ operation: "sync", action: "pull" });
 5. **Write notes for future agents** - Assume zero conversation context
 6. **Claim file paths before editing** - Use reserve to declare ownership (multi-agent only)
 
-## File Path Claiming (Multi-Agent Safety)
+## File Path Claiming (Summary)
 
-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.
+Claim files before editing in multi-agent work using `br reserve <id> --files "..."`.
 
-### When to Use
+See: `references/FILE_CLAIMING.md` for the full protocol and examples.
 
-- **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
+## Best Practices (Summary)
 
-### The Claim/Edit/Release Cycle
+- One task per session, then restart
+- File issues for work >2 minutes
+- Weekly `br doctor`, periodic `br cleanup --days 7`
 
-```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
-```
-
-### 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
-```
-
-## 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
-```
+See: `references/BEST_PRACTICES.md` for maintenance and database health guidance.
 
 ## Quick Reference
 
@@ -490,3 +141,19 @@ 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`

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

@@ -0,0 +1,27 @@
+# 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/EXAMPLES.md

@@ -0,0 +1,45 @@
+# 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

@@ -0,0 +1,101 @@
+# 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
+```