bmad-loop-setup

モジュールのセットアップ

概要

プロジェクトに bmad-loop モジュールをインストールし、設定し、アップグレードします。

このモジュールは特殊です。自動化スキルに加えて、ループを実際に実行する Python プログラムである bmad-loop オーケストレーターツールに依存しており、公開 Git リポジトリの bmad-loop パッケージとしてインストールされます。スキルは単独では何もしません。

_bmad/ の登録を担うのは BMAD インストーラーであり、このスキルではありません。 BMAD インストーラー（npx bmad-method install）を通じて bmad-loop をインストールすると、インストーラーはスキルを _bmad/bmad-loop/ に配置し、そのモジュール専用の設定ファイルとヘルプファイルを書き込み、モジュールを _bmad/_config/（マニフェスト、スキルマニフェスト、ファイルマニフェスト）に登録し、/bmad-help カタログを再構築します。実行のたびに中央の _bmad/config.toml を再生成するため、インストーラー以外のものがそこに書き込んではいけません。

そのため、このスキルの役割は、インストーラーが構造上実行できない部分です。

1. オーケストレーターツールをインストールまたはアップグレードします（インストーラーがコピーするのはスキルディレクトリのみであり、Python パッケージは扱えません）。
2. bmad-loop init を実行して CLI ごとのフックを登録し、同梱スキルを配置し、.bmad-loop/policy.toml と gitignore エントリを書き込みます。
3. bmad-loop validate で事前チェックを行い、ユーザーにロールごとのアダプター設定を案内します。

また、_bmad/bmad-loop/module-help.csv というファイルを更新し、BMAD インストーラーを通さずツールを直接インストールしたプロジェクトでも、モジュールのヘルプ項目が登録されるようにします。_bmad/ 以下のその他のファイルは書き込みも削除もしません。

モジュールの識別情報（名前、コード、バージョン）は ./assets/module.yaml に記載されています。

{project-root} は BMAD 設定の 値 ではリテラルトークンです。そこでは置き換えないでください。ただし、以下のコマンドにおけるファイルシステムパスの_引数_は対象外です。これらは実際のパスなので、実行前に {project-root} を実際のプロジェクトルートに置き換えてください。

有効化時

1. モジュールのメタデータ（code フィールドがモジュール識別子です）を確認するため、./assets/module.yaml を読み込みます。
2. {project-root}/_bmad/ が存在するか確認します。存在しない場合、このプロジェクトには BMAD がインストールされていないことを伝え、自動化スキルは BMAD のインストールを前提としていることを説明します。それでもセットアップでオーケストレーターツールをインストールできます。
3. {project-root}/_bmad/bmad-loop/ が存在するか確認します。存在する場合、このモジュールは BMAD インストーラーによってインストールされ、すでに登録されています。存在しない場合、モジュールは BMAD に登録されていないこと、また npx bmad-method install で bmad-loop を選択してインストールすると、/bmad-help に追加されることをユーザーに伝えます。これをセットアップの条件にはせず、どちらの場合も続行してください。

新規インストールかアップグレードかを判断します。 この判断に基づいて、ツールをアップグレードするか、プロジェクトごとのスキルを更新するかを決めます。次のいずれかに該当する場合は、アップグレードとして扱います。

• ユーザーが引数でアップグレードを指定した場合（upgrade、update、upgrade tool and skills など）。
• オーケストレーターツールが uv の下にすでにインストールされている場合。uv tool list を実行し、bmad-loop の項目を探します。bmad-loop --version を単独で実行しても、十分な根拠にはなりません。ソースチェックアウトや無関係な仮想環境によって実行できている可能性があるためです。手順 1 を参照してください。

それ以外は新規インストールです。続行する前に、判断内容をユーザーに伝えてください。例：「既存の bmad-loop インストールが見つかりました。アップグレードを実行します（ツール＋スキル）」または「既存のインストールは見つかりませんでした。新規セットアップを実行します」。

ユーザーが引数（例：accept all defaults、--headless、upgrade）を指定した場合は、それに従い、対話形式のプロンプトを省略します。その場合も、最後に確認内容をすべて表示してください。

ヘルプエントリーを登録する

このモジュールのヘルプエントリーを更新します。このスキルが _bmad/ の下に書き込むファイルはこれだけで、BMAD インストーラー自体が配置するものとまったく同じです。そのため、インストーラーでセットアップ済みのプロジェクトでは何も変更されず、再実行しても安全です。

mkdir -p "{project-root}/_bmad/bmad-loop"
cp ./assets/module-help.csv "{project-root}/_bmad/bmad-loop/module-help.csv"

/bmad-help は、_bmad/<module>/module-help.csv をすべて基に BMAD インストーラーが再構築する、組み立て済みのカタログ _bmad/_config/bmad-help.csv を読み込みます。そのため、BMAD インストーラーを一度も実行していないプロジェクトでは、これらのエントリーは次回のインストーラー実行時に表示されるようになります。すぐには表示されません。ヘルプシステムが更新されたと主張するのではなく、確認ステップでそのことを明確に伝えてください。

{project-root}/_bmad/ が存在しない場合は、このステップを完全にスキップしてください。

オーケストレーターツールをインストールする

オーケストレーターは、選択したアダプターを通じて新しいコーディング CLI セッションを起動し、開発パスでは bmad-build-auto（上流の開発プリミティブ。名称変更前のリリースでは bmad-dev-auto）を実行します。続いて、done になった仕様に対して再度実行し、フォローアップのレビューパスを行います。また、bmad-loop-sweep を実行し、フックのシグナルを監視して、成果物を検証します。したがって、インストールはセットアップの一部であり、任意の追加項目ではありません。

Git からインストールする理由： BMAD インストーラーはスキルディレクトリのみをプロジェクトにコピーし、隣接するファイルは含めないため、ツールをスキルフォルダーに同梱できません。正式なソースは https://github.com/bmad-code-org/bmad-loop です。（ただし逆の場合は成り立ちます。ツールのホイールにはスキルが同梱されているため、bmad-loop init を実行すると、プロジェクトのスキルツリーにスキルが自動的に配置されます。ステップ 3 を参照してください。）

ユーザーから明示的にスキップするよう依頼された場合（例：skills only／--no-tool）を除き、今すぐインストールまたはアップグレードして、ブートストラップしてください。実行前に {project-root} を実際のプロジェクトパスに解決してください。

1. PATH 上にすでにあるものを確認する： bmad-loop --version を実行します。ここでバージョンが表示されても、このプロジェクトのセットアップが完了していることを意味するわけではありません。現在の環境で何らかの bmad-loop をインポートできることを示しているだけです。これを信頼する前に、uv tool list を実行して bmad-loop を探してください。見つからない場合（PATH 上のコピーがソースチェックアウトまたは無関係な仮想環境由来の場合）は、アクティブな環境がクリーンなインストールを上書きしており、プロジェクトがそのチェックアウトに依存することになるとユーザーに警告してください。ユーザーが明示的に断らない限り、プロジェクトが偶発的な開発環境に依存しないよう、以下の正式なソースからインストールまたはアップグレードしてください。

2. Git リポジトリからインストールまたはアップグレードする（[tui] エクストラによって Textual ダッシュボードがインストールされ、bmad-loop tui が使えるようになります）。uv tool install は uv 独自の管理環境に bmad-loop をインストールするため、PEP 668 による外部管理環境の競合は発生せず、--user、有効化した仮想環境、--break-system-packages も不要です。

   • 新規インストール（uv 管理の bmad-loop がない場合）：

     uv tool install "bmad-loop[tui] @ git+https://github.com/bmad-code-org/bmad-loop.git"
     

     再現性を高めるためにリリースタグを固定するには、Git URL の末尾に @v<X.Y.Z> を追加してください。

   • アップグレード（uv がすでに bmad-loop を管理している場合）：

     1. 差分を報告できるよう、最初に現在のバージョンを記録します：bmad-loop --version。

     2. デフォルトでは main（または現在固定されているタグ）を使用します：

        uv tool upgrade bmad-loop --reinstall
        

        Git ソースの場合は --reinstall が必須です。通常の uv tool upgrade ではキャッシュされたコミットが再利用され、新しいコードが取得されません。次に、再現性のためリリースタグを固定するかどうかを提案してください。ユーザーが特定のバージョンを希望する場合は、次のコマンドで切り替えます：

        uv tool install --force "bmad-loop[tui] @ git+https://github.com/bmad-code-org/bmad-loop.git@v<X.Y.Z>"
        

     3. bmad-loop --version を再実行し、確認ステップで報告するため、変更前 → 変更後を記録します。

3. プロジェクトをブートストラップする — コーディング CLI フック、同梱の bmad-loop-* スキル、.bmad-loop/policy.toml テンプレート、および gitignore エントリーをインストールします（繰り返し実行しても安全です）。 まず、オーケストレーターで操作するコーディング CLIを決めます。サポートされているアダプターは claude（デフォルト）、codex、gemini、copilot、antigravity（Google の agy）です。フックは CLI ごとに登録されるため、この選択は重要です。開発／レビュー／トリアージに使う予定の CLI はすべて登録してください。ユーザーに確認します（セットアップ引数で既に指定されている場合（例：cli: claude, codex）、またはデフォルトを選択済みの場合を除きます。その場合は claude のみをデフォルトにします）。

   「オーケストレーターで操作するコーディング CLI はどれですか？ claude、codex、gemini、copilot、antigravityから選んでください。複数選択できます。[claude]」

   選択した CLI ごとに --cli <name> を 1 つ指定して、コマンドを組み立てます（このフラグは繰り返し指定できます）。アップグレード時は --force-skills を追加してください。これにより、プロジェクトごとのスキルのコピーが確実に更新されます。この指定がないと、init は既存のスキルディレクトリをすべてスキップするため、アップグレードしたツールに対して古いスキルがプロジェクトに残ります。新規インストール時は省略してください。

   # fresh install, claude only (default)
   bmad-loop init --project "{project-root}" --cli claude
   
   # fresh install, multiple, e.g. claude + codex + gemini
   bmad-loop init --project "{project-root}" --cli claude --cli codex --cli gemini
   
   # upgrade — refresh the bundled skills in place
   bmad-loop init --project "{project-root}" --cli claude --force-skills
   

   名前は claude、codex、gemini、copilot、antigravity のいずれかと完全に一致する必要があります。未知のプロファイルを指定すると、init はエラーを返し、有効な名前を一覧表示します。init は CLI ごとに初回のみ必要な注意事項を表示します（例：bmad-loop run の前にプロジェクトで claude を一度起動し、ワークスペースの信頼とフックの承認ダイアログに応答します。起動されたセッションでは初回のダイアログに応答できません）。これらの注意事項をユーザーに伝えてください。

   スキルは自動的にインストールされます。 init は、選択した CLI ごとに、同梱の bmad-loop-* スキルを適切なディレクトリに配置します。claude の場合は .claude/skills/、codex／gemini／copilot／antigravity の場合は .agents/skills/ です。新規インストール時は既存のスキルディレクトリをそのまま残します。アップグレード時は --force-skills により、アップグレードしたツールに同梱されているコピーで上書きします（この手順をスキップしてスキルを自分で管理する場合は --no-skills を使用してください）。

   注： --force-skills は bmad-loop-setup 自体も上書きします（同じバンドルに含まれています）。これは想定どおりの安全な動作です。新たに配置されたセットアップスキルは次回の呼び出しから有効になり、_bmad/custom/*.toml のオーバーライド（スキルディレクトリ名をキーとする）は変更されません。

4. 事前確認 — 設定、sprint-status、git、tmux、コーディング CLI を検証します。

   bmad-loop validate --project "{project-root}"
   

   プロジェクトの準備が完全に整っていない場合（例：まだ sprint-status.yaml がない、または bmad-sprint-planning が実行されていない場合）、validate はゼロ以外の終了コードを返します。新規プロジェクトではこれは想定どおりです。インストールの失敗としてではなく、準備状況のチェックリストとして、検出結果をユーザーに伝えてください。

5. 役割ごとのアダプター設定をユーザーに案内します。 手順 3 の --cli は、各 CLI の フック を登録するだけです。各ステージを実際に実行する CLI は、init がテンプレートから作成する {project-root}/.bmad-loop/policy.toml で設定します。[adapter] name（デフォルトは claude）はすべてのステージに適用されます。省略可能な [adapter.dev]、[adapter.review]、[adapter.triage] テーブルでは、個々のステージを上書きできます（それぞれ独自の name、model、effort、extra_args を指定します）。したがって、開発に claude、レビューに codex を使うなど、複数 CLI を組み合わせる構成では、フックを登録する（手順 3）だけでなく、policy.toml で役割に応じた CLI を指定する必要があります。

   [adapter]
   name = "claude"        # default for all stages
   
   [adapter.review]
   name = "codex"         # review runs on codex instead
   

   ファイルの場所と、policy.toml に記載する CLI はすべて手順 3 で --cli を使って登録しておく必要があることをユーザーに伝えてください（後から追加する場合は bmad-loop init --cli <name> を再実行します）。CLI を 1 つしか使わない場合は policy.toml を変更しないでください。デフォルト設定のままで問題ありません。

確認

報告内容：

• 新規インストール： インストールされた bmad-loop --version、bmad-loop init によってフックが登録され、bmad-loop-* スキルがインストールされ、選択したコーディング CLI 用のポリシーと gitignore が書き込まれたこと（「claude、codex 用のフックとスキルをインストール」のように、それぞれの名前を列挙してください）。
• アップグレード： アップグレード前 → 後の bmad-loop --version（例：「0.3.1 → 0.3.2 にアップグレード」または「0.3.2 のままで最新」）、および各 CLI ツリーで --force-skills を使って bmad-loop-* スキルを更新したこと（スキップではありません）。

また、次の内容も報告してください。

• bmad-loop validate の事前チェック結果（合格、または未完了の項目を示した準備状況チェックリスト）。
• _bmad/bmad-loop/module-help.csv が更新されたこと。この実行前に _bmad/bmad-loop/ が存在しなかった場合（つまり、BMAD インストーラーがモジュールをインストールしていなかった場合）は、次回 BMAD インストーラーの実行後にヘルプ項目が /bmad-help に表示されること、および npx bmad-method install でモジュールをインストールすれば正しく登録されることを伝えてください。
• このスキルは _bmad/ の下にほかのファイルを書き込んでいないこと。モジュールの登録、config.toml、ヘルプカタログは BMAD インストーラーが管理します。

次に、./assets/module.yaml の module_greeting をユーザーに表示してください。

結果

このセッションの残りの間は、ユーザーの設定済みの名前と言語を使用してください。BMAD の中央設定から、BMAD 独自のリゾルバー（4 層の TOML マージ。BMAD v6.10 以降と Python 3.11 以降が必要）を使って読み取ってください。

uv run "{project-root}/_bmad/scripts/resolve_config.py" --project-root "{project-root}" --key core

core テーブルから user_name と communication_language を取得してください。スクリプトが存在しないか、ゼロ以外のコードで終了した場合は、ユーザーに対して中立的な英語で話しかけてください。設定ファイルの書き込みや修復は行わないでください。