subagents-orchestration-guide

name	subagents-orchestration-guide
description	Guides subagent coordination through implementation workflows. Use when: orchestrating multiple agents, managing workflow phases, determining autonomous execution mode, or coordinating recipe execution.

Subagents Orchestration Guide

Spawn rule: every spawn_agent call uses fork_turns="none" so the subagent receives only the task message and explicitly provided context.

Role: The Orchestrator

The orchestrator coordinates subagents. All investigation, analysis, and implementation work flows through specialized subagents.

Prompt Construction Rule

Every subagent prompt must include:

1. Input deliverables with file paths (from previous step or prerequisite check)
2. Expected action (what the agent should do)

Construct the prompt from the agent's Input Parameters section and the deliverables available at that point in the flow.

Automatic Responses

Trigger	Action
New task	Spawn requirement-analyzer
Flow in progress	Check scale determination table for next subagent
Phase completion	Spawn the appropriate agent
Stop point reached	Wait for user approval

First Action Rule [MANDATORY]

To accurately analyze user requirements, pass them directly to requirement-analyzer and determine the workflow based on its analysis results.

ENFORCEMENT: MUST spawn requirement-analyzer as first action for every new task

Decision Flow When Receiving Tasks

Receive New Task -> Analyze requirements with requirement-analyzer
                 -> Scale assessment
                 -> Execute flow based on scale

During flow execution, determine next subagent according to scale determination table

Requirement Change Detection During Flow [MANDATORY]

During flow execution, if detecting the following in user response, MUST stop flow and go to requirement-analyzer:

• Mentions of new features/behaviors (additional operation methods, display on different screens, etc.)
• Additions of constraints/conditions (data volume limits, permission controls, etc.)
• Changes in technical requirements (processing methods, output format changes, etc.)

ENFORCEMENT: If any one applies — MUST restart from requirement-analyzer with integrated requirements

Available Subagents

The following subagents are available:

Implementation Support Agents

1. quality-fixer: Self-contained processing for overall quality assurance and fixes until completion
2. task-decomposer: Appropriate task decomposition of work plans
3. task-executor: Individual task execution and structured response
4. integration-test-reviewer: Review integration/E2E tests for skeleton compliance and quality
5. security-reviewer: Security compliance review against Design Doc and coding-rules after all tasks complete

Document Creation Agents

6. requirement-analyzer: Requirement analysis and work scale determination
7. codebase-analyzer: Existing codebase analysis before Design Doc creation
8. prd-creator: Product Requirements Document creation
9. ui-spec-designer: UI Specification creation from PRD and optional prototype code (frontend/fullstack features)
10. technical-designer: ADR/Design Doc creation
11. work-planner: Work plan creation from Design Doc and test skeletons
12. document-reviewer: Single document quality and rule compliance check
13. code-verifier: Document-code consistency verification for review inputs and post-implementation verification
14. design-sync: Design Doc consistency verification across multiple documents
15. acceptance-test-generator: Generate integration and E2E test skeletons from Design Doc ACs
16. ui-analyzer: UI fact gathering from external resources and existing frontend code before UI Spec, Design Doc, or adjustment work

Orchestration Principles

Task Assignment with Responsibility Separation [MANDATORY]

Assign work based on each subagent's responsibilities:

What to spawn task-executor for:

• Implementation work and test addition
• Confirmation of added tests passing (existing tests are not covered)
• Spawn quality-fixer exclusively for quality assurance

What to spawn quality-fixer for:

• Overall quality assurance (static analysis, style check, all test execution, etc.)
• Complete execution of quality error fixes
• Self-contained processing until fix completion
• Final approved judgment (only after fixes are complete)

Constraints Between Subagents [MANDATORY]

Subagents CANNOT directly call other subagents — all coordination MUST flow through the orchestrator.

ENFORCEMENT: Direct subagent-to-subagent communication is PROHIBITED

Subagent Completion Discipline [MANDATORY]

The orchestrator owns subagent completion. Base waiting decisions on assigned responsibility and observed state, not on an expectation of quick completion. Multi-step search, review, verification, generation, implementation, and quality work can run for extended periods.

Use this contract:

• Workflow subagents are single-purpose workers expected to converge.
• When waiting for a workflow subagent, set timeout_ms to the maximum value accepted by the active wait_agent tool and continue waiting until its completion notification is received.
• Treat timed_out=true as pending and continue waiting.
• Hold final artifact production until every required subagent output is available.

Treat the following as explicit contradictory evidence:

• The subagent returns a terminal status such as approved, needs_revision, blocked, skipped, completed, or escalation_needed
• The orchestrator verifies that it launched the wrong subagent or sent materially incorrect inputs
• A newer explicit user instruction changes or cancels the task

Close a running subagent only when the user redirects the workflow, the orchestrator corrects a launch mistake, or a newer user instruction supersedes the pending task.

ENFORCEMENT: Preserve subagent execution until completion, user redirection, or explicit correction of an orchestrator launch mistake. Speed-based early termination is a CRITICAL VIOLATION.

How to Spawn Agents

Spawn agents using natural language prompts. Provide clear context about what the agent should accomplish. Apply the Spawn rule above.

Spawn Prompt Requirements

• Each spawn prompt must name the target deliverable, input paths, and expected result. When invoking task-executor*, include the exact task file path, for example: Execute the implementation task. Task file: docs/plans/tasks/[filename].md.

Explicit Stop Points [MANDATORY]

Autonomous execution MUST stop and wait for user input at these points.

Phase	Stop Point	User Action Required
Requirements	After requirement-analyzer completes	Confirm requirements / Answer questions
PRD	After document-reviewer completes PRD review	Approve PRD
UI Spec	After document-reviewer completes UI Spec review (frontend/fullstack)	Approve UI Spec
ADR	After document-reviewer completes ADR review (if ADR created)	Approve ADR
Design	After design-sync completes consistency verification	Approve Design Doc
Work Plan	After document-reviewer completes WorkPlan review for Medium/Large, or after simplified plan creation for Small	Batch approval for implementation phase

ENFORCEMENT: After batch approval, autonomous execution proceeds without stops until completion or escalation. Skipping stop points is a CRITICAL VIOLATION.

Approval Status Vocabulary [MANDATORY]

These values standardize review and approval decisions. Review and approval agents MUST use this vocabulary consistently. Executor and quality-control operational statuses such as completed, escalation_needed, and stub_detected remain governed by their agent schemas and the Structured Response Specification.

Status	Scope	Meaning	Next Action
approved	Review/approval agents	All criteria met	Proceed to next phase
approved_with_conditions	Document agents	Criteria met with minor open items	Proceed — carry conditions as input to next phase
approved_with_notes	security-reviewer	Only hardening/policy findings	Proceed — include notes in completion report (no resolution required)
needs_revision	Review/approval agents	Significant issues found	Return to author agent for revision (max 2 iterations)
rejected	Document agents	Fundamental problems	Halt workflow, escalate to user
blocked	security-reviewer	Committed secrets or high-confidence exploitable risk	Halt workflow immediately, escalate to user (requires human intervention)
skipped	Review/approval agents whose schema permits skipping	Preconditions not met for this step	Report reason, proceed

Handling rules:

• approved_with_conditions: append the listed conditions to the document's open-items section, carry them into the next phase, and resolve them before implementation
• approved_with_notes: include the notes in the completion report for awareness

ENFORCEMENT: Using any status value outside this vocabulary for a review or approval decision is a VIOLATION.

WorkPlan Review State [MANDATORY]

Medium and Large work plans must contain a WorkPlan Review section. Small simplified plans are exempt because they have no Design Doc to trace against. The plan is reviewed only when that section records Status: approved and Conditions: none.

Handling rules:

• After WorkPlan review returns approved, invoke work-planner in update mode once to record the review section, without changing implementation content.
• Treat WorkPlan approved_with_conditions the same as needs_revision: return to work-planner in update mode with the conditions, then re-review. Conditions must not be carried into task decomposition or implementation readiness.
• A material work plan update resets WorkPlan Review to Status: pending.
• Standalone build recipes apply WorkPlan review only before task decomposition, not after task files already exist.

Scale Determination and Document Requirements

Scale	File Count	PRD	ADR	Design Doc	Work Plan
Small	1-2	Update*	Not needed	Not needed	Simplified
Medium	3-5	Update*	Conditional**	Required	Required
Large	6+	Required*	Conditional**	Required	Required

* Update if PRD exists for the relevant feature ** When there are architecture changes, new technology introduction, or data flow changes *** New creation/update existing/reverse PRD (when no existing PRD)

Structured Response Specification

Subagents respond in JSON format. The final response from each JSON-returning subagent must be the JSON payload itself, with no trailing prose. Agent TOML files define the full schemas; the orchestrator only relies on these routing keys:

Agent	Routing fields the orchestrator uses
requirement-analyzer	scale, confidence, affectedLayers, adrRequired, scopeDependencies, questions
codebase-analyzer	focusAreas, dataModel, qualityAssurance, dataTransformationPipelines, limitations
ui-analyzer	externalResources, componentStructure, propsPatterns, cssLayout, stateDisplay, focusAreas, candidateWriteSet, limitations
task-executor*	status, escalation_type (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), filesModified, requiresTestReview
quality-fixer*	status, reason, stubFindings, blockingIssues, missingPrerequisites
document-reviewer	verdict.decision, verdict.conditions
code-verifier	summary.status, discrepancies, reverseCoverage
design-sync	sync_status
integration-test-reviewer	status, requiredFixes
security-reviewer	status, findings, notes, requiredFixes
acceptance-test-generator	status, generatedFiles.integration, generatedFiles.fixtureE2e, generatedFiles.serviceE2e, e2eAbsenceReason.fixtureE2e, e2eAbsenceReason.serviceE2e

Implementation Readiness Marker Contract

Work plans use the header line Implementation Readiness: <status>.

Status	Meaning	Consumer Action
pending	Initial state from work-planner; readiness has not been checked	Run the Implementation Readiness Preflight Procedure before task execution
ready	Readiness scan completed and no applicable failures remain	Proceed with task execution
escalated	Readiness scan completed, but one or more failures remain	Read the work plan's Implementation Readiness Report, present remaining gaps, and continue only on explicit user approval
absent	Older work plan without the marker	Run the Implementation Readiness Preflight Procedure and persist the resulting marker

Implementation Readiness Preflight Procedure

Use this procedure after work-plan approval and before autonomous task execution when the flow needs to verify implementation readiness. The procedure supplies the evidence needed for user decisions; prompts for approval only after concrete failing criteria and proposed prep tasks are known.

1. Load the approved work plan exact path and extract Verification Strategies, Quality Assurance Mechanisms, Design-to-Plan Traceability, Reference Contract Values, ADR Bindings, UI Spec Component -> Task Mapping, Connection Map, test skeleton references, E2E absence reasons, phase structure, referenced Design Docs, ADRs, and UI Specs.
2. Evaluate these criteria with evidence:
   • R1 Verification Strategy and binding references resolve
   • R2 E2E prerequisites are addressed
   • R3 Phase 1 observability exists
   • R4 UI rendering surface exists when UI work is present
   • R5 Local service stack or browser harness procedure exists when applicable
3. If every applicable criterion passes, persist ## Implementation Readiness Report in the work plan and set Implementation Readiness: ready.
4. If any criterion fails, present the failing criteria, evidence, and the smallest proposed prep tasks that close the gaps. Continue with prep execution only after explicit user approval for those tasks.
5. If the user declines prep execution, persist Implementation Readiness: escalated with the remaining gaps and stop before autonomous task execution.
6. If the user approves prep execution, create the approved prep task files under docs/plans/tasks/ using the task template. Use {plan-name}-task-prep-{NN}.md for single-layer plans, {plan-name}-backend-task-prep-{NN}.md for backend prep, and {plan-name}-frontend-task-prep-{NN}.md for frontend prep.
7. Execute each exact prep task file through the standard executor -> quality-fixer -> commit cycle, then re-run the scan.
8. After re-scan, set Implementation Readiness: ready when all applicable criteria pass, otherwise Implementation Readiness: escalated, and persist remaining gaps in the Readiness Report.
9. Collapse completed prep task references into the Readiness Report and delete only the prep task files created for the current work plan.

Handling Requirement Changes

Handling Requirement Changes in requirement-analyzer

requirement-analyzer follows the "completely self-contained" principle and processes requirement changes as new input.

How to Integrate Requirements

Integrate initial requirements and later additions as complete sentences, preserving all contextual information communicated by the user. The updated input must remain self-contained without relying on prior conversation turns.

Update Mode for Document Generation Agents

Document generation agents (work-planner, technical-designer, prd-creator) can update existing documents in update mode.

• Initial creation: Create new document in create (default) mode
• On requirement change: Edit existing document and add history in update mode

Basic Flow for Work Planning

Always start with requirement-analyzer, then follow the minimum flow required by scale and affected layers.

Scale	Required flow
Large	requirement-analyzer [Stop] -> prd-creator -> document-reviewer [Stop] -> optional ui-spec-designer + document-reviewer [Stop] -> optional ADR + document-reviewer [Stop] -> codebase-analyzer -> technical-designer* -> code-verifier -> document-reviewer -> design-sync [Stop] -> acceptance-test-generator -> work-planner -> document-reviewer (doc_type: WorkPlan) [Stop] -> task-decomposer
Medium	requirement-analyzer [Stop] -> codebase-analyzer -> optional ui-spec-designer + document-reviewer [Stop] -> technical-designer* -> code-verifier -> document-reviewer -> design-sync [Stop] -> acceptance-test-generator -> work-planner -> document-reviewer (doc_type: WorkPlan) [Stop] -> task-decomposer
Small	requirement-analyzer [Stop] -> simplified plan [Stop: Batch approval] -> direct implementation

Flow rules:

• Frontend and fullstack flows add UI Spec before Design Doc creation
• Create ADR only when architecture, technology, or data-flow changes require it
• Pass requirement-analyzer output and original requirements to codebase-analyzer
• Pass codebase-analyzer output to the designer as Codebase Analysis
• Pass Design Doc path to code-verifier, then pass code_verification to document-reviewer
• Fullstack layer sequencing is defined in references/monorepo-flow.md
• Run WorkPlan review after every Medium/Large work plan creation or update and before batch approval. On needs_revision or WorkPlan approved_with_conditions, return to work-planner in update mode and re-review for max 2 revision iterations as defined by the needs_revision row in Approval Status Vocabulary. On rejected, halt and escalate to the user.

Autonomous Execution Mode

Pre-Execution Environment Check

Principle: Verify subagents can complete their responsibilities

Required environments:

• Commit capability (for per-task commit cycle)
• Quality check tools (quality-fixer will detect and escalate if missing)
• Test runner (task-executor will detect and escalate if missing)

If critical environment unavailable: Escalate with specific missing component before entering autonomous mode

Authority Grant

After environment check passes:

• Batch approval for entire implementation phase grants authority to agents
• task-executor: Implementation authority
• quality-fixer: Fix authority (automatic quality error fixes)

Definition of Autonomous Execution Mode

After "batch approval for entire implementation phase" with work-planner, autonomously execute the following processes without human approval:

Batch approval -> Start autonomous execution mode
  -> task-decomposer: Task decomposition
  -> Task execution loop:
      -> task-executor: Implementation
      -> Escalation judgment:
          - escalation_needed/blocked -> Escalate to user
          - requiresTestReview: true -> integration-test-reviewer
              - needs_revision -> back to task-executor
              - approved -> quality-fixer
          - No issues -> quality-fixer
      -> quality-fixer: Quality check and fixes using the executor `filesModified` set as the stub-detection scope
          - stub_detected -> task-executor/task-executor-frontend: complete implementation -> re-run quality-fixer
      -> Orchestrator: Execute git commit
      -> Check remaining tasks:
          - Yes -> next task
          - No -> code-verifier + security-reviewer: Post-implementation verification
              - all pass -> Completion report
              - any fail -> layer-appropriate task-executor: Verification fixes -> quality-fixer -> re-run failed verifiers
              - blocked -> Escalate to user

Conditions for Stopping Autonomous Execution

Stop autonomous execution and escalate to user in the following cases:

1. Escalation from subagent: When receiving status: "escalation_needed" or status: "blocked"
2. Requirement change detected: Any match in requirement change detection checklist
3. Work-planner update restriction violated: Requirement changes after task-decomposer starts require overall redesign
4. User explicitly stops: Direct stop instruction or interruption

Continue autonomous execution in the following situations:

• A workflow subagent is still pending
• wait_agent returns timed_out=true
• The orchestrator has partial context but is still waiting on a required subagent output

Use the task loop defined in the autonomous execution diagram above. The canonical per-task cycle is:

1. task-executor implementation
2. escalation or integration-test-reviewer decision
3. quality-fixer quality gate
4. git commit on approval

Post-Implementation Verification Pass/Fail Criteria

Verifier	Pass	Fail	Blocked
code-verifier	summary.status is consistent or mostly_consistent	summary.status is needs_review or inconsistent	—
security-reviewer	status is approved or approved_with_notes	status is needs_revision	status is blocked

Re-run only verifiers that failed on the previous verification cycle. Maximum retry count is 1 verification fix cycle. If any failed verifier still fails after the re-run, escalate to the user.

Main Orchestrator Roles

1. State Management: Track current phase, each subagent's state, and next action
2. Information Bridging: Data conversion and transmission between subagents
   • Convert each subagent's output to next subagent's input format
   • Always pass deliverables from previous process to next agent
   • Extract the routing fields listed above
   • Explicitly integrate initial and additional requirements when requirements change
3. Quality Assurance and Commit Execution: Execute git commit per the 4-step task cycle
4. Autonomous Execution Mode Management: Start/stop autonomous execution after approval, escalation decisions
5. ADR Status Management: Update ADR status after user decision (Accepted/Rejected)

Required Handoffs

From	To	Required pass-through
requirement-analyzer	codebase-analyzer	requirement analysis JSON, original requirements, PRD path when available
codebase-analyzer	technical-designer*	Codebase Analysis, including focusAreas, dataModel, qualityAssurance, dataTransformationPipelines, limitations
technical-designer*	code-verifier	Design Doc path
code-verifier	document-reviewer	code_verification JSON
acceptance-test-generator	work-planner	generatedFiles.integration, generatedFiles.fixtureE2e, generatedFiles.serviceE2e, e2eAbsenceReason: { fixtureE2e, serviceE2e }
Design Doc	work-planner	Verification Strategy summary, Output Comparison details, implementation-relevant technical requirements, protected no-change boundaries

Handoff rules:

• Verify generated integration, fixture-e2e, and service-integration-e2e file paths exist before passing them onward
• Escalate only when required outputs are missing without a valid absence reason
• Require work-planner to map every carried-forward technical requirement to a covering task or a justified gap

Important Constraints [MANDATORY]

• Quality check is REQUIRED: quality-fixer approval MUST be obtained before commit
• Structured response REQUIRED: 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, MUST check next step with work planning flow (large/medium/small scale)
• Consistency verification: If subagent determinations contradict, MUST prioritize the constraints and decision rules defined in this orchestration guide

ENFORCEMENT: Violating ANY constraint requires immediate correction

Required Dialogue Points with Humans [MANDATORY]

Basic Principles

• Stopping is REQUIRED: MUST wait for human response at stop points
• Confirmation then Agreement cycle: After document generation, proceed to next step after agreement or fix instructions in update mode
• Specific questions: Make decisions easy with options (A/B/C) or comparison tables

Action Checklist

When receiving a task, check the following:

• Confirmed whether the user provided a specific workflow recipe or explicit execution constraint
• Determined task type (new feature/fix/research, etc.)
• Selected the next subagent according to the decision flow and current phase
• Decided next action according to decision flow
• Monitored requirement changes and errors during autonomous execution mode

References

• references/monorepo-flow.md: Fullstack (monorepo) orchestration flow