@skyf0xx/hedgehog 0.1.7 → 0.1.9

package/README.md

@@ -1,20 +1,12 @@
-# The Antidote to AI Spaghetti Code
+# The Antidote to AI Spaghetti Code ⭐
 
-AI can write code faster than humans ever could.
+[![GitHub stars](https://img.shields.io/github/stars/skyf0xx/hedgehog?style=social)](https://github.com/skyf0xx/hedgehog/stargazers)
 
-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 it needs to **build software that stays clean.**
+**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.
 
-A complete development methodology combining:
-
-- structured workflows
-- opinionated architecture
-- composable skills
-- incremental build loops
-- enforced quality gates
-
-**Build faster, Save context**. Stay aligned. 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)
 
@@ -22,27 +14,22 @@ A complete development methodology combining:
 
 1. An opinionated stack
 2. An enforced build order
-3. Agents and skills that make good engineering the default.
+3. Agents and skills that make good engineering the default
 
-## Hedghog's secret to great outcomes
+## Hedgehog's secret to great outcomes
 
-- 🧩 **Progressive layering:** types → schema → backend → UI, each layer built on a stable one beneath it
-- 🎯 **Small context loops:** decompose work into atomic, verifiable changes
-- 🌳 **Self-documenting architecture:** the codebase carries the context, not the AI
-- 🔁 **Traceable evolution:** decisions are preserved through conventional commits
+- **Progressive layering:** types → schema → backend → UI, each layer built on a stable one beneath it
+- **Small context loops:** decompose work into atomic, verifiable changes
+- **Self-documenting architecture:** the codebase carries the context, not the AI
+- **Traceable evolution:** decisions are preserved through conventional commits
 
 ![Just describe what you want](https://raw.githubusercontent.com/skyf0xx/hedgehog/master/docs/images/curve.png)
 
 ## Why Hedgehog Exists
 
-AI coding starts fast then breaks down.
-
-Context accumulates, prompts get longer, architecture drifts.
+AI coding starts fast, then breaks down. Context accumulates, prompts get longer, architecture drifts. Eventually, adding one more feature feels dangerous.
 
-Eventually, adding one more feature feels
-dangerous.
-
-**The enemy isn't AI. It's the absence of guardrails.**
+Hedgehog's answer: guardrails, not more discipline from the AI.
 
 ## Plans Expire. Structure Doesn't
 
@@ -65,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)
@@ -89,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.
 
@@ -115,7 +108,7 @@ AI becomes the builder operating inside those constraints — turning ideas into
 
 ## Architecture
 
-Hedgehog is a package of agents and skills. An opinionated stack is used so the build order above is mechanical and enforced by the tooling itself:
+Hedgehog is a package of agents and skills, built on an opinionated stack so the build order above is mechanical and enforced by the tooling itself:
 
 | Layer | Choice | Why |
 | --- | --- | --- |
@@ -141,11 +134,9 @@ Hedgehog is a package of agents and skills. An opinionated stack is used so the
 
 ## How Hedgehog Compares
 
-Superpowers and BMAD both improve on raw prompting: one gives the AI good habits, the other gives it a planning process.
-
-But in both, the order of work is a **convention, not a constraint** it's unable to break.
+Superpowers and BMAD both improve on raw prompting: one gives the AI good habits, the other gives it a planning process. In both, the order of work is a convention the AI can still break.
 
-Hedgehog **enforces its build order with tooling** instead: Nx module boundaries, commit hooks, phase gates. The order holds because the tooling holds it, not because the discipline was followed.
+Hedgehog enforces its build order with tooling instead: Nx module boundaries, commit hooks, phase gates. The order holds because the tooling holds it, not because the AI followed the discipline.
 
 | | Superpowers | BMAD | Hedgehog |
 | --- | --- | --- | --- |
@@ -157,3 +148,9 @@ Hedgehog **enforces its build order with tooling** instead: Nx module boundaries
 | **Context per step** | As much as the task pulls in | A full brief, PRD, and architecture doc per story | One module layer at a time (e.g. just the repository, just the controller) |
 | **Finding a bug** | Search wherever the task touched | Search wherever the story touched | Search one layer, in one module, in a fixed order |
 | **Real cost** | No safety net if the model shortcuts its own process | Documentation overhead most solo projects don't need | Less flexibility: the stack and order aren't negotiable |
+
+## Support Hedgehog
+
+If Hedgehog helps you build better AI software, consider giving it a ⭐ on GitHub.
+
+[![GitHub stars](https://img.shields.io/github/stars/skyf0xx/hedgehog?style=social)](https://github.com/skyf0xx/hedgehog/stargazers)

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.7",
+  "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

@@ -0,0 +1,133 @@
+---
+name: bootstrap
+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. 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 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 core piece
+(landed together) plus one per add-on. Before doing anything else:
+
+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 core
+
+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.
+
+## Running your add-on step
+
+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-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 — 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
+
+- 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 `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-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 add-on step" calls for — that's the context
+  budget this design protects.