--- title: "The N1 Spec System — How we design & build with Claude" --- # The N1 Spec System ## 01 What this is, in one minute Every piece of work at N1 — a feature, a bug fix, a new platform service, a product idea, a clinical change — starts life as a **spec**: a short, structured document that says what we're doing and how we'll know it's done. We write specs with Claude, store them in one repo, and build against them. The point is to remove **drift**: the same request producing five different shapes of work depending on who asked and where. The spec is the shared contract. You write it once, properly, and everyone — every teammate and every Claude — reads it the same way. - You don't need to be a project-management expert. The format does that work for you. - A skill called `/spec` walks you through it, section by section, and won't let you skip the parts that matter. - When the spec is done, it goes into the `blueprints` repo, and that's what gets built. **The short version:** Idea → write a spec (with `/spec`) → land it in `blueprints` → Claude Code builds it and opens a pull request → a human reviews and merges. The spec is the thing everything else hangs off. ## 02 Three Claudes, one repo We use Claude in three places, each good at a different job. They cannot talk to each other directly — the only thing they share is the repo. So the spec file in git is the bridge between all of them. - **Claude Chat / Desktop (Projects)** — where you think, argue, decide, and *write the spec*. - **Claude Design** — where you explore what a frontend should look and feel like; you export the result and link it from the spec. - **Claude Code** — where the work actually gets built and a pull request opens. ### The Three Surfaces | Surface | Role | |---------|------| | **Claude Chat / Desktop** | Think · decide · write the spec. Reads the repo; ends by producing a finished spec you submit. | | **Claude Design** | Explore the frontend. Export screens/prototypes into `blueprints/design/` for the spec to link to. | | **Claude Code** | Build against the committed spec, open the PR. Runs in the terminal, on the web, or from Slack. | The repo is the single bridge between them. Because the repo is the only bridge, the repo is the single source of truth. A brilliant idea in a chat that never becomes a committed spec simply doesn't exist as far as the rest of the team and Claude Code are concerned. ## 03 The one rule **The golden rule:** Anything that matters gets written into `blueprints` as a spec. The chat is where you reason; the repo is what persists and what gets built. **If a decision lives only in a chat or a Slack thread, it doesn't exist.** Everything else on this page is just *how* to follow that rule well. ## 04 Which spec do I need? There are eight types. They are not eight unrelated forms — they all share the same backbone (next section) and each just adds the one or two things unique to it. Pick by the **litmus question**: the first one you can answer "yes" to is your type. If you're unsure, `/spec` asks you these same questions and picks for you. ### Spec Types | Type | Pick it when… | What it adds (beyond the backbone) | Layer | |------|---------------|---------------------------------------|-------| | **Bug Fix** | Existing behaviour is *wrong* versus what it should be. | A reproduction, the root cause, and a **permanent regression test** (non-negotiable). | either | | **Refactor** | When done, the system behaves *exactly* the same from the outside. | The invariant ("no observable change") + characterization tests proving it. | either | | **Architecture Decision (ADR)** | You're *choosing between options* with long-lived consequences and want to record the why. | The decision + the alternatives weighed + the consequences. (Building follows in another spec.) | platform | | **Clinical / CHR** | Correctness here is *clinical* — a wrong output could mislead a clinician. | The clinical claim, the mechanism, the evidence (NLM/NCBI). Organised by mechanism, not organ. | product | | **Contract** | It's an *interface two services must agree on*, where changing it breaks the other side. | The interface itself — producer, consumers, the binding shape — defined before either side builds. | platform | | **Service** | It's a *reusable capability* many products could use, knowing none of them. | A clean charter, its public door, and what data it owns. (If it knows "CHR", it's not a service.) | platform | | **Product / Initiative Brief** | You're deciding *whether and what* to build for a user — a new offering, no API yet. | Users/customers and success metrics. The output is a go/no-go and a shape, not code. | product | | **Feature** | None of the above — a decided, scoped change inside one codebase. | Data model · API surface · behaviour · frontend (every UI state). | product (usually) | ### Common Mix-ups - **Bug vs Feature:** the system is wrong → Bug; the system is right but you want *more* → Feature. - **Refactor vs Feature:** the test is observable behaviour. Faster but identical output → Refactor. Faster *and* a new flag → Feature. - **Feature vs Service:** one product uses it → Feature; many products could, and it knows none of them → Service. - **ADR vs Service:** "we decided to extract identity" → ADR; "here is identity, built" → Service. Big extractions are usually an ADR *then* a Service spec. The full criteria, the worked examples, and the templates themselves live in `blueprints/specs/_templates/` — start at its `README.md` (the criteria) or open `index.html` for the visual "which template?" guide. ## 05 Every spec: the backbone & the two gates Whatever the type, every spec answers the same underlying questions. Most carry all ten sections below; the **slim types (Bug, ADR)** use tailored headers for the top few but always keep the two gates and the closing checks. The two ⛨ **gates** are non-skippable — you either fill them in, or write `N/A — `. They are N1's two existential pillars, clinical accuracy and security, turned into structure no one can scroll past. ### The Spine (Ten Sections) 1. **Problem** — What's broken or wanted, why now, who's hurt if we don't. The one core thing. 2. **Outcome / Definition of done** — What is observably true when finished — checkable from outside, not "the code is written." 3. **Scope & non-goals** — The boundary — what we are explicitly NOT doing. 4. **Approach** — How, and why this way over the alternatives you weighed. Simplest reliable design. 5. **Clinical-accuracy gate** — Does it touch PHI or change clinical output? If yes: the claim, the evidence (NLM/NCBI — cited, not from memory), and how a wrong output is caught before a clinician sees it. Else `N/A — why`. 6. **Security gate** — Does it touch auth / data / PHI / secrets / infra? If yes: the boundary, the default-deny posture, where enforcement lives (server side), how it fails secure. Else `N/A — why`. 7. **Risks & failure modes** — What breaks, the blast radius, and how each failure fails loud / non-zero. 8. **Verification** — How we *prove* it works — failure/edge tests first (named), the repo gate that must pass, the evidence a reviewer can see. 9. **Acceptance criteria** — A checklist a reviewer ticks against the diff — each line verifiable. 10. **Open questions** — Must be empty before the spec is `ready`. Resolve, don't defer. ### When is a spec "ready"? A spec is `status: ready` only when **every section is filled, no `TBD` survives in a load-bearing section, both gates are resolved, and Open questions is empty.** That single, checkable rule is the bar. Below it, it's still a draft. ## 06 Platform vs product — one field keeps them honest N1's direction is "AWS for Health Tech": a platform, with products built on top of it — including our own. forge-runner is the platform; the CHR workflows are products that run on it. Every spec declares which side it's on with one frontmatter field, `layer: platform | product`. ### Product Layer **Things we sell or deliver, built on the platform.** Example: each CHR workflow · white-label products · clinical-trial tooling. Spec types: Product Brief, Feature, Clinical/CHR. *Reaches the platform only through the **public door** — the Contract Spec* ### Platform Layer **Reusable primitives behind one clean charter. Product-agnostic.** Example: forge-runner (agentic runtime) · identity · billing · ingestion · data. Spec types: Service, Contract, ADR. ### The Boundary Rule A **platform** service carries zero product-specific logic — forge-runner must not know "CHR" exists. A **product** reaches a platform service only through its published Contract Spec — never into its basement. If a CHR workflow needs something forge-runner doesn't offer, that's a **Contract change reviewed at the platform layer**, not a quiet reach-in. **Why we bother:** "Platform + products" rots when a product team adds "just one product-specific thing" into the platform because it's faster — and six months later forge-runner is a CHR engine that can't run anything else. The `layer` field plus the contract discipline make that leak **visible in the spec and the diff** before it's a problem. ## 07 What a spec actually looks like So you can feel the bar. The top block (the "frontmatter") is the machine-readable header; the body is the backbone from section 05. This is a Feature spec — every type looks like this, with its own one or two extra sections. ```yaml --- frontmatter: the machine-readable header --- type: feature # product-brief|service|contract|feature|refactor|adr|clinical|bug layer: product # platform | product status: draft # draft → ready → in-progress → done owner: arun scope: [api-backend, react-frontend] # repos/services touched consumes: [specs/contract/forge-runner.md] # platform doors used (product layer) tracker: https://github.com/.../issues/123 related: [] # Spec: ## Problem one paragraph; the single core thing this solves. ## Outcome what is observably true when done. ## Scope / Non-goals in scope … · explicitly NOT in scope … ## Approach the design, and why this over the alternatives. ### Data model entities, fields, types, migrations. ### API surface per endpoint: method, path, request, response, codes. ### Behaviour logic, edge cases, invariants. Mark deterministic-must-be-correct vs best-effort/stochastic. ### Frontend flows; every state (default/loading/empty/error/success); links to design exports. ## Clinical-accuracy gate PHI/clinical impact — or "N/A — ". ## Security gate auth/data/infra impact — or "N/A — ". ## Risks & failure modes what breaks; how it fails loud/secure. ## Verification failure/edge tests FIRST (named); repo gate (tests / build / alembic heads==1); evidence. ## Acceptance criteria [ ] reviewer-checkable lines. ## Open questions empty before status: ready. ``` You rarely type this from scratch — `/spec` scaffolds it and fills it with you. The point of seeing it here is to recognise it when you do. ## 08 Your workflow, step by step This is the day-to-day. Most people do all of this in Claude Desktop / web; a few who live in git do steps 1–4 in Claude Code instead. Both end in the same place. ### Step-by-Step Workflow 1. **Start in your N1 Specs project** — Open a chat and describe the work in plain language — a bug, a feature, an idea, a service, whatever it is. No need to know the spec type yet. 2. **Run the spec skill** — Type `/spec` (in Claude Desktop / web) or `/n1:spec` (in Claude Code). It asks the litmus questions, picks the right type, and confirms it with you in one line. 3. **Fill it in, section by section** — The skill walks the backbone with you and asks wherever a fact is missing. Don't let it guess paths, schemas, or evidence — give it the real ones, or mark an open question. It forces both gates. 4. **Reach the ready bar** — Keep going until every section is filled, no `TBD` is left in anything load-bearing, both gates are resolved, and there are no open questions. Now it's `ready`. 5. **Land it in `blueprints`** — **Working in git:** commit the spec under `specs//.md` and open the PR yourself. **Everyone else:** open an issue in `blueprints` with the finished spec pasted in, and a maintainer commits it. *(An automated "New Spec" intake that validates the spec and opens the PR for you is planned, not yet built.)* 6. **Build & review** — Claude Code implements against the committed spec and opens a PR. A human reviews the spec before build and the PR after. Merge when it's clean and green. ## 09 What's required from you The skill does the heavy lifting, but a few things are on you — they're what make a spec trustworthy enough to build from without a back-and-forth. - **Produce a spec, not loose notes.** Any real work becomes a spec in `blueprints`. A chat decision that never lands doesn't count. - **Pick the honest type.** Don't force a Bug into a Feature to skip the regression test, or call a Feature a Refactor. The litmus is there to keep you honest. - **Give real facts, never invented ones.** Paths, schemas, versions, API shapes, evidence — supply the true ones or mark an open question. A fabricated detail is worse than a blank. - **Pin the things that must match exactly.** Write API shapes, data models, and acceptance criteria as precise, checkable lines — `POST /v1/sessions {email} → 201 {token}`, not "add a login endpoint." Prose carries intent; structure carries the facts that can't be read two ways. - **Resolve both gates.** Clinical accuracy and security are never left blank. If they don't apply, say `N/A — ` and why. - **Hit the ready bar before you submit.** No open questions, no load-bearing `TBD`, both gates done. If it's not ready, it stays a draft. - **Write plainly.** Explain a thing before naming it. The reader might be a teammate with zero context — or a Claude six months from now. ## 10 One-time setup You only do this once. After that, `/spec` is just there. ### For everyone (each person, once) 1. In Claude (web / Desktop), create a **Project** called something like "N1 Specs". 2. Open its **custom instructions** and paste in the block from `blueprints/shared-project-instructions.md`. That's what makes `/spec` activate reliably and sets the spec-first workflow. 3. *(Optional)* connect the `blueprints` repo as project knowledge — read-only — so Claude can read the live templates and examples. ### Already done for you (by an admin, once for the org) - The `/spec` skill is provisioned org-wide in Claude (Settings → Skills), so it's available to every member automatically. - In Claude Code, the same skill ships in the `n1` plugin as `/n1:spec` — it's there once your plugin is up to date. **The names differ by surface — same skill:** On Claude web / Desktop it's `/spec`. In Claude Code it's `/n1:spec` (Code namespaces plugin skills). Same behaviour either way. Full setup checklist: `blueprints/SETUP-A-PROJECT.md`. ## 11 Why specs don't get interpreted differently A fair worry: if two people (or two Claudes) read the same spec, do they build the same thing? The honest answer, because a comfortable lie here would poison everything downstream. ### The honest truth **You cannot make two Claudes emit identical code.** Two models — or two versions of the same model — reading the same prose can produce different implementations. So the system **does not depend on identical generation.** It depends on pinning what must match and checking it. This is N1's own deterministic/stochastic line, applied to specs. Interpretation is driven to zero *where it matters* in three moves: 1. **Pin the contract, not the prose** — The must-match facts — API shapes, data models, file paths, contracts, acceptance criteria — are written as precise, checkable lines, not loose English. `POST /v1/sessions {email} → 201 {token}` can't be read three ways; "add a login endpoint" can. 2. **One source, checked at the end** — The spec is the single canonical artifact. Every implementation is verified against its acceptance criteria + failure-first tests + the repo's own gate. Different Claudes may take different paths; they must reach the same checkable outcome. 3. **The check isn't the model** — Validation is the repo's tests and a deterministic completeness check — it never asks a model to behave. A Sonnet, an Opus, a Claude Code from next year — all hit the same check. It survives model updates because it isn't a model. And one quiet lever: a detailed spec turns implementation into **transcribing a contract, not inventing a design**. Low-creativity tasks have low variance to begin with — the structure does most of the convergence before any check runs. That's also why the discipline in section 09 (give real facts, pin what must match) is on you: it's what makes this hold. ## 12 What we don't promise The honesty that makes the rest credible. - **Not identical code.** Sameness lives in the checked outcome, not the generated text. Two builds can differ in naming and layout and both be correct. - **Not "the chat is enough."** A decision that lives only in a chat doesn't exist until it's a committed spec. Chat and Design advise; the repo is truth. - **Not "no review."** A human reviews the spec before build and the PR after. The system makes review *fast and uniform* — it doesn't replace it. - **Not "model updates are free."** A new model may implement differently; the checks are what keep that safe, which is why the checks, not the model, are load-bearing.