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
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
| 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
```bash
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
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

| 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) | 2