bd-to-br-migration
Migrate docs from bd (beads) to br (beads_rust). Use when updating AGENTS.md, converting bd commands, "bd sync" → "br sync --flush-only", or beads migration.
How do I install this agent skill?
npx skills add https://github.com/dicklesworthstone/beads_rust --skill bd-to-br-migrationIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides instructions and scripts for migrating documentation and commands from an older 'beads' tool to a newer 'beads_rust' version. It uses standard development tools like grep and git for discovery and validation. No malicious behaviors were identified.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerwarn
8/8 files flagged
What does this agent skill do?
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](references/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 <id> | br show <id> | 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
| Need | Reference |
|------|-----------|
| Complete before/after examples | [TRANSFORMS.md](references/TRANSFORMS.md) |
| Bulk migration strategy | [BULK.md](references/BULK.md) |
| Common mistakes & fixes | [PITFALLS.md](references/PITFALLS.md) |
---
## Scripts
| Script | Purpose |
|--------|---------|
| `./scripts/find-bd-refs.sh /path` | Find files needing migration |
| `./scripts/verify-migration.sh file.md` | Verify migration complete |
---
## Validation
```bash
# Full verification
./scripts/verify-migration.sh /path/to/AGENTS.md
# Quick check (should return nothing)
grep '`bd ' /path/to/AGENTS.md
If any bd references remain → migration incomplete → re-apply transforms.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/dicklesworthstone/beads_rust/bd-to-br-migration">View bd-to-br-migration on skillZs</a>