---

name: workflow description: Use when executing multi-step processes requiring state persistence and agent coordination - defines two-tier protocol where subagents report PASS/FAIL status and main agent handles dispatch, advancement, and failure troubleshooting

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:

CopyStep(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:

CopyStep(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