create-ai-project 1.20.2 → 1.20.4

package/.claude/skills-ja/subagents-orchestration-guide/SKILL.md

@@ -20,18 +20,9 @@ description: サブエージェントのタスク分担と連携を調整。規
 - **分析・設計**: 該当するサブエージェントに委譲
 - **初動**: ユーザー要件はrequirement-analyzerに渡してから他のステップへ進む
 
-**初動アクション規則**: ユーザー要件を正確に分析するため、requirement-analyzerに直接渡し、その分析結果に基づいてワークフローを決定する。
+### 初動アクション規則
 
-## タスク受領時の判断
-
-```mermaid
-graph TD
-    Start[新規タスク受領] --> RA[requirement-analyzerで要件分析]
-    RA --> Scale[規模判定]
-    Scale --> Flow[規模に応じたフロー実行]
-```
-
-**フロー実行中は規模判定表に従って次のサブエージェントを決定する**
+新しいタスクを受け取ったら、ユーザー要件をrequirement-analyzerに直接渡す。その規模判定結果に基づいてワークフローを決定する。
 
 ### フロー実行中の要件変更検知
 
@@ -59,7 +50,7 @@ graph TD
 10. **technical-designer**: ADR/Design Doc作成（最新技術情報の調査、Property注釈付与）
 11. **work-planner**: 作業計画書作成（テストスケルトンからメタ情報を抽出・反映）
 12. **document-reviewer**: 単一ドキュメントの品質・完成度・ルール準拠チェック
-13. **code-verifier**: Design Docの主張を既存コードベースに対して検証（設計フローでレビュー前に使用）
+13. **code-verifier**: ドキュメントとコードの整合性を検証。実装前: Design Docの主張を既存コードベースに対して検証。実装後: 実装がDesign Docに準拠しているか検証
 14. **design-sync**: Design Doc間の整合性検証（明示的矛盾のみ検出）
 15. **acceptance-test-generator**: Design DocのACとUI Spec（任意）から統合テストとE2Eテストのスケルトン生成
 
@@ -139,7 +130,7 @@ graph TD
 |-------|---------------|-------------|
 | requirement-analyzer | scale, confidence, adrRequired, crossLayerScope, scopeDependencies, questions | scaleでフローを選択。adrRequiredでADRステップ要否を判断 |
 | codebase-analyzer | analysisScope.categoriesDetected, dataModel.detected, focusAreas[], existingElements count, limitations | focusAreasをtechnical-designerにコンテキストとして渡す |
-| code-verifier | consistencyScore, discrepancies[], reverseCoverage (dataOperationsInCode, testBoundariesSectionPresent) | discrepanciesをdocument-reviewerに連携 |
+| code-verifier | status (consistent/mostly_consistent/needs_review/inconsistent), consistencyScore, discrepancies[], reverseCoverage (dataOperationsInCode, testBoundariesSectionPresent). 実装前: Design Docの主張を既存コードに対して検証。実装後: 実装のDesign Doc整合性を検証（`code_paths`で変更ファイルにスコープ） | discrepanciesをdocument-reviewerに連携 |
 | task-executor | status (escalation_needed/completed), escalation_type, testsAdded, requiresTestReview | escalation_needed時: escalation_type別に対応（design_compliance_violation, similar_function_found, similar_component_found, investigation_target_not_found, out_of_scope_file） |
 | quality-fixer | status (approved/blocked), reason, blockingIssues[], missingPrerequisites[] | blocked時: 下記quality-fixer blockedハンドリング参照 |
 | document-reviewer | approvalReady (true/false) | trueで次ステップへ。falseで修正を依頼 |
@@ -177,9 +168,9 @@ quality-fixerが `status: "blocked"` を返した場合、`reason`で判別：
 ### 中規模（3-5ファイル） - 9ステップ（バックエンド） / 11ステップ（フロントエンド/フルスタック）
 
 1. requirement-analyzer → 要件分析 **[停止]**
-2. codebase-analyzer → コードベース分析（要件分析結果を入力）
-3. **（フロントエンド/フルスタックのみ）** プロトタイプコードの有無を確認 → ui-spec-designer → UI Spec作成
-4. **（フロントエンド/フルスタックのみ）** document-reviewer → UI Specレビュー **[停止: UI Spec承認]**
+2. **（フロントエンド/フルスタックのみ）** プロトタイプコードの有無を確認 → ui-spec-designer → UI Spec作成（コンポーネント構造が技術設計に反映されるため先に実施）
+3. **（フロントエンド/フルスタックのみ）** document-reviewer → UI Specレビュー **[停止: UI Spec承認]**
+4. codebase-analyzer → コードベース分析（要件分析結果を入力）
 5. technical-designer → Design Doc作成（codebase-analyzer出力を追加コンテキストとして入力。レイヤー横断時: レイヤー別に作成、レイヤー横断オーケストレーション参照）
 6. code-verifier → Design Docを既存コードに対して検証（doc_type: design-doc）
 7. document-reviewer → Design Docレビュー（code-verifier結果をcode_verificationとして入力。レイヤー横断時: Design Doc毎に実行）
@@ -297,7 +288,7 @@ requirement-analyzerが複数レイヤー（backend + frontend）にまたがる
    #### codebase-analyzer → technical-designer
 
    **codebase-analyzerへの入力**: 要件分析JSON出力、PRDパス（存在する場合）、元のユーザー要件
-   **technical-designerへの入力**: codebase-analyzerのJSON出力をDesign Doc作成プロンプトの追加コンテキストとして渡す。designerは`focusAreas`と`dataModel`を「既存コードベース分析」セクションに反映する。
+   **technical-designerへの入力**: codebase-analyzerのJSON出力をDesign Doc作成プロンプトの追加コンテキストとして渡す。technical-designerは`focusAreas`、`dataModel`、`dataTransformationPipelines`を「既存コードベース分析」セクションおよび「検証戦略」セクションに反映する。
 
    #### code-verifier → document-reviewer（Design Docレビュー）
 
@@ -323,9 +314,7 @@ requirement-analyzerが複数レイヤー（backend + frontend）にまたがる
    - E2Eテストファイル: [パス]（最終フェーズでのみ実行）
 
    **エラー時**: ファイルが生成されない場合はユーザーにエスカレーション
-3. **品質保証とコミット実行**: `status: "approved"`確認後、即座にgit commit実行
-4. **自律実行モード管理**: 承認後の自律実行開始・停止・エスカレーション判断
-5. **ADRステータス管理**: ユーザー判断後のADRステータス更新（Accepted/Rejected）
+3. **ADRステータス管理**: ユーザー判断後のADRステータス更新（Accepted/Rejected）
 
 ## 重要な制約
 
@@ -335,19 +324,15 @@ requirement-analyzerが複数レイヤー（backend + frontend）にまたがる
 - **フロー確認**: 承認取得後は必ず作業計画フロー（大規模/中規模/小規模）で次のステップを確認
 - **整合性検証**: サブエージェントの出力が矛盾した場合、優先順位に従って解決（委譲の境界セクション参照）
 
-## 人間との必須対話ポイント
-
-### 基本原則
-- **停止は必須**: 以下のタイミングでは必ず人間の応答を待つ
-- **AskUserQuestionを使用**: 全ての停止ポイントで確認と質問を提示
-- **確認→合意のサイクル**: ドキュメント生成後は合意またはupdateモードでの修正指示を受けてから次へ進む
-- **具体的な質問**: 選択肢（A/B/C）や比較表を用いて判断しやすく
-- **効率より対話**: 手戻りを防ぐため、早い段階で確認を取る
-
-### 主要な停止ポイント
-- **requirement-analyzer完了後**: 要件分析結果と質問事項の確認
-- **PRD作成→document-reviewer実行後**: 要件理解と整合性の確認
-- **UI Spec作成→document-reviewer実行後**（フロントエンド/フルスタック）: UI仕様の完全性と整合性の確認
-- **ADR作成→document-reviewer実行後**: 技術方針と整合性の確認
-- **Design Doc作成→document-reviewer実行後**: 設計内容と整合性の確認
-- **計画書作成後**: 実装フェーズ全体の一括承認
+### 進捗管理
+
+TaskCreateで全体フェーズを登録。各フェーズ完了時にTaskUpdateで更新。
+
+### 実装後検証のPass/Fail基準
+
+| Verifier | Pass | Fail | Blocked |
+|----------|------|------|---------|
+| code-verifier | `status`が`consistent`または`mostly_consistent` | `status`が`needs_review`または`inconsistent` | — |
+| security-reviewer | `status`が`approved`または`approved_with_notes` | `status`が`needs_revision` | `status`が`blocked` → ユーザーにエスカレーション |
+
+**再実行ルール**: 修正サイクル後、**Fail**を返した検証エージェントのみ再実行。前回Passした検証エージェントは再実行しない。最大2回の修正サイクル — 2回後も不合格が残る場合、残存する検出事項とともにユーザーにエスカレーション。

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

@@ -159,7 +159,6 @@ skills:
       - "エージェント連携パターン"
     sections:
       - "最重要原則：オーケストレーターとして振る舞う"
-      - "タスク受領時の判断"
       - "活用できるサブエージェント"
       - "オーケストレーション原則"
       - "Sub-agent間の制約"
@@ -170,7 +169,6 @@ skills:
       - "自律実行モード"
       - "オーケストレーターの主な役割"
       - "重要な制約"
-      - "人間との必須対話ポイント"
 
   skill-optimization:
     skill: "skill-optimization"

package/CHANGELOG.md

@@ -5,6 +5,63 @@ 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.20.4] - 2026-04-05
+
+### Added
+
+- **codebase-analyzer: Deep call chain tracing** (agents) — Replaced shallow public-interface-only extraction with full-depth analysis. All visibility levels (public, private, internal) are now extracted with recursive call chain tracing within modules. External dependencies are traced to public interface only. Chains exceeding 10 unique functions record the remainder in `limitations`
+- **codebase-analyzer: Data transformation pipeline detection** (agents) — New `dataTransformationPipelines` output field traces step-by-step input→output mapping for requirement-relevant entry points, including external resource lookups (master tables, config, constants) that modify output values
+- **codebase-analyzer: `visibility` field in output schema** (agents) — `existingElements` schema now includes `visibility` (public/private/internal) and `method` as a category option, matching the expanded extraction requirements
+- **technical-designer: Output comparison requirement** (agents) — Designs that replace or modify existing behavior must define a concrete output comparison method (identical input, expected output fields, diff method). When codebase analysis provides `dataTransformationPipelines`, each pipeline step must be covered
+- **technical-designer: Early verification exception clause** (agents) — Default early verification point for replacements/modifications is output comparison. Exception: when primary risk is not behavioral equivalence (e.g., schema compatibility, integration contract), specify alternative target and document why output comparison is deferred
+- **document-reviewer: Output comparison check** (agents) — Missing output comparison for changes that replace or modify existing behavior → `critical` issue. Uncovered `dataTransformationPipelines` steps → `important` issue
+- **design-template: Output Comparison section** (skills) — New section under Verification Strategy for behavioral equivalence verification: comparison input, expected output fields, diff method, and transformation pipeline coverage
+- **orchestration-guide: Pipeline bridge** (skills) — codebase-analyzer → technical-designer bridge now passes `dataTransformationPipelines` to inform Verification Strategy in addition to Existing Codebase Analysis
+
+### Changed
+
+- **technical-designer: Full method inventory** (agents) — Removed "about 5 important ones if over 10" limit. Now requires listing every public method with full signatures to prevent investigation shortcuts that lead to incomplete design documents
+
+## [1.20.3] - 2026-04-04
+
+### Added
+
+- **code-reviewer: Identifier Verification** — Extract identifier specifications (resource names, endpoint paths, config keys, schema names) from Design Doc and verify exact string match against implementation. Added `identifierMatchRate` and `identifierVerification[]` to output schema
+- **code-reviewer: Evidence-Based Confidence** — Multi-source evidence collection (primary: implementation, secondary: tests, tertiary: config/types) with high/medium/low confidence per AC. Added `evidence_source` field to track tool provenance per determination
+- **code-reviewer: Finding Classification** — Quality findings categorized as `dd_violation`/`maintainability`/`reliability`/`coverage_gap` with category-specific rationale requirements. Output Self-Check ensures every finding cites file:line and tool name
+- **Post-Implementation Verification** (commands, skills) — `build` and `front-build` now run code-verifier and security-reviewer in parallel after all tasks complete. Pass/fail criteria defined in orchestration guide with max 2 fix cycles before escalation
+- **front-design: Workflow Overview** — ASCII flow diagram showing the full design pipeline with stop points
+- **front-design: Completion Criteria** — Explicit checklist of required steps before design phase is complete
+- **front-design: design-sync step** — Added Step 4 for cross-document consistency verification before final approval
+- **ADR template: Architecture Impact section** — Documents how the decision affects existing components, dependencies, and constraints
+- **ADR template: Rejected status** — Added to status options alongside Proposed/Accepted/Deprecated/Superseded
+- **PRD template: User Journey and Scope Boundary diagrams** — Required mermaid diagrams added to template
+- **PRD template: MoSCoW prioritization** — Must Have(P1)/Should Have(P2)/Could Have(P3)/Won't Have structure replaces Must/Nice to Have/Out of Scope
+- **PRD template: Quantitative success metrics format** — Each metric specifies numeric target, measurement method, and timeframe
+- **Design template: Error Handling table** — Free-text placeholder replaced with structured table (Category, Example, Detection, Recovery, User Impact)
+- **Design template: Logging sub-categories** — Structured log events, levels, sensitive data handling, and monitoring requirements
+- **Plan template: Hybrid option** — Option C added for hybrid implementation approach alongside Vertical Slice and Horizontal Slice
+- **Security checks: Detection approach** — Added concrete detection methods for Access Control Gaps and Mishandling of Exceptional Conditions patterns
+
+### Changed
+
+- **BP-001 Negative → Positive form** (agents, 17 files) — Converted negative instructions to positive directives across all agent definitions. "Don't forget test creation" → "Include test creation in every task", "No contradiction with PRD" → "All requirements align with PRD", "any prohibited" → "use strict types", etc.
+- **BP-002 Vague → Concrete** (agents, skills) — Replaced ambiguous expressions with measurable criteria. "avoid excessive detail" → "include only information required for task execution and verification", "measurable format" → "each metric specifies a numeric target, measurement method, and timeframe"
+- **Emoji markers removed** (agents) — Removed ✅/❌ markers from instruction contexts (quality-fixer, requirement-analyzer, technical-designer-frontend, build, front-build). Retained only in user-facing output templates
+- **documentation-criteria: Excludes → Scope** (skills) — Separate Includes/Excludes blocks consolidated into single Scope statement per document type, reducing duplication
+- **documentation-criteria: QA phase unified** (skills) — Per-approach "Final Phase: Quality Assurance" entries consolidated into single "All approaches" statement
+- **orchestration-guide: First Action Rule simplified** (skills) — Mermaid diagram and duplicate text replaced with single-line rule
+- **orchestration-guide: Redundant sections removed** (skills) — Required Dialogue Points, Decision Flow diagram, duplicate orchestrator roles compressed
+- **orchestration-guide: Medium frontend flow reordered** (skills) — UI Spec creation moved before codebase analysis to match large-scale flow and front-design command — component structure informs technical design
+- **orchestration-guide: code-verifier description expanded** (skills) — Now documents both pre-implementation and post-implementation verification modes with status field values
+- **front-design: Execution Protocol** (commands) — Replaced role/method block with structured protocol referencing orchestration guide. Documents UI Spec → codebase-analyzer ordering rationale
+- **front-plan: Test skeleton mandatory** (commands) — Removed optional user confirmation — acceptance-test-generator always executes before work-planner per orchestration guide flow
+- **front-build: Streamlined** (commands) — Removed redundant Execution Method, Sub-agent Invocation Method, and Structured Response Specification sections. Scope line added to Execution Protocol
+- **front-review: Orchestrator identity** (commands) — Added Orchestrator Definition with TaskCreate-first action. Replaced rule-advisor with documentation-criteria in fix flow. Step numbering unified (Step 1-11)
+- **review/front-review: Re-validation context** (commands) — Re-validation prompts now include Design Doc path and implementation file list alongside prior issues
+- **review/front-review: Report template** (commands) — Added identifierMatchRate, confidence levels, identifier mismatches, and quality findings sections
+- **skills-index.yaml** (skills) — Removed deleted sections from orchestration-guide entry (Decision Flow, Required Dialogue Points)
+
 ## [1.20.2] - 2026-04-03
 
 ### Added

package/README.ja.md

@@ -19,15 +19,16 @@
 1. [クイックスタート（3ステップ）](#-クイックスタート3ステップ)
 2. [既存プロジェクトの更新](#-既存プロジェクトの更新)
 3. [Vibe Codingの先へ：なぜサブエージェント？](#-vibe-codingの先へなぜサブエージェント)
-4. [スキルシステム](#-スキルシステム)
-5. [このボイラープレートで作られたプロジェクト](#-このボイラープレートで作られたプロジェクト)
-6. [ドキュメント＆ガイド](#-ドキュメントガイド)
-7. [スラッシュコマンド](#-スラッシュコマンド)
-8. [開発ワークフロー](#-claude-code-ワークフロー)
-9. [プロジェクト構成](#-プロジェクト構成)
-10. [パッケージマネージャーの設定](#-パッケージマネージャーの設定)
-11. [多言語対応](#-多言語対応)
-12. [よくある質問](#-よくある質問)
+4. [スラッシュコマンド](#-スラッシュコマンド)
+5. [スキルのカスタマイズ](#-スキルのカスタマイズ)
+6. [スキルシステム](#-スキルシステム)
+7. [このボイラープレートで作られたプロジェクト](#-このボイラープレートで作られたプロジェクト)
+8. [ドキュメント＆ガイド](#-ドキュメントガイド)
+9. [開発ワークフロー](#-claude-code-ワークフロー)
+10. [プロジェクト構成](#-プロジェクト構成)
+11. [パッケージマネージャーの設定](#-パッケージマネージャーの設定)
+12. [多言語対応](#-多言語対応)
+13. [よくある質問](#-よくある質問)
 
 ## ⚡ クイックスタート（3ステップ）
 
@@ -102,7 +103,7 @@ ignoreされたファイルは更新時に保護されます。ただし、ignor
 
 ## 🚀 Vibe Codingの先へ：なぜサブエージェント？
 
-Vibe Codingの先へ — **Agentic Coding**（構造化されたワークフローを専門AIエージェントに委任するアプローチ）がプロフェッショナルな開発の標準になりつつあります。このボイラープレートはClaude Codeのサブエージェントでそれを実現します。
+Vibe Codingの先へ — **Agentic Coding**（構造化されたワークフローを専門AIエージェントに委任するアプローチ）が実践的な開発手法として広がりつつあります。このボイラープレートはClaude Codeのサブエージェントでそれを実現します。
 
 **従来のAIコーディングの問題**
 - ❌ 長時間のセッションでコンテキストを失う
@@ -112,7 +113,7 @@ Vibe Codingの先へ — **Agentic Coding**（構造化されたワークフロ
 **サブエージェントによるContext Engineering**
 - ✅ 専門的な単一の役割に分割（設計、実装、レビュー）
 - ✅ 各エージェントが新鮮で集中したコンテキストを持つ — 枯渇なし
-- ✅ 品質低下なしで規模感のあるタスクを処理
+- ✅ 大規模なプロジェクトでも品質低下なしに処理
 
 これはClaude Codeのサブエージェント機構が、各エージェントを独立したコンテキストウィンドウで実行する仕組みに基づいています。親セッションがタスクを委任し、各サブエージェントはクリーンで集中したコンテキストで処理を開始します。品質チェック（lint、型チェック、テスト、ビルド）はCIではなくコミット前にローカルで実行されるため、フィードバックループが速く、pushする時点でコードは検証済みです。
 
@@ -124,6 +125,45 @@ Vibe Codingの先へ — **Agentic Coding**（構造化されたワークフロ
 
 *サブエージェントが連携してTypeScriptプロジェクトを構築する様子*
 
+## 📝 スラッシュコマンド
+
+Claude Codeで利用できる主要なコマンド
+
+| コマンド | 目的 | 使用場面 |
+|---------|------|----------|
+| `/implement` | 要件から実装までの一貫した開発 | 新機能開発 |
+| `/task` | スキルに基づいた単一タスクの実行 | バグ修正、小規模な変更 |
+| `/design` | 設計書の作成 | アーキテクチャの計画時 |
+| `/plan` | 設計書から作業計画書を作成 | 設計承認後 |
+| `/build` | 既存の計画から実行 | 作業の再開時 |
+| `/review` | コードの準拠性確認 | 実装完了後 |
+| `/diagnose` | 根本原因分析ワークフロー | デバッグ、トラブルシューティング |
+| `/reverse-engineer` | コードからPRD/Design Docを生成 | 既存システムのドキュメント化 |
+| `/create-skill` | 対話形式で新しいスキルを作成 | プロジェクト固有のルールを追加 |
+| `/refine-skill` | 品質レビュー付きでスキルを修正 | スキルの精度改善 |
+
+フロントエンド用（`/front-design`（UI Spec + Design Doc）, `/front-build`, `/front-review`, `/front-plan`）やユーティリティコマンド（`/add-integration-tests`, `/update-doc`）も利用できます。
+
+[コマンドの詳細はこちら →](docs/guides/ja/use-cases.md)
+
+## 🌱 スキルのカスタマイズ
+
+このボイラープレートには汎用的なスキルが同梱されており、すぐに使い始められます。ただし、スキルが本領を発揮するのは、プロジェクト固有のコーディング規約やドメイン制約、チームの意思決定を反映させたときです。
+
+同梱されているスキルはベースラインです。次のステップは、それをあなたのプロジェクトに合わせて育てていくことです。
+
+- **`/project-inject`** — プロジェクトの前提情報を設定（初回実行、毎セッション参照）
+- **`/create-skill`** — 対話形式で新しいスキルを作成
+- **`/refine-skill`** — 既存スキルを品質レビュー付きで改善
+
+スキル作成の原則やベストプラクティスは[スキル編集ガイド](docs/guides/ja/skills-editing-guide.md)を参照してください。
+
+### スキルの効果検証
+
+スキルを作ることと、それが実際にエージェントの挙動を改善しているかを知ることは別の問題です。スキルは互いに影響し合い、プロジェクトのコンテキストとも相互作用するため、確実に効果を知るには実際に動かして比較するしかありません。
+
+[rashomon](https://github.com/shinpr/rashomon)はこのためのClaude Codeプラグインです。スキル変更が本当に改善につながったのか、感覚ではなくエビデンスで確認したいときに使えます。
+
 ## 🎨 スキルシステム
 
 このボイラープレートでは、自律的（Agentic）な実装ワークフローで用いられている原理原則を、日常のタスクにおいても必要に応じて参照できるようスキルとして提供しています。
@@ -171,25 +211,6 @@ Vibe Codingの先へ — **Agentic Coding**（構造化されたワークフロ
 - **[スキル編集ガイド](docs/guides/ja/skills-editing-guide.md)** - ライブラリドキュメント、チームルール、プロジェクト固有の知識をAIに追加
 - **[設計思想](https://qiita.com/shinpr/items/98771c2b8d2e15cafcd5)** - このアプローチがなぜ有効か
 
-## 📝 スラッシュコマンド
-
-Claude Codeで利用できる主要なコマンド
-
-| コマンド | 目的 | 使用場面 |
-|---------|------|----------|
-| `/implement` | 要件から実装までの一貫した開発 | 新機能開発 |
-| `/task` | スキルに基づいた単一タスクの実行 | バグ修正、小規模な変更 |
-| `/design` | 設計書の作成 | アーキテクチャの計画時 |
-| `/plan` | 設計書から作業計画書を作成 | 設計承認後 |
-| `/build` | 既存の計画から実行 | 作業の再開時 |
-| `/review` | コードの準拠性確認 | 実装完了後 |
-| `/diagnose` | 根本原因分析ワークフロー | デバッグ、トラブルシューティング |
-| `/reverse-engineer` | コードからPRD/Design Docを生成 | 既存システムのドキュメント化 |
-
-フロントエンド用（`/front-design`（UI Spec + Design Doc）, `/front-build`, `/front-review`, `/front-plan`）やユーティリティコマンド（`/add-integration-tests`, `/update-doc`）も利用できます。
-
-[コマンドの詳細はこちら →](docs/guides/ja/use-cases.md)
-
 ## 🤖 Claude Code ワークフロー
 
 ```mermaid

package/README.md

@@ -19,15 +19,16 @@
 1. [Quick Start (3 Steps)](#-quick-start-3-steps)
 2. [Updating Existing Projects](#-updating-existing-projects)
 3. [Beyond Vibe Coding: Why Sub Agents?](#-beyond-vibe-coding-why-sub-agents)
-4. [Skills System](#-skills-system)
-5. [Built with This Boilerplate](#-built-with-this-boilerplate)
-6. [Documentation & Guides](#-documentation--guides)
-7. [Slash Commands](#-slash-commands)
-8. [Development Workflow](#-claude-code-workflow)
-9. [Project Structure](#-project-structure)
-10. [Package Manager Configuration](#-package-manager-configuration)
-11. [Multilingual Support](#-multilingual-support)
-12. [FAQ](#-faq)
+4. [Slash Commands](#-slash-commands)
+5. [Customizing Skills](#-customizing-skills)
+6. [Skills System](#-skills-system)
+7. [Built with This Boilerplate](#-built-with-this-boilerplate)
+8. [Documentation & Guides](#-documentation--guides)
+9. [Development Workflow](#-claude-code-workflow)
+10. [Project Structure](#-project-structure)
+11. [Package Manager Configuration](#-package-manager-configuration)
+12. [Multilingual Support](#-multilingual-support)
+13. [FAQ](#-faq)
 
 ## ⚡ Quick Start (3 Steps)
 
@@ -102,7 +103,7 @@ If your project was created before the update feature, just run `npx create-ai-p
 
 ## 🚀 Beyond Vibe Coding: Why Sub Agents?
 
-As teams move beyond vibe coding, **agentic coding** — delegating structured workflows to specialized AI agents — is becoming the professional standard. This boilerplate implements that approach with Claude Code sub-agents:
+As teams move beyond vibe coding, **agentic coding** — delegating structured workflows to specialized AI agents — is gaining traction as a practical approach. This boilerplate implements that approach with Claude Code sub-agents:
 
 **Traditional AI coding struggles with:**
 - ❌ Losing context in long sessions
@@ -124,6 +125,45 @@ This works because Claude Code's sub-agent mechanism runs each agent in its own
 
 *Sub agents working together on a TypeScript project*
 
+## 📝 Slash Commands
+
+Essential commands for Claude Code:
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| `/implement` | End-to-end feature development | New features |
+| `/task` | Single task with skill-based precision | Bug fixes, small changes |
+| `/design` | Create design docs only | Architecture planning |
+| `/plan` | Create work plan from design | After design approval |
+| `/build` | Execute from existing plan | Resume work |
+| `/review` | Check code compliance | Post-implementation |
+| `/diagnose` | Root cause analysis workflow | Debugging, troubleshooting |
+| `/reverse-engineer` | Generate PRD/Design Docs from code | Legacy system documentation |
+| `/create-skill` | Create a new skill through interactive dialog | Adding project-specific rules |
+| `/refine-skill` | Modify an existing skill with quality review | Improving skill accuracy |
+
+Frontend equivalents (`/front-design` for UI Spec + Design Doc, `/front-build`, `/front-review`, `/front-plan`) and utility commands (`/add-integration-tests`, `/update-doc`) are also available.
+
+[Full command reference →](docs/guides/en/use-cases.md)
+
+## 🌱 Customizing Skills
+
+This boilerplate ships with general-purpose skills that work out of the box. But skills reach their full potential when you tailor them to your project — your coding conventions, domain constraints, and team decisions.
+
+Think of the included skills as a baseline. The next step is making them yours:
+
+- **`/project-inject`** — Capture project-specific prerequisites (run once, referenced every session)
+- **`/create-skill`** — Create a new skill through interactive dialog
+- **`/refine-skill`** — Improve an existing skill with optimization review
+
+For principles and best practices on writing effective skills, see the [Skills Editing Guide](docs/guides/en/skills-editing-guide.md).
+
+### Validating Skill Effectiveness
+
+Creating a skill is one thing — knowing whether it actually improves agent behavior is another. Skills interact with each other and with project context, so the only reliable way to know is to run with and without the skill and compare results.
+
+[rashomon](https://github.com/shinpr/rashomon) is a Claude Code plugin for this. Use it when you want evidence, not intuition, that a skill change made things better.
+
 ## 🎨 Skills System
 
 This boilerplate provides the principles used in agentic implementation workflows as skills, making them available for reference in everyday tasks as needed.
@@ -171,25 +211,6 @@ Both were built using the default `/implement` workflow — no manual agent orch
 - **[Skills Editing Guide](docs/guides/en/skills-editing-guide.md)** - Add library docs, team rules, and project-specific knowledge for AI
 - **[Design Philosophy](https://dev.to/shinpr/zero-context-exhaustion-building-production-ready-ai-coding-teams-with-claude-code-sub-agents-31b)** - Why this approach works
 
-## 📝 Slash Commands
-
-Essential commands for Claude Code:
-
-| Command | Purpose | When to Use |
-|---------|---------|-------------|
-| `/implement` | End-to-end feature development | New features |
-| `/task` | Single task with skill-based precision | Bug fixes, small changes |
-| `/design` | Create design docs only | Architecture planning |
-| `/plan` | Create work plan from design | After design approval |
-| `/build` | Execute from existing plan | Resume work |
-| `/review` | Check code compliance | Post-implementation |
-| `/diagnose` | Root cause analysis workflow | Debugging, troubleshooting |
-| `/reverse-engineer` | Generate PRD/Design Docs from code | Legacy system documentation |
-
-Frontend equivalents (`/front-design` for UI Spec + Design Doc, `/front-build`, `/front-review`, `/front-plan`) and utility commands (`/add-integration-tests`, `/update-doc`) are also available.
-
-[Full command reference →](docs/guides/en/use-cases.md)
-
 ## 🤖 Claude Code Workflow
 
 ```mermaid
@@ -211,19 +232,22 @@ Generate PRD and Design Docs from existing code:
 ```mermaid
 graph TB
     subgraph Phase1[Phase 1: PRD Generation]
-        CMD["/reverse-engineer"] --> SD[scope-discoverer unified]
-        SD --> PRD[prd-creator]
+        SD[scope-discoverer] --> PRD[prd-creator]
         PRD --> CV1[code-verifier]
         CV1 --> DR1[document-reviewer]
+        DR1 -->|Revision needed| PRD
+        DR1 -->|Approved| NEXT1[Next unit]
     end
 
     subgraph Phase2[Phase 2: Design Doc Generation]
         TD[technical-designer] --> CV2[code-verifier]
         CV2 --> DR2[document-reviewer]
-        DR2 --> DONE[Complete]
+        DR2 -->|Revision needed| TD
+        DR2 -->|Approved| NEXT2[Next unit]
     end
 
-    DR1 --> |"All PRDs Approved (reuse scope)"| TD
+    NEXT1 -->|"All PRDs Approved (reuse scope)"| TD
+    NEXT2 --> REPORT[Final report]
 ```
 
 ### How It Works
@@ -321,7 +345,7 @@ A: Yes — create a custom skill under `.claude/skills/` with the relevant URLs.
 A: `/project-inject` (once) → `/implement` (features) → auto quality checks → commit
 
 **Q: How is this different from Copilot/Cursor?**
-A: Those help write code. This manages entire development lifecycle with specialized agents.
+A: Those tools focus on code writing assistance. This boilerplate provides a structured development lifecycle managed by specialized agents.
 
 **Q: What is agentic coding and how does this boilerplate support it?**
 A: Agentic coding delegates structured workflows to specialized AI agents instead of relying on conversational prompting. This boilerplate provides pre-configured sub-agents, CLAUDE.md rules, and quality checks so you can adopt that approach without building the scaffolding yourself.

package/docs/guides/en/skills-editing-guide.md

@@ -195,6 +195,8 @@ Standard error format: { success: false, error: string, code: number }
 Check for duplication between files and eliminate contradictions and redundancy.
 Eliminating duplication also reduces maintenance costs by preventing notation inconsistencies from update omissions.
 
+Note: there is a tradeoff between DRY and skill self-containment. If a skill requires context from another skill to be understood, the reader (both human and LLM) has to chase references. When a piece of information is central to a skill's decision-making, it may be worth repeating rather than forcing a cross-reference. Use judgment — eliminate *accidental* duplication, but don't sacrifice clarity for purity.
+
 ### 4. Appropriately Aggregate Responsibilities
 
 Consolidating related content in one skill maintains single responsibility and prevents unnecessary context mixing in tasks.
@@ -355,6 +357,14 @@ All 9 principles are practiced across these skills, serving as practical referen
 3. Add one specific example
 4. Convert negative form to positive form
 
+## Validating Skill Effectiveness
+
+The 9 principles and `/create-skill` / `/refine-skill` help you write better skills, but writing and validating are different problems. Skills interact with each other and with project context, so the only reliable way to know whether a change actually improved agent behavior is to run the task with and without the skill and compare results.
+
+[rashomon](https://github.com/shinpr/rashomon) is a Claude Code plugin for evidence-based skill validation. Its `/recipe-eval-skill` command runs your task in isolated environments and compares results to classify whether the difference is a real improvement or just variance.
+
+Use `/create-skill` and `/refine-skill` for quick iteration, and rashomon when you want proof that a skill change made things better.
+
 ## Summary
 
 Well-written skills stabilize LLM output. By following the 9 principles and continuously refining your skills, you can maximize LLM capabilities. Build the optimal skill set for your project through regular implementation review and improvement.

package/docs/guides/ja/skills-editing-guide.md

@@ -144,12 +144,12 @@ See [examples.md](examples.md) for usage patterns
 ## LLMの実行精度を最大化する9つの原則
 
 スキル作成の原則を9つ紹介します。
-スキル新規作成には`/create-skill`、既存スキルの品質レビュー付き修正には`/refine-skill`コマンドを提供しています。ただしLLMは「生成後に出力と考え方を突き合わせなければ課題に到達しづらい」傾向があるため、対話的にスキルを修正することを最終的には推奨します。
+スキル新規作成には`/create-skill`、既存スキルの品質レビュー付き修正には`/refine-skill`コマンドを提供しています。ただしLLMは「生成後に出力と考え方を突き合わせなければ課題に到達しづらい」傾向があるため、ツールで生成した後は対話的にスキルを修正することを推奨します。
 
 ### 1. 最小記述で最大精度を実現する（コンテキスト圧迫 vs 実行精度）
 
 コンテキストは貴重なリソースです。冗長な説明を避け、本質的な情報のみを記述します。
-一方で、ただ短くすればいいという訳ではなく、判断に迷わない最小限の記述でなければいけません。
+一方で、ただ短くすればいいという訳ではなく、判断に迷わない最小限の記述である必要があります。
 
 ```markdown
 ❌ 冗長な記述（24文字）
@@ -195,6 +195,8 @@ See [examples.md](examples.md) for usage patterns
 ファイル間の重複もチェックし、矛盾や冗長性を排除します。
 更新漏れによる表記揺れのリスクもあるため、重複の排除はメンテナンスコストの低下にもつながります。
 
+ただし、DRYとスキルの自己完結性にはトレードオフがあります。あるスキルの判断に必要な情報が別のスキルにしかない場合、読み手（人間もLLMも）は参照を追いかける必要が生じます。スキルの意思決定に不可欠な情報であれば、相互参照を強いるより繰り返す方が適切な場合もあります。排除すべきは*意図せず生じた*重複であり、明確さを犠牲にしてまで原則への忠実さを追求する必要はありません。
+
 ### 4. 責務を適切に集約する
 
 関連する内容は1つのスキルにまとめることで単一責務を維持でき、タスクに不要なコンテキストの混入を防げます。
@@ -355,6 +357,14 @@ LLMは冒頭の情報により注意を払います。最重要事項を先頭
 3. 具体例を1つ追加
 4. 否定形を肯定形に変換
 
+## スキルの効果検証
+
+9つの原則と`/create-skill`・`/refine-skill`はスキルの作成・改善を支援しますが、作ることと効果を確認することは別の問題です。スキルは互いに影響し合い、プロジェクトのコンテキストとも相互作用するため、変更が本当に挙動を改善したかは実際に動かして比較するしかありません。
+
+[rashomon](https://github.com/shinpr/rashomon)はエビデンスに基づくスキル検証のためのClaude Codeプラグインです。`/recipe-eval-skill`コマンドが隔離された環境でタスクを実行し、結果を比較することで、差異が実質的な改善なのか単なるバラつきなのかを分類します。
+
+`/create-skill`と`/refine-skill`は手軽な反復に、rashomonはスキル変更が本当に改善につながったか証拠が欲しいときに使い分けてください。
+
 ## まとめ
 
 効果的なスキルはLLMの生成を安定させます。9つの原則を意識し、継続的に最適化することでLLMの能力を最大限に引き出すことができます。定期的な実装結果の振り返りと改善を繰り返し、プロジェクトに最適なスキルセットを構築していきましょう。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-ai-project",
-  "version": "1.20.2",
+  "version": "1.20.4",
   "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": [