/oma-orchestration

name: oma-orchestration
description: Dispatch and supervise parallel specialist agents with durable task
  state. Use when automated multi-agent execution is requested.

Orchestration - Automated Multi-Agent Coordination

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 `oma 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 unresolved decisions
• Spawns processes/agents and reads/writes memory/result files
• Preserves unresolved evidence when bounded recovery stops

Structural Flow

Entry

1. Resolve agent vendor routing and runtime dispatch path. 2. Decompose request into priority-tiered tasks. 3. For each task, classify into one or more `domain_tags` by matching against the `Intent signature` block of each installed `.agents/skills/oma-*/SKILL.md`. Tasks that match no domain confidently inherit the union of their parent feature's tags. 4. Select the references needed by each task. One confidently matched skill is sufficient; expand the set when classification is uncertain or a dependency requires another domain. 5. Record selected domains, references, and any fallback reason in the task board. These are coordinator notes, not launcher-enforced exposure fields; use only reference/context controls supported by the active dispatch path. 6. Apply the shared collaboration policy before dispatch: assign edit ownership, peer contact paths, and a collection owner.

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 verified claims, compile summary, and preserve progress artifacts.

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 recovery limits are exceeded, preserve review history and return `partial` or `failed`; never force completion.
• If recovery shows that a required domain reference was missing, update the task's reference selection without changing its frozen acceptance contract, and supply it through the supported context mechanism.

Failure and recovery

• Retry failed agents up to configured limits.
• Re-spawn with review history when review loop is exhausted.
• Continue independent work after recording material corrections; ask only for a material missing decision.

Exit

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

Logical Operations

Actions

| Action | SSL primitive | Evidence | |--------|---------------|----------| | Read config and task context | `READ` | oma config, routing, request | | Classify task into domain tags | `INFER` | task text vs each skill's `Intent signature` | | Select task references | `SELECT` | confident domain matches, dependencies, and supported context controls | | Select dispatch path | `SELECT` | Native vs fallback | | Write session state | `WRITE` | task board and memory files | | Spawn agents | `CALL_TOOL` | exposed native role-subagent tool or `oma 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

• Exposed native role-subagent tools, fallback spawn scripts, memory tools, verify script, QA agent
• Session metrics, prompt templates, task templates

Canonical command path

oma agent spawn <agent-type> <prompt-file> <session-id> --task-id <task.id> -w <workspace>
oma verify agent <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 | | `PRO