bd → br Migration

Core Philosophy:

One behavioral change, mechanical transforms. The ONLY difference is git handling—everything else is find-replace.

Why This Matters

Incomplete migrations leave broken docs. Agents follow stale

bd sync

instructions, expect auto-commit, and lose work. This skill ensures

complete, verified migrations

.

THE EXACT PROMPT — Single File Migration

Migrate this file from bd (beads) to br (beads_rust).

Apply transforms IN THIS ORDER (order matters):

1. Section headers: "bd (beads)" → "br (beads_rust)"

2. Add non-invasive note after beads section header

3. Commands: bd X → br X for ready/list/show/create/update/close/dep/stats

4. Sync command: bd sync → br sync --flush-only

5. Add git steps after EVERY sync:

git add .beads/

git commit -m "sync beads"

6. Issue IDs: bd-### → br-### in thread_ids, subjects, reasons, commits

7. Links: beads_viewer → beads_rust (if present)

Remove completely:

- Daemon references

- Auto-commit assumptions

- Hook installation mentions

- RPC mode

Keep unchanged:

- SQLite/WAL cautions

- bv integration

- Priority system (P0-P4)

VERIFY after editing:

grep -c '`bd ' file.md # Must be 0

grep -c 'bd sync' file.md # Must be 0

grep -c 'br sync --flush-only' file.md # Must be > 0

Why This Prompt Works

Ordered transforms

Dependencies exist (sync must change before adding git steps)

Explicit removals

Daemon/RPC don't exist in br—leaving them confuses agents

Keep list

Prevents accidental removal of still-valid patterns

Built-in verification

Grep commands catch missed transforms

No degrees of freedom

This is a LOW freedom task—exact transforms required Decision Tree: What Are You Migrating? What are you migrating? │ ├─ Single file (AGENTS.md) │ │ │ └─ Follow THE EXACT PROMPT above │ Use: ./scripts/verify-migration.sh file.md │ ├─ Multiple files (batch) │ │ │ ├─ <10 files → Sequential: apply prompt to each │ │ │ └─ 10+ files → Parallel subagents │ Batch ~10 files per agent │ See: BULK.md │ └─ Verify existing migration │ └─ Run: ./scripts/find-bd-refs.sh /path Any output = incomplete migration The One Behavioral Difference ┌─────────────────────────────────────────────────────────────────┐ │ bd (Go) br (Rust) │ ├─────────────────────────────────────────────────────────────────┤ │ bd sync → br sync --flush-only │ │ (auto-commits to git) (exports JSONL only) │ │ │ │ + git add .beads/ │ │ + git commit -m "..." │ └─────────────────────────────────────────────────────────────────┘ Everything else is literally s/bd/br/g Command Map bd br Change Type bd ready br ready Name only bd list br list Name only bd show br show Name only bd create br create Name only bd update br update Name only bd close br close Name only bd dep add br dep add Name only bd stats br stats Name only bd sync br sync --flush-only + git BEHAVIORAL Transform Patterns Pattern 1: The Non-Invasive Note Add immediately after any beads section header: ** Note: ** br is non-invasive and never executes git commands. After br sync --flush-only , you must manually run git add .beads/ && git commit . Pattern 2: Sync Command Transform Before: bd sync After: br sync --flush-only git add .beads/ git commit -m "sync beads" Pattern 3: Session End Transform Before: git add < files

bd sync git push After: git add < files

br sync --flush-only git add .beads/ git commit -m "..." git push Pattern 4: Issue ID Transform Before: thread_id: bd-123 subject: [bd-123] Feature implementation reason: bd-123 After: thread_id: br-123 subject: [br-123] Feature implementation reason: br-123 Validation Loop ┌─────────────────────────────────────────────────────────────────┐ │ VALIDATION IS MANDATORY │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ 1. Apply transforms │ │ ↓ │ │ 2. Run verification: │ │ ./scripts/verify-migration.sh file.md │ │ ↓ │ │ 3. If FAIL → read error → fix specific issue → goto 2 │ │ ↓ │ │ 4. Only proceed when PASS │ │ │ │ ⚠️ Never skip verification. Incomplete migrations break agents.│ └─────────────────────────────────────────────────────────────────┘ Quick Verification Commands

MUST return 0:

grep -c '`bd ' file.md grep -c 'bd sync' file.md grep -c 'bd ready' file.md

MUST return > 0 (if file has sync sections):

grep -c 'br sync --flush-only' file.md grep -c 'git add .beads/' file.md Risk Tiers Operation Risk Freedom Command renames ( bd → br ) Low Mechanical—no judgment Sync transform + git steps Medium MUST add git steps Removing daemon refs Medium Verify not removing valid content Bulk migration (10+ files) High Use subagents with verification Degrees of Freedom: LOW This is a deterministic transformation . There is ONE correct output for each input. No creative interpretation No optional improvements No stylistic choices Apply transforms EXACTLY as specified What Gets Removed Pattern Why Remove Verify Absent "bd daemon" br has no daemon grep -i daemon "auto-commits" br never commits grep -i "auto.*commit" "git hooks" br installs none grep -i "hook" "RPC mode" br has no RPC grep -i "rpc" What Stays Unchanged Pattern Why Keep SQLite/WAL cautions br still uses WAL bv integration Works with both Priority P0-P4 Same system Issue types Same system Dependency tracking Same system .beads/ as source of truth Same system Before/After Example Before (bd)

Issue Tracking with bd (beads) Key invariants: - .beads/ is authoritative

Agent workflow: 1. bd ready to find work 2. bd update <id> --status in_progress 3. Implement 4. bd close <id> 5. bd sync commits changes After (br)

Issue Tracking with br (beads_rust) ** Note: ** br is non-invasive and never executes git commands. After br sync --flush-only , you must manually run git add .beads/ && git commit . Key invariants: - .beads/ is authoritative

Agent workflow: 1. br ready to find work 2. br update <id> --status in_progress 3. Implement 4. br close <id> 5. Sync and commit: ```bash br sync --flush-only git add .beads/ git commit -m "sync beads"

References