opencodekit 0.16.4 → 0.16.5

package/dist/index.js

@@ -759,7 +759,7 @@ var cac = (name = "") => new CAC(name);
 // package.json
 var package_default = {
   name: "opencodekit",
-  version: "0.16.4",
+  version: "0.16.5",
   description: "CLI tool for bootstrapping and managing OpenCodeKit projects",
   keywords: ["agents", "cli", "mcp", "opencode", "opencodekit", "template"],
   license: "MIT",

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)
@@ -540,14 +343,13 @@ beads_sync({ operation: "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
 ```

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

@@ -1,4 +1,4 @@
-# Boundaries: When to Use bd\_\* vs TodoWrite
+# Boundaries: When to Use br vs TodoWrite
 
 Decision criteria for choosing between beads tools and TodoWrite.
 
@@ -6,12 +6,12 @@ Decision criteria for choosing between beads tools and TodoWrite.
 
 **"Could I resume this work after 2 weeks away?"**
 
-- If beads would help you resume → **use bd\_\***
+- If beads would help you resume → **use br**
 - If markdown skim would suffice → **TodoWrite is fine**
 
 ## Decision Matrix
 
-### Use bd\_\* for:
+### Use br for:
 
 **Multi-Session Work**
 
@@ -78,7 +78,7 @@ Decision criteria for choosing between beads tools and TodoWrite.
 
 ## Detailed Comparison
 
-| Aspect           | bd\_\*                            | TodoWrite              |
+| Aspect           | br CLI                            | TodoWrite              |
 | ---------------- | --------------------------------- | ---------------------- |
 | **Persistence**  | Git-backed, survives compaction   | Session-only           |
 | **Dependencies** | Graph-based, auto ready detection | Manual                 |
@@ -89,10 +89,10 @@ Decision criteria for choosing between beads tools and TodoWrite.
 
 ## Integration Patterns
 
-### Pattern 1: bd\_\* as Strategic, TodoWrite as Tactical
+### Pattern 1: br as Strategic, TodoWrite as Tactical
 
 ```
-bd task: "Implement user authentication" (epic)
+br task: "Implement user authentication" (epic)
   ├─ Child: "Create login endpoint"
   ├─ Child: "Add JWT validation"  ← Currently working
   └─ Child: "Implement logout"
@@ -108,16 +108,17 @@ TodoWrite (for JWT validation):
 
 ```
 Session start:
-- bd_claim() gets "Add JWT validation"
+- br ready gets "Add JWT validation"
+- br update <id> --status in_progress
 - Extract acceptance criteria into TodoWrite
 - Work through TodoWrite items
-- Update bd notes as you learn
-- bd_done() when TodoWrite complete
+- Update br notes as you learn
+- br close <id> when TodoWrite complete
 ```
 
 ### Pattern 3: Transition Mid-Session
 
-**From TodoWrite to bd\_\*:**
+**From TodoWrite to br:**
 
 Trigger signals:
 
@@ -129,11 +130,11 @@ Trigger signals:
 **How to transition:**
 
 ```
-1. bd_add() with current TodoWrite content
+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 bd notes before session ends
+5. Update br notes before session ends
 ```
 
 ## Common Mistakes
@@ -147,9 +148,9 @@ Trigger signals:
 - Lose design decisions
 - Duplicate work
 
-**Solution:** Use bd\_\* instead.
+**Solution:** Use br instead.
 
-### Mistake 2: bd\_\* for Simple Linear Tasks
+### Mistake 2: br for Simple Linear Tasks
 
 **What happens:**
 
@@ -168,9 +169,9 @@ Trigger signals:
 - Keep using TodoWrite despite poor fit
 - Lose context when session ends
 
-**Solution:** Transition to bd\_\* when complexity appears.
+**Solution:** Transition to br when complexity appears.
 
-### Mistake 4: Creating Too Many bd Issues
+### Mistake 4: Creating Too Many br Issues
 
 **What happens:**
 
@@ -178,7 +179,7 @@ Trigger signals:
 - Database cluttered
 - Hard to find meaningful work
 
-**Solution:** Use 2-week test. Would bd help after 2 weeks? If no, skip.
+**Solution:** Use 2-week test. Would br help after 2 weeks? If no, skip.
 
 ## The Transition Point
 
@@ -191,28 +192,28 @@ Trigger signals:
 - "User might not continue today"
 - "Found three related issues"
 
-When you notice these: Create bd issue, preserve context.
+When you notice these: Create br issue, preserve context.
 
 ## Summary Heuristics
 
 **Time horizon:**
 
 - Same session → TodoWrite
-- Multiple sessions → bd\_\*
+- Multiple sessions → br
 
 **Dependency structure:**
 
 - Linear steps → TodoWrite
-- Blockers/prerequisites → bd\_\*
+- Blockers/prerequisites → br
 
 **Scope clarity:**
 
 - Well-defined → TodoWrite
-- Exploratory → bd\_\*
+- Exploratory → br
 
 **Multi-agent:**
 
 - Single agent → Either
-- Multiple agents → bd\_\*
+- Multiple agents → br
 
 **When in doubt:** Use the 2-week test.

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

@@ -4,15 +4,13 @@ Beads supports task dependencies for ordering work.
 
 ## Overview
 
-Dependencies affect what work is "ready" - tasks with unmet dependencies won't appear in `bd_claim()` results.
+Dependencies affect what work is "ready" - tasks with unmet dependencies won't appear in `br ready` results.
 
 ## Creating Dependencies
 
-```typescript
-bd_add({
-  title: "Implement API endpoint",
-  deps: ["task:setup-db"], // depends on setup-db task
-});
+```bash
+br create --title "Implement API endpoint" --blocked-by setup-db
+# This task depends on setup-db completing first
 ```
 
 ## Dependency Patterns
@@ -23,7 +21,7 @@ bd_add({
 setup-db → implement-api → add-tests → deploy
 ```
 
-Each task depends on the previous. `bd_claim()` shows only the current step.
+Each task depends on the previous. `br ready` shows only the current step.
 
 ### Parallel Then Merge
 
@@ -47,19 +45,15 @@ One foundational task blocks multiple features.
 
 ## Epic with Children
 
-```typescript
-// Create epic
-bd_add({ title: "OAuth Integration", type: "epic" });
-// Returns: { id: "oauth-abc" }
-
-// Create children with parent
-bd_add({ title: "Setup credentials", parent: "oauth-abc" });
-bd_add({
-  title: "Implement flow",
-  parent: "oauth-abc",
-  deps: ["task:credentials"],
-});
-bd_add({ title: "Add UI", parent: "oauth-abc", deps: ["task:flow"] });
+```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
@@ -67,9 +61,9 @@ bd_add({ title: "Add UI", parent: "oauth-abc", deps: ["task:flow"] });
 When you close a task that's blocking others:
 
 ```
-1. bd_done({ id: "setup-db" })
+1. br close setup-db --reason "Schema created"
 2. Beads automatically updates: implement-api is now ready
-3. bd_claim() returns implement-api
+3. br ready returns implement-api
 4. No manual unblocking needed
 ```
 
@@ -91,8 +85,8 @@ docs depends on feature  // "prefer to update docs after"
 
 **Wrong:**
 
-```
-bd_add({ title: "API", deps: ["task:tests"] })  // API depends on tests?
+```bash
+br create --title "API" --blocked-by tests  # API depends on tests?
 ```
 
 **Problem:** Usually tests depend on API, not the other way.
@@ -121,10 +115,10 @@ bd_add({ title: "API", deps: ["task:tests"] })  // API depends on tests?
 
 ## Viewing Dependencies
 
-```typescript
-bd_show({ id: "task-abc" });
-// Shows what blocks this task and what this task blocks
+```bash
+br show <id>
+# Shows what blocks this task and what this task blocks
 
-bd_blocked();
-// Shows all blocked tasks across project
+br list --status open
+# Shows all open tasks, check dependencies in details
 ```

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

@@ -52,28 +52,26 @@ DESIRED OUTPUT:
 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:
@@ -82,12 +80,11 @@ 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:
 

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

@@ -2,17 +2,19 @@
 
 Detailed step-by-step workflows for common beads usage patterns.
 
+**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`.
+
 ## Session Start Workflow
 
 **Every session when beads is available:**
 
 ```
 Session Start:
-- [ ] bd_init({ team: "project", role: "fe" })
-- [ ] bd_claim() to get ready work
-- [ ] If none ready, bd_ls({ status: "open" })
-- [ ] bd_show({ id }) for full context
-- [ ] bd_reserve({ paths }) before editing
+- [ ] br ready to find unblocked work
+- [ ] br update <id> --status in_progress to claim
+- [ ] If none ready, br list --status open
+- [ ] br show <id> for full context
+- [ ] Begin work
 ```
 
 ## Compaction Survival
@@ -23,8 +25,8 @@ Session Start:
 
 ```
 After Compaction:
-- [ ] bd_ls({ status: "in_progress" }) to see active work
-- [ ] bd_show({ id }) for each in_progress task
+- [ ] br list --status in_progress to see active work
+- [ ] br show <id> for each in_progress task
 - [ ] Read notes: COMPLETED, IN PROGRESS, BLOCKERS, KEY DECISIONS
 - [ ] Reconstruct TodoWrite from notes if needed
 ```
@@ -54,7 +56,7 @@ Working on auth. Made some progress.
 Discovery:
 - [ ] Notice bug, improvement, or follow-up
 - [ ] Assess: blocker or deferrable?
-- [ ] bd_add({ title, desc, pri })
+- [ ] br create --title "..." --type bug --priority 1
 - [ ] If blocker: pause and switch
 - [ ] If deferrable: continue current work
 ```
@@ -86,15 +88,15 @@ A **Ready Front** is the set of tasks with all dependencies satisfied.
 
 **Example: OAuth Integration**
 
-```typescript
-// Create epic
-bd_add({ title: "OAuth integration", type: "epic" });
+```bash
+# Create epic
+br create --title "OAuth integration" --type epic --priority 1
 
-// Walk backward: What does OAuth need?
-bd_add({ title: "Login/logout endpoints", parent: "oauth-abc" });
-bd_add({ title: "Token storage and refresh", parent: "oauth-abc" });
-bd_add({ title: "Authorization code flow", parent: "oauth-abc" });
-bd_add({ title: "OAuth client credentials", parent: "oauth-abc" }); // foundation
+# Walk backward: What does OAuth need?
+br create --title "Login/logout endpoints" --parent oauth-abc
+br create --title "Token storage and refresh" --parent oauth-abc
+br create --title "Authorization code flow" --parent oauth-abc
+br create --title "OAuth client credentials" --parent oauth-abc  # foundation
 ```
 
 ## Side Quest Handling
@@ -102,9 +104,9 @@ bd_add({ title: "OAuth client credentials", parent: "oauth-abc" }); // foundatio
 ```
 Side Quest:
 - [ ] During main work, discover problem
-- [ ] bd_add() for side quest
+- [ ] br create for side quest
 - [ ] Assess: blocker or deferrable?
-- [ ] If blocker: bd_release(), switch to side quest
+- [ ] If blocker: switch to side quest
 - [ ] If deferrable: note it, continue main work
 ```
 
@@ -116,8 +118,10 @@ Side Quest:
 Session End:
 - [ ] Work reaching stopping point
 - [ ] Update notes with COMPLETED/IN PROGRESS/NEXT
-- [ ] bd_done() if task complete
+- [ ] br close <id> --reason "..." if task complete
 - [ ] Otherwise leave in_progress with notes
+- [ ] br sync --flush-only
+- [ ] git add .beads/ && git commit -m "session end"
 - [ ] RESTART SESSION
 ```
 
@@ -125,8 +129,8 @@ Session End:
 
 ```
 Session Start with in_progress:
-- [ ] bd_ls({ status: "in_progress" })
-- [ ] bd_show({ id }) for each
+- [ ] br list --status in_progress
+- [ ] br show <id> for each
 - [ ] Read notes field
 - [ ] Continue from notes context
 ```
@@ -137,9 +141,8 @@ Session Start with in_progress:
 
 ```
 Unblocking:
-- [ ] bd_ls({ status: "open" }) to see all tasks
-- [ ] bd_blocked() to find blocked tasks
-- [ ] Identify blocker tasks
+- [ ] br list --status open to see all tasks
+- [ ] Identify blocked tasks and their blockers
 - [ ] Work on blockers first
 - [ ] Closing blocker unblocks dependent work
 ```
@@ -150,14 +153,15 @@ Unblocking:
 
 ```
 Hybrid:
-- [ ] bd_claim() for high-level task
+- [ ] br ready to find high-level task
+- [ ] br update <id> --status in_progress
 - [ ] Create TodoWrite from acceptance criteria
 - [ ] Work through TodoWrite items
-- [ ] Update bd notes as you learn
-- [ ] When TodoWrite complete, bd_done()
+- [ ] Update br notes as you learn
+- [ ] When TodoWrite complete, br close <id>
 ```
 
-**Why hybrid**: bd provides persistent structure, TodoWrite provides visible progress.
+**Why hybrid**: br provides persistent structure, TodoWrite provides visible progress.
 
 ## Common Patterns
 
@@ -166,7 +170,7 @@ Hybrid:
 ```
 1. Create research task
 2. Update notes with findings
-3. bd_add() for discoveries
+3. br create for discoveries
 4. Close research with conclusion
 ```
 
@@ -185,7 +189,7 @@ Hybrid:
 ```
 1. Create tasks for each step
 2. Work through in dependency order
-3. bd_claim() shows next step
+3. br ready shows next step
 4. Each completion unblocks next
 ```
 
@@ -194,10 +198,9 @@ Hybrid:
 ### Starting Any Session
 
 ```
-- [ ] bd_init()
-- [ ] bd_claim() or bd_ls()
-- [ ] bd_show() for context
-- [ ] bd_reserve() files
+- [ ] br ready
+- [ ] br update <id> --status in_progress
+- [ ] br show <id> for context
 - [ ] Begin work
 ```
 
@@ -205,10 +208,9 @@ Hybrid:
 
 ```
 - [ ] Notice new work needed
-- [ ] bd_add() with clear title
-- [ ] Add context in desc
+- [ ] br create --title "..." with clear title
+- [ ] Add context in description
 - [ ] Assess blocker vs deferrable
-- [ ] Update statuses
 ```
 
 ### Completing Work
@@ -216,7 +218,9 @@ Hybrid:
 ```
 - [ ] Implementation done
 - [ ] Tests passing
-- [ ] bd_done() with summary
-- [ ] bd_claim() for next work
+- [ ] br close <id> --reason "..."
+- [ ] br sync --flush-only
+- [ ] git add .beads/ && git commit
+- [ ] br ready for next work
 - [ ] RESTART SESSION
 ```

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

@@ -1,10 +1,10 @@
 ---
 name: beads-bridge
 description: >
-  Multi-agent task coordination using Beads Village plugin tools. Use when work spans multiple sessions,
+  Multi-agent task coordination using br (beads_rust) and OpenCode tools. 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.0.0"
+version: "2.0.0"
 license: MIT
 ---
 
@@ -12,11 +12,13 @@ license: MIT
 
 Bridge between Beads git-backed task tracking, OpenCode's native todo system, and swarm coordination.
 
+**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 Bridge = Beads + OpenCode Todos + Swarm Monitor**
+**Beads Bridge = Beads (br) + OpenCode Todos + Swarm Monitor**
 
-- **Beads**: Git-backed task tracking with dependency management
+- **Beads (br)**: Git-backed task tracking with dependency management
 - **OpenCode Todos**: Native session-scoped task lists for subagents
 - **Swarm Monitor**: Real-time progress tracking (visualization only)
 
@@ -166,8 +168,10 @@ await swarm_monitor({
   team_name: "api-refactor-swarm",
 });
 
-// 7. Close parent Bead
+// 7. Close parent Bead and sync
 await bash("br close parent-task --reason 'Swarm completed all subtasks'");
+await bash("br sync --flush-only");
+await bash("git add .beads/ && git commit -m 'close parent-task'");
 ```
 
 ### Pattern B: Dependency-Aware Task Scheduling
@@ -240,6 +244,10 @@ Next steps:
   mode: "replace",
 });
 
+// Sync beads before ending session
+await bash("br sync --flush-only");
+await bash("git add .beads/ && git commit -m 'session handoff'");
+
 // Start of session 2: Check status and continue
 const status = await swarm_monitor({
   operation: "status",
@@ -278,7 +286,8 @@ DURING WORK:
 SESSION END:
   beads-sync({ operation: "pull" })  // Sync completed todos back to Beads
   swarm-monitor({ operation: "clear", team_name: "..." })  // Cleanup swarm state
-  br sync --flush-only  // Export Beads changes to git
+  br sync --flush-only  // Export Beads changes
+  git add .beads/ && git commit -m "..."  // Commit changes to git
 
 RECOVERY:
   beads-sync({ operation: "get_shared", list_id: "..." })  // Get shared task list
@@ -292,3 +301,4 @@ RECOVERY:
 3. **Pull completed todos back to Beads** - Keep tracking system in sync
 4. **Check swarm status before spawning** - Avoid duplicate work
 5. **Clear swarm state when done** - Cleanup after completion
+6. **Always sync and commit before session end** - `br sync --flush-only` then `git add .beads/ && git commit`

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencodekit",
-	"version": "0.16.4",
+	"version": "0.16.5",
 	"description": "CLI tool for bootstrapping and managing OpenCodeKit projects",
 	"keywords": ["agents", "cli", "mcp", "opencode", "opencodekit", "template"],
 	"license": "MIT",