Subagents Orchestration Guide Skill

Subagents Orchestration Guide

Role: The Orchestrator

The orchestrator coordinates subagents like a conductor—directing the musicians without playing the instruments.

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

Automatic Responses

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

First Action Rule

Every new task begins with requirement-analyzer.

Decision Flow When Receiving Tasks

graph TD
    Start[Receive New Task] --> RA[Analyze requirements with requirement-analyzer]
    RA --> Scale[Scale assessment]
    Scale --> Flow[Execute flow based on scale]

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

Requirement Change Detection During Flow

During flow execution, if detecting the following in user response, 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.)

If any one applies → Restart from requirement-analyzer with integrated requirements

Available Subagents

The following subagents are available:

Implementation Support Agents

quality-fixer: Self-contained processing for overall quality assurance and fixes until completion
task-decomposer: Appropriate task decomposition of work plans
task-executor: Individual task execution and structured response
integration-test-reviewer: Review integration/E2E tests for skeleton compliance and quality

Document Creation Agents

requirement-analyzer: Requirement analysis and work scale determination
prd-creator: Product Requirements Document creation
technical-designer: ADR/Design Doc creation
work-planner: Work plan creation from Design Doc and test skeletons
document-reviewer: Single document quality and rule compliance check
design-sync: Design Doc consistency verification across multiple documents
acceptance-test-generator: Generate integration and E2E test skeletons from Design Doc ACs

Orchestration Principles

Task Assignment with Responsibility Separation

Assign work based on each subagent's responsibilities:

What to delegate to task-executor:

Implementation work and test addition
Confirmation of added tests passing (existing tests are not covered)
Do not delegate quality assurance

What to delegate to quality-fixer:

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

Important: Subagents cannot directly call other subagents—all coordination flows through the orchestrator.

Explicit Stop Points

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 | | 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 work-planner creates plan | Batch approval for implementation phase |

After batch approval: Autonomous execution proceeds without stops until completion or escalation

Scale Determination and Document Requirements

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

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

How to Call Subagents

Execution Method

Call subagents using the Task tool:

subagent_type: Agent name
description: Concise task description (3-5 words)
prompt: Specific instructions

Call Example (requirement-analyzer)

subagent_type: "requirement-analyzer"
description: "Requirement analysis"
prompt: "Requirements: [user requirements] Please perform requirement analysis and scale determination"

Call Example (task-executor)

subagent_type: "task-executor"
description: "Task execution"
prompt: "Task file: docs/plans/tasks/[filename].md Please complete the implementation"

Structured Response Specification

Each subagent responds in JSON format:

task-executor: status, filesModified, testsAdded, readyForQualityCheck
quality-fixer: status, checksPerformed, fixesApplied, approved
document-reviewer: status, reviewsPerformed, issues, recommendations, approvalReady
design-sync: sync_status, total_conflicts, conflicts (severity, type, source_file, target_file)
integration-test-reviewer: status (approved/needs_revision/blocked), qualityIssues, requiredFixes, verdict
acceptance-test-generator: status, generatedFiles, budgetUsage

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

Important: To maximize accuracy, integrate requirements as complete sentences, including all contextual information communicated by the user.

Integration example:
  Initial: "I want to create user management functionality"
  Addition: "Permission management is also needed"
  Result: "I want to create user management functionality. Permission management is also needed.

          Initial requirement: I want to create user management functionality
          Additional requirement: Permission management is also needed"

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

Criteria for timing when to call each agent:

work-planner: Request updates only before execution
technical-designer: Request updates according to design changes → Execute document-reviewer for consistency check
prd-creator: Request updates according to requirement changes → Execute document-reviewer for consistency check
document-reviewer: Always execute before user approval after PRD/ADR/Design Doc creation/update

Basic Flow for Work Planning

When receiving new features or change requests, start with requirement-analyzer. According to scale determination:

Large Scale (6+ Files)

requirement-analyzer → Requirement analysis + Check existing PRD [Stop: Requirement confirmation/question handling]
prd-creator → PRD creation (update if existing, new creation with thorough investigation if not)
document-reviewer → PRD review [Stop: PRD Approval]
technical-designer → ADR creation (if architecture changes, new technology, or data flow changes)
document-reviewer → ADR review (if ADR created) [Stop: ADR Approval]
technical-designer → Design Doc creation
document-reviewer → Design Doc review
design-sync → Design Doc consistency verification [Stop: Design Doc Approval]
acceptance-test-generator → Integration and E2E test skeleton generation → Orchestrator: Verify generation, then pass information to work-planner (*1)
work-planner → Work plan creation (including integration and E2E test information) [Stop: Batch approval for entire implementation phase]
Start autonomous execution mode: task-decomposer → Execute all tasks → Completion report

Medium Scale (3-5 Files)

requirement-analyzer → Requirement analysis [Stop: Requirement confirmation/question handling]
technical-designer → Design Doc creation
document-reviewer → Design Doc review
design-sync → Design Doc consistency verification [Stop: Design Doc Approval]
acceptance-test-generator → Integration and E2E test skeleton generation → Orchestrator: Verify generation, then pass information to work-planner (*1)
work-planner → Work plan creation (including integration and E2E test information) [Stop: Batch approval for entire implementation phase]
Start autonomous execution mode: task-decomposer → Execute all tasks → Completion report

Small Scale (1-2 Files)

Create simplified plan [Stop: Batch approval for entire implementation phase]
Start autonomous execution mode: Direct implementation → Completion report

Existing Codebase Test Addition Flow

For existing backend implementations (e.g., after reverse-engineer), use the dedicated test addition workflow via /add-integration-tests command.

When to Use

Design Doc exists but tests are missing
After reverse-engineer completes PRD/Design Doc generation
Adding test coverage to legacy backend code

Flow

[Stop: Confirm Design Doc path]
acceptance-test-generator → Generate test skeletons
Create task file → docs/plans/tasks/integration-tests-YYYYMMDD.md
task-executor → Implement tests following task file
integration-test-reviewer → Review test quality
- If needs_revision → Return to step 4
quality-fixer → Final quality check
git commit → Commit test files
Completion report

Key Differences from Standard Flow

No implementation phase (code already exists)
Uses task file for test implementation (same pattern as review.md)
Mandatory integration-test-reviewer step
Backend only (acceptance-test-generator limitation)

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 If detectable by subagent: Proceed (subagent will escalate with detailed context)

Authority Delegation

After environment check passes:

Batch approval for entire implementation phase delegates authority to subagents
task-executor: Implementation authority (can use Edit/Write)
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:

graph TD
    START[Batch approval for entire implementation phase] --> AUTO[Start autonomous execution mode]
    AUTO --> TD[task-decomposer: Task decomposition]
    TD --> LOOP[Task execution loop]
    LOOP --> TE[task-executor: Implementation]
    TE --> ESCJUDGE{Escalation judgment}
    ESCJUDGE -->|escalation_needed/blocked| USERESC[Escalate to user]
    ESCJUDGE -->|testsAdded has int/e2e| ITR[integration-test-reviewer]
    ESCJUDGE -->|No issues| QF
    ITR -->|needs_revision| TE
    ITR -->|approved| QF
    QF[quality-fixer: Quality check and fixes] --> COMMIT[Orchestrator: Execute git commit]
    COMMIT --> CHECK{Any remaining tasks?}
    CHECK -->|Yes| LOOP
    CHECK -->|No| REPORT[Completion report]

    LOOP --> INTERRUPT{User input?}
    INTERRUPT -->|None| TE
    INTERRUPT -->|Yes| REQCHECK{Requirement change check}
    REQCHECK -->|No change| TE
    REQCHECK -->|Change| STOP[Stop autonomous execution]
    STOP --> RA[Re-analyze with requirement-analyzer]

Conditions for Stopping Autonomous Execution

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

Escalation from subagent
- When receiving response with status: "escalation_needed"
- When receiving response with status: "blocked"
When requirement change detected
- Any match in requirement change detection checklist
- Stop autonomous execution and re-analyze with integrated requirements in requirement-analyzer
When work-planner update restriction is violated
- Requirement changes after task-decomposer starts require overall redesign
- Restart entire flow from requirement-analyzer
When user explicitly stops
- Direct stop instruction or interruption

Task Management: 4-Step Cycle

Per-task cycle:

1. task-executor → Implementation
2. Escalation judgment/Follow-up → Check task-executor status
3. quality-fixer → Quality check and fixes
4. git commit → Execute with Bash (on approved: true)

Step 2 Execution Details:

status: escalation_needed or status: blocked → Escalate to user
testsAdded contains *.int.test.ts or *.e2e.test.ts → Execute integration-test-reviewer
- If verdict is needs_revision → Return to task-executor with requiredFixes
- If verdict is approved → Proceed to quality-fixer

Commit trigger: quality-fixer returns approved: true

2-Stage TodoWrite Management

Stage 1: Phase Management (Orchestrator responsibility)

Register overall phases as TodoWrite items
Update status as each phase completes

Stage 2: Task Expansion (Subagent responsibility)

Each subagent registers detailed steps in TodoWrite at execution start
Update status on each step completion

Main Orchestrator Roles

State Management: Grasp current phase, each subagent's state, and next action
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 necessary information from structured responses
- Compose commit messages from changeSummary → Execute git commit with Bash
- Explicitly integrate initial and additional requirements when requirements change
*1 acceptance-test-generator → work-planner

Purpose: Prepare information for work-planner to incorporate into work plan

Orchestrator verification items:
- Verify integration test file path retrieval and existence
- Verify E2E test file path retrieval and existence
Pass to work-planner:
- Integration test file: [path] (create and execute simultaneously with each phase implementation)
- E2E test file: [path] (execute only in final phase)
On error: Escalate to user if files are not generated
Quality Assurance and Commit Execution: After confirming approved=true, immediately execute git commit
Autonomous Execution Mode Management: Start/stop autonomous execution after approval, escalation decisions
ADR Status Management: Update ADR status after user decision (Accepted/Rejected)

Important Constraints

Quality check is mandatory: quality-fixer approval needed before commit
Structured response mandatory: Information transmission between subagents in 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 guidelines

Required Dialogue Points with Humans

Basic Principles

Stopping is mandatory: Always wait for human response at the following timings
Confirmation → 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 if there is an orchestrator instruction
[ ] Determined task type (new feature/fix/research, etc.)
[ ] Considered appropriate subagent utilization
[ ] Decided next action according to decision flow
[ ] Monitored requirement changes and errors during autonomous execution mode

Agent Skills: Subagents Orchestration Guide

Skill Files