# Specs

Specs are structured planning artifacts with phased approvals and automatic staleness tracking. They give you a versioned, machine-readable planning layer above workflows — a place to define what you're building, why, and how, with explicit sign-off gates before execution begins.

## Why Specs?

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
- [workflows](../workflows/index.md) for durable multi-step execution

Those pieces work well for execution. Specs add the missing layer for planning that needs:

- structured review before implementation starts
- independent approval of requirements, design, and task breakdown
- automatic detection when upstream changes invalidate downstream approvals
- version history for every content change
- workflow gate integration so execution waits for approval

Common examples:

- gated feature delivery where design must be approved before implementation begins
- team review cycles where requirements and architecture are signed off independently
- compliance workflows that require documented approval of each planning phase

## What's What

| Concept | What it is |
|---|---|
| **Spec** | A YAML artifact with three planning phases, stored in the artifact database with full version history |
| **Phase** | One of `requirements`, `design`, or `tasks` — each approved independently |
| **Phase status** | `draft` (not yet reviewed), `approved` (signed off), or `stale` (approved but upstream content changed) |
| **Invalidation** | Automatic staleness marking when an upstream phase changes after a downstream phase was approved |
| **Spec diff** | A per-phase content diff between two spec versions, with task-level change tracking |
| **Spec gate** | A workflow gate condition that blocks progression until a specific spec phase is approved |

## How It Fits

```text
Spec Content (YAML)
        │
        ▼
  Artifact Database
  (versioned, SHA-256 hashed)
        │
        ├─→ Phase approvals (requirements, design, tasks)
        ├─→ Invalidation engine (auto-stale on upstream changes)
        ├─→ Version diffs
        └─→ Workflow gate conditions
              │
              ▼
        Workflow Engine
        (blocks steps until phases are approved)
```

## Two Interfaces

| Task | CLI | API |
|---|---|---|
| List specs | `/spec list` | `GET /api/specs` |
| Create a spec | `/spec create <ns> <name>` | `POST /api/specs` |
| Show a spec | `/spec show <fqn>` | `GET /api/specs/{fqn}` |
| Approve a phase | `/spec approve <fqn> <phase>` | `POST /api/specs/{fqn}/phases/{phase}/approve` |
| Unapprove a phase | `/spec unapprove <fqn> <phase>` | `POST /api/specs/{fqn}/phases/{phase}/unapprove` |
| View diff | `/spec diff <fqn>` | `GET /api/specs/{fqn}/diff` |
| Check stale status | — | `GET /api/specs/{fqn}/stale` |
| Portfolio dashboard | `/spec dashboard` | `GET /api/specs/dashboard` |

## Current Scope

The spec system today supports:

- **Create** — author a spec via the CLI editor or API
- **Read** — list, show, and inspect specs with phase status badges
- **Approve / unapprove** — sign off on individual phases or reset them
- **Diff** — compare spec versions (requires at least 2 content versions)
- **Workflow gates** — block workflow steps on unapproved phases

Not yet shipped:

- Content editing via CLI or API (content updates are service-internal today)
- Pack distribution for specs (tracked by [#1010](https://github.com/troylar/anteroom/issues/1010))
- Multi-user approval quorum (tracked by [#998](https://github.com/troylar/anteroom/issues/998))

## Quick Links

### Getting Started

- [Quickstart](quickstart.md) — create and approve a spec in under 5 minutes
- [Concepts](concepts.md) — phases, statuses, invalidation, and workflow gate integration

### Reference

- [Commands](commands.md) — CLI reference for all `/spec` subcommands
- [Schema Reference](schema-reference.md) — YAML format, task fields, and validation rules
- [API Reference](api-reference.md) — REST endpoints for spec lifecycle
- [Troubleshooting](troubleshooting.md) — common issues and solutions

### Related Docs

- [Planning and Execution](../planning-and-execution.md) — how specs, workflows, and missions fit together
- [Workflows](../workflows/index.md) — durable multi-step execution that specs can gate
- [Workflow Concepts](../workflows/concepts.md) — how gates work in the workflow engine
