bmad-method 6.2.3-next.3 → 6.2.3-next.30

package/src/bmm-skills/4-implementation/bmad-correct-course/checklist.md

@@ -217,8 +217,8 @@
 <check-item id="5.5">
 <prompt>Establish agent handoff plan</prompt>
 <action>Identify which roles/agents will execute the changes:</action>
-  - Development team (for implementation)
-  - Product Owner / Scrum Master (for backlog changes)
+  - Developer agent (for implementation)
+  - Product Owner / Developer (for backlog changes)
   - Product Manager / Architect (for strategic changes)
 <action>Define responsibilities for each role</action>
 <status>[ ] Done / [ ] N/A / [ ] Action-needed</status>

package/src/bmm-skills/4-implementation/bmad-correct-course/workflow.md

@@ -2,7 +2,7 @@
 
 **Goal:** Manage significant changes during sprint execution by analyzing impact across all project artifacts and producing a structured Sprint Change Proposal.
 
-**Your Role:** You are a Scrum Master navigating change management. Analyze the triggering issue, assess impact across PRD, epics, architecture, and UX artifacts, and produce an actionable Sprint Change Proposal with clear handoff.
+**Your Role:** You are a Developer navigating change management. Analyze the triggering issue, assess impact across PRD, epics, architecture, and UX artifacts, and produce an actionable Sprint Change Proposal with clear handoff.
 
 ---
 
@@ -192,8 +192,8 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
 <action>Section 5: Implementation Handoff</action>
 
 - Categorize change scope:
-  - Minor: Direct implementation by dev team
-  - Moderate: Backlog reorganization needed (PO/SM)
+  - Minor: Direct implementation by Developer agent
+  - Moderate: Backlog reorganization needed (PO/DEV)
   - Major: Fundamental replan required (PM/Architect)
 - Specify handoff recipients and their responsibilities
 - Define success criteria for implementation
@@ -219,8 +219,8 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
   <action>Finalize Sprint Change Proposal document</action>
   <action>Determine change scope classification:</action>
 
-- **Minor**: Can be implemented directly by development team
-- **Moderate**: Requires backlog reorganization and PO/SM coordination
+- **Minor**: Can be implemented directly by Developer agent
+- **Moderate**: Requires backlog reorganization and PO/DEV coordination
 - **Major**: Needs fundamental replan with PM/Architect involvement
 
 <action>Provide appropriate handoff based on scope:</action>
@@ -228,12 +228,12 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
 </check>
 
 <check if="Minor scope">
-  <action>Route to: Development team for direct implementation</action>
+  <action>Route to: Developer agent for direct implementation</action>
   <action>Deliverables: Finalized edit proposals and implementation tasks</action>
 </check>
 
 <check if="Moderate scope">
-  <action>Route to: Product Owner / Scrum Master agents</action>
+  <action>Route to: Product Owner / Developer agents</action>
   <action>Deliverables: Sprint Change Proposal + backlog reorganization plan</action>
 </check>
 
@@ -261,7 +261,7 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
 - Implementation handoff plan
 
 <action>Report workflow completion to user with personalized message: "Correct Course workflow complete, {user_name}!"</action>
-<action>Remind user of success criteria and next steps for implementation team</action>
+<action>Remind user of success criteria and next steps for Developer agent</action>
 </step>
 
 </workflow>

package/src/bmm-skills/4-implementation/bmad-qa-generate-e2e-tests/checklist.md

@@ -1,4 +1,4 @@
-# Quinn Automate - Validation Checklist
+# QA Automate - Validation Checklist
 
 ## Test Generation
 

package/src/bmm-skills/4-implementation/bmad-quick-dev/spec-template.md

@@ -3,7 +3,7 @@ title: '{title}'
 type: 'feature' # feature | bugfix | refactor | chore
 created: '{date}'
 status: 'draft' # draft | ready-for-dev | in-progress | in-review | done
-context: [] # optional: max 3 project-wide standards/docs. NO source code files.
+context: [] # optional: `{project-root}/`-prefixed paths to project-wide standards/docs the implementation agent should load. Keep short — only what isn't already distilled into the spec body.
 ---
 
 <!-- Target: 900–1300 tokens. Above 1600 = high risk of context rot.

package/src/bmm-skills/4-implementation/bmad-quick-dev/step-01-clarify-and-route.md

@@ -1,7 +1,6 @@
 ---
-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
+spec_file: '' # set at runtime for both routes before leaving this step
 ---
 
 # Step 1: Clarify and Route
@@ -21,7 +20,7 @@ Before listing artifacts or prompting the user, check whether you already know t
 
 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).
+   - If it points to a file that matches the spec template (has `status` frontmatter with a recognized value: draft, ready-for-dev, in-progress, in-review, or done) → set `spec_file` and **EARLY EXIT** to the appropriate step (step-02 for draft, step-03 for ready/in-progress, step-04 for review). For `done`, ingest as context and proceed to INSTRUCTIONS — do not resume.
    - 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
@@ -29,8 +28,8 @@ Before listing artifacts or prompting the user, check whether you already know t
    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).
+   - Active specs (`draft`, `ready-for-dev`, `in-progress`, `in-review`) in `{implementation_artifacts}`? → List them and HALT. Ask user which to resume (or `[N]` for new).
+     - If `draft` selected: Set `spec_file`. **EARLY EXIT** → `./step-02-plan.md` (resume planning from the draft)
      - 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.
@@ -42,6 +41,19 @@ Never ask extra questions if you already understand what the user intends.
 1. Load context.
    - List files in `{planning_artifacts}` and `{implementation_artifacts}`.
    - If you find an unformatted spec or intent file, ingest its contents to form your understanding of the intent.
+   - Planning artifacts are the output of BMAD phases 1-3. Typical files include:
+     - **PRD** (`*prd*`) — product requirements and success criteria
+     - **Architecture** (`*architecture*`) — technical design decisions and constraints
+     - **UX/Design** (`*ux*`) — user experience and interaction design
+     - **Epics** (`*epic*`) — feature breakdown into implementable stories
+     - **Product Brief** (`*brief*`) — project vision and scope
+   - Scan the listing for files matching these patterns. If any look relevant to the current intent, load them selectively — you don't need all of them, but you need the right constraints and requirements rather than guessing from code alone.
+   - **Previous story continuity.** Using the intent and loaded context (especially any epics file), infer whether the current work is a story from an epic. Do not rely on filename patterns or regex — reason about the intent, the artifact listing, and epics content together. If the intent is an epic story:
+     1. Identify the epic and story number.
+     2. Scan `{implementation_artifacts}` for specs from the same epic with `status: done` and a lower story number.
+     3. Load the most recent one (highest story number below current).
+     4. Extract its **Code Map**, **Design Notes**, **Spec Change Log**, and **task list** as continuity context for step-02 planning.
+     If no `done` spec is found but an `in-review` spec exists for the same epic with a lower story number, note it to the user and ask whether to load it. If the intent is not an epic story, or no previous spec exists, skip this silently.
 2. Clarify intent. Do not fantasize, do not leave open questions. If you must ask questions, ask them as a numbered list. When the human replies, verify that every single numbered question was answered. If any were ignored, HALT and re-ask only the missing questions before proceeding. Keep looping until intent is clear enough to implement.
 3. Version control sanity check. Is the working tree clean? Does the current branch make sense for this intent — considering its name and recent history? If the tree is dirty or the branch is an obvious mismatch, HALT and ask the human before proceeding. If version control is unavailable, skip this check.
 4. Multi-goal check (see SCOPE STANDARD). If the intent fails the single-goal criteria:
@@ -52,11 +64,13 @@ Never ask extra questions if you already understand what the user intends.
    - On **K**: Proceed as-is.
 5. Route — choose exactly one:
 
+   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: if its status is `draft`, treat it as the same work and resume it (set `spec_file` to that path, **EARLY EXIT** → `./step-02-plan.md`); otherwise append `-2`, `-3`, etc. Set `spec_file` = `{implementation_artifacts}/spec-{slug}.md`.
+
    **a) One-shot** — zero blast radius: no plausible path by which this change causes unintended consequences elsewhere. Clear intent, no architectural decisions.
+
    **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 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-skills/4-implementation/bmad-quick-dev/step-02-plan.md

@@ -1,5 +1,4 @@
 ---
-wipFile: '{implementation_artifacts}/spec-wip.md'
 deferred_work_file: '{implementation_artifacts}/deferred-work.md'
 ---
 
@@ -12,11 +11,12 @@ 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 `./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:
+1. Draft resume check. If `{spec_file}` exists with `status: draft`, read it and capture the verbatim `<frozen-after-approval>...</frozen-after-approval>` block as `preserved_intent`. Otherwise `preserved_intent` is empty.
+2. Investigate codebase. _Isolate deep exploration in sub-agents/tasks where available. To prevent context snowballing, instruct subagents to give you distilled summaries only._
+3. Read `./spec-template.md` fully. Fill it out based on the intent and investigation. If `{preserved_intent}` is non-empty, substitute it for the `<frozen-after-approval>` block in your filled spec before writing. Write the result to `{spec_file}`.
+4. Self-review against READY FOR DEVELOPMENT standard.
+5. If intent gaps exist, do not fantasize, do not leave open questions, HALT and ask the human.
+6. Token count check (see SCOPE STANDARD). If spec exceeds 1600 tokens:
    - Show user the token count.
    - HALT and ask human: `[S] Split — carve off secondary goals` | `[K] Keep full spec — accept the risks`
    - On **S**: Propose the split — name each secondary goal. Append deferred goals to `{deferred_work_file}`. Rewrite the current spec to cover only the main goal — do not surgically carve sections out; regenerate the spec for the narrowed scope. Continue to checkpoint.
@@ -24,9 +24,21 @@ deferred_work_file: '{implementation_artifacts}/deferred-work.md'
 
 ### CHECKPOINT 1
 
-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`
+Present summary. Display the spec file path as a CWD-relative path (no leading `/`) so it is clickable in the terminal. If token count exceeded 1600 and user chose [K], include the token count and explain why it may be a problem.
 
-- **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.
+After presenting the summary, display this note:
+
+---
+
+Before approving, you can open the spec file in an editor or ask me questions and tell me what to change. You can also use `bmad-advanced-elicitation`, `bmad-party-mode`, or `bmad-code-review` skills, ideally in another session to avoid context bloat.
+
+---
+
+HALT and ask human: `[A] Approve` | `[E] Edit`
+
+- **A**: Re-read `{spec_file}` from disk.
+  - **If the file is missing:** HALT. Tell the user the spec file is gone and STOP — do not write anything to `{spec_file}`, do not set status, do not proceed to Step 3. Nothing below this point runs.
+  - **If the file exists:** Compare the content to what you wrote. If it has changed since you wrote it, acknowledge the external edits — show a brief summary of what changed — and proceed with the updated version. Then set status `ready-for-dev` in `{spec_file}`. Everything inside `<frozen-after-approval>` is now locked — only the human can change it. → Step 3.
 - **E**: Apply changes, then return to CHECKPOINT 1.
 
 

package/src/bmm-skills/4-implementation/bmad-quick-dev/step-03-implement.md

@@ -24,6 +24,8 @@ Capture `baseline_commit` (current HEAD, or `NO_VCS` if version control is unava
 
 Change `{spec_file}` status to `in-progress` in the frontmatter before starting implementation.
 
+If `{spec_file}` has a non-empty `context:` list in its frontmatter, load those files before implementation begins. When handing to a sub-agent, include them in the sub-agent prompt so it has access to the referenced context.
+
 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.

package/src/bmm-skills/4-implementation/bmad-quick-dev/step-oneshot.md

@@ -29,19 +29,31 @@ Deduplicate all review findings. Three categories only:
 
 If a finding is caused by this change but too significant for a trivial patch, HALT and present it to the human for decision before proceeding.
 
+### Generate Spec Trace
+
+Set `{title}` = a concise title derived from the clarified intent.
+
+Write `{spec_file}` using `./spec-template.md`. Fill only these sections — delete all others:
+
+1. **Frontmatter** — set `title: '{title}'`, `type`, `created`, `status: 'done'`. Add `route: 'one-shot'`.
+2. **Title and Intent** — `# {title}` heading and `## Intent` with **Problem** and **Approach** lines. Reuse the summary you already generated for the terminal.
+3. **Suggested Review Order** — append after Intent. Build using the same convention as `./step-05-present.md` § "Generate Suggested Review Order" (spec-file-relative links, concern-based ordering, ultra-concise framing).
+
 ### Commit
 
 If version control is available and the tree is dirty, create a local commit with a conventional message derived from the intent. If VCS is unavailable, skip.
 
 ### Present
 
-1. Open all changed files in the user's editor so they can review the code directly:
-   - 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.
+1. Open the spec in the user's editor so they can click through the Suggested Review Order:
+   - 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.
 2. Display a summary in conversation output, including:
    - The commit hash (if one was created).
-   - 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 `/`.
+   - List of files changed with one-line descriptions. 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 — this differs from spec-file links which use spec-file-relative paths.
    - Review findings breakdown: patches applied, items deferred, items rejected. If all findings were rejected, say so.
+   - 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."
 3. Offer to push and/or create a pull request.
 
 HALT and wait for human input.

package/src/bmm-skills/4-implementation/bmad-quick-dev/workflow.md

@@ -70,10 +70,6 @@ Load and read full config from `{main_config}` and resolve:
 
 YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`.
 
-### 2. Paths
-
-- `wipFile` = `{implementation_artifacts}/spec-wip.md`
-
-### 3. First Step Execution
+### 2. First Step Execution
 
 Read fully and follow: `./step-01-clarify-and-route.md` to begin the workflow.