create-ai-project 1.16.0 → 1.16.2

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

@@ -27,14 +27,11 @@ skills:
       - "デバッグ手法"
       - "型安全性の基礎"
       - "リファクタリング手法"
-      - "技術的判断が必要な場面"
-      - "継続的改善のマインドセット"
       - "実装作業の完全性担保"
+      - "影響範囲分析"
       - "Red-Green-Refactorプロセス（テストファースト開発）"
       - "テスト設計原則"
-      - "テストヘルパーの活用ルール"
       - "テストの粒度原則"
-      - "継続性テストの範囲"
 
   typescript-rules:
     skill: "typescript-rules"
@@ -76,7 +73,6 @@ skills:
       - "技術スタックの基本方針"
       - "環境変数管理とセキュリティ"
       - "アーキテクチャ設計"
-      - "パターン適用の一貫性"
       - "データフロー統一原則"
       - "ビルドとテスト"
 
@@ -88,9 +84,10 @@ skills:
     key-references:
       - "プロジェクト固有（経験則）"
     sections:
-      - "基本設定"
-      - "実装原則"
-      - "カスタマイズガイド"
+      - "プロジェクト概要"
+      - "ドメイン制約"
+      - "開発フェーズ"
+      - "ディレクトリ規約"
 
   documentation-criteria:
     skill: "documentation-criteria"
@@ -111,6 +108,7 @@ skills:
       - "AI自動化ルール"
       - "図表作成要件"
       - "共通ADRとの関係性"
+      - "テンプレート"
 
   implementation-approach:
     skill: "implementation-approach"
@@ -154,10 +152,33 @@ skills:
       - "ワークフロー調整パターン"
       - "エージェント連携パターン"
     sections:
-      - "規模判定"
-      - "ドキュメント要件"
-      - "停止ポイント"
+      - "最重要原則：オーケストレーターとして振る舞う"
+      - "タスク受領時の判断"
+      - "活用できるサブエージェント"
+      - "オーケストレーション原則"
+      - "Sub-agent間の制約"
+      - "規模判定とドキュメント要件"
+      - "構造化レスポンス仕様"
+      - "作業計画時の基本フロー"
+      - "レイヤー横断オーケストレーション"
       - "自律実行モード"
+      - "オーケストレーターの主な役割"
+      - "重要な制約"
+      - "人間との必須対話ポイント"
+
+  skill-optimization:
+    skill: "skill-optimization"
+    tags: [skill-creation, skill-editing, content-optimization, quality-evaluation, description-generation, metadata]
+    typical-use: "スキル新規作成、コンテンツ改善、品質監査、description生成"
+    size: medium
+    key-references:
+      - "BP-001〜008 コンテンツ最適化パターン"
+      - "9つの編集原則"
+    sections:
+      - "基本方針"
+      - "コンテンツ最適化パターン"
+      - "9つの編集原則"
+      - "References"
 
   # フロントエンド固有スキル
   frontend/typescript-rules:
@@ -169,11 +190,13 @@ skills:
       - "React公式ドキュメント - Function Components"
       - "Props-driven開発 - React Patterns"
     sections:
-      - "フロントエンド固有のアンチパターン"
-      - "Frontend実装における型安全性"
-      - "コーディング規約"
+      - "型システム"
+      - "Reactコンポーネント設計"
+      - "状態管理"
       - "エラーハンドリング"
-      - "パフォーマンス最適化"
+      - "イベントハンドリング"
+      - "コーディング規約"
+      - "アンチパターン"
 
   frontend/typescript-testing:
     skill: "frontend/typescript-testing"
@@ -190,6 +213,8 @@ skills:
       - "テストの実装規約"
       - "モックの型安全性の徹底"
       - "React Testing Libraryの基本例"
+      - "テスト品質基準"
+      - "アンチパターン"
 
   frontend/technical-spec:
     skill: "frontend/technical-spec"

package/CHANGELOG.md

@@ -5,6 +5,49 @@ 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.16.2] - 2026-03-03
+
+### Changed
+
+#### Orchestrator Role Clarity (en/ja)
+- Replace prohibition-style delegation ("NEVER investigate yourself") with positive role definition across build, design, implement, plan, update-doc commands: "your role is to invoke sub-agents, pass data between them, and report results"
+
+#### reverse-engineer (en/ja) — Execution Accuracy
+- Add Orchestrator Definition section with structured JSON passing and code-reading delegation
+- Replace prose loop headers with explicit `FOR ... (sequential, one unit at a time)` notation (Steps 2-5, 7-10)
+- Add prerequisite annotation to Step 3 (dependency on Step 2 output)
+- Expand Step 5 revision prompt: replace vague "apply corrections" with severity-based handling (critical/important/recommended)
+- Expand Step 10 from single-line reference to full backend + frontend revision prompts with severity-based handling
+- Add `7a.`/`7b.` labels and sequential execution note for fullstack Design Doc generation
+- Remove redundant "Context Passing" line (moved to Orchestrator Definition)
+
+#### review (en/ja)
+- Add `$STEP_2_OUTPUT` storage for code-reviewer results
+- Replace vague re-validation ("measure improvement") with prior-issue-tracking re-validation using `$STEP_2_OUTPUT`
+
+#### update-doc (en/ja)
+- Add `$STEP_5_OUTPUT` storage for document-reviewer results
+- Expand revision loop: replace single-line description with full sub-agent prompt including severity-based handling and `$STEP_5_OUTPUT` reference
+
+#### Agents — Reverse Engineering Accuracy (en/ja)
+- document-reviewer: add as-is implementation document review rule — verify code-observable behaviors are stated as facts, flag speculative language on deterministic behavior
+- prd-creator: add Language Standard rule — code as SSoT, definitive form for observable behavior, "Undetermined Items" only for genuinely undeterminable claims
+- prd-creator: add Inferred verification rule — attempt code reading before classifying claims as Inferred
+
+## [1.16.1] - 2026-02-23
+
+### Added
+- `/create-skill` command (en/ja) for guided skill creation with interactive dialog and optimization
+- `skill-optimization` skill (en/ja) with BP-001~008 content patterns and 9 editing principles, split into SKILL.md + references/ for context isolation
+- `skill-creator` agent (en/ja) for optimized skill file generation
+- `skill-reviewer` agent (en/ja) for skill quality evaluation with A/B/C grading
+
+### Changed
+- `/refine-skill` command (en/ja): replace inline Three-Pass Review with `skill-reviewer` agent delegation
+
+### Fixed
+- skills-index.yaml (en/ja): sync sections with actual SKILL.md H2 headings across coding-standards, technical-spec, project-context, documentation-criteria, subagents-orchestration-guide, frontend/technical-spec, frontend/typescript-rules (ja), frontend/typescript-testing (ja)
+
 ## [1.16.0] - 2026-02-14
 
 ### Added

package/README.ja.md

@@ -1,4 +1,4 @@
-# AI コーディングプロジェクト ボイラープレート 🤖
+# AI コーディングプロジェクト ボイラープレート — Claude Code対応 🤖
 
 *他の言語で読む: [English](README.md)*
 
@@ -8,17 +8,19 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/shinpr/ai-coding-project-boilerplate/pulls)
 
+> **Claude Code向けAgentic Codingスターターキット & ワークフローボイラープレート** — サブエージェントとContext Engineeringで、コンテキスト枯渇なしにプロダクション品質のTypeScriptプロジェクトを構築。
+
 ⚡ **このボイラープレートは以下のような開発者のためのツールです**
-- AIを活用して**プロダクション品質のTypeScriptプロジェクト**を開発したい
+- AIを活用して**TypeScriptプロジェクト**を効率的に開発したい
 - 長時間のAIコーディングで起きる**コンテキスト枯渇**を回避したい
 - **専門AIエージェント**で開発のワークフローを標準化したい
 
 ## 📖 目次
 1. [クイックスタート（3ステップ）](#-クイックスタート3ステップ)
 2. [既存プロジェクトの更新](#-既存プロジェクトの更新)
-3. [なぜサブエージェント？](#-なぜサブエージェント)
+3. [Vibe Codingの先へ：なぜサブエージェント？](#-vibe-codingの先へなぜサブエージェント)
 4. [スキルシステム](#-スキルシステム)
-5. [実プロジェクトの成果](#-実プロジェクトの成果)
+5. [このボイラープレートで作られたプロジェクト](#-このボイラープレートで作られたプロジェクト)
 6. [ドキュメント＆ガイド](#-ドキュメントガイド)
 7. [スラッシュコマンド](#-スラッシュコマンド)
 8. [開発ワークフロー](#-claude-code-ワークフロー)
@@ -27,15 +29,10 @@
 11. [多言語対応](#-多言語対応)
 12. [よくある質問](#-よくある質問)
 
-> **どれを使うべき？**
-> - **このボイラープレート**を使う → **Claude Code**で**TypeScript × サブエージェント**に最適化し、**精度を最大化**したい場合
-> - **[claude-code-workflows](https://github.com/shinpr/claude-code-workflows)**を使う → **Claude Code**で**どんなプロジェクトでも2コマンドで始められる**、**プログラミング言語非依存**のワークフロー
-> - **[Agentic Code](https://github.com/shinpr/agentic-code)**を使う → **設定不要**で**どんなツール**でも**プログラミング言語の指定なく**開発したい場合（Codex CLI/Cursor/Aider等）
-
 ## ⚡ クイックスタート（3ステップ）
 
 ```bash
-# 1. プロジェクト作成（30秒）
+# 1. プロジェクト作成
 npx create-ai-project my-project --lang=ja
 
 # 2. 依存関係インストール（自動）
@@ -51,7 +48,7 @@ claude                         # Claude Codeを起動
 
 ## 🔄 既存プロジェクトの更新
 
-プロジェクトのエージェント定義、コマンド、スキル、AIルールを最新の状態に保ちます。プロジェクトのルートディレクトリで実行してください：
+プロジェクトのエージェント定義、コマンド、スキル、AIルールを最新の状態に保ちます。プロジェクトのルートディレクトリで実行してください。
 
 ```bash
 # 変更内容をプレビュー（適用なし）
@@ -63,7 +60,7 @@ npx create-ai-project update
 
 ### 仕組み
 
-`npx create-ai-project update`を実行すると、CLIが以下を行います：
+`npx create-ai-project update`を実行すると、CLIが以下を行います。
 
 1. `.create-ai-project.json`マニフェストから現在のバージョンを確認
 2. 最新のパッケージバージョンと比較
@@ -84,7 +81,7 @@ npx create-ai-project update
 
 ### カスタマイズしたファイルの保護
 
-ファイルをカスタマイズしていて上書きされたくない場合：
+ファイルをカスタマイズしていて上書きされたくない場合
 
 ```bash
 # ignoreリストに追加
@@ -103,19 +100,21 @@ ignoreされたファイルは更新時に保護されます。ただし、ignor
 
 更新機能導入前に作成されたプロジェクトでも、プロジェクトのルートディレクトリで`npx create-ai-project update`を実行するだけで利用できます。`.claudelang`から言語設定を自動検出し、マニフェストを初期化します。
 
-## 🚀 なぜサブエージェント？
+## 🚀 Vibe Codingの先へ：なぜサブエージェント？
+
+Vibe Codingの先へ — **Agentic Coding**（構造化されたワークフローを専門AIエージェントに委任するアプローチ）がプロフェッショナルな開発の標準になりつつあります。このボイラープレートはClaude Codeのサブエージェントでそれを実現します。
 
 **従来のAIコーディングの問題**
 - ❌ 長時間のセッションでコンテキストを失う
 - ❌ 時間とともにコード品質が低下
 - ❌ 大規模タスクで頻繁なセッション再起動が必要
 
-**サブエージェントによる解決**
+**サブエージェントによるContext Engineering**
 - ✅ 専門的な単一の役割に分割（設計、実装、レビュー）
-- ✅ コンテキストを常に新鮮に保ち、品質を一定に維持
+- ✅ 各エージェントが新鮮で集中したコンテキストを持つ — 枯渇なし
 - ✅ 品質低下なしで規模感のあるタスクを処理
 
-各サブエージェントは1つのタスクに集中します。その結果、コンテキストは枯渇せず、品質も維持されます。
+これはClaude Codeのサブエージェント機構が、各エージェントを独立したコンテキストウィンドウで実行する仕組みに基づいています。親セッションがタスクを委任し、各サブエージェントはクリーンで集中したコンテキストで処理を開始します。品質チェック（lint、型チェック、テスト、ビルド）はCIではなくコミット前にローカルで実行されるため、フィードバックループが速く、pushする時点でコードは検証済みです。
 
 👉 [サブエージェントについて詳しく（Anthropic docs）](https://docs.anthropic.com/en/docs/claude-code/sub-agents)
 
@@ -123,7 +122,7 @@ ignoreされたファイルは更新時に保護されます。ただし、ignor
 
 ![Demo](./.github/assets/demo.gif)
 
-*サブエージェントが連携してプロダクション品質のTypeScriptプロジェクトを構築する様子*
+*サブエージェントが連携してTypeScriptプロジェクトを構築する様子*
 
 ## 🎨 スキルシステム
 
@@ -146,47 +145,47 @@ ignoreされたファイルは更新時に保護されます。ただし、ignor
 
 👉 [スキルの仕組みについて（Claude Code docs）](https://code.claude.com/docs/ja/skills)
 
-## 🎯 実プロジェクトの成果
+## 🎯 このボイラープレートで作られたプロジェクト
+
+### ⏱️ 時間比較
+- **ボイラープレートなし**: セットアップ + 基盤構築に約1週間
+- **ボイラープレートあり**: 約2日でプロダクション品質のアプリケーション
+
+### 実績
+
+**Sub Agents MCP Server** — Claude Code/Cursor CLIをサブエージェント化するMCPサーバー
+⏱️ 初期開発2日間 → テストコードがソースの約9割を占める構成でプロダクション稼働中
 
-### [Sub agents MCP Server](https://github.com/shinpr/sub-agents-mcp)
-**内容**: Claude Code/Cursor CLIをサブエージェント化するMCPサーバー  
-**時間**: 2日間 → **TypeScript 30ファイル、フルテストカバレッジ**  
-**結果**: プロダクション環境にデプロイ済み、3分でセットアップ可能
+**MCP Image Generator** — Gemini API経由のAI画像生成
+⏱️ 初期開発1.5日間 → マルチ画像ブレンディング、キャラクター一貫性を持つクリエイティブツール
 
-### [MCP Image Generator](https://github.com/shinpr/mcp-image)
-**内容**: Gemini API経由のAI画像生成  
-**時間**: 1.5日間 → **高度な機能を持つクリエイティブツール**  
-**結果**: マルチ画像ブレンディング、キャラクター一貫性、ワンコマンド統合
+いずれもデフォルトの`/implement`ワークフローで構築。エージェントの手動オーケストレーションは不要でした。
 
-> 💡 **ポイント**: 適切なルール + サブエージェント = 素早くプロダクション品質のコードを生成できる
+> プロジェクトを見る: [sub-agents-mcp](https://github.com/shinpr/sub-agents-mcp) ・ [mcp-image](https://github.com/shinpr/mcp-image)
 
 ## 📚 ドキュメント＆ガイド
 
 - **[クイックスタートガイド](docs/guides/ja/quickstart.md)** - 5分で動かす
 - **[ユースケース＆コマンド](docs/guides/ja/use-cases.md)** - 日常ワークフローのリファレンス
-- **[スキル編集ガイド](docs/guides/ja/skills-editing-guide.md)** - プロジェクトに合わせてカスタマイズ
-- **[設計思想](https://qiita.com/shinpr/items/98771c2b8d2e15cafcd5)** - なぜこれが機能するのか
+- **[スキル編集ガイド](docs/guides/ja/skills-editing-guide.md)** - ライブラリドキュメント、チームルール、プロジェクト固有の知識をAIに追加
+- **[設計思想](https://qiita.com/shinpr/items/98771c2b8d2e15cafcd5)** - このアプローチがなぜ有効か
 
 ## 📝 スラッシュコマンド
 
-Claude Codeで利用できる主要なコマンド：
+Claude Codeで利用できる主要なコマンド
 
 | コマンド | 目的 | 使用場面 |
 |---------|------|----------|
-| `/implement` | 要件から実装までの一貫した開発 | 新機能開発（Backend） |
+| `/implement` | 要件から実装までの一貫した開発 | 新機能開発 |
 | `/task` | スキルに基づいた単一タスクの実行 | バグ修正、小規模な変更 |
-| `/design` | 設計書の作成 | アーキテクチャの計画時（Backend） |
-| `/plan` | 設計書から作業計画書を作成 | 設計承認後（Backend） |
-| `/build` | 既存の計画から実行 | 作業の再開時（Backend） |
-| `/review` | コードの準拠性確認 | 実装完了後（Backend） |
-| `/front-design` | フロントエンド設計書の作成 | React/Viteアーキテクチャ計画時 |
-| `/front-plan` | フロントエンド作業計画書を作成 | フロントエンド設計承認後 |
-| `/front-build` | フロントエンド実装の実行 | Reactコンポーネント開発 |
-| `/front-review` | フロントエンドコードの準拠性確認 | 実装完了後（Frontend） |
+| `/design` | 設計書の作成 | アーキテクチャの計画時 |
+| `/plan` | 設計書から作業計画書を作成 | 設計承認後 |
+| `/build` | 既存の計画から実行 | 作業の再開時 |
+| `/review` | コードの準拠性確認 | 実装完了後 |
 | `/diagnose` | 根本原因分析ワークフロー | デバッグ、トラブルシューティング |
-| `/reverse-engineer` | コードからPRD/Design Docを生成 | 既存システムのドキュメント化（fullstackオプションあり） |
-| `/add-integration-tests` | 統合/E2Eテストの追加 | Design Doc存在時のテスト追加 |
-| `/update-doc` | 既存設計ドキュメントの更新 | 仕様変更、レビューフィードバック対応 |
+| `/reverse-engineer` | コードからPRD/Design Docを生成 | 既存システムのドキュメント化 |
+
+フロントエンド用（`/front-design`, `/front-build`, `/front-review`, `/front-plan`）やユーティリティコマンド（`/add-integration-tests`, `/update-doc`）も利用できます。
 
 [コマンドの詳細はこちら →](docs/guides/ja/use-cases.md)
 
@@ -264,7 +263,7 @@ ai-coding-project-boilerplate/
 
 このボイラープレートはデフォルトでnpmを使用しますが、bunやpnpmなど好みのパッケージマネージャーに切り替えることができます。
 
-`package.json`には2つの環境依存設定があります：
+`package.json`には2つの環境依存設定があります。
 
 - **`packageManager`**: 使用するパッケージマネージャーとバージョン
 - **`scripts`**: 各スクリプトの実行コマンド
@@ -286,13 +285,13 @@ ai-coding-project-boilerplate/
 }
 ```
 
-上記は代表例です。スキルやサブエージェント定義で言及されているスクリプトは以下の通りです。必要に応じて書き換えてください：
+上記は代表例です。スキルやサブエージェント定義で言及されているスクリプトは以下の通りです。必要に応じて書き換えてください。
 
 `build`, `build:frontend`, `dev`, `preview`, `type-check`, `test`, `test:coverage`, `test:coverage:fresh`, `test:safe`, `cleanup:processes`, `check`, `check:fix`, `check:code`, `check:unused`, `check:deps`, `check:all`, `format`, `format:check`, `lint`, `lint:fix`
 
 ## 🌐 多言語対応
 
-日本語と英語に対応しています：
+日本語と英語に対応しています。
 
 ```bash
 npm run lang:ja         # 日本語に切り替え
@@ -313,31 +312,24 @@ A: quality-fixerが多くの問題を自動的に検出・修正します。自
 **Q: プロジェクトに合わせたカスタマイズは可能ですか？**
 A: はい、可能です。`/project-inject`を実行してプロジェクトの前提情報を設定してください。この情報は毎セッション開始時にAIが読み込み、実行精度の向上に使われます。
 
+**Q: AIにライブラリのドキュメント（llms.txt、APIリファレンス等）を参照させることはできますか？**
+A: はい。`.claude/skills/`配下にカスタムスキルを作成し、関連するURLを記載してください。詳しくは[スキル編集ガイド](docs/guides/ja/skills-editing-guide.md)を参照してください。
+
 **Q: 基本的な開発の流れを教えてください。**
 A: 初回は`/project-inject`でプロジェクト設定を行い、その後は`/implement`で機能開発、品質チェック、コミットという流れになります。
 
-**Q: GitHub CopilotやCursorとはどう違いますか？**  
+**Q: GitHub CopilotやCursorとはどう違いますか？**
 A: これらのツールはコード記述の支援に特化していますが、本ボイラープレートは開発プロセス全体をサポートする仕組みを提供しています。
 
-## 🤖 サブエージェント一覧
-
-| エージェント | 担当領域 | 使用されるタイミング |
-|------------|---------|------------------|
-| **requirement-analyzer** | タスク規模の判定 | `/implement`コマンド実行時 |
-| **technical-designer** | 設計ドキュメントの作成 | 中規模・大規模機能の開発時 |
-| **document-reviewer** | ドキュメント品質チェック | ドキュメント作成後 |
-| **design-sync** | Design Doc間の整合性検証 | Design Doc作成後 |
-| **acceptance-test-generator** | ACからテストスケルトン生成 | 設計承認後 |
-| **work-planner** | タスクの分解と計画 | 設計完了後 |
-| **task-executor** | 実装作業 | 開発フェーズ |
-| **quality-fixer** | 品質問題の修正 | エラーや警告の検出時 |
-| **code-reviewer** | コードレビュー | `/review`コマンド実行時 |
-| **integration-test-reviewer** | テスト実装品質の検証 | テスト実装後 |
-| **investigator** | 問題調査 | `/diagnose` ステップ1 |
-| **verifier** | 調査結果の検証 | `/diagnose` ステップ3 |
-| **solver** | 解決策の導出 | `/diagnose` ステップ4 |
-| **scope-discoverer** | 機能スコープ発見 | `/reverse-engineer` ステップ1 |
-| **code-verifier** | ドキュメントとコードの整合性検証 | `/reverse-engineer` ステップ3, 8 |
+**Q: Agentic Codingとは？このボイラープレートはどう関係しますか？**
+A: Agentic Codingは、会話的なプロンプティングではなく構造化されたワークフローを専門AIエージェントに委任するアプローチです。このボイラープレートは設定済みのサブエージェント、CLAUDE.mdルール、品質チェックを提供しているので、基盤を自分で組み立てることなくすぐに実践できます。
+
+**Q: コンテキスト枯渇はどう防いでいますか？**
+A: Context Engineeringにより防止しています。各サブエージェントは単一の責務に集中した独自のコンテキストウィンドウで実行されるため、セッションが長くなってもコンテキストは常に新鮮です。実際に770K+トークンのセッションで品質低下なく開発を完了しています — 詳細は[設計思想の記事](https://qiita.com/shinpr/items/98771c2b8d2e15cafcd5)をご覧ください。
+
+## 🤖 サブエージェント
+
+要件分析、設計、計画、実装、品質保証、コードレビュー、デバッグ、リバースエンジニアリングをカバーする20以上の専門サブエージェントを搭載しています。各エージェントは独自のコンテキストウィンドウで実行されるため、集中した処理が可能です。
 
 [エージェントの詳細 →](.claude/agents-ja/)
 
@@ -347,4 +339,4 @@ MIT License - 自由に使用・改変・配布可能
 
 ## 🎯 このプロジェクトについて
 
-AI Coding Project Boilerplateは、AIを活用した開発において、コード品質と開発効率のバランスを重視して設計されています。サブエージェントによる役割分担とコンテキスト管理により、TypeScriptプロジェクトの効率的な開発をサポートします。
+AI Coding Project Boilerplateは、Claude Codeに要件分析から品質チェックまでの構造化された開発ライフサイクルを与えるツールです。専門サブエージェントとContext Engineeringにより、各エージェントが独自のコンテキストウィンドウで集中したタスクを処理するため、長時間のセッションでも品質が安定します。設定済みのCLAUDE.mdルール、カスタムスキル、スラッシュコマンドが同梱されており、ツール基盤を自分で構築することなくAgentic CodingでTypeScriptプロジェクトを始められます。

package/README.md

@@ -1,4 +1,4 @@
-# AI Coding Project Boilerplate 🤖
+# AI Coding Project Boilerplate for Claude Code 🤖
 
 *Read this in other languages: [日本語](README.ja.md)*
 
@@ -8,17 +8,19 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/shinpr/ai-coding-project-boilerplate/pulls)
 
+> **Agentic coding starter kit and workflow boilerplate for Claude Code** — Build production-ready TypeScript projects with sub-agents, context engineering, and zero context exhaustion.
+
 ⚡ **This boilerplate is for developers who want to:**
-- Build **production-ready TypeScript projects** faster with AI
+- Build **TypeScript projects** faster with AI-driven workflows
 - Avoid **context exhaustion** in long AI coding sessions
 - Standardize team workflows with **specialized AI agents**
 
 ## 📖 Table of Contents
 1. [Quick Start (3 Steps)](#-quick-start-3-steps)
 2. [Updating Existing Projects](#-updating-existing-projects)
-3. [Why Sub Agents?](#-why-sub-agents)
+3. [Beyond Vibe Coding: Why Sub Agents?](#-beyond-vibe-coding-why-sub-agents)
 4. [Skills System](#-skills-system)
-5. [Real Projects & Results](#-real-world-results)
+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)
@@ -27,15 +29,10 @@
 11. [Multilingual Support](#-multilingual-support)
 12. [FAQ](#-faq)
 
-> **Which one should you use?**
-> - **Use this Boilerplate** if you want to **maximize precision** with **TypeScript × Sub-agent** setup optimized for **Claude Code**.
-> - **Use [claude-code-workflows](https://github.com/shinpr/claude-code-workflows)** if you're on **Claude Code** and want to **start with any project** in **2 commands** and **language-agnostic** workflows.
-> - **Use [Agentic Code](https://github.com/shinpr/agentic-code)** if you want **zero-config**, **tool-agnostic** workflows **without language restrictions** (Codex CLI/Cursor/Aider etc.).
-
 ## ⚡ Quick Start (3 Steps)
 
 ```bash
-# 1. Create your project (30 seconds)
+# 1. Create your project
 npx create-ai-project my-project
 
 # 2. Install dependencies (automatic)
@@ -103,19 +100,21 @@ Ignored files are preserved during updates. Note that ignoring files may cause v
 
 If your project was created before the update feature, just run `npx create-ai-project update` from your project's root directory. It will automatically initialize the manifest by detecting your language from `.claudelang`.
 
-## 🚀 Why Sub Agents?
+## 🚀 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:
 
 **Traditional AI coding struggles with:**
 - ❌ Losing context in long sessions
-- ❌ Declining code quality over time  
+- ❌ Declining code quality over time
 - ❌ Frequent session restarts for large tasks
 
-**Sub agents solve this by:**
+**Sub agents solve this through context engineering:**
 - ✅ Splitting work into specialized roles (design, implementation, review)
-- ✅ Keeping context fresh and quality consistent
+- ✅ Each agent gets fresh, focused context — no exhaustion
 - ✅ Handling large projects without degradation
 
-Each agent focuses on one thing and does it well. No context exhaustion, no quality drop.
+This works because Claude Code's sub-agent mechanism runs each agent in its own context window. The parent session delegates tasks, and each sub-agent starts with a clean, focused context. Quality checks (lint, type check, test, build) run locally before each commit — not in CI. The feedback loop stays fast, and code is already verified when it's pushed.
 
 👉 [Learn more about Sub Agents (Anthropic docs)](https://docs.anthropic.com/en/docs/claude-code/sub-agents)
 
@@ -123,7 +122,7 @@ Each agent focuses on one thing and does it well. No context exhaustion, no qual
 
 ![Demo](./.github/assets/demo.gif)
 
-*Sub agents working together to build a production-ready TypeScript project*
+*Sub agents working together on a TypeScript project*
 
 ## 🎨 Skills System
 
@@ -146,7 +145,7 @@ This boilerplate provides the principles used in agentic implementation workflow
 
 👉 [Learn how Skills work (Claude Code docs)](https://code.claude.com/docs/en/skills)
 
-## 🎯 Real-World Results
+## 🎯 Built with This Boilerplate
 
 ### ⏱️ Time Comparison
 - **Without this boilerplate**: ~1 week for setup + infrastructure
@@ -154,24 +153,22 @@ This boilerplate provides the principles used in agentic implementation workflow
 
 ### Success Stories
 
-#### [Sub agents MCP Server](https://github.com/shinpr/sub-agents-mcp)
-**What**: MCP server enabling Claude Code/Cursor CLI as sub agents  
-**Time**: 2 days → **30 TypeScript files with full test coverage**  
-**Result**: Production-deployed, 3-minute setup
+**Sub Agents MCP Server** — MCP server enabling Claude Code/Cursor CLI as sub agents
+⏱️ Initial development in 2 days — test code makes up ~90% of the codebase, now in production
 
-#### [MCP Image Generator](https://github.com/shinpr/mcp-image)
-**What**: AI image generation via Gemini API  
-**Time**: 1.5 days → **Complete creative tool with advanced features**  
-**Result**: Multi-image blending, character consistency, one-command integration
+**MCP Image Generator** — AI image generation via Gemini API
+⏱️ Initial development in 1.5 days — complete creative tool with multi-image blending and character consistency
 
-> 💡 **Key Insight**: Proper rules + sub agents = production-quality code at AI speed
+Both were built using the default `/implement` workflow — no manual agent orchestration needed.
+
+> See these projects: [sub-agents-mcp](https://github.com/shinpr/sub-agents-mcp) ・ [mcp-image](https://github.com/shinpr/mcp-image)
 
 ## 📚 Documentation & Guides
 
 - **[Quick Start Guide](docs/guides/en/quickstart.md)** - Get running in 5 minutes
 - **[Use Cases & Commands](docs/guides/en/use-cases.md)** - Daily workflow reference
-- **[Skills Editing Guide](docs/guides/en/skills-editing-guide.md)** - Customize for your project
-- **[Design Philosophy](https://dev.to/shinpr/zero-context-exhaustion-building-production-ready-ai-coding-teams-with-claude-code-sub-agents-31b)** - Why it works (770K tokens without exhaustion)
+- **[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
 
@@ -179,20 +176,16 @@ Essential commands for Claude Code:
 
 | Command | Purpose | When to Use |
 |---------|---------|-------------|
-| `/implement` | End-to-end feature development | New features (Backend) |
+| `/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 (Backend) |
-| `/plan` | Create work plan from design | After design approval (Backend) |
-| `/build` | Execute from existing plan | Resume work (Backend) |
-| `/review` | Check code compliance | Post-implementation (Backend) |
-| `/front-design` | Create frontend design docs | React/Vite architecture planning |
-| `/front-plan` | Create frontend work plan | After frontend design approval |
-| `/front-build` | Execute frontend implementation | React component development |
-| `/front-review` | Check frontend code compliance | Post-implementation (Frontend) |
+| `/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 (fullstack option available) |
-| `/add-integration-tests` | Add integration/E2E tests | When Design Doc exists but tests missing |
-| `/update-doc` | Update existing design documents | Spec changes, review feedback |
+| `/reverse-engineer` | Generate PRD/Design Docs from code | Legacy system documentation |
+
+Frontend equivalents (`/front-design`, `/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)
 
@@ -318,31 +311,24 @@ A: quality-fixer auto-fixes most issues. If not, it provides clear instructions.
 **Q: Can I customize for my project?**
 A: Yes! Run `/project-inject` to set up project-specific prerequisites. This information is read by AI at the start of every session to improve execution accuracy.
 
+**Q: Can I make AI reference my library documentation (llms.txt, API refs, etc.)?**
+A: Yes — create a custom skill under `.claude/skills/` with the relevant URLs. See the [Skills Editing Guide](docs/guides/en/skills-editing-guide.md) for details.
+
 **Q: What's the typical workflow?**
 A: `/project-inject` (once) → `/implement` (features) → auto quality checks → commit
 
-**Q: How is this different from Copilot/Cursor?**  
+**Q: How is this different from Copilot/Cursor?**
 A: Those help write code. This manages entire development lifecycle with specialized agents.
 
-## 🤖 Complete Sub Agents Roster
-
-| Agent | Specialization | Activation |
-|-------|---------------|------------|
-| **requirement-analyzer** | Scale assessment | Start of `/implement` |
-| **technical-designer** | Design documentation | Medium/large features |
-| **document-reviewer** | Document quality check | After document creation |
-| **design-sync** | Design Doc consistency | After Design Doc creation |
-| **acceptance-test-generator** | Test skeleton from ACs | After design approval |
-| **work-planner** | Task breakdown | After design approval |
-| **task-executor** | Implementation | During build phase |
-| **quality-fixer** | Automated fixes | On any quality issue |
-| **code-reviewer** | Compliance check | `/review` command |
-| **integration-test-reviewer** | Test implementation quality | After test implementation |
-| **investigator** | Problem investigation | `/diagnose` Step 1 |
-| **verifier** | Investigation verification | `/diagnose` Step 3 |
-| **solver** | Solution derivation | `/diagnose` Step 4 |
-| **scope-discoverer** | Functional scope discovery | `/reverse-engineer` Step 1 |
-| **code-verifier** | Document-code consistency | `/reverse-engineer` verification |
+**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.
+
+**Q: How does this prevent context exhaustion?**
+A: Through context engineering. Each sub-agent runs in its own context window focused on a single responsibility, so context stays fresh regardless of session length. We've run 770K+ token sessions without quality degradation — details in the [design philosophy post](https://dev.to/shinpr/zero-context-exhaustion-building-production-ready-ai-coding-teams-with-claude-code-sub-agents-31b).
+
+## 🤖 Sub Agents
+
+20+ specialized sub-agents covering the full development lifecycle: requirement analysis, design, planning, implementation, quality assurance, code review, debugging, and reverse engineering. Each agent runs in its own context window for focused execution.
 
 [Full agent list →](.claude/agents-en/)
 
@@ -352,7 +338,7 @@ MIT License - Free to use, modify, and distribute
 
 ## 🎯 About This Project
 
-The AI Coding Project Boilerplate is engineered to maximize AI coding productivity while maintaining human-level code quality. By leveraging specialized sub agents and context engineering, it enables teams to build production-ready TypeScript applications at unprecedented speed.
+AI Coding Project Boilerplate gives Claude Code a structured development lifecycle — from requirements analysis through automated quality checks — using specialized sub-agents and context engineering. Each agent handles a focused task in its own context window, which keeps quality consistent across long sessions. The boilerplate ships with pre-configured CLAUDE.md rules, custom skills, and slash commands, so you can start building TypeScript projects with agentic workflows without assembling the tooling yourself.
 
 ---