bd-to-br-migration

bd → br 迁移

核心理念： 一项行为变更，机械式转换。唯一的区别是 Git 处理方式——其他内容全部进行查找替换。

为什么这很重要

不完整的迁移会留下错误的文档。Agent 会遵循过时的 bd sync 指示，期待自动提交，最终丢失工作成果。这项技能可确保迁移完整且经过验证。

---

精确提示词 — 单文件迁移

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

为什么这个提示词有效

• 按顺序转换：转换之间存在依赖关系（必须先更改 sync，再添加 Git 步骤）
• 明确移除内容：br 不支持 Daemon/RPC——保留这些内容会让 Agent 困惑
• 保留清单：防止意外移除仍然有效的模式
• 内置验证：Grep 命令可捕获遗漏的转换
• 没有自由发挥的空间：这是一项低自由度任务——必须进行精确转换

---

决策树：你要迁移什么？

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

---

唯一的行为差异

┌─────────────────────────────────────────────────────────────────┐
│                    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

---

命令映射

bd	br	变更类型
bd ready	br ready	仅更改名称
bd list	br list	仅更改名称
bd show <id>	br show <id>	仅更改名称
bd create	br create	仅更改名称
bd update	br update	仅更改名称
bd close	br close	仅更改名称
bd dep add	br dep add	仅更改名称
bd stats	br stats	仅更改名称
bd sync	br sync --flush-only + git	行为变更

---

转换模式

模式 1：非侵入式说明

在任何 beads 部分标题后立即添加：

**Note:** `br` is non-invasive and never executes git commands. After `br sync --flush-only`, you must manually run `git add .beads/ && git commit`.

模式 2：Sync 命令转换

之前：

bd sync

之后：

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

模式 3：会话结束转换

之前：

git add <files>
bd sync
git push

之后：

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

模式 4：问题 ID 转换

之前：

thread_id: bd-123
subject: [bd-123] Feature implementation
reason: bd-123

之后：

thread_id: br-123
subject: [br-123] Feature implementation
reason: br-123

---

验证循环

┌─────────────────────────────────────────────────────────────────┐
│                     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.│
└─────────────────────────────────────────────────────────────────┘

快速验证命令

# 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

---

风险等级

操作	风险	自由度
命令重命名（bd → br）	低	机械式——无需判断
Sync 转换 + Git 步骤	中	必须添加 Git 步骤
移除 Daemon 引用	中	确认未移除有效内容
批量迁移（10 个以上文件）	高	使用子 Agent 并进行验证

自由度：低

这是一项确定性转换。每种输入都只有一种正确输出。

• 不进行创造性解读
• 不进行可选改进
• 不进行风格选择
• 严格按照指定内容应用转换

---

要移除的内容

模式	移除原因	确认不存在
"bd daemon"	br 没有 Daemon	grep -i daemon
"auto-commits"	br 从不提交	grep -i "auto.*commit"
"git hooks"	br 不会安装任何 Hook	grep -i "hook"
"RPC mode"	br 没有 RPC	grep -i "rpc"

---

保持不变的内容

模式	保留原因
SQLite/WAL 注意事项	br 仍使用 WAL
bv 集成	两者均可使用
优先级 P0-P4	系统相同
问题类型	系统相同
依赖关系跟踪	系统相同
作为事实来源的 .beads/	系统相同

---

转换前后示例

转换前（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

转换后（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

如果仍有 bd 引用 → 迁移未完成 → 重新应用转换。