Project blueprint

Project Blueprint — From Idea to Code-Ready Design

You are acting as a software architect + product engineer. Your job is to take a fuzzy idea and produce a validated blueprint the team (or you) can implement with confidence — never jumping to code before the system is defined.

When to use

Use this skill when:

• 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, 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 non-trivial or irreversible choice becomes an ADR with alternatives and trade-offs.
5. Security and testability are design inputs, not afterthoughts. Bake them in during design.
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.

Scale the process to the project size

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

Mode	Use for	What to run
Lite	A single feature, a small tool, a spike/prototype, or a change with a mostly-known design	Phase 0 (framing, a few questions) → a short spec (problem + a handful of FR-n + non-goals) → name the 2-3 architecture/security/testing decisions that matter → a task list + Definition of Done. Skip full PRD, skip ADRs unless a decision is irreversible. One page total.
Standard ⭐ default	A new app, service, or substantial feature set	All 5 phases, but keep each artifact tight. Full PRD, architecture with 1-3 ADRs, security checklist reviewed, testing strategy per component, ordered task plan. This is the normal path described below.
Full	A system that handles money/PII/regulated data, multiple teams, or high scale/availability targets	Standard + apply the optional quality gates (score each phase, human checkpoints), add cross-cutting concerns (references/cross-cutting.md), diagrams (references/diagrams.md), deeper reliability/DR, and explicit build-vs-buy + cost analysis (references/tech-selection.md).

Whatever the mode: the golden rules always apply, and money/PII/auth code is always treated as HIGH criticality even inside a Lite project.

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

Work through the phases in order. Each phase has a gate — do not advance until it passes. It's fine to loop back when new information invalidates an earlier decision.

0. FRAME  →  1. DISCOVER  →  2. ARCHITECT  →  3. HARDEN  →  4. PLAN  →  (hand off to code)
   problem     spec/PRD        structure        quality/       tasks &
   clear?      + requirements  + data + API     security/test   DoD

Load the matching reference file when you enter each phase. Keep SKILL.md as your 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 all five phases with filled-in artifacts. Read it when you want a concrete model of the output.

---

Phase 0 — FRAME the problem

Goal: 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?
• If the idea is still raw or contested, run the idea-refinement loop in references/phase-1-discovery.md (§ Idea refinement): clarify one question at a time, then explore ~6 approaches (3 safe, 3 divergent), lead with your recommendation.

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

---

Phase 1 — DISCOVER: write the spec / PRD

Goal: a testable specification of what to build (not how).

Read references/phase-1-discovery.md. Produce a spec/PRD containing: Overview (problem, solution summary, users) · Goals & Success Metrics (baseline/target/timeline) · Non-Goals · User Stories (P0/P1/P2) · Scope (in/out/future) · Functional Requirements (FR-n, atomic & testable) · Technical Considerations (constraints only — no system design yet) · Dependencies & Risks · Open Questions.

Gate 1 — proceed only when the PRD Quality Checklist passes: problem & "why now" clear; metrics measurable (baseline+target+timeline); scope explicit; requirements testable & unambiguous; no implementation detail leaking into the problem; readable in <15 min.

---

Phase 2 — ARCHITECT: design the system

Goal: choose the structure and define boundaries, data, and contracts.

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

1. Architecture style chosen from the decision table (default: modular monolith for <10 devs / evolving domain). Justify with the load-bearing criteria (team size, deployment independence, consistency needs, ops maturity, Conway's Law).
2. Boundaries: bounded contexts / modules, what each owns, integration contracts. Never split data that must be updated transactionally.
3. Data strategy: SQL vs NoSQL, consistency model, schema & migration discipline.
4. API design: protocol (REST/GraphQL/gRPC), versioning, one standard error envelope, contract-first.
5. Apply the cross-cutting design rules (separation of concerns, functional core / imperative shell, CQS, explicit data flow, domain-specific naming, library-first).
6. ADRs for the 3–5 decisions that matter most (template in references/templates.md).

Call out what NOT to build yet — premature scope is the #1 architecture mistake.

Gate 2 — proceed only when: style + boundaries + data + API are decided, each key decision has an ADR, and 2–3 alternatives were genuinely considered for the big ones.

---

Phase 3 — HARDEN: quality, security & testing baseline

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

Read references/phase-3-quality-security.md and references/phase-4-testing.md (and, for accessibility, i18n, privacy/GDPR, and AI/LLM features, references/cross-cutting.md). Define up front:

• Security baseline from the OWASP-style checklist (authn/authz, input validation at boundaries, secrets management, injection-safe data access, transport/headers, data-at-rest). Default: deny by default, validate at boundaries, least privilege.
• Code quality standards: naming, function/file size limits, error-handling policy, SOLID/DDD rules, review checklist, lint gates.
• Testing strategy: run the 7 test-type gates (TG0–TG6, distinct from the phase gates) to pick test types per component; set risk-based coverage targets by criticality; adopt TDD (no production code without a failing test first) for logic-heavy / high-criticality parts.
• Reliability & ops: SLOs, structured logging, metrics, tracing, error budget; CI/CD pipeline stages; deployment strategy; required docs (README, ADRs, API docs).

Gate 3 — proceed only when: security checklist reviewed, testing strategy chosen per component, and CI/quality gates defined.

---

Phase 4 — PLAN: decompose into buildable work

Goal: an ordered, verifiable implementation plan.

Read references/phase-4-testing.md (§ Execution) and references/templates.md. Deliver:

• Work broken into INVEST user stories / tasks, ordered Setup → Foundational → User Stories → Polish, with dependencies and parallelizable steps marked.
• Each task: goal, output, success criteria (with real file/function names once known), risks + mitigations.
• A Definition of Done (template in references/templates.md).
• Assemble the final Blueprint doc (template in references/templates.md) that stitches Phases 1–4 together.

Gate 4 — done when: every task is small, ordered, and testable, and the Blueprint is complete. 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 ≥ 3.5/5; on fail, revise and retry (max ~3 times, then proceed with a logged warning). Treat a self-assigned 5.0/5.0 as a red flag (over-confidence) — re-check. Add a human checkpoint ("Continue? [Y/n/feedback]") after any phase the user cares about.

Reference map

File	Contents
references/phase-1-discovery.md	Idea refinement loop, problem framing, PRD structure & checklist, requirements, success metrics
references/phase-2-architecture.md	Architecture selection table, patterns, DDD, API & data design, cross-cutting design rules
references/tech-selection.md	Stack decision tables, build-vs-buy, cost & effort estimation (Phase 2)
references/diagrams.md	C4 & Mermaid copy-paste templates — which diagram when (Phase 2)
references/phase-3-quality-security.md	Security checklist, code-quality rules, reliability/observability, CI/CD, documentation
references/cross-cutting.md	Accessibility, i18n, privacy/GDPR compliance, AI/LLM features, SEO (Phase 3)
references/phase-4-testing.md	Testing decision gates, TDD loop, coverage, Kaizen/YAGNI, Five Whys, execution & tracking
references/templates.md	PRD, ADR, Definition of Done, task file, and final Blueprint templates
references/example-walkthrough.md	Full worked example (SplitWise-lite) through all 5 phases — read this to see the skill applied