br

br -- Beads Rust 課題トラッカー（公式スキル）

非侵襲的： br は git コマンドを決して実行しません。同期とコミットはご自身の責任で行ってください。

エージェント向けの重要なルール

ルール	理由
バイナリは br	bd は決して使わないでください（古い Go 版です）
必ず --json を使う	解析用の構造化出力です。トークンを節約する場合は --format toon を使ってください
裸の bv は実行しない	対話型 TUI モードでセッションをブロックします
同期は明示的に行う	br sync --flush-only は DB を JSONL にエクスポートするだけです
Git はご自身の作業です	br が操作するのは .beads/ のみです。git add .beads/ && git commit を実行してください
循環依存は禁止	br dep cycles の結果は空でなければなりません
実行時にアクターを解決する	ACTOR="${BR_ACTOR:-assistant}" を使い、--actor "$ACTOR" を渡してください

クイックワークフロー

ACTOR="${BR_ACTOR:-assistant}"

# 1. Find work
br ready --json

# 2. Claim it
br update --actor "$ACTOR" <id> --status in_progress

# 3. Do work...

# 4. Complete
br close --actor "$ACTOR" <id> --reason "Implemented X"

# 5. Sync to git (EXPLICIT!)
br sync --flush-only
git add .beads/ && git commit -m "feat: X (<id>)"

基本コマンド

課題のライフサイクル

ACTOR="${BR_ACTOR:-assistant}"

br init                                              # Initialize .beads/ workspace
br create --actor "$ACTOR" "Title" -p 1 -t task      # Create issue (priority 0-4)
br q --actor "$ACTOR" "Quick note"                   # Quick capture (ID only output)
br show <id> --json                                  # Show issue details
br update --actor "$ACTOR" <id> --status in_progress # Update status
br update --actor "$ACTOR" <id> --priority 0         # Change priority
br close --actor "$ACTOR" <id> --reason "Done"       # Close with reason
br close --actor "$ACTOR" <id1> <id2> --reason "..."  # Close multiple at once
br reopen --actor "$ACTOR" <id>                      # Reopen closed issue

作成オプション

br create --actor "$ACTOR" "Title" \
  --priority 1 \             # 0-4 scale (0=critical, 4=backlog)
  --type task \              # task, bug, feature, epic, question, docs
  --assignee "user@..." \    # Optional assignee
  --labels backend,auth \    # Comma-separated labels
  --description "..."        # Detailed description

更新オプション

br update --actor "$ACTOR" <id> \
  --title "New title" \
  --priority 0 \
  --status in_progress \     # open, in_progress, closed
  --assignee "new@..." \
  --add-label reliability \
  --parent <parent-id> \
  --claim                    # Shorthand for claim-and-start

一括更新（トリアージの一括処理）：

br update --actor "$ACTOR" <id1> <id2> <id3> --priority 2 --add-label triage-reviewed --json

クエリ（エージェントは常に --json を使用）

br ready --json                      # Actionable work (no blockers)
br list --json                       # All issues
br list --status open --sort priority --json  # Filter and sort
br list --priority 0-1 --json        # Filter by priority range
br list --assignee alice --json      # Filter by assignee
br blocked --json                    # Show blocked issues
br search "keyword" --json           # Full-text search
br show <id> --json                  # Issue details with dependencies
br stale --days 30 --json            # Stale issues
br count --by status --json          # Count with grouping

依存関係

br dep add <child> <parent>          # child depends on parent
br dep add <id> <depends-on> --type blocks  # Explicit block type
br dep remove <child> <parent>       # Remove dependency
br dep list <id> --json              # List dependencies for issue
br dep tree <id> --json              # Show dependency tree
br dep cycles --json                 # Find circular deps (MUST be empty!)

重要： br dep cycles の結果は空でなければなりません。循環依存は依存関係グラフを壊し、br ready の信頼性を損ないます。

ラベル

br label add <id> backend auth       # Add multiple labels
br label remove <id> urgent          # Remove label
br label list <id>                   # List issue's labels
br label list-all                    # All labels in project

コメント

ACTOR="${BR_ACTOR:-assistant}"
br comments add --actor "$ACTOR" <id> --message "Triage note" --json
br comments list <id> --json

同期（明示的に実行――自動ではありません）

br sync --flush-only                 # Export DB to JSONL (before git commit)
br sync --import-only                # Import JSONL to DB (after git pull)
br sync --status                     # Check sync status

変更後のワークフロー：

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

プル後のワークフロー：

git pull
br sync --import-only

システムと診断

br doctor                            # Full diagnostics
br stats --json                      # Project statistics
br config list                       # Show all configuration
br config get id.prefix              # Get specific value
br config set defaults.priority=1    # Set value
br where                             # Show workspace location
br version                           # Show version
br upgrade                           # Self-update (if enabled)
br lint --json                       # Lint issues for problems

優先度スケール

優先度	意味	単語ではなく数値を使う
0	重大	直ちに対応が必要
1	高	重要です。早めに対応してください
2	中（デフォルト）	通常の優先度
3	低	時間に余裕があるとき
4	バックログ	将来の検討事項

課題の種類

task、bug、feature、epic、question、docs

出力形式

フラグ	用途
--json	エージェント向けのデフォルト――完全な構造化データ
--format toon	コンテキストウィンドウに制約のあるエージェント向けの、トークン最適化された代替形式
（フラグなし）	色付きの、人が読みやすいターミナル出力

bv との連携

重要： 裸の bv は決して実行しないでください。対話型 TUI が起動し、処理がブロックされます。

# Always use --robot-* flags:
bv --robot-next                      # Single top pick + claim command
bv --robot-triage                    # Full triage with recommendations
bv --robot-plan                      # Parallel execution tracks
bv --robot-insights | jq '.Cycles'   # Check graph health (must be empty)
bv --robot-priority                  # Priority misalignment detection
bv --robot-alerts                    # Stale issues, blocking cascades

Agent Mail による調整

複数エージェント間の調整では、bead ID を thread_id として使用します。

概念	値
Mail thread_id	bd-###（課題 ID）
Mail subject	[bd-###] ...
ファイル予約 reason	bd-###
コミットメッセージ	追跡可能にするため bd-### を含める

# 1. Reserve files for bead
file_reservation_paths(..., reason="bd-123")

# 2. Announce work in thread
send_message(..., thread_id="bd-123", subject="[bd-123] Starting...")

# 3. Do work...

# 4. Close bead and release
br close bd-123 --reason "Completed"
release_file_reservations(...)

セッション終了時の手順

作業セッションを終了する前に、必ず次を行ってください。

git pull --rebase
br sync --flush-only
git add .beads/ && git commit -m "Update issues"
git push
git status  # MUST show "up to date with origin"

エージェントの標準ワークフロー（全体）

ACTOR="${BR_ACTOR:-assistant}"

# 1. Verify workspace
br where
br ready --json
br blocked --json
br list --status open --sort priority --json

# 2. Pick highest-priority ready work
br show <id> --json

# 3. Claim it
br update --actor "$ACTOR" <id> --status in_progress --claim

# 4. Do work...

# 5. Close with evidence
br close --actor "$ACTOR" <id> --reason "Implemented X in commit abc123"

# 6. Check queue impact
br ready --json
br blocked --json

# 7. Sync to git
br sync --flush-only
git add .beads/ && git commit -m "feat: X (<id>)"
git push

トリアージの判断マトリクス

各課題を、次のいずれか1つのカテゴリに分類してください。

分類	対応
implemented	証拠（コミット／PR／ファイル／動作）を示してクローズする
out-of-scope	明確な対象範囲外の理由を示してクローズする
needs-clarification	未回答の具体的な質問をコメントする
actionable	オープンのままにし、ステータス／優先度／ラベル／依存関係を適切に設定する

大規模なトリアージでは、数回更新するごとにチェックポイントを作成してください。

br ready --json
br blocked --json

アンチパターン

• --flush-only または --import-only を指定せずに br sync を実行する
• Git のコミット前に同期を忘れる
• 循環依存を作成する
• 裸の bv を実行する（セッションがブロックされます）
• 自動コミットされると思い込む（br は自動コミットを決して行いません）
• クローズ時の証拠を捏造する――確信がなければ、代わりにコメントしてください
• トリアージ中に無関係な課題を変更する
• 推測で依存関係を追加する

ストレージの構成

.beads/
  beads.db        # SQLite database (primary storage)
  beads.db-shm    # SQLite shared memory (WAL mode)
  beads.db-wal    # SQLite write-ahead log
  issues.jsonl    # JSONL export (for git)
  config.yaml     # Project configuration
  metadata.json   # Workspace metadata

トラブルシューティング

br doctor                    # Full diagnostics
br dep cycles                # Must be empty
br config list               # Check settings
which br                     # Verify br is installed

「データベースがロックされています」：pgrep -f "br " を使って、ほかの br プロセスがないか確認してください。

Worktree エラー（'main' is already checked out）：

git branch beads-sync main
br config set sync.branch beads-sync

詳細なデバッグ：

br -v list                   # Verbose
br -vv list                  # Debug
RUST_LOG=debug br list       # Detailed trace logs

References

Topic	File
Command cookbook	references/COMMANDS.md
Configuration details	references/CONFIG.md
Troubleshooting guide	references/TROUBLESHOOTING.md
Multi-agent integration	references/INTEGRATION.md