# Planning and Execution

Anteroom separates planning from execution. Specs define what to build and get sign-off. Workflows execute the work with durable state and recovery. Missions sit between them as the orchestration layer that turns an approved plan into a coordinated execution strategy.

## The three layers

| Layer | Role | Shipped? | Good for | Not good for |
|---|---|---|---|---|
| **Spec** | Structured planning with phased approvals | Yes | gated review, requirement traceability, team sign-off | durable execution, runtime decisions |
| **Mission** | Orchestration --- turns intent into an execution plan | Yes (CLI) | coordinating workflows, replanning, dependency management | defining requirements, running steps |
| **Workflow** | Durable multi-step execution with persistence | Yes | retries, recovery, monitoring, target locking | deciding what to build, free-form chat |

## When to use what

If you want structured planning with independent phase approvals, use a **spec**.
If you want durable step-by-step execution with resume and monitoring, use a **workflow**.
If you want an AI-driven execution plan that coordinates workflows, subagents, and tools across a larger goal, use a **mission**.

Specs and workflows compose directly: a spec defines the plan, and workflow gate steps block execution until specific spec phases are approved. Missions sit between the two --- reading from an approved spec (or a free-form prompt) and orchestrating one or more workflow runs.

## How they compose

```text
Spec (planning)
    │
    ├─→ requirements ──approve──→ design ──approve──→ tasks ──approve──→
    │
    ▼
Mission (orchestration)
    │
    ├─→ gathers context (artifacts, code, available workflows)
    ├─→ produces a versioned execution plan with dependencies
    ├─→ dispatches work items to workflows, subagents, or tools
    │
    ▼
Workflow (execution)
    │
    ├─→ runner steps (agent, shell, python_script)
    ├─→ gate steps (including spec phase gates)
    ├─→ loops, parallel branches, compensation
    └─→ durable state, resume, monitoring, hooks
```

Specs and workflows also compose directly without a mission:

```text
Spec ──phase approvals──→ Workflow (gate steps check spec phase status)
```

## End-to-end example: gated feature delivery

### Spec + workflow (direct)

1. **Create a spec** with requirements, design, and task breakdown:

    ```bash
    /spec create myteam feature-x
    ```

2. **Review and approve each phase** independently:

    ```bash
    /spec approve @myteam/spec/feature-x requirements
    /spec approve @myteam/spec/feature-x design
    /spec approve @myteam/spec/feature-x tasks
    ```

3. **Run a workflow** that gates on spec approval. The workflow definition includes gate steps like:

    ```yaml
    steps:
      - id: check_design
        type: gate
        condition: spec_design_approved
    ```

    The gate blocks until the design phase is approved, then execution continues through runner steps that implement the work.

4. **Launch from a spec task** to bind a specific task to a workflow run:

    ```bash
    /spec launch @myteam/spec/feature-x task-1 issue_delivery
    ```

### Spec + mission + workflow (orchestrated)

1. Create and approve a spec (same as above).
2. **Create a mission** from the approved spec:

    ```bash
    aroom mission create --spec @myteam/spec/feature-x --adapter workflow --workflow-path defs/build.yaml --launch
    # Or use a profile for automatic workflow selection:
    aroom mission create --spec @myteam/spec/feature-x --profile parallel-review --launch
    ```

3. The mission reads the approved spec and gathers context --- available workflows, prior state, artifact references. When using `--profile`, the compiler discovers available workflows, scores them against the profile, and auto-selects the best fit.
4. The mission produces a **versioned execution plan** with work items, dependencies, and execution bindings.
5. The mission dispatches items to workflows via the WorkflowAdapter, scheduling eligible items as their dependencies complete.
6. **Steer the mission** conversationally as work progresses:

    ```bash
    aroom mission talk <session_id>
    ```

7. Each workflow run still gates on spec phase approval --- the mission coordinates, but does not bypass governance.

## Scope boundaries

Each layer has a clear boundary:

- **Specs** are planning artifacts. They store requirements, design, and tasks with version history and approval gates. They do not execute code, manage runtime state, or make decisions about how work runs.
- **Workflows** are execution engines. They run steps, manage durable state, handle retries and recovery, and report progress. They do not decide what to build or whether a plan is ready.
- **Missions** are orchestrators. They translate approved plans into coordinated execution strategies. They do not replace specs for planning or workflows for execution --- they connect the two.

!!! info
    Mission V1 is CLI-first. Web UI mission steering is planned for a future release.

## Current state

| Capability | Status | Where to learn more |
|---|---|---|
| Spec create, approve, diff | Shipped | [Specs](specs/index.md) |
| Spec invalidation and staleness | Shipped | [Spec concepts](specs/concepts.md) |
| Workflow execution with gates, loops, parallel | Shipped | [Workflows](workflows/index.md) |
| Spec gate conditions in workflows | Shipped | [Workflow concepts](workflows/concepts.md) |
| Launch workflow from spec task | Shipped | [Spec commands](specs/commands.md) |
| Mission create, list, status, update, cancel | Shipped (CLI) | [Missions](missions/index.md) |
| Mission conversational steering | Shipped (CLI) | [Missions](missions/index.md) |
| Mission web UI | Planned | --- |

## See also

- [Specs](specs/index.md) --- structured planning with phased approvals
- [Spec concepts](specs/concepts.md) --- phases, invalidation, and the four-layer mental model
- [Workflows](workflows/index.md) --- durable multi-step execution
- [Workflow concepts](workflows/concepts.md) --- lifecycle, gates, and how workflows relate to specs
- [Missions](missions/index.md) --- orchestration above workflows
