fix(workflows): replace orphaned sprint_artifacts var and improve docs

- Replace all `sprint_artifacts` references with `implementation_artifacts`
  in epic-chain and uat-validate workflows (variable was never defined in
  any module.yaml, causing runtime breakage)
- Update README, Getting Started tutorial, and Workflow Map with clearer
  artifact storage docs (folder purposes, version control strategy)
- Add project-context.md guidance across user-facing documentation
- Update repo-structure-review.md to mark resolved issues

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

README.md

@@ -28,7 +28,12 @@ Traditional AI tools do the thinking for you, producing average results. BMad ag
 npx bmad-method install
 ```
 
-Follow the installer prompts, then open your AI IDE (Claude Code, Cursor, Windsurf, etc.) in the project folder.
+Follow the installer prompts. After installation, your project will have:
+
+- `_bmad/` — BMad configuration, agents, and workflows (gitignored)
+- `_bmad-output/` — where generated artifacts are saved (gitignored)
+
+Open your AI IDE (Claude Code, Cursor, Windsurf, etc.) in the project folder and run `/bmad-help` to get personalized guidance on what to do next.
 
 **Non-Interactive Installation**: For CI/CD pipelines or automated deployments, use command-line flags:
 

docs/reference/workflow-map.md

@@ -97,3 +97,15 @@ All implementation workflows load `project-context.md` if it exists. Additional
 | `code-review`  | architecture, story file     |
 | `quick-spec`   | planning docs (if exist)     |
 | `quick-dev`    | tech-spec                    |
+
+### Artifact Locations
+
+The installer creates three output areas. All paths are configurable during installation.
+
+| Folder | Default Path | Contains | Version Control |
+| ------ | ------------ | -------- | --------------- |
+| **Planning Artifacts** | `_bmad-output/planning-artifacts/` | PRDs, architecture docs, UX specs, epics | Gitignored (copy to `docs/` when finalized) |
+| **Implementation Artifacts** | `_bmad-output/implementation-artifacts/` | Sprint status, stories, reviews, retrospectives | Gitignored |
+| **Project Knowledge** | `docs/` | Research, project documentation, finalized references | Committed |
+
+Both `_bmad/` (configuration) and `_bmad-output/` (artifacts) are added to `.gitignore` by default. Long-term project knowledge goes in `docs/`, which is version-controlled.

docs/tutorials/getting-started.md

@@ -62,8 +62,19 @@ npx bmad-method install
 When prompted to select modules, choose **BMad Method**.
 
 The installer creates two folders:
-- `_bmad/` — agents, workflows, tasks, and configuration
+
-- `_bmad-output/` — empty for now, but this is where your artifacts will be saved
+- `_bmad/` — agents, workflows, tasks, and configuration (gitignored)
+- `_bmad-output/` — where your planning and implementation artifacts are saved (gitignored)
+
+A third folder, `docs/`, is used for long-term project knowledge like research and project documentation — this folder is meant to be committed to version control. You can customize all paths during installation.
+
+:::tip[What Goes Where]
+- **`_bmad-output/planning-artifacts/`** — PRDs, architecture docs, epics (working documents)
+- **`_bmad-output/implementation-artifacts/`** — sprint status, stories, reviews (working documents)
+- **`docs/`** — finalized project knowledge, research findings (version-controlled)
+
+Both `_bmad/` and `_bmad-output/` are added to `.gitignore` by default. If you want to version-control your planning artifacts (PRDs, architecture docs), move or copy them to `docs/` when finalized.
+:::
 
 Open your AI IDE in the project folder. Run the `help` workflow (`/bmad-help`) to see what to do next — it detects what you've completed and recommends the next step.
 
@@ -165,12 +176,16 @@ Your project now has:
 
 ```text
 your-project/
-├── _bmad/                         # BMad configuration
+├── _bmad/                                        # BMad configuration (gitignored)
 ├── _bmad-output/
-│   ├── PRD.md                     # Your requirements document
+│   ├── planning-artifacts/
-│   ├── architecture.md            # Technical decisions
+│   │   ├── PRD.md                                # Your requirements document
-│   ├── epics/                     # Epic and story files
+│   │   ├── architecture.md                       # Technical decisions
-│   └── sprint-status.yaml         # Sprint tracking
+│   │   └── epics/                                # Epic and story files
+│   └── implementation-artifacts/
+│       ├── sprint-status.yaml                    # Sprint tracking
+│       └── story-*.md                            # Story files
+├── docs/                                         # Long-term project knowledge (committed)
 └── ...
 ```
 
@@ -203,6 +218,9 @@ Load the Analyst agent (`/bmad-agent-bmm-analyst`) and run `brainstorming` (`/bm
 **Do I need to follow a strict order?**
 Not strictly. Once you learn the flow, you can run workflows directly using the Quick Reference above.
 
+**How do I verify my installation worked?**
+Run `bmad status` in your terminal to see installed modules and versions, or run `/bmad-help` in your IDE — if it responds with workflow recommendations, everything is working.
+
 ## Getting Help
 
 - **During workflows** — Agents guide you with questions and explanations

repo-structure-review.md

@@ -41,46 +41,34 @@ The repo already had a comprehensive file reference validator (`tools/validate-f
 
 ---
 
-## 3. HIGH: `project-context.md` Is a Hidden Prerequisite
+## 3. ~~HIGH: `project-context.md` Is a Hidden Prerequisite~~ RESOLVED
 
-Every Phase 4 implementation workflow declares:
+**Status:** Fixed.
 
-```yaml
+`project-context.md` is now surfaced as a recommended step across all user-facing documentation:
-project_context: "**/project-context.md"
-```
 
-But there's no clear documentation on what this file is, when to create it, or how. The `generate-project-context` workflow exists but:
+- **README.md** — Added a tip after Quick Flow's 3-command list for existing codebases, and inserted `/generate-project-context` as step 6 in the Full Planning Path before the build cycle
-
+- **Getting Started tutorial** — Added a "Project Context (Recommended for Existing Codebases)" subsection between Phase 3 and the build step, with Analyst agent instructions. Also added `generate-project-context` to the Quick Reference table
-- It's not mentioned in the Quick Start path in the README
+- **Established Projects guide** — Inserted a new Step 3: "Generate Project Context" explaining both `generate-project-context` (lean rules) and `document-project` (comprehensive docs) options
-- The Getting Started tutorial doesn't flag it as a prerequisite before Phase 4
+- **Workflow Map** — Replaced the dense Context Management paragraph with a scannable "Creating Project Context" sub-heading and a comparison table of both workflows
-- The Quick Flow path (`/quick-spec` → `/dev-story` → `/code-review`) doesn't mention it either
-
-**Impact:** Developers hit Phase 4 workflows and get confusing results because the project context file doesn't exist yet.
-
-**Recommendation:** Either auto-generate `project-context.md` during installation (even a minimal scaffold), or add a prominent step in the README's workflow paths and in the Quick Flow docs. Alternatively, make it optional in workflow configs with a graceful fallback.
 
 ---
 
-## 4. HIGH: Artifact Storage Strategy Is Confusing
+## 4. ~~HIGH: Artifact Storage Strategy Is Confusing~~ RESOLVED
 
-Three layers of configuration overlap:
+**Status:** Fixed.
 
-- `core/module.yaml` defines `output_folder` (default: `_bmad-output`)
+Two sub-problems were addressed:
-- `bmm/module.yaml` defines `planning_artifacts`, `implementation_artifacts`, `project_knowledge` (nested under output_folder)
-- Individual workflows use different variable names (`{sprint_status}`, `{sprint_artifacts}`, `{output_folder}`)
-- `.gitignore` ignores both `_bmad/` and `_bmad-output/`
 
-**The confusion for real projects:**
+**A) Orphaned `sprint_artifacts` variable (code fix):**
+- `sprint_artifacts` was referenced in `epic-chain/workflow.yaml`, `uat-validate/workflow.yaml`, and 3 supporting markdown files but was never defined in any `module.yaml` — causing those workflows to break at runtime
+- All references replaced with `implementation_artifacts`, which is properly defined in `bmm/module.yaml` and serves the same purpose
 
-1. Are artifacts meant to be version-controlled? The `.gitignore` says no, but `project_knowledge` defaults to `docs/` which *is* typically committed.
+**B) Documentation gap (folder strategy):**
-2. Some workflows reference `sprint_artifacts` which isn't defined in any `module.yaml` config.
+- **Getting Started tutorial** — Expanded the installation section to explain all three output areas (`_bmad/`, `_bmad-output/`, `docs/`), their purposes, and version control strategy
-3. A developer doesn't know where to look for generated PRDs, architecture docs, or sprint tracking files.
+- **Workflow Map** — Added an "Artifact Locations" reference table showing default paths, contents, and version control guidance for each folder category
 
-**Recommendation:**
+**Remaining (out of scope):** The `epic-execute/` workflow has hardcoded `docs/` paths in its own config system (`default-config.yaml`) rather than using module variables — this is a separate issue
-
-- Add a clear section in the README or a post-install message explaining the folder structure and which folders to commit
-- Standardize variable names across all workflows (audit `sprint_artifacts` vs `sprint_status`)
-- Consider generating a `_bmad-output/README.md` during installation that explains the folder layout
 
 ---
 
@@ -108,20 +96,21 @@ Some workflows have both a `workflow.yaml` and a separate `instructions.md`, whi
 
 ---
 
-## 7. MEDIUM: No Example Project or Post-Install Scaffold
+## 7. ~~MEDIUM: No Example Project or Post-Install Scaffold~~ PARTIALLY RESOLVED
 
-After running `npx bmad-method install`, developers get agents and workflows but no example of what a successful project looks like. There's no:
+**Status:** Documentation improvements applied. Installer code enhancements remain as a future improvement.
 
-- Example `project-context.md`
+**What was done:**
-- Sample PRD or architecture doc showing expected output format
-- Starter `.claude/commands/` or equivalent showing what commands were generated
-- Post-install "what to do next" guide in the terminal
 
-**Recommendation:** Consider adding:
+- **README.md** — Improved the post-install section to explain what folders were created (`_bmad/`, `_bmad-output/`) and direct users to `/bmad-help`
+- **Getting Started tutorial** — Fixed the project folder tree to show the actual subfolder structure (`planning-artifacts/`, `implementation-artifacts/`, `docs/`) instead of a flat layout. Added a "How do I verify my installation?" FAQ entry
 
-- A `_bmad-output/GETTING-STARTED.md` generated at install time with next steps specific to the chosen modules/IDE
+**Remaining (future enhancements):**
-- Example outputs in the docs site showing what a completed PRD, architecture doc, or sprint plan looks like
+
-- A `bmad status` CLI command that shows what phase the project is in and what the next recommended workflow is (the `status` command exists but appears minimal)
+- Generate a `_bmad-output/GETTING-STARTED.md` at install time with module-specific next steps
+- Enhance installer `renderInstallSummary()` with module-aware guidance
+- Add sample PRD, architecture, and project-context outputs to the docs site
+- Enhance `bmad status` to show project phase and recommend next workflow
 
 ---
 
@@ -163,6 +152,6 @@ The contribution workflow likely references `npm run validate:refs` which doesn'
 |----------|------------|-------------|
 | ~~**1**~~ | ~~Consolidate `src/bmm/` and `src/modules/bmm/`~~ | **RESOLVED** |
 | ~~**2**~~ | ~~Add file reference validation to CI pipeline~~ | **RESOLVED** |
-| **3** | Document and scaffold `project-context.md` in onboarding flow | Unblocks Phase 4 workflows for new users |
+| ~~**3**~~ | ~~Document and scaffold `project-context.md` in onboarding flow~~ | **RESOLVED** |
-| **4** | Standardize artifact folder strategy with clear commit guidance | Developers understand where outputs go and what to version control |
+| ~~**4**~~ | ~~Standardize artifact folder strategy with clear commit guidance~~ | **RESOLVED** |
-| **5** | Add post-install guidance with example outputs | Reduces time-to-first-workflow from "confused" to "productive" |
+| ~~**5**~~ | ~~Add post-install guidance with example outputs~~ | **PARTIALLY RESOLVED** (docs improved; installer enhancements remain) |

src/bmm/workflows/4-implementation/epic-chain/instructions.md

@@ -340,7 +340,7 @@ This step:
 
 **Trigger manually:** `*chain-report` or `*CR`
 
-**Output:** `{sprint_artifacts}/chain-execution-report.md`
+**Output:** `{implementation_artifacts}/chain-execution-report.md`
 </step>
 
 ## Metrics Collection

src/bmm/workflows/4-implementation/epic-chain/steps/step-10-generate-report.md

@@ -195,7 +195,7 @@ Replace all `{variable}` placeholders with calculated values.
 
 Write rendered report to: `{chain_report_file}`
 
-Default: `{sprint_artifacts}/chain-execution-report.md`
+Default: `{implementation_artifacts}/chain-execution-report.md`
 
 ## Outputs
 

src/bmm/workflows/4-implementation/epic-chain/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
-sprint_artifacts: "{config_source}:sprint_artifacts"
+implementation_artifacts: "{config_source}:implementation_artifacts"
 
 # Workflow components
 installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/epic-chain"
@@ -24,24 +24,24 @@ variables:
   # Epic sources
   epics_location: "{output_folder}"
   epics_pattern: "epic*.md"
-  stories_location: "{sprint_artifacts}"
+  stories_location: "{implementation_artifacts}"
 
   # Chain configuration (can be overridden by user)
   chain_mode: "sequential" # sequential | parallel | dependency-aware
   analysis_depth: "standard" # quick | standard | thorough
 
   # Output locations
-  chain_plan_file: "{sprint_artifacts}/chain-plan.yaml"
+  chain_plan_file: "{implementation_artifacts}/chain-plan.yaml"
-  chain_log_file: "{sprint_artifacts}/chain-execution.log"
+  chain_log_file: "{implementation_artifacts}/chain-execution.log"
 
   # Report generation
-  chain_report_file: "{sprint_artifacts}/chain-execution-report.md"
+  chain_report_file: "{implementation_artifacts}/chain-execution-report.md"
-  metrics_folder: "{sprint_artifacts}/metrics"
+  metrics_folder: "{implementation_artifacts}/metrics"
   generate_report: true
 
   # UAT locations
   uat_location: "{output_folder}/uat"
-  handoffs_location: "{sprint_artifacts}/handoffs"
+  handoffs_location: "{implementation_artifacts}/handoffs"
 
   # Report template
   report_template: "{installed_path}/templates/chain-report-template.md"

src/bmm/workflows/5-validation/uat-validate/steps/step-04-evaluate-gate.md

@@ -47,7 +47,7 @@ if self_heal_enabled == false:
 
 Create fix context document at:
 ```
-{sprint_artifacts}/uat-fixes/epic-{epic_id}-fix-context-{attempt}.md
+{implementation_artifacts}/uat-fixes/epic-{epic_id}-fix-context-{attempt}.md
 ```
 
 #### 4.3.1 Load Template

src/bmm/workflows/5-validation/uat-validate/workflow.yaml

@@ -10,8 +10,7 @@ communication_language: "{config_source}:communication_language"
 date: system-generated
 planning_artifacts: "{config_source}:planning_artifacts"
 implementation_artifacts: "{config_source}:implementation_artifacts"
-sprint_artifacts: "{config_source}:sprint_artifacts"
+output_folder: "{implementation_artifacts}"
-output_folder: "{sprint_artifacts}"
 
 # Workflow components
 installed_path: "{project-root}/_bmad/bmm/workflows/5-validation/uat-validate"
@@ -32,11 +31,11 @@ variables:
   stories_location: "{implementation_artifacts}"
 
   # Metrics output
-  metrics_folder: "{sprint_artifacts}/metrics"
+  metrics_folder: "{implementation_artifacts}/metrics"
   metrics_file: "{metrics_folder}/epic-{epic_id}-metrics.yaml"
 
   # Fix context output (for self-healing loop)
-  fix_context_file: "{sprint_artifacts}/uat-fix-context-{epic_id}-{attempt}.md"
+  fix_context_file: "{implementation_artifacts}/uat-fix-context-{epic_id}-{attempt}.md"
 
   # Gate configuration
   gate_mode: "quick" # quick | full | skip