60 lines
3.2 KiB
Markdown
60 lines
3.2 KiB
Markdown
# 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."
|