workflow

# 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:

| Command | Purpose |
|---------|---------|
| `rundown run <file>` | Begin a runbook |
| `rundown pass` | Mark current step as passed |
| `rundown fail` | Mark current step as failed |
| `rundown goto N` | Jump to specific step |
| `rundown status` | Check current state |
| `rundown complete` | Mark workflow finished |
| `rundown stop` | Abort workflow |
| `rundown stash` | Pause enforcement (for ad-hoc work) |
| `rundown pop` | Resume enforcement |

### 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.

**