# Spec

A structured specification artifact that tracks requirements, design, and implementation tasks through an approval lifecycle.

**Content format**: YAML with `requirements`, `design`, and `tasks` fields (see [Spec Schema Reference](../../specs/schema-reference.md)).

**How Anteroom uses it**: Specs drive the spec lifecycle -- each spec has three phases (requirements, design, tasks) that move through draft/approved/stale states. Tasks can launch workflow runs. Spec gates in workflows check phase approval status before proceeding.

**Pack ownership behavior**:

- **Content is read-only** -- pack-owned specs cannot have their YAML content edited or be deleted via the API or CLI. The pack is the source of truth
- **Approval and unapproval work normally** -- these are metadata-only operations that don't modify the spec content
- **Pack refresh triggers invalidation** -- when a pack source repo updates and the spec content changes, the invalidation rules run (downstream phases become stale if upstream content changed since approval)

**Example**:

```yaml title="specs/api-design.yaml"
mode: feature
requirements: |
  Users must be able to CRUD API resources via REST endpoints.
design: |
  FastAPI router with Pydantic models. SQLite storage.
tasks:
  - id: setup-router
    summary: Create FastAPI router skeleton
  - id: add-models
    summary: Define Pydantic request/response models
  - id: implement-crud
    summary: Implement CRUD endpoints
    depends_on: [setup-router, add-models]
  - id: write-api-docs
    summary: Document the REST API endpoints
    item_type: docs
    depends_on: [implement-crud]
```

Each task supports an optional `item_type` field (default `task`) that classifies the work: `task`, `docs`, `research`, `review`, `manual`, or `verification`. Non-coding types default to the `noop` adapter so operators can choose appropriate bindings.

**Directory**: `specs/`

**Common mistakes**:

- Forgetting that pack-owned specs are read-only (use approval/unapproval to manage state)
- Creating circular task dependencies (the validator rejects these)
- Using duplicate task IDs within the same spec
