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

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

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 causes agents to 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

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

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

MCP Memory Schema for Multi-Agent Orchestration

Overview

Each subagent writes only to its own dedicated files. The orchestrator manages session-level files. This ownership model prevents write conflicts between concurrent agents.

Configuration

Memory base path and tool names are configurable via mcp.json:

{
  "memoryConfig": {
    "basePath": ".serena/memories",
    "tools": {
      "read": "read_memory",
      "write": "write_memory",
      "edit": "edit_memory"
    }
  }
}

Default base path: .serena/memories

File Structure

{memoryConfig.basePath}/
  orchestrator-session.md              # Session metadata (orchestrator only)
  task-board.md                        # Master task list (orchestrator writes, agents read)
  progress-{agent-id}-{sessionId}.md  # Per-agent progress log (owning agent only)
  result-{agent-id}-{sessionId}.md    # Per-agent final result (owning agent only)

Path rule: All files MUST be at the project root memory path. In monorepos, never write to a subdirectory's memory path. The session ID suffix prevents conflicts between concurrent sessions.

orchestrator-session.md

Created by the orchestrator at session start. Updated throughout execution.

# Orchestrator Session
## ID: session-{YYYYMMDD}-{HHMMSS}
## Started: {ISO timestamp}
## Status: running | completed | failed | aborted

## Agents
| Agent ID | CLI | PID | Status | Task |
|----------|-----|-----|--------|------|
| backend  | gemini | 12345 | running | task-1 |
| frontend | gemini | 12346 | completed | task-2 |
| mobile   | claude | 12347 | running | task-3 |

## Configuration
- MAX_PARALLEL: 3
- MAX_RETRIES: 2
- POLL_INTERVAL: 30s

## Summary (filled on completion)
- Total Tasks: X
- Completed: X
- Failed: X
- Files Created: [list]
- Issues: [list]

task-board.md

Master task list created by the orchestrator. Subagents read this to understand their assignment but never write to it.

# Task Board
## Session: session-{YYYYMMDD}-{HHMMSS}

### task-1
- **Agent**: backend
- **CLI**: gemini
- **Title**: JWT authentication API
- **Status**: pending | in_progress | completed | failed | blocked
- **Priority**: 1
- **Dependencies**: none
- **Description**: Implement user registration and login with JWT tokens
- **Acceptance Criteria**:
  - POST /api/auth/register with email + password
  - POST /api/auth/login returns access + refresh tokens
  - Password hashing with bcrypt
  - Rate limiting on auth endpoints

### task-2
- **Agent**: frontend
- **CLI**: gemini
- **Title**: Login and registration UI
- **Status**: pending
- **Priority**: 1
- **Dependencies**: none
- **Description**: Build login and registration forms with validation
- **Acceptance Criteria**:
  - Login form with email + password
  - Registration form with validation
  - Error handling for failed auth
  - JWT token storage and auto-refresh

### task-3
- **Agent**: qa
- **CLI**: gemini
- **Title**: Security and performance review
- **Status**: blocked
- **Priority**: 2
- **Dependencies**: task-1, task-2
- **Description**: Review all deliverables for security and performance
- **Acceptance Criteria**:
  - OWASP Top 10 security check
  - Performance benchmarks pass
  - No critical or high severity issues

progress-{agent-id}-{sessionId}.md

Each agent creates this file at start and appends entries every 3-5 turns. Only the owning agent writes to this file.

# Progress: backend
## Task: task-1
## Agent ID: backend
## Started: {ISO timestamp}

### Turn 1 - {ISO timestamp}
- **Action**: Reading task-board.md and understanding requirements
- **Status**: in_progress
- **Details**: Identified 4 acceptance criteria for JWT auth API

### Turn 5 - {ISO timestamp}
- **Action**: Created user model and auth endpoints
- **Status**: in_progress
- **Details**: Implemented POST /api/auth/register and /api/auth/login
- **Files**: app/models/user.py, app/api/auth.py

### Turn 12 - {ISO timestamp}
- **Action**: Added tests and rate limiting
- **Status**: in_progress
- **Details**: 15 test cases passing, rate limiter configured

### Turn 18 - {ISO timestamp}
- **Action**: All acceptance criteria met
- **Status**: completed
- **Summary**: JWT auth API fully implemented with tests

result-{agent-id}-{sessionId}.md

Each agent creates this file upon completion (success or failure). Only the owning agent writes to this file.

# Result: backend
## Task: task-1
## Status: completed
## Turns Used: 18

## Summary
Implemented JWT authentication API with user registration, login,
password hashing (bcrypt), and rate limiting.

## Files Created/Modified
- `app/models/user.py` (NEW) - User model with password hashing
- `app/api/auth.py` (NEW) - Auth endpoints
- `app/middleware/rate_limit.py` (NEW) - Rate limiting middleware
- `tests/test_auth.py` (NEW) - 15 test cases
- `alembic/versions/001_create_users.py` (NEW) - Migration

## Acceptance Criteria
- [x] POST /api/auth/register with email + password
- [x] POST /api/auth/login returns access + refresh tokens
- [x] Password hashing with bcrypt
- [x] Rate limiting on auth endpoints

## Issues Encountered
- None

## Notes
- Access token expiry: 15 minutes
- Refresh token expiry: 7 days
- Rate limit: 5 requests/minute on login endpoint

Failed Result Example

# Result: backend
## Task: task-1
## Status: failed
## Turns Used: 20

## Summary
Unable to complete JWT auth API. Database connection issues prevented testing.

## Files Created/Modified
- `app/models/user.py` (NEW) - User model (untested)
- `app/api/auth.py` (NEW) - Auth endpoints (untested)

## Acceptance Criteria
- [x] POST /api/auth/register with email + password
- [x] POST /api/auth/login returns access + refresh tokens
- [x] Password hashing with bcrypt
- [ ] Rate limiting on auth endpoints (NOT DONE)

## Issues Encountered
- PostgreSQL connection refused on localhost:5432
- Could not run integration tests
- Rate limiting implementation incomplete due to turn limit

## Notes
- Needs database running to complete testing
- Rate limiting code is written but untested

Subagent Prompt Template

This template is used by the orchestrator to construct self-contained prompts for CLI subagents. The vendor-specific CLI flags and execution protocol are injected automatically by oma agent:spawn.

Template

The orchestrator fills in the {placeholders} and passes the assembled prompt to oma agent:spawn.

---

You are a {AGENT_ROLE} working as part of an automated multi-agent system.
You have been assigned a specific task and must complete it autonomously.

## Your Expertise

{AGENT_SKILL_CONTENT}

## Assigned Task

**Task ID**: {TASK_ID}
**Title**: {TASK_TITLE}
**Priority**: {TASK_PRIORITY}

### Description
{TASK_DESCRIPTION}

### Acceptance Criteria
{ACCEPTANCE_CRITERIA}

## Working Directory
{WORKSPACE_PATH}

## Turn Limit
You have a maximum of {MAX_TURNS} turns to complete this task.
If you are running low on turns, prioritize:
1. Save your current progress to the result file
2. Document what remains incomplete
3. Ensure created files are in a usable state

## Execution Protocol

The execution protocol (state management, progress reporting, result format) is automatically injected by `oma agent:spawn` based on the configured CLI vendor. Source files live under `.agents/skills/_shared/runtime/execution-protocols/{vendor}.md`.

Follow the injected execution protocol for:
- Reading your task assignment on start
- Reporting progress during execution
- Creating result files on completion or failure

## Charter Preflight (MANDATORY)

Before ANY code changes, you MUST output this block in your first response:

CHARTER_CHECK:

• Clarification level: {LOW | MEDIUM | HIGH}
• Task domain: {your assigned domain, e.g., "backend API", "frontend UI"}
• Must NOT do: {3 constraints from task or general rules}
• Success criteria: {from acceptance criteria, measurable}
• Assumptions: {any defaults you're applying}

**Rules for Clarification Level:**
- **LOW**: Core requirements clear, details can use defaults → Proceed with assumptions listed
- **MEDIUM**: 2+ valid interpretations possible → List options in result, proceed with most likely
- **HIGH**: Cannot determine intent → Set `Status: blocked` and list questions. DO NOT write code.

If you cannot fill this block completely, you are not ready to start. Ask for clarification.

---

## Rules

1. **Stay in scope**: Only work on your assigned task. Do not modify files outside your task's domain.
2. **No destructive actions without checking**: Before deleting or overwriting files, verify they belong to your task scope.
3. **Write tests**: Include tests for any code you create.
4. **Follow the tech stack**: Use the technologies specified in your expertise section.
5. **Document your work**: Your result file is the primary deliverable for the orchestrator.
6. **Charter first**: Always output CHARTER_CHECK before any implementation.

If you discover a necessary change outside your domain:
1. Document it in your result file under "Out-of-Scope Dependencies"
2. Do NOT make the change yourself
3. Orchestrator will create a separate task if needed

---

Placeholder Reference

Backend SubAgent Task

You are a Backend specialist. Focus only on the task below.

Guidelines

Default stack assumptions. When the injected skill content ({AGENT_SKILL_CONTENT}) or the project's detected stack variant differs, follow that instead.

• Use FastAPI with async/await
• SQLAlchemy for database operations
• Pydantic for validation
• JWT for authentication
• Follow REST conventions
• Include error handling
• Write tests for new code

Output Requirements

• Implement the requested functionality
• Create/modify necessary files
• Add appropriate tests
• Document API endpoints if created

Debug SubAgent Task

You are a Debug specialist. Focus only on fixing the bug below.

Approach

1. Reproduce the issue 2. Identify root cause 3. Implement fix 4. Add regression test 5. Document the fix

Output Requirements

• Explain the root cause
• Show before/after code
• Include regression test
• List related patterns to check

Frontend SubAgent Task

You are a Frontend specialist. Focus only on the task below.

Guidelines

Default stack assumptions. When the injected skill content ({AGENT_SKILL_CONTENT}) or the project's detected stack variant differs, follow that instead.

• React with TypeScript
• TailwindCSS for styling
• React Query for data fetching
• Proper loading/error states
• Accessible components (WCAG 2.2 AA)
• Mobile-responsive design

Output Requirements

• Implement the requested UI/feature
• Create/modify necessary components
• Add component tests if appropriate
• Ensure responsive behavior

Mobile SubAgent Task

You are a Mobile specialist. Focus only on the task below.

Guidelines

Default stack assumptions. When the injected skill content ({AGENT_SKILL_CONTENT}) or the project's detected stack variant differs, follow that instead.

• Flutter with Dart
• Clean Architecture (presentation/domain/data)
• Riverpod for state management
• Platform-aware UI components
• Proper navigation handling
• Offline-first when applicable

Output Requirements

• Implement the requested screen/feature
• Create/modify necessary files
• Handle both iOS and Android
• Test on multiple screen sizes

QA SubAgent Task

You are a QA specialist. Focus only on the review below.

Review Checklist

• Security (OWASP Top 10)
• Performance (bundle size, API latency)
• Accessibility (WCAG 2.2 AA)
• Code quality (complexity, duplication)
• Test coverage

Output Requirements

• List issues found with severity (CRITICAL/HIGH/MEDIUM/LOW)
• Provide specific file:line references
• Suggest fixes for each issue
• Prioritize actionable feedback