docs/superpowers — Design Specs & Implementation Plans

This directory is the repo's design history, produced by the AI-assisted workflow described in CONTRIBUTING.md ("Working with Claude Code"). If you want to know why a feature works the way it does, look here before reading code comments.

Layout

• specs/ — approved designs, one per feature, named YYYY-MM-DD-<topic>-design.md. Each records the decisions made during brainstorming (options considered, what was chosen and why, non-goals). These are the closest thing this repo has to ADRs (architecture decision records).
• plans/ — step-by-step implementation plans derived from a spec, executed task-by-task with test-first commits. Checkboxes inside a plan may be stale after execution; the merged PR is the record of what actually happened.

How to read them

• Later specs supersede earlier ones on the same feature. Buylist, for example, evolved across half a dozen specs (intake → portal → sealed → payout tracks → native settlement); the newest dated spec on a topic reflects current intent.
• After merge, code is the authority. A spec captures the design at approval time; if it disagrees with shipped code, something changed during implementation or a later PR — git log --follow on the spec and the files it names will find the divergence.
• To find the PR that implemented a spec, git log --oneline -- <spec path> and look at the commits/PRs adjacent to when the spec landed.

Conventions for new specs/plans

Produced via the superpowers plugin (brainstorm → spec → plan). Keep the YYYY-MM-DD-<topic>-design.md naming, commit the spec before implementation begins, and state superseded specs explicitly in the header when reworking an existing feature.