Specflo Spec

---
name: specflo-spec
description: Use at a specflo project's spec phase, when turning a validated brainstorm into a structured, testable spec before any plan or code. Triggers include "write the spec", "let's spec this out", or `specflo status` showing the spec phase. Do NOT use for trivial fixes or before a brainstorm has been validated.
---

# Spec (specflo)

## Overview

Turn a validated `brainstorm.md` into a **validated `spec.md`** for the active
specflo project: an objective, numbered **testable `REQ-NN` requirements** (each
with a pass/fail acceptance criterion, traced to the `D-NN` decision it derives
from), explicit in/out boundaries, and open questions — then hand off toward the
plan phase. The `specflo` CLI does the artifact I/O; you carry the synthesis,
judgment, and discipline.

## When to use / When NOT

**Use** at the spec phase (the second of `brainstorm → spec → plan → execute`),
once the brainstorm is validated. The spec is a **synthesis of the brainstorm,
not a new interview** — read `brainstorm.md` and write requirements; do not
re-litigate settled decisions.

**Do NOT use** for trivial fixes, or before a brainstorm exists and passes
`specflo validate brainstorm`. If the brainstorm is incomplete, finish it first.

## HARD-GATE

Do NOT write code, scaffold anything, or take any implementation action until the
spec is validated (`specflo validate spec` passes) and the user has explicitly
approved. The discipline here is the **rigor of the artifact** — testable
requirements with pass/fail acceptance — not merely "don't code yet".

## Process

1. **Preflight.** Confirm an active project at the spec phase (`specflo status`).
   Run `specflo spec start` to create or locate `spec.md` (the command prints its
   locator, `<project>/spec` — never build a path yourself). Read the brainstorm
   with `specflo doc show brainstorm`: its Decisions (`D-NN`), Research, Current
   understanding, and Out of scope.
2. **Draft requirements — translate decisions, reframe vague → testable.** For
   each thing the system must do, write a falsifiable requirement. Two moves:
   - **Decision → behavior.** Brainstorm decisions are often *architecture or
     tech-stack* choices ("build on SDK X", "UI in framework Y"), not behaviors —
     and have no inherent pass/fail. Make each testable by spec'ing the
     **behaviors it exists to enable**, and expect one decision to **fan out into
     several requirements** (e.g. "build on the SDK" → separate auth, discovery,
     and version-compatibility requirements, each `--from` that decision).
   - **Reframe fuzzy wants:** `"make it fast"` →
     `"the landscape scan returns within 5s on a warm cache"`, then ask "are these
     the right targets?".
   A good requirement is **✓** "API responds in < 200ms at p95"; a bad one is
   **✗** "the system should be fast".
3. **Give every requirement a pass/fail acceptance criterion.** No subjective
   criteria — write how a verifier confirms it. The check may be **behavioral**
   (observe the running system) or **structural** (a source- or dependency-scan)
   — both are valid as long as the verdict is mechanical. An architectural
   constraint ("all server I/O goes through the SDK; no hand-rolled client") is
   legitimately verified structurally; don't contort it into a fake runtime test.
   Trace it to the decision it comes from with `--from D-NN` where applicable.
4. **Capture inline.** The moment a requirement is settled, record it:
   `specflo requirement add --text "…" --acceptance "…" [--from D-NN]`
   (add `--supersedes REQ-NN` when it replaces an earlier one). Don't batch —
   capture as they happen. **Emit artifact-writing add calls sequentially: one
   at a time, never batched in parallel.** The CLI's advisory lock (D-01) makes
   concurrent adds safe but cannot fix ordering — minted `REQ-NN` IDs follow
   execution order, so parallel emission can record IDs out of authoring order.
   Keep the prose sections (Objective, In scope, Out of scope, Open questions,
   Canonical refs) current with `specflo section set spec "<section>" --file
   <path>` (or `--stdin`): it replaces that one section's body and leaves every
   requirement untouched. Never open `spec.md` in an editor — the CLI is the
   only way in, and the Requirements section is refused there (it belongs to
   `requirement add`).
5. **Hold the scope boundary.** Fill **Boundaries** — In scope and Out of scope —
   carrying the brainstorm's Out of scope / Deferred forward. Both lists must be
   non-empty.
6. **No stale specifics.** The spec is behavioral and durable: no file paths or
   code snippets that churn. One exception — a small prototype snippet that
   encodes a decision more precisely than prose can (a schema or type shape).
7. **Self-review.** Re-read the spec (`specflo doc show spec`) with fresh eyes: placeholder scan; internal
   consistency (do requirements contradict?); two-way ambiguity (pick one reading
   and make it explicit); scope (one plan, or should this decompose?).
8. **Gate + validate.** Ask the user an explicit "ready?". On yes, run
   `specflo validate spec`; fix any reported gaps inline and re-run until it
   passes.
9. **Hand off — pause at the phase boundary.** Surface the end of the phase as one
   clear beat, and **do not auto-advance**: the spec is complete and validated, the
   **checkpoint is saved** (the project's `checkpoint.md`; resume any time with
   `specflo checkpoint`), so this is a **safe place to clear context**. The plan
   phase is next (it synthesizes from `spec.md` and cites `REQ-NN` — no
   re-interview). Then **wait** — `specflo advance` is the user's to call; don't
   change the phase yourself or start the plan.

   **Auto-mode carve-out.** The pause-and-wait above is the *manual* default.
   Under an opt-in `specflo auto` run, the auto-mode bootstrap's **boundary
   override** (marked `== specflo auto-mode bootstrap ==`) supersedes it — once
   the phase validates, advance across `brainstorm → spec → plan → execute` on
   your own without pausing here. This carve-out applies only under that
   bootstrap; absent it, pause as above.

## Fast level

When `specflo status` shows `Level: fast`, this skill runs short:

- **You make the decisions.** At most 3, recorded with `specflo decision add`.
  For each, weigh 2 or 3 approaches, pick one, and put the approaches weighed
  and why you chose that one in the `--rationale`.
- **Do not interview the user,** and **do not pause** at the phase boundary:
  once the phase validates, run `specflo advance` and go on, from brainstorm to
  spec to plan.
- **Deferred work** goes in the brainstorm's Out of scope / Deferred section.
- **Caps:** 3 decisions and 7 tasks. A cap only warns: finish the work already
  recorded, add no more, and put new work in the brainstorm's Out of scope /
  Deferred section. Do not move the project up; the user chose fast.
- **One approval, before execute.** When the plan validates, stop. Show the
  user `specflo doc show brief` and list every choice you made that they have
  not seen: each decision, and any requirement or task beyond what they asked
  for. Run `specflo advance` into execute only after they approve.

Write one requirement per acceptance check; these are the checks the user approves.

## Anti-sycophancy

Take a position on every requirement and state what evidence would change it.
Avoid filler validation: "That's a great requirement," "That could work," "There
are many ways to think about this." Challenge the strongest version of the
user's intent, not a strawman. If a requirement isn't testable, say so and
reframe it.

## Common rationalizations

| Rationalization | Reality |
|---|---|
| "The brainstorm is enough." | The brainstorm captures *decisions*, not *testable requirements*. The spec adds acceptance criteria a verifier can check. |
| "A tech-stack decision isn't a requirement." | It is — spec the *behaviors* it exists to enable. One decision usually fans out into several testable requirements, each `--from` it. |
| "I'll write the acceptance after I code it." | That's a test report, not a specification. Decide pass/fail *before* building. |
| "This requirement is obviously testable." | If you can't state the pass/fail check in one line, it isn't. Write the line. |
| "I'll re-ask the user to be safe." | Re-interviewing is not synthesis. Read the brainstorm (`specflo doc show brainstorm`); only ask about genuine gaps. |
| "Boundaries are obvious." | Unwritten scope is where plans balloon. Write In and Out explicitly. |

## Red flags (stop and correct)

- A requirement has no pass/fail acceptance criterion.
- You wrote a requirement into chat prose instead of `specflo requirement add`.
- You re-interviewed the user on something the brainstorm already decided.
- You put file paths or churn-prone code snippets into `spec.md`.
- You moved toward the plan without an explicit user "ready?" and a passing
  `specflo validate spec`.
- You built or scaffolded something during the spec phase.

## Verification checklist

- [ ] `specflo spec start` was run; `spec.md` exists for the active project.
- [ ] Every requirement is in the Requirements section via `specflo requirement add`.
- [ ] Every prose section was written with `specflo section set`, never by editing the file.
- [ ] Every requirement has a pass/fail **Acceptance** criterion.
- [ ] **Boundaries** — In scope and Out of scope — are both filled in.
- [ ] **Open questions** is present (may say "none").
- [ ] `specflo validate spec` passes.
- [ ] The user explicitly approved readiness before handoff.
- [ ] At hand-off, the checkpoint-saved phase-end beat was surfaced and `specflo advance` was left to the user.
- [ ] No code or scaffolding was produced.