chore: convert dev-story workflow from yaml to markdown#1861
Merged
alexeyv merged 2 commits intobmad-code-org:mainfrom Mar 8, 2026
Merged
chore: convert dev-story workflow from yaml to markdown#1861alexeyv merged 2 commits intobmad-code-org:mainfrom
alexeyv merged 2 commits intobmad-code-org:mainfrom
Conversation
🤖 Augment PR SummarySummary: This PR consolidates the Changes:
Technical Notes: The new format relies on frontmatter + Markdown sections for configuration/metadata, while the operational logic remains encoded as XML-like workflow directives inside the document. 🤖 Was this summary useful? React with 👍 or 👎 |
![augmentcode[bot]](https://avatars.githubusercontent.com/in/1027498?s=60&v=4){kind=small}
| <critical>User skill level ({user_skill_level}) affects conversation style ONLY, not code updates.</critical> | ||
|
|
||
| <step n="1" goal="Find next ready story and load it" tag="sprint-status"> | ||
| <check if="{{story_path}} is provided"> |
There was a problem hiding this comment.
workflow.md checks/sets {{story_path}}, but the INITIALIZATION section defines story_file; if these aren’t aliased by the engine, an explicit story path may never be detected/used.
Severity: medium
Other Locations
src/bmm/workflows/4-implementation/dev-story/workflow.md:37
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
| <action>Identify first incomplete task (unchecked [ ]) in Tasks/Subtasks</action> | ||
|
|
||
| <action if="no incomplete tasks"> | ||
| <goto step="6">Completion sequence</goto> |
There was a problem hiding this comment.
When there are “no incomplete tasks”, the flow jumps to step 6 labeled “Completion sequence”, but step 6 is “Author comprehensive tests” while step 9 handles completion/status updates; this seems like it could skip the actual completion path.
Severity: medium
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
| <critical>Absolutely DO NOT stop because of "milestones", "significant progress", or "session boundaries". Continue in a single execution | ||
| until the story is COMPLETE (all ACs satisfied and all tasks/subtasks checked) UNLESS a HALT condition is triggered or the USER gives | ||
| other instruction.</critical> | ||
| <critical>Do NOT schedule a "next session" or request review pauses unless a HALT condition applies. Only Step 6 decides completion.</critical> |
There was a problem hiding this comment.
The critical directive says “Only Step 6 decides completion”, but later the workflow references “Step 9 completion gates” and step 9 is the completion/status-update step; this inconsistency could cause ambiguous behavior for agents following the instructions literally.
Severity: low
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
| </action> | ||
|
|
||
| <!-- Mark story ready for review - sprint status conditional --> | ||
| <check if="{sprint_status} file exists AND {{current_sprint_status}} != 'no-sprint-tracking'"> |
There was a problem hiding this comment.
Step 9 uses {sprint_status} in condition/actions, while earlier steps use {{sprint_status}}; if templating expects one format consistently, the sprint-status update checks may not run at completion.
Severity: medium
Other Locations
src/bmm/workflows/4-implementation/dev-story/workflow.md:402src/bmm/workflows/4-implementation/dev-story/workflow.md:451src/bmm/workflows/4-implementation/dev-story/workflow.md:452
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
📝 WalkthroughWalkthroughA new comprehensive Dev Story Workflow specification is introduced via Markdown, replacing the previous YAML configuration. The workflow defines an initialization phase and 10-step execution pipeline for implementing development stories, including story discovery, context loading, task implementation with red-green-refactor cycles, testing, validation, and completion handling with sprint-status synchronization. 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)
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: 6
🧹 Nitpick comments (7)
src/bmm/workflows/4-implementation/dev-story/workflow.md (7)
98-98: HALT semantics undefined despite 15+ HALT conditions.The workflow uses HALT extensively (lines 98, 102, 114, 142, 146, 178, 179, 291, 292, 293, 351, 414, 415, 416, 417) but never defines what HALT means operationally:
- Does it throw an error and stop execution?
- Does it pause and wait for user input?
- Does it roll back changes made so far?
- Does it log the HALT reason somewhere?
Furthermore, HALT messages suggest different behaviors:
HALT - Run create-story workflow(line 98) → suggests switching workflowsHALT: "Cannot develop story without access"(line 178) → suggests error terminationHALT and request guidance(line 292) → suggests user interactionAdd a HALT definition to the INITIALIZATION section:
### HALT Conditions When a HALT condition is triggered: 1. Stop execution immediately 2. Display the HALT message to the user 3. Save any in-progress changes to the story file 4. Log the HALT reason in Dev Agent Record 5. Wait for user instruction before resumingDifferentiate HALT types if needed (e.g., HALT-ERROR vs HALT-SWITCH-WORKFLOW vs HALT-REQUEST-INPUT).
Also applies to: 178-178, 291-291, 351-351, 414-414
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/4-implementation/dev-story/workflow.md` at line 98, Add a clear HALT definition under the INITIALIZATION section and standardize HALT usage across the workflow: define operational semantics (stop execution, display HALT message, persist in-progress story file, log the reason to Dev Agent Record, and wait for user instruction) and add HALT type categories (e.g., HALT-ERROR, HALT-SWITCH-WORKFLOW, HALT-REQUEST-INPUT) so occurrences like "HALT - Run create-story" and "HALT: 'Cannot develop story without access'" have deterministic behavior and logging; update references in the document to use the new HALT types and ensure each HALT message maps to one of the defined behaviors.
235-268: No rollback strategy for mid-execution failures.The workflow modifies multiple persistent states:
- Story file status and content (multiple steps)
- sprint-status.yaml (Steps 4 and 9)
- Code files and tests (Steps 5-7)
If the workflow fails mid-execution (e.g., HALT after marking story in-progress in Step 4 but before completing tasks), there's no rollback mechanism to restore the previous state. This leaves the system in an inconsistent state:
- Story marked in-progress but no work done
- Partial code changes without completed tasks
- Manual cleanup required
Consider adding a transaction or rollback strategy:
- Checkpoint mechanism: Save initial state before Step 4, allow rollback on HALT
- Atomic completion: Only persist status changes (story file, sprint-status.yaml) after all tasks pass validation in Step 9
- Recovery guidance: Document manual steps to roll back partial work if workflow fails
- Idempotency: Design workflow to be safely re-runnable from any step without corrupting state
For now, at minimum, document the manual recovery procedure in the INITIALIZATION section.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/4-implementation/dev-story/workflow.md` around lines 235 - 268, The workflow lacks any rollback/checkpoint strategy around multi-file persistent updates (notably in step n="4" where sprint-status.yaml and development_status[{{story_key}}] are modified and later steps 5-9 alter code/tests), so add either a checkpoint-and-rollback or at minimum document recovery: before Step 4 capture and persist the original state (snapshot of {{sprint_status}} file, development_status[{{story_key}}], and note {{current_sprint_status}}), implement a rollback action invoked on HALT/failure to restore those snapshots, and/or update the INITIALIZATION section with clear manual recovery steps (how to revert sprint-status.yaml, reset development_status[{{story_key}}], and revert partial code changes) and note idempotency expectations so the workflow can be safely re-run; reference step n="4", step n="9", {{sprint_status}}, {{current_sprint_status}}, and development_status[{{story_key}}] when adding these changes.
167-167: Missing story file schema validation.The workflow references multiple story file sections throughout (Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Dev Agent Record, File List, Change Log, Status, Senior Developer Review, Review Follow-ups) but never validates that these sections exist or conform to a schema.
If the story file is malformed or missing required sections, the workflow will fail with unclear errors when trying to parse or update sections.
Add a story file schema validation step after loading the story file (after line 163):
<action>Validate story file schema: - Required sections exist: Story, Acceptance Criteria, Tasks/Subtasks, Status - Optional sections: Dev Notes, Dev Agent Record, File List, Change Log - Status field contains valid value (backlog, ready-for-dev, in-progress, review, done) - Tasks/Subtasks section contains at least one task with [ ] or [x] checkbox </action> <action if="schema validation fails">HALT: "Story file is malformed - missing required sections: {{missing_sections}}"</action>Alternatively, reference an external story file schema document if one exists.
Also applies to: 198-199
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/4-implementation/dev-story/workflow.md` at line 167, The workflow currently parses sections in the action "Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Dev Agent Record, File List, Change Log, Status" but does not validate the file schema; add a new action immediately after the story file load (before or directly after the "Parse sections" action) named "Validate story file schema" that enforces required sections (Story, Acceptance Criteria, Tasks/Subtasks, Status), allows optional sections (Dev Notes, Dev Agent Record, File List, Change Log), checks Status is one of [backlog, ready-for-dev, in-progress, review, done], and verifies Tasks/Subtasks contains at least one task checkbox ([ ] or [x]); if validation fails add an action like 'HALT: "Story file is malformed - missing required sections: {{missing_sections}}"' so downstream steps (e.g., parsing/updating sections and review follow-ups) won't run on malformed files.
349-352: Missing error recovery guidance when validation fails.When validation gates fail (line 349), the workflow instructs "DO NOT mark task complete - fix issues first" (line 350) and "HALT if unable to fix" (line 351). However:
- No algorithm for fixing validation failures
- No criteria for determining "unable to fix"
- No retry mechanism or recovery loop
- No debugging guidance
This leaves the agent in a dead-end state with no actionable path forward.
Add recovery guidance:
<check if="ANY validation fails"> <action>DO NOT mark task complete</action> <action>Identify specific validation failures (which tests failed? which ACs unsatisfied?)</action> <action>Attempt to fix validation failures: - Re-run failing tests to confirm failure - Debug test failures and fix implementation - Re-validate acceptance criteria - Run up to 3 fix-and-revalidate cycles </action> <action>If validation still fails after 3 attempts, HALT with detailed failure analysis</action> </check>🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/4-implementation/dev-story/workflow.md` around lines 349 - 352, Update the validation failure branch for the <check if="ANY validation fails"> block to include concrete recovery steps: add an action to identify specific failures (failed tests and unmet acceptance criteria), an action to attempt fixes with a defined loop of up to 3 fix-and-revalidate cycles (re-run failing tests, debug and fix implementation, re-validate acceptance criteria each cycle), criteria to declare "unable to fix" (e.g., persistent failing tests or unmet ACs after 3 attempts), and an action to HALT only after those 3 attempts with a detailed failure analysis (including failing test names, stack traces or error messages, and which ACs remain unsatisfied).
309-309: Test framework inference lacks algorithm or heuristics.Line 309 instructs: "Determine how to run tests for this repo (infer test framework from project structure)." This is a complex task with no guidance provided. Inferring test frameworks requires:
- Checking for test scripts in package.json, Makefile, or build configs
- Detecting test directories (test/, tests/, tests/, spec/)
- Identifying test file patterns (*.test.js, test.py, test.py, *.spec.ts)
- Finding test framework config files (jest.config.js, pytest.ini, karma.conf.js, etc.)
- Handling multi-language repos with multiple test frameworks
Without heuristics, the agent may fail to run tests or execute the wrong command.
Add inference heuristics:
<action>Determine how to run tests: - Check package.json for "test" script → run `npm test` - Check for pytest.ini or setup.cfg → run `pytest` - Check for Makefile with "test" target → run `make test` - Check for test/ or tests/ directory → search for test runner in nearby configs - If uncertain, ASK user: "How should I run tests for this repository?" </action>🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/4-implementation/dev-story/workflow.md` at line 309, The current "Determine how to run tests for this repo (infer test framework from project structure)" action lacks concrete heuristics; update that action in workflow.md to list explicit inference steps: check package.json for a "test" script and run npm test, look for pytest.ini or setup.cfg to run pytest, check Makefile for a "test" target and run make test, detect test directories (test/, tests/, __tests__, spec/) and common test file patterns (*.test.js, *.spec.ts, *_test.py, test_*.py) and search for framework config files (jest.config.js, pytest.ini, karma.conf.js) to choose the runner, handle multi-language repos by preferring repository-level scripts/configs and, if still ambiguous, prompt the user with "How should I run tests for this repository?" so the agent can proceed safely.
31-31: Date format unspecified for system-generateddatevariable.Line 31 defines
dateas "system-generated current datetime" but doesn't specify the format. This variable is used in multiple places:
- Sprint-status
last_updatedfield (lines 243, 397)- Change Log entries (line 356)
- Review dates (line 212)
Without a specified format, different parts of the system might generate inconsistent date representations (ISO 8601 vs. human-readable vs. locale-specific), causing parsing errors or inconsistent display.
Specify the date format:
-- `date` as system-generated current datetime +- `date` as system-generated current datetime (format: YYYY-MM-DD HH:MM:SS)Or reference the project's date format convention if defined elsewhere.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/4-implementation/dev-story/workflow.md` at line 31, The system-generated variable named `date` lacks a specified format, causing inconsistent representations where it's used (e.g., sprint-status `last_updated`, change log entries, review dates); update the generation of `date` to a single canonical format (preferably ISO 8601 / RFC3339 with timezone, e.g., UTC) and document that choice in this workflow file, then ensure all references that set or parse `date` (fields `last_updated`, change log entries, review date usages) produce and expect that ISO 8601 format so parsing/display is consistent across the codebase.
255-259: Status transition validation too permissive.Lines 255-259 warn about unexpected status but continue anyway: "Unexpected story status: {{current_status}}. Expected ready-for-dev or in-progress. Continuing anyway..."
This allows invalid status transitions:
- What if status is already "review" or "done"?
- Re-implementing a completed story could corrupt its state
- No validation of the status transition graph
Add stricter status transition validation:
<check if="current status is neither ready-for-dev nor in-progress"> - <output>⚠️ Unexpected story status: {{current_status}} - Expected ready-for-dev or in-progress. Continuing anyway... - </output> + <action if="current status == 'done'"> + HALT: "Story is already marked done. Use a different workflow to reopen or modify completed stories." + </action> + <action if="current status == 'review'"> + <ask>Story is marked 'review'. Continue implementation anyway? This will move it back to in-progress. [y/n]</ask> + </action> + <output>⚠️ Unexpected story status: {{current_status}}. Proceeding with caution...</output> </check>🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/4-implementation/dev-story/workflow.md` around lines 255 - 259, The current conditional block (<check if="current status is neither ready-for-dev nor in-progress">) is too permissive because it only warns and continues; change it to enforce the allowed transition graph by validating current_status against an explicit allowed set (ready-for-dev, in-progress) and aborting or failing the workflow when current_status is any terminal or invalid state (e.g., review, done, closed), returning a clear error instead of "Continuing anyway..."; update the output to return a hard failure message and ensure the check prevents further steps from running when current_status is not in the allowed set.
🤖 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/dev-story/workflow.md`:
- Line 176: The goto target is incorrect: replace the <goto step="6">Completion
sequence</goto> entry so it points to Step 9 instead of Step 6; update the goto
to reference step="9" (so the flow moves to "Story completion and mark for
review" rather than "Author comprehensive tests") to ensure the completion
sequence branches to the correct step.
- Around line 335-337: The current cross-section sync logic that finds and
checks the corresponding action by matching the action <action> description text
is fragile; update workflow.md and the sync logic to use stable ID-based
matching instead: add a unique ID token (e.g., [AI-R001]) to each review action
item in the "Senior Developer Review (AI) → Action Items" list and require the
corresponding entry in "Review Follow-ups (AI)" to reference that same ID, then
change the code that locates and checks the matching item to look up by ID
rather than description text (refer to the <action> tags and the "Senior
Developer Review (AI) → Action Items" and "Review Follow-ups (AI)" sections),
and add fallback/error handling that logs unmatched IDs so synchronization
failures are visible.
- Line 37: The workflow defines the explicit variable as story_file but the
template references story_path throughout, causing undefined variable errors;
choose one name and make it consistent: either rename the variable declaration
from story_file to story_path or update every template reference (all
occurrences of {{story_path}}) to {{story_file}} so the variable name matches
(check places where {{story_path}} is used and the declaration where story_file
is set, e.g., the variable definition and all template interpolations).
- Around line 301-306: Clarify test authoring by adopting Option A: keep Step
5's "red-green-refactor" as the place for task-specific, minimal
failing->passing tests, remove the current Step 6 "Author comprehensive tests"
block, and relocate comprehensive test responsibilities to Step 9
(pre-completion/acceptance) so full unit/integration/e2e coverage is produced
once per story; also update the loop description that jumps from Step 8 back to
Step 5 to state that comprehensive tests are only done in Step 9 and not on
every task iteration, and adjust any wording referencing "Step 6" or
"comprehensive tests" to point to Step 9 and the red-green-refactor practice in
Step 5.
- Around line 11-17: The workflow.md file contains duplicate critical directives
present in the intro and again in the EXECUTION section; remove the duplicated
block from the intro and leave the canonical directives only in the EXECUTION
section, then replace the removed intro text with a short reference pointing
readers to the EXECUTION section for the rules (preserve the exact directives
text only once and keep items like "Tasks/Subtasks checkboxes, Dev Agent Record
(Debug Log, Completion Notes), File List, Change Log, and Status" and the
HALT/Step 6 language intact in the retained EXECUTION copy so nothing else
changes).
- Around line 186-189: Step 2 currently duplicates the story parsing performed
in Step 1: remove the repeated action lines ("Parse sections: Story, Acceptance
Criteria, Tasks/Subtasks, Dev Notes, Dev Agent Record, File List, Change Log,
Status", "Load comprehensive context from story file's Dev Notes section",
"Extract developer guidance from Dev Notes: architecture requirements, previous
learnings, technical specifications", "Use enhanced story context to inform
implementation decisions and approaches") from the Step 2 block and leave Step 2
focused on loading project-level context only; ensure any references to story
data in Step 2 instead reference the canonical story load in Step 1 (the
original Parse sections / Load comprehensive context actions) to avoid
duplication and divergence.
---
Nitpick comments:
In `@src/bmm/workflows/4-implementation/dev-story/workflow.md`:
- Line 98: Add a clear HALT definition under the INITIALIZATION section and
standardize HALT usage across the workflow: define operational semantics (stop
execution, display HALT message, persist in-progress story file, log the reason
to Dev Agent Record, and wait for user instruction) and add HALT type categories
(e.g., HALT-ERROR, HALT-SWITCH-WORKFLOW, HALT-REQUEST-INPUT) so occurrences like
"HALT - Run create-story" and "HALT: 'Cannot develop story without access'" have
deterministic behavior and logging; update references in the document to use the
new HALT types and ensure each HALT message maps to one of the defined
behaviors.
- Around line 235-268: The workflow lacks any rollback/checkpoint strategy
around multi-file persistent updates (notably in step n="4" where
sprint-status.yaml and development_status[{{story_key}}] are modified and later
steps 5-9 alter code/tests), so add either a checkpoint-and-rollback or at
minimum document recovery: before Step 4 capture and persist the original state
(snapshot of {{sprint_status}} file, development_status[{{story_key}}], and note
{{current_sprint_status}}), implement a rollback action invoked on HALT/failure
to restore those snapshots, and/or update the INITIALIZATION section with clear
manual recovery steps (how to revert sprint-status.yaml, reset
development_status[{{story_key}}], and revert partial code changes) and note
idempotency expectations so the workflow can be safely re-run; reference step
n="4", step n="9", {{sprint_status}}, {{current_sprint_status}}, and
development_status[{{story_key}}] when adding these changes.
- Line 167: The workflow currently parses sections in the action "Parse
sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Dev Agent
Record, File List, Change Log, Status" but does not validate the file schema;
add a new action immediately after the story file load (before or directly after
the "Parse sections" action) named "Validate story file schema" that enforces
required sections (Story, Acceptance Criteria, Tasks/Subtasks, Status), allows
optional sections (Dev Notes, Dev Agent Record, File List, Change Log), checks
Status is one of [backlog, ready-for-dev, in-progress, review, done], and
verifies Tasks/Subtasks contains at least one task checkbox ([ ] or [x]); if
validation fails add an action like 'HALT: "Story file is malformed - missing
required sections: {{missing_sections}}"' so downstream steps (e.g.,
parsing/updating sections and review follow-ups) won't run on malformed files.
- Around line 349-352: Update the validation failure branch for the <check
if="ANY validation fails"> block to include concrete recovery steps: add an
action to identify specific failures (failed tests and unmet acceptance
criteria), an action to attempt fixes with a defined loop of up to 3
fix-and-revalidate cycles (re-run failing tests, debug and fix implementation,
re-validate acceptance criteria each cycle), criteria to declare "unable to fix"
(e.g., persistent failing tests or unmet ACs after 3 attempts), and an action to
HALT only after those 3 attempts with a detailed failure analysis (including
failing test names, stack traces or error messages, and which ACs remain
unsatisfied).
- Line 309: The current "Determine how to run tests for this repo (infer test
framework from project structure)" action lacks concrete heuristics; update that
action in workflow.md to list explicit inference steps: check package.json for a
"test" script and run npm test, look for pytest.ini or setup.cfg to run pytest,
check Makefile for a "test" target and run make test, detect test directories
(test/, tests/, __tests__, spec/) and common test file patterns (*.test.js,
*.spec.ts, *_test.py, test_*.py) and search for framework config files
(jest.config.js, pytest.ini, karma.conf.js) to choose the runner, handle
multi-language repos by preferring repository-level scripts/configs and, if
still ambiguous, prompt the user with "How should I run tests for this
repository?" so the agent can proceed safely.
- Line 31: The system-generated variable named `date` lacks a specified format,
causing inconsistent representations where it's used (e.g., sprint-status
`last_updated`, change log entries, review dates); update the generation of
`date` to a single canonical format (preferably ISO 8601 / RFC3339 with
timezone, e.g., UTC) and document that choice in this workflow file, then ensure
all references that set or parse `date` (fields `last_updated`, change log
entries, review date usages) produce and expect that ISO 8601 format so
parsing/display is consistent across the codebase.
- Around line 255-259: The current conditional block (<check if="current status
is neither ready-for-dev nor in-progress">) is too permissive because it only
warns and continues; change it to enforce the allowed transition graph by
validating current_status against an explicit allowed set (ready-for-dev,
in-progress) and aborting or failing the workflow when current_status is any
terminal or invalid state (e.g., review, done, closed), returning a clear error
instead of "Continuing anyway..."; update the output to return a hard failure
message and ensure the check prevents further steps from running when
current_status is not in the allowed set.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 6d73d4dc-046f-4234-8b43-3b0a29bd4048
📒 Files selected for processing (2)
src/bmm/workflows/4-implementation/dev-story/workflow.mdsrc/bmm/workflows/4-implementation/dev-story/workflow.yaml
💤 Files with no reviewable changes (1)
- src/bmm/workflows/4-implementation/dev-story/workflow.yaml
Comment on lines
+11
to
+17
| - Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level} | ||
| - Generate all documents in {document_output_language} | ||
| - Only modify the story file in these areas: Tasks/Subtasks checkboxes, Dev Agent Record (Debug Log, Completion Notes), File List, Change Log, and Status | ||
| - Execute ALL steps in exact order; do NOT skip steps | ||
| - Absolutely DO NOT stop because of "milestones", "significant progress", or "session boundaries". Continue in a single execution until the story is COMPLETE (all ACs satisfied and all tasks/subtasks checked) UNLESS a HALT condition is triggered or the USER gives other instruction. | ||
| - Do NOT schedule a "next session" or request review pauses unless a HALT condition applies. Only Step 6 decides completion. | ||
| - User skill level ({user_skill_level}) affects conversation style ONLY, not code updates. |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Remove duplicate critical directives.
Lines 11-17 duplicate lines 49-58 verbatim. This violates DRY and creates a maintenance burden—if these rules change, they must be updated in two places, risking divergence.
♻️ Proposed fix: Remove duplication
Option 1 (recommended): Keep directives only in EXECUTION section (lines 49-58) and reference them from the intro:
**Your Role:** Developer implementing the story.
-- Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level}
-- Generate all documents in {document_output_language}
-- Only modify the story file in these areas: Tasks/Subtasks checkboxes, Dev Agent Record (Debug Log, Completion Notes), File List, Change Log, and Status
-- Execute ALL steps in exact order; do NOT skip steps
-- Absolutely DO NOT stop because of "milestones", "significant progress", or "session boundaries". Continue in a single execution until the story is COMPLETE (all ACs satisfied and all tasks/subtasks checked) UNLESS a HALT condition is triggered or the USER gives other instruction.
-- Do NOT schedule a "next session" or request review pauses unless a HALT condition applies. Only Step 6 decides completion.
-- User skill level ({user_skill_level}) affects conversation style ONLY, not code updates.
+- Follow all critical behavioral constraints defined in the EXECUTION section below.Option 2: Keep directives only in intro and remove from EXECUTION section.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/bmm/workflows/4-implementation/dev-story/workflow.md` around lines 11 -
17, The workflow.md file contains duplicate critical directives present in the
intro and again in the EXECUTION section; remove the duplicated block from the
intro and leave the canonical directives only in the EXECUTION section, then
replace the removed intro text with a short reference pointing readers to the
EXECUTION section for the rules (preserve the exact directives text only once
and keep items like "Tasks/Subtasks checkboxes, Dev Agent Record (Debug Log,
Completion Notes), File List, Change Log, and Status" and the HALT/Step 6
language intact in the retained EXECUTION copy so nothing else changes).
|
|
||
| - `installed_path` = `{project-root}/_bmad/bmm/workflows/4-implementation/dev-story` | ||
| - `validation` = `{installed_path}/checklist.md` | ||
| - `story_file` = `` (explicit story path; auto-discovered if empty) |
There was a problem hiding this comment.
Variable name mismatch: story_file defined but story_path used throughout.
Line 37 defines story_file as the explicit story path variable, but the workflow uses {{story_path}} everywhere (lines 61, 62, 107, 108, 118, 151, etc.). This semantic mismatch will cause runtime failures when the workflow tries to reference an undefined variable.
🐛 Proposed fix
-- `story_file` = `` (explicit story path; auto-discovered if empty)
+- `story_path` = `` (explicit story path; auto-discovered if empty)Alternatively, if story_file is the intended name, update all 10+ references from {{story_path}} to {{story_file}} throughout lines 61-163.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/bmm/workflows/4-implementation/dev-story/workflow.md` at line 37, The
workflow defines the explicit variable as story_file but the template references
story_path throughout, causing undefined variable errors; choose one name and
make it consistent: either rename the variable declaration from story_file to
story_path or update every template reference (all occurrences of
{{story_path}}) to {{story_file}} so the variable name matches (check places
where {{story_path}} is used and the declaration where story_file is set, e.g.,
the variable definition and all template interpolations).
| <action>Identify first incomplete task (unchecked [ ]) in Tasks/Subtasks</action> | ||
|
|
||
| <action if="no incomplete tasks"> | ||
| <goto step="6">Completion sequence</goto> |
There was a problem hiding this comment.
Incorrect goto target: should jump to Step 9, not Step 6.
When no incomplete tasks remain, line 176 jumps to Step 6 ("Author comprehensive tests") with the comment "Completion sequence." This is wrong—Step 6 is about test authoring, not completion. The correct target is Step 9 ("Story completion and mark for review").
This critical control flow error would cause the workflow to author tests unnecessarily when the story is already complete.
🐛 Proposed fix
<action if="no incomplete tasks">
- <goto step="6">Completion sequence</goto>
+ <goto step="9">Completion sequence</goto>
</action>🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/bmm/workflows/4-implementation/dev-story/workflow.md` at line 176, The
goto target is incorrect: replace the <goto step="6">Completion sequence</goto>
entry so it points to Step 9 instead of Step 6; update the goto to reference
step="9" (so the flow moves to "Story completion and mark for review" rather
than "Author comprehensive tests") to ensure the completion sequence branches to
the correct step.
Comment on lines
+186
to
+189
| <action>Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Dev Agent Record, File List, Change Log, Status</action> | ||
| <action>Load comprehensive context from story file's Dev Notes section</action> | ||
| <action>Extract developer guidance from Dev Notes: architecture requirements, previous learnings, technical specifications</action> | ||
| <action>Use enhanced story context to inform implementation decisions and approaches</action> |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Duplicate parsing logic already performed in Step 1.
Lines 186-189 repeat the exact parsing operations from lines 167-171 in Step 1:
- Parse story sections
- Load Dev Notes
- Extract developer guidance
- Use enhanced story context
This duplication is wasteful and risks divergence if one location is updated without the other. Step 2's goal is "Load project context and story information," but the story information was already loaded in Step 1.
♻️ Proposed fix: Remove duplicate story parsing from Step 2
<step n="2" goal="Load project context and story information">
<critical>Load all available context to inform implementation</critical>
<action>Load {project_context} for coding standards and project-wide patterns (if exists)</action>
- <action>Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Dev Agent Record, File List, Change Log, Status</action>
- <action>Load comprehensive context from story file's Dev Notes section</action>
- <action>Extract developer guidance from Dev Notes: architecture requirements, previous learnings, technical specifications</action>
- <action>Use enhanced story context to inform implementation decisions and approaches</action>
<output>✅ **Context Loaded**
- Story and project context available for implementation
+ Project context available for implementation (story context loaded in Step 1)
</output>
</step>🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/bmm/workflows/4-implementation/dev-story/workflow.md` around lines 186 -
189, Step 2 currently duplicates the story parsing performed in Step 1: remove
the repeated action lines ("Parse sections: Story, Acceptance Criteria,
Tasks/Subtasks, Dev Notes, Dev Agent Record, File List, Change Log, Status",
"Load comprehensive context from story file's Dev Notes section", "Extract
developer guidance from Dev Notes: architecture requirements, previous
learnings, technical specifications", "Use enhanced story context to inform
implementation decisions and approaches") from the Step 2 block and leave Step 2
focused on loading project-level context only; ensure any references to story
data in Step 2 instead reference the canonical story load in Step 1 (the
original Parse sections / Load comprehensive context actions) to avoid
duplication and divergence.
Comment on lines
+301
to
+306
| <step n="6" goal="Author comprehensive tests"> | ||
| <action>Create unit tests for business logic and core functionality introduced/changed by the task</action> | ||
| <action>Add integration tests for component interactions specified in story requirements</action> | ||
| <action>Include end-to-end tests for critical user flows when story requirements demand them</action> | ||
| <action>Cover edge cases and error handling scenarios identified in story Dev Notes</action> | ||
| </step> |
There was a problem hiding this comment.
Test authoring responsibility unclear: Step 5 already writes tests.
Step 5 (lines 277-282) implements red-green-refactor, which includes writing failing tests first, then making them pass. Step 6 is then titled "Author comprehensive tests" and describes writing unit, integration, and e2e tests.
This creates ambiguity:
- Are tests written in Step 5 or Step 6?
- Does Step 5 write minimal tests and Step 6 expand them?
- Is Step 6 redundant?
The workflow loops back from Step 8 to Step 5 for each task (line 362), so Step 6 executes after every task completion, which seems wrong—comprehensive tests should be authored once per story, not per task.
Clarify the test authoring strategy. Possible fixes:
- Option A: Step 5 writes task-specific tests (red-green-refactor), Step 6 is removed, and comprehensive test authoring moves to Step 9 before completion.
- Option B: Step 5 implements code only, Step 6 writes all tests, but then the red-green-refactor cycle is broken.
- Option C: Explicitly document that Step 5 writes minimal tests and Step 6 adds comprehensive coverage after each task.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/bmm/workflows/4-implementation/dev-story/workflow.md` around lines 301 -
306, Clarify test authoring by adopting Option A: keep Step 5's
"red-green-refactor" as the place for task-specific, minimal failing->passing
tests, remove the current Step 6 "Author comprehensive tests" block, and
relocate comprehensive test responsibilities to Step 9
(pre-completion/acceptance) so full unit/integration/e2e coverage is produced
once per story; also update the loop description that jumps from Step 8 back to
Step 5 to state that comprehensive tests are only done in Step 9 and not on
every task iteration, and adjust any wording referencing "Step 6" or
"comprehensive tests" to point to Step 9 and the red-green-refactor practice in
Step 5.
Merge workflow.yaml config and instructions.xml content into a single workflow.md, following the established conversion pattern. Drop engine scaffolding directives, preserve all behavioral constraints verbatim. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
alexeyv
force-pushed
the
convert-dev-story-yaml-to-md
branch
from
18c073f to
46c885c
Compare
This was referenced Mar 13, 2026
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
dev-storyworkflow from legacy two-file format (workflow.yaml+instructions.xml) to singleworkflow.md<critical>directives, preserve all behavioral constraints verbatimTest plan
🤖 Generated with Claude Code