bmad-customize

BMad カスタマイズ

ユーザーの意図を、カスタマイズ可能なエージェントまたはワークフロースキル向けの、{project-root}/_bmad/custom/ 配下の正しい場所に配置された TOML オーバーライドファイルへ変換します。発見、ルーティング、作成、書き込み、検証を行います。

スコープ v1: スキル単位の [agent] オーバーライド（bmad-agent-<role>.toml / .user.toml）およびスキル単位の [workflow] オーバーライド（bmad-<workflow>.toml / .user.toml）です。中央設定（{project-root}/_bmad/custom/config.toml）はスコープ外です。ユーザーには How to Customize BMad ガイド を案内してください。

対象の customize.toml がユーザーの要望を公開していない場合は、その旨をはっきり伝えてください。フィールドをでっち上げないでください。

事前チェック

• {project-root}/_bmad/ が存在しない → ここでは BMad がセットアップされていません。bmad スキルのセットアップを実行することを提案し、まだ bmad を持っていない場合は先にインストールしてください（npx skills add bmad-code-org/BMAD-METHOD --skill bmad）。ユーザーが拒否した場合は停止してください。
• {project-root}/_bmad/scripts/resolve_customization.py が存在しない → 続行しますが、ステップ 6 の検証は手動マージにフォールバックします。
• 両方とも存在する → 続行します。

アクティベーション

ユーザーに挨拶します。ユーザーの呼び出しがすでに対象スキルと具体的な変更を指定している場合は、ステップ 3 に進んでください。

ステップ 1: 意図の分類

• 指示型 — 特定のスキル + 特定の変更 → ステップ 3。
• 探索型 — 「何をカスタマイズできますか?」 → ステップ 2。
• 監査/反復 — すでにカスタマイズされたものを確認または変更したい → ステップ 2。既存のオーバーライドを持つスキルを先頭に提示し、ステップ 3 で構成する前に既存のオーバーライドを読み取ってください。
• 横断型 — 複数のサーフェスに置ける → ステップ 3。ユーザーと明示的にエージェントかワークフローかを選択してください。

ステップ 2: 発見

uv run {skill-root}/scripts/list_customizable_skills.py --project-root {project-root}

ユーザーが追加の場所にスキルをインストールしている場合は、--extra-root <path>（繰り返し指定可能）を使用してください。

返された agents と workflows をユーザー向けにグループ化してください。それぞれについて、名前、説明、has_team_override または has_user_override が true かどうかを表示します。errors[] があれば提示してください。監査/反復の意図の場合は、すでにオーバーライドされているエントリを先頭に提示してください。

リストが空の場合: scanned_roots を表示し、スキルが別の場所にあるかどうかを尋ねます（--extra-root を提案）。そうでなければ停止してください。

ステップ 3: 適切なサーフェスの決定

対象の customize.toml を読み取ってください。トップレベルの [agent] または [workflow] ブロックがサーフェスを定義します。

チームまたはユーザーのオーバーライドがすでに存在する場合は、まずそれを読み取り、構成する前にすでにオーバーライドされている内容を要約してください。

横断型の意図 — 両方のサーフェスをユーザーと一緒に検討します:

• 特定のエージェントが実行するすべてのワークフロー → エージェントサーフェス（例: persistent_facts、principles を備えた bmad-agent-pm.toml）。
• 1 つのワークフローのみ → ワークフローサーフェス（例: activation_steps_prepend を備えた bmad-prd.toml）。
• 複数の特定のワークフロー → エージェントオーバーライドではなく、複数のワークフローオーバーライドを順に適用します。

単一サーフェスのヒューリスティック:

• ワークフローレベル: テンプレートの差し替え、出力パス、ステップ固有の動作、またはすでに公開されている名前付きスカラー（*_template、on_complete）。外科的で信頼性が高いです。
• エージェントレベル: ペルソナ、コミュニケーションスタイル、組織全体のファクト、メニューの変更、エージェントがディスパッチするすべてのワークフローに適用されるべき動作。

曖昧な場合は、トレードオフとともに両方を提示し、一方を推奨し、ユーザーに決定してもらってください。

公開されているサーフェス外の意図（ステップのロジック、順序、customize.toml にないもの）: その旨を伝えてください。近似として activation_steps_prepend/append または persistent_facts を提案するか、BMad Builder モジュールがインストールされている場合は、カスタムスキルを作成するために bmad-workflow-builder を推奨してください。

ステップ 4: オーバーライドを作成する

平易な英語を、対象の customize.toml フィールドに合わせて TOML に変換します。既存のオーバーライドを読み込んでいる場合は、変更を追加型として位置づけます。

マージのセマンティクス:

• スカラー (icon、role、*_template、on_complete) — オーバーライドが優先されます。
• 追加配列 (persistent_facts、activation_steps_prepend/append、principles) — チーム/ユーザーのエントリが順に追加されます。
• キー付きテーブル配列 (code または id を持つメニュー項目) — 一致するキーは置換され、新しいキーは追加されます。

オーバーライドは疎です。変更するフィールドのみを記述します。customize.toml 全体をコピーしないでください。

テンプレートの差し替え (*_template スカラー): デフォルトテンプレートを {project-root}/_bmad/custom/{skill-name}-{purpose}-template.md にコピーすることを提案し、オーバーライドを新しいパスに向けて設定し、その編集を手伝うことを提案します。

ステップ 5: チームまたはユーザーへの配置

{project-root}/_bmad/custom/ の下:

• {skill-name}.toml — チーム用、コミット対象。ポリシー、組織の慣習、コンプライアンス。
• {skill-name}.user.toml — ユーザー用、gitignore 対象。個人的なトーン、プライベートな情報、ショートカット。

特性によるデフォルト (ポリシー → チーム、個人 → ユーザー)、書き込む前に確認します。

ステップ 6: 表示、確認、書き込み、検証

1. TOML 全体を表示します。ファイルが存在する場合は、差分を表示します。決して無言で上書きしないでください。

2. 明示的な yes を待ちます。

3. 書き込みます。必要に応じて {project-root}/_bmad/custom/ を作成します。

4. 検証します:

   uv run {project-root}/_bmad/scripts/resolve_customization.py --skill <install-path> --project-root {project-root} --key <agent-or-workflow>
   

   マージ後の出力を表示し、変更されたフィールドを指摘します。

   リゾルバーが存在しない、または失敗する場合: 存在するレイヤーを読み込みます — <install-path>/customize.toml (ベース)、{project-root}/_bmad/custom/{skill-name}.toml (チーム)、{project-root}/_bmad/custom/{skill-name}.user.toml (ユーザー) — 同じマージルール (スカラーはオーバーライド、テーブルはディープマージ、code/id をキーとする配列はキーごとにマージ、その他すべての配列は追加) でベース → チーム → ユーザーの順に適用し、変更されたフィールドがどのように解決されるかを説明します。

   検証でオーバーライドが反映されていないことが判明した場合 (フィールドが変更されていない、マージ競合、ファイルが読み込まれていない): 検証出力をコンテキストとしてステップ 4 を再実行します。通常は、フィールド名の誤り、マージモードの誤り (スカラーか配列か)、またはスコープの誤りです。

5. 何が変更されたか、ファイルがどこにあるか、どのように反復するかを要約します。チームのオーバーライドをコミットするようユーザーに促します。

完了条件

• オーバーライドファイルが書き込まれている (またはユーザーが明示的に中止した)。
• ユーザーがリゾルバーの出力を確認している (または手動フォールバックのマージ要約)。
• ユーザーが要約を承認している。

そうでなければ、このスキルは完了していません — 完了させるか、不完全な状態で終了しようとしていることをユーザーに伝えてください。

このスキルが役に立たない場合

• 中央設定 ({project-root}/_bmad/custom/config.toml) — How to Customize BMad ガイド を参照してください。
• ステップロジック、順序、customize.toml にない動作 — 機能リクエストを起票するか、BMad Builder モジュールがインストールされている場合は、bmad-workflow-builder を使ってカスタムスキルを作成してください。どちらについても手伝うことを提案します。
• customize.toml を持たないスキル — カスタマイズできません。