opencodekit 0.16.4 → 0.16.6

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

@@ -1,10 +1,10 @@
 ---
 name: beads
 description: >
-  Multi-agent task coordination using Beads Village plugin tools. Use when work spans multiple
+  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: "1.1.0"
+version: "2.0.0"
 license: MIT
 ---
 
@@ -12,35 +12,49 @@ license: MIT
 
 Graph-based task tracker with file locking for multi-agent coordination. Persists across sessions.
 
+**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`.
+
 ## Overview
 
-**Beads plugin tools** (`bd_*`) replace MCP beads-village with native tools for lower token overhead.
+**br (beads_rust) CLI** replaces the old `bd` (beads) CLI with a faster Rust implementation.
 
 **Key Distinction**:
 
-- **bd\_\* tools**: Multi-session work, dependencies, file locking, agent coordination
+- **br CLI**: Multi-session work, dependencies, file locking, agent coordination
 - **TodoWrite**: Single-session tasks, linear execution, conversation-scoped
 
-**When to Use bd\_\* vs TodoWrite**:
+**When to Use br vs TodoWrite**:
 
-- "Will I need this context in 2 weeks?" → **YES** = bd\_\*
-- "Does this have blockers/dependencies?" → **YES** = bd\_\*
-- "Multiple agents editing same codebase?" → **YES** = bd\_\*
+- "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)
+```
+
 ## Hierarchical Structure: Epic → Task → Subtask
 
 **Beads supports up to 3 levels of hierarchy using hierarchical IDs:**
 
 ```
-bd-a3f8        (Epic - parent feature)
-├── bd-a3f8.1  (Task - first child)
-├── bd-a3f8.2  (Task - second child)
-│   ├── bd-a3f8.2.1  (Subtask - child of .2)
-│   └── bd-a3f8.2.2  (Subtask - child of .2)
-└── bd-a3f8.3  (Task - third child)
+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
@@ -56,38 +70,21 @@ bd-a3f8        (Epic - parent feature)
 
 ### Creating Hierarchical Beads
 
-```typescript
-// Step 1: Create Epic (parent)
-const epic = bd_add({
-  title: "User Authentication System",
-  type: "epic",
-  pri: 1,
-  desc: "Complete auth with OAuth, sessions, and protected routes",
-  tags: ["epic", "auth"],
-});
-// Returns: { id: "bd-a3f8" }
-
-// Step 2: Create child tasks with `parent` parameter
-const task1 = bd_add({
-  title: "Database schema for auth",
-  type: "task",
-  pri: 2,
-  parent: "bd-a3f8", // Links to epic
-  desc: "Create user and session tables",
-  tags: ["backend", "database"],
-});
-// Returns: { id: "bd-a3f8.1" }  ← Hierarchical ID!
-
-// Step 3: Create dependent tasks with `deps` parameter
-const task2 = bd_add({
-  title: "OAuth integration",
-  type: "task",
-  pri: 2,
-  parent: "bd-a3f8",
-  deps: ["bd-a3f8.1"], // Blocked until .1 completes
-  tags: ["backend"],
-});
-// Returns: { id: "bd-a3f8.2" }
+```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
@@ -104,12 +101,12 @@ Beads supports four dependency types:
 ### Parallel Execution with Dependencies
 
 ```
-bd-a3f8.1 [Database] ──┬──> bd-a3f8.2 [Backend] ──┐
+br-a3f8.1 [Database] ──┬──> br-a3f8.2 [Backend] ──┐
      (READY)           │                          │
                        │                          ▼
-                       └──> bd-a3f8.3 [Frontend]  bd-a3f8.5 [Testing]
+                       └──> br-a3f8.3 [Frontend]  br-a3f8.5 [Testing]
                        │         │                     ▲
-                       └──> bd-a3f8.4 [Docs] ──────────┘
+                       └──> br-a3f8.4 [Docs] ──────────┘
 
 Parallel tracks:
 • Agent 1 (backend): .1 → .2
@@ -117,97 +114,66 @@ Parallel tracks:
 • Agent 3 (qa): wait for .2 and .3, then .5
 ```
 
-**Key insight**: After bd-a3f8.1 completes, .2, .3, and .4 all become READY simultaneously. Multiple agents can claim them in parallel.
+**Key insight**: After br-a3f8.1 completes, .2, .3, and .4 all become READY simultaneously. Multiple agents can claim them in parallel.
 
 ### Querying Hierarchy
 
-````typescript
-// See all children of an epic
-bd_ls({ status: "all", limit: 20 });
-// Filter by parent prefix in results
+```bash
+# See all open issues
+br list --status open
 
-// See ready work (unblocked tasks)
-bd_ready();
-// Returns tasks where all dependencies are closed
+# See ready work (unblocked tasks)
+br ready
+# Returns tasks where all dependencies are closed
 ```
 
 ## Session Start Protocol
 
 **Every session, follow these steps:**
 
-### Step 1: Initialize
-
-```typescript
-bd_init({ team: "project", role: "fe" });
-````
-
-Joins workspace, enables role-based task filtering. Roles: fe, be, mobile, devops, qa.
-
-### Step 2: Check Health (Weekly)
-
-```typescript
-bd_doctor();
-```
-
-Repairs database issues. Run at start of week or after sync problems.
-
-### Step 3: Find Ready Work
+### Step 1: Find Ready Work
 
-```typescript
-bd_claim();
+```bash
+br ready
 ```
 
-Returns highest priority task with no blockers, marks it in_progress.
+Returns highest priority task with no blockers.
 
 If no tasks returned, check all open work:
 
-```typescript
-bd_ls({ status: "open" });
-```
-
-### Step 4: Get Full Context
-
-```typescript
-bd_show({ id: "task-abc" });
+```bash
+br list --status open
 ```
 
-Shows full description, dependencies, notes, history.
-
-### Step 5: Reserve Files Before Editing
+### Step 2: Claim Task
 
-```typescript
-bd_reserve({ paths: ["src/auth.ts", "src/types.ts"] });
+```bash
+br update <id> --status in_progress
 ```
 
-**Critical**: Always reserve before editing. Prevents conflicts with other agents.
-
-Check existing locks first:
+### Step 3: Get Full Context
 
-```typescript
-bd_reservations();
+```bash
+br show <id>
 ```
 
-### Step 6: Add Notes as You Work
+Shows full description, dependencies, notes, history.
 
-Use `bd_show` output's notes field. Write notes as if explaining to a future agent with zero conversation context.
+### Step 4: Do the Work
 
-**Note Format** (best practice):
+Implement the task, adding notes as you learn.
 
-```
-COMPLETED: Specific deliverables (e.g., "implemented JWT refresh endpoint")
-IN PROGRESS: Current state + next immediate step
-BLOCKERS: What's preventing progress
-KEY DECISIONS: Important context or user guidance
-```
+### Step 5: Complete and Sync
 
-### Step 7: Complete and Restart
-
-```typescript
-bd_done({ id: "task-abc", msg: "Implemented auth with JWT tokens" });
-// RESTART SESSION - fresh context
+```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 `bd_done()`. One task per session.
+Always restart session after closing a task. One task per session.
 
 ## Task Creation
 
@@ -222,181 +188,54 @@ Create tasks when:
 
 ### Basic Task Creation
 
-```typescript
-bd_add({
-  title: "Fix authentication bug",
-  pri: 0, // 0=critical, 1=high, 2=normal, 3=low, 4=backlog
-  type: "bug", // task, bug, feature, epic, chore
-});
+```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 and Tags
+### With Description
 
-```typescript
-bd_add({
-  title: "Implement OAuth",
-  desc: "Add OAuth2 support for Google, GitHub. Use passport.js.",
-  pri: 1,
-  type: "feature",
-  tags: ["be", "security"], // Role tags for assignment
-});
+```bash
+br create --title "Implement OAuth" --type feature --priority 1 \
+  --description "Add OAuth2 support for Google, GitHub. Use passport.js."
 ```
 
 ### Epic with Children
 
-```typescript
-// Create parent epic
-bd_add({ title: "Epic: OAuth Implementation", pri: 0, type: "epic" });
-// Returns: { id: "oauth-abc" }
-
-// Create child tasks with parent
-bd_add({ title: "Research OAuth providers", pri: 1, parent: "oauth-abc" });
-bd_add({ title: "Implement auth endpoints", pri: 1, parent: "oauth-abc" });
-bd_add({ title: "Add frontend login UI", pri: 2, parent: "oauth-abc" });
-```
-
-## File Reservation
-
-### Reserve Before Edit
-
-```typescript
-bd_reserve({
-  paths: ["src/auth.ts", "src/middleware/jwt.ts"],
-  reason: "Implementing auth feature",
-  ttl: 600, // seconds until expiry (default)
-});
-```
-
-**Returns**:
-
-```json
-{
-  "granted": ["src/auth.ts"],
-  "conflicts": [{ "path": "src/middleware/jwt.ts", "holder": "agent-xyz" }]
-}
-```
-
-### Check Active Locks
-
-```typescript
-bd_reservations();
-```
-
-Shows all locks across workspace with agent IDs and expiry times.
-
-### Handle Conflicts
-
-If file reserved by another agent:
-
-1. **Can wait** → Work on different files first
-2. **Urgent** → Message the agent:
-
-```typescript
-bd_msg({
-  subj: "Need src/middleware/jwt.ts",
-  body: "Working on auth, can you release?",
-  to: "agent-xyz",
-});
-```
-
-3. **Alternative** → Refactor to avoid that file
-
-### Release Early
-
-```typescript
-bd_release({ paths: ["src/auth.ts"] }); // Specific files
-bd_release(); // All your reservations
-```
-
-Note: `bd_done()` auto-releases all your reservations.
-
-## Messaging
-
-### Send Message
-
-```typescript
-bd_msg({
-  subj: "API Ready",
-  body: "Auth endpoints deployed to staging",
-  to: "all", // or specific agent ID
-  importance: "high", // low, normal, high
-});
-```
-
-### Team Broadcast
-
-```typescript
-bd_msg({
-  subj: "Breaking Change",
-  body: "User schema updated, run migrations",
-  to: "all",
-  global: true, // Cross-workspace
-});
-```
-
-### Check Inbox
-
-```typescript
-bd_inbox({ unread: true, n: 10 });
-```
-
-### Acknowledge Messages
-
-```typescript
-bd_ack({ ids: ["msg-abc", "msg-def"] }); // Mark as read
-```
-
-## Agent Coordination
-
-### Who's Working on What
-
-```typescript
-bd_whois(); // All agents with their files and tasks
-bd_whois({ agent: "build-abc" }); // Specific agent lookup
-```
-
-## Status and Analysis
-
-### Workspace Overview
+```bash
+# Create parent epic
+br create --title "Epic: OAuth Implementation" --priority 0 --type epic
+# Returns: oauth-abc
 
-```typescript
-bd_status({ include_agents: true });
+# 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
 ```
 
-Shows ready tasks, in-progress count, active locks, agent info.
-
-### Find Blocked Work
-
-```typescript
-bd_blocked();
-```
-
-Returns tasks that have unresolved dependencies.
-
-### View Dependencies
-
-```typescript
-bd_dep({ action: "tree", child: "<task-id>", type: "blocks" });
-```
+## Git Sync
 
-Shows dependency tree for a specific task.
+### Manual Sync (Non-Invasive)
 
-## Git Sync
+**Important:** `br` never executes git commands. You must manually commit changes.
 
-### Manual Sync
+```bash
+# Export changes to JSONL
+br sync --flush-only
 
-```typescript
-bd_sync();
+# Then manually commit
+git add .beads/
+git commit -m "sync beads"
+git push
 ```
 
-Commits `.beads/` changes, pulls from remote, pushes local commits.
-
 **Use when**: End of session, before handoff, after major progress.
 
 ### Cleanup Old Issues
 
-```typescript
-bd_cleanup({ days: 7 });
+```bash
+br cleanup --days 7
 ```
 
 Removes closed issues older than N days. Run weekly.
@@ -405,96 +244,60 @@ Removes closed issues older than N days. Run weekly.
 
 ### Common Issues
 
-**"Call bd_init() first"**
-
-- Always call `bd_init()` at session start
-
-**File conflicts**
-
-- Check `bd_reservations()` before editing
-- Message holder or work on other files
-
 **No ready tasks**
 
-- Run `bd_ls({ status: "open" })` to see all tasks
-- Some may be blocked - check dependencies
+- Run `br list --status open` to see all tasks
+- Some may be blocked - check dependencies with `br show <id>`
 
 **Sync failures**
 
-- Run `bd_doctor()` to repair database
+- Run `br doctor` to repair database
 - Check git remote access
 
 ## Examples
 
 ### Example 1: Standard Session
 
-```typescript
-// 1. Join and claim
-bd_init({ team: "project", role: "fe" });
-const task = bd_claim();
-// { id: "auth-123", t: "Implement login form", p: 1 }
-
-// 2. Get context
-bd_show({ id: "auth-123" });
-
-// 3. Reserve files
-bd_reserve({ paths: ["src/components/Login.tsx", "src/hooks/useAuth.ts"] });
-
-// 4. Do the work...
-// [implementation]
-
-// 5. Complete
-bd_done({
-  id: "auth-123",
-  msg: "Login form with validation, hooks for auth state",
-});
-// RESTART 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
 
-```typescript
-// Working on task, found more work
-bd_add({
-  title: "Fix edge case in validation",
-  desc: "Empty strings bypass email check - discovered while implementing login",
-  pri: 1,
-  type: "bug",
-});
-// Continue current task, new task tracked for later
+```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: Blocked Work
+### Example 3: Creating Dependencies
 
-```typescript
-// API is down, can't continue
-bd_release(); // Free files for others
-
-// Message team
-bd_msg({
-  subj: "Blocked: API 503",
-  body: "Auth endpoint returning 503, switching tasks",
-  to: "all",
-});
-
-// Claim different task
-const newTask = bd_claim();
-```
+```bash
+# Create tasks with dependencies
+br create --title "Setup database" --type task --priority 1
+# Returns: setup-db
 
-### Example 4: Multi-Agent Coordination
+br create --title "Implement API" --type task --priority 2 --blocked-by setup-db
+# Returns: impl-api (blocked until setup-db closes)
 
-```typescript
-// Agent A (backend)
-bd_init({ team: "project", role: "be" });
-bd_reserve({ paths: ["src/api/auth.ts"] });
-// ... implements API ...
-bd_msg({ subj: "Auth API Ready", to: "all" });
-bd_done({ id: "api-task", msg: "Auth endpoints complete" });
-
-// Agent B (frontend) - sees message
-bd_inbox({ unread: true });
-// { msgs: [{ subj: "Auth API Ready", from: "agent-a" }] }
-bd_claim(); // Gets frontend task that was waiting on API
+br create --title "Add tests" --type task --priority 2 --blocked-by impl-api
+# Returns: add-tests
 ```
 
 ## Multi-Agent Coordination (Swarm Mode)
@@ -505,12 +308,12 @@ For parallel execution with multiple subagents, use the **beads-bridge** skill:
 skill({ name: "beads-bridge" });
 ```
 
-**beads-bridge** provides:
+**beads-bridge** provides (via unified `swarm` tool):
 
-- `beads-sync` - Sync Beads tasks to OpenCode todos for subagent visibility
-- `swarm-monitor` - Real-time progress tracking and visualization
-- `swarm-plan` - Task classification and dependency analysis
-- `swarm-delegate` - Create delegation packets for workers
+- `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:**
 
@@ -518,36 +321,35 @@ skill({ name: "beads-bridge" });
 | ------------------------------ | -------------------------------- |
 | Single agent, linear work      | `beads` skill only               |
 | Multiple agents in parallel    | `beads-bridge` + `beads`         |
-| Need subagents to see tasks    | `beads-bridge` (beads-sync push) |
-| Track worker progress visually | `beads-bridge` (swarm-monitor)   |
+| Need subagents to see tasks    | `beads-bridge` (swarm sync push) |
+| Track worker progress visually | `beads-bridge` (swarm monitor)   |
 
 **Example swarm workflow:**
 
 ```typescript
 // 1. Push beads to OpenCode todos (subagents can see via todoread)
-beads_sync({ operation: "push" });
+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_monitor({ operation: "render_block", team_name: "my-swarm" });
+swarm({ operation: "monitor", action: "render_block", team_name: "my-swarm" });
 
 // 4. Pull completed work back to beads
-beads_sync({ operation: "pull" });
+swarm({ operation: "sync", action: "pull" });
 ```
 
 ## Rules
 
-1. **Always `bd_init()` first** - Required before any other bd\_\* tool
-2. **Reserve before edit** - Prevents conflicts with other agents
-3. **One task per session** - Restart after `bd_done()`
-4. **Write notes for future agents** - Assume zero conversation context
-5. **Use `bd_msg(to="all")`** - For team-wide announcements
-6. **Sync regularly** - `bd_sync()` at session end
+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
 
-## Best Practices (from Steve Yegge)
+## Best Practices
 
 ### Daily/Weekly Maintenance
 
@@ -555,58 +357,40 @@ beads_sync({ operation: "pull" });
 | ------------ | -------------- | --------------------- | ---------------------------------------------- |
 | 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   |
-| Upgrade      | Weekly         | `br upgrade`          | Get latest features and fixes                  |
-| Git hooks    | Once per repo  | `br hooks install`    | Auto-sync on commit/merge/checkout             |
 
 ### 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. **Use short prefixes** - `br-`, `vc-`, `wy-` etc.
-5. **"Land the plane" = PUSH** - `br sync --flush-only` means git push, not "ready when you are"
-6. **Include issue ID in commits** - `git commit -m "Fix bug (bd-abc)"`
+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
+br list --status all --json | wc -l
 
 # Target: under 200-500 issues
 # If over, run cleanup more aggressively:
-bd cleanup --days 3
-```
-
-### Git Hooks (Essential)
-
-```bash
-bd hooks install
+br cleanup --days 3
 ```
 
-Installs hooks for:
-
-- **pre-commit**: Sync before commit
-- **post-merge**: Import changes after merge
-- **pre-push**: Ensure sync before push
-- **post-checkout**: Refresh after branch switch
-
 ## Quick Reference
 
 ```
 SESSION START:
-  bd_init() → bd_claim() → bd_show() → bd_reserve()
+  br ready → br update <id> --status in_progress → br show <id>
 
 DURING WORK:
-  bd_reserve() additional files
-  bd_add() for discovered work (>2min)
-  bd_msg() to coordinate
+  br create for discovered work (>2min)
+  br show <id> for context
 
 SESSION END:
-  bd_done() → RESTART SESSION
+  br close <id> --reason "..." → br sync --flush-only → git add .beads/ && git commit → RESTART SESSION
 
 MAINTENANCE:
-  bd_doctor() - weekly health check
-  bd_cleanup() - remove old issues
-  bd_sync() - git sync
+  br doctor - weekly health check
+  br cleanup --days 7 - remove old issues
 ```