SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsbd-to-br-migration

bd-to-br-migration

Office & productivity

View repository

Updated 10-15 21:09

About this skill

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 <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:**

```markdown
**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.