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 oma-coordination
• Quick bug fixes or minor changes

Important

This skill orchestrates per-agent dispatch.

• If

  target_vendor === current_runtime_vendor

  and the runtime has a verified native path, use native dispatch.
• Otherwise fall back to

  oh-my-ag agent:spawn

  .

Current native executor paths:

• Claude Code:

  claude --agent <agent>

• Codex CLI:

  codex exec "@agent ..."

  using

  .codex/agents/*.toml

• Gemini CLI:

  gemini -p "@agent ..."

  using

  .gemini/agents/*.md

Vendor-specific execution protocols are injected automatically for fallback CLI runs.

Configuration

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

oma verify {agent-type}

result-{agent}-{sessionId}.md

See

resources/subagent-prompt-template.md

resources/memory-schema.md

Memory File Ownership

orchestrator-session.md

task-board.md

progress-{agent}[-{sessionId}].md

result-{agent}[-{sessionId}].md

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] Mechanical Self-Check: lint, type-check, tests, diff scope
    ↓
[2] Verify: Run `oma 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] Mechanical Self-Check (formerly "Self-Review"): Before requesting external review, the implementation agent must:

• Run lint, type-check, and tests in the workspace
• Verify only planned files were modified (diff scope check)
• Fix any mechanical failures (compile errors, test failures)

⚠️ Quality judgment is NOT performed in this step. Design quality, architecture alignment, and acceptance criteria satisfaction are evaluated exclusively in [3] Cross-Review by the QA agent. Reason: Self-evaluation bias — agents consistently overrate their own output (ref: Anthropic harness design research).

[2] Automated Verify:

oma 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

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/core/session-metrics.md

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

lessons-learned.md

redo

Recording

After each user correction event:

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

At session end, if CD >= 50:

1. Include CD summary in final report
2. Trigger QA agent RCA generation
3. 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-to-agent mapping:

  ../_shared/core/skill-routing.md

• Verification:

  scripts/verify.sh <agent-type>

• Session metrics:

  ../_shared/core/session-metrics.md

• API contracts:

  ../_shared/core/api-contracts/

• Context loading:

  ../_shared/core/context-loading.md

• Difficulty guide:

  ../_shared/core/difficulty-guide.md

• Reasoning templates:

  ../_shared/core/reasoning-templates.md

• Clarification protocol:

  ../_shared/core/clarification-protocol.md

• Context budget:

  ../_shared/core/context-budget.md

• Lessons learned:

  ../_shared/core/lessons-learned.md