# Concepts

Specs are Anteroom's structured planning layer: they define what you're building, why, and how, with independent approval gates and automatic staleness tracking.

## The Mental Model

Think in layers:

| Layer | Purpose | Good for | Not good for |
|---|---|---|---|
| **Skill** | Reusable prompt template | `/commit`, `/review`, domain-specific expert behavior | structured planning |
| **Rule** | Always-on guidance or policy | coding standards, security constraints | step sequencing or approvals |
| **Spec** | Structured planning with approvals | gated review, requirement traceability, team sign-off | durable execution state |
| **Workflow** | Multi-step orchestration with persistence | retries, recovery, monitoring, target locking | free-form one-off chat |

If you want a one-command prompt shortcut, use a skill.
If you want policy applied every time, use a rule.
If you want structured planning with phased approvals, use a spec.
If you want durable step-by-step execution, use a workflow.

Specs and workflows work together: a spec defines the plan, and workflow gates can block execution until the plan is approved.

## Three Phases

Every spec has exactly three phases:

### requirements

What the feature must accomplish. This is the "what" and "why" — acceptance criteria, constraints, user stories, or business rules.

### design

The technical approach. This is the "how" — architecture decisions, API contracts, data models, or integration patterns.

### tasks

The actionable work breakdown. Each task has an `id`, a `summary`, and optional `depends_on` references to other tasks in the same spec. See [Schema Reference](schema-reference.md) for the full task format.

The three phases form a natural dependency chain: requirements inform design, and design informs tasks. The [invalidation rules](#invalidation-rules) enforce this ordering.

## Phase Statuses

Each phase has one of three statuses:

| Status | Meaning | How it happens |
|---|---|---|
| `draft` | Not yet reviewed | Initial state, or reset via `unapprove` |
| `approved` | Signed off | Set via `/spec approve` or `POST .../approve` |
| `stale` | Was approved, but upstream content changed | Set automatically by invalidation rules |

Status transitions:

```text
draft ──approve──→ approved ──invalidation──→ stale
  ↑                                            │
  └──────────────unapprove─────────────────────┘
```

A `stale` phase preserves its original approval metadata (`approved_at`, `approved_by`, `approved_at_version`) so you can see when and by whom it was last approved, and which version it was approved at.

## Invalidation Rules

When spec content changes, the invalidation engine automatically marks downstream phases as stale. This is deterministic — the same content change always produces the same staleness result.

Three rules:

| Rule | Trigger | Effect |
|---|---|---|
| 1 | Requirements changed | Design becomes stale (if approved) |
| 2 | Requirements changed | Tasks becomes stale (if approved) |
| 3 | Design changed | Tasks becomes stale (if approved) |

Only `approved` phases can become stale. `draft` phases are unaffected.

The logic follows the natural dependency chain: requirements are upstream of design, and both are upstream of tasks. If you change the foundation, downstream approvals are no longer valid.

!!! info
    Content updates are supported via `/spec edit` in the CLI and `PATCH /api/specs/{fqn}` in the API. Both create a new version when the content hash changes, triggering the invalidation rules above.

## Version History

Every content change to a spec creates a new version. Versions are numbered sequentially starting at 1.

Content changes are detected by SHA-256 hash comparison — metadata-only updates (like approving a phase) do not create new versions.

When a phase is approved, Anteroom records the `approved_at_version`. This is used later to derive stale reasons: if the current version differs from the approved version, the invalidation engine can identify exactly which upstream phases changed.

## Workflow Gates

Specs integrate with the [workflow engine](../workflows/concepts.md) through gate conditions. Three built-in gate conditions are registered automatically:

| Gate condition | Blocks until |
|---|---|
| `spec_requirements_approved` | The spec's requirements phase is `approved` |
| `spec_design_approved` | The spec's design phase is `approved` |
| `spec_tasks_approved` | The spec's tasks phase is `approved` |

To use spec gates in a workflow definition, provide `spec_fqn` in the workflow inputs:

```yaml title="workflow.yaml"
kind: workflow
id: gated_delivery
version: 0.1.0

inputs:
  - name: spec_fqn
    required: true

steps:
  - id: check_requirements
    type: gate
    condition: spec_requirements_approved

  - id: check_design
    type: gate
    condition: spec_design_approved

  - id: implement
    type: runner
    runner: cli_claude
    prompt: "Implement the tasks from the approved spec."
```

Run it with:

```bash
aroom workflow run gated_delivery --spec_fqn @myapp/spec/api-design
```

The workflow will pause at each gate step until the corresponding spec phase is approved.

## Specs and Other Primitives

### Skills

Skills shape how a specific agent task is performed. A workflow step might use a skill-based prompt to implement a spec task, but the spec itself is not a skill — it's the plan that the skill helps execute.

### Rules

Rules constrain behavior during execution. A security rule might prevent an agent from writing unsafe code while implementing a spec task, but the rule doesn't know about specs — it just shapes agent behavior.

### Workflows

Workflows orchestrate durable execution. Specs provide the structured plan that workflows can gate on. The clean split: specs define what to build, workflows coordinate how to build it.

## Current Limits

The spec system is still evolving. Current limitations:

- **No web UI spec detail page** — specs are displayed in the generic artifacts panel only. A dedicated specs interface is tracked by [#1000](https://github.com/troylar/anteroom/issues/1000).
- **Conformance checks are on-demand only** — there is no automatic post-run verification yet. Use `/spec conformance` or `POST /api/specs/{fqn}/conformance` to check manually.
- **Single-user approval** — any user can approve any phase. Multi-user approval with quorum is tracked by [#998](https://github.com/troylar/anteroom/issues/998).

## See Also

- [Quickstart](quickstart.md)
- [Commands](commands.md)
- [Schema Reference](schema-reference.md)
- [API Reference](api-reference.md)
- [Workflow Concepts](../workflows/concepts.md)
