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
• resources/examples.md
• 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

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

Resource scope

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 6. Always use Serena MCP tools as the primary method for code exploration and modification 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

Spawn agents via CLI:

1. Use oma agent:spawn for each task 2. CLI selection follows model_preset (and per-agent overrides) in oma-config.yaml 3. 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}.md files
• 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

• Workflow examples: resources/examples.md

Workflow Guide - Examples

Example 1: Full-Stack TODO App

Input: "Build a TODO app with JWT authentication"

Workflow:

Step 1: PM Agent plans the project
  -> 5 tasks: auth API, CRUD API, login UI, todo UI, QA review

Step 2: Spawn Priority 1 agents via CLI
  # Run in parallel using background processes
  oma agent:spawn backend "JWT authentication API + TODO CRUD" session-id -w ./backend &
  oma agent:spawn frontend "Login/Register UI" session-id -w ./frontend &
  wait

Step 3: Monitor progress
  - Use memory read tool to poll progress-{agent}.md files
  - Verify API contracts align between backend/frontend

Step 4: Spawn Priority 2 after P1 completes
  oma agent:spawn frontend "TODO List UI" session-id -w ./frontend

Step 5: Spawn Priority 3
  oma agent:spawn qa "Security + Performance review" session-id -w .

Step 6: Address QA findings
  - Re-spawn agents for CRITICAL/HIGH issues
  - Verify fixes

Example 2: Adding Feature to Existing App

Input: "Add a comment feature to the blog"

Workflow:

Step 1: PM Agent analyzes existing codebase and plans
  -> 2 tasks: Comments API, Comment Section UI

Step 2: Spawn Backend Agent first (API-first)
  oma agent:spawn backend "Comments API with nested replies, pagination" session-id -w ./backend

Step 3: After backend completes, spawn Frontend Agent
  oma agent:spawn frontend "Comment section UI using the new API endpoints" session-id -w ./frontend
  (Sequential because frontend depends on API contracts)

Step 4: QA review
  oma agent:spawn qa "Security: XSS in comments, rate limiting; Performance: Pagination, N+1 queries" session-id -w .

Example 3: When to Use Orchestrator Instead

User: "Run everything automatically"

Response:

"You want fully automated execution. Let me switch to the
orchestrator skill instead, which will:
1. Spawn CLI subagents automatically
2. Coordinate via Serena Memory
3. Monitor progress and handle retries
4. Return unified results

Use oma-coordination when you want step-by-step control.
Use oma-orchestrator when you want hands-off automation."