Merge 1ee10ddcab into 35a7f101dd

* feat(quick-flow): add quick-dev2 unified workflow

Add the quick-dev2 workflow that unifies clarify, plan, implement,
review, and present into a single flow. Register it in the agent
menu, module-help catalog, and test fixtures.

* fix(quick-flow): rename QD2 trigger to QQ for schema compliance

COMPOUND_TRIGGER_PATTERN only allows uppercase letters in shortcuts.
Rename to QQ so quick-dev2 passes agent schema validation.

* fix(quick-flow): address PR review findings for quick-dev2

- step-04-review: fix copy-paste fallback text to say "perform all
  three reviews inline sequentially" instead of "implement directly"
- workflow.md: add missing planning_artifacts to initialization list,
  matching quick-spec and quick-dev siblings
- quick-flow-solo-dev.agent.yaml: change QD and QQ menu entries from
  workflow: to exec: for .md files, matching the exec-for-md convention

* fix(quick-flow): use human-in-the-loop fallback for review without subagents

Sequential inline reviews in the same context suffer from anchoring
bias and context blowout. Instead, generate separate review prompt
files and ask the human to run each in a separate session.

* refactor(quick-flow): rename quick-dev2 to quick-dev-new-preview

Rename directory, update all references in agent menu, module-help,
and workflow internals.

package.json

@@ -40,7 +40,8 @@
     "lint:md": "markdownlint-cli2 \"**/*.md\"",
     "prepare": "command -v husky >/dev/null 2>&1 && husky || exit 0",
     "rebundle": "node tools/cli/bundlers/bundle-web.js rebundle",
-    "test": "npm run test:schemas && npm run test:refs && npm run test:install && npm run validate:schemas && npm run lint && npm run lint:md && npm run format:check",
+    "test": "npm run test:schemas && npm run test:refs && npm run test:install && npm run test:copilot && npm run validate:schemas && npm run lint && npm run lint:md && npm run format:check",
+    "test:copilot": "node test/test-github-copilot-installer.js",
     "test:coverage": "c8 --reporter=text --reporter=html npm run test:schemas",
     "test:install": "node test/test-installation-components.js",
     "test:refs": "node test/test-file-refs-csv.js",

src/bmm/agents/quick-flow-solo-dev.agent.yaml

@@ -24,9 +24,13 @@ agent:
       description: "[QS] Quick Spec: Architect a quick but complete technical spec with implementation-ready stories/specs"
 
     - trigger: QD or fuzzy match on quick-dev
-      workflow: "{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev/workflow.md"
+      exec: "{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev/workflow.md"
       description: "[QD] Quick-flow Develop: Implement a story tech spec end-to-end (Core of Quick Flow)"
 
+    - trigger: QQ or fuzzy match on quick-dev-new-preview
+      exec: "{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev-new-preview/workflow.md"
+      description: "[QQ] Quick Dev New (Preview): Unified quick flow — clarify intent, plan, implement, review, present (experimental)"
+
     - trigger: CR or fuzzy match on code-review
       workflow: "{project-root}/_bmad/bmm/workflows/4-implementation/code-review/workflow.yaml"
       description: "[CR] Code Review: Initiate a comprehensive code review across multiple quality facets. For best results, use a fresh context and a different quality LLM if available"

src/bmm/module-help.csv

@@ -3,6 +3,7 @@ bmm,anytime,Document Project,DP,,_bmad/bmm/workflows/document-project/workflow.y
 bmm,anytime,Generate Project Context,GPC,,_bmad/bmm/workflows/generate-project-context/workflow.md,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,,_bmad/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md,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,,_bmad/bmm/workflows/bmad-quick-flow/quick-dev/workflow.md,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,,_bmad/bmm/workflows/bmad-quick-flow/quick-dev-new-preview/workflow.md,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,Correct Course,CC,,_bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml,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,,_bmad/bmm/agents/tech-writer/tech-writer.agent.yaml,,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,,_bmad/bmm/agents/tech-writer/tech-writer.agent.yaml,,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",

src/bmm/workflows/bmad-quick-flow/quick-dev-new-preview/steps/step-01-clarify-and-route.md

@@ -0,0 +1,51 @@
+---
+name: 'step-01-clarify-and-route'
+description: 'Capture intent, route to execution path'
+
+wipFile: '{implementation_artifacts}/tech-spec-wip.md'
+deferred_work_file: '{implementation_artifacts}/deferred-work.md'
+spec_file: '' # set at runtime before leaving this step
+---
+
+# Step 1: Clarify and Route
+
+## RULES
+
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- The prompt that triggered this workflow IS the intent — not a hint.
+- Do NOT assume you start from zero.
+
+## ARTIFACT SCAN
+
+- `{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`, set `execution_mode = "plan-code-review"`, skip to step 3.
+  - If `in-review` selected: Set `spec_file`, set `execution_mode = "plan-code-review"`, skip to step 4.
+- 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.
+
+## INSTRUCTIONS
+
+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.
+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:
+   - Present detected distinct goals as a bullet list.
+   - HALT and ask human: `[S] Split — pick first goal, defer the rest` | `[K] Keep as-is`
+   - On **S**: Append deferred goals to `{deferred_work_file}`. Narrow scope to the first-mentioned goal. Continue routing.
+   - On **K**: Proceed as-is.
+5. Generate `spec_file` path:
+   - 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`.
+6. Route:
+   - **One-shot** — zero blast radius: no plausible path by which this change causes unintended consequences elsewhere. Clear intent, no architectural decisions. `execution_mode = "one-shot"`. → Step 3.
+   - **Plan-code-review** — everything else. `execution_mode = "plan-code-review"`. → Step 2.
+   - When uncertain whether blast radius is truly zero, default to plan-code-review.
+
+
+## NEXT
+
+- One-shot / ready-for-dev: Read fully and follow `{installed_path}/steps/step-03-implement.md`
+- Plan-code-review: Read fully and follow `{installed_path}/steps/step-02-plan.md`

src/bmm/workflows/bmad-quick-flow/quick-dev-new-preview/steps/step-02-plan.md

@@ -0,0 +1,39 @@
+---
+name: 'step-02-plan'
+description: 'Investigate, generate spec, present for approval'
+
+templateFile: '{installed_path}/tech-spec-template.md'
+wipFile: '{implementation_artifacts}/tech-spec-wip.md'
+deferred_work_file: '{implementation_artifacts}/deferred-work.md'
+---
+
+# Step 2: Plan
+
+## RULES
+
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- No intermediate approvals.
+
+## 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 `{templateFile}` 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:
+   - Show user the token count.
+   - HALT and ask human: `[S] Split — carve off secondary goals` | `[K] Keep as-is`
+   - 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.
+   - On **K**: Continue to checkpoint with full spec.
+
+### 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`
+
+- **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.
+- **E**: Apply changes, then return to CHECKPOINT 1.
+
+
+## NEXT
+
+Read fully and follow `{installed_path}/steps/step-03-implement.md`

src/bmm/workflows/bmad-quick-flow/quick-dev-new-preview/steps/step-03-implement.md

@@ -0,0 +1,35 @@
+---
+name: 'step-03-implement'
+description: 'Execute implementation directly or via sub-agent. Local only.'
+---
+
+# Step 3: Implement
+
+## RULES
+
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- No push. No remote ops.
+- Sequential execution only.
+- Content inside `<frozen-after-approval>` in `{spec_file}` is read-only. Do not modify.
+
+## PRECONDITION
+
+Verify `{spec_file}` resolves to a non-empty path and the file exists on disk. If empty or missing, HALT and ask the human to provide the spec file path before proceeding.
+
+## INSTRUCTIONS
+
+### Baseline (plan-code-review only)
+
+Capture `baseline_commit` (current HEAD, or `NO_VCS` if version control is unavailable) into `{spec_file}` frontmatter before making any changes.
+
+### Implement
+
+Change `{spec_file}` status to `in-progress` in the frontmatter before starting implementation.
+
+`execution_mode = "one-shot"` or no sub-agents/tasks available: implement the intent.
+
+Otherwise (`execution_mode = "plan-code-review"`): hand `{spec_file}` to a sub-agent/task and let it implement.
+
+## NEXT
+
+Read fully and follow `{installed_path}/steps/step-04-review.md`

src/bmm/workflows/bmad-quick-flow/quick-dev-new-preview/steps/step-04-review.md

@@ -0,0 +1,57 @@
+---
+name: 'step-04-review'
+description: 'Adversarial review, classify findings, optional spec loop'
+
+adversarial_review_task: '{project-root}/_bmad/core/tasks/review-adversarial-general.xml'
+edge_case_hunter_task: '{project-root}/_bmad/core/tasks/review-edge-case-hunter.xml'
+deferred_work_file: '{implementation_artifacts}/deferred-work.md'
+specLoopIteration: 1
+---
+
+# Step 4: Review
+
+## RULES
+
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- Review subagents get NO conversation context.
+
+## INSTRUCTIONS
+
+Change `{spec_file}` status to `in-review` in the frontmatter before continuing.
+
+### Construct Diff (plan-code-review only)
+
+Read `{baseline_commit}` from `{spec_file}` frontmatter. If `{baseline_commit}` is missing or `NO_VCS`, use best effort to determine what changed. Otherwise, construct `{diff_output}` covering all changes — tracked and untracked — since `{baseline_commit}`.
+
+Do NOT `git add` anything — this is read-only inspection.
+
+### Review
+
+**One-shot:** Skip diff construction. Still invoke `{adversarial_review_task}` in a subagent with the changed files — inline review invites anchoring bias.
+
+**Plan-code-review:** Launch three subagents without conversation context. If no sub-agents are available, generate three review prompt files in `{implementation_artifacts}` — one per reviewer role below — and HALT. Ask the human to run each in a separate session (ideally a different LLM) and paste back the findings.
+
+- **Blind hunter** — receives `{diff_output}` only. No spec, no context docs, no project access. Invoke via `{adversarial_review_task}`.
+- **Edge case hunter** — receives `{diff_output}` and read access to the project. Invoke via `{edge_case_hunter_task}`.
+- **Acceptance auditor** — receives `{diff_output}`, `{spec_file}`, and read access to the project. Must also read the docs listed in `{spec_file}` frontmatter `context`. Checks for violations of acceptance criteria, rules, and principles from the spec and context docs.
+
+### Classify
+
+1. Deduplicate all review findings.
+2. Classify each finding. The first three categories are **this story's problem** — caused or exposed by the current change. The last two are **not this story's problem**. 
+   - **intent_gap** — caused by the change; cannot be resolved from the spec because the captured intent is incomplete. Do not infer intent unless there is exactly one possible reading.
+   - **bad_spec** — caused by the change, including direct deviations from spec. The spec should have been clear enough to prevent it. When in doubt between bad_spec and patch, prefer bad_spec — a spec-level fix is more likely to produce coherent code.
+   - **patch** — caused by the change; trivially fixable without human input. Just part of the diff.
+   - **defer** — pre-existing issue not caused by this story, surfaced incidentally by the review. Collect for later focused attention.
+   - **reject** — noise. Drop silently. When unsure between defer and reject, prefer reject — only defer findings you are confident are real.
+3. Process findings in cascading order. If intent_gap or bad_spec findings exist, they trigger a loopback — lower findings are moot since code will be re-derived. If neither exists, process patch and defer normally. Increment `{specLoopIteration}` on each loopback. If it exceeds 5, HALT and escalate to the human. On any loopback, re-evaluate routing — if scope has grown beyond one-shot, escalate `execution_mode` to plan-code-review.
+   - **intent_gap** — Root cause is inside `<frozen-after-approval>`. Revert code changes. Loop back to the human to resolve, then re-run steps 2–4.
+   - **bad_spec** — Root cause is outside `<frozen-after-approval>`. Before reverting code: extract KEEP instructions for positive preservation (what worked well and must survive re-derivation). Revert code changes. Read the `## Spec Change Log` in `{spec_file}` and strictly respect all logged constraints when amending the non-frozen sections that contain the root cause. Append a new change-log entry recording: the triggering finding, what was amended, the known-bad state avoided, and the KEEP instructions. Read fully and follow `{installed_path}/steps/step-03-implement.md` to re-derive the code, then this step will run again.
+   - **patch** — Auto-fix. These are the only findings that survive loopbacks.
+   - **defer** — Append to `{deferred_work_file}`.
+   - **reject** — Drop silently.
+4. Commit.
+
+## NEXT
+
+Read fully and follow `{installed_path}/steps/step-05-present.md`

src/bmm/workflows/bmad-quick-flow/quick-dev-new-preview/steps/step-05-present.md

@@ -0,0 +1,19 @@
+---
+name: 'step-05-present'
+description: 'Present findings, get approval, create PR'
+---
+
+# Step 5: Present
+
+## RULES
+
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- NEVER auto-push.
+
+## INSTRUCTIONS
+
+1. If version control is available and the tree is dirty, create a local commit with a conventional message derived from the spec title.
+2. Change `{spec_file}` status to `done` in the frontmatter.
+3. Display summary of your work to the user, including the commit hash if one was created. Advise on how to review the changes. Offer to push and/or create a pull request.
+
+Workflow complete.

src/bmm/workflows/bmad-quick-flow/quick-dev-new-preview/tech-spec-template.md

@@ -0,0 +1,90 @@
+---
+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.
+---
+
+<!-- Target: 900–1300 tokens. Above 1600 = high risk of context rot.
+     Never over-specify "how" — use boundaries + examples instead.
+     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
+
+<!-- What is broken or missing, and why it matters. Then the high-level approach — the "what", not the "how". -->
+
+**Problem:** ONE_TO_TWO_SENTENCES
+
+**Approach:** ONE_TO_TWO_SENTENCES
+
+## Boundaries & Constraints
+
+<!-- Three tiers: Always = invariant rules. Ask First = human-gated decisions. Never = out of scope + forbidden approaches. -->
+
+**Always:** INVARIANT_RULES
+
+**Ask First:** DECISIONS_REQUIRING_HUMAN_APPROVAL
+<!-- Agent: if any of these trigger during execution, HALT and ask the user before proceeding. -->
+
+**Never:** NON_GOALS_AND_FORBIDDEN_APPROACHES
+
+## I/O & Edge-Case Matrix
+
+<!-- If no meaningful I/O scenarios exist, DELETE THIS ENTIRE SECTION. Do not write "N/A" or "None". -->
+
+| Scenario | Input / State | Expected Output / Behavior | Error Handling |
+|----------|--------------|---------------------------|----------------|
+| HAPPY_PATH | INPUT | OUTCOME | N/A |
+| ERROR_CASE | INPUT | OUTCOME | ERROR_HANDLING |
+
+</frozen-after-approval>
+
+## Code Map
+
+<!-- Agent-populated during planning. Annotated paths prevent blind codebase searching. -->
+
+- `FILE` -- ROLE_OR_RELEVANCE
+- `FILE` -- ROLE_OR_RELEVANCE
+
+## Tasks & Acceptance
+
+<!-- Tasks: backtick-quoted file path -- action -- rationale. Prefer one task per file; group tightly-coupled changes when splitting would be artificial. -->
+<!-- If an I/O Matrix is present, include a task to unit-test its edge cases. -->
+<!-- AC covers system-level behaviors not captured by the I/O Matrix. Do not duplicate I/O scenarios here. -->
+
+**Execution:**
+- [ ] `FILE` -- ACTION -- RATIONALE
+
+**Acceptance Criteria:**
+- Given PRECONDITION, when ACTION, then EXPECTED_RESULT
+
+## Spec Change Log
+
+<!-- Append-only. Populated by step-04 during review loops. Do not modify or delete existing entries.
+     Each entry records: what finding triggered the change, what was amended, what known-bad state
+     the amendment avoids, and any KEEP instructions (what worked well and must survive re-derivation).
+     Empty until the first bad_spec loopback. -->
+
+## Design Notes
+
+<!-- If the approach is straightforward, DELETE THIS ENTIRE SECTION. Do not write "N/A" or "None". -->
+<!-- Design rationale and golden examples only when non-obvious. Keep examples to 5–10 lines. -->
+
+DESIGN_RATIONALE_AND_EXAMPLES
+
+## Verification
+
+<!-- If no build, test, or lint commands apply, DELETE THIS ENTIRE SECTION. Do not write "N/A" or "None". -->
+<!-- How the agent confirms its own work. Prefer CLI commands. When no CLI check applies, state what to inspect manually. -->
+
+**Commands:**
+- `COMMAND` -- expected: SUCCESS_CRITERIA
+
+**Manual checks (if no CLI):**
+- WHAT_TO_INSPECT_AND_EXPECTED_STATE

src/bmm/workflows/bmad-quick-flow/quick-dev-new-preview/workflow.md

@@ -0,0 +1,90 @@
+---
+name: quick-dev-new-preview
+description: 'Unified quick flow - clarify intent, plan, implement, review, present.'
+main_config: '{project-root}/_bmad/bmm/config.yaml'
+
+# Related workflows
+advanced_elicitation: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+party_mode_exec: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+
+# Review building block
+adversarial_review_task: '{project-root}/_bmad/core/tasks/review-adversarial-general.xml'
+---
+
+# Quick Dev New Preview Workflow
+
+**Goal:** Take a user request from intent through implementation, adversarial review, and PR creation in a single unified flow.
+
+**Your Role:** You are an elite developer. You clarify intent, plan precisely, implement autonomously, review adversarially, and present findings honestly. Minimum ceremony, maximum signal.
+
+
+## READY FOR DEVELOPMENT STANDARD
+
+A specification is "Ready for Development" when:
+
+- **Actionable**: Every task has a file path and specific action.
+- **Logical**: Tasks ordered by dependency.
+- **Testable**: All ACs use Given/When/Then.
+- **Complete**: No placeholders or TBDs.
+
+
+## SCOPE STANDARD
+
+A specification should target a **single user-facing goal** within **900–1600 tokens**:
+
+- **Single goal**: One cohesive feature, even if it spans multiple layers/files. Multi-goal means >=2 **top-level independent shippable deliverables** — each could be reviewed, tested, and merged as a separate PR without breaking the others. Never count surface verbs, "and" conjunctions, or noun phrases. Never split cross-layer implementation details inside one user goal.
+  - Split: "add dark mode toggle AND refactor auth to JWT AND build admin dashboard"
+  - Don't split: "add validation and display errors" / "support drag-and-drop AND paste AND retry"
+- **900–1600 tokens**: Optimal range for LLM consumption. Below 900 risks ambiguity; above 1600 risks context-rot in implementation agents.
+- **Neither limit is a gate.** Both are proposals with user override.
+
+
+## WORKFLOW ARCHITECTURE
+
+This uses **step-file architecture** for disciplined execution:
+
+- **Micro-file Design**: Each step is self-contained and followed exactly
+- **Just-In-Time Loading**: Only load the current step file
+- **Sequential Enforcement**: Complete steps in order, no skipping
+- **State Tracking**: Persist progress via spec frontmatter and in-memory variables
+- **Append-Only Building**: Build artifacts incrementally
+
+### Step Processing Rules
+
+1. **READ COMPLETELY**: Read the entire step file before acting
+2. **FOLLOW SEQUENCE**: Execute sections in order
+3. **WAIT FOR INPUT**: Halt at checkpoints and wait for human
+4. **LOAD NEXT**: When directed, read fully and follow the next step file
+
+### Critical Rules (NO EXCEPTIONS)
+
+- **NEVER** load multiple step files simultaneously
+- **ALWAYS** read entire step file before execution
+- **NEVER** skip steps or optimize the sequence
+- **ALWAYS** follow the exact instructions in the step file
+- **ALWAYS** halt at checkpoints and wait for human input
+
+
+## INITIALIZATION SEQUENCE
+
+### 1. Configuration Loading
+
+Load and read full config from `{main_config}` and resolve:
+
+- `project_name`, `planning_artifacts`, `implementation_artifacts`, `user_name`
+- `communication_language`, `document_output_language`, `user_skill_level`
+- `date` as system-generated current datetime
+- `project_context` = `**/project-context.md` (load if exists)
+- CLAUDE.md / memory files (load if exist)
+
+YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`.
+
+### 2. Paths
+
+- `installed_path` = `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev-new-preview`
+- `templateFile` = `{installed_path}/tech-spec-template.md`
+- `wipFile` = `{implementation_artifacts}/tech-spec-wip.md`
+
+### 3. First Step Execution
+
+Read fully and follow: `{installed_path}/steps/step-01-clarify-and-route.md` to begin the workflow.

test/test-github-copilot-installer.js

@@ -0,0 +1,238 @@
+/**
+ * GitHub Copilot Installer Tests
+ *
+ * Tests for the GitHubCopilotSetup class methods:
+ * - loadModuleConfig: module-aware config loading
+ * - createTechWriterPromptContent: BMM-only tech-writer handling
+ * - generateCopilotInstructions: selectedModules deduplication
+ *
+ * Usage: node test/test-github-copilot-installer.js
+ */
+
+const path = require('node:path');
+const fs = require('fs-extra');
+const { GitHubCopilotSetup } = require('../tools/cli/installers/lib/ide/github-copilot');
+
+// ANSI colors
+const colors = {
+  reset: '\u001B[0m',
+  green: '\u001B[32m',
+  red: '\u001B[31m',
+  yellow: '\u001B[33m',
+  cyan: '\u001B[36m',
+  dim: '\u001B[2m',
+};
+
+let passed = 0;
+let failed = 0;
+
+/**
+ * Test helper: Assert condition
+ */
+function assert(condition, testName, errorMessage = '') {
+  if (condition) {
+    console.log(`${colors.green}✓${colors.reset} ${testName}`);
+    passed++;
+  } else {
+    console.log(`${colors.red}✗${colors.reset} ${testName}`);
+    if (errorMessage) {
+      console.log(`  ${colors.dim}${errorMessage}${colors.reset}`);
+    }
+    failed++;
+  }
+}
+
+/**
+ * Test Suite
+ */
+async function runTests() {
+  console.log(`${colors.cyan}========================================`);
+  console.log('GitHub Copilot Installer Tests');
+  console.log(`========================================${colors.reset}\n`);
+
+  const tempDir = path.join(__dirname, 'temp-copilot-test');
+
+  try {
+    // Clean up any leftover temp directory
+    await fs.remove(tempDir);
+    await fs.ensureDir(tempDir);
+
+    const installer = new GitHubCopilotSetup();
+
+    // ============================================================
+    // Test Suite 1: loadModuleConfig
+    // ============================================================
+    console.log(`${colors.yellow}Test Suite 1: loadModuleConfig${colors.reset}\n`);
+
+    // Create mock bmad directory structure with multiple modules
+    const bmadDir = path.join(tempDir, '_bmad');
+    await fs.ensureDir(path.join(bmadDir, 'core'));
+    await fs.ensureDir(path.join(bmadDir, 'bmm'));
+    await fs.ensureDir(path.join(bmadDir, 'custom-module'));
+
+    // Create config files for each module
+    await fs.writeFile(path.join(bmadDir, 'core', 'config.yaml'), 'project_name: Core Project\nuser_name: CoreUser\n');
+    await fs.writeFile(path.join(bmadDir, 'bmm', 'config.yaml'), 'project_name: BMM Project\nuser_name: BmmUser\n');
+    await fs.writeFile(path.join(bmadDir, 'custom-module', 'config.yaml'), 'project_name: Custom Project\nuser_name: CustomUser\n');
+
+    // Test 1a: Load config with only core module (default)
+    const coreConfig = await installer.loadModuleConfig(bmadDir, ['core']);
+    assert(
+      coreConfig.project_name === 'Core Project',
+      'loadModuleConfig loads core config when only core installed',
+      `Got: ${coreConfig.project_name}`,
+    );
+
+    // Test 1b: Load config with bmm module (should prefer bmm over core)
+    const bmmConfig = await installer.loadModuleConfig(bmadDir, ['bmm', 'core']);
+    assert(bmmConfig.project_name === 'BMM Project', 'loadModuleConfig prefers bmm config over core', `Got: ${bmmConfig.project_name}`);
+
+    // Test 1c: Load config with custom module (should prefer custom over core)
+    const customConfig = await installer.loadModuleConfig(bmadDir, ['custom-module', 'core']);
+    assert(
+      customConfig.project_name === 'Custom Project',
+      'loadModuleConfig prefers custom module config over core',
+      `Got: ${customConfig.project_name}`,
+    );
+
+    // Test 1d: Load config with multiple non-core modules (first wins)
+    const multiConfig = await installer.loadModuleConfig(bmadDir, ['bmm', 'custom-module', 'core']);
+    assert(
+      multiConfig.project_name === 'BMM Project',
+      'loadModuleConfig uses first non-core module config',
+      `Got: ${multiConfig.project_name}`,
+    );
+
+    // Test 1e: Empty modules list uses default (core)
+    const defaultConfig = await installer.loadModuleConfig(bmadDir);
+    assert(
+      defaultConfig.project_name === 'Core Project',
+      'loadModuleConfig defaults to core when no modules specified',
+      `Got: ${defaultConfig.project_name}`,
+    );
+
+    // Test 1f: Non-existent module falls back to core
+    const fallbackConfig = await installer.loadModuleConfig(bmadDir, ['nonexistent', 'core']);
+    assert(
+      fallbackConfig.project_name === 'Core Project',
+      'loadModuleConfig falls back to core for non-existent modules',
+      `Got: ${fallbackConfig.project_name}`,
+    );
+
+    console.log('');
+
+    // ============================================================
+    // Test Suite 2: createTechWriterPromptContent (BMM-only)
+    // ============================================================
+    console.log(`${colors.yellow}Test Suite 2: createTechWriterPromptContent (BMM-only)${colors.reset}\n`);
+
+    // Test 2a: BMM tech-writer entry should generate content
+    const bmmTechWriterEntry = {
+      'agent-name': 'tech-writer',
+      module: 'bmm',
+      name: 'Write Document',
+    };
+    const bmmResult = installer.createTechWriterPromptContent(bmmTechWriterEntry);
+    assert(
+      bmmResult !== null && bmmResult.fileName === 'bmad-bmm-write-document',
+      'createTechWriterPromptContent generates content for BMM tech-writer',
+      `Got: ${bmmResult ? bmmResult.fileName : 'null'}`,
+    );
+
+    // Test 2b: Non-BMM tech-writer entry should return null
+    const customTechWriterEntry = {
+      'agent-name': 'tech-writer',
+      module: 'custom-module',
+      name: 'Write Document',
+    };
+    const customResult = installer.createTechWriterPromptContent(customTechWriterEntry);
+    assert(customResult === null, 'createTechWriterPromptContent returns null for non-BMM tech-writer', `Got: ${customResult}`);
+
+    // Test 2c: Core tech-writer entry should return null
+    const coreTechWriterEntry = {
+      'agent-name': 'tech-writer',
+      module: 'core',
+      name: 'Write Document',
+    };
+    const coreResult = installer.createTechWriterPromptContent(coreTechWriterEntry);
+    assert(coreResult === null, 'createTechWriterPromptContent returns null for core tech-writer', `Got: ${coreResult}`);
+
+    // Test 2d: Non-tech-writer BMM entry should return null
+    const nonTechWriterEntry = {
+      'agent-name': 'pm',
+      module: 'bmm',
+      name: 'Write Document',
+    };
+    const nonTechResult = installer.createTechWriterPromptContent(nonTechWriterEntry);
+    assert(nonTechResult === null, 'createTechWriterPromptContent returns null for non-tech-writer agents', `Got: ${nonTechResult}`);
+
+    // Test 2e: Unknown tech-writer command should return null
+    const unknownCmdEntry = {
+      'agent-name': 'tech-writer',
+      module: 'bmm',
+      name: 'Unknown Command',
+    };
+    const unknownResult = installer.createTechWriterPromptContent(unknownCmdEntry);
+    assert(unknownResult === null, 'createTechWriterPromptContent returns null for unknown commands', `Got: ${unknownResult}`);
+
+    console.log('');
+
+    // ============================================================
+    // Test Suite 3: selectedModules deduplication
+    // ============================================================
+    console.log(`${colors.yellow}Test Suite 3: selectedModules deduplication${colors.reset}\n`);
+
+    // We can't easily test generateCopilotInstructions directly without mocking,
+    // but we can verify the deduplication logic pattern
+    const testDedupe = (modules) => {
+      const installedModules = modules.length > 0 ? [...new Set(modules)] : ['core'];
+      return installedModules;
+    };
+
+    // Test 3a: Duplicate modules should be deduplicated
+    const dupeResult = testDedupe(['bmm', 'core', 'bmm', 'custom', 'core', 'custom']);
+    assert(
+      dupeResult.length === 3 && dupeResult.includes('bmm') && dupeResult.includes('core') && dupeResult.includes('custom'),
+      'Deduplication removes duplicate modules',
+      `Got: ${JSON.stringify(dupeResult)}`,
+    );
+
+    // Test 3b: Empty array defaults to core
+    const emptyResult = testDedupe([]);
+    assert(
+      emptyResult.length === 1 && emptyResult[0] === 'core',
+      'Empty modules array defaults to core',
+      `Got: ${JSON.stringify(emptyResult)}`,
+    );
+
+    // Test 3c: Order is preserved after deduplication (first occurrence wins)
+    const orderResult = testDedupe(['custom', 'bmm', 'custom', 'bmm']);
+    assert(
+      orderResult[0] === 'custom' && orderResult[1] === 'bmm',
+      'Deduplication preserves order (first occurrence)',
+      `Got: ${JSON.stringify(orderResult)}`,
+    );
+  } finally {
+    // Cleanup
+    await fs.remove(tempDir);
+  }
+
+  // Print summary
+  console.log(`${colors.cyan}========================================`);
+  console.log('Test Results:');
+  console.log(`  Passed: ${passed}`);
+  console.log(`  Failed: ${failed}`);
+  console.log(`========================================${colors.reset}\n`);
+
+  if (failed > 0) {
+    console.log(`${colors.red}Some tests failed!${colors.reset}`);
+    process.exit(1);
+  } else {
+    console.log(`${colors.green}✨ All GitHub Copilot installer tests passed!${colors.reset}`);
+  }
+}
+
+runTests().catch((error) => {
+  console.error(`${colors.red}Test runner error:${colors.reset}`, error);
+  process.exit(1);
+});

tools/cli/installers/lib/ide/github-copilot.js

@@ -247,9 +247,9 @@ You must fully embody this agent's persona and follow all activation instruction
    */
   createWorkflowPromptContent(entry, workflowFile, toolsStr) {
     const description = this.escapeYamlSingleQuote(this.createPromptDescription(entry.name));
-    // bmm/config.yaml is safe to hardcode here: these prompts are only generated when
+    // Use the module from the bmad-help.csv entry to reference the correct config.yaml
-    // bmad-help.csv exists (bmm module data), so bmm is guaranteed to be installed.
+    const configModule = entry.module || 'core';
-    const configLine = `1. Load {project-root}/${this.bmadFolderName}/bmm/config.yaml and store ALL fields as session variables`;
+    const configLine = `1. Load {project-root}/${this.bmadFolderName}/${configModule}/config.yaml and store ALL fields as session variables`;
 
     let body;
     if (workflowFile.endsWith('.yaml')) {
@@ -324,11 +324,13 @@ ${body}
 
   /**
    * Create prompt content for tech-writer agent-only commands (Pattern C)
+   * Tech-writer is BMM-specific - these commands only work with the BMM module.
    * @param {Object} entry - bmad-help.csv row
    * @returns {Object|null} { fileName, content } or null if not a tech-writer command
    */
   createTechWriterPromptContent(entry) {
-    if (entry['agent-name'] !== 'tech-writer') return null;
+    // Tech-writer is BMM-specific - only process entries from the bmm module
+    if (entry['agent-name'] !== 'tech-writer' || entry.module !== 'bmm') return null;
 
     const techWriterCommands = {
       'Write Document': { code: 'WD', file: 'bmad-bmm-write-document', description: 'Write document' },
@@ -344,14 +346,16 @@ ${body}
     const safeDescription = this.escapeYamlSingleQuote(cmd.description);
     const toolsStr = this.getToolsForFile(`${cmd.file}.prompt.md`);
 
+    // Use the module from the bmad-help.csv entry to reference the correct paths
+    const configModule = entry.module || 'core';
     const content = `---
 description: '${safeDescription}'
 agent: 'agent'
 tools: ${toolsStr}
 ---
 
-1. Load {project-root}/${this.bmadFolderName}/bmm/config.yaml and store ALL fields as session variables
+1. Load {project-root}/${this.bmadFolderName}/${configModule}/config.yaml and store ALL fields as session variables
-2. Load the full agent file from {project-root}/${this.bmadFolderName}/bmm/agents/tech-writer/tech-writer.md and activate the Paige (Technical Writer) persona
+2. Load the full agent file from {project-root}/${this.bmadFolderName}/${configModule}/agents/tech-writer/tech-writer.md and activate the Paige (Technical Writer) persona
 3. Execute the ${entry.name} menu command (${cmd.code})
 `;
 
@@ -376,15 +380,15 @@ tools: ${toolsStr}
     const agentPath = artifact.agentPath || artifact.relativePath;
     const agentFilePath = `{project-root}/${this.bmadFolderName}/${agentPath}`;
 
-    // bmm/config.yaml is safe to hardcode: agent activators are only generated from
+    // Use the agent's module to reference the correct config.yaml
-    // bmm agent artifacts, so bmm is guaranteed to be installed.
+    const configModule = artifact.module || 'core';
     return `---
 description: '${safeDescription}'
 agent: 'agent'
 tools: ${toolsStr}
 ---
 
-1. Load {project-root}/${this.bmadFolderName}/bmm/config.yaml and store ALL fields as session variables
+1. Load {project-root}/${this.bmadFolderName}/${configModule}/config.yaml and store ALL fields as session variables
 2. Load the full agent file from ${agentFilePath}
 3. Follow ALL activation instructions in the agent file
 4. Display the welcome/greeting as instructed
@@ -400,7 +404,13 @@ tools: ${toolsStr}
    * @param {Map} agentManifest - Agent manifest data
    */
   async generateCopilotInstructions(projectDir, bmadDir, agentManifest, options = {}) {
-    const configVars = await this.loadModuleConfig(bmadDir);
+    // Determine installed modules (excluding internal directories)
+    const selectedModules = options.selectedModules || [];
+    // Deduplicate selectedModules to prevent duplicate paths in generated markdown
+    const installedModules = selectedModules.length > 0 ? [...new Set(selectedModules)] : ['core'];
+    const configVars = await this.loadModuleConfig(bmadDir, installedModules);
+    // Filter to only non-core modules for display (core is always listed separately)
+    const nonCoreModules = installedModules.filter((m) => m !== 'core');
 
     // Build the agents table from the manifest
     let agentsTable = '| Agent | Persona | Title | Capabilities |\n|---|---|---|---|\n';
@@ -427,6 +437,36 @@ tools: ${toolsStr}
     }
 
     const bmad = this.bmadFolderName;
+
+    // Build dynamic module paths based on installed modules
+    const moduleAgentPaths = nonCoreModules.map((m) => `\`${bmad}/${m}/agents/\``).join(', ');
+    const moduleWorkflowPaths = nonCoreModules.map((m) => `\`${bmad}/${m}/workflows/\``).join(', ');
+    const moduleConfigPaths = nonCoreModules.map((m) => `\`${bmad}/${m}/config.yaml\``).join(', ');
+
+    // Build agent definitions line
+    let agentDefsLine;
+    if (nonCoreModules.length > 0) {
+      agentDefsLine = `- **Agent definitions**: ${moduleAgentPaths} and \`${bmad}/core/agents/\` (core)`;
+    } else {
+      agentDefsLine = `- **Agent definitions**: \`${bmad}/core/agents/\``;
+    }
+
+    // Build workflow definitions line
+    let workflowDefsLine;
+    if (nonCoreModules.length > 0) {
+      workflowDefsLine = `- **Workflow definitions**: ${moduleWorkflowPaths} (organized by phase)`;
+    } else {
+      workflowDefsLine = `- **Workflow definitions**: \`${bmad}/core/workflows/\``;
+    }
+
+    // Build module configuration line
+    let moduleConfigLine;
+    if (nonCoreModules.length > 0) {
+      moduleConfigLine = `- **Module configuration**: ${moduleConfigPaths}`;
+    } else {
+      moduleConfigLine = `- **Module configuration**: (no non-core modules installed)`;
+    }
+
     const bmadSection = `# BMAD Method — Project Instructions
 
 ## Project Configuration
@@ -443,12 +483,12 @@ tools: ${toolsStr}
 
 ## BMAD Runtime Structure
 
-- **Agent definitions**: \`${bmad}/bmm/agents/\` (BMM module) and \`${bmad}/core/agents/\` (core)
+${agentDefsLine}
-- **Workflow definitions**: \`${bmad}/bmm/workflows/\` (organized by phase)
+${workflowDefsLine}
 - **Core tasks**: \`${bmad}/core/tasks/\` (help, editorial review, indexing, sharding, adversarial review)
 - **Core workflows**: \`${bmad}/core/workflows/\` (brainstorming, party-mode, advanced-elicitation)
 - **Workflow engine**: \`${bmad}/core/tasks/workflow.xml\` (executes YAML-based workflows)
-- **Module configuration**: \`${bmad}/bmm/config.yaml\`
+${moduleConfigLine}
 - **Core configuration**: \`${bmad}/core/config.yaml\`
 - **Agent manifest**: \`${bmad}/_config/agent-manifest.csv\`
 - **Workflow manifest**: \`${bmad}/_config/workflow-manifest.csv\`
@@ -457,7 +497,7 @@ tools: ${toolsStr}
 
 ## Key Conventions
 
-- Always load \`${bmad}/bmm/config.yaml\` before any agent activation or workflow execution
+- Always load the agent/workflow's module \`config.yaml\` before activation or execution (each prompt file specifies which config to load)
 - Store all config fields as session variables: \`{user_name}\`, \`{communication_language}\`, \`{output_folder}\`, \`{planning_artifacts}\`, \`{implementation_artifacts}\`, \`{project_knowledge}\`
 - MD-based workflows execute directly — load and follow the \`.md\` file
 - YAML-based workflows require the workflow engine — load \`workflow.xml\` first, then pass the \`.yaml\` config
@@ -504,13 +544,15 @@ Type \`/bmad-\` in Copilot Chat to see all available BMAD workflows and agent ac
   /**
    * Load module config.yaml for template variables
    * @param {string} bmadDir - BMAD installation directory
+   * @param {string[]} installedModules - List of installed modules to check for config
    * @returns {Object} Config variables
    */
-  async loadModuleConfig(bmadDir) {
+  async loadModuleConfig(bmadDir, installedModules = ['core']) {
-    const bmmConfigPath = path.join(bmadDir, 'bmm', 'config.yaml');
+    // Build config paths from installed modules (non-core first, then core as fallback)
-    const coreConfigPath = path.join(bmadDir, 'core', 'config.yaml');
+    const nonCoreModules = installedModules.filter((m) => m !== 'core');
+    const configPaths = [...nonCoreModules.map((m) => path.join(bmadDir, m, 'config.yaml')), path.join(bmadDir, 'core', 'config.yaml')];
 
-    for (const configPath of [bmmConfigPath, coreConfigPath]) {
+    for (const configPath of configPaths) {
       if (await fs.pathExists(configPath)) {
         try {
           const content = await fs.readFile(configPath, 'utf8');