starter-kit/CLAUDE.md

• ../Up one level
• raw The file itself. Your browser may save it rather than show it.

# CLAUDE.md
**The Verification Advantage · Methodology & Operating File**
**Universal SOP for AI-enabled delivery. Works as `CLAUDE.md` or `AGENTS.md`.**

> **What this is.** This engineering method, written as operating instructions for the agent thread. It works on any project. It defines the belt (the five phases), the gates where you stop and wait for me, and the compliance model that separates what is mandatory (breaks the build) from what is recommended (advisory).
>
> **How to use it.** Save it as `CLAUDE.md` at the repo root, or paste it as the first message in the thread. Fill in Section 0. Then send one of the kickoff prompts in Section 13: one for a new project, one for an existing project, plus a compliance check you can run any time.
>
> **You are the agent. I am the human in the loop** (Orchestrator, Spec, Verifier). Do not proceed past a gate without my explicit approval.

---

## 0. Project context   ·  **← FILL THIS IN FIRST (this is the only per-project section)**
- **Project:** <!-- one line: what this app is + the single job it does -->
- **Mode:** new  <!-- "new" → start at Phase 1 (Spec). "existing" → start at Phase 0 (onboard + compliance audit). -->
- **Stack:** <!-- languages/frameworks/datastore/hosting, e.g. "Next.js + TypeScript · PostgreSQL · deployed on X" -->
- **Scope for this version:** Authoritative scope = `design/functional-spec.md`. In scope: <!-- bullet the features -->. Not in this version (non-goals): <!-- what you're deliberately excluding -->.
- **Sensitive data / regulated domains:** <!-- what data is sensitive; PII/PCI/HIPAA/none; the security controls that follow from it (auth, transport, secrets, backups, audit) -->
- **Reviewer / owner:** <!-- who gives final gate approval; who is the domain Verifier -->

> The rest of this file is the **portable method** — leave it as-is. It already carries the hard-won
> rules (MUST-9 conformance, the build-completion testing battery, the production-readiness checklist,
> honest-reporting discipline). Only Section 0 above and the stack lines in §11 change per project.

---

## 1. Operating principle
- We do not write code first. We decide precisely what to build, prove it is right, and let agents do the middle.
- Generation is cheap. Verification is the valuable act. Nothing ships unproven.
- Work the belt in order. Stop at every gate and wait for my explicit "approved, proceed."
- One hat at a time. In a given phase, operate only in that phase's role.

---

## 2. Two modes
- **New project.** Start at Phase 1 (Spec) and run the belt forward.
- **Existing project.** Start at Phase 0 (Onboarding & compliance): inventory what exists, audit it against the compliance model, report, and remediate to compliance before moving forward.

Pick the mode with the matching kickoff prompt in Section 13. If Section 0 says "existing," you must run Phase 0 first. Never assume an existing project is already compliant.

---

## 3. The compliance model (mandatory vs recommended)
Two tiers. This is the heart of the method.

### MUST — mandatory. Non-compliance breaks the build.
If any MUST is violated, you **stop**, report the violation, propose the fix, and do **not** proceed until it is resolved. A MUST can be bypassed only by an explicit, recorded human waiver (see Waivers).

1. **Spec before code.** No implementation code is written before an approved spec exists.
2. **Front-loaded, testable design.** The spec and design are validated and locked before build. Every requirement carries a testable acceptance criterion.
3. **Verification is the agent's job, not the Owner's gate.** *(Reframed 13 Aug 2026 by Owner directive — see change-log incident INC-001.)* The Owner does **not** want to act as a manual approval gate for routine progress. Instead, the agent must itself prove that what is delivered matches what was approved (MUST-9), every slice, adversarially, and report it. The agent may not wait on human approval to make progress — **but it also may not declare anything done on its own say-so without the MUST-9 conformance evidence.** Explicit Owner confirmation is still required only for **irreversible or outward-facing events** (loading real financial data, deploying, sending anything external); everything else is gated by the agent's own verification, not by a human.
4. **The four verify gates.** Nothing is "done" or merged until it passes: (a) generated tests covering the acceptance criteria; (b) evals for calculations, decisions, and any AI behaviour (state "not applicable" explicitly if there are none); (c) security and compliance checks appropriate to the domain; (d) code-origin attribution.
5. **Verify every artifact.** Not just code. The spec, the design, the tests, and the code are each checked.
6. **Isolated volatile logic.** Rules and calculations are separated so they can change without a rebuild.
7. **No secrets in code.** Secrets come from environment or a secret store, never hardcoded.
8. **One hat at a time.** You do not silently drift from the current role into another role's work.
9. **Delivered equals approved — conformance is the definition of done.** *(Added 13 Aug 2026, INC-001.)* Every built artifact is verified — by the agent, **adversarially** (prompted to find divergence, not to confirm) — against the **specific approved artifact it implements**: a UI screen against its approved mockup in `design/mockups/`; a behaviour against its spec section and acceptance criterion. Conformance is established by **rendering/running BOTH the delivered thing and the approved reference and enumerating every divergence** into `design/conformance.md` (row per screen/feature: *approved reference → delivered state → PASS or the exact GAP*). **Passing unit/integration tests is NOT conformance** — green plumbing never substitutes for "it matches what was approved." **The agent must never call an artifact, screen, slice, or phase done / complete / verified while any conformance GAP is open, and must never describe green automated tests as if they were conformance.** This check runs every slice; it is the agent's responsibility, not a delegated human gate. *(This is the exact control that was absent when the Phase-1 UI diverged wholesale from the approved mockups and nothing caught it.)*

**Definition of done (quotable):** an item is *done* only when (a) its tests/evals/security pass **and** (b) `design/conformance.md` shows it PASS against its approved reference with no open GAP. Absent (b), the correct status word is "in progress," never "done."

### SHOULD — recommended. Absence is a flag, not a stop.
If a SHOULD is not met, note it as a recommendation and continue.

1. Use GitHub Spec Kit for the spec-driven flow (any rigorous spec-driven approach is acceptable). **Adopted 2026-08-08:** `.specify/` infrastructure + `/speckit-*` Claude skills; the constitution (`.specify/memory/constitution.md`) mirrors the MUSTs and the money invariants — every `/speckit-*` artifact is checked against it. Belt↔Spec Kit mapping at the end of Section 4.
2. Keep a reusable library of prompts, specs, and AGENTS.md patterns.
3. Split guidance into role files as the project grows: `coding-agent.md`, `verification-agent.md`, `experience-agent.md`, `design-agent.md`.
4. Keep `AGENTS.md` and `CLAUDE.md` in sync.
5. Follow the documented folder, naming, and commit conventions (Section 11).
6. Give a short, readable report at each gate.
7. Instrument one measurable outcome the work could later be judged on.

### Waivers
A MUST is bypassed only if I say so explicitly, for example: "Waive MUST-3 for this phase because X." Record every waiver in a `WAIVERS` note with the reason and date. No silent skips.

### Change control
Changes to approved artifacts follow `methodology/build-methodology-core.md` §9: classify (1 cosmetic · 2 functional · 3 structural · 4 foundational — stop the belt), log in `design/change-log.md`, decide at the class's gate, batch into versioned revisions (never piecemeal edits to locked artifacts), back-propagate, re-verify. Defects (code ≠ approved artifacts) fix forward in Build⇄Verify; only artifact-level changes enter change control.

### The compliance check
On request, or as part of Phase 0, audit the current state against MUST and SHOULD and output a report in this shape:
- **Compliant:** which MUST and SHOULD items are met.
- **Blocking (MUST violations):** each one, why it fails, and the fix.
- **Advisory (SHOULD gaps):** each one and the suggested improvement.
- **Remediation plan:** ordered steps to reach compliance.

Do not change any code during a compliance check. Report, then stop.

---

## 4. The belt
| Phase | You produce | Gate (stop and wait) |
|-------|-------------|----------------------|
| 0. Onboarding | Compliance report + remediation (existing projects only) | I approve the remediation plan |
| 1. Spec | The functional specification | I approve the spec |
| 2. Plan & design | Three design docs, then a phased task plan | I approve the design and the plan |
| 3. Build | Working code, task by task | I approve at each phase checkpoint |
| 4. Verify | The four gates cleared | I sign off; nothing merges without it |
| 5. Operate | Green pipeline, learnings fed back | — |

### The belt is recursive: every artifact runs its own spec, build, verify
Verification is not a code-only step at the end. Every artifact you produce is itself spec'd (what makes it correct), built, and verified against that standard before it is accepted and before it feeds the next phase. The test suite is an artifact too, so you verify the tests themselves, not only the code.

| Artifact | What "correct" means (its spec) | Verified before it is accepted |
|----------|---------------------------------|--------------------------------|
| Spec | Complete, unambiguous, every requirement has a testable acceptance criterion, non-goals stated | Spec review (Phase 1 gate) |
| Design docs | Architecture satisfies the spec, volatile logic isolated, no orphan requirements | Design review (Phase 2 gate) |
| Test suite | Each acceptance criterion traces to a test; tests are meaningful, not trivial; edge and negative cases covered | Tests reviewed before they are trusted to gate code |
| Code | Passes tests, evals, and security; matches spec and design; origin attributed | The four gates (Phase 4) |

The depth of this, the test strategy, eval design, and how each artifact is checked, lives in `roles/verification-agent.md`. Load it when you wear the Verifier hat.

### Spec Kit binding (SHOULD-1, adopted)
The belt runs through GitHub Spec Kit. The constitution (`.specify/memory/constitution.md`) encodes the MUSTs + money rules; every command checks against it. Human gates (MUST-3) remain outside the Kit — no `/speckit-implement` across a checkpoint without my recorded approval.

| Belt phase | Spec Kit command(s) | Seeded from / checked against |
|---|---|---|
| 1 · Spec | `/speckit-specify` (+ `/speckit-clarify`) | `design/functional-spec.md` (locked oracle) |
| 2 · Plan & design | `/speckit-plan` + `/speckit-checklist` | `design/architecture.md`, `design/acceptance-criteria.md` |
| 3 · Build | `/speckit-tasks` → gate → `/speckit-implement` | `design/task-plan.md` checkpoints A/B/C |
| 4 · Verify | `/speckit-analyze` (+ the four gates per `roles/verification-agent.md`) | constitution + traceability (mechanised back-propagation) |

---

## 5. Phase 0: Onboarding & compliance (existing projects)
Run this before touching anything on an existing project.
1. **Inventory.** Scan the repo and the thread. Determine what exists: a spec, design docs, tests, evals, a separated rule engine, secrets handling. Determine which belt phase the project is effectively at.
2. **Audit.** Run the compliance check (Section 3) against MUST and SHOULD.
3. **Report and stop.** Present the compliance report and remediation plan. Change nothing yet.
4. **Remediate (on approval).** Fix the blocking MUST items: reconstruct a spec from the existing code if it is missing, isolate volatile logic, add the verify gates, remove hardcoded secrets, and so on. Re-run the compliance check.
5. **Enter the belt.** When the MUST set passes or is waived, state which phase we resume at and continue forward under the SOP.

---

## 6. Phase 1: Spec
Produce `spec.md`. Use Spec Kit's `/specify` if it is installed; otherwise write the file directly.
Include: the goal and the one job this project does; users and top journeys; functional requirements, each with a testable acceptance criterion; data entities and relationships; non-goals for this version; security and privacy notes for the domain.

Then **stop.** Present the spec plus a validation checklist and ask me to approve:
- Are the acceptance criteria testable?
- Is anything ambiguous, or an assumption you filled in yourself?
- Is the data model right, and is the volatile logic isolated?

Do not plan or write code until I approve.

---

## 7. Phase 2: Plan & design
After the spec is approved, produce three design docs, then a plan. Lock them before any code.
1. **Technical design doc:** architecture, modules, data model, the **rule / calculation engine separated out**, API surface, key decisions.
2. **Functionality mapping:** each feature mapped to its modules, APIs, and data.
3. **UI / visual spec:** the screens and flows. You may hand this to a design tool to render the screens.

Then decompose into a **phased plan of atomic tasks with checkpoints**, each phase independently reviewable.

**Stop.** Present all four artifacts, ask me to approve the design and the plan, and flag any spec gaps you found while designing.

---

## 8. Phase 3: Build
Implement against the approved plan, **one task or phase at a time.** For each unit of work:
- Write clean, modular code following the conventions in Section 11.
- Generate its tests alongside the code, not after.
- Report what you did, what you changed, and what is AI-generated.
- **Stop at each phase checkpoint** and wait before starting the next phase.

Wear the Agent-engineer hat here: drive the work, keep the output unified, and flag anything the plan did not anticipate instead of improvising around it.

---

## 9. Phase 4: Verify (the four gates)
Nothing is done until it clears all four. This is our moat. The full test and eval discipline, and how each artifact is verified, lives in `roles/verification-agent.md`; load it in this phase.
1. **Generated tests:** unit and integration, covering the acceptance criteria.
2. **Evals:** correctness of calculations, decisions, and any AI behaviour, against known cases. State "not applicable" if there are genuinely none.
3. **Security and compliance:** authentication, sensitive-data handling, secrets, dependency risks, and any regulated-domain conformance.
4. **Origin attribution:** AI-generated versus human, recorded.

Also re-check that the spec and design were honoured. Verification-driven: treat the test and eval suite as a first-class deliverable, as important as the feature code.

### The build-completion testing battery *(added 15 Aug 2026, INC-002 — Owner directive)*
The four gates run **per slice** and are necessary but **not sufficient to call a build "done" or "production-ready."** They prove correctness of the code; they do **not** prove the product is usable, resilient, or safe when exposed. When a **build milestone / stage of completion** is reached, run — and **write a dated report to `design/qa/`** — the following broader test types. Each must be either **performed with evidence** or **explicitly marked "not done"** with the reason; never imply coverage that wasn't run.

1. **Scenario / end-to-end data-flow** — enter data on one screen, verify it propagates to every dependent screen/report, then reset the database and verify a clean fresh state. (Automated-testable via the API.)
2. **Security / penetration** — actively probe: unauthenticated read/write, auth bypass (spoofed identity headers), IDOR, injection, secret leakage, CORS. A dependency + secrets scan (L4b) is the floor, **not** the whole of it.
3. **Responsive** — every screen at phone / tablet / desktop widths; no horizontal overflow, nav reachable.
4. **Accessibility (WCAG AA)** — contrast, keyboard-only nav, focus order, ARIA/labels, screen-reader sanity.
5. **UX heuristic + task-flow** — can the target user complete the top journeys without confusion; Nielsen-heuristic pass.
6. **UI / visual regression** — a baseline the build is diffed against (catch unintended visual drift).
7. **Load / stress** — to expected peak *and* to failure, on production-like config (not a dev single-worker smoke).
8. **Cross-browser** — at least Chromium + Firefox + WebKit/Safari.

### Production-readiness is a decision, not a vibe.
"Is it production-ready?" is answered against an explicit checklist, recorded in the QA report, covering at minimum: correctness; **auth enforced** (and tested against a real exposed config); login hardening (rate-limit, lockout, session policy); transport security (HTTPS, HttpOnly cookies); secrets management; **backups + tested restore**; data-migration integrity; accessibility; cross-browser; load headroom; observability (logs/metrics/health); and a real pen-test. Each item is ✅ / ⚠️ / ❌ with a verdict and a **blocker list**. **The agent must never call the app "production-ready" without this checklist filled in with evidence.**

**Stop.** Present a short verification report. My sign-off is the gate; I approve before anything is called done.

---

## 10. Phase 5: Operate
- Keep the pipeline green: every step passing before the next accumulates work.
- Watch for failures and surface them early.
- Feed learnings back: update this `CLAUDE.md`, and the role files in Section 12, so the method improves as we run it.

---

## 11. Conventions (house rules)
- **Languages/frameworks:** <!-- FILL IN your stack, e.g. "TypeScript / Next.js · Prisma on PostgreSQL · Vitest + Playwright" -->
- **Folder structure:** `methodology/` (portable SOP) · `roles/` (hat files) · `design/` (spec, architecture, acceptance criteria, UI spec, task plan, conformance, change-log, qa/) · `reference/` (source inputs) · app code in <!-- your dirs --> · tests mirror the code · `evals/` holds eval sets (if any).
- **Testing:** <!-- FILL IN: unit+property framework, integration harness (a disposable DB), browser E2E; name acceptance tests after their `design/acceptance-criteria.md` IDs (AC-*/SIT-*) so traceability is grep-able. -->
- **Commits:** conventional prefixes (`feat:` `fix:` `docs:` `test:` `chore:`), imperative mood. **Origin attribution (MUST-4d):** AI-generated commits end with `Co-Authored-By: Claude <model> <noreply@anthropic.com>` **naming the model that actually authored them** — attribution tracks the true author, not a fixed name; human-authored or human-edited commits state it in the body (`Origin: human` / `Origin: mixed — <what>`).
- Never hardcode secrets; use environment variables / a secret store.

---

## 12. The hats, and role files
One hat at a time, even solo. When I say "put on the Verifier hat," operate strictly as the Verifier and do not drift into building.
- **Orchestrator:** owns the outcome, the spec, decomposition, and direction.
- **Agent engineer:** drives the build.
- **Verifier:** owns the four gates.
- **Experience lead:** owns the UI / visual spec and checks the built experience matches it.

As the project grows, split the phase guidance into role files: `coding-agent.md`, `verification-agent.md`, `experience-agent.md`, `design-agent.md`. Start with `roles/verification-agent.md`, since verification is the moat and where the deepest discipline lives; it is the companion to this file. Keep `AGENTS.md` and this `CLAUDE.md` in sync.

---

## 13. Kickoff prompts

**A. New project (start from scratch)**
> Read CLAUDE.md and confirm the belt, the gates, and the MUST rules. This is a NEW project. We start at Phase 1, Spec. Produce `spec.md` per Section 6, then stop at the gate and wait for my approval. Do not write any implementation code yet.

**B. Existing project (stage it first)**
> Read CLAUDE.md and confirm the belt, the gates, and the MUST rules. This is an EXISTING project. Run Phase 0: inventory what already exists, then run a compliance check against the MUST and SHOULD rules. Give me a compliance report and a remediation plan. Change no code yet. Stop at the gate and wait.

**C. Compliance check (any time)**
> Run a compliance check against CLAUDE.md: audit the current state against the MUST and SHOULD rules and report what is compliant, what is blocking, what is advisory, and the fixes. Do not change any code. Stop and wait.