/executing-workflows

name: orchestration:executing-workflows
description: Use when user provides workflow syntax with arrows (-> || ~>), says "run workflow", "execute workflow", "run this", mentions step1 -> step2 patterns. Executes orchestration workflows with real-time visualization, steering, and error recovery.

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: 1. Parse and validate syntax 2. Show execution graph visualization 3. Execute agents with progress updates 4. Handle checkpoints and steering 5. Manage errors gracefully 6. 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 & Save State (Snapshots)

I run agents sequentially or in parallel. **Crucially, I maintain a local execution state file** to ensure reliability and enable "Time-Travel" recovery.

1. Before starting, I create/update `.orchestration/state.json` in the current working directory. 2. After EVERY successful node execution, I update the `state.json` with captured variables and the node's `completed` status. 3. If the workflow is interrupted, crashes, or fails, I retain this state file.

**Sequential** (`->`):

Running: Explore...  [In Progress]
Result: Analysis complete -> State Saved.
Running: implement...  [In Progress]
Result: Feature added -> State Saved.

⏪ Time-Travel Recovery (Resuming)

If you ask me to **"resume"** a workflow: 1. I read `./.orchestration/state.json`. 2. I inject all previously captured variables back into the context. 3. I skip all nodes marked as `completed` and instantly start executing from the exact node where it left off.

**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": 1. List all files with paths 2. 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).

**Note for Scheduled/Headless runs:** If the workflow is running automatically via `@schedule`, the interactive cleanup prompt is suppressed. Temporary files will be left intact so they can be reused on the next run, saving computation time.

Syntax Reference

See [syntax-reference.md](syntax-reference.md) for complete syntax documentation.

**Quick reference**:

| Syntax | Meaning | Example | |--------|---------|---------| | `->` | Sequential | `a -> b` | | `||` | Parallel | `[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