feat(quick-dev): one-shot route generates spec trace file by alexeyv · Pull Request #2121 · bmad-code-org/BMAD-METHOD

alexeyv · 2026-03-25T05:14:32Z

Summary

One-shot route now generates a lightweight spec file (spec-{slug}.md) with frontmatter, intent summary, and suggested review order — eliminating numbering gaps when quick-dev is used as the primary dev loop
Step-01 derives a slug and sets spec_file for both routes (not just plan-code-review)
Step-oneshot reuses the spec template (fill Intent + Review Order, delete the rest) instead of inlining structure, and opens the spec in VS Code like step-05 does

Test plan

Run quick-dev workflow with a trivial one-shot change and verify a spec-{slug}.md trace file appears in {implementation_artifacts}
Verify the generated file has frontmatter with status: done and route: one-shot
Verify Suggested Review Order links are clickable (spec-file-relative) in VS Code
Verify terminal output uses CWD-relative :line paths
npm run validate:skills passes (confirmed locally)

🤖 Generated with Claude Code

One-shot changes now leave a lightweight spec file with frontmatter, intent summary, and suggested review order — eliminating numbering gaps when quick-dev is used as the primary dev loop. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…cture Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

augmentcode · 2026-03-25T05:18:06Z

🤖 Augment PR Summary

Summary: Updates the bmad-quick-dev workflow so the one-shot route produces a lightweight spec “trace” file for review/navigation.

Changes:

Step 1 now derives a slug and sets spec_file for both one-shot and plan-code-review routes
One-shot flow generates spec-{slug}.md from spec-template.md (frontmatter + intent + suggested review order)
One-shot presentation opens the generated spec in VS Code and clarifies path/link conventions for terminal vs spec links

_{🤖 Was this summary useful? React with 👍 or 👎}

augmentcode

Review completed. 3 suggestions posted.

Comment augment review to trigger a new review at any time.

augmentcode · 2026-03-25T05:18:07Z

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

 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.
+   1. 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`.


{slug} is used like a workflow variable in the spec-{slug}.md path, but it isn’t defined in this step’s frontmatter or workflow.md; this can violate the skill validation requirement that {...} references be defined. If this is intended as a literal placeholder for the human/agent to substitute, consider avoiding brace-form here so it won’t be treated as a variable. (Guideline: skill_validation)

Severity: medium

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}

src/bmm-skills/4-implementation/bmad-quick-dev/step-oneshot.md

augmentcode · 2026-03-25T05:18:07Z

src/bmm-skills/4-implementation/bmad-quick-dev/step-oneshot.md

+Write `{spec_file}` using `./spec-template.md`. Fill only these sections — delete all others:
+
+1. **Frontmatter** — fill `title`, `type`, `created`, `status: 'done'`. Add `route: 'one-shot'`.
+2. **Title and Intent** — `# {title}` heading and `## Intent` with **Problem** and **Approach** lines. Reuse the summary you already generated for the terminal.


The inline {title} in # {title} looks like a variable reference rather than a human-filled placeholder, which can trip variable-resolution/validation rules if title isn’t a defined runtime/config variable. If it’s meant to be literal placeholder text, consider representing it without {...} so it won’t be interpreted as a variable. (Guideline: skill_validation)

Severity: medium

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}

coderabbitai · 2026-03-25T05:19:40Z

📝 Walkthrough

Walkthrough

Updated the one-shot workflow path to derive slug-based spec file names during routing and introduced a "Generate Spec Trace" phase that creates the spec file from a template. Modified the presentation phase to open the generated spec file with VS Code instead of all changed files.

Changes

Cohort / File(s)	Summary
Workflow Routing & Spec Generation `src/bmm-skills/4-implementation/bmad-quick-dev/step-01-clarify-and-route.md`, `step-oneshot.md`	Extended one-shot path to derive kebab-case slugs for spec file selection (with collision handling via `-2`, `-3` suffixes), and introduced "Generate Spec Trace" phase that populates spec from template. Updated presentation to open only the generated spec file via `code -r` with fallback to path reporting, and revised conversation summary to include CWD-relative file references and navigation guidance for the spec's Suggested Review Order.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

fix(quick-dev): use absolute paths in code -r invocations #2087: Modifies the code -r invocation and file path arguments in the Present step of step-oneshot.md, directly overlapping with the editor-opening logic changes in this PR.
fix(quick-dev): preserve tracking identifiers in spec slug #2108: Extends slug-derivation behavior in step-01-clarify-and-route.md to ensure tracking identifiers are preserved, which directly relates to the slug-based spec file selection added here.
fix(quick-dev): make file path references clickable #2085: Modifies the one-shot "Present" behavior in step-oneshot.md to change how the spec is opened and presented, overlapping with the presentation phase updates in this PR.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: implementing spec trace file generation in the one-shot route of the quick-dev workflow.
Description check	✅ Passed	The description is directly related to the changeset, covering the spec file generation, slug derivation, template reuse, and VS Code integration mentioned in the file summaries.
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 oneshot-spec-trace

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

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

coderabbitai

🧹 Nitpick comments (1)

src/bmm-skills/4-implementation/bmad-quick-dev/step-01-clarify-and-route.md (1)
56-57: Consider extracting the duplicated slug derivation logic.

The slug derivation and spec_file assignment logic is identical between the one-shot route (lines 56-57) and the plan-code-review route (line 61). This duplication creates a maintenance burden if the logic needs updating.

Consider extracting this into a shared instruction block referenced by both routes, or document that changes to one must be mirrored to the other.

Also applies to: 61-61
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@src/bmm-skills/4-implementation/bmad-quick-dev/step-01-clarify-and-route.md`
around lines 56 - 57, The duplicated slug derivation and spec_file assignment
used in the one-shot route and the plan-code-review route should be extracted
into a single reusable instruction block (e.g., derive_spec_slug or
spec_slug_derivation) and invoked by both routes; update the two places to call
this shared block and remove the duplicated steps so changes to kebab-case slug
rules, tracking-id prefixing, and existing-file suffixing (`-2`, `-3`, etc.) are
made in one spot, or alternatively add a clear comment referencing the other
route to ensure both are kept in sync.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@src/bmm-skills/4-implementation/bmad-quick-dev/step-01-clarify-and-route.md`:
- Around line 56-57: The duplicated slug derivation and spec_file assignment
used in the one-shot route and the plan-code-review route should be extracted
into a single reusable instruction block (e.g., derive_spec_slug or
spec_slug_derivation) and invoked by both routes; update the two places to call
this shared block and remove the duplicated steps so changes to kebab-case slug
rules, tracking-id prefixing, and existing-file suffixing (`-2`, `-3`, etc.) are
made in one spot, or alternatively add a clear comment referencing the other
route to ensure both are kept in sync.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 9497eba0-cad7-4352-8952-fa36e29b2905

📥 Commits

Reviewing files that changed from the base of the PR and between cfe40fc and 4acc0fd.

📒 Files selected for processing (2)

src/bmm-skills/4-implementation/bmad-quick-dev/step-01-clarify-and-route.md
src/bmm-skills/4-implementation/bmad-quick-dev/step-oneshot.md

alexeyv and others added 2 commits March 24, 2026 23:01

refactor(quick-dev): reference spec template instead of inlining stru…

4acc0fd

…cture Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

augmentcode bot reviewed Mar 25, 2026

View reviewed changes

coderabbitai bot reviewed Mar 25, 2026

View reviewed changes

Merge branch 'main' into oneshot-spec-trace

e45e5b5

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(quick-dev): one-shot route generates spec trace file#2121

feat(quick-dev): one-shot route generates spec trace file#2121
alexeyv wants to merge 3 commits intomainfrom
oneshot-spec-trace

alexeyv commented Mar 25, 2026

Uh oh!

augmentcode bot commented Mar 25, 2026

Uh oh!

augmentcode bot left a comment

Uh oh!

augmentcode bot Mar 25, 2026

Uh oh!

Uh oh!

augmentcode bot Mar 25, 2026

Uh oh!

coderabbitai bot commented Mar 25, 2026

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Uh oh!

coderabbitai bot left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

alexeyv commented Mar 25, 2026

Summary

Test plan

Uh oh!

augmentcode bot commented Mar 25, 2026

Uh oh!

augmentcode bot left a comment

Choose a reason for hiding this comment

Uh oh!

augmentcode bot Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

augmentcode bot Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

coderabbitai bot commented Mar 25, 2026

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant