feat: add Delegation Boundary and improve orchestration guide precision

.claude/skills-en/subagents-orchestration-guide/SKILL.md

@@ -16,12 +16,9 @@ This document provides practical behavioral guidelines for me (Claude) to effici
 - **During flow execution**: STRICTLY follow scale-based flow
 - **Each phase**: DELEGATE to appropriate subagent
 - **Stop points**: ALWAYS wait for user approval
-
-### Prohibited Actions
-- Executing investigation directly with Grep/Glob/Read
-- Performing analysis or design without subagent delegation
-- Saying "Let me first investigate" then starting work directly
-- Skipping or postponing requirement-analyzer
+- **Investigation**: Delegate all investigation to requirement-analyzer or codebase-analyzer (Grep/Glob/Read are specialist-internal tools)
+- **Analysis/Design**: Delegate to the appropriate specialist subagent
+- **First action**: Pass user requirements to requirement-analyzer before any other step
 
 **First Action Rule**: To accurately analyze user requirements, pass them directly to requirement-analyzer and determine the workflow based on its analysis results.
 
@@ -68,6 +65,36 @@ graph TD
 
 ## My Orchestration Principles
 
+### Delegation Boundary: What vs How
+
+I pass **what to accomplish** and **where to work**. Each specialist determines **how to execute** autonomously.
+
+**I pass to specialists** (what/where/constraints):
+- Task file path — executor agents (task-executor, task-decomposer) receive a task file path; broader scope requires explicit user request
+- Target directory or package scope — for discovery/review agents (codebase-analyzer, code-verifier, security-reviewer, integration-test-reviewer)
+- Acceptance criteria and hard constraints from the user or design artifacts
+
+**I let specialists determine** (how):
+- Specific commands to run (specialists discover these from project configuration and repo conventions)
+- Execution order and tool flags
+- Executor/fixer agents: which files to inspect or modify within the given scope
+- Review/discovery agents: which files to inspect within the given scope (read-only access)
+
+| | Bad (I prescribe how) | Good (I pass what) |
+|---|---|---|
+| quality-fixer | "Run these checks: 1. lint 2. test" | "Execute all quality checks and fixes" |
+| task-executor | "Edit file X and add handler Y" | "Task file: docs/plans/tasks/003-feature.md" |
+
+**Decision precedence when outputs conflict**:
+1. User instructions (explicit requests or constraints)
+2. Task files and design artifacts (Design Doc, PRD, work plan)
+3. Objective repo state (git status, file system, project configuration)
+4. Specialist judgment
+
+When two specialists conflict, or when a specialist conflicts with my expectation, I apply the precedence order above. I verify against objective repo state (item 3). I follow specialist output when it aligns with items 1 and 2. When specialist output conflicts with user instructions or design artifacts, I follow user instructions first, then design artifacts.
+
+When a specialist cannot determine execution method from repo state and artifacts, the specialist escalates as blocked. I then escalate to the user with the specialist's blocked details.
+
 ### Task Assignment with Responsibility Separation
 
 I understand each subagent's responsibilities and assign work appropriately:
@@ -109,16 +136,25 @@ I repeat this cycle for each task to ensure quality.
 ## Structured Response Specifications
 
 Subagents respond in JSON format. Key fields for orchestrator decisions:
-- **requirement-analyzer**: scale, confidence, adrRequired, crossLayerScope, scopeDependencies, questions
-- **codebase-analyzer**: analysisScope.categoriesDetected, dataModel.detected, focusAreas[], existingElements count, limitations
-- **code-verifier**: (in design flow) consistencyScore, discrepancies[], reverseCoverage (including dataOperationsInCode, testBoundariesSectionPresent)
-- **task-executor**: status (escalation_needed/completed), escalation_type (design_compliance_violation/similar_function_found/similar_component_found/investigation_target_not_found/out_of_scope_file), testsAdded, requiresTestReview
-- **quality-fixer**: status (approved/blocked). Discriminate blocked type by `reason` field: `"Cannot determine due to unclear specification"` → read `blockingIssues[]` for specification details; `"Execution prerequisites not met"` → read `missingPrerequisites[]` with `resolutionSteps` — present these to the user as actionable next steps
-- **document-reviewer**: approvalReady (true/false)
-- **design-sync**: sync_status (synced/conflicts_found)
-- **integration-test-reviewer**: status (approved/needs_revision/blocked), requiredFixes
-- **security-reviewer**: status (approved/approved_with_notes/needs_revision/blocked), findings, notes, requiredFixes
-- **acceptance-test-generator**: status, generatedFiles
+
+| Agent | Key Fields | Decision Logic |
+|-------|-----------|----------------|
+| requirement-analyzer | scale, confidence, adrRequired, crossLayerScope, scopeDependencies, questions | Select flow by scale; check adrRequired for ADR step |
+| codebase-analyzer | analysisScope.categoriesDetected, dataModel.detected, focusAreas[], existingElements count, limitations | Pass focusAreas to technical-designer as context |
+| code-verifier | consistencyScore, discrepancies[], reverseCoverage (dataOperationsInCode, testBoundariesSectionPresent) | Flag discrepancies for document-reviewer |
+| task-executor | status (escalation_needed/completed), escalation_type, testsAdded, requiresTestReview | On escalation_needed: handle by 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[] | On blocked: see quality-fixer blocked handling below |
+| document-reviewer | approvalReady (true/false) | Proceed to next step on true; request fixes on false |
+| design-sync | sync_status (synced/conflicts_found) | On conflicts_found: present conflicts to user before proceeding |
+| integration-test-reviewer | status (approved/needs_revision/blocked), requiredFixes | On needs_revision: pass requiredFixes back to task-executor |
+| security-reviewer | status (approved/approved_with_notes/needs_revision/blocked), findings, notes, requiredFixes | On needs_revision: pass requiredFixes back to task-executor |
+| acceptance-test-generator | status, generatedFiles | Pass generatedFiles to work-planner |
+
+### quality-fixer Blocked Handling
+
+When quality-fixer returns `status: "blocked"`, discriminate by `reason`:
+- `"Cannot determine due to unclear specification"` → read `blockingIssues[]` for specification details
+- `"Execution prerequisites not met"` → read `missingPrerequisites[]` with `resolutionSteps` and present to user as actionable next steps
 
 ## My Basic Flow for Work Planning
 
@@ -301,7 +337,7 @@ Construct the prompt from the agent's Input Parameters section and the deliverab
 - **Structured response is MANDATORY**: Information transmission between subagents MUST use JSON format
 - **Approval management**: Document creation -> Execute document-reviewer -> Get user approval BEFORE proceeding
 - **Flow confirmation**: After getting approval, ALWAYS check next step with work planning flow (large/medium/small scale)
-- **Consistency verification**: IF subagent determinations contradict -> prioritize these guidelines
+- **Consistency verification**: When subagent outputs conflict, apply Decision precedence (see Delegation Boundary section)
 
 ## Required Dialogue Points with Humans
 

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

@@ -16,12 +16,9 @@ description: サブエージェントのタスク分担と連携を調整。規
 - フロー実行中: 規模判定に基づくフローを厳守
 - 各フェーズ: 適切なサブエージェントに委譲
 - 停止ポイント: 必ずユーザー承認を待つ
-
-### 避ける行為
-- Grep/Glob/Readで自分で調査を始める
-- 自分で分析や設計を考え始める
-- 「まず調べてみます」と言って作業を開始する
-- requirement-analyzerを後回しにする
+- **調査**: すべての調査はrequirement-analyzerまたはcodebase-analyzerに委譲（Grep/Glob/Readはサブエージェント内部のツール）
+- **分析・設計**: 該当するサブエージェントに委譲
+- **初動**: ユーザー要件はrequirement-analyzerに渡してから他のステップへ進む
 
 **初動アクション規則**: ユーザー要件を正確に分析するため、requirement-analyzerに直接渡し、その分析結果に基づいてワークフローを決定する。
 
@@ -34,6 +31,8 @@ graph TD
     Scale --> Flow[規模に応じたフロー実行]
 ```
 
+**フロー実行中は規模判定表に従って次のサブエージェントを決定する**
+
 ### フロー実行中の要件変更検知
 
 **フロー実行中**にユーザーレスポンスで以下を検知したら、フローを停止してrequirement-analyzerへ：
@@ -66,6 +65,36 @@ graph TD
 
 ## オーケストレーション原則
 
+### 委譲の境界: What vs How
+
+「何を達成するか」「どこで作業するか」を渡す。各サブエージェントは「どう実行するか」を自律的に決定する。
+
+**渡す情報**（what/where/制約）:
+- タスクファイルパス — executor系（task-executor, task-decomposer）にはタスクファイルパスを渡す。より広いスコープはユーザーの明示的な要求がある場合のみ
+- ディレクトリまたはパッケージスコープ — discovery/review系（codebase-analyzer, code-verifier, security-reviewer, integration-test-reviewer）向け
+- ユーザーまたは設計成果物からの受入条件とハード制約
+
+**サブエージェントに委ねる判断**（how）:
+- 実行するコマンド（プロジェクト設定やリポジトリの規約からサブエージェントが判断）
+- 実行順序やツールフラグ
+- Executor/fixer系: スコープ内で調査・変更するファイルの選択
+- Review/discovery系: スコープ内で調査するファイルの選択（読み取り専用）
+
+| | Bad（howを指定） | Good（whatを指定） |
+|---|---|---|
+| quality-fixer | 「lint → test の順でチェックして」 | 「品質チェックと修正をすべて実行して」 |
+| task-executor | 「ファイルXにハンドラYを追加して」 | 「タスクファイル: docs/plans/tasks/003-feature.md」 |
+
+**出力が矛盾した場合の優先順位**:
+1. ユーザー指示（明示的な要求や制約）
+2. タスクファイルと設計成果物（Design Doc, PRD, 作業計画書）
+3. リポジトリの客観的状態（git status、ファイルシステム、プロジェクト設定）
+4. サブエージェントの判断
+
+サブエージェント同士の判断が衝突した場合、またはサブエージェントの出力が期待と異なる場合、上記の優先順位を適用する。リポジトリの客観的状態（3）で検証し、1・2と整合する出力に従う。矛盾がある場合はユーザー指示、次いで設計成果物に従う。
+
+サブエージェントがリポジトリの状態や成果物から実行方法を判断できない場合、blockedステータスでエスカレーションする。その詳細をユーザーに伝える。
+
 ### 責務分離を意識した振り分け
 
 **task-executorの責務**:
@@ -105,16 +134,25 @@ graph TD
 ## 構造化レスポンス仕様
 
 サブエージェントはJSON形式で応答。オーケストレーター判断に必要なフィールド：
-- **requirement-analyzer**: scale, confidence, adrRequired, crossLayerScope, scopeDependencies, questions
-- **codebase-analyzer**: analysisScope.categoriesDetected, dataModel.detected, focusAreas[], existingElements count, limitations
-- **code-verifier**:（設計フロー時）consistencyScore, discrepancies[], reverseCoverage（dataOperationsInCode, testBoundariesSectionPresent含む）
-- **task-executor**: status (escalation_needed/completed), escalation_type (design_compliance_violation/similar_function_found/similar_component_found/investigation_target_not_found/out_of_scope_file), testsAdded, requiresTestReview
-- **quality-fixer**: status (approved/blocked)。blockedタイプは`reason`フィールドで判別: `"Cannot determine due to unclear specification"` → `blockingIssues[]`で仕様詳細を参照; `"Execution prerequisites not met"` → `missingPrerequisites[]`の`resolutionSteps`を参照し、ユーザーにアクション可能なステップとして提示
-- **document-reviewer**: approvalReady (true/false)
-- **design-sync**: sync_status (synced/conflicts_found)
-- **integration-test-reviewer**: status (approved/needs_revision/blocked), requiredFixes
-- **security-reviewer**: status (approved/approved_with_notes/needs_revision/blocked), findings, notes, requiredFixes
-- **acceptance-test-generator**: status, generatedFiles
+
+| Agent | 主要フィールド | 判断ロジック |
+|-------|---------------|-------------|
+| 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に連携 |
+| 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で修正を依頼 |
+| design-sync | sync_status (synced/conflicts_found) | conflicts_found時: 矛盾をユーザーに提示してから進む |
+| integration-test-reviewer | status (approved/needs_revision/blocked), requiredFixes | needs_revision時: requiredFixesをtask-executorに戻す |
+| security-reviewer | status (approved/approved_with_notes/needs_revision/blocked), findings, notes, requiredFixes | needs_revision時: requiredFixesをtask-executorに戻す |
+| acceptance-test-generator | status, generatedFiles | generatedFilesをwork-plannerに渡す |
+
+### quality-fixer blockedハンドリング
+
+quality-fixerが `status: "blocked"` を返した場合、`reason`で判別：
+- `"Cannot determine due to unclear specification"` → `blockingIssues[]`で仕様詳細を確認
+- `"Execution prerequisites not met"` → `missingPrerequisites[]`の`resolutionSteps`をユーザーにアクション可能なステップとして提示
 
 ## 作業計画時の基本フロー
 
@@ -295,7 +333,7 @@ requirement-analyzerが複数レイヤー（backend + frontend）にまたがる
 - **構造化レスポンス必須**: サブエージェント間の情報伝達はJSON形式
 - **承認管理**: ドキュメント作成→document-reviewer実行→ユーザー承認を得てから次へ進む
 - **フロー確認**: 承認取得後は必ず作業計画フロー（大規模/中規模/小規模）で次のステップを確認
-- **整合性検証**: サブエージェント判定に矛盾がある場合はガイドラインを優先
+- **整合性検証**: サブエージェントの出力が矛盾した場合、優先順位に従って解決（委譲の境界セクション参照）
 
 ## 人間との必須対話ポイント
 

CHANGELOG.md

@@ -5,6 +5,22 @@ 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.2] - 2026-04-03
+
+### Added
+
+- **Delegation Boundary: What vs How** (subagents-orchestration-guide): Orchestrator lacked a definition of what granularity to pass to specialists vs what to let them decide autonomously. Added what/where/constraints vs how separation, Bad/Good comparison table, 4-tier decision precedence for conflict resolution, and escalation rule for undeterminable execution methods
+- **Scope granularity per agent type**: Executor agents receive task file paths by default (broader scope requires explicit user request); discovery/review agents receive directory or package scope with read-only access
+- **quality-fixer blocked handling subsection** (Structured Response Specifications): Moved quality-fixer's multi-branch decision logic from an overloaded table cell into a dedicated subsection for scannability
+
+### Changed
+
+- **Prohibited Actions → positive-form Required Actions**: Negative instructions ("don't investigate directly", "don't skip requirement-analyzer") caused Pink Elephant Problem. Converted to affirmative delegation instructions ("Delegate all investigation to requirement-analyzer or codebase-analyzer")
+- **Structured Response Specifications table format**: Bullet list with mixed-length entries replaced with Agent / Key Fields / Decision Logic table. Each agent's response-to-action mapping is now explicit
+- **Consistency verification constraint**: Vague "prioritize these guidelines" replaced with reference to Decision precedence in the Delegation Boundary section
+- **Remaining negative-form instructions cleaned**: "no modification" → "read-only access", "instead of guessing" removed, "higher-precedence source" → explicit "user instructions first, then design artifacts"
+- **Japanese version: missing operational line added**: "フロー実行中は規模判定表に従って次のサブエージェントを決定する" was present in English but missing in Japanese
+
 ## [1.20.1] - 2026-04-02
 
 ### Added

package.json

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