Menú
Coordinates subagent task distribution and collaboration. Controls scale determination and autonomous execution mode.
Instalar con Codex o Claude Copia este prompt, pégalo en Codex, Claude u otro asistente, y deja que revise la página de la skill y la instale por ti.
Basado en la clasificación ocupacional SOC
PRD、ADR、Design Doc、UI Spec、作業計画書の作成を支援。技術ドキュメントの作成・レビュー時、または「UI Spec/画面設計/コンポーネント分解」が言及された時に使用。
入力・出力・成功基準・決定事項・未解決条件を明確化し、下流エージェントが推測せず実行できるようにする。LLM向けのプロンプト・ハンドオフ・計画成果物・レビュー・レポート・生成指示を記述または改訂する時に使用。
タスクの本質を分析し適切なスキルを選択。規模見積もりとメタデータを返却。タスク開始時、スキル選択時に使用。
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.
Clarifies inputs, outputs, success criteria, decisions, and unresolved conditions so downstream agents can execute without guessing. Use when writing or revising LLM-facing prompts, handoffs, planning artifacts, reviews, reports, or generated instructions.
Analyzes task essence and selects appropriate skills. Returns scale estimates and metadata. Use when starting tasks or selecting skills.
| 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 | verdict.decision (approved/approved_with_conditions/needs_revision/rejected) | Proceed on approved/approved_with_conditions; request fixes on needs_revision; escalate on rejected |
| 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:
needs_revision: re-invoke work-planner (update) and re-review until approved/approved_with_conditions — the plan is a derivation of the Design Doc, so plan-fidelity findings need no user adjudication. On rejected: escalate to user. [Stop: Batch approval]needs_revision: re-invoke work-planner (update) and re-review until approved/approved_with_conditions — the plan is a derivation of the Design Doc, so plan-fidelity findings need no user adjudication. On rejected: escalate to user. [Stop: Batch approval]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 implementation proceeds directly. Verifying the plan is implementable end-to-end (verification-strategy references, fixtures, UI rendering surface, E2E/local lane environment) is an optional preflight the user runs at their discretion via the prepare-implementation recipe, which exits no-op when readiness criteria already pass. This guide does not invoke any orchestrator above the agent layer.
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.