BMAD-METHOD/src/core/tasks/validate-workflow.md

name	description	standalone
validate-workflow	Validate a target file against a checklist	true

Task: Validate Workflow

Initialization

• Load config from {project-root}/_bmad/core/config.yaml.
• Validate config load before continuing:
  • Verify file exists and is readable.
  • Parse YAML and fail fast with explicit error if parsing fails.
  • Require user_name; if missing, abort initialization with descriptive error.
  • Apply explicit defaults when optional keys are absent:
    • communication_language = "English"
    • document_output_language = "English"
  • Log resolved values and config source path.

Purpose

Execute a validation checklist against a target file and report findings clearly and consistently.

Steps

1. Load checklist

   • Use the checklist path provided by the calling workflow (e.g., its validation property).
   • If not provided, ask the user for the checklist path.

2. Load target file

   • Infer candidate target path in this order:
     • Explicit keys in workflow/checklist inputs: file, path, target, filePath
     • Path-like tokens in checklist items
     • First matching path from glob patterns supplied by checklist/input
   • Normalize all candidate paths relative to repo root and resolve ./...

• Validate candidate existence and expected file type (.md, .yaml, .yml, .json, or checklist-defined extension).
• If multiple valid candidates remain, prefer explicit key fields over inferred tokens.
• If no valid candidate is found, prompt user with schema example:
  • Please provide the exact file path (relative to repo root), e.g. ./workflows/ci.yml
• Validate user-supplied path before proceeding.

3. Run the checklist

   • Read the checklist fully.
   • Apply each item systematically to the target file.
   • Record pass/fail and capture specific evidence for any issues.

4. Report findings

   • Summarize issues with clear labels (e.g., CRITICAL/HIGH/MEDIUM/LOW when applicable).
   • Provide actionable fixes for each issue.

5. Edits (if applicable)

   • If checklist requires edits/auto-fixes, follow safe-edit protocol:
     • Ask for confirmation before editing.
     • Create backup snapshot of target file before changes.
     • Use deterministic backup location: {project-root}/.bmad-tmp/validate-workflow/.
     • Name backup as {target-file-name}.{timestamp}.bak and diff as {target-file-name}.{timestamp}.diff.
     • If temp backup directory cannot be created, fall back to adjacent backup file {target-file}.bak.
     • Generate reversible diff preview and show it to user.
     • Apply edits only after user approval.
     • Run syntax/validation checks against edited file.
     • If validation fails or user cancels, rollback from backup and report rollback status.
     • Record full backup and diff paths in task output.
     • Support retain_artifacts flag (default false) to keep backup/diff artifacts when requested.

6. Finalize

   • Confirm completion and provide the final validation summary.
   • If edits succeeded and retain_artifacts is false, delete backup/diff artifacts and report cleanup status.
   • If edits failed or rollback occurred, preserve backup/diff artifacts and report rollback path explicitly.