# Project Blueprint > Acts as software architect to define a software system from scratch BEFORE writing code. Turns a raw idea into a validated, code-ready blueprint — refining the idea, writing the spec/PRD, choosing the architecture, setting the security, quality and testing baseline, and writing the plan and agent handoff files into the repo. Use when starting a new project, feature, or system, when the user says "design/plan/define/architect X", "empezar un proyecto", "definir el sistema antes de codear", or wants a PRD, architecture, technical plan, ADR, or threat model. - Skill: `drewggm/project-blueprint` (Agent Skill, multi-file: 14 files) - Install (CLI): `npx skillmds@latest add drewggm/project-blueprint` - Raw SKILL.md: https://api.skillmd.com/api/skills/drewggm/project-blueprint/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - License: MIT - Author: DrewGGM (https://skillmd.com/u/drewggm) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/drewggm/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. | Mode | Use for | What to run | |---|---|---| | **Lite** | A single feature, a small tool, a spike or 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 and testing decisions that matter → a task list with Verify commands + Definition of Done → `AGENTS.md`. Skip the full PRD; use a one-line Y-statement instead of ADRs unless a decision is irreversible. One page total. | | **Standard** ⭐ *default* | A new app, service, or substantial feature set | All 6 phases, each artifact kept tight. Full PRD, architecture with 1–3 ADRs, threat model, testing strategy per component, ordered task plan, artifacts written to `docs/`. | | **Full** | A system handling money, personal data or regulated data; multiple teams; high scale or availability targets | Standard + scored quality gates and human checkpoints, cross-cutting concerns (`cross-cutting.md`), diagrams (`diagrams.md`), fitness functions, deeper reliability and DR, a project constitution, and explicit build-vs-buy plus cost analysis (`tech-selection.md`). | 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 | File | Contents | |------|----------| | `references/phase-1-discovery.md` | Idea refinement, appetite and rabbit holes, pre-mortem, impact map, PRD structure, requirements and EARS, metrics and counter-metrics, the clarify gate, the Gate 1 checklist | | `references/phase-2-architecture.md` | Architecture characteristics and quality scenarios, style selection, quantum and coupling, patterns, DDD and context mapping, API and data design, idempotency, team topologies, module depth | | `references/tech-selection.md` | Stack decision tables, subdomain triage (core/supporting/generic), build-vs-buy, cost and effort estimation, the tech decision gate | | `references/diagrams.md` | C4 and Mermaid templates, including a data-flow diagram with trust boundaries — which diagram answers which question | | `references/security.md` | ASVS levels, threat modelling (four questions, STRIDE per element, abuse cases), OWASP Top 10 coverage map, the control checklist, supply chain | | `references/quality-reliability.md` | Fitness functions, feedback sensors, code-quality rules, stability patterns, SLOs and error-budget policy, percentile discipline, toil, performance, CI/CD, docs | | `references/testing-strategy.md` | Test-type gates TG0–TG6, the four validation levels, the TDD loop, coverage and mutation testing | | `references/phase-4-planning.md` | Risk-first ordering and the walking skeleton, atomic task criteria, plan self-review, YAGNI and Kaizen, technical-debt quadrant, Five Whys, tracking | | `references/phase-5-handoff.md` | Artifact layout, the tasks.md handoff format, AGENTS.md, the consistency check, the agent session protocol | | `references/cross-cutting.md` | Accessibility, i18n, privacy and GDPR, AI/LLM features mapped to the OWASP LLM Top 10, SEO | | `references/templates.md` | PRD, constitution, ADR, threat register, Definition of Done, task block, blueprint index, consistency report | | `references/principles.md` | The canon worth quoting when a decision stalls, DORA and SPACE, and a recommended reading list | | `references/example-walkthrough.md` | A full worked example through every phase — read this to see the skill applied |