# RUNBOOK — Executing GENESIS.md with Claude Code

> How to actually run the master prompt and turn it into the `enterprise-genesis` template repository. Read once before your first bootstrap. Reference during execution.

---

## TL;DR

1. Install Claude Code, create empty repo folder, drop `GENESIS.md` + `project.config.json` inside, `git init`.
2. Open Claude Code in that folder.
3. Use **Mode 4 (Checkpoint Auto-Commit)** for your first run.
4. Approve each phase one at a time. Claude handles validation + git commits.
5. After Phase 9 completes, push the repo as `enterprise-genesis`.
6. For new projects, **do not re-run this prompt** — clone the repo and run `_init.ps1`.

---

## PRE-FLIGHT — One-Time Setup (~10 minutes)

### 1. Install prerequisites

```bash
# Claude Code
npm install -g @anthropic-ai/claude-code

# Verify
claude --version

# Node (for the template's stack)
node --version   # need 20+

# pnpm
npm install -g pnpm

# .NET (optional, if your project.config.json picks dotnet)
dotnet --version # need 9+

# Docker (for local services)
docker --version
```

### 2. Create the workspace

```bash
mkdir enterprise-genesis
cd enterprise-genesis
git init
git branch -M main
```

### 3. Drop in the two source files

Place these at the root of `enterprise-genesis/`:

- `GENESIS.md` — the master prompt you generated earlier
- `project.config.json` — example below (edit to taste)

Minimal starter `project.config.json`:

```json
{
  "projectName": "LOMA-PORTAL",
  "projectSlug": "loma-portal",
  "projectNamespace": "Loma.Portal",
  "projectDbName": "loma_portal",
  "companyName": "Loma Group",
  "extends": ["angular-enterprise", "dotnet-enterprise", "portal-platform", "premium-theme"],
  "frontend": { "primary": "angular", "secondary": "nextjs" },
  "backend": { "primary": "dotnet", "secondary": "nestjs" },
  "database": { "engine": "postgres", "secondary": "sqlserver", "cache": "redis" },
  "auth": { "strategy": "jwt+refresh", "providers": ["local"], "rbac": true, "multiTenant": false },
  "features": {
    "signalR": true,
    "websocket": true,
    "queueWorker": true,
    "auditLog": true,
    "softDelete": true,
    "i18n": ["en", "th"]
  },
  "ui": { "framework": "tailwind+material", "style": "premium", "darkMode": true, "pwa": true },
  "deployment": { "targets": ["docker", "k8s"], "ci": "gitlab" },
  "ai": { "preferredModel": "claude-opus", "governanceLevel": "strict" },
  "compliance": { "pdpa": true, "gdpr": true, "auditTrail": true }
}
```

### 4. Initial commit

```bash
git add GENESIS.md project.config.json
git commit -m "chore: seed GENESIS prompt and project config"
```

### 5. Launch Claude Code

```bash
claude
```

You're now ready. Pick a mode below.

---

## MODE 4 — Checkpoint Auto-Commit ⭐ (RECOMMENDED for first run)

Claude executes each phase, validates, commits, then asks one yes/no before continuing.

### Bootstrap message (paste once at the start)

```
You are about to execute GENESIS.md to bootstrap the enterprise-genesis template
repository. Read both files at the repo root: GENESIS.md and project.config.json.

Operating mode: CHECKPOINT AUTO-COMMIT

For every phase from 0 through 9, do the following loop:
  1. Echo the phase name and brief plan.
  2. Generate all artifacts required by that phase per GENESIS.md.
  3. Run local validators (pnpm validate / dotnet build / docker compose config)
     as far as they exist at that point.
  4. If anything fails, fix it before continuing. Do not move on with broken state.
  5. Stage and commit with this exact format:
        git add -A
        git commit -m "phase-<N>: <short title> ✅"
  6. Print the §6 STOP CONDITIONS report exactly.
  7. Ask: "Proceed to Phase <N+1>? (yes / no / pause / clear)"
       - yes   = continue
       - no    = halt for manual work
       - pause = stop, I'll resume later in a new session
       - clear = recommend /clear before next phase (context heavy)
  8. Wait for my reply. Do not proceed until I answer.

Start now with Phase 0.
```

### Per-phase user replies

After each phase, Claude will print a phase report and ask. You reply with just one word:

```
yes
```

That's it. Claude handles validation, commit, and starts the next phase.

If something looks off:

```
no — issue: <describe what's wrong>
```

Claude fixes and re-asks.

### When context gets heavy (recommended around Phase 5-6)

When Claude suggests `clear` or you notice slow responses:

```
/clear
```

Then resume:

```
Resume execution of GENESIS.md in CHECKPOINT AUTO-COMMIT mode.
Read git log to determine last completed phase, then proceed to the next.
```

Claude Code auto-loads `CLAUDE.md` on a fresh session, so context recovers fast.

---

## MODE 1 — Full Manual (most control, slowest)

Best for your very first time if you want to inspect every output before committing.

### Phase 0 — Pre-flight

In Claude Code:

```
Read GENESIS.md and project.config.json.
Execute ONLY Phase 0 (Pre-flight): echo resolved presets, write the plan
for Phases 1–9, then STOP. Do not generate any files yet.
```

Review the plan. If happy, proceed.

### Phase 1 — Monorepo Foundation

```
Execute ONLY Phase 1 per GENESIS.md §41. Stop after and emit the §6 report.
Do not start Phase 2.
```

When Claude is done, drop to a terminal (or use Claude's bash tool):

```bash
# Verify Day-1 criteria
pnpm install
docker compose up -d
pnpm validate

# Commit
git add -A
git commit -m "phase-1: monorepo foundation"
```

### Phase 2 — Preset System

Back in Claude Code:

```
Phase 1 committed. Execute ONLY Phase 2. Stop after.
```

Validate, commit:

```bash
pnpm validate
git add -A && git commit -m "phase-2: preset system"
```

### Phases 3 through 9

Same pattern. Use this template:

```
Phase <N-1> committed. Execute ONLY Phase <N>. Stop after.
```

```bash
# Phase-specific validation, then:
git add -A && git commit -m "phase-<N>: <short title>"
```

**Phase-specific validation cheatsheet:**

| Phase | Validation commands                                             |
| ----- | --------------------------------------------------------------- |
| 1     | `pnpm install && docker compose config && pnpm validate`        |
| 2     | `ls presets/ && cat presets/stacks/*/preset.json`               |
| 3     | `pnpm --filter web-* build && pnpm --filter web-* test`         |
| 4     | `dotnet build && pnpm --filter api-* test`                      |
| 5     | `pnpm prisma validate && pnpm prisma migrate dev --create-only` |
| 6     | `pnpm --filter enterprise-modules-* test`                       |
| 7     | `ls .claude/{commands,agents,skills,hooks} && ls .mcp/`         |
| 8     | `pnpm test && pnpm test:e2e && pnpm lint && pnpm typecheck`     |
| 9     | `ls docs/{onboarding,runbooks,decisions}`                       |

---

## MODE 3 — Hybrid Batched (recommended for re-runs)

Use after you've done Mode 1 or Mode 4 once and trust the system.

### Batch plan

| Batch | Phases | Why batched                            |
| ----- | ------ | -------------------------------------- |
| A     | 0, 1   | Critical foundation, do manually       |
| B     | 2, 3   | Presets + frontend, related            |
| C     | 4, 5   | Backend + Prisma, tightly coupled      |
| D     | 6, 7   | Enterprise modules + AI layer          |
| E     | 8      | DevOps alone (heaviest)                |
| F     | 9      | Documentation alone (review carefully) |

### Bootstrap message

```
Execute GENESIS.md in HYBRID BATCH mode using this plan:
  Batch A: Phase 0, Phase 1 — stop after each (manual review).
  Batch B: Phase 2, Phase 3 — validate + commit each, stop after batch.
  Batch C: Phase 4, Phase 5 — validate + commit each, stop after batch.
  Batch D: Phase 6, Phase 7 — validate + commit each, stop after batch.
  Batch E: Phase 8 alone — validate + commit, stop after.
  Batch F: Phase 9 alone — validate + commit, stop after.

For every phase, run validators and commit with:
  git commit -m "phase-<N>: <short title> ✅"

Stop and ask before starting each batch. Start with Batch A, Phase 0.
```

---

## MODE 2 — Fully Autonomous (NOT recommended for first run)

⚠️ This mode **conflicts with §6 STOP CONDITIONS** of GENESIS.md.
Only use after you have done Mode 1 or 4 at least once and want to re-bootstrap quickly.

```
Execute GENESIS.md autonomously through all phases 0-9.
Override §6: do NOT stop between phases unless a validation fails.
For each phase: generate → validate → commit ("phase-<N>: <title> ✅") → continue.
On any validation failure: stop immediately and report.
At the end of Phase 9, print full execution summary.
```

If you use Mode 2, monitor the output. If anything looks wrong, interrupt with **Ctrl+C** and run:

```
git status
git log --oneline
```

…to see where Claude got to. Resume in Mode 4 from the last clean commit.

---

## RECOVERY — When Things Go Wrong

### A phase fails validation

Claude in Mode 4 will not commit a broken phase. Tell it:

```
Diagnose the failure. Show me:
1. Which validator failed
2. What changed in this phase
3. Three options to fix, ranked by risk
Wait for my pick before changing anything.
```

### Wrong files were committed

```bash
# Reset to previous phase
git log --oneline                    # find the last good phase commit
git reset --hard <commit-hash>

# Tell Claude in the next session:
# "Resume from Phase <last good N>. Read git log to confirm state."
```

### Context window exhausted

```
/clear
```

Then:

```
Resume GENESIS.md execution in <Mode 4>. Read git log to determine the last
completed phase, read CLAUDE.md and GENESIS.md, then proceed to the next phase.
```

### Claude drifted from the spec

```
Halt. Show me a diff of what you just generated vs what GENESIS.md §<N>
specifies. Identify any deviations. Wait for my decision.
```

---

## OPTIONAL — Permission Modes for Speed

Claude Code prompts before every shell command and edit by default. For the bootstrap, that's a lot of prompts. Options:

### Option A — Run with auto-accept for edits

```bash
claude --permission-mode acceptEdits
```

Edits auto-approve; shell commands still prompt.

### Option B — Use the project-level allow list

The `.claude/settings.json` generated in Phase 1 already declares allowed tools per GENESIS §23.1. From Phase 2 onward, prompts drop dramatically.

### Option C — Per-session permission

When Claude asks the first time, choose "Yes, and don't ask again this session" for safe operations like `pnpm:*`, `dotnet build`, `git status|diff|log|add|commit`. Never give blanket approval to `rm`, `git push --force`, or env file edits.

---

## AFTER PHASE 9 — Publishing the Template

### 1. Final smoke test

```bash
pnpm install
docker compose up -d
pnpm dev          # all apps must start
pnpm validate     # all validators pass
pnpm test         # seeded tests pass
```

Open the running app. Log in with the seeded admin user. If it works → template is real.

### 2. Push to GitLab / GitHub

```bash
# Example (replace with your org)
git remote add origin git@gitlab.com:loma-group/enterprise-genesis.git
git push -u origin main

# Tag the release
git tag -a v1.0.0 -m "Initial bootstrap of enterprise-genesis"
git push --tags
```

### 3. Make the repo a template

- GitHub: **Settings → Template repository → enable**
- GitLab: **Settings → General → Project templates → register**

### 4. Document the spawn workflow

Add to your team's wiki/Notion:

```
To start a new project:
  git clone git@gitlab.com:loma-group/enterprise-genesis.git my-new-project
  cd my-new-project
  rm -rf .git && git init
  # edit project.config.json
  ./_init.ps1 -Config ./project.config.json   # or _init.sh on macOS/Linux
```

---

## FAQ

**Q: Can I skip a phase?**
A: Not phases 0-1 (foundation). Phases 2-9 can be deferred but expect breakage. Better: complete all phases, then disable/remove what you don't need afterward.

**Q: Phase 9 looks heavy. Can I do it last week of the sprint?**
A: Yes. Phases 1-8 give a working system. Phase 9 (docs/onboarding) can run later, but do it within 2 weeks while context is fresh.

**Q: I want to change project.config.json mid-way. Bad idea?**
A: Yes. Finish all phases first, then re-bootstrap with a new config in a new folder. Configs are not designed to mutate mid-run.

**Q: Can two developers run this in parallel on the same repo?**
A: No. One driver only. Use git worktrees if you must parallelize spawned projects later.

**Q: How long does each phase take?**
A: Rough estimates with Mode 4 on Claude Opus 4.x:

| Phase     | Generation | Validation | Total       |
| --------- | ---------- | ---------- | ----------- |
| 0         | 30 s       | —          | 1 min       |
| 1         | 5 min      | 2 min      | 7 min       |
| 2         | 4 min      | 1 min      | 5 min       |
| 3         | 12 min     | 3 min      | 15 min      |
| 4         | 12 min     | 3 min      | 15 min      |
| 5         | 6 min      | 2 min      | 8 min       |
| 6         | 10 min     | 2 min      | 12 min      |
| 7         | 15 min     | 2 min      | 17 min      |
| 8         | 12 min     | 4 min      | 16 min      |
| 9         | 8 min      | 1 min      | 9 min       |
| **Total** |            |            | **~1h 45m** |

Add ~30 min for human review between phases.

**Q: I want to do Mode 4 but also have Claude skip the confirmation if all validators pass.**
A: Change step 7 in the bootstrap message to: _"If all validators passed, auto-proceed to the next phase. Only ask for confirmation if any validator failed or if the next phase is 7, 8, or 9."_ This is **Mode 4.5** — auto for safe phases, confirm for heavy ones.

---

## QUICK REFERENCE CARD

```
START
  └─ claude
      └─ paste Mode 4 bootstrap message
          └─ for each phase: reply "yes"
              └─ /clear if context heavy
                  └─ Phase 9 done? → push to remote → make template repo
```

That's the whole loop.
