Section 13Systematise — the repeatable system & a PWA template

Everything so far is a workflow you run by hand. The final move turns it into a system, so every new project starts at rung 4 instead of climbing from zero. Two layers, and inheritance between them.

Section 12 closed with a promise: budgeted context and deterministic gates shouldn't stay habits you re-establish by hand every Monday. This chapter keeps that promise, and it starts with an observation about everything that came before. Nearly every practice in this guide has quietly produced a file: standing instructions in AGENTS.md, skills for grilling and test-first work, hooks that enforce house rules, a decision log in docs/adr/ (Section 10), a pipeline definition (Section 8), an eval suite (Section 12). A workflow is those files plus your discipline. A system is those files arranged so the discipline is no longer required — so a new project physically cannot start without them.

Picture the salon owner a few months from now. The booking app took the whole guide to reach production-ready: grilling, tickets, tests, a pipeline, security gates — weeks of climbing. Then she decides to build a second product, a gift-voucher shop for the same salon. Without a system, project two starts the climb from the bottom: naked repo, no hooks, no gates, every lesson re-learned. With the two layers below, project two is born at rung 4 — her hooks fire in the very first session, tests and CI exist before the first feature, staging is a side effect of the first commit. That's what "inheritance" means here: not a metaphor, a mechanism.

Layer 1 — the config that travels with you

The first layer holds everything that is true for you regardless of project. In Claude Code that has a concrete address: a user-level CLAUDE.md (at ~/.claude/CLAUDE.md) is read at the start of every session in every project, alongside whatever the project itself provides — and your personal skills and hooks live in the same per-user config directory. That's the right home for the things you would otherwise re-type forever: the grilling and TDD skills you've refined over months, the pnpm-not-npm hook, standing preferences like "ask before adding a dependency" or "propose a plan before touching more than three files." The sorting test is one question: would I want this in every project I'll ever start? If yes, it's global. If it's about this codebase — its floor plan, its commands, its conventions — it belongs in the project's own AGENTS.md, which sits alongside and speaks for the repo.

Layer 2 — a golden path for the stack you actually use

The second layer is project-shaped: a starter repository for the kind of thing you build, with every hard-won standard from this guide already wired in. The name for this idea is a golden path, and it's worth taking seriously rather than treating the template as a convenience.

The point of the template: inheritance guarantees coverage. The non-functionals from Section 7 and the pipeline from Section 8 become impossible to forget — they're already there before the agent writes a line. A concrete golden-path template for a PWA (Progressive Web App — a website that installs and works offline like a native app) at scale:

• Build: Vite + TypeScript in strict mode (noUncheckedIndexedAccess); Workbox for offline/PWA.
• Tests: Vitest for logic, Playwright for behaviour — with video recording on, so every run produces a demo reel (Section 6).
• Pipeline: CI to Cloudflare Pages, where each preview deploy is your staging; Lighthouse performance budgets and security scans are merge gates.
• Operate: feature flags, error tracking, and Core Web Vitals RUM wired from the start.
• Steer: a lean AGENTS.md (with CLAUDE.md importing it), the pnpm-not-npm hook, the skills, docs/adr/, context.md, and a PR template that encodes the definition of done.

The full-stack extension of this template — a real database, auth, background jobs — is walked through step by step in the companion page Setup, part two: production infrastructure.

Mechanically, turning a repo into a template is one checkbox. Mark it as a template repository on GitHub and it grows a "Use this template" button that stamps out a fresh copy — your files, none of your git history — as a brand-new project. So the gift-voucher shop begins as a click: commit one already carries strict types, both test layers, the pipeline, the security scans, and the PR template that encodes the definition of done. The agent's first session reads the inherited AGENTS.md, finds the floor-plan conventions from Section 10 waiting, and starts building the first tracer bullet inside a fully-gated project. Weeks of climbing, replayed in a minute.

Compounding — one fix, every project

Two layers turn maintenance upside down. When something goes wrong in any project — an accessibility gate that turned out to be missing, a deploy step that flakes, a lesson learned at 11pm — the reflex question becomes: does this fix belong upstream? Patch it in today's repo and one project improves. Patch the template, a skill, or the global config, and every future project improves — and every past one can be pulled up to match. The skill below is that reflex made executable.

The same compounding works on your standing instructions — with one guard. When a session ends with a lesson worth keeping ("always run the migration check before seeding"), have the agent propose it as a permanent rule rather than letting it evaporate. But cap the list — around fifteen entries, oldest pruned when a new one lands — because a learnings file that only ever grows quietly eats the instruction budget Section 12 tells you to protect, and old lessons go stale just like old docs.

The mechanics of "have the agent propose it" are worth pinning down, because the difference between a learnings file that compounds and one that rots is a human gate. End each significant session with one question: "Anything from this session worth making permanent? Draft it as a one-line rule and tell me which file it belongs in — global config, this project's AGENTS.md, or the template." You approve or reject, the same way you gate any other change. For the salon app, a real entry might read "Playwright tests must create their own bookings, never rely on seeded data" — earned during an afternoon lost to a flaky test, worth exactly one line of the instruction budget, and destined for the template so the voucher shop never loses that afternoon at all.

A living docs site, not a stale wiki

AGENTS.md is terse and machine-read every session; docs/adr/ is a raw, append-only decision log. Neither is what a new teammate — or an auditor, or future-you in a year — actually wants to read. Build a third thing: an HTML documentation site generated from files in the repo, rebuilt and republished by CI on every merge to main, the same pipeline that ships the app. Docs written once and left alone rot faster than code, because nothing forces them to change when the code does; a site that only exists as a fresh build of current repo state can't drift the same way a hand-maintained wiki does.

What belongs on it, concretely — the questions this guide keeps coming back to, answered for your project specifically, not in the abstract:

Tooling: Starlight (Astro-based, fast, good defaults out of the box) or Docusaurus (React-based, larger plugin ecosystem, more moving parts) for a JS/TS project; MkDocs with the Material theme if your team leans Python. Whichever you pick, the mechanism matters more than the choice: a docs-build-and-deploy step in the same CI that ships code, and a merge-gate check that flags a PR touching auth, access, pricing, or architecture with no corresponding docs change — the same "did you update the runbook" discipline this guide already asks of disaster-recovery playbooks, applied to documentation generally. The mechanism is unglamorous: a path-based rule — a CODEOWNERS-style list mapping sensitive code paths (the auth module, billing, the schema folder) to the docs pages that describe them — so CI flags any PR that changes the left side without touching the right. Back it with one line in the reviewing agent's checklist ("does this change alter anything a docs page currently claims?") to catch the renames and logic-only changes a path list can't see. As the team grows past a handful of people, a fuller internal developer portal (Backstage is the standard open-source reference) can absorb this same content plus service ownership and catalogues — but the CI-published docs site is the right size for a small team, and grows into that later rather than needing it from day one.

For the salon owner, a documentation site can sound like enterprise ceremony — she's one person; who's the audience? The honest answer: it's insurance against exactly the situations a one-person business can't absorb. A stand-in developer taking over while she's ill for a month. An auditor — or a bigger client's procurement form — asking who can access customer data and where the DPA lives. Future-her, a year after the last change, needing to know why bookings and vouchers share a customer table. Each of those is answered today by archaeology through old chats; the docs site answers them with a URL. And because agents draft the pages from files that already exist — the ADRs, the pipeline config, the access roles — the marginal cost of the insurance has never been lower.

Measure the system, not vibes

Track whether the system actually helps, using DORA metrics: deploy frequency, lead time, change-fail rate, restore time. And run the evals from Section 12 so you improve on evidence, not gut feel.

Used alone with agents, the four numbers have a specific job: watch trends, not absolutes. Agents inflate the speed pair almost for free — of course you deploy more often when implementation costs minutes. The stability pair is where the truth lives. If change-fail rate climbs alongside deploy frequency, the message is precise: your gates are now too weak for your new speed, and the fix is tightening the template's merge gates, not slowing down by hand. DORA measures the pipeline; the evals measure the agent workflow flowing through it. One dashboard for the factory, one for the machine — and both feed the same upstream reflex: every bad trend becomes a fix to the template or a skill, not a resolution to try harder.

Fast agentic output accumulates technical debt silently unless someone looks on purpose. Thoughtworks' Tech Radar practice is a lightweight way to do that: periodically review the tools, libraries, and patterns actually in use and rank each one adopt / trial / assess / hold — so a dependency an agent pulled in eight months ago gets revisited deliberately instead of forgotten until it breaks.

The solo version fits in one quarterly session, and it's another saved prompt: "List every dependency with what it does, when we adopted it, and when its maintainers last released. List every recurring pattern in the codebase. Rank each adopt / trial / assess / hold, and propose tickets for the holds." Half an hour, four times a year — and the charting library an agent pulled in for one graph, unmaintained upstream since spring, becomes a scheduled ticket instead of a security surprise (Section 9's supply-chain worry, handled on a calendar instead of in a crisis). As with Section 10's architecture review, the session ends in tickets, not vibes.

Extract the system — don't build it first

One warning saves weeks: the template is the last move, not the first. Building a perfect golden-path template before shipping anything is procrastination wearing safety gear — you can spend a month wiring gates for projects that don't exist and learn nothing. The sequence that works is the one the salon owner actually lived: build the first project by hand, the whole climb, every chapter of this guide the slow way. Then, when the second project starts and you catch yourself re-doing something — re-writing the same hook, re-explaining the same convention, re-wiring the same pipeline — that is the moment to extract it into the template. Extracted machinery has earned its place, because it demonstrably worked in a shipping project; invented machinery is a guess with a maintenance cost. The same rule governs the small stuff: the third time you type the same correction, make it a hook; the third time you paste the same prompt, make it a skill. The system follows the work. It never precedes it.

And that ordering points at the one thing no template can contain. This chapter is the last mechanical move the guide has to offer — config, templates, docs, metrics, all of it inheritable, all of it file-shaped. What remains is not file-shaped at all: knowing when to trust the system, when to override it, and when not to hand a task to an agent in the first place. That judgment is Section 14.

Quick check: in your third project, you catch the same missing accessibility gate again. Where does the fix go?

Upstream, twice. Into the golden-path template, so every future project has the gate on commit one — and into the project-doctor skill, so every existing project can be audited up to the standard. Fixing only today's repo treats a system problem as a project problem, and guarantees a fourth encounter.

The wider chapter in one breath: turn the hand-run workflow into a system of two inheriting layers. Layer 1, global config — a user-level CLAUDE.md, your skills, your hooks — written once, inherited by every project on session one. Layer 2, a golden-path template — a starter repo where strict types, both test layers, CI, staging previews, and security gates exist before the first feature, one "Use this template" click away — so every new project is born at rung 4. Let it compound: fixes flow upstream, lessons become capped standing rules behind a human gate, and a project-doctor skill audits old repos to the current standard. Publish a living docs site from repo files via the same CI that ships the code — architecture, pipeline, access, legal, monitoring, onboarding — because a generated site can't drift the way a wiki does. Measure the system with DORA's four numbers (trends, not absolutes — watch the stability pair) plus Section 12's evals, and re-rank accumulated tools Tech-Radar-style on a calendar. And extract all of it from real shipped work rather than building it in advance — the system serves the shipping, never the reverse.