beadboard-driver

BeadBoard ドライバー

概要

このスキルは、BeadBoard をコントロールプレーンとして使用し、外部リポジトリでエージェントを実行するための運用手順書です。

基本原則：状態を明示すること＋割り当てを明示すること＋証拠を明示すること。

BeadBoard とは

BeadBoard は、bd を基盤とするエージェント作業のリアルタイムダッシュボードです。エージェントの稼働状況、状態遷移、スウォームの進捗、エージェント間のメールをライブ UI に表示します。人間は BeadBoard UI を使って状況を確認し、調整します。エージェントはこのスキルを使って、ダッシュボードの表示を更新するシグナル（ハートビート、状態遷移、メール）を送信します。

**エージェントが BeadBoard リポジトリ内で作業することはほとんどありません。**自分のプロジェクトリポジトリで作業します。bb と bd は PATH 上でグローバルに利用できます。このスキルで使用するスクリプト（事前確認、メールシムなど）は、このスキルのフォルダーに含まれています。エージェントのランタイムは、このスキルのインストール先を把握しており、そのパスを {baseDir}（この SKILL.md を含むディレクトリ）として提供します。

鉄則

No bead claims, handoffs, or completion statements without:
1) assignee set,
2) coordination checked,
3) evidence recorded.

要件

• bd がインストールされ、PATH 上で利用できること。
• bb または beadboard がグローバルにインストールされ、PATH 上で利用できること。
• 対象リポジトリのルートで作業すること。
• bd のインストール：npm install -g beads-cli
• bb のインストール：GitHub からクローンしてグローバルにインストールします。正確なコマンドはステップ 0 のセットアップを参照してください。

セッション手順書（手順を省略しないでください）

ステップ 0：project.md を読む — キャッシュ優先の判断

ls project.md 2>/dev/null && echo "EXISTS" || echo "MISSING"

**存在しない場合 → このプロジェクトで最初のエージェントです。**以下のセットアップチェックリストを実行してから、ここに戻ってください。

存在する場合 → project.md の先頭にある環境ステータスキャッシュの表を読みます。

• すべての行が pass → **ステップ 1 全体を省略し、ステップ 2 に進みます。**環境は検証済みです。
• fail または unknown の行がある → 該当する確認だけを実行し（ステップ 1 を参照）、問題を修正して project.md を更新し、続行します。

project.md はトークン予算です。すべて問題なければ、その内容を信頼してください。実際に問題がある項目だけ確認に時間を使ってください。

---

セットアップチェックリスト

{baseDir} は、この SKILL.md を含むディレクトリの絶対パスです。エージェントのランタイム（Claude Code、Codex など）によって自動的に挿入されます。ランタイムが自動置換に対応していない場合は、スキルのインストール先を見つけて、絶対パスを手動で指定してください。

project.md が存在しない場合に、順番に一度だけ実行します。

A. bd（beads-cli）を確認する

which bd 2>/dev/null || where bd 2>/dev/null

見つからない場合：

npm install -g beads-cli

B. beads データベースを初期化する（まだ存在しない場合）

ls .beads 2>/dev/null && echo "EXISTS — skip" || bd init

bd config コマンドを実行する前に必ず行ってください。.beads がすでに存在する場合は省略します。

C. bb（BeadBoard）を確認する

which bb 2>/dev/null || where bb 2>/dev/null

見つからない場合 — 調整に bb は必須です。ユーザーに確認してください。

「BeadBoard がインストールされていません。エージェントの調整に必要です。今すぐインストールしますか？リポジトリをクローンし、グローバルにインストールします。」

ユーザーが同意した場合：

git clone https://github.com/zenchantlive/beadboard.git ~/beadboard
cd ~/beadboard && npm install && npm install -g .

D. メールデリゲートを設定する

node {baseDir}/scripts/setup-mail-delegate.mjs

シムの絶対パスを自動的に解決し、bd config set mail.delegate を実行します。

E. セッションの事前確認を実行する

node {baseDir}/scripts/session-preflight.mjs

続行する前に必ず合格する必要があります。bd と bb を確認し、デリゲートが設定されていることを検証します。

F. project.md を作成する

cp {baseDir}/project.template.md ./project.md

環境ステータスキャッシュの表とプロジェクト ID セクションのすべての項目を記入します。検証済みの各行を、今日の日付とともに pass に設定します。これにより、次のエージェントが上記のすべてを再確認せずに済みます。

セッションログに追記します：

| YYYY-MM-DD | `<your-agent-bead-id>` | Initial project.md created, all checks pass |

---

ステップ 1：環境を確認する（project.md がすべて green の場合はスキップ）

project.md に fail または unknown の行がある場合のみ、このステップを実行してください。

失敗したチェックだけを実行します。

失敗した行	修正コマンド
PATH 上の bd	npm install -g beads-cli
PATH 上の bb	クローンして npm install -g . を実行（Bootstrap C を参照）
.beads データベース	bd init（Bootstrap B を参照）
mail.delegate	node {baseDir}/scripts/setup-mail-delegate.mjs
session-preflight	node {baseDir}/scripts/session-preflight.mjs — 報告された問題を修正

{baseDir} は、この SKILL.md が置かれているディレクトリです。エージェントのランタイムが自動的に置き換えます。

修正後、project.md の該当行を今日の日付とともに pass に更新します。

Windows ネイティブ環境または WSL2 で実行している場合は、プラットフォームに関する注意事項を参照してください。

ステップ 2：エージェントの Bead ID を作成してメールを確認する

bd create --title="Agent: bb-<role-name>" --description="<scope>" --type=task --priority=0 --label="gt:agent,role:<orchestrator|ui|graph|backend|infra>"

# Register in bb coordination system and set identity
bb agent register --name <role-name> --role <orchestrator|ui|graph|backend|infra>
export BB_AGENT=<role-name>

命名規則： bd の Bead 名は bb-<role-name>（例：bb-silver-scribe）にします。bb には同じ名前を <role-name>（例：silver-scribe）として登録します。BB_AGENT=<role-name> を設定します。これにより、両方の ID システムが連携します。bd agent state bb-silver-scribe ... は Bead ID を使い、bd mail send は BB_AGENT を自動的に使います。

用語	例	使用箇所
<role-name>	silver-scribe	bb agent register --name、BB_AGENT、bd mail --to
Bead のタイトル	bb-silver-scribe	bd create --title
<agent-bead-id>	beadboard-0m9	bd agent state、bd slot set、bd update --assignee
BB_AGENT の値	silver-scribe	export で設定。すべての bd mail 呼び出しに自動挿入されます

BB_AGENT を設定したので、メールスタック全体を確認します。

node {baseDir}/scripts/ensure-bb-mail-configured.mjs

期待される結果：対応する delegate と actor を含む ok: true。失敗した場合は、失敗時の対処を参照してください。

続行する前に受信トレイを確認します。

bd mail inbox

作業を引き受ける前に、保留中のメッセージをすべて読んで確認応答してください。未確認の HANDOFF メッセージまたは DECISION メッセージが、後続のタスクに影響する場合があります。

次に、ライフサイクルの状態を設定します。

bd agent state <agent-bead-id> spawning
bd agent state <agent-bead-id> running

ステップ 3：環境の変更を project.md に記録する

project.md はステップ 0 ですでに読み込んでいます。このセッション中に何か変更があった場合のみ、ここで更新します。新しいパッケージのインストール、delegate の再設定、新しいプラットフォーム固有の問題の発見などが該当します。変更がなければ、このステップは完全にスキップしてください。

ステップ 1 で fail または unknown の行を修正した場合は、その行を今日の日付とともに pass に更新します。

ステップ 4：重要なメモリとタスクのコンテキストを読む

# Select your primary domain first:
# memory-arch | memory-workflow | memory-agent | memory-ux | memory-reliability
bd query "label=memory AND label=mem-canonical AND label=<domain> AND status=closed" --sort updated --reverse
bd ready
bd show <target-bead-id>

タスクに合ったドメインを選んでください：memory-arch（アーキテクチャ上の決定）、memory-workflow（セッションプロトコル）、memory-agent（エージェントのセットアップ／ID）、memory-ux（UI／UX）、memory-reliability（エラー／復旧）。ドメインアンカーの ID は references/memory-system.md にあります。

bd ready は、ブロックされておらず、担当者も割り当てられていない、着手可能なすべてのタスクを一覧表示します。出力を確認し、bd show に渡す <target-bead-id> を選択してください。

最低限、タスクの契約、依存関係、成功基準、ブロッカーを読みます。

ステップ 5：担当者とフックスロットを設定して作業を引き受ける

bd update <target-bead-id> --status in_progress --assignee <agent-bead-id>
bd slot set <agent-bead-id> hook <target-bead-id>
bd agent state <agent-bead-id> working

--claim は使用しないでください。明示的に --assignee を指定してください。

ステップ 6：メールで実行・ハートビート・連携する

実行中：

bd agent heartbeat <agent-bead-id>

LLM エージェント（Claude Code）： ターンの開始時と、時間のかかるコマンド（ビルド、テスト）の実行直前にハートビートを送信します。ターン間の無応答は想定内です。ヘルスチェックの失敗として扱わないでください。5 分ごとの間隔が適用されるのは、永続的なデーモンで動作するエージェントのみです。

注： ハートビートの未受信時にエージェントを自動的に dead にする Witness の強制適用レイヤーは、まだ稼働していません。ハートビートは記録され、BeadBoard ダッシュボードに表示されますが、現時点では強制適用されません。デーモンの実装は今後のエピックです。

委任されたメールを通じて連携します。

bd mail と bb agent の違い： bd mail inbox/send/read/ack は、設定済みの shim を介して bb agent inbox/send/read/ack に処理を委譲する薄いラッパーであり、送信者の識別情報として BB_AGENT を自動的に挿入します。このスキルでは常に bd mail を使用してください。一部のリファレンスドキュメントには、低レベルの同等コマンドとして bb agent の直接呼び出しが記載されています。shim が設定されていない場合、または bb レベルで直接デバッグする場合にのみ使用してください。

bd mail inbox
bd mail send --to <agent-or-role> --bead <bead-id> --category <HANDOFF|BLOCKED|DECISION|INFO> --subject "<short>" --body "<details>"
bd mail read <message-id>
bd mail ack <message-id>

ブロックされた場合：

• BLOCKED を送信します
• bd agent state <agent-bead-id> stuck を設定します
• 介入または応答があるまで再開しません

最小限のポーリングタイミングと間隔については、references/coordination-system.md → Inbox Polling Protocol を参照してください。

ステップ 7：検証ゲート（コード変更）

npm run typecheck
npm run lint
npm run test

このセッションで新たに実行したコマンドの出力なしに、修正済み／完了と主張しないでください。

ステップ 8：証拠を公開し、クローズして、キャッシュを更新する

bd update <target-bead-id> --notes "<commands run + key outputs + files changed>"
bd close <target-bead-id> --reason "<what was completed>"
bd slot clear <agent-bead-id> hook
bd agent state <agent-bead-id> done

project.md の Environment Status Cache を更新します。

• テストを実行した場合：Tests last run の行を pass／fail と今日の日付に設定します
• preflight を実行した場合：session-preflight の行を更新します
• このセッションで bb agent register を実行した場合：bb agent registered の行を pass | BB_AGENT=<name> と今日の日付に更新します
• Session Log に次の形式で 1 行追加します：| YYYY-MM-DD | <agent-bead-id> | <what you verified/changed> |

この更新により、次のエージェントがチェックを再実行せずに済みます。

ステップ 9：メモリのレビュー

再利用可能な教訓がある場合：

• 正規のメモリ判断 Bead を作成するか、既存のものを置き換えます

再利用可能な教訓がない場合：

• 次のように記録します：Memory review: no new reusable memory.

危険信号

次のいずれかを行おうとしている場合は、停止して修正してください。

• --assignee の履歴を残さずにクローズする
• セッション開始時／担当時／クローズ時に bd mail のチェックを省略する
• ゲートの出力なしに完了を主張する
• リポジトリの project.md ではなく、スキルフォルダー内にプロジェクトのコンテキストを書く
• 古いドキュメントにある非推奨の直接コマンドのパターンを使う

適切なドキュメントの選び方

• references/session-lifecycle.md： セッション全体の開始から終了までの手順。
• references/agent-state-liveness.md： エージェントの状態、ハートビートの間隔、生存状態の解釈。
• references/coordination-system.md： 正式な bb-mail コマンドとカテゴリの意味。
• references/coord-events-sessions-ack.md： トリガーマップ、受信トレイのポーリングプロトコル、ブロックから再開までの手順。
• references/command-matrix.md： 日常業務で使うコマンドの一覧。
• references/failure-modes.md： 決定的な診断方法と復旧手順。
• references/memory-system.md： メモリのアンカー、挿入プロトコル、昇格／置き換えのルール。
• references/archetypes-templates-swarms.md： スウォームの構成、molecule の操作、ワーカーのディスパッチパターン。
• references/missions-realtime.md： リアルタイム／ウォッチャー／イベントのトラブルシューティング。
• references/creating-beads.md： 適切な命名、依存関係、ワークフローに沿ったエピック、タスク、サブタスクの作成。

要点

このランブックに正確に従えば、どのエージェントも事前の状況を把握していない状態から参加し、安全に連携し、手順の逸脱なく監査可能な形で完了できます。

プラットフォームに関する注記

環境変数の構文

シェル	コマンド
bash / zsh (WSL2, Linux, macOS)	export BB_AGENT=<name>
PowerShell (Windows native)	$env:BB_AGENT = "<name>"
cmd.exe (Windows native)	set BB_AGENT=<name>

メール委任パスの形式

bd config set mail.delegate "node <path>/bb-mail-shim.mjs" を設定する場合：

環境	パス形式の例
WSL2	node /home/<you>/<project-path>/skills/beadboard-driver/scripts/bb-mail-shim.mjs
Windows ネイティブ	node C:\Users\<you>\<project-path>\skills\beadboard-driver\scripts\bb-mail-shim.mjs

バイナリの検出

プリフライトスクリプトは、bd と bb が PATH 上にあるかを確認します。Windows ネイティブでは、システムは which の代わりに where を使用します。インストール済みにもかかわらず、プリフライトでバイナリが見つからないと報告された場合は、シェルから where bd と where bb を実行して確認し、PATH が正しく設定されたシェルから実行していることを確かめてください。