blueprint

name	blueprint
description	A living product specification skill. Use when you want to document how a system works, capture user stories and flows, build shared vocabulary, discuss existing functionality, or create a single source of truth for a feature or product area.
version	2
auto_trigger	[{"file_patterns":["**/*.blueprint/README.md","**/*.blueprint/**/*.md"]},{"keywords":["blueprint","living spec","product spec","system spec","document how this works","single source of truth","spec this out"]}]

A living specification for how things work. Not a one-time approval document — a persistent reference that a team maintains, discusses, and evolves alongside the product.

A blueprint answers:

• What the system does, and why it exists
• Who uses it, in what roles, with what goals
• How things flow — the real scenarios, step by step
• What the domain looks like — the entities, their states, their relationships
• What words mean — the shared vocabulary everyone uses to talk about this

It covers both what the system does today and what it should do. When these diverge, that divergence is worth examining.

Describing a new feature or system and need to capture it System exists but is not documented; want to understand and capture what it does Have a blueprint and want the review panel to debate its clarity and completeness Want a systematic checklist audit — six dimensions, structured findings report Want the review panel to evaluate a new feature, behaviour change or rule modification System has changed and the blueprint needs to reflect it Want to create the directory structure for a new blueprint with placeholder files

Why this exists; the problem it solves

What's covered, what's adjacent, what's explicitly out

Who interacts with the system and in what capacity

Shared vocabulary; precise definitions for domain terms

Who needs what and why

How things work end-to-end, with diagrams

Entities with states, invariants, transitions, and relationships

What the system must do; business rules with sources; constraints

Settled decisions with rationale (not just outcomes)

Every question has an owner and a deadline

How this document has evolved

Domain likely covers multiple bounded contexts — split Non-overlapping actor groups belong in separate blueprints Entity groups with no relationships are separate domains Actors who never share a scenario are in different systems

When in doubt, start with one blueprint and split when size makes targeted updates difficult.

Context, Scope, Actors, Terminology — enough to align on vocabulary and boundaries + User Stories, primary Scenarios, Domain Model — enough to start implementation discussions + Error scenarios, Requirements with sources, Decision log — the single source of truth

State the current tier in the README.md manifest so readers know what to expect.

A blueprint describes observable behaviour, not implementation. It says what happens — not which database stores it, which API returns it, or which component renders it.

The test for every detail: "Would someone need to know this to understand how the system behaves, without knowing how it is built?"

A user can have one active subscription at a time — Behaviour An expired invitation cannot be accepted — Behaviour Admins can see all workspaces; members only their own — Access behaviour Subscriptions are stored in the subscriptions table — Implementation Invitations expire via a nightly cron job — Mechanism Access is enforced by a middleware guard on the API — Implementation detail

Implementation details belong in technical design documents. The blueprint belongs to the whole team — product, engineering, support, design — not just engineering.

Why a directory: targeted loading (only read the section you're updating), scenarios grow independently (own directory), smaller files mean better edits, cross-referencing with relative paths works.

Build a blueprint through structured conversation Extract a blueprint from an existing system Convene the review panel to debate clarity and completeness Systematic checklist audit across six dimensions Convene the review panel to evaluate a proposed change Incrementally update a blueprint after system changes Generate the directory structure for a new blueprint

What each section must contain, including cross-blueprint references Mermaid patterns for flows, states and domain models Before/after examples for every section type Keeping a blueprint current: staleness signals, review triggers, ownership