# Genesis

> Turn an empty folder into a working, tested, secured project. Use when the user says \"/genesis\", \"create the project\", \"start a new project\", \"scaffold this\", or begins greenfield work. Follows a STRICT order: lay the mandatory foundation (constitution, skills, AGENTS.md, docs, hardened sandbox) FIRST, then research the problem, then design the architecture, THEN choose the stack, then pl…

- **Type:** Skill
- **Install:** `agentstack add skill-gabrieldabbah-genesis-genesis`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [gabrieldabbah](https://agentstack.voostack.com/s/gabrieldabbah)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [gabrieldabbah](https://github.com/gabrieldabbah)
- **Source:** https://github.com/gabrieldabbah/genesis/tree/main/skills/genesis
- **Website:** https://brandcrafter.app

## Install

```sh
agentstack add skill-gabrieldabbah-genesis-genesis
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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.
2. **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`.
3. **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.
4. **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.
5. **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](https://github.com/gabrieldabbah)
- **Source:** [gabrieldabbah/genesis](https://github.com/gabrieldabbah/genesis)
- **License:** MIT
- **Homepage:** https://brandcrafter.app

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-gabrieldabbah-genesis-genesis
- Seller: https://agentstack.voostack.com/s/gabrieldabbah
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.