refactor(quick-dev): eliminate spec-wip.md singleton

[alexeyv]

Summary

• Removes the shared spec-wip.md file path, which caused parallel quick-dev sessions to overwrite each other's drafts
• Step-02 now writes directly to spec-{slug}.md with status: draft; approval flips status in-place instead of renaming
• Step-01 scans for draft status alongside existing statuses (ready-for-dev, in-progress, in-review) for resume detection

Test plan

• Run quick-dev with a new intent -- verify spec is written to spec-{slug}.md (not spec-wip.md) with status: draft
• Approve at CHECKPOINT 1 -- verify status flips to ready-for-dev in-place, no file rename
• Abandon a session mid-draft, restart quick-dev -- verify the draft appears in the resume list
• Pass a draft spec as an explicit argument -- verify it routes to step-02
• grep -r wipFile or spec-wip across quick-dev step files returns no matches

Generated with Claude Code

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 4d62e6cc-87de-4869-ad91-c8c713d9327b

📥 Commits

Reviewing files that changed from the base of the PR and between aefabc7 and 6e052c9.

📒 Files selected for processing (3)

• src/bmm-skills/4-implementation/bmad-quick-dev/step-01-clarify-and-route.md
• src/bmm-skills/4-implementation/bmad-quick-dev/step-02-plan.md
• src/bmm-skills/4-implementation/bmad-quick-dev/workflow.md

---

📝 Walkthrough

Walkthrough

This pull request updates the BMM quick-dev workflow documentation to recognize draft as an active spec state in Step 1 routing, adds draft-to-step-02 navigation with early exit, and removes the wipFile frontmatter pattern across all workflow steps, replacing it with runtime spec_file initialization.

Changes

Cohort / File(s)	Summary
Quick-dev workflow documentation src/bmm-skills/4-implementation/bmad-quick-dev/step-01-clarify-and-route.md, step-02-plan.md, workflow.md	Removes wipFile frontmatter declaration and pattern; adds draft status as a resumable spec state in Step 1 with early exit routing to step-02; updates Step 2 to write filled specs to {spec_file} instead of {wipFile} and sets status directly in target file rather than renaming.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• refactor(quick-dev): rename tech-spec prefix to spec #2109: Modifies the same quick-dev workflow documentation (step-01, step-02, workflow.md) with overlapping changes to WIP/spec file frontmatter and naming patterns.
• refactor(quick-flow): separate one-shot into self-contained step file #2044: Adjusts step-01 routing and spec_file/frontmatter handling, introducing early exit routing paths similar to the draft handling in this PR.
• feat(quick-dev): clickable spec link at step-02 checkpoint and CWD-relative path convention #2049: Updates step-02 plan behavior around finalized spec file paths, directly related to the shift from wipFile to {spec_file} pattern.

Suggested reviewers

• bmadcode
• pbean

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'refactor(quick-dev): eliminate spec-wip.md singleton' clearly and specifically describes the main change: removing the shared spec-wip.md file path that caused conflicts in parallel sessions.
Description check	✅ Passed	The description is well-related to the changeset, explaining the rationale (parallel session conflicts), the solution (direct writes with draft status), and changes to routing logic.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch refactor/eliminate-wip-file

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[alexeyv]

@CodeRabbit ?

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Read all three changed files
echo "=== workflow.md ==="
cat src/bmm-skills/4-implementation/bmad-quick-dev/workflow.md

echo ""
echo "=== step-01-clarify-and-route.md ==="
cat src/bmm-skills/4-implementation/bmad-quick-dev/step-01-clarify-and-route.md

echo ""
echo "=== step-02-plan.md ==="
cat src/bmm-skills/4-implementation/bmad-quick-dev/step-02-plan.md

echo ""
echo "=== Check for any remaining wipFile / spec-wip references ==="
rg -rn "wipFile|spec-wip" src/bmm-skills/4-implementation/bmad-quick-dev/

Length of output: 11700

---

@alexeyv The refactor looks solid. Here's the review:

---

✅ What's correct

• Clean sweep: no wipFile or spec-wip references remain anywhere in the skill directory.
• step-01 routing is complete: all four entry paths (explicit arg, recent conversation, artifact scan, new intent) correctly set spec_file before any EARLY EXIT. The new draft branch in the scan section is consistent in structure with the existing ready-for-dev / in-progress / in-review branches.
• step-02 [A] action: flipping status: ready-for-dev in-place in {spec_file} is simpler and correct — eliminates the rename entirely.
• workflow.md: renumbering is clean; the removed "Paths" section was the only place wipFile was declared globally.

---

⚠️ Minor gap — status: draft not explicit in step-02 instruction #2

Step-02 instruction #2 currently reads:

Fill it out based on the intent and investigation, and write the result to {spec_file}.

The PR description states that the spec should be written with status: draft. This is presumably true because spec-template.md already carries status: draft as a default field — but instruction #2 is silent about it. If the template ever changes (or an agent fills in a different status), there's no guardrail.

A one-line clarification would close the gap:

- 2. Read `./spec-template.md` fully. Fill it out based on the intent and investigation, and write the result to `{spec_file}`.
+ 2. Read `./spec-template.md` fully. Fill it out based on the intent and investigation, and write the result to `{spec_file}` with `status: draft`.

This makes the initial status an explicit contract, consistent with what step-01 now scans for and what the [A] action flips away from.

---

Everything else — the frontmatter changes, the routing logic, and the no-rename approval flow — is correct and well-structured. The fix above is minor but worth locking in since the whole parallel-session isolation relies on that draft status being reliably present for step-01's scan to detect.

---

🧠 Learnings used

Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1876
File: src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-05-present.md:15-16
Timestamp: 2026-03-11T18:02:12.404Z
Learning: In BMAD-METHOD bmad-quick-dev-new-preview step-05-present.md (src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-05-present.md), setting the `{spec_file}` frontmatter status to `done` before displaying the summary and before any explicit human approval is intentional by design. The workflow treats the spec as finalized at the presentation stage; human review and further revision happen at the user's discretion after presentation. Reviewers must not flag this ordering as premature finalization or request a gating approval step before the status is written.

---

Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1807
File: src/bmm/workflows/bmad-quick-flow/quick-dev2/steps/step-04-review.md:30-30
Timestamp: 2026-03-02T23:53:14.803Z
Learning: In BMAD-METHOD quick-dev2 workflow, one-shot mode relies on session knowledge: the agent executing step-03-implement.md tracks which files it modified in-session, and step-04-review.md invokes `{adversarial_review_task}` with those changed files without constructing a VCS diff. The `baseline_commit` mechanism is only used in plan-code-review mode, not one-shot.

---

Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1896
File: src/core/tasks/bmad-shard-doc/workflow.md:73-86
Timestamp: 2026-03-11T21:28:59.373Z
Learning: In BMAD-METHOD, the missing HALT/error-handling paths in the "Handle Original Document" step of src/core/tasks/bmad-shard-doc/workflow.md (delete and move branches, lines ~73-86) — specifically the absence of failure checks after the delete, mkdir, and move operations before printing confirmation messages — are pre-existing behavior carried over verbatim from the original src/core/tasks/shard-doc.xml. PR `#1896` is a pure format conversion (XML task → native skill directory) with no behavioral changes. Reviewers must not flag these missing error paths as regressions introduced by the conversion; any behavioral improvements (e.g., adding HALT on failure for filesystem ops) should be addressed in a dedicated follow-up PR.

---

Learnt from: n-zhi
Repo: bmad-code-org/BMAD-METHOD PR: 1817
File: tools/cli/installers/lib/ide/templates/combined/antigravity-workflow-yaml.md:13-13
Timestamp: 2026-03-05T14:31:20.599Z
Learning: In BMAD-METHOD, the "Save outputs after EACH section when generating any documents from templates" directive in antigravity-workflow-yaml.md (tools/cli/installers/lib/ide/templates/combined/antigravity-workflow-yaml.md) is a pre-existing pattern inherited verbatim from the corresponding default-*.md template. It is not introduced by PR `#1817`. A future dedicated PR should make this save step conditional and idempotent: consult an artifact policy flag before persisting, use overwrite/merge/versioned semantics, perform atomic writes, and redact sensitive keys—applied holistically across all affected default-*.md and antigravity-*.md templates.

---

Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1896
File: src/core/tasks/bmad-shard-doc/workflow.md:79-85
Timestamp: 2026-03-11T21:29:04.747Z
Learning: In BMAD-METHOD, the archive branch in src/core/tasks/bmad-shard-doc/workflow.md (Step 6, "If user selects m (move)") does not check whether the archive destination path already exists before moving the original document, risking a silent overwrite on reruns. This is pre-existing behavior carried over verbatim from the original src/core/tasks/shard-doc.xml. PR `#1896` is a faithful format conversion (XML task → native skill directory) and does not change workflow logic. Reviewers must not flag the missing existence check / overwrite guard as a regression introduced by this conversion; any behavioral fix (e.g., prompting user to confirm overwrite, generating a non-colliding name) should be addressed in a dedicated follow-up PR.

---

Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1934
File: src/bmm/workflows/2-plan-workflows/bmad-create-ux-design/steps/step-02-discovery.md:158-162
Timestamp: 2026-03-13T21:43:13.299Z
Learning: In BMAD-METHOD, converted-workflow native skills (e.g., src/bmm/workflows/2-plan-workflows/bmad-create-ux-design/) use a different `./` path resolution convention from `bmad-quick-dev-new-preview`-style skills. In step files located inside a `steps/` subdirectory of a converted-workflow skill, `./` resolves relative to the file's own directory (`steps/`), not relative to the skill root. Therefore `./step-03-core-experience.md` inside `steps/step-02-discovery.md` correctly resolves to `steps/step-03-core-experience.md`. Only `workflow.md` at the skill root needs the `./steps/` prefix to reach step files. Reviewers must not apply the skill-root resolution rule from learning 1647d05b (scoped to bmad-quick-dev-new-preview) to converted-workflow skills.

---

Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1860
File: src/bmm/workflows/4-implementation/code-review/workflow.md:60-65
Timestamp: 2026-03-08T17:15:57.663Z
Learning: In BMAD-METHOD code-review workflow (src/bmm/workflows/4-implementation/code-review/workflow.md), the `{{story_path}}` input parameter used in Step 1 ("Use provided {{story_path}} or ask user which story file to review") is not declared in the Input Files table or Configuration Loading section. This is a pre-existing issue inherited from the original instructions.xml, not introduced by the yaml-to-md conversion PR `#1860`. Reviewers should not flag the absence of a formal `{{story_path}}` declaration in conversion PRs; any addition of this parameter to the inputs table should be addressed in a dedicated behavioral follow-up PR.

---

Learnt from: anderewrey
Repo: bmad-code-org/BMAD-METHOD PR: 1826
File: src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-04-final-validation.md:113-118
Timestamp: 2026-03-06T02:00:43.563Z
Learning: In BMAD-METHOD, step-04-final-validation.md (src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-04-final-validation.md) runs in the same single LLM agent session as step-02 (epic design) and step-03 (story creation). The agent retains full in-context knowledge of the architecture, PRD, and all epics/stories it designed. Validation checks such as the File Churn Check (Epic Structure Validation) do not require formal serialized data structures (e.g., affected_files arrays, rationale template fields, or numeric overlap thresholds) because the agent can assess file overlap and recall consolidation decisions from its own session context. Reviewers should not flag the absence of these structures as making the validation unexecutable.

---

Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1862
File: src/bmm/workflows/4-implementation/create-story/workflow.md:63-66
Timestamp: 2026-03-08T18:12:38.710Z
Learning: In BMAD-METHOD create-story workflow (src/bmm/workflows/4-implementation/create-story/workflow.md), the `GOTO step 2a` references throughout Step 1 (and corresponding locations at lines 89-97, 159, 216) are pre-existing issues inherited verbatim from the original instructions.xml. The original instructions.xml (commit 09ce855) already had `GOTO step 2a` at lines 24, 50, 55, 117, and 174 but defined only `<step n="2">` — no `<step n="2a">` label existed. This is not a regression introduced by the yaml-to-md conversion PR `#1862`. Reviewers should not flag these GOTO targets as a conversion regression; any fix should be addressed in a dedicated behavioral follow-up PR.

---

Learnt from: alexeyv
Repo: bmad-code-org/BMAD-METHOD PR: 1807
File: src/bmm/workflows/bmad-quick-flow/quick-dev2/steps/step-01-clarify-and-route.md:21-24
Timestamp: 2026-03-02T23:53:06.292Z
Learning: In BMAD-METHOD workflows (quick-spec, quick-dev, quick-dev2), "skip to step X" instructions based on detected artifact state constitute state-aware routing, not prohibited optimization skipping. The "NEVER skip steps" rule in workflow.md prohibits agents from autonomously optimizing the sequence for efficiency, but does not prohibit state-aware routing to appropriate resumption points when pre-existing artifacts are detected (e.g., specs with status `ready-for-dev`, `in-progress`, or `in-review`).