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 に追加されることをユーザーに伝えます。これをセットアップの条件にはせず、いずれの場合も続行してください。BMAD v7 では、代わりに bmad setup bmad-loop でインストールします（v6 インストーラーではありません。bmad-loop の docs/setup-guide.md の「BMAD v7 へのインストール」を参照してください）。

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

• ユーザーが引数で指定している場合（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 v7 では代わりに bmad setup bmad-loop を使うこと）を伝えてください。
• このスキルは _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 を取得してください。スクリプトが存在しない、またはゼロ以外の終了コードを返す場合は、設定ファイルを書き込んだり修復したりせず、ユーザーに中立的な英語で話しかけてください。