bkd

BKD

$BKD_URL に HTTP リクエストを送信して BKD を操作します。$BKD_URL は、http://host:port/api のような BKD API のルートを指している必要があります。

このエントリーファイルは小さく保ちます。現在のターンに必要なリファレンスのみを読み込みます。

常時適用されるルール

1. リクエストを送信する前に、$BKD_URL を確認してください。設定されていない場合は、ユーザーに尋ねてください。
2. curl -sS --fail-with-body を使用し、解析する前に終了ステータスを確認してください。 変更を伴う操作では、.success == true も必ず確認してください。HTTP エラーや失敗を示すレスポンスが 気付かれないまま通過する可能性があるため、curl -s | jq に頼ってはいけません。
3. すべてのフォローアップの直前に、対象の statusId を読み直してください。記憶しているステータスを 使ってはいけません。また、done の課題にフォローアップを POST してはいけません。 キューに追加されるだけで、何も起動しないためです。review に PATCH し、読み直した値が review であることを確認してから POST してください（references/rest-api.md の bkd_follow_up がこれを行います）。これは、ディスパッチされた課題が送信するレポートや起動用の フォローアップも含め、すべてのフォローアップに適用されます。 statusId に応じて処理を分けてください。todo → フォローアップの全文を POST してから、 working に PATCH。done → review に PATCH してから、フォローアップを POST。 review／working → フォローアップを直接 POST。フォローアップを送信すると、review は 自動的に working に移行します。すでに working の課題に PATCH しても何も起きません。 /restart は失敗またはキャンセルされたセッションに限られ、保存済みのプロンプトを再実行します。 直ちに起動する必要がある場合、{success:true} だけでは不十分です。queued:true は起動が 確認できていないことを意味します。executionId、課題の sessionStatus（pending／running）、 または /processes を確認してください。todo → working の PATCH は結果を待たずに実行されます。 課題を読み直し、sessionStatus が failed の場合は、保留中の入力を処理させるために フォローアップを POST してください。
4. 実行を開始する前に、/processes/capacity を確認してください。
5. 作業を終えたら、done ではなく review に移行してください。人間の確認後に限り done を 使用します。ただし、三層構成の L1 または MR マスターは、作業がベースブランチにマージされた時点で ワークストリームまたはレーンを done に移行します。自身は移行しません（該当するリファレンスを 参照してください）。done への移行は実行中のセッションをキャンセルし、その課題を対象とする cron を 失敗させます（3 回失敗すると自動で一時停止します）。所有する cron は先に削除してください。
6. 課題間の通信にはすべてフォローアップを使用し、すべてのフォローアップ本文に bkd_with_sender を付けてください（または bkd_follow_up 経由で送信してください）。 これにより、ユーザーではなく自身の課題からのメッセージとして表示されます。 references/rest-api.md → リクエスト本文を安全に送信するを参照してください。
7. API に別途記載がない限り、プロジェクトと課題の削除は論理削除として扱ってください。
8. API 呼び出しの成功時は通常 { success, data }、アプリケーションレベルの失敗時は通常 { success, error } が返されますが、一部の HTTP 検証エラーには JSON のエンベロープがありません。 まず通信と HTTP の成功を確認し、次にエンベロープを確認してください。いずれかの確認に失敗した場合は、 安全側に倒して処理を中止してください。
9. サブタスクや長時間実行される操作を待つために sleep を使用してはいけません。三層パターンでは、 L1 は cron を作成しません。ユーザーメッセージと L2 のフォローアップが L1 を起動します。 各 L2 は自身の issue-follow-up cron を所有し、各ラウンドの間に現在のターンを終了します。 三層構成以外のオーケストレーションでは、references/orchestration.md に記載されている コーディネーター cron を使用してください。
10. インライン化禁止ルール：自由形式のテキスト（プロンプト、説明文）を -d '{...}' に インライン化してはいけません。引用符、$、バッククォート、改行は、シェルと JSON のエスケープ処理で 破損します。リポジトリの外にある一時ファイルにテキストを書き込み、jq で本文を作成して、 --data-binary @file を使って POST してください。 references/rest-api.md → リクエスト本文を安全に送信するを参照してください。 固定値のみの本文（例：{"statusId":"working"}）はインライン化しても安全です。
11. working の課題を緊急で修正する場合、修正を送信する前に現在のターンを停止してください。 ソフト割り込みとして cancel を試してください（通常 3～20 秒で review に移行します）。 または、即時強制終了には terminate を使用してください。課題を読み直し、statusId:review で あることを必ず確認してください。まだ working の間は修正を送信してはいけません。 この時間内に cancel が review に移行せず、修正を待てない場合は、terminate してください。 review に移行したらフォローアップを送信します。BKD が working に移行し、代わりのターンを開始します。 done の課題も同じ最終手順に従います。review に移行してから、フォローアップを送信してください。

コアワークフロー

3 階層の調整を開始するショートカット

「bkd を使って調整を開始して」や「BKD L1 を開始して」のような短いフレーズをユーザーが伝えた場合、現在のエージェントセッションを L1 として扱い、references/three-tier-coordination.md を読み込みます。ユーザーがプロンプトで L1／L2／L3 のルールをすべて繰り返す必要はありません。

自動モードのショートカット

ユーザーが「自動モード」「全自動」「L1 自動审核 合并，把计划跑完」のように、人手を介さない実行を求めた場合は、references/three-tier-coordination.md → Auto Mode (unattended L1) を読み込みます。この有効化は、合意した計画について、L1 のバッチごとのディスパッチとマージのゲートに代わる継続的な承認となります。L1 は各 L2 ブランチを自らレビューしてマージし、スコープ内の質問を担当する L2 と解決し、監視用 cron を 1 つ実行し、文書化されたハードストップ（スコープ外の作業、外部に影響する操作または不可逆な操作、リトライ上限到達、ラウンド予算到達）に達した場合にのみ停止します。これは MR モードにも適用され、マスターはユーザーに尋ねず、各レーンの報告作業を自ら受け入れます。

複数リポジトリ調整のショートカット（MR モード）

「BKD の複数リポジトリ調整を開始して」や「多仓库协调を開始して」のようなフレーズをユーザーが伝えた場合、またはプロジェクトディレクトリに複数の git リポジトリがあることが判明した場合は、references/multi-repo-coordination.md を読み込みます。すべて現在のプロジェクト内で行います。MR モードで新しいプロジェクトが作られることはありません。L1 マスターコーディネーターの課題が、ワークスペース内の PMA 形式の台帳を管理し、調整と転送のみを行います（差分の作成、ビルド、コードの判断は行いません）。リポジトリごとに 1 つのレーン課題（L2）があり、プロンプトに記載された作業ディレクトリによって該当リポジトリに結び付けられます（useWorktree:false、すべての git 呼び出しで git -C <repo> を使用）。そのため、リポジトリをまたいでコミットする課題はありません。

メッセージシステム

ユーザーがメッセージシステムの有効化（「启用消息系统」「启用决策 系统」「メッセージシステムを有効にして」「decision events を使って」）を求めた場合、または何かについて通知するよう依頼した場合（「通知我」「…のときに通知して」）、BKD のどのセッションでも references/messages.md を読み込みます。その後、エージェント自身の課題（送信者）が $BKD_URL/messages/items から BKD の /messages インボックスにメッセージを送信します。このインボックスは、ユーザーの Webhook／Telegram チャンネルにもメッセージを転送します。

• 人の判断が必要な事項には決定を送信します。ユーザーの回答は送信者に返信され、次のステップに進めるようになります。影響を受けない作業はそのまま続行されます。
• マイルストーン、完了、ブロッカーには通知を送信します（一方向）。自由形式の質問（expects: "reply"）も送信でき、決定と同様に回答されます。

単一の課題でも、あらゆるコーディネーターでも利用できます。3 階層の L1 と MR のマスターでは、デフォルトで使用します。定例の進捗報告には使用しないでください。/decisions のみを備えたサーバー（コントラクト v1）では、通知なしで決定を利用できます。プローブと会話へのフォールバックはリファレンスに記載されています。

単一課題の実行

set -o pipefail

# 1. Create issue
ISSUE=$(jq -n --arg title "short title" '{title:$title,statusId:"todo"}' \
  | curl -sS --fail-with-body -X POST "$BKD_URL/projects/{projectId}/issues" \
      -H 'Content-Type: application/json' -d @-) || exit 1
if ! printf '%s\n' "$ISSUE" | jq -e '.success == true and (.data.id | type == "string")' >/dev/null; then
  printf 'BKD error: %s\n' "$(printf '%s\n' "$ISSUE" | jq -r '.error // "invalid response"')" >&2
  exit 1
fi
ISSUE_ID=$(printf '%s\n' "$ISSUE" | jq -er '.data.id')

# 2. Queue the complete instruction while the issue is still todo
cat > /tmp/bkd-prompt.txt <<'PROMPT'
full implementation details
PROMPT
# sender: this issue, when running inside BKD (see bkd_with_sender in references/rest-api.md)
jq -n --rawfile prompt /tmp/bkd-prompt.txt --arg p "${BKD_PROJECT_ID:-}" --arg i "${BKD_ISSUE_ID:-}" \
  '{prompt: $prompt} + (if $i != "" then {sender: {kind: "agent", projectId: $p, issueId: $i}} else {} end)' \
  > /tmp/bkd-body.json
FOLLOWUP=$(curl -sS --fail-with-body -X POST "$BKD_URL/projects/{projectId}/issues/$ISSUE_ID/follow-up" \
  -H 'Content-Type: application/json' \
  --data-binary @/tmp/bkd-body.json) || exit 1
printf '%s\n' "$FOLLOWUP" | jq -e '.success == true' >/dev/null || exit 1

# 3. Start the first execution; this transition consumes the queued instruction
START=$(curl -sS --fail-with-body -X PATCH "$BKD_URL/projects/{projectId}/issues/$ISSUE_ID" \
  -H 'Content-Type: application/json' \
  -d '{"statusId":"working"}') || exit 1
printf '%s\n' "$START" | jq -e '.success == true' >/dev/null || exit 1

BKD の変更後は毎回、両方のガードを適用します。curl --fail-with-body が成功した後、.success が true であることを確認してください。必須の .data 値には jq -er を使用してください。|| ブロック内で単に false を実行しても、set -e を使用していないシェルは中断されません。

クイック操作

set -o pipefail

# Health check
curl -sS --fail-with-body "$BKD_URL/health" | jq

# Execution capacity
curl -sS --fail-with-body "$BKD_URL/processes/capacity" | jq

# Monitor logs (last 3 turns, assistant messages only)
curl -sS --fail-with-body "$BKD_URL/projects/{projectId}/issues/{issueId}/logs/filter/types/assistant-message/turn/last3" | jq

# Cron jobs (soft-deleted jobs are never listed)
curl -sS --fail-with-body "$BKD_URL/cron/actions" | jq
curl -sS --fail-with-body "$BKD_URL/cron" | jq

リファレンスパック

現在のタスクに必要なものだけを読み込みます。

• references/rest-api.md BKD の正確なルート、ペイロードの形式、クエリパラメーター、フィールド一覧を確認する場合に使用します。
• references/orchestration.md 複数サブタスクのディスパッチワークフロー、モード選択（worktree と simple）、サブタスクの作成と監視、フォローアップの連絡パターンを確認する場合に使用します。
• references/quality-review.md サブタスクのセルフレビュー責任、コーディネーターのログのフィルター評価、シグナルの分類を確認する場合に使用します。
• references/merge-strategy.md worktree ブランチのマージ、競合の解決、マージ後の検証、worktree モードでサブタスクの完了後に行うクリーンアップを確認する場合に使用します。
• references/multi-repo-coordination.md MR モード（1 つのワークスペースディレクトリに複数の git リポジトリがある場合）を確認する場合に使用します。調整のみを行う L1 マスターと、リポジトリごとに 1 つの L2 レーンを用意し、すべての課題を現在のプロジェクトに登録して、プロンプトの作業ディレクトリとしてリポジトリを指定する方法に加え、PMA 形式のワークスペース台帳、リポジトリ間のコントラクトの順序付け、境界チェック、リポジトリごとのコミットロールバックについて記載されています。
• references/messages.md メッセージシステムが有効な場合（BKD のいずれかのセッションでユーザーが有効にした場合、または三層および MR の調整でデフォルトで有効な場合）に、エージェントが人間の判断を必要とする、またはユーザーに伝えるべきことがある場合は、必ず使用します。有効化、判断依頼と通知の選択、v2 /messages および v1 /decisions のプローブと API、ウェイクシグナル、メッセージの確認、回答の適用、確認応答、クローズまたは取り下げ、Webhook ペイロード、会話へのフォールバックについて記載されています。
• references/three-tier-coordination.md イベント駆動の L1、cron 駆動の L2、短命な L3 による自律的な調整に使用します。ユーザー向けの L1 はユーザーまたは L2 からのフォローアップによってのみ起動され、各キャンペーンは複数の制約付き L2 コーディネーターに分割され、各 L2 は独自の DAG と 15 分間隔のセルフ cron を管理し、L3 の課題では短命のサブタスクが実行されます。エンジンに依存せず、L1／L2／L3 はそれぞれ異なるエンジン（Claude Code、Codex など）で実行できます。ユーザーがモデルを指定しない限り、モデルはサーバーのデフォルト設定のままにします。キャンペーンが複数のセッション／時間にまたがり、容量を考慮した DAG スケジューリングが必要で、スリープなしで実行する必要がある場合は、orchestration.md よりこちらを優先します。

クイックルーティング

意図に応じて参照先を選んでください：

• 単一課題の CRUD、cron ジョブ、または API の詳細：references/rest-api.md を読み込みます。
• 「use bkd to start coordination」や「start BKD L1」のような短い起動フレーズ：references/three-tier-coordination.md を読み込みます。
• 無人／自動実行（「auto mode」、「全自动」）：references/three-tier-coordination.md を読み込み、 Auto Mode (unattended L1) に従います。 ユーザーから依頼されていない限り、これを実行すると決めつけてはいけません。
• 1 つのプロジェクトディレクトリ内で複数の git リポジトリにまたがる作業、または 「start BKD multi-repo coordination」のような起動フレーズ：references/multi-repo-coordination.md を読み込みます（保護されたトランスポートには references/rest-api.md も読み込みます）。
• ユーザーがメッセージ／意思決定システムの有効化、通知、未解決の意思決定やメッセージについて尋ねた場合、またはそのシステムを有効にしたエージェントが人間の判断を必要としている、もしくはマイルストーンを報告する場合：references/messages.md を読み込みます。
• サブタスクの複数振り分けやオーケストレーション：保護されたトランスポートにはまず references/rest-api.md を一度読み込み、その後 references/orchestration.md を読み込みます。
• サブタスクの品質評価やコードレビュー：保護されたトランスポートにはまず references/rest-api.md を一度読み込み、その後 references/quality-review.md を読み込みます。
• worktree のサブタスク完了後のブランチマージ：保護されたトランスポートにはまず references/rest-api.md を一度読み込み、その後 references/merge-strategy.md を読み込みます。
• 異種エンジン間で長期にわたる 3 層連携を行う場合：references/three-tier-coordination.md を読み込みます（L1 をユーザー向けのイベント駆動型に保ち、複数の L2 コーディネーターがそれぞれ別個のワークストリームを担当して cron を介して自律的に進行し、L2／L3 が L1 とは異なるエンジンで実行される場合は、orchestration.md の代わりに使用します）。
• オーケストレーションの全パイプライン：まず references/rest-api.md を一度読み込み、その後各フェーズに進む際に references/orchestration.md、references/quality-review.md、references/merge-strategy.md を読み込みます。