bmad-method 6.2.1-next.9 → 6.2.1

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 → bmm-skills}/module-help.csv

@@ -1,20 +1,18 @@
 module,phase,name,code,sequence,workflow-file,command,required,agent,options,description,output-location,outputs,
 bmm,anytime,Document Project,DP,,skill:bmad-document-project,bmad-bmm-document-project,false,analyst,Create Mode,"Analyze an existing project to produce useful documentation",project-knowledge,*,
-bmm,anytime,Generate Project Context,GPC,,skill:bmad-generate-project-context,bmad-bmm-generate-project-context,false,analyst,Create Mode,"Scan existing codebase to generate a lean LLM-optimized project-context.md containing critical implementation rules patterns and conventions for AI agents. Essential for brownfield projects and quick-flow.",output_folder,"project context",
-bmm,anytime,Quick Spec,QS,,skill:bmad-quick-spec,bmad-bmm-quick-spec,false,quick-flow-solo-dev,Create Mode,"Do not suggest for potentially very complex things unless requested or if the user complains that they do not want to follow the extensive planning of the bmad method. Quick one-off tasks small changes simple apps brownfield additions to well established patterns utilities without extensive planning",planning_artifacts,"tech spec",
-bmm,anytime,Quick Dev,QD,,skill:bmad-quick-dev,bmad-bmm-quick-dev,false,quick-flow-solo-dev,Create Mode,"Quick one-off tasks small changes simple apps utilities without extensive planning - Do not suggest for potentially very complex things unless requested or if the user complains that they do not want to follow the extensive planning of the bmad method, unless the user is already working through the implementation phase and just requests a 1 off things not already in the plan",,,
-bmm,anytime,Quick Dev New Preview,QQ,,skill:bmad-quick-dev-new-preview,bmad-bmm-quick-dev-new-preview,false,quick-flow-solo-dev,Create Mode,"Unified quick flow (experimental): clarify intent plan implement review and present in a single workflow",implementation_artifacts,"tech spec implementation",
+bmm,anytime,Generate Project Context,GPC,,skill:bmad-generate-project-context,bmad-bmm-generate-project-context,false,analyst,Create Mode,"Scan existing codebase to generate a lean LLM-optimized project-context.md containing critical implementation rules patterns and conventions for AI agents. Essential for brownfield projects.",output_folder,"project context",
+bmm,anytime,Quick Dev,QQ,,skill:bmad-quick-dev,bmad-bmm-quick-dev,false,quick-flow-solo-dev,Create Mode,"Unified intent-in code-out workflow: clarify plan implement review and present",implementation_artifacts,"spec and project implementation",
 bmm,anytime,Correct Course,CC,,skill:bmad-correct-course,bmad-bmm-correct-course,false,sm,Create Mode,"Anytime: Navigate significant changes. May recommend start over update PRD redo architecture sprint planning or correct epics and stories",planning_artifacts,"change proposal",
 bmm,anytime,Write Document,WD,,skill:bmad-agent-tech-writer,,false,tech-writer,,"Describe in detail what you want, and the agent will follow the documentation best practices defined in agent memory. Multi-turn conversation with subprocess for research/review.",project-knowledge,"document",
 bmm,anytime,Update Standards,US,,skill:bmad-agent-tech-writer,,false,tech-writer,,"Update agent memory documentation-standards.md with your specific preferences if you discover missing document conventions.",_bmad/_memory/tech-writer-sidecar,"standards",
 bmm,anytime,Mermaid Generate,MG,,skill:bmad-agent-tech-writer,,false,tech-writer,,"Create a Mermaid diagram based on user description. Will suggest diagram types if not specified.",planning_artifacts,"mermaid diagram",
 bmm,anytime,Validate Document,VD,,skill:bmad-agent-tech-writer,,false,tech-writer,,"Review the specified document against documentation standards and best practices. Returns specific actionable improvement suggestions organized by priority.",planning_artifacts,"validation report",
 bmm,anytime,Explain Concept,EC,,skill:bmad-agent-tech-writer,,false,tech-writer,,"Create clear technical explanations with examples and diagrams for complex concepts. Breaks down into digestible sections using task-oriented approach.",project_knowledge,"explanation",
-bmm,1-analysis,Brainstorm Project,BP,10,skill:bmad-brainstorming,bmad-brainstorming,false,analyst,data=_bmad/bmm/data/project-context-template.md,"Expert Guided Facilitation through a single or multiple techniques",planning_artifacts,"brainstorming session",
+bmm,1-analysis,Brainstorm Project,BP,10,skill:bmad-brainstorming,bmad-brainstorming,false,analyst,,"Expert Guided Facilitation through a single or multiple techniques",planning_artifacts,"brainstorming session",
 bmm,1-analysis,Market Research,MR,20,skill:bmad-market-research,bmad-bmm-market-research,false,analyst,Create Mode,"Market analysis competitive landscape customer needs and trends","planning_artifacts|project-knowledge","research documents",
 bmm,1-analysis,Domain Research,DR,21,skill:bmad-domain-research,bmad-bmm-domain-research,false,analyst,Create Mode,"Industry domain deep dive subject matter expertise and terminology","planning_artifacts|project_knowledge","research documents",
 bmm,1-analysis,Technical Research,TR,22,skill:bmad-technical-research,bmad-bmm-technical-research,false,analyst,Create Mode,"Technical feasibility architecture options and implementation approaches","planning_artifacts|project_knowledge","research documents",
-bmm,1-analysis,Create Brief,CB,30,skill:bmad-create-product-brief,bmad-bmm-create-product-brief,false,analyst,Create Mode,"A guided experience to nail down your product idea",planning_artifacts,"product brief",
+bmm,1-analysis,Create Brief,CB,30,skill:bmad-product-brief,bmad-bmm-product-brief,false,analyst,Create Mode,"A guided experience to nail down your product idea",planning_artifacts,"product brief",
 bmm,2-planning,Create PRD,CP,10,skill:bmad-create-prd,bmad-bmm-create-prd,true,pm,Create Mode,"Expert led facilitation to produce your Product Requirements Document",planning_artifacts,prd,
 bmm,2-planning,Validate PRD,VP,20,skill:bmad-validate-prd,bmad-bmm-validate-prd,false,pm,Validate Mode,"Validate PRD is comprehensive lean well organized and cohesive",planning_artifacts,"prd validation report",
 bmm,2-planning,Edit PRD,EP,25,skill:bmad-edit-prd,bmad-bmm-edit-prd,false,pm,Edit Mode,"Improve and enhance an existing PRD",planning_artifacts,"updated prd",

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/workflow.md → core-skills/bmad-help/SKILL.md}

@@ -1,3 +1,7 @@
+---
+name: bmad-help
+description: 'Analyzes current state and user query to answer BMad questions or recommend the next workflow or agent. Use when user says what should I do next, what do I do now, or asks a question about BMad'
+---
 
 # Task: BMAD Help
 
@@ -19,7 +23,7 @@ When `command` field has a value:
 
 ### Skill-Referenced Workflows
 When `workflow-file` starts with `skill:`:
-- The value is a skill reference (e.g., `skill:bmad-quick-dev-new-preview`), NOT a file path
+- The value is a skill reference (e.g., `skill:bmad-quick-dev`), NOT a file path
 - Do NOT attempt to resolve or load it as a file path
 - Display using the `command` column value as a skill name in backticks (same as command-based workflows)
 

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/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/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

package/tools/cli/installers/lib/core/dependency-resolver.js

@@ -82,11 +82,11 @@ class DependencyResolver {
       // Check if this is a source directory (has 'src' subdirectory)
       const srcDir = path.join(bmadDir, 'src');
       if (await fs.pathExists(srcDir)) {
-        // Source directory structure: src/core or src/bmm
+        // Source directory structure: src/core-skills or src/bmm-skills
         if (module === 'core') {
-          moduleDir = path.join(srcDir, 'core');
+          moduleDir = path.join(srcDir, 'core-skills');
         } else if (module === 'bmm') {
-          moduleDir = path.join(srcDir, 'bmm');
+          moduleDir = path.join(srcDir, 'bmm-skills');
         }
       }
 
@@ -401,8 +401,8 @@ class DependencyResolver {
         const bmadPath = dep.dependency.replace(/^bmad\//, '');
 
         // Try to resolve as if it's in src structure
-        // bmad/core/tasks/foo.md -> src/core/tasks/foo.md
-        // bmad/bmm/tasks/bar.md -> src/bmm/tasks/bar.md (bmm is directly under src/)
+        // bmad/core/tasks/foo.md -> src/core-skills/tasks/foo.md
+        // bmad/bmm/tasks/bar.md -> src/bmm-skills/tasks/bar.md (bmm is directly under src/)
         // bmad/cis/agents/bar.md -> src/modules/cis/agents/bar.md
 
         if (bmadPath.startsWith('core/')) {
@@ -584,11 +584,11 @@ class DependencyResolver {
     const relative = path.relative(bmadDir, filePath);
     const parts = relative.split(path.sep);
 
-    // Handle source directory structure (src/core, src/bmm, or src/modules/xxx)
+    // Handle source directory structure (src/core-skills, src/bmm-skills, or src/modules/xxx)
     if (parts[0] === 'src') {
-      if (parts[1] === 'core') {
+      if (parts[1] === 'core-skills') {
         return 'core';
-      } else if (parts[1] === 'bmm') {
+      } else if (parts[1] === 'bmm-skills') {
         return 'bmm';
       } else if (parts[1] === 'modules' && parts.length > 2) {
         return parts[2];
@@ -631,11 +631,11 @@ class DependencyResolver {
       let moduleBase;
 
       // Check if file is in source directory structure
-      if (file.includes('/src/core/') || file.includes('/src/bmm/')) {
+      if (file.includes('/src/core-skills/') || file.includes('/src/bmm-skills/')) {
         if (module === 'core') {
-          moduleBase = path.join(bmadDir, 'src', 'core');
+          moduleBase = path.join(bmadDir, 'src', 'core-skills');
         } else if (module === 'bmm') {
-          moduleBase = path.join(bmadDir, 'src', 'bmm');
+          moduleBase = path.join(bmadDir, 'src', 'bmm-skills');
         }
       } else {
         moduleBase = module === 'core' ? path.join(bmadDir, 'core') : path.join(bmadDir, 'modules', module);