create-beads-orchestration

Beads オーケストレーションの作成

Claude Code 向けに、git ネイティブなタスク追跡を備えた軽量なマルチエージェントオーケストレーションをセットアップします。

このスキルでできること

このスキルでは、次のような完全なマルチエージェントワークフローを初期設定します。

• オーケストレーター（あなた）が問題を調査し、タスクを管理し、実装を委任します
• スーパーバイザー（専門エージェント）が分離されたワークツリーで修正を実行します
• Beads CLI が git ネイティブのタスク管理で全作業を追跡します
• フックがワークフローの規律を自動的に徹底します

各タスクには .worktrees/bd-{BEAD_ID}/ に専用のワークツリーが割り当てられます。これにより、メインの作業ツリーをクリーンな状態に保ち、並行作業を可能にします。

Beads Kanban UI

セットアップでは Beads Kanban UI を自動検出し、それに応じて設定します。見つからない場合は、インストールするかどうかを確認します。

---

ステップ 0：セットアップ状態を検出する（必ず最初に実行）

**ほかの作業を始める前に、初回セットアップか、再起動後の再開かを検出してください。**

ブートストラップの成果物を確認します。

ls .claude/agents/scout.md 2>/dev/null && echo "BOOTSTRAP_COMPLETE" || echo "FRESH_SETUP"

BOOTSTRAP_COMPLETE の場合：

• ブートストラップは以前のセッションで実行済みです
• ステップ 4：検出を実行に直接進んでください
• プロジェクト情報の確認や、ブートストラップの再実行は行わないでください

FRESH_SETUP の場合：

• 新規インストールです
• ステップ 1：プロジェクト情報の取得に進んでください

---

ワークフローの概要

| ステップ | アクション | 実行するタイミング | |------|-------------|-------------| | 0 | セットアップ状態を検出 | **必ず実行**（進行経路を決定） | | 1 | ユーザーからプロジェクト情報を取得 | 初回セットアップのみ | | 2 | ブートストラップを実行 | 初回セットアップのみ | | 3 | **停止** - ユーザーに再起動を指示 | 初回セットアップのみ | | 4 | 検出エージェントを実行 | 再起動後、またはブートストラップが完了済みの場合 |

ステップ 4（検出）が実行されるまで、セットアップは完了しません。

---

ステップ 1：プロジェクト情報を取得する（初回セットアップのみ）

**ステップ 2 に進む前に、プロジェクト情報を取得し、Kanban UI の有無を検出するか、インストールするかを確認する必要があります。**

1. プロジェクトディレクトリ：インストール先（デフォルト：現在の作業ディレクトリ）
2. プロジェクト名：エージェントテンプレートに使用します（指定がない場合、package.json/pyproject.toml から自動推測します）
3. Kanban UI：自動検出するか、ユーザーにインストールするかを確認します

1.1 プロジェクトディレクトリと名前を取得する

ユーザーに確認するか、package.json/pyproject.toml から自動検出します。

1.2 Kanban UI を検出またはインストールする

which bead-kanban 2>/dev/null && echo "KANBAN_FOUND" || echo "KANBAN_NOT_FOUND"

KANBAN_FOUND の場合 → --with-kanban-ui フラグを使用します。ユーザーに次のように伝えます。

Beads Kanban UI を検出しました。API 経由でワークツリー管理を設定します。

KANBAN_NOT_FOUND の場合 → 次のように確認します。

AskUserQuestion(
  questions=[
    {
      "question": "Beads Kanban UI not detected. It adds a visual kanban board with dependency graphs and API-driven worktree management. Install it?",
      "header": "Kanban UI",
      "options": [
        {"label": "Yes, install it (Recommended)", "description": "Runs: npm install -g beads-kanban-ui"},
        {"label": "Skip", "description": "Use git worktrees directly. You can install later."}
      ],
      "multiSelect": false
    }
  ]
)

• 「はい」の場合 → npm install -g beads-kanban-ui を実行し、--with-kanban-ui フラグを使用します
• 「スキップ」の場合 → --with-kanban-ui フラグは使用しないでください

---

ステップ 2：ブートストラップを実行する

# With Kanban UI:
npx beads-orchestration@latest bootstrap \
  --project-name "{{PROJECT_NAME}}" \
  --project-dir "{{PROJECT_DIR}}" \
  --with-kanban-ui

# Without Kanban UI (git worktrees only):
npx beads-orchestration@latest bootstrap \
  --project-name "{{PROJECT_NAME}}" \
  --project-dir "{{PROJECT_DIR}}"

ブートストラップスクリプトでは、次の処理を行います。

1. beads CLI をインストールします（brew、npm、または go を使用）
2. .beads/ ディレクトリを初期化します
3. エージェントテンプレートを .claude/agents/ にコピーします
4. フックを .claude/hooks/ にコピーします
5. .claude/settings.json を設定します
6. オーケストレーターの手順を記載した CLAUDE.md を作成します
7. .gitignore を更新します

先に進む前に、ブートストラップが正常に完了したことを確認してください。

---

ステップ 3：停止 - ユーザーが再起動する必要があります

**ここで必ず停止し、Claude Code を再起動するようユーザーに指示してください。**

ユーザーに次のように伝えます。

セットアップ段階が完了しました。今すぐ Claude Code を再起動してください。

新しいフックと MCP 設定は、再起動後にのみ読み込まれます。

再起動後：

1. 同じプロジェクトディレクトリを開きます
2. 「オーケストレーションのセットアップを続けて」と伝えるか、もう一度 /create-beads-orchestration を実行します
3. セットアップを完了するために、検出エージェントを実行します

この再起動を省略しないでください。再起動しないと、オーケストレーションは動作しません。

このセッションではステップ 4 に進まないでください。再起動は必須です。

ステップ 4：ディスカバリーを実行する（再起動後または検出後）

**次の場合にこのステップを実行します：** - ステップ 0 で `BOOTSTRAP_COMPLETE` が検出された場合、または - ユーザーが再起動後に戻り、「セットアップを続行」と伝えた場合、もしくは `/create-beads-orchestration` を再度実行した場合

1. ブートストラップが完了していることを確認します（.claude/agents/scout.md を確認）。これはステップ 0 ですでに完了しています
2. ディスカバリーエージェントを実行します：

Task(
    subagent_type="discovery",
    prompt="Detect tech stack and create supervisors for this project"
)

ディスカバリーでは、以下が行われます：

• package.json、requirements.txt、Dockerfile などをスキャンします
• 外部ディレクトリから専門エージェントを取得します
• 各スーパーバイザーに beads ワークフローを組み込みます
• スーパーバイザーを .claude/agents/ に書き込みます

3. ディスカバリーの完了後、ユーザーに次のように伝えます：

オーケストレーションのセットアップが完了しました！

作成されたスーパーバイザー：[ディスカバリーで作成されたものの一覧]

これでオーケストレーションワークフローを使用できます：

• bd create "Task name" -d "Description" でタスクを作成します
• オーケストレーターが適切なスーパーバイザーに処理を委任します
• すべての作業で、完了前にコードレビューが必要です

---

作成されるもの

• Beads CLI：Git ネイティブのタスク追跡（1 つの bead = 1 つの worktree = 1 つのタスク）
• コアエージェント：scout、detective、architect、scribe、code-reviewer（すべて Claude Task 経由で実行）
• ディスカバリーエージェント：技術スタックを自動検出し、専門スーパーバイザーを作成します
• フック：オーケストレーターの規律、コードレビューのゲート、簡潔な応答を徹底します
• タスクごとの Worktree ワークフロー：.worktrees/bd-{BEAD_ID}/ で開発を分離します

--with-kanban-ui を指定した場合：

• API（localhost:3008）を使用して worktree を作成し、失敗時は Git にフォールバックします
• Beads Kanban UI が実行されている必要があります

--with-kanban-ui を指定しない場合：

• Git コマンドを直接使用して worktree を作成します

エピックワークフロー（複数ドメインにまたがる機能）

複数のスーパーバイザーが必要な機能（例：DB + API + フロントエンド）には、エピックワークフローを使用します：

エピックを使用する場合

タスクの種類	ワークフロー
単一ドメイン（スーパーバイザー 1 つ）	単独の bead
複数ドメイン（複数のスーパーバイザー）	子タスクを持つエピック

エピックワークフローの手順

1. エピックを作成する：bd create "Feature name" -d "Description" --type epic
2. 設計ドキュメントを作成する（必要な場合）：architect をディスパッチして .designs/{EPIC_ID}.md を作成します
3. 設計ドキュメントをリンクする：bd update {EPIC_ID} --design ".designs/{EPIC_ID}.md"
4. 依存関係を設定して子タスクを作成する：

   bd create "DB schema" -d "..." --parent {EPIC_ID}              # BD-001.1
   bd create "API endpoints" -d "..." --parent {EPIC_ID} --deps BD-001.1  # BD-001.2
   bd create "Frontend" -d "..." --parent {EPIC_ID} --deps BD-001.2       # BD-001.3
   

5. 順次ディスパッチする：bd ready を使用して、ブロックされていないタスクを見つけます（各子タスクには専用の worktree が割り当てられます）
6. ユーザーが各 PR をマージする：次のタスクをディスパッチする前に、子タスクの PR がマージされるのを待ちます
7. エピックをクローズする：すべての子タスクがマージされた後、bd close {EPIC_ID} を実行します

設計ドキュメント

設計ドキュメントにより、エピックの子タスク間で一貫性を保てます：

• スキーマ定義（正確な列名と型）
• API コントラクト（エンドポイント、リクエスト／レスポンスの形式）
• 共有定数／列挙型
• レイヤー間のデータフロー

重要なルール：オーケストレーターは architect をディスパッチして設計ドキュメントを作成します。オーケストレーターが設計ドキュメントを直接作成することはありません。

フックによるエピックワークフローの徹底

• enforce-sequential-dispatch.sh：未解決のブロッカーがある場合、ディスパッチをブロックします
• enforce-bead-for-supervisor.sh：すべてのスーパーバイザーに BEAD_ID を必須とします
• validate-completion.sh：スーパーバイザーの完了前に、worktree、プッシュ、bead のステータスを検証します

要件

• beads CLI：ブートストラップによって自動的にインストールされます（brew、npm、または go 経由）

詳細情報

詳細なドキュメントはこちらをご覧ください：https://github.com/AvivK5498/The-Claude-Protocol