bd-to-br-migration

bd → br の移行

基本方針： 動作上の変更は 1 つ、変換は機械的に行います。違いは Git の処理だけです。それ以外はすべて検索と置換で対応できます。

なぜ重要なのか

不完全な移行では、ドキュメントが壊れたままになります。エージェントは古い 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

このプロンプトが機能する理由

• 順序どおりの変換：依存関係があります（Git の手順を追加する前に sync を変更する必要があります）
• 明示的な削除：br にはデーモン／RPC がないため、残しておくとエージェントを混乱させます
• 維持する項目の一覧：現在も有効なパターンを誤って削除するのを防ぎます
• 組み込みの検証：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：Issue 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 の手順を必ず追加
デーモンへの言及の削除	中	有効な内容を削除していないか確認
一括移行（10 ファイル以上）	高	検証を行いながらサブエージェントを使用

自由度：低

これは決定論的な変換です。各入力に対して、正しい出力は 1 つだけです。

• 創造的な解釈はしない
• 任意の改善は加えない
• 文体上の選択はしない
• 指定されたとおりに変換を厳密に適用する

---

削除するもの

パターン	削除する理由	削除を確認
"bd daemon"	br にはデーモンがありません	grep -i daemon
"auto-commits"	br はコミットしません	grep -i "auto.*commit"
"git hooks"	br は何もインストールしません	grep -i "hook"
"RPC mode"	br には RPC がありません	grep -i "rpc"

---

変更せずに残すもの

パターン	維持する理由
SQLite/WAL に関する注意	br も引き続き WAL を使用します
bv との統合	どちらでも動作します
優先度 P0-P4	同じシステムです
Issue の種類	同じシステムです
依存関係の追跡	同じシステムです
情報源としての .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 への参照が残っている場合 → 移行は未完了です → 変換を再適用してください。