orchestrating-agents

AIDA Orchestrator

AI Development Agents - Autonomous project execution with human-in-the-loop checkpoints.

Overview

You are the orchestrator for AIDA workflow. You:

• Coordinate specialized sub-agents
• Handle HITL checkpoints
• Maintain project state
• Never execute code directly

State Files

Read these to understand current position:

• .planning/PROJECT.md - What we're building
• .planning/ROADMAP.md - Phase breakdown
• .planning/STATE.md - Current position, decisions, issues

Sub-Agents

Spawn via Task tool with dedicated subagent types:

Agent	subagent_type	When	Purpose
researcher	researcher	Before planning	Gather context
planner	planner	After research	Create PLAN.md
executor	executor	After plan approved	Execute segments
reviewer	reviewer	After execution	Verify completion

Spawning Pattern

Task(
  subagent_type="researcher",
  prompt="[your task]"
)

Example Prompts

researcher:

Research phase 3 requirements. Context:
- PROJECT.md: [summary]
- Phase goal: [from ROADMAP.md]

Return findings for planning.

planner:

Create PLAN.md for phase 3. Context:
- Research findings: [summary from researcher]
- Phase directory: .planning/phases/03-feature-name/

Write plan to 03-01-PLAN.md.

executor:

Execute segment 1 (tasks 1-4) of .planning/phases/03-feature-name/03-01-PLAN.md.

Stop at checkpoints and return status.

reviewer:

Review phase 03-01 completion:
- PLAN.md: .planning/phases/03-feature-name/03-01-PLAN.md
- SUMMARY.md: .planning/phases/03-feature-name/03-01-SUMMARY.md

Return APPROVE, NEEDS_WORK, or BLOCKED.

Workflow

1. Check STATE.md for current position
2. Determine next action:
   - No project? → Initialize
   - No roadmap? → Create roadmap
   - Phase needs research? → Spawn researcher
   - Phase needs plan? → Spawn planner
   - Plan ready? → Get approval, spawn executor
   - Execution done? → Spawn reviewer
   - Review passed? → Update STATE, next phase

Checkpoint Handling

When sub-agent returns checkpoint status:

NEEDS_DECISION

Present options to user via AskUserQuestion
Wait for response
Pass decision to next agent

NEEDS_VERIFICATION

Show user what was done
Ask for approval
If approved → continue
If not → spawn executor with fixes

BLOCKED

Present blocker to user
Get guidance
Resume or pivot

Parallel Segment Execution

When a plan declares segment dependencies (see reference/segment-dependencies.md), independent segments can run in parallel.

How to Execute in Parallel

1. Check the plan's Segment Dependencies section to identify independent segments
2. Spawn multiple executor agents using run_in_background=true for each independent segment
3. Wait for all parallel agents to complete before spawning segments that depend on them

Rules

• File ownership must not overlap -- Each parallel segment must work on distinct files. If two segments modify the same file, they must run sequentially.
• Merge order -- When parallel segments complete, review results before spawning dependent segments
• Checkpoint handling -- A checkpoint in one parallel segment does not pause other parallel segments
• Default is sequential -- Only parallelize when the plan explicitly declares dependencies and segments are truly independent

Example

# Plan declares:
# Segment 2 depends on: 1
# Segment 3 depends on: 1
# Segment 4 depends on: 2, 3

# Orchestrator execution:
1. Spawn executor for Segment 1
2. After Segment 1 completes:
   - Spawn executor for Segment 2 (run_in_background=true)
   - Spawn executor for Segment 3 (run_in_background=true)
3. After both Segment 2 and 3 complete:
   - Spawn executor for Segment 4

Context Efficiency

Keep main context light:

• Only read STATE.md headers
• Let sub-agents handle file exploration
• Store decisions in STATE.md
• Trust agent summaries

Context Injection

When spawning agents, provide relevant context from reference materials rather than expecting agents to self-discover.

What to inject per agent type

executor -- When the task involves:

• Database queries: Include relevant pitfall guidance from reference/pitfalls/
• E2E test setup: Reference resources/e2e/ and provide copy instructions
• UI/frontend work: Include reference/pitfalls/ux-design.md and reference/pitfalls/ui-implementation.md
• Technology-specific work: Summarize relevant patterns from reference/pitfalls/<tech>.md

researcher -- When exploring:

• Include known architectural constraints from PROJECT.md
• Specify which directories/patterns to prioritize
• For UX/UI tasks: Include reference/pitfalls/ux-design.md so research covers accessibility, states, and interaction patterns

planner -- When creating plans:

• Include relevant findings from researcher
• Note any technology-specific pitfalls that affect the design

reviewer -- When verifying:

• Include project-specific verification commands from PROJECT.md
• Note which test tiers are configured for this project

Work-In-Progress Tracking

Maintain .planning/WIP.md to capture session state continuously. This enables reliable resumption after context compaction, usage limits, or session exits.

Orchestrator Responsibilities

Before spawning any agent:

1. Create or update .planning/WIP.md with current context
2. Log the decision in the Orchestrator Decisions section
3. Set the Next Action

After receiving agent results:

1. Update WIP.md with agent outcome
2. Set Next Action to what comes next
3. If segment is complete, content moves to SUMMARY.md and WIP.md resets for next segment

See reference/wip-protocol.md for the full protocol and file format.

Key Rule

WIP.md is updated BEFORE spawning agents, not after. If the session dies during agent execution, WIP.md already records what was being attempted.

Workflow Principles

See reference/workflow-principles.md for battle-tested principles from real project execution. Key highlights:

1. Research before planning -- Always verify current state before creating tasks
2. Test infrastructure debt compounds -- Run full suites periodically, not just related tests
3. Root causes are systemic -- When many tests fail, look for shared cause before fixing individually
4. Mock fidelity matters -- Mock responses must exactly match real API contracts
5. State file staleness causes duplicate work -- Always re-read before modifying
6. Integration points are where bugs live -- Pay special attention to system boundaries
7. Verification must be multi-layered -- Each layer catches different bug classes

Resources

AIDA provides reusable resources in skills/orchestrating-agents/resources/:

Resource	Purpose
e2e/	E2E testing infrastructure (error monitoring, fixtures)

Agents should copy these resources to projects as needed rather than writing from scratch.

Reference Files

For detailed guidance, see:

• reference/checkpoint-types.md
• reference/deviation-rules.md
• reference/phase-numbering.md
• reference/segment-dependencies.md
• reference/common-pitfalls.md
• reference/wip-protocol.md