beads

Beads - AI エージェント向け永続タスクメモリ

会話の圧縮後も保持される、グラフベースのイシュートラッカーです。

概要

bd と br (beads_rust) は、Markdown のタスクリストを、git に保存される依存関係を考慮したグラフに置き換えます。bv は、PageRank と媒介中心性を使ったグラフ対応のトリアージ機能を追加します。

主な違い：

• bd/br：複数セッションにわたる作業、依存関係、圧縮後も保持、git で管理
• bv：グラフ分析、優先度のトリアージ、ボトルネックの検出、並列実行の計画
• タスクツール（TaskCreate/TaskUpdate/TaskList）：単一セッションのタスク、ステータス管理、会話単位

判断基準：2 週間後に作業を再開する際、bd がないと難しい場合は、bd を使ってください。

br と bd の違い：br は Rust で書き直されたものです。コマンドは同じですが、br は自動コミットを行わない（git の操作は自分で行います）点と、bd sync が br sync --flush-only になる点が異なります。インストールされている方を使ってください。

bv の安全上の注意：裸の bv は絶対に実行しないでください。対話型 TUI が起動し、ターミナルがブロックされます。必ず --robot-* フラグを使ってください。

ここでコマンドの使い方を学び直す必要はありません。 bd --help / br --help（および各サブコマンドの --help）には、すべてのコマンドとフラグの説明があります。強制実行するコマンドを指定する前に実行してください。プリミティブを組み合わせ、独自のものを作らないでください（composition-over-invention.md）。完全なカタログは CLI_REFERENCE.md（bd）、BR_REFERENCE.md（br）、BV_TRIAGE.md（bv の robot フラグ）にあります。このスキルでは運用方針を説明します。

運用ルール

• 稼働中の bd の読み取り結果を信頼できる情報源として扱ってください。現在のトラッカーの状態を確認するには、bd show、bd ready、bd list、bd export を使ってください。稼働中の bd データを利用できる場合、.beads/issues.jsonl を主な判断材料として扱わないでください。
• CI、リリース、またはロールアウトの作業後に次の対応可能な作業を選ぶ前に、利用できる場合は ao reconcile --json を優先してください。重大度の高い main/release/bead のエビデンスに関する指摘が解決済み、または明示的に置き換えられた後に限り、bd ready を計画の入力として扱ってください。
• リポジトリで .beads/issues.jsonl を追跡しており、トラッカーの状態を変更した場合は、bd export -o .beads/issues.jsonl を明示的に実行して更新してください。.beads/issues.jsonl は git で扱いやすいエクスポート成果物として扱ってください。
• 子イシューをクローズする、または大幅に更新した後は、同じセッション内で未クローズの親イシューを照合してください。古くなった「残る課題」のメモはすぐに更新し、子イシューによって親の最後の実質的な課題が解決された場合は親をクローズしてください。
• 子イシューをクローズする前に、bd close --reason のテキストに対象を明確にしたクローズの根拠を含めてください。 変更したファイル、または明示的にファイルがないことを示すエビデンス成果物、検証コマンド、親イシューの照合結果を記載してください。子の bead のクローズ理由に「完了」や「実装済み」のような一般的な表現を使わないでください。
• bd ready が大まかな包括的イシューを返した場合、曖昧な親の記述をそのまま実装の対象にしないでください。まず残る課題を、実行可能な子イシューとして具体化し、その子イシューを完了してから親イシューを照合してください。
• キューに残っている古い項目は、黙って飛ばすのではなく、内容を整理してください。範囲が広すぎる、または一部がすでに取り込まれている bead は、実際に残っている課題に合わせて書き直してください。
• トラッカーの状態を変更した場合は、次の変更後の手順を実行してください。

bd ...                              # mutate tracker state
bd export -o .beads/issues.jsonl    # if tracked in git
bd vc status
bd dolt commit -m "..."             # if tracker changes are pending
bd dolt push                        # only if a Dolt remote is configured

セッション終了時の手順（br — sync は明示的に実行し、自動では行われません）：

git pull --rebase
br sync --flush-only                # DB → JSONL (reverse: --import-only after pull)
git add .beads/ && git commit -m "Update issues"
git push

前提条件

• bd CLI：バージョン 0.34.0 以降がインストールされ、PATH に含まれていること
• Git リポジトリ：現在のディレクトリが git リポジトリであること
• 初期化：bd init を一度実行していること（エージェントではなく、人間が実行します）

例

ユーザーの指示： /validate

このスキルは依存関係を通じて読み込まれます。エージェントは bd show <id> でイシューのメタデータを読み取り、検証結果を確認対象のイシューに関連付け、検証レポートでイシュー ID を引用します。手動で bd を検索する必要はありません。

ユーザーの指示： /implement ag-xyz-123

このスキルはイシューのライフサイクルを管理するために読み込まれます。本文を確認するには bd show ag-xyz-123 を実行し、依存関係を確認したうえで、完了後に対象を明確にしたクローズの根拠を添えて bd close ag-xyz-123 を実行します。

bv グラフトリアージ

bv を単独で実行してはいけません。必ず --robot-* フラグ（--robot-triage、--robot-next、--robot-plan、--robot-insights、--robot-priority、--robot-alerts。BV_TRIAGE.md の選択ガイドを参照）を使用してください。

主要な指標： PageRank = あらゆる要素が依存しています（最優先で修正）。Betweenness = ボトルネック（複数の経路をブロックします）。両方とも高い場合 = 重大なボトルネックです。ほかの作業をすべて止めて対処してください。

計画から Beads へのワークフロー

Markdown の計画を、依存関係を完全に設定した Beads に変換します。

1. 計画全体、AGENTS.md、README、リンク先の意図に関する issue、受け入れ条件を読みます。
2. 各 issue について br create で Beads を作成し、説明にコンテキストをすべて記載します。
3. 機能、バグ、またはプロダクトに関わる動作にはすべて、フェンス付きの gherkin ブロックを含めるか、記入済みの意図に関する issue へのリンクを記載します。機械的な作業については、受け入れ条件がコマンドまたはファイルのみに基づく場合に限り、Gherkin を省略できます。
4. 実質的な Beads には、docs/architecture/intent-to-loop-hexagon.md の hexagon: 境界ブロック（インバウンドポート、境界づけられたコンテキスト、アダプター、コンテキストパケット、完了状態）を含めます。
5. br dep add / bd dep add で依存関係を設定します。JSONL や データベースのファイルを直接編集してはいけません。
6. 定常状態になるまで、繰り返し仕上げます（通常 6〜9 回）。機能の欠落、過度な単純化、テスト不足、境界の不明確さ、e2e カバレッジの不足、ログの弱さを確認します。
7. 検証します。br dep cycles の出力が空であること、グラフの 健全性を bv --robot-insights で確認すること、最初の Bead を bv --robot-next で確認することが必要です。bv を単独で実行してはいけません。
8. コミット前に明示的に同期します。br sync --flush-only を実行し、その後 git add .beads/ を実行して、適切な場合はトラッカーの変更をコミットします。

Beads は、初めて作業するエージェントが元の計画を参照せずに実装できるほど詳細に記述してください。実装可能な Beads には、明確なスコープ、明示的な依存関係、BDD または機械的な受け入れ条件、ユニットテスト／e2e テストの期待事項、詳細なログの期待事項、名前の付いた完了状態が必要で、依存関係の循環があってはいけません。

トラブルシューティング

症状 → 修正の表（コマンドが見つからない、Git リポジトリではない、init がない、ID プレフィックスのエラー、bv がハングする、依存関係の循環、同期方向の混乱）：TROUBLESHOOTING.md。特に多いものは次の 2 つです。bv がハングする場合は robot フラグが省略されています。br sync の方向に迷った場合は、方向（--flush-only と --import-only）が指定されていません。

参考ドキュメント

• references/beads.feature — 実行可能な仕様：bd 必須のトラッカー、コードより先に作成、準備完了の検出、discovered-from リンク、ライブ読み取りを正とする（soc-qk4b）

• references/ANTI_PATTERNS.md

• references/BOUNDARIES.md

• references/composition-over-invention.md — 強制コマンドを指定する前に bd <subcmd> --help を実行してください。プリミティブを組み合わせ、独自に作り出さないでください

• references/BR_REFERENCE.md

• references/BV_TRIAGE.md

• references/CLI_REFERENCE.md

• references/DEPENDENCIES.md

• references/INTEGRATION_PATTERNS.md

• references/ISSUE_CREATION.md

• references/MIGRATION.md

• references/MOLECULES.md

• references/PATTERNS.md

• references/PLAN_TO_BEADS.md

• references/RESUMABILITY.md

• references/ROUTING.md

• references/STATIC_DATA.md

• references/tracker-migration-and-triage.md

• references/TROUBLESHOOTING.md

• references/WORKFLOWS.md