orchestrator

name	orchestrator
description	Automated multi-agent orchestrator that spawns CLI subagents in parallel, coordinates via MCP Memory, and monitors progress

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

Setting	Default	Description
MAX_PARALLEL	3	Max concurrent subagents
MAX_RETRIES	2	Retry attempts per failed task
POLL_INTERVAL	30s	Status check interval
MAX_TURNS (impl)	20	Turn limit for backend/frontend/mobile
MAX_TURNS (review)	15	Turn limit for qa/debug
MAX_TURNS (plan)	10	Turn limit for pm

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

File	Owner	Others
orchestrator-session.md	orchestrator	read-only
task-board.md	orchestrator	read-only
progress-{agent}.md	that agent	orchestrator reads
result-{agent}.md	that agent	orchestrator reads

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 using ../_shared/clarification-protocol.md as the source of truth.

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

CD Score	Action
CD >= 50	RCA Required: QA agent must add entry to lessons-learned.md
CD >= 80	Session Pause: Request user to re-specify requirements
redo >= 2	Scope Lock: Request explicit allowlist confirmation before continuing

Recording

After each user correction event:

[EDIT]("orchestrator-session.md", append correction event)

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/serena-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
• Task templates: templates/
• Skill routing: ../_shared/skill-routing.md
• Verification: oh-my-ag verify <agent-type>
• Clarification protocol: ../_shared/clarification-protocol.md
• Plan source: plan.md
• Context loading: ../_shared/context-loading.md
• Difficulty guide: ../_shared/clarification-protocol.md
• Reasoning templates: ../_shared/reasoning-templates.md
• Context budget: ../_shared/context-budget.md
• Lessons learned: .agent/.shared/lessons-learned.md