@skyf0xx/hedgehog 0.1.21 → 2.0.0

package/README.md

@@ -1,6 +1,7 @@
 # The Antidote to AI Spaghetti Code ⭐
 
-[![GitHub stars](https://img.shields.io/github/stars/skyf0xx/hedgehog?style=social)](https://github.com/skyf0xx/hedgehog/stargazers)
+[![Weekly downloads](https://img.shields.io/npm/dw/%40skyf0xx%2Fhedgehog?style=for-the-badge)](https://www.npmjs.com/package/@skyf0xx/hedgehog)
+
 
 AI writes code faster than humans ever could, but **speed without discipline creates chaos**.
 
@@ -10,8 +11,8 @@ AI writes code faster than humans ever could, but **speed without discipline cre
 
 Hedgehog pairs **BMAD's planning** with **disciplined execution**, in one workflow.
 
-- Plan: BMAD workflow
 - Build: Hedgehog execution discipline
+- Plan: BMAD workflow
 - Ship: Quality gates and incremental loops
 
 ![Hedgehog - build software the right way, one step at a time](https://raw.githubusercontent.com/skyf0xx/hedgehog/master/docs/images/hero.png)
@@ -22,9 +23,18 @@ 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's secret to great outcomes
 
-- **Progressive layering:** types → schema → backend → UI, each layer built on a stable one beneath it
+- **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,17 +55,17 @@ 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.
+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 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).
 
 ![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
+## The Hedgehog Loop (full-stack-app core)
 
 ``` text
 Planning intake - BMAD-METHOD's brief/PRD/UX spec, mined into scope
@@ -75,6 +85,36 @@ Repeat for the next module or 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.
+
 ## Installation
 
 From an empty project folder:
@@ -83,16 +123,28 @@ From an empty project folder:
 npx @skyf0xx/hedgehog init
 ```
 
-Then open Claude Code and describe what you want to build. The
-`planner` agent runs planning intake first - BMAD-METHOD's brainstorming,
-brief, PRD, and UX spec - then mines that into what's in scope and which
-add-ons (Auth, Queue, Mobile) you need; once you confirm, it scaffolds
-the project itself.
+This installs the `full-stack-app` core by default. For the landing-page
+core instead:
 
-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 planning intake determined your project needs.
+``` bash
+npx @skyf0xx/hedgehog init --core=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.
 
@@ -104,7 +156,7 @@ npx @skyf0xx/hedgehog update
 ```
 
 This refreshes `.claude/agents/` and `.claude/skills/` only — it never
-touches `CLAUDE.md`, `TODO.md`, the golden-core workspace, or
+touches `CLAUDE.md`, `TODO.md`, the core workspace, or
 `skills/BMAD`, since those carry project-specific or write-once content.
 
 ## For Builders
@@ -127,7 +179,9 @@ AI becomes the builder operating inside those constraints - turning ideas into s
 
 ## Architecture
 
-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:
+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 |
 | --- | --- | --- |
@@ -151,11 +205,29 @@ Hedgehog is a package of agents and skills, built on an opinionated stack so the
 | 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. |
+
 ## 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, then enforces the build that follows with tooling, not convention: Nx boundaries, commit hooks, phase gates.
+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 |
 | --- | --- | --- | --- |
@@ -163,7 +235,7 @@ Hedgehog runs BMAD for planning, then enforces the build that follows with tooli
 | **Order comes from** | Skill instructions the agent is told to follow | Sequenced documents (brief → PRD → architecture → stories) | Tooling (Nx, lefthook, phase gate) |
 | **Enforcement mechanism** | None. Prompted convention | None. One optional checklist between phases | Execution mechanically enforced |
 | **Unit of work** | A task, planned in worktree-isolated steps | A story, derived from PRD and architecture docs | A module layer (schema → contract → repo → service → controller → UI) |
-| **Stack** | Whatever the project already uses | No stack opinion | One locked stack (Nx, NestJS, Drizzle, ts-rest, Next.js) |
+| **Stack** | Whatever the project already uses | No stack opinion | One locked stack per core (Nx/NestJS/Drizzle/ts-rest/Next.js for `full-stack-app`; Astro/Tailwind/GSAP for `landing-page`), chosen once at planning intake |
 | **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 - BMAD's docs are mined once, up front |
 | **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 | Stack and order aren't negotiable |
@@ -183,4 +255,4 @@ The `nx-generate`, `nx-run-tasks`, `nx-workspace`, and
 
 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)
+[![GitHub stars](https://img.shields.io/github/stars/skyf0xx/hedgehog?style=social)](https://github.com/skyf0xx/hedgehog/stargazers)

package/bin/cli.mjs

@@ -3,12 +3,13 @@
 // into the current repo, so the discipline travels with the project.
 //
 // Usage:
-//   npx @skyf0xx/hedgehog init          scaffold into the current directory
-//   npx @skyf0xx/hedgehog init --force  overwrite files that already exist
-//   npx @skyf0xx/hedgehog update        refresh .claude/agents + .claude/skills
+//   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 --force                 overwrite files that already exist
+//   npx @skyf0xx/hedgehog update                       refresh .claude/agents + .claude/skills
 //   npx @skyf0xx/hedgehog --help
 
-import { cp, mkdir, access, readdir, stat, rm } from 'node:fs/promises';
+import { cp, mkdir, access, readdir, stat, rm, readFile, writeFile } from 'node:fs/promises';
 import { constants } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join, relative, resolve } from 'node:path';
@@ -16,6 +17,8 @@ import { dirname, join, relative, resolve } from 'node:path';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = resolve(__dirname, '..');
 const DEST_ROOT = process.cwd();
+const CORES_ROOT = join(PKG_ROOT, 'src/golden-cores');
+const DEFAULT_CORE = 'full-stack-app';
 
 // ── tiny ANSI helpers (no deps) ─────────────────────────────────────────
 const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
@@ -31,35 +34,61 @@ const dim = (s) => paint('2', s);
 // this name in the package, renamed back on copy.
 const DOTFILE_RENAMES = { 'gitignore.template': '.gitignore' };
 
+// Every subdirectory of src/golden-cores/ is a valid --core value —
+// discovered from disk so a new core added under golden-cores/ doesn't
+// need this list touched separately.
+async function availableCores() {
+  return (await readdir(CORES_ROOT, { withFileTypes: true }))
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name)
+    .sort();
+}
+
 // ── the payload: what gets copied, and to where under the target repo ───
 // `dir` entries copy a whole tree; `file` entries copy a single file and
-// may rename (templates lose their src/templates/ prefix at the root).
-const PLAN = [
-  { type: 'dir', from: 'src/agents', to: '.claude/agents' },
-  { type: 'dir', from: 'src/skills', to: '.claude/skills' },
-  // The vendored BMAD-METHOD planning shelf that hedgehog-planning-intake
-  // runs — referenced by repo-root-relative path (skills/BMAD/...), so it
-  // lands there rather than under .claude/.
-  { type: 'dir', from: 'skills/BMAD', to: 'skills/BMAD' },
-  { type: 'file', from: 'src/templates/CLAUDE.md', to: 'CLAUDE.md' },
-  { type: 'file', from: 'src/templates/TODO.md', to: 'TODO.md' },
-  // 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: '.' },
-];
+// may rename (templates lose their src/templates/ prefix at the root);
+// `merge` entries concatenate a shared shell with a core-specific include
+// at {{CORE_SECTION}} (see CLAUDE.md template plumbing below).
+// Agents and skills for every core install regardless of which one is
+// chosen — planner needs the full toolset to run core selection at all,
+// and a project can only switch cores before it's bootstrapped anyway.
+function plan(core) {
+  return [
+    { type: 'dir', from: 'src/agents', to: '.claude/agents' },
+    { type: 'dir', from: 'src/skills', to: '.claude/skills' },
+    // The vendored BMAD-METHOD planning shelf that hedgehog-planning-intake
+    // runs — referenced by repo-root-relative path (skills/BMAD/...), so it
+    // lands there rather than under .claude/.
+    { type: 'dir', from: 'skills/BMAD', to: 'skills/BMAD' },
+    {
+      type: 'merge',
+      shell: 'src/templates/CLAUDE.md',
+      include: `src/templates/CLAUDE.core.${core}.md`,
+      to: 'CLAUDE.md',
+    },
+    {
+      type: 'merge',
+      shell: 'src/templates/TODO.md',
+      include: `src/templates/TODO.core.${core}.md`,
+      to: 'TODO.md',
+    },
+    // The pre-built, pre-verified workspace for the chosen core —
+    // everything a fresh project of that shape needs at repo root
+    // (lands the root package.json too, so there's no separate
+    // placeholder for it). The relevant bootstrap-core skill verifies
+    // this on first run rather than generating it live.
+    { type: 'dir', from: `src/golden-cores/${core}`, to: '.' },
+  ];
+}
 
-// The subset of PLAN that's the discipline's payload rather than
+// The subset of plan() that's the discipline's payload rather than
 // project-specific or write-once content: `update` re-copies exactly
 // this, always overwriting, since a consuming project's own
 // .claude/agents and .claude/skills are supposed to match upstream
-// verbatim. CLAUDE.md/TODO.md carry project-filled content, golden-core
-// is verified once by hedgehog-bootstrap-core, and skills/BMAD is
-// re-vendored only deliberately (bmad-revendor) — none of those belong
-// in an update.
+// verbatim. CLAUDE.md/TODO.md carry project-filled content, the core
+// workspace is verified once by its bootstrap-core skill, and
+// skills/BMAD is re-vendored only deliberately (bmad-revendor) — none
+// of those belong in an update.
 const UPDATE_PLAN = [
   { type: 'dir', from: 'src/agents', to: '.claude/agents' },
   { type: 'dir', from: 'src/skills', to: '.claude/skills' },
@@ -71,8 +100,25 @@ const exists = (p) =>
     () => false,
   );
 
+// Writes one planned file to disk — a straight copy, or for a `merge`
+// entry, the shell template with {{CORE_SECTION}} replaced by the
+// chosen core's include.
+async function writePlannedFile(f) {
+  await mkdir(dirname(f.dest), { recursive: true });
+  if (f.merge) {
+    const shell = await readFile(join(PKG_ROOT, f.merge.shell), 'utf8');
+    const section = await readFile(join(PKG_ROOT, f.merge.include), 'utf8');
+    await writeFile(f.dest, shell.replaceAll('{{CORE_SECTION}}', section.trimEnd()));
+    return;
+  }
+  await cp(f.src, f.dest);
+}
+
 // Every destination file this plan would write, resolved absolute.
 async function plannedFiles(entry) {
+  if (entry.type === 'merge') {
+    return [{ dest: join(DEST_ROOT, entry.to), merge: entry }];
+  }
   const src = join(PKG_ROOT, entry.from);
   if (entry.type === 'file') {
     return [{ src, dest: join(DEST_ROOT, entry.to) }];
@@ -92,7 +138,8 @@ async function plannedFiles(entry) {
   return out;
 }
 
-function help() {
+async function help() {
+  const cores = await availableCores();
   console.log(`
 ${bold('Hedgehog installer')}
 
@@ -101,28 +148,40 @@ CLAUDE.md / TODO.md templates into the repo root, so the discipline is
 committed alongside your code.
 
 ${bold('Usage')}
-  npx @skyf0xx/hedgehog init            scaffold into the current directory
-  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 --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 --help
 
-After it runs, commit the .claude/ payload, open Claude Code, and say
-"bootstrap this project" to trigger the hedgehog-bootstrap skill.
+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.
 
 ${bold('update')} re-copies only .claude/agents and .claude/skills from the
 installed Hedgehog version, so an already-bootstrapped project can pick up
 agent/skill changes from a newer release. It always overwrites those two
-directories and never touches CLAUDE.md, TODO.md, golden-core, or
+directories and never touches CLAUDE.md, TODO.md, the core workspace, or
 skills/BMAD — those are project-specific or updated deliberately, not by
 this command.
 `);
 }
 
-async function init({ force }) {
+async function init({ force, core }) {
+  const cores = await availableCores();
+  if (!cores.includes(core)) {
+    console.error(
+      `${red('Unknown core:')} ${core}\n\nAvailable cores: ${cores.join(', ')}\n`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+
   // Resolve the full list of writes up front so we can detect conflicts
   // before touching anything.
   const groups = [];
-  for (const entry of PLAN) {
+  for (const entry of plan(core)) {
     const files = await plannedFiles(entry);
     groups.push({ entry, files });
   }
@@ -151,8 +210,7 @@ async function init({ force }) {
   for (const { files } of groups) {
     for (const f of files) {
       const already = await exists(f.dest);
-      await mkdir(dirname(f.dest), { recursive: true });
-      await cp(f.src, f.dest);
+      await writePlannedFile(f);
       if (already) overwritten++;
       else written++;
       const label = already ? yellow('overwrite') : green('create');
@@ -169,11 +227,13 @@ async function init({ force }) {
   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(
     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.',
+      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.',
     ),
   );
 }
@@ -205,7 +265,7 @@ async function update() {
   console.log(`  2. ${bold('git add -A && git commit -m "chore: update hedgehog"')}\n`);
   console.log(
     dim(
-      'CLAUDE.md, TODO.md, the golden-core workspace, and skills/BMAD are\n' +
+      'CLAUDE.md, TODO.md, the core workspace, and skills/BMAD are\n' +
         'untouched — those carry project-specific or write-once content.',
     ),
   );
@@ -214,14 +274,16 @@ async function update() {
 async function main() {
   const args = process.argv.slice(2);
   if (args.includes('--help') || args.includes('-h') || args.length === 0) {
-    help();
+    await help();
     return;
   }
   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;
 
   if (cmd === 'init') {
-    await init({ force });
+    await init({ force, core });
     return;
   }
 
@@ -231,7 +293,7 @@ async function main() {
   }
 
   console.error(`${red('Unknown command:')} ${cmd}\n`);
-  help();
+  await help();
   process.exitCode = 1;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyf0xx/hedgehog",
-  "version": "0.1.21",
+  "version": "2.0.0",
   "description": "Install the Hedgehog build discipline (agents + skills) into a repo.",
   "type": "module",
   "repository": {
@@ -21,7 +21,7 @@
     "src/agents",
     "src/skills",
     "src/templates",
-    "src/golden-core",
+    "src/golden-cores",
     "skills/BMAD"
   ],
   "engines": {