oma-orchestration

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.

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
PROCESS	Agent CLI processes and verify scripts
MEMORY	Session state and unresolved decisions
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 oma agent spawn.
4. Never exceed configured parallelism or the aggregate recovery budget. Ordinary retries and exploration hypotheses both consume it.
5. Keep session state, task-board state, progress files, claims, and receipts aligned. Use the plan task ID on every spawn and native begin/finish path.
6. Select references by task needs and confidence. Do not expand to all skills solely because one skill matches, or assume task-board metadata enforces runtime exposure.

Current native executor paths:

• Claude Code: Agent tool with .claude/agents/{agent}.md definitions (multiple Agent tool calls in one message run in parallel; results return synchronously — no polling)
• OpenCode: native task tool with subagent_type: {agent-id}; do not use oma agent spawn for same-session OpenCode work because it will not appear as a native child task
• Codex: use the current session's exposed native subagent tool with the resolved custom role from .codex/agents/*.toml when supported; otherwise use oma agent spawn.
• Gemini: use the current session's exposed native role-subagent tool with the resolved role when supported; otherwise use oma agent spawn.

codex exec and gemini -p start external CLI sessions. An @agent string in a prompt does not establish native dispatch or apply a custom-role contract.

Configuration

Setting	Default	Description
MAX_PARALLEL	3	Max concurrent subagents
MAX_RECOVERY_ATTEMPTS	3	Total retries and exploration hypotheses per task, including the original attempt
POLL_INTERVAL	30s	Status check interval
Turn guidance	role-specific	Checkpoint/resume signal, not a hard stop or approval boundary

These are workflow defaults. Resolve model/vendor, parallelism, and budget settings from project configuration. config/cli-config.yaml supplies the vendor transport registry; it does not select the active vendor or override runtime execution settings.

Memory Configuration

Memory provider and tool names are configurable via .agents/mcp.json (not the repo-root .mcp.json, which is the Claude Code MCP server config):

{
  "memoryConfig": {
    "provider": "file",
    "basePath": ".agents/state/memories",
    "tools": {
      "read": "Read",
      "write": "Write",
      "edit": "Edit"
    }
  }
}

Workflow Phases

PHASE 1 - Plan: Reuse the current valid plan or decompose the request; preserve injected session/task/run IDs. PHASE 1.5 - References: Select task references as described in Entry; record uncertainty and expansion reasons without assuming runtime enforcement. PHASE 2 - Setup: Create session/task-board artifacts with the current IDs and selected references. PHASE 3 - Execute: Dispatch ready tasks within MAX_PARALLEL using supported native or fallback context controls. PHASE 4 - Monitor: Poll every POLL_INTERVAL; handle completed/failed/crashed agents PHASE 4.5 - Verify: Run mechanical checks for every completed agent; run oma verify agent {agent-type} only for backend, frontend, mobile, qa, debug, and pm; then run QA cross-review for every completed implementation PHASE 5 - Collect: Read claims and run-scoped reports for plan tasks whose checks passed; compile summary without deleting evidence.

Memory File Ownership

File	Owner	Others
orchestrator-session-{sessionId}.md	orchestrator	read-only
task-board-{sessionId}.md	orchestrator	read-only
progress-{agentId}-{taskId}-{runId}-{sessionId}.md	that run	orchestrator reads
result-{agentId}-{taskId}-{runId}-{sessionId}.md	that run	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: For supported types, run `oma verify agent {agent-type} --workspace {workspace}`
    Unsupported (`db`, `refactor`, `architecture`, `tf-infra`, `docs`) → record SKIP and continue
    ↓ 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 causes agents to consistently overrate their own output (ref: Anthropic harness design research).

[2] Automated Verify:

oma verify agent {agent-type} --workspace {workspace} --json

• Run only for backend, frontend, mobile, qa, debug, and pm.
• For db, refactor, architecture, tf-infra, and docs, record that automated verify is unsupported and continue to QA cross-review after the mechanical checks.
• 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	Stop recovery; preserve failed checks and return partial or failed

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. Resolve relevant automated checks before handoff. Ask for approval only when the next action is outside existing authorization.

Recovery Budget (after review loop exhaustion)

Maintain one budget per workflow lineage and logical goal: attempts_used, attempts_remaining, and any configured cost cap. The original attempt, each ordinary retry, and each exploration hypothesis consume one attempt. Before starting recovery, reserve the complete next action; do not exceed the budget or start an incomplete exploration round.

Use the plan's stable lineage_id and task goal_id from ../_shared/runtime/result-contract.md. New task/run/session IDs do not reset that budget. Freeze the full JSON plan at first dispatch; reject recursive planning/review tasks and post-dispatch plan revisions. A contract change requires an explicitly separated new session and lineage.

Classify failures before retrying: PRODUCT_FAILURE follows the remaining product recovery budget; WORKFLOW_EVIDENCE_FAILURE means current product checks passed but completion claims or bindings failed. Automatic resume stops evidence-only replay. Allow at most one metadata-only repair under the existing task and frozen plan, consuming the same budget, then stop with a partial handoff if unresolved. Do not create PM tasks, rerun product planning, or import another workflow's plan-review loop for evidence failures.

• First remaining attempt: re-spawn with review history.
• Later attempts: choose either one different retry or a 2–3 hypothesis round only if enough attempts and cost remain.
• On cap exhaustion, preserve all checks, review findings, and unresolved work. The task is partial or failed, never completed.

Session evidence

For material corrections or review findings, retain the cause, impact, and evidence in existing task artifacts. Use ../_shared/core/session-metrics.md when a retrospective or separate session summary is useful. Do not score clarification questions or require an RCA based on counters. Resolve the affected work and ask only for a material missing decision.

References

• Prompt template: resources/subagent-prompt-template.md
• Memory schema: resources/memory-schema.md
• 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 contract template (SSOT): ../_shared/core/api-contracts/template.md; read generated contracts from .agents/results/api-contracts/ (run artifact) or docs/plans/contracts/ (durable spec)
• Context loading: ../_shared/core/context-loading.md
• Task decomposition: ../_shared/core/difficulty-guide.md (unresolved scope or dependencies)
• Clarification protocol: ../_shared/core/clarification-protocol.md
• Context budget: ../_shared/core/context-budget.md
• Code intelligence: ../_shared/core/code-intelligence.md
• Runtime lessons: ../_shared/core/lessons-learned.md (recurring failure or requested retrospective)