spec-runner 1.5.0 → 1.7.0

package/bin/spec-runner-installer.js

@@ -25,15 +25,13 @@ const DEST_GITHUB_DIR = path.join(CWD, ".github");
 
 const FORCE = process.env.SPEC_RUNNER_FORCE === "1";
 const TARGET = (process.env.SPEC_RUNNER_TARGET || "").trim().toLowerCase();
-const MODE = (process.env.SPEC_RUNNER_MODE || "").trim().toLowerCase();
-const ARCH_STATUS = (process.env.SPEC_RUNNER_ARCH_STATUS || "").trim().toLowerCase();
 
 const TEMPLATE_ROOT = path.join(PKG_DIR, "spec-runner", "templates");
 const CLAUDE_TEMPLATE_DIR = path.join(TEMPLATE_ROOT, ".claude");
 const COPILOT_TEMPLATE_DIR = path.join(TEMPLATE_ROOT, ".github");
 
 function parseArgs(argv) {
-  const out = { target: "", mode: "", archStatus: "" };
+  const out = { target: "" };
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i];
     if (a === "--target" && i + 1 < argv.length) {
@@ -45,24 +43,6 @@ function parseArgs(argv) {
       out.target = a.slice("--target=".length).trim().toLowerCase();
       continue;
     }
-    if (a === "--mode" && i + 1 < argv.length) {
-      out.mode = String(argv[i + 1] || "").trim().toLowerCase();
-      i += 1;
-      continue;
-    }
-    if (a.startsWith("--mode=")) {
-      out.mode = a.slice("--mode=".length).trim().toLowerCase();
-      continue;
-    }
-    if (a === "--arch-status" && i + 1 < argv.length) {
-      out.archStatus = String(argv[i + 1] || "").trim().toLowerCase();
-      i += 1;
-      continue;
-    }
-    if (a.startsWith("--arch-status=")) {
-      out.archStatus = a.slice("--arch-status=".length).trim().toLowerCase();
-      continue;
-    }
   }
   return out;
 }
@@ -196,48 +176,6 @@ function promptTargetInteractive() {
   return "claude";
 }
 
-function normalizeMode(t) {
-  if (!t) return "";
-  const x = String(t).trim().toLowerCase();
-  if (x === "new" || x === "n") return "new";
-  if (x === "existing" || x === "exist" || x === "e") return "existing";
-  return "";
-}
-
-function promptModeInteractive() {
-  if (!isTTY()) return "new";
-
-  const ans = promptLine(
-    "\nプロジェクトの状態を選んでください:\n" +
-    "  1) 新規プロジェクト\n" +
-    "  2) 既存プロジェクト\n" +
-    "選択 [1/2] : "
-  );
-  if (ans === "2") return "existing";
-  return "new";
-}
-
-function normalizeArchStatus(t) {
-  if (!t) return "";
-  const x = String(t).trim().toLowerCase();
-  if (x === "undecided" || x === "u") return "undecided";
-  if (x === "decided" || x === "d") return "decided";
-  return "";
-}
-
-function promptArchStatusInteractive() {
-  if (!isTTY()) return "undecided";
-
-  const ans = promptLine(
-    "\nアーキテクチャの状態を選んでください:\n" +
-    "  1) 未決定（これから決める）\n" +
-    "  2) 既に決まっている\n" +
-    "選択 [1/2] : "
-  );
-  if (ans === "2") return "decided";
-  return "undecided";
-}
-
 function archivePathFor(destPath, archiveRoot) {
   // destPath は CWD の配下を想定
   const rel = path.relative(CWD, destPath);
@@ -390,21 +328,12 @@ function printBanner() {
   console.log("");
 }
 
-function printNextSteps(archStatus) {
+function printNextSteps() {
   console.log("─────────────────────────────────────────");
-  if (archStatus === "decided") {
-    console.log("次のステップ:");
-    console.log("");
-    console.log("  1. .spec-runner/architecture/architecture.yaml を用意してください。");
-    console.log("     （既に決まっているアーキテクチャを記述）");
-    console.log("");
-    console.log("  2. Claude Code を開いて /architecture-skill-development を実行してください。");
-  } else {
-    console.log("次のステップ:");
-    console.log("");
-    console.log("  Claude Code を開いて、作りたいものを伝えてください。");
-    console.log("  セットアップが自動で始まります。");
-  }
+  console.log("次のステップ:");
+  console.log("");
+  console.log("  Claude Code を開いて、作りたいものを伝えてください。");
+  console.log("  セットアップが自動で始まります。");
   console.log("─────────────────────────────────────────");
 }
 
@@ -415,13 +344,6 @@ function main() {
   let target = normalizeTarget(args.target) || normalizeTarget(TARGET);
   if (!target) target = promptTargetInteractive();
 
-  let mode = normalizeMode(args.mode) || normalizeMode(MODE);
-  if (!mode) mode = promptModeInteractive();
-
-  let archStatus = normalizeArchStatus(args.archStatus) || normalizeArchStatus(ARCH_STATUS);
-  if (!archStatus && mode === "new") archStatus = promptArchStatusInteractive();
-  if (!archStatus) archStatus = "undecided";
-
   const ts = FORCE ? isoTimestampSafe() : null;
   const archiveRoot = ts ? path.join(CWD, ".spec-runner", "archive", ts) : null;
 
@@ -466,7 +388,7 @@ function main() {
   else if (target === "copilot") console.log("完了: .github/ を導入しました。");
   else console.log("完了: .claude/ と .github/ を導入しました。");
   console.log("");
-  printNextSteps(archStatus);
+  printNextSteps();
 }
 
 main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-runner",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "docs を正本にした開発運用ハーネスを Claude / Copilot に導入する",
   "license": "MIT",
   "bin": {

package/spec-runner/templates/.claude/rules/agent-delegation.md

@@ -14,6 +14,7 @@ description: メインエージェントがサブエージェントへ委任す
 | コーディング規約チェック | `@review-code` | 実装・修正が完了したとき |
 | テスト実行＋失敗分析 | `@run-tests` | 実装・修正が完了したとき |
 | 変更の影響範囲調査 | `@analyze-impact` | design-change で影響範囲を洗うとき |
+| エラー・技術的な詰まりの調査 | サブエージェント（WebSearch） | 解決策が不明なとき。`.spec-runner/references/resources.md` に記載された URL を起点に検索する |
 
 ## 並行起動
 

package/spec-runner/templates/.claude/skills/architecture-definition/SKILL.md

@@ -31,7 +31,14 @@ Phase 5: architecture-skill-development へ自動移行
    | `ddd` | 複雑なビジネスドメインがある。集約・境界コンテキストで設計する必要がある |
    | `layered` | CRUD 中心またはビジネスロジックがシンプル。UC・サービス層で設計すれば十分 |
 
-6. 使用する AI 連携を確認する
+6. フロントエンドの有無を確認する
+
+   | 値 | 基準 |
+   |----|------|
+   | `true` | Web UI・モバイル画面がある |
+   | `false` | API・バックエンドのみ |
+
+7. 使用する AI 連携を確認する
 
    | 連携 | フォルダ |
    |------|---------|
@@ -39,7 +46,7 @@ Phase 5: architecture-skill-development へ自動移行
    | `github` | `.github/`（GitHub Copilot） |
    | 両方 | `.claude/` と `.github/` |
 
-7. ユーザーに確認・承認を得る
+8. ユーザーに確認・承認を得る
 
 ## Phase 2: フォルダ構造の決定
 
@@ -65,6 +72,7 @@ Phase 5: architecture-skill-development へ自動移行
 2. 最低限、以下を構造化する
    - **integrations**: Phase 1 で確認した連携（`[claude]` / `[github]` / `[claude, github]`）
    - **style**: Phase 1 で選択したスタイル（`ddd` / `layered`）
+   - **has_frontend**: Phase 1 で確認したフロントエンドの有無（`true` / `false`）
    - **folder_structure**: Phase 2 で決定した構造（`src/` / `tests/` / `docs/` など）
    - domain_structure（style: ddd のときのみ）
    - runtime_units

package/spec-runner/templates/.claude/skills/architecture-skill-development/SKILL.md

@@ -37,16 +37,19 @@ Phase 6: セットアップ専用 skill のアーカイブ提案
 2. 常時守る約束は rule にする
 3. 毎回コピーする設計書は template にする
 
-### seed の選択
+### プロジェクト専用スキルの作成
 
-`architecture.yaml` の `style` を読み、使う seed を決める。
+`architecture.yaml` の `style` に応じた seed（`ddd-seed` / `simple-seed`）がインストール済みの場合、どのように専用スキルを作るかをユーザーに確認する。
 
-| style | 使う seed | 説明 |
-|-------|----------|------|
-| `ddd` | `ddd-seed` | ドメイン層（集約・値オブジェクト）を持つ DDD 向けフロー |
-| `layered` | `simple-seed` | ドメイン層を持たない UC・サービス層中心のフロー |
+| 選択肢 | 内容 |
+|--------|------|
+| 新規に作る | `harness-format.md` を基に、このプロジェクトのフローをゼロから記述する |
+| リネームだけ | seed ファイルをプロジェクト専用名に変更する |
+| リネーム＋構成変更 | seed をリネームしたうえでフェーズ構成・テンプレートパスをプロジェクトの実態に合わせて書き換える |
 
-選んだ seed の SKILL.md をコピーし、フェーズ構成・テンプレートパス・用語をこのプロジェクトの実態に合わせて書き換えたプロジェクト専用 skill を作る（Phase 1 は完了済みのため削除する。元の seed はアーカイブ候補とする）。
+seed が存在しない場合は「新規に作る」で進める。
+
+`has_frontend: true` の場合は、UC ファイルに画面レイアウトセクションを含める旨を専用スキルに明記する。
 
 4. ユーザーに確認・承認を得る
 
@@ -86,6 +89,19 @@ Phase 6: セットアップ専用 skill のアーカイブ提案
 3. **言語・型固有ルール**: `<your-language-and-type-rules>` を言語・フレームワークに合わせた具体的なルールに書き換える
 4. **プロジェクト構造**: `<your-project-structure>` を `folder_structure` の実際のディレクトリ構成に書き換える
 
+### リファレンス URL の登録
+
+`.spec-runner/references/resources.md` に、このプロジェクトで使う公式ドキュメントの URL を登録する。
+
+1. ユーザーに以下を確認する:
+   - 言語・フレームワーク・ツールの公式ドキュメント URL
+   - 参考にしているサンプルリポジトリ・リファレンス実装
+   - API 仕様（OpenAPI など）
+   - 社内 Wiki・Notion などの内部ドキュメント
+   - その他ベストプラクティス記事・移行ガイドなど
+2. 教えてもらった情報を名前・カテゴリとともに `.spec-runner/references/resources.md` の該当テーブルに書き込む
+3. ユーザーが追加を終えたら次へ進む
+
 ### その他の基盤 skill
 
 同様のプレースホルダーや汎用記述が他の skill にあれば、同じ要領で書き換える。
@@ -107,8 +123,7 @@ Phase 6: セットアップ専用 skill のアーカイブ提案
 |---|---|
 | `architecture-definition` | 新規プロジェクト初期化専用。アーキテクチャ確定後は不要 |
 | `existing-project-to-docs` | 既存プロジェクト取り込み専用。docs 生成後は不要 |
-| `ddd-seed` | style: ddd で seed 使用後は不要。ただし `architecture-definition` も同時アーカイブする場合のみ `templates/01_要件定義/` を削除可 |
-| `simple-seed` | style: layered で seed 使用後は不要 |
+| `ddd-seed` / `simple-seed` | プロジェクト専用スキル作成後は不要 |
 | `architecture-skill-development`（このファイル自身） | project 専用 skill が安定したら不要。アーキテクチャ大変更時は再利用可 |
 
 ### 手順
@@ -118,7 +133,7 @@ Phase 6: セットアップ専用 skill のアーカイブ提案
 3. 必要であれば削除前にバックアップ先をユーザーに伝える
 4. `.spec-runner/` の不要ファイルも整理する
    - `intake/current-system-inventory.md` — docs に昇格済みなら削除してよい
-   - `architecture/architecture.yaml` — project 専用 skill が完成し、参照不要になったら削除してよい
+   - `architecture/architecture.yaml` — **削除しない**。設計変更のたびに最新状態を保つ。プロジェクトの全体像を把握するための正本として使い続ける
    - `scripts/scan.js` — **削除しない**。`@analyze-impact` が常時依存しているため
 5. `CLAUDE.md` を更新する
    - 「初回自動起動」セクション（spec-runner インストール時に生成されたもの）を削除する

package/spec-runner/templates/.claude/skills/ddd-seed/SKILL.md

@@ -5,6 +5,18 @@ description: UC/DDD 駆動の docs 正本開発フローの種。新規プロジ
 
 # ddd-seed
 
+## 前提: architecture.yaml の読み込み
+
+開始前に `.spec-runner/architecture/architecture.yaml` を読み、以下を確認する:
+
+| キー | 用途 |
+|------|------|
+| `style` | このスキル（`ddd`）が適切かを確認 |
+| `has_frontend` | `true` なら UC ファイルに「画面レイアウト」セクションを含める |
+| `folder_structure` | `maps_to` パスの基準として参照する |
+
+設計フェーズで新たな方針・コンポーネントが確定したら、都度 architecture.yaml を最新状態に保つ。
+
 ## 全体フロー
 
 ```
@@ -21,6 +33,7 @@ Phase 5: TDD → 実装
 - 詳細設計は `01_ドメイン/` `02_ユースケース/` `03_DB・外部サービス/` の 3 層で構成する
 - ドメインを先に設計し、UC はドメインを参照する形で書く。ドメインの中に UC は入れない
 - `maps_to` は必ず設定する。パス推定に頼らない
+- 実装ファイルのパスは UC ドキュメント本文に書かない。`maps_to` ヘッダーで管理する
 - ユーザー承認なしに次フェーズへ進めない
 
 ## Phase 1: 要件定義
@@ -91,6 +104,8 @@ docs/03_詳細設計/01_ドメイン/
 
 テンプレート: `templates/03_詳細設計/02_ユースケース/UC-{日本語名}.md`
 
+> `has_frontend: true` の場合は各 UC ファイルに「画面レイアウト」セクションを含める。`false` なら削除する。
+
 ```
 docs/03_詳細設計/02_ユースケース/
   UC-{日本語名}.md

package/spec-runner/templates/.claude/skills/ddd-seed/templates/02_/346/246/202/350/246/201/350/250/255/350/250/210//343/203/246/343/203/274/343/202/271/343/202/261/343/203/274/343/202/271/344/270/200/350/246/247.md

@@ -10,6 +10,16 @@ spec_runner:
 
 # ユースケース一覧
 
+<!-- カテゴリは機能領域や画面単位で分ける。例: 認証、ユーザー管理、商品管理 など -->
+
+## {カテゴリ名}
+
+| UC ID | UC名 | 種別 | 概要 |
+|-------|------|------|------|
+| UC-{番号} | {UC名} | Command / Query | {概要} |
+
+## {カテゴリ名}
+
 | UC ID | UC名 | 種別 | 概要 |
 |-------|------|------|------|
 | UC-{番号} | {UC名} | Command / Query | {概要} |

package/spec-runner/templates/.claude/skills/ddd-seed/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/02_/343/203/246/343/203/274/343/202/271/343/202/261/343/203/274/343/202/271/UC-{/346/227/245/346/234/254/350/252/236/345/220/215}.md

@@ -48,6 +48,21 @@ sequenceDiagram
 |------------|---------|------|
 | {エラーケース} | {発生条件} | {対応} |
 
+## 画面レイアウト
+
+> `has_frontend: true` のときのみ記載する。不要なら削除する。
+
+- 画面名: {画面名}
+- 遷移元: {前の画面 or -}
+- 遷移先: {次の画面 or -}
+
+```
+{画面レイアウト概要 — ASCII art / Markdown テーブルで表現}
+```
+
+- 主要 UI 要素:
+  - {入力フォーム・ボタン・一覧表示など}
+
 ## テスト観点
 
 - {正常系の観点}

package/spec-runner/templates/.claude/skills/design-change/SKILL.md

@@ -10,6 +10,18 @@ description: 既存機能の変更を docs 正本で進めるフローガイド
 影響範囲のチェックリストは `references/影響範囲チェックリスト.md` を参照する。
 ADR テンプレートは `templates/90_ADR/ADRテンプレート.md` を使用する。
 
+## 前提: architecture.yaml の読み込み
+
+開始前に `.spec-runner/architecture/architecture.yaml` を読み、以下を確認する:
+
+| キー | 用途 |
+|------|------|
+| `style` | Phase 4/5 のフォルダパス・設計順序を決定 |
+| `has_frontend` | UC 修正時に「画面レイアウト」セクションの要否を判断 |
+| `folder_structure` | 影響ドキュメントのパス確認に使用 |
+
+設計変更によって方針・構成に変化があった場合は、architecture.yaml も合わせて更新する。
+
 ## 全体フロー
 
 ```

package/spec-runner/templates/.claude/skills/simple-seed/SKILL.md

@@ -5,6 +5,18 @@ description: レイヤードアーキテクチャ / CRUD 中心のプロジェ
 
 # simple-seed
 
+## 前提: architecture.yaml の読み込み
+
+開始前に `.spec-runner/architecture/architecture.yaml` を読み、以下を確認する:
+
+| キー | 用途 |
+|------|------|
+| `style` | このスキル（`layered`）が適切かを確認 |
+| `has_frontend` | `true` なら UC ファイルに「画面レイアウト」セクションを含める |
+| `folder_structure` | `maps_to` パスの基準として参照する |
+
+設計フェーズで新たな方針・コンポーネントが確定したら、都度 architecture.yaml を最新状態に保つ。
+
 ## 全体フロー
 
 ```
@@ -20,6 +32,7 @@ Phase 5: TDD → 実装
 - docs は正本とし、各ドキュメントに `spec_runner`ヘッダーを付ける
 - 詳細設計は `01_ユースケース/` `02_DB・外部サービス/` の 2 層で構成する
 - `maps_to` は必ず設定する。パス推定に頼らない
+- 実装ファイルのパスは UC ドキュメント本文に書かない。`maps_to` ヘッダーで管理する
 - ユーザー承認なしに次フェーズへ進めない
 
 ## Phase 1: 要件定義
@@ -69,6 +82,8 @@ UC → DB・外部サービス の順に設計する。
 
 テンプレート: `templates/03_詳細設計/01_ユースケース/UC-{日本語名}.md`
 
+> `has_frontend: true` の場合は各 UC ファイルに「画面レイアウト」セクションを含める。`false` なら削除する。
+
 ```
 docs/03_詳細設計/01_ユースケース/
   UC-{日本語名}.md

package/spec-runner/templates/.claude/skills/simple-seed/templates/02_/346/246/202/350/246/201/350/250/255/350/250/210//343/203/246/343/203/274/343/202/271/343/202/261/343/203/274/343/202/271/344/270/200/350/246/247.md

@@ -10,6 +10,16 @@ spec_runner:
 
 # ユースケース一覧
 
+<!-- カテゴリは機能領域や画面単位で分ける。例: 認証、ユーザー管理、商品管理 など -->
+
+## {カテゴリ名}
+
+| UC ID | UC名 | 種別 | 概要 |
+|-------|------|------|------|
+| UC-{番号} | {UC名} | Command / Query | {概要} |
+
+## {カテゴリ名}
+
 | UC ID | UC名 | 種別 | 概要 |
 |-------|------|------|------|
 | UC-{番号} | {UC名} | Command / Query | {概要} |

package/spec-runner/templates/.claude/skills/simple-seed/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/01_/343/203/246/343/203/274/343/202/271/343/202/261/343/203/274/343/202/271/UC-{/346/227/245/346/234/254/350/252/236/345/220/215}.md

@@ -46,6 +46,21 @@ sequenceDiagram
 |------------|---------|------|
 | {エラーケース} | {発生条件} | {対応} |
 
+## 画面レイアウト
+
+> `has_frontend: true` のときのみ記載する。不要なら削除する。
+
+- 画面名: {画面名}
+- 遷移元: {前の画面 or -}
+- 遷移先: {次の画面 or -}
+
+```
+{画面レイアウト概要 — ASCII art / Markdown テーブルで表現}
+```
+
+- 主要 UI 要素:
+  - {入力フォーム・ボタン・一覧表示など}
+
 ## テスト観点
 
 - {正常系の観点}

package/spec-runner/templates/.github/skills/architecture-definition/SKILL.md

@@ -31,7 +31,14 @@ Phase 5: architecture-skill-development へ自動移行
    | `ddd` | 複雑なビジネスドメインがある。集約・境界コンテキストで設計する必要がある |
    | `layered` | CRUD 中心またはビジネスロジックがシンプル。UC・サービス層で設計すれば十分 |
 
-6. 使用する AI 連携を確認する
+6. フロントエンドの有無を確認する
+
+   | 値 | 基準 |
+   |----|------|
+   | `true` | Web UI・モバイル画面がある |
+   | `false` | API・バックエンドのみ |
+
+7. 使用する AI 連携を確認する
 
    | 連携 | フォルダ |
    |------|---------|
@@ -39,7 +46,7 @@ Phase 5: architecture-skill-development へ自動移行
    | `github` | `.github/`（GitHub Copilot） |
    | 両方 | `.claude/` と `.github/` |
 
-7. ユーザーに確認・承認を得る
+8. ユーザーに確認・承認を得る
 
 ## Phase 2: フォルダ構造の決定
 
@@ -65,6 +72,7 @@ Phase 5: architecture-skill-development へ自動移行
 2. 最低限、以下を構造化する
    - **integrations**: Phase 1 で確認した連携（`[claude]` / `[github]` / `[claude, github]`）
    - **style**: Phase 1 で選択したスタイル（`ddd` / `layered`）
+   - **has_frontend**: Phase 1 で確認したフロントエンドの有無（`true` / `false`）
    - **folder_structure**: Phase 2 で決定した構造（`src/` / `tests/` / `docs/` など）
    - domain_structure（style: ddd のときのみ）
    - runtime_units

package/spec-runner/templates/.github/skills/architecture-skill-development/SKILL.md

@@ -37,16 +37,19 @@ Phase 6: セットアップ専用 skill のアーカイブ提案
 2. 常時守る約束は rule にする
 3. 毎回コピーする設計書は template にする
 
-### seed の選択
+### プロジェクト専用スキルの作成
 
-`architecture.yaml` の `style` を読み、使う seed を決める。
+`architecture.yaml` の `style` に応じた seed（`ddd-seed` / `simple-seed`）がインストール済みの場合、どのように専用スキルを作るかをユーザーに確認する。
 
-| style | 使う seed | 説明 |
-|-------|----------|------|
-| `ddd` | `ddd-seed` | ドメイン層（集約・値オブジェクト）を持つ DDD 向けフロー |
-| `layered` | `simple-seed` | ドメイン層を持たない UC・サービス層中心のフロー |
+| 選択肢 | 内容 |
+|--------|------|
+| 新規に作る | `harness-format.md` を基に、このプロジェクトのフローをゼロから記述する |
+| リネームだけ | seed ファイルをプロジェクト専用名に変更する |
+| リネーム＋構成変更 | seed をリネームしたうえでフェーズ構成・テンプレートパスをプロジェクトの実態に合わせて書き換える |
 
-選んだ seed の SKILL.md をコピーし、フェーズ構成・テンプレートパス・用語をこのプロジェクトの実態に合わせて書き換えたプロジェクト専用 skill を作る（Phase 1 は完了済みのため削除する。元の seed はアーカイブ候補とする）。
+seed が存在しない場合は「新規に作る」で進める。
+
+`has_frontend: true` の場合は、UC ファイルに画面レイアウトセクションを含める旨を専用スキルに明記する。
 
 4. ユーザーに確認・承認を得る
 
@@ -86,6 +89,19 @@ Phase 6: セットアップ専用 skill のアーカイブ提案
 3. **言語・型固有ルール**: `<your-language-and-type-rules>` を言語・フレームワークに合わせた具体的なルールに書き換える
 4. **プロジェクト構造**: `<your-project-structure>` を `folder_structure` の実際のディレクトリ構成に書き換える
 
+### リファレンス URL の登録
+
+`.spec-runner/references/resources.md` に、このプロジェクトで使う公式ドキュメントの URL を登録する。
+
+1. ユーザーに以下を確認する:
+   - 言語・フレームワーク・ツールの公式ドキュメント URL
+   - 参考にしているサンプルリポジトリ・リファレンス実装
+   - API 仕様（OpenAPI など）
+   - 社内 Wiki・Notion などの内部ドキュメント
+   - その他ベストプラクティス記事・移行ガイドなど
+2. 教えてもらった情報を名前・カテゴリとともに `.spec-runner/references/resources.md` の該当テーブルに書き込む
+3. ユーザーが追加を終えたら次へ進む
+
 ### その他の基盤 skill
 
 同様のプレースホルダーや汎用記述が他の skill にあれば、同じ要領で書き換える。
@@ -107,8 +123,7 @@ Phase 6: セットアップ専用 skill のアーカイブ提案
 |---|---|
 | `architecture-definition` | 新規プロジェクト初期化専用。アーキテクチャ確定後は不要 |
 | `existing-project-to-docs` | 既存プロジェクト取り込み専用。docs 生成後は不要 |
-| `ddd-seed` | style: ddd で seed 使用後は不要。ただし `architecture-definition` も同時アーカイブする場合のみ `templates/01_要件定義/` を削除可 |
-| `simple-seed` | style: layered で seed 使用後は不要 |
+| `ddd-seed` / `simple-seed` | プロジェクト専用スキル作成後は不要 |
 | `architecture-skill-development`（このファイル自身） | project 専用 skill が安定したら不要。アーキテクチャ大変更時は再利用可 |
 
 ### 手順
@@ -118,7 +133,7 @@ Phase 6: セットアップ専用 skill のアーカイブ提案
 3. 必要であれば削除前にバックアップ先をユーザーに伝える
 4. `.spec-runner/` の不要ファイルも整理する
    - `intake/current-system-inventory.md` — docs に昇格済みなら削除してよい
-   - `architecture/architecture.yaml` — project 専用 skill が完成し、参照不要になったら削除してよい
+   - `architecture/architecture.yaml` — **削除しない**。設計変更のたびに最新状態を保つ。プロジェクトの全体像を把握するための正本として使い続ける
    - `scripts/scan.js` — **削除しない**。`@analyze-impact` が常時依存しているため
 5. `CLAUDE.md` を更新する
    - 「初回自動起動」セクション（spec-runner インストール時に生成されたもの）を削除する

package/spec-runner/templates/.github/skills/ddd-seed/SKILL.md

@@ -5,6 +5,18 @@ description: UC/DDD 駆動の docs 正本開発フローの種。新規プロジ
 
 # ddd-seed
 
+## 前提: architecture.yaml の読み込み
+
+開始前に `.spec-runner/architecture/architecture.yaml` を読み、以下を確認する:
+
+| キー | 用途 |
+|------|------|
+| `style` | このスキル（`ddd`）が適切かを確認 |
+| `has_frontend` | `true` なら UC ファイルに「画面レイアウト」セクションを含める |
+| `folder_structure` | `maps_to` パスの基準として参照する |
+
+設計フェーズで新たな方針・コンポーネントが確定したら、都度 architecture.yaml を最新状態に保つ。
+
 ## 全体フロー
 
 ```
@@ -21,6 +33,7 @@ Phase 5: TDD → 実装
 - 詳細設計は `01_ドメイン/` `02_ユースケース/` `03_DB・外部サービス/` の 3 層で構成する
 - ドメインを先に設計し、UC はドメインを参照する形で書く。ドメインの中に UC は入れない
 - `maps_to` は必ず設定する。パス推定に頼らない
+- 実装ファイルのパスは UC ドキュメント本文に書かない。`maps_to` ヘッダーで管理する
 - ユーザー承認なしに次フェーズへ進めない
 
 ## Phase 1: 要件定義
@@ -91,6 +104,8 @@ docs/03_詳細設計/01_ドメイン/
 
 テンプレート: `templates/03_詳細設計/02_ユースケース/UC-{日本語名}.md`
 
+> `has_frontend: true` の場合は各 UC ファイルに「画面レイアウト」セクションを含める。`false` なら削除する。
+
 ```
 docs/03_詳細設計/02_ユースケース/
   UC-{日本語名}.md

package/spec-runner/templates/.github/skills/ddd-seed/templates/02_/346/246/202/350/246/201/350/250/255/350/250/210//343/203/246/343/203/274/343/202/271/343/202/261/343/203/274/343/202/271/344/270/200/350/246/247.md

@@ -10,6 +10,16 @@ spec_runner:
 
 # ユースケース一覧
 
+<!-- カテゴリは機能領域や画面単位で分ける。例: 認証、ユーザー管理、商品管理 など -->
+
+## {カテゴリ名}
+
+| UC ID | UC名 | 種別 | 概要 |
+|-------|------|------|------|
+| UC-{番号} | {UC名} | Command / Query | {概要} |
+
+## {カテゴリ名}
+
 | UC ID | UC名 | 種別 | 概要 |
 |-------|------|------|------|
 | UC-{番号} | {UC名} | Command / Query | {概要} |

package/spec-runner/templates/.github/skills/ddd-seed/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/02_/343/203/246/343/203/274/343/202/271/343/202/261/343/203/274/343/202/271/UC-{/346/227/245/346/234/254/350/252/236/345/220/215}.md

@@ -48,6 +48,21 @@ sequenceDiagram
 |------------|---------|------|
 | {エラーケース} | {発生条件} | {対応} |
 
+## 画面レイアウト
+
+> `has_frontend: true` のときのみ記載する。不要なら削除する。
+
+- 画面名: {画面名}
+- 遷移元: {前の画面 or -}
+- 遷移先: {次の画面 or -}
+
+```
+{画面レイアウト概要 — ASCII art / Markdown テーブルで表現}
+```
+
+- 主要 UI 要素:
+  - {入力フォーム・ボタン・一覧表示など}
+
 ## テスト観点
 
 - {正常系の観点}

package/spec-runner/templates/.github/skills/design-change/SKILL.md

@@ -10,6 +10,18 @@ description: 既存機能の変更を docs 正本で進めるフローガイド
 影響範囲のチェックリストは `references/影響範囲チェックリスト.md` を参照する。
 ADR テンプレートは `templates/90_ADR/ADRテンプレート.md` を使用する。
 
+## 前提: architecture.yaml の読み込み
+
+開始前に `.spec-runner/architecture/architecture.yaml` を読み、以下を確認する:
+
+| キー | 用途 |
+|------|------|
+| `style` | Phase 4/5 のフォルダパス・設計順序を決定 |
+| `has_frontend` | UC 修正時に「画面レイアウト」セクションの要否を判断 |
+| `folder_structure` | 影響ドキュメントのパス確認に使用 |
+
+設計変更によって方針・構成に変化があった場合は、architecture.yaml も合わせて更新する。
+
 ## 全体フロー
 
 ```

package/spec-runner/templates/.github/skills/simple-seed/SKILL.md

@@ -5,6 +5,18 @@ description: レイヤードアーキテクチャ / CRUD 中心のプロジェ
 
 # simple-seed
 
+## 前提: architecture.yaml の読み込み
+
+開始前に `.spec-runner/architecture/architecture.yaml` を読み、以下を確認する:
+
+| キー | 用途 |
+|------|------|
+| `style` | このスキル（`layered`）が適切かを確認 |
+| `has_frontend` | `true` なら UC ファイルに「画面レイアウト」セクションを含める |
+| `folder_structure` | `maps_to` パスの基準として参照する |
+
+設計フェーズで新たな方針・コンポーネントが確定したら、都度 architecture.yaml を最新状態に保つ。
+
 ## 全体フロー
 
 ```
@@ -20,6 +32,7 @@ Phase 5: TDD → 実装
 - docs は正本とし、各ドキュメントに `spec_runner`ヘッダーを付ける
 - 詳細設計は `01_ユースケース/` `02_DB・外部サービス/` の 2 層で構成する
 - `maps_to` は必ず設定する。パス推定に頼らない
+- 実装ファイルのパスは UC ドキュメント本文に書かない。`maps_to` ヘッダーで管理する
 - ユーザー承認なしに次フェーズへ進めない
 
 ## Phase 1: 要件定義
@@ -69,6 +82,8 @@ UC → DB・外部サービス の順に設計する。
 
 テンプレート: `templates/03_詳細設計/01_ユースケース/UC-{日本語名}.md`
 
+> `has_frontend: true` の場合は各 UC ファイルに「画面レイアウト」セクションを含める。`false` なら削除する。
+
 ```
 docs/03_詳細設計/01_ユースケース/
   UC-{日本語名}.md

package/spec-runner/templates/.github/skills/simple-seed/templates/02_/346/246/202/350/246/201/350/250/255/350/250/210//343/203/246/343/203/274/343/202/271/343/202/261/343/203/274/343/202/271/344/270/200/350/246/247.md

@@ -10,6 +10,16 @@ spec_runner:
 
 # ユースケース一覧
 
+<!-- カテゴリは機能領域や画面単位で分ける。例: 認証、ユーザー管理、商品管理 など -->
+
+## {カテゴリ名}
+
+| UC ID | UC名 | 種別 | 概要 |
+|-------|------|------|------|
+| UC-{番号} | {UC名} | Command / Query | {概要} |
+
+## {カテゴリ名}
+
 | UC ID | UC名 | 種別 | 概要 |
 |-------|------|------|------|
 | UC-{番号} | {UC名} | Command / Query | {概要} |

package/spec-runner/templates/.github/skills/simple-seed/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/01_/343/203/246/343/203/274/343/202/271/343/202/261/343/203/274/343/202/271/UC-{/346/227/245/346/234/254/350/252/236/345/220/215}.md

@@ -46,6 +46,21 @@ sequenceDiagram
 |------------|---------|------|
 | {エラーケース} | {発生条件} | {対応} |
 
+## 画面レイアウト
+
+> `has_frontend: true` のときのみ記載する。不要なら削除する。
+
+- 画面名: {画面名}
+- 遷移元: {前の画面 or -}
+- 遷移先: {次の画面 or -}
+
+```
+{画面レイアウト概要 — ASCII art / Markdown テーブルで表現}
+```
+
+- 主要 UI 要素:
+  - {入力フォーム・ボタン・一覧表示など}
+
 ## テスト観点
 
 - {正常系の観点}

package/spec-runner/templates/.spec-runner/references/resources.md

@@ -0,0 +1,46 @@
+# Resources
+
+エラーや調査が必要なときにサブエージェントが参照する外部リソース一覧。
+`architecture-skill-development` 実行時に登録する。
+
+## 言語・ランタイム
+
+| 名前 | URL |
+|------|-----|
+| {言語名} | {公式ドキュメントURL} |
+
+## フレームワーク・ライブラリ
+
+| 名前 | URL |
+|------|-----|
+| {フレームワーク名} | {公式ドキュメントURL} |
+
+## インフラ・ツール
+
+| 名前 | URL |
+|------|-----|
+| {ツール名} | {公式ドキュメントURL} |
+
+## サンプル・リファレンス実装
+
+| 名前 | URL |
+|------|-----|
+| {リポジトリ名} | {URL} |
+
+## API 仕様
+
+| 名前 | URL |
+|------|-----|
+| {API名} | {URL} |
+
+## 社内ドキュメント・Wiki
+
+| 名前 | URL |
+|------|-----|
+| {ドキュメント名} | {URL} |
+
+## その他（移行ガイド・ベストプラクティス記事など）
+
+| 名前 | URL |
+|------|-----|
+| {タイトル} | {URL} |