bmad-os-audit-file-refs

name	bmad-os-audit-file-refs
description	Audit BMAD source files for file-reference convention violations using parallel Haiku subagents. Use when users requests an "audit file references" for a skill, workflow or task.

audit-file-refs

Audit new-format BMAD source files for file-reference convention violations using parallel Haiku subagents.

Convention

In new-format BMAD workflow and task files (src/bmm/, src/core/, src/utility/), every file path reference must use one of these valid forms:

• {project-root}/_bmad/path/to/file.ext — canonical form, always correct
• {installed_path}/relative/path — valid in new-format step files (always defined by workflow.md before any step is reached)
• Template/runtime variables: {nextStepFile}, {workflowFile}, {{mustache}}, {output_folder}, {communication_language}, etc. — skip these, they are substituted at runtime

Flag any reference that uses:

• ./step-NN.md or ../something.md — relative paths
• step-NN.md — bare filename with no path prefix
• steps/step-NN.md — bare steps-relative path (missing {project-root}/_bmad/... prefix)
• `_bmad/core/tasks/help.md` — bare _bmad/ path (missing {project-root}/)
• /Users/..., /home/..., C:\... — absolute system paths

References inside fenced code blocks ( ```) are examples — skip them.

Old-format files in src/bmm/workflows/4-implementation/ use {installed_path} by design within the XML calling chain — exclude that directory entirely.

Steps

1. Run this command to get the file list:

   find src/bmm src/core src/utility -type f \( -name "*.md" -o -name "*.yaml" \) | grep -v "4-implementation" | sort
   

2. Divide the resulting file paths into batches of roughly 20 files each.

3. For each batch, spawn a subagent (subagent_type: "Explore", model: "haiku") with this prompt (fill in the actual file paths):

   Read each of these files (use the Read tool on each): [list the file paths from this batch]

   For each file, identify every line that contains a file path reference that violates the convention described below. Skip references inside fenced code blocks. Skip template variables (anything containing { that isn't {project-root} or {installed_path}).

   Valid references: {project-root}/_bmad/..., {installed_path}/..., template variables. Flag: bare filenames (step-NN.md), ./ or ../ relative paths, bare steps/ paths, bare _bmad/ paths (without {project-root}/), absolute system paths.

   Return findings as a list: path/to/file.md:LINE_NUMBER | VIOLATION_TYPE | offending text

   If a file has no violations, include it as: path/to/file.md | clean

   End your response with a single line: FILES CHECKED: N where N is the exact number of files you read.

4. Collect all findings from all subagents.

5. Self-check before reporting: Count the total number of files returned by the find command. Sum the FILES CHECKED: N values across all subagent responses. If the totals do not match, identify which files are missing and re-run subagents for those files before proceeding. Do not produce the final report until all files are accounted for.

6. Output a final report:

   • Group findings by violation type
   • List each finding as file:line — offending text
   • Show total count of violations and number of affected files
   • If nothing found, say "All files conform to the convention."