Describe your idea
I would like to propose a new step-based workflow designed to execute at the end of an Epic—similar to the existing Epic Retrospective workflow—but focused strictly on code health, structural cohesion, and refactoring.
While BMAD excels at implementing stories in isolated, context-engineered steps, the incremental nature of building a feature story-by-story can naturally result in scattered logic, slight redundancies, and overly complex routes. This workflow would direct the Architect and Developer agents to review the entirety of the Epic's codebase changes, identify fragmentation, and perform a dedicated refactoring pass to simplify the code, clarify business flows, and improve long-term maintainability.
Why is this needed?
BMAD's agentic workflow is powerful because it isolates context for the Developer agent, ensuring focus on the immediate story. However, after 5 to 10 stories are merged incrementally, projects inevitably accumulate "incremental tech debt." For example, multiple stories might add overlapping helper functions, or a single route loader might become cluttered with sequential patches that could easily be unified into a single clean flow.
Without an Epic-level consolidation phase, this complexity compounds over multiple Epics. An automated end-of-epic refactoring workflow bridges the gap between "all stories pass tests" and "the codebase is elegant and production-ready." It ensures the project remains scalable and reduces the friction of context limits for future BMAD development cycles.
How should it work?
I propose a new step-based workflow (e.g., bmad-epic-consolidation or epic-refactor) that runs after the final story of an Epic is completed, either right before or as an actionable extension of the epic-retrospective.
- Epic Context Analysis: The Architect agent ingests the Epic's final state, comparing the original PRD/Architecture against the implemented codebase to understand the overarching business flows.
- Identification of Clutter: The Architect identifies duplicate logic, bloated route handlers, and fragmented state management introduced during the incremental story implementation.
- Refactoring Plan & HIL Check: A structured refactoring plan is generated and presented to the human user for approval (Human-in-the-loop checkpoint).
- Execution & Review: The Developer agent implements the cleanup tasks, followed by the standard QA / Code Review workflows (e.g., bmad-bmm-code-review) to ensure no existing tests or business logic were broken during simplification.
Describe your idea
I would like to propose a new step-based workflow designed to execute at the end of an Epic—similar to the existing Epic Retrospective workflow—but focused strictly on code health, structural cohesion, and refactoring.
While BMAD excels at implementing stories in isolated, context-engineered steps, the incremental nature of building a feature story-by-story can naturally result in scattered logic, slight redundancies, and overly complex routes. This workflow would direct the Architect and Developer agents to review the entirety of the Epic's codebase changes, identify fragmentation, and perform a dedicated refactoring pass to simplify the code, clarify business flows, and improve long-term maintainability.
Why is this needed?
BMAD's agentic workflow is powerful because it isolates context for the Developer agent, ensuring focus on the immediate story. However, after 5 to 10 stories are merged incrementally, projects inevitably accumulate "incremental tech debt." For example, multiple stories might add overlapping helper functions, or a single route loader might become cluttered with sequential patches that could easily be unified into a single clean flow.
Without an Epic-level consolidation phase, this complexity compounds over multiple Epics. An automated end-of-epic refactoring workflow bridges the gap between "all stories pass tests" and "the codebase is elegant and production-ready." It ensures the project remains scalable and reduces the friction of context limits for future BMAD development cycles.
How should it work?
I propose a new step-based workflow (e.g.,
bmad-epic-consolidationorepic-refactor) that runs after the final story of an Epic is completed, either right before or as an actionable extension of theepic-retrospective.