From 9ca0316674b7284fede4324d335e30a55b0d5406 Mon Sep 17 00:00:00 2001 From: Alex Verkhovsky Date: Tue, 7 Apr 2026 10:14:24 -0700 Subject: [PATCH] refactor(quick-dev): eliminate spec-wip.md singleton (#2214) * refactor(quick-dev): eliminate spec-wip.md singleton Write directly to spec-{slug}.md with status: draft instead of using a shared spec-wip.md file. Use draft status for resume detection in step-01. Removes wipFile variable from all step frontmatter and workflow initialization. Co-Authored-By: Claude Opus 4.6 (1M context) * fix(quick-dev): address PR review findings - step-02: preserve Intent block on draft resume instead of regenerating from template (F1) - step-01: resume existing draft on slug collision rather than creating -2 duplicate (F3) - step-01: recognize `done` status and ingest as context instead of silently re-implementing (F4) - step-oneshot: remove unused spec_file frontmatter declaration (F6) --------- Co-authored-by: Claude Opus 4.6 (1M context) --- .../bmad-quick-dev/step-01-clarify-and-route.md | 9 ++++----- .../bmad-quick-dev/step-02-plan.md | 14 +++++++------- .../bmad-quick-dev/step-oneshot.md | 1 - .../4-implementation/bmad-quick-dev/workflow.md | 6 +----- 4 files changed, 12 insertions(+), 18 deletions(-) diff --git a/src/bmm-skills/4-implementation/bmad-quick-dev/step-01-clarify-and-route.md b/src/bmm-skills/4-implementation/bmad-quick-dev/step-01-clarify-and-route.md index da55cb9a0..5e04d8545 100644 --- a/src/bmm-skills/4-implementation/bmad-quick-dev/step-01-clarify-and-route.md +++ b/src/bmm-skills/4-implementation/bmad-quick-dev/step-01-clarify-and-route.md @@ -1,5 +1,4 @@ --- -wipFile: '{implementation_artifacts}/spec-wip.md' deferred_work_file: '{implementation_artifacts}/deferred-work.md' spec_file: '' # set at runtime for both routes before leaving this step --- @@ -21,7 +20,7 @@ Before listing artifacts or prompting the user, check whether you already know t 1. Explicit argument Did the user pass a specific file path, spec name, or clear instruction this message? - - If it points to a file that matches the spec template (has `status` frontmatter with a recognized value: ready-for-dev, in-progress, or in-review) → set `spec_file` and **EARLY EXIT** to the appropriate step (step-03 for ready/in-progress, step-04 for review). + - If it points to a file that matches the spec template (has `status` frontmatter with a recognized value: draft, ready-for-dev, in-progress, in-review, or done) → set `spec_file` and **EARLY EXIT** to the appropriate step (step-02 for draft, step-03 for ready/in-progress, step-04 for review). For `done`, ingest as context and proceed to INSTRUCTIONS — do not resume. - Anything else (intent files, external docs, plans, descriptions) → ingest it as starting intent and proceed to INSTRUCTIONS. Do not attempt to infer a workflow state from it. 2. Recent conversation @@ -29,8 +28,8 @@ Before listing artifacts or prompting the user, check whether you already know t Use the same routing as above. 3. Otherwise — scan artifacts and ask - - `{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). + - Active specs (`draft`, `ready-for-dev`, `in-progress`, `in-review`) in `{implementation_artifacts}`? → List them and HALT. Ask user which to resume (or `[N]` for new). + - If `draft` selected: Set `spec_file`. **EARLY EXIT** → `./step-02-plan.md` (resume planning from the draft) - 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? → Suggest treating its contents as the starting intent. Do NOT attempt to infer a state and resume it. @@ -65,7 +64,7 @@ Never ask extra questions if you already understand what the user intends. - On **K**: Proceed as-is. 5. Route — choose exactly one: - Derive a valid kebab-case slug from the clarified intent. If the intent references a tracking identifier (story number, issue number, ticket ID), lead the slug with it (e.g. `3-2-digest-delivery`, `gh-47-fix-auth`). If `{implementation_artifacts}/spec-{slug}.md` already exists, append `-2`, `-3`, etc. Set `spec_file` = `{implementation_artifacts}/spec-{slug}.md`. + Derive a valid kebab-case slug from the clarified intent. If the intent references a tracking identifier (story number, issue number, ticket ID), lead the slug with it (e.g. `3-2-digest-delivery`, `gh-47-fix-auth`). If `{implementation_artifacts}/spec-{slug}.md` already exists: if its status is `draft`, treat it as the same work and resume it (set `spec_file` to that path, **EARLY EXIT** → `./step-02-plan.md`); otherwise append `-2`, `-3`, etc. Set `spec_file` = `{implementation_artifacts}/spec-{slug}.md`. **a) One-shot** — zero blast radius: no plausible path by which this change causes unintended consequences elsewhere. Clear intent, no architectural decisions. diff --git a/src/bmm-skills/4-implementation/bmad-quick-dev/step-02-plan.md b/src/bmm-skills/4-implementation/bmad-quick-dev/step-02-plan.md index 361d4c566..2ab75284c 100644 --- a/src/bmm-skills/4-implementation/bmad-quick-dev/step-02-plan.md +++ b/src/bmm-skills/4-implementation/bmad-quick-dev/step-02-plan.md @@ -1,5 +1,4 @@ --- -wipFile: '{implementation_artifacts}/spec-wip.md' deferred_work_file: '{implementation_artifacts}/deferred-work.md' --- @@ -12,11 +11,12 @@ 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 `./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: +1. Draft resume check. If `{spec_file}` exists with `status: draft`, read it and capture the verbatim `...` block as `preserved_intent`. Otherwise `preserved_intent` is empty. +2. Investigate codebase. _Isolate deep exploration in sub-agents/tasks where available. To prevent context snowballing, instruct subagents to give you distilled summaries only._ +3. Read `./spec-template.md` fully. Fill it out based on the intent and investigation. If `{preserved_intent}` is non-empty, substitute it for the `` block in your filled spec before writing. Write the result to `{spec_file}`. +4. Self-review against READY FOR DEVELOPMENT standard. +5. If intent gaps exist, do not fantasize, do not leave open questions, HALT and ask the human. +6. Token count check (see SCOPE STANDARD). If spec exceeds 1600 tokens: - Show user the token count. - HALT and ask human: `[S] Split — carve off secondary goals` | `[K] Keep full spec — accept the risks` - On **S**: Propose the split — name each secondary goal. Append deferred goals to `{deferred_work_file}`. Rewrite the current spec to cover only the main goal — do not surgically carve sections out; regenerate the spec for the narrowed scope. Continue to checkpoint. @@ -26,7 +26,7 @@ deferred_work_file: '{implementation_artifacts}/deferred-work.md' Present summary. If token count exceeded 1600 and user chose [K], include the token count and explain why it may be a problem. HALT and ask human: `[A] Approve` | `[E] Edit` -- **A**: Rename `{wipFile}` to `{spec_file}`, set status `ready-for-dev`. Everything inside `` is now locked — only the human can change it. Display the finalized spec path to the user as a CWD-relative path (no leading `/`) so it is clickable in the terminal. → Step 3. +- **A**: Set status `ready-for-dev` in `{spec_file}`. Everything inside `` is now locked — only the human can change it. Display the finalized spec path to the user as a CWD-relative path (no leading `/`) so it is clickable in the terminal. → Step 3. - **E**: Apply changes, then return to CHECKPOINT 1. diff --git a/src/bmm-skills/4-implementation/bmad-quick-dev/step-oneshot.md b/src/bmm-skills/4-implementation/bmad-quick-dev/step-oneshot.md index b6384159a..0c52d4328 100644 --- a/src/bmm-skills/4-implementation/bmad-quick-dev/step-oneshot.md +++ b/src/bmm-skills/4-implementation/bmad-quick-dev/step-oneshot.md @@ -1,6 +1,5 @@ --- deferred_work_file: '{implementation_artifacts}/deferred-work.md' -spec_file: '' # set by step-01 before entering this step --- # Step One-Shot: Implement, Review, Present diff --git a/src/bmm-skills/4-implementation/bmad-quick-dev/workflow.md b/src/bmm-skills/4-implementation/bmad-quick-dev/workflow.md index f842532bf..55b8fda72 100644 --- a/src/bmm-skills/4-implementation/bmad-quick-dev/workflow.md +++ b/src/bmm-skills/4-implementation/bmad-quick-dev/workflow.md @@ -70,10 +70,6 @@ Load and read full config from `{main_config}` and resolve: YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`. -### 2. Paths - -- `wipFile` = `{implementation_artifacts}/spec-wip.md` - -### 3. First Step Execution +### 2. First Step Execution Read fully and follow: `./step-01-clarify-and-route.md` to begin the workflow.