starter-kit/README.md

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

# Methodology Starter Kit

This is a **portable engineering method**, not a code framework. It carries the belt (Spec → Design →
Build → Verify → Operate), the gates, the MUST/SHOULD rules, and the hard-won controls
(conformance = done, the build-completion testing battery, the production-readiness checklist,
honest-reporting discipline). No app code, no stack lock-in — drop it into any repo and the agent runs
the process against **your** spec.

## It works in three modes — same files, different starting phase
The method is **mode-aware** (see `CLAUDE.md §2` + Section 0 `Mode:`), so this kit is not
"new-project only":

1. **New project** → set `Mode: new`. Start at **Phase 1 (Spec)**. Use kickoff **A** (CLAUDE.md §13).
2. **Drop into an existing project** → set `Mode: existing`. Start at **Phase 0**: the agent inventories
   what's there, runs a **compliance audit** against the MUSTs/SHOULDs, reports, and remediates to
   compliance before moving forward. Use kickoff **B** (onboard) or **C** (compliance-check only).
3. **Keep it as a project's living base** → it stays in the repo as `CLAUDE.md` and the `design/`
   register. Every slice updates `conformance.md`; every change goes through `change-log.md`; every
   lesson feeds back into `CLAUDE.md` (Phase 5). That's exactly how the project this was extracted from
   uses it — the kit *is* that base, generalised.

## 3-minute setup
1. Copy this folder's contents into the new/existing repo root.
2. Open **`CLAUDE.md` → Section 0** and fill it in (project, **Mode**, stack, scope, sensitive data,
   reviewers). Fill the stack lines in **§11** and the **domain invariants** in `.specify/memory/constitution.md`.
3. Wire `scripts/verify.sh` + `scripts/security_check.sh` to your stack's commands (`<FILL IN>` lines),
   `chmod +x scripts/*.sh`.
4. Paste the matching **kickoff prompt** (CLAUDE.md §13) to the agent. It takes it from there, stopping
   at each gate.

## What's inside
```
CLAUDE.md                     the SOP — belt, gates, MUSTs, testing battery, prod-readiness, kickoffs
methodology/
  build-methodology-core.md   the portable core (belt + change-control §9)
roles/                        hat files: verification-agent (the STLC), design-agent, experience-agent
.specify/memory/constitution.md   the MUSTs mirror + your domain invariants  (fill in)
design/
  functional-spec.md          Phase-1 spec template
  architecture.md             Phase-2 technical design template
  acceptance-criteria.md      AC-*/SIT-* traceability template
  conformance.md              MUST-9 delivered-vs-approved register (the anti-drift control)
  change-log.md               change-control register (CR classes 1–4) + incident retrospectives
  uat-script.md               L4a human UAT template (not a render-check)
  security-checklist.md       domain-sized security gate
  qa/test-report-TEMPLATE.md  build-milestone QA report + production-readiness checklist
WAIVERS.md                    recorded MUST waivers (no silent skips)
scripts/
  verify.sh                   L0–L4b layered pipeline (stack-neutral)
  security_check.sh           deps audit · secret scan · .env hygiene
```

## The two rules that make it work (learned the expensive way)
- **Conformance is the definition of done (MUST-9).** "Delivered == the approved design," proven
  adversarially every slice in `conformance.md`. Green unit/e2e tests are *plumbing*, never conformance.
- **A build isn't "done" or "production-ready" on a vibe.** At a milestone, run the full testing battery
  (scenario, penetration, responsive, a11y, UX, visual-regression, load, cross-browser), write the QA
  report, and fill the production-readiness checklist with evidence. Mark honestly what was **not** run.

Keep improving it: when something slips, write the root cause + the new control into `CLAUDE.md` and the
change-log. The method is supposed to get sharper every project it runs.