bmad-method 6.11.1-next.0 → 6.11.1-next.10

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method",
-  "version": "6.11.1-next.0",
+  "version": "6.11.1-next.10",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "keywords": [
     "agile",
@@ -44,7 +44,7 @@
     "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:site-url && npm run test:channels && npm run test:renderer && npm run test:retrospective && npm run test:sprint-planning && 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:install": "node test/test-installation-components.js && node test/test-shim-policy.js",
     "test:refs": "node test/test-file-refs-csv.js",
     "test:renderer": "uv run --python 3.11 python -m unittest src/scripts/tests/test_config_utils.py src/scripts/tests/test_resolve_config.py src/scripts/tests/test_resolve_customization.py && node test/test-build-auto-renderer.js",
     "test:retrospective": "uv run --python 3.11 src/bmm-skills/ship/bmad-retrospective/scripts/tests/test_git_evidence.py && uv run --python 3.11 src/bmm-skills/ship/bmad-retrospective/scripts/tests/test_sprint_status.py",

package/src/bmm-skills/agents/bmad-agent-analyst/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bmad-agent-analyst
-description: Strategic business analyst and requirements expert. Use when the user asks to talk to Mary or requests the business analyst.
+description: Business analyst for market research, competitive analysis, and requirements. Use when the user asks to talk to Mary or requests the business analyst
 ---
 
 # Mary — Business Analyst

package/src/bmm-skills/agents/bmad-agent-architect/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bmad-agent-architect
-description: System architect and technical design leader. Use when the user asks to talk to Winston or requests the architect.
+description: System architect and technical design leader. Use when the user asks to talk to Winston or requests the architect
 ---
 
 # Winston — System Architect

package/src/bmm-skills/agents/bmad-agent-dev/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bmad-agent-dev
-description: Senior software engineer for story execution and code implementation. Use when the user asks to talk to Amelia or requests the developer agent.
+description: Senior software engineer who implements stories and code changes. Use when the user asks to talk to Amelia or requests the developer agent
 ---
 
 # Amelia — Senior Software Engineer

package/src/bmm-skills/agents/bmad-agent-pm/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bmad-agent-pm
-description: Product manager for PRD creation and requirements discovery. Use when the user asks to talk to John or requests the product manager.
+description: Product manager for PRD creation and requirements discovery. Use when the user asks to talk to John or requests the product manager
 ---
 
 # John — Product Manager

package/src/bmm-skills/agents/bmad-agent-ux-designer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bmad-agent-ux-designer
-description: UX designer and UI specialist. Use when the user asks to talk to Sally or requests the UX designer.
+description: UX designer and UI specialist. Use when the user asks to talk to Sally or requests the UX designer
 ---
 
 # Sally — UX Designer

package/src/bmm-skills/module-help.csv

@@ -1,19 +1,19 @@
 module,skill,display-name,menu-code,description,action,args,phase,preceded-by,followed-by,required,output-location,outputs
 BMad Method,_meta,,,,,,,,,false,https://docs.bmad-method.org/llms.txt,
 BMad Method,bmad-project-context,Project Context,PC,"Set up or refresh a repo's agent instructions so AI agents work well in it: verified commands, policy, conventions that differ from defaults, and known pitfalls. Setup, refresh, record, and audit — replaces document-project and generate-project-context.",,,anytime,,,false,repo root,AGENTS.md managed block
-BMad Method,bmad-build,Build,BD,Official Phase 4 implementation loop: clarify intent plan implement review and present.,,,ship,bmad-sprint-planning,bmad-code-review,true,implementation_artifacts,spec and project implementation
-BMad Method,bmad-spec,Spec,SPC,"Use to distill any intent input (brief, PRD, transcript, brain dump, design folder, mixed multi-source) into a succinct, no-fluff SPEC.md contract + companions that downstream work derives from. Locks the WHAT before the HOW. Works for software, game design, research, editorial, policy, business, anything intent-bearing. Validation mode also available.",,[path],anytime,,,false,{output_folder}/specs/spec-{slug},SPEC.md + companion files
-BMad Method,bmad-correct-course,Correct Course,CC,Navigate significant changes. May recommend start over update PRD redo architecture sprint planning or correct epics and stories.,,,anytime,,,false,planning_artifacts,change proposal
-BMad Method,bmad-brainstorming,Brainstorm Project,BP,Expert guided facilitation through a single or multiple techniques.,,,plan,,,false,{output_folder}/brainstorming,brainstorming session
-BMad Method,bmad-product-brief,Create Brief,CB,An expert guided experience to nail down your product idea in a brief. a gentler approach than PRFAQ when you are already sure of your concept and nothing will sway you.,,-A,plan,,,false,planning_artifacts,product brief
-BMad Method,bmad-prfaq,PRFAQ Challenge,WB,Working Backwards guided experience to forge and stress-test your product concept to ensure you have a great product that users will love and need through the PRFAQ gauntlet to determine feasibility and alignment with user needs. alternative to product brief.,,-H,plan,,,false,planning_artifacts,prfaq document
-BMad Method,bmad-prd,Create Edit and Review PRD,PRD,"Facilitated PRD workflow — create a new PRD via coached discovery, update an existing one against a change signal, or validate a finished PRD against a checklist with an HTML findings report.",,,2-planning,bmad-product-brief,,true,planning_artifacts,prd
-BMad Method,bmad-ux,Create UX,CU,"Guidance through realizing the plan for your UX, strongly recommended if a UI is a primary piece of the proposed project.",,,2-planning,bmad-prd,,false,planning_artifacts,ux design
-BMad Method,bmad-architecture,Architecture,CA,Offer once requirements exist (a PRD or spec; plus UX if present) and the user is ready to move from what to how. Also offer any time independently-built parts risk diverging. Produces the architecture spine: the invariants that keep features epics and stories consistent. Comes before epics and stories and scales from a quick spine to a full architecture (brownfield: ratifies the existing codebase).,,,plan,,,true,planning_artifacts,architecture
-BMad Method,bmad-create-epics-and-stories,Create Epics and Stories,CE,,,,plan,bmad-architecture,,true,planning_artifacts,epics and stories
-BMad Method,bmad-sprint-planning,Sprint Planning,SP,Readiness gate then tracking: verifies the planning is implementable (PASS/CONCERNS/FAIL) and produces the sprint status the implementation agents follow for every story.,,,plan,,,true,implementation_artifacts,sprint status
-BMad Method,bmad-sprint-planning,Sprint Status,SS,Anytime: summarize sprint status with risks open action items and the next recommended action; can also validate or repair the tracking file.,status,,anytime,,,false,,status summary
-BMad Method,bmad-code-review,Code Review,CR,Ad hoc review of any code change. Optional extra layer after Build's built-in review.,,,ship,bmad-build,,false,,
-BMad Method,bmad-checkpoint-preview,Checkpoint,CK,Guided walkthrough of a change from purpose and context into details. Use for human review of commits branches or PRs.,,,ship,,,false,,
-BMad Method,bmad-qa-generate-e2e-tests,QA Automation Test,QA,Generate automated API and E2E tests for implemented code. NOT for code review or story validation — use CR for that.,,,ship,bmad-build,,false,implementation_artifacts,test suite
-BMad Method,bmad-retrospective,Retrospective,ER,Optional at epic end: Review completed work lessons learned and next epic or if major issues consider CC.,,,ship,bmad-code-review,,false,implementation_artifacts,retrospective
+BMad Method,bmad-build,Build,BD,"The standard implementation flow: clarify intent, plan, implement, review, and present.",,,ship,bmad-sprint-planning,bmad-code-review,true,implementation_artifacts,spec and project implementation
+BMad Method,bmad-spec,Spec,SPC,"Condense any input (brief, PRD, transcript, brain dump, design folder, or several sources at once) into a short SPEC.md plus supporting files that later work builds from. Pins down what to build before deciding how. Works for software, game design, research, editorial, policy, business — anything with an intent behind it. Can also validate an existing spec.",,[path],anytime,,,false,{output_folder}/specs/spec-{slug},SPEC.md + companion files
+BMad Method,bmad-correct-course,Correct Course,CC,"Assess a significant mid-sprint change. May recommend starting over, updating the PRD, redoing architecture or sprint planning, or correcting epics and stories.",,,anytime,,,false,planning_artifacts,change proposal
+BMad Method,bmad-brainstorming,Brainstorm Project,BP,Guided idea-generation session using one or more brainstorming techniques.,,,plan,,,false,{output_folder}/brainstorming,brainstorming session
+BMad Method,bmad-product-brief,Create Brief,CB,A guided conversation that captures your product idea in a brief. A gentler alternative to the PRFAQ when you are already committed to your concept.,,-A,plan,,,false,planning_artifacts,product brief
+BMad Method,bmad-prfaq,PRFAQ Challenge,WB,"Amazon's Working Backwards method: write the press release for the finished product first, then answer hard customer and stakeholder questions to test whether the concept holds up. An alternative to the product brief.",,-H,plan,,,false,planning_artifacts,prfaq document
+BMad Method,bmad-prd,Create Edit and Review PRD,PRD,"Create a new PRD through guided discovery, update an existing one when plans change, or validate a finished PRD against a checklist with an HTML findings report.",,,2-planning,bmad-product-brief,,true,planning_artifacts,prd
+BMad Method,bmad-ux,Create UX,CU,"Capture UX decisions into design and experience documents. Strongly recommended when a UI is a major part of the project.",,,2-planning,bmad-prd,,false,planning_artifacts,ux design
+BMad Method,bmad-architecture,Architecture,CA,"Offer once requirements exist (a PRD or spec, plus UX if present) and the user is ready to decide how to build. Also offer any time separately built parts risk becoming inconsistent. Records the architecture decisions that keep features, epics, and stories consistent. Comes before epics and stories; scales from a few key decisions to a full architecture, and can document the conventions of an existing codebase.",,,plan,,,true,planning_artifacts,architecture
+BMad Method,bmad-create-epics-and-stories,Create Epics and Stories,CE,Break the PRD and architecture into epics and user stories with acceptance criteria.,,,plan,bmad-architecture,,true,planning_artifacts,epics and stories
+BMad Method,bmad-sprint-planning,Sprint Planning,SP,"Checks the planning is complete enough to implement (PASS/CONCERNS/FAIL), then generates the sprint status file that implementation agents follow for every story.",,,plan,,,true,implementation_artifacts,sprint status
+BMad Method,bmad-sprint-planning,Sprint Status,SS,"Summarize sprint progress at any time: risks, open action items, and the recommended next action. Can also validate or repair the tracking file.",status,,anytime,,,false,,status summary
+BMad Method,bmad-code-review,Code Review,CR,Ad hoc review of any code change. An optional extra check after Build's built-in review.,,,ship,bmad-build,,false,,
+BMad Method,bmad-checkpoint-preview,Checkpoint,CK,"Guided walkthrough of a change, from purpose and context into details. Use for human review of commits, branches, or PRs.",,,ship,,,false,,
+BMad Method,bmad-qa-generate-e2e-tests,QA Automation Test,QA,Generate automated API and end-to-end tests for implemented code. Not for code review or story validation — use Code Review for that.,,,ship,bmad-build,,false,implementation_artifacts,test suite
+BMad Method,bmad-retrospective,Retrospective,ER,"Optional at the end of an epic: review the completed work and lessons learned, and look ahead to the next epic. If major issues surfaced, consider Correct Course.",,,ship,bmad-code-review,,false,implementation_artifacts,retrospective

package/src/bmm-skills/module.yaml

@@ -1,6 +1,6 @@
 code: bmm
 name: "BMad Method"
-description: "Agile Ai Driven Development"
+description: "Agile AI-driven development"
 default_selected: true # This module will be selected by default for new installations
 
 # Variables from Core Config inserted:

package/src/bmm-skills/plan/bmad-architecture/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bmad-architecture
-description: 'Produce the architecture: a lean spine of invariants that keeps everything built from it consistent, projected into whatever format the work needs. Use when the user says "create the architecture", "create technical architecture", "architecture spine", or "create a solution design".'
+description: 'Work out and record the architecture decisions that keep separately built parts of a system consistent, in a short architecture document. Creates, updates, or validates one; works from a spec, a raw idea, or an existing codebase. Use when the user says "create the architecture", "create technical architecture", "architecture spine", or "create a solution design"'
 ---
 # BMad Architecture
 

package/src/bmm-skills/plan/bmad-generate-project-context/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: bmad-generate-project-context
 description: 'Deprecated — forwards to bmad-project-context. Use when the user says "generate project context" or "create project context"'
+metadata:
+  lifecycle: shim
 ---
 
 # DEPRECATED — forwards to bmad-project-context

package/src/bmm-skills/plan/bmad-prd/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bmad-prd
-description: Create, update, or validate a PRD. Use when the user wants help producing, editing, or validating a PRD.
+description: Create, update, or validate a PRD. Use when the user wants help producing, editing, or validating a PRD
 ---
 # BMad PRD
 

package/src/bmm-skills/plan/bmad-prfaq/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bmad-prfaq
-description: Working Backwards PRFAQ challenge that stress-tests a product concept customer-first. Use when the user requests to 'create a PRFAQ', 'work backwards', or 'run the PRFAQ challenge'.
+description: "Test a product concept with Amazon's Working Backwards method: write the press release for the finished product first, then answer hard customer and stakeholder questions, ending in a complete PRFAQ document. Use when the user requests to 'create a PRFAQ', 'work backwards', or 'run the PRFAQ challenge'"
 ---
 
 # Working Backwards: The PRFAQ Challenge

package/src/bmm-skills/plan/bmad-prfaq/bmad-manifest.json

@@ -4,7 +4,7 @@
     {
       "name": "working-backwards",
       "menu-code": "WB",
-      "description": "Produces battle-tested PRFAQ document and optional LLM distillate for PRD input.",
+      "description": "Produces a PRFAQ document and an optional condensed version for use as PRD input.",
       "supports-headless": true,
       "phase-name": "plan",
       "preceded-by": ["brainstorming", "perform-research"],

package/src/bmm-skills/plan/bmad-product-brief/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bmad-product-brief
-description: Create, update, or validate a product brief. Use when the user wants help producing, editing, or validating a brief.
+description: Create, update, or validate a product brief. Use when the user wants help producing, editing, or validating a brief
 ---
 
 # Overview

package/src/bmm-skills/plan/bmad-project-context/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bmad-project-context
-description: 'Set up, refresh, or audit a repository''s agent instructions (the AGENTS.md block) so AI agents work well in that repo. Also records observed agent mistakes as pitfall lines. Must be invoked by name.'
+description: 'Set up, adopt, refresh, or audit a repository''s agent instructions (the AGENTS.md block) so AI agents work well in that repo. Also records observed agent mistakes as pitfalls. Must be invoked by name'
 ---
 
 # Overview
@@ -9,7 +9,7 @@ A conversation that produces a repository's agent instructions: a small verified
 
 Conversational always; the user approves every write.
 
-**Args:** intent (`setup` | `refresh` | `record` | `audit`); a target repo or path; extra source paths or URLs. Supplied values skip their questions.
+**Args:** intent (`setup` | `adopt` | `refresh` | `record` | `audit`); a target repo or path; extra source paths or URLs.
 
 ## Resolution rules
 
@@ -22,9 +22,9 @@ Conversational always; the user approves every write.
 1. Resolve customization: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. On failure, read `{skill-root}/customize.toml` directly and use defaults. Execute `{workflow.activation_steps_prepend}`; treat `{workflow.persistent_facts}` entries as standing context (`file:` = paths/globs to load, others verbatim).
 2. Config: if `{project-root}/_bmad` exists, `uv run {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root}` and read `{user_name}`, `{communication_language}` (use it every turn), `{output_folder}`. Standalone: skip.
 3. **Load `references/best-practices.md` and `references/template.md` before anything else.** Every decision below is made against them.
-4. Detect intent and greet `{user_name}`: **setup** (no block in the target — the default), **refresh** (a block exists), **record** (the user reports a mistake agents made), **audit** (re-verify and prune). Fold `{workflow.external_sources}` into the source list. Execute `{workflow.activation_steps_append}`.
+4. Detect intent and greet `{user_name}`: **setup** (no instruction file in the target carries meaningful content — scaffolding alone, empty headings, a comment, a lone import line, is not meaningful; when unsure, adopt, since adopting a near-empty file costs one small ledger while setting up a meaningful one loses instructions), **adopt** (an instruction file has content but no managed block, whatever its state and whoever wrote it — the migration form of refresh; that file is the baseline and every instruction in it enters the ledger of step 1), **refresh** (a managed block exists), **record** (the user reports a mistake agents made), **audit** (re-verify and prune). A supplied intent that contradicts what detection finds — e.g. `setup` against a file with content — is surfaced and confirmed, never silently obeyed. Fold `{workflow.external_sources}` into the source list. Execute `{workflow.activation_steps_append}`.
 
-## Setup and Refresh Steps
+## Setup, Adoption, and Refresh Steps
 
 No writes until step 5!
 
@@ -32,6 +32,8 @@ No writes until step 5!
 
 Read `AGENTS.md`, harness or agent specific rule files, docs folders, and any notes carrying lessons. Report what exists and how it measures up, per `best-practices.md`.
 
+Existing instructions are the baseline being improved, never raw material to discard. Open a **ledger**: one entry per existing section and per independently meaningful instruction, opened at `retain` or `rewrite`, carrying what an agent would get wrong without it. Entries settle as evidence arrives in steps 2–4 — `retain | rewrite | relocate | automate | delete`, each with its reason, its evidence, the risk if it goes, a destination for a relocation, and an approval flag. Deletion needs one of the four grounds in `best-practices.md`, and a relocation destination must itself be loaded or sit behind an observable trigger — a move into a file nothing reads is a deletion and needs its ground. Setup has nothing to map and opens no ledger; refresh opens entries for the lines it proposes to change or remove, the block's own included. A lesson found outside the instruction files — a warning in a README, a notes file — is an ordinary candidate, not a ledger entry.
+
 If the target contains separable units — a workspace manifest listing members, or directories carrying their own build manifest — name them and ask whether this run covers the root only, all of them, or which. Absent that evidence, do not ask. Sibling repositories are not children; each is its own target, offered in turn.
 
 ### 2. Ask what they bring
@@ -61,9 +63,9 @@ Only what no scan reaches: what agents keep getting wrong here, what is off limi
 
 ### 5. Show the block, then write it
 
-Compose against `template.md`. For each candidate, ask first whether a hook, lint rule, or CI check enforces it better than prose; if so propose the check, and the line becomes the fallback if they decline.
+Compose against `template.md`. For each candidate, ask first whether a hook, lint rule, or CI check enforces it better than prose; if so propose the check, and the line becomes the fallback if they decline. A ledger entry marked `automate` keeps its instruction until its check is in place (a later run deletes the line under ground 2 once the check is live).
 
-**Show the complete block before writing it**, and every child block alongside it — one approval covers the set. On approval, splice between the markers, leaving everything outside them byte-identical. Fill each provenance line with today's date and the verified SHA.
+**Show the complete block before writing it**, and every child block alongside it — one approval covers the set. **Present the settled ledger with it**: replacement text alone is an incomplete proposal, because it shows what the user gains and hides what they lose. Every existing instruction appears with its decision and reason; retains and rewrites may be grouped, every relocation, automation, and deletion is itemized. A deletion resting on none of the first three grounds is held for line-item approval — approving the block never approves it — and a declined deletion, relocation, or automation reverts to retain. On approval, splice between the markers — the splice itself touches nothing outside them. Text outside the markers changes only through a settled ledger entry or a proposed fix the user has seen, never as a side effect of the splice. Fill each provenance line with today's date and the verified SHA.
 
 Where an instruction elsewhere contradicts the block in a way that changes behavior — a stale `CLAUDE.md` line, a retired command — propose the fix to that file. Two live contradictory instructions is a defect.
 
@@ -71,15 +73,21 @@ Never commit.
 
 ### 6. Close
 
-- What went in, and what was left out and why.
-- Why, in the user's terms, from `best-practices.md` — why it is small, why what the repo already states stays out, why a pitfall line stays until its cause is gone.
+- What went in, what was left out and why, and — after adoption or refresh — where each existing instruction landed.
+- Why, in the user's terms, from `best-practices.md` — why it is small, why what the repo already states stays out, why a pitfall stays until its cause is gone.
 - How it loads, and that other harness files can point at it.
 - Maintenance: re-run after significant change, `record` the moment an agent gets something wrong, prefer a check over a new line.
 - Rules repeating across their projects, or personal rather than the team's, belong in their global agent config.
 
 ### Refresh
 
-Same steps, step 1 as a diff. Read the provenance line, re-verify every path and every caveat, and run `git log --diff-filter=DR --name-only` since the recorded SHA against every line — update or remove lines whose evidence is gone. Never re-ask what a prior run settled; the interview shrinks to what changed about how the team works. The block grows only on new evidence.
+Same steps, step 1 as a diff. Read the provenance line, re-verify every path and every caveat, and run `git log --diff-filter=DR --name-only` since the recorded SHA against every line — update or remove lines whose evidence is gone. Every proposed removal is a ledger entry shown in step 5, never a silent edit, and handwritten instructions outside the block are treated as in adoption — any proposal touching them enters the ledger. Never re-ask what a prior run settled; the interview shrinks to what changed about how the team works. The block grows only on new evidence.
+
+### Adoption
+
+Refresh against instructions this skill has never touched. Nothing was settled by a prior run, so the full interview applies — and the file itself is maintainer testimony, so the ledger is the run's main output: the user should be able to read it and see where each of their instructions went.
+
+The proposal states what remains of every file instructions were moved out of — commonly a `CLAUDE.md` reduced to `@AGENTS.md`, once that import is verified for every harness in use, like any loading mechanism. No instruction lives in two loaded files, where it is paid for twice; a duplicate, verbatim or reworded, is kept once — the block keeps the survivor — and that settles both entries.
 
 ### Greenfield
 
@@ -91,7 +99,7 @@ If the target has a `project-context.md` from the retired skills, commonly under
 
 ## Record
 
-Capture one observed agent mistake as it happens — the only admissible source for a pitfall line.
+Capture one observed agent mistake as it happens — the only admissible source for a pitfall.
 
 Take the task, the mistake, the correction, and its evidence. Check the block for a line already covering it. One occurrence is noted; a recurring or costly mistake earns a line now — an exact invocation under **Running and verifying** when it is a command error, otherwise a pitfall. Write it and show the diff. If it is mechanically preventable, propose the hook, lint rule, or CI check instead.
 
@@ -99,11 +107,13 @@ Take the task, the mistake, the correction, and its evidence. Check the block fo
 
 Re-check every caveat, path-check every file, follow every pointer, and ask of every line whether removing it would change agent behavior. Check for contradictions with other instruction files.
 
-Failing lines move behind an observable trigger, get fixed, or are deleted — confirm deletions first. **A policy or pitfall line goes only when the thing it guards is gone or the user retires it; nothing failing lately is not grounds.** Audit ends smaller or equal.
+Failing lines get fixed, move behind an observable trigger, or become ledger entries: a removal needs one of the four grounds in `best-practices.md`, presented and settled as in step 5 before anything is removed. **A policy or pitfall goes only when the thing it guards is gone or the user retires it; nothing failing lately is not grounds.** Audit ends smaller or equal.
 
 ## Children
 
-A component, nested repository, or extracted rules file gets its own file under the same shape when work keeps landing there and its truths do not belong at the parent level. Rules bounded to a directory go in a nested `AGENTS.md` there, attached by location. Use a linked file only when the trigger is not a path.
+A component, nested repository, or extracted rules file gets its own file under the same shape when work keeps landing there and every condition holds: its rules are subtree-exclusive, they are substantial (a handful of rules is not a file), the split materially reduces the parent block, the loading mechanism is verified for every harness in use — checked, never assumed — and the user approves the split. Otherwise the rules stay in the parent block as path-qualified lines ("in `src/importer/`: ..."), which cost less than a file nobody loads. Why the loading check: `best-practices.md`.
+
+Use a linked file only when the trigger is not a path.
 
 A chosen child that ends with nothing its parent does not already say gets no file. Say so and move on.
 

package/src/bmm-skills/plan/bmad-project-context/references/best-practices.md

@@ -4,15 +4,19 @@ Rules for deciding what goes in the block, for judging what a repo already has,
 
 ## The test
 
-Can an agent derive this by reading the repository? If yes, leave it out — a stored copy is a stale duplicate of something the agent reads more accurately first-hand, and it is charged on every session. Write down what the code cannot say.
+Not *could an agent derive this* but *what does it cost when it doesn't*: how much exploration finding it takes, how likely the agent is to search the right place in time rather than guess, whether it is available at the point of use or only after the mistake, what a retrieval failure costs — a wasted search, or corrupt data — and whether it is a rule that must hold or a detail the code already shows.
+
+A line that stops the same rediscovery every session earns its place, derivable or not. A stored copy of what the agent reads more accurately first-hand does not — it rots, and it is charged every session.
 
 ## Admit
 
 - **Policy the code cannot express** — branch rules, frozen and protected paths, generated files, secrets, security and compliance. Stated by a human or read off an enforcing config, never inferred.
-- **What a config file cannot say about running the project** — the root test script does nothing in this workspace, integration tests need a service up first, the suite takes eleven minutes so iterate on single files, the `Makefile` is the real entry point and `package.json` is vestigial, CI runs a typecheck the test script does not. The invocation itself is already stated in `package.json`, `Makefile`, `pyproject.toml`, or CI config and does not earn a line — the correction or the caveat does.
+- **What a config file cannot say about running the project** — the root test script does nothing in this workspace, integration tests need a service up first, the suite takes eleven minutes so iterate on single files, the `Makefile` is the real entry point and `package.json` is vestigial, CI runs a typecheck the test script does not. An invocation the obvious guess gets right is already stated in `package.json`, `Makefile`, `pyproject.toml`, or CI config and does not earn a line — the correction, the caveat, and the right command to use do.
 - **Conventions that differ from ecosystem defaults.** An agent follows the norm unless told otherwise, so only the divergences earn a line. Command invocations count: when the obvious command is wrong here — a bare-repo prefix, a required wrapper — the exact working invocation earns a line, and no observed mistake is needed to admit it.
 - **Pitfalls with observed evidence** — a recorded lesson, the maintainer's recollection, the same mistake fixed repeatedly in history, or one this session made and caught. A repo yields hundreds of trap-looking facts and none of them predict real mistakes; only observed behavior does. A surprising scan finding is a question to ask, not a line to write.
 - **Runtime behavior invisible from the repo** — replaying webhooks, lying health endpoints, environment quirks — once a human confirms it.
+- **Cross-component rules**, admitted when getting one wrong in one file breaks something elsewhere — what must stay true across parts of the system the agent cannot see from the file it is editing: who owns what, how data must flow, what order a pipeline runs in. "Writes go through the dispatcher; direct store mutation skips the transaction." "The importer is two passes — validate every row, then commit; never write inside the parse loop." A six-line map of who owns what. Never an inventory written for completeness; the exclusions below still bind.
+- **Required tool and runtime versions**, read from the project files that declare them, never from this session's environment — which answers faster, and wrongly, so the mistake arrives before the search.
 - **Entry points and pointers** to where work lands.
 
 Prefer prohibitions to advice, and name the permitted alternative in the same line.
@@ -25,26 +29,30 @@ Prefer prohibitions to advice, and name the permitted alternative in the same li
 | Anything included for being interesting | Interest is not need |
 | Style rules an agent self-enforces | Belongs in a formatter, linter, hook, or CI check — propose the check instead |
 | Platitudes | Already the default |
-| Commands already stated in `package.json`, a `Makefile`, or CI config | Read from the source of truth; a copy drifts the moment a script is renamed |
+| Transcribed command lists whose obvious invocation is already right | Read from `package.json`, a `Makefile`, or CI config; a copy drifts the moment a script is renamed. The right command to use, and any command the obvious guess gets wrong, are admitted above |
 | Pasted code, changelog content, fast-changing facts | Stale immediately |
 | Aspirational state | Describe what is; intent belongs in specs |
 | History and edit narration | Git holds it; state present truth |
 
 ## Retire
 
-A policy or pitfall line goes only when the thing it guards is gone, or the user retires it. Nothing failing lately is not evidence — a working rule erases its own evidence.
+A policy or pitfall goes only when the thing it guards is gone, or the user retires it. Nothing failing lately is not evidence — a working rule erases its own evidence. Any other existing instruction goes only on one of the four grounds under "Judging an existing file".
 
-Every other line faces one question at each write: would removing it change agent behavior? If no, cut it.
+Every line faces one question at each write: would removing it change agent behavior? If no, cut it — but for a line a human wrote, that answer only opens a candidate; a ground still has to carry it.
 
 ## Size
 
 Every line is paid in every session, and instruction-following degrades as the loaded set grows. Count what other always-loaded files add. Over budget means cut the weakest lines or move them behind a trigger — never raise the budget. Ten lines of evidence means ten lines.
 
+An adopted file must fit the budget too, but shrinking it works differently. Move the weakest instructions out first — into a child file, a linked doc, or a hook or check that enforces them. Deleting still needs one of the four grounds. If the file is still too big and no ground justifies another deletion, show the user and let them decide — an over-budget file they chose beats a gutted one they didn't. "Keep it small" disciplines what this skill writes, never what the maintainer already wrote.
+
 ## Retrieval
 
 An index the agent must choose to fetch gets skipped; one already in context does not. Keep everything load-bearing in the block. A pointer out of it names a trigger the agent can observe — a path, a file type, a named task — never one it must judge ("when the task is complex") or track about itself ("before your first edit").
 
-Rules bounded to a directory go in a nested `AGENTS.md` there, attached by location rather than by pointer. Use a linked file only when the trigger is not a path.
+Rules bounded to a directory can go in a nested `AGENTS.md` there, attached by location rather than by pointer — but only when they are subtree-exclusive and substantial, the split materially reduces the root block, the user approves it, and **loading is verified for every harness in use**. Check, never assume: several harnesses build the instruction chain once at session start, root down to the working directory, so a nested file is invisible to the session that later edits into that subtree. Unverified means path-qualified lines at root instead — "in `src/importer/`: ..." — cheaper than a file nobody loads.
+
+Use a linked file only when the trigger is not a path.
 
 ## Maintain
 
@@ -62,4 +70,15 @@ Two things belong in the user's global agent config instead — rules repeating
 
 ## Judging an existing file
 
-Report, in this order: what is derivable filler, what is unverifiable or stale, what is missing against the sections above, and what is already good. Keep recorded lessons by default — they are maintainer testimony, and are challenged only with evidence that the thing they name is gone or wrong.
+Every instruction a human wrote is presumed intentional: someone paid for it, usually by watching an agent fail. The file is the baseline being improved, not raw material. Keep its phrasing where it works, and carry each instruction through a ledger entry — `retain | rewrite | relocate | automate | delete`, opened at retain or rewrite — so the user sees where all of it went.
+
+**Deletion needs one of four grounds:**
+
+1. **Stale or incorrect** — the referent is gone, or the instruction was never true; the evidence is named.
+2. **Mechanically enforced** — a hook, linter, formatter, or CI check already fails the violation, so the line has no work left to do.
+3. **Harmful or contradictory** — it points agents at the wrong thing, or it contradicts another live instruction and loses the reconciliation.
+4. **The user approved this deletion** — asked as a line item, never implied by approving a replacement block.
+
+Grounds 1–3 are evidence the run carries itself, and ride the block approval; ground 4 is the ask-first path everything else takes. Nothing else deletes. Brevity is not grounds, nothing failing lately is not grounds, "the agent could derive it" is not grounds, and **"it is discoverable somewhere in the repository" is never, alone, grounds** — that is the reasoning that empties good files. Content the exclusions table rejects — a directory tree, a stack list, pasted code — has no ground of its own: propose the deletion and let it land under ground 4, asked rather than assumed.
+
+Report, in this order: what is unverifiable or stale, what is missing against the sections above, what is already good, and the ledger, every relocation, automation, and deletion itemized. Recorded lessons are maintainer testimony — kept by default, challenged only with evidence that the thing they name is gone or wrong.

package/src/bmm-skills/plan/bmad-project-context/references/template.md

@@ -5,7 +5,7 @@ Sections in this order. Omit any section with nothing that passes its rule — n
 1. **Orientation** — three or four sentences: what this is, the stack, where planning and deeper docs live.
 2. **Policy** — what the org requires.
 3. **Where things are** — entry points, and pointers to children and linked files.
-4. **Running and verifying** — only what `package.json`, a `Makefile`, or CI config does not already say.
+4. **Running and verifying** — the right commands to run and the required tool versions, plus what `package.json`, `pyproject.toml`, a `Makefile`, or CI config does not already say.
 5. **Conventions that differ from defaults**
 6. **Known pitfalls**
 

package/src/bmm-skills/plan/bmad-spec/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bmad-spec
-description: Distill any intent input into the SPEC kernel + companions — the canonical, preservation-validated machine contract for downstream work. Use when the user says "create a spec", "distill this into a spec", "validate this spec", "update the spec", or "break this into stories".
+description: 'Condense any input — an idea, brief, PRD, transcript, or mixed notes — into a short spec: SPEC.md plus supporting files that downstream skills build from. Also updates and validates existing specs, and can break a spec into stories. Use when the user says "create a spec", "distill this into a spec", "validate this spec", "update the spec", or "break this into stories"'
 ---
 
 # BMad Spec

package/src/bmm-skills/plan/bmad-sprint-planning/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bmad-sprint-planning
-description: 'Gate planning readiness, generate sprint status tracking from epics, summarize sprint progress, and validate or repair the tracking file. Use when the user says "run sprint planning", "generate sprint plan", "check implementation readiness", "show sprint status", "validate sprint status", or "fix sprint status"'
+description: 'Check that planning is complete enough to implement, then generate the sprint status file from the epics. Can also summarize sprint progress and validate or repair the tracking file. Use when the user says "run sprint planning", "generate sprint plan", "check implementation readiness", "show sprint status", "validate sprint status", or "fix sprint status"'
 ---
 
 # Overview

package/src/bmm-skills/plan/bmad-ux/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bmad-ux
-description: Plan UX patterns and design specifications. Use when the user says "lets create UX design" or "create UX specifications" or "help me plan the UX"
+description: 'Capture the user''s UX vision in two documents: DESIGN.md for how the product looks and EXPERIENCE.md for how it behaves. Use when the user says "lets create UX design" or "create UX specifications" or "help me plan the UX"'
 ---
 # BMad UX
 

package/src/bmm-skills/ship/bmad-build/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bmad-build
-description: 'Implements any user intent, requirement, story, bug fix or change request by producing clean working code artifacts that follow the project''s existing architecture, patterns and conventions. Use when the user wants to build, fix, tweak, refactor, add or modify any code, component or feature.'
+description: 'Turns a work item — feature, story, bug fix, change request — into working code, reviewed and verified. Use when the user hands over an outcome and leaves the edits to you; a bare story or issue link counts. Also use whenever the user asks BMAD by name — then any change qualifies, even a tiny fully-specified edit. Do not volunteer for interactive edits the user directs and reviews themselves, or for version-control operations that record existing work without changing it.'
 ---
 
 Run the following command exactly once without changing the current working directory. Replace `{project-root}` with the absolute path to the project root and `{skill-root}` with the absolute path to this skill's directory:

package/src/bmm-skills/ship/bmad-build/step-oneshot.md

@@ -5,7 +5,7 @@
 - **Language** — Speak in `{{.communication_language}}`. Write any file output in `{{.document_output_language}}`.
 - NEVER auto-push.
 - All review subagents must run at the same model capability as the current session.
-- Run subagents synchronously: launch them together, then wait for all results before continuing.
+- Run subagents synchronously: launch them together as blocking calls awaited in this turn — never backgrounded or detached, never ending the turn to await results.
 
 ## INSTRUCTIONS
 
@@ -25,18 +25,17 @@ If a layer's instruction requires subagents and none are available, for each suc
 
 ### Classify
 
-Deduplicate all review findings. Three categories only:
+Deduplicate all review findings, then route each finding in this order:
 
-- **patch** — trivially fixable. Auto-fix immediately.
-- **defer** — pre-existing issue not caused by this change. Append one new entry to `{{.implementation_artifacts}}/deferred-work.md` using this format. Do not modify existing entries or look for duplicates.
+- **patch** — Patch every finding caused or exposed by this change that shows a defect that actually occurs, missing coverage for a specific case, or a broken gate or convention — not a state nothing reaches — and whose smallest fix is trivial, adds no public surface, and guards no state the finding did not demonstrate. Apply that smallest fix immediately.
+- **HALT** — HALT on every finding caused or exposed by this change that shows the same evidence but whose smallest fix fails any of those conditions. Present it to the human for decision before proceeding.
+- **defer** — Defer every other real finding, including pre-existing issues and improvement ideas. Append one new entry to `{{.implementation_artifacts}}/deferred-work.md` using this format. Do not modify existing entries or look for duplicates.
   ```markdown
   - source_spec: `{spec_file}`
     summary: <one sentence>
     evidence: <why this is real>
   ```
-- **reject** — noise. Drop silently.
-
-If a finding is caused by this change but too significant for a trivial patch, HALT and present it to the human for decision before proceeding.
+- **reject** — Reject only noise. Drop silently.
 
 ### Generate Spec Trace
 

package/src/bmm-skills/ship/bmad-build-auto/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bmad-build-auto
-description: 'One iteration of an unattended development loop. Use when invoked by name.'
+description: 'One iteration of an unattended development loop. Use when invoked by name'
 ---
 
 Run the following command exactly once without changing the current working directory. Replace `{project-root}` with the absolute path to the project root and `{skill-root}` with the absolute path to this skill's directory:

package/src/bmm-skills/ship/bmad-checkpoint-preview/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bmad-checkpoint-preview
-description: 'LLM-assisted human-in-the-loop review. Make sense of a change, focus attention where it matters, test. Use when the user says "checkpoint", "human review", or "walk me through this change".'
+description: 'Walk the user through reviewing a change: what it is for, what to look at closely, and how to test it. Use when the user says "checkpoint", "human review", or "walk me through this change"'
 ---
 
 # Checkpoint Review Workflow

package/src/bmm-skills/ship/bmad-code-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bmad-code-review
-description: 'Adversarial code review using parallel review layers and structured triage. Use when the user says "run code review" or "review this code"'
+description: 'Review code changes with several independent reviewers in parallel, then triage and present the findings. Use when the user says "run code review" or "review this code"'
 ---
 
 # Code Review Workflow

package/src/bmm-skills/ship/bmad-code-review/steps/step-02-review.md

@@ -8,7 +8,7 @@ failed_layers: '' # set at runtime: comma-separated list of layers that failed o
 
 - YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
 - All review subagents must run at the same model capability as the current session.
-- Run subagents synchronously: launch them together, then wait for all results before continuing.
+- Run subagents synchronously: launch them together as blocking calls awaited in this turn — never backgrounded or detached, never ending the turn to await results.
 
 ## INSTRUCTIONS
 

package/src/bmm-skills/ship/bmad-correct-course/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bmad-correct-course
-description: 'Manage significant changes during sprint execution. Use when the user says "correct course" or "propose sprint change"'
+description: 'Assess the impact of a significant change during sprint execution across the PRD, epics, architecture, and UX documents, and produce a sprint change proposal. Use when the user says "correct course" or "propose sprint change"'
 ---
 
 # Correct Course - Sprint Change Management Workflow

package/src/bmm-skills/ship/bmad-qa-generate-e2e-tests/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bmad-qa-generate-e2e-tests
-description: 'Generate end to end automated tests for existing features. Use when the user says "create qa automated tests for [feature]"'
+description: 'Generate automated API and end-to-end tests for implemented features. Use when the user says "create qa automated tests for [feature]"'
 ---
 
 # QA Generate E2E Tests Workflow

package/src/bmm-skills/ship/bmad-retrospective/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bmad-retrospective
-description: 'Evidence-based epic retrospective — collect what the epic produced, verify findings against sources, render an acceptance verdict. Use when the user says "run a retrospective" or "lets retro the epic [epic]". Supports -H/--headless.'
+description: 'Review a completed epic against the evidence it left behind — spec, stories, diffs, commits, sprint status — and produce a retrospective with sourced findings, action items, and an acceptance decision. Use when the user says "run a retrospective" or "lets retro the epic [epic]". Supports -H/--headless'
 ---
 
 # Retrospective

package/src/bmm-skills/v6-shims/bmad-create-architecture/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: bmad-create-architecture
-description: 'Deprecated — forwards to bmad-architecture (create intent).'
+description: 'Deprecated — forwards to bmad-architecture (create intent)'
+metadata:
+  lifecycle: shim
 ---
 
 # DEPRECATED — forwards to bmad-architecture (create intent)

package/src/bmm-skills/v6-shims/bmad-create-prd/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: bmad-create-prd
-description: 'Deprecated — forwards to bmad-prd (create intent).'
+description: 'Deprecated — forwards to bmad-prd (create intent)'
+metadata:
+  lifecycle: shim
 ---
 
 # DEPRECATED — forwards to bmad-prd (create intent)

package/src/bmm-skills/v6-shims/bmad-create-story/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: bmad-create-story
-description: "Deprecated: `bmad-build` is now the official implementation method. Only use this when explicitly invoked by name."
+description: "Deprecated: `bmad-build` is now the official implementation method. Only use this when explicitly invoked by name"
+metadata:
+  lifecycle: shim
 ---
 
 # Create Story Workflow

package/src/bmm-skills/v6-shims/bmad-dev-auto/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: bmad-dev-auto
-description: "Deprecated: forwards to bmad-build-auto. Do not use unless invoked by name."
+description: "Deprecated: forwards to bmad-build-auto. Do not use unless invoked by name"
+metadata:
+  lifecycle: shim
 ---
 
 # Deprecated Build Auto Alias