Oma Coordination

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

• Confirm the task is complex enough for multi-agent coordination.
• Start with PM task decomposition.
• Identify priority tiers and shared contracts.

Scenes

• PREPARE: Define session, domains, and task decomposition needs.
• ACT: Spawn agents by priority with separate workspaces.
• VERIFY: Monitor progress and API/data contract alignment.
• 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
• Serena MCP for exploration and modification when used by specialists

Canonical command path

oma agent:spawn pm "<planning task>" <session-id> -w ./pm
oma agent:spawn backend "<backend task>" <session-id> -w ./backend &
oma agent:spawn frontend "<frontend task>" <session-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-orchestrator.

Useful agent:spawn options: -m/--model <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

• Always start with PM Agent for task decomposition
• Spawn independent tasks in parallel (same priority tier)
• Define API contracts before frontend/mobile tasks
• QA review is always the final step
• Assign separate workspaces to avoid file conflicts (or use --isolation worktree for a git worktree per spawn)
• Always use Serena MCP tools as the primary method for code exploration and modification
• 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:

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

# Example: spawn backend and frontend in parallel
oma agent:spawn backend "task description" session-id -w ./backend &
oma agent:spawn frontend "task description" session-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