bmad-method 6.2.1-next.9 → 6.2.2

package/src/{bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview → bmm-skills/4-implementation/bmad-quick-dev}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: bmad-quick-dev-new-preview
+name: bmad-quick-dev
 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.'
 ---
 

package/src/{bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/tech-spec-template.md → bmm-skills/4-implementation/bmad-quick-dev/spec-template.md}

@@ -11,8 +11,6 @@ context: [] # optional: max 3 project-wide standards/docs. NO source code files.
      Cohesive cross-layer stories (DB+BE+UI) stay in ONE file.
      IMPORTANT: Remove all HTML comments when filling this template. -->
 
-# {title}
-
 <frozen-after-approval reason="human-owned intent — do not modify unless human renegotiates">
 
 ## Intent

package/src/{bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview → bmm-skills/4-implementation/bmad-quick-dev}/step-01-clarify-and-route.md

@@ -1,5 +1,5 @@
 ---
-wipFile: '{implementation_artifacts}/tech-spec-wip.md'
+wipFile: '{implementation_artifacts}/spec-wip.md'
 deferred_work_file: '{implementation_artifacts}/deferred-work.md'
 spec_file: '' # set at runtime for plan-code-review before leaving this step
 ---
@@ -15,13 +15,27 @@ spec_file: '' # set at runtime for plan-code-review before leaving this step
 - The user chose this workflow on purpose. Later steps (e.g. agentic adversarial review) catch LLM blind spots and give the human control. Do not skip them.
 - **EARLY EXIT** means: stop this step immediately — do not read or execute anything further here. Read and fully follow the target file instead. Return here ONLY if a later step explicitly says to loop back.
 
-## ARTIFACT SCAN
+## Intent check (do this first)
 
-- `{wipFile}` exists? → Offer resume or archive.
-- Active specs (`ready-for-dev`, `in-progress`, `in-review`) in `{implementation_artifacts}`? → List them and HALT. Ask user which to resume (or `[N]` for new).
-  - If `ready-for-dev` or `in-progress` selected: Set `spec_file`. **EARLY EXIT** → `./step-03-implement.md`
-  - If `in-review` selected: Set `spec_file`. **EARLY EXIT** → `./step-04-review.md`
-- Unformatted spec or intent file lacking `status` frontmatter in `{implementation_artifacts}`? → Suggest to the user to treat its contents as the starting intent for this workflow. DO NOT attempt to infer a state and resume it.
+Before listing artifacts or prompting the user, check whether you already know the intent. Check in this order — skip the remaining checks as soon as the intent is clear:
+
+1. Explicit argument
+   Did the user pass a specific file path, spec name, or clear instruction this message?
+   - If it points to a file that matches the spec template (has `status` frontmatter with a recognized value: ready-for-dev, in-progress, or in-review) → set `spec_file` and **EARLY EXIT** to the appropriate step (step-03 for ready/in-progress, step-04 for review).
+   - Anything else (intent files, external docs, plans, descriptions) → ingest it as starting intent and proceed to INSTRUCTIONS. Do not attempt to infer a workflow state from it.
+
+2. Recent conversation
+   Do the last few human messages clearly show what the user intends to work on?
+   Use the same routing as above.
+
+3. Otherwise — scan artifacts and ask
+   - `{wipFile}` exists? → Offer resume or archive.
+   - Active specs (`ready-for-dev`, `in-progress`, `in-review`) in `{implementation_artifacts}`? → List them and HALT. Ask user which to resume (or `[N]` for new).
+     - If `ready-for-dev` or `in-progress` selected: Set `spec_file`. **EARLY EXIT** → `./step-03-implement.md`
+     - If `in-review` selected: Set `spec_file`. **EARLY EXIT** → `./step-04-review.md`
+   - Unformatted spec or intent file lacking `status` frontmatter? → Suggest treating its contents as the starting intent. Do NOT attempt to infer a state and resume it.
+
+Never ask extra questions if you already understand what the user intends.
 
 ## INSTRUCTIONS
 
@@ -42,7 +56,7 @@ spec_file: '' # set at runtime for plan-code-review before leaving this step
    **EARLY EXIT** → `./step-oneshot.md`
 
    **b) Plan-code-review** — everything else. When uncertain whether blast radius is truly zero, choose this path.
-   1. Derive a valid kebab-case slug from the clarified intent. If `{implementation_artifacts}/tech-spec-{slug}.md` already exists, append `-2`, `-3`, etc. Set `spec_file` = `{implementation_artifacts}/tech-spec-{slug}.md`.
+   1. Derive a valid kebab-case slug from the clarified intent. If the intent references a tracking identifier (story number, issue number, ticket ID), lead the slug with it (e.g. `3-2-digest-delivery`, `gh-47-fix-auth`). If `{implementation_artifacts}/spec-{slug}.md` already exists, append `-2`, `-3`, etc. Set `spec_file` = `{implementation_artifacts}/spec-{slug}.md`.
 
 
 ## NEXT

package/src/{bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview → bmm-skills/4-implementation/bmad-quick-dev}/step-02-plan.md

@@ -1,5 +1,5 @@
 ---
-wipFile: '{implementation_artifacts}/tech-spec-wip.md'
+wipFile: '{implementation_artifacts}/spec-wip.md'
 deferred_work_file: '{implementation_artifacts}/deferred-work.md'
 ---
 
@@ -13,7 +13,7 @@ deferred_work_file: '{implementation_artifacts}/deferred-work.md'
 ## INSTRUCTIONS
 
 1. Investigate codebase. _Isolate deep exploration in sub-agents/tasks where available. To prevent context snowballing, instruct subagents to give you distilled summaries only._
-2. Read `./tech-spec-template.md` fully. Fill it out based on the intent and investigation, and write the result to `{wipFile}`.
+2. Read `./spec-template.md` fully. Fill it out based on the intent and investigation, and write the result to `{wipFile}`.
 3. Self-review against READY FOR DEVELOPMENT standard.
 4. If intent gaps exist, do not fantasize, do not leave open questions, HALT and ask the human.
 5. Token count check (see SCOPE STANDARD). If spec exceeds 1600 tokens:
@@ -26,7 +26,7 @@ deferred_work_file: '{implementation_artifacts}/deferred-work.md'
 
 Present summary. If token count exceeded 1600 and user chose [K], include the token count and explain why it may be a problem. HALT and ask human: `[A] Approve` | `[E] Edit`
 
-- **A**: Rename `{wipFile}` to `{spec_file}`, set status `ready-for-dev`. Everything inside `<frozen-after-approval>` is now locked — only the human can change it. → Step 3.
+- **A**: Rename `{wipFile}` to `{spec_file}`, set status `ready-for-dev`. Everything inside `<frozen-after-approval>` is now locked — only the human can change it. Display the finalized spec path to the user as a CWD-relative path (no leading `/`) so it is clickable in the terminal. → Step 3.
 - **E**: Apply changes, then return to CHECKPOINT 1.
 
 

package/src/{bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview → bmm-skills/4-implementation/bmad-quick-dev}/step-03-implement.md

@@ -26,6 +26,12 @@ Change `{spec_file}` status to `in-progress` in the frontmatter before starting
 
 Hand `{spec_file}` to a sub-agent/task and let it implement. If no sub-agents are available, implement directly.
 
+**Path formatting rule:** Any markdown links written into `{spec_file}` must use paths relative to `{spec_file}`'s directory so they are clickable in VS Code. Any file paths displayed in terminal/conversation output must use CWD-relative format with `:line` notation (e.g., `src/path/file.ts:42`) for terminal clickability. No leading `/` in either case.
+
+### Self-Check
+
+Before leaving this step, verify every task in the `## Tasks & Acceptance` section of `{spec_file}` is complete. Mark each finished task `[x]`. If any task is not done, finish it before proceeding.
+
 ## NEXT
 
 Read fully and follow `./step-04-review.md`

package/src/{bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview → bmm-skills/4-implementation/bmad-quick-dev}/step-05-present.md

@@ -22,7 +22,7 @@ Build the trail as an ordered sequence of **stops** — clickable `path:line` re
 2. **Lead with the entry point** — the single highest-leverage file:line a reviewer should look at first to grasp the design intent.
 3. **Inside each concern**, order stops from most important / architecturally interesting to supporting. Lightly bias toward higher-risk or boundary-crossing stops.
 4. **End with peripherals** — tests, config, types, and other supporting changes come last.
-5. **Every code reference is a clickable workspace-relative link.** Format each stop as a markdown link: `[short-name:line](/project-root-relative/path/to/file.ts#L42)`. The link target uses a leading `/` (workspace root) with a `#L` line anchor. Use the file's basename (or shortest unambiguous suffix) plus line number as the link text.
+5. **Every code reference is a clickable spec-file-relative link.** Compute each link target as a relative path from `{spec_file}`'s directory to the changed file. Format each stop as a markdown link: `[short-name:line](../../path/to/file.ts#L42)`. Use a `#L` line anchor. Use the file's basename (or shortest unambiguous suffix) plus line number as the link text. The relative path must be dynamically derived — never hardcode the depth.
 6. **Each stop gets one ultra-concise line of framing** (≤15 words) — why this approach was chosen here and what it achieves in the context of the change. No paragraphs.
 
 Format each stop as framing first, link on the next indented line:
@@ -33,17 +33,19 @@ Format each stop as framing first, link on the next indented line:
 **{Concern name}**
 
 - {one-line framing}
-  [`file.ts:42`](/src/path/to/file.ts#L42)
+  [`file.ts:42`](../../src/path/to/file.ts#L42)
 
 - {one-line framing}
-  [`other.ts:17`](/src/path/to/other.ts#L17)
+  [`other.ts:17`](../../src/path/to/other.ts#L17)
 
 **{Next concern}**
 
 - {one-line framing}
-  [`file.ts:88`](/src/path/to/file.ts#L88)
+  [`file.ts:88`](../../src/path/to/file.ts#L88)
 ```
 
+> The `../../` prefix above is illustrative — compute the actual relative path from `{spec_file}`'s directory to each target file.
+
 When there is only one concern, omit the bold label — just list the stops directly.
 
 ### Commit and Present
@@ -51,9 +53,9 @@ When there is only one concern, omit the bold label — just list the stops dire
 1. Change `{spec_file}` status to `done` in the frontmatter.
 2. If version control is available and the tree is dirty, create a local commit with a conventional message derived from the spec title.
 3. Open the spec in the user's editor so they can click through the Suggested Review Order:
-   - Run `code -r "{spec_file}"` to open the spec in the current VS Code window (reuses the window where the project or worktree is open). Always double-quote the path to handle spaces and special characters.
+   - Resolve two absolute paths: (1) the repository root (`git rev-parse --show-toplevel` — returns the worktree root when in a worktree, project root otherwise; if this fails, fall back to the current working directory), (2) `{spec_file}`. Run `code -r "{absolute-root}" "{absolute-spec-file}"` — the root first so VS Code opens in the right context, then the spec file. Always double-quote paths to handle spaces and special characters.
    - If `code` is not available (command fails), skip gracefully and tell the user the spec file path instead.
-4. Display summary of your work to the user, including the commit hash if one was created. Include:
+4. Display summary of your work to the user, including the commit hash if one was created. Any file paths shown in conversation/terminal output must use CWD-relative format (no leading `/`) with `:line` notation (e.g., `src/path/file.ts:42`) for terminal clickability — the goal is to make paths clickable in terminal emulators. Include:
    - A note that the spec is open in their editor (or the file path if it couldn't be opened). Mention that `{spec_file}` now contains a Suggested Review Order.
    - **Navigation tip:** "Ctrl+click (Cmd+click on macOS) the links in the Suggested Review Order to jump to each stop."
    - Offer to push and/or create a pull request.

package/src/{bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview → bmm-skills/4-implementation/bmad-quick-dev}/step-oneshot.md

@@ -36,11 +36,11 @@ If version control is available and the tree is dirty, create a local commit wit
 ### Present
 
 1. Open all changed files in the user's editor so they can review the code directly:
-   - Run `code -r "{project-root}" <changed-file-paths>` — the project root as the first argument, then each changed file path. Always double-quote paths with spaces.
+   - Resolve two sets of absolute paths: (1) the repository root (`git rev-parse --show-toplevel` — returns the worktree root when in a worktree, project root otherwise; if this fails, fall back to the current working directory), (2) each changed file. Run `code -r "{absolute-root}" <absolute-changed-file-paths>` — the root first so VS Code opens in the right context, then each changed file. Always double-quote paths to handle spaces and special characters.
    - If `code` is not available (command fails), skip gracefully and list the file paths instead.
 2. Display a summary in conversation output, including:
    - The commit hash (if one was created).
-   - List of files changed with one-line descriptions.
+   - List of files changed with one-line descriptions. Use CWD-relative paths with `:line` notation (e.g., `src/path/file.ts:42`) for terminal clickability. No leading `/`.
    - Review findings breakdown: patches applied, items deferred, items rejected. If all findings were rejected, say so.
 3. Offer to push and/or create a pull request.
 

package/src/{bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview → bmm-skills/4-implementation/bmad-quick-dev}/workflow.md

@@ -4,9 +4,9 @@ main_config: '{project-root}/_bmad/bmm/config.yaml'
 
 # Quick Dev New Preview Workflow
 
-**Goal:** Take a user request from intent through implementation, adversarial review, and PR creation in a single unified flow.
+**Goal:** Turn user intent into a hardened, reviewable artifact.
 
-**Your Role:** You are an elite developer. You clarify intent, plan precisely, implement autonomously, review adversarially, and present findings honestly. Minimum ceremony, maximum signal.
+**CRITICAL:** If a step says "read fully and follow step-XX", you read and follow step-XX. No exceptions.
 
 
 ## READY FOR DEVELOPMENT STANDARD
@@ -72,7 +72,7 @@ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `
 
 ### 2. Paths
 
-- `wipFile` = `{implementation_artifacts}/tech-spec-wip.md`
+- `wipFile` = `{implementation_artifacts}/spec-wip.md`
 
 ### 3. First Step Execution
 

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

@@ -0,0 +1,30 @@
+module,skill,display-name,menu-code,description,action,args,phase,after,before,required,output-location,outputs
+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-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,A guided experience to nail down your product idea.,,1-analysis,,,false,planning_artifacts,product brief
+BMad Method,bmad-create-prd,Create PRD,CP,Expert led facilitation to produce your Product Requirements Document.,,2-planning,,,true,planning_artifacts,prd
+BMad Method,bmad-validate-prd,Validate PRD,VP,,,[path],2-planning,bmad-create-prd,,false,planning_artifacts,prd validation report
+BMad Method,bmad-edit-prd,Edit PRD,EP,,,[path],2-planning,bmad-validate-prd,,false,planning_artifacts,updated prd
+BMad Method,bmad-create-ux-design,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-create-prd,,false,planning_artifacts,ux design
+BMad Method,bmad-create-architecture,Create Architecture,CA,Guided workflow to document technical decisions.,,3-solutioning,,,true,planning_artifacts,architecture
+BMad Method,bmad-create-epics-and-stories,Create Epics and Stories,CE,,,3-solutioning,bmad-create-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-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

package/src/{core/skills/bmad-advanced-elicitation/workflow.md → core-skills/bmad-advanced-elicitation/SKILL.md}

@@ -1,8 +1,10 @@
 ---
+name: bmad-advanced-elicitation
+description: 'Push the LLM to reconsider, refine, and improve its recent output. Use when user asks for deeper critique or mentions a known deeper critique method, e.g. socratic, first principles, pre-mortem, red team.'
 agent_party: '{project-root}/_bmad/_config/agent-manifest.csv'
 ---
 
-# Advanced Elicitation Workflow
+# Advanced Elicitation
 
 **Goal:** Push the LLM to reconsider, refine, and improve its recent output.
 

package/src/{core/skills/bmad-editorial-review-prose/workflow.md → core-skills/bmad-editorial-review-prose/SKILL.md}

@@ -1,3 +1,8 @@
+---
+name: bmad-editorial-review-prose
+description: 'Clinical copy-editor that reviews text for communication issues. Use when user says review for prose or improve the prose'
+---
+
 # Editorial Review - Prose
 
 **Goal:** Review text for communication issues that impede comprehension and output suggested fixes in a three-column table.

package/src/{core/skills/bmad-editorial-review-structure/workflow.md → core-skills/bmad-editorial-review-structure/SKILL.md}

@@ -1,3 +1,8 @@
+---
+name: bmad-editorial-review-structure
+description: 'Structural editor that proposes cuts, reorganization, and simplification while preserving comprehension. Use when user requests structural review or editorial review of structure'
+---
+
 # Editorial Review - Structure
 
 **Goal:** Review document structure and propose substantive changes to improve clarity and flow -- run this BEFORE copy editing.

package/src/core-skills/bmad-help/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: bmad-help
+description: 'Analyzes current state and user query to answer BMad questions or recommend the next skill(s) to use. Use when user asks for help, bmad help, what to do next, or what to start with in BMad.'
+---
+
+# BMad Help
+
+## Purpose
+
+Help the user understand where they are in their BMad workflow and what to do next. Answer BMad questions when asked.
+
+## Desired Outcomes
+
+When this skill completes, the user should:
+
+1. **Know where they are** — which module and phase they're in, what's already been completed
+2. **Know what to do next** — the next recommended and/or required step, with clear reasoning
+3. **Know how to invoke it** — skill name, menu code, action context, and any args that shortcut the conversation
+4. **Get offered a quick start** — when a single skill is the clear next step, offer to run it for the user right now rather than just listing it
+5. **Feel oriented, not overwhelmed** — surface only what's relevant to their current position; don't dump the entire catalog
+
+## Data Sources
+
+- **Catalog**: `{project-root}/_bmad/_config/bmad-help.csv` — assembled manifest of all installed module skills
+- **Config**: `config.yaml` and `user-config.yaml` files in `{project-root}/_bmad/` and its subfolders — resolve `output-location` variables, provide `communication_language` and `project_knowledge`
+- **Artifacts**: Files matching `outputs` patterns at resolved `output-location` paths reveal which steps are possibly completed; their content may also provide grounding context for recommendations
+- **Project knowledge**: If `project_knowledge` resolves to an existing path, read it for grounding context. Never fabricate project-specific details.
+
+## CSV Interpretation
+
+The catalog uses this format:
+
+```
+module,skill,display-name,menu-code,description,action,args,phase,after,before,required,output-location,outputs
+```
+
+**Phases** determine the high-level flow:
+- `anytime` — available regardless of workflow state
+- Numbered phases (`1-analysis`, `2-planning`, etc.) flow in order; naming varies by module
+
+**Dependencies** determine ordering within and across phases:
+- `after` — skills that should ideally complete before this one
+- `before` — skills that should run after this one
+- Format: `skill-name` for single-action skills, `skill-name:action` for multi-action skills
+
+**Required gates**:
+- `required=true` items must complete before the user can meaningfully proceed to later phases
+- A phase with no required items is entirely optional — recommend it but be clear about what's actually required next
+
+**Completion detection**:
+- Search resolved output paths for `outputs` patterns
+- Fuzzy-match found files to catalog rows
+- User may also state completion explicitly, or it may be evident from the current conversation
+
+**Descriptions carry routing context** — some contain cycle info and alternate paths (e.g., "back to DS if fixes needed"). Read them as navigation hints, not just display text.
+
+## Response Format
+
+For each recommended item, present:
+- `[menu-code]` **Display name** — e.g., "[CP] Create PRD"
+- Skill name in backticks — e.g., `bmad-create-prd`
+- For multi-action skills: action invocation context — e.g., "tech-writer lets create a mermaid diagram!"
+- Description if present in CSV; otherwise your existing knowledge of the skill suffices
+- Args if available
+
+**Ordering**: Show optional items first, then the next required item. Make it clear which is which.
+
+## Constraints
+
+- Present all output in `{communication_language}`
+- Recommend running each skill in a **fresh context window**
+- Match the user's tone — conversational when they're casual, structured when they want specifics
+- If the active module is ambiguous, ask rather than guess

package/src/{core/skills/bmad-index-docs/workflow.md → core-skills/bmad-index-docs/SKILL.md}

@@ -1,3 +1,8 @@
+---
+name: bmad-index-docs
+description: 'Generates or updates an index.md to reference all docs in the folder. Use if user requests to create or update an index of all files in a specific folder'
+---
+
 # Index Docs
 
 **Goal:** Generate or update an index.md to reference all docs in a target folder.

package/src/{core/skills/bmad-review-adversarial-general/workflow.md → core-skills/bmad-review-adversarial-general/SKILL.md}

@@ -1,3 +1,8 @@
+---
+name: bmad-review-adversarial-general
+description: 'Perform a Cynical Review and produce a findings report. Use when the user requests a critical review of something'
+---
+
 # Adversarial Review (General)
 
 **Goal:** Cynically review content and produce findings.

package/src/{core/skills/bmad-review-edge-case-hunter/workflow.md → core-skills/bmad-review-edge-case-hunter/SKILL.md}

@@ -1,3 +1,8 @@
+---
+name: bmad-review-edge-case-hunter
+description: 'Walk every branching path and boundary condition in content, report only unhandled edge cases. Orthogonal to adversarial review - method-driven not attitude-driven. Use when you need exhaustive edge-case analysis of code, specs, or diffs.'
+---
+
 # Edge Case Hunter Review
 
 **Goal:** You are a pure path tracer. Never comment on whether code is good or bad; only list missing handling.

package/src/{core/skills/bmad-shard-doc/workflow.md → core-skills/bmad-shard-doc/SKILL.md}

@@ -1,3 +1,8 @@
+---
+name: bmad-shard-doc
+description: 'Splits large markdown documents into smaller, organized files based on level 2 (default) sections. Use if the user says perform shard document'
+---
+
 # Shard Document
 
 **Goal:** Split large markdown documents into smaller, organized files based on level 2 sections using `npx @kayvan/markdown-tree-parser`.

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

@@ -0,0 +1,11 @@
+module,skill,display-name,menu-code,description,action,args,phase,after,before,required,output-location,outputs
+Core,bmad-brainstorming,Brainstorming,BSP,Use early in ideation or when stuck generating ideas.,,anytime,,,false,{output_folder}/brainstorming,brainstorming session
+Core,bmad-party-mode,Party Mode,PM,Orchestrate multi-agent discussions when you need multiple perspectives or want agents to collaborate.,,anytime,,,false,,
+Core,bmad-help,BMad Help,BH,,,anytime,,,false,,
+Core,bmad-index-docs,Index Docs,ID,Use when LLM needs to understand available docs without loading everything.,,anytime,,,false,,
+Core,bmad-shard-doc,Shard Document,SD,Use when doc becomes too large (>500 lines) to manage effectively.,[path],anytime,,,false,,
+Core,bmad-editorial-review-prose,Editorial Review - Prose,EP,Use after drafting to polish written content.,[path],anytime,,,false,report located with target document,three-column markdown table with suggested fixes
+Core,bmad-editorial-review-structure,Editorial Review - Structure,ES,Use when doc produced from multiple subprocesses or needs structural improvement.,[path],anytime,,,false,report located with target document,
+Core,bmad-review-adversarial-general,Adversarial Review,AR,"Use for quality assurance or before finalizing deliverables. Code Review in other modules runs this automatically, but also useful for document reviews.",[path],anytime,,,false,,
+Core,bmad-review-edge-case-hunter,Edge Case Hunter Review,ECH,Use alongside adversarial review for orthogonal coverage — method-driven not attitude-driven.,[path],anytime,,,false,,
+Core,bmad-distillator,Distillator,DG,Use when you need token-efficient distillates that preserve all information for downstream LLM consumption.,[path],anytime,,,false,adjacent to source document or specified output_path,distillate markdown file(s)

package/tools/bmad-npx-wrapper.js

@@ -5,7 +5,7 @@
  * This file ensures proper execution when run via npx from GitHub or npm registry
  */
 
-const { execSync } = require('node:child_process');
+const { execFileSync } = require('node:child_process');
 const path = require('node:path');
 const fs = require('node:fs');
 
@@ -25,7 +25,7 @@ if (isNpxExecution) {
 
   try {
     // Execute CLI from user's working directory (process.cwd()), not npm cache
-    execSync(`node "${bmadCliPath}" ${args.join(' ')}`, {
+    execFileSync('node', [bmadCliPath, ...args], {
       stdio: 'inherit',
       cwd: process.cwd(), // This preserves the user's working directory
     });

package/tools/cli/commands/install.js

@@ -18,7 +18,7 @@ module.exports = {
       'Comma-separated list of tool/IDE IDs to configure (e.g., "claude-code,cursor"). Use "none" to skip tool configuration.',
     ],
     ['--custom-content <paths>', 'Comma-separated list of paths to custom modules/agents/workflows'],
-    ['--action <type>', 'Action type for existing installations: install, update, quick-update, or compile-agents'],
+    ['--action <type>', 'Action type for existing installations: install, update, or quick-update'],
     ['--user-name <name>', 'Name for agents to use (default: system username)'],
     ['--communication-language <lang>', 'Language for agent communication (default: English)'],
     ['--document-output-language <lang>', 'Language for document output (default: English)'],
@@ -49,13 +49,6 @@ module.exports = {
         process.exit(0);
       }
 
-      // Handle compile agents separately
-      if (config.actionType === 'compile-agents') {
-        const result = await installer.compileAgents(config);
-        await prompts.log.info(`Recompiled ${result.agentCount} agents with customizations applied`);
-        process.exit(0);
-      }
-
       // Regular install/update flow
       const result = await installer.install(config);
 

package/tools/cli/external-official-modules.yaml

@@ -4,7 +4,7 @@
 modules:
   bmad-builder:
     url: https://github.com/bmad-code-org/bmad-builder
-    module-definition: src/module.yaml
+    module-definition: skills/module.yaml
     code: bmb
     name: "BMad Builder"
     description: "Agent and Builder"

package/tools/cli/installers/lib/core/config-collector.js

@@ -954,29 +954,121 @@ class ConfigCollector {
         return match;
       }
 
-      // Look for the config value in allAnswers (already answered questions)
-      let configValue = this.allAnswers[configKey] || this.allAnswers[`core_${configKey}`];
-
-      // Check in already collected config
-      if (!configValue) {
-        for (const mod of Object.keys(this.collectedConfig)) {
-          if (mod !== '_meta' && this.collectedConfig[mod] && this.collectedConfig[mod][configKey]) {
-            configValue = this.collectedConfig[mod][configKey];
-            break;
-          }
+      const configValue = this.resolveConfigValue(configKey, currentModule, moduleConfig);
+
+      return configValue || match;
+    });
+  }
+
+  /**
+   * Clean a stored path-like value for prompt display/input reuse.
+   * @param {*} value - Stored value
+   * @returns {*} Cleaned value
+   */
+  cleanPromptValue(value) {
+    if (typeof value === 'string' && value.startsWith('{project-root}/')) {
+      return value.replace('{project-root}/', '');
+    }
+
+    return value;
+  }
+
+  /**
+   * Resolve a config key from answers, collected config, existing config, or schema defaults.
+   * @param {string} configKey - Config key to resolve
+   * @param {string} currentModule - Current module name
+   * @param {Object} moduleConfig - Current module config schema
+   * @returns {*} Resolved value
+   */
+  resolveConfigValue(configKey, currentModule = null, moduleConfig = null) {
+    // Look for the config value in allAnswers (already answered questions)
+    let configValue = this.allAnswers?.[configKey] || this.allAnswers?.[`core_${configKey}`];
+
+    if (!configValue && this.allAnswers) {
+      for (const [answerKey, answerValue] of Object.entries(this.allAnswers)) {
+        if (answerKey.endsWith(`_${configKey}`)) {
+          configValue = answerValue;
+          break;
         }
       }
+    }
 
-      // If still not found and we're in the same module, use the default from the config schema
-      if (!configValue && currentModule && moduleConfig && moduleConfig[configKey]) {
-        const referencedItem = moduleConfig[configKey];
-        if (referencedItem && referencedItem.default !== undefined) {
-          configValue = referencedItem.default;
+    // Prefer the current module's persisted value when re-prompting an existing install
+    if (!configValue && currentModule && this.existingConfig?.[currentModule]?.[configKey] !== undefined) {
+      configValue = this.existingConfig[currentModule][configKey];
+    }
+
+    // Check in already collected config
+    if (!configValue) {
+      for (const mod of Object.keys(this.collectedConfig)) {
+        if (mod !== '_meta' && this.collectedConfig[mod] && this.collectedConfig[mod][configKey]) {
+          configValue = this.collectedConfig[mod][configKey];
+          break;
         }
       }
+    }
 
-      return configValue || match;
-    });
+    // Fall back to other existing module config values
+    if (!configValue && this.existingConfig) {
+      for (const mod of Object.keys(this.existingConfig)) {
+        if (mod !== '_meta' && this.existingConfig[mod] && this.existingConfig[mod][configKey]) {
+          configValue = this.existingConfig[mod][configKey];
+          break;
+        }
+      }
+    }
+
+    // If still not found and we're in the same module, use the default from the config schema
+    if (!configValue && currentModule && moduleConfig && moduleConfig[configKey]) {
+      const referencedItem = moduleConfig[configKey];
+      if (referencedItem && referencedItem.default !== undefined) {
+        configValue = referencedItem.default;
+      }
+    }
+
+    return this.cleanPromptValue(configValue);
+  }
+
+  /**
+   * Convert an existing stored value back into the prompt-facing value for templated fields.
+   * For example, "{test_artifacts}/{value}" + "_bmad-output/test-artifacts/test-design"
+   * becomes "test-design" so the template is not applied twice on modify.
+   * @param {*} existingValue - Stored config value
+   * @param {string} moduleName - Module name
+   * @param {Object} item - Config item definition
+   * @param {Object} moduleConfig - Current module config schema
+   * @returns {*} Prompt-facing default value
+   */
+  normalizeExistingValueForPrompt(existingValue, moduleName, item, moduleConfig = null) {
+    const cleanedValue = this.cleanPromptValue(existingValue);
+
+    if (typeof cleanedValue !== 'string' || typeof item?.result !== 'string' || !item.result.includes('{value}')) {
+      return cleanedValue;
+    }
+
+    const [prefixTemplate = '', suffixTemplate = ''] = item.result.split('{value}');
+    const prefix = this.cleanPromptValue(this.replacePlaceholders(prefixTemplate, moduleName, moduleConfig));
+    const suffix = this.cleanPromptValue(this.replacePlaceholders(suffixTemplate, moduleName, moduleConfig));
+
+    if ((prefix && !cleanedValue.startsWith(prefix)) || (suffix && !cleanedValue.endsWith(suffix))) {
+      return cleanedValue;
+    }
+
+    const startIndex = prefix.length;
+    const endIndex = suffix ? cleanedValue.length - suffix.length : cleanedValue.length;
+    if (endIndex < startIndex) {
+      return cleanedValue;
+    }
+
+    let promptValue = cleanedValue.slice(startIndex, endIndex);
+    if (promptValue.startsWith('/')) {
+      promptValue = promptValue.slice(1);
+    }
+    if (promptValue.endsWith('/')) {
+      promptValue = promptValue.slice(0, -1);
+    }
+
+    return promptValue || cleanedValue;
   }
 
   /**
@@ -993,12 +1085,7 @@ class ConfigCollector {
     let existingValue = null;
     if (this.existingConfig && this.existingConfig[moduleName]) {
       existingValue = this.existingConfig[moduleName][key];
-
-      // Clean up existing value - remove {project-root}/ prefix if present
-      // This prevents duplication when the result template adds it back
-      if (typeof existingValue === 'string' && existingValue.startsWith('{project-root}/')) {
-        existingValue = existingValue.replace('{project-root}/', '');
-      }
+      existingValue = this.normalizeExistingValueForPrompt(existingValue, moduleName, item, moduleConfig);
     }
 
     // Special handling for user_name: default to system user