shinpr/ai-coding-project-boilerplate-subagents-orchestration-guide
Coordinates subagents through scale-based planning, approval, implementation, verification, and escalation flows. Use when routing work to subagents, executing an approved work plan, or resuming autonomous execution.
npx skills add https://github.com/shinpr/ai-coding-project-boilerplate --skill subagents-orchestration-guideThis document provides practical behavioral guidelines for me (Claude) to efficiently process tasks by utilizing subagents.
Role Definition: I am an orchestrator, not an executor.
When receiving a new task, pass user requirements directly to requirement-analyzer. Determine the workflow based on its scale assessment result.
requirement-analyzer returns a convergence object. Run the requirement-convergence hearing protocol at the requirements stop point on that output, recording each step's evidence, then re-invoke requirement-analyzer with the answers so the record is re-judged. The hearing runs in the orchestrator because it requires AskUserQuestion, and runs after the analysis because the orchestrator investigates nothing itself.
During flow execution, if detecting the following in user response, stop flow and go to requirement-analyzer:
When any condition applies, record the integrated requirements and restart from requirement-analyzer.
10. technical-designer: ADR/Design Doc creation (latest technology research, Property annotation assignment)
11. work-planner: Work plan creation from Design Doc and test skeletons
12. document-reviewer: Single document quality, completeness, and rule compliance check
13. code-verifier: Verify document-code consistency. Pre-implementation: Design Doc claims against existing codebase. Post-implementation: implementation against Design Doc
14. design-sync: Design Doc consistency verification (detects explicit conflicts only)
15. acceptance-test-generator: Generate separate integration and E2E test skeletons from Design Doc ACs and optional UI Spec
16. ui-analyzer: Gather UI facts (external sources + existing UI code) for frontend design preparation — read-only
I pass what to accomplish and where to work. Each specialist determines how to execute autonomously.
I pass to specialists (what/where/constraints):
I let specialists determine (how):
| | Bad (I prescribe how) | Good (I pass 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 two specialists conflict, or when a specialist conflicts with my expectation, I apply the precedence order above. I verify against objective repo state (item 3). I follow specialist output when it aligns with items 1 and 2. When specialist output conflicts with user instructions or design artifacts, I follow user instructions first, then design artifacts.
When a specialist cannot determine execution method from repo state and artifacts, the specialist escalates as blocked. I then escalate to the user with the specialist's blocked details.
I understand each subagent's responsibilities and assign work appropriately:
task-executor Responsibilities (DELEGATE these):
quality-fixer Responsibilities (DELEGATE these):
Basic Cycle: I manage the 4-step cycle of task-executor -> escalation judgment/follow-up -> quality-fixer -> commit.
I repeat this cycle for each task to ensure quality.
Layer-Aware Routing: For cross-layer features, select executor and quality-fixer by task filename pattern (see Cross-Layer Orchestration).
Important: Subagents cannot directly call other subagents. When coordinating multiple subagents, the main AI (Claude) operates as the orchestrator.
The file-count ranges below set the floor. documentation-criteria skill's Structural Escalation raises the confirmed scale — and therefore the required-document row — when any ADR Creation Condition applies, and it only raises a level.
| Scale | Baseline File Count | PRD | ADR | Design Doc | Work Plan |
|-------|---------------------|-----|-----|------------|-----------|
| Small | 1-2 | Update[^1] | Not needed | Not needed | Single task file in task-template format under docs/plans/tasks/ (no separate plan document) |
| Medium | 3-5 | Update[^1] | Conditional[^2] | Required | Required |
| Large | 6+ | Required[^3] | Conditional[^2] | Required | Required |
[^1]: Update existing PRD if one exists for the relevant feature
[^2]: Required when: architecture changes, new technology introduction, OR data flow changes
[^3]: Create new PRD, update existing PRD, or create reverse PRD (when no existing PRD)
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 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.
Subagents respond in JSON format. Key fields for orchestrator decisions:
| Agent | Key Fields | Decision Logic |
|-------|-----------|----------------|
| requirement-analyzer | scale, confidence, adrRequired, crossLayerScope, scopeDependencies, questions, convergence (four fields, each with a readiness label; a field below ready also returns as a convergence question) | Select flow by scale — the value already includes Structural Escalation; check adrRequired for ADR step; run the requirement-convergence hearing on convergence before proceeding |
| codebase-analyzer | analysisScope.categoriesDetected, dataModel.detected, qualityAssurance (mechanisms[], domainConstraints[]), focusAreas[], existingElements count, limitations | Pass focusAreas to technical-designer as context |
| ui-analyzer | externalResources (status, per-axis fetch_status), componentStructure[], propsPatterns[], cssLayout[], stateDisplay[], focusAreas[], candidateWriteSet[], limitations | Pass the ui-analyzer JSON to ui-spec-designer and technical-designer-frontend; each consumes the fields named in its own input declaration |
| code-verifier | summary.status (consistent/mostly_consistent/needs_review/inconsistent/blocked), summary.blockingReason, summary.consistencyScore, discrepancies[], reverseCoverage (dataOperationsInCode, testBoundariesSectionPresent). Read the verdict from summary.status — discrepancies[].status is a per-finding field (drift/gap/conflict) and is not the verdict. Pre-implementation: verifies Design Doc claims against existing codebase. Post-implementation: verifies implementation consistency against Design Doc (pass code_paths scoped to changed files) | Flag discrepancies for document-reviewer |
| task-executor | Input: task_file (required in orchestrated flows); optional Fix Mode signals requiredFixes or incompleteImplementations — when either is non-empty, skip task_already_completed and extend allowed list with each item's file_path / location (parse location as file[:line]); each incompleteImplementations[] entry may carry type: "missing_logic" \| "hollow_test" and the executor branches its fix action by type. Output: status (escalation_needed/completed), filesModified[], testsAdded, requiresTestReview, runnableCheck{level, executed, command, result, substance, substanceIssue, reason}, escalation_type ∈ {task_file_not_found, task_already_completed, target_files_missing, 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, unresolved_input}. | On escalation_needed: handle by escalation_type. On unresolved_input: present unresolvedItems[] to the user — a requirement-decision item needs the named decision before the task can re-run; an implementation-detail item names the constraint no in-scope option satisfies |
| quality-fixer | Input: task_file (path to current task file — always pass this in orchestrated flows), filesModified (extract from the upstream implementation step's response — passes the task's write set as the primary scope for stub-detection; falls back to git diff HEAD when omitted), runnableCheck (extract from the upstream implementation step's response — passes the test execution evidence including substance and substanceIssue so the substance check has the runtime signal; omit when the upstream did not run tests), qualityCommand (pass the project's authoritative quality command when the recipe or technical-spec names one, so every task in the run is verified by the same command; omit to let the fixer discover commands from the project configuration). Status: approved/stub_detected/blocked. stub_detected → incompleteImplementations[] items carry type: "missing_logic" \| "hollow_test"; route back to the implementation step (which branches its fix action on type), then re-run quality-fixer. blocked → see quality-fixer blocked handling below | On stub_detected: re-invoke the implementation step. On blocked: see handling below |
| document-reviewer | Input: doc_type, target, review_context (creation for a newly authored document, update for a revision of an approved one, as-is for a reverse-engineered document — declares why the review was requested so legitimately absent paired inputs are not read as defects), plus the doc_type-specific inputs. Output: verdict.decision (approved/approved_with_conditions/needs_revision/rejected), recommendations (includes an entry naming the checks that did not run when paired inputs were absent, and the absence of code verification when code_verification came back blocked) | Proceed on approved/approved_with_conditions; request fixes on needs_revision; escalate on rejected. Read the recommendations for skipped checks before treating an approval as full-scope |
| design-sync | sync_status (NO_CONFLICTS/CONFLICTS_FOUND) | On CONFLICTS_FOUND: present conflicts to user before proceeding |
| integration-test-reviewer | Input: testFile (one or more paths — pass every test file the change touched, from the implementation step's testsAdded), diffBase (optional — the revision the tests are compared against, so review scope is the change rather than the whole file), designDocPath (optional), taskFiles (optional). Output: verdict.decision (approved/needs_revision/blocked), verdict.reason, testFiles[], fileResults[] (one entry per reviewed file, each carrying its own reviewBasis of skeleton/proof_obligations/prompt_claims/none plus that file's compliance counts and quality issues), proofObligationCoverage[] (task-scoped, spanning all reviewed files — one task's obligations may be split across files, so this is where coverage is resolved), requiredFixes[] (each location begins with the file path). blocked has two causes: a reviewed file whose reviewBasis is none, or a contradiction between the basis and the Design Doc. Branch on verdict.decision — top-level status is the verification outcome axis (passed/failed/needs_improvement) and is not the routing decision | On needs_revision: re-invoke the routed executor in Fix Mode with the same task_file and requiredFixes[]. On blocked: escalate with verdict.reason |
| security-reviewer | Input: designDoc, implementationFiles. Output: status (approved/approved_with_notes/needs_revision/blocked), findings, notes, irreversibleHazards[] (non-empty when an irreversible-operation hazard is blocked — each entry names the required decision, which forces status blocked), requiredFixes | On needs_revision: create a consolidated fix task file with the affected file paths from requiredFixes[].location populated into Target Files, then invoke the routed executor in Fix Mode with that task_file and the requiredFixes[] array, then quality-fixer, then re-invoke security-reviewer to verify resolution. On blocked: escalate to user with the blocking findings — fix is not within the agent layer's authority |
| acceptance-test-generator | status, generatedFiles.{integration,fixtureE2e,serviceE2e} (path\|null per lane), budgetUsage per lane, e2eAbsenceReason per E2E lane (null when emitted; reason enum is owned by acceptance-test-generator and integration-e2e-testing skill) | Verify each non-null file path exists, pass per-lane paths and absence reasons to work-planner |
When quality-fixer returns status: "blocked", discriminate by reason:
"Cannot determine due to unclear specification" → read blockingIssues[] for specification details"Execution prerequisites not met" → read missingPrerequisites[] with resolutionSteps and present to user as actionable next steps"Quality failure outside current task scope" → present outOfScopeFailures[] and needsUserDecision to the user and stop. Re-invoke quality-fixer only when the user expands the task scope to include the failureWhen receiving new features or change requests, I first request requirement analysis from requirement-analyzer.
According to scale determination:
10. code-verifier → Verify Design Doc against existing code (doc_type: design-doc)
11. document-reviewer → Design Doc review (pass code-verifier results as code_verification; cross-layer: per Design Doc)
12. design-sync → Consistency verification [Stop: Design Doc Approval]
13. acceptance-test-generator → Test skeleton generation, pass to work-planner (*1)
14. work-planner → Work plan creation
15. document-reviewer → Work plan review (doc_type: WorkPlan; pass the Design Doc path so AC/contract/state coverage is traceable). On needs_revision: re-invoke work-planner (update) and re-review until approved/approved_with_conditions — the plan is a derivation of the Design Doc, so plan-fidelity findings need no user adjudication. On rejected: escalate to user. [Stop: Batch approval]
16. task-decomposer → Autonomous execution → Completion report
10. work-planner → Work plan creation
11. document-reviewer → Work plan review (doc_type: WorkPlan; pass the Design Doc path so AC/contract/state coverage is traceable). On needs_revision: re-invoke work-planner (update) and re-review until approved/approved_with_conditions — the plan is a derivation of the Design Doc, so plan-fidelity findings need no user adjudication. On rejected: escalate to user. [Stop: Batch approval]
12. task-decomposer → Autonomous execution → Completion report
nonGoals is user-authored and no agent can supply it. When Structural Escalation raises the scale, switch to the Medium flow from this pointdocs/plans/tasks/ instead of a separate work plan + decomposition; that path is what task-executor receives as task_file. [Stop: Batch approval]Note: At Small scale the implementation step still runs through task-executor with the standard 4-step cycle (task-executor → escalation judgment → quality-fixer → commit). Direct orchestrator edits are not used.
For Medium / Large scale, after Batch approval implementation proceeds directly. Verifying the plan is implementable end-to-end (verification-strategy references, fixtures, UI rendering surface, E2E/local lane environment) is an optional preflight the user runs at their discretion via the prepare-implementation recipe, which exits no-op when readiness criteria already pass. This guide does not invoke any orchestrator above the agent layer.
When requirement-analyzer determines the feature spans multiple layers (backend + frontend) via crossLayerScope, the following extensions apply. Step numbers below follow the large-scale flow. For medium-scale cross-layer flows, replace the single codebase-analysis and Design Doc segment with the same backend-first, frontend-second sequence below; use the named phase transitions rather than reusing large-flow step numbers.
Replace the standard Design Doc creation step with per-layer creation:
| Step | Agent | Purpose |
|------|-------|---------|
| 8 | codebase-analyzer ×2 | Codebase analysis per layer (pass req-analyzer output, filtered to layer) |
| 9 | technical-designer | Backend Design Doc (with backend codebase-analyzer context) |
| 10 | code-verifier | Verify Backend Design Doc against existing code (its result JSON becomes prior_layer_verification for step 12) |
| 11 | document-reviewer | Review Backend Design Doc (pass step-10 result as code_verification and backend codebase-analyzer JSON as codebase_analysis). [Stop on critical issues] — structural defects here block step 12. |
| 12 | technical-designer-frontend | Frontend Design Doc (with frontend codebase-analyzer context + reviewed Backend Design Doc + prior_layer_verification from step 10 + UI Spec) |
| 13 | code-verifier | Verify Frontend Design Doc against existing code |
| 14 | document-reviewer | Review Frontend Design Doc (pass step-13 result as code_verification and frontend codebase-analyzer JSON as codebase_analysis). [Stop on critical issues] — structural defects here block step 15. |
| 15 | design-sync | Cross-layer consistency verification [Stop] |
The codebase-analyzer ×2 invocations can run in parallel. The backend path (steps 9-11) runs sequentially before step 12 so that the frontend designer reads a backend Design Doc whose structural defects (AC gaps, Fact Disposition Table issues, Verification Strategy defects) have already been surfaced by document-reviewer, and whose code/doc discrepancies have already been enumerated by code-verifier. The frontend designer can then identify which backend contracts have known issues via prior_layer_verification.discrepancies[] and the step-11 review feedback, and design around those unstable surfaces (route integration points to stable contracts, or record the dependency in ## Cross-Layer Assumptions).
Layer Context in Design Doc Creation:
prior_layer_verification.discrepancies[] and the review findings; limit verified-claim inference to what the verifier output states explicitly. For contracts you must depend on that remain unverified, list them in the ## Cross-Layer Assumptions section with justification and verification target. Reference UI Spec at [path] for component structure. Focus on: component hierarchy, state management, UI interactions, data fetching."design-sync: Use frontend Design Doc as source. design-sync auto-discovers other Design Docs in docs/design/ for comparison.
Pass all Design Docs to work-planner with vertical slicing instruction:
During autonomous execution, route agents by task filename pattern. This table also defines the two executor lanes a work plan task entry selects between:
| Executor lane | Filename Pattern | Executor | Quality Fixer |
|---|---|---|---|
| backend | *-task-* or *-backend-task-* | task-executor | quality-fixer |
| frontend | *-frontend-task-* | task-executor-frontend | quality-fixer-frontend |
A work plan task entry records exactly one lane; task materialization copies that value and selects the filename from this table rather than inferring the layer from target paths.
After starting autonomous execution mode:
status: escalation_needed or status: blocked -> Escalate to userrequiresTestReview is true -> Execute integration-test-reviewerverdict.decision is needs_revision -> Re-invoke the routed executor (task-executor or task-executor-frontend per Layer-Aware Agent Routing) in Fix Mode with the same task_file and the requiredFixes[] arrayverdict.decision is blocked -> Escalate to user with the reviewer's stated blocking reason and the review basis it could not establish; re-invoke the reviewer only after the user supplies that basisverdict.decision is approved -> Proceed to quality-fixerStop autonomous execution and escalate to user in the following cases:
status: "escalation_needed"status: "blocked"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.After the selected flow completes, return:
{
"status": "completed | blocked", "scale": "small | medium | large", "completedTasks": [{"taskFile": "path", "status": "completed", "commit": "sha-or-null"}], "filesModified": ["path"],
"verification": [{"check": "name", "result": "passed | failed | not_run", "evidence": "command or verifier result"}], "verifiers": [{"name": "agent", "status": "status value"}], "unresolvedItems": [{"item": "decision or evidence", "requiredInput": "input", "escalation": "condition"}]
}
Set status to completed only when every required task, quality gate, verifier, and commit step in the selected flow has completed. Set it to blocked when an unresolved item prevents the next transition.
Pass: the convergence object from the last requirement-analyzer invocation (or, in a flow with no requirement-analyzer, the orchestrator's own judged record) to whichever agent carries it forward. Pass it unchanged; each field's readiness label travels with it.
outcome to Success Criteria, and nonGoals plus speculative requirements to Future / Out of Scope with origin userRequirement Convergence when no PRD exists, and always records the fields left weak-but-explicit therenonGoals and speculative requirements as capabilities the UI Spec leaves outnonGoals and speculative requirements as excluded from every task entry. At Small scale no PRD or Design Doc exists, so the weak-but-explicit fields stay in the orchestrator's own context per the storage protocol rather than becoming blocking items in the task filePass to codebase-analyzer: requirement-analyzer JSON output (including convergence), PRD path (if exists), original user requirements
Pass to technical-designer: codebase-analyzer JSON output as additional context in the Design Doc creation prompt. Required downstream uses:
focusAreas → canonical disposition-target list for the Fact Disposition Table (one row per focusArea, carrying through fact_id and evidence verbatim)dataModel, dataTransformationPipelines, qualityAssurance → Existing Codebase Analysis, Verification Strategy, and Quality Assurance Mechanisms sectionsPass to code-verifier: Design Doc path (doc_type: design-doc). Omit code_paths; the verifier independently discovers code scope from the document.
Pass to document-reviewer: code-verifier JSON output as code_verification, the same codebase-analyzer JSON previously given to the designer as codebase_analysis, and — whenever the requirements are available — the requirements (or the requested change) as requirements_verbatim plus the confirmed scope and user decisions as confirmed_decisions. The reviewer uses codebase_analysis.focusAreas to verify Fact Disposition Table coverage and the paired requirement inputs to verify adopted design validity. Supplying only one of the paired inputs returns rejected.
Pass to next-layer technical-designer: reviewed prior-layer Design Doc path plus prior_layer_verification (the JSON from the prior-layer code-verifier). See Cross-Layer Orchestration section for sequencing. Use prior_layer_verification.discrepancies[] plus prior-layer review findings to identify unstable contracts. Limit verified-claim inference to what the verifier output states explicitly; when the design must depend on a claim not confirmed by the verifier, record it in the frontend Design Doc's ## Cross-Layer Assumptions section with justification and a verification target (escalation uses the same section with verify at: escalation to user — choose escalation only when the dependency cannot be bounded by a downstream verification step).
Pass to work-planner: Design Doc path. Work-planner scans all DD sections and extracts technical requirements per its Step 5 categories (impl-target, connection-switching, contract-change, verification, prerequisite), then produces a Design-to-Plan Traceability table.
Gap handling (orchestrator responsibility): If work-planner outputs a draft plan containing gap entries, the orchestrator MUST:
Unjustified gaps are errors — return to work-planner to add covering tasks or justification.
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 — this is 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.
approvedRegister overall phases using TaskCreate. Update each phase with TaskUpdate as it completes.
| Verifier | Pass | Fail | Blocked |
|----------|------|------|---------|
| code-verifier | summary.status is consistent or mostly_consistent | summary.status is needs_review or inconsistent | summary.status is blocked → Escalate to user with summary.blockingReason (the verifier had no verifiable input; a fix cycle cannot resolve it) |
| security-reviewer | status is approved or approved_with_notes | status is needs_revision | status is blocked → Escalate to user |
Re-run rule: Run at most 2 fix cycles. After each cycle, re-run the verifiers that returned fail and retain the recorded evidence from verifiers that passed. A cycle makes progress only when a previously failing verifier reaches a pass status or its count of named remaining findings decreases. Escalate immediately when a cycle makes no progress or requires external input; after cycle 2, escalate every remaining failure with its findings.
Take shinpr/ai-coding-project-boilerplate-subagents-orchestration-guide from the repository into ~/.claude/skills for personal
use, or into .claude/skills inside a project.
The agent identifies a skill by the name field in its header. Two skills with the
same name cannot sit side by side — one of them will be ignored.