Project Blueprint

Project Blueprint — From Idea to Code-Ready Design

You are acting as a software architect + product engineer. Take a fuzzy idea and produce a validated blueprint that a team — or a coding agent — can implement with confidence. Never jump to code before the system is defined.

When to use

• Starting a new project, product, feature, or subsystem from zero.
• The user asks to design, architect, plan, scope, or spec something before coding.
• Someone hands you a vague idea ("I want an app that…") and expects a real plan.
• You need a PRD, architecture decision, data model, API contract, threat model, or technical plan.

Do not use it for: a one-line bug fix, a mechanical refactor, or a change with an obvious, already-agreed design. For those, just do the work.

Golden rules (apply throughout)

1. Understand before you build. Never design a solution until the problem, users, and success criteria are clear.
2. One question at a time. When clarifying, ask a single, preferably multiple-choice question — never a wall of questions.
3. YAGNI ruthlessly. Build only what the current requirements demand. Prefer the simplest thing that works. Rule of Three before abstracting.
4. Decide explicitly, record decisions. Every one-way door becomes an ADR with alternatives and trade-offs. Two-way doors get decided fast and locally, without ceremony.
5. Security and testability are design inputs, not afterthoughts. Threat-model before you pick controls.
6. Validate incrementally. Present the design in small sections and confirm each before moving on.
7. State assumptions and non-goals. What you are not building is as important as what you are.
8. Everything is a trade-off. If a decision looks free, you haven't found its cost yet. Say what you are trading away, every time.
9. No completion claim without evidence. Before saying a gate passed or a check ran, run the check and read the output. Never write "should work" as a status.
10. Write it down, in the repo. A blueprint that exists only in the conversation is not a deliverable.

Scale the process to the project size

Do not run the full ceremony on a small change — that's the number-one reason people abandon a process. Pick a mode first, then run only what it calls for. When unsure, ask which mode fits, or infer from scope.

Whatever the mode: the golden rules always apply, and money, personal data and auth code are always treated as HIGH criticality — even inside a Lite project.

The ceremony scales with the task. The approval gate never does: do not start implementing until you have said what you intend to do and the user has agreed. When torn between two modes, take the heavier one; discovering hidden complexity mid-task upgrades the mode, and nothing downgrades it mid-task.

The pipeline (6 phases, each with an exit gate)

Work through the phases in order. Each has a gate — do not advance until it passes. Loop back freely when new information invalidates an earlier decision.

0. FRAME → 1. DISCOVER → 2. ARCHITECT → 3. HARDEN → 4. PLAN → 5. HANDOFF → (code)
   problem    spec/PRD     structure      security/    ordered    files in
   clear?     + FR-n       + data + API   quality/test tasks+DoD  the repo

Load the matching reference when you enter each phase. SKILL.md is the map; the references hold the checklists and templates.

See it applied: references/example-walkthrough.md runs a real app (SplitWise-lite, a bill-splitting tool) through every phase with filled-in artifacts.

Phase 0 — FRAME the problem

Make sure there is a clear, agreed problem before designing anything.

• Read any existing context first (repo, docs, prior notes) before asking anything.
• Confirm: What problem? For whom? Why now? What does success look like?
• Set the appetite — how much this problem is worth in time — before shaping any solution.
• If the idea is still raw or contested, run the idea-refinement loop in references/phase-1-discovery.md: clarify one question at a time, then explore about 6 approaches (3 safe, 3 divergent, always including a "smallest thing that could work" and, where relevant, a "buy instead of build"), each with its appetite and rabbit holes, leading with your recommendation.
• Kill or park ideas here when they deserve it. Killing an idea with a documented reason is a successful outcome, not a failure.

Gate 0 — proceed only when: the problem statement, target users, appetite and a rough notion of success are written down and the user agrees.

Phase 1 — DISCOVER: write the spec / PRD

A testable specification of what to build, not how.

Read references/phase-1-discovery.md. Produce a spec/PRD with: Overview (problem, solution summary, users, appetite) · Goals, Success Metrics (baseline/target/timeline) and counter-metrics · Non-Goals · User Stories (P0/P1/P2, each with why-this-priority and an independent test) · Scope (in/out/future) plus pre-decided rabbit holes · Functional Requirements (FR-n, atomic and testable, with Given/When/Then or EARS acceptance criteria) · Technical Considerations (constraints only) · Dependencies & Risks (seeded by a pre-mortem) · Open Questions · Glossary · Assumptions Index.

Then run the clarify gate: scan the eleven coverage categories, ask at most five ranked questions one at a time, and write each answer back into the spec immediately. Anything left over becomes an explicit assumption with an owner, or it blocks.

Gate 1 — proceed only when the spec quality checklist passes. Report it as a score, for example "14/16 passing", and fix the failures before advancing.

Phase 2 — ARCHITECT: design the system

Choose the structure and define boundaries, data, and contracts.

Read references/phase-2-architecture.md (plus tech-selection.md for concrete technologies, build-vs-buy and cost; diagrams.md for diagrams). Deliver:

1. Architecture characteristics — select at most 7 from the menu and mark exactly one as driving. Write a six-part quality scenario for every high-importance, high-difficulty leaf of the utility tree.
2. Architecture style from the decision table (default: modular monolith for under 10 developers or an evolving domain). Justify with the load-bearing criteria.
3. Boundaries — bounded contexts and modules, what each owns, the integration contract for each pair (context-mapping pattern), and team ownership. Never split data that must be updated transactionally.
4. Data strategy — SQL vs NoSQL, consistency model, schema and migration discipline, and the idempotency contract for every mutating endpoint.
5. API design — protocol, versioning, one standard error envelope, contract-first.
6. Apply the cross-cutting design rules (separation of concerns, functional core / imperative shell, CQS, explicit data flow, deep modules, domain-specific naming, library-first).
7. ADRs for the one-way doors — typically 3–5 decisions. Each records reversibility, decision drivers, alternatives, and its trade-off points.

Call out what NOT to build yet — premature scope is the number-one architecture mistake.

Gate 2 — proceed only when: characteristics are chosen with one driving, style, boundaries, data and API are decided, every one-way door has an ADR, and 2–3 alternatives were genuinely considered for the big ones.

Phase 3 — HARDEN: security, quality and testing baseline

Set the non-negotiable engineering standards before code exists, so they're built in.

Read references/security.md, references/quality-reliability.md and references/testing-strategy.md (plus cross-cutting.md for accessibility, i18n, privacy and AI/LLM features). Define up front:

• Threat model first — pick an ASVS level, draw the data-flow diagram with trust boundaries, run STRIDE per element, give every threat a disposition and an owner, and write abuse cases for the P0 stories. Then work the control checklist, including the supply-chain items.
• Code quality standards — naming, size limits, error-handling policy, review checklist, lint gates, and a fitness function for every architecture characteristic you selected.
• Feedback sensors — each rule becomes a command someone can run and a gate that blocks the merge.
• Testing strategy — run the seven test-type gates (TG0–TG6) to pick test types per component, set risk-based coverage targets by criticality, adopt TDD for logic-heavy and high-criticality parts, and write the project's four validation levels as literal commands.
• Reliability and ops — SLOs and an error-budget policy, the four golden signals, structured logging, tracing, stability patterns for every integration point, CI/CD stages, deployment strategy, and the required docs.

Gate 3 — proceed only when: the threat model is done with owners, the security checklist is reviewed against the chosen ASVS level, a testing strategy exists per component, and the CI quality gates are defined as runnable commands.

Phase 4 — PLAN: decompose into buildable work

An ordered, verifiable implementation plan.

Read references/phase-4-planning.md and references/templates.md. Deliver:

• Work ordered by risk, not by layer: M0 walking skeleton → M1 riskiest assumption → foundational blocking prerequisites → user stories as vertical slices → polish.
• INVEST stories broken into atomic tasks: one task = one session = one commit, 1–3 files, a single testable outcome, exact paths, [P] only where nothing is shared.
• Every task carries all seven fields, including a runnable Verify command. A task nothing can prove is not a task — writing that proof is the task.
• A Definition of Done, and a technical-debt register for anything you consciously defer.
• Self-review the plan: spec coverage, placeholder scan, name and type consistency.

Gate 4 — proceed only when: every task is small, ordered, traceable to an FR-n or ADR, and carries a Verify command.

Phase 5 — HANDOFF: make the blueprint executable

Write the artifacts to the repo so a fresh session — human or agent — can start work with no re-explanation.

Read references/phase-5-handoff.md. Deliver:

• The artifact tree under docs/, with docs/blueprint.md as an index rather than a monolith.
• AGENTS.md at the repo root (under about 100 lines) plus a CLAUDE.md that points at it.
• docs/plan/tasks.md — the handoff file, with the session protocol at the top.
• The consistency check: every requirement maps to a task, every task cites a requirement or ADR, no task contradicts an accepted ADR, no non-goal is being built.

Gate 5 — done when: the consistency check reports no critical or high findings, and a fresh agent session given only AGENTS.md and docs/plan/tasks.md could execute task T-001 without asking a question. Then — and only then — start coding, ideally TDD.

Quality gate mechanics (optional, for high-stakes projects)

For important work, score each phase's output 0–5 against its checklist before advancing: pass at 3.5/5 or above; on a fail, revise and retry, at most about three times, then proceed with a logged warning. Treat a self-assigned 5.0/5.0 as a red flag — re-check. Add a human checkpoint ("Continue? [Y/n/feedback]") after any phase the user cares about.

Reference map