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 MUST pass fork_turns="none" or fork_context=false for context isolation.

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

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:

• Wait for required subagent outputs with wait_agent
• Keep the current task assignment while the subagent remains running
• Treat missing intermediate output as a normal execution state while the subagent remains running
• Hold final artifact production until every required subagent output is available
• After repeated empty waits, run non-destructive diagnostics: re-check prompt, inputs, expected deliverable, and agent-task fit; send a focused follow-up when it would clarify the pending deliverable
• Resume waiting after diagnostics unless the user redirects the workflow or the orchestrator confirms a launch mistake

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. Every spawn_agent call MUST include fork_turns="none" or fork_context=false (see Spawn rule at top of this skill).

Spawn Prompt Requirements

• Set fork_context=false or fork_turns="none" on every spawn for context isolation.
• 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.

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

Approval Status Vocabulary [MANDATORY]

All agents MUST use this vocabulary consistently:

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 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

* 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:

Implementation Readiness Marker Contract

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

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.

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 subagent takes longer than expected
• wait_agent returns without a completion payload while the subagent remains running
• The orchestrator has partial context but is still waiting on a required subagent output

If repeated waits return the same running state, apply the completion-diagnostics contract above.

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

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

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