Playbook: New Project

Objective

A repo where an agent can work productively and safely: scaffolded stack, CLAUDE.md, an ARCHITECTURE.md skeleton, a first spec, and enforced quality gates — all before the second feature exists. Rails before cargo: every hour spent on rails at hour zero saves a session of cleanup per week for the life of the project, because agents amplify whatever structure exists on day one — including its absence.

When to use

Greenfield, empty directory, you own the decisions. If the idea itself is still fuzzy, run Idea to Spec first. If the repo already exists, this playbook is over — go to MVP Build or Add a Feature.

Inputs required

• A one-paragraph statement of what the system is and who uses it.
• A stack decision — see step 1. The agent can inform this; it must not own it.
• Deployment target (even provisional: "Fly.io", "a VPS", "internal k8s").

Step-by-step process

1. Decide the stack yourself

Decide it directly if you have conviction. If not, make the agent present options rather than pick:

I'm building <one-paragraph description>. Team: <size and background>.
Deployment target: <target>. Propose 2–3 stack options. For each: the
components, why it fits THIS project, operational cost, and the strongest
argument against it. Bias toward boring, widely-documented technology.
Do not recommend one. Do not write any code.

You choose. An agent left to choose optimizes for what's plentiful in training data or what's novel — neither is your criterion, and you'll operate this stack for years. See Exploring Options and What Not to Delegate.

2. Scaffold the walking skeleton

Scaffold a new <stack> project in this empty directory. Requirements:

- Use the standard generator (<e.g. npm create vite, django-admin startproject>)
  where one exists; hand-roll nothing the generator provides.
- One trivial end-to-end path that proves the wiring: one route/page returning
  real data from one DB table (a `health` or `notes` table is fine).
- Include: README with run instructions, .env.example, .gitignore,
  and the test runner installed with ONE passing test.
- Do NOT add: auth, docker-compose for services we don't have yet, an
  abstraction layer, folders for features that don't exist, or any library
  not needed to run the skeleton.
- Target size: under 25 files. If you're about to exceed that, stop and
  show me the file list first.

When done, print the exact commands to run the app and the test.

Run those commands yourself. Do not proceed on the agent's claim that it works.

3. Governing docs — before feature one

This is the step everyone skips because feature one is more fun. Skipping it means every future session re-derives (differently) what these docs would have said.

The skeleton runs. Before any feature work, create three docs:

1. CLAUDE.md — commands to run/test/lint, the stack and versions, code
   conventions you inferred from the scaffold, and a "never do" list I'll
   dictate: <e.g. never edit generated files, never add a dependency without
   asking, never commit directly to main>.
2. ARCHITECTURE.md — skeleton only: the components that exist today, one
   line each, plus an empty "Decisions" section. No aspirational content —
   nothing that doesn't exist yet.
3. specs/001-<first-feature>.md — a spec skeleton for the first real
   feature with empty sections: Goal, Non-goals, Acceptance criteria,
   Out of scope. I will fill in the content.

Keep all three short. These are living docs, not documentation theater.

Then edit them by hand — especially the CLAUDE.md never-do list and the spec's acceptance criteria. Templates: Repo Docs and Specs and Planning; rationale: CLAUDE.md and AGENTS.md.

4. Quality gates — before feature two

Feature one may proceed on the spec from step 3. Nothing else lands until gates exist, because ungated agent output is unverifiable by definition — you'd be accepting claims, not code:

Set up quality gates for this repo:

- typecheck, lint (with the stack's standard config, not a custom one),
  and test — each runnable as a single command, documented in CLAUDE.md.
- One `make check` (or npm run check) that runs all three.
- CI (<GitHub Actions>) running `check` on every push and PR; failures block merge.

Then prove the gates work: introduce a deliberate type error, show me the
CI-equivalent command failing locally, and revert it.

The deliberate-failure proof is the point. A gate that has never been red is not known to exist. See Quality Gates.

Human review points

1. Stack choice — yours alone (step 1).
2. Skeleton runs — you execute the run/test commands with your own hands (step 2).
3. Governing docs — you personally edit CLAUDE.md rules and the spec's acceptance criteria (step 3).
4. Gates go red — you witness the deliberate failure fail (step 4).

Expected artifacts

Running skeleton (< ~25 files) · CLAUDE.md · ARCHITECTURE.md skeleton · specs/001-*.md · one-command check · CI that has been observed red and green.

Common failures

Symptom	Root cause	Early detection	Fix
Agent scaffolds an exotic stack ("Bun + Elysia + Drizzle + HTMX")	Optimizing for novelty/recency, not your operability	It happens in step 1 — you never let the agent decide	Name the stack in the scaffold prompt; regenerate rather than migrate
40 files of abstraction before any feature — repositories, DI container, core/interfaces/	Agent pattern-matches "serious project" boilerplate from training data	File count in the scaffold diff; folders named after patterns instead of features	The under 25 files / "stop and show me the list" constraint; delete speculative layers on sight — they cost nothing to re-add later
No test runner, so "it works" is unverifiable	Test setup deferred as "not a feature"	You can't complete step 4	Test runner ships inside the scaffold prompt with one passing test — non-negotiable
CLAUDE.md written after ten features	Docs treated as documentation, not steering	Session 2 re-asks questions session 1 answered	Step 3 is ordered before feature one for exactly this reason
CI green because it runs nothing	Workflow file exists but wires to no-op scripts	The deliberate-failure proof stays green	Fix the wiring; never trust an untested gate

Recovery strategy

Wrong stack or over-scaffolded before feature one: delete and rescaffold with a corrected prompt — at this stage regeneration is minutes and untangling is hours. If features already exist on a bad skeleton, stop feature work, run steps 3–4 retroactively, then continue. If it's the stack itself that's wrong post-features, that's a Migration.

Acceptance criteria

• [ ] Skeleton's end-to-end path verified by a human-executed command
• [ ] CLAUDE.md, ARCHITECTURE.md, and spec 001 exist and were human-edited
• [ ] check command runs typecheck + lint + test; CI blocks merge on failure
• [ ] The gate has been observed red on a deliberate error
• [ ] Zero speculative abstractions: every file traceable to the skeleton path or a doc

Related

• Idea to Spec — run first when the idea itself is still vague.
• MVP Build — the natural next playbook once rails exist.
• CLAUDE.md and AGENTS.md — what belongs in the steering file you just created.
• Repo Docs templates — fill-in-able CLAUDE.md and ARCHITECTURE.md starting points.
• Quality Gates — deeper treatment of the gates step 4 installs.
• What Not to Delegate — why stack choice stayed with you.