bmad-revendor · git:20260903.6410e6b · 2026-09-03 · sha256 010ed007311b4892

bmad-revendor git:20260903.6410e6bA

Immutable. This exact content is served forever at /api/v1/blob/010ed007311b4892.

---
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.