Method · The spec pack

The spec pack: constitution, spec, plan, tasks

A spec pack is four versioned documents: the constitution sets the rules, the spec says what each feature must do, the plan says how we build it, and the tasks break it into small, checkable units. Code, tests and reviews all trace back to them.

Updated 22 November 2026

What a spec pack is

A spec pack is the written source of truth for a frontend. It holds four documents in one repository, each versioned like code: a constitution, a spec per feature, a plan and a task list. Nothing is built that the pack does not describe, and every change to scope is a change to the pack first.

We write the pack before any component exists. That order matters. When requirements live in chat threads, tickets and memory, each person carries a slightly different version of the product. The pack replaces those versions with one text that the client, the engineers, the coding agents and the tests all read from.

The pack is also what you own at the end of a Spec Sprint. You can build with us, with another team or in-house. The documents are plain Markdown, so they work with any editor and any tool.

Document Answers Changes when
Constitution What must always be true of this product? Rarely: a new market, a new standard, a new brand rule
Spec What must this feature do, and how do we know? When the feature’s scope changes
Plan How will we build it? When the architecture or an integration changes
Tasks What is the next small, verifiable unit of work? Every day during a build

The constitution: rules that hold for every feature

The constitution lists the non-negotiables for the whole product. It covers accessibility level, performance budget, privacy stance, supported browsers and devices, security baseline and brand rules. Every feature spec inherits it, so no single feature can quietly lower the bar.

A constitution is short. Most fit on two pages. It is written in plain sentences, each one checkable. “The site is fast” is not a rule. “Interaction to Next Paint stays under 200 ms at the 75th percentile on a mid-range phone” is.

# Constitution: member portal

## Accessibility
- WCAG 2.2 AA on every page and state, including errors and empty states.
- Every interactive element is reachable and operable by keyboard alone.

## Performance budget (75th percentile, mid-range phone, 4G)
- LCP ≤ 2.5 s · INP ≤ 200 ms · CLS ≤ 0.1
- JavaScript per route ≤ 170 KB compressed.

## Privacy
- No third-party request before consent. Every storage key is listed in the spec that creates it.
- Every form field maps to a stated purpose.

## Security
- Strict Content Security Policy; no inline scripts without a nonce.
- Session tokens are httpOnly cookies, never readable by scripts.

The constitution is the first document we write, and the constitution template is the one we start from.

The spec: what each feature must do

A feature spec describes one feature completely: who it is for, what they can do, every state the interface can be in, the data it collects and why, and the acceptance criteria that prove it works. If a behaviour is not in the spec, it is not in scope.

The core of each spec is its acceptance criteria, written in Given/When/Then. Each criterion describes one observable behaviour from the user’s side. Each one later becomes an automated test, which is how the spec stays true after the feature ships. We cover how to write them in acceptance criteria for frontends.

# Spec: spending limit · v1.2

## User story
As a member, I want to set a monthly spending limit before my first payment,
so that I stay in control of what I spend.

## States
- No limit set · limit set · limit reached · limit change pending (24 h cool-down)

## Data collected
| Field | Purpose | Retention |
| --- | --- | --- |
| limit_amount | Enforce the member's chosen limit | While the account is open |

## Acceptance criteria
- AC-1 The limit step is shown before payment methods on first checkout.
- AC-2 Skipping requires an explicit "no limit" choice, which is logged.
- AC-3 Raising a limit takes effect after 24 hours; lowering it is immediate.

The spec also names what is out of scope. That list prevents the slow growth of features that nobody priced.

The plan: how we will build it

The plan turns the spec into an engineering approach. It names the components, the design tokens, the rendering strategy for each route, the integrations and the test strategy. It is where architecture decisions are recorded, with the reason for each, so a later team can see why the code looks the way it does.

A plan stays close to the spec. Each section points at the criteria it serves. When a criterion asks for an immediate change on lowering a limit, the plan says which component owns that state, which API call confirms it, and which test proves it.

# Plan: spending limit

## Components
- LimitStep (checkout, before PaymentMethods) · LimitBanner (account header)

## State
- Server is the source of truth; the client shows a pending state until confirmed.

## Integrations
- PATCH /limits (existing API) · audit log event "limit.skipped"

## Tests
- AC-1, AC-2: Playwright, checkout flow
- AC-3: Vitest on the limit reducer + Playwright for the pending banner

## Decisions
- D-4 Limit state is server-owned. Reason: two devices must never disagree.

The tasks: small units that can be verified

Tasks break the plan into units small enough to build, review and verify on their own. Each task links to the acceptance criteria it satisfies. A task without a criterion is not started, because nobody could say when it is done.

Small tasks are what make agent-assisted delivery safe. A coding agent receives one task, its criteria and the relevant part of the plan. A senior engineer reviews the result against those same criteria. The task list is also how progress is reported: done, next and blocked, every week.

# Tasks: spending limit

- [x] T-1 LimitStep component with three options and "no limit" · AC-1, AC-2
- [x] T-2 Log "limit.skipped" on explicit skip · AC-2
- [ ] T-3 Pending state and 24 h cool-down banner · AC-3
- [ ] T-4 Keyboard and screen-reader pass on LimitStep · constitution: accessibility

How the pack stays current

The pack is versioned with the code, so it never drifts into a document nobody reads. A change request becomes a spec change first, then a plan change, then new tasks. In an existing codebase we write these as ADDED, MODIFIED or REMOVED deltas, described in Spec Kit and OpenSpec.

At each release, a trace report shows every acceptance criterion, the test that checks it and its result. The report closes the loop: the pack says what was promised, and the report shows what was delivered.

What you get from it

You get a product that does what was agreed, and a written record that proves it. Scope is visible before you pay for a build. Change requests have a clear price because they are written against a known baseline. And the pack outlives any single team: whoever works on the product next starts from the same documents we did.

Start with a Spec Sprint

One to two weeks to a versioned spec you own, whoever builds it.

Start a Spec Sprint