build-factory

Build Factory — autonomous headless coding loop

Use this skill to help the user (a non-developer) stand up a new autonomous build loop for a software product: Claude plans here, headless Claude Code builds in the cloud one task per branch, CI tests every PR, optional Codex review, the human merges (auto-merge only if GitHub allows), and merge can chain the next task.

Smoke-proven: ~/Projects/build-factory-toy / jzoccali/build-factory-toy (2026-07-18). Read references/05_TOY_PROOF.md before debugging auth.

How to run this skill

1. Orient the user. Roles: you (chat) = planner; Claude Code on GitHub Actions = builder (no Allow clicks); GitHub main = truth; Supabase = backend when needed; Lovable = optional UI path (not required for headless apps); Codex = optional reviewer. The repo is the shared brain.

2. Build Gate first. Then BuilderOS genesis + charter before product code:

   • genesis.md from ~/BuilderOS/templates/genesis.md
   • CLAUDE.md from assets/templates/CLAUDE.md (BuilderOS v3 header)
   • Architecture Plan (schema-first if there is a DB)
   • Prompt Library = work packets (references/03_PROMPT_LIBRARY_TEMPLATE.md)

3. Walk human setup from references/01_SETUP_CHECKLIST.md — screen by screen. Critical path:

   • Private GitHub repo
   • claude setup-token → secret CLAUDE_CODE_OAUTH_TOKEN (one continuous paste)
   • Actions: Read and write + Allow GitHub Actions to create and approve pull requests
   • Variables: LOOP_ENABLED=true
   • Claude GitHub App on the repo
   • Supabase only if the product needs it; Lovable only if the user wants that UI path

4. Drop in the harness from assets/templates/ (workflows include live fixes: id-token: write, prompt input, soft auto-merge, PR permission error message).

5. Run the loop — Actions → Build loop → Run workflow. Merge green PRs (human is normal on free private). Merging can chain the next task.

Non-negotiables

• Schema-first when there is a DB; one schema-owner; serial migrations.
• Merge gate: schema/DB → human merge; features → auto-merge only if the repo supports it (often not on free private).
• CLAUDE_CODE_OAUTH_TOKEN from claude setup-token — not a random API key, not a line-wrapped broken paste.
• BuilderOS v3 only: ~/BuilderOS/OPERATE.md + full deglaze on done.
• Debug from references/02_GOTCHAS.md + references/05_TOY_PROOF.md.
• Every factory repo should ship build-loop/PREAMBLE.md (template in assets/templates/build-loop/PREAMBLE.md): frontload decisions, freeze acceptance checks, halt only on verify commands — not full loopgen.

Files in this skill

• references/00_BOOTSTRAP_PROMPT.md — paste-into-a-new-project prompt that turns Claude into the planning brain.
• references/01_SETUP_CHECKLIST.md — human setup: repo, Supabase, Lovable, Codex review, secrets, Variables, GitHub settings, billing table.
• references/02_GOTCHAS.md — the landmine map.
• references/03_PROMPT_LIBRARY_TEMPLATE.md — task-queue template + shared preamble + worked examples.
• references/04_UPGRADES.md — v2 changelog + phase-2 roadmap.
• references/05_TOY_PROOF.md — live smoke evidence + failure table (2026-07-18).
• assets/templates/ — drop-in repo files: CLAUDE.md, workflows, queue.yml, scripts, RLS tests.

Read the relevant reference file fully before guiding the user through that step; hand them the matching template file from assets/templates/.

Governance — BuilderOS v3 (Joey's safety net)

Canonical: ~/BuilderOS/ · OPERATE: ~/BuilderOS/OPERATE.md · Bridge: ~/BuilderOS/BUILD-FACTORY-BRIDGE.md
Do not open ~/Documents/BuilderOS v2. 2/ for normal factory builds (archive/librarian only).

Before scaffolding an app:

1. Build Gate + preflight — fill project genesis.md from ~/BuilderOS/templates/genesis.md (why build, build vs buy, one loop, scale honesty, deps, 14-day proof).
2. Charter — project CLAUDE.md from v3 template (this skill’s assets/templates/CLAUDE.md after merge).
3. Architecture Plan only after genesis — schema-first for the whole product.
4. Prompt Library tasks = work packets: in/out scope, files allowed, completion contract, evidence commands, no adjacent systems.
5. Done = CI green + evidence block in PR + full deglaze (~/BuilderOS/library/deglaze/SKILL.md). AI claims are not evidence.
6. Manifest + court at checkpoints (manifest.json, court.html).
7. Health/medical-adjacent apps: genesis MUST include safety section (not-medical-advice, sensitive-data, sourced domain logic).

Rebuild checklist: ~/BuilderOS/BUILD-FACTORY-BRIDGE.md.