From 6446b687b8fe397d2ac6a2c6ae878b5b8ffe7a72 Mon Sep 17 00:00:00 2001 From: Alex Verkhovsky Date: Sun, 5 Apr 2026 09:29:38 -0700 Subject: [PATCH 1/4] 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) --- .../bmad-quick-dev/compile-epic-context.md | 72 +++++++++++++++++++ .../step-01-clarify-and-route.md | 30 ++++---- 2 files changed, 89 insertions(+), 13 deletions(-) create mode 100644 src/bmm-skills/4-implementation/bmad-quick-dev/compile-epic-context.md diff --git a/src/bmm-skills/4-implementation/bmad-quick-dev/compile-epic-context.md b/src/bmm-skills/4-implementation/bmad-quick-dev/compile-epic-context.md new file mode 100644 index 000000000..d554b96ed --- /dev/null +++ b/src/bmm-skills/4-implementation/bmad-quick-dev/compile-epic-context.md @@ -0,0 +1,72 @@ +# Compile Epic Context + +You are a context-compilation agent. Your job is to read planning artifacts and produce a single, scoped context document for one epic. + +## Inputs + +You will receive: + +- **Epic number** — which epic to compile context for +- **Epics file path** — the file containing epic and story definitions +- **Planning artifacts directory** — where PRD, architecture, UX, and other planning docs live +- **Output path** — where to write the compiled context file + +## Instructions + +1. **Load the epics file** and extract the definition for the target epic: its title, goal, and story list. + +2. **Scan the planning artifacts directory** for these standard BMAD files: + - PRD (`*prd*`) — product requirements and success criteria + - Architecture (`*architecture*`) — technical design decisions and constraints + - UX/Design (`*ux*`) — user experience and interaction design + - Product Brief (`*brief*`) — project vision and scope + +3. **For each planning doc found**, load it and extract only the sections relevant to this epic. Relevance means: the section describes a constraint, requirement, pattern, or decision that a developer working on any story in this epic needs to know. Skip sections that are about other epics or unrelated features. + +4. **Write the compiled context file** to the output path using the format below. + +## Output format + +```markdown +# Epic {N} Context: {Epic Title} + + + +## Goal + +{One paragraph: what this epic achieves and why it matters.} + +## Stories + +{Numbered list of stories in this epic — ID and title only. No details.} + +## Requirements & Constraints + +{Relevant product requirements, success criteria, and non-functional requirements scoped to this epic. Describe by purpose, not by source document section.} + +## Technical Decisions + +{Architecture decisions, tech stack constraints, API patterns, data models, and conventions relevant to this epic. Include ADR references where applicable.} + +## UX & Interaction Patterns + +{Relevant UX patterns, interaction flows, and design constraints. Omit this section entirely if no UX doc exists or nothing is relevant.} + +## Cross-Story Dependencies + +{Dependencies between stories within this epic, and any dependencies on other epics or external systems. Omit if none.} +``` + +## Error handling + +- If the epics file does not exist or the target epic number is not found in it, write nothing and report the problem to the calling agent. +- If no planning docs match the expected patterns, write the output file with only the Goal and Stories sections populated from the epics file. Note the absence of planning docs in the Goal section. + +## Rules + +- **Scope aggressively.** Include only what a developer working on this epic 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 paste entire planning doc sections. Distill into what matters for implementation. +- **No story-level details.** The story list is for orientation only. Individual story specs handle the details. +- **No code.** Nothing derivable from reading the codebase belongs here. +- **Keep it compact.** Target 800–1500 tokens. This file will be loaded into quick-dev's context alongside other material. diff --git a/src/bmm-skills/4-implementation/bmad-quick-dev/step-01-clarify-and-route.md b/src/bmm-skills/4-implementation/bmad-quick-dev/step-01-clarify-and-route.md index da55cb9a0..b50a80953 100644 --- a/src/bmm-skills/4-implementation/bmad-quick-dev/step-01-clarify-and-route.md +++ b/src/bmm-skills/4-implementation/bmad-quick-dev/step-01-clarify-and-route.md @@ -42,19 +42,23 @@ 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. + - **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. + + **A) Epic story path** — if the intent is an epic story: + 1. Identify the epic number and story number. + 2. Check if `{implementation_artifacts}/epic-{N}-context.md` exists (where N is the epic number). + - **If it exists**: load it. This is the compiled planning context for the epic — do not load raw planning docs (PRD, architecture, UX, etc.). + - **If it does not exist**: 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`. When the sub-agent completes, verify the output file exists and is non-empty. If the file is missing, empty, or the sub-agent errored, fall back to path B. Otherwise load the compiled file. + 3. **Previous story continuity.** 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: From 565167aafdf8ef0663065e10f35eb83933d21e6d Mon Sep 17 00:00:00 2001 From: Alex Verkhovsky Date: Tue, 7 Apr 2026 13:35:58 -0700 Subject: [PATCH 2/4] fix(quick-dev): tighten epic context loading per PR review - Validate cached epic--context.md is non-empty and starts with the expected header before loading; treat invalid cache as missing. - Replace inline {N} placeholders with 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. --- .../bmad-quick-dev/step-01-clarify-and-route.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/bmm-skills/4-implementation/bmad-quick-dev/step-01-clarify-and-route.md b/src/bmm-skills/4-implementation/bmad-quick-dev/step-01-clarify-and-route.md index b50a80953..b3ba6338e 100644 --- a/src/bmm-skills/4-implementation/bmad-quick-dev/step-01-clarify-and-route.md +++ b/src/bmm-skills/4-implementation/bmad-quick-dev/step-01-clarify-and-route.md @@ -46,9 +46,9 @@ Never ask extra questions if you already understand what the user intends. **A) Epic story path** — if the intent is an epic story: 1. Identify the epic number and story number. - 2. Check if `{implementation_artifacts}/epic-{N}-context.md` exists (where N is the epic number). - - **If it exists**: load it. This is the compiled planning context for the epic — do not load raw planning docs (PRD, architecture, UX, etc.). - - **If it does not exist**: 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`. When the sub-agent completes, verify the output file exists and is non-empty. If the file is missing, empty, or the sub-agent errored, fall back to path B. Otherwise load the compiled file. + 2. Check if `{implementation_artifacts}/epic--context.md` exists (where `` is the epic number). + - **If it exists**: verify it is non-empty and starts with a `# Epic Context` header. If valid, load it — this is the compiled planning context for the epic, do not load raw planning docs (PRD, architecture, UX, etc.). If invalid (empty, truncated, or wrong header), treat it as missing and fall through to the compilation step below. + - **If it does not exist**: 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--context.md`. When the sub-agent completes, verify the output file exists and is non-empty. If the file is missing, empty, or the sub-agent errored, fall back to loading raw planning artifacts using path B's loading procedure below (scan `{planning_artifacts}` for PRD, architecture, UX, and epics files and load selectively) — apply this fallback even though the intent is an epic story; do not re-evaluate path B's gating clause. Otherwise load the compiled file. 3. **Previous story continuity.** 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: From 7a321a56c0df1523964cd92f6df1a9f9317128e8 Mon Sep 17 00:00:00 2001 From: Alex Verkhovsky Date: Wed, 8 Apr 2026 10:02:36 -0700 Subject: [PATCH 3/4] 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 instead of {N} in the filename for consistency with step-01. --- .../bmad-quick-dev/compile-epic-context.md | 66 ++++++++----------- 1 file changed, 28 insertions(+), 38 deletions(-) diff --git a/src/bmm-skills/4-implementation/bmad-quick-dev/compile-epic-context.md b/src/bmm-skills/4-implementation/bmad-quick-dev/compile-epic-context.md index d554b96ed..5f7c665d7 100644 --- a/src/bmm-skills/4-implementation/bmad-quick-dev/compile-epic-context.md +++ b/src/bmm-skills/4-implementation/bmad-quick-dev/compile-epic-context.md @@ -1,72 +1,62 @@ # Compile Epic Context -You are a context-compilation agent. Your job is to read planning artifacts and produce a single, scoped context document for one epic. +**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--context.md`). -## Inputs +**Steps** -You will receive: +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. -- **Epic number** — which epic to compile context for -- **Epics file path** — the file containing epic and story definitions -- **Planning artifacts directory** — where PRD, architecture, UX, and other planning docs live -- **Output path** — where to write the compiled context file +## Exact Output Format -## Instructions - -1. **Load the epics file** and extract the definition for the target epic: its title, goal, and story list. - -2. **Scan the planning artifacts directory** for these standard BMAD files: - - PRD (`*prd*`) — product requirements and success criteria - - Architecture (`*architecture*`) — technical design decisions and constraints - - UX/Design (`*ux*`) — user experience and interaction design - - Product Brief (`*brief*`) — project vision and scope - -3. **For each planning doc found**, load it and extract only the sections relevant to this epic. Relevance means: the section describes a constraint, requirement, pattern, or decision that a developer working on any story in this epic needs to know. Skip sections that are about other epics or unrelated features. - -4. **Write the compiled context file** to the output path using the format below. - -## Output format +Use these headings verbatim: ```markdown # Epic {N} Context: {Epic Title} - + ## Goal -{One paragraph: what this epic achieves and why it matters.} +{One clear paragraph: what this epic achieves and why it matters.} ## Stories -{Numbered list of stories in this epic — ID and title only. No details.} +- Story X.Y: Brief title only +- ... ## Requirements & Constraints -{Relevant product requirements, success criteria, and non-functional requirements scoped to this epic. Describe by purpose, not by source document section.} +{Relevant functional/non-functional requirements and success criteria for this epic (describe by purpose, not source).} ## Technical Decisions -{Architecture decisions, tech stack constraints, API patterns, data models, and conventions relevant to this epic. Include ADR references where applicable.} +{Key architecture decisions, constraints, patterns, data models, and conventions relevant to this epic.} ## UX & Interaction Patterns -{Relevant UX patterns, interaction flows, and design constraints. Omit this section entirely if no UX doc exists or nothing is relevant.} +{Relevant UX flows, interaction patterns, and design constraints (omit section entirely if nothing relevant).} ## Cross-Story Dependencies -{Dependencies between stories within this epic, and any dependencies on other epics or external systems. Omit if none.} +{Dependencies between stories in this epic or with other epics/systems (omit if none).} ``` -## Error handling - -- If the epics file does not exist or the target epic number is not found in it, write nothing and report the problem to the calling agent. -- If no planning docs match the expected patterns, write the output file with only the Goal and Stories sections populated from the epics file. Note the absence of planning docs in the Goal section. - ## Rules -- **Scope aggressively.** Include only what a developer working on this epic needs. When in doubt, leave it out — the developer can always read the full planning doc. +- **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 paste entire planning doc sections. Distill into what matters for implementation. +- **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. -- **No code.** Nothing derivable from reading the codebase belongs here. -- **Keep it compact.** Target 800–1500 tokens. This file will be loaded into quick-dev's context alongside other material. +- **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. From 0452ba53cfd587a639faa50c507af91f3c8c4c70 Mon Sep 17 00:00:00 2001 From: Alex Verkhovsky Date: Wed, 8 Apr 2026 10:30:42 -0700 Subject: [PATCH 4/4] 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 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). --- .../step-01-clarify-and-route.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/src/bmm-skills/4-implementation/bmad-quick-dev/step-01-clarify-and-route.md b/src/bmm-skills/4-implementation/bmad-quick-dev/step-01-clarify-and-route.md index b3ba6338e..a0c5029be 100644 --- a/src/bmm-skills/4-implementation/bmad-quick-dev/step-01-clarify-and-route.md +++ b/src/bmm-skills/4-implementation/bmad-quick-dev/step-01-clarify-and-route.md @@ -45,11 +45,20 @@ Never ask extra questions if you already understand what the user intends. - **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. **A) Epic story path** — if the intent is an epic story: - 1. Identify the epic number and story number. - 2. Check if `{implementation_artifacts}/epic--context.md` exists (where `` is the epic number). - - **If it exists**: verify it is non-empty and starts with a `# Epic Context` header. If valid, load it — this is the compiled planning context for the epic, do not load raw planning docs (PRD, architecture, UX, etc.). If invalid (empty, truncated, or wrong header), treat it as missing and fall through to the compilation step below. - - **If it does not exist**: 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--context.md`. When the sub-agent completes, verify the output file exists and is non-empty. If the file is missing, empty, or the sub-agent errored, fall back to loading raw planning artifacts using path B's loading procedure below (scan `{planning_artifacts}` for PRD, architecture, UX, and epics files and load selectively) — apply this fallback even though the intent is an epic story; do not re-evaluate path B's gating clause. Otherwise load the compiled file. - 3. **Previous story continuity.** 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. + + 1. Identify the epic number and (if present) the story number. + + 2. **Check for a valid cached epic context.** Look for `{implementation_artifacts}/epic--context.md` (where `` is the epic number). A file is **valid** when it exists, is non-empty, and starts with `# Epic Context:` (with the correct epic number). + - **If valid:** load it as the primary planning context. Do not load raw planning docs (PRD, architecture, UX, etc.). Skip to step 5. + - **If missing, empty, or invalid:** continue to step 3. + + 3. **Compile epic context.** Produce `{implementation_artifacts}/epic--context.md` by following `./compile-epic-context.md`, in order of preference: + - **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--context.md`. + - **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 or fall back to path B.** After compilation, verify the output file exists, is non-empty, and starts with `# Epic Context:`. If valid, load it. If verification fails, fall back to path B's raw planning artifacts loading procedure below (scan `{planning_artifacts}` for PRD, architecture, UX, and epics files and load selectively) — apply this fallback even though the intent is an epic story; do not re-evaluate path B's gating clause. + + 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: