fix: standardize all relative step file refs to {project-root}/_bmad/ paths

[alexeyv]

Summary

Converts all non-conforming relative file references in new-format workflows to full {project-root}/_bmad/... paths. Addresses three of the four remaining categories from #1718.

Categories fixed

Category	Count	Example → Result
Bare `_bmad/...` refs	9	`_bmad/core/tasks/help.md` → `{project-root}/_bmad/core/tasks/help.md`
`./step-NN.md` sibling refs	~82	`./step-02.md` → `{project-root}/_bmad/.../steps/step-02.md`
Bare `step-NN.md` refs	~13	`step-04.md` → `{project-root}/_bmad/.../steps/step-04.md`
`steps/step-NN.md` from workflow.md	~6	`steps/step-01.md` → `{project-root}/_bmad/.../steps/step-01.md`

Files changed

• src/core/tasks/help.md
• 68 files across src/bmm/workflows/ (step files and workflow.md files in all new-format workflows)

Test plan

• All existing tests pass (npm test)
• Zero bare relative step refs remaining (verified with grep)

Closes #1718 (partial — all relative ref categories; installer rewriting and docs items remain)

[augmentcode]

🤖 Augment PR Summary

Summary: This PR standardizes new-format workflow step references to absolute {project-root}/_bmad/… paths so they resolve consistently regardless of the current working directory.

Changes:

• Replaced relative step references (e.g., ./step-NN.md, step-NN.md, and steps/step-NN.md) with full {project-root}/_bmad/bmm/workflows/… paths across ~68 workflow/step files.
• Converted “bare” _bmad/… references (notably to core/tasks/help.md) to include the {project-root} prefix.
• Updated various in-step instructions/examples ("Load…", "Read fully and follow…") to match the new absolute paths.
• Updated src/core/tasks/help.md to load the help catalog from {project-root}/_bmad/_config/bmad-help.csv and to describe scanning configs under {project-root}/_bmad/.

Technical Notes: Addresses multiple remaining relative-reference categories tracked in #1718 by making step resolution deterministic and path-independent.

_{🤖 Was this summary useful? React with 👍 or 👎}

[augmentcode]

Review completed. 3 suggestions posted.

Comment augment review to trigger a new review at any time.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR systematically converts all relative file path references in BMAD's new-format workflows to absolute {project-root}/_bmad/... paths across 77 step and workflow files. Changes update navigation directives, frontmatter fields, and inline path strings to enforce the standardized path convention.

Changes

Cohort / File(s)	Summary
Create Product Brief workflow src/bmm/workflows/1-analysis/create-product-brief/steps/step-0{1,1b,2,3,4,5,6}-*.md	Updated nextStepFile frontmatter and Load/NEXT STEP directives from relative paths (./step-NN.md) to {project-root}/_bmad/bmm/workflows/1-analysis/create-product-brief/steps/step-NN.md format.
Research domain/market/technical workflows src/bmm/workflows/1-analysis/research/{domain,market,technical}-steps/step-0{1..6}-*.md	Normalized all step file references in Load directives, NEXT STEP instructions, and continuation messages from relative paths to fully-qualified {project-root}/_bmad/... paths.
Create PRD workflow (steps-c) src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-0{1b,2..12}-*.md, src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-13-*.md	Updated nextStepFile references and path directives to use {project-root}/_bmad/... format; also updated completion message in validation step to include {project-root} prefix.
Create PRD workflow meta src/bmm/workflows/2-plan-workflows/create-prd/...	No changes to this cohort.
Create UX Design workflow src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-0{1,1b,2..14}-*.md, src/bmm/workflows/2-plan-workflows/create-ux-design/workflow.md	Converted all step-to-step navigation paths from relative to {project-root}/_bmad/... format; updated workflow.md initialization instruction to use absolute path.
Check Implementation Readiness workflow src/bmm/workflows/3-solutioning/check-implementation-readiness/{workflow.md,steps/step-06-*.md}	Updated workflow initialization path and step-06 help reference to use {project-root}/_bmad/... format.
Create Architecture workflow src/bmm/workflows/3-solutioning/create-architecture/{workflow.md,steps/step-0{1,1b,2..8}-*.md}	Converted all step navigation and continuation paths to {project-root}/_bmad/... format; expanded step-01b continuation guidance with enumerated valid step file list.
Create Epics and Stories workflow src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-04-*.md	Updated help reference in completion message to use {project-root}/_bmad/... format.
Quick Flow workflows (quick-dev/quick-spec) src/bmm/workflows/bmad-quick-flow/{quick-dev,quick-spec}/**/*.md	Normalized all step navigation references and workflow initialization paths to {project-root}/_bmad/... format; quick-dev step-01 updated multiple NEXT directives for different mode paths.
Generate Project Context workflow src/bmm/workflows/generate-project-context/{workflow.md,steps/step-0{1,2}-*.md}	Updated workflow and step file path references to use {project-root}/_bmad/... format.
Core help task src/core/tasks/help.md	Updated two display strings (catalog load path and output location reference) to use {project-root}/_bmad/... prefix instead of bare _bmad/ path.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• PR #1494 — Adds file reference validator (tools/validate-file-refs.js) that detects non-conforming path formats; this PR supplies the migration targets that validator enforces.
• PR #1491 — Restores/adds generate-project-context workflow files; this PR updates those same files to use standardized {project-root} paths.
• PR #1675 — Modifies create-prd steps-c step-02/02b/02c file chaining; this PR updates the same files' path references to standardized format.

Suggested reviewers

• bmadcode

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: standardizing relative step file references to {project-root}/_bmad/ paths across workflows.
Description check	✅ Passed	The description is well-related to the changeset, providing clear categories of fixes, file counts, and test verification for the path standardization work.
Linked Issues check	✅ Passed	The PR successfully addresses the primary objectives from #1718 by converting three of four remaining categories of non-conforming relative references (bare _bmad/, ./step-NN.md, bare step-NN.md, and steps/step-NN.md refs) to standardized {project-root}/_bmad/ paths across 69 files.
Out of Scope Changes check	✅ Passed	All changes are in-scope: 69 files across src/core/tasks/help.md and src/bmm/workflows/ were modified to standardize relative file references to {project-root}/_bmad/ paths, directly addressing #1718 item 2 with no unrelated alterations detected.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 10

Note

Due to the large number of review comments, Critical, Major severity comments were prioritized as inline comments.

[bmadcode]

nice, thank you !!