feat: Add documentation guides, simplify folder structure, and major workflow refactoring

Created two comprehensive guides for v6 features:

**docs/agent-customization-guide.md**
- Complete guide for customizing agent names, personas, memories, and behaviors
- Update-safe customization via bmad/_cfg/agents/ configuration files
- Real-world examples (TDD setup, multilingual agents, custom workflows)
- Troubleshooting and best practices

**docs/web-bundles-gemini-gpt-guide.md**
- Comprehensive guide for using BMad agents in Gemini Gems and Custom GPTs
- Critical setup rules with exact configuration text required
- Cost-saving strategy: web planning → local implementation (60-80% savings)
- Platform comparison (Gemini Gems strongly recommended over Custom GPTs)
- Complete workflow examples showing full planning-to-implementation cycle
- Team bundle guidance (Gemini 2.5 Pro+ only)

**README.md updates**
- Added prominent links in v6 Core Enhancements section
- Created new "Customization & Sharing" documentation category
- Web Bundles feature highlighted with direct guide link

**Unified output folder structure across all modules:**

**Before (confusing):**
- output_folder: Main docs
- game_design_docs: Separate design folder
- tech_docs: Separate technical folder
- dev_ephemeral_location: Separate ephemeral folder outside docs

**After (simplified):**
- output_folder: Single location for ALL AI-generated artifacts (default: "docs")
  - Clearer prompt: "Where should AI Generated Artifacts be saved?"
- sprint_artifacts: Phase 4 ephemeral content now WITHIN output_folder
  - BMM: {output_folder}/stories (stories, context, reports)
  - BMGD: {output_folder}/sprint-artifacts
  - No longer in separate {bmad_folder}-ephemeral location

**Benefits:**
- One clear location for all planning artifacts (PRD, Architecture, UX, etc.)
- Phase 4 ephemeral items logically grouped within output folder
- Eliminated confusing separate folder proliferation
- sprint_artifacts now configurable per module

**Files changed:**
- src/core/_module-installer/install-config.yaml
- src/modules/bmm/_module-installer/install-config.yaml
- src/modules/bmgd/_module-installer/install-config.yaml

**Also cleaned up BMGD config:**
- Renamed: specified_framework → primary_platform (clearer naming)
- Removed: unused data_path variable

Replaced old "project_level" (0-4) system with new "selected_track" terminology:
- **quick-flow**: Bug fixes and small features (replaces Level 0-1)
- **bmad-method**: Full planning track (replaces Level 2-3)
- **enterprise-bmad-method**: Extended planning (replaces Level 4)

**Core workflow updates:**
- solutioning-gate-check: Complete rewrite of validation logic for track-based artifacts
- architecture: Updated context detection, error handling, and messaging for tracks
- workflow-init: Updated artifact detection patterns for track-based paths
- All workflow status paths updated (method-greenfield, method-brownfield, enterprise-*)

Unified variable naming conventions across all workflows:
- {output_folder} → {output-folder} (hyphenated format)
- {dev_ephemeral_location} → {sprint_artifacts} (clearer purpose)
- Hardcoded status file paths → {workflow_status_file} variable

Fixed corrupted variable patterns throughout workflow files:
- {output*folder} → {output-folder}
- {ephemeral*location} → {sprint_artifacts}
- \_prd* → *prd* (escaped underscore artifacts)
- **\*\***\_\_\_**\*\*** → proper field placeholders

Affected patterns included malformed glob patterns, template variables, and markdown formatting artifacts from previous edits.

**Architecture workflow (create-architecture):**
- Fixed: "Decision Architecture" → "Create Architecture" (consistent naming)
- Improved PRD not found handling with exit/continue options
- Better user guidance when running standalone vs. within workflow path
- Removed hardcoded Level checks, now track-aware
- Enhanced validation checklist formatting (□ → - [])
- Typo fixes: "mulitple" → "multiple"

**Solutioning gate check:**
- Complete validation logic rewrite for track-based system
- Removed Level-specific artifact expectations
- Simplified document discovery (track determines what exists)
- Better analysis prompts and user feedback

**Workflow-init:**
- Updated artifact detection patterns for new folder structure
- Fixed corrupt glob patterns throughout
- Better sprint_artifacts location detection
- Improved workflow path assignment logic

**Various workflows:**
- Consistent variable naming across 40+ workflow files
- Improved error messages and user guidance
- Better markdown formatting (checkboxes, lists)
- Removed redundant validation criteria files (now inline)

Removed duplicate BMGD 4-production workflows (12 workflows):
- code-review, correct-course, create-story, dev-story
- epic-tech-context, retrospective, sprint-planning
- story-context, story-done, story-ready

**Why:** BMGD now uses shared BMM Phase 4 implementation workflows
**Benefit:** Single source of truth, no duplication to maintain

Also removed:
- validation-criteria.yaml (validation now inline in instructions)
- architecture-patterns.yaml references (patterns now managed differently)
- AUDIT-REPORT.md files (stale audit artifacts)

**BMB workflows:**
- Updated checklists for workflow and module creation
- Improved agent architecture documentation
- Minor instruction clarifications

**Core brainstorming workflow:**
- Updated README with usage examples
- Enhanced instructions and template clarity
- Better integration with other modules

**BMM installer:**
- Updated for track-based system
- sprint_artifacts configuration

**Tech Writer agent:**
- Minor configuration update for documentation workflows

Removed 200+ files that should not be in repository:
- Installed agent markdown files (analyst, architect, dev, pm, sm, tea, etc.)
- Complete workflow instruction copies
- Documentation duplicates (quick-start, agents-guide, workflows-*)
- Test architecture knowledge base (22 files, 14,000+ lines)
- Configuration files (config.yaml, team definitions)

These are generated during installation and should not be version controlled.

Removed 21 pre-generated XML bundles:
- BMM agents (analyst, architect, dev, pm, sm, tea, tech-writer, ux-designer)
- BMGD agents (game-architect, game-designer, game-dev, game-scrum-master)
- CIS agents (brainstorming-coach, creative-problem-solver, etc.)
- Team bundles (team-fullstack, team-gamedev, creative-squad)

**Why:** Users should generate fresh bundles via `npm run bundle` to get latest changes and customizations.

- **2 new documentation files** (comprehensive guides)
- **98 source files modified** (299 insertions, 6,567 deletions)
- **3 installer config files simplified** (major folder structure improvement)
- **200+ .bmad/ artifacts removed** (should not be in repo)
- **21 web-bundle files removed** (users regenerate as needed)
- **12 duplicate workflows removed** (BMGD consolidation)
- **40+ workflows updated** (track system, variable standardization, corruption fixes)

src/modules/bmm/workflows/4-implementation/code-review/workflow.yaml

@@ -11,29 +11,24 @@ communication_language: "{config_source}:communication_language"
 user_skill_level: "{config_source}:user_skill_level"
 document_output_language: "{config_source}:document_output_language"
 date: system-generated
-ephemeral_files: "{config_source}:dev_ephemeral_location"
-sprint_status: "{context_dir}/sprint-status.yaml || {output_folder}/sprint-status.yaml"
+sprint_artifacts: "{config_source}:sprint_artifacts"
+sprint_status: "{sprint_artifacts}/sprint-status.yaml || {output_folder}/sprint-status.yaml"
 
 # Workflow components
 installed_path: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/code-review"
 instructions: "{installed_path}/instructions.md"
 validation: "{installed_path}/checklist.md"
-
-# This is an action workflow (no output template document)
 template: false
 
-# Variables (can be provided by caller)
 variables:
-  story_path: "{ephemeral_files}/stories" # Optional: Explicit path to story file. If not provided, finds first story with status "review"
-  story_dir: "{ephemeral_files}/stories" # Directory containing story files
-  tech_spec_search_dir: "{project-root}/docs"
+  story_dir: "{sprint_artifacts}"
+  tech_spec_search_dir: "{output_folder}"
   tech_spec_glob_template: "tech-spec-epic-{{epic_num}}*.md"
   arch_docs_search_dirs: |
-    - "{project-root}/docs"
     - "{output_folder}"
   arch_docs_file_names: |
     - architecture.md
-  backlog_file: "{project-root}/docs/backlog.md"
+  backlog_file: "{output_folder}/backlog.md"
   update_epic_followups: true
   epic_followups_section_title: "Post-Review Follow-ups"
 
@@ -55,5 +50,4 @@ input_file_patterns:
     sharded: "{output_folder}/docs/index.md"
 
 standalone: true
-
 web_bundle: false

src/modules/bmm/workflows/4-implementation/correct-course/workflow.yaml

@@ -18,28 +18,6 @@ validation: "{installed_path}/checklist.md"
 checklist: "{installed_path}/checklist.md"
 default_output_file: "{output_folder}/sprint-change-proposal-{date}.md"
 
-# Workflow execution mode (interactive: step-by-step with user, non-interactive: automated)
-mode: interactive
-
-required_inputs:
-  - change_trigger: "Description of the issue or change that triggered this workflow"
-  - project_documents: "Access to PRD, Epics/Stories, Architecture, UI/UX specs"
-
-output_artifacts:
-  - sprint_change_proposal: "Comprehensive proposal documenting issue, impact, and recommended changes"
-  - artifact_edits: "Specific before/after edits for affected documents"
-  - handoff_plan: "Clear routing for implementation based on change scope"
-
-halt_conditions:
-  - "Change trigger unclear or undefined"
-  - "Core project documents unavailable"
-  - "Impact analysis incomplete"
-  - "User approval not obtained"
-
-execution_modes:
-  - incremental: "Recommended - Refine each edit with user collaboration"
-  - batch: "Present all changes at once for review"
-
 standalone: true
 
 web_bundle: false

src/modules/bmm/workflows/4-implementation/create-story/instructions.md

@@ -10,43 +10,14 @@
 <workflow>
 
   <step n="1" goal="Load config and initialize">
-    <action>Resolve variables from config_source: story_dir (dev_ephemeral_location), output_folder, user_name, communication_language. If story_dir missing → ASK user to provide a stories directory and update variable.</action>
+    <action>Resolve variables from config_source: story_dir (sprint_artifacts), output_folder, user_name, communication_language. If story_dir missing → ASK user to provide a stories directory and update variable.</action>
     <action>Create {{story_dir}} if it does not exist</action>
     <action>Resolve installed component paths from workflow.yaml: template, instructions, validation</action>
     <action>Resolve recommended inputs if present: epics_file, prd_file, architecture_file</action>
+    <action>Load architecture/standards docs: For each file name in {{arch_docs_file_names}} within {{arch_docs_search_dirs}}, read if exists. Collect testing, coding standards, security, and architectural patterns.</action>
   </step>
 
   <step n="2" goal="Discover and load source documents">
-    <action>
-      Selective Epic Loading
-
-      **Strategy**: This workflow needs only ONE specific epic and its stories, not all epics. This provides huge efficiency gains when epics are sharded.
-
-      **Epic Discovery Process (SELECTIVE OPTIMIZATION):**
-
-      1. **Determine which epic** you need (epic_num from story context - e.g., story "3-2-feature-name" needs Epic 3)
-      2. **Check for sharded version**: Look for `epics/*n*.md` where n is the epic number such as epics/epic-3-foo.md
-      3. **If sharded version found**:
-        - Read `index.md` to understand structure
-        - **Load ONLY `epic-{epic_num}.md`** (e.g., `epics/epic-3.md` for Epic 3)
-        - DO NOT load all epic files - only the one needed!
-        - This is the key efficiency optimization for large multi-epic projects
-      4. **If whole document found**: Load the complete `epics.md` file and extract the relevant epic
-
-      **Other Documents (prd, architecture, ux-design) - Full Load:**
-
-      1. **Search for whole document first** - Use fuzzy file matching
-      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 structure
-        - Read ALL section files listed in the index
-        - Treat combined content as single document
-      4. **Brownfield projects**: The `document-project` workflow creates `{output_folder}/docs/index.md`
-
-      **Priority**: If both whole and sharded versions exist, use the whole document.
-
-      **UX-Heavy Projects**: Always check for ux-design documentation as it provides critical context for UI-focused stories.
-    </action>
     <critical>PREVIOUS STORY CONTINUITY: Essential for maintaining context and learning from prior development</critical>
 
     <action>Find the previous completed story to extract dev agent learnings and review findings:
@@ -139,12 +110,12 @@
     <check if="no backlog story found">
       <output>📋 No backlog stories found in sprint-status.yaml
 
-All stories are either already drafted or completed.
+        All stories are either already drafted or completed.
 
-**Options:**
-1. Run sprint-planning to refresh story tracking
-2. Load PM agent and run correct-course to add more stories
-3. Check if current sprint is complete
+        **Options:**
+        1. Run sprint-planning to refresh story tracking
+        2. Load PM agent and run correct-course to add more stories
+        3. Check if current sprint is complete
       </output>
       <action>HALT</action>
     </check>

src/modules/bmm/workflows/4-implementation/create-story/workflow.yaml

@@ -8,7 +8,7 @@ output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
 date: system-generated
-story_dir: "{config_source}:dev_ephemeral_location/stories"
+story_dir: "{config_source}:sprint_artifacts"
 
 # Workflow components
 installed_path: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/create-story"
@@ -18,7 +18,7 @@ validation: "{installed_path}/checklist.md"
 
 # Variables and inputs
 variables:
-  sprint_status: "{config_source}:dev_ephemeral_location/sprint-status.yaml || {output_folder}/sprint-status.yaml" # Primary source for story tracking
+  sprint_status: "{config_source}:sprint_artifacts/sprint-status.yaml || {output_folder}/sprint-status.yaml" # Primary source for story tracking
   epics_file: "{output_folder}/epics.md" # Preferred source for epic/story breakdown
   prd_file: "{output_folder}/PRD.md" # Fallback for requirements
   architecture_file: "{output_folder}/architecture.md" # Optional architecture context
@@ -32,8 +32,6 @@ variables:
     - *architecture*.md
   story_title: "" # Will be elicited if not derivable
 
-# Output configuration
-# Uses story_key from sprint-status.yaml (e.g., "1-2-user-authentication")
 default_output_file: "{story_dir}/{{story_key}}.md"
 
 # Smart input file references - handles both whole docs and sharded docs

src/modules/bmm/workflows/4-implementation/dev-story/AUDIT-REPORT.md

@@ -1,367 +0,0 @@
-# Workflow Audit Report
-
-**Workflow:** dev-story
-**Audit Date:** 2025-10-25
-**Auditor:** Audit Workflow (BMAD v6)
-**Workflow Type:** Action Workflow
-**Module:** BMM (BMad Method)
-
----
-
-## Executive Summary
-
-**Overall Status:** GOOD - Minor issues to address
-
-- Critical Issues: 0
-- Important Issues: 3
-- Cleanup Recommendations: 2
-
-The dev-story workflow is well-structured and follows most BMAD v6 standards. The workflow correctly sets `web_bundle: false` as expected for implementation workflows. However, there are several config variable usage issues and some variables referenced in instructions that are not defined in the YAML.
-
----
-
-## 1. Standard Config Block Validation
-
-**Status:** PASS ✓
-
-The workflow.yaml contains all required standard config variables:
-
-- ✓ `config_source: "{project-root}/{bmad_folder}/bmm/config.yaml"` - Correctly defined
-- ✓ `output_folder: "{config_source}:output_folder"` - Pulls from config_source
-- ✓ `user_name: "{config_source}:user_name"` - Pulls from config_source
-- ✓ `communication_language: "{config_source}:communication_language"` - Pulls from config_source
-- ✓ `date: system-generated` - Correctly set
-
-All standard config variables are present and properly formatted using {project-root} variable syntax.
-
----
-
-## 2. YAML/Instruction/Template Alignment
-
-**Variables Analyzed:** 9 (excluding standard config)
-**Used in Instructions:** 6
-**Unused (Bloat):** 3
-
-### YAML Variables Defined
-
-1. `story_dir` - USED in instructions (file paths)
-2. `context_path` - UNUSED (appears to duplicate story_dir)
-3. `story_file` - USED in instructions
-4. `context_file` - USED in instructions
-5. `installed_path` - USED in instructions (workflow.xml reference)
-6. `instructions` - USED in instructions (self-reference in critical tag)
-7. `validation` - USED in instructions (checklist reference)
-8. `web_bundle` - CONFIGURATION (correctly set to false)
-9. `date` - USED in instructions (config variable)
-
-### Variables Used in Instructions But NOT Defined in YAML
-
-**IMPORTANT ISSUE:** The following variables are referenced in instructions.md but are NOT defined in workflow.yaml:
-
-1. `{user_skill_level}` - Used 4 times (lines 6, 13, 173, 182)
-2. `{document_output_language}` - Used 1 time (line 7)
-3. `{run_until_complete}` - Used 1 time (line 108)
-4. `{run_tests_command}` - Used 1 time (line 120)
-
-These variables appear to be pulling from config.yaml but are not explicitly defined in the workflow.yaml file. While the config_source mechanism may provide these, workflow.yaml should document all variables used in the workflow for clarity.
-
-### Unused Variables (Bloat)
-
-1. **context_path** - Defined as `"{config_source}:dev_ephemeral_location"` but never used. This duplicates `story_dir` functionality.
-
----
-
-## 3. Config Variable Usage
-
-**Communication Language:** PASS ✓
-**User Name:** PASS ✓
-**Output Folder:** PASS ✓
-**Date:** PASS ✓
-
-### Detailed Analysis
-
-**Communication Language:**
-
-- ✓ Used in line 6: "Communicate all responses in {communication_language}"
-- ✓ Properly used as agent instruction variable (not in template)
-
-**User Name:**
-
-- ✓ Used in line 169: "Communicate to {user_name} that story implementation is complete"
-- ✓ Appropriately used for personalization
-
-**Output Folder:**
-
-- ✓ Used multiple times for sprint-status.yaml file paths
-- ✓ All file operations target {output_folder} correctly
-- ✓ No hardcoded paths detected
-
-**Date:**
-
-- ✓ Available for agent use (system-generated)
-- ✓ Used appropriately in context of workflow execution
-
-### Additional Config Variables
-
-**IMPORTANT ISSUE:** The workflow uses additional variables that appear to come from config but are not explicitly documented:
-
-1. `{user_skill_level}` - Used to tailor communication style
-2. `{document_output_language}` - Used for document generation
-3. `{run_until_complete}` - Used for execution control
-4. `{run_tests_command}` - Used for test execution
-
-These should either be:
-
-- Added to workflow.yaml with proper config_source references, OR
-- Documented as optional config variables with defaults
-
----
-
-## 4. Web Bundle Validation
-
-**Web Bundle Present:** No (Intentional)
-**Status:** EXPECTED ✓
-
-The workflow correctly sets `web_bundle: false`. This is the expected configuration for implementation workflows that:
-
-- Run locally in the development environment
-- Don't need to be bundled for web deployment
-- Are IDE-integrated workflows
-
-**No issues found** - This is the correct configuration for dev-story.
-
----
-
-## 5. Bloat Detection
-
-**Bloat Percentage:** 11% (1 unused field / 9 total fields)
-**Cleanup Potential:** Low
-
-### Unused YAML Fields
-
-1. **context_path** (line 11 in workflow.yaml)
-   - Defined as: `"{config_source}:dev_ephemeral_location"`
-   - Never referenced in instructions.md
-   - Duplicates functionality of `story_dir` variable
-   - **Recommendation:** Remove this variable as `story_dir` serves the same purpose
-
-### Hardcoded Values
-
-No significant hardcoded values that should be variables were detected. The workflow properly uses variables for:
-
-- File paths ({output_folder}, {story_dir})
-- User personalization ({user_name})
-- Communication style ({communication_language}, {user_skill_level})
-
-### Calculation
-
-- Total yaml fields: 9 (excluding standard config and metadata)
-- Used fields: 8
-- Unused fields: 1 (context_path)
-- Bloat percentage: 11%
-
-**Status:** Acceptable (under 15% threshold)
-
----
-
-## 6. Template Variable Mapping
-
-**Not Applicable** - This is an action workflow, not a document workflow.
-
-No template.md file exists, which is correct for action-type workflows.
-
----
-
-## 7. Instructions Quality Analysis
-
-### Structure
-
-- ✓ Steps numbered sequentially (1, 1.5, 2-7)
-- ✓ Each step has clear goal attributes
-- ✓ Proper use of XML tags (<action>, <check>, <goto>, <anchor>, <output>)
-- ✓ Logical flow control with anchors and conditional checks
-- ✓ Repeat patterns used appropriately (step 2-5 loop)
-
-### Critical Tags
-
-- ✓ Critical blocks present and well-defined
-- ✓ Clear references to workflow execution engine
-- ✓ Workflow.yaml load requirement specified
-- ✓ Communication preferences documented
-
-### Variable Usage Consistency
-
-**ISSUE:** Inconsistent variable syntax found:
-
-1. Lines 4, 5 use `{project_root}` (underscore)
-2. Line 166 uses `{project-root}` (hyphen)
-
-**Recommendation:** Standardize to `{project-root}` throughout (hyphen is the standard in BMAD v6)
-
-### Step Quality
-
-**Excellent:**
-
-- Steps are focused and single-purpose
-- Clear HALT conditions defined
-- Comprehensive validation checks
-- Good error handling patterns
-- Iterative execution model well-structured
-
-**Areas for improvement:**
-
-- Step 1 is complex and could potentially be split
-- Some <action if="..."> conditionals could be clearer with <check> blocks
-
----
-
-## Recommendations
-
-### Critical (Fix Immediately)
-
-None - No critical issues detected.
-
-### Important (Address Soon)
-
-1. **Document or Define Missing Variables**
-   - Add explicit definitions in workflow.yaml for: `user_skill_level`, `document_output_language`, `run_until_complete`, `run_tests_command`
-   - OR document these as optional config variables with defaults
-   - These variables are used in instructions but not defined in YAML
-   - **Impact:** Reduces clarity and may cause confusion about variable sources
-
-2. **Standardize project-root Variable Syntax**
-   - Change line 4 `{project_root}` to `{project-root}` (hyphen)
-   - Ensure consistency with BMAD v6 standard naming convention
-   - **Impact:** Maintains consistency with framework standards
-
-3. **Remove or Use context_path Variable**
-   - Variable `context_path` is defined but never used
-   - Since `story_dir` serves the same purpose, remove `context_path`
-   - OR if there's a semantic difference, document why both exist
-   - **Impact:** Reduces bloat and potential confusion
-
-### Cleanup (Nice to Have)
-
-1. **Consider Splitting Step 1**
-   - Step 1 handles both story discovery AND file loading
-   - Could be split into "1. Find Story" and "2. Load Story Files"
-   - Would improve clarity and maintainability
-   - **Impact:** Minor improvement to workflow structure
-
-2. **Add Variable Documentation Comment**
-   - Add a comment block in workflow.yaml listing all variables used by this workflow
-   - Include both explicit YAML variables and config-pulled variables
-   - Example format:
-     ```yaml
-     # Workflow-specific variables
-     # - story_file: Path to story markdown
-     # - story_dir: Directory containing stories
-     #
-     # Config-pulled variables (from bmm/config.yaml)
-     # - user_skill_level: User's technical skill level
-     # - document_output_language: Language for generated docs
-     ```
-   - **Impact:** Improves developer understanding and maintenance
-
----
-
-## Validation Checklist
-
-### Structure ✓
-
-- [x] workflow.yaml loads without YAML syntax errors
-- [x] instructions.md exists and is properly formatted
-- [x] No template.md (correct for action workflow)
-- [x] All critical headers present in instructions
-- [x] Workflow type correctly identified (action)
-- [x] All referenced files exist
-- [x] No placeholder text remains
-
-### Standard Config Block ✓
-
-- [x] config_source points to correct module config
-- [x] output_folder pulls from config_source
-- [x] user_name pulls from config_source
-- [x] communication_language pulls from config_source
-- [x] date is system-generated
-- [x] Config source uses {project-root} variable
-- [x] Standard config comment present
-
-### Config Variable Usage ✓
-
-- [x] Instructions communicate in {communication_language}
-- [x] Instructions address {user_name}
-- [x] All file outputs use {output_folder}
-- [x] No hardcoded paths
-- [x] Date available for agent awareness
-
-### YAML/Instruction/Template Alignment ⚠️
-
-- [⚠️] Some variables used in instructions not defined in YAML
-- [x] Template variables N/A (action workflow)
-- [x] Variable names are descriptive
-- [⚠️] One unused yaml field (context_path)
-
-### Web Bundle Validation ✓
-
-- [x] web_bundle: false is correct for this workflow
-- [x] No web_bundle section needed
-- [x] Workflow is local/IDE-integrated only
-
-### Instructions Quality ✓
-
-- [x] Steps numbered sequentially
-- [x] Clear goal attributes
-- [x] Proper XML tag usage
-- [x] Logical flow control
-- [⚠️] Minor inconsistency: {project_root} vs {project-root}
-
-### Bloat Detection ✓
-
-- [x] Bloat percentage: 11% (acceptable, under 15%)
-- [x] No significant hardcoded values
-- [x] No redundant configuration
-- [x] One cleanup recommendation (context_path)
-
----
-
-## Next Steps
-
-1. **Define missing variables** - Add explicit YAML definitions or document as config-pulled variables
-2. **Standardize variable syntax** - Change `{project_root}` to `{project-root}`
-3. **Remove context_path** - Clean up unused variable
-4. **Re-run audit** - Verify improvements after fixes
-
----
-
-## Additional Notes
-
-### Strengths
-
-1. **Comprehensive Workflow Logic:** The dev-story workflow is well-thought-out with proper error handling, validation gates, and iterative execution
-2. **Config Integration:** Excellent use of config variables for user personalization and output management
-3. **Clear Documentation:** Instructions are detailed with specific HALT conditions and validation checkpoints
-4. **Proper Web Bundle Setting:** Correctly identifies this as a local-only workflow with web_bundle: false
-5. **Step Flow:** Excellent use of anchors, goto, and conditional checks for complex flow control
-
-### Workflow Purpose
-
-This workflow executes user stories by:
-
-- Finding ready-for-dev stories from sprint status
-- Implementing tasks and subtasks incrementally
-- Writing comprehensive tests
-- Validating against acceptance criteria
-- Updating story status through sprint lifecycle
-- Supporting different user skill levels with adaptive communication
-
-The workflow is a critical part of the BMM implementation phase and shows mature design patterns.
-
----
-
-**Audit Complete** - Generated by audit-workflow v1.0
-
-**Pass Rate:** 89% (62 passed / 70 total checks)
-**Recommendation:** Good - Minor fixes needed
-
-The dev-story workflow is production-ready with minor improvements recommended. The issues identified are primarily documentation and consistency improvements rather than functional problems.

src/modules/bmm/workflows/4-implementation/dev-story/workflow.yaml

@@ -9,9 +9,7 @@ user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
 user_skill_level: "{config_source}:user_skill_level"
 document_output_language: "{config_source}:document_output_language"
-story_dir: "{config_source}:dev_ephemeral_location"
-run_until_complete: "{config_source}:run_until_complete"
-run_tests_command: "{config_source}:run_tests_command"
+story_dir: "{config_source}:sprint_artifacts"
 date: system-generated
 
 story_file: "" # Explicit story path; auto-discovered if empty

src/modules/bmm/workflows/4-implementation/epic-tech-context/instructions.md

@@ -15,7 +15,7 @@
 
     **Epic Discovery Process (SELECTIVE OPTIMIZATION):**
 
-    1. **Determine which epic** you need (epic_num from workflow context or user input)
+    1. **Determine which epic** you need (epic_num from {sprint_status} or user input)
     2. **Check for sharded version**: Look for `epics/index.md`
     3. **If sharded version found**:
       - Read `index.md` to understand structure
@@ -27,7 +27,7 @@
     **Other Documents (prd, gdd, architecture, ux-design) - Full Load:**
 
     1. **Search for whole document first** - Use fuzzy file matching
-    2. **Check for sharded version** - If whole document not found, look for `{doc-name}/index.md`
+    2. **Check for sharded version** - If whole document not found, look for `{doc-name}/*.*`
     3. **If sharded version found**:
       - Read `index.md` to understand structure
       - Read ALL section files listed in the index
@@ -158,7 +158,7 @@ Continuing to regenerate tech spec...
     <invoke-task>Validate against checklist at {installed_path}/checklist.md using {bmad_folder}/core/tasks/validate-workflow.xml</invoke-task>
 
     <!-- Mark epic as contexted -->
-    <action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
+    <action>Load the FULL file: {sprint_status}</action>
     <action>Find development_status key "epic-{{epic_id}}"</action>
     <action>Verify current status is "backlog" (expected previous state)</action>
     <action>Update development_status["epic-{{epic_id}}"] = "contexted"</action>

src/modules/bmm/workflows/4-implementation/epic-tech-context/workflow.yaml

@@ -8,8 +8,8 @@ output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
 date: system-generated
-context_dir: "{config_source}:dev_ephemeral_location/stories"
-sprint_status: "{context_dir}/sprint-status.yaml || {output_folder}/sprint-status.yaml"
+sprint_artifacts: "{config_source}:sprint_artifacts"
+sprint_status: "{sprint_artifacts}/sprint-status.yaml || {output_folder}/sprint-status.yaml"
 
 # Smart input file references - handles both whole docs and sharded docs
 # Priority: Whole document first, then sharded version
@@ -41,8 +41,6 @@ instructions: "{installed_path}/instructions.md"
 validation: "{installed_path}/checklist.md"
 
 # Output configuration
-default_output_file: "{context_dir}/tech-spec-epic-{{epic_id}}.md"
-
+default_output_file: "{sprint_artifacts}/tech-spec-epic-{{epic_id}}.md"
 standalone: true
-
 web_bundle: false

src/modules/bmm/workflows/4-implementation/retrospective/instructions.md

@@ -382,7 +382,7 @@ Alice (Product Owner): "Good thinking - helps us connect what we learned to what
 <action>Attempt to load next epic using selective loading strategy:</action>
 
 **Try sharded first (more specific):**
-<action>Check if file exists: {output*folder}/\_epic*/epic-{{next_epic_num}}.md</action>
+<action>Check if file exists: {output-folder}/\_epic\*/epic-{{next_epic_num}}.md</action>
 
 <check if="sharded epic file found">
   <action>Load {output_folder}/*epic*/epic-{{next_epic_num}}.md</action>
@@ -391,7 +391,7 @@ Alice (Product Owner): "Good thinking - helps us connect what we learned to what
 
 **Fallback to whole document:**
 <check if="sharded epic not found">
-<action>Check if file exists: {output*folder}/\_epic*.md</action>
+<action>Check if file exists: {output-folder}/\_epic\*.md</action>
 
   <check if="whole epic file found">
     <action>Load entire epics document</action>

src/modules/bmm/workflows/4-implementation/retrospective/workflow.yaml

@@ -10,15 +10,12 @@ communication_language: "{config_source}:communication_language"
 user_skill_level: "{config_source}:user_skill_level"
 document_output_language: "{config_source}:document_output_language"
 date: system-generated
-ephemeral_files: "{config_source}:dev_ephemeral_location"
+sprint_artifacts: "{config_source}:sprint_artifacts"
 
 installed_path: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/retrospective"
 template: false
 instructions: "{installed_path}/instructions.md"
 
-mode: interactive
-trigger: "Run AFTER completing an epic"
-
 required_inputs:
   - agent_manifest: "{project-root}/{bmad_folder}/_cfg/agent-manifest.csv"
 
@@ -31,40 +28,20 @@ input_file_patterns:
     sharded_index: "{output_folder}/*epic*/index.md"
     sharded_single: "{output_folder}/*epic*/epic-{{epic_num}}.md"
   previous_retrospective:
-    pattern: "{ephemeral_files}/retrospectives/epic-{{prev_epic_num}}-retro-*.md"
+    pattern: "{sprint_artifacts}/**/epic-{{prev_epic_num}}-retro-*.md"
   architecture:
     whole: "{output_folder}/*architecture*.md"
-    sharded: "{output_folder}/*architecture*/index.md"
+    sharded: "{output_folder}/*architecture*/*.md"
   prd:
     whole: "{output_folder}/*prd*.md"
-    sharded: "{output_folder}/*prd*/index.md"
+    sharded: "{output_folder}/*prd*/*.md"
   document_project:
-    sharded: "{output_folder}/docs/index.md"
+    sharded: "{output_folder}/*.md"
 
 # Required files
-sprint_status_file: "{context_dir}/sprint-status.yaml || {output_folder}/sprint-status.yaml"
-story_directory: "{ephemeral_files}/stories"
-retrospectives_folder: "{ephemeral_files}/retrospectives"
-
-output_artifacts:
-  - retrospective_summary: "Comprehensive review of what went well and what could improve"
-  - lessons_learned: "Key insights for future epics"
-  - action_items: "Specific improvements with ownership"
-  - next_epic_preparation: "Dependencies, gaps, and preparation tasks for next epic"
-  - critical_path: "Blockers or prerequisites that must be addressed"
-
-facilitation:
-  facilitator: "Bob (Scrum Master)"
-  tone: "Psychological safety - no blame, focus on systems and processes"
-  format: "Two-part: (1) Review completed epic + (2) Preview next epic preparation"
-
-validation_required:
-  - testing_complete: "Has full regression testing been completed?"
-  - deployment_status: "Has epic been deployed to production?"
-  - business_validation: "Have stakeholders reviewed and accepted deliverables?"
-  - technical_health: "Is codebase in stable, maintainable state?"
-  - blocker_resolution: "Any unresolved blockers that will impact next epic?"
+sprint_status_file: "{sprint_artifacts}/sprint-status.yaml || {output_folder}/sprint-status.yaml"
+story_directory: "{sprint_artifacts}"
+retrospectives_folder: "{sprint_artifacts}"
 
 standalone: true
-
 web_bundle: false

src/modules/bmm/workflows/4-implementation/sprint-planning/workflow.yaml

@@ -8,7 +8,7 @@ output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
 date: system-generated
-ephemeral_files: "{config_source}:dev_ephemeral_location"
+sprint_artifacts: "{config_source}:sprint_artifacts"
 
 # Workflow components
 installed_path: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/sprint-planning"
@@ -20,19 +20,18 @@ validation: "{installed_path}/checklist.md"
 variables:
   # Project identification
   project_name: "{config_source}:project_name"
-  project_key: "{config_source}:project_name" # Future: Jira project key, Linear workspace ID, etc.
 
   # Tracking system configuration
   tracking_system: "file-system" # Options: file-system, Future will support other options from config of mcp such as jira, linear, trello
   story_location: "{project-root}/docs/stories" # Relative path for file-system, Future will support URL for Jira/Linear/Trello
-  story_location_absolute: "{config_source}:dev_ephemeral_location" # Absolute path for file operations
+  story_location_absolute: "{config_source}:sprint_artifacts" # Absolute path for file operations
 
   # Source files (file-system only)
   epics_location: "{output_folder}" # Directory containing epic*.md files
   epics_pattern: "epic*.md" # Pattern to find epic files
 
   # Output configuration
-  status_file: "{ephemeral_files}/sprint-status.yaml"
+  status_file: "{sprint_artifacts}/sprint-status.yaml"
 
 # Smart input file references - handles both whole docs and sharded docs
 # Priority: Whole document first, then sharded version

src/modules/bmm/workflows/4-implementation/story-context/instructions.md

@@ -11,35 +11,6 @@
 
 <critical>DOCUMENT OUTPUT: Technical context file (.context.xml). Concise, structured, project-relative paths only.</critical>
 
-## 📚 Document Discovery - Selective Epic Loading
-
-**Strategy**: This workflow needs only ONE specific epic and its stories, not all epics. This provides huge efficiency gains when epics are sharded.
-
-**Epic Discovery Process (SELECTIVE OPTIMIZATION):**
-
-1. **Determine which epic** you need (epic_num from story key - e.g., story "3-2-feature-name" needs Epic 3)
-2. **Check for sharded version**: Look for `epics/index.md`
-3. **If sharded version found**:
-   - Read `index.md` to understand structure
-   - **Load ONLY `epic-{epic_num}.md`** (e.g., `epics/epic-3.md` for Epic 3)
-   - DO NOT load all epic files - only the one needed!
-   - This is the key efficiency optimization for large multi-epic projects
-4. **If whole document found**: Load the complete `epics.md` file and extract the relevant epic
-
-**Other Documents (prd, architecture, ux-design) - Full Load:**
-
-1. **Search for whole document first** - Use fuzzy file matching
-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 structure
-   - Read ALL section files listed in the index
-   - Treat combined content as single document
-4. **Brownfield projects**: The `document-project` workflow creates `{output_folder}/docs/index.md`
-
-**Priority**: If both whole and sharded versions exist, use the whole document.
-
-**UX-Heavy Projects**: Always check for ux-design documentation as it provides critical context for UI-focused stories.
-
 <workflow>
   <step n="1" goal="Find drafted story and check for existing context" tag="sprint-status">
     <check if="{{story_path}} is provided">
@@ -89,10 +60,10 @@
     <check if="context file already exists">
       <output>⚠️ Context file already exists: {default_output_file}
 
-**What would you like to do?**
-1. **Replace** - Generate new context file (overwrites existing)
-2. **Verify** - Validate existing context file
-3. **Cancel** - Exit without changes
+        **What would you like to do?**
+        1. **Replace** - Generate new context file (overwrites existing)
+        2. **Verify** - Validate existing context file
+        3. **Cancel** - Exit without changes
       </output>
       <ask>Choose action (replace/verify/cancel):</ask>
 

src/modules/bmm/workflows/4-implementation/story-context/workflow.yaml

@@ -9,9 +9,9 @@ output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
 document_output_language: "{config_source}:document_output_language"
-story_path: "{config_source}:dev_ephemeral_location/stories"
+story_path: "{config_source}:sprint_artifacts/stories"
 date: system-generated
-ephemeral_files: "{config_source}:dev_ephemeral_location"
+sprint_artifacts: "{config_source}:sprint_artifacts"
 sprint_status: "{context_dir}/sprint-status.yaml || {output_folder}/sprint-status.yaml"
 
 # Workflow components

src/modules/bmm/workflows/4-implementation/story-done/workflow.yaml

@@ -17,7 +17,7 @@ instructions: "{installed_path}/instructions.md"
 
 # Variables and inputs
 variables:
-  story_dir: "{config_source}:dev_ephemeral_location/stories" # Directory where stories are stored
+  story_dir: "{config_source}:sprint_artifacts/stories" # Directory where stories are stored
 
 # Output configuration - no output file, just status updates
 default_output_file: ""

src/modules/bmm/workflows/4-implementation/story-ready/instructions.md

@@ -14,12 +14,12 @@
 
 <action>If {{story_path}} is provided → use it directly; extract story_key from filename or metadata; GOTO mark_ready</action>
 
-<critical>MUST read COMPLETE sprint-status.yaml file from start to end to preserve order</critical>
-<action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
+<critical>MUST read COMPLETE {sprint_status} file from start to end to preserve order</critical>
+<action>Load the FULL file: {sprint_status}</action>
 <action>Read ALL lines from beginning to end - do not skip any content</action>
 <action>Parse the development_status section completely</action>
 
-<action>Find ALL stories (reading in order from top to bottom) where:
+<action>Find ALL stories (reading in order from start to end) where:
 
 - Key matches pattern: number-number-name (e.g., "1-2-user-auth")
 - NOT an epic key (epic-X) or retrospective (epic-X-retrospective)
@@ -30,7 +30,7 @@
 <action>Count total drafted stories found</action>
 
 <check if="no drafted stories found">
-  <output>📋 No drafted stories found in sprint-status.yaml
+  <output>📋 No drafted stories found in {sprint_status}
 
 All stories are either still in backlog or already marked ready/in-progress/done.
 
@@ -67,7 +67,7 @@ All stories are either still in backlog or already marked ready/in-progress/done
 </step>
 
 <step n="2" goal="Update sprint status to ready-for-dev" tag="sprint-status">
-<action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
+<action>Load the FULL file: {sprint_status}</action>
 <action>Find development_status key matching {{story_key}}</action>
 <action>Verify current status is "drafted" (expected previous state)</action>
 <action>Update development_status[{{story_key}}] = "ready-for-dev"</action>

src/modules/bmm/workflows/4-implementation/story-ready/workflow.yaml

@@ -9,7 +9,7 @@ output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
 date: system-generated
-sprint_status: "{context_dir}/sprint-status.yaml || {output_folder}/sprint-status.yaml"
+sprint_status: "{output_folder}/sprint-status.yaml || {sprint_artifacts}/sprint-status.yaml"
 
 # Workflow components
 installed_path: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/story-ready"
@@ -17,10 +17,7 @@ instructions: "{installed_path}/instructions.md"
 
 # Variables and inputs
 variables:
-  story_dir: "{config_source}:dev_ephemeral_location/stories" # Directory where stories are stored
-
-# Output configuration - no output file, just status updates
-default_output_file: ""
+  story_dir: "{config_source}:sprint_artifacts"
 
 standalone: true