hedgehog: Instructions file for Claude Code

Hedgehog (this repo)

Hedgehog is a build discipline for AI-guided software projects. This repo holds the discipline itself as a package of Claude Code agents and skills — the executable payload a consuming project copies in to work Hedgehog-style, and is the source of the method. See README.md for the discipline's stance and rationale.

This repo is the engine: the CLI, the build graph, the host adapters, the core registry, and the agents and skills every core shares. Each core — full-stack-app, pwa-app, landing-page, copywriting, deepseek-harness, authored (a from-scratch design), and adopted (brownfield adoption) — ships as its own npm package holding that core's workspace, agents, skills, and CLAUDE.md section. src/registry/cores.json names them; init fetches the one a project asks for.

Layout

• src/agents/ — the subagent roles every core shares, copied into a consuming project's own .claude/agents/: planner (planning intake, core selection, module scoping), bootstrap (Bootstrap step sequencing), reviewer (phase and layer transition checks, Correction Protocol review), and tweaker (change requests on a project with nothing in flight, sized through hedgehog-daily, and friction-log-driven Hedgehog issue suggestions). A core's own build agents ship in that core's package and install alongside these.
• src/skills/ — the packaged procedures every core shares, copied into a consuming project's own .claude/skills/. A core's own loop, bootstrap, and reference skills ship in that core's package and install alongside these.
  • hedgehog-planning-intake — runs the vendored BMAD-METHOD planning shelf (vendor-skills/BMAD/), shared by every core, and mines its output into scope boundary, domain modules, and the Add-ons decision on full-stack-app. Invoked by planner; landing-page runs this skill's shelf too, then mines the same archive through hedgehog-landing-loop's own planning-intake section instead.
  • hedgehog-daily — the shared triage gate for a change request on a project that already has a build graph and nothing in flight. Reads the installed core's layer sequence, scope globs and verify commands from .hedgehog/core.yaml and routes to one of three exits: a tweak made and committed on the spot (one layer, existing files, and the default under ambiguity), change-work through hedgehog intent add and the core's own loop, or a re-plan. tweaker runs it for job 1's sizing call.
  • conventional-commits — reconstructs step-shaped, conventional commit history when work didn't land cleanly as it went (mainly Correction Protocol cleanups).
  • no-history-in-output — keeps project-facing documents (root CLAUDE.md, .hedgehog/core-design.md, specs, READMEs) written as a current, as-is snapshot rather than a log of edits or decisions, on first generation and every later revision.
  • hedgehog-contributing — forking, branching, and PR-opening procedure for contributing a fix or ROADMAP.md item back to the Hedgehog project itself, as opposed to a consuming project's own code.
  • pr-writing — writing style (brief, info-dense, Simplified Technical English, only verified claims) and the pre-open checklist (CI passing, one change per PR) for a PR, commit message, or review comment in any repo. hedgehog-contributing uses it for Hedgehog's own PRs.
  • filing-issues — the mechanics of getting planned work into GitHub issues: which repo an issue belongs in, when to split a plan into a tracking issue plus sub-issues, which account files it, labels, and acceptance criteria. Defers to pr-writing for how an issue is worded.
• src/registry/ — the core table and the fetcher that acts on it. cores.json names every core, the npm package that ships it, its version range, its install flag (absent on authored and adopted, which are chosen during planning rather than at install time), and the prose planner reads in Phase 0 to pick one; index.mjs loads and resolves it by name or flag. manifest.mjs owns the shape of the hedgehog-core.yaml every core package carries at its root — which agents, skills, vendored shelves, workspace, and CLAUDE.md section that core contributes. fetch.mjs resolves a core package with npm pack, extracts it, and caches the extraction at ~/.hedgehog/cores/<name>/<version>/ so a repeat install needs no network; installed.mjs records which core a project installed, so update refreshes that core's agents and skills from the same package.
• vendor-skills/BMAD/ — BMAD-METHOD (bmad-code-org/BMAD-METHOD, MIT-licensed), vendored in full: the planning shelf hedgehog-planning-intake runs. See vendor-skills/BMAD/ATTRIBUTION.md for the pinned source commit; re-vendoring is a deliberate act via the bmad-revendor skill, not automatic.
• src/templates/ — files a consuming project copies (and then edits or deletes) rather than running as-is: CLAUDE.md, the project-root guide the installer drops in (project-context placeholders the planner fills at planning intake, plus the Hedgehog constants — stack, layout, rules, skill/agent pointers, and context-management guidance). Each core package's own CLAUDE.core.md fills that shell's {{CORE_SECTION}} — at install time when init names a core, or by the matching bootstrap-core skill when init ran naming none and the shell landed with that placeholder still unfilled. {{HOST_DISPATCH}} is filled at install time from the chosen host's DISPATCH.md.
• src/db/ — the SQLite build graph a consuming project's Bootstrap initializes at .hedgehog/hedgehog.db: schema, intents/tasks, plan (compiles intents into the task graph), next/ready/status/claim (what to work on and lease it), verify/gate (close a layer, check a phase transition), friction, debt, decision (inherited context for dependent tasks — a limitation or a design choice, respectively), drift, boundary, why, overrides, reconcile (absorbs work that landed outside the loop, on the user's per-task confirmation, recorded in committed .hedgehog/reconciled/*.json so db rebuild replays it), conflict, commitLock, core, rebuild, graph-server (serves src/templates/graph.html's visualization), and community (the star prompt raised at the first completed intent). Schema changes are versioned: schema.mjs's runMigrations tracks a graph's PRAGMA user_version against CURRENT_SCHEMA_VERSION, applying only the migrations it hasn't seen yet on every writable open, and failing loudly if the graph is newer than this installed CLI knows about; hedgehog db migrate runs the same check on demand and reports what moved. This is the live source of truth every loop skill and its agents query and mutate for what's next and what's done.
• bin/cli.mjs — the hedgehog CLI installed by npx @skyf0xx/hedgehog: init (installer), core record-adopted (lands the adopted core's agents/skills and records them for hedgehog-adopt, which has no init step of its own to call from), and the subcommands (status, next, verify, claim, intent add, plan, friction add/list, …) that read and write src/db/'s build graph.
• src/hosts/ — one entry per coding agent Hedgehog installs into (Claude Code, Cursor, Gemini CLI): where the payload lands, which instructions file that agent loads, and how to emit the agent files when its format differs from the canonical one. capabilities.mjs owns the agent → tool-grant fact for hosts that can't register a per-agent grant; routing.mjs generates the root AGENTS.md index from the agents' and skills' own frontmatter; claude-md-merge.mjs safely merges a core's CLAUDE.md section into a repo's hand-written root instructions file (adoption case). version.mjs owns payload-staleness detection: init and update stamp the version they wrote into .hedgehog/version.json, and that stamp is compared against the newest published release. See ARCHITECTURE.md for the host table and AUTHORING-CORES.md for the package contract a new core must satisfy.