OMA Multi-Agent Orchestrator

Orchestrator - Automated Multi-Agent Coordinator

Scheduling

Goal

Automatically orchestrate multi-agent execution with task decomposition, native/fallback dispatch, memory coordination, progress monitoring, verification, QA cross-review, retry, and result collection.

Intent signature

• User asks to orchestrate, run in parallel, automate multi-agent execution, or coordinate full-stack work end to end.
• Task requires multiple specialist agents and a persistent review/remediation loop.

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

Expected inputs

• Complex feature or workflow request
• Project config, model/vendor routing, agent types, task constraints, and workspace/session needs
• Acceptance criteria and verification expectations

Expected outputs

• Orchestrator session state, task board, progress files, result files, and final summary
• Specialist agent outputs after mechanical checks, automated verify, and QA cross-review
• Review history and retry/remediation status when loops fail

Dependencies

• .agents/oma-config.yaml, .codex/agents/*.toml, .gemini/agents/*.md, or fallback oh-my-ag agent:spawn
• Memory provider config, subagent prompt template, scripts, task templates, verify script, and session metrics

Control-flow features

• Branches by vendor/native dispatch availability, priority tiers, agent completion/failure, verification status, QA verdict, retry limits, and clarification debt
• Spawns processes/agents and reads/writes memory/result files
• Blocks termination until persistent workflows complete

Structural Flow

Entry

1. Resolve agent vendor routing and runtime dispatch path.
2. Decompose request into priority-tiered tasks.
3. Create session memory and task board.

Scenes

1. PREPARE: Plan, setup session ID, and initialize memory files.
2. ACT: Spawn agents by priority tier within parallelism limits.
3. VERIFY: Run self-check, oma verify, and QA cross-review loop.
4. RECOVER: Retry failed agents with review history when limits allow.
5. FINALIZE: Collect result files, compile summary, and clean progress files.

Transitions

• If native dispatch is available for current runtime/vendor, use it.
• If vendors differ or native path is unavailable, use fallback spawn.
• If verify or QA fails, feed feedback back to the implementation agent.
• If review loop limits are exceeded, report review history and quality warning.

Failure and recovery

• Retry failed agents up to configured limits.
• Re-spawn with review history when review loop is exhausted.
• Pause or request re-specification when clarification debt thresholds are exceeded.

Exit

• Success: all tasks complete, verify/review pass, and results are summarized.
• Partial success: failed agents, exhausted review loops, or clarification debt are explicit.

Logical Operations

Actions

Tools and instruments

• Native CLI subagent dispatch, fallback spawn scripts, memory tools, verify script, QA agent
• Session metrics, prompt templates, task templates

Canonical command path

oma agent:spawn <agent-type> "<task>" <session-id> -w <workspace>
oma verify <agent-type> --workspace <workspace> --json

When native runtime dispatch is available, prefer the runtime-specific native path listed in this skill before falling back to oma agent:spawn.

Resource scope

Preconditions

• Task is decomposable into specialist agent work.
• Runtime/vendor dispatch path or fallback exists.

Effects and side effects

• Spawns agents and writes session/progress/result artifacts.
• May cause code changes through specialist agents.
• May trigger iterative review and retries.

Guardrails

1. Orchestrate per-agent dispatch from the project configuration before spawning any agent.
2. If target_vendor === current_runtime_vendor and the runtime has a verified native path, use native dispatch.
3. Otherwise fall back to oh-my-ag agent:spawn.
4. Never exceed the configured parallelism or retry limits.
5. Keep session state, task-board state, progress files, and result files aligned throughout the run.

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"
    }
  }
}