ADR-002: Capability specs are organized by capability/domain, not by ticket or page


Status	Accepted
Date	2026-07-07
Author	Łukasz Bodurka
Tags	methodology, specs

Context

A capability spec needs one organizing axis. Three candidates recur - and the wrong one keeps coming back in practice (a consumer's align produced specs/cms/001-core/, Spec Kit's ticket numbering leaking in). This records the axis and the rejected forms so it is not re-litigated.

Decision drivers

A spec is the long-lived truth of a domain, not a per-change artifact.
A cross-cutting concept must have exactly one canonical home.
Coding agents file these - the axis must be unambiguous and mechanically guardable.

Options considered

Per-ticket / Spec Kit NNN-feature/ - disposable, re-created per branch; maps to changes, not to living truth. (Leaked as specs/cms/001-core/ in a real align.)
Per-page / route (pdp/, checkout/) - a concept like packages spans the homepage, PDP and checkout, so per-page specs duplicate it across pages and drift.
Per-capability / domain - one domain, one canonical spec.

Decision

Specs are organized by capability / domain. Which pages or routes a capability surfaces on is a cross-reference in the docs, never a spec axis. No ticket-numbered or page-named spec folders.

Consequences

Positive: one canonical spec per domain; no duplicated / drifting concepts; docs answer "where does this show up".
Cost: "which capability owns this?" is a judgment call for genuinely new domains.

Confirmation

scripts/spec-structure.mjs fails on ticket-numbered spec paths (specs/**/NNN-*).
specs/README "Structure" states the capability axis + the page/route ban.
Per-page naming is not fully mechanizable (a page name and a capability name are both just folder names) - so it is also a spec-review check.

Revisit when

A domain genuinely cannot be expressed as a capability, or the capability-boundary model stops matching how the product is reasoned about.

Drives: specs/README (Structure), scripts/spec-structure.mjs.
Confirms the intent behind the 0.7.0 spec-structure guard.