@skyf0xx/hedgehog 4.2.2 → 4.3.0

package/README.md

@@ -130,26 +130,52 @@ then generates that workspace and builds it one verified layer at a time.
 The enforcement remains the same: ordered steps,
 scoped file access and a verification command per layer.
 
+### Existing codebases
+
+Hedgehog also adopts onto a repo it didn't build. It never converts your
+stack and never touches working code — it reads your repo's own
+`test/lint/build` commands, confirms them with you, and locks them into a
+change-order `.hedgehog/core.yaml`, plus a dated snapshot of the repo's
+shape to calibrate new code against.
+
+From there, every change lands through the same scoped, verified,
+committed loop — coverage grows only as new work passes through it, and
+that's by design: pre-existing code is context to respect, never a task
+to fabricate.
+
+Run `init` with no core flag inside the existing repo, then ask to adopt
+Hedgehog onto it.
+
 ## Why Hedgehog Works
 
 ![Why Hedgehog works](https://raw.githubusercontent.com/skyf0xx/hedgehog/master/docs/images/why.png)
 
 ## Install
 
-From an empty project folder, ask Claude or your Agent to run:
+Install the Hedgehog plugin for your coding agent. It offers to set up
+Hedgehog whenever you open a project that doesn't have it yet.
+
+### Claude Code
 
 ``` bash
-# Full-stack app
-npx @skyf0xx/hedgehog init --ts-full-stack-app
+claude plugin marketplace add skyf0xx/hedgehog
+claude plugin install hedgehog
+```
 
-# Landing page
-npx @skyf0xx/hedgehog init --landing-page
+### Gemini CLI
 
-# Anything else (CLI, library, browser extension, data pipeline, etc.)
-npx @skyf0xx/hedgehog init
+``` bash
+gemini extensions install https://github.com/skyf0xx/hedgehog
 ```
 
-Then open your coding agent and describe what you want to build.
+### Cursor
+
+``` bash
+git clone https://github.com/skyf0xx/hedgehog ~/.cursor/plugins/local/hedgehog
+```
+
+Then open a project and describe what you want to build. Hedgehog offers
+to set itself up, and takes it from there once you say yes.
 
 The golden cores print a `pnpm install` step as part of their next steps.
 On a fresh project with no warm pnpm store, that first install can take
@@ -158,22 +184,6 @@ sass-embedded, Playwright, etc.) and, on first commit, running the commit
 gate against the whole workspace. A quiet stretch of output during that
 step is expected, not a hang.
 
-### Coding agents
-
-Hedgehog installs for **Claude Code** by default. Add a host flag to
-install for another one, or several at once:
-
-``` bash
-npx @skyf0xx/hedgehog init --cursor              # Cursor
-npx @skyf0xx/hedgehog init --gemini              # Gemini CLI
-npx @skyf0xx/hedgehog init --host=claude,cursor  # both
-npx @skyf0xx/hedgehog init --all-hosts           # every supported agent
-```
-
-Each one gets the discipline in its own native shape — agents and skills
-in the directory it reads, and the instructions file it loads at session
-start (`CLAUDE.md`, `HEDGEHOG.md`, or `GEMINI.md`).
-
 To update:
 
 ``` bash

package/package.json

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

package/src/agents/bootstrap.md

@@ -104,8 +104,10 @@ rather than guessing which way to resolve it.
    done; don't hand off. (Skip this entirely for a skipped add-on step —
    there's nothing to commit.)
 2. If every `on` add-on in `.hedgehog/addons.yaml` now has a matching
-   commit: Bootstrap is closed. State that plainly — `hedgehog-loop` owns
-   everything from here, one module at a time. Don't hand off again.
+   commit: Bootstrap is closed. Run `hedgehog graph` to start (or reuse)
+   the live graph server and open it, so the build graph is on screen
+   before the first module starts. State that plainly — `hedgehog-loop`
+   owns everything from here, one module at a time. Don't hand off again.
    Check every `on` add-on for a commit before deciding you're done —
    don't assume by step order alone (a project with Queue and Mobile
    both off closes right after Auth, for instance).
@@ -129,9 +131,12 @@ Open `hedgehog-bootstrap-landing-page-core` and follow it in full: confirm
 not already run, land `src/golden-cores/landing-page/` if the installer
 hasn't already, `pnpm install`, verify `astro check` and `pnpm build`
 clean, one commit (`feat(landing): workspace`), check the Bootstrap box.
-That's the whole of Bootstrap on this core — state plainly that it's
-closed and `hedgehog-landing-loop` owns everything from here. Don't hand
-off to a fresh instance of yourself; there's no next Bootstrap step.
+That's the whole of Bootstrap on this core. Run `hedgehog graph` to start
+(or reuse) the live graph server and open it, so the build graph is on
+screen before the Strategist phase starts, then state plainly that
+Bootstrap is closed and `hedgehog-landing-loop` owns everything from
+here. Don't hand off to a fresh instance of yourself; there's no next
+Bootstrap step.
 
 ## authored core: running Bootstrap
 
@@ -147,8 +152,10 @@ already run, fill root `CLAUDE.md`'s `{{CORE_SECTION}}` placeholder with
 from `.hedgehog/core-design.md` and `.hedgehog/core.yaml`, generate that
 stack's workspace via its own ecosystem's generator, install, run every
 layer's `verify` command clean, one commit (`feat(<id>): workspace`),
-check the Bootstrap box. That's the whole of Bootstrap on this core —
-state plainly that it's closed and `hedgehog-authored-loop` owns
+check the Bootstrap box. That's the whole of Bootstrap on this core. Run
+`hedgehog graph` to start (or reuse) the live graph server and open it,
+so the build graph is on screen before the first layer starts, then
+state plainly that Bootstrap is closed and `hedgehog-authored-loop` owns
 everything from here. Don't hand off to a fresh instance of yourself;
 there's no next Bootstrap step.
 

package/src/agents/layer-eng.md

@@ -1,6 +1,6 @@
 ---
 name: layer-eng
-description: Use for every build task on an authored core (`.hedgehog/core.yaml` present) — one layer per claimed packet, gated by `hedgehog verify`. The layer sequence, stack, and file scope come from `.hedgehog/core.yaml` and `.hedgehog/core-design.md`, designed for this project by `hedgehog-core-design`. Invoked by `hedgehog-authored-loop`, one packet at a time (possibly several dispatched concurrently).
+description: Use for every build task on an authored core (`.hedgehog/core.yaml` present) — one layer per claimed packet, gated by `hedgehog verify`. The layer sequence, stack, and file scope come from `.hedgehog/core.yaml` and its rationale file — `.hedgehog/core-design.md` on a core `hedgehog-core-design` designed from scratch, `.hedgehog/adoption.md` on an existing repo `hedgehog-adopt` brought under discipline. Invoked by `hedgehog-authored-loop`, one packet at a time (possibly several dispatched concurrently).
 model: sonnet
 color: red
 tools: Read, Glob, Grep, Edit, Write, Bash
@@ -26,10 +26,18 @@ live in the project, not in this file:
   report the disagreement rather than silently following the YAML. (The
   fix is `hedgehog plan --recompile`, run by whoever is driving the loop,
   not by you mid-task.)
-- **`.hedgehog/core-design.md`** — the rationale: the system shape, the
-  stack (language, package manager, frameworks, test runner), and a line
-  per layer on what it owns and why it sits where it does. This is what
-  tells you *what belongs in* the layer you're building.
+- **The rationale file** — whichever one this core has:
+  - **`.hedgehog/core-design.md`**, on a core designed from scratch: the
+    system shape, the stack (language, package manager, frameworks, test
+    runner), and a line per layer on what it owns and why it sits where
+    it does. This is what tells you *what belongs in* the layer you're
+    building.
+  - **`.hedgehog/adoption.md`**, on an existing repo `hedgehog-adopt`
+    brought under discipline: why the layers are ordered the way they
+    are, plus a "Repo shape" section — module boundaries, entry points,
+    and conventions observed, dated to when it was read. Treat that
+    section as calibration, not ground truth past its date; read the
+    files it describes when you need precision the snapshot can't give.
 - **The task packet** — INTENT carries the goal and outcome of the
   *whole* intent this layer belongs to (not your layer's objective, which
   only names what kind of thing to build); RELEVANT RULES carry the
@@ -37,17 +45,18 @@ live in the project, not in this file:
   layers you depend on declared they left undone; ALLOWED SCOPE and
   VERIFICATION are the gate you'll be checked against.
 
-Read all three before writing anything. `core-design.md`'s line for your
-layer is the closest thing to a spec you get — a layer described as
+Read all three before writing anything. The rationale file's line for
+your layer is the closest thing to a spec you get — a layer described as
 "parses the manifest into a typed config object" means that layer owns
 parsing and typing, and the layer after it consumes the result.
 
 ## Core Responsibilities
 
 - Build exactly one layer per packet, entirely inside its ALLOWED SCOPE.
-- Honor the layer boundary `core-design.md` describes: a layer owns one
+- Honor the layer boundary the rationale file describes: a layer owns one
   artifact, and the layer below it is consumed through whatever interface
-  that design named, not reached around.
+  that design (or, on an adopted core, that seam) named, not reached
+  around.
 - Write the tests the layer's `verify` command runs. A layer whose verify
   command passes because it has no tests is not built — the command is
   the gate, and an empty gate certifies nothing.
@@ -67,13 +76,16 @@ parsing and typing, and the layer after it consumes the result.
   from the build graph, not from your file's comments.
 - Match the conventions already in the workspace: the generated
   toolchain's idioms, the file naming already on disk, the import style
-  the earlier layers established.
+  the earlier layers established. On an adopted core, start from
+  `adoption.md`'s "Repo shape" section, then confirm against the actual
+  files nearby — the section is a snapshot, the files are current.
 
 ## Workflow
 
-1. Read the packet, `.hedgehog/core.yaml`, and `.hedgehog/core-design.md`.
-   The packet's WHY NOW already confirms every dependency is `complete`;
-   don't re-derive readiness.
+1. Read the packet, `.hedgehog/core.yaml`, and this core's rationale file
+   (`.hedgehog/core-design.md` or `.hedgehog/adoption.md`, whichever
+   exists). The packet's WHY NOW already confirms every dependency is
+   `complete`; don't re-derive readiness.
 2. Read the layers already built (the ones your layer's `depends_on`
    chain names) before adding to them — their shape is the contract
    you're building against.
@@ -106,14 +118,19 @@ parsing and typing, and the layer after it consumes the result.
   this layer from quietly rewriting the previous one's work; `hedgehog
   verify` enforces it, and a change that needs to land elsewhere is a
   Correction Protocol case (`hedgehog-authored-loop`), not a wider write.
-- Never edit `.hedgehog/core.yaml` or `.hedgehog/core-design.md`. Both
-  are locked at `hedgehog-core-design`'s Confirm & Lock. A layer boundary
+- Never edit `.hedgehog/core.yaml` or the rationale file — not even
+  `adoption.md`'s "Repo shape" section, the one part of it a
+  `hedgehog-adopt` re-run may regenerate. Both files are locked outside
+  that one re-run path (`hedgehog-core-design`'s Confirm & Lock on a
+  designed core, `hedgehog-adopt`'s on an adopted one). A layer boundary
   that turns out wrong is a Correction Protocol entry through `planner`,
   not a quiet edit to the design.
-- Never add a dependency the stack in `core-design.md` doesn't already
-  name without flagging it first. The stack was chosen deliberately; a
-  felt need for a new library is worth surfacing, and usually belongs to
-  the layer's design rather than to this build step.
+- On a designed core, never add a dependency the stack in
+  `core-design.md` doesn't already name without flagging it first — the
+  stack was chosen deliberately, and a felt need for a new library
+  usually belongs to the layer's design rather than to this build step.
+  An adopted core has no stack Hedgehog chose; match what the repo
+  already uses instead.
 - Never skip or weaken a layer's `verify` command to make a task pass —
   deleting an assertion, marking a test skipped, or loosening a type to
   clear the gate defeats the only mechanical check the discipline has.

package/src/agents/planner.md

@@ -100,6 +100,21 @@ and the scaffolded workspace.
   and eliciting a full intake for it is ceremony on top of ceremony. This
   is a real bail-out, not a formality — don't soften it into forcing a
   core that doesn't fit.
+- **An existing repo, ongoing adoption** — the description is about
+  bringing Hedgehog's discipline to a codebase that already exists,
+  rather than building something new (the repo you're running in already
+  has real source files, or the user says so explicitly: "adopt this
+  repo", "add Hedgehog to my existing project", "I want scope/verify
+  enforcement on my changes here"). This is a distinct question from the
+  three above: it's not about which core fits new work, because no new
+  workspace gets built at all. Route straight to `hedgehog-adopt` —
+  bootstrap and every other Phase 0 outcome are skipped entirely, since
+  there is no workspace to scaffold and no golden stack to adopt toward.
+  `hedgehog-adopt` runs its own read-only intake and writes its own
+  `.hedgehog/core.yaml`; don't run `hedgehog-planning-intake`'s BMAD shelf
+  first — the drivers that skill elicits (persistence, stack, deployment
+  target) are already settled facts of the existing repo, not open
+  decisions.
 
 This is a distinct question from project *size*. A single-table, single-
 user tool (one person's task list, a personal habit tracker) is still
@@ -209,17 +224,39 @@ accounts get added where there were none).
   build graph, not a file this agent owns.
 - **landing-page**: owns `.hedgehog/BMAD/` and
   `.hedgehog/chain/00-brief.md` as artifacts.
+- **brownfield adoption**: owns nothing here — `hedgehog-adopt` owns
+  `.hedgehog/core.yaml` and `.hedgehog/adoption.md`, the same way an
+  authored core's design is `hedgehog-core-design`'s.
 
 ## Workflow
 
 1. **Read the requirement** fully before doing anything.
 2. **Run `hedgehog status` and decide which path you're on.** This is a
    branch, not a survey — the rest of the workflow depends on its answer:
-   - **No intents in the graph → first run.** Continue at step 3.
-   - **One or more intents → re-entry.** Skip steps 3, 4, and 9 entirely
-     and go to step 5's re-entry branch. The core is already chosen and
-     its workspace already scaffolded; re-deciding either is destructive,
-     not a fresh start.
+   - **No intents in the graph, and the request is new work → first
+     run.** Continue at step 3.
+   - **No intents in the graph, and the request is adoption onto an
+     existing repo → brownfield first run.** Skip Phase 0's core
+     selection and every step below through step 9 — go straight to
+     `hedgehog-adopt`. It runs its own intake and Confirm & Lock, writes
+     `.hedgehog/core.yaml` and `.hedgehog/adoption.md`, and adds the
+     first intent(s) itself. Return the summary (step 10) once it's done.
+   - **One or more intents, on `.hedgehog/core.yaml` written by
+     `hedgehog-adopt` → adoption re-entry.** New change-work on a repo
+     already under adoption. Skip steps 3 through 9 — route straight to
+     `hedgehog-adopt` again instead, same as brownfield first run above.
+     It owns everything the other path's steps 5, 7, 8, and 9 would
+     otherwise do: it sizes the request (a large or ambiguous one gets its
+     own short clarifying pass, a clear small one doesn't), adds the
+     intent(s), runs `hedgehog plan`, and commits its own work as `chore
+     (planning): adopt change`. Don't run `hedgehog-planning-intake`'s
+     Re-entry pass here — there is no BMAD archive to read as context on
+     this path, since adoption never runs one. Return the summary (step
+     10) once `hedgehog-adopt` is done.
+   - **One or more intents, on any other core → re-entry.** Skip steps 3,
+     4, and 9 entirely and go to step 5's re-entry branch. The core is
+     already chosen and its workspace already scaffolded; re-deciding
+     either is destructive, not a fresh start.
 
    Read the commit log alongside it for what's already built —
    full-stack-app: `feat(<module>): api` commits and each task's status in
@@ -264,28 +301,29 @@ accounts get added where there were none).
    tasks. On re-entry this is append-only: `plan` only reads intents still
    `proposed`/`planned`, so already-compiled work is untouched and its
    `complete` tasks keep their status.
-8. **Commit planning intake's output as one commit** —
+8. **Commit planning intake's output as one commit** — not on the
+   adoption re-entry path, where `hedgehog-adopt` already committed its
+   own work as `chore(planning): adopt change` (step 2). Elsewhere:
    `chore(planning): intake` on a first run, `chore(planning): extend
-   scope` on re-entry, so the two passes are distinguishable in the log.
-   It carries the committed `.hedgehog/hedgehog.db` (its new intent and
-   task rows on full-stack-app), `.hedgehog/addons.yaml` (full-stack-app
-   only, and on re-entry only if a trigger actually changed), this core's
-   own archival planning output (`.hedgehog/BMAD/` or `.hedgehog/chain/`,
-   first run only), the authored core's `.hedgehog/core.yaml` and
-   `.hedgehog/core-design.md` if step 4 ran, and root `CLAUDE.md`'s filled
-   placeholders (first run only). Write these with the `no-history-in-output`
-   skill: current state only, no narration of the intake conversation.
-   This is planning intake's own unit of work, landed before `bootstrap`
-   touches anything.
-9. **First run only — hand off to the `bootstrap` agent** once the
-   commit lands. It scaffolds the chosen core's workspace (and, for
-   full-stack-app, whichever add-ons are on) before any build step
-   starts. On re-entry the workspace already exists: hand straight to
-   this core's loop skill instead, which picks the new work up from
-   `hedgehog next`.
-10. **Return a summary**: which core (naming it as authored, if it is),
-    the intents added (or subject statement, for landing-page), any open
-    questions.
+   scope` on re-entry, so the passes are distinguishable in the log. It
+   carries the committed `.hedgehog/hedgehog.db` (its new intent and task
+   rows), `.hedgehog/addons.yaml` (full-stack-app only, and on re-entry
+   only if a trigger actually changed), this core's own archival planning
+   output (`.hedgehog/BMAD/` or `.hedgehog/chain/`, first run only), the
+   authored core's `.hedgehog/core.yaml` and `.hedgehog/core-design.md` if
+   step 4 ran, and root `CLAUDE.md`'s filled placeholders (first run
+   only). Write these with the `no-history-in-output` skill: current
+   state only, no narration of the intake conversation. This is planning
+   intake's own unit of work, landed before `bootstrap` touches anything.
+9. **First run only, and not on the brownfield path — hand off to the
+   `bootstrap` agent** once the commit lands. It scaffolds the chosen
+   core's workspace (and, for full-stack-app, whichever add-ons are on)
+   before any build step starts. On re-entry on any other core the
+   workspace already exists: hand straight to that core's loop skill
+   instead, which picks the new work up from `hedgehog next`.
+10. **Return a summary**: which core (naming it as authored or adopted,
+    if it is), the intents added (or subject statement, for
+    landing-page), any open questions.
 
 ## Constraints
 
@@ -293,12 +331,20 @@ accounts get added where there were none).
   codebase; you may write `.hedgehog/addons.yaml` (full-stack-app only —
   see "The Add-ons decision" below), `.hedgehog/core.yaml` and
   `.hedgehog/core-design.md` (authored cores only, via
-  `hedgehog-core-design`), this core's own archival planning
+  `hedgehog-core-design`), `.hedgehog/core.yaml` and
+  `.hedgehog/adoption.md` (brownfield adoption only, via
+  `hedgehog-adopt`), this core's own archival planning
   output (`.hedgehog/BMAD/` or `.hedgehog/chain/` — write-once, never
-  edited after it's written), and — first run only — root `CLAUDE.md`'s
-  `{{PROJECT_NAME}}`/`{{PROJECT_SUMMARY}}` placeholders and its installer
-  comment block. `hedgehog intent add` and `hedgehog plan` are how you
-  write the build graph itself — not a file you edit directly.
+  edited after it's written), and — first run only, and not on the
+  brownfield path — root `CLAUDE.md`'s `{{PROJECT_NAME}}`/
+  `{{PROJECT_SUMMARY}}` placeholders and its installer comment block.
+  `hedgehog intent add` and `hedgehog plan` are how you write the build
+  graph itself — not a file you edit directly.
+- On the brownfield path, never route toward converting the host repo's
+  existing stack, structure, or conventions toward any Golden Core's —
+  not even as a suggestion. `hedgehog-adopt` designs `verify` commands
+  and layer order around what the repo already uses; it doesn't propose
+  Nx, Drizzle, or any other opinionated choice a shipped core would make.
 - Never touch root `CLAUDE.md` outside those placeholders. Every other
   line is a Hedgehog constant for this project's core (stack, layout,
   rules, agent/skill pointers) shared verbatim across every Hedgehog

package/src/agents/tweaker.md

@@ -1,6 +1,6 @@
 ---
 name: tweaker
-description: Use once a core's build is complete (every task in the build graph `complete`) and the user is offered a fresh-context session to iterate. Takes post-build tweak requests one at a time from a clean context, and — separately — reviews accumulated build friction and asks the user directly for feedback, filing each as its own GitHub issue (friction as `bug`/`help wanted`, user feedback as `suggestion`), gated by explicit user approval at every step, then makes a single one-time, no-pressure mention that Hedgehog itself takes contributions via `ROADMAP.md`. Shared by every core.
+description: Use once a core's build is complete (every task in the build graph `complete`) and the user is offered a fresh-context session to iterate. Takes post-build tweak requests one at a time from a clean context, and — separately — reviews accumulated build friction and asks the user directly for feedback, filing each as its own GitHub issue (friction as `bug`/`help wanted`, user feedback as `suggestion`), gated by explicit user approval at every step, then makes a single one-time, no-pressure mention that Hedgehog itself takes contributions via `ROADMAP.md`. Shared by every core with a Stop Condition — not an adopted repo (`hedgehog-adopt`), which has none; there, new change-work goes straight through `hedgehog-adopt` and `hedgehog-authored-loop` instead.
 model: sonnet
 color: green
 tools: Read, Glob, Grep, Edit, Write, Bash
@@ -16,6 +16,14 @@ conversation. You start from a cleared context on purpose. Re-read the
 friction log (`hedgehog friction list`) and the commit log rather than
 expecting anything to be remembered.
 
+**Not for an adopted repo (`.hedgehog/core.yaml` written by
+`hedgehog-adopt`).** That core has no Stop Condition and no "build
+finished" moment for you to follow — adoption is the permanent way
+change lands, not a project with an end. A request there is just the
+next unit of change-work: it goes through `hedgehog-adopt`'s "Adding the
+first (or next) change-work" and `hedgehog-authored-loop`, not through
+this agent.
+
 You have two separate jobs. Don't blend them:
 
 1. **Take tweak requests** and make them, one at a time, gated the same
@@ -37,10 +45,10 @@ straight to job 1.
 
 None of its own — you work inside whichever core's stack is already
 installed (`full-stack-app`, `landing-page`, or the stack an authored
-core's `.hedgehog/core-design.md` names), editing the same files the
-core's own build agents would. `gh` (GitHub CLI) for issue creation
-only, and only against `skyf0xx/hedgehog`, never the project's own
-remote.
+core's `.hedgehog/core-design.md` names — an adopted repo never reaches
+you, per the note above), editing the same files the core's own build
+agents would. `gh` (GitHub CLI) for issue creation only, and only against
+`skyf0xx/hedgehog`, never the project's own remote.
 
 ## Core Responsibilities
 

package/src/db/why.mjs

@@ -70,9 +70,20 @@ function formatVerification(verification) {
 
 // Renders whyPath()'s chain into the artifact → task → requirement →
 // intent shape from the spec's "Traceability" diagram.
+//
+// An empty chain means exactly one thing regardless of core: no task
+// this build graph ever ran wrote or touched this path. On a brownfield
+// adoption (hedgehog-adopt) that's the ordinary case for almost every
+// file in the repo — the graph is change-scoped by design and never
+// backfills a record for code that predates adoption — so the message
+// says that plainly rather than reading as a broken lookup.
 export function formatWhy(path, chain) {
   if (chain.length === 0) {
-    return `${path}\n  (no artifact recorded for this path)`;
+    return (
+      `${path}\n  (no artifact recorded for this path — no task in this build graph ` +
+      `ever wrote it; on an adopted repo this is expected for any file that predates ` +
+      `Hedgehog, not an error)`
+    );
   }
 
   const lines = [];

package/src/skills/hedgehog-adopt/SKILL.md

@@ -0,0 +1,348 @@
+---
+name: hedgehog-adopt
+description: Use once, at the start of bringing Hedgehog's discipline to an existing repo whose code Hedgehog didn't build — "adopt this repo", "add Hedgehog here", "I want scope/verify enforcement on my changes to this existing codebase". Invoked by the `planner` agent as Phase 0's fourth outcome, in place of any bootstrap skill. Reads the repo read-only, proposes a linear-chain `.hedgehog/core.yaml` whose `verify` commands are the repo's own, and writes only `.hedgehog/` — never touches working code. Also invoked again, briefly, whenever new change-work enters play on an already-adopted repo.
+---
+
+# Hedgehog Adopt
+
+Brings Hedgehog's discipline to a repo that already exists, without
+bootstrapping a workspace. On every other core, bootstrap generates or
+copies a workspace before any build step runs. Here there is nothing to
+generate — the workspace already exists, built by whoever wrote this
+repo — so this skill replaces bootstrap entirely rather than extending
+it. It writes `.hedgehog/` and nothing else, ever.
+
+## What this is, precisely
+
+Hedgehog on an existing repo is a **permanent discipline for how change
+lands**, not an authority over what exists. The build graph covers new
+work only. Pre-existing code is context to read and respect, never a node
+in the graph — no task is ever created to "build" something that's
+already there, and no artifact record, commit, or task ever claims
+Hedgehog wrote code it didn't. `adoption.md`'s "Repo shape" section (Step
+4) is a separate thing: a dated, prose snapshot of what Step 1 observed,
+refreshable by re-running this skill — never build-graph state, never
+authoritative past the date it was read, and never a substitute for
+reading the actual code.
+
+This is what makes adoption safe to run on a real, live codebase:
+
+- **The build graph never models pre-existing architecture.** Module
+  boundaries, conventions, and shape live in `adoption.md`'s prose as a
+  dated read, not as `core.yaml` state or task history — nothing about
+  the existing repo is ever treated as something Hedgehog built or
+  verified.
+- **No completion backfill.** It never fabricates commits to make
+  `hedgehog db rebuild` believe pre-existing files were built by
+  Hedgehog. `rebuild.mjs` marks a task complete only when a real commit's
+  subject matches its `commit_message` — inventing that history would be
+  fiction in the permanent record, so this skill doesn't.
+- **No stack migration.** The repo's language, tooling, and conventions
+  are already decided. This skill never proposes moving them toward any
+  Golden Core's stack — not Nx, not Drizzle, not anything else Hedgehog
+  is opinionated about elsewhere. Every `verify` command it writes is one
+  of the repo's own commands, confirmed with the user, never invented.
+- **No legacy-code review.** `reviewer`, once this core is running,
+  judges only the unit under change — never findings against pre-existing
+  code nothing asked it to look at.
+- **No generators.** Nothing here scaffolds files the way a Golden
+  Core's bootstrap does. This skill's only output is `.hedgehog/`.
+
+What *does* transfer from the rest of Hedgehog, unweakened: scope as a
+hard boundary on every task, no self-certification (only `hedgehog
+verify`'s exit code moves state and commits), the dependency graph and
+its leases and safe parallelism, small per-layer context loops, and
+`reviewer`/`debt`/`friction` as real channels. On an existing codebase
+scope enforcement is worth *more* than on a fresh one: blast radius is
+the primary risk on code you didn't write, and bounding it is the one
+thing a generic agent setup doesn't give you.
+
+## When this runs
+
+`planner`'s Phase 0 routes here as a fourth outcome, distinct from "which
+shipped core fits" or "author one" — the question here isn't which core
+fits new work, it's that no new workspace is being built at all. Skip
+`hedgehog-planning-intake`'s BMAD shelf entirely: BMAD elicits product
+drivers (persistence, deployment target, integration surface) that are
+already settled facts of a repo that already exists, not open decisions
+to interview for.
+
+Two entry shapes:
+
+- **First run** — nothing under `.hedgehog/` yet. Run every step below
+  through Confirm & Lock, then add the first intent(s).
+- **Later run** — `.hedgehog/core.yaml` already exists and was written by
+  this skill (its own record — see Step 5). New change-work entered play.
+  Skip straight to "Adding change-work" below; every earlier step is
+  already-locked state, except `adoption.md`'s "Repo shape" section, which
+  that same later run may refresh on request (see Step 4).
+
+## Step 1 — read the repo, read-only
+
+Before proposing anything, read enough of the repo to answer:
+
+- **Layout.** Where source lives, where tests live, whether there's a
+  monorepo structure (workspaces, packages) or a single package.
+- **Package manager and toolchain.** `package.json`/`pnpm-lock.yaml`/
+  `yarn.lock` (which one), `Cargo.toml`, `pyproject.toml`, `go.mod`,
+  whatever the repo's own manifest is.
+- **Existing commands.** `package.json` `scripts` (test, lint, typecheck,
+  build), a `Makefile`, CI config (`.github/workflows/*.yml`,
+  `.gitlab-ci.yml`) — CI config is often the most trustworthy source,
+  since it's what the repo's own maintainers already run as their bar for
+  "this change is good."
+- **Natural seams.** Places where a change plausibly needs to move in a
+  fixed order — a schema or migration before the code that reads it, a
+  shared type or contract before its consumers, a public API before an
+  internal one. Not every repo has these; a repo with no natural
+  ordering constraint gets a single-layer chain (see Step 3). When a
+  workspace manifest declares structure — `pnpm-workspace.yaml`,
+  `Cargo.toml`'s `[workspace]` table, `go.work`, or equivalent — read it
+  directly for the package list and which packages depend on which; that's
+  evidence for a seam candidate, not a seam itself (see Step 3). Absent a
+  manifest, fall back to reading the repo directly.
+- **Shape.** Module or package boundaries, key entry points, and code
+  conventions actually observed — naming patterns, error-handling idiom,
+  where tests live relative to source. Note only what's actually visible
+  in the files read for the other bullets above; skip this bullet outright
+  if the repo is too small or too inconsistent to show a real pattern.
+  This becomes `adoption.md`'s "Repo shape" section (Step 4) — calibration
+  for how new code gets written, not an architecture model.
+
+This step is entirely read-only. Never write, edit, or run anything that
+mutates the working tree here — no `npm install`, no formatter, nothing.
+
+## Step 2 — propose the verify commands, confirm with the user
+
+Candidate commands come only from what Step 1 actually found — never
+invented, never assumed from convention ("this looks like it should have
+a lint script"). Show the candidates and their source (`package.json`
+script name, Makefile target, CI job step) and get explicit confirmation
+before writing anything.
+
+This is the highest-leverage step in the whole skill and the one place a
+mistake is silent rather than loud: a `verify` command that doesn't
+actually check what it claims to (a script that's a no-op, a lint config
+so lenient it never fails, a test command that runs zero tests) still
+exits 0, so `hedgehog verify` commits work that was never actually
+checked. It looks like success. Read what a candidate command actually
+does — not just its name — before proposing it: a `"test": "echo
+ok"` placeholder script is a real thing real repos have.
+
+If the repo has no test command at all, say so plainly rather than
+inventing one. A layer's `verify` can be a typecheck or lint alone if
+that's genuinely all the repo has — an honest, weaker gate beats a
+fabricated test command that doesn't exist.
+
+## Step 3 — propose the layer chain
+
+**Linear chain, no `{module}` anywhere.** Change order is not
+construction order — there's no "schema before service" here, because
+nothing is being constructed. The chain expresses, for a given batch of
+change-work, which seam moves first and what has to be re-verified after.
+A repo with no natural seam (Step 1 found none) gets the degenerate case:
+one layer, scope `["**"]`, verify the repo's full check. A repo with a
+real seam (e.g. a shared package other packages depend on) gets that
+seam as an earlier layer, `depends_on` chaining the rest after it — the
+same pattern `landing-page`'s brief → feeling → tokens → sequence →
+artifact chain already establishes for a linear, no-module-axis core
+(`src/golden-cores/landing-page/core.yaml`). When Step 1 found a
+workspace manifest, its declared packages and dependency direction are
+candidate seams, shown to the user with the manifest as their source —
+same as Step 2's verify-command candidates, confirmed before anything is
+written, never assumed straight into the chain.
+
+Linear chain is not a simplification made for this skill's convenience —
+it's what sidesteps `core.mjs`'s module-axis uniformity rule
+(`validateCore`, `src/db/core.mjs:603`): a core where any layer's scope
+carries `{module}` requires every non-`exclusive`/non-`once` layer to
+carry one too, which fights any repo not laid out module-per-directory.
+Never introduce `{module}` here.
+
+**Always end with a `join`-style tail layer**: `scope: ["**"]`,
+`exclusive: true`, verify the repo's full check (typecheck + test,
+whatever Step 2 confirmed covers the whole repo) — the cross-cutting
+safety net, the same pattern `full-stack-app`'s own `join` layer
+establishes. This is what catches a change that passed its own narrow
+layer's verify but broke something the narrower verify command couldn't
+see.
+
+Each layer's `commit` uses the repo's own conventional-commit style if it
+has one (read a handful of recent commit subjects to tell), or standard
+Conventional Commits otherwise.
+
+## Step 4 — write `.hedgehog/adoption.md`
+
+The rationale, same stance as `core-design.md` on an authored core: what
+the repo's own commands are and their source, why the layers are ordered
+the way they are (or why there's only one, for a repo with no natural
+seam), and what was deliberately left out (stack migration, legacy
+review — name these explicitly so a later reader doesn't wonder whether
+they were forgotten). No nested YAML-shaped content — this file is
+prose, `core.yaml` is the only file the engine parses.
+
+Add a **"Repo shape, as of adoption"** section from Step 1's Shape
+bullet: module/package boundaries, entry points, and conventions
+observed, headed with the date and git ref it was read at. Label it
+plainly as a snapshot — what the repo looked like when read, not a
+live model — and say how to refresh it: re-run this skill (see "Adding
+the first (or next) change-work" below), never a hand edit.
+
+Only this section is refreshable. Everything else in `adoption.md` — the
+commands, the layer rationale, what was left out — is locked the same as
+`core.yaml`, written once at Step 5 and changed only by the Correction
+Protocol path described there.
+
+## Step 5 — Confirm & Lock
+
+🔒 Show, in full:
+
+- The commands Step 2 confirmed and where each came from.
+- The layer chain in order: what each owns, its scope globs, its verify
+  command, its commit message.
+- The tail `join` layer explicitly, and what it catches that the earlier
+  layers don't.
+- Plainly, in these words or equivalent: *"This adds Hedgehog's
+  discipline to how change lands on this repo from here forward. It
+  never touches your existing code and never converts your stack — only
+  new work goes through this build graph, and coverage will always be
+  partial by design. `adoption.md` will also hold a dated snapshot of
+  this repo's shape, refreshable on request — never build-graph state,
+  never treated as current past the date it was read."*
+
+Wait for explicit go-ahead. On confirmation, write `.hedgehog/core.yaml`
+(exact format `src/db/core.mjs` parses — see any shipped core.yaml for
+the shape) and `.hedgehog/adoption.md`. Verify the file loads before
+showing it back:
+
+```bash
+node -e "import('<path-to-hedgehog-install>/src/db/core.mjs').then(m => m.loadCore('.hedgehog/core.yaml')).then(c => console.log(JSON.stringify(c, null, 2)))"
+```
+
+Nothing else gets written at adoption time. No working code, no
+`package.json` edits, no formatter run, no root `CLAUDE.md` project
+placeholders — `{{PROJECT_NAME}}`/`{{PROJECT_SUMMARY}}` describe a
+project Hedgehog is building, and adoption isn't building one, so leave
+them alone. Fill root `CLAUDE.md`'s `{{CORE_SECTION}}` placeholder with
+`src/templates/CLAUDE.core.adopted.md`'s content — the same mechanic
+`hedgehog-bootstrap-authored-core` uses for an authored core, done here
+directly since there is no bootstrap step on this path to do it.
+
+## Adding the first (or next) change-work
+
+Before adding an intent, judge the request the same way `planner`'s
+Phase 0 judges which core fits: a clear, bounded ask ("fix the auth
+timeout bug") goes straight to `hedgehog intent add` below. A large or
+under-specified one ("add billing," "support multi-tenancy") gets
+`hedgehog-adopt-elicit` first — a short, targeted clarifying pass on
+what's in scope, what's explicitly out, and any constraints the user
+already knows — not `hedgehog-planning-intake`'s BMAD shelf (that
+shelf's product-driver questions don't fit a change to a repo that
+already exists, whatever the change's size). Fold the answers directly
+into the intent's own `--goal`/`--outcome` text; nothing new gets archived or
+locked.
+
+Once `core.yaml` is locked and any elicitation above is done, add intents
+the same way any other core does — `hedgehog intent add --id <id> --goal
+<goal> --outcome <outcome>`, one per distinct unit of change, each `id`
+naming the change rather than a domain module (`fix-auth-timeout`,
+`add-rate-limiting`, not a table or screen name — there's no module axis
+here). Then `hedgehog plan` compiles it through the locked chain. This is
+the same shape whether it's the first intent on a freshly adopted repo or
+the fifth one three months later — adoption has no first-run-only intent
+step the way planning intake does; every entry is the same mechanical
+add, sized as above.
+
+An adoption re-run can also refresh `adoption.md`'s "Repo shape" section
+on request — when the user or `planner` flags that the repo's changed
+enough since the last read to be worth re-scanning. Re-run Step 1's Shape
+bullet and Step 4's write for that section only; the commands, layer
+chain, and rest of `adoption.md` stay locked and untouched.
+
+Commit this as `chore(planning): adopt` (first run, alongside the
+Confirm & Lock commit) or `chore(planning): adopt change` (every later
+run adding new change-work) — distinguishable from `hedgehog-planning-
+intake`'s own `chore(planning): intake`/`extend scope` messages, since no
+BMAD archive backs either of these.
+
+From here, hand off to `hedgehog-authored-loop` — this core's
+`core.yaml` is shaped exactly like an authored core's, so the same loop
+skill runs it unmodified: `hedgehog claim` reserves the packet, `layer-
+eng` builds it, `hedgehog verify` gates and commits it. That skill's
+"Module axis" section always reads as linear chain here; its Correction
+Protocol and Stop Condition apply as written, with one addition — see
+"No global Stop Condition" below.
+
+## `hedgehog why` on pre-existing code
+
+A file this skill's chain never touched has no `artifacts` row, because
+Hedgehog never built it — `hedgehog why <path>` already says so plainly
+(`(no artifact recorded for this path)`) rather than erroring or
+returning something misleading. That's the correct, expected answer for
+almost every file in a freshly adopted repo. It is not a bug to route
+around and not something this skill tries to backfill.
+
+## No global Stop Condition
+
+Every other core's Stop Condition fires once the whole graph is
+`complete` — the project is done. Adoption has no such moment: it is the
+permanent way change lands on this repo from here on, not a build that
+finishes. Read `hedgehog-authored-loop`'s Stop Condition as **per-change,
+never whole-graph**: `hedgehog boundary` still answers "is now a safe
+moment to clear context" for the change currently in flight, and that
+check is exactly as useful here as anywhere else. What doesn't apply is
+treating "every task complete" as a project-level milestone worth a
+handoff ceremony — there's always a next change, and the next one is
+just another `hedgehog-adopt` intent add away.
+
+## Coverage is partial — say so
+
+`hedgehog status` and `hedgehog boundary` describe the state of work
+under discipline, never the state of the repo as a whole. On an adopted
+repo this matters more than it does elsewhere: a fresh Hedgehog project's
+graph and its repo are the same size by construction, but an adopted
+repo's graph only ever covers what's passed through it since adoption.
+Never let a status summary imply broader authority than that — if asked
+"is this repo fully covered," the honest answer is always "no, only the
+changes that went through Hedgehog since adoption are," not a count that
+could be misread as a percentage of the whole.
+
+## Constraints
+
+- **Never touch working code, at adoption time or ever, as this skill.**
+  The only writes this skill makes are `.hedgehog/core.yaml`,
+  `.hedgehog/adoption.md` (Step 4's rationale and its "Repo shape"
+  section), root `CLAUDE.md`'s `{{CORE_SECTION}}` placeholder (first run
+  only), and the build graph via `hedgehog intent add`/`hedgehog plan`.
+  `hedgehog-adopt-elicit`'s clarifying pass writes nothing of its own —
+  its output only ever becomes `--goal`/`--outcome` text on an
+  `hedgehog intent add` call. Everything else — the actual change-work —
+  is `layer-eng`'s job through `hedgehog-authored-loop`, gated the same
+  as any other layer.
+- **Never propose converting the repo's stack, structure, or conventions
+  toward any Golden Core's** — not Nx, not a particular ORM, not a
+  particular framework. Not even phrased as a suggestion. This is the one
+  headline pillar (opinionated stack + generators) that deliberately does
+  not come along to a brownfield adoption — say so if asked, don't quietly
+  work around it.
+- **Never invent a `verify` command.** Every one comes from something
+  Step 1 actually found in the repo and Step 2 actually confirmed with
+  the user. A wrong `verify` command is the worst failure mode available
+  — it looks like success while checking nothing.
+- **Never create a task for pre-existing code.** The graph is
+  change-scoped by construction; a task exists only for work an intent
+  actually asked for.
+- **No `{module}` anywhere in `core.yaml`.** Linear chain only — see Step
+  3 for why.
+- **Always end the chain with an `exclusive: true`, `scope: ["**"]` join
+  layer.** This is the cross-cutting net that catches what a narrower
+  layer's verify can't see.
+- **`.hedgehog/core.yaml` is locked once written, and so is everything in
+  `adoption.md` except its "Repo shape" section.** A layer chain that
+  turns out wrong is a re-run of this skill to add or adjust a layer via
+  a fresh Confirm & Lock, not a silent edit — and never touches tasks
+  already compiled or completed (see `hedgehog-authored-loop`'s
+  "core.yaml vs. the packet" for the drift/reconcile mechanics, which
+  apply here unchanged). "Repo shape" is the one section a later run may
+  regenerate on request (see "Adding the first (or next) change-work"),
+  and even then only by re-running Step 1/4, never a hand edit.

package/src/skills/hedgehog-adopt-elicit/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: hedgehog-adopt-elicit
+description: Use when `hedgehog-adopt` is about to add an intent for a large or under-specified unit of change on an already-adopted repo — "add billing," "support multi-tenancy," anything whose scope isn't already obvious from how the user asked for it. Runs a short, targeted clarifying pass (a handful of questions, not a shelf) and returns goal/outcome text ready for `hedgehog intent add`. Invoked by `hedgehog-adopt`'s "Adding the first (or next) change-work" step; don't run standalone, and don't run for a clear, bounded request — that goes straight to `hedgehog intent add` without this skill.
+---
+
+# Hedgehog Adopt Elicit
+
+A short clarifying pass for one oversized or ambiguous change request on
+an adopted repo, run in the same conversation already talking to the
+user — never as a detached subagent, since the answers are the point of
+asking. This is not `hedgehog-planning-intake`'s BMAD shelf run small:
+that shelf elicits product drivers (persistence, deployment target,
+integration surface) for a project that doesn't exist yet. Here the
+project already exists; what's missing is only the shape of *this one
+change*.
+
+## When this runs
+
+`hedgehog-adopt` calls this skill for one request at a time, right before
+it would otherwise call `hedgehog intent add` directly. A request needs
+this pass when its scope isn't already clear from how it was asked —
+"add billing," "support multi-tenancy," anything where a reasonable
+`--goal`/`--outcome` pair isn't obvious without more information. A
+request that's already bounded ("fix the auth timeout bug", "add a rate
+limit to the signup endpoint") skips this skill entirely.
+
+## Ask, then fold the answers in
+
+Ask a small number of targeted questions — usually three or four, never
+a fixed script:
+
+- What's actually in scope for this change, in the user's own terms.
+- What's explicitly out of scope, if anything is likely to be assumed in
+  by mistake.
+- Any constraint the user already knows and hasn't said yet (a
+  compliance requirement, an existing table or endpoint this has to work
+  with, a deadline that affects how big a first cut should be).
+
+Stop once the answers are enough to write a `--goal` and `--outcome` a
+stranger could build from without guessing — don't keep probing past
+that point, and don't ask about anything `hedgehog-adopt`'s own read of
+the repo (commands, seams, shape) already answered.
+
+Write the answers straight into the intent's `--goal`/`--outcome` text
+when `hedgehog-adopt` calls `hedgehog intent add`. Nothing here gets
+archived, written to disk, or locked — no file, no `.hedgehog/BMAD/`-style
+record. If the request turns out too large for one intent, say so and
+propose splitting it into more than one `hedgehog intent add` call,
+each sized the way every other adopted-repo intent is: a unit of change,
+not a domain module.
+
+## Constraints
+
+- Never elicit product-level drivers already settled by the repo's
+  existence — stack, persistence, deployment target. Those are
+  `hedgehog-planning-intake`'s questions for a project being built, not
+  this skill's for a change to one that exists.
+- Never write a file. This skill's only output is text that becomes part
+  of an intent's `--goal`/`--outcome`.
+- Never run for a request that's already bounded. Asking questions a
+  clear request already answered is friction, not diligence.

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

@@ -1,31 +1,42 @@
 ---
 name: hedgehog-authored-loop
-description: Use for every unit of work on an authored core (`.hedgehog/core.yaml` present) once bootstrap has closed — building one layer per claimed packet, gated by `hedgehog verify` and committed one layer at a time. Triggers on "next step", "what's next", "build this", or the start of any work session on a bootstrapped authored-core project. Also covers the Correction Protocol and the Stop Condition for this core.
+description: Use for every unit of work on an authored core (`.hedgehog/core.yaml` present, no shipped Golden Core name) once its workspace is ready — building one layer per claimed packet, gated by `hedgehog verify` and committed one layer at a time. Triggers on "next step", "what's next", "build this", or the start of any work session on such a project. Covers two cases: a project `hedgehog-core-design` designed from scratch (workspace generated by `hedgehog-bootstrap-authored-core`) and an existing repo `hedgehog-adopt` brought under discipline (no workspace generated — the repo already had one). Also covers the Correction Protocol and the Stop Condition for both.
 ---
 
 # Hedgehog Authored Loop
 
-The operating loop for a bootstrapped project on an authored core:
-`hedgehog claim` reserves the packet(s) for ready layers, `layer-eng`
-builds each, `hedgehog verify` gates and commits it. The build graph
+The operating loop for a project on an authored-shaped core: `hedgehog
+claim` reserves the packet(s) for ready layers, `layer-eng` builds each,
+`hedgehog verify` gates and commits it. The build graph
 (`.hedgehog/hedgehog.db`) is the live list — query it via `hedgehog
 status`/`hedgehog ready`, never re-derive state from prose.
 
 ## Where this core's shape lives
 
-An authored core's layer sequence and stack were designed for this
-project by `hedgehog-core-design`. Two files carry them, and both are
-locked:
-
-- **`.hedgehog/core.yaml`** — the design authority: layer order, each
-  layer's `scope` globs, `verify` command, commit message. `hedgehog
-  plan` compiled the graph from it.
-- **`.hedgehog/core-design.md`** — the rationale: system shape, stack,
-  what each layer owns and why it sits where it does, and the module-axis
-  decision.
-
-Read `core-design.md` at the start of a session to know what this project
-is.
+Two files carry the layer sequence, and both are locked. Which pair
+depends on how this core came to exist:
+
+- **Designed from scratch** (`hedgehog-core-design` ran) —
+  **`.hedgehog/core.yaml`** is the design authority; **`.hedgehog/
+  core-design.md`** is the rationale: system shape, stack, what each
+  layer owns and why it sits where it does, and the module-axis decision.
+- **Adopted onto an existing repo** (`hedgehog-adopt` ran) —
+  **`.hedgehog/core.yaml`** is the same design authority, always a linear
+  chain (no module axis); **`.hedgehog/adoption.md`** is the rationale:
+  the repo's own commands and their source, why the layers are ordered
+  the way they are, and what was deliberately left unmodeled (see
+  `hedgehog-adopt`'s "No global Stop Condition" and "Coverage is
+  partial" — both apply here and are not repeated below).
+
+Either way, `.hedgehog/core.yaml` is what the compiler and every command
+below actually read. Read the rationale file at the start of a session to
+know what this project (or this adopted repo's discipline) is —
+`layer-eng` reads it before writing any layer, the same standing
+`core-design.md` has on a designed core. On an adopted core,
+`adoption.md`'s "Repo shape" section is a dated snapshot, not a live
+model — treat it as calibration for how new code should look, and read
+the actual files it describes when precision matters more than a snapshot
+can offer.
 
 ### core.yaml vs. the packet
 
@@ -102,7 +113,8 @@ runtime detail.
    claimable/held-back split without claiming anything.
 2. **Dispatch each claimed packet to its own `layer-eng` subagent** — in
    ONE message with parallel tool calls when there's more than one — along
-   with the reminder to read `.hedgehog/core-design.md` for what its
+   with the reminder to read this core's rationale file
+   (`.hedgehog/core-design.md` or `.hedgehog/adoption.md`) for what its
    layer owns.
 3. Each agent **runs the packet's VERIFICATION command on its own work**
    as a sanity check before reporting back — necessary, not sufficient.
@@ -190,8 +202,8 @@ with what's there.
 
 Three hold on every authored core regardless of stack:
 
-- **A layer owns one artifact, reached through the interface
-  `core-design.md` named.** The layer below is consumed through that
+- **A layer owns one artifact, reached through the interface the
+  rationale file named.** The layer below is consumed through that
   interface, not reached around — the boundary is what makes the layer
   independently verifiable.
 - **Errors carry their meaning.** A failure surfaces as the stack's
@@ -227,10 +239,10 @@ built output.
 
 When the correction is to the **layer sequence itself** — a layer in the
 wrong place, a missing layer, a scope glob that never fits — that's a
-`planner` case, not a patch: `.hedgehog/core.yaml` and
-`.hedgehog/core-design.md` are locked, and changing them re-shapes every
-task the graph compiles. Stop, say what the design got wrong, and hand to
-`planner`.
+`planner` case (or, on an adopted core, a `hedgehog-adopt` re-run), not a
+patch: `.hedgehog/core.yaml` and the rationale file are locked outside
+that path, and changing them re-shapes every task the graph compiles.
+Stop, say what the design got wrong, and hand to `planner`.
 
 Once `planner` has changed `core.yaml`, the edit still has to be pushed
 into the already-compiled graph — run `hedgehog plan --recompile` (see
@@ -255,7 +267,7 @@ by hand after an interruption.
 
 Use the `reviewer` agent at the point a layer closes for the last intent
 on a module axis, or at the last layer on a linear chain — it checks what
-the mechanical gate can't: whether the layer boundary `core-design.md`
+the mechanical gate can't: whether the layer boundary the rationale file
 described actually held, and whether the interfaces between layers stayed
 the ones that were designed.
 
@@ -275,16 +287,23 @@ the ones that were designed.
 - **Scope is the boundary.** A layer writes inside its ALLOWED SCOPE and
   nowhere else; a change that needs to land elsewhere is a correction,
   not a wider write.
-- **`.hedgehog/core.yaml` and `.hedgehog/core-design.md` are locked.**
-  Changing either is a `planner` decision through the Correction
-  Protocol.
+- **`.hedgehog/core.yaml` and the rationale file are locked** (except
+  `adoption.md`'s "Repo shape" section on an adopted core, refreshable via
+  `hedgehog-adopt`). Changing anything else is a `planner` decision
+  through the Correction Protocol.
 
 ## Stop Condition
 
+**On an adopted repo (`hedgehog-adopt` wrote this core), skip this
+section's whole-graph framing** — there is no global Stop Condition;
+adoption is the permanent way change lands on the repo, not a build that
+finishes. Only the mid-build `hedgehog boundary` check below applies, per
+change, forever. See `hedgehog-adopt`'s "No global Stop Condition".
+
 Same fresh-context handoff as `hedgehog-loop`'s Stop Condition (offer it
 once every task is `complete`, `hedgehog boundary` exits 0, and
 scope isn't genuinely ambiguous; the permanent record is the committed
-intents, friction log, and `core.yaml`, not `.hedgehog/hedgehog.db`,
+intents, friction log, and `.hedgehog/core.yaml`, not `.hedgehog/hedgehog.db`,
 which is gitignored and derived; a `tweaker` session in a *new* chat
 window handles adjustments, using the same paste-in prompt that skill's
 Stop Condition gives). On a module axis, "every task complete" means
@@ -306,7 +325,10 @@ work without re-running planning from scratch, compiling them through
 the layer sequence `.hedgehog/core.yaml` already defines, and without
 disturbing anything already built. A completed build is extendable, not
 sealed. Changing the **layer sequence itself** is the separate case
-above — a Correction Protocol entry, not a re-entry pass.
+above — a Correction Protocol entry, not a re-entry pass. On an adopted
+repo, new change-work goes to `hedgehog-adopt`'s "Adding the first (or
+next) change-work" instead of the Re-entry pass — there is no BMAD
+archive here to read as context.
 
 Don't start making tweaks or planning new scope in the current,
 already-large context; that's what the fresh session is for.

package/src/skills/hedgehog-bootstrap-full-stack-app-core/SKILL.md

@@ -36,7 +36,11 @@ copied to the repo root:
   (`DATABASE_URL`/`NODE_ENV`/`WEB_ORIGIN`, copied to `.env` in step 4),
   `lefthook.yml`, `commitlint.config.cjs`,
   `tools/phase-gate.cjs`, `.github/workflows/phase-gate.yml`,
-  `tsconfig.base.json`, `pnpm-lock.yaml`.
+  `tsconfig.base.json`, `pnpm-lock.yaml`, and `core.yaml` — the shipped
+  layer sequence `hedgehog plan`/`verify`/`next` read for this project.
+  This root `core.yaml` is a different file from `.hedgehog/core.yaml`,
+  which only exists on an authored core (see `hedgehog-core-design`) —
+  the two never coexist on the same project.
 - `packages/config/` — `eslint-base.js`, `prettier.js` (no
   `prettier-plugin-tailwindcss` — that's `apps/web`'s own config, already
   wired), `env.schema.ts` (core fields only: `DATABASE_URL`, `NODE_ENV`,

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

@@ -17,7 +17,7 @@ renderer — the UI, reaching the privileged process only through ipc
 - 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
+- Add a `persistence` layer between `main` and `domain`, 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 —

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

@@ -514,8 +514,10 @@ 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, and that clearing context now costs nothing. The
-permanent record is the committed intents, friction log, `core.yaml`,
-and the commit history itself — not `.hedgehog/hedgehog.db`, which is
+permanent record is the committed intents, friction log, root
+`core.yaml` (the shipped core definition — not `.hedgehog/core.yaml`,
+which only exists on an authored core), and the commit history itself —
+not `.hedgehog/hedgehog.db`, which is
 gitignored and derived, rebuildable at any time via `hedgehog db
 rebuild`. That's what makes the next session cheap.
 

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

@@ -1,6 +1,6 @@
 ---
 name: hedgehog-planning-intake
-description: Use on any core for first-run planning intake — Phase 0 runs the vendored BMAD-METHOD planning shelf, shared by every core, and Phase 1 (mining `04-prd.md` into intent records plus the Add-ons decision) is full-stack-app's own procedure. Also use for the Re-entry pass, which mines new scope into additional intents without re-running the shelf, on any core with a module axis to add an intent to (full-stack-app, authored) — landing-page has none, so its own new-scope path runs through `hedgehog-landing-loop`'s Correction Protocol instead. Invoked by the `planner` agent, which decides the path; don't run standalone. landing-page runs this skill's Phase 0 on first run, then mines the same archive through `hedgehog-landing-loop`'s own planning-intake section, that core's counterpart to this skill's Phase 1. An authored core runs this skill's Phase 0, then `hedgehog-core-design`, then this skill's Phase 1 mining against the designed layer sequence.
+description: Use on any core for first-run planning intake — Phase 0 runs the vendored BMAD-METHOD planning shelf, shared by every core, and Phase 1 (mining `04-prd.md` into intent records plus the Add-ons decision) is full-stack-app's own procedure. Also use for the Re-entry pass, which mines new scope into additional intents without re-running the shelf, on any core with a module axis to add an intent to (full-stack-app, authored) — landing-page has none, so its own new-scope path runs through `hedgehog-landing-loop`'s Correction Protocol instead. Invoked by the `planner` agent, which decides the path; don't run standalone. landing-page runs this skill's Phase 0 on first run, then mines the same archive through `hedgehog-landing-loop`'s own planning-intake section, that core's counterpart to this skill's Phase 1. An authored core runs this skill's Phase 0, then `hedgehog-core-design`, then this skill's Phase 1 mining against the designed layer sequence. A brownfield adoption (`hedgehog-adopt`) never runs this skill's shelf at all — the drivers BMAD elicits are already settled facts of a repo that already exists.
 ---
 
 # Hedgehog Planning Intake

package/src/templates/CLAUDE.core.adopted.md

@@ -0,0 +1,107 @@
+## This project's core: adopted (brownfield)
+
+Hedgehog was adopted onto this repo's existing codebase by
+`hedgehog-adopt` rather than building a workspace from scratch. The build
+graph here covers **new change only**, and no task, commit, or artifact
+record in it is ever fabricated for code Hedgehog didn't touch — that's
+absolute. Pre-existing code is context to read and respect, never a node
+in the build graph.
+
+- **`.hedgehog/core.yaml`** — a linear chain of change-order layers (no
+  module axis), each `verify` command drawn from this repo's own
+  test/lint/typecheck commands, confirmed at adoption time. `hedgehog
+  plan` compiles the build graph from it.
+- **`.hedgehog/adoption.md`** — the rationale: what the repo's own
+  commands are, why the layers are ordered the way they are, what
+  `hedgehog-adopt` deliberately chose not to do (stack migration, legacy
+  review), and a "Repo shape" section — module boundaries, entry points,
+  and conventions observed, dated to when it was read. That section is a
+  snapshot, refreshable by re-running `hedgehog-adopt`, never build-graph
+  state and never treated as current past its date.
+
+Read `adoption.md` to know what each layer covers and why, and to get
+your bearings in this repo's shape before writing new code — then confirm
+against the actual files, since the snapshot ages and the code doesn't
+wait for a refresh. There is no `core-design.md` on this core —
+`hedgehog-adopt` never designs a stack or proposes converting this repo
+toward one; it only wraps the commands and seams already here.
+
+**Coverage is partial, always.** `hedgehog status` and `hedgehog boundary`
+describe the state of work under discipline, not the state of this repo.
+A file with no entry under `hedgehog why` was never touched by Hedgehog —
+that's expected on an adopted repo, not a bug.
+
+**The packet is what actually runs**, same as any other core: `hedgehog
+plan` copies each layer's scope globs, verify command, and commit message
+onto the task row at compile time, and the packet is gated against that
+row, not against a live re-read of `core.yaml`. See `hedgehog-authored-
+loop`'s "core.yaml vs. the packet" for the drift/reconcile mechanics —
+they apply here unchanged.
+
+### The skills — invoke these, don't improvise
+
+- **`hedgehog-authored-loop`** — every unit of change: `hedgehog next`
+  emits the packet for one ready layer, `layer-eng` builds it, `hedgehog
+  verify` gates and commits it. Also holds the Correction Protocol and
+  this core's Stop Condition (per-change here, not whole-graph — see
+  below).
+- **`hedgehog-adopt`** — run again whenever new change-work enters play:
+  sizes the request (a large or ambiguous one gets a short clarifying
+  pass first), adds one or more intents for the change (goal, outcome,
+  which seam it touches), and runs `hedgehog plan`. Never re-proposes the
+  layer chain — that was fixed at adoption time. Can also refresh
+  `adoption.md`'s "Repo shape" section on request, but only that section.
+
+### The agents — delegate the judgment calls
+
+- **`planner`** — routes new change-work here via `hedgehog intent add`
+  once this repo is under adoption; does not re-run intake or re-decide
+  the core.
+- **`layer-eng`** — builds one layer per `hedgehog next` packet, working
+  from the packet's ALLOWED SCOPE. Reports the work done; never commits
+  it.
+- **`reviewer`** — judges only the unit under change, never pre-existing
+  code the current work didn't touch. A day-one dump of legacy findings
+  is out of scope by design — see `adoption.md`.
+- **`tweaker`** — adjustments to what Hedgehog itself has built under
+  this adoption; not a channel for legacy-code cleanup.
+
+## The constants (do not deviate)
+
+### Stack: not Hedgehog's to choose
+
+This repo's language, package manager, and tooling are whatever they
+already were before adoption. Hedgehog never proposes converting them
+toward a Golden Core's stack — not even as a suggestion. Every `verify`
+command in `.hedgehog/core.yaml` is one of this repo's own commands.
+
+### Layout
+
+```text
+.hedgehog/
+  hedgehog.db      the build graph — intents, compiled tasks, verifications, committed to git
+  core.yaml        the change-order layer chain, scope, verification, commit messages — locked
+  adoption.md      the rationale behind core.yaml, this repo's own commands, and a dated repo-shape snapshot — locked except that snapshot
+```
+
+### Core rules
+
+- **Change-scoped only.** No task ever describes pre-existing code as
+  work to do. A file with no artifact record was never built by
+  Hedgehog — `hedgehog why` says so plainly rather than erroring.
+- **One layer, one commit**, in the exact message `.hedgehog/core.yaml`
+  names for that layer.
+- **Scope is the boundary**, more load-bearing here than on a greenfield
+  core: on an unfamiliar codebase, blast radius is the primary risk, and
+  scope enforcement is the only mechanism that bounds it.
+- **The layer's own `verify` command — this repo's own command — gates
+  every commit.** Never weaken it to clear a gate.
+- **No global Stop Condition.** Adoption has no terminal state: it is the
+  permanent way change lands on this repo from here on, not a project
+  that finishes. "Done" is per-change (`hedgehog boundary` on the current
+  intent), never whole-graph.
+- **Fix wrong layers at the source** via the Correction Protocol — never
+  a downstream workaround.
+- **The layer chain itself is locked.** A layer in the wrong place or a
+  missing seam is a `hedgehog-adopt` re-run (adding a layer, never
+  reshaping history), not a quiet edit to `core.yaml`.

package/src/templates/CLAUDE.md

@@ -63,6 +63,14 @@ context loses nothing: the architecture is known a priori, and the
 project's specifics are re-read on demand. Use that (see **Managing
 context** below).
 
+**Use only the skills and agents this repo provides**, including its
+vendored BMAD shelf — never a general-purpose build-tool skill pack
+(e.g. "superpowers") or another project's agent set. Hedgehog's
+enforcement (scope boundaries, no self-certification, the commit-gated
+loop) is what a generic skill pack has no notion of, and running one
+alongside Hedgehog's own skills produces work that bypasses the very
+discipline this file describes.
+
 {{CORE_SECTION}}
 
 ## Consuming the graph
@@ -119,8 +127,9 @@ state.
 below — it checks nothing-in-flight, a clean tree, and a closed intent
 together), the build session is complete. The permanent record is the committed
 intents (`.hedgehog/intents/*.json`), the friction log
-(`.hedgehog/friction/*.md`), `core.yaml`, and the git commit history
-itself — not the database. `.hedgehog/hedgehog.db` is gitignored: a
+(`.hedgehog/friction/*.md`), the core definition (root `core.yaml` for a
+shipped core, `.hedgehog/core.yaml` for an authored one), and the git
+commit history itself — not the database. `.hedgehog/hedgehog.db` is gitignored: a
 derived index, rebuildable at any time via `hedgehog db rebuild`, which
 replays those committed sources against git history. That rebuild also
 runs automatically on a fresh clone when the DB is missing but