create-ai-project 1.21.0 → 1.22.1

package/.claude/skills-ja/project-context/references/template.md

@@ -0,0 +1,154 @@
+# プロジェクトコンテキスト セクションカタログ
+
+このファイルは `/project-inject` が利用するセクションカタログである。利用側エージェントは `SKILL.md` のみを読み込み、このファイルは更新操作時のみ読み込まれる。
+
+## セクション一覧
+
+| セクション | 採用ルール | ヒアリング質問の取得元 |
+|------------|-----------|------------------------|
+| プロジェクト概要 | 常に含める | このファイル（下記） |
+| ドメイン制約 | AIの判断を変えるルールが少なくとも1つある場合に含める | このファイル（下記） |
+| 開発フェーズ | フェーズがAIの動作を実質的に変える場合に含める（例: プロトタイプではテストひな型生成を抑制） | このファイル（下記） |
+| ディレクトリ規約 | リポジトリ構造から自明でないファイル配置ルールがある場合に含める | このファイル（下記） |
+| 外部リソース | プロジェクトがリポジトリ外のリソース（デザインソース、スキーマソース、シークレットストア、IaCソース等）に依存する場合に含める | `external-resources-{frontend,backend,api,infra}.md`（プロジェクトに該当するドメインのみ読み込む） |
+
+## セクション定義
+
+### プロジェクト概要
+
+**採用**: 常に。
+
+**ヒアリング**:
+- AskUserQuestion 1: 「このプロジェクトは何をするものか？（1〜2文）」
+- AskUserQuestion 2: 「どのドメインに属するか？」 一般的なカテゴリから具体的な選択肢例を提示する（例: 開発者ツール、金融、ヘルスケア、EC、社内プラットフォーム）。常に「その他」を含める。
+
+**出力構造**:
+```markdown
+## プロジェクト概要
+- **このプロジェクトが何をするか**: <1〜2文>
+- **ドメイン**: <ドメイン>
+```
+
+### ドメイン制約
+
+**採用**: AIが無視するとバグまたはコンプライアンス違反を引き起こす制約が少なくとも1つある場合に含める。
+
+**ヒアリング**:
+- AskUserQuestion: 「このプロジェクトでAIが従うべきドメイン固有のルールはあるか？」 選択肢: 「はい、列挙する」 / 「いいえ、ドメイン制約は該当しない」。
+- 「はい」の場合: 各ルール（最大3件）について、ルール文と測定可能なチェックを収集する。pass/fail で評価できる文のみを採用し、主観的な表現は測定可能な形に書き換える（例: 「PIIに気をつける」を「ログ出力は匿名化された患者IDを使用」に変換）。
+- 例示の言い回しは「プロジェクト概要」で得たドメインに合わせる（例: 金融なら「全ての金額変更操作で監査ログを追記」、開発者ツールなら「生成コードは lockfile コマンドが呼び出せる状態を保つ」）。
+
+**出力構造**（制約が0件の場合はセクションごと省略）:
+```markdown
+## ドメイン制約
+1. <測定可能なルール 1>
+2. <測定可能なルール 2>
+3. <測定可能なルール 3>
+```
+
+### 開発フェーズ
+
+**採用**: フェーズがAIの動作を実質的に変える場合に含める。フェーズ間で動作が同一の場合はスキップする。
+
+**ヒアリング**:
+- AskUserQuestion: 「このプロジェクトはどのフェーズか？」 選択肢: 「プロトタイプ」、「本番開発」、「運用中」、「フェーズ間で意味のある違いはない」。
+- 「フェーズ間で意味のある違いはない」の場合: セクションごと省略する。
+
+**出力構造**:
+```markdown
+## 開発フェーズ
+- **フェーズ**: <プロトタイプ | 本番開発 | 運用中>
+```
+
+### ディレクトリ規約
+
+**採用**: リポジトリ構造から自明でない（コントリビュータがツリーを見て誤推測する）ファイル配置ルールが少なくとも1つある場合に含める。
+
+**ヒアリング**:
+- AskUserQuestion: 「AIが従うべきファイル配置ルールはあるか？」 選択肢: 「はい」 / 「いいえ」。
+- 「はい」の場合: 各ルールをトリガーと配置先を1行で明示する形で収集する（例: 「作業中の一時ファイル: `./tmp/` 配下に配置し、完了時に削除」）。
+
+**出力構造**（ルールが0件の場合はセクションごと省略）:
+```markdown
+## ディレクトリ規約
+- <ルール 1>
+- <ルール 2>
+```
+
+### 外部リソース
+
+**採用**: 選択されたドメインのうち少なくとも1つに該当する軸が存在するか、自己申告の追加項目が存在する場合にセクションを含める。それ以外の場合はセクションごと省略する。
+
+**ヒアリングのルーティング**:
+- AskUserQuestion: 「このプロジェクトに該当する外部リソースのドメインはどれか？」 マルチセレクト選択肢:
+  - フロントエンド（デザインソース、デザインシステム、ガイドライン、表示検証環境）
+  - バックエンド（データベーススキーマ、マイグレーション履歴、シークレットストア、バックグラウンドジョブ）
+  - APIコントラクト（スキーマソース、モック、認証、スキーマ変更プロセス）
+  - インフラストラクチャ（IaCソース、環境設定、インフラのシークレット、デプロイトリガー）
+  - 該当なし
+- 選択された各ドメインについて、下記の対応表に従って参照ファイルを読み込み、そのヒアリングプロトコルを実行する。
+
+**ドメインとファイルの対応**:
+| ドメイン（ユーザー向けラベル） | 参照ファイル |
+|--------------------------------|--------------|
+| フロントエンド | `external-resources-frontend.md` |
+| バックエンド | `external-resources-backend.md` |
+| APIコントラクト | `external-resources-api.md` |
+| インフラストラクチャ | `external-resources-infra.md` |
+
+**ヒアリングプロトコル**（ドメイン参照ファイル単位）: 各参照ファイルは構造化された軸群と自己申告フェーズを定義する。構造化フェーズは軸ごとに AskUserQuestion を 1 回行い、「該当なし」を明示的な選択肢として提示する。自己申告フェーズは構造化フェーズの結果に関わらず必ず 1 回実行し、自由記述の追加項目を収集する。
+
+**軸ごとの出力スキーマ（3 フィールド）**:
+```markdown
+#### <軸名>
+- ソースタイプ: <ユーザーが選択した AskUserQuestion 選択肢の原文>
+- 場所: <URL | ファイルパス | サービス名 / パッケージ名>
+- アクセス方法: <WebFetch | ファイル読み込み | MCP サーバー名 | CLI コマンド | 手動手順>
+```
+
+**軸出力ルール**:
+
+1. **軸出力はスキーマを埋められるかで決まる。** ユーザーの選択肢が **場所** と **アクセス方法** の具体値が確定する外部リソースを指す場合、軸ブロックを出力する。次の選択肢では当該軸の出力行を 0 行にする：
+   - リソース不在を表明する選択肢: 「該当なし」、「<リソース>なし」、「<リソース>は不要」、「文書化された<リソース>なし」、「アドホックな<リソース>」、「手動<プロセス>（<リソース>なし）」。
+   - その他の選択肢のうち、場所とアクセス方法の値が空になるもの。
+
+2. **同一軸内の複数インスタンス**（例: primary・analytics の DB が併存、CSS とアクセシビリティのガイドラインが別ファイル）— 識別接尾辞を付けて軸ブロックを繰り返す:
+   ```markdown
+   #### データベーススキーマソース — Primary
+   - ソースタイプ: リポジトリ内のスキーマファイル
+   - 場所: prisma/schema.prisma
+   - アクセス方法: ファイル読み込み
+
+   #### データベーススキーマソース — Analytics
+   - ソースタイプ: ライブ DB を introspect する DB MCP サーバー
+   - 場所: bigquery-prod
+   - アクセス方法: MCP サーバー `bigquery`
+   ```
+
+3. **軸間の参照**（例: 同一のシークレットストアがバックエンドとインフラストラクチャの両方に登場）— 1 回目の出現が正本フィールドを保持し、2 回目の出現はそこへの参照として出力する:
+   ```markdown
+   #### インフラのシークレット
+   - ソースタイプ: シークレットマネージャーから IaC のデータルックアップで取得するシークレット
+   - 参照先: バックエンド > シークレットストア と同一ストア
+   - アクセス方法: <継承; 差異がある場合のみ記録>
+   ```
+
+**ドメインブロックの構造**:
+```markdown
+### <ドメイン>
+
+<軸ブロック群（カタログ順、上記ルールに従って出力）>
+
+#### 追加リソース
+
+<自己申告フェーズで項目が収集された場合のみ出力。同一ドメインブロック内の最後の該当軸の後に配置>
+- <ユーザーが記述した自由記述の説明>
+```
+
+## 出力組み立てルール
+
+ヒアリング完了後、呼び出し元コマンド（`/project-inject`）が指定する順序で設定済み `SKILL.md` を組み立てる。このファイルは各セクションの内容構造（上記）と、以下のセクション横断ルールを所有する：
+
+1. 省略対象のセクションは出力行を 0 行にする。再構築された本文は次の採用セクションへ直接進む。
+2. 外部リソース内のドメインブロックは、ヒアリング時のユーザー選択順とは独立してカタログ順（フロントエンド → バックエンド → APIコントラクト → インフラストラクチャ）で配置する。
+3. 「曖昧ルールの差し戻し」ルール（`/project-inject` Step 3 で定義）は、`add` および `update` 区分の全セクションに対するヒアリング時のフィルタとして適用される。フィルタを通過したルールが通常のセクション出力経路で書き出され、フィルタ自体の出力行は 0 行となる。

package/.claude/skills-ja/task-analyzer/references/skills-index.yaml

@@ -86,11 +86,6 @@ skills:
     size: small
     key-references:
       - "プロジェクト固有（経験則）"
-    sections:
-      - "プロジェクト概要"
-      - "ドメイン制約"
-      - "開発フェーズ"
-      - "ディレクトリ規約"
 
   documentation-criteria:
     skill: "documentation-criteria"

package/CHANGELOG.md

@@ -5,6 +5,31 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.22.1] - 2026-05-16
+
+### Added
+
+- **Minimal Surface Alternatives design gate** (agents, skills) — Gate-1 sub-gate for `technical-designer` and `technical-designer-frontend` requiring each new maintenance-surface-bearing element (persistent state; public-contract elements or cross-boundary fields/props; behavioral modes/flags/variants; reusable abstractions or component splits) to be evaluated against subtractive alternatives via a 5-step procedure: Fix Requirements (referencing the Design Doc, PRD, or UI Spec by AC ID, AC heading, EARS clause, or constraint ID) → Diverge with at least one subtractive alternative → Compare in a context-adaptive table → Converge on the smallest surface using a 5-column resolution priority → Record Rejected Alternatives. Context-specific in-scope sets distinguish backend (fields crossing module/service boundaries, concept/mode/flag) from frontend (ownership boundary crossings — public API props of exported reusable components, Context values, state lifted across ownership boundaries — plus props/modes/variants that change observable behavior). `document-reviewer` enforces section existence at Gate 0 and per-element quality at Gate 1 (AC reference present, subtractive alternative present, rationale anchored to a current requirement smaller alternatives fail to cover, rejected log present). `code-reviewer` escalates when implementation introduces in-scope elements absent from the Design Doc's section. `technical-designer` Reverse-Engineer Mode skips the gate (documenting existing elements, not introducing new ones)
+- **Minimum Surface for Required Coverage principle** (skills) — New `coding-standards` Basic Principle, distinct from YAGNI: YAGNI is a time-axis check (refuse work for future-only needs); this principle constrains surface area at a fixed coverage point. Adoption is justified by naming a current requirement or constraint that smaller alternatives fail to cover; value-based arguments (reusable, future-ready, convenient for implementation) serve as tiebreakers only
+- **Design Doc template: Minimal Surface Alternatives and Future Extensibility sections** (skills) — `design-template.md` gains a per-element 5-step output template (fixed requirements, alternatives table with column-name adaptation guidance for backend/frontend contexts, resolution priority for selecting "smallest", selection rationale, rejected alternatives log) and a Future Extensibility section recording capabilities excluded from the current design surface (Deferred possibilities tied to a current requirement, Intentional limitations, Extension points limited to existing interfaces with named current consumers). The two sections are distinguished by record granularity — Step 5 records element-level rejections, Future Extensibility records capability-level exclusions
+- **CLAUDE.md Scope Discipline rule** (project rules) — New section in `CLAUDE.md` defining how to keep edits within the user's specified scope
+
+### Changed
+
+- **`documentation-criteria` Design Doc Includes list** (skills) — Adds "Minimal Surface Alternatives" as required Design Doc content when introducing maintenance-surface elements, keeping the required-content list in sync with `document-reviewer` enforcement
+
+## [1.22.0] - 2026-05-10
+
+### Added
+
+- **External Resources section in project-context skill** (skills) — Captures access methods for resources outside the repository (design source, design system, schema source, secret store, IaC source, deployment trigger) across four domains: frontend, backend, API contract, infrastructure. Each domain reference (`references/external-resources-{frontend,backend,api,infra}.md`) defines four structured axes plus a self-declaration phase. Per-axis output schema records three fields: Source type, Location, Access method. Multiple-instance and cross-axis-reference rules cover primary/analytics splits and resources shared across domains
+- **Template-driven /project-inject command** (commands) — Section catalog and hearing protocol live in `.claude/skills/project-context/references/template.md`; new dimensions are added by editing the template. Section-level hearing supports five dispositions (`add` / `keep` / `update` / `remove` / `skip`) for incremental updates without re-running the full flow. Vagueness rejection filter sends back subjective rules for measurable rephrasing during hearing
+
+### Changed
+
+- **project-context skill scope** (skills) — Expanded from domain constraints / development phase / directory conventions to also cover external-resource access methods. Description frontmatter advertises all four axes with explicit "Use when" trigger phrases (session start, project structure check, domain rules, external resources). Configured SKILL.md is shaped by /project-inject from the catalog; unconfigured stub ships as a minimal one-line invitation to run /project-inject
+- **skills-index validator: dynamic-content skills allowed** (tooling) — `scripts/check-skills-index.mjs` treats yaml entries with no sections as dynamic content (logged, skipped) rather than failing. Releases the prior implicit requirement that every skill have at least one static section, removing the need for stub-padding workarounds for skills whose content is populated at runtime
+
 ## [1.21.0] - 2026-05-03
 
 ### Added

package/CLAUDE.en.md

@@ -29,7 +29,7 @@ Core rules for maximizing AI execution accuracy. All instructions must follow th
 **Trigger**: When starting work that involves Edit/Write/MultiEdit tools
 
 - [ ] Execute rule-advisor subagent (using Task tool)
-- [ ] Update tasks with TaskCreate/TaskUpdate
+- [ ] Create/update tasks with TaskCreate/TaskUpdate
   - Record taskEssence as completion criteria
   - Reflect firstActionGuidance as first action
   - Record warningPatterns as checkpoints during execution
@@ -70,6 +70,15 @@ Pause work and report status when these conditions occur:
 4. Present action plan to user
 5. Execute fix after approval
 
+## Scope Discipline
+
+**Apply instructions to the user's specified scope. Ask before expanding it.**
+
+- Treat explicit quantities and targets ("one", "this file", "only X") as boundaries
+- Copy/move/mirror requests preserve content verbatim; edit content only when requested
+- Port/translation requests preserve intent and behavior; adapt only what the destination context requires
+- Ask before changing related files, symmetric locations, adjacent behavior, or adding "helpful" extras
+
 ## User Confirmation Required
 
 Obtain user confirmation before implementation in these situations:

package/CLAUDE.ja.md

@@ -6,7 +6,7 @@ AI実行精度最大化のための中核ルール。全ての指示はこのフ
 
 **すべてのEdit/Write/MultiEditツール使用前にユーザー承認が必須**
 
-- 編集作業の前にAskUserQuestionで変更計画を提示し、明示的な承認を得ること
+- 編集ツール使用前にAskUserQuestionで変更計画を提示し、明示的な承認を得ること
 - 調査・読み込み・分析は承認不要
 
 ## 品質基準：技術的な妥協をしない
@@ -29,7 +29,7 @@ AI実行精度最大化のための中核ルール。全ての指示はこのフ
 **トリガー**: Edit/Write/MultiEditツールを使う作業の開始時
 
 - [ ] rule-advisorサブエージェントを実行（Taskツール使用）
-- [ ] TaskCreate/TaskUpdateでタスクを更新
+- [ ] TaskCreate/TaskUpdateでタスクを作成・更新
   - taskEssenceを完了判断基準として記録
   - firstActionGuidanceを初動アクションとして反映
   - warningPatternsを実行中の確認項目として記録
@@ -43,7 +43,7 @@ AI実行精度最大化のための中核ルール。全ての指示はこのフ
 ### Step 3: 実装実行
 
 - [ ] 承認されたアプローチに従いEdit/Write/MultiEditを実行
-- [ ] 3ファイル編集ごとにTaskUpdateで更新（進捗と方向性を確認）
+- [ ] ファイル編集3回ごとにTaskUpdateで更新（進捗と方向性を確認）
 
 ### Step 4: 品質検証
 
@@ -70,6 +70,15 @@ AI実行精度最大化のための中核ルール。全ての指示はこのフ
 4. 対処計画をユーザーに提示
 5. 承認後に修正を実行
 
+## スコープ規律
+
+**指示はユーザーが指定したスコープ内で実行する。拡張する前に確認を取る。**
+
+- 明示された数量と対象（"one"、"this file"、"only X" 等）は境界として扱う
+- コピー/移動/ミラー依頼は内容をそのまま維持し、変更は依頼があったときのみ行う
+- 移植/翻訳依頼は意図と振る舞いを保持し、適応は移植先・翻訳先の文脈で必要な範囲に限る
+- 関連ファイル、対応箇所、隣接する振る舞いの変更、「ついで」の追加は、変更前に確認する
+
 ## ユーザー確認必須
 
 以下の状況では実装前にユーザー確認を取得：

package/CLAUDE.md

@@ -6,7 +6,7 @@ AI実行精度最大化のための中核ルール。全ての指示はこのフ
 
 **すべてのEdit/Write/MultiEditツール使用前にユーザー承認が必須**
 
-- 編集作業の前にAskUserQuestionで変更計画を提示し、明示的な承認を得ること
+- 編集ツール使用前にAskUserQuestionで変更計画を提示し、明示的な承認を得ること
 - 調査・読み込み・分析は承認不要
 
 ## 品質基準：技術的な妥協をしない
@@ -29,7 +29,7 @@ AI実行精度最大化のための中核ルール。全ての指示はこのフ
 **トリガー**: Edit/Write/MultiEditツールを使う作業の開始時
 
 - [ ] rule-advisorサブエージェントを実行（Taskツール使用）
-- [ ] TaskCreate/TaskUpdateでタスクを更新
+- [ ] TaskCreate/TaskUpdateでタスクを作成・更新
   - taskEssenceを完了判断基準として記録
   - firstActionGuidanceを初動アクションとして反映
   - warningPatternsを実行中の確認項目として記録
@@ -43,7 +43,7 @@ AI実行精度最大化のための中核ルール。全ての指示はこのフ
 ### Step 3: 実装実行
 
 - [ ] 承認されたアプローチに従いEdit/Write/MultiEditを実行
-- [ ] 3ファイル編集ごとにTaskUpdateで更新（進捗と方向性を確認）
+- [ ] ファイル編集3回ごとにTaskUpdateで更新（進捗と方向性を確認）
 
 ### Step 4: 品質検証
 
@@ -70,6 +70,15 @@ AI実行精度最大化のための中核ルール。全ての指示はこのフ
 4. 対処計画をユーザーに提示
 5. 承認後に修正を実行
 
+## スコープ規律
+
+**指示はユーザーが指定したスコープ内で実行する。拡張する前に確認を取る。**
+
+- 明示された数量と対象（"one"、"this file"、"only X" 等）は境界として扱う
+- コピー/移動/ミラー依頼は内容をそのまま維持し、変更は依頼があったときのみ行う
+- 移植/翻訳依頼は意図と振る舞いを保持し、適応は移植先・翻訳先の文脈で必要な範囲に限る
+- 関連ファイル、対応箇所、隣接する振る舞いの変更、「ついで」の追加は、変更前に確認する
+
 ## ユーザー確認必須
 
 以下の状況では実装前にユーザー確認を取得：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-ai-project",
-  "version": "1.21.0",
+  "version": "1.22.1",
   "packageManager": "npm@10.8.2",
   "description": "TypeScript boilerplate with skills and sub-agents for Claude Code. Prevents context exhaustion through role-based task splitting.",
   "keywords": [

package/scripts/check-skills-index.mjs

@@ -112,8 +112,7 @@ async function checkLanguage(lang) {
     const actual = extractH2Headings(markdown)
 
     if (expected.length === 0) {
-      reports.push(`[${lang}] ! ${name}: yaml has no sections listed (expected at least one to validate)`)
-      failed++
+      reports.push(`[${lang}] - ${name}: dynamic content (no static sections to validate)`)
       continue
     }