Workflow Execution

Overview

Workflows are multi-step processes with state tracking. Two-tier orchestration: subagents execute individual steps and report outcomes; main agent dispatches, monitors, and handles failures.

Core principle: Subagents fail fast, main agent troubleshoots.

When to Use

• •Multi-step processes needing state persistence across context clears
• •Parallel subagent orchestration with status tracking
• •PASS/FAIL signaling between agents
• •Processes requiring retry/resume capability

Not for: Single-step steps, ad-hoc commands

For Subagents

You're executing a workflow step. Your context shows:

• •Step N: What you need to do
• •Attempt: Retry count if applicable

Protocol

1. •Execute the step as described in the prompt
2. •End your response with a status line: STATUS: PASS or STATUS: FAIL
3. •If stuck, blocked, or unclear, report STATUS: FAIL - main agent will handle

Do NOT:

• •Advance the parent workflow - only your orchestrator does that
• •Try to fix infrastructure issues - report FAIL and let main handle
• •Continue past errors - fail fast so main can troubleshoot

You CAN: Run your own nested workflows with full workflow commands.

For Main Agent

You orchestrate the workflow. Use these commands:

Dispatching Steps

Include StepId in Step tool description - hooks handle the rest automatically:

Step(description="2.1 - Review authentication code", ...)

The StepId format is N.X where N is step number, X is substep number.

Hook automation:

• •PostToolUse hook parses StepId from description, calls rundown run --step 2.1
• •SubagentStart hook binds the agent to the queued step
• •SubagentStop hook parses STATUS line, calls rundown next --pass/--fail --agent {id}

Do NOT manually call rundown run --step - hooks handle this.

Parallel Substeps

For parallel execution (e.g., ### 2.{n} substeps):

1. •Dispatch all agents in one message (multiple Step tool calls)
2. •Run rundown status to check agent completion
3. •When all agents report done, run rundown next

Dynamic Substep {n} Syntax

### N.{n} marks dynamic substeps - orchestrator decides count at runtime.

Dispatch with sequential StepIds in description:

Step(description="3.1 - Agent 1 review", ...)
Step(description="3.2 - Agent 2 review", ...)

• •$n in workflow prompts substitutes with substep number (1, 2, etc.)
• •Hooks handle step queuing and agent binding automatically

Handling Failures

When subagent reports STATUS: FAIL: check output, discuss with user, then retry or jump (--goto N) or abort (stop).

Common Mistakes