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>
This commit is contained in:
Caleb
parent
a58fb564d1
commit
1eedebaca8
|
|
@ -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:
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
│ ├── architecture.md # Technical decisions
|
||||
│ ├── epics/ # Epic and story files
|
||||
│ └── sprint-status.yaml # Sprint tracking
|
||||
│ ├── planning-artifacts/
|
||||
│ │ ├── PRD.md # Your requirements document
|
||||
│ │ ├── architecture.md # Technical decisions
|
||||
│ │ └── 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
|
||||
|
|
|
|||
|
|
@ -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: "**/project-context.md"
|
||||
```
|
||||
`project-context.md` is now surfaced as a recommended step across all user-facing documentation:
|
||||
|
||||
But there's no clear documentation on what this file is, when to create it, or how. The `generate-project-context` workflow exists but:
|
||||
|
||||
- It's not mentioned in the Quick Start path in the README
|
||||
- The Getting Started tutorial doesn't flag it as a prerequisite before Phase 4
|
||||
- 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.
|
||||
- **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
|
||||
- **Established Projects guide** — Inserted a new Step 3: "Generate Project Context" explaining both `generate-project-context` (lean rules) and `document-project` (comprehensive docs) options
|
||||
- **Workflow Map** — Replaced the dense Context Management paragraph with a scannable "Creating Project Context" sub-heading and a comparison table of both workflows
|
||||
|
||||
---
|
||||
|
||||
## 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`)
|
||||
- `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/`
|
||||
Two sub-problems were addressed:
|
||||
|
||||
**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.
|
||||
2. Some workflows reference `sprint_artifacts` which isn't defined in any `module.yaml` config.
|
||||
3. A developer doesn't know where to look for generated PRDs, architecture docs, or sprint tracking files.
|
||||
**B) Documentation gap (folder strategy):**
|
||||
- **Getting Started tutorial** — Expanded the installation section to explain all three output areas (`_bmad/`, `_bmad-output/`, `docs/`), their purposes, and version control strategy
|
||||
- **Workflow Map** — Added an "Artifact Locations" reference table showing default paths, contents, and version control guidance for each folder category
|
||||
|
||||
**Recommendation:**
|
||||
|
||||
- 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
|
||||
**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
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -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`
|
||||
- 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
|
||||
**What was done:**
|
||||
|
||||
**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
|
||||
- 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)
|
||||
**Remaining (future enhancements):**
|
||||
|
||||
- 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 |
|
||||
| **4** | Standardize artifact folder strategy with clear commit guidance | Developers understand where outputs go and what to version control |
|
||||
| **5** | Add post-install guidance with example outputs | Reduces time-to-first-workflow from "confused" to "productive" |
|
||||
| ~~**3**~~ | ~~Document and scaffold `project-context.md` in onboarding flow~~ | **RESOLVED** |
|
||||
| ~~**4**~~ | ~~Standardize artifact folder strategy with clear commit guidance~~ | **RESOLVED** |
|
||||
| ~~**5**~~ | ~~Add post-install guidance with example outputs~~ | **PARTIALLY RESOLVED** (docs improved; installer enhancements remain) |
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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_log_file: "{sprint_artifacts}/chain-execution.log"
|
||||
chain_plan_file: "{implementation_artifacts}/chain-plan.yaml"
|
||||
chain_log_file: "{implementation_artifacts}/chain-execution.log"
|
||||
|
||||
# Report generation
|
||||
chain_report_file: "{sprint_artifacts}/chain-execution-report.md"
|
||||
metrics_folder: "{sprint_artifacts}/metrics"
|
||||
chain_report_file: "{implementation_artifacts}/chain-execution-report.md"
|
||||
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"
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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: "{sprint_artifacts}"
|
||||
output_folder: "{implementation_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
|
||||
|
|
|
|||
Loading…
Reference in New Issue