Merge 33bd6b5d86 into 3ba51e1bac

* feat(quick-dev): add epic context compilation to step-01

Fork step-01 context loading: epic stories get a sub-agent that
compiles planning docs into a cached epic-{N}-context.md, while
freeform intents keep the lightweight directory-listing path.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(quick-dev): tighten epic context loading per PR review

- Validate cached epic-<N>-context.md is non-empty and starts with the
  expected header before loading; treat invalid cache as missing.
- Replace inline {N} placeholders with <N> so the skill validator does
  not flag them as unresolved workflow variables.
- Replace ambiguous "fall back to path B" with an explicit instruction
  to scan/load planning artifacts using path B's procedure, with a note
  not to re-evaluate path B's gating clause.

Addresses CodeRabbit and Augment review comments on PR #2218.

* refactor(quick-dev): tighten compile-epic-context prompt

- Restructure with Task/Steps opening and Exact Output Format section.
- Switch Stories template to bullet form for clarity.
- Add "no hallucination" and explicit "omit empty sections except Goal
  and Stories" rules.
- Use <N> instead of {N} in the filename for consistency with step-01.

* refactor(quick-dev): restructure epic-story context loading

Reshape path A of step-01 into five explicit numbered steps and add an
inline-compilation fallback for runtimes that cannot spawn sub-agents
(Copilot, Codex, local Ollama, older Claude).

- Pull cache validity, compilation, verification, and continuity into
  separate numbered steps instead of nested paragraphs.
- Define "valid cached context" upfront: non-empty and starts with
  `# Epic <N> Context:`.
- Add inline-compilation fallback: runtimes without sub-agent support
  read compile-epic-context.md and follow it directly.
- Make previous-story continuity run regardless of which context source
  succeeded (cache hit, fresh compilation, or path-B raw fallback).

* fix(quick-dev): address review findings on epic context compilation

- Add freshness check to cached epic-N-context.md (invalidate when any
  planning artifact is newer)
- Remove the silent fall-back-to-raw-planning-docs path on compile
  failure; HALT and report instead
- Add explicit "ambiguous → freeform" tiebreakers for both the path A
  header and the epic-number identification step
- Drop "verbatim" from compile-epic-context.md format header to resolve
  the verbatim-vs-omit-empty contradiction

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

src/bmm-skills/4-implementation/bmad-quick-dev/compile-epic-context.md

@@ -0,0 +1,62 @@
+# Compile Epic Context
+
+**Task**
+Given an epic number, the epics file, the planning artifacts directory, and a desired output path, compile a clean, focused, developer-ready context file (`epic-<N>-context.md`).
+
+**Steps**
+
+1. Read the epics file and extract the target epic's title, goal, and list of stories.
+2. Scan the planning artifacts directory for the standard files (PRD, architecture, UX/design, product brief).
+3. Pull only the information relevant to this epic.
+4. Write the compiled context to the exact output path using the format below.
+
+## Exact Output Format
+
+Use these headings:
+
+```markdown
+# Epic {N} Context: {Epic Title}
+
+<!-- Compiled from planning artifacts. Edit freely. Regenerate with compile-epic-context if planning docs change. -->
+
+## Goal
+
+{One clear paragraph: what this epic achieves and why it matters.}
+
+## Stories
+
+- Story X.Y: Brief title only
+- ...
+
+## Requirements & Constraints
+
+{Relevant functional/non-functional requirements and success criteria for this epic (describe by purpose, not source).}
+
+## Technical Decisions
+
+{Key architecture decisions, constraints, patterns, data models, and conventions relevant to this epic.}
+
+## UX & Interaction Patterns
+
+{Relevant UX flows, interaction patterns, and design constraints (omit section entirely if nothing relevant).}
+
+## Cross-Story Dependencies
+
+{Dependencies between stories in this epic or with other epics/systems (omit if none).}
+```
+
+## Rules
+
+- **Scope aggressively.** Include only what a developer working on any story in this epic actually needs. When in doubt, leave it out — the developer can always read the full planning doc.
+- **Describe by purpose, not by source.** Write "API responses must include pagination metadata" not "Per PRD section 3.2.1, pagination is required." Planning doc internals will change; the constraint won't.
+- **No full copies.** Never quote source documents, section numbers, or paste large blocks verbatim. Always distill.
+- **No story-level details.** The story list is for orientation only. Individual story specs handle the details.
+- **Nothing derivable from the codebase.** Don't document what a developer can learn by reading the code.
+- **Be concise and actionable.** Target 800–1500 tokens total. This file loads into quick-dev's context alongside other material.
+- **Never hallucinate content.** If source material doesn't say something, don't invent it.
+- **Omit empty sections entirely**, except Goal and Stories, which are always required.
+
+## Error handling
+
+- **If the epics file is missing or the target epic is not found:** write nothing and report the problem to the calling agent. Goal and Stories cannot be populated without a usable epics file.
+- **If planning artifacts are missing or empty:** still produce the file with Goal and Stories populated from the epics file, and note the gap in the Goal section. Never hallucinate content to fill missing sections.

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

@@ -53,7 +53,7 @@ context: [] # optional: `{project-root}/`-prefixed paths to project-wide standar
 ## 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. -->
+<!-- REQUIRED: Include test tasks for every new or modified behavior. 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:**

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

@@ -41,19 +41,32 @@ 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:
+   - **Determine context strategy.** Using the intent and the artifact listing, infer whether the current work is a story from an epic. Do not rely on filename patterns or regex — reason about the intent, the listing, and any epics file content together.
-     - **PRD** (`*prd*`) — product requirements and success criteria
+
-     - **Architecture** (`*architecture*`) — technical design decisions and constraints
+     **A) Epic story path** — if the intent is clearly an epic story:
-     - **UX/Design** (`*ux*`) — user experience and interaction design
+
-     - **Epics** (`*epic*`) — feature breakdown into implementable stories
+     1. Identify the epic number and (if present) the story number. If you can't identify an epic number, use path B.
-     - **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.
+     2. **Check for a valid cached epic context.** Look for `{implementation_artifacts}/epic-<N>-context.md` (where `<N>` is the epic number). A file is **valid** when it exists, is non-empty, starts with `# Epic <N> Context:` (with the correct epic number), and no file in `{planning_artifacts}` is newer.
-   - **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:
+        - **If valid:** load it as the primary planning context. Do not load raw planning docs (PRD, architecture, UX, etc.). Skip to step 5.
-     1. Identify the epic and story number.
+        - **If missing, empty, or invalid:** continue to step 3.
-     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).
+     3. **Compile epic context.** Produce `{implementation_artifacts}/epic-<N>-context.md` by following `./compile-epic-context.md`, in order of preference:
-     4. Extract its **Code Map**, **Design Notes**, **Spec Change Log**, and **task list** as continuity context for step-02 planning.
+        - **Preferred — sub-agent:** spawn a sub-agent with `./compile-epic-context.md` as its prompt. Pass it the epic number, the epics file path, the `{planning_artifacts}` directory, and the output path `{implementation_artifacts}/epic-<N>-context.md`.
-     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.
+        - **Fallback — inline** (for runtimes without sub-agent support, e.g. Copilot, Codex, local Ollama, older Claude): if your runtime cannot spawn sub-agents, or the spawn fails/times out, read `./compile-epic-context.md` yourself and follow its instructions to produce the same output file.
+
+     4. **Verify.** After compilation, verify the output file exists, is non-empty, and starts with `# Epic <N> Context:`. If valid, load it. If verification fails, HALT and report the failure.
+
+     5. **Previous story continuity.** Regardless of which context source succeeded above, scan `{implementation_artifacts}` for specs from the same epic with `status: done` and a lower story number. Load the most recent one (highest story number below current). 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.
+
+     **B) Freeform path** — if the intent is not an epic story:
+     - 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.
 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:

src/bmm-skills/4-implementation/bmad-quick-dev/step-02-plan.md

@@ -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**: Set status `ready-for-dev` in `{spec_file}`. 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.
 
 

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

@@ -30,9 +30,27 @@ Hand `{spec_file}` to a sub-agent/task and let it implement. If no sub-agents ar
 
 **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.
 
+### Tests
+
+**This is mandatory, not optional.** After implementation, write tests for every new or modified behavior. Follow the project's testing conventions discovered from `{project_context}`, CLAUDE.md, the existing test suite, and any configured test tooling.
+
+1. **Discover conventions.** Identify the project's test framework, file-naming patterns, and test directory structure in this order:
+   - First, inspect existing tests.
+   - If existing tests are missing or insufficient, inspect the repo's configured test tooling: test scripts, dependencies/devDependencies, and test config files (for example `package.json`, `pytest.ini`, `pyproject.toml`, `jest.config.*`, `vitest.config.*`, `mocha` config, `rspec` config, `go test` conventions, etc.).
+   - Only if neither existing tests nor configured tooling establish conventions should you fall back to the project's language-idiomatic defaults.
+2. **Write tests.** Cover:
+   - Happy-path behavior for each new or changed feature.
+   - Edge cases and error scenarios from the I/O & Edge-Case Matrix (if present in the spec).
+   - Regressions — any behavior that could break due to the change.
+3. **Run tests.** Execute the test suite. All new and existing tests must pass. If any test fails, fix the implementation or the test before proceeding.
+
+If the project has no test infrastructure at all (no existing tests, no test framework, no relevant test config, no test directory, and no test scripts), note this in the spec under `## Verification` and skip — but this is the only acceptable reason to skip tests. Record this skip reason explicitly in the final summary output.
+
 ### 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.
+Before leaving this step, verify:
+1. 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.
+2. Tests exist for every new or modified behavior (unless the project has no test infrastructure). If tests are missing, go back and write them before proceeding.
 
 ## NEXT
 

src/bmm-skills/4-implementation/bmad-quick-dev/step-04-review.md

@@ -26,7 +26,7 @@ Launch three subagents without conversation context. If no sub-agents are availa
 
 - **Blind hunter** — receives `{diff_output}` only. No spec, no context docs, no project access. Invoke via the `bmad-review-adversarial-general` skill.
 - **Edge case hunter** — receives `{diff_output}` and read access to the project. Invoke via the `bmad-review-edge-case-hunter` skill.
-- **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.
+- **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. **Must also verify that tests exist for every new or modified behavior** — missing test coverage for changed code is a `bad_spec` finding unless the project has no test infrastructure.
 
 ### Classify
 

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

@@ -15,6 +15,19 @@ deferred_work_file: '{implementation_artifacts}/deferred-work.md'
 
 Implement the clarified intent directly.
 
+### Tests
+
+**This is mandatory, not optional.** After implementation, write tests for every new or modified behavior. Follow the project's testing conventions discovered from `{project_context}`, CLAUDE.md, the existing test suite, and any configured test tooling.
+
+1. **Discover conventions.** Identify the project's test framework, file-naming patterns, and test directory structure in this order:
+   - First, inspect existing tests.
+   - If existing tests are missing or insufficient, inspect the repo's configured test tooling: test scripts, dependencies/devDependencies, and test config files (for example `package.json`, `pytest.ini`, `pyproject.toml`, `jest.config.*`, `vitest.config.*`, `mocha` config, `rspec` config, `go test` conventions, etc.).
+   - Only if neither existing tests nor configured tooling establish conventions should you fall back to the project's language-idiomatic defaults.
+2. **Write tests.** Cover happy-path behavior, edge cases, and regressions.
+3. **Run tests.** All new and existing tests must pass. Fix failures before proceeding.
+
+If the project has no test infrastructure at all (no existing tests, no test framework, no relevant test config, no test directory, and no test scripts), skip — but this is the only acceptable reason to skip tests. Record this skip reason explicitly in the final summary output.
+
 ### Review
 
 Invoke the `bmad-review-adversarial-general` skill in a subagent with the changed files. The subagent gets NO conversation context — to avoid anchoring bias. If no sub-agents are available, write the changed files to a review prompt file in `{implementation_artifacts}` and HALT. Ask the human to run the review in a separate session and paste back the findings.

src/bmm-skills/module-help.csv

@@ -1,4 +1,5 @@
 module,skill,display-name,menu-code,description,action,args,phase,after,before,required,output-location,outputs
+BMad Method,_meta,,,,,,,,,false,https://docs.bmad-method.org/llms.txt,
 BMad Method,bmad-document-project,Document Project,DP,Analyze an existing project to produce useful documentation.,,anytime,,,false,project-knowledge,*
 BMad Method,bmad-generate-project-context,Generate Project Context,GPC,Scan existing codebase to generate a lean LLM-optimized project-context.md. Essential for brownfield projects.,,anytime,,,false,output_folder,project context
 BMad Method,bmad-quick-dev,Quick Dev,QQ,Unified intent-in code-out workflow: clarify plan implement review and present.,,anytime,,,false,implementation_artifacts,spec and project implementation

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

@@ -7,7 +7,7 @@ description: 'Analyzes current state and user query to answer BMad questions or
 
 ## Purpose
 
-Help the user understand where they are in their BMad workflow and what to do next. Answer BMad questions when asked.
+Help the user understand where they are in their BMad workflow and what to do next, and also answer broader questions when asked that could be augmented with remote sources such as module documentation sources.
 
 ## Desired Outcomes
 
@@ -18,6 +18,7 @@ When this skill completes, the user should:
 3. **Know how to invoke it** — skill name, menu code, action context, and any args that shortcut the conversation
 4. **Get offered a quick start** — when a single skill is the clear next step, offer to run it for the user right now rather than just listing it
 5. **Feel oriented, not overwhelmed** — surface only what's relevant to their current position; don't dump the entire catalog
+6. **Get answers to general questions** — when the question doesn't map to a specific skill, use the module's registered documentation to give a grounded answer
 
 ## Data Sources
 
@@ -25,6 +26,7 @@ When this skill completes, the user should:
 - **Config**: `config.yaml` and `user-config.yaml` files in `{project-root}/_bmad/` and its subfolders — resolve `output-location` variables, provide `communication_language` and `project_knowledge`
 - **Artifacts**: Files matching `outputs` patterns at resolved `output-location` paths reveal which steps are possibly completed; their content may also provide grounding context for recommendations
 - **Project knowledge**: If `project_knowledge` resolves to an existing path, read it for grounding context. Never fabricate project-specific details.
+- **Module docs**: Rows with `_meta` in the `skill` column carry a URL or path in `output-location` pointing to the module's documentation (e.g., llms.txt). Fetch and use these to answer general questions about that module.
 
 ## CSV Interpretation
 
@@ -70,4 +72,4 @@ For each recommended item, present:
 - Present all output in `{communication_language}`
 - Recommend running each skill in a **fresh context window**
 - Match the user's tone — conversational when they're casual, structured when they want specifics
-- If the active module is ambiguous, ask rather than guess
+- If the active module is ambiguous, retrieve all meta rows remote sources to find relevant info also to help answer their question

src/core-skills/module-help.csv

@@ -1,4 +1,5 @@
 module,skill,display-name,menu-code,description,action,args,phase,after,before,required,output-location,outputs
+Core,_meta,,,,,,,,,false,https://docs.bmad-method.org/llms.txt,
 Core,bmad-brainstorming,Brainstorming,BSP,Use early in ideation or when stuck generating ideas.,,anytime,,,false,{output_folder}/brainstorming,brainstorming session
 Core,bmad-party-mode,Party Mode,PM,Orchestrate multi-agent discussions when you need multiple perspectives or want agents to collaborate.,,anytime,,,false,,
 Core,bmad-help,BMad Help,BH,,,anytime,,,false,,

tools/installer/core/installer.js

@@ -969,6 +969,14 @@ class Installer {
                 outputs,
               ] = columns;
 
+              // Pass through _meta rows as-is (module metadata, not a skill)
+              if (phase === '_meta') {
+                const finalModule = (!module || module.trim() === '') && moduleName !== 'core' ? moduleName : module || '';
+                const metaRow = [finalModule, '_meta', '', '', '', '', '', 'false', '', '', '', '', '', '', outputLocation || '', ''];
+                allRows.push(metaRow.map((c) => this.escapeCSVField(c)).join(','));
+                continue;
+              }
+
               // If module column is empty, set it to this module's name (except for core which stays empty for universal tools)
               const finalModule = (!module || module.trim() === '') && moduleName !== 'core' ? moduleName : module || '';