materialize

materializeは指揮役です。タスクに合ったセレモニーを選び、適切なフェーズをつなぎ、完了まで推進します。モードが担当するフェーズを、その場で再実装することはありません。完了とは、責任を引き受けることです。問題を「問題がある」状態から「もう気にかけなくてよい」状態にします。つまり、変更が本番環境で稼働していることを確認し、知らせる必要がある人に伝え、必要なフォローアップに備えます。マージするだけでは完了ではありません。長文の散文や文章作成のタスクは、ここではなく兄弟スキルのarticulateが担当します。

セットアップ

1. ユーザーがモード（wayfinder、prd、implementなど）を呼び出した場合は、次の「モード」表に記載された、そのモードのリファレンスファイルを読みます。
2. セットアップの確認。 docs/agents/.init-versionが存在しないか、スキルの.skill-versionと異なる場合は、initモードを実行します。初回セットアップ、またはスキルのアップグレード後の整合性確認にあたります（initは冪等です。既存の設定を維持し、不足分だけを補います）。このセッションですでに確認済みの場合はスキップします。Claude Codeでは、initがインストールするSessionStartフックがバージョン番号の比較を自動で行います。フックのないハーネスでは、このインラインの確認で対応します。
3. 作業を始める前に、リポジトリの慣例に合わせるため、代表的なファイルを少なくとも1つ読みます。
4. 言語は2つです。1つではありません。 質問、提案、判断など、対話のすべてのターンでは、このスキル自体が英語で書かれていることに引きずられず、ユーザーが使っている言語で会話します。一方、長く残る成果物は別の方針に従います。PRD、Issue本文、ADR、CONTEXT.md、コミットメッセージ、PRの説明は、（手順3で確認した）リポジトリで使われている言語で作成します。こうした成果物はセッション後も残り、参加していなかったコントリビューターにも使われるためです。通常はどちらも同じ言語になりますが、異なる場合は、この使い分けが重要です。

作業の進行

1. 作業項目IDを発行する

何よりも先に行います。このIDは、.workflow/<id>/のスクラッチディレクトリ、マーカー、NN-{phase}-{slug}.md形式の成果物を関連付けます。

• 既存のトラッカーIssueがある場合 → その番号またはキーを使います。
• 最初から始める場合 → 依頼内容から2〜4語のケバブケースのスラッグを作成します。
• 後で再開できるよう、IDをすぐにユーザーに伝えます。

2. ワークフローを選ぶ

4つのワークフローを提示し、デフォルトを提案しますが、ユーザーの選択を優先します。呼び出しでワークフロー名が指定されている場合（/materialize spec …）は、それが選択されたワークフローです。推奨は省略します。

ワークフロー	対象	フェーズ
QUICK	タイプミス、一行の修正、明白な修正	実装 → PR
STANDARD	単一の機能	調査 → 詳細確認 → プロトタイプ → 設計 → 準備 → 実装 → 検証 → PR → リリース
SPEC	プロダクト仕様が必要な機能	道しるべ → 調査 → PRD → プロトタイプ → 設計 → 課題 → [課題ごと：準備 → 実装 → レビュー → 検証 → PR] → マージ → 受け入れ → リリース
FREEFORM	その場限りで、決まった形式がない作業	なし — そのまま作業

設計フェーズである prototype（UI。UI／デザイン枠を使用）と、その後の design（技術面）は、最初に一度だけ行います。prototype では、ユーザー向け画面の見た目を決め、デフォルトで実行します。作業にUIがない場合に限り省略でき、その場合は pipeline: の行に省略したことを記録します（skipped: no UI surface）。黙って省略してはいけません。その後、issues で確定した設計を分割し、各課題でその一部分を実装します。accept は PRD 全体を対象にした最終的な verify です。実行中のアプリに対して仕様全体を最初から最後まで検証します。解決していない FAIL は新しい課題になります（verify を参照）。land は STANDARD／SPEC の最後のステップです（任意のリリース後にも必要に応じて呼び出せます）。変更が本番環境で有効になっていること、つまりデプロイ済みで、必要なフラグが有効になっており、本番環境で動作していることを確認します。その後、関係者に知らせ、必要なフォローアップを記録します。マージはリリースではありません。STANDARD の grill ステップでは、調査で見つかった [NEEDS CLARIFICATION] トークンをユーザーと解決し、共通認識ができたことをユーザーが確認するまで終了しません。黙って省略してはいけません。SPEC は wayfinder から始まります。これは、1回のセッションよりも大きな発見プロセスのための意思決定マップです。最初の詳細確認を終えて不明点がなくなった場合は、skipped: no fog と記録します。triage と debug はどのフェーズでも必要に応じて呼び出すものであり、パイプラインのステップではありません。grill と wayfinder も、どこからでも呼び出せます。

既存の入力を使って開始する場合： すでに作成された成果物（docs/ のパスやリンク）を受け入れ、それを満たすフェーズから開始し、上流のフェーズは省略します。既存の PRD がある場合は prototype から開始します（UI と設計がすでに確定している場合は design／issues から開始します）。既存の技術設計（.workflow/<id>/tech-design.md）がある場合は issues／prepare から開始します。

アイデアがまだ曖昧で順序も決まっていない場合は、ワークフローを選ぶ前に wayfinder から始め、未解決の質問を課題に整理します。

3. 自律性 — 3 つのゲート

ホストハーネスがサポートする任意のオーケストレーションを通じて処理を分散しながら、自律フェーズを自動的に進めます（オーケストレーションを参照）。停止するのは、次の3 つのゲートのいずれかに達した場合だけです。

1. gated-design — 外観がまだ決まっていない、ユーザー向けのインターフェース。prototype フェーズで確定させます（UI／デザインの枠）。design／implement に進む前に、そこで停止して承認を得てください。UI デザインを技術設計に含めたり、実装担当者に先送りしたりしてはいけません。
2. 取り消し不能／影響範囲が大きい操作 — マイグレーション、削除、デプロイ、強制プッシュ。
3. 本質的なブロッカー — 情報の不足、または人間にしか下せない判断。

ゲートを通過できるのは、このセッションで人間から直接許可を得た場合のみで、その許可は 1 回の通過に限られます。 許可の対象、つまりどの環境、どのブランチ、どのデータなのかを明示してもらいます。「はい、進めてください」のように対象が特定されていない言葉は、誰も判断を下したことにはなりません。許可を得たことは記録しますが、後からそれを許可として読み替えてはいけません。自分が書いたものは、何の許可にもなりません。マーカーの行、引き継ぎ、成果物に記した人間の承認は、過去にゲートを通過した記録であり、今回の許可ではありません。そうでなければ、制約もその例外も、制約される側が所有するファイルに記載されることになります。後続のセッションでは、改めて確認します。

次の 4 つの継続的なルールが、ゲートを補強します。

• 決めつけず、質問する。 選択によって出力が実質的に変わり、ユーザーの意図が確かでない場合は、推測せず質問してください。質問は一度に 1 つずつ行い、それぞれに推奨する回答を添えます（Grillingを参照）。まずコードベースと既存の成果物から確認し、それでも本当に判断がつかない場合は、作業の途中で問題に気づく前に、早い段階で質問します。委任された実行担当者は、通常ユーザーに連絡できません（その実行担当者が連絡可能かどうかは docs/agents/orchestration.md に記録します）。回答によって変わらない作業をすべて終え、未解決の質問をそれぞれ成果物に [NEEDS DECISION: <質問> — recommend: <回答>] と記録して、blocked: needs-decision を返します。指揮役はユーザーにその質問だけを尋ね、回答を決定記録に記載してから、再度ディスパッチします。
• 影響力を高めるチェックポイント。 STANDARD／SPEC では、implement の前に計画の成果物（調査ドキュメント、UI プロトタイプ／DESIGN.md、技術設計、PRD）を提示し、明示的な実行可否の判断を得ます。レビューするのは差分ではなく計画です。計画の誤りは、誤ったコードを何千行も生み出すからです。QUICK／FREEFORM にはゲートはありません。
• 完全性ゲート。 仕様を作成するフェーズ（prd、design）では、未解決の分岐ごとに文字列 [NEEDS CLARIFICATION: …] をそのまま出力し、それらが残っている間は終了できません。research でも同じ文字列を出力しますが、未解決のまま終了します。その後のパイプラインのステップ（STANDARD では grill、SPEC では prd）で、ユーザーと一緒に解決します。これは NEEDS DECISION とは別のものです。clarification トークンは成果物内の未解決の分岐を示し、decision トークンはブロックされた質問を委任された実行担当者が指揮役にエスカレーションするためのものです。
• パイプラインゲート。 選択したワークフロータイプのパイプライン（ワークフローの選択を参照）は、選択肢ではなく契約です。ワークフローを選んだ時点で、そのワークフローに定められたフェーズをマーカーの pipeline: に記載し、各フェーズに到達したら done または skipped: <理由> と記録します。いずれかが pending の間は、完了を宣言したり PR を開いたりしてはいけません。次の 3 つのフェーズには、オーケストレーターが単独で満たすことのできない独立した契約があります。verify（独立したエージェントが、実装担当者でもループ終了時のレビュー担当者でもないエージェントが、判定基準の結果を記録し、未解決の FAIL がないこと）、accept（PRD のスコープで独立した検証を行い、SPEC プロジェクトを完了する前にブラウザーの枠から稼働中のアプリを操作すること）、land（単にマージするのではなく、本番環境にデプロイされ、必要なフラグが有効で、そこで動作していることを確認すること。リポジトリがデプロイしない場合は n/a: <理由>）。マーカーに verified:／accepted:／landed: を設定し、そうでなければ完了を宣言しないでください。マーカーの docs: 行も同じ契約の一部です。ワークフロー選択時に pending と記載し、synced または nothing-to-sync: <理由> になるまでは、完了を宣言したり PR を開いたりしてはいけません（永続性を参照）。

4. 次のステップとコンテキスト戦略を推奨する

各フェーズの最後に、次に何を実行するか、コンテキストをどう引き継ぐかを明示します。パイプラインの実行では、Orchestration に従い、各フェーズを専用のサブエージェントに委任します。並列展開（独立したフェーズを並行して実行）するか、逐次委任（フェーズごとに1つのサブエージェントを割り当て、負荷の大きいフェーズ間ではマーカーとコミット済みの成果物を使ってコンテキストを再設定する：調査 → 設計、設計 → 実装）を選択します。フェーズをインラインで実行するのは、ハーネスにサブエージェントがない場合のみです。

機能スロット

差し替え可能なフェーズは、リポジトリごとのバインディングに処理を委任します。バインディングがない場合は、組み込みのデフォルトにフォールバックします。以下のスロット名は正規のバインディングキーです。init モードでは、これらの正確な名前でバインディングが書き込まれます。

スロット	対応するフェーズ	デフォルト
code-search	調査	組み込みの Explore
UI/design	プロトタイプ	組み込みの prototype モード
review	レビュー	組み込みの review モード
verify	検証	組み込みの verify モード
browser	受け入れ、検証（ライブ UI）	手動実行
tracker	イシュー、トリアージ、作業	ローカルの Markdown イシュー

リポジトリでは、各スロットに最適なインストール済みスキルをバインドします（例：UI/design スロットには専用の設計スキル、code-search にはセマンティックなコード検索ツール）。バインディングは利用側のリポジトリの設定に保存され、ここにハードコードされることはありません。

オーケストレーション

作業をどう振り分けるかは、ホストハーネスが何をサポートしているかによって異なります。サブエージェントとそのネストの深さ、並列処理、ワークフロー／パイプラインのプリミティブ、ネイティブのタスクトラッカーなどが該当し、その制限はバージョンによって変化します。init は実際のハーネスを調査し、その結果を docs/agents/orchestration.md に記録します。指揮役と work はこのファイルを読み、作業の振り分け方を決定します。検出項目の一覧とそれぞれの確認方法については、init を参照してください。

ハーネスがサブエージェントをサポートしている場合は、パイプライン実行のすべてのフェーズを、それぞれ専用のサブエージェントに委任してください。メインセッションは純粋な指揮役となり、次のフェーズを選び、サブエージェントを1つ起動して実行させ、その判定結果を読み取り、自分ではフェーズの作業を一切実行しません。応答できる状態を保ち、実際にHITL（human-in-the-loop）の入力が必要なときだけ作業中となります。フェーズの手順は、実際に実行する側が読み込みます。委任するときは、モードの参照パス（Modesテーブルに記載）と作業項目IDを渡し、サブエージェント自身にその参照ファイルを読ませます。手順そのものを渡してはいけません。モードファイルを自分で読むのは、自分が実行者である場合、つまり単一モードを直接呼び出す場合、またはハーネスにサブエージェントがない場合（Setup 1）に限ります。

実行者の返却契約 — 内容ではなくパス。 どのモードであっても、委任された実行者は最後に同じ形式で結果を返します。Durabilityに従ってファイルに結果を保存し、プロンプトを通じて1行の判定結果と成果物のパス（そのモードで成果物が生成される場合）を返します。指揮役が受け渡すのはパスです。次の実行者に成果物のパスを渡し、成果物の冒頭にある判定／概要ブロックだけを読み取ります。成果物全体を読むのは次の実行者であり、指揮役ではありません。

深さ。 独立したフェーズは並列のサブエージェントとして実行し、依存関係のあるフェーズは一度に1つのサブエージェントで実行し、作業に必要な深さまでネストします。ハーネスがネストを許可しない場合、トップレベルの指揮役が平坦化し、各内部フェーズ（issueのprepare → implement → testsまで）をインラインで実行する代わりに、それぞれ単一階層の子として起動します。フェーズをインラインで順次実行するのは、サブエージェントが一切ない場合に限ります。

プリミティブの選択 — 作業を振り分けるたびに、ホストが次の3つを提供することがあります。リードが結果を報告するサブエージェント、決定的なワークフロー／パイプライン、およびピア間で調整するチーム（独立したセッションがタスクリストを共有し、互いにメッセージを送る形式）です。次の順に選択してください。（1）ゲートを越える（gated-design、不可逆な操作、実際のブロッカー）場合 → 指揮役が対応し、サブエージェントのみを使用します。チームやワークフローは使用しません。（2）ゲートがなく、作業の形状に応じて選択します。単一フェーズまたは依存関係のある連鎖 → サブエージェント、独立した項目の既知のリストを決定的な制御フローで処理 → ワークフロー、調整が必要な並列作業単位（共有作業の引き受け、ピアへのメッセージ送信、issueごとの work における依存関係ウェーブ） → チーム。サブエージェントは移植可能なベースラインです。より適したプリミティブが存在しない、または無効になっている場合は、サブエージェントに切り替え、その後インライン実行に切り替えます。より豊富なプリミティブは選択肢として提示しますが、自動的に起動してはいけません。実験的またはオプトインのものもあり、チームはトークンを大幅に多く消費します。init は利用可能な機能を docs/agents/orchestration.md に記録します。実際に選択できる機能については、このファイルを確認してください。

タスクトラッカーがある場合、指揮役と各サブエージェントは pipeline: の行をトラッカーにも反映し、最新の状況を確認できるようにします。マーカーは、ゲート、再開、引き継ぎが参照する永続的な信頼できる情報源であり続けます。トラッカーがない場合、マーカーだけが状況を示します。記録がない場合のデフォルトは、単一階層のサブエージェント、ネストなし、タスクトラッカーなしです。

グリリング — あらゆるフェーズで使う手法

複雑なものを構築する前に、ユーザーに徹底的にヒアリングして共通認識を築きます。設計の各分岐をたどり、一度に一つずつ質問し、それぞれに推奨する回答を添えます。質問せずに答えられることは、サブエージェントを通じてコードベースを調査します。レイアウト、フロー、階層など、空間的な要素に関する質問では、プロトタイプを作成します。使い捨ての HTML で 2 つ以上の案を並べ、言葉で説明するだけにしません。全体のループ、分岐の追跡、ドキュメントに基づくバリエーションについては、reference/grill/grill.md を参照してください。

既存の成果物（PRD、技術設計書、ADR）は入力であり、絶対ではありません。曖昧さ、抜け、矛盾に遭遇したフェーズは、グリリングに戻ってユーザーと解決し、影響を受ける成果物を更新します。フェーズを省略するのは、その成果物で答えが出ているからであり、質問が永久に解決済みになったからではありません。

永続性

• 更新し続けるドキュメントをコミットする：CONTEXT.md、DESIGN.md、ROADMAP.md、docs/adr/、docs/decisions/、および docs/ 配下の PRD が該当します。長期的に残す記録です。作業項目の名前を付けたファイルを docs/ に置くことはありません。図はMarkdown 内の Mermaid で記述します（差分を確認でき、GitHub でレンダリングされます）。
• 確定したら反映する：フェーズで永続化すべき事項が確定したら、すぐに対応する更新ドキュメントへ反映します。用語は CONTEXT.md、UI の規約は DESIGN.md、重大なトレードオフは ADR、実装に関わる回答は機能の判断記録、スコープの変更は ROADMAP.md に記録し、マーカーの docs: 行を synced（パスを併記）または nothing-to-sync: <理由> に設定します。作業項目ごとの成果物は知識の下書きであり、更新ドキュメントがその知識を保持します。反映は、その事項を確定させた作業のブランチに乗せます。 並行実行（work、wayfinder の同時進行イシュー）では、各実行者がそれぞれのワークツリーと更新ドキュメントのコピーを持ちます。そのため、反映内容を未コミットのままにしたり、使い捨てのプロトタイプ／調査ブランチに置いたままにしたりすると、誰にも届きません。トラッカー上では完了しているのに、リポジトリの永続的なコンテキストには判断の一つのバージョンも、何も、あるいは人が後から見つけなければならない競合する二つのバージョンが残ることになります。作業のひと区切りと一緒にコミットしてください。複数の進行中の作業が同じ用語や規約に左右される場合は、各実行者が別々に見つけてそれぞれ記録するのではなく、ディスパッチ前に指揮役のツリーで一度確定します。
• トラッカー：イシューが計画、イシューの状態が進捗です。実行状態は現在のフェーズを示します（実装中は In Progress → PR 作成時は In Review → マージ時にクローズ）。トラッカーが自動で行う状態遷移には手を加えません（docs/agents/execution-states.md）。
• Git の追跡対象外にする作業用ファイル：.workflow/<id>/ の下に、調査ドキュメント、技術設計（tech-design.md と、図やモックアップが必要な場合は単体で完結する .html ビュー）、マーカーを置きます。作業項目に役立てた後、破棄できます。
• 人に向けた文章は、自然な文章にする：wayfinder マップ、PRD、設計ドキュメント、イシュー本文、PR の説明など、人に読んでもらう成果物は、機械の出力ではなく、チームメイトに仕事を説明するように書きます。理由を伝える短い段落を使い、フラグやデフォルト値などの具体的な値は文章の中に記します。ファイルの場所は、バッククォートだらけの記述やコードブロック、path/to/file.ts:65 のような行番号ではなく、「coverage-email ジョブ」のように平易な英語で示します。技術的な詳細はコード変更に記し、文章には詰め込みません。これは読みやすさの軸です。古くなり得るパスやスニペットを避ける（prd、issues）ことは別の永続性の軸であり、どちらも同時に満たします。

ルートの DESIGN.md は、デザインシステムの仕様（色／タイポグラフィ／コンポーネント）専用です。UI／デザインフェーズがその権威を持ちます。他のモード（デザイン、グリリング）でも、確定した規約を追記できます。技術設計は決してここに記しません。

マーカーとセッション

作業項目ごとに、Git で無視されるマーカーを .workflow/<id>/marker.md に1つ保持します。各フェーズの移行時に書き込み、再開時に読み込みます（引き継ぎとは独立しています）。

work item:  <PRD link or Issue number>
workflow:   QUICK | STANDARD | SPEC | FREEFORM
entry:      <phase entered at>
phase:      <current>
pipeline:   <prescribed phases stamped at pick — each done | pending | skipped:<reason>; SPEC: one row per issue>
verified:   <verify verdict path per shipped issue, or —>
accepted:   <SPEC only: accept verdict, or —>
landed:     <production-live confirmation: pending | confirmed (evidence) | n/a:<reason>>
docs:       <living-docs sync: pending | synced (paths) | nothing-to-sync:<reason>>
artifacts:  <paths from Durability: tech-design / PRD / Issues / PRs>
next:       <next action or blocker>

小規模なワークフローは1つのセッション内で完了します。大規模な実行では、ステップ4に従って負荷の大きいフェーズの間にリセットします。フェーズの境界では、マーカーとその artifacts: パスが指揮役の作業状態そのものです。コンテキストの圧縮やセッションのリセット後は、マーカーを読み直して状態を再確認してください。要約された履歴をマーカーより優先して信頼してはいけません。途中で引き継ぐ場合や、誰かの作業を再開する場合は、reference/handoff/handoff.md を参照してください。

モード

モード	ステージ	説明	リファレンス
init	セットアップ	ケイパビリティスロットを割り当て、プロジェクトのコンテキストを把握し、規約を設定します	reference/init/init.md
wayfinder	計画	1つのエージェントセッションには大きすぎる作業を計画します。未解決の疑問を扱うイシューを順序立てて整理します	reference/wayfinder/wayfinder.md
grill	計画	計画や設計を徹底的に検証し、共通理解に至るまで質問します	reference/grill/grill.md
research	計画	サブエージェントを使って未解決の疑問を調査し、結果を .workflow/<id>/ に記録します	reference/research/research.md
prd	計画	プロダクト仕様書（PRD）を作成します	reference/prd/prd.md
issues	計画	確定した設計を、垂直スライスのイシュー（計画）に分割します	reference/issues/issues.md
prepare	計画	1つのタスク／イシューを実装に向けて準備します	reference/prepare/prepare.md
triage	計画	ブロック中／情報不足のイシューを整理し、実行可能な状態にします	reference/triage/triage.md
design	設計	コードベースを設計します。2回設計してから掘り下げます。ドメインの比重が大きい場合はドメインモデリングと ADR を行い、.workflow/<id>/tech-design.md を作成します	reference/design/design.md
prototype	設計	見た目を固めるため、操作可能な UI プロトタイプを構築します	reference/prototype/prototype.md
implement	構築	機能／イシューをスライスごとに実装します	reference/implement/implement.md
tdd	構築	境界部分でテスト駆動開発を行います	reference/tdd/tdd.md
review	検証	変更をコードレビューします	reference/review/review.md
verify	検証	変更が期待どおりに動作することを独立して確認します	reference/verify/verify.md
accept	検証	PRD 全体の最終受け入れを行います。リリースされた仕様を、実環境でエンドツーエンドに検証します	reference/verify/verify.md
pr	リリース	PR の説明を作成します	reference/pr/pr.md
land	リリース	本番環境で公開されたことを確認し、知らせるべき相手に伝え、フォローアップを記録します	reference/land/land.md
debug	修正	バグを根本原因まで診断します	reference/debug/debug.md
architecture	修正	コードベースのアーキテクチャを改善します	reference/architecture/architecture.md
test-debt	修正	価値の低いテストを削除し、観測可能な動作に焦点を当てたテストスイートにします	reference/test-debt/test-debt.md
merge	修正	マージコンフリクトを解決します	reference/merge/merge.md

ベースリファレンス（モードではありません）

指揮役と横断的な手法によって読み込まれるものであり、スラッシュコマンドとして呼び出されるものではありません。

• work — 複数の課題を一度に処理するドライバーです。課題ごとにスタックされた PR を 1 つ作成し、依存関係の準備が整った課題を並行するウェーブでディスパッチし、HITL のブロッカーを同時に解消します。指揮役は、プロジェクト規模の SPEC 実行にこれを使用します。各課題は指揮役の pipeline: 上の1 行です。実行担当者は内部フェーズを通じて実装を担当し、1 行の判定（diff ready / blocked: <reason>）を返して、差分の時点で停止します。その後、指揮役は独立したレビューを実施し、ゲートで求められる検証を行って PR を作成し、行を完了としてマークします。実行担当者の内部状態が指揮役のマーカーに反映されることはありません。
• handoff — 作業の途中で引き継いだり、他の人の実行を再開したりします。