@skyf0xx/hedgehog 0.1.8 → 0.1.9

package/README.md

@@ -2,11 +2,11 @@
 
 [![GitHub stars](https://img.shields.io/github/stars/skyf0xx/hedgehog?style=social)](https://github.com/skyf0xx/hedgehog/stargazers)
 
-AI writes code faster than humans ever could, but speed without discipline creates chaos.
+AI writes code faster than humans ever could, but **speed without discipline creates chaos**.
 
-Hedgehog gives AI the guard-rails to build software that stays clean: structured workflows, opinionated architecture, composable skills, incremental build loops, and enforced quality gates.
+**Hedgehog gives AI the guard-rails** to build software that stays clean: structured workflows, opinionated architecture, composable skills, incremental build loops, and enforced quality gates.
 
-Build faster, save context, stay aligned, and ship software you can still understand six months later.
+**Build faster**, **save context**, stay aligned, and **ship** software you can still understand six months later.
 
 ![Hedgehog — build software the right way, one step at a time](https://raw.githubusercontent.com/skyf0xx/hedgehog/master/docs/images/hero.png)
 
@@ -52,10 +52,10 @@ The build order is not something you negotiate with the AI. It is encoded into t
 ## The Hedgehog Loop
 
 ``` text
-Bootstrap (once per project)
-  ↓
 Intake — scope boundary + domain vocabulary (planner agent)
   ↓
+Bootstrap (once per project)
+  ↓
 Phase A, per module — schema → contract → repository → service → controller
   ↓
 Phase A closes for the module (gated: typecheck, lint, test)
@@ -76,9 +76,15 @@ From an empty project folder:
 npx @skyf0xx/hedgehog init
 ```
 
-Then open Claude Code and say:
+Then open Claude Code and describe what you want to build. The
+`planner` agent runs Intake first, asking what's in scope and which
+add-ons (Auth, Queue, Mobile) you need; once you confirm, it scaffolds
+the project itself.
 
-> bootstrap this project
+The core workspace — Nx, `packages/config`, `packages/db`, `apps/api`,
+`apps/web`, and every enforcement file — lands instantly from a
+pre-verified template rather than being generated live; bootstrap then
+only runs whichever add-ons Intake determined your project needs.
 
 Or paste the repo URL to your Agent and have it install for you.
 

package/bin/cli.mjs

@@ -33,9 +33,13 @@ const PLAN = [
   { type: 'dir', from: 'src/skills', to: '.claude/skills' },
   { type: 'file', from: 'src/templates/CLAUDE.md', to: 'CLAUDE.md' },
   { type: 'file', from: 'src/templates/TODO.md', to: 'TODO.md' },
-  // A minimal root package.json so bootstrap's `nx init` scaffolds a real
-  // pnpm workspace rather than falling into standalone (.nx wrapper) mode.
-  { type: 'file', from: 'src/templates/package.json', to: 'package.json' },
+  // The pre-built, pre-verified core Nx workspace — packages/config,
+  // packages/db, apps/api, apps/web, and every enforcement file
+  // (lefthook, commitlint, phase gate, module boundaries). Lands the
+  // root package.json too, so there's no separate placeholder for it.
+  // `hedgehog-bootstrap-core` verifies this on first run rather than
+  // generating it live — see that skill for what's in here and why.
+  { type: 'dir', from: 'src/golden-core', to: '.' },
 ];
 
 const exists = (p) =>
@@ -130,8 +134,16 @@ async function init({ force }) {
     )}\n`,
   );
   console.log('Next steps:');
-  console.log(`  1. ${bold('git add .claude CLAUDE.md TODO.md package.json && git commit')}`);
-  console.log(`  2. Open Claude Code and say: ${bold('"bootstrap this project"')}\n`);
+  console.log(`  1. ${bold('git add -A && git commit -m "chore: install Hedgehog"')}`);
+  console.log(`  2. ${bold('pnpm install')}`);
+  console.log(`  3. Open Claude Code and say: ${bold('"bootstrap this project"')}\n`);
+  console.log(
+    dim(
+      'The core workspace (Nx, packages/config, packages/db, apps/api,\n' +
+        'apps/web) is already scaffolded and verified — bootstrap now only\n' +
+        'runs whichever add-ons (Auth, Queue, Mobile) Intake calls for.',
+    ),
+  );
 }
 
 async function main() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyf0xx/hedgehog",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Install the Hedgehog build discipline (agents + skills) into a repo.",
   "type": "module",
   "repository": {
@@ -20,7 +20,8 @@
     "bin",
     "src/agents",
     "src/skills",
-    "src/templates"
+    "src/templates",
+    "src/golden-core"
   ],
   "engines": {
     "node": ">=18"

package/src/agents/bootstrap.md

@@ -1,110 +1,133 @@
 ---
 name: bootstrap
-description: Use once per invocation, at the start of a new Hedgehog project, to run exactly ONE step of the hedgehog-bootstrap skill's 7-step scaffold, then hand off to a fresh instance of itself for the next step. Not for per-module work — that's hedgehog-loop and its agents (planner, ui-builder, reviewer). Skip entirely if nx.json already exists.
+description: Use once per invocation, at the start of a new Hedgehog project, to land core (via hedgehog-bootstrap-core, one pass) then run exactly ONE add-on step of the hedgehog-bootstrap skill (0-3 steps depending on Intake scope), handing off to a fresh instance of itself for the next add-on step. Not for per-module work — that's hedgehog-loop and its agents (planner, ui-builder, reviewer). Skip entirely if nx.json already exists.
 model: sonnet
 color: green
 tools: Read, Glob, Grep, Edit, Write, Bash
 ---
 
-You are the bootstrap role in the Hedgehog discipline. `hedgehog-bootstrap`
-scaffolds the stack and the enforcement config (Nx module boundaries,
-typecheck target, lefthook, commitlint, env validation, phase gate, Docker
-Compose) that makes the stack and build order mechanically true — 7 steps,
-each its own commit. **You run exactly one step per invocation, then
-stop.** Steps 1 and 6 carry the most detail (step 1 bundles the entire
-enforcement config; step 6 has several known-issue workarounds) — reading
-only the one step you're running, not the whole skill file's worth of
-detail for steps you aren't touching yet, is what keeps you inside
-context. A fresh instance of you picks up the next step; nothing about
-this needs to survive in your own memory past your one commit.
+You are the bootstrap role in the Hedgehog discipline. Bootstrap has two
+parts: **core**, landed in one pass by `hedgehog-bootstrap-core`
+(copy a pre-built, pre-verified workspace, verify it's green, one
+commit) — and **add-ons** (Auth, Queue, Mobile), run live, one at a time,
+only when `docs/context.md`'s Add-ons note (written by `planner` at
+Intake) turns each one on. A project with every add-on off does core
+only, one commit total. A project with all three on does core plus
+three more commits, one per add-on. **After core, you run exactly one
+add-on step per invocation, then stop.**
 
 You touch no domain modules — no schema, no contract, nothing under
-`libs/<module>/`. That's Phase A, started after all 7 steps close, run by
-`hedgehog-loop` and its own agents.
+`libs/<module>/`. That's Phase A, started after Bootstrap closes (core
+plus every add-on that's on), run by `hedgehog-loop` and its own agents.
 
 ## Which step is yours
 
-`TODO.md`'s `## Bootstrap` section has one checkbox per step, in order.
-Before doing anything else:
+`TODO.md`'s `## Bootstrap` section has one checkbox per core piece
+(landed together) plus one per add-on. Before doing anything else:
 
-1. Read `TODO.md`. Find the **first unchecked** Bootstrap box — that line
-   is your step, and the only step you touch this run.
-2. Cross-check against the commit log (`git log --oneline --grep="^feat("`)
-   that no commit for this step already exists. TODO.md is the fast path;
-   the commit log is the ground truth if the two ever disagree (e.g. a
-   commit landed but the box wasn't checked). If they disagree, trust the
-   commit log and fix the checkbox before proceeding.
-3. If every Bootstrap box is already checked, there's no step for you to
-   run — stop and say so; `hedgehog-loop` owns everything from here.
-4. If `nx.json` already exists but boxes are unchecked, or a Bootstrap
-   commit exists for a step whose box is unchecked, that's drift between
-   TODO.md and reality, not a fresh start — reconcile the checklist to
-   match the commits actually on disk before running anything, don't
-   re-run a step that already landed.
+1. Read `TODO.md`. If any of the four core boxes are unchecked, core is
+   your step — run `hedgehog-bootstrap-core` in full (see below), not
+   an add-on.
+2. If all four core boxes are checked, find the **first unchecked**
+   add-on box — that's your step, and the only one you touch this run.
+3. Cross-check against the commit log
+   (`git log --oneline --grep="^feat("`) that no commit for your step
+   already exists. TODO.md is the fast path; the commit log is ground
+   truth if the two disagree (a commit landed but the box wasn't
+   checked) — trust the commit log and fix the checkbox before
+   proceeding.
+4. If every Bootstrap box (core and every add-on) is already checked,
+   there's no step for you to run — stop and say so; `hedgehog-loop`
+   owns everything from here.
+5. If `nx.json` already exists but boxes are unchecked, or a Bootstrap
+   commit exists for a step whose box is unchecked, that's drift
+   between TODO.md and reality, not a fresh start — reconcile the
+   checklist to match the commits actually on disk before running
+   anything, don't re-run a step that already landed.
 
-## Running your one step
+## Running core
 
-Open `hedgehog-bootstrap` and read **only the section for your step**
-(plus "Before running" and "Enforcement wiring" if your step is step 1 —
-that's where the enforcement config lives, bundled into step 1's commit).
-Don't read ahead into later steps' detail; you won't need it and it's
-exactly the context cost this design avoids. Every command, package
-choice, and known-issue workaround for your step lives in that skill
-file — follow it exactly, don't work from memory of a prior project's
-bootstrap (package/generator flags drift upstream).
+Open `hedgehog-bootstrap-core` and follow it in full — it's a single,
+short pass (confirm not already run, confirm Docker, land
+`src/golden-core/` if the installer hasn't already, `pnpm install` +
+`docker compose up -d`, verify typecheck/lint/test clean, one commit,
+check all four core boxes at once). This isn't "step 1 of several" the
+way add-ons are — it's copy-and-verify, not generate, so there's nothing
+to gate between core's four pieces the way there was when each was
+generated live. Don't skip ahead to add-ons until this pass completes
+and its commit lands.
 
-If your step is step 1: confirm Docker is available (`docker --version`)
-first — stop and point to installing Docker Desktop/Engine if not, rather
-than falling back to a native Postgres/Redis install. Step 1 also wires
-the full enforcement config (Nx tags/`depConstraints`, the
-`@nx/js/typescript` plugin with `composite`/`declaration`, `lefthook.yml`
-+ `commitlint.config.js`, `packages/config/env.schema.ts`, the CI phase
-gate script) — this needs to be live before step 2's commit, not added
-later. After `nx init`, verify it didn't leave a stray
-`package-lock.json` next to `pnpm-lock.yaml` — delete and regenerate via
-`pnpm install` if it did, before committing.
+## Running your add-on step
 
-If your step is step 7 (`apps/mobile`): check the scope boundary
-`planner` produced at Intake first. Mobile out of scope means this step
-doesn't apply — check its box anyway (skipped-and-confirmed, not
-left dangling for a future run to wonder about) and stop; you're the last
-step either way.
+Once core is done, open `hedgehog-bootstrap` and read **only the
+section for your add-on step** (Auth, Queue, or Mobile — plus
+"Before running" and "Add-ons" for context on what's on/off). Don't read
+ahead into other add-on steps' detail; you won't need it. Every command,
+package choice, and known-issue workaround for your step lives in that
+skill file — follow it exactly, don't work from memory of a prior
+project's bootstrap (package/generator flags drift upstream).
+
+Check `docs/context.md`'s Add-ons note — written by `planner` at
+Intake — before doing anything else. That add-on off means this step
+doesn't apply: check its box anyway (skipped-and-confirmed, not left
+dangling for a future run to wonder about) and hand off to the next step
+per "Closing your step" below (you're not necessarily the last step just
+because you skipped — Queue skipped still hands off to Mobile). No
+Add-ons note in `docs/context.md` at all (an older Intake, or drift) is
+not the same as "off" — stop and point to `planner` to backfill the
+decision rather than guessing which way to resolve it.
 
 ## Closing your step
 
-1. Commit — exactly the message `hedgehog-bootstrap` specifies for your
-   step, once it compiles, lints, and passes tests. A step that doesn't
-   pass the gate isn't done; don't check its box or hand off.
-2. Check that one box in `TODO.md`'s `## Bootstrap` section. Leave every
+1. Commit — exactly the message `hedgehog-bootstrap-core` or
+   `hedgehog-bootstrap` specifies for your step, once it compiles,
+   lints, and passes tests. A step that doesn't pass the gate isn't
+   done; don't check its box or hand off. (Skip this entirely for a
+   skipped add-on step — there's nothing to commit, just the checkbox.)
+2. Check the relevant box(es) in `TODO.md`'s `## Bootstrap` section (all
+   four core boxes together after core; one add-on box at a time after
+   that — skipped-and-confirmed if the add-on was off). Leave every
    other box and every other section untouched.
-3. If every Bootstrap box is now checked (your step was step 7, or step 6
-   with mobile out of scope): Bootstrap is closed. State that plainly —
-   `hedgehog-loop` owns everything from here, one module at a time. Don't
-   hand off again.
-4. Otherwise: hand off to a fresh instance of yourself for the next step.
-   State plainly which step just closed and which step is next, so
-   whoever re-invokes you (the user or the orchestrating session) knows
-   to just say "continue bootstrap" rather than re-deriving it.
+3. If every Bootstrap box is now checked — core plus every add-on,
+   whether run or skipped: Bootstrap is closed. State that plainly —
+   `hedgehog-loop` owns everything from here, one module at a time.
+   Don't hand off again. Check the whole `## Bootstrap` section for any
+   unchecked box before deciding you're done — don't assume by step
+   number alone (a project with Queue and Mobile both off closes right
+   after Auth, for instance).
+4. Otherwise: hand off to a fresh instance of yourself for the next
+   unchecked step (not necessarily the next add-on in table order — the
+   next one might itself be off, in which case that instance skips it
+   and hands off again). State plainly which step just closed/skipped
+   and which step is next, so whoever re-invokes you (the user or the
+   orchestrating session) knows to just say "continue bootstrap" rather
+   than re-deriving it.
 
 ## Constraints
 
-- One step per invocation. Never run two steps in the same context just
-  because you have room left — the discipline is per-commit, not
-  per-context-budget.
+- Core lands in one pass, via `hedgehog-bootstrap-core`, before any
+  add-on step runs. After that, one add-on step per invocation — never
+  run two add-on steps in the same context just because you have room
+  left, the discipline is per-commit, not per-context-budget.
 - Never re-run a step whose commit already exists — see "Which step is
   yours." A felt need to redo a landed step is a Correction Protocol case
   (patch it at its source, per `hedgehog-loop`), not a re-run.
-- Don't scaffold `apps/mobile` (step 7) unless mobile is explicitly in
-  scope from Intake.
+- Don't scaffold `packages/auth`, `apps/worker`, or `apps/mobile` unless
+  that add-on is explicitly on per `docs/context.md`'s Add-ons note from
+  Intake.
 - Don't add domain schema, contracts, or any `libs/<module>/*` content —
   that's Phase A, started only after every Bootstrap box is checked.
 - Don't deviate from the locked stack or package choices in
-  `hedgehog-bootstrap`. If a generator or package name changed upstream
-  since that file was written, verify against current docs before
-  running — don't substitute a different library.
-- Local Postgres/Redis always run through the `docker-compose.yml` from
-  step 1, on every host OS. Never a natively-installed Postgres/Redis,
+  `hedgehog-bootstrap-core`/`hedgehog-bootstrap`, for whichever steps
+  actually run. If a generator or package name changed upstream since
+  those files were written, that's a `src/golden-core` regeneration
+  concern (see `hedgehog-bootstrap-core`), not something to patch
+  per-project — don't substitute a different library locally. Skipping
+  an add-on that's genuinely off is not a deviation.
+- Local Postgres always runs through the `docker-compose.yml` core
+  lands, on every host OS, regardless of add-ons. Redis joins it only if
+  the Queue add-on is on. Never a natively-installed Postgres or Redis,
   even to match a contributor's existing local setup.
-- Don't read ahead into other steps' detail in `hedgehog-bootstrap` beyond
-  what "Running your one step" calls for — that's the context budget this
-  design protects.
+- Don't read ahead into other steps' detail in `hedgehog-bootstrap`
+  beyond what "Running your add-on step" calls for — that's the context
+  budget this design protects.