@skyf0xx/hedgehog 0.1.12 → 0.1.13

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

@@ -0,0 +1,172 @@
+---
+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.
+---
+
+# 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
+
+State the BMAD attribution, then run the vendored shelf in full
+sequence, every time — no per-project skip logic, no reduced default
+set:
+
+1. `bmad-brainstorming` (`skills/BMAD/core-skills/bmad-brainstorming`) —
+   diverge on the idea before locking anything.
+2. `bmad-product-brief` (`skills/BMAD/bmm-skills/1-analysis/bmad-product-brief`)
+   — the product brief.
+3. `bmad-prfaq` (`skills/BMAD/bmm-skills/1-analysis/bmad-prfaq`) — vets
+   the idea press-release-style.
+4. `bmad-prd` (`skills/BMAD/bmm-skills/2-plan-workflows/bmad-prd`) — the
+   PRD, including its Glossary (entities, relationships, cardinality).
+5. `bmad-ux` (`skills/BMAD/bmm-skills/2-plan-workflows/bmad-ux`) — the UX
+   spec, `DESIGN.md` + `EXPERIENCE.md`.
+6. `bmad-deep-recon` (`skills/BMAD/core-skills/bmad-deep-recon`) —
+   market/competitive/user-voice research.
+
+Any skill may itself invoke `bmad-advanced-elicitation`
+(`skills/BMAD/core-skills/bmad-advanced-elicitation`) at its own pause
+points — that's expected, let it run.
+
+Write each skill's output to `.hedgehog/BMAD/`, per the fixed layout:
+
+```
+.hedgehog/BMAD/
+  00-manifest.md        # attribution + pinned version + date + which skills ran
+  01-brainstorming.md
+  02-brief.md
+  03-prfaq.md
+  04-prd.md
+  05-ux-spec/
+    DESIGN.md
+    EXPERIENCE.md
+  06-research.md
+```
+
+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
+
+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
+Auth/Queue/Mobile toggle or a module-ownership/FK table; the PRD's
+Glossary is the closest thing, but it's vocabulary-shaped prose, not a
+decision table:
+
+1. **Scope boundary** — derive from the brief's Scope section plus the
+   PRD's Glossary/Features. In scope: what the elicited material actually
+   called for. Out of scope: anything the brief or PRD flagged as
+   deferred, painful-but-not-now, or explicitly excluded.
+2. **Domain modules** — derive from the PRD's Glossary (entity,
+   relationships, cardinality): one table = one module, same rule as
+   Hedgehog has always used. A cluster with its own lifecycle, referenced
+   by other things, is a candidate module; a thing mentioned only as a
+   property of another isn't.
+3. **Cross-module references** — from the Glossary's relationships/
+   cardinality, identify which module's schema holds the FK, so build
+   order between modules is clear before anyone writes a schema.
+4. **Add-ons decision** (Auth, Queue, Mobile) — check BMAD's docs (brief,
+   PRD, UX spec) for each trigger first:
+   - **Auth** — on if the material describes accounts, logins, or
+     per-user/per-account data.
+   - **Queue** — on if at least one described operation is genuinely
+     long-running, needs retries, or fans out.
+   - **Mobile** — on if the material explicitly wants a mobile app
+     alongside or instead of web.
+
+   Infer first, gap-fill second — this is not a second full interview.
+   For any add-on the text leaves genuinely unresolved (not mentioned
+   either way), ask the user directly, the same direct-question posture
+   as an ambiguous scope boundary: "does this need user accounts/login,
+   or is it just for you?", "is anything here a background job, or is it
+   all instant reads and writes?", "web only, or mobile too?" A "no" is a
+   resolved answer, not a gap. Never default an add-on on or off without
+   either a concrete trigger in BMAD's docs or a direct answer — an
+   unasked add-on question is a guess.
+5. **Run Confirm & Lock** (below) before writing anything.
+6. **Write `TODO.md`** — the checklist mirroring Bootstrap, Phase A, and
+   Phase B steps per module and add-on in scope, plus the `## Add-ons`
+   block (see "The Add-ons block" below).
+7. **File `docs/design/<module>-notes.md` per module** — sourced from
+   `.hedgehog/BMAD/05-ux-spec/EXPERIENCE.md` (information architecture,
+   states, flows) and `DESIGN.md` (visual identity): file each module's
+   slice into its own notes file, same fixed filename pattern, same
+   "every module gets one, even if empty" rule as always — a module with
+   no UX-spec material yet still gets a `docs/design/<module>-notes.md`
+   stating that plainly, not a missing file. `ux-planner` reads this file
+   as raw screen/flow material at that module's Phase B.
+8. **Fill root `CLAUDE.md`'s `{{PROJECT_NAME}}` and `{{PROJECT_SUMMARY}}`
+   placeholders**, first run only, then delete the installer's HTML
+   comment block at the top of that file. Leave every other line
+   untouched.
+
+On a later run (new scope entering play), skip steps 4 and 8 unless new
+scope genuinely changes an add-on trigger (e.g. accounts get added where
+there were none) or the project's identity itself changed — append new
+module sections to `TODO.md` only, never touch an existing module's
+checked boxes or reorder modules already in progress.
+
+## The Add-ons block
+
+`TODO.md` carries the Add-ons decision directly — no side-channel
+document. Write a short, fixed-format `## Add-ons` block into `TODO.md`:
+
+```
+## Add-ons
+- Auth: on — accounts/login in scope
+- Queue: off — no long-running ops
+- Mobile: off — not requested
+```
+
+Each line: the add-on, on/off, a one-line reason it landed there. This is
+the single stable, machine-checkable field every downstream check reads
+— `hedgehog-bootstrap`, `bootstrap`, `hedgehog-loop`, and `reviewer` all
+check `TODO.md`'s `## Add-ons` block, not any other file. An absent
+`## Add-ons` block reads as "never decided," not "decided off" — those
+two are distinct and downstream checks treat them differently.
+
+## Confirm & Lock
+
+Everything through Phase 1 mining is provisional and cheap to change —
+nothing has been written yet. This stage is the last point before that
+stops being true, so it's a hard stop, not a recap in passing.
+
+🔒 **Confirm & Lock**. Show, in full, not condensed:
+
+- The scope boundary (in / out), sourced from the brief + PRD.
+- The Add-ons decision (Auth / Queue / Mobile, each explicitly on or
+  off, with the one-line reason — from BMAD's docs or a direct answer).
+- The domain vocabulary / module list, in build order, with any
+  cross-module FK dependencies flagged.
+- Which BMAD skills ran and where their output lives
+  (`.hedgehog/BMAD/`).
+
+Then state plainly what happens on confirmation, before it happens:
+
+> This locks in `TODO.md` (with the `## Add-ons` block) and
+> `docs/design/<module>-notes.md` per module, and hands off to the
+> `bootstrap` agent to scaffold the workspace and whichever add-ons are
+> on. Phase A build (schema first) starts on the first module once that
+> closes. Anything wrong or missing — say so now; it's a normal edit
+> before this point, and a Correction Protocol entry after. Confirm to
+> proceed, or tell me what to change.
+
+Wait for an explicit go-ahead. A revision here is just another mining
+pass — update the draft, re-run this stage, don't write anything until
+the confirmation holds.

package/src/templates/CLAUDE.md

@@ -2,19 +2,21 @@
   Hedgehog project CLAUDE.md template.
 
   This file is copied into a consuming project's repo root at install
-  time. Placeholders wrapped in {{ }} are filled in once, at Intake, by
-  the `planner` agent (or by hand). Everything outside the placeholders is
-  a constant of the Hedgehog discipline and should be left as-is.
+  time. Placeholders wrapped in {{ }} are filled in once, at planning
+  intake, by the `planner` agent (or by hand). Everything outside the
+  placeholders is a constant of the Hedgehog discipline and should be
+  left as-is.
 
   Delete this comment block after the placeholders are filled in.
 -->
 
 # {{PROJECT_NAME}}
 
-{{PROJECT_SUMMARY — 2–4 sentences the `planner` writes at Intake: what
-this project is, who it's for, and what it does. State current intent, not
-history. Keep it tight — the full product narrative, scope boundary, and
-domain vocabulary live in docs/context.md, not here.}}
+{{PROJECT_SUMMARY — 2–4 sentences the `planner` writes at planning
+intake: what this project is, who it's for, and what it does. State
+current intent, not history. Keep it tight — the full product narrative,
+scope boundary, and domain vocabulary live in `.hedgehog/BMAD/` (the
+planning documents) and `TODO.md`, not here.}}
 
 This project is built with **Hedgehog**: a backend-first, one-step-at-a-time
 build discipline. The rules below aren't project preferences — they're how
@@ -25,10 +27,12 @@ the build stays mechanically correct. Follow them exactly.
 If `{{PROJECT_SUMMARY}}` above is still an unfilled placeholder, this is a
 brand-new install and nothing has been built yet. Open with something
 short and warm — 🦔 plus one line asking what the user wants to build —
-then hand straight to `planner` to run Intake. Don't re-explain the
-discipline or summarize this file; the greeting is one line, not a tour.
-Skip this entirely once the placeholder is filled in — every later session
-starts with `TODO.md`, not a greeting.
+then hand straight to `planner`, which runs planning intake on
+BMAD-METHOD (brainstorming → brief → PRD → UX spec), then mines that
+output into Hedgehog's own scope boundary and `## Add-ons` decision.
+Don't re-explain the discipline or summarize this file; the greeting is
+one line, not a tour. Skip this entirely once the placeholder is filled
+in — every later session starts with `TODO.md`, not a greeting.
 
 ## How to work here
 
@@ -36,12 +40,14 @@ The build is a loop of small, gated, committed steps. You never hold the
 whole plan in context — the plan lives in the structure:
 
 - **`TODO.md`** is the live checklist and the source of truth for what's
-  next. Read it at the start of every session. Its only state is
+  next, including the `## Add-ons` block (Auth/Queue/Mobile, each on or
+  off). Read it at the start of every session. Its only state is
   checked/unchecked.
-- **`docs/context.md`** is the product's current-state document — product
-  narrative, scope boundary, domain vocabulary. Every project has one,
-  written by `planner` at Intake and kept current on later Intakes. It
-  states what's true now, never a history of what changed.
+- **`.hedgehog/BMAD/`** is the archival record of planning intake —
+  BMAD-METHOD's brainstorming, brief, PRD, and UX spec output, written
+  once by `planner` and never edited after. It's historical record, the
+  same relationship the commit log has to a merged PR — nothing in the
+  day-to-day build reads it live.
 - **The commit log** is the record of what's built and why. Conventional
   commits (`feat(<module>): schema`, `feat(<module>): api`, …) are how
   progress is read, not a conversation summary.
@@ -70,24 +76,25 @@ steps from memory:
   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) Intake turned on. Skip if `nx.json` already exists.
+  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).
-- **`hedgehog-intake`** — the Intake elicitation/synthesis procedure
-  (scope boundary, add-ons decision, domain vocabulary). Invoked by the
-  `planner` agent; don't run it standalone.
 
 ### The agents — delegate the judgment calls
 
-- **`planner`** — Intake (whether Hedgehog applies at all, scope
-  boundary, the add-ons decision, and 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`. On first
-  Intake, hands off to the `bootstrap` agent once Confirm & Lock holds.
+- **`planner`** — planning intake (whether Hedgehog applies at all, 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 Intake turned on. Triggered automatically by
-  `planner` after first Intake; skip if `nx.json` already exists.
+  whichever add-on steps planning intake turned on. Triggered
+  automatically by `planner` after its first run; skip if `nx.json`
+  already exists.
 - **`ux-planner`** — once per module in Phase B, after the hook exists and
   before the screen: writes `docs/design/<module>.md`.
 - **`ui-builder`** — builds screens from the ux-planner rationale.
@@ -107,9 +114,9 @@ every host OS) · Railway · **ts-rest** contracts · **Zod** validation ·
 Pino logging · Vitest + Playwright (tests) · Conventional Commits +
 commitlint + lefthook · Sentry.
 
-**Add-ons** — each on or off per project, decided at Intake and recorded
-in `docs/context.md`'s Add-ons note; check that file for this project's
-actual picks rather than assuming any of these are present:
+**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 |
 | --- | --- |
@@ -119,8 +126,8 @@ actual picks rather than assuming any of these are present:
 
 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 `docs/context.md`
-first.
+`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
@@ -145,13 +152,14 @@ packages/
   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/
-  context.md product narrative, scope boundary, add-ons decision, domain vocabulary (Intake)
-  design     <module>-notes.md (Intake) and <module>.md (ux-planner)
+  design     <module>-notes.md (planner, sourced from BMAD's UX spec) and <module>.md (ux-planner)
 ```
 
-Check `docs/context.md`'s Add-ons note before assuming any "only if"
-line above is actually present in this codebase.
+Check `TODO.md`'s `## Add-ons` block before assuming any "only if" line
+above is actually present in this codebase.
 
 ### Core rules
 
@@ -195,8 +203,8 @@ off. Keep it thin.
 **When the build is done:** once every module in scope has both phases
 checked, the build session is complete. **Delete `TODO.md`** — a finished
 checklist is noise, and the commit log is the durable record of what was
-built. **`docs/context.md` stays** — it's the product's current-state
-document, not a checklist.
+built. **`.hedgehog/BMAD/` stays** — it's the archival planning record,
+not a checklist.
 
 ## Managing context
 
@@ -208,11 +216,12 @@ context small:
   `TODO.md` and continue. Nothing is lost, because the checklist, commits,
   and code hold all the state. Prefer this over letting one session
   accumulate the entire project.
-- **A cleared or new session recovers by reading `TODO.md`,
-  `docs/context.md`, and the commit log**, never by needing the prior
-  conversation.
+- **A cleared or new session recovers by reading `TODO.md` and the
+  commit log**, never by needing the prior conversation. `.hedgehog/BMAD/`
+  is available if the product narrative itself needs re-reading, but
+  day-to-day recovery doesn't need it.
 - **Delegate heavy work to agents.** The project scaffold (`bootstrap`),
-  Intake elicitation (`planner`), screen builds (`ui-builder`), and
+  planning intake (`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

package/src/templates/TODO.md

@@ -1,17 +1,26 @@
 # TODO
  
 <!-- 2-3 sentences: what is this project. Full product narrative, scope
-boundary, and domain vocabulary live in docs/context.md — every project
-has one, written by planner at Intake. -->
+boundary, and domain vocabulary live in .hedgehog/BMAD/04-prd.md — every
+project has one, written by planner from BMAD-METHOD's planning shelf. -->
  
 ## Context
  
-(fill in per project — see docs/context.md for the full picture)
+(fill in per project — see .hedgehog/BMAD/04-prd.md for the full picture)
+
+## Add-ons
+
+<!-- Written by planner at planning intake. Each line: on/off + the
+one-line reason. An absent block reads as "never decided," not "off". -->
+
+- Auth: (fill in: on/off — reason)
+- Queue: (fill in: on/off — reason)
+- Mobile: (fill in: on/off — reason)
  
 ## Bootstrap
 
-<!-- Add-on steps (planner marks each on/skipped at Intake, per
-docs/context.md's Add-ons note) run live, one at a time, after core. A
+<!-- Add-on steps (planner marks each on/skipped at planning intake, per
+the ## Add-ons block above) run live, one at a time, after core. A
 skipped add-on gets checked off as skipped, not left unchecked. -->
 
 - [x] Nx workspace + `packages/config` (incl. `docker-compose.yml` for local Postgres) — core, landed via `hedgehog init`, verified via `hedgehog-bootstrap-core`