bd-to-br-migration

Files (8)

• SELF-TEST.md
• SKILL.md
• BULK.md · references/
• PITFALLS.md · references/
• TRANSFORMS.md · references/
• find-bd-refs.sh · scripts/
• verify-migration.sh · scripts/
• batch-migrator.md · subagents/

SKILL.md (first lines)

<!-- TOC: Philosophy | THE EXACT PROMPT | Decision Tree | Command Map | Transform Patterns | Validation Loop | Risk Tiers | References -->

# 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

From danzam98/claude-skills-toolkit, MIT.

More from danzam98/claude-skills-toolkit