@skyf0xx/hedgehog 2.0.13 → 3.0.0

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

@@ -16,9 +16,10 @@ This piece is deterministic — the same commands produce the same output
 on every project — so the output is committed once, upstream, and copied
 here instead of re-derived by an agent on every run.
 
-This skill has no per-project decisions to make: no add-ons, no `TODO.md`
-dependency beyond checking its own Bootstrap line, nothing to ask.
-Landing-page's core is identical on every project running it.
+This skill has no per-project decisions to make: no add-ons, no
+dependency beyond confirming its own commit hasn't already landed,
+nothing to ask. Landing-page's core is identical on every project
+running it.
 
 ## What lands
 
@@ -98,12 +99,9 @@ the same gate every phase in this core's loop runs.
 feat(landing): workspace
 ```
 
-One commit for all of core, landed as a verified copy.
-
-### 6. `TODO.md`'s core line
-
-The Bootstrap line ships pre-checked in the `landing-page` `TODO.md`
-template. If step 2's fallback copy ran, check it now.
+One commit for all of core, landed as a verified copy. That commit
+existing is the record that core landed — `bootstrap` checks for it via
+the commit log, not a checklist line.
 
 ## Known issues baked into the landing-page core
 

package/src/skills/hedgehog-core-design/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: hedgehog-core-design
+description: Use on full-stack-app and landing-page alike only when neither shipped Golden Core fits a project that is still building something real — picks the stack and designs the layer sequence for it, and writes `.hedgehog/core.yaml`. Invoked by the `planner` agent as Phase 0's third outcome, after the vendored BMAD shelf has run; don't run standalone and don't run when a shipped core fits.
+---
+
+# Hedgehog Core Design
+
+Designs a core definition for a project no shipped Golden Core fits.
+Hedgehog decides the architecture here — the stack, the layers, their
+order, their file scope, their verification — and shows it back for
+confirmation. The user is asked about their product, never asked to pick
+a stack or design layers; a person who could name the right stack and
+layer sequence unprompted wouldn't need a build discipline to enforce it.
+
+The output is one file, `.hedgehog/core.yaml`, in the exact format
+shipped cores use (spec: "Core definitions"). Everything else this skill
+produces is rationale, and rationale goes to `.hedgehog/core-design.md`,
+not into `core.yaml` — the loader (`src/db/core.mjs`) parses a narrow
+YAML subset and throws on anything outside it.
+
+## When this runs
+
+After `hedgehog-planning-intake`'s Phase 0, not before. An architecture
+can't be designed from a one-line project description: the drivers that
+decide it — persistence, concurrency, deployment target, integration
+surface — are exactly what BMAD's brief and PRD elicit. So `planner`'s
+Phase 0 reaches its third outcome ("neither shipped core fits, but
+something is being built"), runs the BMAD shelf in full, then opens this
+skill against that archive. Intent mining follows this skill, not the
+other way round — the layer sequence has to exist before `hedgehog plan`
+can compile anything against it.
+
+## Step 1 — name the system shape
+
+Say what the project fundamentally is, in one line, before deriving
+anything from it: a CLI, a library or SDK, a data pipeline, a browser
+extension, a desktop app, a compiler or language tool, a bot or agent, a
+game, an infrastructure/deploy tool. Pick the dominant one. A project
+with several surfaces has one primary system and the rest are layers
+inside it, not co-equal architectures.
+
+This is the step that catches a misrouted Phase 0. If the shape you land
+on is "a web app with a database behind it," that is `full-stack-app` and
+you should say so and route back rather than author a near-copy of a
+shipped core under a new name. The same goes for a marketing page that
+grew a second page — still `landing-page`.
+
+## Step 2 — pick the stack
+
+Name the language, package manager, and the one or two frameworks that
+shape the architecture (a web/CLI/RPC framework, not every library the
+project will eventually need) before deriving layers — a layer's `verify`
+command can't be written until the test runner and build tooling are
+decided, and layer boundaries themselves often follow framework
+conventions (e.g. a middleware layer only exists if the framework has
+middleware). Don't ask the user to choose — the same reasoning Step 1
+applies to layers applies here: naming a stack is exactly what a build
+discipline exists to decide unprompted, and asking would just relocate
+the design work onto the person who came here to avoid doing it.
+
+Pick one default per system shape, the same way the shipped cores commit
+to one choice per row rather than a menu (`hedgehog-bootstrap`'s stack
+table). Substitute off a default only for a concrete, named constraint
+read from `.hedgehog/BMAD/` — never a general preference for variety:
+
+| System shape | Default stack | Substitute when |
+|---|---|---|
+| CLI | TypeScript + Node, Commander, Vitest, pnpm | the target users are a Python-first or Go-first ecosystem (data/ML tooling → Python + Typer + pytest; infra/systems tooling → Go + Cobra + `go test`) |
+| Library / SDK | TypeScript, tsup, Vitest, pnpm | the consuming ecosystem is fixed by the brief (a Python package → Python + Hatch + pytest; publishing to both → author the TS core first, wrap it) |
+| Data pipeline | Python, stdlib/argparse or Dagster for orchestration, pytest, uv or pip | the pipeline is thin glue over an existing Node/TS service mesh already named in the brief |
+| Browser extension | TypeScript, the target browser's WebExtension API (`@types/chrome` or WXT), Vitest, pnpm | none in practice — this shape has one real ecosystem |
+| Desktop app | TypeScript + Electron, Vitest + Playwright, pnpm | native platform integration is a stated hard requirement (macOS/Windows-only, deep OS API use) → Swift/AppKit or C#/WinUI, per platform, named explicitly |
+| Compiler / language tool | Rust, `cargo test`, Cargo | the brief is explicitly about fast iteration over raw performance, or targets a JS/TS-only toolchain (a Babel/ESLint plugin) → TypeScript, Vitest, pnpm |
+| Bot / agent | TypeScript, Vitest, pnpm | the brief calls for heavy ML/data-science library use → Python, pytest, uv |
+| Game | TypeScript + a canvas/WebGL engine already named in the brief (e.g. PixiJS, Three.js), Vitest, pnpm | a native/console target is explicit → the engine's native language (C#/Unity, C++), named per that engine |
+| Infra / deploy tool | Go, `go test`, Go modules | the tool is a thin wrapper generating config/manifests with no systems-level need → TypeScript, Vitest, pnpm |
+
+A shape not on this table is rare enough that no default has been
+battle-tested — reason from the same drivers `hedgehog-bootstrap`'s
+table encodes (ecosystem the target users already live in, deployment
+target, the language the brief's own examples or comparables are
+written in) and name the result as a judgment call, not a table lookup,
+in `core-design.md`'s rationale.
+
+Record the choice as one line — language, package manager, the named
+framework(s), test runner — before moving to Step 3; every layer's
+`scope` and `verify` in Step 3 draws from it.
+
+## Step 3 — derive the layers
+
+Read `.hedgehog/BMAD/` for what the system actually does, then decide the
+layers it builds in. A layer earns its place by owning a distinct
+artifact that can be verified on its own. Order by dependency first (a
+layer that another layer imports comes first) and by risk second (where
+two layers are independent, build the one that would invalidate the other
+if it went wrong first).
+
+Three rules with teeth:
+
+- **A layer with no executable verification is not a layer.** Fold it
+  into its neighbour or drop it. `verify: manually inspect` is not a
+  verify command, and the loader rejects an empty one outright
+  (`validateCore`, `src/db/core.mjs`).
+- **A layer whose file scope overlaps another layer's is not a layer.**
+  Scope is what stops step N from quietly rewriting step N−1's work;
+  overlapping globs make that enforcement meaningless.
+- **Don't reproduce a Golden Core's sequence under new names.** If
+  schema → contract → repository → service → controller is genuinely
+  right, Phase 0 picked the wrong outcome.
+
+Four to seven layers is the usual range. Fewer than three means the
+project probably wanted a shipped core or no core at all; more than eight
+means several layers are one layer with internal steps.
+
+## Step 4 — decide the module axis
+
+Answer explicitly, because it changes the shape of the whole graph:
+
+- **Module axis** (like `full-stack-app`) — the layer chain instantiates
+  once per intent. Every scope glob, verify command, and commit message
+  that differs per module carries the `{module}` placeholder, which
+  `hedgehog plan` fills with the intent's id (`src/db/plan.mjs`). The
+  graph is intents × layers tasks.
+- **Linear chain** (like `landing-page`) — one pass total, no `{module}`
+  anywhere. The graph is one task per layer. Mine the project as a single
+  intent.
+
+Choose a module axis when the project has repeating units of domain work
+that each walk the same layers (entities, commands, resources,
+integrations). Choose a linear chain when the project is built once,
+front to back.
+
+Getting this wrong is the most common failure. A module-axis core whose
+scopes omit `{module}` gives every intent identical scope globs, so
+intent A's task may write intent B's files and the scope enforcement that
+justifies authoring a core at all disappears. Check every glob before
+writing the file.
+
+## Step 5 — write `.hedgehog/core.yaml`
+
+The loader parses `id` plus a `layers` list of flat maps. Every layer
+needs all five fields — `depends_on` is omitted only on the first layer:
+
+```yaml
+id: cli-tool
+layers:
+  - id: command-model
+    scope: ["src/commands/**"]
+    verify: "pnpm test commands && pnpm typecheck"
+    commit: "feat({module}): command model"
+  - id: domain
+    depends_on: command-model
+    scope: ["src/domain/{module}/**"]
+    verify: "pnpm test {module}-domain"
+    commit: "feat({module}): domain"
+  - id: adapter
+    depends_on: domain
+    scope: ["src/adapters/{module}/**"]
+    verify: "pnpm test {module}-adapter"
+    commit: "feat({module}): adapter"
+```
+
+Constraints the loader and compiler impose, all of them silent failures
+if missed:
+
+- **`commit` is required in practice**, though `validateCore` doesn't
+  check it. `hedgehog plan` writes `commit_message` from it for every
+  task (`src/db/plan.mjs`); a layer without one compiles to a task with
+  an empty commit message, and the Correction Protocol and `hedgehog why`
+  both hang off commit shape. Use the conventional-commit form every
+  other core uses: `feat({module}): <layer>`, or `feat(<project>):
+  <layer>` on a linear chain.
+- **`scope` must be an inline list** — `["a/**", "b/**"]` on one line.
+  Block sequences under `scope:` don't parse.
+- **No nesting beyond a layer's flat fields.** Flat top-level keys other
+  than `id` and `layers` are ignored, but any nested block
+  (`architecture:`, `modules:`, `decisions:`) throws at load. Rationale
+  belongs in `.hedgehog/core-design.md`.
+- **`depends_on` names one layer**, and the chain must be acyclic. The
+  compiler walks it directly into `dependencies` rows.
+
+Verify the file loads before showing it back, by calling the loader
+directly:
+
+```bash
+node -e "import('./src/db/core.mjs').then(m => m.loadCore('.hedgehog/core.yaml')).then(c => console.log(JSON.stringify(c, null, 2)))"
+```
+
+Read the layers it prints back: a field the parser dropped shows up as an
+empty string or `[]` there, and a `{module}` you meant to include is
+visible in the globs or absent from them. A `core.yaml` that throws at
+load time is the one failure mode that strands a project with no path
+forward.
+
+## Step 6 — write `.hedgehog/core-design.md`
+
+The rationale the engine doesn't read but the project needs: the system
+shape and why, the stack and why (the default it came from, or the named
+constraint that justified a substitution), the layers with a line each on
+what they own and why they sit where they do, the module-axis decision,
+and anything left unresolved. Written once, archival, never edited after
+— the same stance `.hedgehog/BMAD/` takes. Later changes to the
+architecture are Correction Protocol entries in the commit log, not edits
+here.
+
+## Confirm & Lock
+
+Authoring a core is the most consequential decision in a Hedgehog project
+— every task the graph ever compiles walks this sequence — and it's cheap
+to change only until the file lands. Hard stop.
+
+🔒 **Confirm & Lock**. Show, in full, not condensed:
+
+- The system shape, in the one line from step 1.
+- The stack: language, package manager, and named framework(s), plus
+  whether it's the shape's default or a substitution — and if a
+  substitution, the one-line constraint that justified it.
+- Each layer in order: what it owns, its scope globs, its verify command,
+  its commit message.
+- The module-axis decision, named as such, with the consequence stated
+  (intents × layers tasks, or one task per layer).
+- That this is an authored core: the sequence was designed for this
+  project, not battle-tested across many, and it carries the same
+  enforcement as a Golden Core but a weaker guarantee.
+
+Then state plainly what happens on confirmation, before it happens:
+
+> This writes `.hedgehog/core.yaml` and `.hedgehog/core-design.md`, then
+> planning intake mines the PRD into intents against this layer sequence.
+> Every task this project ever builds walks these layers in this order.
+> Anything wrong — 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 another design pass —
+update the draft, re-run this stage, write nothing until the confirmation
+holds. Once confirmed and written, control returns to `planner`, which
+runs `hedgehog-planning-intake`'s Phase 1 mining against this core the
+same way it would against a shipped one.

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

@@ -1,15 +1,18 @@
 ---
 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/element → 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.
+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/element → sequence → artifact pipeline, gated by `hedgehog verify` and committed one phase at a time. 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.
+The operating loop for a bootstrapped `landing-page` project: `hedgehog
+next` emits the packet for one ready phase, run it through its owning
+agent, `hedgehog verify` gates and commits it. The build graph
+(`.hedgehog/hedgehog.db`) is the live list — query it via `hedgehog
+status`/`hedgehog next`, never re-derive state from prose. The five
+compiled phases (`src/golden-cores/landing-page/core.yaml`, already the
+source of truth) are the degenerate one-module case of the layer graph:
+one task per phase, each depending on the one before it.
 
 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
@@ -55,19 +58,29 @@ back at Confirm & Lock for the user to accept or correct.
    `.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
+   their output lives (`.hedgehog/BMAD/`), before writing anything to the
+   build graph. State plainly what happens on confirmation: *"This locks
+   in the brief, adds the `landing` intent to the build graph
+   (`hedgehog intent add`), compiles it into the five-phase chain
+   (`hedgehog plan`), commits (`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.
+5. **Add the intent and compile the graph**: `hedgehog intent add --id
+   landing --goal "<subject statement>" --outcome "<audience + single
+   job>"` — one call, no `--rule`/`--depends-on` needed; landing-page has
+   no module axis, so this single intent is what `hedgehog plan` compiles
+   against `src/golden-cores/landing-page/core.yaml` into the five phase
+   tasks. Run `hedgehog plan` next, then `hedgehog status` to show the
+   compiled chain.
+6. **Commit planning intake's output as one commit**,
+   `chore(planning): intake` — the committed `.hedgehog/hedgehog.db` (the
+   `landing` intent and its compiled tasks), `.hedgehog/BMAD/`,
+   `.hedgehog/chain/00-brief.md`, and root `CLAUDE.md`'s filled
+   placeholders.
+7. **Hand off to `bootstrap`** once the commit lands.
 
 `planner` owns this section; see that agent for when it runs.
 
@@ -79,6 +92,15 @@ agent works from anything but what was actually handed to it. Steps 4a
 only parallel-input point in the chain, both reading the same upstream
 artifact; everything else is strictly sequential.
 
+This table's 12 rows are the fine-grained, per-agent-dispatch view. The
+compiled build graph (`src/golden-cores/landing-page/core.yaml`) has only
+5 layers — `brief`/`feeling`/`tokens`/`sequence`/`artifact` — because it's
+the coarser, one-task-per-commit view: rows 1–4 compile into one `feeling`
+task, 5–7 into one `tokens` task, 8–10 into one `sequence` task, 11–12
+into one `artifact` task. These are intentionally not 1:1; don't "fix"
+either one to match the other's granularity — see The Loop below for how
+one delegated phase relates to one compiled task.
+
 | # | 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` |
@@ -112,30 +134,39 @@ paragraph algorithm, and their self-tests.
 
 ## 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. Phase 10
-   (`landing-copywriter`) is delegated once per section, in
-   `landing-sequencer`'s order — each invocation is still "exactly one
-   phase" in the sense this step means: one section, reviewed and locked,
-   before the next invocation starts.
-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. Phase 10 stays unchecked until every section in
-   `landing-sequencer`'s list has locked, not after the first section.
-7. **Repeat**, one delegated phase (or one section, at phase 10) at a
-   time.
-
-Each commit batches exactly one phase's artifact; a wrong phase is fixed
-forward later via the Correction Protocol.
+1. **Run `hedgehog next`.** It emits the task packet for one ready
+   compiled layer (STATUS/WHY NOW/BLOCKED DOWNSTREAM/ALLOWED
+   SCOPE/VERIFICATION) — trust it: `hedgehog next` never emits a layer
+   whose dependency isn't `complete`, so there's no separate gate check to
+   run by hand.
+2. **Map the packet's layer to the fine-grained phases it bundles**, per
+   the table above (`feeling` = phases 1–4, `tokens` = 5–7, `sequence` =
+   8–10, `artifact` = 11–12), and **delegate to that layer's owning
+   agent(s)**, passing 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. Within a bundled layer, run its phases in order and in one
+   continuous pass: phase 10 (`landing-copywriter`) still runs once per
+   section, in `landing-sequencer`'s order, every section reviewed and
+   locked before the next starts, all still inside the one `sequence`
+   task.
+3. Each agent **runs its own self-test** (see that agent's own file for
+   what it checks) before presenting its artifact — necessary, not
+   sufficient. This is a sanity check the agent does for itself; it does
+   not move the task and the agent does not commit its own work.
+4. Once every phase inside the packet's layer has been presented and
+   locked by the user, **run `hedgehog verify <task-id>`.** It checks the
+   touched files against the packet's ALLOWED SCOPE, runs the layer's
+   `VERIFICATION` command, and on a pass writes the commit (the exact
+   Conventional Commit message from the table above) and unlocks the next
+   layer. On a scope violation or a failing check, the task stays
+   `implemented`/`failed` and nothing downstream unlocks — fix it and
+   re-run `hedgehog verify`, don't hand-commit around it.
+5. **Repeat** — `hedgehog next` again for the following layer.
+
+Each `hedgehog verify` call commits exactly one compiled layer's
+artifact; a wrong phase is fixed forward later via the Correction
+Protocol.
 
 ## Friction log
 
@@ -146,12 +177,13 @@ user feedback implied something was wrong even without a direct
 correction (a preference stated once that, read plainly, means an
 earlier phase missed something) — is signal worth keeping past this
 session, separate from the Correction Protocol that fixes it in the
-moment. Append one entry to `.hedgehog/friction.md` (create it if it
-doesn't exist) when that happens: what was tried, what went wrong or was
-implied, why if visible, and the commit/redline it traces to. This is a
-log, not a todo list — don't let it block or slow the loop; append and
-keep moving. `tweaker` reads it once the build reaches its Stop
-Condition.
+moment. Log one entry via `hedgehog friction add "<note>" [--task
+<task-id>]` when that happens: what was tried, what went wrong or was
+implied, why if visible, and the commit/redline it traces to, all in the
+note text; pass `--task` with the compiled layer's task id when the
+friction traces to one. This is a log, not a todo list — don't let it
+block or slow the loop; log and keep moving. `tweaker` reads it (via
+`hedgehog friction list`) once the build reaches its Stop Condition.
 
 ## Correction Protocol
 
@@ -206,7 +238,8 @@ 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–11 has its commit landed.
+- `hedgehog status` shows the `sequence` task `complete` (phases 1–11's
+  commits have landed).
 
 Before `landing-strategist` starts, confirm planning intake's Confirm &
 Lock has held and its commit has landed. If not, stop and ask.
@@ -254,17 +287,18 @@ procedure:
 
 ## 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.
+A build session ends when `hedgehog status` shows the `artifact` task
+`complete` (`landing-builder`'s artifact is committed and every task in
+the chain is done), or when the subject statement or an adjective is
+ambiguous enough that continuing means guessing — ask one question and
+wait.
 
 On the former (a real build completion, not an ambiguity stop), offer a
 fresh-context handoff before doing anything else: tell the user the
-build is complete, that clearing context now costs nothing (`TODO.md`
-and the commit log hold everything), and that a `tweaker` session is the
-right next step for any adjustments — it starts clean, reviews
-`.hedgehog/friction.md` once for a possible discipline-improvement
-suggestion, and takes tweak requests one at a time from there. Don't
-start making tweaks in the current, already-large context; that's what
-the fresh session is for.
+build is complete, that clearing context now costs nothing (the build
+graph and the commit log hold everything), and that a `tweaker` session
+is the right next step for any adjustments — it starts clean, reviews
+the friction log (`hedgehog friction list`) once for a possible
+discipline-improvement suggestion, and takes tweak requests one at a
+time from there. Don't start making tweaks in the current, already-large
+context; that's what the fresh session is for.