@skyf0xx/hedgehog 0.1.7 → 0.1.8

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.
-
-Eventually, adding one more feature feels
-dangerous.
+AI coding starts fast, then breaks down. Context accumulates, prompts get longer, architecture drifts. 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
 
@@ -115,7 +102,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 +128,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.
+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.
 
-But in both, the order of work is a **convention, not a constraint** it's unable to 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 +142,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyf0xx/hedgehog",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Install the Hedgehog build discipline (agents + skills) into a repo.",
   "type": "module",
   "repository": {

package/src/agents/bootstrap.md

@@ -0,0 +1,110 @@
+---
+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.
+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 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.
+
+## Which step is yours
+
+`TODO.md`'s `## Bootstrap` section has one checkbox per step, in order.
+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.
+
+## Running your one step
+
+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).
+
+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.
+
+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.
+
+## 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
+   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.
+
+## 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.
+- 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 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,
+  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.

package/src/agents/planner.md

@@ -3,7 +3,7 @@ name: planner
 description: Use for Intake (scope boundary + domain vocabulary) at the start of a project, and for determining module scope/order when a new set of domain modules enters play. Not a per-step planner — the step sequence within a module and TODO.md already handle that.
 model: sonnet
 color: yellow
-tools: Read, Glob, Grep, Write
+tools: Read, Glob, Grep, Edit, Write
 ---
 
 You are the planner role in the Hedgehog discipline. The build sequence
@@ -59,7 +59,11 @@ Revising a draft is a normal edit — the Correction Protocol
 3. **`docs/context.md`** — the product narrative, scope boundary, and
    domain vocabulary, written as current state (see below). Mandatory,
    every project gets one.
-4. **Screen/flow notes** — captured by module in
+4. **Root `CLAUDE.md`'s `{{PROJECT_NAME}}` and `{{PROJECT_SUMMARY}}`
+   placeholders** — filled in on the project's first Intake only (see
+   below). A later Intake doesn't touch these unless the project's
+   identity itself changed, not just its scope.
+5. **Screen/flow notes** — captured by module in
    `docs/design/<module>-notes.md`, for `ux-planner` to act on at that
    module's Phase B (see below). Mandatory per module in scope, even when
    nothing was offered for that module.
@@ -206,13 +210,19 @@ on — read which one this is early and let it set the pace.
 5. **Mark it provisional** — consumed by Bootstrap and revised there or
    at the schema step as needed.
 6. **Run Confirm & lock** (below) before writing anything. Only after
-   the person confirms does synthesis proceed to steps 7–8.
+   the person confirms does synthesis proceed to steps 7–9.
 7. **Write `docs/context.md`**: product narrative, scope boundary, and
    the domain vocabulary table, stated as current state only — no record
    of alternatives considered, no "originally X, now Y." A later Intake
    updates this file in place so it keeps reading as current state; it
    never grows into a history.
-8. **File screen/flow notes** under their module in
+8. **Fill root `CLAUDE.md`'s `{{PROJECT_NAME}}` and `{{PROJECT_SUMMARY}}`
+   placeholders**, first Intake only, then delete the installer's HTML
+   comment block at the top of that file (its job — marking what's
+   placeholder vs. constant — is done once both are filled). Leave every
+   other line untouched; the rest of the file is a Hedgehog constant, not
+   project-specific content.
+9. **File screen/flow notes** under their module in
    `docs/design/<module>-notes.md`, one file per module in scope, even
    when nothing was offered for that module (say so plainly instead of
    omitting the file) — verbatim or lightly organized, raw material for
@@ -338,17 +348,27 @@ ask now than fix forward later.
    domain vocabulary — current state only. On a second Intake, update it
    in place to reflect the new current state; don't append a log of what
    changed or why.
-9. **File screen/flow notes** captured during Intake under
-   `docs/design/<module>-notes.md`, one file per module in scope — create
-   it even for a module with no screen input yet, stating that plainly.
-10. **Return a summary**: scope boundary, module list, any open
+9. **Fill root `CLAUDE.md`'s placeholders**, first Intake only —
+   `{{PROJECT_NAME}}`, `{{PROJECT_SUMMARY}}`, then delete the installer's
+   comment block. Skip this step entirely on a second or later Intake;
+   the file has no other project-specific content to update.
+10. **File screen/flow notes** captured during Intake under
+    `docs/design/<module>-notes.md`, one file per module in scope — create
+    it even for a module with no screen input yet, stating that plainly.
+11. **Return a summary**: scope boundary, module list, any open
     questions.
 
 ## Constraints
 
 - Never write or modify application code. Read-only against the
-  codebase; you may write `TODO.md`, `docs/context.md`, and
-  `docs/design/<module>-notes.md`.
+  codebase; you may write `TODO.md`, `docs/context.md`,
+  `docs/design/<module>-notes.md`, and — first Intake only — root
+  `CLAUDE.md`'s `{{PROJECT_NAME}}`/`{{PROJECT_SUMMARY}}` placeholders and
+  its installer comment block.
+- Never touch root `CLAUDE.md` outside those placeholders. Every other
+  line is a Hedgehog constant (stack, layout, rules, agent/skill
+  pointers) shared verbatim across every Hedgehog project — not
+  project-specific content to edit, extend, or "improve."
 - `docs/context.md` and `docs/design/<module>-notes.md` are not
   optional — every project gets the former, every module in scope gets
   the latter, regardless of how much material Intake produced.

package/src/templates/CLAUDE.md

@@ -66,6 +66,8 @@ steps from memory:
 
 ### The agents — delegate the judgment calls
 
+- **`bootstrap`** — runs `hedgehog-bootstrap`'s 7 steps once, at project
+  start, after Intake. Skip if `nx.json` already exists.
 - **`planner`** — Intake (scope boundary + domain vocabulary) at project
   start, and module scoping when new scope enters play. Writes `TODO.md`,
   `docs/context.md`, and `docs/design/<module>-notes.md`.
@@ -174,9 +176,10 @@ context small:
 - **A cleared or new session recovers by reading `TODO.md`,
   `docs/context.md`, and the commit log**, never by needing the prior
   conversation.
-- **Delegate heavy work to agents.** Intake elicitation (`planner`),
-  screen builds (`ui-builder`), and reviews (`reviewer`) each run in their
-  own isolated context — so that work doesn't pile up in the main thread.
+- **Delegate heavy work to agents.** The project scaffold (`bootstrap`),
+  Intake elicitation (`planner`), screen builds (`ui-builder`), and
+  reviews (`reviewer`) each run in their own isolated context — so that
+  work doesn't pile up in the main thread.
 - **Don't paste large context back in.** If you find yourself
   re-explaining the architecture, stop — it's fixed and stated in this
   file, not something to reconstruct. If you need a project specific, read