// Coordinates subagent task distribution and collaboration. Controls scale determination and autonomous execution mode.
| name | subagents-orchestration-guide |
| description | Coordinates subagent task distribution and collaboration. Controls scale determination and autonomous execution mode. |
This document provides practical behavioral guidelines for me (Claude) to efficiently process tasks by utilizing subagents.
Role Definition: I am an orchestrator, not an executor.
When receiving a new task, pass user requirements directly to requirement-analyzer. Determine the workflow based on its scale assessment result.
During flow execution, if detecting the following in user response, stop flow and go to requirement-analyzer:
If any one applies -> Restart from requirement-analyzer with integrated requirements
I pass what to accomplish and where to work. Each specialist determines how to execute autonomously.
I pass to specialists (what/where/constraints):
I let specialists determine (how):
| 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:
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.
I understand each subagent's responsibilities and assign work appropriately:
task-executor Responsibilities (DELEGATE these):
quality-fixer Responsibilities (DELEGATE these):
Basic Cycle: I manage the 4-step cycle of task-executor -> escalation judgment/follow-up -> quality-fixer -> commit.
I repeat this cycle for each task to ensure quality.
Layer-Aware Routing: For cross-layer features, select executor and quality-fixer by task filename pattern (see Cross-Layer Orchestration).
Important: Subagents cannot directly call other subagents. When coordinating multiple subagents, the main AI (Claude) operates as the orchestrator.
| Scale | File Count | PRD | ADR | Design Doc | Work Plan |
|---|---|---|---|---|---|
| Small | 1-2 | Update1 | Not needed | Not needed | Single task file in task-template format under docs/plans/tasks/ (no separate plan document) |
| Medium | 3-5 | Update1 | Conditional2 | Required | Required |
| Large | 6+ | Required3 | Conditional2 | Required | Required |
All subagent invocation uses the Agent tool with:
subagent_type: Agent name (e.g., "task-executor")description: Concise task description (3-5 words)prompt: Specific instructions including deliverable pathsThe orchestrator coordinates work using only the following tools:
| Tool | Purpose |
|---|---|
| Agent | Invoke subagents |
| AskUserQuestion | User confirmations and questions |
| TaskCreate / TaskUpdate | Progress tracking |
| Bash | Shell operations (git commit, ls, verification commands) |
| Read | Deliverable documents for information bridging between subagents |
All implementation work (Edit, Write, MultiEdit) is performed by subagents, not the orchestrator.
Subagents respond in JSON format. Key fields for orchestrator decisions:
| 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, qualityAssurance (mechanisms[], domainConstraints[]), focusAreas[], existingElements count, limitations | Pass focusAreas to technical-designer as context |
| ui-analyzer | externalResources (status, per-axis fetch_status), componentStructure[], propsPatterns[], cssLayout[], stateDisplay[], focusAreas[], candidateWriteSet[], limitations | Pass the ui-analyzer JSON to ui-spec-designer and technical-designer-frontend; each consumes the fields named in its own input declaration |
| code-verifier | status (consistent/mostly_consistent/needs_review/inconsistent), consistencyScore, discrepancies[], reverseCoverage (dataOperationsInCode, testBoundariesSectionPresent). Pre-implementation: verifies Design Doc claims against existing codebase. Post-implementation: verifies implementation consistency against Design Doc (pass code_paths scoped to changed files) | Flag discrepancies for document-reviewer |
| task-executor | Input: task_file (required in orchestrated flows); optional Fix Mode signals requiredFixes or incompleteImplementations — when either is non-empty, skip task_already_completed and extend allowed list with each item's file_path / location (parse location as file[:line]); each incompleteImplementations[] entry may carry type: "missing_logic" | "hollow_test" and the executor branches its fix action by type. Output: status (escalation_needed/completed), filesModified[], testsAdded, requiresTestReview, runnableCheck{level, executed, command, result, substance, substanceIssue, reason}, escalation_type ∈ {task_file_not_found, task_already_completed, target_files_missing, design_compliance_violation, similar_function_found, similar_component_found, investigation_target_not_found, out_of_scope_file, dependency_version_uncertain, binding_decision_violation, test_environment_not_ready}. | On escalation_needed: handle by escalation_type |
| quality-fixer | Input: task_file (path to current task file — always pass this in orchestrated flows), filesModified (extract from the upstream implementation step's response — passes the task's write set as the primary scope for stub-detection; falls back to git diff HEAD when omitted), runnableCheck (extract from the upstream implementation step's response — passes the test execution evidence including substance and substanceIssue so the substance check has the runtime signal; omit when the upstream did not run tests). Status: approved/stub_detected/blocked. stub_detected → incompleteImplementations[] items carry type: "missing_logic" | "hollow_test"; route back to the implementation step (which branches its fix action on type), then re-run quality-fixer. blocked → see quality-fixer blocked handling below | On stub_detected: re-invoke the implementation step. On blocked: see handling below |
| document-reviewer | approvalReady (true/false) | Proceed to next step on true; request fixes on false |
| design-sync | sync_status (NO_CONFLICTS/CONFLICTS_FOUND) | On CONFLICTS_FOUND: present conflicts to user before proceeding |
| integration-test-reviewer | status (approved/needs_revision/blocked), requiredFixes | On needs_revision: re-invoke the routed executor in Fix Mode with the same task_file and requiredFixes[] |
| security-reviewer | status (approved/approved_with_notes/needs_revision/blocked), findings, notes, requiredFixes | On needs_revision: create a consolidated fix task file with the affected file paths from requiredFixes[].location populated into Target Files, then invoke the routed executor in Fix Mode with that task_file and the requiredFixes[] array, then quality-fixer, then re-invoke security-reviewer to verify resolution. On blocked: escalate to user with the blocking findings — fix is not within the agent layer's authority |
| acceptance-test-generator | status, generatedFiles.{integration,fixtureE2e,serviceE2e} (path|null per lane), budgetUsage per lane, e2eAbsenceReason per E2E lane (null when emitted; reason enum is owned by acceptance-test-generator and integration-e2e-testing skill) | Verify each non-null file path exists, pass per-lane paths and absence reasons to work-planner |
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 stepsWhen receiving new features or change requests, I first request requirement analysis from requirement-analyzer. According to scale determination:
docs/plans/tasks/ instead of a separate work plan + decomposition; that path is what task-executor receives as task_file. [Stop: Batch approval]Note: At Small scale the implementation step still runs through task-executor with the standard 4-step cycle (task-executor → escalation judgment → quality-fixer → commit). Direct orchestrator edits are not used.
For Medium / Large scale, after Batch approval the work plan carries an Implementation Readiness: header (work-planner emits pending; promotion to ready or escalated is an external orchestration concern). The marker takes one of three values:
pending — initial state set by work-plannerready — readiness verification has completed with no remaining gaps; safe to start the task execution cycleescalated — readiness verification has completed but residual gaps require user judgment before executionExternal orchestration owns both the producer that promotes the marker beyond pending and the consumer that reads it before invoking task-executor. This guide does not invoke any orchestrator above the agent layer; agents read/write the marker only when explicitly asked.
When requirement-analyzer determines the feature spans multiple layers (backend + frontend) via crossLayerScope, the following extensions apply. Step numbers below follow the large-scale flow. For medium-scale flows where Design Doc creation starts at step 2, apply the same pattern as steps 2a/2b/3/4.
Replace the standard Design Doc creation step with per-layer creation:
| Step | Agent | Purpose |
|---|---|---|
| 8 | codebase-analyzer ×2 | Codebase analysis per layer (pass req-analyzer output, filtered to layer) |
| 9 | technical-designer | Backend Design Doc (with backend codebase-analyzer context) |
| 10 | code-verifier | Verify Backend Design Doc against existing code (its result JSON becomes prior_layer_verification for step 12) |
| 11 | document-reviewer | Review Backend Design Doc (pass step-10 result as code_verification and backend codebase-analyzer JSON as codebase_analysis). [Stop on critical issues] — structural defects here block step 12. |
| 12 | technical-designer-frontend | Frontend Design Doc (with frontend codebase-analyzer context + reviewed Backend Design Doc + prior_layer_verification from step 10 + UI Spec) |
| 13 | code-verifier | Verify Frontend Design Doc against existing code |
| 14 | document-reviewer | Review Frontend Design Doc (pass step-13 result as code_verification and frontend codebase-analyzer JSON as codebase_analysis). [Stop on critical issues] — structural defects here block step 15. |
| 15 | design-sync | Cross-layer consistency verification [Stop] |
The codebase-analyzer ×2 invocations can run in parallel. The backend path (steps 9-11) runs sequentially before step 12 so that the frontend designer reads a backend Design Doc whose structural defects (AC gaps, Fact Disposition Table issues, Verification Strategy defects) have already been surfaced by document-reviewer, and whose code/doc discrepancies have already been enumerated by code-verifier. The frontend designer can then identify which backend contracts have known issues via prior_layer_verification.discrepancies[] and the step-11 review feedback, and design around those unstable surfaces (route integration points to stable contracts, or record the dependency in ## Cross-Layer Assumptions).
Layer Context in Design Doc Creation:
prior_layer_verification.discrepancies[] and the review findings; limit verified-claim inference to what the verifier output states explicitly. For contracts you must depend on that remain unverified, list them in the ## Cross-Layer Assumptions section with justification and verification target. Reference UI Spec at [path] for component structure. Focus on: component hierarchy, state management, UI interactions, data fetching."design-sync: Use frontend Design Doc as source. design-sync auto-discovers other Design Docs in docs/design/ for comparison.
Pass all Design Docs to work-planner with vertical slicing instruction:
During autonomous execution, route agents by task filename pattern:
| Filename Pattern | Executor | Quality Fixer |
|---|---|---|
*-task-* or *-backend-task-* | task-executor | quality-fixer |
*-frontend-task-* | task-executor-frontend | quality-fixer-frontend |
After starting autonomous execution mode:
status: escalation_needed or status: blocked -> Escalate to userrequiresTestReview is true -> Execute integration-test-reviewer
needs_revision -> Re-invoke the routed executor (task-executor or task-executor-frontend per Layer-Aware Agent Routing) in Fix Mode with the same task_file and the requiredFixes[] arrayapproved -> Proceed to quality-fixerStop autonomous execution and escalate to user in the following cases:
Escalation from subagent
status: "escalation_needed"status: "blocked"When requirement change detected
When work-planner update restriction is violated
When user explicitly stops
Every subagent prompt must include:
Construct the prompt from the agent's Input Parameters section and the deliverables available at that point in the flow.
Two additional rules:
[placeholder] in examples below with concrete values before invoking the Agent tool.State Management: Grasp current phase, each subagent's state, and next action
Information Bridging: Data conversion and transmission between subagents
Pass to codebase-analyzer: requirement-analyzer JSON output, PRD path (if exists), original user requirements Pass to technical-designer: codebase-analyzer JSON output as additional context in the Design Doc creation prompt. Required downstream uses:
focusAreas → canonical disposition-target list for the Fact Disposition Table (one row per focusArea, carrying through fact_id and evidence verbatim)dataModel, dataTransformationPipelines, qualityAssurance → Existing Codebase Analysis, Verification Strategy, and Quality Assurance Mechanisms sectionsPass to code-verifier: Design Doc path (doc_type: design-doc). Omit code_paths; the verifier independently discovers code scope from the document.
Pass to document-reviewer: code-verifier JSON output as code_verification parameter, and the same codebase-analyzer JSON previously given to the designer as codebase_analysis. The reviewer uses codebase_analysis.focusAreas to verify Fact Disposition Table coverage.
Pass to next-layer technical-designer: reviewed prior-layer Design Doc path plus prior_layer_verification (the JSON from the prior-layer code-verifier). See Cross-Layer Orchestration section for sequencing. Use prior_layer_verification.discrepancies[] plus prior-layer review findings to identify unstable contracts. Limit verified-claim inference to what the verifier output states explicitly; when the design must depend on a claim not confirmed by the verifier, record it in the frontend Design Doc's ## Cross-Layer Assumptions section with justification and a verification target (escalation uses the same section with verify at: escalation to user — choose escalation only when the dependency cannot be bounded by a downstream verification step).
Pass to work-planner: Design Doc path. Work-planner scans all DD sections and extracts technical requirements per its Step 5 categories (impl-target, connection-switching, contract-change, verification, prerequisite), then produces a Design-to-Plan Traceability table.
Gap handling (orchestrator responsibility): If work-planner outputs a draft plan containing gap entries, the orchestrator MUST:
Pass to acceptance-test-generator: Design Doc path; UI Spec path (if exists).
Orchestrator verification: Every non-null generatedFiles.<lane> path exists on disk. For each null lane, e2eAbsenceReason.<lane> is present — this is intentional absence, not an error.
Pass to work-planner: integration / fixture-e2e / service-integration-e2e file paths (or null per lane), per-lane absence reasons, plus timing guidance — integration tests are created alongside each phase implementation, fixture-e2e tests are created alongside the UI feature phase, service-integration-e2e tests are executed only in the final phase.
On error: Escalate to user when status != completed and integration file generation failed unexpectedly. A null E2E lane with a valid absence reason is not an error.
ADR Status Management: Update ADR status after user decision (Accepted/Rejected)
Register overall phases using TaskCreate. Update each phase with TaskUpdate as it completes.
| Verifier | Pass | Fail | Blocked |
|---|---|---|---|
| code-verifier | status is consistent or mostly_consistent | status is needs_review or inconsistent | — |
| security-reviewer | status is approved or approved_with_notes | status is needs_revision | status is blocked → Escalate to user |
Re-run rule: After fix cycle, re-run only verifiers that returned fail. Verifiers that passed on the previous run are not re-run. Maximum 2 fix cycles — if still failing after 2 cycles, escalate to user with remaining findings.
サブエージェントのタスク分担と連携を調整。規模判定と自律実行モードを制御。大規模タスク分割時に使用。
PRD、ADR、Design Doc、UI Spec、作業計画書の作成を支援。技術ドキュメントの作成・レビュー時、または「UI Spec/画面設計/コンポーネント分解」が言及された時に使用。
Guides PRD, ADR, Design Doc, UI Spec, and Work Plan creation. Use when creating or reviewing technical documents, or when "UI spec/screen design/component decomposition" is mentioned.
コードの品質問題、アンチパターン、可読性を検査。機能実装、コードレビュー、リファクタリング時に使用。
Detects code smells, anti-patterns, and readability issues. Use when implementing features, reviewing code, or refactoring.
Provides project-specific prerequisites for AI execution accuracy — domain constraints, development phase, directory conventions, external resource access methods. Use when the session starts, when checking project structure, or when a task references domain rules or external resources outside the repository.