feat(quick-dev): add VS Code opening ergonomics to step 5#2039
Conversation
Replace vscode://file/ absolute URI links with workspace-root-relative markdown links using #L anchors — portable across machines and worktrees. Add code -r open-in-editor step with graceful fallback, and Ctrl+click navigation tip for reviewers.
📝 WalkthroughWalkthroughUpdated step-05-present.md workflow documentation to replace absolute vscode:// file references with workspace-relative links, added editor-opening functionality for spec files with graceful fallback, and updated navigation guidance to include editor-open feedback. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
📝 Coding Plan
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. Comment Tip CodeRabbit can generate a title for your PR based on the changes.Add |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In
`@src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/step-05-present.md`:
- Line 30: Update the instruction text in step-05-present.md to capitalize
"Markdown" where it currently reads "markdown link"; locate the sentence
describing code reference links (the bulleted rule that starts "Every code
reference is a clickable workspace-relative link") and change "markdown link" to
"Markdown link" so the term is properly capitalized in the documentation.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 4c547382-6440-4640-8265-675c8d3d96c5
📒 Files selected for processing (1)
src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/step-05-present.md
| 3. **Inside each concern**, order stops from most important / architecturally interesting to supporting. Lightly bias toward higher-risk or boundary-crossing stops. | ||
| 4. **End with peripherals** — tests, config, types, and other supporting changes come last. | ||
| 5. **Every code reference is a clickable `vscode://file/` link.** Format each stop as a markdown link: `[short-name:line](vscode://file/absolute/path:line:1)`. Use the file's basename (or shortest unambiguous suffix) as the link text. | ||
| 5. **Every code reference is a clickable workspace-relative link.** Format each stop as a markdown link: `[short-name:line](/project-root-relative/path/to/file.ts#L42)`. The link target uses a leading `/` (workspace root) with a `#L` line anchor. Use the file's basename (or shortest unambiguous suffix) plus line number as the link text. |
There was a problem hiding this comment.
Capitalize “Markdown” in instruction text.
Tiny docs-quality nit: “markdown link” → “Markdown link.”
🧰 Tools
🪛 LanguageTool
[uncategorized] ~30-~30: Did you mean the formatting language “Markdown” (= proper noun)?
Context: ...-relative link.** Format each stop as a markdown link: `[short-name:line](/project-root-...
(MARKDOWN_NNP)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In
`@src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/step-05-present.md`
at line 30, Update the instruction text in step-05-present.md to capitalize
"Markdown" where it currently reads "markdown link"; locate the sentence
describing code reference links (the bulleted rule that starts "Every code
reference is a clickable workspace-relative link") and change "markdown link" to
"Markdown link" so the term is properly capitalized in the documentation.
🤖 Augment PR SummarySummary: Updates Quick Dev step 5 to generate VS Code-friendly, workspace-root-relative Suggested Review Order links (instead of machine-specific 🤖 Was this summary useful? React with 👍 or 👎 |
![augmentcode[bot]](https://avatars.githubusercontent.com/in/1027498?s=60&v=4){kind=small}
| 3. **Inside each concern**, order stops from most important / architecturally interesting to supporting. Lightly bias toward higher-risk or boundary-crossing stops. | ||
| 4. **End with peripherals** — tests, config, types, and other supporting changes come last. | ||
| 5. **Every code reference is a clickable `vscode://file/` link.** Format each stop as a markdown link: `[short-name:line](vscode://file/absolute/path:line:1)`. Use the file's basename (or shortest unambiguous suffix) as the link text. | ||
| 5. **Every code reference is a clickable workspace-relative link.** Format each stop as a markdown link: `[short-name:line](/project-root-relative/path/to/file.ts#L42)`. The link target uses a leading `/` (workspace root) with a `#L` line anchor. Use the file's basename (or shortest unambiguous suffix) plus line number as the link text. |
There was a problem hiding this comment.
The new workspace-root-relative link format (/path#L42) works in VS Code, but if {spec_file} is read in other renderers (e.g., GitHub web UI) these /... links won’t resolve to repo files. If the spec is expected to be consumed outside VS Code, it may be worth explicitly calling out that these links are intended for editor navigation.
Severity: low
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
| 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. Display summary of your work to the user, including the commit hash if one was created. Advise on how to review the changes — for plan-code-review, mention that `{spec_file}` now contains a Suggested Review Order. Offer to push and/or create a pull request. | ||
| 3. Open the spec in the user's editor so they can click through the Suggested Review Order: |
There was a problem hiding this comment.
In execution_mode = "one-shot", this step says the Suggested Review Order is shown in conversation output (not appended to {spec_file}), so opening {spec_file} here may not actually let the user click through the review stops. Consider clarifying that this “open spec to click through” behavior is plan-code-review-only, or ensuring one-shot also writes the section into {spec_file}.
Severity: medium
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
| 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. Display summary of your work to the user, including the commit hash if one was created. Advise on how to review the changes — for plan-code-review, mention that `{spec_file}` now contains a Suggested Review Order. Offer to push and/or create a pull request. | ||
| 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). |
There was a problem hiding this comment.
When running code -r {spec_file}, if {spec_file} can include spaces or shell-sensitive characters, the command may fail unless it’s properly quoted/escaped by whatever executes it. It could be helpful to specify the expected quoting/escaping behavior (or show it in the command example).
Severity: low
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
Ensure paths with spaces or special characters are handled correctly
by double-quoting the {spec_file} variable in the editor open command.
One-shot mode displays the review order in conversation output and has no spec file to open. Guard the code -r step and spec-specific summary items behind plan-code-review.
1 participant
Summary
vscode://file/absolute URI links in Suggested Review Order with workspace-root-relative markdown links using#Lanchors — portable across machines and worktreescode -r {spec_file}open-in-editor step after commit with graceful fallback when VS Code CLI unavailableContext
Story 1.2 from the av-hitl-review implementation plan. Builds on Story 1.1 (PR #2033) which added the Suggested Review Order generation.
Research confirmed VS Code natively supports
[text](/path#L42)in markdown since v1.63 for all file types. Thevscode://file/format required absolute paths, broke across machines, and locked to a single editor.Test plan
[name:line](/path#L42)links instead ofvscode://file/URIscode -ropens the spec in the existing VS Code window (not a new one)codeCLI unavailable — verify step 5 prints the spec path and continues gracefully