feat: cross-file reference validator for BMAD source files

[arcaven]

Describe your idea

A CI validator (tools/validate-file-refs.js) that checks cross-file references in src/ content files — agents, workflows, tasks, and steps — and reports broken paths. It follows the same scan/extract/resolve/report pattern as validate-doc-links.js and plugs into the existing validate CI job.

The tool validates {project-root}/_bmad/ references, relative paths (./, ../), exec attributes, <invoke-task> tags, step metadata (thisStepFile/nextStepFile), and Load directives. It also detects absolute path leaks (/Users/, /home/, C:\) in source files.

It runs in warning mode by default (exit 0) so it provides visibility without blocking CI. A --strict flag is available for enforcement when the team is ready.

Why is this needed?

Looking at the project's closed issue history, broken file references and path handling problems account for 59 bugs — 25% of all 236 closed bugs — and over 129 maintainer/user comments. These two categories have no automated prevention today. When files are renamed, moved, or have extensions changed (e.g., the .yaml to .md migration), stale references are left behind and only surface through user reports after release.

The existing docs:validate-links covers documentation links in docs/, and validate:schemas covers YAML structure, but neither checks whether the file paths referenced inside workflow, agent, and task content actually point to real files.

On a test run against the current main, the validator immediately finds 5 broken references matching known open issues #1455/#1324 (missing validate-workflow.xml) and #1212 (wrong .yaml extension, actual file is .md), along with 2 previously unreported broken relative paths in the create-prd workflow steps.

What the data shows

To quantify the value, we replayed the validator against all 26 v6 release tags (alpha.0 through Beta.2):

Metric	Value
Tags analyzed	26
Unique broken refs tracked across history	289
Fixed manually over time without automation	285
Peak breakage in a single release (alpha.23)	208 broken refs
Still broken on current HEAD	5
False positives on current HEAD	0

Key moments where the validator would have made a difference:

• alpha.17 — src/modules/ migration (137 broken refs): When content moved from src/bmm/ to src/modules/bmm/, dozens of agent YAML references became stale. All 137 would have appeared in the build log on that PR, giving the maintainer a complete fix list before merging. Instead, these were found and fixed piecemeal across 5 subsequent releases.

• alpha.23 — peak breakage (208 refs): The bmb/workflows/module/ restructure added ~40 more broken relative refs on top of existing ones. The validator would have flagged every one on the PR itself.

• The workflow.xml task file contains an incorrect file extension reference for the party-mode workflow #1212 — party-mode .yaml vs .md extension: Introduced at alpha.17 (2025-12-16), reported by a user over a month later. The validator catches this the day it's committed.

• Missing validate-workflow.xml referenced in create-story checklist #1455/[BUG] Missing _bmad/core/tasks/validate-workflow.xml breaks create-story validation (latest update of V6.) #1324 — missing validate-workflow.xml: Introduced at Beta.0 (2026-01-26). Would have been caught in the same CI run that shipped the release.

• 2 unreported broken relative paths: step-11-polish.md and step-e-04-complete.md reference sibling directories with ./ instead of ../. No user had reported these — the validator is the first detection.

The pattern is consistent: file reorganizations introduce broken references in bulk, which are then fixed reactively over multiple releases through user reports. Automated detection at the PR level would collapse that feedback loop from weeks/months to the moment the breaking change is proposed.

Non-blocking adoption

The validator is designed for gradual adoption. It adds a step to the existing validate CI job but exits 0 regardless of findings — build results are unaffected. Broken references appear in the build log for visibility without blocking merges.

When the team is ready to enforce, it's a single-line change:

- "validate:refs": "node tools/validate-file-refs.js"
+ "validate:refs": "node tools/validate-file-refs.js --strict"

No existing CI checks, pre-commit hooks, or npm scripts are modified in behavior. The validator is purely additive.

How should it work?

• Scans src/ for .yaml, .md, and .xml files (212 files, 479 references today)
• Maps {project-root}/_bmad/ references to source tree paths (_bmad/core/ → src/core/, _bmad/bmm/ → src/bmm/)
• Checks relative path references resolve from the containing file's directory
• Skips runtime variables ({output_folder}, {timestamp}, {{mustache}}) and install-generated files (_config/, config.yaml)
• Reports broken references with file path, line context, and expected target
• Self-contained: uses only node:fs, node:path, and yaml (already a project dependency)
• Adds validate:refs npm script and a step in the validate job in quality.yaml

PR

Working implementation: #1494

Additional context

The validator's structure follows validate-doc-links.js (371 lines) as a template and ports regex patterns from dependency-resolver.js's parseFileReferences() rather than importing the class directly, keeping it self-contained. The implementation is 430 lines, within the CONTRIBUTING.md guidelines.

Reference patterns validated were cataloged by auditing all 212 source files. The full inventory covers 13 distinct reference patterns including YAML path values, step sequencing metadata, XML invoke-task tags, and markdown Load directives.

[bmadcode]

This issue relates to BMad Builder (BMB) which is maintained in a separate repository.

Please report this issue at: https://github.com/bmad-code-org/bmad-builder/issues/new

If you believe this issue actually belongs in the BMAD-METHOD repository, please let us know and we'll reopen it.

[arcaven]

@bmadcode This is actually for BMAD-METHOD, not BMB — it's a CI tool (and can run locally) that plugs into the existing validate job in .github/workflows/quality.yaml alongside validate-doc-links.js and validate-agent-schema.js. It checks the ~480 cross-file references across src/ and catches issues like #1212 and #1455/#1324 on current main.

The goal is to help maintainers and contributors proactively detect broken file references before they're merged. Based on this repo's closed issue history, that category accounts for ~25% of all reported bugs. Right now those are only found by users post-release.

The current implementation logs warnings in CI output, but if you'd prefer, I can (easily) surface findings directly in PRs — inline annotations on changed files, or a review comment like CodeRabbit — so authors and reviewers see broken references before merge. Happy to adapt the notification method to whatever fits your workflow.

EDIT: It could probably be incorporated into BMB as well, but the PR (#1494) targets this repo specifically.
I've looked at BMB, and I agreee, it would ALSO benefit from this approach, not just in running discovering this class of issues automatically (or even fixing them automatically, if you want) but in other ways. I've detailed a proposal at bmad-code-org/bmad-builder#7 but the first step remains for your consideration, to re-open and review this feature. That being said, I won't be offended if you don't want it.