bd-to-br-migration — Skillopedia

<!-- 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 instructions, expect auto-commit, and lose work. This skill ensures complete, verified migrations . --- THE EXACT PROMPT — Single File Migration Why This Prompt Works - Ordered transforms : Dependencies exist (sync must change before…

file.md\n```\n\n**Fix:** `br sync` → `br sync --flush-only`\n\n---\n\n### 3. Mixed Terminology in Same File\n\n**Symptom:** Confusing docs with both `bd-123` and `br-123` references.\n\n**Cause:** Partial migration, missed some issue ID references.\n\n**Detection:**\n```bash\n# Check for both patterns in same file\nif grep -q 'bd-[0-9]' file.md && grep -q 'br-[0-9]' file.md; then\n echo \"MIXED IDs in file.md\"\nfi\n```\n\n**Fix:** Search comprehensively:\n```bash\ngrep -n 'bd-[0-9]' file.md\n# Transform all to br-###\n```\n\n---\n\n## Transform Pitfalls\n\n### 4. Missing Non-Invasive Note\n\n**Symptom:** Readers follow br commands but expect auto-commit behavior.\n\n**Cause:** Forgot to add the critical behavioral note.\n\n**Detection:**\n```bash\n# Files with br commands but no note\nif grep -q '`br ' file.md && ! grep -q 'non-invasive' file.md; then\n echo \"MISSING NOTE: $f\"\nfi\n```\n\n**Fix:** Add after section header:\n```markdown\n**Note:** `br` is non-invasive and never executes git commands. After `br sync --flush-only`, you must manually run `git add .beads/ && git commit`.\n```\n\n---\n\n### 5. Daemon/Hook References Left Behind\n\n**Symptom:** Docs mention \"daemon\" or \"hooks\" that don't exist in br.\n\n**Cause:** Failed to remove bd-specific content.\n\n**Detection:**\n```bash\ngrep -in 'daemon\\|hook\\|rpc' file.md\n```\n\n**Fix:** Remove these sections entirely (not transform—DELETE).\n\n---\n\n### 6. Incomplete Pattern Search\n\n**Symptom:** Some bd references remain after \"complete\" migration.\n\n**Cause:** bd references appear in unexpected places:\n- Inline code: `` `bd` ``\n- Code blocks inside examples\n- Mapping tables\n- P0 workflow sections\n- Agent Mail examples\n\n**Detection (comprehensive):**\n```bash\ngrep -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\n```\n\n**Fix:** Search with ALL patterns, not just common ones.\n\n---\n\n## Verification Pitfalls\n\n### 7. False Positive in Verification\n\n**Symptom:** Verification passes but file still has issues.\n\n**Cause:** Verification only checks specific patterns, misses edge cases.\n\n**Example missed patterns:**\n```markdown\nUse bd for issue tracking # No backticks, not caught\nThe bd tool is deprecated # Prose reference, not caught\n```\n\n**Fix:** Add prose check:\n```bash\ngrep -i '\\bbd\\b' file.md | grep -v '`bd' | grep -v 'br'\n```\n\n---\n\n### 8. False Negative in Verification\n\n**Symptom:** Verification fails but file is actually correct.\n\n**Cause:** File legitimately has no beads section (verification expects br patterns).\n\n**Detection:**\n```bash\n# Check if file actually has beads content\ngrep -q 'beads\\|\\.beads\\|br ' file.md && echo \"Has beads\"\n```\n\n**Fix:** Skip verification for files without beads sections.\n\n---\n\n## Bulk Migration Pitfalls\n\n### 9. Parallel Agent File Conflicts\n\n**Symptom:** File corrupted or has duplicate content.\n\n**Cause:** Two agents edited same file simultaneously.\n\n**Prevention:**\n- Strict batching—no file in multiple batches\n- Sequential verification between batches\n\n**Recovery:**\n```bash\ngit checkout -- /path/to/corrupted/file.md\n# Re-run migration for this file only\n```\n\n---\n\n### 10. Batch Size Too Large\n\n**Symptom:** Agent context overflow, incomplete migrations.\n\n**Cause:** >15 files per batch exceeds practical context.\n\n**Fix:** Max 10 files per subagent batch.\n\n---\n\n### 11. Not Verifying Between Batches\n\n**Symptom:** Later batches build on broken earlier batches.\n\n**Cause:** Proceeded without verification.\n\n**Fix:** ALWAYS verify before next batch:\n```bash\n./scripts/verify-migration.sh /path/to/batch/*.md\n```\n\n---\n\n## Quick Diagnostics\n\n### Comprehensive Health Check\n\n```bash\n#!/usr/bin/env bash\nfile=\"$1\"\n\necho \"=== Checking: $file ===\"\n\n# Should be 0\necho -n \"bd commands: \"\ngrep -c '`bd ' \"$file\" 2>/dev/null || echo \"0\"\n\necho -n \"bd sync: \"\ngrep -c 'bd sync' \"$file\" 2>/dev/null || echo \"0\"\n\necho -n \"bd-### IDs: \"\ngrep -c 'bd-[0-9]' \"$file\" 2>/dev/null || echo \"0\"\n\n# Should be > 0 if file has beads sections\necho -n \"br sync --flush-only: \"\ngrep -c 'br sync --flush-only' \"$file\" 2>/dev/null || echo \"0\"\n\necho -n \"git add .beads/: \"\ngrep -c 'git add .beads/' \"$file\" 2>/dev/null || echo \"0\"\n\necho -n \"non-invasive note: \"\ngrep -c 'non-invasive' \"$file\" 2>/dev/null || echo \"0\"\n\n# Should be 0\necho -n \"daemon refs: \"\ngrep -ci 'daemon' \"$file\" 2>/dev/null || echo \"0\"\n\necho -n \"hook refs: \"\ngrep -ci '\\bhook\\b' \"$file\" 2>/dev/null || echo \"0\"\n```\n\n### One-Liner Status\n\n```bash\n# Quick pass/fail for file\ngrep -q '`bd ' file.md && echo \"FAIL: bd refs remain\" || echo \"PASS: no bd refs\"\n```\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":5635,"content_sha256":"0fffeca4d4a33d56b284dc2956229e8f52a70ae1bd4a226b66ee3ad15f277823"},{"filename":"references/TRANSFORMS.md","content":"# Complete Transform Reference\n\n## Table of Contents\n- [Section Headers](#section-headers)\n- [Command Transforms](#command-transforms)\n- [Workflow Transforms](#workflow-transforms)\n- [Session Protocol](#session-protocol)\n- [Landing the Plane](#landing-the-plane)\n- [Agent Mail Integration](#agent-mail-integration)\n- [Full File Example](#full-file-example)\n\n---\n\n## Section Headers\n\n| Before | After |\n|--------|-------|\n| `## Issue Tracking with bd (beads)` | `## Issue Tracking with br (beads_rust)` |\n| `## Beads (bd)` | `## Beads (br)` |\n| `## Beads (bd) — Dependency-Aware Issue Tracking` | `## Beads (br) — Dependency-Aware Issue Tracking` |\n| `[beads_viewer](https://...)` | `[beads_rust](https://github.com/Dicklesworthstone/beads_rust)` |\n\n---\n\n## Command Transforms\n\n### Simple Renames (No Behavioral Change)\n\n```bash\n# Before → After (all identical except name)\nbd ready → br ready\nbd list → br list\nbd list --status=open → br list --status=open\nbd show \u003cid> → br show \u003cid>\nbd create → br create\nbd create --title=\"...\" --type=task --priority=2 → br create --title=\"...\" --type=task --priority=2\nbd update \u003cid> → br update \u003cid>\nbd update \u003cid> --status=in_progress → br update \u003cid> --status=in_progress\nbd close \u003cid> → br close \u003cid>\nbd close \u003cid> --reason=\"Done\" → br close \u003cid> --reason=\"Done\"\nbd dep add → br dep add\nbd stats → br stats\n```\n\n### Sync Transform (BEHAVIORAL CHANGE)\n\n**Before:**\n```bash\nbd sync # Commits and pushes\n```\n\n**After:**\n```bash\nbr sync --flush-only # Exports only\ngit add .beads/ # YOU stage\ngit commit -m \"...\" # YOU commit\n```\n\n---\n\n## Workflow Transforms\n\n### Basic Workflow\n\n**Before:**\n```markdown\n1. **Start**: Run `bd ready` to find actionable work\n2. **Claim**: Use `bd update \u003cid> --status=in_progress`\n3. **Work**: Implement the task\n4. **Complete**: Use `bd close \u003cid>`\n5. **Sync**: Always run `bd sync` at session end\n```\n\n**After:**\n```markdown\n1. **Start**: Run `br ready` to find actionable work\n2. **Claim**: Use `br update \u003cid> --status=in_progress`\n3. **Work**: Implement the task\n4. **Complete**: Use `br close \u003cid>`\n5. **Sync**: Run `br sync --flush-only` then manually commit `.beads/`\n```\n\n### Agent Workflow with Commands\n\n**Before:**\n```markdown\n### Agent workflow:\n\n1. `bd ready` to find unblocked work.\n2. Claim: `bd update \u003cid> --status in_progress`.\n3. Implement + test.\n4. Close when done.\n5. Commit `.beads/` in the same commit as code changes.\n```\n\n**After:**\n```markdown\n### Agent workflow:\n\n1. `br ready` to find unblocked work.\n2. Claim: `br update \u003cid> --status in_progress`.\n3. Implement + test.\n4. Close when done.\n5. Sync and commit:\n ```bash\n br sync --flush-only\n git add .beads/\n git commit -m \"...\"\n ```\n```\n\n---\n\n## Session Protocol\n\n### Before\n```bash\ngit status # Check what changed\ngit add \u003cfiles> # Stage code changes\nbd sync # Commit beads changes\ngit commit -m \"...\" # Commit code\nbd sync # Commit any new beads changes\ngit push # Push to remote\n```\n\n### After\n```bash\ngit status # Check what changed\ngit add \u003cfiles> # Stage code changes\nbr sync --flush-only # Export beads to JSONL (no git ops)\ngit add .beads/ # Stage beads changes\ngit commit -m \"...\" # Commit everything\ngit push # Push to remote\n```\n\n---\n\n## Landing the Plane\n\n### Before\n```bash\ngit pull --rebase\nbd sync\ngit push\ngit status # MUST show \"up to date with origin\"\n```\n\n### After\n```bash\ngit pull --rebase\nbr sync --flush-only # Export beads to JSONL (no git ops)\ngit add .beads/ # Stage beads changes\ngit commit -m \"sync beads\" # Commit beads\ngit push\ngit status # MUST show \"up to date with origin\"\n```\n\n---\n\n## Agent Mail Integration\n\n### Thread ID Convention\n\n**Before:**\n```markdown\n- Mail `thread_id`: `bd-###`\n- Mail subject: `[bd-###] ...`\n- File reservation `reason`: `bd-###`\n- Commit messages: Include `bd-###` for traceability\n```\n\n**After:**\n```markdown\n- Mail `thread_id`: `br-###`\n- Mail subject: `[br-###] ...`\n- File reservation `reason`: `br-###`\n- Commit messages: Include `br-###` for traceability\n```\n\n### Typical Agent Flow\n\n**Before:**\n```markdown\n1. **Pick ready work (Beads):**\n ```bash\n bd ready --json\n ```\n\n2. **Reserve edit surface (Mail):**\n ```\n file_reservation_paths(..., reason=\"bd-123\")\n ```\n\n3. **Announce start (Mail):**\n ```\n send_message(..., thread_id=\"bd-123\", subject=\"[bd-123] Start: \u003ctitle>\")\n ```\n```\n\n**After:**\n```markdown\n1. **Pick ready work (Beads):**\n ```bash\n br ready --json\n ```\n\n2. **Reserve edit surface (Mail):**\n ```\n file_reservation_paths(..., reason=\"br-123\")\n ```\n\n3. **Announce start (Mail):**\n ```\n send_message(..., thread_id=\"br-123\", subject=\"[br-123] Start: \u003ctitle>\")\n ```\n```\n\n---\n\n## Full File Example\n\n### Before (Complete Section)\n\n```markdown\n## Issue Tracking with bd (beads)\n\nAll issue tracking goes through **bd**. No other TODO systems.\n\nKey invariants:\n- `.beads/` is authoritative state and **must always be committed** with code changes.\n- Do not edit `.beads/*.jsonl` directly; only via `bd`.\n\n### Basics\n\nCheck ready work:\n```bash\nbd ready --json\n```\n\n### Essential Commands\n\n```bash\nbd ready # Show issues ready to work\nbd list --status=open # All open issues\nbd create --title=\"...\" --type=task --priority=2\nbd update \u003cid> --status=in_progress\nbd close \u003cid> --reason=\"Completed\"\nbd sync # Commit and push changes\n```\n\n### Session End Checklist\n\n```bash\ngit status\ngit add \u003cfiles>\nbd sync\ngit commit -m \"...\"\ngit push\n```\n```\n\n### After (Complete Section)\n\n```markdown\n## Issue Tracking with br (beads_rust)\n\nAll issue tracking goes through **br** (beads_rust). No other TODO systems.\n\n**Note:** `br` is non-invasive and never executes git commands. After `br sync --flush-only`, you must manually run `git add .beads/ && git commit`.\n\nKey invariants:\n- `.beads/` is authoritative state and **must always be committed** with code changes.\n- Do not edit `.beads/*.jsonl` directly; only via `br`.\n\n### Basics\n\nCheck ready work:\n```bash\nbr ready --json\n```\n\n### Essential Commands\n\n```bash\nbr ready # Show issues ready to work\nbr list --status=open # All open issues\nbr create --title=\"...\" --type=task --priority=2\nbr update \u003cid> --status=in_progress\nbr close \u003cid> --reason=\"Completed\"\nbr sync --flush-only # Export to JSONL (no git ops)\n```\n\n### Session End Checklist\n\n```bash\ngit status\ngit add \u003cfiles>\nbr sync --flush-only\ngit add .beads/\ngit commit -m \"...\"\ngit push\n```\n```\n\n---\n\n## Quick Search\n\n```bash\n# Find specific transform patterns\ngrep -i \"session\" references/TRANSFORMS.md\ngrep -i \"landing\" references/TRANSFORMS.md\ngrep -i \"agent mail\" references/TRANSFORMS.md\n```\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":6883,"content_sha256":"dbef4999a34312232fe18baffaacf81608067779234f5c4a46bc9b73e6bb7338"},{"filename":"scripts/find-bd-refs.sh","content":"#!/usr/bin/env bash\n# Find files containing bd (beads) references that need migration to br\n# Usage: ./find-bd-refs.sh [path]\n#\n# Exit codes:\n# 0 - No bd references found (migration complete)\n# 1 - bd references found (migration needed)\n\nset -euo pipefail\n\npath=\"${1:-.}\"\n\necho \"=== bd → br Migration Discovery ===\"\necho \"Scanning: $path\"\necho \"\"\n\n# Find files with bd command references\nbd_files=$(grep -rl '`bd ' \"$path\" --include=\"*.md\" 2>/dev/null || true)\nif [[ -n \"$bd_files\" ]]; then\n echo \"=== Files with \\`bd\\` command references ===\"\n echo \"$bd_files\"\n echo \"\"\nfi\n\n# Find files with bd sync specifically\nsync_files=$(grep -rl 'bd sync' \"$path\" --include=\"*.md\" 2>/dev/null || true)\nif [[ -n \"$sync_files\" ]]; then\n echo \"=== Files with bd sync (critical to migrate) ===\"\n echo \"$sync_files\"\n echo \"\"\nfi\n\n# Find files with bd-### issue IDs\nid_files=$(grep -rl 'bd-[0-9]' \"$path\" --include=\"*.md\" 2>/dev/null || true)\nif [[ -n \"$id_files\" ]]; then\n echo \"=== Files with bd-### issue IDs ===\"\n echo \"$id_files\"\n echo \"\"\nfi\n\n# Count summary\nbd_count=$(echo \"$bd_files\" | grep -c . 2>/dev/null || echo \"0\")\nsync_count=$(echo \"$sync_files\" | grep -c . 2>/dev/null || echo \"0\")\nid_count=$(echo \"$id_files\" | grep -c . 2>/dev/null || echo \"0\")\n\necho \"=== Summary ===\"\necho \"Files with bd commands: $bd_count\"\necho \"Files with bd sync: $sync_count\"\necho \"Files with bd-### IDs: $id_count\"\n\n# Unique files needing migration\nall_files=$(echo -e \"$bd_files\\n$sync_files\\n$id_files\" | grep -v '^

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

| sort -u || true)\ntotal=$(echo \"$all_files\" | grep -c . 2>/dev/null || echo \"0\")\necho \"\"\necho \"Total unique files needing migration: $total\"\n\nif [[ \"$total\" -gt 0 ]]; then\n echo \"\"\n echo \"=== Migration Recommendation ===\"\n if [[ \"$total\" -le 5 ]]; then\n echo \"Strategy: Sequential (1-5 files)\"\n echo \"Run: Apply THE EXACT PROMPT to each file\"\n elif [[ \"$total\" -le 15 ]]; then\n echo \"Strategy: 2 parallel subagents (~$((total/2)) files each)\"\n elif [[ \"$total\" -le 50 ]]; then\n echo \"Strategy: 5 parallel subagents (~$((total/5)) files each)\"\n else\n echo \"Strategy: 8 parallel subagents (~$((total/8)) files each)\"\n fi\n exit 1\nelse\n echo \"\"\n echo \"✓ No bd references found. Migration complete!\"\n exit 0\nfi\n","content_type":"application/x-sh; charset=utf-8","language":"bash","size":2305,"content_sha256":"6b8b741a0ec3408e50b7888edbca865394b8e4a56a7a5a8f763fc3c3705362b2"},{"filename":"scripts/verify-migration.sh","content":"#!/usr/bin/env bash\n# Verify bd → br migration is complete for a file\n# Usage: ./verify-migration.sh \u003cfile.md>\n#\n# Exit codes:\n# 0 - Migration verified complete\n# 1 - File not found or argument error\n# 2 - Migration incomplete (blocked)\n\nset -euo pipefail\n\nfile=\"${1:?Usage: verify-migration.sh \u003cfile.md>}\"\n\nif [[ ! -f \"$file\" ]]; then\n echo \"ERROR: File not found: $file\"\n exit 1\nfi\n\necho \"=== Migration Verification: $file ===\"\necho \"\"\n\nerrors=0\nwarnings=0\n\n# === MUST BE 0 ===\n\necho \"Checking for remaining bd references (must be 0)...\"\n\n# Check for bd command references\nbd_refs=$(grep -c '`bd ' \"$file\" 2>/dev/null || echo \"0\")\nif [[ \"$bd_refs\" -gt 0 ]]; then\n echo \" ✗ FAIL: Found $bd_refs \\`bd\\` command references\"\n grep -n '`bd ' \"$file\" | head -3 | sed 's/^/ /'\n errors=$((errors + 1))\nelse\n echo \" ✓ PASS: No \\`bd\\` command references\"\nfi\n\n# Check for bd sync specifically\nbd_sync=$(grep -c 'bd sync' \"$file\" 2>/dev/null || echo \"0\")\nif [[ \"$bd_sync\" -gt 0 ]]; then\n echo \" ✗ FAIL: Found $bd_sync 'bd sync' references\"\n grep -n 'bd sync' \"$file\" | head -3 | sed 's/^/ /'\n errors=$((errors + 1))\nelse\n echo \" ✓ PASS: No 'bd sync' references\"\nfi\n\n# Check for bd-### issue IDs\nbd_ids=$(grep -c 'bd-[0-9]' \"$file\" 2>/dev/null || echo \"0\")\nif [[ \"$bd_ids\" -gt 0 ]]; then\n echo \" ✗ FAIL: Found $bd_ids 'bd-###' issue ID references\"\n grep -n 'bd-[0-9]' \"$file\" | head -3 | sed 's/^/ /'\n errors=$((errors + 1))\nelse\n echo \" ✓ PASS: No 'bd-###' issue IDs\"\nfi\n\n# Check for daemon references (should be removed)\ndaemon_refs=$(grep -ci 'daemon' \"$file\" 2>/dev/null || echo \"0\")\nif [[ \"$daemon_refs\" -gt 0 ]]; then\n echo \" ⚠ WARN: Found $daemon_refs daemon references (br has no daemon)\"\n warnings=$((warnings + 1))\nfi\n\necho \"\"\n\n# === Check if file has beads content ===\n\nhas_beads=$(grep -c 'beads\\|\\.beads\\|br ready\\|br sync' \"$file\" 2>/dev/null || echo \"0\")\n\nif [[ \"$has_beads\" -gt 0 ]]; then\n echo \"Checking for required br patterns (file has beads content)...\"\n\n # Check for br sync --flush-only\n br_sync=$(grep -c 'br sync --flush-only' \"$file\" 2>/dev/null || echo \"0\")\n if [[ \"$br_sync\" -eq 0 ]]; then\n echo \" ⚠ WARN: No 'br sync --flush-only' found (expected if file has sync sections)\"\n warnings=$((warnings + 1))\n else\n echo \" ✓ PASS: Found $br_sync 'br sync --flush-only' references\"\n fi\n\n # Check for git add .beads/\n git_add=$(grep -c 'git add .beads/' \"$file\" 2>/dev/null || echo \"0\")\n if [[ \"$git_add\" -eq 0 && \"$br_sync\" -gt 0 ]]; then\n echo \" ⚠ WARN: No 'git add .beads/' found (required after br sync)\"\n warnings=$((warnings + 1))\n elif [[ \"$git_add\" -gt 0 ]]; then\n echo \" ✓ PASS: Found $git_add 'git add .beads/' references\"\n fi\n\n # Check for non-invasive note\n note=$(grep -c 'non-invasive' \"$file\" 2>/dev/null || echo \"0\")\n if [[ \"$note\" -eq 0 ]]; then\n echo \" ⚠ WARN: No non-invasive note found\"\n warnings=$((warnings + 1))\n else\n echo \" ✓ PASS: Non-invasive note present\"\n fi\nelse\n echo \"Note: File does not appear to have beads content (skipping br pattern checks)\"\nfi\n\n# === Summary ===\n\necho \"\"\necho \"=== Summary ===\"\nif [[ \"$errors\" -eq 0 ]]; then\n if [[ \"$warnings\" -gt 0 ]]; then\n echo \"PASS with $warnings warning(s)\"\n echo \"Review warnings above - may need attention\"\n exit 0\n else\n echo \"✓ PASS: Migration verified complete\"\n exit 0\n fi\nelse\n echo \"✗ FAIL: $errors error(s), $warnings warning(s)\"\n echo \"\"\n echo \"Fix the errors above and re-run verification\"\n exit 2\nfi\n","content_type":"application/x-sh; charset=utf-8","language":"bash","size":3679,"content_sha256":"cb28fd1ab29ef8f271b12bc325c0e3de1c23716d37b67e7d549ad1e048b5dc2e"},{"filename":"SELF-TEST.md","content":"# Self-Test: bd-to-br-migration\n\n## Trigger Phrases\n\nThese should activate this skill:\n\n| Phrase | Expected |\n|--------|----------|\n| \"migrate from bd to br\" | Activates |\n| \"convert bd commands to br\" | Activates |\n| \"update AGENTS.md from beads to beads_rust\" | Activates |\n| \"bd sync to br sync\" | Activates |\n| \"beads migration\" | Activates |\n| \"fix bd references\" | Activates |\n\n## Quick Validation\n\n```bash\n# Skill structure exists\nls -la .claude/skills/bd-to-br-migration/\n\n# Scripts are executable\nls -la .claude/skills/bd-to-br-migration/scripts/\n\n# References exist\nls -la .claude/skills/bd-to-br-migration/references/\n\n# Subagent exists\nls -la .claude/skills/bd-to-br-migration/subagents/\n```\n\n## Functional Tests\n\n### Test 1: Discovery Script\n\n```bash\n# Run discovery (should report file counts)\n.claude/skills/bd-to-br-migration/scripts/find-bd-refs.sh /data/projects/test-project/\n```\n\nExpected: Lists files with bd refs, provides migration strategy recommendation.\n\n### Test 2: Verification Script\n\n```bash\n# Create test file\ncat > /tmp/test-migration.md \u003c\u003c 'EOF'\n## Issue Tracking with br (beads_rust)\n\n**Note:** `br` is non-invasive and never executes git commands.\n\n```bash\nbr ready\nbr sync --flush-only\ngit add .beads/\ngit commit -m \"sync\"\n```\nEOF\n\n# Should pass\n.claude/skills/bd-to-br-migration/scripts/verify-migration.sh /tmp/test-migration.md\necho \"Exit code: $?\" # Should be 0\n```\n\n### Test 3: Verification Failure\n\n```bash\n# Create file with bd refs (should fail)\ncat > /tmp/test-bd.md \u003c\u003c 'EOF'\n## Issue Tracking with bd (beads)\n\n```bash\nbd ready\nbd sync\n```\nEOF\n\n# Should fail\n.claude/skills/bd-to-br-migration/scripts/verify-migration.sh /tmp/test-bd.md\necho \"Exit code: $?\" # Should be 2\n```\n\n## Integration Tests\n\n### Test 4: Single File Migration\n\n1. Ask: \"Migrate this file from bd to br: /tmp/test-bd.md\"\n2. Expected:\n - Skill activates\n - Transforms applied in order\n - Verification runs\n - File passes verification\n\n### Test 5: Bulk Migration\n\n1. Ask: \"How do I migrate 50 AGENTS.md files from bd to br?\"\n2. Expected:\n - Skill activates\n - References decision tree\n - Recommends 5 parallel subagents\n - Provides THE EXACT PROMPT for batch migration\n\n## Content Verification\n\n### THE EXACT PROMPT exists and includes:\n- [ ] Ordered transforms (1-7)\n- [ ] Remove list (daemon, hooks, RPC)\n- [ ] Keep list (SQLite, bv, priorities)\n- [ ] Verification commands\n\n### Decision Tree exists for:\n- [ ] Single file\n- [ ] Multiple files (\u003c10)\n- [ ] Bulk (10+)\n\n### Transform Patterns include:\n- [ ] Non-invasive note\n- [ ] Sync command transform\n- [ ] Session end transform\n- [ ] Issue ID transform\n\n### References complete:\n- [ ] TRANSFORMS.md - Full before/after examples\n- [ ] BULK.md - Subagent prompts\n- [ ] PITFALLS.md - Common mistakes\n\n## Cleanup\n\n```bash\nrm -f /tmp/test-migration.md /tmp/test-bd.md\n```\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":2855,"content_sha256":"242efe01ebf6b922b7874d9548791e0358a456fee54dbbc36fb26cff541e4c2b"},{"filename":"subagents/batch-migrator.md","content":"---\nname: bd-br-batch-migrator\ndescription: Migrate batch of AGENTS.md files from bd to br\ntools: Read, Edit, Bash\npermissionMode: acceptEdits\n---\n\n# Batch Migration Subagent\n\nYou are a specialized migration agent. Your ONLY job: migrate files from bd (beads) to br (beads_rust).\n\n## Your Mission\n\nMigrate the files listed in the prompt from bd to br following the exact transform rules.\n\n## Transform Rules (Apply IN ORDER)\n\n1. **Section headers**: \"bd (beads)\" → \"br (beads_rust)\"\n\n2. **Add non-invasive note** after beads section header:\n ```markdown\n **Note:** `br` is non-invasive and never executes git commands. After `br sync --flush-only`, you must manually run `git add .beads/ && git commit`.\n ```\n\n3. **Commands**: `bd X` → `br X` for:\n - ready, list, show, create, update, close, dep, stats\n\n4. **Sync command**: `bd sync` → `br sync --flush-only`\n\n5. **Add git steps** after EVERY sync command:\n ```bash\n git add .beads/\n git commit -m \"sync beads\"\n ```\n\n6. **Issue IDs**: `bd-###` → `br-###` in:\n - thread_ids\n - subjects\n - reasons\n - commit messages\n\n7. **Links**: `beads_viewer` → `beads_rust`\n\n## Removal Rules\n\nDELETE completely (not transform):\n- Daemon references\n- Auto-commit assumptions\n- Hook installation mentions\n- RPC mode references\n\n## Verification\n\nAfter EACH file, verify:\n```bash\ngrep -c '`bd ' FILE # Must be 0\ngrep -c 'bd sync' FILE # Must be 0\n```\n\nIf verification fails, DO NOT proceed. Fix the file first.\n\n## Reporting\n\nAfter each file, report:\n```\n✓ /path/file.md - migrated\n```\n\nOr if failed:\n```\n✗ /path/file.md - FAILED: [specific reason]\n```\n\n## Constraints\n\n- **One file at a time** — Complete and verify before moving to next\n- **No creative interpretation** — This is mechanical transformation\n- **No improvements** — Don't \"improve\" code you're migrating\n- **Exact transforms only** — Apply rules literally\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":1907,"content_sha256":"e50e6d5e60ac6158842fd85c0ec41cddcef127b3123920cde42c0c8531170985"}],"content_json":{"type":"doc","content":[{"type":"paragraph","content":[{"text":"\u003c!-- TOC: Philosophy | THE EXACT PROMPT | Decision Tree | Command Map | Transform Patterns | Validation Loop | Risk Tiers | References -->","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"bd → br Migration","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"Core Philosophy:","type":"text","marks":[{"type":"strong"}]},{"text":" One behavioral change, mechanical transforms. The ONLY difference is git handling—everything else is find-replace.","type":"text"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Why This Matters","type":"text"}]},{"type":"paragraph","content":[{"text":"Incomplete migrations leave broken docs. Agents follow stale ","type":"text"},{"text":"bd sync","type":"text","marks":[{"type":"code_inline"}]},{"text":" instructions, expect auto-commit, and lose work. This skill ensures ","type":"text"},{"text":"complete, verified migrations","type":"text","marks":[{"type":"strong"}]},{"text":".","type":"text"}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"THE EXACT PROMPT — Single File Migration","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"Migrate this file from bd (beads) to br (beads_rust).\n\nApply transforms IN THIS ORDER (order matters):\n1. Section headers: \"bd (beads)\" → \"br (beads_rust)\"\n2. Add non-invasive note after beads section header\n3. Commands: `bd X` → `br X` for ready/list/show/create/update/close/dep/stats\n4. Sync command: `bd sync` → `br sync --flush-only`\n5. Add git steps after EVERY sync:\n git add .beads/\n git commit -m \"sync beads\"\n6. Issue IDs: bd-### → br-### in thread_ids, subjects, reasons, commits\n7. Links: beads_viewer → beads_rust (if present)\n\nRemove completely:\n- Daemon references\n- Auto-commit assumptions\n- Hook installation mentions\n- RPC mode\n\nKeep unchanged:\n- SQLite/WAL cautions\n- bv integration\n- Priority system (P0-P4)\n\nVERIFY after editing:\ngrep -c '`bd ' file.md # Must be 0\ngrep -c 'bd sync' file.md # Must be 0\ngrep -c 'br sync --flush-only' file.md # Must be > 0","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Why This Prompt Works","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Ordered transforms","type":"text","marks":[{"type":"strong"}]},{"text":": Dependencies exist (sync must change before adding git steps)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Explicit removals","type":"text","marks":[{"type":"strong"}]},{"text":": Daemon/RPC don't exist in br—leaving them confuses agents","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Keep list","type":"text","marks":[{"type":"strong"}]},{"text":": Prevents accidental removal of still-valid patterns","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Built-in verification","type":"text","marks":[{"type":"strong"}]},{"text":": Grep commands catch missed transforms","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"No degrees of freedom","type":"text","marks":[{"type":"strong"}]},{"text":": This is a LOW freedom task—exact transforms required","type":"text"}]}]}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Decision Tree: What Are You Migrating?","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"What are you migrating?\n│\n├─ Single file (AGENTS.md)\n│ │\n│ └─ Follow THE EXACT PROMPT above\n│ Use: ./scripts/verify-migration.sh file.md\n│\n├─ Multiple files (batch)\n│ │\n│ ├─ \u003c10 files → Sequential: apply prompt to each\n│ │\n│ └─ 10+ files → Parallel subagents\n│ Batch ~10 files per agent\n│ See: [BULK.md](references/BULK.md)\n│\n└─ Verify existing migration\n │\n └─ Run: ./scripts/find-bd-refs.sh /path\n Any output = incomplete migration","type":"text"}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"The One Behavioral Difference","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"┌─────────────────────────────────────────────────────────────────┐\n│ bd (Go) br (Rust) │\n├─────────────────────────────────────────────────────────────────┤\n│ bd sync → br sync --flush-only │\n│ (auto-commits to git) (exports JSONL only) │\n│ │\n│ + git add .beads/ │\n│ + git commit -m \"...\" │\n└─────────────────────────────────────────────────────────────────┘\n\nEverything else is literally s/bd/br/g","type":"text"}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Command Map","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"bd","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"br","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Change Type","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"bd ready","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"br ready","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Name only","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"bd list","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"br list","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Name only","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"bd show \u003cid>","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"br show \u003cid>","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Name only","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"bd create","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"br create","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Name only","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"bd update","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"br update","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Name only","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"bd close","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"br close","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Name only","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"bd dep add","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"br dep add","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Name only","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"bd stats","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"br stats","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Name only","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"bd sync","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"br sync --flush-only","type":"text","marks":[{"type":"code_inline"}]},{"text":" + git","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"BEHAVIORAL","type":"text","marks":[{"type":"strong"}]}]}]}]}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Transform Patterns","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Pattern 1: The Non-Invasive Note","type":"text"}]},{"type":"paragraph","content":[{"text":"Add immediately after any beads section header:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"markdown"},"content":[{"text":"**Note:** `br` is non-invasive and never executes git commands. After `br sync --flush-only`, you must manually run `git add .beads/ && git commit`.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Pattern 2: Sync Command Transform","type":"text"}]},{"type":"paragraph","content":[{"text":"Before:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"bd sync","type":"text"}]},{"type":"paragraph","content":[{"text":"After:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"br sync --flush-only\ngit add .beads/\ngit commit -m \"sync beads\"","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Pattern 3: Session End Transform","type":"text"}]},{"type":"paragraph","content":[{"text":"Before:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"git add \u003cfiles>\nbd sync\ngit push","type":"text"}]},{"type":"paragraph","content":[{"text":"After:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"git add \u003cfiles>\nbr sync --flush-only\ngit add .beads/\ngit commit -m \"...\"\ngit push","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Pattern 4: Issue ID Transform","type":"text"}]},{"type":"paragraph","content":[{"text":"Before:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"markdown"},"content":[{"text":"thread_id: bd-123\nsubject: [bd-123] Feature implementation\nreason: bd-123","type":"text"}]},{"type":"paragraph","content":[{"text":"After:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"markdown"},"content":[{"text":"thread_id: br-123\nsubject: [br-123] Feature implementation\nreason: br-123","type":"text"}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Validation Loop","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"┌─────────────────────────────────────────────────────────────────┐\n│ VALIDATION IS MANDATORY │\n├─────────────────────────────────────────────────────────────────┤\n│ │\n│ 1. Apply transforms │\n│ ↓ │\n│ 2. Run verification: │\n│ ./scripts/verify-migration.sh file.md │\n│ ↓ │\n│ 3. If FAIL → read error → fix specific issue → goto 2 │\n│ ↓ │\n│ 4. Only proceed when PASS │\n│ │\n│ ⚠️ Never skip verification. Incomplete migrations break agents.│\n└─────────────────────────────────────────────────────────────────┘","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Quick Verification Commands","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# MUST return 0:\ngrep -c '`bd ' file.md\ngrep -c 'bd sync' file.md\ngrep -c 'bd ready' file.md\n\n# MUST return > 0 (if file has sync sections):\ngrep -c 'br sync --flush-only' file.md\ngrep -c 'git add .beads/' file.md","type":"text"}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Risk Tiers","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Operation","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Risk","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Freedom","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Command renames (","type":"text"},{"text":"bd","type":"text","marks":[{"type":"code_inline"}]},{"text":" → ","type":"text"},{"text":"br","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Low","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Mechanical—no judgment","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Sync transform + git steps","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Medium","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"MUST add git steps","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Removing daemon refs","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Medium","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Verify not removing valid content","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Bulk migration (10+ files)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"High","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Use subagents with verification","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Degrees of Freedom: LOW","type":"text"}]},{"type":"paragraph","content":[{"text":"This is a ","type":"text"},{"text":"deterministic transformation","type":"text","marks":[{"type":"strong"}]},{"text":". There is ONE correct output for each input.","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"No creative interpretation","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"No optional improvements","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"No stylistic choices","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Apply transforms EXACTLY as specified","type":"text"}]}]}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"What Gets Removed","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Pattern","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Why Remove","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Verify Absent","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"\"bd daemon\"","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"br has no daemon","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"grep -i daemon","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"\"auto-commits\"","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"br never commits","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"grep -i \"auto.*commit\"","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"\"git hooks\"","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"br installs none","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"grep -i \"hook\"","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"\"RPC mode\"","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"br has no RPC","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"grep -i \"rpc\"","type":"text","marks":[{"type":"code_inline"}]}]}]}]}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"What Stays Unchanged","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Pattern","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Why Keep","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"SQLite/WAL cautions","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"br still uses WAL","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"bv integration","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Works with both","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Priority P0-P4","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Same system","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Issue types","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Same system","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Dependency tracking","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Same system","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":".beads/","type":"text","marks":[{"type":"code_inline"}]},{"text":" as source of truth","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Same system","type":"text"}]}]}]}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Before/After Example","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Before (bd)","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"markdown"},"content":[{"text":"## Issue Tracking with bd (beads)\n\nKey invariants:\n- `.beads/` is authoritative\n\n### Agent workflow:\n1. `bd ready` to find work\n2. `bd update \u003cid> --status in_progress`\n3. Implement\n4. `bd close \u003cid>`\n5. `bd sync` commits changes","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"After (br)","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"markdown"},"content":[{"text":"## Issue Tracking with br (beads_rust)\n\n**Note:** `br` is non-invasive and never executes git commands. After `br sync --flush-only`, you must manually run `git add .beads/ && git commit`.\n\nKey invariants:\n- `.beads/` is authoritative\n\n### Agent workflow:\n1. `br ready` to find work\n2. `br update \u003cid> --status in_progress`\n3. Implement\n4. `br close \u003cid>`\n5. Sync and commit:\n ```bash\n br sync --flush-only\n git add .beads/\n git commit -m \"sync beads\"","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"\n---\n\n## References\n\n| Need | Reference |\n|------|-----------|\n| Complete before/after examples | [TRANSFORMS.md](references/TRANSFORMS.md) |\n| Bulk migration strategy | [BULK.md](references/BULK.md) |\n| Common mistakes & fixes | [PITFALLS.md](references/PITFALLS.md) |\n\n---\n\n## Scripts\n\n| Script | Purpose |\n|--------|---------|\n| `./scripts/find-bd-refs.sh /path` | Find files needing migration |\n| `./scripts/verify-migration.sh file.md` | Verify migration complete |\n\n---\n\n## Validation\n\n```bash\n# Full verification\n./scripts/verify-migration.sh /path/to/AGENTS.md\n\n# Quick check (should return nothing)\ngrep '`bd ' /path/to/AGENTS.md","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"If any bd references remain → migration incomplete → re-apply transforms.","type":"text"}]}]},"metadata":{"date":"2026-06-05","name":"bd-to-br-migration","author":"@skillopedia","source":{"stars":44,"repo_name":"claude-skills","origin_url":"https://github.com/ratacat/claude-skills/blob/HEAD/skills/bd-to-br-migration/SKILL.md","repo_owner":"ratacat","body_sha256":"d6f35935bc20b5963cdcacc291537859fc4483458ed4a7890b39461653baf8de","cluster_key":"6a38851ad2b064bdfb43093e5913f387572aa7fbe9bd9913ab8f763eedee04fa","clean_bundle":{"format":"clean-skill-bundle-v1","source":"ratacat/claude-skills/skills/bd-to-br-migration/SKILL.md","attachments":[{"id":"b5c4f4a9-279f-554c-b5ab-0440dacdf23e","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/b5c4f4a9-279f-554c-b5ab-0440dacdf23e/attachment.md","path":"SELF-TEST.md","size":2855,"sha256":"242efe01ebf6b922b7874d9548791e0358a456fee54dbbc36fb26cff541e4c2b","contentType":"text/markdown; charset=utf-8"},{"id":"93fd1b16-f79b-57b1-9b55-818650e0a82a","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/93fd1b16-f79b-57b1-9b55-818650e0a82a/attachment.md","path":"references/BULK.md","size":5559,"sha256":"fd13bb2dea21381658e4fc644ebff302e9d24eb284cc2ee42e501390caa5d9fa","contentType":"text/markdown; charset=utf-8"},{"id":"7fea787d-ca46-5347-92c0-c2b10e92ba5e","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/7fea787d-ca46-5347-92c0-c2b10e92ba5e/attachment.md","path":"references/PITFALLS.md","size":5635,"sha256":"0fffeca4d4a33d56b284dc2956229e8f52a70ae1bd4a226b66ee3ad15f277823","contentType":"text/markdown; charset=utf-8"},{"id":"46cf822d-9c5f-5c37-8c5c-364e0eac6349","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/46cf822d-9c5f-5c37-8c5c-364e0eac6349/attachment.md","path":"references/TRANSFORMS.md","size":6883,"sha256":"dbef4999a34312232fe18baffaacf81608067779234f5c4a46bc9b73e6bb7338","contentType":"text/markdown; charset=utf-8"},{"id":"5355ece9-5bdd-5f74-bb70-2bd8b22f1732","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/5355ece9-5bdd-5f74-bb70-2bd8b22f1732/attachment.sh","path":"scripts/find-bd-refs.sh","size":2305,"sha256":"6b8b741a0ec3408e50b7888edbca865394b8e4a56a7a5a8f763fc3c3705362b2","contentType":"application/x-sh; charset=utf-8"},{"id":"6affed37-b3e4-5bc8-b667-e2f629eec8fb","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/6affed37-b3e4-5bc8-b667-e2f629eec8fb/attachment.sh","path":"scripts/verify-migration.sh","size":3679,"sha256":"cb28fd1ab29ef8f271b12bc325c0e3de1c23716d37b67e7d549ad1e048b5dc2e","contentType":"application/x-sh; charset=utf-8"},{"id":"76de652f-12d2-5be3-9fe1-58a51bb3311a","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/76de652f-12d2-5be3-9fe1-58a51bb3311a/attachment.md","path":"subagents/batch-migrator.md","size":1907,"sha256":"e50e6d5e60ac6158842fd85c0ec41cddcef127b3123920cde42c0c8531170985","contentType":"text/markdown; charset=utf-8"}],"bundle_sha256":"9b3a0ebc2f2081f39d3c3a4340be547f9595524cefdf49fd173f033c7f8f51f7","attachment_count":7,"text_attachments":7,"attachment_storage":"skillopedia-attachments-v1","binary_attachments":0,"excluded_attachments":[]},"cluster_size":1,"skill_md_path":"skills/bd-to-br-migration/SKILL.md","import_metadata":{"date":"2026-06-05","author":"@skillopedia","version":"v1","category":"software-engineering","category_label":"Engineering"},"exact_dupes_collapsed_into_this":0},"version":"v1","category":"software-engineering","import_tag":"clean-skills-v1","description":"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."}},"renderedAt":1782981261582}

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.