feat!: distribute BMAD as a flat skills tree via npx skills and plugin marketplaces

[alexeyv]

Why

BMAD's skills depended on its npm installer to turn nested source files into an
installation. This PR makes the repository itself installable: 29 skills live
under skills/<canonical-id>/, and the bmad hub handles project setup,
update checks, and repair.

Users can install with npx skills add bmad-code-org/BMAD-METHOD, or use the
Claude Code and Codex marketplaces supplied by
bmad-code-org/bmad-plugins.

What changes

• Flat skills distribution. Each skill carries its own instructions and a
  module-manifest.toml declaring its module, version, update source, and
  knowledge location. The tree contains 21 method skills and eight
  toolbox skills, including the bmad hub. No packaging step is needed for
  the Skills CLI.
• Project runtime. bmad setup creates scripts, configuration, and output
  directories, preserving existing answers and customizations on subsequent
  runs. bmad update checks installed versions without installing updates;
  plugin copies report plugin-managed. bmad doctor repairs an existing
  runtime. Deterministic work runs through Python.
• Release source. All source manifests and the stamper use
  github:bmad-code-org/BMAD-METHOD/skills. GitHub update checks explicitly
  read main. Plugin packaging lives in the separate plugin repository.
• Release process. Stamp the release on dev, merge a dev → main
  PR with a merge commit, tag that merge commit, then stamp the next patch
  placeholder on dev. There are no release branches or back-merges.
  The stamper synchronizes all manifests, package.json, and both root
  version fields in package-lock.json, preserving dependency versions.
  It rejects invalid SemVer, -dev, and build metadata.
• CI and contribution targets. Quality runs on pushes to main and
  dev, and on PRs to any branch. A metadata-only pull_request_target
  workflow retargets newly opened PRs from main to dev, except when the
  head branch is dev. Contributor guidance directs 6.12 npm maintenance
  to V6.12.
• Installer removal and tooling. Remove the classic installer, npm
  publishing pipeline, and legacy shim skills. Skill and file-reference
  validation and renderer snapshot tests use Python. CLAUDE.md imports
  AGENTS.md; the site tooling directory is docs-site/.
• Documentation. The README describes all three install routes and the
  hub commands. The release runbook replaces the temporary rehearsal process.
  Site documentation intentionally continues to describe npm until the first
  official release under the new distribution scheme.

All version declarations remain 6.12.0-next; this PR does not cut a release.

Validation

• npm ci && npm run quality passes on committed HEAD in the checkout being
  pushed, including formatting, lint, documentation build and link checks,
  JavaScript tests, Python tests, and skill/reference validation.
• Python: 500 tests and 32 subtests pass.
• Regression coverage verifies the pinned main URL, package-version
  synchronization, dependency preservation, and no writes on invalid or
  missing package metadata.
• Stamping a temporary copy with its current version preserves all 31
  versioned files byte-for-byte.
• npm ci reports 11 dependency advisories (two moderate, nine high);
  dependency remediation is outside this change.

Rollout outside this PR

• Create V6.12 from v6.12.0, adapt its npm publish workflow, and move
  maintenance PRs there.
• Create dev from main and retarget this PR to dev before merging.
  Apply the planned protection to main and retarget other development PRs.
• Cut the first release using the runbook, update the plugin builder's source
  to BMAD-METHOD, rebuild plugins, and verify all three install routes.
• Update site documentation when the new scheme has an official release.

Replaces #2736.

[greptile-apps]

Too many files changed for review (434 files, 100 file limit).

Bypass the limit by tagging @greptile-apps to review.

[github-actions]

@coderabbitai review

[blade035]

Retested on opencode CLI after the flat skills tree landed — working end-to-end. ✅

Environment: opencode 1.18.27 (CLI, non-interactive opencode run), fresh empty directory, installed with npx skills add bmad-code-org/BMAD-METHOD → all 29 skills under .agents/skills/ with a project-local skills-lock.json (nothing written to ~/.agents). BMAD-METHOD main @ beb368e5 (6.13.0-next, i.e. post-merge main — first release isn't cut yet).

Verification (marker-injection repro from #2692, adapted to the new layout):

1. Discovery — a session in that directory lists all 29 bmad-* skills alongside the user's global skills.
2. Deterministic load — planted a RETEST_MARKER_a41c token in bmad-brainstorming/SKILL.md and asked the agent to load the skill and report its test token; it returned the exact token. The JSON event stream shows exactly one skill tool call and zero file reads — content is delivered through opencode's native skill mechanism, not left to the model to hunt down.
3. Root-cause check (the @ resolution detail from fix(installer): generate working OpenCode command pointers #2692): a command file whose body is the old @skills/bmad-brainstorming syntax still injects nothing by itself — the agent only obtains the content by noticing the name and invoking the skill tool on its own (the non-deterministic/agentic path diagnosed back then). A body of @.agents/skills/bmad-brainstorming/SKILL.md resolves as a readable file reference. So the @-as-namespace limitation in opencode is unchanged — but with the installer gone, nothing generates those pointers anymore, which moots it for BMAD.

Raw evidence

$ opencode --version
1.18.27

$ npx skills add bmad-code-org/BMAD-METHOD
◇ Found 29 skills
● Installing all 29 skills
└ Done!   → .agents/skills/ (29 bmad-* folders), project-local skills-lock.json,
            ~/.agents untouched (verified by mtimes)

[Discovery] "list your available skills, names only" →
bmad, bmad-advanced-elicitation, bmad-agent-analyst, bmad-agent-architect,
bmad-agent-dev, bmad-agent-pm, bmad-agent-ux-designer, bmad-architecture,
bmad-brainstorming, bmad-build, bmad-build-auto, bmad-code-review,
bmad-correct-course, bmad-create-epics-and-stories, bmad-customize,
bmad-deep-recon, bmad-forge-idea, bmad-party-mode, bmad-prd, bmad-prfaq,
bmad-product-brief, bmad-project-context, bmad-qa-generate-e2e-tests,
bmad-retrospective, bmad-review, bmad-spec, bmad-sprint-planning, bmad-ux,
bmad-walkthrough   (+ the user's global skills)

[Native skill load] marker planted in bmad-brainstorming/SKILL.md, then
"load the skill and reply with its test token" →
RETEST_MARKER_a41c
JSON events: 1× tool "skill", 0× read/bash — deterministic delivery

[Old pointer syntax] command body: @skills/bmad-brainstorming →
RETEST_MARKER_a41c, but JSON events: 1× tool "skill"
(the agent discovered and invoked the skill itself; the `@` reference injected nothing)

[Path pointer syntax] command body: @.agents/skills/bmad-brainstorming/SKILL.md →
RETEST_MARKER_a41c, JSON events: 1× tool "read" (resolvable file reference)

Thanks for the rework — the new distribution model is a big improvement for opencode users.