oma-coordination

---
name: oma-coordination
description: Coordinate assigned specialist tasks and handoffs manually. Use
  when supervising a multi-agent project step by step.
---

# Multi-Agent Workflow Guide

## Scheduling

### Goal
Guide manual multi-agent coordination for complex work that spans PM, frontend, backend, mobile, and QA responsibilities.

### Intent signature
- User wants step-by-step coordination, manual agent spawning, or multi-domain work planning without full automation.
- Task spans multiple specialist agents and requires contract alignment.

### When to use

- Complex feature spanning multiple domains (full-stack, mobile)
- Coordination needed between frontend, backend, mobile, and QA
- User wants step-by-step guidance for multi-agent coordination

### When NOT to use

- Simple single-domain task -> use the specific agent directly
- User wants automated execution -> use orchestrator
- Quick bug fixes or minor changes

### Expected inputs
- Complex feature or project goal
- Required domains and priority tiers
- Workspace/session constraints and API/data contract needs

### Expected outputs
- Manual coordination sequence
- PM task decomposition, agent spawn order, monitoring guidance, and QA review step
- API/data contract alignment checkpoints

### Dependencies
- PM, frontend, backend, mobile, QA, and orchestrator skills
- CLI `oma agent spawn` and progress/result memory conventions

### Control-flow features
- Branches by task complexity, priority tiers, dependency ordering, and whether automation is desired
- Spawns independent same-priority tasks in parallel when appropriate
- Monitors progress files and contract alignment

## Structural Flow

### Entry
1. Confirm the task is complex enough for multi-agent coordination.
2. Start with PM task decomposition.
3. Identify priority tiers and shared contracts.

### Scenes
1. **PREPARE**: Define session, domains, and task decomposition needs.
2. **ACT**: Spawn agents by priority with separate workspaces.
3. **VERIFY**: Monitor progress and API/data contract alignment.
4. **FINALIZE**: Run QA review and coordinate remediation.

### Transitions
- If task is simple, route to one specialist.
- If user wants automated execution, use orchestrator.
- If QA finds CRITICAL issues, re-spawn responsible agents.

### Failure and recovery
- If contracts diverge, pause downstream frontend/mobile work until backend/API contract is reconciled.
- If agent workspaces conflict, split ownership boundaries.
- If progress stalls, inspect progress files and reissue focused instructions.

### Exit
- Success: specialist outputs are coordinated and QA-reviewed.
- Partial success: blocked agents, contract conflicts, or QA failures are explicit.

## Logical Operations

### Actions
| Action | SSL primitive | Evidence |
|--------|---------------|----------|
| Read request and domains | `READ` | User prompt and project context |
| Select agent plan | `SELECT` | PM decomposition and priority tiers |
| Spawn agents | `CALL_TOOL` | `oma agent spawn` |
| Monitor progress | `READ` | `progress-{agent}[-{sessionId}].md` |
| Validate contracts | `VALIDATE` | API/data model alignment |
| Notify coordination status | `NOTIFY` | Final coordination summary |

### Tools and instruments
- `oma agent spawn`, PM/frontend/backend/mobile/QA agents
- Memory/progress/result files
- Configured code intelligence, with native fallback per `../_shared/core/code-intelligence.md`

### Canonical command path
```bash
oma agent spawn pm <pm-prompt-file> <session-id> --task-id <plan.pm_task.id> -w ./pm
oma agent spawn backend <backend-prompt-file> <session-id> --task-id <plan.backend_task.id> -w ./backend &
oma agent spawn frontend <frontend-prompt-file> <session-id> --task-id <plan.frontend_task.id> -w ./frontend &
wait
```

When native runtime dispatch is available (per-agent target vendor equals the current runtime vendor), prefer the runtime's native subagent path and use `oma agent spawn` as the cross-vendor fallback — same resolution rule as oma-orchestration.

Useful `agent spawn` options: `--vendor <vendor>` (CLI vendor override), `--isolation worktree` (git worktree per spawn, prevents file conflicts), `--read-only` (non-destructive tools only, e.g. for review/QA passes).

### Resource scope
| Scope | Resource target |
|-------|-----------------|
| `LOCAL_FS` | Progress/result files and workspaces |
| `PROCESS` | Agent spawn commands |
| `MEMORY` | Session state and task board |
| `CODEBASE` | Shared contracts and implementation areas |

### Preconditions
- Task requires multiple domains.
- PM decomposition can identify independent priority tiers.

### Effects and side effects
- Spawns or guides multiple agents.
- Coordinates workspace ownership and QA feedback.

### Guardrails

1. Always start with PM Agent for task decomposition
2. Spawn independent tasks in parallel (same priority tier)
3. Define API contracts before frontend/mobile tasks
4. QA review is always the final step
5. Assign separate workspaces to avoid file conflicts (or use `--isolation worktree` for a git worktree per spawn)
6. Follow `../_shared/core/code-intelligence.md`: discover configured tools, do not auto-install or track, and use native scoped search when unavailable or timed out
7. Never skip steps in the workflow; follow each step sequentially without omission

### Workflow

#### Step 1: Plan with PM Agent

PM Agent analyzes requirements, selects tech stack, creates task breakdown with priorities.

#### Step 2: Spawn Agents by Priority

Resolve the dispatch path per agent, then spawn:

1. Resolve the per-agent target vendor from oma-config.yaml (`agents:` override, else `model_preset`)
2. If the target vendor equals the current runtime vendor and a native subagent path exists, use native dispatch
3. Otherwise use `oma agent spawn` for that agent
4. Spawn all same-priority tasks in parallel using background processes

```bash
# Example: spawn backend and frontend in parallel
oma agent spawn backend backend-prompt.md session-id --task-id plan.backend_task.id -w ./backend &
oma agent spawn frontend frontend-prompt.md session-id --task-id plan.frontend_task.id -w ./frontend &
wait
```

#### Step 3: Monitor & Coordinate

- Use memory read tool to poll `progress-{agent}[-{sessionId}].md` files (spawned agents write the session-suffixed form)
- Verify API contracts align between agents
- Ensure shared data models are consistent

#### Step 4: QA Review

Spawn QA Agent last to review all deliverables. Address CRITICAL issues by re-spawning agents.

### Automated Alternative

For fully automated execution without manual spawning, use the **orchestrator** skill instead.

## References