Orchestrator – Automated Multi-Agent Coordinator

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 workflow-guide
• Quick bug fixes or minor changes

Important

This skill orchestrates CLI subagents via gemini -p "..." --approval-mode=yolo. It uses MCP Memory tools as a shared state bus. Each subagent runs as an independent process.

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 2 – Setup: Use memory write tool to create orchestrator-session.md + task-board.md PHASE 3 – Execute: Spawn agents by priority tier (never exceed MAX_PARALLEL) PHASE 4 – Monitor: Poll every POLL_INTERVAL; handle completed/failed/crashed agents PHASE 4.5 – Verify: Run oh-my-ag verify {agent-type} per completed agent PHASE 5 – Collect: Read all result-{agent}.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

Verification Gate (PHASE 4.5)

After each agent completes, run automated verification before accepting the result:

oh-my-ag verify {agent-type} --workspace {workspace}
# or with JSON output for programmatic use:
oh-my-ag verify {agent-type} --workspace {workspace} --json

• PASS (exit 0): Accept result, advance to next task
• FAIL (exit 1): Treat as failure → enter Retry Logic with verify output as error context
• This is mandatory. Never skip verification even if the agent reports success.

Retry Logic

• 1st retry: Wait 30s, re-spawn with error context (include verify output)
• 2nd retry: Wait 60s, add “Try a different approach”
• Final failure: Report to user, ask whether to continue or abort

Clarification Debt (CD) Monitoring

Track user corrections during session execution. See ../_shared/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

Serena Memory (CLI Mode)

See ../_shared/memory-protocol.md.

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 routing: ../_shared/skill-routing.md
• Verification: scripts/verify.sh <agent-type>
• Session metrics: ../_shared/session-metrics.md
• API contracts: ../_shared/api-contracts/
• Context loading: ../_shared/context-loading.md
• Difficulty guide: ../_shared/difficulty-guide.md
• Reasoning templates: ../_shared/reasoning-templates.md
• Clarification protocol: ../_shared/clarification-protocol.md
• Context budget: ../_shared/context-budget.md
• Lessons learned: ../_shared/lessons-learned.md