Bd To Br Migration

<!-- 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

---

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

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

---

What Stays Unchanged

---

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:

br sync --flush-only git add .beads/ git commit -m "sync beads"

---

References

---

Scripts

---

Validation

# 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.

Bulk Migration Strategy

Table of Contents

• Discovery Phase
• Batch Strategy
• Subagent Prompt
• Verification Phase
• Commit Strategy
• Rollback

---

Discovery Phase

Find All Files Needing Migration

# Find files with bd command references
grep -l '`bd ' /data/projects/*/AGENTS.md 2>/dev/null

# Count total files
grep -l '`bd ' /data/projects/*/AGENTS.md 2>/dev/null | wc -l

# Find files with bd sync specifically
grep -l 'bd sync' /data/projects/*/AGENTS.md 2>/dev/null

# Find files with bd-### issue IDs
grep -l 'bd-[0-9]' /data/projects/*/AGENTS.md 2>/dev/null

Use the Discovery Script

./scripts/find-bd-refs.sh /data/projects/

Output:

=== Files with bd references ===
/data/projects/foo/AGENTS.md
/data/projects/bar/AGENTS.md
...

=== Count summary ===
Files with bd commands: 74
Files with bd sync: 68
Files with bd-### IDs: 45

---

Batch Strategy

Decision Matrix

Batching Rules

1. ~10 files per subagent — Sweet spot for context and verification 2. Group by project type — Similar files migrate similarly 3. Verify each batch — Don't proceed to next batch until current passes 4. One agent per batch — No file touched by multiple agents

---

Subagent Prompt

THE EXACT PROMPT — Batch Migration

Migrate these files from bd (beads) to br (beads_rust):

FILES:
- /data/projects/project1/AGENTS.md
- /data/projects/project2/AGENTS.md
- /data/projects/project3/AGENTS.md
[... list all files in batch ...]

Apply transforms IN THIS ORDER for each file:
1. Section headers: "bd (beads)" → "br (beads_rust)"
2. Add non-invasive note after 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`.
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 command:
   git add .beads/
   git commit -m "sync beads"
6. Issue IDs: bd-### → br-### in thread_ids, subjects, reasons
7. Links: beads_viewer → beads_rust (if present)

Remove completely:
- Daemon references
- Auto-commit assumptions
- Hook installation mentions

VERIFY each file after editing:
grep -c '`bd ' FILE.md     # Must be 0
grep -c 'bd sync' FILE.md  # Must be 0

Report format:
✓ /path/file.md - migrated
✗ /path/file.md - FAILED: [reason]

Do NOT proceed to next file if current file fails verification.

---

Verification Phase

Post-Batch Verification

# Verify no bd refs remain (should return empty)
grep -l '`bd ' /data/projects/*/AGENTS.md 2>/dev/null | grep -v beads_rust

# Verify new patterns exist
grep -l 'br sync --flush-only' /data/projects/*/AGENTS.md | wc -l
grep -l 'git add .beads/' /data/projects/*/AGENTS.md | wc -l

Full Verification Script

# Run on all files
for f in /data/projects/*/AGENTS.md; do
  ./scripts/verify-migration.sh "$f" || echo "FAILED: $f"
done

Expected Results

---

Commit Strategy

Option 1: Single Commit (Recommended)

# Stage all AGENTS.md changes
git add /data/projects/*/AGENTS.md

# Single descriptive commit
git commit -m "$(cat <<'EOF'
docs: migrate AGENTS.md from bd to br (beads_rust)

- bd → br command references
- bd sync → br sync --flush-only + manual git steps
- bd-### → br-### issue ID convention
- Added non-invasive note explaining git requirements
- Removed daemon/RPC references (not applicable to br)

Affected: ~74 AGENTS.md files

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
EOF
)"

Option 2: Per-Project Commits

# For each project
for project in /data/projects/*/; do
  if [[ -f "$project/AGENTS.md" ]]; then
    git add "$project/AGENTS.md"
    git commit -m "docs($project): migrate AGENTS.md bd → br"
  fi
done

---

Rollback

If Migration Introduced Errors

# Check git diff for specific file
git diff /data/projects/PROJECT/AGENTS.md

# Restore single file
git checkout -- /data/projects/PROJECT/AGENTS.md

# Restore all AGENTS.md files (CAREFUL)
git checkout -- /data/projects/*/AGENTS.md

Partial Rollback

# Find files that failed verification
for f in /data/projects/*/AGENTS.md; do
  if ! ./scripts/verify-migration.sh "$f" >/dev/null 2>&1; then
    echo "Restoring: $f"
    git checkout -- "$f"
  fi
done

---

Progress Tracking

For large migrations, track progress:

# bd → br Migration Progress

## Completed Batches
- [x] Batch 1: projects a-g (10 files) - verified
- [x] Batch 2: projects h-n (10 files) - verified
- [ ] Batch 3: projects o-t (10 files) - in progress

## Issues Encountered
- project_x: No beads section (skipped)
- project_y: Custom bd wrapper (manual review needed)

## Verification Status
Total files: 74
Migrated: 45
Remaining: 29

Common Pitfalls & Fixes

Table of Contents

• Critical Pitfalls
• Transform Pitfalls
• Verification Pitfalls
• Bulk Migration Pitfalls
• Quick Diagnostics

---

Critical Pitfalls

1. Forgetting Manual Git Steps (THE BIG ONE)

Symptom: Work appears lost after session end.

Cause: Agent followed migrated docs but docs didn't include git steps after br sync --flush-only.

Detection:

# Find files with sync but no git add
for f in /data/projects/*/AGENTS.md; do
  if grep -q 'br sync --flush-only' "$f" && ! grep -q 'git add .beads/' "$f"; then
    echo "MISSING GIT STEPS: $f"
  fi
done

Fix: After EVERY br sync --flush-only, add:

git add .beads/
git commit -m "sync beads"

---

2. Incomplete Sync Transform

Symptom: br sync fails or behaves unexpectedly.

Cause: Transformed bd sync to br sync but forgot --flush-only flag.

Detection:

grep -n 'br sync[^-]' file.md
grep -n 'br sync$' file.md

Fix: br sync → br sync --flush-only

---

3. Mixed Terminology in Same File

Symptom: Confusing docs with both bd-123 and br-123 references.

Cause: Partial migration, missed some issue ID references.

Detection:

# Check for both patterns in same file
if grep -q 'bd-[0-9]' file.md && grep -q 'br-[0-9]' file.md; then
  echo "MIXED IDs in file.md"
fi

Fix: Search comprehensively:

grep -n 'bd-[0-9]' file.md
# Transform all to br-###

---

Transform Pitfalls

4. Missing Non-Invasive Note

Symptom: Readers follow br commands but expect auto-commit behavior.

Cause: Forgot to add the critical behavioral note.

Detection:

# Files with br commands but no note
if grep -q '`br ' file.md && ! grep -q 'non-invasive' file.md; then
  echo "MISSING NOTE: $f"
fi

Fix: Add after 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`.

---

5. Daemon/Hook References Left Behind

Symptom: Docs mention "daemon" or "hooks" that don't exist in br.

Cause: Failed to remove bd-specific content.

Detection:

grep -in 'daemon\|hook\|rpc' file.md

Fix: Remove these sections entirely (not transform—DELETE).

---

6. Incomplete Pattern Search

Symptom: Some bd references remain after "complete" migration.

Cause: bd references appear in unexpected places:

• Inline code: ` bd `
• Code blocks inside examples
• Mapping tables
• P0 workflow sections
• Agent Mail examples

Detection (comprehensive):

grep -E '(bd ready|bd list|bd show|bd create|bd update|bd close|bd sync|bd dep|bd stats|bd-[0-9]|\`bd )' file.md

Fix: Search with ALL patterns, not just common ones.

---

Verification Pitfalls

7. False Positive in Verification

Symptom: Verification passes but file still has issues.

Cause: Verification only checks specific patterns, misses edge cases.

Example missed patterns:

Use bd for issue tracking    # No backticks, not caught
The bd tool is deprecated    # Prose reference, not caught

Fix: Add prose check:

grep -i '\bbd\b' file.md | grep -v '`bd' | grep -v 'br'

---

8. False Negative in Verification

Symptom: Verification fails but file is actually correct.

Cause: File legitimately has no beads section (verification expects br patterns).

Detection:

# Check if file actually has beads content
grep -q 'beads\|\.beads\|br ' file.md && echo "Has beads"

Fix: Skip verification for files without beads sections.

---

Bulk Migration Pitfalls

9. Parallel Agent File Conflicts

Symptom: File corrupted or has duplicate content.

Cause: Two agents edited same file simultaneously.

Prevention:

• Strict batching—no file in multiple batches
• Sequential verification between batches

Recovery:

git checkout -- /path/to/corrupted/file.md
# Re-run migration for this file only

---

10. Batch Size Too Large

Symptom: Agent context overflow, incomplete migrations.

Cause: >15 files per batch exceeds practical context.

Fix: Max 10 files per subagent batch.

---

11. Not Verifying Between Batches

Symptom: Later batches build on broken earlier batches.

Cause: Proceeded without verification.

Fix: ALWAYS verify before next batch:

./scripts/verify-migration.sh /path/to/batch/*.md

---

Quick Diagnostics

Comprehensive Health Check

#!/usr/bin/env bash
file="$1"

echo "=== Checking: $file ==="

# Should be 0
echo -n "bd commands: "
grep -c '`bd ' "$file" 2>/dev/null || echo "0"

echo -n "bd sync: "
grep -c 'bd sync' "$file" 2>/dev/null || echo "0"

echo -n "bd-### IDs: "
grep -c 'bd-[0-9]' "$file" 2>/dev/null || echo "0"

# Should be > 0 if file has beads sections
echo -n "br sync --flush-only: "
grep -c 'br sync --flush-only' "$file" 2>/dev/null || echo "0"

echo -n "git add .beads/: "
grep -c 'git add .beads/' "$file" 2>/dev/null || echo "0"

echo -n "non-invasive note: "
grep -c 'non-invasive' "$file" 2>/dev/null || echo "0"

# Should be 0
echo -n "daemon refs: "
grep -ci 'daemon' "$file" 2>/dev/null || echo "0"

echo -n "hook refs: "
grep -ci '\bhook\b' "$file" 2>/dev/null || echo "0"

One-Liner Status

# Quick pass/fail for file
grep -q '`bd ' file.md && echo "FAIL: bd refs remain" || echo "PASS: no bd refs"

Complete Transform Reference

Table of Contents

• Section Headers
• Command Transforms
• Workflow Transforms
• Session Protocol
• Landing the Plane
• Agent Mail Integration
• Full File Example

---

Section Headers

---

Command Transforms

Simple Renames (No Behavioral Change)

# Before → After (all identical except name)
bd ready              → br ready
bd list               → br list
bd list --status=open → br list --status=open
bd show <id>          → br show <id>
bd create             → br create
bd create --title="..." --type=task --priority=2 → br create --title="..." --type=task --priority=2
bd update <id>        → br update <id>
bd update <id> --status=in_progress → br update <id> --status=in_progress
bd close <id>         → br close <id>
bd close <id> --reason="Done" → br close <id> --reason="Done"
bd dep add            → br dep add
bd stats              → br stats

Sync Transform (BEHAVIORAL CHANGE)

Before:

bd sync               # Commits and pushes

After:

br sync --flush-only  # Exports only
git add .beads/       # YOU stage
git commit -m "..."   # YOU commit

---

Workflow Transforms

Basic Workflow

Before:

1. **Start**: Run `bd ready` to find actionable work
2. **Claim**: Use `bd update <id> --status=in_progress`
3. **Work**: Implement the task
4. **Complete**: Use `bd close <id>`
5. **Sync**: Always run `bd sync` at session end

After:

1. **Start**: Run `br ready` to find actionable work
2. **Claim**: Use `br update <id> --status=in_progress`
3. **Work**: Implement the task
4. **Complete**: Use `br close <id>`
5. **Sync**: Run `br sync --flush-only` then manually commit `.beads/`

Agent Workflow with Commands

Before:

### Agent workflow:

1. `bd ready` to find unblocked work.
2. Claim: `bd update <id> --status in_progress`.
3. Implement + test.
4. Close when done.
5. Commit `.beads/` in the same commit as code changes.

After:

### Agent workflow:

1. `br ready` to find unblocked work.
2. Claim: `br update <id> --status in_progress`.
3. Implement + test.
4. Close when done.
5. Sync and commit:

br sync --flush-only git add .beads/ git commit -m "..."

---

Session Protocol

Before

git status              # Check what changed
git add <files>         # Stage code changes
bd sync                 # Commit beads changes
git commit -m "..."     # Commit code
bd sync                 # Commit any new beads changes
git push                # Push to remote

After

git status              # Check what changed
git add <files>         # Stage code changes
br sync --flush-only    # Export beads to JSONL (no git ops)
git add .beads/         # Stage beads changes
git commit -m "..."     # Commit everything
git push                # Push to remote

---

Landing the Plane

Before

git pull --rebase
bd sync
git push
git status  # MUST show "up to date with origin"

After

git pull --rebase
br sync --flush-only    # Export beads to JSONL (no git ops)
git add .beads/         # Stage beads changes
git commit -m "sync beads"  # Commit beads
git push
git status  # MUST show "up to date with origin"

---

Agent Mail Integration

Thread ID Convention

Before:

- Mail `thread_id`: `bd-###`
- Mail subject: `[bd-###] ...`
- File reservation `reason`: `bd-###`
- Commit messages: Include `bd-###` for traceability

After:

- Mail `thread_id`: `br-###`
- Mail subject: `[br-###] ...`
- File reservation `reason`: `br-###`
- Commit messages: Include `br-###` for traceability

Typical Agent Flow

Before:

1. **Pick ready work (Beads):**

bd ready --json

2. **Reserve edit surface (Mail):**

file_reservation_paths(..., reason="bd-123")

3. **Announce start (Mail):**

send_message(..., thread_id="bd-123", subject="[bd-123] Start: <title>")

After:

1. **Pick ready work (Beads):**

br ready --json

2. **Reserve edit surface (Mail):**

file_reservation_paths(..., reason="br-123")

3. **Announce start (Mail):**

send_message(..., thread_id="br-123", subject="[br-123] Start: <title>")

---

Full File Example

Before (Complete Section)

## Issue Tracking with bd (beads)

All issue tracking goes through **bd**. No other TODO systems.

Key invariants:
- `.beads/` is authoritative state and **must always be committed** with code changes.
- Do not edit `.beads/*.jsonl` directly; only via `bd`.

### Basics

Check ready work:

bd ready --json

### Essential Commands

bd ready # Show issues ready to work bd list --status=open # All open issues bd create --title="..." --type=task --priority=2 bd update <id> --status=in_progress bd close <id> --reason="Completed" bd sync # Commit and push changes

### Session End Checklist

git status git add <files> bd sync git commit -m "..." git push

After (Complete Section)

## Issue Tracking with br (beads_rust)

All issue tracking goes through **br** (beads_rust). No other TODO systems.

**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 state and **must always be committed** with code changes.
- Do not edit `.beads/*.jsonl` directly; only via `br`.

### Basics

Check ready work:

br ready --json

### Essential Commands

br ready # Show issues ready to work br list --status=open # All open issues br create --title="..." --type=task --priority=2 br update <id> --status=in_progress br close <id> --reason="Completed" br sync --flush-only # Export to JSONL (no git ops)

### Session End Checklist

git status git add <files> br sync --flush-only git add .beads/ git commit -m "..." git push

---

Quick Search

# Find specific transform patterns
grep -i "session" references/TRANSFORMS.md
grep -i "landing" references/TRANSFORMS.md
grep -i "agent mail" references/TRANSFORMS.md

Self-Test: bd-to-br-migration

Trigger Phrases

These should activate this skill:

Quick Validation

# Skill structure exists
ls -la .claude/skills/bd-to-br-migration/

# Scripts are executable
ls -la .claude/skills/bd-to-br-migration/scripts/

# References exist
ls -la .claude/skills/bd-to-br-migration/references/

# Subagent exists
ls -la .claude/skills/bd-to-br-migration/subagents/

Functional Tests

Test 1: Discovery Script

# Run discovery (should report file counts)
.claude/skills/bd-to-br-migration/scripts/find-bd-refs.sh /data/projects/test-project/

Expected: Lists files with bd refs, provides migration strategy recommendation.

Test 2: Verification Script

# Create test file
cat > /tmp/test-migration.md << 'EOF'
## Issue Tracking with br (beads_rust)

**Note:** `br` is non-invasive and never executes git commands.

br ready br sync --flush-only git add .beads/ git commit -m "sync"

EOF

# Should pass
.claude/skills/bd-to-br-migration/scripts/verify-migration.sh /tmp/test-migration.md
echo "Exit code: $?"  # Should be 0

Test 3: Verification Failure

# Create file with bd refs (should fail)
cat > /tmp/test-bd.md << 'EOF'
## Issue Tracking with bd (beads)

bd ready bd sync

EOF

# Should fail
.claude/skills/bd-to-br-migration/scripts/verify-migration.sh /tmp/test-bd.md
echo "Exit code: $?"  # Should be 2

Integration Tests

Test 4: Single File Migration

1. Ask: "Migrate this file from bd to br: /tmp/test-bd.md" 2. Expected:

• Skill activates
• Transforms applied in order
• Verification runs
• File passes verification

Test 5: Bulk Migration

1. Ask: "How do I migrate 50 AGENTS.md files from bd to br?" 2. Expected:

• Skill activates
• References decision tree
• Recommends 5 parallel subagents
• Provides THE EXACT PROMPT for batch migration

Content Verification

THE EXACT PROMPT exists and includes:

• [ ] Ordered transforms (1-7)
• [ ] Remove list (daemon, hooks, RPC)
• [ ] Keep list (SQLite, bv, priorities)
• [ ] Verification commands

Decision Tree exists for:

• [ ] Single file
• [ ] Multiple files (<10)
• [ ] Bulk (10+)

Transform Patterns include:

• [ ] Non-invasive note
• [ ] Sync command transform
• [ ] Session end transform
• [ ] Issue ID transform

References complete:

• [ ] TRANSFORMS.md - Full before/after examples
• [ ] BULK.md - Subagent prompts
• [ ] PITFALLS.md - Common mistakes

Cleanup

rm -f /tmp/test-migration.md /tmp/test-bd.md

Batch Migration Subagent

You are a specialized migration agent. Your ONLY job: migrate files from bd (beads) to br (beads_rust).

Your Mission

Migrate the files listed in the prompt from bd to br following the exact transform rules.

Transform Rules (Apply IN ORDER)

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

2. Add non-invasive note after 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`.

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

   git add .beads/
   git commit -m "sync beads"

6. Issue IDs: bd-### → br-### in:

• thread_ids
• subjects
• reasons
• commit messages

7. Links: beads_viewer → beads_rust

Removal Rules

DELETE completely (not transform):

• Daemon references
• Auto-commit assumptions
• Hook installation mentions
• RPC mode references

Verification

After EACH file, verify:

grep -c '`bd ' FILE     # Must be 0
grep -c 'bd sync' FILE  # Must be 0

If verification fails, DO NOT proceed. Fix the file first.

Reporting

After each file, report:

✓ /path/file.md - migrated

Or if failed:

✗ /path/file.md - FAILED: [specific reason]

Constraints

• One file at a time — Complete and verify before moving to next
• No creative interpretation — This is mechanical transformation
• No improvements — Don't "improve" code you're migrating
• Exact transforms only — Apply rules literally