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, Codex reviews, a fix-pass resolves findings, the human merges, and merge deploys + chains the next task.

How to run this skill

1. Orient the user. Roles in one breath: you (Claude in chat) = planner/coordinator; Claude Code on GitHub Actions = builder; Codex = reviewer; GitHub main = source of truth; Supabase = backend; Lovable = UI (added last); GHL = notifications. The repo is the shared brain.

2. Build Gate first, then interview. Before scaffolding, confirm building is the right move now — not avoidance of validation or a sale. Then write the three canonical docs — in this order. Do not write code yet.

   • Architecture Plan — schema-first data model for the whole product, RLS rules, storage, integrations. Multi-tenant tables carry an owner/tenant id and are RLS-protected. RLS helpers go in a private. schema (never auth.), search_path pinned, execute to authenticated.
   • CLAUDE.md — repo standing orders. Start from assets/templates/CLAUDE.md, adapt lightly. It is BuilderOS-governed — set the governance tier and keep the governance header (security floor + evidence-based done + Build Gate).
   • Prompt Library — the task queue: one bounded prompt = one branch = one PR, in dependency order. Use references/03_PROMPT_LIBRARY_TEMPLATE.md.

3. Walk the human setup from references/01_SETUP_CHECKLIST.md: private GitHub repo → own Supabase project (not Lovable Cloud) → Lovable connected to that repo + Supabase → install the Claude GitHub App → claude setup-token → add GitHub secrets → set repo/branch-protection settings. Name the exact screen and the exact text to paste, numbered.

4. Drop in the harness — copy assets/templates/ into the new repo: .github/workflows/{build-loop,ci,fix-pass,deploy,codex-autofix}.yml, build-loop/{queue.yml,scripts/*}, tests/{rls.test.mjs,README.md}, and CLAUDE.md. Set the repo Variables (NOTIFY_EMAIL, LOOP_ENABLED, MAX_BUDGET_USD, BUILDER_MODEL) and the MAIL_* secrets. Have the user build the first schema task by hand and confirm CI is green (RLS test passes) before enabling feature-lane auto-merge.

5. Run the loop — Actions → Build loop → Run workflow. Review PR + Codex findings, merge (human for schema/DB, auto for features). Merge chains the next task.

Non-negotiables (carry these into every build)

• Schema-first: design the whole data model once; never refactor it later.
• One schema-owner, serial append-only migrations. Feature agents request schema changes, never write them.
• Merge gate: schema/DB PRs → human merges; feature PRs → auto-merge on green CI.
• Subscription token, not API key: the loop runs on CLAUDE_CODE_OAUTH_TOKEN. A fresh API key's ~10k tokens/min limit kills the builder with a 429.
• Make open decisions configurable, not hard-coded.
• Governed by BuilderOS (builderos-doctrine): the Build Gate (is building the right move, or is the next step validation/a sale?), the security floor (secrets server-side only, RLS mandatory), and evidence-based done are non-moving. Answer the Build Gate before queuing feature tasks.
• Before debugging anything, read references/02_GOTCHAS.md — CI-gate fix, GitHub App identity (PRs from the default token don't trigger CI), compose-from-main ordering, private. schema for RLS helpers, no whitespace in secrets, fresh-run vs re-run, show_full_output: true.

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 (review loop, email alerts, budget cap, kill-switch, RLS harness) + the phase-2 roadmap.
• assets/templates/ — drop-in repo files: CLAUDE.md, the five workflows (build-loop, ci, fix-pass, deploy, codex-autofix), queue.yml, the selector + prompt-extractor scripts, and the tests/ RLS harness.

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

Governance — run through BuilderOS (Joey's safety net)

Before planning an app, open a project-genesis/ brief in BuilderOS (~/Documents/BuilderOS v2. 2/): problem, evidence, scope, deal-breakers. That brief feeds this skill's Architecture Plan. Build Factory's CI + Codex review satisfy BuilderOS's evidence standard ("AI claims are not evidence — verify"); the merge gate is the human audit. On ship, close with a lessons-learned/ entry + a changelog/ line. Route any new ideas to incoming/ or candidates/ — NEVER write to core/ directly (Joey's doctrine). For health/medical-adjacent apps, the genesis brief MUST include a safety section (not-medical-advice, sensitive-data handling, sourced domain logic).