refactor: comprehensive workflow modernization and standardization

## Major Improvements

### 1. Elicitation System Modernization
- Removed legacy `<elicit-required />` tag from workflow.xml
- Replaced with direct `<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>` pattern
- More explicit, self-documenting, and eliminates indirection layer
- Added strategic elicitation points across all planning workflows:
  - PRD: After success criteria, scope, functional requirements, and final review
  - Create-Epics-And-Stories: After epic proposals and each epic's stories
  - Architecture: After decisions, structure, patterns, implementation patterns, and final doc
  - Updated audit-workflow tag scanner to remove obsolete elicit-required reference

### 2. Input Document Discovery Streamlined
- Replaced verbose 19-line "Input Document Discovery" sections with single critical tag
- New format: `<critical>Input documents specified in workflow.yaml input_file_patterns...</critical>`
- Eliminates duplication - workflow.yaml already defines patterns
- Updated across 6 workflows (PRD, create-epics-and-stories, architecture, tech-spec, UX, gate-check)
- Saved ~114 lines of repeated bloat

### 3. Scale System Migration (Levels 0-4 → 3 Tracks)
- Updated PRD workflow from "Level 0-4" to "Quick Flow / BMad Method / Enterprise Method"
- Changed `project_level` variable to `project_track`
- Removed `target_scale` variable (no longer needed)
- Updated workflow.yaml descriptions to reference tracks not levels
- Updated checklist from "Level 2" and "Level 3-4" to "BMad Method" and "Enterprise Method"
- Aligns with new scale-adaptive-system.md (3-track methodology)

### 4. Epic/Story Template Standardization
- Replaced hardcoded 8-epic template with clean repeating pattern using N/M variables
- Added BDD-style acceptance criteria (Given/When/Then/And)
- Removed instructional bloat from templates (moved to instructions.md where it belongs)
- Template shows OUTPUT structure, instructions show PROCESS
- Applied to both create-epics-and-stories and tech-spec workflows
- Templates now use HTML comments to indicate repeating sections

### 5. Workflow.yaml Pattern Consistency
- Standardized input_file_patterns across all workflows
- Separated `recommended_inputs` (semantic WHAT) from `input_file_patterns` (file discovery WHERE)
- Removed duplication between recommended_inputs file paths and input_file_patterns
- Create-epics-and-stories now uses proper whole/sharded pattern like architecture workflow
- Solutioning-gate-check cleaned up to use semantic descriptions not file paths

## Files Changed (18)
- Core: workflow.xml (removed elicit-required tag and references)
- Audit workflow: Updated tag pattern scanner
- PRD workflow: Elicitation points, track migration, input discovery
- Create-epics-and-stories: Template rebuild, BDD format, elicitation, input patterns
- Tech-spec: Template rebuild, BDD format, input discovery
- UX Design: Input discovery streamlined
- Architecture: Elicitation at 5 key decision points, input discovery
- Gate-check: Input pattern cleanup, input discovery

## Impact
- More consistent elicitation across workflows
- Cleaner, more maintainable templates
- Better separation of concerns (templates vs instructions)
- Aligned with v6 3-track scale system
- Reduced bloat and duplication significantly
This commit is contained in:
Brian Madison
2025-11-04 00:09:19 -06:00
parent c5117e5382
commit accae5d789
18 changed files with 292 additions and 590 deletions

View File

@@ -9,24 +9,8 @@
<critical>Communicate all responses in {communication_language} and tailor to {user_skill_level}</critical>
<critical>Generate all documents in {document_output_language}</critical>
<critical>This workflow replaces architecture with a conversation-driven approach</critical>
## 📚 Input Document Discovery
This workflow requires: PRD and epics/stories, and may reference UX design specifications or brownfield project documentation.
**Discovery Process** (execute for each referenced document):
1. **Search for whole document first** - Use fuzzy file matching to find the complete document
2. **Check for sharded version** - If whole document not found, look for `{doc-name}/index.md`
3. **If sharded version found**:
- Read `index.md` to understand the document structure
- Read ALL section files listed in the index
- Treat the combined content as if it were a single document
4. **Brownfield projects**: The `document-project` workflow always creates `{output_folder}/docs/index.md`
**Priority**: If both whole and sharded versions exist, use the whole document.
**Fuzzy matching**: Be flexible with document names - users may use variations in naming conventions.
<critical>Input documents specified in workflow.yaml input_file_patterns - workflow engine handles fuzzy matching, whole vs sharded document discovery automatically</critical>
<critical>ELICITATION POINTS: After completing each major architectural decision area (identified by template-output tags for decision_record, project_structure, novel_pattern_designs, implementation_patterns, and architecture_document), invoke advanced elicitation to refine decisions before proceeding</critical>
<step n="0" goal="Validate workflow readiness" tag="workflow-status">
<action>Check if {output_folder}/bmm-workflow-status.yaml exists</action>
@@ -379,6 +363,7 @@ Provided by Starter: {{yes_if_from_starter}}
</action>
<template-output>decision_record</template-output>
<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
</step>
<step n="5" goal="Address cross-cutting concerns">
@@ -408,6 +393,7 @@ Provided by Starter: {{yes_if_from_starter}}
</action>
<template-output>project_structure</template-output>
<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
</step>
<step n="7" goal="Design novel architectural patterns" optional="true">
@@ -481,6 +467,7 @@ Provided by Starter: {{yes_if_from_starter}}
</check>
<template-output>novel_pattern_designs</template-output>
<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
</step>
<step n="8" goal="Define implementation patterns to prevent agent conflicts">
@@ -573,6 +560,7 @@ Enforcement: "All agents MUST follow this pattern"
</action>
<template-output>implementation_patterns</template-output>
<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
</step>
<step n="9" goal="Validate architectural coherence">
@@ -626,6 +614,7 @@ Enforcement: "All agents MUST follow this pattern"
</action>
<template-output>architecture_document</template-output>
<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
</step>
<step n="11" goal="Validate document completeness">

View File

@@ -3,24 +3,7 @@
<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
<critical>You MUST have already loaded and processed: {project-root}/bmad/bmm/workflows/3-solutioning/solutioning-gate-check/workflow.yaml</critical>
<critical>Communicate all findings and analysis in {communication_language} throughout the assessment</critical>
## 📚 Input Document Discovery
This workflow validates: PRD, epics/stories, architecture, and may reference UX design, tech specs, or brownfield project documentation.
**Discovery Process** (execute for each referenced document):
1. **Search for whole document first** - Use fuzzy file matching to find the complete document
2. **Check for sharded version** - If whole document not found, look for `{doc-name}/index.md`
3. **If sharded version found**:
- Read `index.md` to understand the document structure
- Read ALL section files listed in the index
- Treat the combined content as if it were a single document
4. **Brownfield projects**: The `document-project` workflow always creates `{output_folder}/docs/index.md`
**Priority**: If both whole and sharded versions exist, use the whole document.
**Fuzzy matching**: Be flexible with document names - users may use variations in naming conventions.
<critical>Input documents specified in workflow.yaml input_file_patterns - workflow engine handles fuzzy matching, whole vs sharded document discovery automatically</critical>
<workflow>

View File

@@ -24,13 +24,13 @@ validation: "{installed_path}/checklist.md"
# Output configuration
default_output_file: "{output_folder}/implementation-readiness-report-{{date}}.md"
# Expected input documents (varies by project level)
# Input requirements
recommended_inputs:
- prd: "{output_folder}/prd*.md"
- architecture: "{output_folder}/architecture*.md or {output_folder}/architecture*.md"
- tech_spec: "{output_folder}/tech-spec*.md"
- epics_stories: "{output_folder}/epic*.md"
- ux_artifacts: "{output_folder}/ux*.md"
- prd: "Product Requirements Document with FRs and NFRs"
- architecture: "System Architecture with decisions and patterns"
- tech_spec: "Technical Specification (for Quick Flow track)"
- epics: "Epic breakdown with user stories"
- ux_design: "UX design specification (if UI components)"
# Smart input file references - handles both whole docs and sharded docs
# Priority: Whole document first, then sharded version