@skyf0xx/hedgehog 2.0.0 → 2.0.1

package/README.md

@@ -23,18 +23,16 @@ Hedgehog pairs **BMAD's planning** with **disciplined execution**, in one workfl
 2. An enforced build order
 3. Agents and skills that make good engineering the default
 
-Hedgehog ships more than one **core** — a fixed stack, agent set, and
-build order for one project shape. `full-stack-app` is the original: Nx,
-NestJS, Drizzle, ts-rest, Next.js, backend-first (see **The Hedgehog
-Loop**, below). A second core, `landing-page`, applies the same
-discipline to a different shape — Astro, GSAP, a fixed pipeline for
-turning a brief into a traceable, non-templated page instead of a
-domain-module build order (see **The Chain Method**, below). Which core
-applies is decided once, at planning intake, from what you describe.
+Hedgehog currently builds:
+
+1. **Full-stack TypeScript apps**: built module by module, backend
+   first, on a fixed stack
+2. **Beautiful, unique landing pages**: a fixed pipeline from brief to
+   a traceable, distinct page built on modern frameworks
 
 ## Hedgehog's secret to great outcomes
 
-- **Progressive layering:** each core builds one stable layer at a time — types → schema → backend → UI on `full-stack-app`; brief → feeling → tokens → sequence → artifact on `landing-page`
+- **Progressive layering:** each core builds one stable layer at a time: types → schema → backend → UI on `full-stack-app`; brief → feeling → tokens → sequence → artifact on `landing-page`
 - **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
@@ -45,9 +43,9 @@ applies is decided once, at planning intake, from what you describe.
 
 AI coding starts fast, then breaks down. Context accumulates, prompts get longer, architecture drifts. Eventually, adding one more feature feels dangerous.
 
-Hedgehog's answer: guardrails, not more discipline from the AI.
+Hedgehog fixes this with guardrails instead of more discipline from the AI.
 
-## Plans Expire. Structure Doesn't
+### Plans Expire. Structure Doesn't
 
 Without a build order enforced mechanically, an AI (or a person) has to carry the whole plan in its head: architecture, sequencing, past decisions, etc. as an ever-growing prompt.
 
@@ -55,107 +53,57 @@ Hedgehog doesn't ask the AI to remember a plan. It makes the plan visible in the
 
 ### The AI should never wonder what to do next
 
-Instead of asking AI to hold an entire application in context, Hedgehog turns the build into a sequence of small, deterministic steps. The exact sequence depends on the project's core — a stateful app and a landing page don't share a build order, so they don't share an enforcement mechanism either. On the `full-stack-app` core:
+Instead of asking AI to hold an entire application in context, Hedgehog turns the build into a sequence of small, deterministic steps. The exact sequence depends on the project's core: a stateful app and a landing page don't share a build order, so they don't share an enforcement mechanism either. On the `full-stack-app` core:
 
 Each module is built progressively: schema → contract → repository → service → controller. Every step is gated by tests and committed before the next begins.
 
 Backend comes first. Every module gets a working, typed API before any screen is built. The frontend becomes a consumer of stable capabilities, not a parallel source of complexity.
 
-The build order is not something you negotiate with the AI. It is encoded into the process — the same is true on the `landing-page` core, just for a different sequence (see **The Chain Method**, below).
+The build order is not something you negotiate with the AI. It is encoded into the process, per core (see **The Hedgehog Loop**, below).
 
 ![Small steps, big leverage: small context loops, continuous verification, traceable evolution, sustainable velocity](https://raw.githubusercontent.com/skyf0xx/hedgehog/master/docs/images/small-steps.png)
 
-## The Hedgehog Loop (full-stack-app core)
+## The Hedgehog Loop
+
+Every core runs the same loop: plan, bootstrap, then build in a fixed,
+mechanically-enforced order on an opinionated stack.
 
 ``` text
-Planning intake - BMAD-METHOD's brief/PRD/UX spec, mined into scope
-boundary + domain vocabulary (planner agent)
-  ↓
-Bootstrap (once per project)
+Planning intake - BMAD-METHOD's planning shelf, mined into this core's
+scoping artifact
   ↓
-Phase A, per module - schema → contract → repository → service → controller
+Bootstrap
   ↓
-Phase A closes for the module (gated: typecheck, lint, test)
+Build in gated steps
   ↓
-Phase B, per module - hook → UX rationale → screen
-  ↓
-Repeat for the next module or the next step
+Repeat for the next step
 ```
 
-
 ![Why Hedgehog works: a different way to build with AI, comparing traditional AI workflow to Hedgehog](https://raw.githubusercontent.com/skyf0xx/hedgehog/master/docs/images/why.png)
 
-## The Chain Method (landing-page core)
-
-A different shape gets a different loop, not a variant of this one —
-there's no domain module to build, so the enforced order is a pipeline
-instead of a layer sequence:
-
-``` text
-Planning intake - BMAD-METHOD's brief/PR-FAQ/PRD/UX spec, mined into a
-subject/audience/single-job statement (planner agent)
-  ↓
-Bootstrap (once per project - Astro + Tailwind workspace)
-  ↓
-Strategy - subject statement → adjective pairs → visceral/behavioral/
-reflective sort → top/heart/base note timing (landing-strategist)
-  ↓
-Systems - ingredient dials + copy voice (parallel) → token system →
-signature motif (landing-systems)
-  ↓
-Sequence - per-section transitions, weight, pacing (landing-sequencer)
-  ↓
-Audit - traceability/distinctiveness + usability, reconciled to a pass
-(landing-critic) - redlines route back to the phase that owns them
-  ↓
-Build - the artifact, in Astro (landing-builder)
-```
-
-Every choice traces back to a sentence in the subject statement, or it
-gets cut — that traceability is what keeps the output from converging on
-the same templated look every AI-generated page defaults to.
+Each core defines its own build order and stack.
 
 ## Installation
 
 From an empty project folder:
 
 ``` bash
-npx @skyf0xx/hedgehog init
-```
-
-This installs the `full-stack-app` core by default. For the landing-page
-core instead:
+# 1. Full-stack app (Nx, NestJS, Drizzle, ts-rest, Next.js)
+npx @skyf0xx/hedgehog init --ts-full-stack-app
 
-``` bash
-npx @skyf0xx/hedgehog init --core=landing-page
+# 2. Landing page (Astro, Tailwind, GSAP)
+npx @skyf0xx/hedgehog init --landing-page
 ```
 
-Then open Claude Code and describe what you want to build. The
-`planner` agent decides which core actually applies (overriding the
-installer's default if what you describe doesn't match it), then runs
-that core's own planning intake — both cores run BMAD-METHOD's
-brainstorming, brief, PR-FAQ, PRD, UX spec, and deep-recon in full;
-`full-stack-app` mines that output into scope boundary and domain
-vocabulary, `landing-page` mines it into a subject/audience/job
-statement. Once you confirm, it scaffolds the project itself.
-
-The chosen core's workspace - for `full-stack-app`: Nx, `packages/config`,
-`packages/db`, `apps/api`, `apps/web`, and every enforcement file; for
-`landing-page`: the Astro + Tailwind workspace and its animation library
-set - lands instantly from a pre-verified template rather than being
-generated live; bootstrap then verifies it (and, on `full-stack-app`,
-runs whichever add-ons planning intake determined your project needs).
-
-Or paste the repo URL to your Agent and have it install for you.
+Then open Claude Code and describe what you want to build.
 
-On a project that's already installed Hedgehog, pick up agent/skill
-changes from a newer release with:
+To update:
 
 ``` bash
 npx @skyf0xx/hedgehog update
 ```
 
-This refreshes `.claude/agents/` and `.claude/skills/` only — it never
+This refreshes `.claude/agents/` and `.claude/skills/` only. It never
 touches `CLAUDE.md`, `TODO.md`, the core workspace, or
 `skills/BMAD`, since those carry project-specific or write-once content.
 
@@ -175,59 +123,17 @@ Under the hood, it applies the practices experienced engineers rely on:
 - continuous verification
 - conventional commits
 
-AI becomes the builder operating inside those constraints - turning ideas into software without requiring you to manage every implementation detail.
+AI becomes the builder operating inside those constraints, turning ideas into software without requiring you to manage every implementation detail.
 
 ## Architecture
 
-Hedgehog is a package of agents and skills, built on an opinionated stack per core so the build order above is mechanical and enforced by the tooling itself.
-
-### `full-stack-app` core
-
-| Layer | Choice | Why |
-| --- | --- | --- |
-| Monorepo | Nx | Enforces module boundaries at compile time. |
-| Package manager | pnpm | Prevents accidental cross-package dependencies. |
-| Backend | NestJS | Modules naturally mirror Hedgehog's build progression. |
-| ORM | Drizzle + drizzle-zod | Database schema is the single source of truth. |
-| Database | PostgreSQL | Simple, relational, predictable. |
-| Local infra | Docker Compose | Postgres/Redis run identically on every machine. |
-| Platform | Railway | Infrastructure is available from the first commit. |
-| API contract | ts-rest | Contracts are code, not documentation. |
-| Validation | Zod | One schema for runtime and compile time. |
-| Auth | Better Auth | Secure by default from day one. |
-| Data fetching | TanStack Query | UI consumes typed APIs, never implementation details. |
-| Web | Next.js + ShadCN + Tailwind | UI remains a thin presentation layer. |
-| Mobile | Expo + RN Reusables | Shares contracts and design tokens with web. |
-| Jobs | BullMQ + Redis | Async boundaries exist before they're needed. |
-| Logging | Pino | Structured logs from the first feature. |
-| Linting | ESLint + Prettier | One shared standard across every module. |
-| Testing | Vitest + Playwright | Every step is verifiable before progressing. |
-| Commits | Conventional Commits | Architectural decisions become permanent history. |
-| Observability | Sentry | Failures map cleanly back to module boundaries. |
-
-### `landing-page` core
-
-Every choice below maps to a specific dial or phase in the Chain
-Method — nothing here is a default reached for out of habit:
-
-| Layer | Choice | Why |
-| --- | --- | --- |
-| Framework | Astro | Zero-JS-by-default shell; islands only where interaction is actually needed. |
-| Styling | Tailwind (v4, CSS-first) | Config as token layer only — no component library pre-deciding how things look. |
-| Animation | GSAP + ScrollTrigger | Owns per-section pacing and top/heart/base fade timing with real control. |
-| Scroll feel | Lenis | The "weight and suspension" dial, instead of default browser scroll physics. |
-| Copy reveal | SplitType | Line/word/char splitting — makes copy rhythm visible in motion, not just static text. |
-| Motif | SVG-first + Paper.js | Hand-authored graphics; Paper.js for a motif that evolves (augmentation/inversion) across sections. |
-| Motif transforms | GSAP MorphSVGPlugin | Ships free inside the `gsap` package — for a motif that physically transforms across sections. |
-| Texture | Custom SVG noise/grain filter | Cheap materiality layer nothing else in the stack owns. |
-| Design handoff | Figma MCP / Stitch MCP | Input only, at the Strategist/Builder boundaries — never allowed to set spacing/style defaults directly. |
-| 3D (rare) | React Three Fiber | Only when the subject is genuinely spatial; skipped by default. |
+Hedgehog is a package of agents and skills, built on an opinionated stack per core so the build order above is mechanical and enforced by the tooling itself. See [ARCHITECTURE.md](ARCHITECTURE.md) for details.
 
 ## How Hedgehog Compares
 
 Superpowers and BMAD both improve on raw prompting: one gives the AI good habits, the other a planning process. Alone, either can still be broken by convention.
 
-Hedgehog runs BMAD for planning on both cores — the same full shelf either way, mined differently per core's own shape — then enforces the build that follows with tooling, not convention — Nx boundaries, commit hooks, and phase gates on `full-stack-app`; a redline-gated pipeline on `landing-page`.
+Hedgehog runs BMAD for planning on both cores (the same full shelf either way, mined differently per core's own shape), then enforces the build that follows with tooling, not convention: Nx boundaries, commit hooks, and phase gates on `full-stack-app`; a redline-gated pipeline on `landing-page`.
 
 | | Superpowers | BMAD | Hedgehog + BMAD |
 | --- | --- | --- | --- |

package/bin/cli.mjs

@@ -3,8 +3,8 @@
 // into the current repo, so the discipline travels with the project.
 //
 // Usage:
-//   npx @skyf0xx/hedgehog init                        scaffold, full-stack-app core (default)
-//   npx @skyf0xx/hedgehog init --core=landing-page     scaffold with a named core instead
+//   npx @skyf0xx/hedgehog init                        scaffold, ts-full-stack-app core (default)
+//   npx @skyf0xx/hedgehog init --landing-page          scaffold the landing-page core instead
 //   npx @skyf0xx/hedgehog init --force                 overwrite files that already exist
 //   npx @skyf0xx/hedgehog update                       refresh .claude/agents + .claude/skills
 //   npx @skyf0xx/hedgehog --help
@@ -20,6 +20,16 @@ const DEST_ROOT = process.cwd();
 const CORES_ROOT = join(PKG_ROOT, 'src/golden-cores');
 const DEFAULT_CORE = 'full-stack-app';
 
+// One install flag per core, named for what a user is asking to build
+// rather than the internal src/golden-cores/<name> directory — the two
+// diverge deliberately so the CLI's public surface can stay stable
+// while cores are renamed or added underneath it. Adding a core means
+// adding one entry here (and a matching src/golden-cores/<dir>).
+const CORE_FLAGS = {
+  '--ts-full-stack-app': 'full-stack-app',
+  '--landing-page': 'landing-page',
+};
+
 // ── tiny ANSI helpers (no deps) ─────────────────────────────────────────
 const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
 const paint = (code, s) => (useColor ? `\x1b[${code}m${s}\x1b[0m` : s);
@@ -148,16 +158,18 @@ CLAUDE.md / TODO.md templates into the repo root, so the discipline is
 committed alongside your code.
 
 ${bold('Usage')}
-  npx @skyf0xx/hedgehog init                    scaffold, ${DEFAULT_CORE} core (default)
-  npx @skyf0xx/hedgehog init --core=<name>      scaffold with a named core instead
-  npx @skyf0xx/hedgehog init --force            overwrite existing files
-  npx @skyf0xx/hedgehog update                  refresh .claude/agents + .claude/skills
+  npx @skyf0xx/hedgehog init                      scaffold, ${DEFAULT_CORE} core (default)
+  npx @skyf0xx/hedgehog init --ts-full-stack-app  scaffold the full-stack-app core explicitly
+  npx @skyf0xx/hedgehog init --landing-page       scaffold the landing-page core instead
+  npx @skyf0xx/hedgehog init --force              overwrite existing files
+  npx @skyf0xx/hedgehog update                    refresh .claude/agents + .claude/skills
   npx @skyf0xx/hedgehog --help
 
 Available cores: ${cores.join(', ')}
 
-After it runs, commit the payload, open Claude Code, and say
-"bootstrap this project" to trigger the matching bootstrap-core skill.
+After it runs, commit the payload, open Claude Code, and describe what
+you want to build — the planner agent runs planning intake, then hands
+off to bootstrap.
 
 ${bold('update')} re-copies only .claude/agents and .claude/skills from the
 installed Hedgehog version, so an already-bootstrapped project can pick up
@@ -226,14 +238,20 @@ async function init({ force, core }) {
   console.log('Next steps:');
   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(`Core: ${bold(core)} — already scaffolded and verified.`));
+  console.log(`  3. Open Claude Code and describe what you want to build.`);
+  console.log(
+    dim(
+      `     The ${bold('planner')} agent runs planning intake, then hands off to bootstrap.`,
+    ),
+  );
+  console.log();
+  console.log(dim(`Core: ${bold(core)} (installer default — planner may override it).`));
   console.log(
     dim(
       core === DEFAULT_CORE
         ? '(Nx, packages/config, packages/db, apps/api, apps/web) — bootstrap\n' +
-            'now only runs whichever add-ons (Auth, Queue, Mobile) Intake calls for.'
-        : 'bootstrap now only runs whichever add-on steps this core defines, if any.',
+            'runs whichever add-ons (Auth, Queue, Mobile) intake calls for.'
+        : 'bootstrap runs whichever add-on steps this core defines, if any.',
     ),
   );
 }
@@ -279,8 +297,17 @@ async function main() {
   }
   const cmd = args[0];
   const force = args.includes('--force') || args.includes('-f');
-  const coreArg = args.find((a) => a.startsWith('--core='));
-  const core = coreArg ? coreArg.slice('--core='.length) : DEFAULT_CORE;
+  const coreFlag = args.find((a) => a in CORE_FLAGS);
+  if (coreFlag === undefined && args.some((a) => a.startsWith('--core='))) {
+    const attempted = args.find((a) => a.startsWith('--core='));
+    console.error(
+      `${red('Unknown flag:')} ${attempted}\n\n` +
+        `Use an explicit core flag instead: ${Object.keys(CORE_FLAGS).join(', ')}\n`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const core = coreFlag ? CORE_FLAGS[coreFlag] : DEFAULT_CORE;
 
   if (cmd === 'init') {
     await init({ force, core });

package/package.json

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

package/src/skills/hedgehog-bootstrap-landing-page-core/SKILL.md

@@ -57,7 +57,7 @@ re-copy: patch the specific file at its source.
 
 ### 2. Land `src/golden-cores/landing-page/`
 
-In the common case this is already done — `hedgehog init --core=landing-page`'s
+In the common case this is already done — `hedgehog init --landing-page`'s
 installer copies `src/golden-cores/landing-page/` to the repo root at
 install time, the same way it copies `src/agents` to `.claude/agents`.
 Check whether the core files are already present (same check as step 1).