# Workflows

Workflows let you run multi-step, resumable automation with durable state instead of hiding long-running work inside one chat transcript.

## Why Workflows?

Anteroom already gives you strong building blocks:

- [skills](../cli/skills.md) for reusable task prompts
- [tools](../cli/tools.md) for file edits, bash, search, and sub-agents
- [rules](../packs/types/rule.md) for always-on guidance and hard constraints
- [packs](../packs/index.md) and [spaces](../spaces/index.md) for sharing behavior and policy

Those pieces work well for a single turn. Workflows add the missing layer for work that spans:

- multiple steps
- retries and review loops
- process restarts
- durable state and history
- external monitoring

Common examples:

- issue delivery from approved plan to ready-for-review output
- overnight research collection and summarization
- gated document-generation pipelines
- policy-controlled operational runbooks

## What's What

| Concept | What it is |
|---|---|
| **Workflow definition** | A YAML file describing inputs, policies, steps, and optional notifications |
| **Workflow run** | One execution of a workflow against a specific target |
| **Runner step** | A unit of work executed by an agent runner, shell command, or Python script |
| **Gate step** | A named condition that can continue or block the run |
| **Loop step** | A bounded retry/review loop over nested steps |
| **Workflow event** | A durable state transition such as `step_started` or `run_completed` |
| **Workflow lock** | A DB-backed guard that prevents concurrent runs on the same target |
| **Hook** | A best-effort outbound notification via webhook or Unix socket |
| **Parallel step** | Concurrent branch execution with join:all and fail-fast cancellation (#976) |
| **Compensation** | Reverse-order rollback blocks on steps, triggered on failure (#978) |
| **Params** | Overridable defaults declared in the definition, supplied at runtime via `--param` (#958) |
| **Trigger** | A schedule or event that automatically enqueues a workflow run |
| **Schedule** | A cron-based trigger stored in the database with atomic claim semantics |
| **Spec** | A structured planning artifact with phased approvals that can gate workflow progression |

## How It Fits

```text
Workflow Definition (YAML)
        │
        ▼
Workflow Engine
        │
        ├─→ agent runners / shell / python_script
        ├─→ workflow state in SQLite
        ├─→ workflow events
        ├─→ CLI progress output
        ├─→ read-only REST API
        └─→ SSE + notification hooks
```

## Current Scope

The current workflow feature set is intentionally narrow:

- CLI owns execution: `run`, `status`, `list`, `history`, `resume`, `cancel`, `validate`, `simulate`
- the web UI provides monitoring and run control via REST/SSE
- the engine is generic; the shipped generic reference example is `issue_delivery`, while the best default local delivery entry point is `local_work_item_router`

!!! info
    Workflows are not a replacement for skills. A workflow coordinates durable execution over time. A skill shapes how a specific agent task is performed inside one step.

## Quick Links

### Start Here

- [Quickstart](quickstart.md) — run a workflow, inspect progress, and recover from interruption
- [Concepts](concepts.md) — mental model, lifecycle, state, and how workflows relate to skills and rules
- [Definitions](definitions.md) — YAML format, step types, hooks, and validation rules
- [Commands](commands.md) — CLI reference for running and recovering workflows
- [Monitoring](monitoring.md) — CLI progress, events, hooks, REST, and SSE
- [API Reference](api-reference.md) — exact endpoints and SSE parameters

### Related Docs

- [Planning and Execution](../planning-and-execution.md) — how specs, workflows, and missions fit together
- [CLI Skills](../cli/skills.md) — reusable prompt templates for agent tasks
- [Packs & Artifacts](../packs/index.md) — distribute skills, rules, and config across teams
- [Spaces](../spaces/index.md) — activate packs and project context per workspace
- [Specs](../specs/index.md) — structured planning artifacts with approval gates
- [Advanced Architecture](../advanced/architecture.md) — shared engine and runtime context

## Reference Example

The current reference workflow lives at `examples/workflows/issue_delivery.yaml`.

It is included as an example of how to express a real end-to-end process with gates,
runner steps, loops, monitoring hooks, and recovery. It is the generic reference, not the recommended
default for local Claude/Codex delivery. For the highest-quality local issue and PR flow, start with
`examples/workflows/local_work_item_router.yaml`.

`issue_delivery` is not the definition of the
workflow feature itself, and it should not be read as the only kind of workflow the
engine supports.
