Orchestrator - Automated Multi-Agent Coordinator

When to use

Complex feature requires multiple specialized agents working in parallel
User wants automated execution without manually spawning agents
Full-stack implementation spanning backend, frontend, mobile, and QA
User says "run it automatically", "run in parallel", or similar automation requests

When NOT to use

Simple single-domain task -> use the specific agent directly
User wants step-by-step manual control -> use workflow-guide
Quick bug fixes or minor changes

Important

This skill orchestrates CLI subagents via oh-my-ag agent:spawn. The CLI vendor (gemini, claude, codex, qwen) is resolved from configuration. Vendor-specific execution protocols are injected automatically. Each subagent runs as an independent process.

Configuration

Setting	Default	Description
MAX_PARALLEL	3	Max concurrent subagents
MAX_RETRIES	2	Retry attempts per failed task
POLL_INTERVAL	30s	Status check interval
MAX_TURNS (impl)	20	Turn limit for backend/frontend/mobile
MAX_TURNS (review)	15	Turn limit for qa/debug
MAX_TURNS (plan)	10	Turn limit for pm

Memory Configuration

Memory provider and tool names are configurable via mcp.json:

{
  "memoryConfig": {
    "provider": "serena",
    "basePath": ".serena/memories",
    "tools": {
      "read": "read_memory",
      "write": "write_memory",
      "edit": "edit_memory"
    }
  }
}

Workflow Phases

PHASE 1 - Plan: Analyze request -> decompose tasks -> generate session ID PHASE 2 - Setup: Use memory write tool to create orchestrator-session.md + task-board.md PHASE 3 - Execute: Spawn agents by priority tier (never exceed MAX_PARALLEL) PHASE 4 - Monitor: Poll every POLL_INTERVAL; handle completed/failed/crashed agents PHASE 4.5 - Verify: Run oh-my-ag verify {agent-type} per completed agent PHASE 5 - Collect: Read all result-{agent}.md, compile summary, cleanup progress files

See resources/subagent-prompt-template.md for prompt construction. See resources/memory-schema.md for memory file formats.

Memory File Ownership

File	Owner	Others
`orchestrator-session.md`	orchestrator	read-only
`task-board.md`	orchestrator	read-only
`progress-{agent}.md`	that agent	orchestrator reads
`result-{agent}.md`	that agent	orchestrator reads

Agent-to-Agent Review Loop (PHASE 4.5)

After each agent completes, enter an iterative review loop — not a single-pass verification.

Loop Flow

Agent completes work
    ↓
[1] Self-Review: Agent reviews its own changes
    ↓
[2] Verify: Run `oh-my-ag verify {agent-type} --workspace {workspace}`
    ↓ FAIL → Agent receives feedback, fixes, back to [1]
    ↓ PASS
[3] Cross-Review: QA agent reviews the changes
    ↓ FAIL → Agent receives review feedback, fixes, back to [1]
    ↓ PASS
Accept result ✓

Step Details

[1] Self-Review: Before requesting external review, the implementation agent must:

Re-read its own diff and check against the task's acceptance criteria
Run lint, type-check, and tests in the workspace
Fix any issues found before proceeding

[2] Automated Verify:

oh-my-ag verify {agent-type} --workspace {workspace} --json

PASS (exit 0): Proceed to cross-review
FAIL (exit 1): Feed verify output back to the agent as correction context

[3] Cross-Review: Spawn QA agent to review the changes:

QA agent reads the diff, runs checks, evaluates against acceptance criteria
If docs/CODE-REVIEW.md exists, QA agent uses it as the review checklist
QA agent outputs: PASS (with optional nits) or FAIL (with specific issues)
On FAIL: issues are fed back to the implementation agent for fixing

Loop Limits

Counter	Max	On Exceeded
Self-review + fix cycles	3	Escalate to cross-review regardless
Cross-review rejections	2	Report to user with review history
Total loop iterations	5	Force-complete with quality warning

Review Feedback Format

When feeding review results back to the implementation agent:

## Review Feedback (iteration {n}/{max})
**Reviewer**: {self / verify / qa-agent}
**Verdict**: FAIL
**Issues**:
1. {specific issue with file and line reference}
2. {specific issue}
**Fix instruction**: {what to change}

This replaces single-pass verification. Most "nitpicking" should happen agent-to-agent. Human review is reserved for final approval, not catching lint errors.

Retry Logic (after review loop exhaustion)

1st retry: Re-spawn agent with full review history as context
2nd retry: Re-spawn with "Try a different approach" + review history
Final failure: Report to user with complete review trail, ask whether to continue or abort

Clarification Debt (CD) Monitoring

Track user corrections during session execution. See ../_shared/session-metrics.md for full protocol.

Event Classification

When user sends feedback during session:

clarify (+10): User answering agent's question
correct (+25): User correcting agent's misunderstanding
redo (+40): User rejecting work, requesting restart

Threshold Actions

CD Score	Action
CD >= 50	RCA Required: QA agent must add entry to `lessons-learned.md`
CD >= 80	Session Pause: Request user to re-specify requirements
`redo` >= 2	Scope Lock: Request explicit allowlist confirmation before continuing

Recording

After each user correction event:

[EDIT]("session-metrics.md", append event to Events table)

At session end, if CD >= 50:

Include CD summary in final report
Trigger QA agent RCA generation
Update lessons-learned.md with prevention measures

References

Prompt template: resources/subagent-prompt-template.md
Memory schema: resources/memory-schema.md
Config: config/cli-config.yaml
Scripts: scripts/spawn-agent.sh, scripts/parallel-run.sh, scripts/verify.sh
Task templates: templates/
Skill routing: ../_shared/skill-routing.md
Verification: scripts/verify.sh <agent-type>
Session metrics: ../_shared/session-metrics.md
API contracts: ../_shared/api-contracts/
Context loading: ../_shared/context-loading.md
Difficulty guide: ../_shared/difficulty-guide.md
Reasoning templates: ../_shared/reasoning-templates.md
Clarification protocol: ../_shared/clarification-protocol.md
Context budget: ../_shared/context-budget.md
Lessons learned: ../_shared/lessons-learned.md

orchestrator