# Specs and plans

Write the work down before the agent writes code - versioned plans for most work, phased specs with testable requirements for work that has to be right.

Agents build what they were told, and they fill any gap in the ask with a guess. Plans and specs close the gap before any code is written. Both live in your repository under `.warden/`, so they are reviewed, versioned and shared like code.

Open them from a project's **Planning** tab, or with {{kbd:⌘+K}} → **Plans** / **Specs** (`c p` and `c s` start a new one).

## Plans

A plan is a document the agent works from: the approach, the steps, the risks.

- **Draft with Planner** writes it from your description, using the *Planning & architecture* model.
- Comment on it and choose **Revise with comments**: each revision is a new version (v1, v2…), kept side by side.
- **Approve** the version you are happy with, then **Implement plan**: the agent builds it in a chat with `/implement-plan <slug>`.

```bash title="On disk"
.warden/plans/rate-limit-login/
  meta.json      # title, status, the approved version
  v1.md
  v2.md
```

## Specs

A spec is for work that has to be right. It has up to three phases, each approved before the next unlocks:

| Phase | Says | Written as |
|---|---|---|
| **Requirements** | What and why: the problem, who it is for, the behaviour, non-goals. A bug gets current, expected and how to reproduce. | Testable behaviour statements: *When a user fails to log in five times, the system shall refuse further attempts for 15 minutes.* |
| **Design** | How: the approach, and the **invariants**, the things that must always hold. | Prose, plus invariants Warden can check. |
| **Tasks** | The steps to build it, in phases. | A checklist the agent works through. |

How many phases a spec needs depends on its [assurance level](assurance): **tasks only at L1**, **requirements and tasks at L2**, **all three at L3 and L4**.

Build a spec with `/implement-spec <slug>` (add `next`, `all` or a phase such as `P3`). The agent works phase by phase, and a live checklist sits above the composer.

```bash title="On disk"
.warden/specs/rate-limit-login/
  meta.json         # level, status of each phase
  requirements.md
  design.md
  tasks.md
  invariants.json
  coverage.json     # which test checks which requirement
```

### Checks that correspond to the spec

Each requirement and invariant is linked to the check (a test, a property, a proof) that shows it holds, recorded in `coverage.json`. **Run checks** on the spec runs the linked checks of the phases built so far, and they run again after the agent's turns. Warden's spec validation flags a requirement with no linked check, so the spec and the checks stay in step.

Things the agent finds during the build that are outside the spec go on a **Found during build** worklist. At L2 an open item is a warning at Verify; at L3 and above it fails Verify until it is dealt with.

## Plans and specs in the Software Factory

The Factory's **Shape** stage drafts a plan (Standard lane) or a spec (Assured lane) for each item, and waits for a person to approve it. **Send to Factory** puts an existing plan or spec on the line. See [What each stage means](factory-stages#shape).