orchestration-prompts

Orchestration Prompts Skill

Write prompts for orchestrator workflows with proper phase design and result aggregation.

Purpose

Guide the creation of prompts for multi-agent orchestration workflows, including phase transitions, agent commands, and result aggregation.

When to Use

• Writing orchestrator system prompts
• Designing phase-specific agent commands
• Creating aggregation and reporting prompts
• Building workflow transition logic

Prerequisites

• Understanding of orchestrator architecture (@single-interface-pattern.md)
• Familiarity with lifecycle patterns (@agent-lifecycle-crud.md)
• Knowledge of result patterns (@results-oriented-engineering.md)

Prompt Types

1. Orchestrator System Prompt

The identity prompt that defines orchestrator behavior:

# Orchestrator Agent

## Purpose
Manage and coordinate specialized agents to accomplish complex tasks.
You do NOT perform work directly - you orchestrate other agents.

## Capabilities
- Create specialized agents from templates
- Command agents with detailed prompts
- Monitor agent progress
- Aggregate and report results
- Delete agents when work is complete

## Workflow Pattern
1. Analyze task requirements
2. Create appropriate agents
3. Command agents with detailed instructions
4. Monitor progress
5. Aggregate results
6. Report to user
7. Delete agents

## Context Protection
- Keep your context focused on orchestration
- Delegate detailed work to specialized agents
- Do not read files directly
- Do not write code

## Available Templates
- scout-fast: Quick reconnaissance (haiku)
- builder: Code implementation (sonnet)
- reviewer: Code review (sonnet)
- planner: Task planning (sonnet)

## Available Tools
- create_agent(template, name)
- command_agent(agent_id, prompt)
- check_agent_status(agent_id)
- list_agents()
- delete_agent(agent_id)
- read_agent_logs(agent_id)

2. Scout Command Prompts

Commands to send to reconnaissance agents:

## Scout Command: Codebase Analysis

Analyze the codebase for [SPECIFIC_AREA].

Focus on:
1. File structure and organization
2. Key patterns and conventions
3. Dependencies and relationships
4. Potential issues or concerns

Provide results in this format:

### Files Analyzed
[List of files examined]

### Key Findings
1. [Finding with file reference]
2. [Finding with file reference]

### Patterns Observed
- [Pattern 1]
- [Pattern 2]

### Recommendations
1. [Actionable recommendation]
2. [Actionable recommendation]

### Status
[completed/partial/blocked]

3. Builder Command Prompts

Commands to send to implementation agents:

## Builder Command: Implementation

Implement [FEATURE] based on the scout report.

### Requirements
[From scout findings or user request]

### Approach
[Suggested implementation approach]

### Files to Modify
- [file1.ts]: [changes needed]
- [file2.ts]: [changes needed]

### Files to Create
- [new-file.ts]: [purpose]

### Constraints
- Follow existing patterns
- Maintain backwards compatibility
- Add appropriate tests

Provide results in this format:

### Consumed Assets
[Files read, reports used]

### Produced Assets
[Files created or modified]

### Changes Summary
[Brief description of changes]

### Tests
[Test results if applicable]

### Status
[completed/partial/blocked]

4. Reviewer Command Prompts

Commands to send to review agents:

## Reviewer Command: Verification

Review the implementation from [BUILDER_AGENT].

### Context
[Scout findings and builder changes]

### Review Criteria
1. Correctness: Does it meet requirements?
2. Quality: Does it follow patterns?
3. Security: Are there vulnerabilities?
4. Performance: Are there concerns?
5. Tests: Is coverage adequate?

Provide results in this format:

### Consumed Assets
[Files reviewed, reports referenced]

### Findings by Severity

**Blocker:**
[Issues that must be fixed]

**High Risk:**
[Significant concerns]

**Medium Risk:**
[Should be addressed]

**Low Risk:**
[Nice to fix]

### Verdict
[Pass/Pass with recommendations/Fail]

### Recommendations
[Prioritized list of improvements]

### Status
[completed]

5. Aggregation Prompts

Prompts for combining results:

## Aggregation: Final Report

Compile final report from all agent results.

### Input
- Scout report: [summary]
- Builder report: [summary]
- Reviewer report: [summary]

### Output Format

## Task Completion Report

**Task:** [Original task]
**Duration:** [Total time]
**Cost:** [Total cost]

### Phase Summary

| Phase | Agents | Duration | Status |
| --- | --- | --- | --- |
| Scout | [n] | [time] | [status] |
| Build | [n] | [time] | [status] |
| Review | [n] | [time] | [status] |

### Results

**Files Created:**
[List]

**Files Modified:**
[List]

### Review Summary
[From reviewer]

### Outstanding Items
[Any remaining work]

### Conclusion
[1-2 sentence summary]

Workflow Phase Design

Standard Phases

Phase	Purpose	Agents	Output
Scout	Understand	1-3 scouts	Findings report
Plan	Design	1 planner	Implementation plan
Build	Implement	1-2 builders	Code changes
Review	Verify	1 reviewer	Review report
Report	Summarize	Orchestrator	Final report

Phase Transitions

Scout Complete --> Aggregate Findings --> Plan Phase
Plan Complete --> Validate Plan --> Build Phase
Build Complete --> Aggregate Changes --> Review Phase
Review Complete --> Check Verdict --> Report or Iterate

Conditional Flows

## Conditional: Review Failure

If reviewer verdict is "Fail":
1. Parse blocking issues
2. Create builder agent
3. Command: Fix specific issues
4. Re-run review phase
5. Maximum 3 iterations

If still failing after 3 iterations:
1. Report partial completion
2. List unresolved issues
3. Request user intervention

Prompt Engineering Tips

For Orchestrator Prompts

• Be explicit about not doing work directly
• List available tools and templates
• Define clear workflow pattern
• Emphasize context protection

For Agent Commands

• Include all needed context
• Specify exact output format
• List files to examine/modify
• Set clear scope boundaries

For Aggregation

• Define input sources
• Specify output structure
• Include metrics to calculate
• Handle partial results

Output Format

When writing orchestration prompts, provide:

## Orchestration Prompt Design

### Orchestrator System Prompt
[Full system prompt]

### Agent Command Templates

**Scout Commands:**
[Template with placeholders]

**Builder Commands:**
[Template with placeholders]

**Reviewer Commands:**
[Template with placeholders]

### Phase Transitions
[Flow diagram or description]

### Aggregation Format
[Final report template]

### Error Handling
[Failure scenarios and responses]

Design Checklist

• Orchestrator system prompt complete
• Scout command template created
• Builder command template created
• Reviewer command template created
• Aggregation format defined
• Phase transitions documented
• Error handling covered
• Output formats standardized

Anti-Patterns

Anti-Pattern	Problem	Solution
Vague commands	Poor agent output	Specific instructions
No output format	Unparseable results	Standard templates
Missing context	Agent re-discovers info	Include scout findings
No error handling	Workflow breaks	Conditional flows
Orchestrator doing work	Context pollution	Strict delegation

Cross-References

• @single-interface-pattern.md - Orchestrator architecture
• @results-oriented-engineering.md - Result formats
• @multi-agent-context-protection.md - Context boundaries
• @orchestrator-design skill - System design

Version History

• v1.0.0 (2025-12-26): Initial release

---

Last Updated

Date: 2025-12-26 Model: claude-opus-4-5-20251101