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. 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 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 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. - 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` | | Compute exposed skill set | `SELECT` | intersection of domain tags and installed skills | | Select dispatch path | `SELECT` | Native vs fallback | | Write session state | `WRITE` | task board and memory files | | Spawn agents | `CALL_TOOL` | native CLI 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 - 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> <prompt-file> <session-id> --task-id <task.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 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. 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` ### 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 runtime/vendor settings from project configuration; do not depend on this skill's stale `config/cli-config.yaml` for runtime behavior. ### 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): ```json { "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**: Create `orchestrator-session-{sessionId}.md` and `task-board-{sessionId}.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 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-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**: ```bash 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 <!-- oma-docs:ignore-start --> - If `docs/CODE-REVIEW.md` exists, QA agent uses it as the review checklist <!-- oma-docs:ignore-end --> - 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)