Single-responsibility agents and multi-agent workflows in AI-powered development tools

Maksim Bartoshyk

Lead Software Engineer, Global Delivery

Aliaksandr Paklonski

Director, Technology Solutions, Global Delivery

DATE

Dec 30, 2025

When using AI-powered coding assistants, developers often find themselves typing the same complex instructions repeatedly for code reviews, refactoring patterns or test generation. Sharing these proven prompts across a team requires copy-pasting or informal knowledge transfer.

Modern AI development tools address this with reusable prompts: predefined instructions you can save, share, and run on demand. Think of them as functions for your AI interactions: define once, use anywhere. These prompts often map to a specific SDLC task or domain role. That’s why we call them agents: each one acts as a specialist with a clear responsibility. As GenAI usage grows, teams quickly hit tasks that are too large for a single agent prompt. Building a feature typically requires requirements analysis, planning, implementation, and validation.

Each step needs different context and produces artifacts for the next. This is where workflows come in: coordinated sequences of agents, each handling one part of the problem.

Workflow capabilities are now available in major AI coding tools: Cursor, Windsurf, GitHub Copilot and Claude Code. Often such capabilities are considered as experimental, but we observe constant progress in this area. For instance, GitHub Copilot introduces custom agents with handoffs - ability to pass control to the next agent by pressing a single button. Claude Code introduces the 'native' sub-agents, allowing execution of agents in complete isolation. Vendors actively develop their tools and adopt proven features from competitors, so we expect continued rapid evolution across the ecosystem.

Across tools, the core prompt content is usually portable. The main differences are packaging and orchestration: file locations, metadata formats, how a tool references another step, and what context gets carried forward. This article maps what is implemented where and calls out the practical nuances that change how reliable a workflow feels.

What are single-responsibility agents in AI coding tools?

A single-responsibility agent is a reusable prompt built to do one job end to end. It has a clear input contract, a fixed output format, and no responsibility beyond that single task, which keeps it predictable. For example, when you invoke a custom Cursor command in a new chat tab of Cursor IDE Agent, the IDE starts a completely new agentic tool session using your predefined instructions and processes the request independently. Since each execution happens in isolation from other tasks, the agent remains predictable, easy to maintain, and performs with a high success rate and decent quality.

You can also run the same agent inside an existing session when the current context is relevant. In that case, the agent’s instructions combine with prior context, which can improve results, but it also increases the risk of unwanted carryover. The key is to keep the responsibility narrow enough that the agent remains repeatable across developers and repos.

Single-responsibility agent implementation example

Take this Cursor code review agent for example. Store the prompt in the .cursor/commands folder, for example code-review-checklist.md. You can then invoke it from Cursor Agent chat using /code-review-checklist with an input argument.

The directory structure includes:


.cursor/
└── commands/
    └── code-review-checklist.md

 code-review-checklist.md

# Code Review Checklist

## Objective
Ensure that the code meets quality standards and is ready for integration.

## Steps
1. Readability: Is the code easy to understand? Are comments and documentation provided where necessary?
2. Functionality: Does the code perform the intended task correctly?
3. Performance: Are there any potential performance bottlenecks?
4. Security: Are there any security vulnerabilities?
5. Testing: Are there sufficient tests? Do they cover edge cases?
6. Style: Does the code adhere to the project's coding standards and style guides?

## Checklist
- [ ] Code is free of syntax errors.
- [ ] Code is free of logical errors.
- [ ] Code is optimized for performance.
- [ ] Code is secure against common vulnerabilities.
- [ ] Code includes appropriate tests.
- [ ] Code follows the project's style guidelines.

What is a multi-agent workflow and when do you need one instead of one agent?

Multi-agent workflows involve multiple agents working in a defined sequence to solve a specific problem through multiple coordinated steps, where each agent prepares artifacts or context for the next agent in the workflow. These workflows can be orchestrated in two ways - by an agent or by a human.

Agent orchestration

In this approach, a master agent references multiple specialized agents and executes them in a specific order. The orchestrating agent decides which agent to call next based on the current state and previous results.

Pros:

Automatic - no or minimum human involvement is required

Cons:

Everything runs is in a single agentic session (i.e. single context window) in most tools (as of November 2025)
Errors compound across steps (without intermediate results review)
As a result - lower probability of successful output
More difficult to debug when something goes wrong, comparing to a single agent (need to review the whole conversation)

Human orchestration

With human orchestration, a person manually calls separate agents in specific order and reviews the results between steps. This introduces a feedback loop where a human can make corrections before errors compound.

Pros:

Better results at each step due to better context management*
Higher probability of success for overall result
Human can provide clarifications and corrections mid-process

Cons:

Requires human time and attention
Depends on the ability to review and understand large amount of machine-to-machine generated artifacts
Has slower overall execution time

*It is up to the human to decide how to run the next workflow step:

In the same agentic tool session, sharing all the existing context
In the same (or new) agentic tool session, but with summarizing ("compacting") context before calling the next step, meaning that only important information has left in the context. The way it works depends on an agentic tool you are using.
In the completely new agentic tool session with manually selected initial context, usually fully focused on the workflow step task.

Multi-agent workflow implementation example

We recommend building workflows using the following concepts:

limiting each agent scope of work, but keeping reasonably low number of agents
using "memory" - special files reflecting:
- common project rules and guidelines
- input and(or) output templates for each agent
- current workflow state (which step is active, which steps completed with a brief status, current output of each step)
inserting "breakpoints", places where execution should be continued only after human validation and approval
using code execution whenever task is algorithmic and does not require GenAI strengths - this will increase workflow stability and reduce token usage

If you need a complicated real-world example to explore those concepts in action, you could take a look at existing open-source projects that are becoming popular for AI-assisted development:

Spec Kit - spec-driven development framework, guides AI agents through multiple steps (spec, plan, implement). Uses memory files for project rules, templates for each step, and breakpoints for human review.
OpenSpec - similar multi-step approach focused on updating existing code. Uses separate folders to track current state and proposed changes, with memory files and templates for each workflow stage.
BMAD-Method - creates specialized AI agents that work in steps with planning and memory. Uses templates and custom tools to break down complex tasks into manageable workflow stages.

However, we observe now that most of specialists build own solutions and do not use helper frameworks or libraries. We see that the industry explores options how to give more structure to general coding and SDLC and mentioned frameworks are worth looking at for assessment, although there are currently some concerns regarding their maturity.

Below you will find a simpler example that shows an approach to orchestrate multi-step workflow in Cursor IDE using custom commands. Workflow is intended to help developer with a new feature implementation. Each custom command file stores specific agent prompt.

 Directory structure

cursor-commands-orchestration/
├── .cursor/
│   └── commands/                       # Reusable workflow agents
│       ├── 00_orchestrator.md          # Master agent, orchestrates other agents
│       ├── 01_analyze_requirements.md
│       ├── 02_create_plan.md
│       ├── 03_implement.md
│       ├── 04_test_validate.md
│       ├── 05_document.md
│       └── README.md
├── workflow-state/                     # Workflow state during execution
│   ├── analysis-results.md
│   ├── implementation-plan.md
│   ├── implementation-results.md
│   ├── test-results.md
│   └── workflow-summary.md
└── .cursorrules                        # AI behavior guidelines

Step 0: Workflow Orchestrator

00_orchestrator.md

# Workflow Orchestrator

## Overview
This command orchestrates a complete multi-step development workflow from analysis to documentation.

## Workflow Steps
This orchestrator will guide you through 5 sequential steps:

1. Analyze - Understand requirements and current state
2. Plan - Create detailed implementation plan
3. Implement - Execute the plan with checkpoints
4. Test - Validate implementation
5. Document - Complete all documentation

## Orchestration Instructions
When invoked, execute the following workflow:

### Step 1: Analysis
- Invoke .cursor/commands/01_analyze_requirements.md with the user's task description
- Wait for analysis completion
- Summarize key findings from analysis-results.md

### Step 2: Planning
- Invoke .cursor/commands/02_create_plan.md
- Present the implementation plan to user
- APPROVAL GATE: Wait for user approval before proceeding

### Step 3: Implementation
- Create checkpoint "pre-implementation"
- Invoke .cursor/commands/03_implement.md
- After each phase, create a checkpoint
- Summarize implementation progress

### Step 4: Testing
- Invoke .cursor/commands/04_test_validate.md
- Report test results
- If tests fail, ask user if they want to fix or rollback

### Step 5: Documentation
- Invoke .cursor/commands/05_document.md
- Present final workflow summary
- Mark workflow as complete

## Execution Rules
1. Sequential Execution: Complete each step fully before proceeding
2. State Preservation: Always save intermediate results to workflow-state
3. Checkpoints: Create checkpoints before and after major changes
4. Explicit Context: Reference previous step outputs explicitly
5. Approval Gates: Stop and wait for user approval at critical points
6. Error Handling: If a step fails, stop and ask user how to proceed

## Workflow State Directory
All intermediate results are stored in workflow-state/:
- analysis-results.md - Requirements and impact analysis
- implementation-plan.md - Detailed implementation plan
- implementation-results.md - What was actually implemented
- test-results.md - Testing outcomes
- workflow-summary.md - Final summary and documentation

## Usage
Invoke with: /00_orchestrator [detailed task description]

Example: /00_orchestrator Add user authentication with JWT tokens

Step 1: Analyze Requirements

01_analyze_requirements.md

# Step 1: Analyze Requirements

## Objective
Analyze the project requirements and current codebase state to understand what needs to be done.

## Context Requirements
- Access to project documentation
- Current codebase structure
- User requirements or feature requests

## Actions
1. Review relevant documentation (@docs or specified files)
2. Analyze existing codebase structure using @codebase
3. Identify files and components that will be affected
4. List dependencies and constraints
5. Identify potential risks or challenges

## Analysis Checklist
- [ ] Requirements clearly understood
- [ ] Affected files identified
- [ ] Dependencies mapped
- [ ] Risks documented
- [ ] Questions for clarification noted

## Outputs
Create workflow-state/analysis-results.md with:
- Summary of requirements
- List of files to modify/create
- Dependency analysis
- Risk assessment
- Clarifying questions (if any)

## Next Step
After analysis is complete, proceed to Step 2 (Planning) or address clarifying questions first.

## Usage
Invoke this command with: /01_analyze_requirements [description of task]

Step 2: Create Plan

02_create_plan.md

# Step 2: Create Implementation Plan

## Objective
Based on the analysis, create a detailed implementation plan with specific steps and file changes.

## Context Requirements
- Results from Step 1: workflow-state/analysis-results.md
- Current codebase state

## Actions
1. Review analysis results from previous step
2. Break down implementation into logical phases
3. Define specific file changes for each phase
4. Identify test requirements
5. Estimate complexity and potential issues
6. Create checkpoint plan (where to save state)

## Planning Checklist
- [ ] Implementation broken into clear phases
- [ ] Each phase has specific file changes defined
- [ ] Test strategy defined
- [ ] Rollback strategy considered
- [ ] Dependencies ordered correctly

## Outputs
Create workflow-state/implementation-plan.md with:
- Phase-by-phase implementation plan
- Specific files to modify in each phase
- Code structure and architecture decisions
- Test cases to implement
- Checkpoint strategy

## Approval Gate
STOP HERE and present the plan to the user for approval before proceeding to Step 3.

## Next Step
After plan approval, proceed to Step 3 (Implementation).

## Usage
Invoke this command with: /02_create_plan

Step 3: Implement

03_implement.md

# Step 3: Implementation

## Objective
Execute the approved implementation plan phase by phase.

## Context Requirements
- Approved plan: workflow-state/implementation-plan.md
- Analysis results: workflow-state/analysis-results.md

## Actions
1. Review the approved implementation plan
2. Create checkpoint before starting
3. Implement Phase 1 changes
4. Create checkpoint after Phase 1
5. Implement Phase 2 changes (and so on)
6. Create final checkpoint after all changes

## Implementation Rules
- Follow the plan strictly unless you discover an issue
- If deviating from plan, explain why and get approval
- Create checkpoints between phases
- Test each phase before moving to next
- Document any unexpected challenges or changes

## Implementation Checklist
- [ ] Checkpoint created before starting
- [ ] Phase 1 completed and tested
- [ ] Phase 2 completed and tested
- [ ] [Add more phases as needed]
- [ ] All file changes completed
- [ ] Code follows project standards
- [ ] No linter errors introduced

## Outputs
Create workflow-state/implementation-results.md with:
- List of all files modified/created
- Summary of changes made
- Any deviations from original plan and why
- Issues encountered and resolutions
- Status of each phase

## Next Step
After implementation is complete, proceed to Step 4 (Testing & Validation).

## Usage
Invoke this command with: /03_implement

Step 4: Test and Validate

04_test_validate.md

# Step 4: Test & Validation

## Objective
Validate the implementation through testing and verification.

## Context Requirements
- Implementation results: workflow-state/implementation-results.md
- Implementation plan: workflow-state/implementation-plan.md
- Modified files from Step 3

## Actions
1. Review all files modified in Step 3
2. Run existing test suites
3. Create or update tests for new functionality
4. Perform manual testing checklist
5. Check for linter errors
6. Verify all requirements from Step 1 are met
7. Check for edge cases and error handling

## Testing Checklist
- [ ] All existing tests pass
- [ ] New tests created for new functionality
- [ ] New tests pass
- [ ] No linter errors
- [ ] Edge cases handled
- [ ] Error handling implemented
- [ ] All original requirements satisfied
- [ ] Performance is acceptable

## Outputs
Create workflow-state/test-results.md with:
- Test execution summary
- List of tests added or modified
- Any issues found and their status
- Coverage report (if applicable)
- Validation checklist status

## Next Step
If tests pass, proceed to Step 5 (Documentation). If tests fail, return to Step 3 with fixes.

## Usage
Invoke this command with: /04_test_validate

Step 5: Documentation

05_document.md

# Step 5: Documentation

## Objective
Document all changes, decisions, and usage for future reference.

## Context Requirements
- Analysis results: workflow-state/analysis-results.md
- Implementation plan: workflow-state/implementation-plan.md
- Implementation results: workflow-state/implementation-results.md
- Test results: workflow-state/test-results.md
- All modified files

## Actions
1. Update inline code documentation (comments, JSDoc, etc.)
2. Update README if necessary
3. Update API documentation
4. Create or update user guides if needed
5. Document architectural decisions
6. Update changelog
7. Create summary of workflow execution

## Documentation Checklist
- [ ] Code comments updated
- [ ] Function and class documentation complete
- [ ] README updated (if needed)
- [ ] API documentation current
- [ ] Changelog updated
- [ ] Architectural decisions documented

## Outputs
1. Updated documentation files
2. workflow-state/workflow-summary.md with:
   - Overview of what was accomplished
   - All files changed
   - Key decisions made
   - Tests added
   - How to use new functionality
   - Future considerations

## Workflow Complete
This is the final step. Review the workflow-summary.md and ensure all objectives are met.

## Usage
Invoke this command with: /05_document

Usage option 1: automatic orchestration
Call /00_orchestrator Add user authentication with JWT from a Cursor Agent chat.

The orchestrator will:
1. Analyze requirements
2. Create a plan and wait for approval
3. Implement the plan with checkpoints
4. Test the implementation
5. Document everything

Orchestrator agent is referencing other workflow agents by mentioning appropriate files. Cursor Agent automatically injects referenced workflow agents' prompts while executing workflow. All the workflow steps are executed in the same agentic tool session and share all the workflow execution context from start to end.

Usage option 2: run individual steps

Call /01_analyze_requirements Add dark mode toggle and review the analysis
Call /02_create_plan and approve or modify the plan
Call /03_implement to implement the plan
......

Better results could be achieved if each workflow agent is triggered in separate Cursor Agent chat, especially when each separate agent has complicated set of instructions with conditional branching.

Workflow Steps Explained

Step 1: Analyze Requirements

Understands what needs to be done
Identifies affected files and dependencies
Assesses risks and challenges
Output: analysis-results.md

Step 2: Create Plan

Breaks down work into phases
Defines specific file changes
Plans testing strategy
Output: implementation-plan.md
Approval Gate: Review and approve before continuing

Step 3: Implementation

Executes the plan phase by phase
Creates checkpoints between phases
Documents deviations from plan
Output: implementation-results.md

Step 4: Test & Validate

Runs existing tests
Creates new tests for new functionality
Validates requirements
Output: test-results.md

Step 5: Documentation

Updates code documentation
Updates README and guides
Creates workflow summary
Output: workflow-summary.md

Key Features

Context Preservation: Each step saves its results to workflow-state/ , allowing subsequent steps to build on previous work.
Checkpoints: Automatic checkpoints are created at critical points, enabling rollback if needed.
Approval Gates: Critical steps wait for user approval, ensuring control is maintained over the workflow.
State Management: Intermediate results are saved and can be reviewed, modified, or used for future reference.
Iterative Refinement: If a step doesn't meet expectations, it is possible to rollback and retry with modifications.

Claude Code

Example below shows the exact workflow, implemented with Cursor, but adapted to Claude Code command line tool.

Unlike Cursor, Claude Code provides several different features to reuse functionality and prompts: skills, slash commands and sub-agents.

	Skills	Slash Commands	Subagents
Context	Operate within the calling context (main conversation or sub-agent)	Operate within the main conversation context	Operate isolated with own context
Execution	Triggered automatically by Claude when matched to request context	Invoked explicitly by the user	Triggered automatically by Claude when matched to request context
Purpose	Modular capabilities that extend functionality, available for GenAI (for example, extracting data from a PDF file)	Define frequently-used prompts as modular shortcuts the user can execute	Define specialized pre-configured AI assistants that can be invoked to handle specific types of tasks
Setup complexity	High (several metadata files integrated with python scripts)	Low (prompt stored in a file)	Moderate (prompt with metadata, stored in a single file)

All these features provide high degree of flexibility and allow fine-tuning of your workflow.

Skills could be used to extend agents capabilities (same skill shared across all agents), slash commands to implement both workflow steps and orchestrator, sub-agents - to implement workflow steps.

Claude Code Slash commands based workflow

Slash commands are stored as a separate markdown files in .claude/commands folder. Commands are just prompts without any specific format specification, except for input arguments. This functionality has high similarity to Cursor Commands.

 Directory structure

claude-commands-orchestration/
├── .claude/
│   └── commands/
│       ├── 00_orchestrator.md          # Main command (run with /00_orchestrator)
│       ├── 01_analyze_requirements.md  # Analysis agent
│       ├── 02_create_plan.md           # Planning agent
│       ├── 03_implement.md             # Implementation agent
│       ├── 04_test_validate.md         # Testing agent
│       └── 05_document.md              # Documentation agent
└── workflow-state/                     # Workflow state during execution
    ├── analysis-results.md
    ├── implementation-plan.md
    ├── implementation-results.md
    ├── test-results.md
    └── workflow-summary.md

Prompts for main workflow steps (from 01_analyze_requirement to 05_document) are exactly the same as in Cursor example above. Orchestrator prompt is adapted to use SlashCommand tool.

 00_orchestrator.md

# Workflow Orchestrator

## Overview
This command orchestrates a complete multi-step development workflow from analysis to documentation.

## Workflow Steps
This orchestrator will guide you through 5 sequential steps:

1. Analyze - Understand requirements and current state
2. Plan - Create detailed implementation plan
3. Implement - Execute the plan with checkpoints
4. Test - Validate implementation
5. Document - Complete all documentation

## Orchestration Instructions
When invoked, execute the following workflow:

### Step 1: Analysis
- Invoke SlashCommand tool: /01_analyze_requirements [user's task description]
- Wait for analysis completion
- Summarize key findings from analysis-results.md

### Step 2: Planning
- Invoke SlashCommand tool: /02_create_plan
- Present the implementation plan to user
- APPROVAL GATE: Wait for user approval before proceeding

### Step 3: Implementation
- Create checkpoint "pre-implementation"
- After receiving user approval, invoke SlashCommand tool: /03_implement
- After each phase, create a checkpoint
- Summarize implementation progress

### Step 4: Testing
- Invoke SlashCommand tool: /04_test_validate
- Report test results
- If tests fail, ask user if they want to fix or rollback

### Step 5: Documentation
- Invoke SlashCommand tool: /05_document.md
- Present final workflow summary
- Mark workflow as complete

## Execution Rules
1. Sequential Execution: Complete each step fully before proceeding
2. State Preservation: Always save intermediate results to workflow-state
3. Checkpoints: Create checkpoints before and after major changes
4. Explicit Context: Reference previous step outputs explicitly
5. Approval Gates: Stop and wait for user approval at critical points
6. Error Handling: If a step fails, stop and ask user how to proceed

## Workflow State Directory
All intermediate results are stored in workflow-state/:
- analysis-results.md - Requirements and impact analysis
- implementation-plan.md - Detailed implementation plan
- implementation-results.md - What was actually implemented
- test-results.md - Testing outcomes
- workflow-summary.md - Final summary and documentation

## Usage
Invoke with: /00_orchestrator [detailed task description]

Example: /00_orchestrator Add user authentication with JWT tokens

The same options exist to execute workflow: using either orchestrator command or running sequence of commands manually. With orchestrator everything is run in the same agentic tool session, with manual orchestration user chooses how to manage context (spawn a new Claude Code session or use existing one).

Utilizing Claude Code Sub-agents

Sub-agents is a Claude Code feature that allows to execute each separate workflow step in isolated context window. Claude Code calls sub-agents from the main conversation, provides focused input context and only inspects the final result.

We do not recommend using sub-agent for orchestration task due to the following reasons:

It seems that sub-agents could not call other sub-agents
While sub agent is running, main thread does not show much details about sub-agent progress

Orchestration should be done by slash command, while sub-agents could be used for individual workflow steps. Such approach may lead to increased token consumption comparing to workflow based exclusively on commands, but gives the following benefits:

Main context thread is focused only on management of workflow execution and user interaction, it is not "spoiled" by intermediate results of each workflow step
Each sub-agent is focused on a specific task, its context is not "spoiled" by the workflow orchestration and intermediate results from other steps
Sub-agents could be executed in parallel to speed up workflow when feasible
Sub-agents are configurable: list of tools, permissions, skills, model. Each workflow step could be tweaked separately, for instance, to use cheaper model for simpler tasks.

Possible drawbacks:

limited interactivity: Claude Code shows sub-agent execution with only a few details, user interaction is only possible with an "Ask user" tool, which is not always feasible. It seems to be impractical to implement conversational sub-agents: sub-agent starts analysis, builds context and finishes own execution with a question to the user in the output; main conversation thread then asks question to the user and provides and answer to a sub-agent in a completely new sub-agent call - context lost. Claude Code documentation mentions resumable sub-agents, however it is not clear how to force Claude Code work this way.
each sub-agent call has context overhead - Claude tools, skills, system prompt etc.

Sub-agents in Claude Code have a specific file format with required and optional metadata. Unlike slash commands sub-agents are stored in .claude/agents folder. Below are example of workflow implementation using slash command orchestrator and sub-agents as workflow steps.

 Directory structure

claude-agents-orchestration/
├── .claude/
│   ├── agents/
│   │   ├── 01_analyze_requirements.md  # Analysis agent
│   │   ├── 02_create_plan.md           # Planning agent
│   │   ├── 03_implement.md             # Implementation agent
│   │   ├── 04_test_validate.md         # Testing agent
│   │   └── 05_document.md              # Documentation agent
│   └── commands/
│       └── 00_orchestrator.md          # Main command (run with /00_orchestrator)
└── workflow-state/                     # Workflow state during execution
    ├── analysis-results.md
    ├── implementation-plan.md
    ├── implementation-results.md
    ├── test-results.md
    └── workflow-summary.md

Step 0: Workflow Orchestrator

00_orchestrator.md

# Workflow Orchestrator

## Overview
This command orchestrates a complete multi-step development workflow from analysis to documentation.

## Workflow Steps
This orchestrator will guide you through 5 sequential steps:

1. Analyze - Understand requirements and current state
2. Plan - Create detailed implementation plan
3. Implement - Execute the plan with checkpoints
4. Test - Validate implementation
5. Document - Complete all documentation

## Orchestration Instructions
When invoked, execute the following workflow:

### Step 1: Analysis
- Invoke Task tool with subagent_type: "analyze-requirements", provide user's task description as input prompt
- Wait for analysis completion
- Summarize key findings from analysis-results.md

### Step 2: Planning
- Invoke Task tool with subagent_type: "create-plan"
- Present the implementation plan to user
- APPROVAL GATE: Wait for user approval before proceeding

### Step 3: Implementation
- Create checkpoint "pre-implementation"
- After receiving user approval, invoke Task tool with subagent_type: "implement"
- After each phase, create a checkpoint
- Summarize implementation progress

### Step 4: Testing
- Invoke Task tool with subagent_type: "test-validate"
- Report test results
- If tests fail, ask user if they want to fix or rollback

### Step 5: Documentation
- Invoke Task tool with subagent_type: "document"
- Present final workflow summary
- Mark workflow as complete

## Execution Rules
1. Sequential Execution: Complete each step fully before proceeding
2. State Preservation: Always save intermediate results to workflow-state
3. Checkpoints: Create checkpoints before and after major changes
4. Explicit Context: Reference previous step outputs explicitly
5. Approval Gates: Stop and wait for user approval at critical points
6. Error Handling: If a step fails, stop and ask user how to proceed

## Workflow State Directory
All intermediate results are stored in workflow-state/:
- analysis-results.md - Requirements and impact analysis
- implementation-plan.md - Detailed implementation plan
- implementation-results.md - What was actually implemented
- test-results.md - Testing outcomes
- workflow-summary.md - Final summary and documentation

## Usage
Invoke with: /00_orchestrator [detailed task description]

Example: /00_orchestrator Add user authentication with JWT tokens

Step 1: Analyze Requirements

01_analyze_requirements.md

---
name: analyze-requirements
description: Specialized agent for thoroughly analyzing project requirements and assessing the current codebase state. Use this agent to understand what needs to be implemented by exploring project structure, identifying affected areas, analyzing dependencies, assessing risks, and creating a comprehensive analysis document that will guide the planning phase.
tools: Bash, Glob, Grep, Read, Edit, Write, BashOutput, AskUserQuestion
model: sonnet
---

# Agent: Analyze Requirements

## Objective
Analyze the project requirements and current codebase state to understand what needs to be done.

## Context Requirements
- Access to project documentation
- Current codebase structure
- User requirements or feature requests

## Actions
1. Review relevant documentation (@docs or specified files)
2. Analyze existing codebase structure using @codebase
3. Identify files and components that will be affected
4. List dependencies and constraints
5. Identify potential risks or challenges

## Analysis Checklist
- [ ] Requirements clearly understood
- [ ] Affected files identified
- [ ] Dependencies mapped
- [ ] Risks documented
- [ ] Questions for clarification noted

## Outputs
Create workflow-state/analysis-results.md with:
- Summary of requirements
- List of files to modify/create
- Dependency analysis
- Risk assessment
- Clarifying questions (if any)

Step 2: Create Plan

02_create_plan.md

---
name: create-plan
description: Specialized agent for creating detailed, actionable implementation plans. Use this agent after requirements analysis to break down the work into logical phases, define specific file changes, plan testing strategies, make architectural decisions, and create risk mitigation plans. This agent reviews the analysis results and produces a comprehensive plan ready for user approval before implementation.
tools: Bash, Glob, Grep, Read, Edit, Write, BashOutput, AskUserQuestion
model: sonnet
---

# Agent: Create Implementation Plan

## Objective
Based on the analysis, create a detailed implementation plan with specific steps and file changes.

## Context Requirements
- Results from Step 1: workflow-state/analysis-results.md
- Current codebase state

## Actions
1. Review analysis results from previous step
2. Break down implementation into logical phases
3. Define specific file changes for each phase
4. Identify test requirements
5. Estimate complexity and potential issues
6. Create checkpoint plan (where to save state)

## Planning Checklist
- [ ] Implementation broken into clear phases
- [ ] Each phase has specific file changes defined
- [ ] Test strategy defined
- [ ] Rollback strategy considered
- [ ] Dependencies ordered correctly

## Outputs
Create workflow-state/implementation-plan.md with:
- Phase-by-phase implementation plan
- Specific files to modify in each phase
- Code structure and architecture decisions
- Test cases to implement
- Checkpoint strategy

Step 3: Implement

03_implement.md

---
name: implement
description: Specialized agent for executing approved implementation plans phase by phase. Use this agent after the plan has been approved to make actual code changes to the codebase. This agent follows the plan carefully, implements each phase in order, maintains code quality, tests incrementally, handles issues appropriately, and documents all changes and deviations.
tools: Bash, Glob, Grep, Read, Edit, Write, BashOutput, AskUserQuestion
model: sonnet
---

# Agent: Implementation

## Objective
Execute the approved implementation plan phase by phase.

## Context Requirements
- Approved plan: workflow-state/implementation-plan.md
- Analysis results: workflow-state/analysis-results.md

## Actions
1. Review the approved implementation plan
2. Create checkpoint before starting
3. Implement Phase 1 changes
4. Create checkpoint after Phase 1
5. Implement Phase 2 changes (and so on)
6. Create final checkpoint after all changes

## Implementation Rules
- Follow the plan strictly unless you discover an issue
- If deviating from plan, explain why and get approval
- Create checkpoints between phases
- Test each phase before moving to next
- Document any unexpected challenges or changes

## Implementation Checklist
- [ ] Checkpoint created before starting
- [ ] Phase 1 completed and tested
- [ ] Phase 2 completed and tested
- [ ] [Add more phases as needed]
- [ ] All file changes completed
- [ ] Code follows project standards
- [ ] No linter errors introduced

## Outputs
Create workflow-state/implementation-results.md with:
- List of all files modified or created
- Summary of changes made
- Any deviations from original plan and why
- Issues encountered and resolutions
- Status of each phase

Step 4: Test and Validate

04_test_validate.md

---
name: test-validate
description: Specialized agent for thoroughly testing and validating implementations. Use this agent after implementation to verify all requirements are met, run existing test suites, create new tests for new functionality, check code quality with linters and type checkers, perform manual validation, test edge cases and error handling, and create comprehensive test reports with recommendations.
tools: Bash, Glob, Grep, Read, Edit, Write, BashOutput, AskUserQuestion
model: sonnet
---

# Agent: Test & Validation

## Objective
Validate the implementation through testing and verification.

## Context Requirements
- Implementation results: workflow-state/implementation-results.md
- Implementation plan: workflow-state/implementation-plan.md
- Modified files from Step 3

## Actions
1. Review all files modified in Step 3
2. Run existing test suites
3. Create or update tests for new functionality
4. Perform manual testing checklist
5. Check for linter errors
6. Verify all requirements from Step 1 are met
7. Check for edge cases and error handling

## Testing Checklist
- [ ] All existing tests pass
- [ ] New tests created for new functionality
- [ ] New tests pass
- [ ] No linter errors
- [ ] Edge cases handled
- [ ] Error handling implemented
- [ ] All original requirements satisfied
- [ ] Performance is acceptable

## Outputs
Create workflow-state/test-results.md with:
- Test execution summary
- List of tests added or modified
- Any issues found and their status
- Coverage report (if applicable)
- Validation checklist status

Step 5: Document

05_document.md

---
name: document
description: Specialized agent for creating comprehensive documentation after implementation and testing. Use this agent to update code documentation (comments, JSDoc, docstrings), update project documentation (README, API docs, user guides), document architectural decisions, update changelogs, and create detailed workflow summaries. This is the final step that ensures all changes and decisions are properly documented for future reference.
tools: Bash, Glob, Grep, Read, Edit, Write, BashOutput, AskUserQuestion
model: sonnet
---

# Agent: Documentation

## Objective
Document all changes, decisions, and usage for future reference.

## Context Requirements
- Analysis results: workflow-state/analysis-results.md
- Implementation plan: workflow-state/implementation-plan.md
- Implementation results: workflow-state/implementation-results.md
- Test results: workflow-state/test-results.md
- All modified files

## Actions
1. Update inline code documentation (comments, JSDoc, etc.)
2. Update README if necessary
3. Update API documentation
4. Create or update user guides if needed
5. Document architectural decisions
6. Update changelog
7. Create summary of workflow execution

## Documentation Checklist
- [ ] Code comments updated
- [ ] Function and class documentation complete
- [ ] README updated (if needed)
- [ ] API documentation current
- [ ] Changelog updated
- [ ] Architectural decisions documented

## Outputs
1. Updated documentation files
2. workflow-state/workflow-summary.md with:
   - Overview of what was accomplished
   - All files changed
   - Key decisions made
   - Tests added
   - How to use new functionality
   - Future considerations

You may notice that orchestrator calls sub-agents referencing Task Tool. There is not much in official documentation about it, but it seems it is used internally by Claude Code to spawn sub-agents (see unofficial documentation here and here). The tool looks very promising - allows you create and run sub-agents on demand:

Start with generating a prompt, that you want to execute in a separate sub-agent context (or load it from file, for example).
Run Task Tool with the generated prompt.

 On-demand sub agent example

# On-demand sub agent example

Use the Task tool to invoke the agent:

- Read path/to/prompt-file.md for the agent's prompt
- Use Task tool with subagent_type: "general-purpose" and provide the full agent's prompt
- Provide an input to the agent

Windsurf

Official documentation: Windsurf workflows

Note: despite Windsurf calling a single set of instructions stored in a file a "workflow", this isn't a workflow in terms of this document. We call a multi-agent workflow a system, which requires coordination between different agents, each agent with its own context and specialization. By concept Windsurf workflow feature is a close analogue of Cursor Commands and Claude Code Slash commands.

Example of the workflow implementation is exactly the same as in Cursor with the similar folder structure. Each workflow agent prompt is stored in own file under .windsurf/workflows folder.

 Directory structure

windsurf-workflows-orchestration/
├── .windsurf/
│   └── workflows/                    # Workflow definitions for Windsurf
│       ├── 00_orchestrator.md        # Master orchestrator workflow
│       ├── 01_analyze_requirements.md
│       ├── 02_create_plan.md
│       ├── 03_implement.md
│       ├── 04_test_validate.md
│       └── 05_document.md
└── workflow-state/                   # Intermediate results during execution
    ├── analysis-results.md
    ├── implementation-plan.md
    ├── implementation-results.md
    ├── test-results.md
    └── workflow-summary.md

Each Windsurf workflow file has optional metadata parameters:

description: purpose of the workflow
auto_execution_mode: "safe" or "turbo", defines whether the user will be asked for approval when executing commands

Step 0: Workflow Orchestrator

00_orchestrator.md

---
description: Orchestrates a 5-step development workflow from analysis to documentation
auto_execution_mode: 3
---

# Workflow Orchestrator

## Overview
This workflow orchestrates a complete multi-step development workflow from analysis to documentation, adapted for Windsurf.

## Workflow Steps
This orchestrator will guide you through 5 sequential steps:

1. Analyze - Understand requirements and current state
2. Plan - Create detailed implementation plan
3. Implement - Execute the plan with checkpoints
4. Test - Validate implementation
5. Document - Complete all documentation

## Orchestration Instructions
When this workflow runs, follow the sequence below:

### Step 1: Analysis
- Run the step workflow 01_analyze_requirements from .windsurf/workflows/01_analyze_requirements.md with the user's task description
- Wait for analysis completion
- Summarize key findings from workflow-state/analysis-results.md

### Step 2: Planning
- Run the step workflow 02_create_plan from .windsurf/workflows/02_create_plan.md
- Present the implementation plan to the user
- APPROVAL GATE: Wait for user approval before proceeding

### Step 3: Implementation
- Create a checkpoint named pre-implementation
- Run the step workflow 03_implement from .windsurf/workflows/03_implement.md
- After each phase, create a checkpoint
- Summarize implementation progress

### Step 4: Testing
- Run the step workflow 04_test_validate from .windsurf/workflows/04_test_validate.md
- Report test results
- If tests fail, ask the user if they want to fix or rollback

### Step 5: Documentation
- Run the step workflow 05_document from .windsurf/workflows/05_document.md
- Present final workflow summary
- Mark workflow as complete

## Execution Rules
1. Sequential Execution: Complete each step fully before proceeding
2. State Preservation: Always save intermediate results to workflow-state/
3. Checkpoints: Create checkpoints before and after major changes
4. Explicit Context: Reference previous step outputs explicitly
5. Approval Gates: Stop and wait for user approval at critical points
6. Error Handling: If a step fails, stop and ask the user how to proceed

## Workflow State Directory
All intermediate results are stored in workflow-state/:
- analysis-results.md - Requirements and impact analysis
- implementation-plan.md - Detailed implementation plan
- implementation-results.md - What was actually implemented
- test-results.md - Testing outcomes
- workflow-summary.md - Final summary and documentation

## Usage
- Open Windsurf in this workspace
- Run the /00_orchestrator workflow with a detailed task description

Example:
/00_orchestrator Add user authentication with JWT tokens

Step 1: Analyze Requirements

01_analyze_requirements.md

---
description: Analyzes requirements and the current codebase to understand the requested change.
auto_execution_mode: 3
---

# Step 1: Analyze Requirements

## Objective
Analyze the project requirements and current codebase state to understand what needs to be done.

## Context Requirements
- Access to project documentation
- Current codebase structure
- User requirements or feature requests

## Actions
1. Review relevant documentation (or specified files)
2. Analyze existing codebase structure
3. Identify files and components that will be affected
4. List dependencies and constraints
5. Identify potential risks or challenges

## Analysis Checklist
- [ ] Requirements clearly understood
- [ ] Affected files identified
- [ ] Dependencies mapped
- [ ] Risks documented
- [ ] Questions for clarification noted

## Outputs
Create workflow-state/analysis-results.md with:
- Summary of requirements
- List of files to modify or create
- Dependency analysis
- Risk assessment
- Clarifying questions (if any)

## Next Step
After analysis is complete, proceed to Step 2 (Planning).

## Usage
Run the 01_analyze_requirements workflow from .windsurf/workflows/01_analyze_requirements.md and provide a description of the task to analyze.

Step 2: Plan

02_create_plan.md

---
description: Creates a detailed, phase-based implementation plan from the analysis results.
auto_execution_mode: 3
---

# Step 2: Create Implementation Plan

## Objective
Based on the analysis, create a detailed implementation plan with specific steps and file changes.

## Context Requirements
- Results from Step 1: workflow-state/analysis-results.md
- Current codebase state

## Actions
1. Review analysis results from previous step
2. Break down implementation into logical phases
3. Define specific file changes for each phase
4. Identify test requirements
5. Estimate complexity and potential issues
6. Create checkpoint plan (where to save state)

## Planning Checklist
- [ ] Implementation broken into clear phases
- [ ] Each phase has specific file changes defined
- [ ] Test strategy defined
- [ ] Rollback strategy considered
- [ ] Dependencies ordered correctly

## Outputs
Create workflow-state/implementation-plan.md with:
- Phase-by-phase implementation plan
- Specific files to modify in each phase
- Code structure and architecture decisions
- Test cases to implement
- Checkpoint strategy

## Approval Gate
STOP HERE and present the plan to the user for approval before proceeding to Step 3.

## Next Step
After plan approval, proceed to Step 3 (Implementation).

## Usage
Run the 02_create_plan workflow from .windsurf/workflows/02_create_plan.md after 01_analyze_requirements has produced workflow-state/analysis-results.md

Step 3: Implement

03_implement.md

---
description: Executes the approved implementation plan in phases with checkpoints and tracking.
auto_execution_mode: 3
---

# Step 3: Implementation

## Objective
Execute the approved implementation plan phase by phase.

## Context Requirements
- Approved plan: workflow-state/implementation-plan.md
- Analysis results: workflow-state/analysis-results.md

## Actions
1. Review the approved implementation plan
2. Create a checkpoint before starting
3. Implement Phase 1 changes
4. Create a checkpoint after Phase 1
5. Implement Phase 2 changes (and so on)
6. Create a final checkpoint after all changes

## Implementation Rules
- Follow the plan strictly unless you discover an issue
- If deviating from plan, explain why and get approval
- Create checkpoints between phases
- Test each phase before moving to next
- Document any unexpected challenges or changes

## Implementation Checklist
- [ ] Checkpoint created before starting
- [ ] Phase 1 completed and tested
- [ ] Phase 2 completed and tested
- [ ] [Add more phases as needed]
- [ ] All file changes completed
- [ ] Code follows project standards
- [ ] No linter errors introduced

## Outputs
Create workflow-state/implementation-results.md with:
- List of all files modified or created
- Summary of changes made
- Any deviations from original plan and why
- Issues encountered and resolutions
- Status of each phase

## Next Step
After implementation is complete, proceed to Step 4 (Testing & Validation).

## Usage
Run the 03_implement workflow from .windsurf/workflows/03_implement.md after the implementation plan has been created and approved.

Step 4: Test and Validate

04_test_validate.md

---
description: Validates the implementation through automated and manual testing against requirements.
auto_execution_mode: 3
---

# Step 4: Test & Validation

## Objective
Validate the implementation through testing and verification.

## Context Requirements
- Implementation results: workflow-state/implementation-results.md
- Implementation plan: workflow-state/implementation-plan.md
- Modified files from Step 3

## Actions
1. Review all files modified in Step 3
2. Run existing test suites
3. Create or update tests for new functionality
4. Perform manual testing checklist
5. Check for linter errors
6. Verify all requirements from Step 1 are met
7. Check for edge cases and error handling

## Testing Checklist
- [ ] All existing tests pass
- [ ] New tests created for new functionality
- [ ] New tests pass
- [ ] No linter errors
- [ ] Edge cases handled
- [ ] Error handling implemented
- [ ] All original requirements satisfied
- [ ] Performance is acceptable

## Outputs
Create workflow-state/test-results.md with:
- Test execution summary
- List of tests added or modified
- Any issues found and their status
- Coverage report (if applicable)
- Validation checklist status

## Next Step
If tests pass, proceed to Step 5 (Documentation). If tests fail, return to Step 3 with fixes.

## Usage
Run the 04_test_validate workflow from .windsurf/workflows/04_test_validate.md after implementation is complete.

Step 5: Documentation

05_document.md

---
description: Documents the changes, decisions, and usage and produces a final workflow summary.
auto_execution_mode: 3
---

# Step 5: Documentation

## Objective
Document all changes, decisions, and usage for future reference.

## Context Requirements
- Analysis results: workflow-state/analysis-results.md
- Implementation plan: workflow-state/implementation-plan.md
- Implementation results: workflow-state/implementation-results.md
- Test results: workflow-state/test-results.md
- All modified files

## Actions
1. Update inline code documentation (comments, JSDoc, etc.)
2. Update README if necessary
3. Update API documentation
4. Create or update user guides if needed
5. Document architectural decisions
6. Update changelog
7. Create summary of workflow execution

## Documentation Checklist
- [ ] Code comments updated
- [ ] Function and class documentation complete
- [ ] README updated (if needed)
- [ ] API documentation current
- [ ] Changelog updated
- [ ] Architectural decisions documented

## Outputs
1. Updated documentation files
2. workflow-state/workflow-summary.md with:
   - Overview of what was accomplished
   - All files changed
   - Key decisions made
   - Tests added
   - How to use new functionality
   - Future considerations

## Workflow Complete
This is the final step. Review workflow-state/workflow-summary.md and ensure all objectives are met.

## Usage
Run the 05_document workflow from .windsurf/workflows/05_document.md after testing has completed successfully.

The same options exist to execute our example workflow: using either orchestrator or running sequence of agents manually. With orchestrator everything is run in the same Windsurf Cascade agentic session, with manual orchestration user chooses how to manage context (use existing session or trigger a new one).

GitHub Copilot

Note: The examples below are based on VSCode GitHub Copilot extension.

GitHub Copilot provides the next features, that allow to reuse prompts: prompt files and custom agents. Prompt files are run with /prompt-name pattern in GitHub Copilot Chat input, custom agents are selected in GitHub Copilot Chat dropdown (custom agents are previously known as chat modes). Both prompt files and custom agents are configurable, allowing you, for example, select model or restrict number of tools available for the prompt execution. The key difference between prompt files and custom agents is where the prompt is sent to LLM:

prompt from prompt file is sent to LLM as a user-level prompt
prompt from custom agent is sent to LLM as a part of system prompt

GitHub Copilot Prompt Files based workflow

Prompt files are stored in a separate markdown files in .github/prompts folder with a special suffix *.prompt.md. Each prompt file can have an optional metadata, allowing to fine-tune and optimize it according to the task.

Metadata Field	Description
description	A short description of the prompt. This helps users understand the purpose of the prompt.
name	The name of the prompt file, used after typing in chat. Defaults to the file name if absent.
argument-hint	Optional text shown in the chat input field to guide how users interact with the prompt.
agent	Specifies the agent to run the prompt: ask, edit, agent (default), or a custom agent name.
model	The language model used when running the prompt. Defaults to the current model if unspecified.
tools	A list of available tools or tool sets for the prompt. Can include built-in or extension tools.

Important observations:

Mentioning "run /other-prompt-name" in orchestrator seems not working - we have to refer to exact file, i.e. "continue with instructions in #file:path-to-file.md".
Prompt file metadata is applied only when you trigger prompt file from GitHub Copilot Chat, running the same prompt from orchestrator inherits orchestrator configuration. This reveals limitation in metadata configuration - you could rely on it only with manual orchestration.

 Directory structure

github-copilot-prompt-files-orchestration/
├── .github/
│   └── prompts/
│       ├── 00_orchestrator.prompt.md          # Main command (run with /00_orchestrator)
│       ├── 01_analyze_requirements.prompt.md  # Analysis agent
│       ├── 02_create_plan.prompt.md           # Planning agent
│       ├── 03_implement.prompt.md             # Implementation agent
│       ├── 04_test_validate.prompt.md         # Testing agent
│       └── 05_document.prompt.md              # Documentation agent
└── workflow-state/                            # Workflow state during execution
    ├── analysis-results.md
    ├── implementation-plan.md
    ├── implementation-results.md
    ├── test-results.md
    └── workflow-summary.md

Prompts for the main workflow steps (from 01_analyze_requirement to 05_document) are exactly the same as in Cursor example above. Orchestrator prompt is different - it is adapted to explicitly mention from which file prompt should be loaded.

 00_orchestrator.md

---
name: orchestrator
description: Orchestrates a complete multi-step development workflow from analysis to documentation
argument-hint: "[detailed task description]"
---

# Workflow Orchestrator

## Overview
This command orchestrates a complete multi-step development workflow from analysis to documentation.

## Workflow Steps
This orchestrator will guide you through 5 sequential steps:

1. Analyze – Understand requirements and current state
2. Plan – Create detailed implementation plan
3. Implement – Execute the plan with checkpoints
4. Test – Validate implementation
5. Document – Complete all documentation

## Orchestration Instructions
When invoked, execute the following workflow:

### Step 1: Analysis
- Invoke prompt from #file:./01_analyze_requirements.prompt.md providing the user's task description as input
- Wait for analysis completion
- Summarize key findings from analysis-results.md

### Step 2: Planning
- Invoke prompt from #file:./02_create_plan.prompt.md
- Present the implementation plan to user
- APPROVAL GATE: Wait for user approval before proceeding

### Step 3: Implementation
- Create checkpoint "pre-implementation"
- Invoke prompt from #file:./03_implement.prompt.md
- After each phase, create a checkpoint
- Summarize implementation progress

### Step 4: Testing
- Invoke prompt from #file:./04_test_validate.prompt.md
- Report test results
- If tests fail, ask user if they want to fix or rollback

### Step 5: Documentation
- Invoke prompt from #file:./05_document.prompt.md
- Present final workflow summary
- Mark workflow as complete

## Execution Rules
1. Sequential Execution: Complete each step fully before proceeding
2. State Preservation: Always save intermediate results to workflow-state
3. Checkpoints: Create checkpoints before and after major changes
4. Explicit Context: Reference previous step outputs explicitly
5. Approval Gates: Stop and wait for user approval at critical points
6. Error Handling: If a step fails, stop and ask user how to proceed

## Workflow State Directory
All intermediate results are stored in workflow-state/:
- analysis-results.md – Requirements and impact analysis
- implementation-plan.md – Detailed implementation plan
- implementation-results.md – What was actually implemented
- test-results.md – Testing outcomes
- workflow-summary.md – Final summary and documentation

GitHub Copilot Custom Agents based workflow

Each custom agent is stored in folder .github/agents and available in GitHub Copilot Chat dropdown. Custom agents have optional metadata, allowing to configure model, tools, handoffs* etc. By defining custom agent metadata you could perform-fine tuning of the workflow.

Metadata Field	Description
`description`	A brief description of the custom agent's purpose and capabilities, shown in the chat input placeholder.
`name`	The name of the custom agent. Defaults to the filename if not specified.
`argument-hint`	Optional hint text displayed in the chat input to guide users on how to interact with this custom agent.
`tools`	List of tools or tool sets available for this custom agent. Can include built-in tools, MCP servers, and extension tools.
`model`	The AI model to use when running the agent. If unspecified, defaults to the current model selected in the environment.
`target`	Target environment or context for the agent (for example, `vscode` or `github-copilot`).
`mcp-servers`	Optional configuration list of Model Context Protocol (MCP) servers and tools to be used by the agent (mainly for GitHub).
`handoffs`	Optional list of sequential workflow handoffs to other agents with button labels, target agents, optional prompts, and auto-submit flags.
`handoffs.label`	The label shown on the handoff button for transitioning to another agent.
`handoffs.agent`	The target custom agent identifier to switch to when a handoff occurs.
`handoffs.prompt`	Optional prompt text to send to the target agent upon handoff.
`handoffs.send`	Optional boolean to auto-submit the prompt when handing off (default is `false`).

*Handoffs is a useful feature for manual orchestrated workflow. Handoffs allow you to transition seamlessly from one specialized agent to another with a single click - you define which agent the context goes to and with which prompt. Technically, when you perform a handoff:

Instructions in system prompt of the existing conversation is replaced by the next custom agent prompt
Handoff prompt is submitted as a next user message to LLM

In case of automatic orchestration special tool could be used: #runSubagent (documentation), note that this feature is marked as experimental and you need to explicitly enable it for custom agents. This tool allows to run custom agent in an isolated context from the main agentic session (somehow similar to Claude Code Subagents). You just need to provide the exact name of the custom agent. Unfortunately, it is not fully clear when this tool is run from GitHub Copilot GUI, we recommend to inspect chat debug window to confirm that everything works as expected.

 Directory structure

github-copilot-custom-agents-orchestration/
├── .github/
│   └── agents/
│       ├── 00_orchestrator.md          # Main command (run with /00_orchestrator)
│       ├── 01_analyze_requirements.md  # Analysis agent
│       ├── 02_create_plan.md           # Planning agent
│       ├── 03_implement.md             # Implementation agent
│       ├── 04_test_validate.md         # Testing agent
│       └── 05_document.md              # Documentation agent
└── workflow-state/                     # Workflow state during execution
    ├── analysis-results.md
    ├── implementation-plan.md
    ├── implementation-results.md
    ├── test-results.md
    └── workflow-summary.md

The example below shows the next capabilities:

Running custom agents manually with help of handoff functionality
Using orchestrator agent to run each workflow step in isolated context with #runSubagent tool
Limiting number of tools available for each agent

Step 0: Workflow Orchestrator

name: orchestrator tools: runSubagent

---
name: orchestrator
description: Orchestrates a complete multi-step development workflow from analysis to documentation
tools: ['runSubagent']
---

Workflow Orchestrator

Overview

This command orchestrates a complete multi-step development workflow from analysis to documentation.

Workflow Steps

This orchestrator will guide you through 5 sequential steps:

Analyze - Understand requirements and current state
Plan - Create detailed implementation plan
Implement - Execute the plan with checkpoints
Test - Validate implementation
Document - Complete all documentation

Orchestration Instructions

When invoked, execute the following workflow:

Step 1: Analysis

Invoke tool #runSubagent analyze-requirements, provide the user's task description
Wait for analysis completion
Summarize key findings from analysis-results.md

Step 2: Planning

Invoke tool #runSubagent create-plan
Present the implementation plan to user

Approval gate: wait for user approval before proceeding.

Step 3: Implementation

Create checkpoint "pre-implementation"
Invoke tool #runSubagent implement
After each phase, create a checkpoint
Summarize implementation progress

Step 4: Testing

Invoke tool #runSubagent test-validate
Report test results
If tests fail, ask user if they want to fix or rollback

Step 5: Documentation

Invoke tool #runSubagent document
Present final workflow summary
Mark workflow as complete

Execution Rules

Sequential Execution: complete each step fully before proceeding
State Preservation: always save intermediate results to workflow-state
Checkpoints: create checkpoints before and after major changes
Explicit Context: reference previous step outputs explicitly
Approval Gates: stop and wait for user approval at critical points
Error Handling: if a step fails, stop and ask user how to proceed

Workflow State Directory

All intermediate results are stored in workflow-state/:

analysis-results.md - Requirements and impact analysis
implementation-plan.md - Detailed implementation plan
implementation-results.md - What was actually implemented
test-results.md - Testing outcomes
workflow-summary.md - Final summary and documentation

Step 1: Analyze Requirements

01_analyze_requirements.md

---
name: analyze-requirements
description: Analyzes project requirements and codebase state to understand what needs to be done
tools: ['edit/createFile', 'edit/createDirectory', 'edit/editFiles', 'search', 'usages']
handoffs:
  - label: Create Implementation Plan
    agent: create-plan
    prompt: Now create an implementation plan based on the analysis results.
    send: false
---

# Step 1: Analyze Requirements

You are a requirements analysis specialist focused on understanding project requirements and current codebase state.

## Your Role
Analyze the project requirements and current codebase state to understand what needs to be done for the given task.

## Context You Need
- Access to project documentation
- Current codebase structure
- User requirements or feature requests

## Your Analysis Process
1. Review relevant documentation (@docs or specified files)
2. Analyze existing codebase structure using @codebase
3. Identify files and components that will be affected
4. List dependencies and constraints
5. Identify potential risks or challenges

## Analysis Checklist
Ensure you address:
- [ ] Requirements clearly understood
- [ ] Affected files identified
- [ ] Dependencies mapped
- [ ] Risks documented
- [ ] Questions for clarification noted

## Your Output
Create workflow-state/analysis-results.md with:
- Summary of requirements: Clear statement of what needs to be done
- List of files to modify or create: Specific file paths and reasons
- Dependency analysis: What the changes depend on
- Risk assessment: Potential issues or challenges
- Clarifying questions: Any questions that need user input

## Important Guidelines
- Be thorough but concise
- Focus on facts, not assumptions
- Identify gaps in information early
- Document technical constraints
- Consider backward compatibility
- Think about testing requirements

Step 2: Create Plan

02_create_plan.md

---
name: create-plan
description: Creates a detailed implementation plan with specific steps and file changes based on requirements analysis
tools: ['edit/createFile', 'edit/createDirectory', 'edit/editFiles', 'search', 'usages']
handoffs:
  - label: Implement
    agent: implement
    prompt: Implement a plan.
    send: false
---

# Step 2: Create Implementation Plan

You are an implementation planning specialist focused on creating detailed, actionable plans for software development tasks.

## Your Role
Based on the requirements analysis, create a detailed implementation plan with specific steps and file changes.

## Context You Need
- Results from Step 1: workflow-state/analysis-results.md
- Current codebase state

## Your Planning Process
1. Review analysis results from the previous step
2. Break down implementation into logical phases
3. Define specific file changes for each phase
4. Identify test requirements
5. Estimate complexity and potential issues
6. Create checkpoint plan (where to save state)

## Planning Checklist
Ensure your plan includes:
- [ ] Implementation broken into clear phases
- [ ] Each phase has specific file changes defined
- [ ] Test strategy defined
- [ ] Rollback strategy considered
- [ ] Dependencies ordered correctly

## Your Output
Create workflow-state/implementation-plan.md with:
- Phase-by-phase implementation plan: Numbered phases with clear objectives
- Specific files to modify in each phase: Exact file paths and changes
- Code structure and architecture decisions: How the solution will be structured
- Test cases to implement: Required tests
- Checkpoint strategy: When to create checkpoints for rollback safety

## Important Guidelines
- Be specific with file paths and function names
- Order phases logically (dependencies first)
- Keep phases small and manageable
- Consider existing patterns in the codebase
- Plan for error handling and edge cases
- Include both implementation and testing in the plan
- Make the plan clear enough that another developer could follow it

Step 3: Implement

03_implement.md

---
name: implement
description: Executes the approved implementation plan phase by phase with checkpoints and documentation
tools: ['edit/createFile', 'edit/createDirectory', 'edit/editFiles', 'search', 'usages']
handoffs:
  - label: Test and validate
    agent: test-validate
    prompt: Now test and validate the implementation
    send: false
---

# Step 3: Implementation

You are an implementation specialist focused on executing approved plans with precision and proper checkpointing.

## Your Role
Execute the approved implementation plan phase by phase, creating checkpoints and documenting progress.

## Context You Need
- Approved plan: workflow-state/implementation-plan.md
- Analysis results: workflow-state/analysis-results.md

## Your Implementation Process
1. Review the approved implementation plan
2. Create checkpoint before starting (if using git)
3. Implement Phase 1 changes
4. Create checkpoint after Phase 1
5. Implement Phase 2 changes
6. Continue for all phases
7. Create final checkpoint after all changes

## Implementation Rules
- Follow the plan strictly unless you discover an issue
- If deviating from plan: Explain why and get user approval
- Create checkpoints between phases: Allow for rollback
- Test each phase before moving to next: Catch issues early
- Document unexpected challenges or changes: Keep audit trail

## Implementation Checklist
Track your progress:
- [ ] Checkpoint created before starting
- [ ] Phase 1 completed and tested
- [ ] Phase 2 completed and tested
- [ ] [Add more phases as needed]
- [ ] All file changes completed
- [ ] Code follows project standards
- [ ] No linter errors introduced

## Your Output
Create workflow-state/implementation-results.md with:
- List of all files modified or created: Complete file inventory
- Summary of changes made: What was done in each file
- Any deviations from original plan and why: Transparency on changes
- Issues encountered and resolutions: Problem-solving documentation
- Status of each phase: Phase completion checklist

## Important Guidelines
- Write clean, idiomatic code matching project style
- Add appropriate comments for complex logic
- Handle errors gracefully
- Consider performance implications
- Maintain backward compatibility when possible
- Use existing utilities and patterns from the codebase
- Do not introduce unnecessary dependencies

Step 4: Test and Validate

04_test_validate.md

---
name: test-validate
description: Validates implementation through comprehensive testing and verification
tools: ['edit/createFile', 'edit/createDirectory', 'edit/editFiles', 'search', 'runCommands', 'usages']
handoffs:
  - label: Documentation
    agent: document
    prompt: Now create documentation.
    send: false
---

# Step 4: Test & Validation

You are a quality assurance specialist focused on thorough testing and validation of code changes.

## Your Role
Validate the implementation through testing and verification to ensure quality and correctness.

## Context You Need
- Implementation results: workflow-state/implementation-results.md
- Implementation plan: workflow-state/implementation-plan.md
- Modified files from Step 3

## Your Testing Process
1. Review all files modified in Step 3
2. Run existing test suites
3. Create or update tests for new functionality
4. Perform manual testing checklist
5. Check for linter errors
6. Verify all requirements from Step 1 are met
7. Check for edge cases and error handling

## Testing Checklist
Verify each item:
- [ ] All existing tests pass
- [ ] New tests created for new functionality
- [ ] New tests pass
- [ ] No linter errors
- [ ] Edge cases handled
- [ ] Error handling implemented
- [ ] All original requirements satisfied
- [ ] Performance is acceptable

## Your Output
Create workflow-state/test-results.md with:
- Test execution summary: Overall pass or fail status
- List of tests added or modified: Specific test files and test cases
- Any issues found and their status: Bugs found and whether fixed
- Coverage report (if applicable): Percentage of code covered
- Validation checklist status: Checkmark report

## Important Guidelines
- Run tests before creating new ones: Ensure no regressions
- Write meaningful test names: Describe what is being tested
- Test happy paths and error cases: Comprehensive coverage
- Consider boundary conditions: Min/max values, empty inputs, nulls
- Test integration points: How components work together
- Use existing test patterns: Match project testing style
- Document test failures clearly: Make debugging easier

## Decision Point
If tests pass, proceed to Step 5 (Documentation).
If tests fail, return to Step 3 with fixes using /03_implement.

Step 5: Documentation

05_document.md

---
name: document
description: Documents all changes, decisions, and usage for future reference
tools: ['edit/createFile', 'edit/createDirectory', 'edit/editFiles', 'search', 'usages']
---

# Step 5: Documentation

You are a technical documentation specialist focused on creating clear, comprehensive documentation for code changes.

## Your Role
Document all changes, decisions, and usage for future reference to ensure maintainability and knowledge transfer.

## Context You Need
- Analysis results: workflow-state/analysis-results.md
- Implementation plan: workflow-state/implementation-plan.md
- Implementation results: workflow-state/implementation-results.md
- Test results: workflow-state/test-results.md
- All modified files

## Your Documentation Process
1. Update inline code documentation (comments, JSDoc, docstrings, etc.)
2. Update README if necessary
3. Update API documentation
4. Create or update user guides if needed
5. Document architectural decisions
6. Update changelog
7. Create summary of workflow execution

## Documentation Checklist
Ensure completeness:
- [ ] Code comments updated
- [ ] Function or class documentation complete
- [ ] README updated (if needed)
- [ ] API documentation current
- [ ] Changelog updated
- [ ] Architectural decisions documented

## Your Outputs

### 1. Update In-Code Documentation
- Add or update function documentation
- Add or update class documentation
- Add explanatory comments for complex logic
- Update any inline documentation

### 2. Create Workflow Summary
Create workflow-state/workflow-summary.md with:
- Overview of what was accomplished: High-level summary
- All files changed: Complete list with brief description of changes
- Key decisions made: Important architectural or implementation choices
- Tests added: What testing was implemented
- How to use new functionality: Usage examples and API reference
- Future considerations: Technical debt, improvements, or follow-up work

## Important Guidelines
- Write for the future: Assume reader does not have current context
- Be concise but complete: Balance brevity with completeness
- Use examples: Show actual usage where helpful
- Link to relevant resources: Reference external docs when applicable
- Document the why: Not just what was done, but why decisions were made
- Update existing docs: Do not leave outdated information
- Use consistent formatting: Match project documentation style

## Workflow Complete
This is the final step. Review the workflow-summary.md and ensure all objectives from Step 1 are met.

## Summary
Provide the user with:
- Confirmation that all steps are complete
- Location of the workflow summary
- Quick summary of what was accomplished
- Any follow-up actions or recommendations

Which agentic tool should you choose for workflows today?

Our experiments show that prompts quality, overall workflow design and particular LLM capabilities are key factors of success. LLM is responsible for understanding and following the instructions correctly, agentic tool is responsible for managing conversation and providing tools for LLM (environment access). All agentic tools described in this document do not have strong native orchestration capabilities, orchestrator prompt relies on fact, that LLM understands that instructions should be loaded from files and executed in specific order. There is no visual representation of workflow state, only GitHub Copilot started to introduce UI features related to orchestration - handoffs, but GitHub Copilot custom agents in general are considered as either preview or experimental feature.

All tools mentioned in this document are more or less similar in agentic capabilities, start with whatever you have access to and switch to another tool only if you see a particular benefits or have personal preference. GitHub Copilot and Claude Code, however, could provide more flexibility and fine-tuning potential in workflow configuration.

Workflow success rate

Below we explore a simple model for calculating workflow success rate. We can assume that all steps are independent and the success rate is the same at each step. This helps us understand the compound effect of errors across multiple agent interactions.

Given n steps, we define overall success rate as: (success rate at step 1) × (success rate at step 2) × ... × (success rate at step n)

Agent-orchestrated workflow without human review (90% success per step):

Steps	Success Rate
1	0.90
2	0.81
3	0.73
4	0.66
5	0.59

As you can see, with a high 0.9 success rate per step, a 5-step workflow only succeeds with probability 0.59. This explains why fully automated multi-agent workflows frequently struggle to deliver reliable results.

With "human-in-the-loop" we can review the result after each step and correct issues, effectively increasing the per-step success rate, let's, for example, increase individual rate to 0.97:

Human-orchestrated workflow with intermediate results review (97% success per step):

Steps	Success Rate
1	0.97
2	0.94
3	0.91
4	0.89
5	0.86

This demonstrates why it's critical to perform reviews to significantly increase the success rate of multi-agent workflows. Even a small improvement in per-step quality (90% → 97%) results in significant improvements in end-to-end success (59% → 86% for 5 steps). However, this result achieved at a cost - review may take significant human effort.

What are the practical recommendations for adopting agents and workflows?

Based on the analysis above, below are practical recommendations for adopting reusable agents and workflows.

Single-responsibility agents (recommended for practical use on a project)

Use them for repetitive, well-defined tasks that follow consistent patterns (code reviews, refactoring, test generation, etc.)
Document your agents and share them across the team
Maintain agents to ensure quality of the output improves over time

Multi-agent workflows (recommended to experiment with)

Keep in mind that at the current level of GenAI capabilities you have to apply techniques improving workflow success rate:

Prefer human orchestration over agent orchestration
Humans must validate intermediate results and provide corrections, despite reviewing AI-generated machine-to-machine artifacts is exhausting
Keep context focused, pass only what's needed for the next step, keep separate context windows for each step
Find a balance between number of workflow agents and how narrow the separate agent focus is (narrowing focus increases individual success rate, increasing number of steps decreases overall success rate)
Monitor success rates and adjust your workflow design based on actual results

Consider that usually there is no specific UI guiding you through the workflow, complex workflows constantly require to keep track of the workflow state. Some of the features used to run workflows automatically are still marked as an experimental by agentic tool vendors.

Documentation references

List of popular tools allowing you to create reusable agents and workflows:

MAKE AI-NATIVE DEVELOPMENT WORK FOR YOUR TEAM MAKE AI-NATIVE DEVELOPMENT WORK FOR YOUR TEAM

Frequent Searches

Single-responsibility agents and multi-agent workflows in AI-powered development tools

CATEGORY

Maksim Bartoshyk

Aliaksandr Paklonski

DATE

Workflow Orchestrator

Overview

Workflow Steps

Orchestration Instructions

Execution Rules

Workflow State Directory