A forkable starting point for Claude Code projects, extracted from a real production app (MysteryMixClub). It ships the workflow layer that made that project pleasant to build with Claude — subagents, a disciplined CLAUDE.md, non-negotiable git hygiene, a full local hook chain, and CI — wrapped around a minimal but running FastAPI + React skeleton, so every quality gate is green from the first clone.
- Click Use this template on GitHub (or fork/clone).
- Open the repo in Claude Code and say:
Claude interviews you (name, description, issue tracker, branch model, design tokens), rewrites every placeholder, re-verifies the gates, and deletes SETUP.md. Details: SETUP.md.
Read SETUP.md and run the setup. - Run the stack:
scripts/dev-up.sh→ web on :5173, API on :8000, Postgres in Docker. (stop/logs/checksubcommands included.)
Prerequisites: Node 20+, Python 3.11+, Docker with Compose v2. dev-up.sh
offers to install the first two if missing.
The workflow layer (the actual point of this template):
CLAUDE.md— session-start ritual (read the docs, load the sprint, confirm before acting), working rules, CI/CD summary, a "known gotchas" section of lessons learned the hard way, and a docs map..claude/agents/— four subagents with deliberate separation of duties:developer(implements, never reviews itself),reviewer(read-only, PASS/FAIL reports),tester(writes/runs tests, never fixes code),ui-agent(owns the design system, enforces the style guide).docs/git-hygiene.md— non-negotiable git rules: branch-before-code, one branch at a time, the squash-merge trap and its reconciliation gate, and the hook PATH gotcha. Battle-tested; read it once and you'll know why each rule exists.- Local hook chain (Husky v9):
pre-commit→ lint-staged (ESLint/Prettier- ruff),
commit-msg→ commitlint (Conventional Commits),pre-push→ frontend typecheck + backend pytest. Installed bynpm installat the root.
- ruff),
- CI (
.github/workflows/ci.yml): frontend lint/typecheck/test; backend ruff/mypy/pytest+coverage against real Postgres, an Alembic upgrade→downgrade→upgrade round-trip on every PR, and non-blocking dependency audits. Needs zero secrets. docs/taxonomy — design / technical / prd / discovery / qa / security, each stub explaining what belongs there, plus feature-flag conventions.- Guided foundation interviews — three interview-style walkthroughs Claude
runs with you after bootstrap to create your PRD
(
docs/prd/prd-interview.md), technical design (docs/technical/technical-design-interview.md), and design system (docs/design/style-guide-interview.md— mood in, enforced palette/type tokens out, wired into Tailwind and the agents). Each deletes itself once its document exists. examples/deploy-digitalocean/— a complete, inert reference deploy (staging on a Droplet, production on App Platform, approval-gated) to adapt or replace.
The skeleton app (small on purpose):
backend/— FastAPI + async SQLAlchemy + Alembic (wired, with an empty initial migration) + pydantic-settings;/healthroute; pytest suite that hits a real test database.frontend/— Vite + React + TypeScript + Tailwind (named design tokens only); one page that calls/healthto prove the full plumbing; Vitest + Testing Library.
feature/* off develop → PR into develop (CI must pass) → merge →
PR develop → main as a deliberate production promotion. CI runs on PRs
(plus manual workflow_dispatch). After creating your repo, configure branch
protection — the checklist is in docs/ci-cd.md; protection
settings don't travel with a template. Prefer trunk-based? The SETUP.md
bootstrap offers a main-only variant.
Prose files use {{TOKENS}}; runnable files use the literal slug myapp so
everything works before bootstrap. The bootstrap ends with a grep contract
proving no placeholder survived. You can also do it by hand — the full
inventory table is in SETUP.md.
MIT — see LICENSE. Your generated project is yours; relicense as you wish.