/gaia-spec

/gaia-spec turns a feature idea into a SPEC through a guided conversation. A SPEC is a written description of what to build and how to test it, locked once saved. The command then plans the SPEC in the same session with /gaia-plan and ends at the plan’s KICKOFF prompt. It never writes the code itself: the building starts in a fresh session.

The SPEC and its plan are saved in the Notebook.

When to use it

Run /gaia-spec for a feature whose scope is not clear yet: the description raises more questions than it answers, or two people could read it and picture different features. It is also the way to present an idea and refine it before any code is written.

For changes whose goal is already obvious (a bug fix, a refactor of known code, a copy edit), just prompt Claude, or go straight to /gaia-plan.

How to invoke

Interactive (most common)

/gaia-spec your feature description

Claude asks you a series of questions to settle what you want. Any question with a fixed set of answers is a menu, with the recommended option first and a Discuss this option to talk it through.

Auto mode

/gaia-spec auto your feature description

Claude answers its own questions, picking the recommended option each time, and proceeds without stopping. It skips the model check, checks both gates itself instead of showing them to you, and always starts a new SPEC instead of resuming a draft. Use it when the description is already complete, or when you keep picking the recommended option anyway. A description is required: without one, auto mode stops at once. Anything it could not settle is written down as an open question for you to review.

Auto mode carries into the plan: the SPEC is planned with /gaia-plan auto, so the whole run finishes without asking you anything.

A description whose first word is “auto” is always read as auto mode, so reword one that starts with that word.

What gets produced

Everything lands in .notebook/specs/SPEC-NNN/:

File	Purpose
SPEC.md	The locked SPEC: the intent, the success criteria, the UATs, the scope rules (what must always happen, what needs your approval first, what must never happen), the decisions settled during the conversation with their reasons, and a summary of any research.
AUDIT.md	The SPEC audit’s report: instructions the plan must follow, the fixes folded into the SPEC, and the findings that were disproved.
plan/	The plan, written by /gaia-plan in the same session.

UATs

A UAT (user acceptance test) is an automated acceptance test written into the SPEC. No person runs it. Each one has three parts:

• Given: the starting state
• When: one action, by the user or the system
• Then: an outcome a test can check, with no “should” and no hedging

Writing them is this command’s job. Claude proposes them at gate 1, before asking any questions, and you confirm or change them. The questions that follow refine them, and the SPEC audit tries to find a way each one could pass while the feature is still broken.

Once the SPEC is saved, the UATs are the contract. /gaia-plan turns them into tests, and changing one means formally reopening the SPEC.

Before it starts

• Model check. The SPEC is written by your session’s model. On a model other than Opus or Fable, Claude offers to stop so you can switch with /model first.
• Housekeeping. Notebook entries GAIA no longer needs are cleared out. See How entries are cleared.
• Pull check. When your checkout has an older GAIA version than the remote, Claude offers to pull first.
• Resume. When an unfinished draft exists, you choose to resume it or start new. Claude can tell when another open session is still writing a draft, so two sessions never resume the same one.

SPEC numbers

Each SPEC number is reserved by pushing a spec/NNN git tag to the remote, so teammates never get the same number. Reserving one changes no files in your checkout. See Numbers do not travel for what happens with no remote.

A SPEC moves through four statuses: draft, ready, merged, and abandoned.

The flow

1. Reserve the SPEC number and write the first draft.
2. Gate 1: shape. Before asking anything, Claude prints in plain language what it thinks you want and every proposed UAT. You confirm or revise. Claude keeps a copy of what you confirmed so later steps can catch the SPEC drifting away from it.
3. Questions. One question at a time, each based on your last answer. The questions stop once every topic is settled, or at most after 10 real questions (5 in auto mode). When Claude needs facts, it runs the research itself and brings you the findings.
4. Self-review. A sub-agent checks that the draft still matches what you confirmed at gate 1 and does not contradict itself. It fixes minor problems itself. Critical and major problems come to you as one list, each with its recommended fix, and you answer once: accept all as recommended, or revise the ones you name.
5. SPEC audit. Independent reviewers check the draft against your actual code. See The SPEC audit.
6. Gate 2: the brief. Claude prints a brief of the final SPEC: what it changes, why, what success looks like, every UAT, what the plan will do because of the audit, the costs and risks you are accepting, and anything still not settled. The paths to the full draft and to AUDIT.md sit at the bottom if you want to read them. Revise until it is right.
7. Save to the notebook, then run a lint that enforces the lock.
8. Plan it here. /gaia-spec invokes /gaia-plan with the SPEC in the same session. The run ends at the plan’s report: a cost box and the KICKOFF prompt to paste into a fresh session.

Caution

Confirming gate 2 saves the SPEC and locks it. To change a saved SPEC you must formally reopen it, with a written reason and a record of how the UATs change, and the lint enforces this. Get it right before you confirm.

Reopening a saved SPEC

When a plan stops because a UAT can no longer hold, reopen the SPEC:

/gaia-spec reopen SPEC-<NNN>

Claude asks why the UAT cannot hold, starting from the change the stopped plan suggested. It then proposes the new UAT text, together with any change to the plan that follows from it, and asks you to confirm. It records your reason and the old UAT text in the SPEC, checks the SPEC with the lint, and offers to discard the stopped phase’s unfinished edits so the plan can resume. It ends by giving you the plan’s KICKOFF prompt to paste into a fresh session.

The SPEC audit

Before gate 2, a team of reviewers checks the draft. Each one is a fresh sub-agent that reads your code and the draft for itself, so it checks the SPEC against what is really there, not against what the conversation assumed. The audit runs on every SPEC, and you cannot skip it.

The SPEC audit

How hard it looks

Claude first sizes up the draft. A low-stakes SPEC with a narrow scope gets the Standard audit. A high-stakes one, or one that touches security or a data migration, gets the Deep audit.

The lenses

Each reviewer looks through one lens. GAIA names each lens with a short code, such as COV, when it starts the audit and in each finding’s id. Four core lenses run on every SPEC:

Lens	What it checks
(FG) Factual grounding	Every claim about your code, a dependency, a file path, or an existing convention is true. A new dependency is justified and its version pinned.
(TST) UAT testability	Each UAT can fail. The reviewer looks for a way a UAT passes while the feature is still broken, and proposes a tighter one.
(COV) Coverage and consistency	Every success criterion has a UAT, every promise in the intent is covered, the scope rules do not contradict the UATs, and the SPEC follows your project’s conventions.
(RT) Red team and feasibility	The reviewer tries to break the SPEC: a way every UAT passes yet the feature is not delivered, a check that cannot actually run, a file or caller the SPEC missed, an assumption the plan would inherit as fact.

Specialist lenses join when the draft touches their area:

Lens	Joins when the SPEC touches
(SEC) Security	Sign-in, tokens or secrets, redirects, uploads, permissions, personal data, raw user input, headers, cookies
(MIG) Migration	Data formats or schemas, renamed or removed fields, breaking API changes
(A11Y) Accessibility	Components, routes, pages, anything that renders on screen
(DOC) Documentation	Wiki or docs deliverables
(PERF) Performance	Data volume, loops over collections, network calls, caching, rendering

Refutation

Every critical or major finding then goes to a separate reviewer whose job is to disprove it. That reviewer rejects the finding unless it can show the problem in the code or the draft, which keeps false alarms and inflated severities out of your SPEC.

On the Deep audit, three reviewers try to disprove each finding, each from a different angle: correctness, security, and whether the problem actually happens as described. A finding stays only if at least two of the three fail to disprove it. A completeness reviewer then looks for anything every lens missed.

When the lenses raise a very large number of findings (more than 24 critical or major ones on the Standard audit, more than 8 on the Deep audit), one reviewer per lens checks all of that lens’s findings instead, and the completeness review is skipped. That keeps the number of reviewers fixed, so the audit’s time and token cost do not climb with every extra finding. Little is lost: with that many findings, several lenses have usually raised the same problem on their own, which already cross-checks it, and that much volume already covers the gaps a completeness reviewer would hunt for.

What happens to a finding that survives

Each surviving finding is one of two kinds:

• The SPEC itself is wrong: a UAT that could pass on broken code, a missing UAT, or a wrong intent. The fix goes into the draft. Critical and major fixes come to you as one list to accept or revise. Minor ones are folded in without asking.
• The SPEC is right, but the build needs steering: for example, a file the change must also update. The finding is written into AUDIT.md as an instruction, and the plan must follow it.

The draft is not saved yet, so none of this needs a formal reopening. Gate 2’s brief tells you what the plan will do because of the audit.

In auto mode, a clear-cut fix is applied, and a finding with more than one reasonable fix is left open for you to review.

If Claude cannot start sub-agents in your session, the audit is skipped, the self-review is the safety net, and gate 2’s brief says the audit did not run.

While a spec session runs

• It writes only to the notebook and GAIA’s local files: .notebook/specs/, .gaia/local/cache/, and the usage ledger. It never edits frontend/app/** or any other source. Because nothing it writes is tracked, you can keep working in other sessions while it runs, on a branch or in a worktree.
• Project decisions go into the SPEC, the wiki, or .claude/rules/, never into machine-local memory.
• Your progress is saved as you go, after every answer and every gate. To stop, type a save request (such as “save partial” or “resume later”) into a question’s Other answer, or choose to save from inside Discuss this. The next /gaia-spec offers to resume.
• Long sessions pause when the context reaches the red band, like any other: Claude saves, then you continue here or clear and resume. See Work lifecycle.

After the plan runs

Before it writes any code, the plan’s orchestrator turns the UATs into tests that fail at first. It closes out the SPEC after the implementation merges. See /gaia-plan.

The run ends with a cost box covering the spec and the plan.