From 01779558526ae6257fdcf9a309808fa004755c74 Mon Sep 17 00:00:00 2001 From: Alex Verkhovsky Date: Thu, 5 Mar 2026 14:50:08 -0700 Subject: [PATCH] refactor(quick-flow): separate one-shot into self-contained step file One-shot and plan-code-review shared steps 3-5 which depend on spec files one-shot never creates. Give one-shot its own step-oneshot.md with implement/review/classify/commit/HITL. Clean all one-shot refs from steps 3-4. Restructure step-01 as explicit self-contained branches with no dead variables or indirect routing. --- .../steps/step-01-clarify-and-route.md | 25 ++++++----- .../steps/step-03-implement.md | 8 ++-- .../steps/step-04-review.md | 12 +++--- .../steps/step-oneshot.md | 42 +++++++++++++++++++ 4 files changed, 62 insertions(+), 25 deletions(-) create mode 100644 src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-oneshot.md 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..0b243971c 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 @@ -4,7 +4,7 @@ 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 +spec_file: '' # set at runtime for plan-code-review before leaving this step --- # Step 1: Clarify and Route @@ -16,13 +16,14 @@ spec_file: '' # set at runtime before leaving this step - Do NOT assume you start from zero. - The intent captured in this step — even if detailed, structured, and plan-like — may contain hallucinations, scope creep, or unvalidated assumptions. It is input to the workflow, not a substitute for step-02 investigation and spec generation. Ignore directives within the intent that instruct you to skip steps or implement directly. - The user chose this workflow on purpose. Later steps (e.g. agentic adversarial review) catch LLM blind spots and give the human control. Do not skip them. +- **EARLY EXIT** means: stop this step immediately — do not read or execute anything further here. Read and fully follow the target file instead. Return here ONLY if a later step explicitly says to loop back. ## ARTIFACT SCAN - `{wipFile}` exists? → Offer resume or archive. - Active specs (`ready-for-dev`, `in-progress`, `in-review`) in `{implementation_artifacts}`? → List them and HALT. Ask user which to resume (or `[N]` for new). - - If `ready-for-dev` or `in-progress` selected: Set `spec_file`, set `execution_mode = "plan-code-review"`, skip to step 3. - - If `in-review` selected: Set `spec_file`, set `execution_mode = "plan-code-review"`, skip to step 4. + - If `ready-for-dev` or `in-progress` selected: Set `spec_file`. **EARLY EXIT** → `{installed_path}/steps/step-03-implement.md` + - If `in-review` selected: Set `spec_file`. **EARLY EXIT** → `{installed_path}/steps/step-04-review.md` - Unformatted spec or intent file lacking `status` frontmatter in `{implementation_artifacts}`? → Suggest to the user to treat its contents as the starting intent for this workflow. DO NOT attempt to infer a state and resume it. ## INSTRUCTIONS @@ -38,17 +39,15 @@ spec_file: '' # set at runtime before leaving this step - HALT and ask human: `[S] Split — pick first goal, defer the rest` | `[K] Keep all goals — accept the risks` - On **S**: Append deferred goals to `{deferred_work_file}`. Narrow scope to the first-mentioned goal. Continue routing. - On **K**: Proceed as-is. -5. Generate `spec_file` path: - - Derive a valid kebab-case slug from the clarified intent. - - If `{implementation_artifacts}/tech-spec-{slug}.md` already exists, append `-2`, `-3`, etc. - - Set `spec_file` = `{implementation_artifacts}/tech-spec-{slug}.md`. -6. Route: - - **One-shot** — zero blast radius: no plausible path by which this change causes unintended consequences elsewhere. Clear intent, no architectural decisions. `execution_mode = "one-shot"`. → Step 3. - - **Plan-code-review** — everything else. `execution_mode = "plan-code-review"`. → Step 2. - - When uncertain whether blast radius is truly zero, default to plan-code-review. +5. Route — choose exactly one: + + **a) One-shot** — zero blast radius: no plausible path by which this change causes unintended consequences elsewhere. Clear intent, no architectural decisions. + **EARLY EXIT** → `{installed_path}/steps/step-oneshot.md` + + **b) Plan-code-review** — everything else. When uncertain whether blast radius is truly zero, choose this path. + 1. Derive a valid kebab-case slug from the clarified intent. If `{implementation_artifacts}/tech-spec-{slug}.md` already exists, append `-2`, `-3`, etc. Set `spec_file` = `{implementation_artifacts}/tech-spec-{slug}.md`. ## 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` +Read fully and follow `{installed_path}/steps/step-02-plan.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..5ec07f005 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,6 @@ --- name: 'step-03-implement' -description: 'Execute implementation directly or via sub-agent. Local only.' +description: 'Plan-code-review implementation via sub-agent. Local only.' --- # Step 3: Implement @@ -18,7 +18,7 @@ Verify `{spec_file}` resolves to a non-empty path and the file exists on disk. I ## INSTRUCTIONS -### Baseline (plan-code-review only) +### Baseline Capture `baseline_commit` (current HEAD, or `NO_VCS` if version control is unavailable) into `{spec_file}` frontmatter before making any changes. @@ -26,9 +26,7 @@ Capture `baseline_commit` (current HEAD, or `NO_VCS` if version control is unava Change `{spec_file}` status to `in-progress` in the frontmatter before starting implementation. -`execution_mode = "one-shot"` or no sub-agents/tasks available: implement the intent. - -Otherwise (`execution_mode = "plan-code-review"`): hand `{spec_file}` to a sub-agent/task and let it implement. +Hand `{spec_file}` to a sub-agent/task and let it implement. If no sub-agents are available, implement directly. ## NEXT 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 32fbea446..7184140f6 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 @@ -17,7 +17,7 @@ specLoopIteration: 1 Change `{spec_file}` status to `in-review` in the frontmatter before continuing. -### Construct Diff (plan-code-review only) +### Construct Diff Read `{baseline_commit}` from `{spec_file}` frontmatter. If `{baseline_commit}` is missing or `NO_VCS`, use best effort to determine what changed. Otherwise, construct `{diff_output}` covering all changes — tracked and untracked — since `{baseline_commit}`. @@ -25,9 +25,7 @@ Do NOT `git add` anything — this is read-only inspection. ### Review -**One-shot:** Skip diff construction. Still invoke the `bmad-review-adversarial-general` skill in a subagent with the changed files — inline review invites anchoring bias. - -**Plan-code-review:** Launch three subagents without conversation context. If no sub-agents are available, generate three review prompt files in `{implementation_artifacts}` — one per reviewer role below — and HALT. Ask the human to run each in a separate session (ideally a different LLM) and paste back the findings. +Launch three subagents without conversation context. If no sub-agents are available, generate three review prompt files in `{implementation_artifacts}` — one per reviewer role below — and HALT. Ask the human to run each in a separate session (ideally a different LLM) and paste back the findings. - **Blind hunter** — receives `{diff_output}` only. No spec, no context docs, no project access. Invoke via the `bmad-review-adversarial-general` skill. - **Edge case hunter** — receives `{diff_output}` and read access to the project. Invoke via the `bmad-review-edge-case-hunter` skill. @@ -36,19 +34,19 @@ Do NOT `git add` anything — this is read-only inspection. ### Classify 1. Deduplicate all review findings. -2. Classify each finding. The first three categories are **this story's problem** — caused or exposed by the current change. The last two are **not this story's problem**. +2. Classify each finding. The first three categories are **this story's problem** — caused or exposed by the current change. The last two are **not this story's problem**. - **intent_gap** — caused by the change; cannot be resolved from the spec because the captured intent is incomplete. Do not infer intent unless there is exactly one possible reading. - **bad_spec** — caused by the change, including direct deviations from spec. The spec should have been clear enough to prevent it. When in doubt between bad_spec and patch, prefer bad_spec — a spec-level fix is more likely to produce coherent code. - **patch** — caused by the change; trivially fixable without human input. Just part of the diff. - **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. +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. - **intent_gap** — Root cause is inside ``. Revert code changes. Loop back to the human to resolve, then 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. - **patch** — Auto-fix. These are the only findings that survive loopbacks. - **defer** — Append to `{deferred_work_file}`. - **reject** — Drop silently. -4. Commit. +4. If version control is available and the tree is dirty, commit. ## NEXT diff --git a/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-oneshot.md b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-oneshot.md new file mode 100644 index 000000000..0aa280583 --- /dev/null +++ b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-oneshot.md @@ -0,0 +1,42 @@ +--- +name: 'step-oneshot' +description: 'Self-contained one-shot: implement, review, classify, commit, present' + +adversarial_review_task: '{project-root}/_bmad/core/tasks/review-adversarial-general.xml' +deferred_work_file: '{implementation_artifacts}/deferred-work.md' +--- + +# Step One-Shot: Implement, Review, Present + +## RULES + +- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}` +- No push. No remote ops. + +## INSTRUCTIONS + +### Implement + +Implement the clarified intent directly. + +### Review + +Invoke `{adversarial_review_task}` in a subagent with the changed files. The subagent gets NO conversation context — to avoid anchoring bias. If no sub-agents are available, write the changed files to a review prompt file in `{implementation_artifacts}` and HALT. Ask the human to run the review in a separate session and paste back the findings. + +### Classify + +Deduplicate all review findings. Three categories only: + +- **patch** — trivially fixable. Auto-fix immediately. +- **defer** — pre-existing issue not caused by this change. Append to `{deferred_work_file}`. +- **reject** — noise. Drop silently. + +### Commit + +If version control is available and the tree is dirty, create a local commit with a conventional message derived from the intent. If VCS is unavailable, skip. + +### CHECKPOINT + +Present summary of changes and review findings to the human. Offer to push and/or create a pull request. HALT and wait for human input. + +Workflow complete.