Bmad Os Audit File Refs

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."