Genesis

Genesis — foundation first, understand the problem, THEN build

You are running genesis. Apply the axiomatic-induction constitution throughout (read it first). Greenfield only — if the folder already holds a real codebase, stop and say genesis is greenfield-only — unless this is a resume (a half-built genesis repo relaunching after a usage pause; see below).

Resuming a paused run — CHECK THIS FIRST (before the greenfield guard or any phase)

A run that hit the usage limit checkpointed and halted; the external resumer (or you) relaunches genesis after the window resets with a prompt like "Resume the paused genesis build." Before the greenfield guard or any phase, check for a resume marker:

• If .scratch/resume.json (or .scratch/resume.json.inflight) exists, or .scratch/acceptance.json

exists with criteria_met=false → this is a RESUME, not a fresh start. Do Phase R and nothing else.

• Otherwise → it's a fresh start: apply the greenfield guard and begin at Phase 0.

Phase R — Resume (skip the greenfield guard and Phases 0–5)

1. Do NOT abort on the existing codebase, and do NOT re-run Phases 0–5 — the foundation, research,

design, stack, and plan already exist on disk; re-running would duplicate or clobber work.

1. Load the checkpoint. Read .scratch/resume.json — canonical schema

{ "next_item": "", "state": "", "expected_reset": "" } (the overlord wrote it at pause) — plus .scratch/acceptance.json, docs/TODO.md, and docs/TODO-done.md.

1. Reconcile in-flight work. Whatever was mid-build when it paused (state) may be partial — re-verify it

with test-gate before trusting it; if it's broken/incomplete, reset that item to [~] and rebuild it.

1. Re-enter Phase 6 at next_item. Hand control back to the overlord, which resumes its loop exactly

as in Phase 6 (pick next → roster → build → test → review → integrate → advance → checkpoint), under the same usage-guard / self-verify / defer-credentialed rules. Run to 100% as usual.

1. Clear the marker once resumed: remove .scratch/resume.json.inflight (the daemon's transient rename) so

a later pause writes a fresh resume.json.

The order of operations is STRICT — do not jump ahead

The #1 mistake to avoid: do not ask about or decide the stack, framework, or package manager until Phase 4. A problem does not start with "what stack?" — it starts with foundation and understanding. Work the phases in order; honor only the early setup gates (the Phase-0 paramount question + system prerequisites), then run uninterrupted to 100% — defer credentialed steps to the handoff, never stop mid-build to ask. Make every step idempotent (re-running updates, never duplicates). Use a TodoWrite list mirroring these phases so the order is visible and enforced. Full detail: [reference.md](reference.md).

Optional dashboard. If the user wants a UI (or says "open the dashboard"), the genesis-dashboard skill launches a local PWA. While it's running, keep .scratch/dashboard-state.json updated as you move through the phases, and check .scratch/dashboard-inbox.jsonl for button actions (connect a service, pause/resume, answer a question). The terminal flow works fine without it — the dashboard is purely a window.

Phase 0 — Capture the problem (plain English, brief)

• If invoked as /genesis use : load the seed, restate it, ask only the deltas.
• Otherwise: get the problem / objective and the prime directive (A0) in plain English. That's it.
• Do NOT ask about stack/framework/tooling here. If the user volunteers a preference, record it as a hint

for Phase 4 and move on. Don't discuss "how to build" yet.

• This is your only window to ask. If — and only if — a paramount, scope-bifurcating question isn't

answered by the prompt (e.g. consumer app vs internal tool), ask it here, batched, once (A5). After Phase 0 the run is uninterrupted to 100%: you decide everything else and log it. Default to a reasonable assumption over a question — never stop later to ask what you could have assumed and recorded.

Phase 1 — Foundation (MANDATORY for every repo; stack-agnostic)

Lay the must-have substrate before any stack talk — this is the template every genesis repo gets:

• Vendor/enable the constitution and wire the skills; write AGENTS.md (from

templates/AGENTS.template.md) + CLAUDE.md containing @AGENTS.md.

• System prerequisites — detect at the start, defer what you can. Detect what's installed (`command -v

docker, node --version, etc. — rtk-friendly, no find -not/-exec). A tool needed to build/test *at all* (the runtime, package manager) is the **one sanctioned pre-build prompt** — surface it once, batched with the Phase-0 question. A tool that only blocks *some* work (e.g. Docker for integration tests) is **documented in docs/REQUIREMENTS.md as a 🙋 handoff item and deferred** — build everything else, don't halt. Record all in docs/REQUIREMENTS.md (from templates/docs/REQUIREMENTS.md`).

• Create the docs skeleton (templates/docs/*), the .gitignore (copy templates/gitignore.template;

keep its universal + secrets + .scratch/* sections always, append the stack's once known), the .env family (from templates/env/ — only .env.example is committed; generate random secrets with the # generate: commands), .scratch/, and .github/pull_request_template.md (from templates/.github/ — so /generate-pr has a template to fill).

• Write the root README.md from templates/README.project.md (top-tier quality). **READMEs are

mandatory** — see the depth-2 rule below; seed the root now and keep folder READMEs current as the tree grows.

• Write .claude/settings.json: filesystem write-scope + secret read-denials (both layers) +

network posture (default open — only allow-list for money/PII apps; posture is outbound only). See [reference.md](reference.md) §Sandbox.

• No network exposure in dev/test (hard rule): never auto-start servers; never bind a public interface. If a

server is genuinely needed (an asked-for preview, an e2e test), bind 127.0.0.1 only — never 0.0.0.0 — and tear it down. Opening a public port happens only at deploy (a 🚧 human gate). There is no reason to expose a SaaS while building/testing it. See [reference.md](reference.md) §Network exposure.

• Self-verify the sandbox by behavior (the user never types /sandbox): attempt one out-of-scope write and

one fake-secret read; confirm both are blocked. If a check misbehaves, a setting name needs adjusting — fix it and report; otherwise say nothing and continue. (Procedure in [reference.md](reference.md) §Self-verify.)

• Lay the foundation, note what you set, and keep going — do not block for a yes (the run goes 0→100%

in one prompt). Offer to save a seed (§Seeds in reference.md) in passing, without waiting on it.

Phase 2 — Research & understand (before any architecture or stack)

• Use the sources skill + web research to understand the domain: requirements, constraints, prior art,

candidate approaches, and candidate stacks (research only — do not commit to a stack yet).

• Find the best that exists. Identify the single best-in-class product/codebase for each surface (UI/UX,

core, copy) — not just any prior art — and capture what makes it excellent. These become the named references every worker must meet or beat (AGENTS.md §1; A18/A19). Mediocre input → mediocre output; ground in the best.

• Record findings in docs/PROJECT.md and the trusted registry in docs/SOURCES.md. Ground every claim

in a real source (constitution A15); flag the uncorroborated as conjecture.

• If the project has a UI, also research design references now (2–3 best-in-class products in the same

space) and the UX patterns that make them feel good (via sources/web) — this feeds the design system in Phase 3. Low-effort UI is the default failure mode; treat design as first-class research, not "later."

Phase 3 — Architecture & docs (before stack/build)

• Draft docs/ARCHITECTURE.md — the components and the deterministic↔generative seam — and finish

docs/PROJECT.md, from the research. The architecture/spec precedes the build (A4). Record choices in docs/DECISIONS.md.

• If the project has a UI: apply the design skill to define the design system (tokens — type

scale, spacing rhythm, semantic colors + states, radius/shadow, breakpoints; a reused component library) and to spec the key screens & flows with ALL their states (loading/empty/error/success/edge) in docs/DESIGN.md (from templates/docs/DESIGN.md) — before any UI is built. Design to the simplicity bar: one clear primary action per screen, minimal text (the AI default is too much — cut), teach-by-doing, motion over words, the "parakeet test" (usable by recognition, without reading). This is what stops the output from looking low-effort or over-built.

Phase 4 — Choose the stack (NOW, and only now — derived, not assumed)

• Decide the stack (language, framework, package manager, test runner) with **rationale grounded in the

architecture + research, log it in docs/DECISIONS.md, and proceed — don't stop to confirm (honor any Phase-0 hint). Only now fill the stack-specific parts: the test harness (docs/TESTING.md), build/artifact dirs in .gitignore, the integrations the project needs (wire each from integrations/registry/*.yaml), and the list of external skills for the user to install (you list them; you don't run npx skills add). For a frontend, recommend a craft skill** (e.g. frontend-design, the Vercel React best-practices skill, or impeccable) alongside the bundled design skill.

• Instantiate the worker roster. The 5 core agents ship with the plugin and are always available; the

specialists are per-project. For each chosen integration's worker: (and any archetype-appropriate specialist), copy ${CLAUDE_PLUGIN_ROOT}/agents/_library/.md → the project's .claude/agents/.md so the overlord can dispatch it. Specialists not needed are not copied. For any UI project, always instantiate design.md and a11y.md — UI quality is not optional.

• Finalize the .env family for the chosen stack + every selected integration's env_keys; if the project

calls an external AI/provider, add fallback envs (e.g. PRIMARY_LLM, FALLBACK_LLMS) per [templates/docs/RESILIENCE.md](../../templates/docs/RESILIENCE.md). Ensure .gitignore ignores all .env* except .env.example.

• Design fallbacks & degradation (constitution's degrade law): provider fallback chains, cached/last-known

responses, and a deterministic offline/fake mode — so test scope is broad (happy path + each fallback + the degraded/offline path + injected errors). Write docs/RESILIENCE.md.

• If archetype = SaaS: plan a high-quality admin dashboard + structured logging per

[templates/docs/ADMIN-DASHBOARD.md](../../templates/docs/ADMIN-DASHBOARD.md) (version/build + server time + live refresh, log export, audit log). These become TODO items with acceptance criteria in Phase 5.

Phase 5 — Plan (the big TODO, then perfect it)

• Build the master docs/TODO.md with the todo skill: a large list, ordered by priority → ease →

dependency count, broken into sub-tasks, each with a status marker ([ ]/[~]/[?]), a verification type (🤖 auto vs 🙋 needs the human's credentials/accounts), a real → verify:, and deps:. Fill gaps with reasoned assumptions logged in docs/DECISIONS.md (don't interrogate the user — A5), then re-sort. Create the empty dated archive docs/TODO-done.md. (Deeper engineering detail can live in docs/PLAN.md; docs/TODO.md is the actionable backlog.)

• The plan must include EVERY single thing — be exhaustive, not just headline features. Use genesis's own

skills while planning (sources for research, design for the UI spec, axiomatic-induction to derive and order) — research and design come BEFORE listing build tasks, so nothing is hand-waved. Every item carries, as acceptance criteria, the named best-in-class reference it must meet or beat and the skills the worker must use (A18/A19) — so "done" means excellent, not merely working. Before declaring the plan ready, confirm it covers each dimension below (omit one only with a written reason):

• UI (if any): the simplicity bar (one primary action per screen, minimal text, teach-by-doing, motion

over words, parakeet test), every screen and every state (loading/empty/error/success/edge), the design system + component library, responsive breakpoints, accessibility (WCAG AA), minimal real microcopy — each a UI item carrying the design skill's UI definition-of-done as its acceptance criteria.

• Core/domain logic with unit + property tests; the deterministic↔generative seam typed.
• Each integration (wire + verify) and provider fallbacks/degraded/offline paths (docs/RESILIENCE.md).
• SaaS: the admin dashboard + structured logging (docs/ADMIN-DASHBOARD.md).
• Tests of broad scope: unit · property · contract · integration · e2e · visual · a11y · fallback/offline.
• Security items (per security-audit + each integration's checklist).
• Docs: root + per-folder READMEs (depth 2), ARCHITECTURE, DESIGN, DEPLOYMENT, REQUIREMENTS.
• Ops: logging, health checks, the deployment handoff.

Phase 6 — Build autonomously (the overlord drives)

Hand control to the overlord agent (Opus). It loops, one docs/TODO.md item at a time: pick next → compose the worker roster → builder (test-first) → tester (test-gate) → reviewer + secaudit → review every detail vs AGENTS.md + constitution → integrate or bounce → advance the item's status (todo skill; 🙋 items are deferred to docs/DEPLOYMENT.md, not asked about mid-run or auto-closed) → update .scratch/acceptance.json.

• The excellence bar (overlord §The bar): every artifact must meet or beat its **named best-in-class

reference and use the relevant skills; the overlord briefs to that reference, reviews against it + the §VII invariants, and bounces anything merely adequate — "working" is the floor, not done. Perfect = crafted to the best that exists and** the simplest thing that clears it (A18/A19/A11), never bloated.

• Fundamentals before fan-out (overlord Dispatch discipline): early waves dispatch only the few workers

that build prerequisites (skeleton, test harness, core types/seam); widen to many parallel workers only after the foundation is in place and green. Don't spawn a swarm before the substrate exists; never dispatch an item whose deps: aren't satisfied. Fewer, well-sequenced workers beat 100 premature ones. Code and UI/UX work always runs on the best model available (Opus); the run-and-report roles (tester, docs-writer) inherit the run's model. Efficiency comes from fewer dispatches, not cheaper ones — scale the roster to each item's risk (a typo doesn't need the full chain; batch trivial items into one brief).

• Usage-aware (usage-guard): at the threshold it stops starting new work, lets in-flight workers finish,

checkpoints silently (a state-save — it never asks you to restart it or confirm a resume), and halts cleanly so the external resumer auto-resumes after the reset.

• Run to 100%, never stop to ask (overlord §Run to 100%): empty repo → built/tested/reviewed/documented

SaaS in one prompt. Never ask a choice question — if options are all on docs/TODO.md, do them all in dependency order. Decide and log anything the

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: gabrieldabbah
• Source: gabrieldabbah/genesis
• License: MIT
• Homepage: https://brandcrafter.app

Install and usage instructions live in the source repository linked above.