Guides subagent coordination through implementation workflows. Use when orchestrating multiple agents, managing workflow phases, or determining autonomous execution mode. Defines scale determination, document requirements, and stop points.
npxskills add shinpr/claude-code-workflows--skill subagents-orchestration-guideLoading…
All investigation, analysis, and implementation work flows through specialized subagents.
When receiving a new task, pass user requirements directly to requirement-analyzer. Determine the workflow based on its scale assessment result.
During flow execution, monitor user responses for scope-expanding signals:
When any signal is detected → Restart from requirement-analyzer with integrated requirements
Implementation support:
Document creation: 6. requirement-analyzer: Requirement analysis and work scale determination 7. codebase-analyzer: Analyze existing codebase to produce focused guidance for technical design (data, contracts, dependencies, quality assurance mechanisms) 8. 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 to inherit MCP access 9. : Product Requirements Document creation 10. : UI Specification creation from PRD and optional prototype code (frontend/fullstack features) 11. : ADR/Design Doc creation 12. : Work plan creation from Design Doc and test skeletons 13. : Single document quality and rule compliance check 14. : Verify document-code consistency. Pre-implementation: Design Doc claims against existing codebase. Post-implementation: implementation against Design Doc 15. : Design Doc consistency verification across multiple documents 16. : Generate integration and E2E test skeletons from Design Doc ACs
disallowedToolsThe orchestrator passes what to accomplish and where to work. Each specialist determines how to execute autonomously.
Pass to specialists (what/where/constraints):
Let specialists determine (how):
| 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:
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.
Assign work based on each subagent's responsibilities:
What to delegate to task-executor:
What to delegate to quality-fixer:
Important: Subagents cannot directly call other subagents—all coordination flows through the orchestrator.
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 | 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)
Each subagent invocation is a fresh Agent tool call, isolating each phase's context; a SendMessage resume reuses the prior agent's context and breaks that isolation. Each call uses:
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.
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.When invoked alongside codebase-analyzer for frontend or fullstack-frontend work, run both agents in parallel and pass both JSON outputs to consumers (ui-spec-designer for the design phase; technical-designer-frontend for the Design Doc phase).
Subagents respond in JSON format. Key fields for orchestrator decisions:
ui: prefix when merging with codebase analysis facts), candidateWriteSet[] (with confidence labels), limitationscode_paths scoped to changed files)task_file (path to current task file — always pass this in orchestrated flows). Status: approved/stub_detected/blocked. stub_detected → route back to task-executor with incompleteImplementations[] details for completion, then re-run quality-fixer. blocked → discriminate by reason field: "Cannot determine due to unclear specification" → read blockingIssues[] for specification details; "Execution prerequisites not met" → read missingPrerequisites[] with resolutionSteps — present these to the user as actionable next stepsverdict.decision (approved/approved_with_conditions/needs_revision/rejected)requirement-analyzer follows the "completely self-contained" principle and processes requirement changes as new input.
Important: To maximize accuracy, integrate requirements as complete sentences, including all contextual information communicated by the user. Result format: raw concatenation of all requirements, followed by a labeled summary (Initial requirement: … / Additional requirement: …).
Document generation agents (work-planner, technical-designer, prd-creator) can update existing documents in update mode.
Criteria for timing when to call each agent:
Always start with requirement-analyzer, then select the minimum planning flow required by scale and affected layers.
| Scale | Planning flow (ends at task-decomposer for Medium/Large; ends at work-planner for Small) |
|---|---|
| Large | requirement-analyzer → PRD → PRD review → external resource hearing → optional ADR → codebase-analyzer (+ ui-analyzer in parallel for frontend/fullstack) → optional UI Spec → Design Doc → code-verifier → document-reviewer → design-sync → acceptance-test-generator → work-planner → work plan review (document-reviewer, doc_type WorkPlan) → task-decomposer |
| Medium | requirement-analyzer → external resource hearing → codebase-analyzer (+ ui-analyzer in parallel for frontend/fullstack) → optional UI Spec → optional ADR → Design Doc → code-verifier → document-reviewer → design-sync → acceptance-test-generator → work-planner → work plan review (document-reviewer, doc_type WorkPlan) → task-decomposer |
| Small | requirement-analyzer → work-planner |
External resource hearing runs in the orchestrator (it requires AskUserQuestion). ui-analyzer joins codebase-analyzer in parallel only when the work has a frontend surface; for backend-only work the planning flow uses codebase-analyzer alone.
After the planning flow completes and the user grants batch approval, implementation proceeds. Verifying the plan is implementable end-to-end (verification lanes, fixtures, E2E environment) is an optional preflight the user runs at their discretion via the recipe-prepare-implementation recipe; this guide does not invoke any orchestrator above the agent layer.
Then execute the task execution cycle: task-executor → quality-fixer → commit for each task. See "Autonomous Execution Mode" below for full per-task details. At Small scale this cycle still applies — implementation runs through task-executor, not orchestrator-direct edits.
Each agent name in the chain is invoked via the Agent tool (per "Orchestrator's Permitted Tools" above).
Rules:
references/monorepo-flow.mddesign-sync is required whenever multiple Design Docs existtask-decomposer begins only after work plan review (document-reviewer, doc_type WorkPlan; Medium/Large) and batch approvalverdict.decision needs_revision, route back to work-planner (update) and re-review until approved/approved_with_conditions; rejected escalates to the user. The work plan is a derivation of the Design Doc, so plan-fidelity findings need no user adjudicationPrinciple: Verify subagents can complete their responsibilities
Required environments:
If critical environment unavailable: Escalate with specific missing component before entering autonomous mode If detectable by subagent: Proceed (subagent will escalate with detailed context)
After environment check passes:
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 -->|requiresTestReview: true| ITR[integration-test-reviewer]
ESCJUDGE -->|No issues| QF
ITR -->|needs_revision| TE
ITR -->|approved| QF
QF[quality-fixer: Quality check and fixes] --> QFJUDGE{quality-fixer result}
QFJUDGE -->|stub_detected| TE
QFJUDGE -->|approved| COMMIT[Orchestrator: Execute git commit]
QFJUDGE -->|blocked| USERESC
COMMIT --> CHECK{Any remaining tasks?}
CHECK -->|Yes| LOOP
CHECK -->|No| VERIFY[Post-implementation verification]
VERIFY --> CV[code-verifier: DD consistency check]
VERIFY --> SEC[security-reviewer: Security review]
CV --> VRESULT{Verification results}
SEC --> VRESULT
VRESULT -->|All passed| REPORT[Completion report]
VRESULT -->|Any failed| VFIX[task-executor: Verification fixes]
VFIX --> QF2[quality-fixer: Quality check]
QF2 --> REVERIFY[Re-run failed verifiers only]
REVERIFY --> VRESULT
VRESULT -->|blocked| USERESC
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]
| 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.
Stop 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
Per-task cycle:
status: escalation_needed or blocked → Escalate to userrequiresTestReview is true → Execute integration-test-reviewer
needs_revision → Return to step 1 with requiredFixesapproved → Proceed to step 3task_file
stub_detected → Return to step 1 with incompleteImplementations[] detailsblocked → Escalate to userapproved → Proceed to step 4approved)Register overall phases using TaskCreate. Update each phase with TaskUpdate as it completes.
State Management: Grasp current phase, each subagent's state, and next action
Information Bridging: Data conversion and transmission between subagents
requirement_analysis, prd_path (if exists), original user requirementsfocusAreas → canonical disposition-target list for the Fact Disposition TabledataModel, dataTransformationPipelines, qualityAssurance → Existing Codebase Analysis / Verification Strategy / Quality Assurance sectionsdoc_type: design-doc)code_paths; code-verifier discovers scope from the documentcode_verification JSON and the same codebase_analysis JSON previously given to the designerfocusAreasreferences/monorepo-flow.mdprior_layer_verificationdiscrepancies[] as known issues to address or escalate. Do not infer verified claims that are not explicitly present in the verifier output.Pass to work-planner: Design Doc path. Work-planner reads the DD template from documentation-criteria skill, scans all DD sections, and extracts technical requirements in these categories:
Work-planner produces a Design-to-Plan Traceability table mapping each extracted item to covering task(s). Items without a covering task must be marked as gap with justification. Unjustified gaps are errors. Justified gaps require user confirmation before plan approval.
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 (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)
Recap (defined above): quality-fixer approval before commit; inter-agent communication is JSON; document-reviewer + user approval before proceeding; check next step against work planning flow after approval; resolve conflicts via Decision precedence.
references/monorepo-flow.md: Fullstack (monorepo) orchestration flow
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).