Convert quick-spec workflow to native skill package#1946
Merged
Conversation
🤖 Augment PR SummarySummary: Converts the Quick Spec workflow into a native skill package so it can be installed/discovered as a skill. Changes:
Technical Notes: Skill discovery relies on 🤖 Was this summary useful? React with 👍 or 👎 |
![augmentcode[bot]](https://avatars.githubusercontent.com/in/1027498?s=60&v=4){kind=small}
| - `[1]` → Read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-02-investigate.md` (Step 2) | ||
| - `[1, 2]` → Read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-03-generate.md` (Step 3) | ||
| - `[1, 2, 3]` → Read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-04-review.md` (Step 4) | ||
| - `[1]` → Read fully and follow: `./steps/step-02-investigate.md` (Step 2) |
There was a problem hiding this comment.
These ./steps/... references are inside a file that already lives under steps/, so when resolved relative to this file they point to steps/steps/... (non-existent) and can break the continue/jump flow. This also appears in other step files, so it may be worth ensuring next-step references are expressed in a way that resolves correctly from the current step file. (Guideline: valid_file_references)
Severity: high
Other Locations
src/bmm/workflows/bmad-quick-flow/bmad-quick-spec/steps/step-01-understand.md:58src/bmm/workflows/bmad-quick-flow/bmad-quick-spec/steps/step-01-understand.md:59src/bmm/workflows/bmad-quick-flow/bmad-quick-spec/steps/step-01-understand.md:170src/bmm/workflows/bmad-quick-flow/bmad-quick-spec/steps/step-02-investigate.md:124src/bmm/workflows/bmad-quick-flow/bmad-quick-spec/steps/step-03-generate.md:115
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
📝 WalkthroughWalkthroughThis change reorganizes the quick-spec workflow by moving it to a new Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 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 |
![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
🧹 Nitpick comments (6)
src/bmm/workflows/bmad-quick-flow/bmad-quick-spec/SKILL.md (1)
6-6: Use the canonical action-instruction verb for delegation.Prefer
Read fully and follow: workflow.mdfor consistency with workflow action directives.Based on learnings: when standardizing action instructions, use “load/read and follow” phrasing for executable directives.
🤖 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-spec/SKILL.md` at line 6, Replace the existing directive "Follow the instructions in [workflow.md]." in SKILL.md with the canonical action-instruction phrasing "Read fully and follow: workflow.md" so the delegation uses the standardized "load/read and follow" verb; update the sentence in src/bmm/workflows/bmad-quick-flow/bmad-quick-spec/SKILL.md (the line containing that directive) to exactly use "Read fully and follow: workflow.md".src/bmm/workflows/bmad-quick-flow/bmad-quick-spec/steps/step-01-understand.md (1)
57-59: Transition targets are repeated literals across the step file.Consolidate next-step targets into reusable variables to reduce maintenance drift during future renames/moves.
Also applies to: 170-170
🤖 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-spec/steps/step-01-understand.md` around lines 57 - 59, The transition links in step-01-understand.md repeatedly inline the same next-step paths (`./steps/step-02-investigate.md`, `./steps/step-03-generate.md`, `./steps/step-04-review.md`); replace these repeated literal targets with single reusable variables/constants (e.g., NEXT_STEP_2, NEXT_STEP_3, NEXT_STEP_4) declared at the top of the spec or in a shared include and then reference those variables in the three list items so future renames/moves require changing only the variable definitions rather than each occurrence.src/bmm/workflows/bmad-quick-flow/bmad-quick-spec/workflow.md (1)
77-77: Entry-step target should be a declared variable, not an inline literal.Declare a
first_stepvariable in frontmatter and reference it here to reduce path-coupling during future reorganizations.🤖 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-spec/workflow.md` at line 77, Declare a frontmatter variable named first_step in this workflow's YAML frontmatter set to the step path (e.g., "./steps/step-01-understand.md") and then replace the inline literal in the entry-step reference ("Read fully and follow: `./steps/step-01-understand.md`") with a reference to that variable (first_step) so the entry-target uses the declared first_step instead of a hard-coded path; update any other occurrences in workflow.md that reference the same path to use first_step as well.src/bmm/workflows/bmad-quick-flow/bmad-quick-spec/steps/step-03-generate.md (1)
115-115: Step transition target is hardcoded and brittle.The next-step path is duplicated across step files. Consider a shared transition variable (frontmatter/workflow-level constant) to reduce rename drift.
🤖 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-spec/steps/step-03-generate.md` at line 115, This step file hardcodes the next-step path ("./steps/step-04-review.md"), causing duplication and rename drift; replace the literal path with a shared transition variable defined in frontmatter (e.g., next_step: step_04_review) or a workflow-level constant (e.g., NEXT_STEP_REVIEW) and update all step files that reference "./steps/step-04-review.md" to use that variable (look for occurrences in step-03-generate.md and other step-*.md files) so renames only need a single change.src/bmm/workflows/bmad-quick-flow/bmad-quick-spec/bmad-skill-manifest.yaml (1)
1-1: Skill identity is implicitly tied to directory name without a guardrail.This works, but a future directory rename will silently change canonical identity. Add a lightweight CI/assertion check in manifest-generation tests to lock expected quick-flow skill IDs.
🤖 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-spec/bmad-skill-manifest.yaml` at line 1, Add a CI-level assertion in the manifest-generation tests to prevent silent identity drift: update the test suite that validates manifests to open bmad-skill-manifest.yaml (the file containing "type: skill") and assert that the computed/declared skill ID equals the canonical expected ID (e.g., the known quick-flow ID for this repo); if the code derives IDs from directory names, compare the derived value to a hard-coded expected string (e.g., "bmad-quick-spec" or the repo's canonical skill id) and fail the test if they differ so future renames will surface as test failures.src/bmm/workflows/bmad-quick-flow/bmad-quick-spec/steps/step-02-investigate.md (1)
124-124: Continue target should be indirected, not literal.Use a variable for the Step 3 target to avoid hardcoded path churn across Step 1/2/3 files.
🤖 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-spec/steps/step-02-investigate.md` at line 124, The continue target is hardcoded as "./steps/step-03-generate.md"; replace that literal with a reusable variable (e.g., a frontmatter key like "nextStep3" or "step3Target") and update the line "IF C: Verify frontmatter updated with `stepsCompleted: [1, 2]`, then read fully and follow: `./steps/step-03-generate.md`" to reference the variable (e.g., "...follow: `{{nextStep3}}`"); ensure the frontmatter in this file defines that variable and that Step 1/3 files use the same variable name for consistency.
🤖 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-spec/steps/step-01-understand.md`:
- Around line 57-59: The menu logic that branches on stepsCompleted (currently
handling only [1], [1, 2], [1, 2, 3]) needs an explicit fallback for malformed
or out-of-order states: update the decision code that determines next step (the
same logic that maps stepsCompleted to links like
./steps/step-02-investigate.md, ./steps/step-03-generate.md,
./steps/step-04-review.md) to detect unexpected arrays/values and present a
repair/reset/archive prompt (e.g., “Reset progress / Repair state / Archive
session”) with a safe default action; implement this as an else/catch branch
that logs the anomaly and routes the user to a clear recovery flow.
---
Nitpick comments:
In `@src/bmm/workflows/bmad-quick-flow/bmad-quick-spec/bmad-skill-manifest.yaml`:
- Line 1: Add a CI-level assertion in the manifest-generation tests to prevent
silent identity drift: update the test suite that validates manifests to open
bmad-skill-manifest.yaml (the file containing "type: skill") and assert that the
computed/declared skill ID equals the canonical expected ID (e.g., the known
quick-flow ID for this repo); if the code derives IDs from directory names,
compare the derived value to a hard-coded expected string (e.g.,
"bmad-quick-spec" or the repo's canonical skill id) and fail the test if they
differ so future renames will surface as test failures.
In `@src/bmm/workflows/bmad-quick-flow/bmad-quick-spec/SKILL.md`:
- Line 6: Replace the existing directive "Follow the instructions in
[workflow.md]." in SKILL.md with the canonical action-instruction phrasing "Read
fully and follow: workflow.md" so the delegation uses the standardized
"load/read and follow" verb; update the sentence in
src/bmm/workflows/bmad-quick-flow/bmad-quick-spec/SKILL.md (the line containing
that directive) to exactly use "Read fully and follow: workflow.md".
In
`@src/bmm/workflows/bmad-quick-flow/bmad-quick-spec/steps/step-01-understand.md`:
- Around line 57-59: The transition links in step-01-understand.md repeatedly
inline the same next-step paths (`./steps/step-02-investigate.md`,
`./steps/step-03-generate.md`, `./steps/step-04-review.md`); replace these
repeated literal targets with single reusable variables/constants (e.g.,
NEXT_STEP_2, NEXT_STEP_3, NEXT_STEP_4) declared at the top of the spec or in a
shared include and then reference those variables in the three list items so
future renames/moves require changing only the variable definitions rather than
each occurrence.
In
`@src/bmm/workflows/bmad-quick-flow/bmad-quick-spec/steps/step-02-investigate.md`:
- Line 124: The continue target is hardcoded as "./steps/step-03-generate.md";
replace that literal with a reusable variable (e.g., a frontmatter key like
"nextStep3" or "step3Target") and update the line "IF C: Verify frontmatter
updated with `stepsCompleted: [1, 2]`, then read fully and follow:
`./steps/step-03-generate.md`" to reference the variable (e.g., "...follow:
`{{nextStep3}}`"); ensure the frontmatter in this file defines that variable and
that Step 1/3 files use the same variable name for consistency.
In `@src/bmm/workflows/bmad-quick-flow/bmad-quick-spec/steps/step-03-generate.md`:
- Line 115: This step file hardcodes the next-step path
("./steps/step-04-review.md"), causing duplication and rename drift; replace the
literal path with a shared transition variable defined in frontmatter (e.g.,
next_step: step_04_review) or a workflow-level constant (e.g., NEXT_STEP_REVIEW)
and update all step files that reference "./steps/step-04-review.md" to use that
variable (look for occurrences in step-03-generate.md and other step-*.md files)
so renames only need a single change.
In `@src/bmm/workflows/bmad-quick-flow/bmad-quick-spec/workflow.md`:
- Line 77: Declare a frontmatter variable named first_step in this workflow's
YAML frontmatter set to the step path (e.g., "./steps/step-01-understand.md")
and then replace the inline literal in the entry-step reference ("Read fully and
follow: `./steps/step-01-understand.md`") with a reference to that variable
(first_step) so the entry-target uses the declared first_step instead of a
hard-coded path; update any other occurrences in workflow.md that reference the
same path to use first_step as well.
🪄 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: 22461fcb-743b-4153-af46-cff66bd1f173
⛔ Files ignored due to path filters (1)
src/bmm/module-help.csvis excluded by!**/*.csv
📒 Files selected for processing (11)
src/bmm/agents/quick-flow-solo-dev.agent.yamlsrc/bmm/workflows/bmad-quick-flow/bmad-quick-spec/SKILL.mdsrc/bmm/workflows/bmad-quick-flow/bmad-quick-spec/bmad-skill-manifest.yamlsrc/bmm/workflows/bmad-quick-flow/bmad-quick-spec/steps/step-01-understand.mdsrc/bmm/workflows/bmad-quick-flow/bmad-quick-spec/steps/step-02-investigate.mdsrc/bmm/workflows/bmad-quick-flow/bmad-quick-spec/steps/step-03-generate.mdsrc/bmm/workflows/bmad-quick-flow/bmad-quick-spec/steps/step-04-review.mdsrc/bmm/workflows/bmad-quick-flow/bmad-quick-spec/tech-spec-template.mdsrc/bmm/workflows/bmad-quick-flow/bmad-quick-spec/workflow.mdsrc/bmm/workflows/bmad-quick-flow/quick-dev/workflow.mdsrc/bmm/workflows/bmad-quick-flow/quick-spec/bmad-skill-manifest.yaml
💤 Files with no reviewable changes (1)
- src/bmm/workflows/bmad-quick-flow/quick-spec/bmad-skill-manifest.yaml
Comment on lines
+57
to
+59
| - `[1]` → Read fully and follow: `./steps/step-02-investigate.md` (Step 2) | ||
| - `[1, 2]` → Read fully and follow: `./steps/step-03-generate.md` (Step 3) | ||
| - `[1, 2, 3]` → Read fully and follow: `./steps/step-04-review.md` (Step 4) |
There was a problem hiding this comment.
Resume routing has no safe default for unexpected stepsCompleted states.
The menu only enumerates [1], [1, 2], [1, 2, 3]. Add an explicit fallback branch (repair/reset/archive prompt) for malformed or out-of-order state.
🤖 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-spec/steps/step-01-understand.md`
around lines 57 - 59, The menu logic that branches on stepsCompleted (currently
handling only [1], [1, 2], [1, 2, 3]) needs an explicit fallback for malformed
or out-of-order states: update the decision code that determines next step (the
same logic that maps stepsCompleted to links like
./steps/step-02-investigate.md, ./steps/step-03-generate.md,
./steps/step-04-review.md) to detect unexpected arrays/values and present a
repair/reset/archive prompt (e.g., “Reset progress / Repair state / Archive
session”) with a safe default action; implement this as an else/catch branch
that logs the anomaly and routes the user to a clear recovery flow.
alexeyv
force-pushed
the
convert-quick-spec-skill
branch
2 times, most recently
from
f5c75e9 to
813089a
Compare
The agent menu entry for QS was still using a raw file path instead of the skill dispatcher, inconsistent with module-help.csv. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Step files are inside steps/ so inter-step references must be ./step-NN.md not ./steps/step-NN.md (which would double-nest). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
alexeyv
force-pushed
the
convert-quick-spec-skill
branch
from
813089a to
3678dbe
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
src/bmm/workflows/bmad-quick-flow/quick-specto native skill packagesrc/bmm/workflows/bmad-quick-flow/bmad-quick-spectype: skill) and addedSKILL.mdsrc/bmm/module-help.csv(workflow-filetoskill:bmad-quick-spec)src/bmm/agents/quick-flow-solo-dev.agent.yaml(exectoskill:bmad-quick-spec)src/bmm/workflows/bmad-quick-flow/quick-dev/workflow.mdquick-spec cross-reference to renamed pathValidation
workflow.mdand all four step files (metadata/path deltas only)tech-spec-template.mdnode tools/cli/bmad-cli.js install --directory /Users/alex/src/bmad --modules bmm --tools claude-code --yes.claude/skills/bmad-quick-spec/with generatedSKILL.md_bmad/_config/skill-manifest.csvcontainsbmad-quick-spec_bmad/_config/workflow-manifest.csvhas nobmad-quick-specentrynpm test(passes)Deferrals
/Users/alex/src/bmad/_bmad-output/implementation-artifacts/deferred-work.mdfor this conversion pass (non-interactive terminal execution)