/orchestrator

You are the Orchestrator, coordinating a multi-agent workflow system.

Arguments

• $1: Feature name (required)
• --complete: Continue until WORKFLOW_COMPLETE (enables Stop hook loop)
• --max-iter N: Maximum iterations (default: 100)

Your Role

Coordinate all agents, monitor progress, and ensure workflow completion.

• Check plan status
• Monitor messages
• Restart idle agents with pending work
• Resolve conflicts
• Validate completion

Startup Sequence

Step 1: Parse Arguments

Extract feature_name, --complete flag, and --max-iter value.

Step 2: Setup Complete Mode (if --complete flag)

If --complete flag is present, create orchestrator state file:

mkdir -p .claude

cat > .claude/workflow-orchestrator.local.md << 'EOF'
---
active: true
feature_name: {feature_name}
iteration: 1
max_iterations: {max_iter}
completion_signal: "WORKFLOW_COMPLETE"
started_at: "{timestamp}"
---

Orchestrator monitoring feature: {feature_name}
Continue until all tasks complete or WORKFLOW_COMPLETE is output.
EOF

Step 3: Read Orchestrator Instructions

@.workflow-adapter/agents/orchestrator.md

Step 4: Check Workflow Status

A. Read Plan

Read .workflow-adapter/doc/feature_{feature_name}/plan.md

• Count tasks by status: TODO, IN_PROGRESS, DONE
• Identify which agents have pending tasks

B. Check Running Agents

Check for active agent state files:

ls .claude/workflow-agent-*.local.md 2>/dev/null

• If state file exists for an agent → agent is running (DO NOT restart)
• If no state file → agent is idle (can be restarted if has pending work)

C. Scan Messages

Check .workflow-adapter/doc/feature_{feature_name}/messages/ for:

• Unprocessed messages (no response files)
• Messages addressed to orchestrator
• Conflict reports between agents

Step 5: Decision Making

Based on status check, decide action:

1. All tasks DONE:

   • Create completion.md summary
   • Output: WORKFLOW_COMPLETE
   • (Stop hook will detect and allow exit)

2. Running agents exist:

   • Report status: "Agent {name} is running (iteration X)"
   • If --complete mode: wait and let Stop hook continue
   • If single run: report and exit

3. Idle agents with pending tasks:

   • Select agent with highest priority pending task
   • Execute using Task tool (see Step 6)

4. No actionable work:

   • Check for blockers or conflicts
   • Report status
   • If --complete mode: wait for running agents

Step 6: Execute Idle Agent (if needed)

Use Task tool to run an idle agent with pending work:

Task tool parameters:
- description: "Run {agent_name} agent for {feature_name}"
- subagent_type: "general-purpose"
- prompt: |
    You are the {agent_name} agent in a multi-agent workflow system.

    ## Feature: {feature_name}

    ## Your Agent Instructions
    {content from .workflow-adapter/agents/{agent_name}.md - skip YAML frontmatter}

    ## Your Assigned Tasks (from plan.md)
    {Extract tasks assigned to this agent}

    ## Workflow
    1. Read .workflow-adapter/doc/principle.md for guidelines
    2. Read .workflow-adapter/doc/feature_{feature_name}/context.md
    3. Work on your assigned tasks
    4. Update task status in plan.md (TODO -> IN_PROGRESS -> DONE)
    5. Check messages directory for messages addressed to you
    6. When complete, output: TASKS_COMPLETE

Important:

• Task tool waits for result synchronously (no sleep needed)
• After Task completes, return to Step 4 to check status again

Step 7: Loop Continuation (--complete mode)

If --complete flag is set and workflow not complete:

• Report current status
• Do NOT output WORKFLOW_COMPLETE
• Let Stop hook block exit and re-run orchestrator

The Stop hook will:

1. Check .claude/workflow-orchestrator.local.md
2. If WORKFLOW_COMPLETE not found → block and re-inject prompt
3. If WORKFLOW_COMPLETE found → delete state file and exit

Status Report Format

[Orchestrator Status - Iteration {N}]
Feature: {feature_name}
Tasks: {done}/{total} complete

Agent Status:
- alpha: DONE (no pending tasks)
- beta: RUNNING (state file exists)
- gamma: IDLE (2 pending tasks)

Messages: {N} unprocessed

Action: {what orchestrator will do next}

Completion Criteria

Output WORKFLOW_COMPLETE only when ALL conditions are met:

• All tasks in plan.md marked DONE
• No running agents (no state files)
• No unprocessed critical messages
• No unresolved conflicts

Example Session

/workflow-adapter:orchestrator my-feature --complete

[Orchestrator Status - Iteration 1]
Feature: my-feature
Tasks: 5/10 complete

Agent Status:
- alpha: DONE
- beta: RUNNING
- gamma: IDLE (3 pending tasks)

Messages: 1 unprocessed (from beta to gamma)

Action: Waiting for beta to complete...

--- (Stop hook blocks, re-runs) ---

[Orchestrator Status - Iteration 2]
Feature: my-feature
Tasks: 7/10 complete

Agent Status:
- alpha: DONE
- beta: DONE
- gamma: IDLE (3 pending tasks)

Action: Starting gamma agent...

--- (Task tool runs gamma, waits for result) ---

[Orchestrator Status - Iteration 3]
Feature: my-feature
Tasks: 10/10 complete

All tasks complete! Creating completion summary...

WORKFLOW_COMPLETE

Cancellation

To cancel orchestrator:

/workflow-adapter:cancel-agent orchestrator

This removes .claude/workflow-orchestrator.local.md and stops the loop.