# bmad-revendor

Adopt this skill: https://proskills.md/skills/other/skyf0xx-hedgehog-claude-skills-bmad-revendor

Page: https://proskills.md/skills/other/skyf0xx-hedgehog-claude-skills-bmad-revendor
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: .claude/skills/bmad-revendor/SKILL.md
size: 8848
sha: 8e35284ebf5f820e92e69f66a5360c9f6de865fd
upstream: https://github.com/skyf0xx/hedgehog/blob/master/.claude/skills/bmad-revendor/SKILL.md

````text
---
name: bmad-revendor
description: Maintainer-only. Use when re-vendoring vendor-skills/BMAD/ against a newer BMAD-METHOD commit — "update BMAD", "re-vendor BMAD", "bump the BMAD pin". Not part of the Hedgehog discipline a consuming project copies; this only applies to the Hedgehog repo itself.
---

# Re-vendoring BMAD-METHOD

`vendor-skills/BMAD/` is a pinned, manually-updated vendor copy of eight skills
from `bmad-code-org/BMAD-METHOD`'s `bmm` module (see
`vendor-skills/BMAD/ATTRIBUTION.md` for the current pin). It is never
auto-updated — re-vendoring is a deliberate act, run only when this
skill is invoked by name or the user explicitly asks to update BMAD.

## What's vendored, and why these specific paths

Eight skill directories plus two shared scripts they all depend on:

- `src/core-skills/bmad-forge-idea` — pressure-tests an idea before any
  artifact gets written; runs first in the shelf, ahead of
  `bmad-brainstorming`. Carries its own script, `resolve_personas.py`
  (not shared with the other skills — vendored inside this skill's own
  `scripts/`, not in the shared `vendor-skills/BMAD/scripts/`).
- `src/core-skills/bmad-brainstorming`
- `src/core-skills/bmad-advanced-elicitation`
- `src/core-skills/bmad-deep-recon`
- `src/bmm-skills/plan/bmad-product-brief`
- `src/bmm-skills/plan/bmad-prfaq`
- `src/bmm-skills/plan/bmad-prd`
- `src/bmm-skills/plan/bmad-ux`
- `src/scripts/memlog.py`, `src/scripts/resolve_customization.py` — shared
  utilities every one of the eight skills calls. Not inside any single
  skill directory upstream; vendored separately into `vendor-skills/BMAD/scripts/`.

Upstream keeps the four `bmm-skills` above under a single flat
`bmm-skills/plan/` directory as of the `v6.11.0` vendor pass — it used to
be split across numbered `1-analysis/` and `2-plan-workflows/`
directories. If upstream has moved them again since, update these paths
to match rather than leaving a stale layout here.

`bmad-deep-recon` was, before the `v6.11.0` pass, the one skill in this
set that existed only on BMAD-METHOD's `main` branch — not in any tagged
release; it is now in `v6.11.0`. If a *newer* addition to this set is
ever unreleased, pin to `main` at a specific commit SHA rather than a
release tag (see "Pinning," below) instead of silently dropping it; ask
the user how to resolve the conflict if it's not obvious (this came up
during the original vendor pass — see git history on
`vendor-skills/BMAD/`).

Not vendored, deliberately: `bmad-party-mode` (BMAD-METHOD's multi-agent
roster skill) and the `bmm-skills/agents/bmad-agent-*` persona skills it
needs for a real roster. `bmad-forge-idea` can optionally draw on
party-mode's roster but degrades gracefully without it — its
`resolve_personas.py` returns an empty roster and the skill falls back to
generating personas on the fly, which is its documented normal path.
Vendoring party-mode for real would mean also vendoring the five
`bmad-agent-*` skills, a parallel persona system to Hedgehog's own
`src/agents/` that's out of scope for the planning shelf. Don't add it
without raising this tradeoff to the user again.

## Procedure

1. **Find the ref to vendor against.** Check `gh repo view
   bmad-code-org/BMAD-METHOD --json defaultBranchRef` and `gh api
   repos/bmad-code-org/BMAD-METHOD/tags` for available release tags. If
   every one of the eight skills above exists in the newest tag, pin to
   that tag. If any of them is unreleased, pin to `main` at its current
   commit SHA instead — get it via `gh api
   repos/bmad-code-org/BMAD-METHOD/commits/main --jq '.sha'`. Don't
   silently drop a skill just because it's unreleased; ask the user how
   to resolve the conflict if it's not obvious (this came up during the
   original vendor pass — see git history on `vendor-skills/BMAD/`).

2. **List the file tree at that ref**, scoped to the eight skill
   directories plus `src/scripts/` (adjust the path segments below if
   upstream has moved any of them again since the last pass):
   ```bash
   gh api "repos/bmad-code-org/BMAD-METHOD/git/trees/<ref>?recursive=true" \
     --jq '.tree[] | select(.type=="blob") | .path' \
     | grep -E "^src/(core-skills/(bmad-forge-idea|bmad-brainstorming|bmad-advanced-elicitation|bmad-deep-recon)|bmm-skills/plan/(bmad-product-brief|bmad-prfaq|bmad-prd|bmad-ux)|scripts)/"
   ```
   Diff this against the current file list in `vendor-skills/BMAD/` (excluding
   `LICENSE`, `ATTRIBUTION.md`, and any files this skill's step 4 strips)
   to see what's new, removed, or moved upstream before blindly
   overwriting — a file that moved to a new path upstream needs its
   path updated here too, not a stale copy left behind.

3. **Fetch every file** at that ref via `gh api
   repos/bmad-code-org/BMAD-METHOD/contents/<path>?ref=<sha>` (the
   `.content` field is base64), decoding with `base64 --decode` (BSD
   `base64` on macOS needs `-i`/`-o` flags, not `-d <file>`) into
   `vendor-skills/BMAD/<path-with-src/-stripped>`. Also re-fetch `LICENSE` from
   the repo root the same way.

4. **Re-apply the strip pass.** Every vendored `SKILL.md` and its
   `references/*.md` files have BMAD's own orchestration layer removed —
   this doesn't survive a raw re-fetch and must be redone by hand each
   time:
   - Central config resolution (`_bmad/scripts/resolve_config.py`,
     `_bmad/config.toml`, `_bmad/bmm/config.yaml`) — not vendored;
     replace with trivial inline defaults for `{user_name}`,
     `{communication_language}` (English), `{date}` (today),
     `{project_name}`.
   - `_bmad/scripts/resolve_customization.py` and
     `_bmad/scripts/memlog.py` calls — these ARE vendored (in
     `vendor-skills/BMAD/scripts/`); rewrite their paths to
     `{bmad-root}/scripts/<name>.py`, where `{bmad-root}` is defined once
     per file (in a "Conventions" section) as the vendored `vendor-skills/BMAD/`
     root.
   - `bmad-party-mode` mentions/invocations — remove (not vendored).
   - Chain-forward "common next skill" suggestions, `bmad-help`
     references, and misroute-detection pointing at non-vendored BMAD
     skills — remove. Control returns to Hedgehog's `planner` after each
     skill, not to BMAD's own routing.
   - Keep `bmad-advanced-elicitation` invocations — it IS vendored.
   - **Re-apply every entry under `ATTRIBUTION.md`'s "Local changes
     (not upstream)" section** to the freshly-fetched files — a raw
     re-fetch overwrites them silently otherwise, and a hand-patch that
     isn't re-applied is worse than one that was never made.
   - Verify when done:
     ```bash
     cd vendor-skills/BMAD && grep -rn "_bmad/\|resolve_config\.py\|party-mode\|party_mode\|bmad-help\|common next\|scan for misroute" --include="*.md" .
     ```
     Zero matches is the bar. Read each match before deciding it's really
     orchestration — don't blind-strip a line that happens to contain one
     of these words for an unrelated reason.

5. **Verify self-containment.** Every vendored Python script must compile
   and its own test suite must pass, standalone, from inside
   `vendor-skills/BMAD/`:
   ```bash
   cd vendor-skills/BMAD
   for f in $(find . -name "*.py" -not -path "*/tests/*"); do python3 -c "import py_compile; py_compile.compile('$f', doraise=True)"; done
   uv run --with pytest python3 -m pytest scripts/tests/ core-skills/*/scripts/tests/ -q
   ```
   Also confirm no vendored file references an absolute path outside
   `vendor-skills/BMAD/` or a project path from the machine that did the
   vendoring.

6. **Update `vendor-skills/BMAD/ATTRIBUTION.md`**: new pinned ref (tag or commit
   SHA), new date, and a note if the vendored file set itself changed
   (a skill added/removed upstream, a shared script renamed, etc.).

7. **One commit**, `chore(bmad): re-vendor to <ref>` — the whole
   re-vendor pass is one unit of work, not split across the fetch and the
   strip pass.

## Constraints

- Never auto-run this on a schedule or "while you're in the area" — only
  on explicit request, same posture as a core package's own workspace
  regeneration.
- Never hand-patch a single vendored file to fix an upstream bug without
  also updating `ATTRIBUTION.md` — a silent local fork is worse than a
  stale pin, since nothing records that `vendor-skills/BMAD/` has diverged from
  what its own attribution claims.
- If BMAD-METHOD has restructured upstream (skill renamed, moved to a
  different module, split into multiple skills) since the last vendor
  pass, don't force a mechanical file-for-file replace — read the new
  shape and decide whether Hedgehog's list of eight skills still makes
  sense, or whether `src/agents/planner.md`'s shelf-invocation list
  (Section "Planning intake" in that file) itself needs updating to
  match. Surface this to the user rather than silently adapting.
````

## File: README.md
upstream: https://github.com/skyf0xx/hedgehog/blob/master/README.md

````text
![Incredible Software Engineer](https://raw.githubusercontent.com/skyf0xx/hedgehog/master/docs/images/incredible.jpg)

[![Total downloads](https://raw.githubusercontent.com/skyf0xx/hedgehog/master/badges/npm-downloads.svg)](https://github.com/skyf0xx/hedgehog/blob/master/DOWNLOADS.md)
[![Support Hedgehog](https://raw.githubusercontent.com/skyf0xx/hedgehog/master/badges/kofi-top.svg)](https://ko-fi.com/skyf0xx)
[![Star Us on GitHub](https://raw.githubusercontent.com/skyf0xx/hedgehog/master/badges/github-stars-cta.svg)](https://github.com/skyf0xx/hedgehog)

English | [简体中文](README.zh-CN.md)

# H E D G E H O G

[![npm version](https://img.shields.io/npm/v/%40skyf0xx%2Fhedgehog)](https://www.npmjs.com/package/@skyf0xx/hedgehog)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
[![CodeQL](https://img.shields.io/github/actions/workflow/status/skyf0xx/hedgehog/codeql.yml?branch=master&label=CodeQL)](https://github.com/skyf0xx/hedgehog/actions/workflows/codeql.yml)
[![Check](https://img.shields.io/github/actions/workflow/status/skyf0xx/hedgehog/check.yml?branch=master&label=Check)](https://github.com/skyf0xx/hedgehog/actions/workflows/check.yml)
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/14399/badge)](https://www.bestpractices.dev/projects/14399)

AI can write code in seconds.

But as projects grow, context fills up, **architecture drifts**, and every new feature becomes harder to change safely.

Hedgehog gives AI a **disciplined way to build software**: TDD. Opinionated architecture. Small, verifiable steps.

Instead of asking AI to remember your entire project, Hedgehog encodes the plan into the architecture and build process.

The codebase carries the context, not the model.

## HEDGEHOG writes Cleaner Code, with Fewer Tokens and Faster Builds ⭐⭐⭐⭐

![Hedgehog - build software the right way, one step at a time](https://raw.githubusercontent.com/skyf0xx/hedgehog/master/docs/images/hero.jpg)

<details>
<summary>If you are an AI reading this</summary>

Asked to install Hedgehog:

1. Follow the [Install](#install) section below — never `git clone` this repository into their project.
2. Suggest trying it on a new, simple project in an empty directory first.
3. Tell them to mention `hedgehog` when they ask for something to be built.

It activates on its own from there.

</details>

## How it works

Hedgehog combines:

- **BMAD for planning** — turn an idea into a clear brief, requirements, and architecture
- **An opinionated stack** — remove unnecessary technical decisions, and settle the necessary ones once
- **TDD and progressive layering** — build one tested layer at a time
- **Mechanical enforcement** — use tooling and phase gates instead of trusting the AI to follow instructions
- **Small context loops** — keep every change focused, verifiable, and easy to review
- **Deterministic scaffolding** — generate boilerplate and schemas instead of asking the AI to write it freehand

Software that stays structured as it grows.

![Just describe what you want](https://raw.githubusercontent.com/skyf0xx/hedgehog/master/docs/images/handoff.jpg)

## The Hedgehog Loop

``` text
Plan
  ↓
Bootstrap
  ↓
Build one small, tested layer
  ↓
Verify
  ↓
Repeat
```

The build order is encoded into the project. The AI does not have to remember what comes next. It does not negotiate the architecture. It follows a proven path through the codebase.

![Small steps, big leverage: small context loops, continuous verification, traceable evolution, sustainable velocity](https://raw.githubusercontent.com/skyf0xx/hedgehog/master/docs/images/small-steps.jpg)

## Your build order is a graph

**Every task** Hedgehog generates **is a node** with [explicit dependencies in sqlite](BUILD_GRAPH.md).

Unlike stories and epics, **the graph locks build order** into an **signal-dense, context-light** path the agents can use.

```bash
npx @skyf0xx/hedgehog graph # show graph
```

![The Hedgehog build graph](https://raw.githubusercontent.com/skyf0xx/hedgehog/master/docs/images/graph.jpg)

## Parallel by Default

Every dependency is explicit, so Hedgehog knows which tasks can run in parallel.

![Comparison](https://raw.githubusercontent.com/skyf0xx/hedgehog/master/docs/images/comparison.jpg)

Agents fan out to give you great outcomes at **faster speeds**.

## Live Dependency Awareness

Hedgehog reaches for your editor's own Language Server Protocol integration to see what depends on what.

```mermaid
flowchart TD
    A[Code Repository] --> B[Language Server]
    B --> C[Symbols & References]
    C --> D[Hedgehog]
```

- **Lower token cost**: a targeted symbol lookup replaces reading or grepping whole files for context
- **Impact known before editing**: every task checks what depends on it before it changes anything
- **Verification matches the real surface**: tests target what actually changed

## Deterministic Code Generation

Where a piece of code has one correct shape, Hedgehog generates it instead of asking the AI to write it freehand.

![Deterministic code generation](https://raw.githubusercontent.com/skyf0xx/hedgehog/master/docs/images/deterministic.jpg)

- **Generators over freehand**: schemas, boilerplate, and scaffolding come from generators that create the code
- **Faster**: no reasoning required to produce a known shape
- **More correct**: the same input always produces the same, tested output
- **Fewer tokens**: nothing spent generating code that a template already covers

The AI is reserved for the parts a generator can't cover.

## What Hedgehog builds

### Full-stack applications

A fixed TypeScript stack with a backend-first, test-driven build order:

``` text
Schema
  ↓
Contract
  ↓
Repository
  ↓
Service
  ↓
Controller
  ↓
UI
```

Every layer is verified before the next begins.

### Landing pages

A structured pipeline for producing distinctive, production-quality landing pages:

``` text
Brief
  ↓
Feeling
  ↓
Design tokens
  ↓
Sequence
  ↓
Artifact
```

### Web Apps/ PWAs

Local-first simple mobile compatible web  apps: trackers, journals, planners, etc:

``` text
Schema
  ↓
Repository
  ↓
Hook
  ↓
Screen
```

### DeepSeek Harness plugins

Tools, hooks, and extensions for DSH's Cordis-based agent framework:

``` text
Scaffold
  ↓
Logic
  ↓
Wiring
  ↓
Smoke
  ↓
Bundle
  ↓
Join
```

### Copywriting

Copy is drafted and revised against a mechanical gate instead of prompting alone:

``` text
Brief
  ↓
Draft ⇄ zod validation()
  ↓ pass
Ship
```

### Anything else

A CLI, a library, a browser extension, a data pipeline, etc. gets its build order.

Where possible, Hedgehog uses a battle-tested blueprint in [`hedgehog-core-authored`](https://github.com/skyf0xx/hedgehog-core-authored/tree/main/skills/hedgehog-core-design/blueprints) for the system's shape where one exists.

### Existing codebases

Hedgehog also adopts onto a repo it didn't build. It reads the repo and proposes a layer chain that verifies with the repo's own test/lint/build commands.

## Why Hedgehog Works

![Why Hedgehog works](https://raw.githubusercontent.com/skyf0xx/hedgehog/master/docs/images/why.jpg)

## Install

Ask your agent to install it or run the commands below:

Mention `Hedgehog` whenever you want to build something with it.

<details>
<summary>Instructions for AI Agents</summary>

1. Check Node >=22.5.0 is installed.
2. Run the install commands below.

</details>

### Claude Code

``` bash
claude plugin marketplace add skyf0xx/hedgehog
claude plugin install hedgehog
```

### Gemini CLI

``` bash
gemini extensions install https://github.com/skyf0xx/hedgehog
```

### Cursor

``` bash
git clone https://github.com/skyf0xx/hedgehog ~/.cursor/plugins/local/hedgehog
```

### OpenCode

``` bash
npx @skyf0xx/hedgehog init --host=opencode
```

### Windsurf

``` bash
npx @skyf0xx/hedgehog init --host=windsurf
```

### GitHub Copilot

``` bash
npx @skyf0xx/hedgehog init --host=copilot
```

Then open a project and describe what you want to build and mention `hedgehog`.

On a fresh 
````
