diff --git a/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/step-01-clarify-and-route.md b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/step-01-clarify-and-route.md index 5671b6c66..047a2bf7a 100644 --- a/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/step-01-clarify-and-route.md +++ b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/step-01-clarify-and-route.md @@ -1,7 +1,7 @@ --- 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 @@ -13,13 +13,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** → `./step-03-implement.md` + - If `in-review` selected: Set `spec_file`. **EARLY EXIT** → `./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 @@ -35,17 +36,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** → `./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 `./step-03-implement.md` -- Plan-code-review: Read fully and follow `./step-02-plan.md` +Read fully and follow `./step-02-plan.md` diff --git a/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/step-03-implement.md b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/step-03-implement.md index fb596eb79..e90e20731 100644 --- a/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/step-03-implement.md +++ b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/step-03-implement.md @@ -16,7 +16,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. @@ -24,9 +24,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/step-04-review.md b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/step-04-review.md index 154e97d0a..2e4449733 100644 --- a/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/step-04-review.md +++ b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/step-04-review.md @@ -14,7 +14,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}`. @@ -22,9 +22,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. @@ -33,18 +31,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. 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 `./step-05-present.md` diff --git a/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/step-05-present.md b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/step-05-present.md index c71c4d380..fc126443f 100644 --- a/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/step-05-present.md +++ b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/step-05-present.md @@ -12,14 +12,9 @@ ### Generate Suggested Review Order -Determine what changed: +Read `{baseline_commit}` from `{spec_file}` frontmatter and construct the diff of all changes since that commit. -- **Plan-code-review:** Read `{baseline_commit}` from `{spec_file}` frontmatter and construct the diff of all changes since that commit. -- **One-shot:** No baseline exists. Use the files you created or modified during implementation. - -**Plan-code-review:** Append the review order as a `## Suggested Review Order` section to `{spec_file}` **after the last existing section**. Do not modify the Code Map. - -**One-shot:** Display the review order directly in conversation output. +Append the review order as a `## Suggested Review Order` section to `{spec_file}` **after the last existing section**. Do not modify the Code Map. Build the trail as an ordered sequence of **stops** — clickable `path:line` references with brief framing — optimized for a human reviewer reading top-down to understand the change: @@ -53,13 +48,13 @@ When there is only one concern, omit the bold label — just list the stops dire ### Commit and Present -1. **Plan-code-review:** Change `{spec_file}` status to `done` in the frontmatter. -2. If version control is available and the tree is dirty, create a local commit with a conventional message derived from the spec title (plan-code-review) or the intent (one-shot). -3. **Plan-code-review only:** Open the spec in the user's editor so they can click through the Suggested Review Order: +1. Change `{spec_file}` status to `done` in the frontmatter. +2. If version control is available and the tree is dirty, create a local commit with a conventional message derived from the spec title. +3. Open the spec in the user's editor so they can click through the Suggested Review Order: - Run `code -r "{spec_file}"` to open the spec in the current VS Code window (reuses the window where the project or worktree is open). Always double-quote the path to handle spaces and special characters. - If `code` is not available (command fails), skip gracefully and tell the user the spec file path instead. 4. Display summary of your work to the user, including the commit hash if one was created. Include: - - **Plan-code-review:** A note that the spec is open in their editor (or the file path if it couldn't be opened). Mention that `{spec_file}` now contains a Suggested Review Order. + - A note that the spec is open in their editor (or the file path if it couldn't be opened). Mention that `{spec_file}` now contains a Suggested Review Order. - **Navigation tip:** "Ctrl+click (Cmd+click on macOS) the links in the Suggested Review Order to jump to each stop." - Offer to push and/or create a pull request. diff --git a/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/step-oneshot.md b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/step-oneshot.md new file mode 100644 index 000000000..23e476433 --- /dev/null +++ b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/step-oneshot.md @@ -0,0 +1,49 @@ +--- +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}` +- NEVER auto-push. + +## INSTRUCTIONS + +### Implement + +Implement the clarified intent directly. + +### Review + +Invoke the `bmad-review-adversarial-general` skill 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. + +If a finding is caused by this change but too significant for a trivial patch, HALT and present it to the human for decision before proceeding. + +### 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. + +### Present + +1. Open all changed files in the user's editor so they can review the code directly: + - Run `code -r "{project-root}" ` — the project root as the first argument, then each changed file path. Always double-quote paths with spaces. + - If `code` is not available (command fails), skip gracefully and list the file paths instead. +2. Display a summary in conversation output, including: + - The commit hash (if one was created). + - List of files changed with one-line descriptions. + - Review findings breakdown: patches applied, items deferred, items rejected. If all findings were rejected, say so. +3. Offer to push and/or create a pull request. + +HALT and wait for human input. + +Workflow complete.