convert dev-story workflow to native skill package#1940
Merged
Conversation
🤖 Augment PR SummarySummary: Converts the legacy 🤖 Was this summary useful? React with 👍 or 👎 |
![augmentcode[bot]](https://avatars.githubusercontent.com/in/1027498?s=60&v=4){kind=small}
src/bmm/agents/dev.agent.yaml
Outdated
| menu: | ||
| - trigger: DS or fuzzy match on dev-story | ||
| exec: "{project-root}/_bmad/bmm/workflows/4-implementation/dev-story/workflow.md" | ||
| exec: "{project-root}/_bmad/bmm/workflows/4-implementation/bmad-dev-story/workflow.md" |
There was a problem hiding this comment.
The menu trigger text still says “fuzzy match on dev-story” even though the exec path now targets bmad-dev-story; consider updating the trigger/help text too so users aren’t guided toward the old name.
Severity: low
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
| - `installed_path` = `{project-root}/_bmad/bmm/workflows/4-implementation/dev-story` | ||
| - `validation` = `{installed_path}/checklist.md` | ||
| - `installed_path` = `.` | ||
| - `validation` = `./checklist.md` |
There was a problem hiding this comment.
validation = ./checklist.md relies on the execution cwd matching the workflow directory; using {installed_path}/checklist.md would keep path resolution unambiguous and aligns with the placeholder guidance. (Guideline: path_placeholders_required)
Severity: medium
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
alexeyv
force-pushed
the
convert-dev-story-skill
branch
from
1971f02 to
0503914
Compare
📝 WalkthroughWalkthroughConverts the dev-story workflow from file-based execution to a skill-based invocation pattern by updating the agent menu entry, adding skill metadata files, renaming the workflow, and removing legacy manifest entries. 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 (11)
src/bmm/workflows/4-implementation/bmad-dev-story/workflow.md (5)
35-35:validationpath resolution contract is implicit
./checklist.mdis valid only if resolution is guaranteed relative to the skill root. Make that resolution basis explicit in this workflow contract to prevent runtime/environment ambiguity.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/4-implementation/bmad-dev-story/workflow.md` at line 35, The workflow currently uses `validation = ./checklist.md` with an implicit resolution rule; update the workflow contract text to explicitly state that the `validation` path is resolved relative to the skill root directory (i.e., treat `./` as the skill root) so environments and runtime loaders know the base for `./checklist.md`; mention the `validation` field and example `./checklist.md` so consumers understand the required resolution semantics.
35-35: Add an explicit preflight for missing checklistThe path changed; fail early if the checklist is missing so execution doesn’t proceed with a latent validation failure.
Proposed workflow guard
### Paths - `validation` = `./checklist.md` - `story_file` = `` (explicit story path; auto-discovered if empty) - `sprint_status` = `{implementation_artifacts}/sprint-status.yaml` + +Preflight: +- If `{{validation}}` does not exist, HALT with: "Missing validation checklist at {{validation}}"🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/4-implementation/bmad-dev-story/workflow.md` at line 35, The workflow currently references a `validation` key set to `./checklist.md` but lacks an explicit preflight check for the checklist file; add a startup guard that verifies the existence and readability of the `./checklist.md` file (the `validation` path) before proceeding and immediately fail the run with a clear error if it's missing or unreadable so execution cannot continue with a latent validation failure.
2-3: Add a short deprecation bridge for legacydev-storycallersGiven the identifier rename, consider a temporary compatibility note/alias strategy in user-facing entrypoints to avoid breaking older invocation habits during rollout.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/4-implementation/bmad-dev-story/workflow.md` around lines 2 - 3, Add a short deprecation bridge so callers of the legacy identifier "dev-story" continue to work: update the user-facing entrypoints that dispatch workflows to accept "dev-story" as an alias for the new "bmad-dev-story", route it internally to the same implementation, and emit a clear deprecation warning when "dev-story" is used advising callers to switch to "bmad-dev-story"; ensure the alias is only a thin shim (no duplicate logic) and add a single-line comment/doc note in the workflow metadata referencing both identifiers to aid rollout and removal later.
35-37: Path conventions are mixed in one block
validationis relative whilesprint_statusis templated absolute. Normalizing this (or documenting why mixed modes are required) will reduce maintenance mistakes during future conversions.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/4-implementation/bmad-dev-story/workflow.md` around lines 35 - 37, The block mixes path conventions: `validation` uses a relative path while `sprint_status` uses a templated absolute path (`{implementation_artifacts}`) and `story_file` is empty; pick one convention and apply it consistently (or document the rationale). Update `validation` and/or `sprint_status` so both use the same scheme (e.g., change `validation` to `{implementation_artifacts}/checklist.md` or convert `sprint_status` to a relative `./sprint-status.yaml`), and ensure `story_file` behavior is documented if left empty; adjust any consuming code or docs referencing `validation`, `story_file`, or `sprint_status` to match the chosen convention.
2-3: Codify skill-ID consistency as a CI invariantThis rename now depends on synchronized values across workflow frontmatter,
SKILL.md, agent exec, and module help. Add an automated check so future renames fail fast if any reference drifts.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/4-implementation/bmad-dev-story/workflow.md` around lines 2 - 3, Add a CI invariant that verifies the skill ID is consistent across the workflow frontmatter "name: bmad-dev-story", the SKILL.md declared skill id, the agent exec/config that references the skill, and the module help string; implement a small script (e.g., verify-skill-id.sh or a Node.js script) that parses the workflow frontmatter (look for "name:"), reads SKILL.md for the canonical skill id, inspects the agent execution/config code that references the skill id (search for "bmad-dev-story" or the skill id string), and checks the module help text, failing with a clear error if any value differs; add that script as a step to CI (pre-merge) so any drift is caught automatically.src/bmm/agents/dev.agent.yaml (2)
32-33: Expose canonical skill phrase in the trigger textThe trigger still advertises
dev-storyonly. Includebmad-dev-storyin trigger phrasing so users who learned the canonical skill ID can discover it directly.Proposed trigger update
- - trigger: DS or fuzzy match on dev-story + - trigger: DS or fuzzy match on dev-story or bmad-dev-story exec: "skill:bmad-dev-story"🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/agents/dev.agent.yaml` around lines 32 - 33, Update the trigger text so it advertises the canonical skill ID alongside the legacy phrase: change the trigger string that currently reads "DS or fuzzy match on dev-story" to include "bmad-dev-story" (the canonical skill referenced by exec: "skill:bmad-dev-story"), e.g. a combined phrasing like "DS or fuzzy match on dev-story or bmad-dev-story"; ensure the YAML trigger field and the exec mapping for skill:bmad-dev-story remain unchanged.
33-38: Menu currently mixes skill dispatch and file-path dispatchDS now uses
skill:...while CR remains direct path. Standardizing dispatch strategy across this menu will simplify validation and reduce future migration churn.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/agents/dev.agent.yaml` around lines 33 - 38, The menu mixes dispatch styles: DS uses skill dispatch ("skill:bmad-dev-story") while CR uses a direct path ("{project-root}/_bmad/bmm/workflows/4-implementation/code-review/workflow.md"); change the CR entry to use a skill dispatch (e.g., set exec to "skill:bmad-code-review") so both entries use "skill:..." format, keep the trigger and description as-is, and ensure the new skill name matches any existing skill handler or is added to the skill registry.src/bmm/workflows/4-implementation/bmad-dev-story/bmad-skill-manifest.yaml (2)
1-1: Manifest behavior depends on implicit defaultsWith only
type: skill, install behavior is inferred. Consider pinning intent explicitly (for example install policy fields where supported) so behavior won’t drift if defaults change later.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/4-implementation/bmad-dev-story/bmad-skill-manifest.yaml` at line 1, The manifest currently relies on the implicit default "type: skill" which makes install behavior brittle; update the bmad-skill-manifest.yaml to explicitly declare the intended install intent/policy instead of relying on implicit defaults (e.g., add an explicit intent or installPolicy field such as intent: install or installPolicy: <desired-policy> alongside type: skill) so the install behavior for this skill (manifest "type: skill") remains stable even if defaults change.
1-1: Add a CI guard for required skill artifactsA
type: skillmanifest without expected companion files (SKILL.md,workflow.md) should fail validation early.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/4-implementation/bmad-dev-story/bmad-skill-manifest.yaml` at line 1, Add a CI guard that fails validation when a manifest declares "type: skill" but companion documentation/artifacts are missing: in the manifest validation step (e.g., the validate_manifest or manifest-validator job), detect manifests containing the literal key/value "type: skill" and verify that SKILL.md and workflow.md exist alongside the manifest (or at repo root as your convention dictates); if either file is absent, emit a clear error referencing the manifest and exit non‑zero so CI fails early.src/bmm/workflows/4-implementation/bmad-dev-story/SKILL.md (2)
6-6: Add plain-path fallback for non-rendered contextsSome execution contexts won’t render Markdown links. Include a direct path instruction alongside the link to keep this robust.
Proposed wording
-Follow the instructions in [workflow.md](workflow.md). +Follow the instructions in [workflow.md](workflow.md). +If link rendering is unavailable, read and follow `./workflow.md` directly.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/4-implementation/bmad-dev-story/SKILL.md` at line 6, Replace the inline Markdown link "[workflow.md](workflow.md)" with a combined link + plain-path fallback so non-rendering contexts still have a usable path; update SKILL.md's line containing that link to read the linked form followed immediately by a plain text path/instruction (e.g., "See workflow.md — path: workflow.md") so both rendered Markdown and plain-text consumers can access the file.
2-3: Skill metadata is duplicated across files and can drift
name/descriptionnow live in multiple places (SKILL.mdand workflow frontmatter). Add an automated parity check (or generate one from the other) to prevent silent divergence.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/4-implementation/bmad-dev-story/SKILL.md` around lines 2 - 3, Add an automated parity check that ensures the SKILL.md metadata (the name "bmad-dev-story" and its description keys) matches the workflow frontmatter: implement a small script (e.g., check_skill_parity) that parses the workflow frontmatter and SKILL.md, compares the name and description fields, and exits non‑zero with a clear error if they differ; wire this script into CI (pre-commit or pipeline) or replace SKILL.md generation by emitting SKILL.md from the workflow frontmatter (single source of truth) so the values in SKILL.md and the workflow frontmatter cannot drift.
🤖 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/4-implementation/bmad-dev-story/workflow.md`:
- Line 2: Update all prose/checklist references of the old skill name
"dev-story" to the new canonical name "bmad-dev-story"; search for the literal
string "dev-story" in workflow and checklist markdown files (where the
executable integration already uses bmad-dev-story) and replace those instances
so instructions, checklist items, and user-facing text consistently use
"bmad-dev-story" instead of "dev-story".
---
Nitpick comments:
In `@src/bmm/agents/dev.agent.yaml`:
- Around line 32-33: Update the trigger text so it advertises the canonical
skill ID alongside the legacy phrase: change the trigger string that currently
reads "DS or fuzzy match on dev-story" to include "bmad-dev-story" (the
canonical skill referenced by exec: "skill:bmad-dev-story"), e.g. a combined
phrasing like "DS or fuzzy match on dev-story or bmad-dev-story"; ensure the
YAML trigger field and the exec mapping for skill:bmad-dev-story remain
unchanged.
- Around line 33-38: The menu mixes dispatch styles: DS uses skill dispatch
("skill:bmad-dev-story") while CR uses a direct path
("{project-root}/_bmad/bmm/workflows/4-implementation/code-review/workflow.md");
change the CR entry to use a skill dispatch (e.g., set exec to
"skill:bmad-code-review") so both entries use "skill:..." format, keep the
trigger and description as-is, and ensure the new skill name matches any
existing skill handler or is added to the skill registry.
In `@src/bmm/workflows/4-implementation/bmad-dev-story/bmad-skill-manifest.yaml`:
- Line 1: The manifest currently relies on the implicit default "type: skill"
which makes install behavior brittle; update the bmad-skill-manifest.yaml to
explicitly declare the intended install intent/policy instead of relying on
implicit defaults (e.g., add an explicit intent or installPolicy field such as
intent: install or installPolicy: <desired-policy> alongside type: skill) so the
install behavior for this skill (manifest "type: skill") remains stable even if
defaults change.
- Line 1: Add a CI guard that fails validation when a manifest declares "type:
skill" but companion documentation/artifacts are missing: in the manifest
validation step (e.g., the validate_manifest or manifest-validator job), detect
manifests containing the literal key/value "type: skill" and verify that
SKILL.md and workflow.md exist alongside the manifest (or at repo root as your
convention dictates); if either file is absent, emit a clear error referencing
the manifest and exit non‑zero so CI fails early.
In `@src/bmm/workflows/4-implementation/bmad-dev-story/SKILL.md`:
- Line 6: Replace the inline Markdown link "[workflow.md](workflow.md)" with a
combined link + plain-path fallback so non-rendering contexts still have a
usable path; update SKILL.md's line containing that link to read the linked form
followed immediately by a plain text path/instruction (e.g., "See workflow.md —
path: workflow.md") so both rendered Markdown and plain-text consumers can
access the file.
- Around line 2-3: Add an automated parity check that ensures the SKILL.md
metadata (the name "bmad-dev-story" and its description keys) matches the
workflow frontmatter: implement a small script (e.g., check_skill_parity) that
parses the workflow frontmatter and SKILL.md, compares the name and description
fields, and exits non‑zero with a clear error if they differ; wire this script
into CI (pre-commit or pipeline) or replace SKILL.md generation by emitting
SKILL.md from the workflow frontmatter (single source of truth) so the values in
SKILL.md and the workflow frontmatter cannot drift.
In `@src/bmm/workflows/4-implementation/bmad-dev-story/workflow.md`:
- Line 35: The workflow currently uses `validation = ./checklist.md` with an
implicit resolution rule; update the workflow contract text to explicitly state
that the `validation` path is resolved relative to the skill root directory
(i.e., treat `./` as the skill root) so environments and runtime loaders know
the base for `./checklist.md`; mention the `validation` field and example
`./checklist.md` so consumers understand the required resolution semantics.
- Line 35: The workflow currently references a `validation` key set to
`./checklist.md` but lacks an explicit preflight check for the checklist file;
add a startup guard that verifies the existence and readability of the
`./checklist.md` file (the `validation` path) before proceeding and immediately
fail the run with a clear error if it's missing or unreadable so execution
cannot continue with a latent validation failure.
- Around line 2-3: Add a short deprecation bridge so callers of the legacy
identifier "dev-story" continue to work: update the user-facing entrypoints that
dispatch workflows to accept "dev-story" as an alias for the new
"bmad-dev-story", route it internally to the same implementation, and emit a
clear deprecation warning when "dev-story" is used advising callers to switch to
"bmad-dev-story"; ensure the alias is only a thin shim (no duplicate logic) and
add a single-line comment/doc note in the workflow metadata referencing both
identifiers to aid rollout and removal later.
- Around line 35-37: The block mixes path conventions: `validation` uses a
relative path while `sprint_status` uses a templated absolute path
(`{implementation_artifacts}`) and `story_file` is empty; pick one convention
and apply it consistently (or document the rationale). Update `validation`
and/or `sprint_status` so both use the same scheme (e.g., change `validation` to
`{implementation_artifacts}/checklist.md` or convert `sprint_status` to a
relative `./sprint-status.yaml`), and ensure `story_file` behavior is documented
if left empty; adjust any consuming code or docs referencing `validation`,
`story_file`, or `sprint_status` to match the chosen convention.
- Around line 2-3: Add a CI invariant that verifies the skill ID is consistent
across the workflow frontmatter "name: bmad-dev-story", the SKILL.md declared
skill id, the agent exec/config that references the skill, and the module help
string; implement a small script (e.g., verify-skill-id.sh or a Node.js script)
that parses the workflow frontmatter (look for "name:"), reads SKILL.md for the
canonical skill id, inspects the agent execution/config code that references the
skill id (search for "bmad-dev-story" or the skill id string), and checks the
module help text, failing with a clear error if any value differs; add that
script as a step to CI (pre-merge) so any drift is caught automatically.
🪄 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: d83e914d-b231-4c99-b2e8-dac4aab4c850
⛔ Files ignored due to path filters (1)
src/bmm/module-help.csvis excluded by!**/*.csv
📒 Files selected for processing (6)
src/bmm/agents/dev.agent.yamlsrc/bmm/workflows/4-implementation/bmad-dev-story/SKILL.mdsrc/bmm/workflows/4-implementation/bmad-dev-story/bmad-skill-manifest.yamlsrc/bmm/workflows/4-implementation/bmad-dev-story/checklist.mdsrc/bmm/workflows/4-implementation/bmad-dev-story/workflow.mdsrc/bmm/workflows/4-implementation/dev-story/bmad-skill-manifest.yaml
💤 Files with no reviewable changes (1)
- src/bmm/workflows/4-implementation/dev-story/bmad-skill-manifest.yaml
| @@ -1,5 +1,5 @@ | |||
| --- | |||
| name: dev-story | |||
| name: bmad-dev-story | |||
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# 1) stale skill invocations
rg -n --fixed-strings 'skill:dev-story' || true
# 2) stale direct workflow-path invocations for old dev-story location/name
rg -n --fixed-strings '/4-implementation/dev-story/' || true
rg -nP '\bdev-story\b' || trueRepository: bmad-code-org/BMAD-METHOD
Length of output: 3116
Stale prose references to legacy dev-story in instructions should be updated
The skill renaming to bmad-dev-story is correct and already propagated to executable integration points (dev.agent.yaml, module-help.csv). However, prose instructions and checklist items in other workflow files still reference the legacy dev-story name:
src/bmm/workflows/4-implementation/sprint-status/workflow.md(lines 132, 134)src/bmm/workflows/4-implementation/bmad-create-story/checklist.md(line 322)src/bmm/workflows/4-implementation/bmad-create-story/workflow.md(lines 380, 382)
Update these references to use bmad-dev-story for consistency and to prevent user confusion.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/bmm/workflows/4-implementation/bmad-dev-story/workflow.md` at line 2,
Update all prose/checklist references of the old skill name "dev-story" to the
new canonical name "bmad-dev-story"; search for the literal string "dev-story"
in workflow and checklist markdown files (where the executable integration
already uses bmad-dev-story) and replace those instances so instructions,
checklist items, and user-facing text consistently use "bmad-dev-story" instead
of "dev-story".
4275c6a to
9645475
Compare
alexeyv
force-pushed
the
convert-dev-story-skill
branch
from
0c62d8d to
ffc12e3
Compare
alexeyv
added a commit
that referenced
this pull request
Mar 14, 2026
* convert dev-story workflow to native skill package * align dev-story skill references with upstream patterns * remove obsolete skill frontmatter from dev-story workflow
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
4-implementation/dev-storyfrom legacytype: workflowpackaging to nativetype: skillsrc/bmm/workflows/4-implementation/bmad-dev-storySKILL.mdwrapper and switch manifest totype: skillinstalled_path,validation)src/bmm/module-help.csv(workflow-file->skill:bmad-dev-story)src/bmm/agents/dev.agent.yaml(exec path to renamed workflow dir)Mechanical Conversion Guardrails
workflow.mdbehavior and execution orderchecklist.mdcontent verbatimValidation
node tools/cli/bmad-cli.js install --directory /Users/alex/src/bmad --modules bmm --tools claude-code --yes/Users/alex/src/bmad/.claude/skills/bmad-dev-story/Users/alex/src/bmad/_bmad/_config/skill-manifest.csvand absent from workflow manifestnpm test(passes)workflow.mdafter normalizing only expected rename/path substitutions -> no diffchecklist.md-> no diffNotes