@skyf0xx/hedgehog 0.1.21 → 2.0.0

package/src/skills/hedgehog-landing-loop/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: hedgehog-landing-loop
+description: Use for every unit of work on the landing-page core, from planning intake through the final build phase — the Chain Method's brief → feeling → tokens/motif → sequence → artifact pipeline, gated and committed one phase at a time, checked off TODO.md. Triggers on "next step", "next phase", "what's next", or the start of any work session on a bootstrapped landing-page project. Also covers this core's own planning intake and Correction Protocol.
+---
+
+# Hedgehog Landing Loop
+
+The operating loop for a bootstrapped `landing-page` project: pick the
+next phase, run it through its owning agent, gate it, commit it, check it
+off. `TODO.md` at repo root is the live list — read it before starting.
+It's thin: a context blurb plus a checklist mirroring the phase structure
+below. Checked/unchecked is its only state.
+
+This is the **Chain Method**: a pipeline where every visual choice traces
+back to a reason. No agent may introduce a choice that doesn't originate
+in the previous agent's output — that discipline is what this skill
+enforces mechanically, the same role Nx module boundaries play for
+`full-stack-app`.
+
+## Planning intake (Phase 0, before any build phase)
+
+Run once, before `bootstrap` scaffolds the workspace. Opens with
+`hedgehog-planning-intake`'s Phase 0 — the same vendored BMAD-METHOD
+shelf `full-stack-app` runs, in the same full sequence, archived to the
+same `.hedgehog/BMAD/` layout. After that Phase 0 completes, this
+section does its own mining — a one-paragraph subject statement, the
+landing-page counterpart to `hedgehog-planning-intake`'s own Phase 1
+(domain modules and an Add-ons decision on full-stack-app). That mined
+draft becomes the first draft of `.hedgehog/chain/00-brief.md`, shown
+back at Confirm & Lock for the user to accept or correct.
+
+1. **Run `hedgehog-planning-intake`'s Phase 0 in full**: state the BMAD
+   attribution it states, then run `bmad-brainstorming`,
+   `bmad-product-brief`, `bmad-prfaq`, `bmad-prd`, `bmad-ux`,
+   `bmad-deep-recon`, archived to `.hedgehog/BMAD/` with the fixed layout
+   and `00-manifest.md` attribution header that skill's Phase 0 defines.
+   `.hedgehog/BMAD/` is archival and immutable once written, same as
+   `full-stack-app` — nothing in this core's day-to-day loop reads it
+   live after this step mines it once.
+2. **Mine a draft subject statement** from `.hedgehog/BMAD/`: the
+   concrete subject (what is this actually selling/announcing/showing),
+   the audience, and the page's single job, sourced from the brief and
+   PR-FAQ (a landing page's brief and PR-FAQ are the closest BMAD
+   artifacts to a subject statement — the PRD's Glossary and deep-recon
+   output are read for supporting color, not required to resolve a
+   one-page subject/audience/job). Where BMAD's material leaves any of
+   the three genuinely unresolved, ask directly — don't proceed on
+   vagueness, and don't invent an audience or job that wasn't stated,
+   mined, or confirmed.
+3. **Write `.hedgehog/chain/00-brief.md`** — the mined subject statement,
+   one paragraph, plus the audience and single job named explicitly.
+   This is the root every downstream phase's traceability audit walks
+   back to; it draws from BMAD's archive but is its own file, in this
+   core's own `.hedgehog/chain/` layout, not a pointer into
+   `.hedgehog/BMAD/`.
+4. **Confirm & Lock** — show the mined subject statement, audience, and
+   job back in plain terms, alongside which BMAD skills ran and where
+   their output lives (`.hedgehog/BMAD/`), before writing `TODO.md`.
+   State plainly what happens on confirmation: *"This locks in the
+   brief, commits it (`chore(planning): intake`), and hands off to
+   `bootstrap` to scaffold the Astro workspace. The Strategist phase
+   starts once that closes. Anything wrong or missing — say so now."*
+   Wait for explicit go-ahead — a revision here is just another mining
+   pass against the same BMAD archive, not a Correction Protocol entry,
+   since nothing downstream exists yet.
+5. **Write `TODO.md`** mirroring the phase table below, then commit
+   planning intake's output as one commit, `chore(planning): intake` —
+   `TODO.md`, `.hedgehog/BMAD/`, `.hedgehog/chain/00-brief.md`, and root
+   `CLAUDE.md`'s filled placeholders.
+6. **Hand off to `bootstrap`** once the commit lands.
+
+`planner` owns this section; see that agent for when it runs.
+
+## The Chain Method phases
+
+Every phase's input is the prior phase's output, in this exact order — no
+agent works from anything but what was actually handed to it. Steps 4a
+(inside `landing-systems`) and 4c (inside `landing-strategist`) are the
+only parallel-input point in the chain, both reading the same upstream
+artifact; everything else is strictly sequential.
+
+| # | Phase | Agent | Produces | Commit |
+|---|---|---|---|---|
+| 1 | Strategist | `landing-strategist` | Subject/audience/job statement (from planning intake — restated here as this phase's formal output) | `feat(landing): strategy` |
+| 1b | Diagnostician | `landing-strategist` | Awareness level, Sophistication level, Sin/desire, Big Idea, Category/Positioning statement | bundled into `feat(landing): strategy` |
+| 1c | Narrative Agent | `landing-strategist` | StoryBrand arc (Character → Problem → Guide → Plan → Action → Success/Failure), subject as Guide | bundled into `feat(landing): strategy` |
+| 1d | Objection Agent | `landing-strategist` | Ranked objection map, each tagged with a Cialdini rebuttal principle | bundled into `feat(landing): strategy` |
+| 2 | Brand Anthropologist | `landing-strategist` | 3–5 adjective pairs (each with a named opposite) | bundled into `feat(landing): strategy` |
+| 3 | Psychologist | `landing-strategist` | Adjectives sorted visceral / behavioral / reflective | bundled into `feat(landing): strategy` |
+| 4 | Perfumer | `landing-strategist` | Top/heart/base note timing per adjective, the page's peak moment, the ending treatment | bundled into `feat(landing): strategy` |
+| 5 | Ingredient Director + Copywriter | `landing-systems` | Dial table (color/type/form/space/motion) + voice spec + gated headline (2 backups) + objection rebuttal prose, run against the same sorted-adjectives/diagnosis input | `feat(landing): systems` |
+| 6 | Systems Designer | `landing-systems` | The token system (hex values, type roles, spacing unit, easing family, copy voice, with note timing attached) | bundled into `feat(landing): systems` |
+| 7 | Motif Artist | `landing-systems` | Signature motif (source, persistence, continuity, scale range, literalness) | bundled into `feat(landing): systems` |
+| 8 | Sequencer | `landing-sequencer` | Per-section transition type, weight, spacing, beat structure | `feat(landing): sequence` |
+| 9 | Critic + Usability Auditor | `landing-critic` | Redlines, or a pass — reconciled traceability/distinctiveness + usability audit | `feat(landing): audit` (no commit if redlined — see Correction Protocol) |
+| 10 | Builder | `landing-builder` | The built page, in Astro | `feat(landing): build` |
+
+Phases 1 through 4 (including 1b/1c/1d) are one agent's context
+(`landing-strategist`) because they're one continuous judgment call —
+subject into diagnosis into feeling into timing — not separable artifacts
+with different tool footprints. Same reasoning collapses 5–7 into
+`landing-systems` (everything that becomes a Tailwind token or a line of
+copy) and 8/9's reconciliation into a single `landing-critic` pass. See
+each agent's own file for the internal sub-steps it runs through.
+
+## The Loop (every unit of work)
+
+1. **Pick the next phase** per the table above, from `TODO.md`. One phase
+   at a time, in order.
+2. **Check the gate.** The prior phase is checkpointed and committed
+   first.
+3. **Delegate exactly one phase** to its owning agent, passing it the
+   full chain so far (every upstream artifact, not just the immediately
+   prior one) — an agent that only sees its direct input can't verify its
+   own traceability back to the subject statement.
+4. The agent **runs its self-test** (see that agent's own file for what
+   it checks) before presenting its artifact.
+5. The agent **commits** using the exact Conventional Commit format
+   above.
+6. **Check off the line in `TODO.md`** once the agent reports the commit
+   landed.
+7. **Repeat**, one delegated phase at a time.
+
+Each commit batches exactly one phase's artifact; a wrong phase is fixed
+forward later via the Correction Protocol.
+
+## Correction Protocol
+
+When a downstream phase reveals an upstream phase was wrong — most often
+`landing-critic` redlining something that doesn't trace back to the
+subject statement, or matches a known AI-default cluster:
+
+1. Stop.
+2. Patch the upstream phase directly, in place, via that phase's owning
+   agent.
+3. Fast-forward every dependent phase that breaks. A token system change
+   (phase 6) ripples through the motif (7), the sequence (8), and the
+   build (10) — each gets its own small commit, in order, not one bundled
+   fix.
+4. Re-run `landing-critic` against the patched chain before resuming.
+5. The commit messages are the explanation.
+6. Resume the loop.
+
+Use `conventional-commits` when a correction touches several phases in
+one working-tree pass and needs splitting back into per-phase commits.
+
+## Phase Transition Checks
+
+Before `landing-builder` starts, confirm:
+
+- `landing-critic` returned a pass, not a redline — a redlined spec never
+  reaches the Builder; it goes back to the phase the redline names.
+- Every phase 1–9 has its commit landed.
+
+Before `landing-strategist` starts, confirm planning intake's Confirm &
+Lock has held and its commit has landed. If not, stop and ask.
+
+## Rules
+
+- **No agent introduces a choice that doesn't originate in the previous
+  agent's output.** This is the chain's core discipline — enforced by
+  `landing-critic`'s traceability audit, not by tooling, so treat a
+  critic redline with the same weight a failed typecheck gets elsewhere
+  in Hedgehog.
+- **Ingredients move in agreement.** Color, type, space, motion, copy
+  rhythm, and pacing are reconciled into one system at phase 6 — a
+  mismatch (warm color, cold type) is a defect `landing-systems` owns
+  fixing, not a later polish pass.
+- **Sequential except phases 5's two parallel inputs.** The Ingredient
+  Director and Copywriter sub-steps inside `landing-systems` read the
+  same sorted-adjectives input and can run together; every other phase
+  waits on the one before it.
+- **A wrong phase gets fixed at its source** — the Correction Protocol,
+  not a downstream workaround (e.g. don't patch the Builder's output to
+  fix a token that's wrong at the Systems Designer level).
+- **The Critic's veto is real.** `landing-critic` can send any phase back
+  to its owning agent, citing which audit failed; it cannot rewrite the
+  artifact itself.
+- **Figma/Stitch MCP output is input only.** Anything handed off from
+  those tools is re-derived through the token system (phase 6) before it
+  touches Tailwind config — never copied through as final values.
+
+## Stop Condition
+
+A build session ends when every phase in `TODO.md` is checked off and
+`landing-builder`'s artifact is committed, or when the subject statement
+or an adjective is ambiguous enough that continuing means guessing — ask
+one question and wait.

package/src/skills/hedgehog-planning-intake/SKILL.md

@@ -1,19 +1,24 @@
 ---
 name: hedgehog-planning-intake
-description: Use once per project, at the start, and again on a scoped pass when new domain scope enters play — runs the vendored BMAD-METHOD planning shelf, mines its output into scope boundary/domain modules/the Add-ons decision, and gates on Confirm & Lock before anything is written. Invoked by the `planner` agent; don't run standalone.
+description: Use once per project, at the start, on either core — Phase 0 (running the vendored BMAD-METHOD planning shelf) is shared by full-stack-app and landing-page alike; Phase 1 (mining BMAD's output into scope boundary/domain modules/the Add-ons decision) is full-stack-app's own procedure, run again on a scoped pass when new domain scope enters play. Invoked by the `planner` agent after Phase 0 core selection; don't run standalone. landing-page runs this skill's Phase 0, then mines the same archive through `hedgehog-landing-loop`'s own planning-intake section, that core's counterpart to this skill's Phase 1.
 ---
 
 # Hedgehog Planning Intake
 
-Turns a person's description of a problem into `TODO.md` (with its
-`## Add-ons` block) and `docs/design/<module>-notes.md` per module, by
-running the vendored BMAD-METHOD planning shelf and mining its output.
-This is the mechanics `planner` calls once its "does Hedgehog apply at
-all" check passes — the interpretive judgment (scope boundary, module
-split, Add-ons decision, Confirm & Lock) still belongs to `planner`; this
-skill is the fixed procedure that judgment runs inside.
-
-## Phase 0 — BMAD elicitation
+Turns a person's description of a problem into planning material, by
+running the vendored BMAD-METHOD planning shelf (Phase 0, shared by both
+cores) and mining its output. On full-stack-app that mining is this
+skill's own Phase 1, into scope boundary/domain modules/Add-ons; on
+landing-page it's `hedgehog-landing-loop`'s planning-intake section, into
+a subject/audience/job statement. This is the mechanics `planner` calls
+once its Phase 0 core-selection check has picked a core — the
+interpretive judgment (scope boundary, module split, Add-ons decision on
+full-stack-app; subject statement on landing-page; Confirm & Lock either
+way) belongs to `planner`; this skill (Phase 0, and Phase 1 on
+full-stack-app) and `hedgehog-landing-loop` (landing-page's own mining)
+are the fixed procedures that judgment runs inside.
+
+## Phase 0 — BMAD elicitation (both cores)
 
 State the BMAD attribution, then run the vendored shelf in full
 sequence, every time — no per-project skip logic, no reduced default
@@ -55,13 +60,21 @@ Every file/folder carries a one-line attribution header. `00-manifest.md`
 states the source repo, pinned version (`skills/BMAD/ATTRIBUTION.md` has
 the pinned commit), date, and which skills ran.
 
-`.hedgehog/BMAD/` is archival and immutable once written. Nothing in
-`hedgehog-loop`'s day-to-day operation, `hedgehog-bootstrap`, or
-`reviewer` reads this folder live — `planner` reads it exactly once,
-right after the shelf completes, to mine it. After that it's historical
-record only, the same relationship the commit log has to a merged PR.
-
-## Phase 1 — Mining
+`.hedgehog/BMAD/` is archival and immutable once written, on both cores.
+Nothing in `hedgehog-loop`'s day-to-day operation, `hedgehog-bootstrap`,
+or `reviewer` reads this folder live — `planner` reads it exactly once,
+right after the shelf completes, to mine it (this skill's Phase 1 below
+on full-stack-app; `hedgehog-landing-loop`'s planning-intake section on
+landing-page). After that it's historical record only, the same
+relationship the commit log has to a merged PR.
+
+## Phase 1 — Mining (full-stack-app only)
+
+landing-page's counterpart to this Phase 1 is
+`hedgehog-landing-loop`'s own planning-intake section, run once Phase 0
+above completes: it mines the same `.hedgehog/BMAD/` archive into a
+subject/audience/job statement, in place of the scope boundary/domain
+modules/Add-ons decision this Phase 1 produces.
 
 Read `.hedgehog/BMAD/` once and do the interpretive work BMAD's docs
 don't do for you — none of BMAD's outputs contain a ready-made

package/src/templates/CLAUDE.core.full-stack-app.md

@@ -0,0 +1,131 @@
+## This project's core: full-stack-app
+
+Backend-first, schema → contract → repository → service → controller, then
+hook → UX rationale → screen, per domain module. See `.hedgehog/BMAD/` for
+the archival planning intake output — BMAD-METHOD's brainstorming, brief,
+PRD, and UX spec, written once by `planner` and never edited after.
+`TODO.md` also carries this core's `## Add-ons` block (Auth/Queue/Mobile,
+each on or off) — check it before assuming any add-on's infra exists.
+
+### The skills — invoke these, don't improvise
+
+The discipline is packaged as skills. Use them; don't reconstruct their
+steps from memory:
+
+- **`hedgehog-loop`** — every unit of work once bootstrapped: pick the
+  next step from `TODO.md`, build exactly one, gate it, commit it, check
+  it off. Also holds the Correction Protocol for fixing a wrong upstream
+  step. Invoke it at the start of any build session and for "what's next".
+- **`hedgehog-bootstrap`** — run **once**, at project start, to scaffold
+  the core stack, the enforcement config, and whichever add-ons (Auth,
+  Queue, Mobile) planning intake turned on. Skip if `nx.json` already
+  exists.
+- **`conventional-commits`** — when a change spans several steps in one
+  working-tree pass and needs splitting back into per-step commits (mainly
+  Correction Protocol cleanups).
+
+### The agents — delegate the judgment calls
+
+- **`planner`** — planning intake (which core applies, then
+  `hedgehog-planning-intake`'s BMAD-METHOD brainstorming/brief/PRD/UX-spec
+  shelf, mined into scope boundary, the Add-ons decision, and domain
+  vocabulary) at project start, and module scoping when new scope enters
+  play. Writes `TODO.md` (including its `## Add-ons` block),
+  `.hedgehog/BMAD/`, and `docs/design/<module>-notes.md`. On first run,
+  hands off to the `bootstrap` agent once Confirm & Lock holds.
+- **`bootstrap`** — runs `hedgehog-bootstrap`'s core steps (always) plus
+  whichever add-on steps planning intake turned on. Triggered
+  automatically by `planner` after its first run; skip if `nx.json`
+  already exists.
+- **`backend-eng`** — builds each module's Phase A steps (schema →
+  contract → repository → service → controller → queue?), one step at a
+  time, gated and committed in its own context.
+- **`ux-planner`** — once per module in Phase B, after the hook exists and
+  before the screen: writes `docs/design/<module>.md`.
+- **`front-end-eng`** — builds each module's Phase B steps (hook, screen)
+  from the ux-planner rationale, one step at a time, in its own context.
+- **`reviewer`** — phase-transition and Correction Protocol checks the
+  mechanical gate can't make (port discipline, FK-by-ID discipline,
+  contract shape).
+
+## The constants (do not deviate)
+
+### Stack: core (locked, every project) + add-ons (this project's picks below)
+
+**Core** — applies regardless of project size or which add-ons are on:
+Nx monorepo · pnpm · **NestJS** (all domain logic + DB access) · **Drizzle**
+(+ `drizzle-zod`) · **PostgreSQL** · **Docker Compose** (local Postgres,
+every host OS) · Railway · **ts-rest** contracts · **Zod** validation ·
+**TanStack Query** hooks · **Next.js** + ShadCN + Tailwind (web, UI only) ·
+Pino logging · Vitest + Playwright (tests) · Conventional Commits +
+commitlint + lefthook · Sentry.
+
+**Add-ons** — each on or off per project, decided at planning intake and
+recorded in `TODO.md`'s `## Add-ons` block; check that block for this
+project's actual picks rather than assuming any of these are present:
+
+| Add-on | Adds |
+| --- | --- |
+| Auth | Better Auth, `packages/auth`, a global auth guard on `apps/api` |
+| Queue | BullMQ + Redis, `apps/worker`, a `Queue` port/adapter seam |
+| Mobile | Expo + React Native Reusables + NativeWind, `apps/mobile` |
+
+An add-on that's off means the corresponding piece of infra genuinely
+isn't in this codebase — don't write code assuming `packages/auth`,
+`apps/worker`, or `apps/mobile` exist without checking `TODO.md`'s
+`## Add-ons` block first.
+
+Don't substitute libraries, in core or in whichever add-ons are on. If a
+package or generator name changed upstream, verify against current docs
+before running — don't swap in a different library.
+
+### Layout
+
+```
+docker-compose.yml   local Postgres (+ Redis if Queue add-on is on) — every host OS, no native install
+apps/
+  web        Next.js — UI only
+  mobile     Expo — only if Mobile add-on is on
+  api        NestJS — owns all domain logic + DB access
+  worker     BullMQ consumers — only if Queue add-on is on
+packages/
+  db         Drizzle schema + client
+  contracts  ts-rest + Zod contracts
+  hooks      TanStack Query — shared web + mobile
+  jobs       typed job registry / queue definitions — only if Queue add-on is on
+  auth       Better Auth config — only if Auth add-on is on
+  config     locked ESLint/Prettier/tsconfig/env schema
+  shared     cross-cutting types + utils
+libs/
+  <module>/port · <module>/repository · <module>/service   (one triplet per table)
+.hedgehog/
+  BMAD/      archival planning intake output (brief, PRD, UX spec, research) — write-once, from planner
+docs/
+  design     <module>-notes.md (planner, sourced from BMAD's UX spec) and <module>.md (ux-planner)
+```
+
+Check `TODO.md`'s `## Add-ons` block before assuming any "only if" line
+above is actually present in this codebase.
+
+### Core rules
+
+- **One table = one domain module.** Each carries the full step sequence.
+- **Cross-module references are FK-by-ID only.** A service imports only
+  its own ports — never another module's adapter. (Enforced by Nx module
+  boundaries; building out of order fails `nx lint`.)
+- **Backend before frontend.** Phase A (schema → contract → repository →
+  service → controller → queue?) closes for a module before Phase B
+  (hooks → screen) opens. Enforced by the CI phase gate.
+- **Sequential within a phase.** A step starts only once the previous one
+  compiles and passes tests.
+- **One step = one commit**, in the exact Conventional Commit format from
+  `hedgehog-loop`. A commit that fails typecheck/lint/test does not happen
+  (lefthook gate).
+- **Fix wrong steps at the source** via the Correction Protocol — never a
+  downstream workaround.
+- **Local Postgres always runs through `docker-compose.yml`**, 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.
+- **`packages/config` is the single source** for shared config. A per-app
+  override request means fix the base config, not add an override.

package/src/templates/CLAUDE.core.landing-page.md

@@ -0,0 +1,133 @@
+## This project's core: landing-page
+
+The Chain Method: brief → feeling → tokens/motif → sequence → artifact,
+where every visual choice traces back to a sentence that caused it. No
+domain data, no backend — a single (or few-page) marketing site, built
+once through a fixed pipeline rather than iterated on freely. See
+`.hedgehog/BMAD/` for the vendored BMAD-METHOD shelf's raw output and
+`.hedgehog/chain/` for this core's own archival planning intake output —
+the Strategist's subject statement, the adjective/note tables, and the
+token system, written once by `planner` and the pipeline agents, never
+edited after a phase closes.
+
+### The skills — invoke these, don't improvise
+
+- **`hedgehog-landing-loop`** — every unit of work once bootstrapped:
+  pick the next step from `TODO.md`, run exactly one Chain Method phase
+  through its owning agent, gate it, commit it, check it off. Also holds
+  the Correction Protocol for fixing a wrong upstream phase (e.g. a
+  motif that doesn't trace back to the subject statement). Invoke it at
+  the start of any build session and for "what's next".
+- **`hedgehog-bootstrap-landing-page-core`** — run **once**, at project
+  start, to land the pre-verified Astro + Tailwind workspace. Skip if
+  `astro.config.mjs` already exists.
+- **`conventional-commits`** — when a change spans several phases in one
+  working-tree pass and needs splitting back into per-phase commits
+  (mainly Correction Protocol cleanups).
+
+### The agents — delegate the judgment calls
+
+- **`planner`** — planning intake (which core applies, then this core's
+  own brief intake: the vendored BMAD-METHOD shelf, run in full and
+  mined into subject, audience, single page job) at project start.
+  Writes `TODO.md`, `.hedgehog/BMAD/`, and `.hedgehog/chain/00-brief.md`.
+  On first run, hands off to the `bootstrap` agent once Confirm & Lock
+  holds.
+- **`bootstrap`** — runs `hedgehog-bootstrap-landing-page-core`'s steps.
+  Triggered automatically by `planner` after its first run; skip if
+  `astro.config.mjs` already exists.
+- **`landing-strategist`** — Chain Method steps 1–3 and 4c, plus the
+  Diagnostician/Narrative Agent/Objection Agent sub-steps folded into
+  step 1: subject statement → Awareness/Sophistication/Big-Idea
+  diagnosis → narrative arc → objection map → adjective pairs
+  (visceral/behavioral/reflective) → top/heart/base note timing and the
+  page's single peak moment. One context, one artifact: the emotional
+  and persuasive target spec.
+- **`landing-systems`** — steps 4a/4b/5/6, run together: the ingredient
+  dial table, the copy voice spec (plus the Awareness-gated headline and
+  objection rebuttal prose), the token system that reconciles them, and
+  the signature motif. Owns everything that becomes a Tailwind token or a
+  piece of copy.
+- **`landing-sequencer`** — step 7: per-section transition type, weight,
+  spacing, and beat structure — the GSAP/ScrollTrigger/Lenis pacing spec
+  the Builder implements against.
+- **`landing-critic`** — steps 8–9 reconciled: traceability/distinctiveness
+  audit (does every choice trace to the subject statement, does anything
+  match a known AI-default cluster) and the usability pass (Fitts's Law
+  on the CTA, affordance/signifier check). Has veto power; cannot rewrite,
+  only redline back to the owning agent.
+- **`landing-builder`** — step 10: builds the audited spec exactly in
+  Astro. Anything that can't be built as specified is flagged back up the
+  chain, never silently improvised around.
+
+## The constants (do not deviate)
+
+### Stack (locked, every project — no add-ons on this core)
+
+**Astro** (zero-JS-by-default shell, islands only where interaction is
+genuinely needed) · **Tailwind** (config as token layer only — no
+component library on top) · **GSAP + ScrollTrigger** (primary animation
+engine; owns Sequencer pacing and top/heart/base fade timing) ·
+**Lenis** (smooth-scroll feel) · **SVG-first** (hand-authored graphics
+for the motif — no icon library or generator look) · **SplitType**
+(line/word/char copy-reveal splitting) · **Paper.js** (canvas vector
+work for a motif that evolves across sections) · **MorphSVGPlugin**
+(GSAP — for a motif that physically transforms across sections) ·
+**custom SVG noise/grain filter** (cheap materiality/texture layer) ·
+**React Three Fiber** (rare — only when the subject is genuinely
+spatial; default is to skip it).
+
+Figma MCP / Stitch MCP are handoff/input tools only, used at the
+Strategist/Builder boundaries — never allowed to set spacing or style
+defaults directly. Anything they hand off is re-derived through the
+Systems Designer's token system (step 5) before it touches Tailwind
+config.
+
+Don't substitute libraries. If a package name changed upstream, verify
+against current docs before running — don't swap in a different one, and
+don't reach for a component library or icon set to fill a gap one of the
+above doesn't cover; that gap is a signal to go back to the Ingredient
+Vocabulary and derive the right choice, not to default to something
+off-the-shelf.
+
+### Layout
+
+```
+astro.config.mjs     Astro workspace root
+tailwind.config.ts    token layer only — hex values, type roles, spacing unit, easing family from Step 5
+src/
+  pages/              one file per page (usually just index.astro)
+  sections/           one component per page section, in Sequencer order
+  motifs/             the signature SVG/Paper.js motif + its variation rules
+  styles/             global.css — Tailwind import + CSS variable theme
+.hedgehog/
+  BMAD/               vendored BMAD-METHOD shelf's raw output (brief, PR-FAQ, PRD, UX spec, research) —
+                       write-once, from planner
+  chain/              this core's own archival planning intake output — subject statement, adjective tables,
+                       token system, motif spec, sequence spec — write-once, from planner + pipeline agents
+docs/
+  design/              audited spec (Critic + Usability Auditor reconciled) the Builder builds from
+```
+
+### Core rules
+
+- **One page, one job.** The Strategist's subject statement names it;
+  every downstream choice traces back to that sentence or gets cut.
+- **No agent introduces a choice that doesn't originate in the previous
+  agent's output.** A motif the Motif Artist didn't source from the
+  subject, a color the Ingredient Director didn't derive from an
+  adjective — both get redlined by the Critic, not waved through.
+- **Ingredients move in agreement.** Color, type, space, motion, copy
+  rhythm, and pacing are one system reconciled at step 5 — a page warm
+  in color but cold in type is a defect, not a style choice.
+- **Sequential through the pipeline.** A phase starts only once the
+  phase before it is checkpointed and committed — steps 4a/4b/4c run in
+  parallel (same input), everything else is strictly sequential.
+- **One phase = one commit**, in the exact Conventional Commit format
+  from `hedgehog-landing-loop`.
+- **Fix wrong phases at the source** via the Correction Protocol — never
+  a downstream workaround (e.g. don't patch the Builder's output to fix
+  a token that's wrong at the Systems Designer's level).
+- **The Critic's veto is real.** A traceability or default-cluster
+  failure blocks the Builder from starting, the same way a failing gate
+  blocks a commit elsewhere in Hedgehog.