chore: sync v6.5.0 + refactor to installer-based pipeline (v6.5.0.1) - #69
Open
tgorka wants to merge 68 commits into
Open
chore: sync v6.5.0 + refactor to installer-based pipeline (v6.5.0.1)#69tgorka wants to merge 68 commits into
tgorka wants to merge 68 commits into
Conversation
release: v6.0.0-Beta.8.0
release: v6.0.3.3
…ons-1772002853578 Add Claude Code GitHub Workflow
release: v6.0.3.4
release: v6.0.4.2
release: v6.0.4.3
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
release: v6.2.0.0
release: v6.2.0.1
release: v6.2.0.2
release: v6.2.0.3
release: v6.2.0.4
release: v6.2.2.0
Complements clean-orphaned-skills.ts (which removes whole orphan skill directories) by detecting individual files that survive inside skill directories that still exist. For example, when upstream renames or removes a sub-file while keeping the skill's top-level directory, the stale file is never cleaned up because sync only copies/overwrites. Multiple upstream sources can contribute into the same plugin skill directory (e.g., skills/research/ receives content from both core and GDS), so the expected file set is the union across all enabled sources, plus SKILL.md (generated) and plugin-only data. Run: bun run find-orphans # report all sources bun run find-orphans -- --source core # filter report bun run find-orphans:delete # delete orphans Opt-in only — not wired into sync-all, mirroring clean:orphaned's invocation pattern.
Upstream release: https://github.com/bmad-code-org/BMAD-METHOD/releases/tag/v6.3.0 Notable upstream changes pulled in: - bmad-init skill eliminated; config now loads from _bmad/bmm/config.yaml - Dev personas Barry/Quinn/Bob consolidated into Developer (Amelia) — corresponding skill dirs removed (bmad-agent-qa, bmad-agent-quick-flow- solo-dev, bmad-agent-sm) - spec-wip.md singleton replaced by spec-{slug}.md (status field) - Custom content installation removed in favor of marketplace-based install Tooling fix included: clean-orphaned-skills.ts now also checks src/core-skills/ for valid skill names. Upstream renamed src/core/skills/ → src/core-skills/ at v6.2.x but the cleanup script was still pointing at the old path, causing it to wrongly remove core skills that sync had just populated (bmad-brainstorming, bmad-distillator, etc.). Backward-compatible: older paths are still checked as fallbacks. Plugin version bumped to 6.3.0.0 via bun run bump-core.
Upstream releases covered: v1.8.0 through v1.12.2 Latest at https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/releases Notable upstream changes pulled in: - v1.9.0: Skills made self-contained with embedded resources (tea-index.csv) - v1.9.1: Playwright 1.59 compatibility, banner and doc cross-link updates - v1.10+: Continued refinements to testarch workflows (atdd, trace, nfr, ci, framework, automate, test-design, test-review, teach-me-testing) The fetch-latest bump picked v1.12.2 rather than the v1.9.1 referenced in issue PabloLION#58 because several intermediate releases have shipped since the issue was opened. Happy to pin to v1.9.1 via --tag if preferred — this brings the plugin to the actual latest TEA release. Plugin version bumped to 6.3.0.1 via bun run bump-module --source tea.
Upstream releases covered: v0.2.3, v0.2.4, v0.3.0 Latest at https://github.com/bmad-code-org/bmad-module-game-dev-studio/releases Notable upstream changes pulled in: - v0.2.2: All 22 workflows renamed with gds- prefix (applied earlier, inherited here) - v0.2.3: Workflow refs changed from markdown links to bare paths (Opencode compatibility) - v0.2.4: Hardcoded _bmad/ paths replaced with relative / skill: prefixes (future-proofing) - v0.3.0: Latest tag — brings plugin to newest GDS release Structural changes surfaced by find-orphan-files: - gds-create-gdd: steps/ → steps-c/ reorganization — 15 old step files removed - gds-quick-dev: steps/ → steps-c/ reorganization — 6 old step files removed - 3 orphan skill dirs removed by clean:orphaned (create-prd, gds-quick-dev-new-preview, gds-quick-spec) - 5 new game-dev agents regenerated The fetch-latest bump picked v0.3.0 rather than the v0.2.4 referenced in issue PabloLION#56 because v0.3.0 shipped between the issue opening and this sync. Happy to pin to v0.2.4 via --tag if preferred. Plugin version bumped to 6.3.0.2 via bun run bump-module --source gds.
Brings main up to 6.3.0.2 (core v6.3.0, TEA v1.12.2, GDS v0.3.0) so the fork's main branch can be used as a Claude Code marketplace source for testing before upstream PR PabloLION#60 merges.
Strip legacy paths and fallbacks ahead of the v6.5.0 regression-style sync: - clean-orphaned-skills.ts: drop 3-element candidate array (src/core/skills, src/core/workflows) and check only the canonical src/core-skills/ location. - path-rewriter.ts (addCoreSpecialWorkflows): remove try-newDir-then-oldDir fallback. Drop the un-prefixed-name back-compat alias map -- v6.5.0 upstream no longer emits _bmad/core/workflows/<name>/ references (verified with grep, zero hits). - sync-upstream-content.ts: replace the inline ad-hoc version-update block (which only touched .plugin-version, package.json, plugin.json) with a delegation to updateJsonVersionFiles() from bump-utils.ts. This fixes the long-standing marketplace.json drift (was stuck at 6.2.0.4 because the inline block never updated it). - upstream-sources.ts: TODO note on TEA agentRefMappings, to be reviewed after Phase 5 validation against TEA v1.15.1 (which moved the agent to SKILL.md format). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Delete the entire plugins/bmad/skills/, plugins/bmad/_shared/, and plugins/bmad/templates/ trees so the next sync rebuilds them purely from the v6.5.0-era upstream sources. This is the strongest guarantee that no v6.3-era artifact survives the upgrade. Preserved: - plugins/bmad/agents/ (22 files, 100% plugin-owned per pluginOnlyAgents) - plugins/bmad/.claude-plugin/plugin.json (plugin manifest) - plugins/bmad/README.md (marketplace landing readme) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
While running the v6.5.0 sync, two new path-pattern categories surfaced that
the rewriter didn't yet handle:
1. **User-side passthrough aliases** (zero rewrites, no warnings):
- _bmad/scripts/ — resolve_config.py / resolve_customization.py (upstream
tooling the user invokes from their project root)
- _bmad/custom/ — user-authored config.toml overrides
- _bmad/planning/ — user-authored PRD / architecture docs
These reference the user's project tree, not plugin content. Treating them
like _memory (silent passthrough) is the correct semantics.
2. **Un-prefixed core skill aliases** (cross-module refs):
- TEA v1.15.1 still emits {project-root}/_bmad/core/workflows/<un-prefixed-name>/
references (e.g., advanced-elicitation, party-mode). Restore the un-prefixed
fallback alias in addCoreSpecialWorkflows so cross-module callers continue
to resolve until upstream catches up.
After both fixes, sync now reports zero rewrite warnings.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Upstream release: https://github.com/bmad-code-org/bmad-module-game-dev-studio/releases/tag/v0.4.0 Notable upstream changes pulled in: - customize.toml authoring pattern adopted across GDS workflow skills - Various agent SKILL.md frontmatter refreshes - Knowledge / step-file content updates Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Upstream release: https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite/releases/tag/v0.2.0 Notable upstream changes pulled in: - customize.toml authoring pattern adopted for all bmad-cis-* workflow skills - Step-file refreshes across design-thinking / brainstorming / problem-solving suites Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Upstream release: https://github.com/bmad-code-org/bmad-builder/releases/tag/v1.7.0 Notable upstream changes pulled in: - bmad-agent-builder, bmad-module-builder, bmad-workflow-builder, bmad-bmb-setup workflow / step refreshes - customize.toml introduced where applicable Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Upstream release: https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/releases/tag/v1.15.1 Notable upstream changes pulled in: - TEA agent moved from YAML to SKILL.md format (bmad-tea/SKILL.md) - customize.toml adopted for testarch-* workflow skills - Knowledge base, step-file, and checklist refreshes across the test-architecture workflows (atdd, automate, ci, framework, nfr, test-design, test-review, trace) Note: agentRefMappings retained in scripts/lib/upstream-sources.ts for now — TEA still emits some un-prefixed cross-module refs (advanced-elicitation, party-mode) which the path-rewriter handles via the un-prefixed core alias fallback. TODO to drop these mappings once upstream catches up. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Upstream release: https://github.com/bmad-code-org/BMAD-METHOD/releases/tag/v6.5.0 Notable v6.5.0 upstream changes pulled in: - NEW core skill `bmad-customize` (skill-level [agent]/[workflow] override layer, replacing the older central-config approach) - customize.toml authoring pattern adopted across BMM and core skills - module.yaml introduced at module roots - workflow.md / bmad-skill-manifest.yaml deletions across implementation phase (already in skipContentFiles list, transparent to plugin) - Step-file, instruction, and checklist refreshes across most workflows Plugin version anchors updated to v6.5.0.0 across: - .plugin-version - package.json - plugins/bmad/.claude-plugin/plugin.json - .claude-plugin/marketplace.json (was stuck at v6.2.0.4 — fixed by the bump-utils delegation in the earlier sync-upstream-content.ts edit) - README badge Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ugin-only Validate flagged these two GDS agents as having no upstream counterpart in v0.4.0. They are maintained directly in plugins/bmad/agents/ and are not generated from any upstream SKILL.md, so list them in pluginOnlyAgents. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Add an Added/Changed/Removed/Fixed entry covering the v6.5.0 sync, backward-compat removal, marketplace.json fix, and plugin-only agent registrations. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- README.md
• Replace "Deprecation Notice" + "Features" sections with a "How
it's built" preamble (thin wrapper around npx bmad-method) plus a
feature list framed around the 102-skill output.
• Replace the multi-section Agents listing with a single Agent
Personas table — agents are skills now, no separate directory.
• Update Workflow Phase examples to reference the actual flat skill
names (bmad-market-research etc.).
• Update the comparison table: 102 skills (41 BMM + 11 TEA + 4 BMB +
10 CIS + 36 GDS), 21 agent personas (shipped as skills), source-of-
truth = official npx installer, validation strategy simplified.
• Drop "Released" column from upstream version table (would require
git clones).
- AGENTS.md
• Available Scripts: drop generate:*, sync:source, sync-all,
bump-core, bump-module (deleted in Phase 3).
• Upstream Sync section: rewrite for the npx-installer flow.
• Replace 26-row "Current Agents" table (which mixed BMM zombie
personas + CIS skills) with a smaller reference table pointing
readers at the canonical SKILL.md frontmatter for the full list.
• Automation First: restate around `bun run sync` as the single
sync command.
- docs/upstream-sync-design.md, docs/script-pipeline.md
Mark both as historical (pre-v6.5.0+) since the pipeline they
describe no longer exists. Body of each doc kept as archaeological
reference.
- tests/e2e/skill-load.test.ts
• Update skill names to current v6.5.0 prefixed form (bmad-help,
bmad-brainstorming, bmad-customize, bmad-create-prd, …).
• Replace removed init/status tests with bmad-customize coverage.
• Replace "Use the quinn agent" delegation with /bmad:bmad-tea and
/bmad:bmad-agent-pm slash invocations (agents-as-skills).
• Refresh smoke pool to use real v6.5.0 skill slugs.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Detailed CHANGELOG entry covering:
- The architectural shift to npx bmad-method install as the source of
truth (vs the previous multi-source git-clone pipeline).
- The 102-skill output (was 93), with the 9 net-new entries called out
by category (research skills flattened, 6 agent-skills relocated,
gds-document-project added).
- Removal of plugins/bmad/{agents,_shared,templates}/ — agents are
skills now, _shared content moved into per-skill resources/.
- Removal of 16 scripts (~3455 lines net) and the package.json
entries that backed them.
- Migration steps for existing users.
Bump versions: 6.5.0.0 → 6.5.0.1 across .plugin-version,
package.json, plugins/bmad/.claude-plugin/plugin.json,
.claude-plugin/marketplace.json. README badge regenerated.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
chore: re-source plugin from npx bmad-method install (v6.5.0.1)
Bumps core BMAD-METHOD to v6.6.0 and TEA to v1.17.0. BMB / CIS / GDS remain at v1.7.0 / v0.2.0 / v0.4.0 (already at the latest stable GitHub tag). Skill count holds at 102; only 3 upstream skill files changed (the new "Implementation Efficiency" guidance for bmad-create-epics-and-stories). Breaking-change matrix from upstream v6.6.0: - --tools none removed: not used (sync passes --tools claude-code) - project_name moved to [core] in config.toml: end-user install only - legacy bmad-bmm-* / bmad-agent-bmm-* skills auto-removed: none in tree Sync script fixes: - bumpModuleVersions() now reads canonical _bmad/_config/manifest.yaml produced by the v6.6.0 installer. Previous regex against _bmad/<mod>/config.yaml silently no-op'd because that file no longer carries a version: field. Without this fix TEA v1.17.0 would not have been picked up. - Reordered: updateReadmeBadge() runs after bumpModuleVersions() so the README badge and version table reflect freshly-written module versions. Quality gates: typecheck, lint, validate, e2e (6/6 passing) — all green. Idempotent: re-running the sync produces no further diff.
chore: sync upstream BMAD-METHOD v6.6.0 (plugin v6.6.0.0)
- pruneDeprecatedSkills(): drop any skill whose frontmatter description starts with DEPRECATED — the plugin ships only the current surface, no backwards-compatibility forwarders - captureRuntimeTemplate(): copy the installer's _bmad/ runtime tree into plugins/bmad/runtime/_bmad/, templatize the project name as __BMAD_PROJECT_NAME__, strip pruned-shim rows from _config/*.csv, and store nested .gitignore files as dot.gitignore (a real one would exclude sibling template files from this repo's git tree) - plugins/bmad/runtime/ joins the wipe-and-regenerate cycle - validate: no-deprecated-shims invariant + runtime/init asset checks - bump-utils: no spurious version-not-found warnings on idempotent re-sync; sync summary recounts files after pruning - biome: exclude plugins/bmad/skills/ and plugins/bmad/runtime/ entirely (upstream v6.10 ships lintable assets biome would reformat, breaking the byte-for-byte mirror) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Skills resolve per-project files from {project-root}/_bmad/ (module
config, shared scripts like memlog.py / resolve_customization.py —
mandatory since upstream v6.9's canonical memlog) and write artifacts
to configured output folders. The immutable plugin cannot provide
those files, so:
- plugins/bmad/scripts/init.sh: idempotent initializer — fills in
missing _bmad/ files from the runtime template (never overwrites),
substitutes the real project name, restores dot.gitignore →
.gitignore, creates default output folders (_bmad-output/*, docs/,
skills/*-artifacts). Supports --dry-run and a target-dir argument.
- plugins/bmad/commands/init.md: /bmad:init slash command wrapping
the script via ${CLAUDE_PLUGIN_ROOT}
- plugin.json: declare the commands directory
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Regenerated plugins/bmad/skills/ from npx bmad-method@6.10.0 install --tools claude-code. Module bumps: TEA v1.17.0 → v1.19.0, BMB v1.7.0 → v2.1.0, CIS v0.2.0 → v0.2.1, GDS v0.4.0 → v0.6.0. Skill count 102 → 100 (42 BMM + 11 TEA + 4 BMB + 10 CIS + 33 GDS): - new: bmad-prd, bmad-architecture, bmad-ux, bmad-spec, bmad-forge-idea, bmad-dev-auto, bmad-eval-runner, gds-gdd, gds-prd, gds-ux, gds-investigate - retired upstream: bmad-distillator, bmad-create-ux-design, the GDS create/edit/validate trios (consolidated into intent-based skills) - pruned deprecated shims (not shipped): bmad-create-prd, bmad-edit-prd, bmad-validate-prd, bmad-create-architecture Also captures the installer's _bmad/ runtime tree as plugins/bmad/runtime/_bmad/ (40 files) for /bmad:init, and adds the test:unit script to package.json alongside the version bump. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- tests/plugin-tree.test.ts: no deprecated shims survive, retired skills absent, v6.7–v6.10 surface present, runtime template complete and templatized, manifest hygiene, plugin manifest wiring - tests/init-script.test.ts: full structure creation, project-name substitution, idempotency (never overwrites), --dry-run - e2e smoke pool: bmad-create-prd → bmad-prd, bmad-create-architecture → bmad-architecture; added bmad-spec and bmad-forge-idea - CI: run bun run validate and bun run test:unit (e2e still needs the claude CLI and stays manual) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- README: 100-skill breakdown, intent-based planning skills, Step 3 /bmad:init walkthrough, documented divergences from raw installer output (shim pruning + runtime template), refreshed comparison table - CHANGELOG: 6.10.0.0 entry with upstream breaking-change matrix (v6.7 → v6.10) - AGENTS.md: sync pipeline steps (prune + runtime capture), test:unit, never-hand-edit warning for generated trees - docs/bmad-ecosystem.md: v6.10.0.0 module inventory (21 personas / 100 skills), removed references to the deleted pre-6.5 sync layer - docs/manual-testing.md: rewritten for the current skill surface and /bmad:init (was describing the pre-v6.5 instructions.md layout) - docs/versioning.md: patch counter starts at .0 (matches practice) - plugins/bmad/README.md: rewritten — still listed the pre-v6.3 agent roster (bmad-master, sm, quick-flow-solo-dev) and retired skills Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
bmad-loop (upstream v6.10's successor to bmad-automator) is a Python
orchestrator tool, not an npx-installer module — its Claude Code
skills ship inside its own repo under src/bmad_loop/data/skills/
(BMAD module code bmad-loop). Skill count 100 → 103.
- sync: new syncLoopSkills() step clones bmad-code-org/bmad-loop at
the tag pinned in .upstream-versions/loop.json (--loop-tag to
override) and copies bmad-loop-{setup,resolve,sweep} into the
plugin skill tree; loop skills go through the same deprecation
prune as installer output
- upstream-sources: 'loop' registered → version validation, README
version table and badge row generated automatically
- sync-upstream.yml: check-loop job watches bmad-loop releases weekly
- tests: bmad-loop-* skills added to the expected current surface
- docs: README (6 modules / 103 skills, third divergence note),
CHANGELOG, AGENTS.md sync steps, bmad-ecosystem inventory, plugin
README (bmad-loop-setup quick start)
The orchestrator tool itself is installed per-project by
/bmad:bmad-loop-setup (uv tool install from the bmad-loop repo);
core's bmad-dev-auto remains the inner dev primitive it drives.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
chore: sync upstream BMAD-METHOD v6.6.0 → v6.10.0 (plugin v6.10.0.0)
Core v6.11.0 moves bmad-loop into the installer registry (`bmad-modules.yaml`, `code: bmad-loop`) and renames the deprecation marker, which broke two silent assumptions in the sync: - `pruneDeprecatedSkills()` matched a literal uppercase `DEPRECATED` description. v6.11.0 writes `'Deprecated — forwards to …'`, so the prune matched zero skills while still reporting success. Rather than fix the predicate, the prune is removed: upstream's own `v6-shims/README.md` states external module repos still invoke those IDs and 'removal rides the v7 cut — never a 6.x minor'. - `syncLoopSkills()` cloned bmad-loop at a pinned tag and copied over the installer's own output. Deleted; `bmad-loop` joins `--modules`. New capability: custom sources. A real BMad module absent from the official registry (bmad-manticore) is cloned at a pinned tag and handed to the installer as a local `--custom-source` path, then captured into its own sibling plugin. Local path rather than URL keeps the run reproducible — `--custom-source <url>` resolves the moving default branch. Each custom source gets its own installer run so a plugin's runtime template only advertises the modules that plugin ships. Also templatizes `user_name` and install timestamps (the vendored tree shipped the literal `Dev`), vendors the upstream module-authoring template, replaces six copy-pasted release-watcher jobs with one matrix driven by the source registry, retires the resolved-workaround watcher, and points the badge base URL at this fork rather than its parent. Review hardening (findings from two adversarial review passes): - `.plugin-version` is written LAST, after the three JSON manifests. Advancing it first made any interruption unrecoverable: the re-run reads the already-advanced value, `updateJsonVersionFiles` takes its no-op branch, and the manifests stay behind forever — publishing new content under the old version, which no installed user is offered. The patch counter is now preserved when core is unchanged, so a re-sync cannot walk a published 6.11.0.1 back to 6.11.0.0. - Custom sources are fetched by `refs/tags/<tag>` into a detached HEAD rather than `git clone --branch <tag>`, which resolves branches before tags and so can be shadowed by a same-named branch. The resolved SHA is logged, and the vendored template's SHA is verified against its pin. - `.upstream-versions/<id>.json` for a custom source is written after its content is captured, not right after the clone. The old order let a mid-run failure leave the repo advertising a version it does not ship, with validate green. - Sibling plugins now get their own filtered `_config/skill-manifest.csv`, so the skill-surface gate covers them too; previously a partial upstream prefix rename would have shipped a silent subset past a non-empty `skills/` check. - Help rows naming a skill the installer did not install are dropped at capture. manticore v1.0.1 declares mc-audio, whose frontmatter is invalid YAML, so the installer rejects it — shipping the row made bmad-help offer and route to a skill that is not there. - `rehashFilesManifest()` asserts the manifest header and always logs its count. Its row guard pins the column count and hash width, so an upstream schema change would have made every row skip at once and silently restored the non-idempotency it exists to remove. - `flagValue()` accepts `--flag=value` and rejects a value starting with `--`. `--tag=v6.12.0` used to be ignored, silently syncing the pinned version instead and producing a tree every gate passes. - All throwaway checkouts moved under `.upstream-clones/`, so one .gitignore line covers them. The per-clone literals meant a second CUSTOM_SOURCES entry became committable. Deliberately not widened to `.upstream-*`, which would swallow `.upstream-versions/`. - The release watcher no longer depends on an issue tracker. This repo is a fork, forks ship with issues disabled, and `gh issue list` exits 1 in that state — under `set -euo pipefail` every drifted source would have turned the job red and filed nothing. Drift now always lands in the job summary plus a workflow warning; an issue is filed only if the tracker is enabled, deduped on exact title rather than GitHub's relevance search. The matrix step gained `set -euo pipefail` and fails on an empty matrix instead of instantiating zero jobs and reporting success.
Full from-scratch regeneration — `bun run sync -- --tag v6.11.0` wipes
plugins/bmad/{skills,runtime} and rebuilds them from a fresh installer
run, so every file is byte-identical to what `npx bmad-method install`
produces. 110 skills (was 103), 1388 files.
Skill-surface delta vs v6.10.0:
- Added: bmad-build, bmad-build-auto (replace bmad-quick-dev /
bmad-dev-auto), bmad-review (one skill, many lenses), bmad-deep-recon
(market + domain + technical research consolidated),
bmad-project-context (replaces bmad-document-project and
bmad-generate-project-context).
- Removed upstream: bmad-index-docs, bmad-shard-doc,
bmad-check-implementation-readiness (folded into bmad-sprint-planning's
readiness gate), bmad-agent-tech-writer (Paige retired).
- The 20 v6 deprecation shims now ship. See the pipeline commit: upstream
states external module repos still invoke those IDs in 6.x.
Runtime template additions: _bmad/render/ (content-addressed skill
snapshots written by render_skill.py), _bmad/scripts/render_skill.py and
config_utils.py, _bmad/bmad-loop/ (loop is a registry module now), and
the two v6-shims/README.md stubs. `user_name` and the install
timestamps are templatized — the v6.10 tree shipped a literal `Dev`.
Module versions, all read back from the installer's own
_bmad/_config/manifest.yaml rather than guessed: bmb v2.1.0 -> v2.2.1,
tea v1.19.0 -> v1.23.3, bmad-loop v0.8.0 -> v0.11.0, cis -> v0.3.1,
gds -> v0.7.1. The v6.10 sync had written cis.json and gds.json
transposed (manifest recorded cis v0.2.1 / gds v0.6.0); both are now
correct, so CIS is not the downgrade the numbers suggest.
Gates land with the content they measure: `bun run validate` now
compares plugins/bmad/skills/ against the installer's own
_config/skill-manifest.csv in both directions, replacing the
"no DEPRECATED shims" rule that v6.11's sentence-case rename had turned
into a check that passed while measuring nothing. It also rejects any
vendored file carrying the install-dir name, a non-placeholder
user_name, or a live nested .gitignore, and requires registry sources to
pin a v-prefixed tag. The e2e smoke pool drops the retired and shimmed
skills for their v6.11 replacements.
Gate hardening from review: the templatization check now asserts every
known machine-specific key equals its placeholder (user_name,
project_name, installDate, lastUpdated) AND, independently of those
keys, scans config/manifest files for a surviving ISO timestamp or this
operator's identity. The key-based half shares a predicate with the sync
it audits and therefore cannot catch the sync silently missing a renamed
key; the value-based half can, which is the exact failure mode this
rebuild exists to fix. The skill-surface check runs per published plugin
and additionally resolves every module-help row to a shipped skill.
checkVersion now requires all four version anchors to agree — an
interrupted bump leaves .plugin-version ahead of three manifests that
still agree with each other, so nothing previously noticed.
Each gate mutation-verified: a leaked installDate, a leaked
project_name, the operator's name under a renamed key, a disagreeing
package.json version, and a help row naming a non-existent skill are all
caught.
The identity half of the templatization scan matches only where the
operator's name is the WHOLE value of a `key: value` line — any key, so
a renamed one is still caught, but prose is not. A bare word search
cried wolf on CI: GitHub Actions runs as `runner`, and `bmad-eval-runner`
is a real skill id that appears throughout the manifests.
…the module template The marketplace now carries two plugins. **bmad-manticore** (upstream v1.0.1, 15 skills) is a real BMad module — it ships skills/module.yaml with code `manticore` — but is absent from upstream's official `bmad-modules.yaml` registry, so the sync installs it through `--custom-source` from a tag-pinned local clone. It is a separate plugin rather than 15 more skills inside the aggregate because its prerequisites (ffmpeg, node/npx, uv, Python >=3.11, multi-GB model caches) are irrelevant to most users, because 14 of its 15 skills fail closed until `mc-setup` has written `[modules.manticore]` into _bmad/custom/config.toml, and because mc-agent is an always-on persona that would compete for activation with the aggregate's agents. It stays usable: the only core runtime it needs (_bmad/scripts/resolve_config.py, _bmad/custom/) is materialised by /bmad:init from the bmad plugin. Two upstream defects at v1.0.1 are documented, not patched: mc-audio's frontmatter is invalid YAML (unquoted scalar containing ': ') so the installer drops it, 16 declared skills installing as 15; and mc-agent is absent from the core agent roster. Upstream main fixes the first but marks both 3.0.0 and 3.1.0 '- Unreleased' and carries no tag above v1.0.1, so this bundle stays on the tag. **bmad-module-template** is vendored to plugins/bmad/templates/, NOT published. Its own manifest points at ./skills/my-skill, a directory that exists in no upstream ref — an early .gitignore rule (`.*/skills`) swallowed the scaffold. Publishing it would put a dead `my-module` entry in front of users; vendoring gives module authors the scaffold next to bmad-module-builder. The gates for both additions land with them: validate now requires every plugins/<dir> to be published in the marketplace (a marketplace install is a git clone of the whole repo, so an unlisted directory is dead weight in it) and every declared plugin's plugin.json to agree with its entry; and it requires the vendored template's README. The plugin-tree tests assert the two-plugin marketplace, manticore's mc-* skills plus its module-help.csv, and that the module template is present with a dot.gitignore yet absent from the plugins array. Review hardening: the manticore plugin now carries its own filtered _config/skill-manifest.csv, so the skill-surface gate covers it in both directions rather than only checking that skills/ is non-empty — a partial upstream prefix rename would otherwise ship a silent subset. The mc-audio help row is dropped at capture: upstream declares the skill but its frontmatter is invalid YAML, so the installer never installs it, and shipping the row made bmad-help offer and route to something absent. A new gate resolves every module-help row to a shipped skill so this cannot recur. The plugin.json skills/commands assertions were replaced by the entry points they were standing in for; those manifest keys are no-ops for this layout, so pinning them failed on valid cleanups and passed on nothing real.
- Substitutes the two placeholders the sync added alongside the project name: `__BMAD_USER_NAME__` (from `git config user.name`, falling back to $USER) and `__BMAD_INSTALL_DATE__`. The v6.10 template shipped whoever last ran the sync as the literal user name. - `--with-plugin <name>` registers a sibling plugin from the same marketplace: materializes its `_bmad/<module>/` metadata and merges its help rows into `_bmad/_config/bmad-help.csv` so `bmad-help` lists them. Opt-in, never inferred from the directory listing — a marketplace install is a git clone of the whole repo, so a sibling's files are present whether or not the plugin is enabled. /bmad:init decides from its own loaded skill list. The merge is row-level and idempotent, and pads a missing trailing newline first: the installer writes bmad-help.csv without one, so a naive append glued the first merged row onto the last existing row and produced a 12-column line plus a duplicate on the next run. - Warns (never fails) when `uv` is absent. bmad-build and bmad-build-auto carry no workflow logic in v6.11 — they run `uv run _bmad/scripts/render_skill.py` and HALT without it. - Argument parsing moved to a shift loop; unknown options are now an error instead of being silently treated as the target directory. Tests land with the behaviour: --with-plugin merge idempotency and CSV column integrity after the merge, no-merge-without-the-flag, user-name and install-date substitution with no placeholder surviving, and both error paths. Removing the bmad-help.csv trailing-newline pad fails the merge-idempotency test. Review hardening — the delivery layer was the weakest part of the stack: - **/bmad:init can now upgrade a repo, not only seed one.** `copy_missing` skipped every existing path, so a repo initialized under v6.10 kept its stale shared scripts, a help catalog naming eight skills v6.11 removed while omitting 34 it ships, and the literal `user_name = "Dev"` leak this whole stack exists to delete — making "safe to re-run after a plugin update" false in exactly the case it was written for. `_bmad/custom/**` stays user-owned and untouched; everything else is installer-managed (upstream's own header calls it "Regenerated on every install — treat as read-only") and is refreshed when it differs from the template. Verified end to end against a real v6.10-initialized repo: 7 created, 17 refreshed, the Dev leak gone, bmad-build present. - **Substituted values are sanitized for their destination.** They land inside TOML strings and unquoted YAML scalars, so a git identity like `He said "hi": C:\Users\tg #1` made config.user.toml unparseable by tomllib and config.yaml unparseable by PyYAML — taking down resolve_config.py, which every skill calls. A literal newline aborted the run mid-materialization, unrecoverably. - **The date a repo was initialized is preserved across refreshes.** Restamping made every re-run report a refresh of all twelve date-bearing files. - **Sibling `_config/` is not materialized.** The sibling's filtered skill-manifest exists for this repo's gates; copying it replaced the user's 110-row aggregate manifest with 15 rows. - **Sibling help rows cannot zombie.** The catalog is reassembled from the pristine template plus each registered sibling's current rows, so a point release that reworded or removed a skill cannot leave the old version behind. Naming the same sibling twice merges it once. - **--dry-run no longer reports work it did not do** ("Done: 39 created" with an empty directory). Every one mutation-verified: identity sanitization, the refresh, the custom/ exemption, the sibling _config skip, the dry-run wording, date preservation, sibling dedupe, and the trailing-newline pad each fail the suite when removed.
README: two-plugin marketplace, a Requirements section for the new hard uv/Python>=3.11 dependency, per-module skill counts derived from the installer manifest, the corrected 17-persona roster (Paige retired), the one-chain Phase 4, and the gates `bun run validate` actually runs. The 'no backwards-compatibility shims' claim is replaced by the reversal and its upstream justification. AGENTS.md: the sync section now describes the two installer runs, custom sources, the registry-driven CI matrix, and manifest-sourced version bumps. Adds a Marketplace section, and corrects the Git Workflow section — it claimed PRs target `dev`, while all four merged PRs targeted `main` and `dev` sits 51 commits behind with nothing of its own. CONTRIBUTING.md gets the same correction plus the stacked-PR flow. docs/module-integration.md was fully stale and unmarked: it documented `.upstream/<repo>` clones, an `UpstreamSource` interface of a dozen fields, and `generate:agents` / `generate:skills` scripts, none of which have existed since v6.5.0.1. Rewritten as the real procedure, one section per delivery `kind`, with bmad-manticore and bmad-module-template as worked examples. docs/releasing.md now matches scripts/release.sh and records two defects it has today: the script requires the retired `dev` branch, and its bump step uses BSD `sed -i ''`, which on GNU sed aborts after rewriting `.plugin-version` but before the three JSON files — a partial bump that also trips the clean-tree precondition on retry. Documented, not fixed, because that file is out of this change's scope. Also refreshed: versioning (8 sources, the pin-format rule the gate enforces, manticore's independent version line), bmad-ecosystem (re-audited against gh api — every upstream repo now ships its own marketplace.json, automator is archived, wds is deprecated), terminology (the four-layer TOML precedence, verified from config_utils.py rather than from prose), manual-testing (both plugins, --with-plugin, the uv-missing path), and dated superseding notes on the two historical documents that asserted current-tense falsehoods.
docs: refresh the whole documentation surface for v6.11.0
All three defects were hit while releasing v6.11.0.0, which had to be tagged and published by hand. - **It required the `dev` branch** and opened a dev -> main PR. `dev` was retired as the trunk in v6.11.0.0 (51 commits behind, nothing of its own), so the script refused to run on the branch releases actually come from. It now runs from `main`, and when the version anchors already carry the target version — the normal shape of a sync release, because `bun run sync` writes them — it runs the four gates and tags in one pass, with no branch and no PR. - **The bump used `sed -i ''`,** the BSD-only in-place form. GNU sed reads the empty string as the script and the real expression as a filename, so under `set -euo pipefail` the run aborted after `.plugin-version` had been rewritten but before the three JSON manifests — a partial bump, which then tripped the clean-tree precondition on every retry. Replaced with the attached-suffix form both seds accept, and followed by `bun run validate`: it requires all four anchors to agree, so a partial bump can no longer reach a PR. - **`bd sync` ran unguarded under `set -e`.** A `bd` that is present but incompatible killed the release after the bump commit, leaving a release branch with no PR behind it. Found by the test harness below, where a `bd` without a `sync` subcommand is on PATH. Now a warning. Also: notes come from the CHANGELOG's `## [<version>]` section instead of `--generate-notes` (a sync release's commit list spans ~1,900 regenerated files); local `main` must equal `origin/main` before tagging, since a tag on a local-only commit resolves for nobody; and the gates run before tagging on the no-bump path. Verified against a bare-clone harness (`git clone --bare` as origin) so the guards were exercised for real, not reasoned about: refuses a non-main branch, refuses a dirty tree, refuses an out-of-sync main, refuses an existing tag; and the bump path moves all four anchors together, passes validate, regenerates the README table, leaves the bmad-manticore entry on its own version line, survives a failing `bd`, pushes the branch, and stops only at `gh pr create` for want of a GitHub remote.
fix(release): make release.sh able to cut a release
…berately
Core v6.11.0 -> v6.12.0. Module bumps, all read back from the
installer's own _bmad/_config/manifest.yaml: bmb v2.2.1 -> v2.2.2,
cis v0.3.1 -> v0.3.2, gds v0.7.1 -> v0.7.2, tea v1.23.3 -> v1.26.0,
bmad-loop v0.11.0 -> v0.11.1. Manticore stays on v1.0.1 and the module
template on f1440ec8 — neither has moved upstream (manticore's main
still self-declares 3.1.0 with both 3.x sections marked Unreleased).
Skill surface 110 -> 111: bmad-checkpoint-preview was renamed
bmad-walkthrough (CK -> WT) and the old id now forwards, so both ship.
## The one deliberate divergence: --shims
v6.12.0 makes the v6 deprecation shims opt-in and its own prompt
recommends declining them. The sync passes --shims anyway, on evidence
rather than on upstream's now-stale v6-shims/README:
GDS v0.7.2 — which this bundle ships — still depends on three shim ids,
and not in prose. Live instructions:
gds-quick-dev/step-oneshot.md:22 "Invoke the
`bmad-review-adversarial-general` skill in a subagent"
gds-code-review/steps/step-02-review.md:21, gds-quick-dev/step-04-review.md:28
Live configuration:
gds-ux/customize.toml:80-81, gds-create-game-brief/customize.toml:67-68
doc_standards = [… "skill:bmad-editorial-review-structure",
"skill:bmad-editorial-review-prose"]
Installing with the new default produced a 90-skill tree in which five
game-dev skills instruct the agent to invoke skills the plugin does not
contain. That is a broken cross-module path, not a tidier surface.
The divergence is gated, not just commented: validate now resolves every
`skill:<id>` value in every customize.toml against the shipped set.
Unlike prose that merely mentions an old name, those are live config the
skill dispatches on. Mutation-verified — removing
bmad-editorial-review-structure fails validate naming both GDS files. The
day GDS stops referencing them, the gate goes quiet and --shims can go.
Also refreshed the pinned module versions the plugin-tree test asserts
against manifest.yaml.
Incremental, not a rewrite — the docs were rebuilt one release ago and
are structurally correct. Changed what v6.12.0 makes false.
- Pinned versions and counts everywhere they appear: core v6.12.0, bmb
v2.2.2, cis v0.3.2, gds v0.7.2, tea v1.26.0, bmad-loop v0.11.1;
110 -> 111 skills (bmm 35 -> 36); 20 -> 21 deprecated-described skills;
a plain /bmad:init now creates 36, not 37. Every number derived from
the tree or from a real init run, not carried over.
- **The shim rationale is rewritten, not restated.** v6.11.0.0 justified
shipping the shims by quoting upstream's v6-shims/README.md. v6.12.0
made them opt-in and left that README stale, so the same conclusion now
rests on different evidence: GDS v0.7.2's live instructions and
customize.toml values. README, AGENTS, the plugin README, the ecosystem
audit and module-integration all say so in those terms, and
module-integration gains an edge-case section — 'a module can depend on
a skill the installer stops installing by default' — next to its
existing sibling about the installer silently dropping skills.
- README gains a 'New in v6.12.0' block: bmad-walkthrough replacing
bmad-checkpoint-preview, Build sizing its own ceremony, review triage
logging a verdict per finding, bmad-project-context adopting a
handwritten AGENTS.md, and the two renames that break custom overrides
(persistent_facts now empty, {diff_output} -> {diff_file}).
- Ecosystem re-audited against gh api: bmad-plugins, bmad-eval-quality
and cis-skills added with one line each on why none is a bundle
candidate; bmad-skills recorded as no longer listed in the org.
- manual-testing gains a check for the dependency that justifies
--shims, since that is what will one day retire it.
- CHANGELOG: 6.12.0.0 section, and the release-script fixes that were
sitting under Unreleased are folded into it.
docs: refresh for v6.12.0
`--with-plugin replaces the module rows rather than accumulating them` copied all of `plugins/` into a temp dir — 1,543 files — inside bun's 5s default timeout. It overran on a loaded box often enough to be a real flake: reproduced on origin/main, one run in two failed with `timed out after 5000ms` and a knock-on `init.sh exited with 143` (SIGTERM) reported as an unhandled error between tests. init.sh only ever reads three subtrees, so copy those: the bmad plugin's scripts/ and runtime/, and the sibling's runtime/. 35 files instead of 1,543. Three consecutive runs: 6.1s, 6.8s, 7.9s, all green. Still measures what it did before — with `add_sibling` mutated to a no-op the file fails 3 tests. Also fixes two gaps in the CI workflow that this stack exposed: - `pull_request` was filtered to base branches [dev, main], so every PR in a stack except the bottom one ran NO checks at all and was reported as having none rather than as failing. PR #16 in this very stack was green-by-absence. - `uv` was not installed, so a test that resolves customization through the real `_bmad/scripts/*.py` (which run under `uv run`) failed with ENOENT on the runner while passing locally. uv is a declared prerequisite of the plugin itself — bmad-build and bmad-build-auto halt without it — so installing it in CI makes the gate match reality instead of weakening the assertion to suit the runner.
Copied verbatim from BMAD-METHOD's `docs-site/public/`. Verified they are what they claim: the SVG parses as XML with viewBox 0 0 1000 1000 and `aria-label="BMad"`; the ICO is a real 3-image icon directory (16x16, 32x32, 48x48, all 32bpp). The README now shows the mark beside the title, which is the only place it becomes visible on github.com — GitHub serves its own favicon for repository pages and ignores one at a repo root, and this repo publishes no Pages site. The root files are there for anything that does look for `/favicon.ico`: a static host serving the repo, a self-hosted forge, or local tooling. Attribution matters here and is recorded in the README. Upstream's TRADEMARK.md puts the BMad name and logo explicitly OUTSIDE the MIT grant, and forbids using the logo in a way that suggests an official or endorsed product. The note states the source, that the mark identifies the upstream this plugin packages, and that this is an unofficial redistribution — which is the permitted nominative use, not endorsement. If you would rather not carry the mark at all, reverting this commit is enough; nothing else references the files.
Answers a real question: can BMAD customization live in the home
directory, or must every repo carry its own copy? Measured against the
v6.12 runtime rather than guessed.
**It must be per-project, and `~/_bmad` is a rejected design, not a gap.**
Every layer `_bmad/scripts/config_utils.py` reads is under
`{project-root}/_bmad`: config.toml -> config.user.toml ->
custom/config.toml -> custom/config.user.toml centrally, and
customize.toml -> custom/<skill>.toml -> custom/<skill>.user.toml per
skill. Nothing reads $HOME. `resolve_customization.py` says why: the
working directory leads "because ... a home-installed skill walks up to
`~`, and any `~/_bmad` there would otherwise mask the real project's
overrides."
There IS an ancestor walk — I confirmed an ancestor `_bmad/` is used by a
repo that has none — but it is nearest-wins, never merged: giving the
repo its own `_bmad/` took the override from SHARED-FROM-ANCESTOR to [].
And skills invoke the resolver with `--project-root {project-root}`,
pinning the root to the repo and bypassing the walk entirely.
So the only seam that works is `custom/`, and it works because it is the
one layer neither the installer nor /bmad:init ever rewrites. Verified
through the exact call a skill makes: a linked custom/ supplies both the
per-skill override and the central config layer, while project_name
still resolves per-repo.
Behaviour: existing overrides are moved into the shared directory; a file
the shared directory already owns is never clobbered, because every other
repo sharing it would silently inherit this one's version; re-running is
a no-op; repointing an existing link is refused rather than done quietly.
Four mutations, each killed by the tests: not creating the link, letting
a local file clobber the shared one, allowing a silent repoint, and using
logical `pwd` instead of `pwd -P` — that last one was a real bug the
tests caught, since `cd` keeps the logical path through a symlink and
made an idempotent re-run look like a conflicting repoint.
feat(init): --shared-custom links _bmad/custom out of the project
release.sh takes its notes from the `## [<version>]` section, so the favicon, --shared-custom and test-flake entries would have shipped in a release whose notes never mentioned them.
docs(changelog): fold Unreleased into 6.12.0.0
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR brings the plugin to v6.5.0.1 and consolidates two coherent
pieces of work that landed on
tgorka/bmad-plugin@main:module bumps (TEA v1.12.2 → v1.15.1, BMB v1.4.0 → v1.7.0, CIS
v0.1.9 → v0.2.0, GDS v0.3.0 → v0.4.0). Regression-style upgrade
with no backward-compat fallbacks.
wrapper around the official
npx bmad-method install --tools claude-codeoutput (replaces the multi-source git-clone-basedsync pipeline). No upstream version change — purely a refactor
of how the plugin is built.
Why the architectural refactor (v6.5.0.1)
While auditing v6.5.0.0, several drift points surfaced between what the
old multi-source sync pipeline produced and what the official
npx bmad-method installproduces. Rather than patch each drift point,the right move is to delegate 100% of content shaping to the official
installer:
customize.tomlfilesskills/research/<name>/skills/<name>/.mdinagents/skills/gds-document-projectskills/workflows/*.mdfilesWhat changed
Added:
scripts/sync-from-installer.ts(~220 lines) — the new sync scriptdocs/plan-npx-resync.md— migration plan / rationaleRemoved:
sync-upstream-content.ts,sync-all.ts,generate-{agents,skills,agent-manifest}.ts,clean-orphaned-skills.ts,find-orphan-files.ts,bump-{core,module}.ts,lib/path-rewriter.ts,lib/workflow-iterator.ts, 7lib/checks/*.tsfilesplugins/bmad/agents/— agents are skills now, invoke via/bmad:bmad-agent-pm,/bmad:bmad-tea, etc.plugins/bmad/_shared/— replaced by per-skillresources/plugins/bmad/templates/— templates ship inside individual skilldirs
Test plan
bun run typecheck— greenbun run lint— greenbun run validate— green (now: version consistency +plugins/bmad/skills/sanity check)bun test— 6 pass, 0 fail (refreshed for v6.5.0+ skill names)claude plugin marketplace addproducesa 1392-file tree byte-identical to source (verified with
sha256sum diff)
/bmad:bmad-help,/bmad:bmad-customize,/bmad:bmad-create-prd,/bmad:bmad-tea,/bmad:gds-create-gddall load correctlyMigration notes for downstream consumers
Agent picker affordance change: agents are skills now, invoke as
/bmad:bmad-agent-pm,/bmad:bmad-teaetc. instead of "Use the pmagent…".
Commit structure
15 atomic commits on
tgorka:mainsincev6.3.0.2. Highlights:v6.5.0.0 (sync):
chore: remove v6.2/v6.3 backward-compat fallbacks before v6.5.0 syncchore: wipe legacy plugins/bmad content for clean v6.5.0 rebuildfix: path-rewriter for v6.5.0 user-side aliases and cross-module refschore: sync upstream {GDS,CIS,BMB,TEA,core} v…fix: register gds-agent-game-qa and gds-agent-game-scrum-master as plugin-onlydocs: changelog for v6.5.0.0v6.5.0.1 (refactor):
feat(scripts): add installer-based sync (replaces multi-source sync)chore: regenerate plugin tree from npx bmad-method@6.5.0 installrefactor(scripts): retire multi-source sync (-3455 lines)docs: refresh README/AGENTS/sync docs for installer-based pipelinedocs: changelog for v6.5.0.1 (installer-based sync refactor)🤖 Generated with Claude Code