The spec-first template pack (brainstorm → spec → plan files)

The best AI coding upgrade I ever made was a rule, not a model: no code before spec. Every Settl feature runs the same pipeline: a design-only brainstorm → a written spec → an implementation plan with TDD tasks → THEN code. It sounds slow; it's why one person ships app-store products. When I skip it, I get my five-fixes-for-one-bug story. The spec folder in my repo is the real senior engineer.

The three files

1. YYYY-MM-DD-<feature>-brainstorm.md: design-only session. Explicitly NOT allowed to produce code. Questions to close before anything else:

## Problem: who hurts, when, how badly?
## Options considered: at least 2, with the losers and WHY they lost
## Chosen direction: one paragraph
## Out of scope: the list that prevents drive-by features
## Open questions: anything unresolved blocks the spec, not the code

2. YYYY-MM-DD-<feature>-spec.md: what "done" means.

## Behavior: user-visible outcomes, including the AFTER states (undo, delete, retry)
## Wire/data contracts: exact shapes, null-handling, error codes
## Edge cases: enumerated, each one will become a test
## Non-goals: restated from brainstorm
## Feature flag: name + default (OFF)

3. YYYY-MM-DD-<feature>-plan.md: TDD tasks an agent can execute.

Task N: <slice of behavior>
  - Write test <name>; run it; MUST FAIL for reason <expected failure>
  - Implement minimal code to green; run full suite
  - Files touched: <list>   Depends on: Task N-1

The rules that make it work

Each stage gates the next. Open questions in the brainstorm block the spec; fuzzy behavior in the spec blocks the plan; a plan task without a test isn't a task.
Agents get the plan, never the idea. "Build me X" produces confident wrong code. A plan of failing-test-first tasks produces verifiable increments. This is the difference between prompt-and-pray and engineering.
Specs are living, dated, and kept. The folder of past specs is searchable context, for you and for every future agent session ("read the spec before touching the data layer" is a repo rule for me).
Skipping is allowed, consciously, for tiny changes. Typos and copy edits don't need the pipeline. The tell you should NOT have skipped: your second failed fix on the same bug (see settl.fyi/social/five-fixes-wrong-layer).
Design decisions get made once, in writing. Mid-implementation "wait, should this be a sheet or a screen?" means the brainstorm was skipped. Pause, write it down, resume.

Steal this for your app

The pipeline is model-agnostic: it upgrades every agent you'll ever use, because it converts ambiguity (where models flail) into verification (where they excel).
Start with just the spec file if three feels heavy. Even one page of "done means / edge cases / out of scope" kills most wrong-code-fast disasters.
Date-prefix everything and never delete: your spec folder becomes the institutional memory a solo founder otherwise doesn't have.

Run this on your codebase

Paste this into Claude Code in your repo:

Audit this repo for code that shipped without a spec.
Find any specs, plans, or brainstorm docs folder; note its naming convention and how recent it is.
Map recent features from git history to spec files; flag features with code but no written spec or plan.
Check specs for done-means behavior, wire contracts, enumerated edge cases, non-goals, and a named feature flag defaulting OFF; flag missing sections.
Check plans for TDD-shaped tasks (test name, expected failure, files touched); flag plan tasks with no test.
Flag bugs fixed more than once in history, the tell that the pipeline was skipped.
Report findings as a checklist before changing anything.

R093: add a scope-change ledger

The original done state is the baseline. Without it, "nearly done" can survive for weeks because every new request quietly changes the finish line.

Keep this ledger beside the active implementation plan:

| Requested addition | Evidence or reason | Work or date displaced |
| Time impact | Approver | Decision | Revised done state |

Run every addition through four questions:

Is this required by the approved spec or genuinely new?
Which accepted task, non-goal, or delivery date changes if we take it now?
Who owns the product decision?
What exact done state replaces the old one?

"It is small" is not an answer. Ask for the touched files, tests, migration, copy, analytics, and rollout work before accepting the claim. If the addition has value but does not belong now, move it to deferred work with its evidence link. Do not leave it as a comment inside an active task.

Use this with Claude Code:

Compare the requested addition with the approved spec and implementation plan.
Return: in-scope or new, evidence, affected tasks, displaced commitment,
time impact, approval owner, and revised done state.
Do not edit the plan or code. If no tradeoff is named, return BLOCKED.

Comment CREEP for this module.

Download the runnable scope-control pack

The starter turns a fictional spec, plan, and addition into a reviewable scope ledger. It does not edit the plan or approve the change.