Oma 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

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

Scenes

• PREPARE: Plan, setup session ID, and initialize memory files.
• ACT: Spawn agents by priority tier within parallelism limits.
• VERIFY: Run self-check, oma verify, and QA cross-review loop.
• RECOVER: Retry failed agents with review history when limits allow.
• 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

| Action | SSL primitive | Evidence |

|--------|---------------|----------|

| Read config and task context | READ | oma config, routing, request |

| Select dispatch path | SELECT | Native vs fallback |

| Write session state | WRITE | task board and memory files |

| Spawn agents | CALL_TOOL | native CLI or oh-my-ag agent:spawn |

| Poll progress | READ | progress/result files |

| Run verification | CALL_TOOL | oma verify, tests, QA |

| Update retry state | UPDATE_STATE | loop counters and CD metrics |

| Report final result | NOTIFY | compiled summary |

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

| Scope | Resource target |

|-------|-----------------|

| LOCAL_FS | Session, task-board, progress, result, config files |

| PROCESS | Agent CLI processes and verify scripts |

| MEMORY | Session state and clarification debt |

| CODEBASE | Workspaces owned by spawned agents |

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

• Orchestrate per-agent dispatch from the project configuration before spawning any agent.
• 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.
• Never exceed the configured parallelism or retry limits.
• 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

| 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 oma verify {agent-type} per completed agent

PHASE 5 - Collect: Read all result-{agent}-{sessionId}.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}[-{sessionId}].md | that agent | orchestrator reads |

| result-{agent}[-{sessionId}].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] 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

| Counter | Max | On Exceeded |

|---------|-----|-------------|

| Self-check + 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/core/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-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