mirror of
https://github.com/bmad-code-org/BMAD-METHOD.git
synced 2026-09-01 15:09:07 +08:00
Alex Verkhovsky
49069b8b52
* feat(quick-dev): render templates via stdlib Python at skill entry Move compile-time variable substitution out of the LLM and into a deterministic Python step. SKILL.md becomes a two-line stdout-dispatch shim that runs render.py and follows the instruction it prints. The renderer reads BMad configuration from the central four-layer TOML surface introduced in #2285 (_bmad/config.toml plus config.user.toml and the two _bmad/custom/ overrides), with a fallback to the legacy per-module _bmad/bmm/config.yaml for pre-#2285 installs. Compile-time refs ({{.var}}) get substituted at render time. LLM-runtime refs ({var}) pass through untouched. Renderer (render.py) - Python 3 stdlib only (tomllib, already bundled since 3.11). UTF-8 I/O. Every invocation rebuilds from scratch — no hash, no cache. - find_project_root walks up from cwd; HALT to stdout if no _bmad/ is found anywhere on the path. - load_central_config deep-merges the four TOML layers in priority order (base-team → base-user → custom-team → custom-user) so user overrides in _bmad/custom/config.user.toml win over installer- regenerated base values. flatten_central_config lifts scalar keys from [core] and [modules.bmm] into the renderer's flat namespace; module keys beat core on collision (matches the installer's own core-key-stripping behavior). - When _bmad/config.toml is absent, falls through to the legacy flat-YAML parser for _bmad/bmm/config.yaml — the renderer keeps working across the #2285 transition. - {{.var}} substitution; unresolved refs emit empty string (Go missingkey=zero semantics). - Smart defaults for planning_artifacts / implementation_artifacts / communication_language applied after config load. Derives sprint_status / deferred_work_file from implementation_artifacts. {{.main_config}} points at whichever surface was actually read. - Renders every .md in the skill dir except SKILL.md to {project-root}/_bmad/render/bmad-quick-dev/. - On success, stderr summary plus a single stdout line: "read and follow {workflow_md}". On failure, stdout HALT directive — per the Anthropic skills spec, script stdout is the defined agent- communication channel. Skill entry (SKILL.md) - Two-line shim: run python render.py, follow stdout. No template tokens in SKILL.md itself. Template conversions - workflow.md, step-01..05, step-oneshot, sync-sprint-status: convert every compile-time {var} reference to {{.var}}. Runtime refs preserved. - spec-template.md untouched (single-curly comment hint stays as documentation). Skill-prose cleanups bundled in - Remove dead step-file frontmatter: empty-string variable declarations (spec_file, story_key, diff_output, review_mode) in quick-dev step-01 and code-review step-01; empty --- --- blocks in step-03 and step-05; the specLoopIteration counter init moved from step-04 frontmatter into the step body where first-entry vs loopback semantics are explicit. - Unify the language rule across all six quick-dev step files plus workflow.md. Tooling - tools/validate-skills.js: add TPL-01 rule. Files whose name contains "template" must not contain compile-time {{.var}} substitutions. Template files seed durable, version-controlled artifacts that execute on other machines; baking a value at render time would freeze a machine-local path into every downstream artifact. - tools/validate-file-refs.js: add render/ to INSTALL_ONLY_PATHS so the validator recognizes the runtime-generated buffer. - tools/skill-validator.md: document TPL-01; deterministic rule count bumped from 14 to 15. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * refactor(quick-dev): drop render.py YAML fallback and smart defaults Single happy path: central _bmad/config.toml with four-layer merge, Python 3.11+ required (no ImportError guard), HALT if config missing. Deletes load_flat_yaml, the YAML fallback branch, the setdefault block for planning_artifacts/implementation_artifacts/communication_language, and the tomllib ImportError fallback. Part of plan-quick-dev-python-config-hardening.md (F0). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(quick-dev): normalize render.py paths to forward slashes On Windows, os.path.join returns backslash-separated paths that can misrender as escape sequences when later concatenated into POSIX shell strings or regexes. Normalize the project root to forward slashes after find_project_root, and use posixpath.join for every path that gets baked into rendered .md files or joined into config values. os.makedirs and os.listdir accept forward-slash paths on Windows, so their call sites stay as-is. Part of plan-quick-dev-python-config-hardening.md (F3). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(quick-dev): preserve source line endings in render.py Python text-mode open() with the platform default performs universal- newline translation: on Windows, LF source files get written as CRLF, producing spurious diffs when rendered output is compared against source. Pass newline="" on both the source read and the rendered write so line endings pass through verbatim. Part of plan-quick-dev-python-config-hardening.md (F4). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(quick-dev): delete stale .md renders before rebuilding render.py rebuilds from scratch per the docstring, but makedirs(exist_ok=True) only overwrites files that still exist in the source — stale outputs from renamed/deleted source files linger in _bmad/render/bmad-quick-dev/ forever. Remove every .md in the render dir before the render loop; keep the dir itself and any non-.md files. Part of plan-quick-dev-python-config-hardening.md (F5). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(quick-dev): scope render/ whitelist to bmad-quick-dev The previous INSTALL_ONLY_PATHS entry 'render/' was a blanket prefix that let every {project-root}/_bmad/render/... reference in any skill slip past validation. Narrow to 'render/bmad-quick-dev/' so only this skill's render buffer is whitelisted. Future skills adopting the stdout-dispatch renderer pattern add their own entries explicitly. Part of plan-quick-dev-python-config-hardening.md (F6). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * test(quick-dev): add renderer smoke test with TOML override New test/test-quick-dev-renderer.js spins up a temp project with base _bmad/config.toml and a _bmad/custom/config.user.toml override, runs render.py, and asserts the override wins in rendered workflow.md and that sprint_status is rooted at an absolute path in the temp project. Registered as test:renderer in package.json and chained into the npm test script. Part of plan-quick-dev-python-config-hardening.md (F7). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(quick-dev): HALT cleanly when base config.toml is unparseable Load the four config layers through a load_toml helper that marks the base _bmad/config.toml as required. A missing, unparseable, or unreadable base now prints a HALT directive to stdout and exits, instead of being silently skipped and then crashing downstream with a KeyError when a derived value (e.g. implementation_artifacts) is absent. Optional layers still warn on stderr and fall back to empty. Merge semantics are unchanged (dict-aware deep merge, override wins for lists and scalars). * fix(quick-dev): resolve render.py via {skill-root} in skill entry shim The bare `python render.py` shim assumes the agent's working directory is the skill directory, but agents run from the project root, so the script is not found. Reference it as `{skill-root}/render.py` — BMAD's standard token for a skill's installed directory, already used by every other skill's resolve_customization.py invocation — and add the one-line `{skill-root}` explainer so the model resolves it from an instruction rather than guessing. Interpreter stays `python`; the python vs python3 choice is a separate cross-platform concern. * refactor(quick-dev): resolve [workflow] customization in render.py render.py now merges the three customize layers (customize.toml -> custom/bmad-quick-dev.toml -> .user.toml) with the same structural rules as resolve_customization.py and inlines the resolved [workflow] values, so no {workflow.*} placeholder survives. workflow.md drops its Step 1 runtime resolver + manual-merge fallback; step-05 and step-oneshot drop their runtime workflow.on_complete calls. The shared resolve_customization.py and every other skill are untouched. Smoke test extended with a [workflow] override fixture covering inlining, array append, and no-leak assertions. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(quick-dev): harden render.py invocation in the SKILL.md shim The shim called bare `python`, which can resolve to Python 2 or be absent; render.py needs 3.11+ for tomllib. Spell out python3 and the version requirement. Also make the exit code authoritative: on a non-zero exit (including an uncaught crash that writes only to stderr), do not proceed -- report what was printed and stop. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore(quick-dev): drop the render.py success stderr line The "rendered N files" progress line was pure diagnostic noise. The shim already tells the LLM to ignore stderr and follow the stdout instruction, so on success render.py now prints only the "read and follow ..." line. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(quick-dev): drop the activation gate sentence from the rendered workflow The gate ported from #2398 defended against runtime customization indirection: agents guessed resolver outputs instead of executing them, silently skipping append steps. render.py inlines the prepend/append entries into the rendered workflow.md, so there is nothing left to short-circuit, and each inlined list already carries its own execute- in-order imperative. In the default install both lists render as _None._ and the gate is pure noise. * feat(quick-dev): materialize review layers into invocation blocks Reconcile #2550 with render-time [workflow] resolution. Main made review layers configurable as [[workflow.review_layers]] arrays of tables and had the LLM resolve them during activation; this branch resolves the [workflow] block in render.py instead, so activation-time resolution no longer exists and the layer refs must be materialized at render time. Rather than inlining the layer tables as data plus interpretation rules, render.py now knows this skill's customization schema outright and renders review_layers/oneshot_review_layers as direct invocation blocks: disabled layers (empty instruction) drop out, each active layer becomes a #### section holding its instruction verbatim, zero active layers renders the HALT instruction, and runtime placeholders like {diff_output} pass through. The only judgment left to the LLM is the optional `when` condition, which renders as a run-time guard line. The step-04/step-oneshot review intros collapse to a single execute-in- parallel imperative. Smoke test covers default rendering, replace-by-id, disable-by-empty-instruction, when-guards, and the all-disabled HALT. * fix(quick-dev): invoke render.py via uv run per house standard The SKILL.md shim launched render.py with bare `python3`, which the rest of BMAD is migrating away from: the customize-bmad docs and the installer's uv-check standardize on `uv run` (uv provisions a suitable 3.11+ interpreter on demand). Bare `python3` is also fragile on Windows, where python.org installs expose `python`/`py` rather than `python3`. Make `uv run` the primary invocation and demote `python3` to the documented fallback, spelling out `python`/`py -3` for Windows and the 3.11+ tomllib requirement. render.py itself is unchanged; the renderer test drives it directly and is unaffected. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(quick-dev): HALT cleanly on missing or malformed config render.py derived sprint_status/deferred_work_file from an unconditional vars_["implementation_artifacts"] subscript, so a config lacking that key raised a raw KeyError instead of the stdout HALT the rest of the script uses on bad input. flatten_central_config likewise called .get("bmm") on merged["modules"] without checking it was a table, so a non-table [modules] crashed with an AttributeError. Guard both: HALT with a clear stdout directive when implementation_artifacts is missing or blank, and coerce a non-dict modules to {} before indexing. Add renderer regression tests asserting each path exits without a Python traceback. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * refactor(quick-dev): resolve config at compile time, drop the runtime re-read The activation "Load Config" step told the LLM to open {{.main_config}} and re-resolve project_name, communication_language, sprint_status, etc. at run time -- but render.py already bakes those from the full four-layer config merge. main_config pointed at only the base _bmad/config.toml, so on installs with override layers (config.user.toml / custom/*) the runtime re-read saw stale values that could contradict the baked {{.var}} in the same rendered file. It also handed resolution back to the LLM: the drift this skill's renderer exists to remove. Delete the ceremony and wire each value where it is actually used: - Every value the step resolved is already inlined at its point of use (planning/implementation_artifacts, sprint_status, communication_language) or loaded via persistent_facts (project-context.md), so the central block was pure redundancy. - Fold document_output_language into the per-step language rule, adopting the house-canonical form ("Speak in X. Write any file output in Y.") already used by bmad-checkpoint-preview. - Move the {date} = current-datetime definition to step-02, where the spec template's {date} field is filled. - Drop the user greeting (user_name) and user_skill_level tailoring: quick-dev is not a conversational skill and neither was load-bearing. - Remove main_config from render.py; it had no remaining consumer. Renderer tests repointed at the files that now carry these values, plus coverage for document_output_language baking and main_config removal. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs(quick-dev): reference variables by bare name, not placeholder curlies Curlies mean "expand this to the value"; a bare backticked name means "this is the variable/field I'm talking about". Several step files wrapped a variable in curlies where they were only naming, assigning, passing, or testing it -- so the notation implied an expansion that never happens: - step-01: identify `epic_num`/`story_num`, set/leave `story_key` unset - step-02: test `preserved_intent`; and resolve the template's `date` field (was `{date}`, which read as "expand date here" rather than naming it) - step-03/step-05/step-oneshot: pass `target_status` to sync-sprint-status, set `title` - sync-sprint-status: the `target_status` parameter, `story_key` precondition, and both `target_status` conditionals Value tokens that are genuinely materialized in place -- `{spec_file}` paths, `development_status[{story_key}]`, "set ... to `{target_status}`" -- stay curly. Also reword step-02's frozen-block instruction from the ambiguous "substitute it for the `<frozen-after-approval>` block" to "replace the `<frozen-after-approval>` block in the spec you just filled out with `preserved_intent`" so it's clear the replacement happens in the artifact. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * refactor(quick-dev): require uv, drop the python3 interpreter fallback The SKILL.md shim tried `uv run render.py` and, if uv was missing, retried with a bare `python3`/`py -3` interpreter. Nothing else in the codebase does that interpreter fallback: the uv-based skills (bmad-prd, bmad-ux, bmad-architecture, bmad-product-brief) fall back to reading customize.toml and using defaults -- graceful feature degradation, never a different runner -- and the legacy skills just call python3 outright. uv is the established house runner (memlog.py, resolve_customization.py, lint_spine.py all invoke it). That graceful-degrade path does not exist here: render.py is the entry dispatch that produces the workflow.md the LLM then follows, so there is nothing to fall back to. The only honest outcomes are "uv runs it" or "HALT". Make uv the floor and drop the fallback. Pin the interpreter the house way -- a PEP 723 `requires-python = ">=3.11"` block, matching memlog.py/lint_spine.py -- so `uv run` provisions a 3.11+ interpreter and the tomllib requirement is guaranteed rather than hoped for. This replaces the prose "needs 3.11+" hedge the shim used to carry. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
121 lines
4.0 KiB
JSON
121 lines
4.0 KiB
JSON
{
|
|
"$schema": "https://json.schemastore.org/package.json",
|
|
"name": "bmad-method",
|
|
"version": "6.10.0",
|
|
"description": "Breakthrough Method of Agile AI-driven Development",
|
|
"keywords": [
|
|
"agile",
|
|
"ai",
|
|
"orchestrator",
|
|
"development",
|
|
"methodology",
|
|
"agents",
|
|
"bmad"
|
|
],
|
|
"repository": {
|
|
"type": "git",
|
|
"url": "git+https://github.com/bmad-code-org/BMAD-METHOD.git"
|
|
},
|
|
"license": "MIT",
|
|
"author": "Brian (BMad) Madison",
|
|
"main": "tools/installer/bmad-cli.js",
|
|
"bin": {
|
|
"bmad": "tools/installer/bmad-cli.js",
|
|
"bmad-method": "tools/installer/bmad-cli.js"
|
|
},
|
|
"scripts": {
|
|
"bmad:install": "node tools/installer/bmad-cli.js install",
|
|
"bmad:uninstall": "node tools/installer/bmad-cli.js uninstall",
|
|
"docs:build": "node tools/build-docs.mjs",
|
|
"docs:dev": "astro dev --root website",
|
|
"docs:fix-links": "node tools/fix-doc-links.js",
|
|
"docs:preview": "astro preview --root website",
|
|
"docs:validate-links": "node tools/validate-doc-links.js",
|
|
"docs:validate-sidebar": "node tools/validate-sidebar-order.js",
|
|
"format:check": "prettier --check \"**/*.{js,cjs,mjs,json,yaml}\"",
|
|
"format:fix": "prettier --write \"**/*.{js,cjs,mjs,json,yaml}\"",
|
|
"format:fix:staged": "prettier --write",
|
|
"install:bmad": "node tools/installer/bmad-cli.js install",
|
|
"lint": "eslint . --ext .js,.cjs,.mjs,.yaml --max-warnings=0",
|
|
"lint:fix": "eslint . --ext .js,.cjs,.mjs,.yaml --fix",
|
|
"lint:md": "markdownlint-cli2 \"**/*.md\"",
|
|
"prepare": "command -v husky >/dev/null 2>&1 && husky || exit 0",
|
|
"quality": "npm run format:check && npm run lint && npm run lint:md && npm run docs:build && npm run test:install && npm run test:urls && npm run test:renderer && npm run validate:refs && npm run validate:skills && npm run docs:validate-sidebar",
|
|
"rebundle": "node tools/installer/bundlers/bundle-web.js rebundle",
|
|
"test": "npm run test:refs && npm run test:install && npm run test:urls && npm run test:channels && npm run test:renderer && npm run test:skills && npm run lint && npm run lint:md && npm run format:check",
|
|
"test:channels": "node test/test-installer-channels.js",
|
|
"test:install": "node test/test-installation-components.js",
|
|
"test:refs": "node test/test-file-refs-csv.js",
|
|
"test:renderer": "node test/test-quick-dev-renderer.js",
|
|
"test:skills": "node test/test-validate-skills.js",
|
|
"test:urls": "node test/test-parse-source-urls.js",
|
|
"validate:refs": "node tools/validate-file-refs.js --strict",
|
|
"validate:skills": "node tools/validate-skills.js --strict"
|
|
},
|
|
"lint-staged": {
|
|
"*.{js,cjs,mjs}": [
|
|
"npm run lint:fix",
|
|
"npm run format:fix:staged"
|
|
],
|
|
"*.yaml": [
|
|
"eslint --fix",
|
|
"npm run format:fix:staged"
|
|
],
|
|
"*.json": [
|
|
"npm run format:fix:staged"
|
|
],
|
|
"*.md": [
|
|
"markdownlint-cli2"
|
|
]
|
|
},
|
|
"overrides": {
|
|
"esbuild": "^0.28.1",
|
|
"markdownlint-cli2": {
|
|
"markdown-it": "^14.2.0"
|
|
}
|
|
},
|
|
"dependencies": {
|
|
"@clack/core": "^1.3.1",
|
|
"@clack/prompts": "^1.4.0",
|
|
"@kayvan/markdown-tree-parser": "^1.6.1",
|
|
"chalk": "^4.1.2",
|
|
"commander": "^14.0.0",
|
|
"csv-parse": "^6.1.0",
|
|
"glob": "^11.0.3",
|
|
"ignore": "^7.0.5",
|
|
"js-yaml": "^4.1.0",
|
|
"picocolors": "^1.1.1",
|
|
"semver": "^7.6.3",
|
|
"xml2js": "^0.6.2",
|
|
"yaml": "^2.7.0"
|
|
},
|
|
"devDependencies": {
|
|
"@astrojs/sitemap": "^3.7.3",
|
|
"@astrojs/starlight": "^0.40.0",
|
|
"@eslint/js": "^9.33.0",
|
|
"astro": "^6.4.6",
|
|
"c8": "^10.1.3",
|
|
"eslint": "^9.33.0",
|
|
"eslint-config-prettier": "^10.1.8",
|
|
"eslint-plugin-n": "^17.21.3",
|
|
"eslint-plugin-unicorn": "^60.0.0",
|
|
"eslint-plugin-yml": "^1.18.0",
|
|
"husky": "^9.1.7",
|
|
"jest": "^30.2.0",
|
|
"lint-staged": "^16.1.1",
|
|
"markdownlint-cli2": "^0.19.1",
|
|
"prettier": "^3.7.4",
|
|
"prettier-plugin-packagejson": "^2.5.19",
|
|
"sharp": "^0.33.5",
|
|
"unist-util-visit": "^5.1.0",
|
|
"yaml-eslint-parser": "^1.2.3",
|
|
"yaml-lint": "^1.7.0"
|
|
},
|
|
"engines": {
|
|
"node": ">=20.12.0"
|
|
},
|
|
"publishConfig": {
|
|
"access": "public"
|
|
}
|
|
}
|