bmad-method 6.10.1-next.8 → 6.11.0

package/src/bmm-skills/{1-analysis → agents}/bmad-agent-analyst/customize.toml

@@ -62,17 +62,32 @@ skill = "bmad-brainstorming"
 [[agent.menu]]
 code = "MR"
 description = "Market analysis, competitive landscape, customer needs and trends"
-skill = "bmad-market-research"
+prompt = "Invoke the `bmad-deep-recon` skill with the market research type pre-selected (forwarded activation: skip type inference)."
 
 [[agent.menu]]
 code = "DR"
 description = "Industry domain deep dive, subject matter expertise and terminology"
-skill = "bmad-domain-research"
+prompt = "Invoke the `bmad-deep-recon` skill with the domain research type pre-selected (forwarded activation: skip type inference)."
 
 [[agent.menu]]
 code = "TR"
-description = "Technical feasibility, architecture options and implementation approaches"
-skill = "bmad-technical-research"
+description = "Technical landscape, architecture patterns and implementation reality"
+prompt = "Invoke the `bmad-deep-recon` skill with the technical research type pre-selected (forwarded activation: skip type inference)."
+
+[[agent.menu]]
+code = "TS"
+description = "Choose between technologies, vendors, or tools — decision matrix and recommendation"
+prompt = "Invoke the `bmad-deep-recon` skill in the select decision shape (forwarded activation: shape select; infer the subject type from the candidates)."
+
+[[agent.menu]]
+code = "CR"
+description = "Competitive teardown of named competitors — offers, pricing, positioning, trajectory"
+prompt = "Invoke the `bmad-deep-recon` skill with the competitive research type pre-selected (forwarded activation: skip type inference)."
+
+[[agent.menu]]
+code = "UV"
+description = "User-voice research — reviews, communities, jobs-to-be-done"
+prompt = "Invoke the `bmad-deep-recon` skill with the user-voice research type pre-selected (forwarded activation: skip type inference)."
 
 [[agent.menu]]
 code = "CB"
@@ -85,6 +100,6 @@ description = "Working Backwards PRFAQ challenge — forge and stress-test produ
 skill = "bmad-prfaq"
 
 [[agent.menu]]
-code = "DP"
-description = "Analyze an existing project to produce documentation for human and LLM consumption"
-skill = "bmad-document-project"
+code = "PC"
+description = "Set up or refresh this repo's agent instructions — verified commands, policy, conventions, pitfalls (setup, refresh, record, audit)"
+skill = "bmad-project-context"

package/src/bmm-skills/{3-solutioning → agents}/bmad-agent-architect/SKILL.md

@@ -20,7 +20,7 @@ You are Winston, the System Architect. You turn product requirements and UX into
 
 ### Step 1: Resolve the Agent Block
 
-Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key agent`
+Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key agent`
 
 **If the script fails**, resolve the `agent` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
 

package/src/bmm-skills/{3-solutioning → agents}/bmad-agent-architect/customize.toml

@@ -61,5 +61,5 @@ skill = "bmad-architecture"
 
 [[agent.menu]]
 code = "IR"
-description = "Ensure the PRD, UX, Architecture and Epics and Stories List are all aligned"
-skill = "bmad-check-implementation-readiness"
+description = "Check implementation readiness — verify the planning artifacts are complete and aligned (opens sprint planning; stop after the gate or continue into tracking)"
+skill = "bmad-sprint-planning"

package/src/bmm-skills/{4-implementation → agents}/bmad-agent-dev/SKILL.md

@@ -20,7 +20,7 @@ You are Amelia, the Senior Software Engineer. You execute approved stories with
 
 ### Step 1: Resolve the Agent Block
 
-Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key agent`
+Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key agent`
 
 **If the script fails**, resolve the `agent` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
 

package/src/bmm-skills/{4-implementation → agents}/bmad-agent-dev/customize.toml

@@ -48,6 +48,9 @@ principles = [
   "No task complete without passing tests.",
   "Red, green, refactor — in that order.",
   "Tasks executed in the sequence written.",
+  "Never add epic or story references as inline code comments (e.g. # Epic: X, # Story: PROJ-42).",
+  "Code comments explain why, not what — no AI workflow metadata, planning refs, or story tracking in source code.",
+  "Generated code must be production-ready: clean, minimal, and free of AI-generated noise.",
 ]
 
 # Capabilities menu. Overrides merge by `code`: matching codes replace the item
@@ -55,14 +58,9 @@ principles = [
 # registered skill by name) or `prompt` (executes the prompt text directly).
 
 [[agent.menu]]
-code = "DS"
-description = "Write the next or specified story's tests and code"
-skill = "bmad-dev-story"
-
-[[agent.menu]]
-code = "QD"
-description = "Unified quick flow — clarify intent, plan, implement, review, present"
-skill = "bmad-quick-dev"
+code = "BD"
+description = "Implement a feature, fix, or story"
+skill = "bmad-build"
 
 [[agent.menu]]
 code = "QA"
@@ -79,12 +77,7 @@ code = "SP"
 description = "Generate or update the sprint plan that sequences tasks for implementation"
 skill = "bmad-sprint-planning"
 
-[[agent.menu]]
-code = "CS"
-description = "Prepare a story with all required context for implementation"
-skill = "bmad-create-story"
-
 [[agent.menu]]
 code = "ER"
-description = "Party mode review of all work completed across an epic"
+description = "Evidence-based review of a completed epic against its acceptance criteria"
 skill = "bmad-retrospective"

package/src/bmm-skills/{2-plan-workflows → agents}/bmad-agent-pm/SKILL.md

@@ -20,7 +20,7 @@ You are John, the Product Manager. You drive PRD creation through user interview
 
 ### Step 1: Resolve the Agent Block
 
-Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key agent`
+Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key agent`
 
 **If the script fails**, resolve the `agent` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
 

package/src/bmm-skills/{2-plan-workflows → agents}/bmad-agent-pm/customize.toml

@@ -66,8 +66,8 @@ skill = "bmad-create-epics-and-stories"
 
 [[agent.menu]]
 code = "IR"
-description = "Ensure the PRD, UX, Architecture and Epics and Stories List are all aligned"
-skill = "bmad-check-implementation-readiness"
+description = "Check implementation readiness — verify the planning artifacts are complete and aligned (opens sprint planning; stop after the gate or continue into tracking)"
+skill = "bmad-sprint-planning"
 
 [[agent.menu]]
 code = "CC"

package/src/bmm-skills/{2-plan-workflows → agents}/bmad-agent-ux-designer/SKILL.md

@@ -20,7 +20,7 @@ You are Sally, the UX Designer. You translate user needs into interaction design
 
 ### Step 1: Resolve the Agent Block
 
-Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key agent`
+Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key agent`
 
 **If the script fails**, resolve the `agent` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
 

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

@@ -1,31 +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-document-project,Document Project,DP,Analyze an existing project to produce useful documentation.,,,anytime,,,false,project-knowledge,*
-BMad Method,bmad-generate-project-context,Generate Project Context,GPC,Scan existing codebase to generate a lean LLM-optimized project-context.md. Essential for brownfield projects.,,,anytime,,,false,output_folder,project context
-BMad Method,bmad-quick-dev,Quick Dev,QQ,Unified intent-in code-out workflow: clarify plan implement review and present.,,,anytime,,,false,implementation_artifacts,spec and project implementation
+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-agent-tech-writer,Write Document,WD,"Describe in detail what you want, and the agent will follow documentation best practices. Multi-turn conversation with subprocess for research/review.",write,,anytime,,,false,project-knowledge,document
-BMad Method,bmad-agent-tech-writer,Update Standards,US,Update agent memory documentation-standards.md with your specific preferences if you discover missing document conventions.,update-standards,,anytime,,,false,_bmad/_memory/tech-writer-sidecar,standards
-BMad Method,bmad-agent-tech-writer,Mermaid Generate,MG,Create a Mermaid diagram based on user description. Will suggest diagram types if not specified.,mermaid,,anytime,,,false,planning_artifacts,mermaid diagram
-BMad Method,bmad-agent-tech-writer,Validate Document,VD,Review the specified document against documentation standards and best practices. Returns specific actionable improvement suggestions organized by priority.,validate,[path],anytime,,,false,planning_artifacts,validation report
-BMad Method,bmad-agent-tech-writer,Explain Concept,EC,Create clear technical explanations with examples and diagrams for complex concepts.,explain,[topic],anytime,,,false,project_knowledge,explanation
-BMad Method,bmad-brainstorming,Brainstorm Project,BP,Expert guided facilitation through a single or multiple techniques.,,,1-analysis,,,false,planning_artifacts,brainstorming session
-BMad Method,bmad-market-research,Market Research,MR,Market analysis competitive landscape customer needs and trends.,,,1-analysis,,,false,planning_artifacts|project-knowledge,research documents
-BMad Method,bmad-domain-research,Domain Research,DR,Industry domain deep dive subject matter expertise and terminology.,,,1-analysis,,,false,planning_artifacts|project_knowledge,research documents
-BMad Method,bmad-technical-research,Technical Research,TR,Technical feasibility architecture options and implementation approaches.,,,1-analysis,,,false,planning_artifacts|project_knowledge,research documents
-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,1-analysis,,,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,1-analysis,,,false,planning_artifacts,prfaq document
+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).,,,3-solutioning,,,true,planning_artifacts,architecture
-BMad Method,bmad-create-epics-and-stories,Create Epics and Stories,CE,,,,3-solutioning,bmad-architecture,,true,planning_artifacts,epics and stories
-BMad Method,bmad-check-implementation-readiness,Check Implementation Readiness,IR,Ensure PRD UX Architecture and Epics Stories are aligned.,,,3-solutioning,bmad-create-epics-and-stories,,true,planning_artifacts,readiness report
-BMad Method,bmad-sprint-planning,Sprint Planning,SP,Kicks off implementation by producing a plan the implementation agents will follow in sequence for every story.,,,4-implementation,,,true,implementation_artifacts,sprint status
-BMad Method,bmad-sprint-status,Sprint Status,SS,Anytime: Summarize sprint status and route to next workflow.,,,4-implementation,bmad-sprint-planning,,false,,
-BMad Method,bmad-create-story,Create Story,CS,Story cycle start: Prepare first found story in the sprint plan that is next or a specific epic/story designation.,create,,4-implementation,bmad-sprint-planning,bmad-create-story:validate,true,implementation_artifacts,story
-BMad Method,bmad-create-story,Validate Story,VS,Validates story readiness and completeness before development work begins.,validate,,4-implementation,bmad-create-story:create,bmad-dev-story,false,implementation_artifacts,story validation report
-BMad Method,bmad-dev-story,Dev Story,DS,Story cycle: Execute story implementation tasks and tests then CR then back to DS if fixes needed.,,,4-implementation,bmad-create-story:validate,,true,,
-BMad Method,bmad-code-review,Code Review,CR,Story cycle: If issues back to DS if approved then next CS or ER if epic complete.,,,4-implementation,bmad-dev-story,,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.,,,4-implementation,,,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.,,,4-implementation,bmad-dev-story,,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.,,,4-implementation,bmad-code-review,,false,implementation_artifacts,retrospective
+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

package/src/bmm-skills/module.yaml

@@ -1,6 +1,6 @@
 code: bmm
 name: "BMad Method"
-description: "Full-lifecycle AI agile development: analysis, planning, architecture, implementation"
+description: "Agile Ai Driven Development"
 default_selected: true # This module will be selected by default for new installations
 
 # Variables from Core Config inserted:
@@ -30,8 +30,8 @@ planning_artifacts: # Phase 1-3 artifacts
   default: "{output_folder}/planning-artifacts"
   result: "{project-root}/{value}"
 
-implementation_artifacts: # Phase 4 artifacts and quick-dev flow output
-  prompt: "Where should implementation artifacts be stored? (Sprint status, stories, reviews, retrospectives, Quick Flow output)"
+implementation_artifacts: # Phase 4 artifacts and build flow output
+  prompt: "Where should implementation artifacts be stored? (Sprint status, stories, reviews, retrospectives, Build output)"
   default: "{output_folder}/implementation-artifacts"
   result: "{project-root}/{value}"
 
@@ -40,11 +40,8 @@ project_knowledge: # Artifacts from research, document-project output, other lon
   default: "docs"
   result: "{project-root}/{value}"
 
-# Directories to create during installation (declarative, no code execution)
-directories:
-  - "{planning_artifacts}"
-  - "{implementation_artifacts}"
-  - "{project_knowledge}"
+# No pre-created directories: planning_artifacts, implementation_artifacts, and
+# project_knowledge are created lazily by whichever skill first writes to them.
 
 # Agent roster — essence only. External skills (party-mode, retrospective,
 # advanced-elicitation, help catalog) read these descriptors to route, display,
@@ -59,13 +56,6 @@ agents:
     team: software-development
     description: "Channels Porter's strategic rigor and Minto's Pyramid Principle, grounds every finding in verifiable evidence, represents every stakeholder voice. Speaks like a treasure hunter narrating the find: thrilled by every clue, precise once the pattern emerges."
 
-  - code: bmad-agent-tech-writer
-    name: Paige
-    title: Technical Writer
-    icon: "📚"
-    team: software-development
-    description: "Master of CommonMark, DITA, and OpenAPI; turns complex concepts into accessible structured docs, favors diagrams over walls of text, every word earning its place. Speaks like the patient teacher you wish you'd had, using analogies that make complex things feel simple."
-
   - code: bmad-agent-pm
     name: John
     title: Product Manager

package/src/bmm-skills/{3-solutioning → plan}/bmad-architecture/SKILL.md

@@ -48,10 +48,10 @@ Writes go through the shared script (don't read the file back except on resume):
 
 ## On Activation
 
-**Forwarded activation:** if a caller (e.g. the `bmad-create-architecture` shim) invoked you with a stated intent and pre-resolved customization fields, honor them verbatim — skip your own intent inference, use the supplied values for those named fields, and resolve only the remaining fields from your own `customize.toml`.
+**Forwarded activation:** if a caller invoked you with a stated intent and pre-resolved customization fields, honor them verbatim — skip your own intent inference, use the supplied values for those named fields, and resolve only the remaining fields from your own `customize.toml`.
 
 1. Resolve customization: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow` (on failure read `{skill-root}/customize.toml`, use defaults). Run `{workflow.activation_steps_prepend}`, then `{workflow.activation_steps_append}`. Hold `{workflow.persistent_facts}` as standing context — the default loads `project-context.md`, load-bearing for brownfield — and consult `{workflow.external_sources}` on demand.
-2. Load `{project-root}/_bmad/bmm/config.yaml` (+ `config.user.yaml`) for `{user_name}`, `{communication_language}`, `{document_output_language}`, `{planning_artifacts}`, `{project_name}`, `{date}`; missing keys take neutral defaults, never block.
+2. Resolve config: `uv run {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root}` (merges `_bmad/config.toml`, `_bmad/config.user.toml`, and the `_bmad/custom/` overrides). From the merged JSON resolve `{user_name}`, `{communication_language}`, `{document_output_language}`, `{project_name}` (under `core`), `{planning_artifacts}` (under `modules.bmm`), and `{date}`; missing keys take neutral defaults, never block.
 3. Headless (no interactive user) → follow `references/headless.md` for the whole run. Otherwise greet `{user_name}` in `{communication_language}`. Detect the intent from the conversation and input — **create** (the default), **update** an existing spine, or **validate** one (see those sections). If the real ask is requirements / UX / a capability contract / epic breakdown / an agent, invoke the `bmad-prd`, `bmad-ux`, `bmad-spec`, `bmad-create-epics-and-stories`, or `bmad-workflow-builder` (if the BMad Builder module is installed) skill instead.
 4. If a run folder for this target already exists under `{workflow.spine_output_path}`, offer to resume from its memlog rather than restart.
 5. Interactive create: offer the working mode in `{communication_language}` — **Coaching path** (default) or **Fast path** (see *How you work*) — before any drafting; default to Coaching unless the user asks for speed.
@@ -73,7 +73,7 @@ Walk the sequence; reviewer fixes land before polish.
 4. **Triage.** Open questions and `[ASSUMPTION]` tags: blockers (unsafe for what's next) resolved one at a time; the rest deferred with a revisit condition in the memlog.
 5. **Renderings & polish.** The spine is the build deliverable; with it and the memlog now in place, produce any *additional* human-facing artifact the user needs, scoped to the purpose and audience drawn out up front. The up-front question already flagged whether one's needed; if it wasn't, still offer one here, seeding concrete options: an interactive HTML+SVG deck to walk a team through the architecture and drive discussion, a fuller HTML/md solution design, a C4 set, or a view of how the work splits across teams/epics. Build only what they pick, right-sized to that purpose; apply `{workflow.doc_standards}` polish to that prose only, never to the spine.
 6. **External handoffs.** Run `{workflow.external_handoffs}`; surface returned URLs/IDs. Offer to invoke the `bmad-spec` skill to adopt the spine as a companion, keeping `AD` IDs stable so downstream can cite them.
-7. **Close.** Set the spine's own frontmatter `status: final`, `updated: {date}`; log a `memlog.py append --type event --text "spine finalized"` (the memlog has no status field). Share paths. Next, **lead with `bmad-spec`** — recommend adopting/refreshing the spine as a spec companion (always the top recommendation when a spec was an input, and a useful next step even when it wasn't), then `bmad-create-epics-and-stories` or — epic altitude — `bmad-create-story`; or invoke `bmad-help` to route.
+7. **Close.** Set the spine's own frontmatter `status: final`, `updated: {date}`; log a `memlog.py append --type event --text "spine finalized"` (the memlog has no status field). Share paths. Next, **lead with `bmad-spec`** — recommend adopting/refreshing the spine as a spec companion (always the top recommendation when a spec was an input, and a useful next step even when it wasn't), then `bmad-create-epics-and-stories` or — epic altitude — `bmad-build`; or invoke `bmad-help` to route.
 8. Run `{workflow.on_complete}`.
 
 ## Update

package/src/bmm-skills/{3-solutioning → plan}/bmad-architecture/customize.toml

@@ -59,9 +59,11 @@ run_folder_pattern = "architecture-{project_name}-{date}"
 # short, structured outputs, which are terse and carry decisions in AD-n blocks and diagrams by
 # design. Each entry is a `skill:`, `file:`, or plain-text directive applied before the user sees
 # the polished draft. Suggested order: structural passes first, prose mechanics last. Append-only.
+# The default entry runs bmad-review's two editorial lenses in order:
+# structure, then prose on top of the structure findings. The `lenses=` suffix
+# names them; drop it to let bmad-review pick what fits the content.
 doc_standards = [
-  "skill:bmad-editorial-review-structure",
-  "skill:bmad-editorial-review-prose",
+  "skill:bmad-review lenses=structure,prose",
 ]
 
 # External-source registry. Natural-language directives describing knowledge bases, MCP tools, or

package/src/bmm-skills/{3-solutioning → plan}/bmad-create-epics-and-stories/SKILL.md

@@ -51,7 +51,7 @@ This uses **step-file architecture** for disciplined execution:
 
 ### Step 1: Resolve the Workflow Block
 
-Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`
+Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`
 
 **If the script fails**, resolve the `workflow` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
 

package/src/bmm-skills/{3-solutioning → plan}/bmad-create-epics-and-stories/steps/step-04-final-validation.md

@@ -138,6 +138,6 @@ Upon Completion of task output: offer to answer any questions about the Epics an
 
 ## On Complete
 
-Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete`
+Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete`
 
 If the resolved `workflow.on_complete` is non-empty, follow it as the final terminal instruction before exiting.

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

@@ -0,0 +1,10 @@
+---
+name: bmad-generate-project-context
+description: 'Deprecated — forwards to bmad-project-context. Use when the user says "generate project context" or "create project context"'
+---
+
+# DEPRECATED — forwards to bmad-project-context
+
+Tell the user: this skill is deprecated — `bmad-project-context` now owns this job. Instead of one generated `project-context.md`, it writes a small verified block inside the repo's `AGENTS.md`, and any existing `project-context.md` is offered up for absorption rather than left orphaned. Invoke `bmad-project-context` next time.
+
+Then invoke `bmad-project-context` with **setup** intent, forwarding the user's original request and any inputs they supplied (architecture doc, spec, standards, preferences), verbatim. It takes the workflow from here.

package/src/bmm-skills/{2-plan-workflows → plan}/bmad-prd/SKILL.md

@@ -15,10 +15,12 @@ You are a master facilitator and coach helping the user create, edit, or validat
 
 ## On Activation
 
+**Forwarded activation:** if a caller invoked you with a stated intent and pre-resolved customization fields (e.g. the `bmad-create-prd` / `bmad-edit-prd` / `bmad-validate-prd` shims), honor them verbatim — skip your own intent inference, use the supplied values for those named fields, and resolve only the remaining fields from your own `customize.toml`.
+
 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.
 2. Run `{workflow.activation_steps_prepend}`. Treat `{workflow.persistent_facts}` as foundational context (entries prefixed `file:` are loaded). `{workflow.external_sources}` is an org-configured registry of internal tools (knowledge bases, MCP tools); consult them alongside generic web research on the same triggers, org tools preferred when their directive matches. Research itself fires during Discovery — see **Research subagents**.
 3. Load `{project-root}/_bmad/bmm/config.yaml` (+ `config.user.yaml` if present). Resolve `{user_name}`, `{communication_language}`, `{document_output_language}`, `{planning_artifacts}`, `{project_name}`, `{date}`. Missing keys → neutral defaults; never block.
-4. If headless, follow `references/headless.md` for the whole run. Otherwise greet the user **by name** using `{user_name}` and **in their language** using `{communication_language}` — and stay in `{communication_language}` for every turn for the entire run, not just the greeting. In the greeting, let the user know that at any point they can invoke `bmad-party-mode` for multi-agent perspectives or `bmad-advanced-elicitation` for deeper exploration on a specific section. Then scan for misroute on the first message: if the signal points elsewhere (game → BMad GDS; express build → `bmad-quick-dev`; one-pager → `bmad-product-brief`; vet product idea → `bmad-prfaq`; agent skill or custom agent → `bmad-workflow-builder`), suggest they might want the other options before continuing.
+4. If headless, follow `references/headless.md` for the whole run. Otherwise greet the user **by name** using `{user_name}` and **in their language** using `{communication_language}` — and stay in `{communication_language}` for every turn for the entire run, not just the greeting. In the greeting, let the user know that at any point they can invoke `bmad-party-mode` for multi-agent perspectives or `bmad-advanced-elicitation` for deeper exploration on a specific section. Then scan for misroute on the first message: if the signal points elsewhere (game → BMad GDS; express build → `bmad-build`; one-pager → `bmad-product-brief`; vet product idea → `bmad-prfaq`; agent skill or custom agent → `bmad-workflow-builder`), suggest they might want the other options before continuing.
 5. Detect intent: **Create** (no PRD), **Update** (existing PRD), **Validate** (critique only). If ambiguous, ask. For Create intent, before binding a fresh workspace, scan `{workflow.prd_output_path}` for prior in-progress runs (folders matching `{workflow.run_folder_pattern}` whose `prd.md` frontmatter `status` is not `final`); if any exist, offer to resume rather than starting over.
 
 Run `{workflow.activation_steps_append}`.

package/src/bmm-skills/{2-plan-workflows → plan}/bmad-prd/assets/prd-template.md

@@ -161,5 +161,5 @@ updated: {YYYY-MM-DD}
 - **Environmental and Reliability Requirements**.
 
 ### Small-scope all-inclusive *(use when scope is 1-2 stories' worth and the user wants a single captured artifact — chosen during the Right-skill check in Discovery)*
-- **Stories** — story-level specs listed inline at the end of the doc. Each story: *"As a [persona], I can [action] [under conditions]. Acceptance: [testable criteria]."* Numbered Story-1, Story-2, ... for reference. Pair with very lean §1 Vision, §2 Target User (often just JTBD + one UJ), §3 Glossary (handful of terms), §4 Features (often a single feature), §6 MVP Scope (in/out very tight). The whole doc fits on a page or two and captures intent + implementable stories in one place. If the user doesn't want the captured artifact at all, `bmad-quick-dev` is the better path — this cluster is only for "I want a doc *and* the stories."
+- **Stories** — story-level specs listed inline at the end of the doc. Each story: *"As a [persona], I can [action] [under conditions]. Acceptance: [testable criteria]."* Numbered Story-1, Story-2, ... for reference. Pair with very lean §1 Vision, §2 Target User (often just JTBD + one UJ), §3 Glossary (handful of terms), §4 Features (often a single feature), §6 MVP Scope (in/out very tight). The whole doc fits on a page or two and captures intent + implementable stories in one place. If the user doesn't want the captured artifact at all, `bmad-build` is the better path — this cluster is only for "I want a doc *and* the stories."
 

package/src/bmm-skills/{2-plan-workflows → plan}/bmad-prd/customize.toml

@@ -71,7 +71,7 @@ run_folder_pattern = "prd-{project_name}-{date}"
 # findings before the user sees the draft. Encodes standards, not options.
 #
 # Examples:
-#   "skill:bmad-editorial-review-prose"
+#   "skill:bmad-review lenses=structure,prose"
 #   "file:{project-root}/_bmad/style-guides/company-voice.md"
 #   "Convert all dates to ISO 8601 format."
 #
@@ -82,9 +82,11 @@ run_folder_pattern = "prd-{project_name}-{date}"
 #
 # Override the array in team/user TOML to add additional standards. Append-only:
 # base entries cannot be removed or replaced (resolver has no removal mechanism).
+# The default entry runs bmad-review's two editorial lenses in order:
+# structure, then prose on top of the structure findings. The `lenses=` suffix
+# names them; drop it to let bmad-review pick what fits the content.
 doc_standards = [
-  "skill:bmad-editorial-review-structure",
-  "skill:bmad-editorial-review-prose",
+  "skill:bmad-review lenses=structure,prose",
 ]
 
 # External-source registry. Natural-language directives describing knowledge

package/src/bmm-skills/{2-plan-workflows → plan}/bmad-prd/references/validate.md

@@ -41,11 +41,11 @@ Once every selected reviewer has returned, the parent synthesizes one consolidat
    - **Footer.** Rubric path, ISO timestamp.
 3. Write the filled HTML to `{doc_workspace}/validation-report.html`.
 4. Write the markdown twin to `{doc_workspace}/validation-report.md` (same content, grouped by severity rather than by dimension — see format below; this is the canonical form for downstream re-reading).
-5. Open the HTML in the default browser:
+5. Open the HTML in the default browser with the platform opener — `open` on macOS, `xdg-open` on Linux, `start ""` on Windows — double-quoting the path:
    ```bash
-   python3 -c "import webbrowser, pathlib; webbrowser.open(pathlib.Path('{doc_workspace}/validation-report.html').resolve().as_uri())"
+   open "{doc_workspace}/validation-report.html"
    ```
-   Skip the open step in headless mode (see `references/headless.md`).
+   If the command fails, don't retry with another opener: tell the user the file path and move on. Skip the open step in headless mode (see `references/headless.md`).
 
 ### Markdown twin format
 

package/src/bmm-skills/{1-analysis → plan}/bmad-prfaq/SKILL.md

@@ -30,7 +30,7 @@ The PRFAQ forces customer-first clarity: write the press release announcing the
 
 ### Step 1: Resolve the Workflow Block
 
-Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`
+Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`
 
 **If the script fails**, resolve the `workflow` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
 

package/src/bmm-skills/{1-analysis → plan}/bmad-prfaq/bmad-manifest.json

@@ -6,7 +6,7 @@
       "menu-code": "WB",
       "description": "Produces battle-tested PRFAQ document and optional LLM distillate for PRD input.",
       "supports-headless": true,
-      "phase-name": "1-analysis",
+      "phase-name": "plan",
       "preceded-by": ["brainstorming", "perform-research"],
       "followed-by": ["create-prd"],
       "is-required": false,

package/src/bmm-skills/{1-analysis → plan}/bmad-prfaq/references/verdict.md

@@ -78,6 +78,6 @@ purpose: "Token-efficient context for downstream PRD creation"
 
 This is the terminal stage. If the user wants to revise, loop back to the relevant stage. Otherwise, the workflow is done.
 
-Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete`
+Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete`
 
 If the resolved `workflow.on_complete` is non-empty, follow it as the final terminal instruction before exiting.

package/src/bmm-skills/{1-analysis → plan}/bmad-product-brief/SKILL.md

@@ -64,7 +64,7 @@ Omit keys for artifacts that were not produced.
 
 ## Discovery
 
-Conversationally surface what the user brings, why this brief exists, the domain, and the form-factor (mobile / web / desktop / multi-surface / hardware / API — what *is* this thing) — echo back how each shapes your approach. Open with space for the full picture: invite a brain dump and ask up front for any source material they already have (memo, deck, transcript, prior brief, slack thread). Read what exists first; ask only what is missing. After the dump, a simple "anything else?" often surfaces what they almost forgot. Drill into specifics only after the broad shape is on the table; premature granular questions interrupt the dump and miss the room. Get a read on stakes early (passion project, internal pitch, investor input, public launch), and let that calibrate how hard you push. During the dump, spawn web-research subagents to ground the picture — landscape, comparables, current state — AI especially, where training data ages by the week. Subagent searches; parent gets a digest. Deep work (full market sizing, exhaustive teardowns) → suggest `bmad-market-research` or `bmad-domain-research`.
+Conversationally surface what the user brings, why this brief exists, the domain, and the form-factor (mobile / web / desktop / multi-surface / hardware / API — what *is* this thing) — echo back how each shapes your approach. Open with space for the full picture: invite a brain dump and ask up front for any source material they already have (memo, deck, transcript, prior brief, slack thread). Read what exists first; ask only what is missing. After the dump, a simple "anything else?" often surfaces what they almost forgot. Drill into specifics only after the broad shape is on the table; premature granular questions interrupt the dump and miss the room. Get a read on stakes early (passion project, internal pitch, investor input, public launch), and let that calibrate how hard you push. During the dump, spawn web-research subagents to ground the picture — landscape, comparables, current state — AI especially, where training data ages by the week. Subagent searches; parent gets a digest. Deep work (full market sizing, exhaustive teardowns) → suggest `bmad-deep-recon` (market or domain type).
 
 Once stakes are read and the dump is captured, offer the working mode in the user's language:
 

package/src/bmm-skills/{1-analysis → plan}/bmad-product-brief/customize.toml

@@ -53,7 +53,7 @@ run_folder_pattern = "brief-{project_name}-{date}"
 # findings before the user sees the draft. Encodes standards, not options.
 #
 # Examples:
-#   "skill:bmad-editorial-review-prose"
+#   "skill:bmad-review lenses=structure,prose"
 #   "file:{project-root}/_bmad/style-guides/company-voice.md"
 #   "Convert all dates to ISO 8601 format."
 #
@@ -64,9 +64,11 @@ run_folder_pattern = "brief-{project_name}-{date}"
 #
 # Override the array in team/user TOML to add additional standards. Append-only:
 # base entries cannot be removed or replaced (resolver has no removal mechanism).
+# The default entry runs bmad-review's two editorial lenses in order:
+# structure, then prose on top of the structure findings. The `lenses=` suffix
+# names them; drop it to let bmad-review pick what fits the content.
 doc_standards = [
-  "skill:bmad-editorial-review-structure",
-  "skill:bmad-editorial-review-prose",
+  "skill:bmad-review lenses=structure,prose",
 ]
 
 # External-source registry. Natural-language directives describing knowledge

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

@@ -0,0 +1,110 @@
+---
+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.'
+---
+
+# Overview
+
+A conversation that produces a repository's agent instructions: a small verified block inside `AGENTS.md`. The user brings rules they want followed — governance, security, standards — and the repository supplies the rest, 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.
+
+## Resolution rules
+
+- Bare paths and `{skill-root}` (e.g. `references/best-practices.md`) resolve from this skill's installed directory.
+- `{project-root}` → the project working directory.
+- **Target** → the repository being described, defaulting to `{project-root}`. If it resolves to more than one working tree, or to one the user cannot commit in, ask before writing.
+
+## On Activation
+
+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}`.
+
+## Setup and Refresh Steps
+
+No writes until step 5!
+
+### 1. Assess and report
+
+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`.
+
+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
+
+Rules to follow regardless of what the repo does: governance, security and compliance, coding standards, style guides, frozen areas. Ask for outside documents too — handbooks, wikis, architecture docs, MCP knowledgebases. Note the paths; do not read them yet.
+
+Greenfield: this is the whole content. Brownfield: it is the half no scan reaches.
+
+### 3. Discover and verify
+
+Fan out with parallel subagents against what the sections need — executable config and CI for policy and for what they already state, tracked source for conventions and boundaries, targeted history for constraints whose reason must still hold.
+
+`package.json`, a `Makefile`, `pyproject.toml`, and CI config are read to know what the block must not repeat. Their caveats come from the human in step 4. Path-check every claim naming a file.
+
+Each child agreed in step 1 is scanned as its own scope, against its own manifests.
+
+### 4. Interview the gaps
+
+Only what no scan reaches: what agents keep getting wrong here, what is off limits, what a domain term means, why a constraint exists.
+
+- Never ask what a scan could answer. Asking the user to confirm a path-checked claim, or one a config file already states, is a defect.
+- Ask recall questions, not review lists. Never hand the user a selection problem a scan created.
+- A mistake this session made and caught is observed evidence — offer it.
+- A repeatable command spotted in anything read this session — a log, a doc, its own runs — whose correct form is not the obvious guess is a candidate line: offer it. E.g. `uv run pytest` where plain `pytest` looks right but runs outside the project environment.
+- Batches of at most eight; fewer is better. A batch yielding nothing new means write.
+- When the repo contradicts the user, show the evidence and ask. Never write the claim as given, never drop it silently.
+
+### 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.
+
+**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.
+
+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.
+
+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.
+- 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.
+
+### Greenfield
+
+Seeded from a spec or planning document, or interview alone. Commands that do not exist yet are written as explicit TODOs naming the decided stack, never a guessed invocation stated as fact, and verified on the first refresh after code exists. A genuinely contested design decision — real tradeoffs, multiple viable shapes — goes to `bmad-architecture`.
+
+### Migration
+
+If the target has a `project-context.md` from the retired skills, commonly under `{output_folder}`, read it in step 1 and offer to absorb its content. Do not delete it without agreement, and do not silently orphan it.
+
+## Record
+
+Capture one observed agent mistake as it happens — the only admissible source for a pitfall line.
+
+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.
+
+## Audit
+
+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.
+
+## 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 chosen child that ends with nothing its parent does not already say gets no file. Say so and move on.
+
+List every child in the parent's **Where things are** with one line and its path. Discovery never depends on the harness finding it.