Project Firestarter — start every project production-ready

Why it exists

Every new repo re-pays the same tax: wire up CI, write the commit conventions, remember the Docker gotchas, set up review and auto-merge, document onboarding. It takes days, it's inconsistent across projects, and last project's hard-won lessons rarely reach the next one. Firestarter pays that tax once — and gives you a documented process to fold new lessons back in.

The merits

Concrete wins you get on day one, not eventually.

🐳

Zero host SDKs

Everything runs in Docker. No "install Node/Python/Dart" — make up and go. New contributors productive in one command.

🤖

AI-reviewed auto-merge

A workflow calls the Anthropic API, posts a verdict, and squash-merges green PRs. No human-review bottleneck.

✅

Green before push

One make precommit mirrors every CI gate locally, in Docker. Stop pushing to "see if CI passes."

📐

Conventions enforced

Conventional Commits + forward-only migrations enforced by git hooks and CI — not left to discipline.

🔭

It documents itself

A storyboard harness renders a live planned-vs-implemented map from real screenshots of your UI — now a stack precept, so every stack ships one.

🛡️

Privacy-split dashboards

Opt-in native and static-web references share one verified operational model while keeping local-only records on-device and publishing only an explicit sanitized snapshot.

🚀

Share where safe

Deploy-enabled web stacks expose a local app through make deploy; client-only and security-gated stacks keep distribution owner-gated.

🧩

Stacks + add-ons

FastAPI+Next.js, Supabase+Flutter, a Manifest V3 browser extension, or a durable Node notifier — gotchas baked into comments. Auth, capture, narration, secret, orchestration, service-supervisor, semantic browser-policy, SSRF, agent, and k8s add-ons stay opt-in.

🤝

AI-agent ready

A root AGENTS.md lets Claude Code, Codex, Cursor, or Aider drive the repo on sight.

Proven, not theoretical

Firestarter runs its own template on itself — same CI, AI review, and auto-merge it ships. Every feature in it landed through that pipeline.

100%

of its own features shipped via AI-reviewed auto-merge

host SDKs required to build

production-track stacks ready to stamp

command to share your app publicly

One operational model, two safe surfaces

The opt-in dashboard references keep workstation state and browser sharing as separate trust decisions. Both validate the same queue, test, resource-budget, and signal records; every record declares whether it is sanitized or local-only and whether it is verified, estimated, unavailable, or not implemented.

local control surface

Native macOS floater

Imports a canonical local snapshot into sandboxed storage, rejects unverified local-only records and unsafe input files, and retains a validated snapshot rollback. It does not transmit local state or self-update.

sanitized sharing surface

Static browser dashboard

Renders one explicitly supplied sanitized-remote snapshot. An offline publisher drops local-only records, verifies privacy and immutable release hashes, compensates failed activation, and never opens a browser-to-workstation bridge.

Read the usage, validation, publication, and rollback guide ↗

Quickstart

You need only Docker. The generator itself runs in a container — nothing touches your host.

# Interactive — prompts for every value (Enter = default):
./bin/firestart.sh

# Non-interactive:
./bin/firestart.sh --defaults --set project_slug=lighthouse --set stack=fastapi-next

# A browser-extension project:
./bin/firestart.sh --defaults --set stack=chrome-extension --set project_slug=buddy

# A durable notification tutorial:
./bin/firestart.sh --defaults --set stack=node-notifier --set project_slug=relay

# Opt-in add-ons (all off by default):
./bin/firestart.sh --set include_auth=yes   # or include_bug_report, include_ssrf_fetch, include_k8s

Then: make hook-install → make up && make migrate → gh secret set ANTHROPIC_API_KEY to turn on the reviewer.

Four real stacks

fastapi-next lineage

fastapi-next

FastAPI + PostgreSQL/pgvector + Redis backend · Next.js (App Router) frontend · Playwright storyboard.

supabase-flutter lineage

supabase-flutter

Postgres/PostGIS + PostgREST + GoTrue · Flutter app · Dart service layer · React/Vite splash — with the ARM64 / schema-reload / GoTrue gotchas baked into the comments.

chrome-extension lineage

chrome-extension

Manifest V3 extension · esbuild build · Vitest units · host-only Playwright e2e that loads the unpacked extension · a side-panel storyboard. The first DB-less stack.

durable notification lineage

node-notifier

Express + BullMQ + private Redis + Socket.IO · saved task reconciliation · explicit acknowledgement · local signed sessions · provider-neutral OIDC production boundary · real-Redis tests and a live lifecycle storyboard.

How it works

A firestarter.config.json manifest declares the variables; a stdlib-only generator (run in Docker — no pip) substitutes {{ tokens }} and overlays the chosen stack. Substitution is whitelist-only, so GitHub Actions ${{ … }} is never clobbered.

1 · Configure

Answer a few prompts (or pass flags / a JSON file). Pick a stack, set the name, ports, and scopes.

2 · Stamp

The generator overlays the universal meta-layer + your stack (+ any add-ons) into a fresh repo.

3 · Ship

make up, push a PR, and the AI reviewer + auto-merge take it from there.