Subagents Orchestration Guide

Subagents Orchestration Guide

Load subagent-delegation for assignment, waiting, and intervention rules. This guide owns workflow-specific coordination.

Spawn rule: every spawn_agent call uses fork_turns="none" so the subagent receives only the task message and explicitly provided context.

Role: The Orchestrator

The orchestrator owns workflow state and directly performs lightweight coordination: locating artifacts, reading status fields, resolving paths, applying explicit user answers, updating execution plans and approval fields, running deterministic repository checks, and composing specialist inputs. Invoke a specialized subagent when a recipe names that role or the work requires its domain judgment or implementation authority.

Execution Plans

Reuse one active execution plan for the recipe. When none exists, create it before substantive multi-step work with the recipe phases and final verification, then update the same plan as evidence is produced. Agent-internal execution plans remain local to each agent. Plans prevent skipped work; their wording or presence is not a user approval gate.

Entry Ownership

The invoked recipe determines the workflow entry point. Recipes for new or scope-changing requirements may invoke requirement-analyzer for compact scope and cost evidence. The user and orchestrator retain requirements, Structural Scale, and ADR decisions. Continuation, build, review, diagnosis, document update, and reverse-engineering recipes resume from their declared artifacts and request new scope evidence only when their own scope-change rule fires.

Requirement Convergence

The orchestrator builds the convergence object from the user's wording and uses requirement-analyzer's scope and cost evidence for trade-offs, questions, and routing decisions. At the requirements stop, run the requirement-convergence hearing, then determine Structural Scale from the confirmed requirements and supplied evidence. User-confirmed boundaries supply requirements; orchestrator decisions supply routing.

Before a PRD or Design Doc exists, include the object only in the handoff that needs it. After it is persisted, pass the document path instead of copying the object through later prompts.

A PRD is both a binding product contract and a Product Context carrier. Downstream design and planning prompts consume the converged outcome, confirmed requirements, acceptance criteria, user-decided exclusions, and explicit constraints. They load Product Context only when one of those binding items cites it. This keeps business, UX, and feasibility background available for product judgment without turning it into implementation scope.

Requirement Change Detection During Flow [MANDATORY]

During flow execution, compare a user addition with the approved outcome, requirements, and exclusions:

• A clarification that preserves all three is applied by the orchestrator to the active artifact or task.

Resume from the earliest artifact affected by a confirmed scope change while preserving completed unaffected work.

Orchestration Principles

Task Assignment with Responsibility Separation [MANDATORY]

Assign work based on each subagent's responsibilities:

What the orchestrator completes directly:

• Artifact discovery, path and status resolution, and exact task-set computation
• Execution-plan and approval-field updates
• Applying explicit user answers and governing-source resolutions
• Deterministic commands and lightweight evidence collection needed to route the next step

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:

• Applicable repository checks discovered from the task, changed files, manifests, configuration, and CI
• Complete execution of quality error fixes
• Self-contained processing until fix completion
• Final approved judgment (only after fixes are complete)

How to Spawn Agents

Apply the Spawn rule above. Resolve missing workflow inputs that affect the next action or its verification from repository and governing evidence; route remaining blockers through Orchestrator Escalation Resolution.

Spawn Prompt Requirements

• When the assigned action writes repository files, include: The orchestrator has delegated this repository-writing task from the user's requested workflow. This invocation authorizes the repository writes required to produce or update the assigned deliverable within the supplied scope. Perform the writes and return the result. The orchestrator applies any workflow review or approval gate to the returned artifact afterward.
• When invoking task-executor*, also include the exact task file path, for example: Execute the implementation task. Task file: docs/plans/tasks/[filename].md.

Analysis Assignment

For codebase-analyzer and ui-analyzer, determine the effective child model, including known inheritance. Pass exploration_mode: autonomous only for gpt-6-astra; pass guided for every other or unknown model.

Assign distinct questions: codebase analysis owns responsibility/data/contracts/reuse; UI analysis owns rendering/interaction/visual evidence. Pass existing relevant findings as prior_evidence to reuse them. Carry evidence-backed simplifications into design or adjustment as candidates, retaining their conditions; outcome or approved-decision changes remain user decisions.

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 Orchestrator Escalation Resolution requires user input. Skipping stop points is a CRITICAL VIOLATION.

Design Approval

At the existing design approval stop, read the current PRD (when present) and Design Doc(s). Derive the minimum user-visible value and briefly state it alongside the major changes included, making internal mechanism changes or refactoring visible. Ask whether this MVP and scope match the user's intent. Keep this to a short alignment message, rather than design detail or a justification of necessity. Apply corrections through the existing scope-change flow.

Common Status Meanings

Use agent statuses as routing signals, not as a parser contract. Interpret the returned artifact and evidence when a field is absent or worded differently.

Review Resolution

Apply references/review-resolution.md to design and post-implementation reviews. Pass the governing requirements and accepted decisions to reviewers and correction authors.

Orchestrator Escalation Resolution [MANDATORY]

Apply this procedure when a workflow result cannot support the next action, including escalation_needed, blocked, a missing artifact, or contradictory evidence. The response returns control to the orchestrator; it is not itself a human stop. For review results, Review Resolution still governs scope, completed reviewers, and rerun boundaries.

1. Resolve the issue from approved requirements, governing artifacts, repository evidence, and prior agent outputs. Choose the smallest resolution that preserves approved intent.
2. Invoke the responsible author or reviewer with the artifact and concrete issue, then retry the interrupted step with the resulting artifact and evidence.
3. Retry the interrupted step while corrections add evidence or materially change the result. When progress stops, decide the remaining disposition from governing sources and continue to the next resolution step.
4. Resume when the interrupted step succeeds or only a non-blocking disagreement remains. Escalate to the user only when resolution requires a new or changed requirement, a business or product decision, a change to an approved major design decision, unavailable user-held authority, or an unauthorized irreversible action. Preserve completed work and unaffected tasks.

Work Plan Resolution

Resolve an exact Work Plan path from the first applicable source: an explicit recipe argument, the active execution plan's Work Plan, or Work Plans derived from task files matching the recipe's managed task patterns. When no managed task file yields a candidate, treat non-template Work Plans as candidates. Use the sole candidate; when multiple candidates remain, present them for selection; when none exists, report the exact missing prerequisite.

Work Plan Approval

Planning recipes create and review the Work Plan, then ask the user to approve its implementation scope. Record the result in the plan's existing plan-level status field.

A build proceeds when the plan clearly records user approval. Treat common plan-level forms such as WorkPlan Review or Implementation Approval with an approved status as equivalent; headings and punctuation are not control fields. When approval is absent or genuinely ambiguous, ask once before invoking agents. A requested material plan change returns to work-planner and document review, then asks for approval again. Regenerate uncommitted task files affected by the changed plan and preserve completed unaffected work.

Scale Determination and Document Requirements

Use documentation-criteria Structural Scale as the single scale definition.

* Update if PRD exists for the relevant feature ** One ADR per durable technical choice that requires comparison between at least two credible materially distinct options; the Choice and Durability filters determine qualification independently of scale *** New creation/update existing/reverse PRD (when no existing PRD)

Using Agent Results

Agent schemas describe their full internal result. The orchestrator consumes only the fields needed for the next action:

Continue through minor optional-field, serialization, or wording differences when the orchestrator can verify the required outcome from the artifact, repository, or command result. Verify claimed paths before passing them onward. Route a missing artifact, failed implementation, unresolved contradiction, or otherwise unusable result through Orchestrator Escalation Resolution.

Per-Task Change Set

For each implementation task, record diffBase and maintain one taskWriteSet:

1. Initialize it from the first executor's filesModified and the repository diff from diffBase.
2. Union files changed by executor retries, review fixes, stub repairs, and the quality fixer.
3. Before quality review and before commit, reconcile it with repository state so earlier changes are retained and unrelated user changes are excluded.
4. Pass the accumulated taskWriteSet to the quality fixer. After quality approval, commit only implementation, test, and required generated files in that set. After that commit succeeds, mark the Task File's satisfied Completion Criteria and the corresponding Work Plan task and phase complete, then update the active execution plan.

Task Files and Work Plans are local workflow state. Exclude both from implementation commits; their checkboxes record completion only after quality approval and a successful implementation commit.

Handling Requirement Changes

Handling Requirement Changes in requirement-analyzer

Pass requirement changes to requirement-analyzer as complete self-contained 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

After the selected entry recipe completes its requirement stop, follow the minimum flow required by scale and affected layers. Continuation recipes resume from their declared artifact.

Flow rules:

• Backend layer analysis runs codebase-analyzer. Frontend layer analysis resolves decision-relevant external or prototype inputs, then runs codebase-analyzer and ui-analyzer; independent calls may run in parallel. Fullstack layer analysis follows references/monorepo-flow.md.
• Frontend and fullstack flows create the UI Spec from completed layer analysis before ADR or Design Doc creation.
• When a frontend or fullstack UI Spec uses a prototype, pass prototype_reference_strength to ui-spec-designer. Use binding when the supplied context makes the prototype's rendering the implementation target; otherwise use reference. Ask the user only when the choice changes the current UI outcome and the supplied context materially supports both readings.
• After analysis, apply the Choice filter to each candidateDecisionPoint, then apply the Durability filter to the retained set. Create one ADR per qualifying point, then review and approve the complete ADR batch once. These filters are the exclusive ADR creation basis and Structural Scale is supporting context.
• Pass requirement-analyzer's compact scope evidence and original requirements to codebase-analyzer; the orchestrator separately owns and carries the confirmed convergence record until a PRD or Design Doc persists it.
• For Small flows whose confirmed scope is carried by the execution task, use the llm-friendly-context Task File Contract to create docs/plans/tasks/small-{name}.md. Build its outcome, targets, steps, and verification from the confirmed requirement and repository scope; embed outcome, requirements, nonGoals, and readiness in Governing Sources. Pass the exact file to the layer-appropriate executor. Requirement confirmation authorizes this cycle; work-planner, WorkPlan review, and task-decomposer are outside the path. Remove the task file after Post-Implementation Review passes.
• Pass only codebase-analyzer material that changes reuse, simplification, option validity or selection, lifecycle cost, a preserved contract, design, or verification to the relevant ADR/Design Doc owner.
• Pass a Design Doc path to code-verifier, apply Review Resolution to its discrepancies, and pass only resolved verification evidence 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. Resolve needs_revision through Review Resolution with work-planner, then ask the user to approve the reviewed plan. Route governing-source contradictions through Orchestrator Escalation Resolution.

Autonomous Execution Mode

Conditional Environment Preparation

Build recipes proceed with the approved task set. recipe-prepare-implementation runs when the user explicitly requests repository-local setup or when a concrete task-local capability failure makes preparation the smallest authorized Orchestrator Escalation Resolution. Unaffected implementation continues.

Authority Grant

After implementation-scope approval:

• Medium/Large Work Plan batch approval, or Small-flow confirmation of the converged requirement, grants execution authority
• task-executor: Implementation authority
• quality-fixer: Fix authority (automatic quality error fixes)

Definition of Autonomous Execution Mode

After implementation-scope approval, autonomously execute the following processes without human approval:

Approved scope -> task decomposition when needed -> each task:
implementation -> optional integration-test review -> quality-fixer -> commit
-> final code/security review -> completion report

Reviewer findings in this mode are candidates, not work orders; create repair work only from the Review Resolution apply set.

For each task, record diffBase, run the routed executor, and inspect the resulting repository change. Add each execution or repair result to the Per-Task Change Set. Run integration-test-reviewer when requiresTestReview is true and changed integration/E2E paths exist, then resolve findings through Review Resolution. Run the routed quality-fixer with the accumulated taskWriteSet and the executor's operation-verification evidence. The quality fixer reruns task-specific verification when evidence is missing or its fixes can invalidate that evidence. On quality approval, add its changed paths to the set and commit the implementation files. After the commit succeeds, mark the Task File's satisfied Completion Criteria and the corresponding Work Plan task and phase complete, then update the active execution plan. Repair stub_detected through the same implementation owner. Resolve blocked or unusable results through Orchestrator Escalation Resolution.

Conditions for Stopping Autonomous Execution

Stop autonomous execution and request user input in the following cases:

1. Orchestrator resolution requires user input: Orchestrator Escalation Resolution reaches one of its user-escalation conditions
2. Confirmed scope change needs approval: Requirement Change Detection routes the addition through Requirement Convergence
3. User explicitly stops: Direct stop instruction or interruption

Agent blocked results, maintained blocking findings, and implementation deviations first enter Orchestrator Escalation Resolution. The orchestrator requests user input only under that procedure's explicit user-decision conditions.

Continue autonomous execution in the following situations:

• A workflow subagent is still pending
• wait_agent returns timed_out=true
• The orchestrator has partial context but is still waiting on a required subagent output

Use the task loop defined in the autonomous execution diagram above. The canonical per-task cycle is:

1. capture diffBase, execute the task, and accumulate its change set
2. resolve escalation or integration-test review when applicable
3. run the quality fixer on the accumulated change set and repair until approved
4. commit implementation files, then record Task File, Work Plan task/phase, and execution-plan completion locally

Post-Implementation Review

Run code-reviewer against the complete implementation change set and its governing Design Docs, or the active task file for a Small flow. Rerun only a reviewer that has not passed, with prior_feedback containing its previous complete result, finding dispositions, and correction paths or diff; preserve passed reviewers and unaffected evidence. The Small path also passes its active task file to security-reviewer as type: task-file. Mechanical repository checks remain owned by the quality-fixer in each implementation or review-fix task cycle.

Apply Review Resolution to reviewer findings. Apply a security-reviewer finding only when leaving it unresolved would violate an explicit governing requirement or repository rule, or leave a concrete material security failure in the actual reachable trust model. The violated requirement, rule, or failure defines implementation scope: route the smallest correction that resolves it, treating the reviewer's suggestion as one candidate implementation.

Main Orchestrator Roles

1. State Management: Track current phase, each subagent's state, and next action
2. Lightweight Workflow Work: Resolve artifact paths and statuses, decide convergence and finding dispositions exclusively from supplied materials, update execution plans and approval fields, and run deterministic routing checks
3. Information Bridging: Data conversion and transmission between subagents
   • Extract only facts that can change the next consumer's decision, action, or verification
   • Pass artifact paths instead of copied content when the artifact is the next consumer's governing input
   • Explicitly integrate initial and additional requirements when requirements change
4. Quality Assurance and Commit Execution: Execute git commit through the per-task cycle
5. Autonomous Execution Mode Management: Start/stop autonomous execution after approval and escalation decisions
6. ADR Status Management: Update ADR status after user decision (Accepted/Rejected)

Required Handoffs

Handoff rules:

• Until persistence, pass the compact convergence object only to the next consumer that needs it. After persistence, pass its PRD or Design Doc path
• Downstream consumers exclude nonGoals and speculative requirements from current work
• Verify generated artifact paths before passing them onward
• Require every Work Plan task to cite the Design Doc section or AC that authorizes its repository implementation outcome

Important Constraints [MANDATORY]

• Quality check is REQUIRED: quality-fixer approval MUST be obtained before commit
• Usable result required: Continue from verified artifacts and repository evidence; resolve missing or unusable results before passing them onward
• Approval management: Document creation -> Execute document-reviewer -> Get user approval before proceeding
• Flow confirmation: After approval, select the next step from the active recipe and current artifact state
• 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, complete review resolution before requesting approval or proceeding from an existing approval
• 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 active recipe and current phase
• Decided the next action from the active recipe and current artifact state
• Monitored requirement changes and errors during autonomous execution mode

References

• references/review-resolution.md: Evidence- and ROI-based review finding resolution
• references/monorepo-flow.md: Fullstack (monorepo) orchestration flow