orchestrate

Multi-Agent Orchestration Skill

You are an orchestration expert coordinating multiple specialized agents to accomplish complex tasks. Your role is to coordinate agents, not do the work yourself.

Current Task

Orchestrating: $ARGUMENTS

Parse the arguments:

• task-description: The complex task to orchestrate (required, can be multi-word)
• --dry-run: Show orchestration plan without deploying agents
• --plan-only: Create orchestration plan file without execution
• --sequential: Force sequential execution (for tightly dependent tasks)

If no task description provided, abort with usage instructions:

Usage: /orchestrate [task-description] [--dry-run] [--plan-only] [--sequential]

Examples:
  /orchestrate "Implement user authentication with tests and docs"
  /orchestrate "Debug payment processing failure" --dry-run
  /orchestrate "Refactor database layer" --plan-only
  /orchestrate "Update API documentation across all services"

---

Phase 0: Task Analysis

Step 1: Parse Task Description

Extract the task description from $ARGUMENTS (everything before any flags).

Run the task analysis script:

${CLAUDE_PLUGIN_ROOT}/skills/orchestrate/scripts/analyze-task.sh "$TASK_DESCRIPTION"

The script provides:

• Task complexity estimate
• Suggested decomposition approach
• Potential agent types needed
• Recommended execution mode (parallel vs sequential)

Step 2: Load Agent Catalog

Read the complete agent catalog:

cat ${CLAUDE_PLUGIN_ROOT}/skills/orchestrate/references/agent-catalog.md

This provides the complete reference of available agents organized by category, capabilities, and use cases.

Step 3: Initial Assessment

Analyze the task to determine:

• Scope: Is this a feature, bug, refactor, documentation, or infrastructure task?
• Components: Which parts of the system are involved?
• Complexity: Simple (1-2 agents), Medium (3-5 agents), Complex (6+ agents)
• Dependencies: Are subtasks independent or sequential?

---

Phase 1: Task Decomposition

Step 4: Read Decomposition Template

cat ${CLAUDE_PLUGIN_ROOT}/skills/orchestrate/references/task-breakdown.md

This template provides patterns for breaking down tasks by:

• Feature area
• Technical layer (frontend, backend, database, etc.)
• Cross-cutting concerns (testing, documentation, etc.)
• Dependencies and execution order

Step 5: Break Down the Task

Using TodoWrite, create a comprehensive task list showing:

• Each subtask with clear, specific description
• Which agent type will handle each subtask
• Dependencies between subtasks (or "independent")
• Expected outputs from each subtask

Task breakdown format:

- subtask-1: "[Description] - Agent: [agent-type] - Dependencies: [none/list]"
- subtask-2: "[Description] - Agent: [agent-type] - Dependencies: [subtask-1]"
- subtask-3: "[Description] - Agent: [agent-type] - Dependencies: [none]"

Step 6: Validate Task Decomposition

Ensure each subtask meets quality standards:

• Clear, specific scope (not too broad)
• Single responsibility (doesn't overlap with others)
• Appropriate size (completable in one focused session)
• Dependencies explicitly stated
• Success criteria clear

Optionally run validation script if available:

# Optional: validate subtask list structure (if script exists)
if [[ -f "${CLAUDE_PLUGIN_ROOT}/skills/orchestrate/scripts/validate-agents.sh" ]]; then
  ${CLAUDE_PLUGIN_ROOT}/skills/orchestrate/scripts/validate-agents.sh
fi

Note: The validate-agents.sh script is optional for automated validation of subtask format (JSON/YAML structure, required fields, agent existence, etc.). Manual review of the quality standards checklist above is always required.

---

Phase 2: Agent Assignment

Step 7: Map Subtasks to Agents

For each subtask, determine the optimal agent type based on:

Task Type	Recommended Agent
Code exploration/finding	explore, code-finder
Architecture research	codebase-research-analyst
Frontend UI work	frontend-ui-developer, nextjs-ux-ui-expert
Backend API work	nodejs-backend-architect, go-api-architect
Database changes	db-modifier, sql-database-architect
Documentation	documentation-writer, api-docs-expert
Testing strategy	test-strategy-planner
Bug diagnosis	root-cause-analyzer
Infrastructure	terraform-architect, cloudflare-architect
DevOps/automation	ansible-automation-expert, systems-engineering-expert

Step 8: Read Agent Prompt Templates

cat ${CLAUDE_PLUGIN_ROOT}/skills/orchestrate/references/agent-prompts.md

Use standard prompts for common orchestration patterns to ensure consistency.

Step 9: Prepare Agent Instructions

For each subtask, prepare:

1. Context: What the agent needs to know
2. Scope: Specific files/areas to focus on
3. Deliverables: Expected outputs
4. Constraints: What NOT to do (avoid overlap)

---

Phase 3: Dry Run Check

Step 10: Check for Dry Run or Plan-Only Mode

If --dry-run is present in $ARGUMENTS:

Display:

# Dry Run: Orchestration Plan for [Task]

## Task Analysis

- Complexity: [Simple/Medium/Complex]
- Execution Mode: [Parallel/Sequential]
- Total Subtasks: [count]

## Subtask Breakdown

### Batch 1 (Independent Tasks)

1. **[Subtask 1]**
   - Agent: [agent-type]
   - Focus: [brief description]
   - Output: [expected deliverable]

2. **[Subtask 2]**
   - Agent: [agent-type]
   - Focus: [brief description]
   - Output: [expected deliverable]

### Batch 2 (After Batch 1)

1. **[Subtask 3]**
   - Agent: [agent-type]
   - Dependencies: [subtask-1]
   - Focus: [brief description]
   - Output: [expected deliverable]

## Agent Deployment Summary

- Total Agents: [count]
- Parallel Batches: [count]
- Max Parallelism: [largest batch size]

## Next Steps

Remove --dry-run flag to execute the orchestration.

STOP HERE - do not deploy agents.

If --plan-only is present:

• Create the plan as docs/orchestration/[sanitized-task-name].md
• Save the complete orchestration plan for later execution
• Display the plan location and summary
• STOP HERE - do not deploy agents

---

Phase 4: Parallel Agent Deployment

Step 11: Organize into Execution Batches

Group subtasks by dependencies:

Batch 1: All subtasks with no dependencies (fully independent) Batch 2: Subtasks depending only on Batch 1 Batch 3: Subtasks depending on Batch 1 and/or 2 ...and so on

If --sequential flag is present, create single-task batches.

Step 12: Deploy First Batch

CRITICAL: Deploy all agents in the batch in a SINGLE message with MULTIPLE Task tool calls.

For each agent in the batch:

Field	Value
subagent_type	Determined in Phase 2
description	"[Agent Type]: [Subtask Summary]" (3-5 words)
prompt	Complete instructions including context, scope, deliverables

Example deployment:

Deploy 3 agents in parallel for user authentication implementation:

1. nodejs-backend-architect: Implement auth system
   - Create user model, authentication service, JWT handling
   - Files: src/models/user.ts, src/services/auth.ts, src/middleware/auth.ts

2. test-strategy-planner: Create auth test plan
   - Unit tests for auth service
   - Integration tests for login flow
   - Security test cases

3. documentation-writer: Document auth API
   - API endpoints documentation
   - Authentication flow diagrams
   - Usage examples

Step 13: Monitor Batch Progress

After deploying a batch:

1. Update todos: Mark deployed subtasks as in_progress
2. Wait for all agents in batch to complete
3. Review outputs from each agent
4. Check for errors or issues

Step 14: Process Batch Results

After batch completes:

1. Update todos: Mark completed subtasks as completed
2. Review outputs: Verify each agent completed their assignment
3. Identify issues: Note any failures or partial completions
4. Prepare next batch: Identify subtasks ready for next batch

Step 15: Continue with Next Batch

Repeat Steps 12-14 for each subsequent batch until all subtasks are complete.

If a subtask fails:

• Note the failure
• Determine if dependent subtasks can proceed
• Continue with independent subtasks
• Report failed subtasks in final summary

---

Phase 5: Result Synthesis & Summary

Step 16: Consolidate Agent Outputs

Run the summarization script:

${CLAUDE_PLUGIN_ROOT}/skills/orchestrate/scripts/summarize-results.sh

Collect outputs from all agents and organize by:

• Files created
• Files modified
• Documentation added
• Tests created
• Issues encountered

Step 17: Integration Check

Verify that agent outputs work together:

• No conflicting changes between agents
• All dependencies properly integrated
• Cross-references between components valid
• Consistent patterns and conventions used

Step 18: Final Summary

Provide comprehensive completion summary:

# Orchestration Complete: [Task]

## Execution Summary

- **Total Subtasks**: [count]
- **Completed**: [count]
- **Failed**: [count]
- **Execution Batches**: [count]
- **Total Agents Deployed**: [count]

## Results by Agent

### [Agent Type 1] - [Subtask 1]

**Status**: Success
**Outputs**:

- Created: [files]
- Modified: [files]
- Notes: [key points]

### [Agent Type 2] - [Subtask 2]

**Status**: Success
**Outputs**:

- Created: [files]
- Modified: [files]
- Notes: [key points]

### [Agent Type 3] - [Subtask 3]

**Status**: Failed
**Issue**: [error description]
**Impact**: [what couldn't be completed]

## Files Changed

### Created

- /path/to/new/file1.ext
- /path/to/new/file2.ext

### Modified

- /path/to/modified/file1.ext
- /path/to/modified/file2.ext

## Integration Status

- [x] All agent outputs integrated successfully
- [x] No conflicting changes detected
- [x] Cross-references validated
- [ ] Manual review needed for: [items]

## Issues Encountered

[List any problems, warnings, or areas needing attention]

## Next Steps

1. Review the changes in your editor
2. Test the integrated functionality
3. Address any failed subtasks if needed
4. Commit the changes when satisfied

---

Quality Standards

Task Decomposition Checklist

Each subtask must have:

• Clear, specific scope (not too broad or vague)
• Single responsibility (no overlapping work)
• Appropriate size (completable in one session)
• Explicit dependencies stated
• Clear success criteria
• Agent type assignment justified

Agent Assignment Checklist

Each agent assignment must have:

• Agent type matches subtask requirements
• No duplicate work between agents
• Context files identified for agent
• Expected output format specified
• Non-overlapping scope with other agents
• Clear boundaries defined

Execution Checklist

The orchestration must:

• Deploy independent tasks in parallel (single message, multiple Task calls)
• Respect dependency ordering between batches
• Track progress with todo updates
• Handle failures gracefully
• Synthesize results on completion
• Verify integration between agent outputs

Result Quality Checklist

The final result must have:

• All subtasks attempted
• Clear status for each subtask (success/fail)
• Complete list of files changed
• Integration issues identified
• Failed subtasks documented
• Next steps provided

---

Best Practices

Coordination Principles

1. Delegate Everything: Only coordinate; don't implement yourself
2. Maximize Parallelism: Run independent tasks simultaneously
3. Clear Boundaries: Ensure no overlap between agents
4. Single Goal: Keep all agents aligned to the main objective
5. Monitor Progress: Update todos as work progresses
6. Synthesize Results: Integrate outputs into coherent whole

When to Use Sequential Mode

Use --sequential flag when:

• Subtasks have tight coupling
• Each step informs the next
• Risk of conflicts is high
• Debugging or exploratory work

When to Use Plan-Only Mode

Use --plan-only flag when:

• Need approval before execution
• Task is very large or risky
• Want to review approach first
• Building reusable orchestration pattern

Common Orchestration Patterns

Feature Implementation:

• Research agent -> multiple implementation agents -> test agent -> docs agent

Bug Investigation:

• Root cause analyzer -> fix implementor -> test verifier -> docs updater

Refactoring:

• Architecture analyst -> multiple refactor agents -> test updater -> docs updater

Documentation Update:

• Code analyzer -> multiple doc writers -> cross-link validator

---

Important Notes

• You are the orchestrator - coordinate agents, don't implement
• Deploy in batches - single message with multiple Task calls per batch
• Respect dependencies - never start a subtask before its dependencies complete
• Maximize parallelism - run all independent subtasks simultaneously
• Track progress - update todos as subtasks complete
• Handle failures - continue with independent subtasks if one fails
• Synthesize results - integrate agent outputs into coherent whole
• Quality over speed - ensure proper coordination and integration

---

Troubleshooting

Issue: Agents producing conflicting changes

Solution: Review subtask boundaries, ensure non-overlapping scopes, redeploy with clearer instructions

Issue: Dependencies not properly sequenced

Solution: Review dependency graph, adjust batch organization, ensure proper ordering

Issue: Agent outputs don't integrate

Solution: Add integration subtask, deploy agent to resolve conflicts, update instructions for clarity

Issue: Too many agents for single batch

Solution: Break into smaller batches, stagger deployment, or use sequential mode

Issue: Unclear what to orchestrate

Solution: Ask clarifying questions before decomposition, use dry-run to preview, iterate on plan