@skyf0xx/hedgehog 3.0.6 → 3.0.7

package/README.md

@@ -88,7 +88,7 @@ Artifact
 
 ### Anything else
 
-A CLI, a library, a browser extension, a data pipeline, etc. fitting neither shape gets its own build order, designed at intake rather than chosen from a menu.
+A CLI, a library, a browser extension, a data pipeline, etc. fitting neither shape gets its own build order, designed at intake rather than chosen from a menu — starting from a [battle-tested blueprint](src/skills/hedgehog-core-design/blueprints) for the system's shape where one exists.
 
 Run `init` with no core flag: planning intake names the system shape, picks
 the stack, derives the layers, and locks them to `.hedgehog/core.yaml`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyf0xx/hedgehog",
-  "version": "3.0.6",
+  "version": "3.0.7",
   "description": "Install the Hedgehog build discipline (agents + skills) into a repo, for Claude Code, Cursor, or Gemini CLI.",
   "type": "module",
   "repository": {

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

@@ -61,7 +61,12 @@ 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:
+read from `.hedgehog/BMAD/` — never a general preference for variety.
+Prefer an opinionated framework over a bare library wherever the shape
+has one (a web/CLI/RPC framework that fixes where things live, the way
+NestJS does for `full-stack-app`) — an opinionated default is a guardrail
+this discipline doesn't have to write down, and is worth more than the
+popular thin alternative:
 
 | System shape | Default stack | Substitute when |
 |---|---|---|
@@ -72,7 +77,7 @@ read from `.hedgehog/BMAD/` — never a general preference for variety:
 | 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 |
+| Game | TypeScript + PixiJS (2D) or Three.js (3D), Vitest, pnpm — read the dimensionality off the brief; an engine the brief names outright wins over both | a native/console target is explicit → the engine the brief names, per that engine's own language (see the caveat below) |
 | 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
@@ -82,20 +87,72 @@ 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.
 
+Where a substitution lands on a stack whose primary artifacts are binary
+(engine scenes and prefabs, visual-editor projects, compiled design
+files), say so at Confirm & Lock. Scope globs and `verify` commands still
+hold on that stack's text sources, but a layer whose real output is a
+binary file can't be diffed or meaningfully gated, so the enforcement is
+partial in a way the text-source defaults aren't. That's a reason to
+prefer a text-source stack where the brief leaves it open, and a fact the
+user should have before confirming where it doesn't.
+
 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.
+framework(s), test runner — before moving to Step 3. Alongside it, record
+a one-line decision for each of these concerns, whichever apply to the
+shape (a browser extension has no DI story; a data pipeline has no
+routing layer) — each is a place an authored core silently forks into
+per-project convention if left unstated, the way `full-stack-app` never
+has to think about because NestJS already decided:
+
+- **Composition** — how one part of the system gets a dependency it
+  doesn't construct itself (a DI container, explicit constructor passing,
+  a module registry).
+- **Error model** — how a failure crosses a layer boundary (typed
+  exceptions, a `Result`/`Either` return, error codes).
+- **Config and secrets** — where runtime configuration is read from and
+  validated (env vars through a typed schema, a config file, flags).
+- **Entrypoint layout** — what file the runtime starts from and how it
+  wires the layers together.
+
+Every layer's `scope` and `verify` in Step 3 draws from this record.
 
 ## 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:
+layer that another layer imports comes first), by contract second (a
+layer that pins an external interface — a schema, a wire format, a public
+API surface — comes before the layers that build against it, the way
+`full-stack-app` puts `schema` before `contract` before everything else),
+and by risk third (where two layers are still tied, build the one that
+would invalidate the other if it went wrong first).
+
+Start from the blueprint for the chosen system shape — a starting
+sequence, not a fixed one. Each blueprint names where it's safe to add,
+merge, or drop a layer for the project at hand, and the one boundary that
+has to hold whatever else changes; treat those adaptation points as
+expected, not as exceptions. Record which blueprint was used and what
+changed from it in `core-design.md`'s rationale (Step 6).
+
+| System shape | Blueprint |
+|---|---|
+| CLI | [blueprints/cli.md](blueprints/cli.md) |
+| Library / SDK | [blueprints/library-sdk.md](blueprints/library-sdk.md) |
+| Data pipeline | [blueprints/data-pipeline.md](blueprints/data-pipeline.md) |
+| Browser extension | [blueprints/browser-extension.md](blueprints/browser-extension.md) |
+| Desktop app | [blueprints/desktop-app.md](blueprints/desktop-app.md) |
+| Compiler / language tool | [blueprints/compiler-language-tool.md](blueprints/compiler-language-tool.md) |
+| Bot / agent | [blueprints/bot-agent.md](blueprints/bot-agent.md) |
+| Game | [blueprints/game.md](blueprints/game.md) |
+| Infra / deploy tool | [blueprints/infra-deploy-tool.md](blueprints/infra-deploy-tool.md) |
+
+A shape off this table gets no starting sequence — derive layers directly
+from this step's rules and the BMAD brief, and name that in
+`core-design.md` as a judgment call, the same as an off-table stack.
+
+Three rules with teeth, on every blueprint and every derived sequence
+alike:
 
 - **A layer with no executable verification is not a layer.** Fold it
   into its neighbour or drop it. `verify: manually inspect` is not a
@@ -178,6 +235,12 @@ if missed:
   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` must prove the layer's own claim, not just exit clean.** A
+  command that runs but asserts nothing (`tsc --noEmit` alone on a layer
+  whose job is behavior, a `test -s` on a file nothing checks the content
+  of) passes on an empty implementation. Pair typecheck/build commands
+  with a test command that exercises the layer's actual output whenever
+  the layer produces behavior, not just types.
 
 Verify the file loads before showing it back, by calling the loader
 directly:
@@ -196,12 +259,14 @@ forward.
 
 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.
+constraint that justified a substitution), the composition/error/config/
+entrypoint decisions from Step 2, the layer blueprint used and what
+changed from it (or, off-table, that layers were derived directly and
+why), 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
 

package/src/skills/hedgehog-core-design/blueprints/bot-agent.md

@@ -0,0 +1,35 @@
+# Bot / agent blueprint
+
+A starting layer sequence for `hedgehog-core-design` Step 3 on the
+bot/agent system shape. Adapt it for the project at hand — the
+adaptation points below are expected, not exceptions — and record what
+changed in `core-design.md`'s rationale.
+
+```
+contract  — the typed input/output shape of every capability, and the intent type policy decides over
+tools     — each capability's implementation, independently callable and testable with no model in the loop
+policy    — the decision logic: which tool a given input calls, knowing nothing about the delivery surface
+transport — the platform integration (webhook, socket, polling loop) carrying input in and results back out
+```
+
+## Adaptation points
+
+- Merge `transport` into `policy` when the agent runs as a single-process
+  script with no external trigger surface (a CLI-invoked agent, a batch
+  job) — there's no separate integration to isolate.
+- Split `tools` per capability (`tools/{module}`) when the agent's
+  capabilities hit independent external systems with their own auth and
+  failure modes; keep one layer when they share a backend.
+- Add a `memory` layer between `tools` and `policy`, depending on
+  `contract`, when the agent persists state across runs (conversation
+  history, a vector store) — keep it out of `policy` so the decision logic
+  stays testable against a fake memory.
+
+## Boundary that must hold
+
+`policy` calls tools only through the types `contract` defines — never by
+constructing a provider-specific call inline — and never imports
+`transport`. This is what makes the decision logic testable without
+standing up the real delivery surface or a live model: a policy layer
+that reaches into a specific SDK can only be tested against that SDK, and
+that is the layer whose behavior most needs cheap tests.

package/src/skills/hedgehog-core-design/blueprints/browser-extension.md

@@ -0,0 +1,26 @@
+# Browser extension blueprint
+
+A starting layer sequence for `hedgehog-core-design` Step 3 on the
+browser extension system shape. Adapt it for the project at hand — the
+adaptation points below are expected, not exceptions — and record what
+changed in `core-design.md`'s rationale.
+
+```
+messaging  — the typed message contract between background/content-script/popup
+background — the service-worker-side logic (state, alarms, cross-tab coordination)
+content    — page-context logic (DOM reads/writes, page-side event listeners)
+popup      — the extension UI, consumes background/content only through messaging
+```
+
+## Adaptation points
+
+- Drop `popup` entirely for an extension with no browser action UI.
+- Merge `content` into `background` when the extension never injects into
+  page context (a pure background-worker extension).
+
+## Boundary that must hold
+
+`popup` never imports from `background` or `content` directly — every
+cross-context call goes through `messaging`, because a WebExtension's
+contexts are separate JS runtimes and a direct import silently fails at
+runtime rather than at build time.

package/src/skills/hedgehog-core-design/blueprints/cli.md

@@ -0,0 +1,26 @@
+# CLI blueprint
+
+A starting layer sequence for `hedgehog-core-design` Step 3 on the CLI
+system shape. Adapt it for the project at hand — the adaptation points
+below are expected, not exceptions — and record what changed in
+`core-design.md`'s rationale.
+
+```
+command    — argument/flag parsing and dispatch only, one file per subcommand
+domain     — the logic the command triggers, no knowledge of argv or stdout
+io-adapter — anything crossing a real boundary: filesystem, network, a wrapped subprocess
+```
+
+## Adaptation points
+
+- Merge `io-adapter` into `domain` when the tool touches only the local
+  filesystem through the language's standard library — no separate
+  adapter earns its place.
+- Add a `config` layer before `command` when the tool reads a
+  project-level config file in addition to flags.
+
+## Boundary that must hold
+
+Never let `command` reach past `domain` into `io-adapter` directly — that
+collapses the one boundary that makes `domain` testable without a real
+filesystem or network.

package/src/skills/hedgehog-core-design/blueprints/compiler-language-tool.md

@@ -0,0 +1,36 @@
+# Compiler / language tool blueprint
+
+A starting layer sequence for `hedgehog-core-design` Step 3 on the
+compiler/language tool system shape. Adapt it for the project at hand —
+the adaptation points below are expected, not exceptions — and record
+what changed in `core-design.md`'s rationale.
+
+```
+ast       — the node types, spans, and the diagnostic type every later layer reports through
+lexer     — source text to tokens
+parser    — tokens to ast, recovering from errors rather than aborting on the first one
+analysis  — name resolution, type checking, lints: ast in, diagnostics out
+emit      — the output artifact: generated code, a formatted document, a transformed ast
+```
+
+## Adaptation points
+
+- Merge `lexer` into `parser` when the grammar is simple enough that the
+  tokenizer is a handful of functions (a config language, a template
+  syntax) — a separate layer buys nothing.
+- Drop `emit` for a pure analysis tool (a linter, a type checker) whose
+  output is diagnostics rather than an artifact.
+- Drop `analysis` for a pure syntactic tool (a formatter, a
+  syntax-highlighter grammar) that never resolves names or types.
+- Add a `driver` layer after `emit` when the tool has a real CLI or
+  watch-mode surface — it owns argv, file discovery, and diagnostic
+  rendering, keeping the pipeline layers free of both.
+
+## Boundary that must hold
+
+`ast` comes first and everything depends on it, because the node types
+and the span/diagnostic representation are the contract every other layer
+speaks. Layers report errors as diagnostics carrying spans — never by
+printing, and never by aborting on the first failure. A tool that stops
+at the first error can't be used in an editor, and retrofitting error
+recovery after `parser` is written is a rewrite of `parser`.

package/src/skills/hedgehog-core-design/blueprints/data-pipeline.md

@@ -0,0 +1,36 @@
+# Data pipeline blueprint
+
+A starting layer sequence for `hedgehog-core-design` Step 3 on the data
+pipeline system shape. Adapt it for the project at hand — the adaptation
+points below are expected, not exceptions — and record what changed in
+`core-design.md`'s rationale.
+
+```
+schema    — the typed shape of every record crossing a stage boundary, and the validation that enforces it
+extract   — pulling raw records from each source, with no reshaping beyond what the source forces
+transform — the business logic: cleaning, joining, deriving, aggregating, all pure and source-agnostic
+load      — writing results to the destination, plus whatever idempotency/upsert key the destination needs
+schedule  — the orchestration wiring: what runs when, retries, backfill entry points
+```
+
+## Adaptation points
+
+- Merge `schedule` into `load` when the pipeline is invoked externally
+  (cron calling a script, an orchestrator defined outside this repo) —
+  there's no orchestration surface here to build.
+- Split `extract` per source (`extract/{module}`) when the pipeline pulls
+  from several genuinely different systems with independent failure modes
+  and auth; keep one `extract` layer for a single source.
+- Merge `schema` into `extract` when there is one source and one
+  destination and the record shape is small enough to declare in a single
+  file — the types still exist and are still validated, they just don't
+  need a layer of their own.
+
+## Boundary that must hold
+
+`transform` never reads from a source or writes to a destination — it
+takes validated records in and returns records out. This is what lets the
+business logic be tested on fixtures without network, credentials, or a
+warehouse, and it's the boundary that decays first under deadline
+pressure. A transform that "just needs one lookup" from the source is the
+signal to widen `extract`'s output, not to reach across.

package/src/skills/hedgehog-core-design/blueprints/desktop-app.md

@@ -0,0 +1,34 @@
+# Desktop app blueprint
+
+A starting layer sequence for `hedgehog-core-design` Step 3 on the
+desktop app system shape. Adapt it for the project at hand — the
+adaptation points below are expected, not exceptions — and record what
+changed in `core-design.md`'s rationale.
+
+```
+ipc      — the typed contract between the privileged process and the UI process
+main     — privileged-process logic: filesystem, OS integration, windows, auto-update, native menus
+domain   — the app's own logic, running in whichever process owns it, with no window or IPC knowledge
+renderer — the UI, reaching the privileged process only through ipc
+```
+
+## Adaptation points
+
+- Merge `domain` into `main` for an app whose logic is mostly OS
+  orchestration (a launcher, a sync daemon with a thin window) — there's
+  no separable domain to isolate.
+- Add a `persistence` layer between `domain` and `main`, depending on
+  `domain`, when the app owns a real local store (SQLite, a document
+  format) rather than plain preference files.
+- On a native stack (Swift/AppKit, C#/WinUI) the `ipc` layer disappears —
+  there's one process. Keep `domain` separate from `renderer` regardless;
+  that boundary is what survives a platform's UI framework changing.
+
+## Boundary that must hold
+
+`renderer` never touches the filesystem, spawns processes, or reads
+secrets directly — every privileged operation crosses `ipc` to `main`.
+This is a security boundary before it's an architectural one: a renderer
+running remote or user-supplied content with direct privileged access is
+the standard desktop-app vulnerability, and the layer split is what keeps
+the privileged surface small enough to audit.

package/src/skills/hedgehog-core-design/blueprints/game.md

@@ -0,0 +1,35 @@
+# Game blueprint
+
+A starting layer sequence for `hedgehog-core-design` Step 3 on the game
+system shape. Adapt it for the project at hand — the adaptation points
+below are expected, not exceptions — and record what changed in
+`core-design.md`'s rationale.
+
+```
+state   — the world model and the rules that mutate it: pure, deterministic, no rendering or input
+systems — the per-tick logic (movement, collision, ai, scoring) operating on state
+input   — device events to intents, so state never reads a keyboard or gamepad directly
+render  — drawing current state to the canvas/scene graph, reading state and never writing it
+loop    — the tick/frame driver wiring input, systems, and render together
+```
+
+## Adaptation points
+
+- Merge `systems` into `state` for a game whose rules are small enough to
+  live with the model (a puzzle game, a turn-based prototype).
+- Add an `assets` layer before `render`, depending on nothing, when the
+  game has a real content pipeline (sprite atlases, audio banks, level
+  data) rather than a handful of inline files.
+- On an engine that owns the frame loop, `loop` disappears into the
+  engine — keep the other four, mapped onto the engine's own lifecycle
+  hooks, and scope them to the engine's text sources (scripts), since
+  scenes and prefabs are binary and can't be gated.
+
+## Boundary that must hold
+
+`render` reads `state` and never writes it, and `state` never reads input
+devices or draws. A deterministic state layer is what makes a game
+testable at all — you can tick it through a scripted sequence of intents
+and assert the outcome with no window open. It's also what makes replays,
+save files, and any future networking possible; a game whose rules mutate
+during rendering can never get those without a rewrite.

package/src/skills/hedgehog-core-design/blueprints/infra-deploy-tool.md

@@ -0,0 +1,34 @@
+# Infra / deploy tool blueprint
+
+A starting layer sequence for `hedgehog-core-design` Step 3 on the
+infra/deploy tool system shape. Adapt it for the project at hand — the
+adaptation points below are expected, not exceptions — and record what
+changed in `core-design.md`'s rationale.
+
+```
+model    — the typed desired-state the tool works against, parsed and validated from config
+provider — the typed operations against each target system (cloud api, kubernetes, ssh), one per target
+plan     — diffing desired state against observed state into an ordered list of changes, pure and printable
+apply    — executing a plan through providers, with the failure/rollback behavior the tool promises
+cli      — argv, output rendering, and the confirmation gate in front of apply
+```
+
+## Adaptation points
+
+- Merge `plan` into `apply` only for a tool that is genuinely fire-and-forget
+  (a one-shot bootstrap script) — and note that this gives up the dry-run
+  surface, which is the main reason to reach for this shape.
+- Split `provider` per target (`provider/{module}`) when the tool spans
+  several systems with independent auth and failure modes; keep one layer
+  for a single target.
+- Drop `model` as its own layer when desired state comes entirely from
+  flags rather than a config file.
+
+## Boundary that must hold
+
+`plan` computes changes without performing any, and `apply` performs only
+what a plan named. A tool that mutates during planning can't offer a
+trustworthy dry run, and dry run is the safety property this shape exists
+to provide — an infra tool without it is a script that edits production
+with no preview. `plan` must be printable and diffable on its own, with
+no credentials required beyond reading observed state.

package/src/skills/hedgehog-core-design/blueprints/library-sdk.md

@@ -0,0 +1,31 @@
+# Library / SDK blueprint
+
+A starting layer sequence for `hedgehog-core-design` Step 3 on the
+library/SDK system shape. Adapt it for the project at hand — the
+adaptation points below are expected, not exceptions — and record what
+changed in `core-design.md`'s rationale.
+
+```
+core     — the implementation, importable and testable with no knowledge of how it's packaged
+public   — the exported surface: what `index.ts` re-exports, typed and versioned independently of internals
+examples — runnable usage samples that exercise the public surface only, doubling as integration tests
+```
+
+## Adaptation points
+
+- Drop `examples` as its own layer when the consuming ecosystem's
+  convention folds them into the test suite (pytest doctests, Rust
+  `examples/` compiled by `cargo test`) — fold its verify command into
+  `public`'s instead.
+- Split `core` into per-domain sub-layers (`core/{module}`) only when the
+  library has genuinely independent domains a consumer might import
+  separately (a multi-package SDK) — a single-purpose library keeps one
+  `core` layer.
+
+## Boundary that must hold
+
+`public` re-exports from `core`; nothing outside `public` is a supported
+import path. A consumer reaching into `core` directly is the signal this
+boundary was drawn in the wrong place, not a usage error to document
+around — the layer sequence exists so `core` can change shape without
+breaking every consumer, and an internal import defeats that.