Executing Orchestration Workflows

I execute workflows with real-time visualization, progress tracking, and interactive steering at checkpoints.

When I Activate

I automatically activate when you:

• Provide workflow syntax to execute

• Ask to "run a workflow"

• Mention workflow execution

• Want to execute a template

• Ask "how do I run this workflow?"

Quick Start

Just provide workflow syntax and I'll handle the rest:

Explore:"Analyze codebase":analysis -> implement:"Add feature based on {analysis}":code -> general-purpose:"Run tests":results

I automatically:

• Parse and validate syntax

• Show execution graph visualization

• Execute agents with progress updates

• Handle checkpoints and steering

• Manage errors gracefully

• Clean up temporary files (with user confirmation)

Execution Process

Phase 1: Parse & Validate

I analyze your workflow:

• Validate syntax correctness

• Check agent references

• Verify variable bindings

• Identify checkpoints

• Map execution graph

Phase 2: Visualize

I show you the execution plan using ASCII art:

Execution Graph: +-----------------+ | Explore | | (Analyze code) | +--------+--------+ | v +-----------------+ | implement | | (Add feature) | +--------+--------+ | v +-----------------+ | general-purpose | | (Run tests) | +-----------------+

Phase 3: Execute

I run agents sequentially or in parallel:

Sequential (-> ):

Running: Explore... [In Progress] Result: Analysis complete Running: implement... [In Progress] Result: Feature added

Parallel (|| ):

Running: task1... [In Progress] Running: task2... [In Progress] Running: task3... [In Progress] All complete! Merging results...

Phase 4: Steering

At checkpoints (@review ), you control flow:

@review-point reached

Options: [C]ontinue - Proceed with workflow [R]etry - Re-run previous step [M]odify - Adjust and continue [A]bort - Stop workflow

Your choice?

Phase 5: Error Recovery

If agent fails, I offer options:

Agent 'implement' failed: Tests not passing

Options:

• Retry with same instruction
• Modify instruction and retry
• Skip this step (continue workflow)
• Abort workflow

What would you like to do?

Phase 6: Cleanup (CONDITIONAL)

IMPORTANT: After workflow execution, check for temporary files and ask user before deleting.

Step 1: Detect Temporary Files

Check for existence of temporary files in the current working directory:

Check temp-agents

TEMP_AGENTS=$(ls ./temp-agents/*.md 2>/dev/null | wc -l)

Check temp-scripts

TEMP_SCRIPTS=$(ls ./temp-scripts/* 2>/dev/null | wc -l)

Check temporary JSON (NOT .flow files!)

TEMP_JSON=$(ls ./examples/*.json 2>/dev/null | wc -l)

TOTAL=$((TEMP_AGENTS + TEMP_SCRIPTS + TEMP_JSON))

Step 2: If Files Exist, Ask User

Only if TOTAL > 0 , use AskUserQuestion:

AskUserQuestion({ questions: [{ question: "Found ${TOTAL} temporary files. Do you want to delete them?", header: "Cleanup", multiSelect: false, options: [ {label: "Yes, delete all", description: "Remove all temporary files (temp-agents, temp-scripts, temp JSON)"}, {label: "Show me first", description: "List files before deciding"}, {label: "No, keep them", description: "Leave files for manual review"} ] }] })

Step 3: Execute Cleanup if Confirmed

If user chose "Yes, delete all":

Delete temp-agents (in current working directory)

rm -f ./temp-agents/*.md

Delete temp-scripts (in current working directory)

rm -rf ./temp-scripts/*

Delete temporary JSON only (keep .flow files!)

rm -f ./examples/*.json

Report what was deleted:

Cleaned up ${TOTAL} temporary files:

• ${TEMP_AGENTS} temp agents removed
• ${TEMP_SCRIPTS} temp scripts removed
• ${TEMP_JSON} temporary JSON files removed

If user chose "Show me first":

• List all files with paths

• Ask again: "Delete these files?" with Yes/No options

Step 4: Skip if No Files

If TOTAL == 0 , skip cleanup silently (don't bother user).

Syntax Reference

See syntax-reference.md for complete syntax documentation.

Quick reference:

Syntax Meaning Example

->

Sequential a -> b

`

`

~>

Conditional (if passed)~> next

@

Checkpoint @review

:var

Output capture task:output

{var}

Variable interpolation "Use {output}"

$agent

Temp agent $scanner:"Scan"

Agent Types

Built-in Claude Code agents (no prefix):

• Explore

• Fast codebase exploration and search

• Plan

• Planning and breaking down tasks

• general-purpose

• Versatile agent for complex multi-step tasks

Plugin agents (orchestration: prefix):

• orchestration:workflow-socratic-designer

• Workflow creation via Socratic method

• orchestration:workflow-syntax-designer

• Custom syntax design

External agents (registered via /orchestration:init):

• Agents from ~/.claude/agents/ can be registered and used directly

• Example: expert-code-implementer , code-optimizer (if registered)

Temp agents ($name):

• Created during workflow execution in ./temp-agents/

• Automatically cleaned up after workflow (with user confirmation)

• Can be promoted to permanent agents if useful

Variable Passing

See variables.md for advanced variable usage.

Capture output:

Explore:"Find routes":routes -> analyze:"Check {routes}":findings

Conditional on variables:

test:"Run tests":results -> (if results.passed)> deploy -> (if results.failed)> debug

Error Handling

Common error patterns:

Retry on failure:

@attempt -> operation:"Try task" -> (if failed)~> wait:"Wait 5s" -> @attempt > (if passed)> continue

Fallback path:

primary:"Try primary" -> (if failed)~> backup:"Use backup" > (if passed)> process

Stop on critical error:

security-scan:"Scan" -> (if critical-issues)~> @emergency-stop -> abort > (if clean)> deploy

Checkpoints

See checkpoints.md for checkpoint details.

Basic checkpoint:

implement -> @review -> deploy

Labeled checkpoint:

@quality-gate:"Review code quality. Approve?"

Conditional checkpoint:

(if security-critical)~> @security-review

Parallel Execution

See parallel.md for parallel execution patterns.

Basic parallel:

[task1 || task2 || task3] -> merge

Parallel with individual variables:

[ task1:"First":result1 || task2:"Second":result2 || task3:"Third":result3 ] -> general-purpose:"Process {result1}, {result2}, {result3}"

Conditional parallel:

(if needs-full-scan)~> [security || performance || style] > (if needs-quick-check)> basic-lint

Examples

See examples/ for categorized workflow examples:

• sequential.md - Sequential workflows

• parallel.md - Parallel execution

• conditional.md - Conditional logic

• error-handling.md - Error recovery

• checkpoints.md - Manual gates

Execution Modes

Normal mode (default):

• Full execution with all phases

• Interactive checkpoints

• Error recovery prompts

Dry-run mode:

• Parse and validate only

• Show execution plan

• No actual agent execution

Auto mode:

• Skip checkpoint prompts

• Automatic error retry (up to 3 times)

• Minimal user interaction

Progress Tracking

During execution, I show:

Workflow: TDD Implementation Progress: [========..] 80%

Phase 1: Done - Requirements analyzed Phase 2: Done - Tests written Phase 3: Done - Tests verified failing Phase 4: Paused - Checkpoint: review-test-coverage Phase 5: In Progress - Implementing code... Phase 6: Pending Phase 7: Pending

Workflow Metadata

Track execution metadata:

Workflow: debug-and-fix.flow Started: 2025-01-08 14:32:10 Duration: 5m 23s Agents used: 8 Checkpoints: 2 Status: Complete

Agents executed:

• Explore (x1)
• general-purpose (x5)
• expert-code-implementer (x2)

Resources:

• Files read: 12
• Files modified: 3
• Tests run: 1

Tips for Successful Execution

• Start simple - Test with small workflows first

• Use checkpoints - Add review points for critical steps

• Capture outputs - Use variables to pass data between agents

• Handle errors - Add fallback paths for critical operations

• Monitor progress - Watch execution visualization

Common Issues

Agent not found:

• Check agent name spelling

• Verify temp agent exists in ./temp-agents/

• Ensure namespace prefix for plugin agents

Variable not found:

• Verify variable was captured with :varname

• Check variable name spelling in {varname}

• Ensure variable set before use

Checkpoint skipped:

• Checkpoints only work in normal mode

• Check checkpoint syntax: @checkpoint-name

Parallel execution failed:

• Ensure parallel tasks are independent

• Check bracket syntax: [a || b]

• Verify no shared state between parallel tasks

Related Skills

• creating-workflows: Design and create workflows

• managing-agents: Create and manage custom agents

• debugging-workflows: Debug workflow issues

• using-templates: Execute workflow templates

Commands

• /orchestration:run

• Execute workflow from file or inline

• /orchestration:template

• Execute saved template

• /orchestration:explain

• Explain workflow execution plan

Ready to execute? Provide your workflow syntax or template name!