From 6ff29d470708516b272ab33a3e79db9f9bd85e13 Mon Sep 17 00:00:00 2001 From: Alex Verkhovsky Date: Sat, 14 Mar 2026 15:18:55 -0600 Subject: [PATCH 1/6] feat(tools): add inference-based skill validator LLM-readable validation prompt covering 19 rules across 6 categories: SKILL.md frontmatter, workflow.md hygiene, path resolution, step file structure, sequential execution, and file reference integrity. Designed to catch anti-patterns from mechanical workflow-to-skill conversions (installed_path abuse, intra-skill path variables, metadata in wrong frontmatter). Co-Authored-By: Claude Opus 4.6 (1M context) --- tools/skill-validator.md | 277 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 277 insertions(+) create mode 100644 tools/skill-validator.md diff --git a/tools/skill-validator.md b/tools/skill-validator.md new file mode 100644 index 000000000..184b85da4 --- /dev/null +++ b/tools/skill-validator.md @@ -0,0 +1,277 @@ +# Skill Validator — Inference-Based + +An LLM-readable validation prompt for skills following the Agent Skills open standard. + +## How to Use + +1. You are given a **skill directory path** to validate. +2. Read every file in the skill directory recursively. +3. Apply every rule in the catalog below to every applicable file. +4. Produce a findings report using the report template at the end. + +If no findings are generated, the skill passes validation. + +--- + +## Definitions + +- **Skill directory**: the folder containing `SKILL.md` and all supporting files. +- **Internal reference**: a file path from one file in the skill to another file in the same skill. +- **External reference**: a file path from a skill file to a file outside the skill directory. +- **Originating file**: the file that contains the reference (path resolution is relative to this file's location). +- **Config variable**: a name-value pair whose value comes from the project config file (e.g., `planning_artifacts`, `implementation_artifacts`, `communication_language`). +- **Runtime variable**: a name-value pair whose value is set during workflow execution (e.g., `spec_file`, `date`, `status`). +- **Intra-skill path variable**: a frontmatter variable whose value is a path to another file within the same skill — this is an anti-pattern. + +--- + +## Rule Catalog + +### SKILL-01 — SKILL.md Must Exist + +- **Severity:** CRITICAL +- **Applies to:** skill directory +- **Rule:** The skill directory must contain a file named `SKILL.md` (exact case). +- **Detection:** Check for the file's existence. +- **Fix:** Create `SKILL.md` as the skill entrypoint. + +### SKILL-02 — SKILL.md Must Have `name` in Frontmatter + +- **Severity:** CRITICAL +- **Applies to:** `SKILL.md` +- **Rule:** The YAML frontmatter must contain a `name` field. +- **Detection:** Parse the `---` delimited frontmatter block and check for `name:`. +- **Fix:** Add `name: ` to the frontmatter. + +### SKILL-03 — SKILL.md Must Have `description` in Frontmatter + +- **Severity:** CRITICAL +- **Applies to:** `SKILL.md` +- **Rule:** The YAML frontmatter must contain a `description` field. +- **Detection:** Parse the `---` delimited frontmatter block and check for `description:`. +- **Fix:** Add `description: ''` to the frontmatter. + +### SKILL-04 — `name` Format + +- **Severity:** HIGH +- **Applies to:** `SKILL.md` +- **Rule:** The `name` value must use only lowercase letters, numbers, and hyphens. Max 64 characters. Must not contain "anthropic" or "claude". +- **Detection:** Regex test: `^[a-z0-9][a-z0-9-]{0,62}[a-z0-9]$`. String search for forbidden substrings. +- **Fix:** Rename to comply with the format. + +### SKILL-05 — `description` Quality + +- **Severity:** MEDIUM +- **Applies to:** `SKILL.md` +- **Rule:** The `description` must state both what the skill does AND when to use it. Max 1024 characters. +- **Detection:** Check length. Look for trigger phrases like "Use when" or "Use if" — their absence suggests the description only says _what_ but not _when_. +- **Fix:** Append a "Use when..." clause to the description. + +--- + +### WF-01 — workflow.md Must NOT Have `name` in Frontmatter + +- **Severity:** HIGH +- **Applies to:** `workflow.md` (if it exists) +- **Rule:** The `name` field belongs only in `SKILL.md`. If `workflow.md` has YAML frontmatter, it must not contain `name:`. +- **Detection:** Parse frontmatter and check for `name:` key. +- **Fix:** Remove the `name:` line from workflow.md frontmatter. + +### WF-02 — workflow.md Must NOT Have `description` in Frontmatter + +- **Severity:** HIGH +- **Applies to:** `workflow.md` (if it exists) +- **Rule:** The `description` field belongs only in `SKILL.md`. If `workflow.md` has YAML frontmatter, it must not contain `description:`. +- **Detection:** Parse frontmatter and check for `description:` key. +- **Fix:** Remove the `description:` line from workflow.md frontmatter. + +### WF-03 — workflow.md Frontmatter Variables Must Be Config or Runtime Only + +- **Severity:** HIGH +- **Applies to:** `workflow.md` frontmatter +- **Rule:** Every variable defined in workflow.md frontmatter must be either: + - A config variable (value references `{project-root}` or a config-derived variable like `{planning_artifacts}`) + - A runtime variable (value is empty, a placeholder, or set during execution) + - A legitimate external path expression + + It must NOT be a path to a file within the skill directory. +- **Detection:** For each frontmatter variable, check if its value resolves to a file inside the skill (e.g., starts with `./`, `{installed_path}`, or is a bare relative path to a sibling file). If so, it is an intra-skill path variable. +- **Fix:** Remove the variable. Use a hardcoded relative path inline where the file is referenced. + +--- + +### PATH-01 — Internal References Must Be Relative From Originating File + +- **Severity:** CRITICAL +- **Applies to:** all files in the skill +- **Rule:** Any reference from one file in the skill to another file in the same skill must be a relative path resolved from the directory of the originating file. Use `./` prefix for siblings or children, `../` for parent traversal. Bare relative filenames in markdown links (e.g., `[text](sibling.md)`) are also acceptable. +- **Detection:** Scan for file path references (in markdown links, frontmatter values, inline backtick paths, and prose instructions like "Read fully and follow"). Verify each internal reference uses relative notation (`./`, `../`, or bare filename). Always resolve the path from the originating file's directory — a reference to `./steps/step-01.md` from a file already inside `steps/` would resolve to `steps/steps/step-01.md`, which is wrong. +- **Examples:** + - CORRECT: `./steps/step-01-init.md` (from workflow.md at skill root to a step) + - CORRECT: `./template.md` (from workflow.md to a sibling) + - CORRECT: `../template.md` (from steps/step-01.md to a skill-root file) + - CORRECT: `[workflow.md](workflow.md)` (markdown link to sibling — bare relative) + - CORRECT: `./step-02-plan.md` (from steps/step-01.md to a sibling step) + - WRONG: `./steps/step-02-plan.md` (from a file already inside steps/ — resolves to steps/steps/) + - WRONG: `{installed_path}/template.md` + - WRONG: `{project-root}/.claude/skills/my-skill/template.md` + - WRONG: `/Users/someone/.claude/skills/my-skill/steps/step-01.md` + - WRONG: `~/.claude/skills/my-skill/file.md` + +### PATH-02 — No `installed_path` Variable + +- **Severity:** HIGH +- **Applies to:** all files in the skill +- **Rule:** The `installed_path` variable is an anti-pattern from the pre-skill workflow era. It must not be defined in any frontmatter, and `{installed_path}` must not appear anywhere in any file. +- **Detection:** Search all files for: + - Frontmatter key `installed_path:` + - String `{installed_path}` anywhere in content + - Markdown/prose assigning `installed_path` (e.g., `` `installed_path` = `.` ``) +- **Fix:** Remove all `installed_path` definitions. Replace every `{installed_path}/path` with `./path` (relative from the file that contains the reference). If the reference is in a step file and points to a skill-root file, use `../path` instead. + +### PATH-03 — External References Must Use `{project-root}` or Config Variables + +- **Severity:** HIGH +- **Applies to:** all files in the skill +- **Rule:** References to files outside the skill directory must use `{project-root}/...` or a config-derived variable path (e.g., `{planning_artifacts}/...`, `{implementation_artifacts}/...`). +- **Detection:** Identify file references that point outside the skill. Verify they start with `{project-root}` or a known config variable. Flag absolute paths, home-relative paths (`~/`), or bare paths that resolve outside the skill. +- **Fix:** Replace with `{project-root}/...` or the appropriate config variable. + +### PATH-04 — No Intra-Skill Path Variables + +- **Severity:** MEDIUM +- **Applies to:** all files (frontmatter AND body content) +- **Rule:** Variables must not store paths to files within the same skill. These paths should be hardcoded as relative paths inline where used. This applies to YAML frontmatter variables AND markdown body variable assignments (e.g., `` `template` = `./template.md` `` under a `### Paths` section). +- **Detection:** For each variable with a path-like value — whether defined in frontmatter or in body text — determine if the target is inside the skill directory. Indicators: value starts with `./`, `../`, `{installed_path}`, or is a bare filename of a file that exists in the skill. Exclude variables whose values are prefixed with a config variable like `{planning_artifacts}`, `{implementation_artifacts}`, `{project-root}`, or other config-derived paths — these are external references and are legitimate. +- **Fix:** Remove the variable. Replace each `{variable_name}` usage with the direct relative path. +- **Exception:** If a path variable is used in 4+ locations across multiple files and the path is non-trivial, a variable MAY be acceptable. Flag it as LOW instead and note the exception. + +--- + +### STEP-01 — Step File Naming + +- **Severity:** MEDIUM +- **Applies to:** files in `steps/` directory +- **Rule:** Step files must be named `step-NN-description.md` where NN is a zero-padded two-digit number. An optional single-letter variant suffix is allowed for branching steps (e.g., `step-01b-continue.md`). +- **Detection:** Regex: `^step-\d{2}[a-z]?-[a-z0-9-]+\.md$` +- **Fix:** Rename to match the pattern. + +### STEP-02 — Step Must Have a Goal Section + +- **Severity:** HIGH +- **Applies to:** step files +- **Rule:** Each step must clearly state its goal. Look for a heading like `## YOUR TASK`, `## STEP GOAL`, `## INSTRUCTIONS`, `## INITIALIZATION`, `## EXECUTION`, `# Step N:`, or a frontmatter `goal:` field. +- **Detection:** Scan for goal-indicating headings (including `# Step N: Title` as a top-level heading that names the step's purpose) or frontmatter. +- **Fix:** Add a clear goal section. + +### STEP-03 — Step Must Reference Next Step + +- **Severity:** MEDIUM +- **Applies to:** step files (except the final step) +- **Rule:** Each non-terminal step must contain a reference to the next step file for sequential execution. +- **Detection:** Look for `## NEXT` section or inline reference to a next step file. Remember to resolve the reference from the originating file's directory (PATH-01 applies here too). +- **Fix:** Add a `## NEXT` section with the relative path to the next step. +- **Note:** A terminal step is one that has no next-step reference and either contains completion/finalization language or is the highest-numbered step. If a workflow branches, there may be multiple terminal steps. + +### STEP-04 — Halt Before Menu + +- **Severity:** HIGH +- **Applies to:** step files +- **Rule:** Any step that presents a user menu (e.g., `[C] Continue`, `[A] Approve`, `[S] Split`) must explicitly HALT and wait for user response before proceeding. +- **Detection:** Find menu patterns (bracketed letter options). Check that text within the same section (under the same heading) includes "HALT", "wait", "stop", "FORBIDDEN to proceed", or equivalent. +- **Fix:** Add an explicit HALT instruction before or after the menu. + +### STEP-05 — No Forward Loading + +- **Severity:** HIGH +- **Applies to:** step files +- **Rule:** A step must not load or read future step files until the current step is complete. Just-in-time loading only. +- **Detection:** Look for instructions to read multiple step files simultaneously, or unconditional references to step files with higher numbers than the current step. Exempt locations: `## NEXT` sections, navigation/dispatch sections that list valid resumption targets, and conditional routing branches. +- **Fix:** Remove premature step loading. Ensure only the current step is active. + +### STEP-06 — Step File Frontmatter: No `name` or `description` + +- **Severity:** MEDIUM +- **Applies to:** step files +- **Rule:** Step files should not have `name:` or `description:` in their YAML frontmatter. These are metadata noise — the step's purpose is conveyed by its goal section and filename. +- **Detection:** Parse step file frontmatter for `name:` or `description:` keys. +- **Fix:** Remove `name:` and `description:` from step file frontmatter. + +### STEP-07 — Step Count + +- **Severity:** LOW +- **Applies to:** workflow as a whole +- **Rule:** A sharded workflow should have between 2 and 10 step files. More than 10 risks LLM context degradation. +- **Detection:** Count files matching `step-*.md` in the `steps/` directory. +- **Fix:** Consider consolidating steps if over 10. + +--- + +### SEQ-01 — No Skip Instructions + +- **Severity:** HIGH +- **Applies to:** all files +- **Rule:** No file should instruct the agent to skip steps or optimize step order. Sequential execution is mandatory. +- **Detection:** Scan for phrases like "skip to step", "jump to step", "skip ahead", "optimize the order", "you may skip". Exclude negation context (e.g., "do NOT skip steps", "NEVER skip") — these are enforcement instructions, not skip instructions. +- **Exception:** Conditional routing (e.g., "if X, go to step N; otherwise step M") is valid workflow branching, not skipping. + +### SEQ-02 — No Time Estimates + +- **Severity:** LOW +- **Applies to:** all files +- **Rule:** Workflow files should not include time estimates. AI execution speed varies too much for estimates to be meaningful. +- **Detection:** Scan for patterns like "takes X minutes", "~N min", "estimated time", "ETA". +- **Fix:** Remove time estimates. + +--- + +### REF-01 — File References Must Resolve + +- **Severity:** HIGH +- **Applies to:** all files +- **Rule:** All file path references within the skill (markdown links, backtick paths, frontmatter values) should point to files that plausibly exist. +- **Detection:** For internal references, verify the target file exists in the skill directory. For external references using config variables, verify the path structure is plausible (you cannot resolve config variables, but you can check that the path after the variable looks reasonable — e.g., `{planning_artifacts}/*.md` is plausible, `{planning_artifacts}/../../etc/passwd` is not). +- **Fix:** Correct the path or remove the dead reference. + +--- + +## Report Template + +When reporting findings, use this format: + +```markdown +# Skill Validation Report: {skill-name} + +**Directory:** {path} +**Date:** {date} +**Files scanned:** {count} + +## Summary + +| Severity | Count | +|----------|-------| +| CRITICAL | N | +| HIGH | N | +| MEDIUM | N | +| LOW | N | + +## Findings + +### {RULE-ID} — {Rule Title} + +- **Severity:** {severity} +- **File:** `{relative-path-within-skill}` +- **Line:** {line number or range, if identifiable} +- **Detail:** {what was found} +- **Fix:** {specific fix for this instance} + +--- + +(repeat for each finding, grouped by rule ID) + +## Passed Rules + +(list rule IDs that produced no findings) +``` + +If zero findings: report "All {N} rules passed. No findings." and list all passed rule IDs. From b93d0087db95fc709f7e0f3d9a0eeec4368b8bad Mon Sep 17 00:00:00 2001 From: Alex Verkhovsky Date: Sat, 14 Mar 2026 15:49:07 -0600 Subject: [PATCH 2/6] fix(skill): clean up bmad-create-product-brief validation findings Remove name/description from step frontmatter (STEP-06), inline intra-skill path variables (PATH-04), prefix bare external path with {project-root} (PATH-03), and normalize template placeholders to double-curly convention (REF-01). Co-Authored-By: Claude Opus 4.6 (1M context) --- .../product-brief.template.md | 4 ++-- .../steps/step-01-init.md | 15 ++++----------- .../steps/step-01b-continue.md | 3 --- .../steps/step-02-vision.md | 8 ++------ .../steps/step-03-users.md | 8 ++------ .../steps/step-04-metrics.md | 8 ++------ .../steps/step-05-scope.md | 8 ++------ .../steps/step-06-complete.md | 3 --- 8 files changed, 14 insertions(+), 43 deletions(-) diff --git a/src/bmm/workflows/1-analysis/bmad-create-product-brief/product-brief.template.md b/src/bmm/workflows/1-analysis/bmad-create-product-brief/product-brief.template.md index d41d5620c..9f6189c2c 100644 --- a/src/bmm/workflows/1-analysis/bmad-create-product-brief/product-brief.template.md +++ b/src/bmm/workflows/1-analysis/bmad-create-product-brief/product-brief.template.md @@ -1,8 +1,8 @@ --- stepsCompleted: [] inputDocuments: [] -date: { system-date } -author: { user } +date: {{system-date}} +author: {{user_name}} --- # Product Brief: {{project_name}} diff --git a/src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-01-init.md b/src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-01-init.md index 496180933..479811f1b 100644 --- a/src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-01-init.md +++ b/src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-01-init.md @@ -1,13 +1,6 @@ --- -name: 'step-01-init' -description: 'Initialize the product brief workflow by detecting continuation state and setting up the document' - # File References -nextStepFile: './step-02-vision.md' outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md' - -# Template References -productBriefTemplate: '../product-brief.template.md' --- # Step 1: Product Brief Initialization @@ -88,7 +81,7 @@ load context documents using smart discovery. Documents can be in the following - {planning_artifacts}/** - {output_folder}/** - {product_knowledge}/** -- docs/** +- {project-root}/docs/** Also - when searching - documents can be a single markdown file, or a folder with an index and multiple files. For Example, if searching for `*foo*.md` and not found, also search for a folder called *foo*/index.md (which indicates sharded content) @@ -112,7 +105,7 @@ Try to discover the following: **Document Setup:** -- Copy the template from `{productBriefTemplate}` to `{outputFile}`, and update the frontmatter fields +- Copy the template from `../product-brief.template.md` to `{outputFile}`, and update the frontmatter fields #### C. Present Initialization Results @@ -141,7 +134,7 @@ Display: "**Proceeding to product vision discovery...**" #### Menu Handling Logic: -- After setup report is presented, without delay, read fully and follow: {nextStepFile} +- After setup report is presented, without delay, read fully and follow: ./step-02-vision.md #### EXECUTION RULES: @@ -150,7 +143,7 @@ Display: "**Proceeding to product vision discovery...**" ## CRITICAL STEP COMPLETION NOTE -ONLY WHEN [setup completion is achieved and frontmatter properly updated], will you then read fully and follow: `{nextStepFile}` to begin product vision discovery. +ONLY WHEN [setup completion is achieved and frontmatter properly updated], will you then read fully and follow: `./step-02-vision.md` to begin product vision discovery. --- diff --git a/src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-01b-continue.md b/src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-01b-continue.md index 99b2495fe..bd2af1be6 100644 --- a/src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-01b-continue.md +++ b/src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-01b-continue.md @@ -1,7 +1,4 @@ --- -name: 'step-01b-continue' -description: 'Resume the product brief workflow from where it was left off, ensuring smooth continuation' - # File References outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md' --- diff --git a/src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-02-vision.md b/src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-02-vision.md index dfc263814..4729aaf3d 100644 --- a/src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-02-vision.md +++ b/src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-02-vision.md @@ -1,9 +1,5 @@ --- -name: 'step-02-vision' -description: 'Discover and define the core product vision, problem statement, and unique value proposition' - # File References -nextStepFile: './step-03-users.md' outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md' # Task References @@ -159,7 +155,7 @@ Prepare the following structure for document append: - IF A: Read fully and follow: {advancedElicitationTask} with current vision content to dive deeper and refine - IF P: Read fully and follow: {partyModeWorkflow} to bring different perspectives to positioning and differentiation -- IF C: Save content to {outputFile}, update frontmatter with stepsCompleted: [1, 2], then read fully and follow: {nextStepFile} +- IF C: Save content to {outputFile}, update frontmatter with stepsCompleted: [1, 2], then read fully and follow: ./step-03-users.md - IF Any other comments or queries: help user respond then [Redisplay Menu Options](#7-present-menu-options) #### EXECUTION RULES: @@ -171,7 +167,7 @@ Prepare the following structure for document append: ## CRITICAL STEP COMPLETION NOTE -ONLY WHEN [C continue option] is selected and [vision content finalized and saved to document with frontmatter updated], will you then read fully and follow: `{nextStepFile}` to begin target user discovery. +ONLY WHEN [C continue option] is selected and [vision content finalized and saved to document with frontmatter updated], will you then read fully and follow: `./step-03-users.md` to begin target user discovery. --- diff --git a/src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-03-users.md b/src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-03-users.md index 3125cad69..2c4f8f71e 100644 --- a/src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-03-users.md +++ b/src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-03-users.md @@ -1,9 +1,5 @@ --- -name: 'step-03-users' -description: 'Define target users with rich personas and map their key interactions with the product' - # File References -nextStepFile: './step-04-metrics.md' outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md' # Task References @@ -162,7 +158,7 @@ Prepare the following structure for document append: - IF A: Read fully and follow: {advancedElicitationTask} with current user content to dive deeper into personas and journeys - IF P: Read fully and follow: {partyModeWorkflow} to bring different perspectives to validate user understanding -- IF C: Save content to {outputFile}, update frontmatter with stepsCompleted: [1, 2, 3], then read fully and follow: {nextStepFile} +- IF C: Save content to {outputFile}, update frontmatter with stepsCompleted: [1, 2, 3], then read fully and follow: ./step-04-metrics.md - IF Any other comments or queries: help user respond then [Redisplay Menu Options](#6-present-menu-options) #### EXECUTION RULES: @@ -174,7 +170,7 @@ Prepare the following structure for document append: ## CRITICAL STEP COMPLETION NOTE -ONLY WHEN [C continue option] is selected and [user personas finalized and saved to document with frontmatter updated], will you then read fully and follow: `{nextStepFile}` to begin success metrics definition. +ONLY WHEN [C continue option] is selected and [user personas finalized and saved to document with frontmatter updated], will you then read fully and follow: `./step-04-metrics.md` to begin success metrics definition. --- diff --git a/src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-04-metrics.md b/src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-04-metrics.md index 30b32b9df..55c29cf0e 100644 --- a/src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-04-metrics.md +++ b/src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-04-metrics.md @@ -1,9 +1,5 @@ --- -name: 'step-04-metrics' -description: 'Define comprehensive success metrics that include user success, business objectives, and key performance indicators' - # File References -nextStepFile: './step-05-scope.md' outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md' # Task References @@ -165,7 +161,7 @@ Prepare the following structure for document append: - IF A: Read fully and follow: {advancedElicitationTask} with current metrics content to dive deeper into success metric insights - IF P: Read fully and follow: {partyModeWorkflow} to bring different perspectives to validate comprehensive metrics -- IF C: Save content to {outputFile}, update frontmatter with stepsCompleted: [1, 2, 3, 4], then read fully and follow: {nextStepFile} +- IF C: Save content to {outputFile}, update frontmatter with stepsCompleted: [1, 2, 3, 4], then read fully and follow: ./step-05-scope.md - IF Any other comments or queries: help user respond then [Redisplay Menu Options](#7-present-menu-options) #### EXECUTION RULES: @@ -177,7 +173,7 @@ Prepare the following structure for document append: ## CRITICAL STEP COMPLETION NOTE -ONLY WHEN [C continue option] is selected and [success metrics finalized and saved to document with frontmatter updated], will you then read fully and follow: `{nextStepFile}` to begin MVP scope definition. +ONLY WHEN [C continue option] is selected and [success metrics finalized and saved to document with frontmatter updated], will you then read fully and follow: `./step-05-scope.md` to begin MVP scope definition. --- diff --git a/src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-05-scope.md b/src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-05-scope.md index 9073f76dd..c8b5d6115 100644 --- a/src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-05-scope.md +++ b/src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-05-scope.md @@ -1,9 +1,5 @@ --- -name: 'step-05-scope' -description: 'Define MVP scope with clear boundaries and outline future vision while managing scope creep' - # File References -nextStepFile: './step-06-complete.md' outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md' # Task References @@ -179,7 +175,7 @@ Prepare the following structure for document append: - IF A: Read fully and follow: {advancedElicitationTask} with current scope content to optimize scope definition - IF P: Read fully and follow: {partyModeWorkflow} to bring different perspectives to validate MVP scope -- IF C: Save content to {outputFile}, update frontmatter with stepsCompleted: [1, 2, 3, 4, 5], then read fully and follow: {nextStepFile} +- IF C: Save content to {outputFile}, update frontmatter with stepsCompleted: [1, 2, 3, 4, 5], then read fully and follow: ./step-06-complete.md - IF Any other comments or queries: help user respond then [Redisplay Menu Options](#7-present-menu-options) #### EXECUTION RULES: @@ -191,7 +187,7 @@ Prepare the following structure for document append: ## CRITICAL STEP COMPLETION NOTE -ONLY WHEN [C continue option] is selected and [MVP scope finalized and saved to document with frontmatter updated], will you then read fully and follow: `{nextStepFile}` to complete the product brief workflow. +ONLY WHEN [C continue option] is selected and [MVP scope finalized and saved to document with frontmatter updated], will you then read fully and follow: `./step-06-complete.md` to complete the product brief workflow. --- diff --git a/src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-06-complete.md b/src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-06-complete.md index 7363f7c95..f1f5c302c 100644 --- a/src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-06-complete.md +++ b/src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-06-complete.md @@ -1,7 +1,4 @@ --- -name: 'step-06-complete' -description: 'Complete the product brief workflow, update status files, and suggest next steps for the project' - # File References outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md' --- From f4084ea1999a10672809e17a372fd46467a6932c Mon Sep 17 00:00:00 2001 From: Alex Verkhovsky Date: Sat, 14 Mar 2026 15:49:10 -0600 Subject: [PATCH 3/6] feat(tools): add SKILL-05 name-matches-dir and REF-01 variable-defined rules MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit SKILL-05 checks that SKILL.md name matches the directory name. REF-01 checks that every {variable} traces to frontmatter, config, or runtime — exempts {{double-curly}} template placeholders. Co-Authored-By: Claude Opus 4.6 (1M context) --- tools/skill-validator.md | 27 +++++++++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/tools/skill-validator.md b/tools/skill-validator.md index 184b85da4..a3327cea1 100644 --- a/tools/skill-validator.md +++ b/tools/skill-validator.md @@ -59,7 +59,15 @@ If no findings are generated, the skill passes validation. - **Detection:** Regex test: `^[a-z0-9][a-z0-9-]{0,62}[a-z0-9]$`. String search for forbidden substrings. - **Fix:** Rename to comply with the format. -### SKILL-05 — `description` Quality +### SKILL-05 — `name` Must Match Directory Name + +- **Severity:** HIGH +- **Applies to:** `SKILL.md` +- **Rule:** The `name` value in SKILL.md frontmatter must exactly match the skill directory name. The directory name is the canonical identifier used by installers, manifests, and `skill:` references throughout the project. +- **Detection:** Compare the `name:` frontmatter value against the basename of the skill directory (i.e., the immediate parent directory of `SKILL.md`). +- **Fix:** Change the `name:` value to match the directory name, or rename the directory to match — prefer changing `name:` unless other references depend on the current value. + +### SKILL-06 — `description` Quality - **Severity:** MEDIUM - **Applies to:** `SKILL.md` @@ -225,7 +233,22 @@ If no findings are generated, the skill passes validation. --- -### REF-01 — File References Must Resolve +### REF-01 — Variable References Must Be Defined + +- **Severity:** HIGH +- **Applies to:** all files +- **Rule:** Every `{variable_name}` reference in any file (body text, frontmatter values, inline instructions) must resolve to a defined source. Valid sources are: + 1. A frontmatter variable in the same file + 2. A frontmatter variable in the skill's `workflow.md` (workflow-level variables are available to all steps) + 3. A known config variable from the project config (e.g., `project-root`, `planning_artifacts`, `implementation_artifacts`, `communication_language`) + 4. A known runtime variable set during execution (e.g., `date`, `status`, `project_name`, user-provided input variables) +- **Detection:** Collect all `{...}` tokens in the file. For each, check whether it is defined in the file's own frontmatter, in `workflow.md` frontmatter, or is a recognized config/runtime variable. Flag any token that cannot be traced to a source. Use the config variable list from the project's `config.yaml` as the reference for recognized config variables. Runtime variables are those explicitly described as user-provided or set during execution in the workflow instructions. +- **Exceptions:** + - Double-curly `{{variable}}` — these are template placeholders intended to survive into generated output (e.g., `{{project_name}}` in a template file). Do not flag these. + - Variables inside fenced code blocks that are clearly illustrative examples. +- **Fix:** Either define the variable in the appropriate frontmatter, or replace the reference with a literal value. If the variable is a config variable that was misspelled, correct the spelling. + +### REF-02 — File References Must Resolve - **Severity:** HIGH - **Applies to:** all files From f3d6ee2cb83499de82dabc985e48e3ae279df80a Mon Sep 17 00:00:00 2001 From: Alex Verkhovsky Date: Sat, 14 Mar 2026 16:04:03 -0600 Subject: [PATCH 4/6] fix(skill): clean up bmad-create-ux-design validation findings Remove installed_path and intra-skill template_path variable (PATH-02, PATH-04), prefix bare docs/** with {project-root} (PATH-03), inline undefined variable references (REF-01), fix wrong config variable in output path (REF-02). Co-Authored-By: Claude Opus 4.6 (1M context) --- .../bmad-create-ux-design/steps/step-01-init.md | 4 ++-- .../bmad-create-ux-design/steps/step-01b-continue.md | 2 +- .../bmad-create-ux-design/steps/step-14-complete.md | 4 ++-- .../2-plan-workflows/bmad-create-ux-design/workflow.md | 2 -- 4 files changed, 5 insertions(+), 7 deletions(-) diff --git a/src/bmm/workflows/2-plan-workflows/bmad-create-ux-design/steps/step-01-init.md b/src/bmm/workflows/2-plan-workflows/bmad-create-ux-design/steps/step-01-init.md index 62969bafd..2ec7ecb36 100644 --- a/src/bmm/workflows/2-plan-workflows/bmad-create-ux-design/steps/step-01-init.md +++ b/src/bmm/workflows/2-plan-workflows/bmad-create-ux-design/steps/step-01-init.md @@ -58,7 +58,7 @@ Discover and load context documents using smart discovery. Documents can be in t - {planning_artifacts}/** - {output_folder}/** - {product_knowledge}/** -- docs/** +- {project-root}/docs/** Also - when searching - documents can be a single markdown file, or a folder with an index and multiple files. For Example, if searching for `*foo*.md` and not found, also search for a folder called *foo*/index.md (which indicates sharded content) @@ -80,7 +80,7 @@ Try to discover the following: #### B. Create Initial Document -Copy the template from `{installed_path}/ux-design-template.md` to `{planning_artifacts}/ux-design-specification.md` +Copy the template from `../ux-design-template.md` to `{planning_artifacts}/ux-design-specification.md` Initialize frontmatter in the template. #### C. Complete Initialization and Report diff --git a/src/bmm/workflows/2-plan-workflows/bmad-create-ux-design/steps/step-01b-continue.md b/src/bmm/workflows/2-plan-workflows/bmad-create-ux-design/steps/step-01b-continue.md index 3d0f647e2..cd1df25f0 100644 --- a/src/bmm/workflows/2-plan-workflows/bmad-create-ux-design/steps/step-01b-continue.md +++ b/src/bmm/workflows/2-plan-workflows/bmad-create-ux-design/steps/step-01b-continue.md @@ -108,7 +108,7 @@ After presenting current progress, ask: If `lastStep` indicates the final step is completed: "Great news! It looks like we've already completed the UX design workflow for {{project_name}}. -The final UX design specification is ready at {output_folder}/ux-design-specification.md with all sections completed through step {finalStepNumber}. +The final UX design specification is ready at {planning_artifacts}/ux-design-specification.md with all sections completed through step {finalStepNumber}. The complete UX design includes visual foundations, user flows, and design specifications ready for implementation. diff --git a/src/bmm/workflows/2-plan-workflows/bmad-create-ux-design/steps/step-14-complete.md b/src/bmm/workflows/2-plan-workflows/bmad-create-ux-design/steps/step-14-complete.md index 73b07217d..67d99c427 100644 --- a/src/bmm/workflows/2-plan-workflows/bmad-create-ux-design/steps/step-14-complete.md +++ b/src/bmm/workflows/2-plan-workflows/bmad-create-ux-design/steps/step-14-complete.md @@ -75,8 +75,8 @@ This specification is now ready to guide visual design, implementation, and deve Update the main workflow status file: -- Load `{status_file}` from workflow configuration (if exists) -- Update workflow_status["create-ux-design"] = "{default_output_file}" +- Load the project's workflow status file (if one exists) +- Update workflow_status["create-ux-design"] = `{planning_artifacts}/ux-design-specification.md` - Save file, preserving all comments and structure - Mark current timestamp as completion time diff --git a/src/bmm/workflows/2-plan-workflows/bmad-create-ux-design/workflow.md b/src/bmm/workflows/2-plan-workflows/bmad-create-ux-design/workflow.md index c039c170e..04be36641 100644 --- a/src/bmm/workflows/2-plan-workflows/bmad-create-ux-design/workflow.md +++ b/src/bmm/workflows/2-plan-workflows/bmad-create-ux-design/workflow.md @@ -27,8 +27,6 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve: ### Paths -- `installed_path` = `.` -- `template_path` = `{installed_path}/ux-design-template.md` - `default_output_file` = `{planning_artifacts}/ux-design-specification.md` ## EXECUTION From 516557451ac20dda760b6d77b6d7da98b566fa19 Mon Sep 17 00:00:00 2001 From: Alex Verkhovsky Date: Sat, 14 Mar 2026 16:05:57 -0600 Subject: [PATCH 5/6] refactor: convert bmad-edit-prd from shared workflow to standalone skill Move edit-prd workflow and steps-e/ out of the shared create-prd directory into its own bmad-edit-prd skill directory with SKILL.md, workflow.md, and bmad-skill-manifest.yaml. Update pm.agent.yaml and module-help.csv to use skill:bmad-edit-prd. Fix validationWorkflow path in step-e-04 to use absolute {project-root} reference since relative path breaks after move. --- src/bmm/agents/pm.agent.yaml | 2 +- src/bmm/module-help.csv | 2 +- src/bmm/workflows/2-plan-workflows/bmad-edit-prd/SKILL.md | 6 ++++++ .../2-plan-workflows/bmad-edit-prd/bmad-skill-manifest.yaml | 1 + .../steps-e/step-e-01-discovery.md | 0 .../steps-e/step-e-01b-legacy-conversion.md | 0 .../steps-e/step-e-02-review.md | 0 .../{create-prd => bmad-edit-prd}/steps-e/step-e-03-edit.md | 0 .../steps-e/step-e-04-complete.md | 2 +- .../workflow-edit-prd.md => bmad-edit-prd/workflow.md} | 2 -- .../2-plan-workflows/create-prd/bmad-skill-manifest.yaml | 5 ----- 11 files changed, 10 insertions(+), 10 deletions(-) create mode 100644 src/bmm/workflows/2-plan-workflows/bmad-edit-prd/SKILL.md create mode 100644 src/bmm/workflows/2-plan-workflows/bmad-edit-prd/bmad-skill-manifest.yaml rename src/bmm/workflows/2-plan-workflows/{create-prd => bmad-edit-prd}/steps-e/step-e-01-discovery.md (100%) rename src/bmm/workflows/2-plan-workflows/{create-prd => bmad-edit-prd}/steps-e/step-e-01b-legacy-conversion.md (100%) rename src/bmm/workflows/2-plan-workflows/{create-prd => bmad-edit-prd}/steps-e/step-e-02-review.md (100%) rename src/bmm/workflows/2-plan-workflows/{create-prd => bmad-edit-prd}/steps-e/step-e-03-edit.md (100%) rename src/bmm/workflows/2-plan-workflows/{create-prd => bmad-edit-prd}/steps-e/step-e-04-complete.md (97%) rename src/bmm/workflows/2-plan-workflows/{create-prd/workflow-edit-prd.md => bmad-edit-prd/workflow.md} (96%) diff --git a/src/bmm/agents/pm.agent.yaml b/src/bmm/agents/pm.agent.yaml index 6fcb9774d..c8fc271cd 100644 --- a/src/bmm/agents/pm.agent.yaml +++ b/src/bmm/agents/pm.agent.yaml @@ -28,7 +28,7 @@ agent: description: "[VP] Validate PRD: Validate a Product Requirements Document is comprehensive, lean, well organized and cohesive" - trigger: EP or fuzzy match on edit-prd - exec: "{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-prd/workflow-edit-prd.md" + exec: "skill:bmad-edit-prd" description: "[EP] Edit PRD: Update an existing Product Requirements Document" - trigger: CE or fuzzy match on epics-stories diff --git a/src/bmm/module-help.csv b/src/bmm/module-help.csv index 82dad1aa0..1c21ac015 100644 --- a/src/bmm/module-help.csv +++ b/src/bmm/module-help.csv @@ -17,7 +17,7 @@ bmm,1-analysis,Technical Research,TR,22,skill:bmad-technical-research,bmad-bmm-t bmm,1-analysis,Create Brief,CB,30,skill:bmad-create-product-brief,bmad-bmm-create-product-brief,false,analyst,Create Mode,"A guided experience to nail down your product idea",planning_artifacts,"product brief", bmm,2-planning,Create PRD,CP,10,_bmad/bmm/workflows/2-plan-workflows/create-prd/workflow-create-prd.md,bmad-bmm-create-prd,true,pm,Create Mode,"Expert led facilitation to produce your Product Requirements Document",planning_artifacts,prd, bmm,2-planning,Validate PRD,VP,20,_bmad/bmm/workflows/2-plan-workflows/create-prd/workflow-validate-prd.md,bmad-bmm-validate-prd,false,pm,Validate Mode,"Validate PRD is comprehensive lean well organized and cohesive",planning_artifacts,"prd validation report", -bmm,2-planning,Edit PRD,EP,25,_bmad/bmm/workflows/2-plan-workflows/create-prd/workflow-edit-prd.md,bmad-bmm-edit-prd,false,pm,Edit Mode,"Improve and enhance an existing PRD",planning_artifacts,"updated prd", +bmm,2-planning,Edit PRD,EP,25,skill:bmad-edit-prd,bmad-bmm-edit-prd,false,pm,Edit Mode,"Improve and enhance an existing PRD",planning_artifacts,"updated prd", bmm,2-planning,Create UX,CU,30,skill:bmad-create-ux-design,bmad-bmm-create-ux-design,false,ux-designer,Create Mode,"Guidance through realizing the plan for your UX, strongly recommended if a UI is a primary piece of the proposed project",planning_artifacts,"ux design", bmm,3-solutioning,Create Architecture,CA,10,skill:bmad-create-architecture,bmad-bmm-create-architecture,true,architect,Create Mode,"Guided Workflow to document technical decisions",planning_artifacts,architecture, bmm,3-solutioning,Create Epics and Stories,CE,30,skill:bmad-create-epics-and-stories,bmad-bmm-create-epics-and-stories,true,pm,Create Mode,"Create the Epics and Stories Listing",planning_artifacts,"epics and stories", diff --git a/src/bmm/workflows/2-plan-workflows/bmad-edit-prd/SKILL.md b/src/bmm/workflows/2-plan-workflows/bmad-edit-prd/SKILL.md new file mode 100644 index 000000000..43f6e3181 --- /dev/null +++ b/src/bmm/workflows/2-plan-workflows/bmad-edit-prd/SKILL.md @@ -0,0 +1,6 @@ +--- +name: bmad-edit-prd +description: 'Edit an existing PRD. Use when the user says "edit this PRD".' +--- + +Follow the instructions in [workflow.md](workflow.md). diff --git a/src/bmm/workflows/2-plan-workflows/bmad-edit-prd/bmad-skill-manifest.yaml b/src/bmm/workflows/2-plan-workflows/bmad-edit-prd/bmad-skill-manifest.yaml new file mode 100644 index 000000000..d0f08abdb --- /dev/null +++ b/src/bmm/workflows/2-plan-workflows/bmad-edit-prd/bmad-skill-manifest.yaml @@ -0,0 +1 @@ +type: skill diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/steps-e/step-e-01-discovery.md b/src/bmm/workflows/2-plan-workflows/bmad-edit-prd/steps-e/step-e-01-discovery.md similarity index 100% rename from src/bmm/workflows/2-plan-workflows/create-prd/steps-e/step-e-01-discovery.md rename to src/bmm/workflows/2-plan-workflows/bmad-edit-prd/steps-e/step-e-01-discovery.md diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/steps-e/step-e-01b-legacy-conversion.md b/src/bmm/workflows/2-plan-workflows/bmad-edit-prd/steps-e/step-e-01b-legacy-conversion.md similarity index 100% rename from src/bmm/workflows/2-plan-workflows/create-prd/steps-e/step-e-01b-legacy-conversion.md rename to src/bmm/workflows/2-plan-workflows/bmad-edit-prd/steps-e/step-e-01b-legacy-conversion.md diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/steps-e/step-e-02-review.md b/src/bmm/workflows/2-plan-workflows/bmad-edit-prd/steps-e/step-e-02-review.md similarity index 100% rename from src/bmm/workflows/2-plan-workflows/create-prd/steps-e/step-e-02-review.md rename to src/bmm/workflows/2-plan-workflows/bmad-edit-prd/steps-e/step-e-02-review.md diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/steps-e/step-e-03-edit.md b/src/bmm/workflows/2-plan-workflows/bmad-edit-prd/steps-e/step-e-03-edit.md similarity index 100% rename from src/bmm/workflows/2-plan-workflows/create-prd/steps-e/step-e-03-edit.md rename to src/bmm/workflows/2-plan-workflows/bmad-edit-prd/steps-e/step-e-03-edit.md diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/steps-e/step-e-04-complete.md b/src/bmm/workflows/2-plan-workflows/bmad-edit-prd/steps-e/step-e-04-complete.md similarity index 97% rename from src/bmm/workflows/2-plan-workflows/create-prd/steps-e/step-e-04-complete.md rename to src/bmm/workflows/2-plan-workflows/bmad-edit-prd/steps-e/step-e-04-complete.md index 5d681feed..ad394488e 100644 --- a/src/bmm/workflows/2-plan-workflows/create-prd/steps-e/step-e-04-complete.md +++ b/src/bmm/workflows/2-plan-workflows/bmad-edit-prd/steps-e/step-e-04-complete.md @@ -4,7 +4,7 @@ description: 'Complete & Validate - Present options for next steps including ful # File references (ONLY variables used in this step) prdFile: '{prd_file_path}' -validationWorkflow: '../steps-v/step-v-01-discovery.md' +validationWorkflow: '{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-01-discovery.md' --- # Step E-4: Complete & Validate diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/workflow-edit-prd.md b/src/bmm/workflows/2-plan-workflows/bmad-edit-prd/workflow.md similarity index 96% rename from src/bmm/workflows/2-plan-workflows/create-prd/workflow-edit-prd.md rename to src/bmm/workflows/2-plan-workflows/bmad-edit-prd/workflow.md index cdf6b938d..a765a5459 100644 --- a/src/bmm/workflows/2-plan-workflows/create-prd/workflow-edit-prd.md +++ b/src/bmm/workflows/2-plan-workflows/bmad-edit-prd/workflow.md @@ -1,6 +1,4 @@ --- -name: edit-prd -description: 'Edit an existing PRD. Use when the user says "edit this PRD".' main_config: '{project-root}/_bmad/bmm/config.yaml' editWorkflow: './steps-e/step-e-01-discovery.md' --- diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/bmad-skill-manifest.yaml b/src/bmm/workflows/2-plan-workflows/create-prd/bmad-skill-manifest.yaml index aea9910a2..32464dcc8 100644 --- a/src/bmm/workflows/2-plan-workflows/create-prd/bmad-skill-manifest.yaml +++ b/src/bmm/workflows/2-plan-workflows/create-prd/bmad-skill-manifest.yaml @@ -3,11 +3,6 @@ workflow-create-prd.md: type: workflow description: "Create a PRD from scratch. Use when the user says 'lets create a product requirements document' or 'I want to create a new PRD'" -workflow-edit-prd.md: - canonicalId: bmad-edit-prd - type: workflow - description: "Edit an existing PRD. Use when the user says 'edit this PRD'" - workflow-validate-prd.md: canonicalId: bmad-validate-prd type: workflow From b9926e1c4a72ffb4ee8c2960097dfe55cdaef12e Mon Sep 17 00:00:00 2001 From: Alex Verkhovsky Date: Sat, 14 Mar 2026 16:16:34 -0600 Subject: [PATCH 6/6] fix(skill): clean up bmad-check-implementation-readiness validation findings Remove name/description from step frontmatter (STEP-06) and inline nextStepFile/templateFile path variables as literal relative paths (PATH-04). Co-Authored-By: Claude Opus 4.6 (1M context) --- .../steps/step-01-document-discovery.md | 11 +++-------- .../steps/step-02-prd-analysis.md | 6 +----- .../steps/step-03-epic-coverage-validation.md | 6 +----- .../steps/step-04-ux-alignment.md | 6 +----- .../steps/step-05-epic-quality-review.md | 8 ++------ .../steps/step-06-final-assessment.md | 3 --- 6 files changed, 8 insertions(+), 32 deletions(-) diff --git a/src/bmm/workflows/3-solutioning/bmad-check-implementation-readiness/steps/step-01-document-discovery.md b/src/bmm/workflows/3-solutioning/bmad-check-implementation-readiness/steps/step-01-document-discovery.md index 877193f3d..a4c524cfd 100644 --- a/src/bmm/workflows/3-solutioning/bmad-check-implementation-readiness/steps/step-01-document-discovery.md +++ b/src/bmm/workflows/3-solutioning/bmad-check-implementation-readiness/steps/step-01-document-discovery.md @@ -1,10 +1,5 @@ --- -name: 'step-01-document-discovery' -description: 'Discover and inventory all project documents, handling duplicates and organizing file structure' - -nextStepFile: './step-02-prd-analysis.md' outputFile: '{planning_artifacts}/implementation-readiness-report-{{date}}.md' -templateFile: '../templates/readiness-report-template.md' --- # Step 1: Document Discovery @@ -122,7 +117,7 @@ If required documents not found: ### 5. Add Initial Report Section -Initialize {outputFile} with {templateFile}. +Initialize {outputFile} with ../templates/readiness-report-template.md. ### 6. Present Findings and Get Confirmation @@ -156,12 +151,12 @@ Display: **Select an Option:** [C] Continue to File Validation #### Menu Handling Logic: -- IF C: Save document inventory to {outputFile}, update frontmatter with completed step and files being included, and then read fully and follow: {nextStepFile} +- IF C: Save document inventory to {outputFile}, update frontmatter with completed step and files being included, and then read fully and follow: ./step-02-prd-analysis.md - IF Any other comments or queries: help user respond then redisplay menu ## CRITICAL STEP COMPLETION NOTE -ONLY WHEN C is selected and document inventory is saved will you load {nextStepFile} to begin file validation. +ONLY WHEN C is selected and document inventory is saved will you load ./step-02-prd-analysis.md to begin file validation. --- diff --git a/src/bmm/workflows/3-solutioning/bmad-check-implementation-readiness/steps/step-02-prd-analysis.md b/src/bmm/workflows/3-solutioning/bmad-check-implementation-readiness/steps/step-02-prd-analysis.md index 4d22e7da9..85cadc4d4 100644 --- a/src/bmm/workflows/3-solutioning/bmad-check-implementation-readiness/steps/step-02-prd-analysis.md +++ b/src/bmm/workflows/3-solutioning/bmad-check-implementation-readiness/steps/step-02-prd-analysis.md @@ -1,8 +1,4 @@ --- -name: 'step-02-prd-analysis' -description: 'Read and analyze PRD to extract all FRs and NFRs for coverage validation' - -nextStepFile: './step-03-epic-coverage-validation.md' outputFile: '{planning_artifacts}/implementation-readiness-report-{{date}}.md' epicsFile: '{planning_artifacts}/*epic*.md' # Will be resolved to actual file --- @@ -149,7 +145,7 @@ After PRD analysis complete, immediately load next step for epic coverage valida ## PROCEEDING TO EPIC COVERAGE VALIDATION -PRD analysis complete. Loading next step to validate epic coverage. +PRD analysis complete. Read fully and follow: `./step-03-epic-coverage-validation.md` --- diff --git a/src/bmm/workflows/3-solutioning/bmad-check-implementation-readiness/steps/step-03-epic-coverage-validation.md b/src/bmm/workflows/3-solutioning/bmad-check-implementation-readiness/steps/step-03-epic-coverage-validation.md index b73511bea..961ee740c 100644 --- a/src/bmm/workflows/3-solutioning/bmad-check-implementation-readiness/steps/step-03-epic-coverage-validation.md +++ b/src/bmm/workflows/3-solutioning/bmad-check-implementation-readiness/steps/step-03-epic-coverage-validation.md @@ -1,8 +1,4 @@ --- -name: 'step-03-epic-coverage-validation' -description: 'Validate that all PRD FRs are covered in epics and stories' - -nextStepFile: './step-04-ux-alignment.md' outputFile: '{planning_artifacts}/implementation-readiness-report-{{date}}.md' --- @@ -150,7 +146,7 @@ After coverage validation complete, immediately load next step. ## PROCEEDING TO UX ALIGNMENT -Epic coverage validation complete. Loading next step for UX alignment. +Epic coverage validation complete. Read fully and follow: `./step-04-ux-alignment.md` --- diff --git a/src/bmm/workflows/3-solutioning/bmad-check-implementation-readiness/steps/step-04-ux-alignment.md b/src/bmm/workflows/3-solutioning/bmad-check-implementation-readiness/steps/step-04-ux-alignment.md index 236ad3b51..05718abe4 100644 --- a/src/bmm/workflows/3-solutioning/bmad-check-implementation-readiness/steps/step-04-ux-alignment.md +++ b/src/bmm/workflows/3-solutioning/bmad-check-implementation-readiness/steps/step-04-ux-alignment.md @@ -1,8 +1,4 @@ --- -name: 'step-04-ux-alignment' -description: 'Check for UX document and validate alignment with PRD and Architecture' - -nextStepFile: './step-05-epic-quality-review.md' outputFile: '{planning_artifacts}/implementation-readiness-report-{{date}}.md' --- @@ -113,7 +109,7 @@ After UX assessment complete, immediately load next step. ## PROCEEDING TO EPIC QUALITY REVIEW -UX alignment assessment complete. Loading next step for epic quality review. +UX alignment assessment complete. Read fully and follow: `./step-05-epic-quality-review.md` --- diff --git a/src/bmm/workflows/3-solutioning/bmad-check-implementation-readiness/steps/step-05-epic-quality-review.md b/src/bmm/workflows/3-solutioning/bmad-check-implementation-readiness/steps/step-05-epic-quality-review.md index 9f6d087f8..2e088f9b1 100644 --- a/src/bmm/workflows/3-solutioning/bmad-check-implementation-readiness/steps/step-05-epic-quality-review.md +++ b/src/bmm/workflows/3-solutioning/bmad-check-implementation-readiness/steps/step-05-epic-quality-review.md @@ -1,8 +1,4 @@ --- -name: 'step-05-epic-quality-review' -description: 'Validate epics and stories against create-epics-and-stories best practices' - -nextStepFile: './step-06-final-assessment.md' outputFile: '{planning_artifacts}/implementation-readiness-report-{{date}}.md' --- @@ -217,11 +213,11 @@ After completing epic quality review: - Update {outputFile} with all quality findings - Document specific best practices violations - Provide actionable recommendations -- Load {nextStepFile} for final readiness assessment +- Load ./step-06-final-assessment.md for final readiness assessment ## CRITICAL STEP COMPLETION NOTE -This step executes autonomously. Load {nextStepFile} only after complete epic quality review is documented. +This step executes autonomously. Load ./step-06-final-assessment.md only after complete epic quality review is documented. --- diff --git a/src/bmm/workflows/3-solutioning/bmad-check-implementation-readiness/steps/step-06-final-assessment.md b/src/bmm/workflows/3-solutioning/bmad-check-implementation-readiness/steps/step-06-final-assessment.md index 548aa8f6d..467864215 100644 --- a/src/bmm/workflows/3-solutioning/bmad-check-implementation-readiness/steps/step-06-final-assessment.md +++ b/src/bmm/workflows/3-solutioning/bmad-check-implementation-readiness/steps/step-06-final-assessment.md @@ -1,7 +1,4 @@ --- -name: 'step-06-final-assessment' -description: 'Compile final assessment and polish the readiness report' - outputFile: '{planning_artifacts}/implementation-readiness-report-{{date}}.md' ---