chore(bmm): complete quick-dev-new-preview native skill metadata#1947
chore(bmm): complete quick-dev-new-preview native skill metadata#1947
Conversation
🤖 Augment PR SummarySummary: Completes native-skill metadata for the Changes:
🤖 Was this summary useful? React with 👍 or 👎 |
![augmentcode[bot]](https://avatars.githubusercontent.com/in/1027498?s=60&v=4){kind=small}
| @@ -1,4 +1,6 @@ | |||
| --- | |||
| name: bmad-quick-dev-new-preview | |||
There was a problem hiding this comment.
Consider adding an installed_path frontmatter field as well, since this workflow later references relative files like ./tech-spec-template.md and ./steps/... (see (Guideline: workflow_installed_path)). Without it, relative references may resolve differently depending on how/where the workflow is installed/executed.
Severity: medium
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
alexeyv
force-pushed
the
convert-quick-dev-new-preview-skill
branch
from
3c54553 to
1f0cf05
Compare
📝 WalkthroughWalkthroughAdded frontmatter metadata (name and description fields) to a workflow markdown file. No changes to workflow logic, steps, or control flow. The modification is purely declarative documentation addition. Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~2 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.
🧹 Nitpick comments (7)
src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/workflow.md (7)
3-3: Description uses subjective term "clean" without definition.What does "clean working code artifacts" mean? The term "clean" is subjective and varies by developer, team, and context. Does it mean:
- Passes linting?
- Follows project conventions?
- Has no code smells?
- Meets quality gates?
- Something else?
Without definition, this term creates ambiguity about what the workflow guarantees. The word "working" is more concrete (functionality meets acceptance criteria), but "clean" is a value judgment that should either be defined or removed.
Proposed fix
-description: 'Implements any user intent, requirement, story, bug fix or change request by producing clean working code artifacts that follow the project''s existing architecture, patterns and conventions. Use when the user wants to build, fix, tweak, refactor, add or modify any code, component or feature.' +description: 'Implements code-focused requirements, stories, bug fixes, and change requests by producing working code artifacts that follow the project''s existing architecture, patterns and conventions. Use for building, fixing, refactoring, or modifying code, components, or features.'🤖 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/workflow.md` at line 3, Update the description to remove or define the subjective term "clean": replace "clean working code artifacts" with a concrete, measurable checklist (e.g., "working code artifacts that pass project linting and type checks, follow existing architecture/conventions, include unit/integration tests for new behavior, and contain necessary documentation/README updates and changelog entries"); edit the description line in workflow.md (the description string) so it references these specific criteria instead of the word "clean" to remove ambiguity.
2-3: Missing version metadata — no way to track frontmatter evolution.If this frontmatter is being added to "comply with native skill requirements" (per PR), how will future changes be tracked? There's no version field to indicate:
- Which iteration of the metadata this is
- Whether breaking changes have occurred
- Compatibility with tooling that consumes this frontmatter
Given that the skill itself is "new-preview" and will evolve (per learning: "will replace quick-dev and quick-spec upon graduation"), version metadata is particularly important to coordinate changes across skill metadata, tooling, and dependent workflows.
Proposed fix
--- name: bmad-quick-dev-new-preview description: '...' +version: '0.1.0-preview' main_config: '{project-root}/_bmad/bmm/config.yaml' ---🤖 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/workflow.md` around lines 2 - 3, Add explicit version metadata to the workflow frontmatter for bmad-quick-dev-new-preview so consumers can track iterations and compatibility; update the frontmatter block (near the "name: bmad-quick-dev-new-preview" and "description: ..." entries) to include fields like version (semantic version string, e.g., "version: 1.0.0"), schema_version or spec_version to indicate frontmatter schema, and an optional changelog or compatibility_notes field; ensure the new keys follow existing project conventions for frontmatter naming and formatting so tooling that reads the workflow can detect and validate version changes.
3-3: Description mixes concerns — combines capability description with trigger logic.The description has three distinct concerns packed into one field:
- Capability: "Implements... by producing... artifacts"
- Quality constraint: "that follow the project's existing architecture"
- Trigger condition: "Use when the user wants to..."
The "Use when" clause is orchestrator/routing logic, not a description of what the skill does. This belongs in separate metadata (e.g., a
triggerorwhen_to_usefield) or in routing documentation, not embedded in the description field.This mixing makes the description harder to parse programmatically and creates ambiguity about whether the "Use when" clause is part of the skill's contract or just advice.
Proposed fix — separate concerns
-description: 'Implements any user intent, requirement, story, bug fix or change request by producing clean working code artifacts that follow the project''s existing architecture, patterns and conventions. Use when the user wants to build, fix, tweak, refactor, add or modify any code, component or feature.' +description: 'Implements code-focused requirements, stories, bug fixes, and change requests by producing working code that follows the project''s existing architecture, patterns, and conventions.'If trigger logic is needed, add a separate frontmatter field:
triggers: 'build, fix, refactor, add, or modify code, components, or features'🤖 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/workflow.md` at line 3, The description frontmatter currently mixes capability, quality constraints and routing logic in the description field; edit the description value (the description frontmatter key) to include only the capability and quality constraint ("Implements any user intent... producing clean working code artifacts that follow the project's existing architecture, patterns and conventions") and extract the routing text ("Use when the user wants to build, fix, tweak, refactor, add or modify any code, component or feature") into a new separate frontmatter field such as triggers or when_to_use; update the workflow.md frontmatter to remove the "Use when..." clause from description and add a new triggers (or when_to_use) field with that trigger text so the routing logic is separated from the skill description.
3-3: Description claims "single unified flow" but omits execution time expectations.The description (and line 9 Goal) emphasize that this is a "single unified flow" from intent to PR creation, but there's no indication of how long this takes. Users need to know:
- Is this a 2-minute quick fix or a 30-minute comprehensive implementation?
- Can I invoke this in a tight deadline situation?
- Should I expect multiple human checkpoints (line 49, 58) or fully autonomous execution?
Without execution time or checkpoint metadata, users can't plan their workflow invocation or decide between this and alternatives (e.g., quick-spec for planning-only).
Proposed fix
--- name: bmad-quick-dev-new-preview description: '...' +estimated_time: '10-30 minutes depending on scope' +checkpoints: ['clarify-intent', 'review-spec', 'review-implementation'] +autonomy: 'semi-autonomous with human checkpoints' main_config: '{project-root}/_bmad/bmm/config.yaml' ---🤖 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/workflow.md` at line 3, Update the workflow.md "description" and the "Goal" (referenced as the single unified flow) to include explicit execution time expectations (e.g., typical duration range and best-case/worst-case estimates) and add checkpoint metadata for human review points mentioned at lines referencing 'line 49' and 'line 58' (or the sections that describe human checkpoints) indicating whether they are optional or required and expected latency for each; ensure the added fields are short, machine-parseable (e.g., "expected_duration: 5-30m" and "checkpoint: {name, required: true/false, expected_delay: 10m}") so callers can programmatically decide between quick and comprehensive flows.
2-3: Missing prerequisites and requirements metadata.The frontmatter doesn't specify:
- Required configuration keys: e.g.,
planning_artifacts,implementation_artifacts,user_name(line 67)- Required files: e.g.,
tech-spec-template.md(line 77), optionalproject-context.md(line 70)- VCS requirements: workflow mentions PR creation (line 9) — does it require git? A specific remote? Branch protections?
- Permissions needed: filesystem write access, git commit/push permissions, etc.
Without this metadata, users can't validate prerequisites before invocation. The workflow will fail partway through execution when a missing requirement is discovered, wasting time and leaving partial artifacts.
Proposed fix
--- name: bmad-quick-dev-new-preview description: '...' +required_config: ['planning_artifacts', 'implementation_artifacts', 'user_name', 'communication_language', 'document_output_language'] +required_files: ['tech-spec-template.md'] +optional_files: ['project-context.md', 'CLAUDE.md'] +requires_vcs: git +requires_permissions: ['filesystem:write', 'git:commit', 'git:push'] main_config: '{project-root}/_bmad/bmm/config.yaml' ---🤖 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/workflow.md` around lines 2 - 3, The frontmatter for the workflow is missing prerequisite metadata; update the workflow's YAML frontmatter (in bmad-quick-dev-new-preview) to declare required configuration keys (planning_artifacts, implementation_artifacts, user_name), required files (tech-spec-template.md and optional project-context.md), VCS requirements (e.g., git required, remote name, branch naming/ protections if applicable) and needed permissions (filesystem write, git commit/push, PR creation rights); add clear descriptions and expected formats for each key so callers can validate inputs before execution and prevent mid-run failures.
2-3: Missing taxonomic metadata — no tags, categories, or related skills.The frontmatter lacks discovery and relationship metadata:
- No tags: Can't programmatically discover this as a "quick-flow", "implementation", "code-generation", or "adversarial-review" workflow
- No category: Can't group with related workflows (e.g., development, implementation phase)
- No related skills: Can't suggest alternatives or complementary skills (e.g., quick-spec for planning-only mode)
This forces users to rely on filename conventions and manual documentation lookups. If the skill is intended for programmatic discovery or IDE integration (per PR mention of installation tooling), taxonomic metadata is essential.
Proposed fix
--- name: bmad-quick-dev-new-preview description: '...' +tags: ['quick-flow', 'implementation', 'code-generation', 'adversarial-review', 'pr-creation'] +category: 'development' +related_skills: ['bmad-quick-spec', 'bmad-quick-dev', 'bmad-code-review'] main_config: '{project-root}/_bmad/bmm/config.yaml' ---🤖 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/workflow.md` around lines 2 - 3, The workflow frontmatter (name: bmad-quick-dev-new-preview / description) is missing taxonomic metadata; add explicit fields like tags (e.g., ["quick-flow","implementation","code-generation","adversarial-review"]), category (e.g., "development" or "implementation"), and related_skills (e.g., ["quick-spec","code-review","testing"]) to the top-level frontmatter so the workflow can be programmatically discovered and grouped; update the file's frontmatter block with these new keys and sensible values aligned to the existing naming and purpose.
3-3: Description violates "concise, action-oriented" convention.Retrieved learning states that bmad-skill-manifest.yaml descriptions "follow a concise, action-oriented convention consistent across all manifests" and are "intentionally brief" without enumerating "output format details" or "implementation-specific wording."
This description is 50+ words in a single run-on sentence, includes implementation details ("follow the project's existing architecture, patterns and conventions"), and mixes multiple concerns. While this is workflow.md (not the manifest), consistency with the project's established description conventions would improve:
- Readability: Shorter, focused descriptions are easier to scan
- Programmatic parsing: Single-sentence descriptions are harder to parse into structured fields
- Maintenance: Verbose descriptions drift more easily from actual behavior
Proposed fix — follow convention
-description: 'Implements any user intent, requirement, story, bug fix or change request by producing clean working code artifacts that follow the project''s existing architecture, patterns and conventions. Use when the user wants to build, fix, tweak, refactor, add or modify any code, component or feature.' +description: 'Implements code-focused requirements through planning, implementation, adversarial review, and PR creation.'Based on learnings, descriptions should be concise and action-oriented.
🤖 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/workflow.md` at line 3, The description field currently contains a long, implementation-focused sentence; replace the YAML "description" value in workflow.md with a concise, action-oriented single sentence that states the workflow's purpose without implementation details or output-format instructions (e.g., "Implements user requests by producing clean, working code artifacts."). Ensure the new text follows the bmad-skill-manifest convention of brevity and focus and does not enumerate architecture or formatting requirements.
🤖 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/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/workflow.md`:
- Line 3: Update the description to remove or define the subjective term
"clean": replace "clean working code artifacts" with a concrete, measurable
checklist (e.g., "working code artifacts that pass project linting and type
checks, follow existing architecture/conventions, include unit/integration tests
for new behavior, and contain necessary documentation/README updates and
changelog entries"); edit the description line in workflow.md (the description
string) so it references these specific criteria instead of the word "clean" to
remove ambiguity.
- Around line 2-3: Add explicit version metadata to the workflow frontmatter for
bmad-quick-dev-new-preview so consumers can track iterations and compatibility;
update the frontmatter block (near the "name: bmad-quick-dev-new-preview" and
"description: ..." entries) to include fields like version (semantic version
string, e.g., "version: 1.0.0"), schema_version or spec_version to indicate
frontmatter schema, and an optional changelog or compatibility_notes field;
ensure the new keys follow existing project conventions for frontmatter naming
and formatting so tooling that reads the workflow can detect and validate
version changes.
- Line 3: The description frontmatter currently mixes capability, quality
constraints and routing logic in the description field; edit the description
value (the description frontmatter key) to include only the capability and
quality constraint ("Implements any user intent... producing clean working code
artifacts that follow the project's existing architecture, patterns and
conventions") and extract the routing text ("Use when the user wants to build,
fix, tweak, refactor, add or modify any code, component or feature") into a new
separate frontmatter field such as triggers or when_to_use; update the
workflow.md frontmatter to remove the "Use when..." clause from description and
add a new triggers (or when_to_use) field with that trigger text so the routing
logic is separated from the skill description.
- Line 3: Update the workflow.md "description" and the "Goal" (referenced as the
single unified flow) to include explicit execution time expectations (e.g.,
typical duration range and best-case/worst-case estimates) and add checkpoint
metadata for human review points mentioned at lines referencing 'line 49' and
'line 58' (or the sections that describe human checkpoints) indicating whether
they are optional or required and expected latency for each; ensure the added
fields are short, machine-parseable (e.g., "expected_duration: 5-30m" and
"checkpoint: {name, required: true/false, expected_delay: 10m}") so callers can
programmatically decide between quick and comprehensive flows.
- Around line 2-3: The frontmatter for the workflow is missing prerequisite
metadata; update the workflow's YAML frontmatter (in bmad-quick-dev-new-preview)
to declare required configuration keys (planning_artifacts,
implementation_artifacts, user_name), required files (tech-spec-template.md and
optional project-context.md), VCS requirements (e.g., git required, remote name,
branch naming/ protections if applicable) and needed permissions (filesystem
write, git commit/push, PR creation rights); add clear descriptions and expected
formats for each key so callers can validate inputs before execution and prevent
mid-run failures.
- Around line 2-3: The workflow frontmatter (name: bmad-quick-dev-new-preview /
description) is missing taxonomic metadata; add explicit fields like tags (e.g.,
["quick-flow","implementation","code-generation","adversarial-review"]),
category (e.g., "development" or "implementation"), and related_skills (e.g.,
["quick-spec","code-review","testing"]) to the top-level frontmatter so the
workflow can be programmatically discovered and grouped; update the file's
frontmatter block with these new keys and sensible values aligned to the
existing naming and purpose.
- Line 3: The description field currently contains a long,
implementation-focused sentence; replace the YAML "description" value in
workflow.md with a concise, action-oriented single sentence that states the
workflow's purpose without implementation details or output-format instructions
(e.g., "Implements user requests by producing clean, working code artifacts.").
Ensure the new text follows the bmad-skill-manifest convention of brevity and
focus and does not enumerate architecture or formatting requirements.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 2bb2714c-82aa-48a0-b0b3-5bdae76c43b7
📒 Files selected for processing (1)
src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/workflow.md
1 participant
Summary
bmad-quick-dev-new-previewby adding missingworkflow.mdfrontmatter fieldsname: bmad-quick-dev-new-previewdescriptionmatching the skill trigger textWhy
bmad-skill-manifest.yamlis alreadytype: skill; this PR closes a remaining mechanical metadata gap soworkflow.mdcomplies with native skill requirements without changing behavior.Mechanical Constraints
Validation
node tools/cli/bmad-cli.js install --directory /Users/alex/src/bmad --modules bmm --tools claude-code --yes.claude/skills/bmad-quick-dev-new-preview/exists withworkflow.md,steps/, template, andSKILL.md_bmad/_config/skill-manifest.csvcontainsbmad-quick-dev-new-previewnpm testpassed (full repo suite)Functional Equivalence (before/after)
workflow.mdcontent after frontmatter against previous HEADsteps/*.mdandtech-spec-template.mdagainst previous HEADNotes