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 — <why>. 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.

--- 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: <Feature name>

## 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 — <why>".

## Security gate
auth/data/infra impact — or "N/A — <why>".

## 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/<area>/<name>.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 — <why> 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.