From b1209a97da569710ef036f770d44a9201a4018e7 Mon Sep 17 00:00:00 2001 From: Alex Verkhovsky Date: Sat, 14 Mar 2026 17:02:08 -0600 Subject: [PATCH] fix(skill): validation cleanup for quick-flow skills bmad-quick-dev-new-preview: fix wrong step-to-step path references from within steps/ directory, remove step frontmatter metadata and intra-skill path variables. bmad-quick-dev: remove step frontmatter metadata, inline nextStepFile path variables as literal relative paths. bmad-quick-spec: remove name/description from workflow.md frontmatter, fix absolute self-references using {project-root} for intra-skill paths, remove step frontmatter metadata. Co-Authored-By: Claude Opus 4.6 (1M context) --- .../steps/step-01-clarify-and-route.md | 7 ++----- .../steps/step-02-plan.md | 8 ++------ .../steps/step-03-implement.md | 4 +--- .../steps/step-04-review.md | 9 +++------ .../steps/step-05-present.md | 2 -- .../bmad-quick-dev-new-preview/workflow.md | 1 - .../steps/step-01-mode-detection.md | 17 ++++++----------- .../steps/step-02-context-gathering.md | 6 +----- .../bmad-quick-dev/steps/step-03-execute.md | 6 +----- .../bmad-quick-dev/steps/step-04-self-check.md | 6 +----- .../steps/step-05-adversarial-review.md | 6 +----- .../steps/step-06-resolve-findings.md | 2 -- .../bmad-quick-spec/steps/step-01-understand.md | 6 +----- .../steps/step-02-investigate.md | 3 --- .../bmad-quick-spec/steps/step-03-generate.md | 3 --- .../bmad-quick-spec/steps/step-04-review.md | 3 --- 16 files changed, 19 insertions(+), 70 deletions(-) diff --git a/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-01-clarify-and-route.md b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-01-clarify-and-route.md index b8812e4f6..5671b6c66 100644 --- a/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-01-clarify-and-route.md +++ b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-01-clarify-and-route.md @@ -1,7 +1,4 @@ --- -name: 'step-01-clarify-and-route' -description: 'Capture intent, route to execution path' - wipFile: '{implementation_artifacts}/tech-spec-wip.md' deferred_work_file: '{implementation_artifacts}/deferred-work.md' spec_file: '' # set at runtime before leaving this step @@ -50,5 +47,5 @@ spec_file: '' # set at runtime before leaving this step ## NEXT -- One-shot / ready-for-dev: Read fully and follow `./steps/step-03-implement.md` -- Plan-code-review: Read fully and follow `./steps/step-02-plan.md` +- One-shot / ready-for-dev: Read fully and follow `./step-03-implement.md` +- Plan-code-review: Read fully and follow `./step-02-plan.md` diff --git a/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-02-plan.md b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-02-plan.md index 22df65b60..70e7c83fb 100644 --- a/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-02-plan.md +++ b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-02-plan.md @@ -1,8 +1,4 @@ --- -name: 'step-02-plan' -description: 'Investigate, generate spec, present for approval' - -templateFile: '../tech-spec-template.md' wipFile: '{implementation_artifacts}/tech-spec-wip.md' deferred_work_file: '{implementation_artifacts}/deferred-work.md' --- @@ -17,7 +13,7 @@ deferred_work_file: '{implementation_artifacts}/deferred-work.md' ## INSTRUCTIONS 1. Investigate codebase. _Isolate deep exploration in sub-agents/tasks where available. To prevent context snowballing, instruct subagents to give you distilled summaries only._ -2. Read `{templateFile}` fully. Fill it out based on the intent and investigation, and write the result to `{wipFile}`. +2. Read `../tech-spec-template.md` fully. Fill it out based on the intent and investigation, and write the result to `{wipFile}`. 3. Self-review against READY FOR DEVELOPMENT standard. 4. If intent gaps exist, do not fantasize, do not leave open questions, HALT and ask the human. 5. Token count check (see SCOPE STANDARD). If spec exceeds 1600 tokens: @@ -36,4 +32,4 @@ Present summary. If token count exceeded 1600 and user chose [K], include the to ## NEXT -Read fully and follow `./steps/step-03-implement.md` +Read fully and follow `./step-03-implement.md` diff --git a/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-03-implement.md b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-03-implement.md index 97d189272..fb596eb79 100644 --- a/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-03-implement.md +++ b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-03-implement.md @@ -1,6 +1,4 @@ --- -name: 'step-03-implement' -description: 'Execute implementation directly or via sub-agent. Local only.' --- # Step 3: Implement @@ -32,4 +30,4 @@ Otherwise (`execution_mode = "plan-code-review"`): hand `{spec_file}` to a sub-a ## NEXT -Read fully and follow `./steps/step-04-review.md` +Read fully and follow `./step-04-review.md` diff --git a/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-04-review.md b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-04-review.md index 79e4510f8..154e97d0a 100644 --- a/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-04-review.md +++ b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-04-review.md @@ -1,7 +1,4 @@ --- -name: 'step-04-review' -description: 'Adversarial review, classify findings, optional spec loop' - deferred_work_file: '{implementation_artifacts}/deferred-work.md' specLoopIteration: 1 --- @@ -43,11 +40,11 @@ Do NOT `git add` anything — this is read-only inspection. - **defer** — pre-existing issue not caused by this story, surfaced incidentally by the review. Collect for later focused attention. - **reject** — noise. Drop silently. When unsure between defer and reject, prefer reject — only defer findings you are confident are real. 3. Process findings in cascading order. If intent_gap or bad_spec findings exist, they trigger a loopback — lower findings are moot since code will be re-derived. If neither exists, process patch and defer normally. Increment `{specLoopIteration}` on each loopback. If it exceeds 5, HALT and escalate to the human. On any loopback, re-evaluate routing — if scope has grown beyond one-shot, escalate `execution_mode` to plan-code-review. - - **intent_gap** — Root cause is inside ``. Revert code changes. Loop back to the human to resolve. Once resolved, read fully and follow `./steps/step-02-plan.md` to re-run steps 2–4. - - **bad_spec** — Root cause is outside ``. Before reverting code: extract KEEP instructions for positive preservation (what worked well and must survive re-derivation). Revert code changes. Read the `## Spec Change Log` in `{spec_file}` and strictly respect all logged constraints when amending the non-frozen sections that contain the root cause. Append a new change-log entry recording: the triggering finding, what was amended, the known-bad state avoided, and the KEEP instructions. Read fully and follow `./steps/step-03-implement.md` to re-derive the code, then this step will run again. + - **intent_gap** — Root cause is inside ``. Revert code changes. Loop back to the human to resolve. Once resolved, read fully and follow `./step-02-plan.md` to re-run steps 2–4. + - **bad_spec** — Root cause is outside ``. Before reverting code: extract KEEP instructions for positive preservation (what worked well and must survive re-derivation). Revert code changes. Read the `## Spec Change Log` in `{spec_file}` and strictly respect all logged constraints when amending the non-frozen sections that contain the root cause. Append a new change-log entry recording: the triggering finding, what was amended, the known-bad state avoided, and the KEEP instructions. Read fully and follow `./step-03-implement.md` to re-derive the code, then this step will run again. - **patch** — Auto-fix. These are the only findings that survive loopbacks. - **defer** — Append to `{deferred_work_file}`. - **reject** — Drop silently. ## NEXT -Read fully and follow `./steps/step-05-present.md` +Read fully and follow `./step-05-present.md` diff --git a/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-05-present.md b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-05-present.md index c9bc13d50..800394015 100644 --- a/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-05-present.md +++ b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-05-present.md @@ -1,6 +1,4 @@ --- -name: 'step-05-present' -description: 'Present findings, get approval, create PR' --- # Step 5: Present diff --git a/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/workflow.md b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/workflow.md index 71d231ac1..6da0bc844 100644 --- a/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/workflow.md +++ b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/workflow.md @@ -72,7 +72,6 @@ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config ` ### 2. Paths -- `templateFile` = `./tech-spec-template.md` - `wipFile` = `{implementation_artifacts}/tech-spec-wip.md` ### 3. First Step Execution diff --git a/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/steps/step-01-mode-detection.md b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/steps/step-01-mode-detection.md index 8de9be3fd..b0a7f933e 100644 --- a/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/steps/step-01-mode-detection.md +++ b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/steps/step-01-mode-detection.md @@ -1,9 +1,4 @@ --- -name: 'step-01-mode-detection' -description: 'Determine execution mode (tech-spec vs direct), handle escalation, set state variables' - -nextStepFile_modeA: './step-03-execute.md' -nextStepFile_modeB: './step-02-context-gathering.md' --- # Step 1: Mode Detection @@ -50,7 +45,7 @@ Analyze the user's input to determine mode: - Load the spec, extract tasks/context/AC - Set `{execution_mode}` = "tech-spec" - Set `{tech_spec_path}` = provided path -- **NEXT:** Read fully and follow: `{nextStepFile_modeA}` +- **NEXT:** Read fully and follow: `./step-03-execute.md` **Mode B: Direct Instructions** @@ -91,7 +86,7 @@ Display: "**Select:** [P] Plan first (tech-spec) [E] Execute directly" #### Menu Handling Logic: - IF P: Direct user to `{quick_spec_workflow}`. **EXIT Quick Dev.** -- IF E: Ask for any additional guidance, then **NEXT:** Read fully and follow: `{nextStepFile_modeB}` +- IF E: Ask for any additional guidance, then **NEXT:** Read fully and follow: `./step-02-context-gathering.md` #### EXECUTION RULES: @@ -114,7 +109,7 @@ Display: - IF P: Direct to `{quick_spec_workflow}`. **EXIT Quick Dev.** - IF W: Direct user to run the PRD workflow instead. **EXIT Quick Dev.** -- IF E: Ask for guidance, then **NEXT:** Read fully and follow: `{nextStepFile_modeB}` +- IF E: Ask for guidance, then **NEXT:** Read fully and follow: `./step-02-context-gathering.md` #### EXECUTION RULES: @@ -137,7 +132,7 @@ Display: - IF P: Direct to `{quick_spec_workflow}`. **EXIT Quick Dev.** - IF W: Direct user to run the PRD workflow instead. **EXIT Quick Dev.** -- IF E: Ask for guidance, then **NEXT:** Read fully and follow: `{nextStepFile_modeB}` +- IF E: Ask for guidance, then **NEXT:** Read fully and follow: `./step-02-context-gathering.md` #### EXECUTION RULES: @@ -150,8 +145,8 @@ Display: **CRITICAL:** When this step completes, explicitly state which step to load: -- Mode A (tech-spec): "**NEXT:** read fully and follow: `{nextStepFile_modeA}`" -- Mode B (direct, [E] selected): "**NEXT:** Read fully and follow: `{nextStepFile_modeB}`" +- Mode A (tech-spec): "**NEXT:** read fully and follow: `./step-03-execute.md`" +- Mode B (direct, [E] selected): "**NEXT:** Read fully and follow: `./step-02-context-gathering.md`" - Escalation ([P] or [W]): "**EXITING Quick Dev.** Follow the directed workflow." --- diff --git a/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/steps/step-02-context-gathering.md b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/steps/step-02-context-gathering.md index 3652bb924..ba4750c15 100644 --- a/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/steps/step-02-context-gathering.md +++ b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/steps/step-02-context-gathering.md @@ -1,8 +1,4 @@ --- -name: 'step-02-context-gathering' -description: 'Quick context gathering for direct mode - identify files, patterns, dependencies' - -nextStepFile: './step-03-execute.md' --- # Step 2: Context Gathering (Direct Mode) @@ -97,7 +93,7 @@ Ready to execute? (y/n/adjust) **CRITICAL:** When user confirms ready, explicitly state: -- **y:** "**NEXT:** Read fully and follow: `{nextStepFile}`" +- **y:** "**NEXT:** Read fully and follow: `./step-03-execute.md`" - **n/adjust:** Continue gathering context, then re-present plan --- diff --git a/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/steps/step-03-execute.md b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/steps/step-03-execute.md index 06801af7a..7feafef37 100644 --- a/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/steps/step-03-execute.md +++ b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/steps/step-03-execute.md @@ -1,8 +1,4 @@ --- -name: 'step-03-execute' -description: 'Execute implementation - iterate through tasks, write code, run tests' - -nextStepFile: './step-04-self-check.md' --- # Step 3: Execute Implementation @@ -89,7 +85,7 @@ For each task: ## NEXT STEP -When ALL tasks are complete (or halted on blocker), read fully and follow: `{nextStepFile}`. +When ALL tasks are complete (or halted on blocker), read fully and follow: `./step-04-self-check.md`. --- diff --git a/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/steps/step-04-self-check.md b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/steps/step-04-self-check.md index e70de8515..ffb3ce1b7 100644 --- a/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/steps/step-04-self-check.md +++ b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/steps/step-04-self-check.md @@ -1,8 +1,4 @@ --- -name: 'step-04-self-check' -description: 'Self-audit implementation against tasks, tests, AC, and patterns' - -nextStepFile: './step-05-adversarial-review.md' --- # Step 4: Self-Check @@ -89,7 +85,7 @@ Proceeding to adversarial code review... ## NEXT STEP -Proceed immediately to `{nextStepFile}`. +Proceed immediately to `./step-05-adversarial-review.md`. --- diff --git a/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/steps/step-05-adversarial-review.md b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/steps/step-05-adversarial-review.md index 29a0cef19..58ec3d3ae 100644 --- a/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/steps/step-05-adversarial-review.md +++ b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/steps/step-05-adversarial-review.md @@ -1,8 +1,4 @@ --- -name: 'step-05-adversarial-review' -description: 'Construct diff and invoke adversarial review skill' - -nextStepFile: './step-06-resolve-findings.md' --- # Step 5: Adversarial Code Review @@ -77,7 +73,7 @@ If TodoWrite or similar tool is available, turn each finding into a TODO, includ ## NEXT STEP -With findings in hand, read fully and follow: `{nextStepFile}` for user to choose resolution approach. +With findings in hand, read fully and follow: `./step-06-resolve-findings.md` for user to choose resolution approach. --- diff --git a/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/steps/step-06-resolve-findings.md b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/steps/step-06-resolve-findings.md index 5c9165c86..aaebf1108 100644 --- a/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/steps/step-06-resolve-findings.md +++ b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/steps/step-06-resolve-findings.md @@ -1,6 +1,4 @@ --- -name: 'step-06-resolve-findings' -description: 'Handle review findings interactively, apply fixes, update tech-spec with final status' --- # Step 6: Resolve Findings diff --git a/src/bmm/workflows/bmad-quick-flow/bmad-quick-spec/steps/step-01-understand.md b/src/bmm/workflows/bmad-quick-flow/bmad-quick-spec/steps/step-01-understand.md index 855c2c3c4..21799d8f9 100644 --- a/src/bmm/workflows/bmad-quick-flow/bmad-quick-spec/steps/step-01-understand.md +++ b/src/bmm/workflows/bmad-quick-flow/bmad-quick-spec/steps/step-01-understand.md @@ -1,8 +1,4 @@ --- -name: 'step-01-understand' -description: 'Analyze the requirement delta between current state and what user wants to build' - -templateFile: '../tech-spec-template.md' wipFile: '{implementation_artifacts}/tech-spec-wip.md' --- @@ -125,7 +121,7 @@ b) **Ask the user to confirm the captured understanding before proceeding.** a) **Create the tech-spec WIP file:** -1. Copy template from `{templateFile}` +1. Copy template from `../tech-spec-template.md` 2. Write to `{wipFile}` 3. Update frontmatter with captured values: ```yaml diff --git a/src/bmm/workflows/bmad-quick-flow/bmad-quick-spec/steps/step-02-investigate.md b/src/bmm/workflows/bmad-quick-flow/bmad-quick-spec/steps/step-02-investigate.md index 48d9aa7f8..07ef40c05 100644 --- a/src/bmm/workflows/bmad-quick-flow/bmad-quick-spec/steps/step-02-investigate.md +++ b/src/bmm/workflows/bmad-quick-flow/bmad-quick-spec/steps/step-02-investigate.md @@ -1,7 +1,4 @@ --- -name: 'step-02-investigate' -description: 'Map technical constraints and anchor points within the codebase' - wipFile: '{implementation_artifacts}/tech-spec-wip.md' --- diff --git a/src/bmm/workflows/bmad-quick-flow/bmad-quick-spec/steps/step-03-generate.md b/src/bmm/workflows/bmad-quick-flow/bmad-quick-spec/steps/step-03-generate.md index 42dc43dd1..17ef38ae2 100644 --- a/src/bmm/workflows/bmad-quick-flow/bmad-quick-spec/steps/step-03-generate.md +++ b/src/bmm/workflows/bmad-quick-flow/bmad-quick-spec/steps/step-03-generate.md @@ -1,7 +1,4 @@ --- -name: 'step-03-generate' -description: 'Build the implementation plan based on the technical mapping of constraints' - wipFile: '{implementation_artifacts}/tech-spec-wip.md' --- diff --git a/src/bmm/workflows/bmad-quick-flow/bmad-quick-spec/steps/step-04-review.md b/src/bmm/workflows/bmad-quick-flow/bmad-quick-spec/steps/step-04-review.md index a973caecd..828b6e197 100644 --- a/src/bmm/workflows/bmad-quick-flow/bmad-quick-spec/steps/step-04-review.md +++ b/src/bmm/workflows/bmad-quick-flow/bmad-quick-spec/steps/step-04-review.md @@ -1,7 +1,4 @@ --- -name: 'step-04-review' -description: 'Review and finalize the tech-spec' - wipFile: '{implementation_artifacts}/tech-spec-wip.md' ---