asset-spec

!bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys review_mode,automation

アセット仕様

引数が指定されていない場合は、design/assets/entity-inventory.md が存在するか確認します。

• 存在する場合：内容を読み、ステータスが「Needed」で仕様ファイルがまだない最初のエンティティまたは画面を見つけて、AskUserQuestion を使用します。
  • プロンプト：「次に仕様を作成する項目は [name] です。仕様を作成しますか？」
  • 選択肢：[A] はい — [name] の仕様を作成 / [B] 別の項目を選ぶ / [C] ここで終了
• エンティティ一覧がない場合：design/assets/asset-manifest.md を確認します。マニフェストが存在する場合は、上記と同じ手順で、マニフェストを参照します。
• どちらも存在しない場合：失敗として終了するのではなく、エンティティと画面の一覧作成フロー（以下のフェーズ 0b）を開始します。

---

すべての AskUserQuestion 呼び出しは .claude/docs/automation-modes.md に従います （collaborative は常に確認、guided は主要な項目のみ確認、autonomous は記録して続行します。 automation_always_ask のカテゴリは常に確認します）。注：外部画像生成ツールを実際に呼び出す場合（画像 API を呼び出す場合）は、modes.automation の設定にかかわらず、必ず確認を求めます。これは、external_calls が automation_always_ask に含まれているかどうかとは無関係に適用される、取り消し不能な外部操作に対する保護です。（現在、このスキルが出力するのは生成プロンプトのテキストのみです。実際の生成機能が将来組み込まれる場合に、この保護が適用されます。）

フェーズ 0b：エンティティと画面の一覧作成（引数も既存の一覧もない場合に実行）

このフローでは、ゲームで視覚的に必要となるすべてのもののマスターリストである design/assets/entity-inventory.md を作成します。アセット仕様の作業を始める前に一度実行します。

ステップ 1 — ドキュメントから情報を収集

利用可能なすべての資料を並行して読み、ドキュメントごとに必要なセクションを特定します。Grep ツール（パターン ^#、コンテンツモード）で必要な見出しを探し、Read でオフセットと上限を指定して該当範囲を読みます。

• design/gdd/systems-index.md — 記載されているすべてのシステムを抽出します
• GDD のアセット関連の内容 — すべての GDD を全文読みしないでください。必要なセクションは標準の見出しで示されており、名前のあるエンティティはレジストリにあります。

  Grep pattern="## (Visual/Audio Requirements|UI Requirements)" glob="design/gdd/*.md" output_mode="content" -A 25
  

  名前のあるエンティティ（キャラクター、敵、建物、アイテム）については、存在し、エントリがある場合は design/registry/entities.yaml の entities／items を読みます。そうでない場合は、GDD 内で名前のある内容を検索します。Visual/Audio セクションが存在しないか、[To be designed] と記載されている場合に限り、GDD を全文読みします（そのケースはフェーズ 1 ですでに処理されます）。VFX イベントは Visual/Audio の検索結果に現れます。
• design/art/art-bible.md — 名前のあるビジュアルカテゴリと、アセット種別に関する想定を抽出します
• design/narrative/ — キャラクターや世界のエンティティに関するドキュメントがあれば確認します（任意。必須ではありません）

ステップ 2 — 一覧案を作成

見つかった項目をカテゴリ別に整理します。

Characters / Protagonists
Enemies / Creatures
Buildings / Structures
Environment / Terrain
Items / Props
VFX / Particles
UI Screens (list each screen by name)
HUD Elements
Audio (SFX, music — descriptions only, no generation prompts)
Other

各項目について、見つかった元のドキュメントを記録します。

ステップ 3 — 提示して共同で調整

作成した一覧案全体を会話でユーザーに提示します。その後、AskUserQuestion を使用します。

• プロンプト：「GDD とアートバイブルから、[N] 個のビジュアルエンティティと [N] 個の UI 画面が見つかりました。一覧をご確認ください。不足しているものや不要なものはありますか？」
• 選択肢：
  • [A] 問題ありません — この一覧を保存
  • [B] 説明した項目を追加する
  • [C] 該当しない項目を削除する
  • [D] 追加と削除の両方 — 編集させてください

[B] または [D] の場合：追加する項目をユーザーに説明してもらいます。「レベル背景に使用する中世の城塞」のような簡単な説明でも、詳細な説明でもかまいません。ユーザーが納得するまで、一緒に調整します。

[C] または [D] の場合：削除する項目とその理由を尋ねます。該当項目を一覧から削除します。

Step 4 — インベントリを書き込む

ユーザーの承認後、次のように尋ねます。「エンティティインベントリを design/assets/entity-inventory.md に書き込んでもよろしいですか？」

ファイルを書き込みます：

# Visual Entity & Screen Inventory

> Generated: [date]
> Sources: [list of source docs read]

## Entities

| # | Name | Type | Description | Source | Status |
|---|------|------|-------------|--------|--------|
| 1 | [name] | Character / Enemy / Building / Environment / Item / Other | [brief description] | [source doc] | Needed |

## UI Screens

| # | Screen Name | Description | Source | Status |
|---|-------------|-------------|--------|--------|
| 1 | Main Menu | [description] | [source] | Needed |

## HUD Elements

| # | Element | Description | Source | Status |
|---|---------|-------------|--------|--------|

## Audio

| # | Name | Type (SFX / Music / Ambient) | Description | Source | Status |
|---|------|------------------------------|-------------|--------|--------|

書き込み後、ユーザーに次のように伝えます：

「エンティティインベントリを保存しました。次のステップ：

• インベントリにある各 UI 画面について /ux-design [screen name] を実行します
• 各ビジュアルエンティティについて、該当するものに応じて /asset-spec system:[name]、level:[name]、character:[name] のいずれかを実行します
• または、インベントリを1項目ずつ処理するため、再度 /asset-spec を実行します」

---

フェーズ 0：引数を解析する

以下を抽出します：

• 対象タイプ：system、level、character のいずれか
• 対象名：コロンの後の名前（kebab-case に正規化）
• レビュー モード：指定されている場合は --review [full|lean|solo]

有効なモードは、このスキルの冒頭で resolve_config --keys review_mode によってすでに解決されているモードです。これは設定の全階層を適用します。何も設定されていない場合は modes.rigor に従い、minimal（既定）では solo、standard では lean、full では full になります。--review 引数を指定すると、この実行に限りモードが上書きされます。

モードの動作：

• full：art-director と technical-artist の両方を並行して起動します
• lean：art-director のみを起動します。より高速ですが、技術的制約の確認を省略します
• solo：エージェントを起動せず、メインセッションがアートバイブルのルールだけをもとに仕様を作成します。単純なアセットカテゴリや、深さより速度を優先する場合に使用します

---

フェーズ 1：コンテキストを収集する

ユーザーに何かを尋ねる前に、すべての資料を読み込みます。アートバイブルと GDD はセクションごとに読みます。Grep ツールで必要な見出し（パターン ^#、コンテンツモード）を探し、Read で offset と limit を指定して該当範囲を読み込みます。

必須の読み込み：

• アートバイブル：design/art/art-bible.md を読み込みます。存在しない場合は失敗とします：

  「アートバイブルが見つかりません。まず /art-bible を実行してください。アセット仕様はアートバイブルのビジュアルルールとアセット基準に基づきます。」

  例外 — minimal パス。 アートバイブルがなく、design/game-brief.md が存在する場合（rigor: minimal ではアートバイブルは必須ではありません）、失敗とはしません。ブリーフの Art & audio direction の行を仕様の基準とし、出力の先頭でその旨を伝えます。「ブリーフの1行のアートディレクションを基準としています。アートバイブルがないため、以下の色、形、アセット基準のルールは制約ではなく提案です。」省略可能な選択肢として /art-bible を1回だけ提示します。作成する仕様も同じ基準に従います。ヘッダーには > **Art Bible**: の代わりに > **Art direction**: design/game-brief.md (Art & audio direction) — no art bible と記載し、各アセットには Art Bible Anchors ブロックの代わりに **Brief anchor:** [適用したブリーフの行] を記載します。また、アートバイブルのセクションや §8 のティアを仕様内で参照しません。 以下を抽出します：Visual Identity Statement、Color System（セマンティックカラー）、Shape Language、Asset Standards（アートバイブル第8セクション — 寸法、形式、ポリゴン数の予算、テクスチャ解像度のティア）。

• プロジェクト設定：project.yaml の performance.* と naming.* を読み込みます。キーが存在しないか空の場合（project.yaml に performance または naming ブロックがない場合も含む）は、.claude/docs/technical-preferences.md を参照します。パフォーマンス予算と命名規則を抽出します。

対象タイプ別のソースドキュメントの読み込み：

• system：design/gdd/[target-name].md を読み込みます。Visual/Audio Requirements セクションを抽出します。存在しない場合、または [To be designed] と記載されている場合：

  "design/gdd/[target-name].md の Visual/Audio セクションは空です。/design-system [target-name] を実行して GDD を完成させるか、ビジュアルに関するニーズを手動で説明してください。" AskUserQuestion を使用します：[A] ニーズを手動で説明する / [B] 中止 — まず GDD を完成させる

• level：design/levels/[target-name].md を読み込みます。アート要件、アセットリスト、VFX のニーズ、および Step 4 のアートディレクターによる制作コンセプトの仕様を抽出します。
• character または entity：design/narrative/characters/[target-name].md を読み込むか、design/narrative/ および design/assets/entity-inventory.md を検索して該当する項目を探します。ビジュアルの説明、役割、指定されている識別上の特徴を抽出します。
  • ソースドキュメントが見つからない場合：そこで処理を失敗させないでください。代わりに AskUserQuestion を使用します：
    • プロンプト：「[name] のプロフィールが見つかりません。簡潔に説明してください。1、2文で十分です。」
    • オプション：[A] 今すぐ説明する / [B] このエンティティをスキップする / [C] ここで中止する
    • [A] の場合：ユーザーの説明をソースとして使用します。簡潔な回答なら簡潔な仕様を、詳細な回答なら詳細な仕様を作成します。ユーザーが提供した詳細度をそのまま受け入れ、それに基づいて作業します。

任意の読み込み：

• この対象の既存仕様：design/assets/specs/[target-name]-assets.md が存在する場合は読み込みます。これは再実行であり、Phase 2 では前回以降の新規項目または変更点のみを提案します（Phase 5 でファイルをその場で更新します）。
• 既存のマニフェスト：design/assets/asset-manifest.md が存在する場合は読み込みます。この対象ですでに仕様化されたアセットを抽出し、重複を避けます。
• 関連する仕様：design/assets/specs/*.md を Glob で検索し、共有できるアセットがないか確認します（例：あるシステム向けに仕様化された共通 UI 要素が、ここでも使える場合があります）。

コンテキストの要約を提示：

アセット仕様： [対象タイプ] — [対象名]

• ソースドキュメント：[path] — [N] 種類のアセットを特定
• アートバイブル：あり — セクション 8 にアセット基準
• この対象の既存仕様：[N 件を仕様化済み／なし]
• 他の仕様で見つかった共有アセット：[一覧または「なし」]

---

Phase 2：アセットの特定

ソースドキュメントから、明示されているものも暗示されているものも含め、言及されているすべてのアセットタイプを抽出します。

システムの場合：VFX イベント、スプライト参照、UI 要素、オーディオトリガー、パーティクルエフェクト、アイコンのニーズ、「ビジュアルフィードバック」に関する記述を探します。

レベルの場合：固有の環境プロップ、雰囲気を演出する VFX、ライティング設定、環境音、スカイボックス／背景、エリア固有のマテリアルを探します。

キャラクターの場合：スプライトシート（idle、walk、attack、death）、ポートレート／アバター、アビリティに付随する VFX、UI 表現（アイコン、ヘルスバーのスキン）を探します。

アセットを次のカテゴリに分類します：

• スプライト／2D アート — キャラクタースプライト、UI アイコン、タイルシート
• VFX／パーティクル — ヒットエフェクト、環境パーティクル、画面エフェクト
• 環境 — プロップ、タイル、背景、スカイボックス
• UI — HUD 要素、メニューアート、フォント（カスタムの場合）
• オーディオ — 効果音、音楽トラック、環境音のループ（※オーディオ仕様は説明のみで、生成プロンプトは含めません）
• 3D アセット — メッシュ、マテリアル（エンジンに応じて該当する場合）

特定したすべてのアセット一覧をユーザーに提示します。AskUserQuestion を使用します：

• プロンプト：「[target] 向けに [N] カテゴリにわたる [N] 件のアセットを特定しました。仕様化の前に確認してください：」
• まず会話の本文にカテゴリ別の一覧を表示します
• オプション：[A] 続行 — すべて仕様化する / [B] 一部のアセットを削除する / [C] 見落としたアセットを追加する / [D] カテゴリを調整する

ユーザーがアセット一覧を承認するまで、Phase 3 に進んではいけません。

---

Phase 3：仕様の生成

レビュー方式に基づいて専門エージェントを起動します。すべての Agent 呼び出しを同時に実行し、1つが終わるまで次を開始せずに待つことはしないでください。

フルモード — 並列で起動：

art-director を Agent 経由で起動：

• 提供する情報：Phase 2 の全アセットリスト、アートバイブルの Visual Identity Statement、Color System、Shape Language、ソースドキュメントのビジュアル要件、アートバイブルの Section 9 に記載された参考ゲームやアート
• 依頼内容：「このリストの各アセットについて、以下を作成してください：（1）アートバイブルの Shape Language と Color System に基づく、2～3 文のビジュアル説明。異なる 2 人のアーティストが一貫した結果を制作できる程度に具体的に記述してください。（2）AI 画像ツールで使用できる生成プロンプト（Midjourney／Stable Diffusion 形式。スタイルのキーワード、構図、色パレットの基準、ネガティブプロンプトを含めてください）。（3）このアセットに直接適用されるアートバイブルのルール（該当するセクションを明記）。オーディオアセットの場合は、生成プロンプトの代わりに音の特徴を説明してください。」

technical-artist を Agent 経由で起動：

• 提供する情報：全アセットリスト、アートバイブルの Asset Standards（Section 8）、パフォーマンス予算（project.yaml の performance.*、なければ technical-preferences.md）、エンジン名とバージョン
• 依頼内容：「このリストの各アセットについて、以下を指定してください：（1）正確な寸法またはポリゴン数（アートバイブルの Asset Standards の段階に合わせ、新しいサイズを作り出さないでください）。（2）ファイル形式とエクスポート設定。（3）命名規則（project.yaml の naming.*、なければ technical-preferences.md）。（4）このアセット種別が遵守すべきエンジン固有の制約。（5）該当する場合は LOD 要件。アートバイブルが推奨する標準とエンジンの制約が食い違うアセット種別があれば指摘してください。」

リーンモード — art-director のみ起動（technical-artist はスキップ）。

ソロモード — どちらもスキップ。アートバイブルのルールのみから仕様を導き、技術的制約が検証されていないことを明記します。

スキップしたエージェントはすべて、出力内で仕様の前に名前を挙げてください： 「technical-artist はスキップされました — リーンモード：技術的制約は検証されていません。」／ 「art-director と technical-artist はスキップされました — ソロモード：このセッションで仕様を作成しました。技術的制約は検証されていません。」エージェントなしで作成した仕様は、エージェントがレビューしたかのように記述してはいけません。

Phase 4 の前に両方の回答を収集してください。 art-director と technical-artist の間に矛盾がある場合（例：art-director が 4K テクスチャを指定し、technical-artist がエンジンの予算上 512px が必要だと指摘した場合）は、明示的に提示してください。黙って解決してはいけません。

---

Phase 4：仕様の作成とレビュー

エージェントの出力をまとめ、アセットごとに仕様のドラフトを作成します。次の形式ですべての仕様を会話内に提示してください：

## ASSET-[NNN] — [Asset Name]

| Field | Value |
|-------|-------|
| Category | [Sprite / VFX / Environment / UI / Audio / 3D] |
| Dimensions | [e.g. 256×256px, 4-frame sprite sheet] |
| Format | [PNG / SVG / WAV / etc.] |
| Naming | [e.g. vfx_frost_hit_01.png] |
| Polycount | [if 3D — e.g. <800 tris] |
| Texture Res | [e.g. 512px — matches Art Bible §8 Tier 2] |

**Visual Description:**
[2–3 sentences. Specific enough for two artists to produce consistent results.]

**Art Bible Anchors:**
- §3 Shape Language: [relevant rule applied]
- §4 Color System: [color role — e.g. "uses Threat Blue per semantic color rules"]

**Generation Prompt:**
[Ready-to-use prompt. Include: style keywords, composition notes, color palette anchors, lighting direction, negative prompts.]

**Status:** Needed

すべての仕様を提示した後、AskUserQuestion を使用します：

• 質問：「[target] のアセット仕様 — [N] 件です。レビューは完了しましたか？」
• 選択肢：[A] すべて承認 — ファイルに書き込む / [B] 特定のアセットを修正 / [C] 別の方向性で再生成

[B] の場合：どのアセットをどう変更するか尋ねます。内容をその場で修正し、再提示します。軽微なテキスト修正でエージェントを再起動してはいけません。ビジュアルの方向性自体を変更する必要がある場合にのみ再起動してください。

[C] の場合：どの方向性に変更するか尋ねます。更新したブリーフを使って、該当するエージェントを再起動します。

---

Phase 5：仕様ファイルの書き込み

承認後、次のように尋ねます：「仕様を design/assets/specs/[target-name]-assets.md に書き込んでもよいですか？」

ファイルがすでに存在する場合（同じターゲットの再実行）は、その場で更新し、全体を上書きしてはいけません。既存の ASSET-NNN ブロックと ID を維持し、ユーザーが承認した変更のみを適用して、新しいアセットにはプロジェクト全体で次に使える ID を割り当てます。変更内容を示したうえで、「書き込んでもよいですか？」ではなく「design/assets/specs/[target-name]-assets.md を更新してもよいですか？」と尋ねます。

次の内容でファイルを書き込みます：

# Asset Specs — [Target Type]: [Target Name]

> **Source**: [path to source GDD/level/character doc]
> **Art Bible**: design/art/art-bible.md
> **Generated**: [date]
> **Status**: [N] assets specced / [N] approved / [N] in production / [N] done

[all asset specs in ASSET-NNN format]

次に design/assets/asset-manifest.md を更新します。存在しない場合は作成します：

# Asset Manifest

> Last updated: [date]

## Progress Summary

| Total | Needed | In Progress | Done | Approved |
|-------|--------|-------------|------|----------|
| [N] | [N] | [N] | [N] | [N] |

## Assets by Context

### [Target Type]: [Target Name]
| Asset ID | Name | Category | Status | Spec File |
|----------|------|----------|--------|-----------|
| ASSET-001 | [name] | [category] | Needed | design/assets/specs/[target]-assets.md |

マニフェストがすでに存在する場合は、新しいコンテキストブロックを追加します。このターゲットの再実行時は、2 つ目のブロックを追加するのではなく、既存のブロックに新しい行を追加し、進捗サマリーの件数を更新します。

「design/assets/asset-manifest.md を更新してもよいですか？」と尋ねます。

---

フェーズ 6：終了

AskUserQuestion を使用します：

• プロンプト："[target] のアセット仕様が完了しました。次は何をしますか？"
• オプション：
  • [A] 別のシステムの仕様を作成 — /asset-spec system:[next-system]
  • [B] レベルの仕様を作成 — /asset-spec level:[level-name]
  • [C] キャラクターの仕様を作成 — /asset-spec character:[character-name]
  • [D] /asset-audit を実行 — 納品されたアセットを仕様に照らして検証
  • [E] ここで終了

---

アセット ID の割り当て

アセット ID はコンテキストごとではなく、プロジェクト全体を通して連番で割り当てます。ID を割り当てる前にマニフェストを読み、現在の最大番号を確認してください：

Grep pattern="ASSET-" path="design/assets/asset-manifest.md"

新しいアセットは ASSET-[highest + 1] から開始します。これにより、ID がプロジェクト全体で安定し、一意になります。

マニフェストがまだない場合は、ASSET-001 から開始します。

---

共有アセットプロトコル

アセットの仕様を作成する前に、別のコンテキストの仕様に同等のアセットがすでに存在するか確認してください：

• 共通の UI 要素（ヘルスバー、スコア表示など）は、複数のシステムで共有されることがよくあります
• 汎用的な環境小物は、複数のレベルに登場する場合があります
• キャラクターの VFX（ヒット時の火花、死亡エフェクトなど）は、色違いのバリエーションを加えた基本仕様を再利用する場合があります

一致するアセットが見つかった場合：重複を作成せず、既存の ASSET-ID を参照してください。マニフェストの「参照元」列に共有用途を記載します。

「ASSET-012（汎用ヒット火花）は、Combat システム向けにすでに仕様が作成されています。Tower Defense でも再利用し、参照元に tower-defense を追加します。」

---

エラー復旧プロトコル

起動したエージェントのいずれかが BLOCKED を返すか、完了できない場合：

1. ただちに通知します：「[AgentName]：BLOCKED — [reason]」
2. lean モードの場合、または technical-artist がブロックされた場合：art-director の出力のみで続行し、技術的な制約が検証されていないことを明記します
3. solo モードの場合、または art-director がブロックされた場合：アートバイブルのルールに基づいて説明を作成し、「アートディレクター未確認 — 制作前にアートバイブルとの照合が必要」と記載します
4. 必ず部分的な仕様を作成します — エージェントが 1 つブロックされても、作業を破棄してはいけません

---

コラボレーションプロトコル

collaborative モード（デフォルト）で適用されます。 guided モードと autonomous モードについては、.claude/docs/automation-modes.md を参照してください。以下のルールはコラボレーションモードで必要な事項を説明したもので、すべてのモードに共通する動作ではありません。

すべてのフェーズで次の手順に従います：特定 → 確認 → 生成 → レビュー → 承認 → 書き込み

• アセット一覧をユーザーに確認する前に、アセットの仕様を作成してはいけません
• 仕様は必ずアートバイブルに準拠させます — アートバイブルに矛盾する仕様は誤りです
• エージェント間の意見の相違はすべて明らかにします — どれか 1 つを黙って選んではいけません
• 明示的な承認を得てから仕様ファイルを書き込みます
• 仕様を書き込んだら、ただちにマニフェストを更新します

---

推奨される次の手順

• /asset-spec [next-context] を実行して、残りのシステム、レベル、キャラクターの仕様作成を続けます
• /asset-audit を実行して、納品されたアセットを記述済みの仕様に照らして検証し、不足や不一致を特定します