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 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. 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. Build a per-task exposed_skill_set = skills whose name is in domain_tags. If |exposed_skill_set| < 2 after classification, fall back to the full installed set (flat exposure) and record exposure_fallback: true in the task board.
5. Create session memory and task board with exposed_skill_set and exposure_fallback per task.

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.
• If a task's exposed_skill_set excludes a skill that a recovered failure indicates was needed, re-classify the task and re-dispatch with the expanded set rather than retrying against the original narrow set.

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 oma 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.
6. Domain gating must be soft: prefer a narrower exposed_skill_set, but fall back to flat exposure when classification confidence is low rather than starving a task of a required specialist.

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

These are skill-level defaults applied by the orchestrating agent; they are not read from config/cli-config.yaml (which carries only vendor CLI and execution settings such as results_dir and timeout).

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: Analyze request -> decompose tasks -> generate session ID PHASE 1.5 - Domain gate: For each task, intersect Intent signature matches across installed skills to derive exposed_skill_set. Record exposure_fallback: true when the intersection is too small to be useful and the flat library is used instead. PHASE 2 - Setup: Use memory write tool to create orchestrator-session.md + task-board.md (include exposed_skill_set per task) PHASE 3 - Execute: Spawn agents by priority tier (never exceed MAX_PARALLEL); inject only exposed_skill_set into each subagent's available specialist list 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-type} only for backend, frontend, mobile, qa, debug, and pm; then run QA cross-review for every completed implementation 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

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

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)

Before starting any retry, check the termination conditions (OR, whichever fires first wins):

1. Retry cap: retry count for this agent has reached MAX_RETRIES — do not start another cycle.
2. Session cost cap: if a quota cap is configured (loadQuotaCap() from cli/io/session-cost.ts; no cap → skip), call checkCap(sessionId, cap). On exceeded === true, save the agent's partial results, report early termination due to quota, and do not spawn the next retry or any remaining agents in the tier.

If neither condition fires:

• 1st retry: Re-spawn agent with full review history as context
• 2nd retry: Re-spawn with "Try a different approach" + review history
• After MAX_RETRIES exhausted (cost cap not exceeded): activate the Exploration Loop (see orchestrate.md Step 5): generate 2-3 alternative hypotheses, spawn the same agent type with different hypothesis prompts in parallel separate workspaces, score with Quality Score when available, keep the highest-scoring approach, and record all experiments in the Experiment Ledger.
• 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

Recording

After each user correction event:

[EDIT]("session-metrics.md", append event to Events table)

At session end, if CD >= 50:

1. Include CD summary in final report
2. Trigger QA agent RCA generation
3. 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 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
• Difficulty guide: ../_shared/core/difficulty-guide.md
• Clarification protocol: ../_shared/core/clarification-protocol.md
• Context budget: ../_shared/core/context-budget.md
• Lessons learned: ../_shared/core/lessons-learned.md