subagents-orchestration-guide

Subagents Orchestration Guide

Role: The Orchestrator

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

First Action Rule

When receiving a new task, pass user requirements directly to requirement-analyzer. Determine the workflow based on its scale assessment result.

Requirement Change Detection During Flow

During flow execution, monitor user responses for scope-expanding signals:

• 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.)

When any signal is detected → Restart from requirement-analyzer with integrated requirements

Available Subagents

Implementation support:

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-principles after all tasks complete

Document creation:

1. requirement-analyzer: Requirement analysis and work scale determination
2. codebase-analyzer: Analyze existing codebase to produce focused guidance for technical design (data, contracts, dependencies, quality assurance mechanisms)
3. ui-analyzer: Read the project's external-resources file, fetch external UI sources (design origin, design system, guidelines) via MCP/URL/file, and analyze existing UI code. Frontend/fullstack features; runs in parallel with codebase-analyzer. Uses disallowedTools to inherit MCP access
4. prd-creator: Product Requirements Document creation
5. ui-spec-designer: UI Specification creation from PRD and optional prototype code (frontend/fullstack features)
6. technical-designer: ADR/Design Doc creation
7. work-planner: Work plan creation from Design Doc and test skeletons
8. document-reviewer: Single document quality and rule compliance check
9. code-verifier: Verify document-code consistency. Pre-implementation: Design Doc claims against existing codebase. Post-implementation: implementation against Design Doc
10. design-sync: Design Doc consistency verification across multiple documents
11. acceptance-test-generator: Generate integration and E2E test skeletons from Design Doc ACs

Orchestration Principles

Delegation Boundary: What vs How

The orchestrator passes what to accomplish and where to work. Each specialist determines how to execute autonomously.

Pass to specialists (what/where/constraints):

• Target directory, package, or file paths
• Task file path or scope description
• Acceptance criteria and hard constraints from the user or design artifacts

Let specialists determine (how):

• Specific commands to run (specialists discover these from project configuration and repo conventions)
• Execution order and tool flags
• Which files to inspect or modify within the given scope

| | Bad (orchestrator prescribes how) | Good (orchestrator passes 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:

1. User instructions (explicit requests or constraints)
2. Task files and design artifacts (Design Doc, PRD, work plan)
3. Objective repo state (git status, file system, project configuration)
4. Specialist judgment

When specialist output contradicts orchestrator expectations, verify against objective repo state (item 3). If repo state confirms the specialist, follow the specialist. Override specialist output only when it conflicts with items 1 or 2.

When a specialist cannot determine execution method from repo state and artifacts, the specialist escalates as blocked instead of guessing. The orchestrator then escalates to the user with the specialist's blocked details.

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)
• Delegate quality assurance exclusively to quality-fixer (or quality-fixer-frontend for frontend tasks)

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. Use AskUserQuestion to present confirmations and questions.

| 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 work plan review (document-reviewer, doc_type WorkPlan; Medium/Large) or work-planner (Small) completes | 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

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 paths

Orchestrator's Permitted Tools

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

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.

Two additional rules:

• Subagents see only the Agent prompt and files they read. Include required paths, prior JSON, parameters, and scope constraints explicitly.
• Replace every [placeholder] in examples below with concrete values before invoking the Agent