fix: remove output_folder/story_dir aliases, flatten variables sections (#1602)

Drop pointless alias variables (output_folder, story_dir, story_directory)
from Phase 4, Quick Flow, and QA workflows. Replace all references with
the canonical {implementation_artifacts} or {planning_artifacts} variables.

Also flatten unnecessary `variables:` YAML nesting in all affected
workflow.yaml files — the workflow engine treats all keys as top-level,
so the nesting added complexity with no semantic value.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

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

@@ -12,7 +12,6 @@ document_output_language: "{config_source}:document_output_language"
 date: system-generated
 planning_artifacts: "{config_source}:planning_artifacts"
 implementation_artifacts: "{config_source}:implementation_artifacts"
-output_folder: "{implementation_artifacts}"
 sprint_status: "{implementation_artifacts}/sprint-status.yaml"
 
 # Workflow components
@@ -21,10 +20,7 @@ instructions: "{installed_path}/instructions.xml"
 validation: "{installed_path}/checklist.md"
 template: false
 
-variables:
-  # Project context
-  project_context: "**/project-context.md"
-  story_dir: "{implementation_artifacts}"
+project_context: "**/project-context.md"
 
 # Smart input file references - handles both whole docs and sharded docs
 # Priority: Whole document first, then sharded version

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

@@ -12,7 +12,6 @@ date: system-generated
 implementation_artifacts: "{config_source}:implementation_artifacts"
 planning_artifacts: "{config_source}:planning_artifacts"
 project_knowledge: "{config_source}:project_knowledge"
-output_folder: "{implementation_artifacts}"
 sprint_status: "{implementation_artifacts}/sprint-status.yaml"
 project_context: "**/project-context.md"
 

src/bmm/workflows/4-implementation/create-story/checklist.md

@@ -49,7 +49,7 @@ This is a COMPETITION to create the **ULTIMATE story context** that makes LLM de
 ### **Required Inputs:**
 
 - **Story file**: The story file to review and improve
-- **Workflow variables**: From workflow.yaml (story_dir, output_folder, epics_file, etc.)
+- **Workflow variables**: From workflow.yaml (implementation_artifacts, epics_file, etc.)
 - **Source documents**: Epics, architecture, etc. (discovered or provided)
 - **Validation framework**: `validate-workflow.xml` (handles checklist execution)
 
@@ -65,7 +65,7 @@ You will systematically re-do the entire story creation process, but with a crit
 2. **Load the story file**: `{story_file_path}` (provided by user or discovered)
 3. **Load validation framework**: `{project-root}/_bmad/core/tasks/validate-workflow.xml`
 4. **Extract metadata**: epic_num, story_num, story_key, story_title from story file
-5. **Resolve all workflow variables**: story_dir, output_folder, epics_file, architecture_file, etc.
+5. **Resolve all workflow variables**: implementation_artifacts, epics_file, architecture_file, etc.
 6. **Understand current status**: What story implementation guidance is currently provided?
 
 **Note:** If running in fresh context, user should provide the story file path being reviewed. If running from create-story workflow, the validation framework will automatically discover the checklist and story file.

src/bmm/workflows/4-implementation/create-story/instructions.xml

@@ -192,7 +192,7 @@
     (As a, I want, so that) - Detailed acceptance criteria (already BDD formatted) - Technical requirements specific to this story -
     Business context and value - Success criteria <!-- Previous story analysis for context continuity -->
     <check if="story_num > 1">
-      <action>Load previous story file: {{story_dir}}/{{epic_num}}-{{previous_story_num}}-*.md</action> **PREVIOUS STORY INTELLIGENCE:** -
+      <action>Load previous story file: {{implementation_artifacts}}/{{epic_num}}-{{previous_story_num}}-*.md</action> **PREVIOUS STORY INTELLIGENCE:** -
     Dev notes and learnings from previous story - Review feedback and corrections needed - Files that were created/modified and their
     patterns - Testing approaches that worked/didn't work - Problems encountered and solutions found - Code patterns established <action>Extract
     all learnings that could impact current story implementation</action>

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

@@ -9,8 +9,6 @@ communication_language: "{config_source}:communication_language"
 date: system-generated
 planning_artifacts: "{config_source}:planning_artifacts"
 implementation_artifacts: "{config_source}:implementation_artifacts"
-output_folder: "{implementation_artifacts}"
-story_dir: "{implementation_artifacts}"
 
 # Workflow components
 installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/create-story"
@@ -19,18 +17,14 @@ instructions: "{installed_path}/instructions.xml"
 validation: "{installed_path}/checklist.md"
 
 # Variables and inputs
-variables:
-  sprint_status: "{implementation_artifacts}/sprint-status.yaml" # Primary source for story tracking
-  epics_file: "{planning_artifacts}/epics.md" # Enhanced epics+stories with BDD and source hints
-  prd_file: "{planning_artifacts}/prd.md" # Fallback for requirements (if not in epics file)
-  architecture_file: "{planning_artifacts}/architecture.md" # Fallback for constraints (if not in epics file)
-  ux_file: "{planning_artifacts}/*ux*.md" # Fallback for UX requirements (if not in epics file)
-  story_title: "" # Will be elicited if not derivable
-
-# Project context
+sprint_status: "{implementation_artifacts}/sprint-status.yaml" # Primary source for story tracking
+epics_file: "{planning_artifacts}/epics.md" # Enhanced epics+stories with BDD and source hints
+prd_file: "{planning_artifacts}/prd.md" # Fallback for requirements (if not in epics file)
+architecture_file: "{planning_artifacts}/architecture.md" # Fallback for constraints (if not in epics file)
+ux_file: "{planning_artifacts}/*ux*.md" # Fallback for UX requirements (if not in epics file)
+story_title: "" # Will be elicited if not derivable
 project_context: "**/project-context.md"
-
-default_output_file: "{story_dir}/{{story_key}}.md"
+default_output_file: "{implementation_artifacts}/{{story_key}}.md"
 
 # Smart input file references - Simplified for enhanced approach
 # The epics+stories file should contain everything needed with source hints

src/bmm/workflows/4-implementation/dev-story/instructions.xml

@@ -78,7 +78,7 @@
 
     <!-- Non-sprint story discovery -->
     <check if="{{sprint_status}} file does NOT exist">
-      <action>Search {story_dir} for stories directly</action>
+      <action>Search {implementation_artifacts} for stories directly</action>
       <action>Find stories with "ready-for-dev" status in files</action>
       <action>Look for story files matching pattern: *-*-*.md</action>
       <action>Read each candidate story file to check Status section</action>
@@ -114,7 +114,7 @@
     </check>
 
     <action>Store the found story_key (e.g., "1-2-user-authentication") for later status updates</action>
-    <action>Find matching story file in {story_dir} using story_key pattern: {{story_key}}.md</action>
+    <action>Find matching story file in {implementation_artifacts} using story_key pattern: {{story_key}}.md</action>
     <action>Read COMPLETE story file from discovered path</action>
 
     <anchor id="task_check" />

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

@@ -4,12 +4,10 @@ author: "BMad"
 
 # Critical variables from config
 config_source: "{project-root}/_bmad/bmm/config.yaml"
-output_folder: "{config_source}:output_folder"
 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}:implementation_artifacts"
 date: system-generated
 
 # Workflow components

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

@@ -81,7 +81,7 @@ Bob (Scrum Master): "I'm having trouble detecting the completed epic from {sprin
 <check if="{{epic_number}} still not determined">
   <action>PRIORITY 3: Fallback to stories folder</action>
 
-<action>Scan {story_directory} for highest numbered story files</action>
+<action>Scan {implementation_artifacts} for highest numbered story files</action>
 <action>Extract epic numbers from story filenames (pattern: epic-X-Y-story-name.md)</action>
 <action>Set {{detected_epic}} = highest epic number found</action>
 
@@ -171,7 +171,7 @@ Bob (Scrum Master): "Before we start the team discussion, let me review all the
 Charlie (Senior Dev): "Good idea - those dev notes always have gold in them."
 </output>
 
-<action>For each story in epic {{epic_number}}, read the complete story file from {story_directory}/{{epic_number}}-{{story_num}}-\*.md</action>
+<action>For each story in epic {{epic_number}}, read the complete story file from {implementation_artifacts}/{{epic_number}}-{{story_num}}-\*.md</action>
 
 <action>Extract and analyze from each story:</action>
 

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

@@ -4,7 +4,6 @@ description: "Run after epic completion to review overall success, extract lesso
 author: "BMad"
 
 config_source: "{project-root}/_bmad/bmm/config.yaml"
-output_folder: "{config_source}:implementation_artifacts}"
 user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
 user_skill_level: "{config_source}:user_skill_level"
@@ -52,5 +51,4 @@ input_file_patterns:
 
 # Required files
 sprint_status_file: "{implementation_artifacts}/sprint-status.yaml"
-story_directory: "{implementation_artifacts}"
 retrospectives_folder: "{implementation_artifacts}"

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

@@ -9,7 +9,6 @@ communication_language: "{config_source}:communication_language"
 date: system-generated
 implementation_artifacts: "{config_source}:implementation_artifacts"
 planning_artifacts: "{config_source}:planning_artifacts"
-output_folder: "{implementation_artifacts}"
 
 # Workflow components
 installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/sprint-planning"
@@ -18,24 +17,21 @@ template: "{installed_path}/sprint-status-template.yaml"
 validation: "{installed_path}/checklist.md"
 
 # Variables and inputs
-variables:
-  # Project context
-  project_context: "**/project-context.md"
-  # Project identification
-  project_name: "{config_source}:project_name"
+project_context: "**/project-context.md"
+project_name: "{config_source}:project_name"
 
-  # Tracking system configuration
-  tracking_system: "file-system" # Options: file-system, Future will support other options from config of mcp such as jira, linear, trello
-  project_key: "NOKEY" # Placeholder for tracker integrations; file-system uses a no-op key
-  story_location: "{config_source}:implementation_artifacts" # Relative path for file-system, Future will support URL for Jira/Linear/Trello
-  story_location_absolute: "{config_source}:implementation_artifacts" # Absolute path for file operations
+# Tracking system configuration
+tracking_system: "file-system" # Options: file-system, Future will support other options from config of mcp such as jira, linear, trello
+project_key: "NOKEY" # Placeholder for tracker integrations; file-system uses a no-op key
+story_location: "{config_source}:implementation_artifacts" # Relative path for file-system, Future will support URL for Jira/Linear/Trello
+story_location_absolute: "{config_source}:implementation_artifacts" # Absolute path for file operations
 
-  # Source files (file-system only)
-  epics_location: "{planning_artifacts}" # Directory containing epic*.md files
-  epics_pattern: "epic*.md" # Pattern to find epic files
+# Source files (file-system only)
+epics_location: "{planning_artifacts}" # Directory containing epic*.md files
+epics_pattern: "epic*.md" # Pattern to find epic files
 
-  # Output configuration
-  status_file: "{implementation_artifacts}/sprint-status.yaml"
+# Output configuration
+status_file: "{implementation_artifacts}/sprint-status.yaml"
 
 # Smart input file references - handles both whole docs and sharded docs
 # Priority: Whole document first, then sharded version
@@ -43,8 +39,8 @@ variables:
 input_file_patterns:
   epics:
     description: "All epics with user stories"
-    whole: "{output_folder}/*epic*.md"
-    sharded: "{output_folder}/*epic*/*.md"
+    whole: "{planning_artifacts}/*epic*.md"
+    sharded: "{planning_artifacts}/*epic*/*.md"
     load_strategy: "FULL_LOAD"
 
 # Output configuration

src/bmm/workflows/4-implementation/sprint-status/workflow.yaml

@@ -5,7 +5,6 @@ author: "BMad"
 
 # Critical variables from config
 config_source: "{project-root}/_bmad/bmm/config.yaml"
-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"
@@ -19,9 +18,8 @@ installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/sprint-stat
 instructions: "{installed_path}/instructions.md"
 
 # Inputs
-variables:
-  sprint_status_file: "{implementation_artifacts}/sprint-status.yaml"
-  tracking_system: "file-system"
+sprint_status_file: "{implementation_artifacts}/sprint-status.yaml"
+tracking_system: "file-system"
 
 # Smart input file references
 input_file_patterns:

src/bmm/workflows/bmad-quick-flow/quick-dev/workflow.md

@@ -28,7 +28,7 @@ This uses **step-file architecture** for focused execution:
 Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
 
 - `user_name`, `communication_language`, `user_skill_level`
-- `output_folder`, `planning_artifacts`,  `implementation_artifacts`
+- `planning_artifacts`, `implementation_artifacts`
 - `date` as system-generated current datetime
 - ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
 

src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-01-understand.md

@@ -76,7 +76,7 @@ a) **Before asking detailed questions, do a rapid scan to understand the landsca
 
 b) **Check for existing context docs:**
 
-- Check `{output_folder}` and `{planning_artifacts}`for planning documents (PRD, architecture, epics, research)
+- Check `{implementation_artifacts}` and `{planning_artifacts}`for planning documents (PRD, architecture, epics, research)
 - Check for `**/project-context.md` - if it exists, skim for patterns and conventions
 - Check for any existing stories or specs related to user's request
 

src/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md

@@ -68,7 +68,7 @@ This uses **step-file architecture** for disciplined execution:
 
 Load and read full config from `{main_config}` and resolve:
 
-- `project_name`, `output_folder`, `planning_artifacts`, `implementation_artifacts`, `user_name`
+- `project_name`, `planning_artifacts`, `implementation_artifacts`, `user_name`
 - `communication_language`, `document_output_language`, `user_skill_level`
 - `date` as system-generated current datetime
 - `project_context` = `**/project-context.md` (load if exists)

src/bmm/workflows/qa/automate/workflow.yaml

@@ -5,7 +5,6 @@ author: "BMad"
 
 # Critical variables from config
 config_source: "{project-root}/_bmad/bmm/config.yaml"
-output_folder: "{config_source}:output_folder"
 implementation_artifacts: "{config_source}:implementation_artifacts"
 user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
@@ -19,10 +18,8 @@ validation: "{installed_path}/checklist.md"
 template: false
 
 # Variables and inputs
-variables:
-  # Directory paths
-  test_dir: "{project-root}/tests" # Root test directory
-  source_dir: "{project-root}" # Source code directory
+test_dir: "{project-root}/tests" # Root test directory
+source_dir: "{project-root}" # Source code directory
 
 # Output configuration
 default_output_file: "{implementation_artifacts}/tests/test-summary.md"