04FEATURES

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.

View .md

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 ⌘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>.

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: 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.

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.