mirror of
https://github.com/bmadcode/BMAD-METHOD.git
synced 2025-12-29 16:14:59 +00:00
path fixes, documentation updates, md-xplodr added to core tools
This commit is contained in:
Brian Madison
@@ -1,7 +1,7 @@
|
||||
# Develop Story - Workflow Instructions
|
||||
|
||||
```xml
|
||||
<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml</critical>
|
||||
<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
|
||||
<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
|
||||
<critical>Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level}</critical>
|
||||
<critical>Generate all documents in {document_output_language}</critical>
|
||||
@@ -52,7 +52,7 @@
|
||||
|
||||
<action>Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Dev Agent Record, File List, Change Log, Status</action>
|
||||
|
||||
<action>Check if context file exists at: {{story_dir}}/{{story_key}}.context.md</action>
|
||||
<action>Check if context file exists at: {{story_dir}}/{{story_key}}.context.xml</action>
|
||||
<check if="context file exists">
|
||||
<action>Read COMPLETE context file</action>
|
||||
<action>Parse all sections: story details, artifacts (docs, code, dependencies), interfaces, constraints, tests</action>
|
||||
@@ -105,15 +105,15 @@ Expected ready-for-dev or in-progress. Continuing anyway...
|
||||
<action if="new or different than what is documented dependencies are needed">ASK user for approval before adding</action>
|
||||
<action if="3 consecutive implementation failures occur">HALT and request guidance</action>
|
||||
<action if="required configuration is missing">HALT: "Cannot proceed without necessary configuration files"</action>
|
||||
<action if="{{run_until_complete}} == true">Do not stop after partial progress; continue iterating tasks until all ACs are satisfied or a HALT condition triggers</action>
|
||||
<critical>Do NOT propose to pause for review, standups, or validation until Step 6 gates are satisfied</critical>
|
||||
<critical>Do not stop after partial progress; continue iterating tasks until all ACs are satisfied and tested or a HALT condition triggers</critical>
|
||||
<critical>Do NOT propose to pause for review, stand-ups, or validation until Step 6 gates are satisfied</critical>
|
||||
</step>
|
||||
|
||||
<step n="3" 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 where applicable</action>
|
||||
<action>Include end-to-end tests for critical user flows if applicable</action>
|
||||
<action>Cover edge cases and error handling scenarios noted in the plan</action>
|
||||
<action>Add integration tests for component interactions where desired by test plan or story notes</action>
|
||||
<action>Include end-to-end tests for critical user flows where desired by test plan or story notes</action>
|
||||
<action>Cover edge cases and error handling scenarios noted in the test plan or story notes</action>
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Run validations and tests">
|
||||
|
||||
@@ -7,13 +7,16 @@ config_source: "{project-root}/bmad/bmm/config.yaml"
|
||||
output_folder: "{config_source}:output_folder"
|
||||
user_name: "{config_source}:user_name"
|
||||
communication_language: "{config_source}:communication_language"
|
||||
user_skill_level: "{config_source}:user_skill_level"
|
||||
document_output_language: "{config_source}:document_output_language"
|
||||
story_dir: "{config_source}:dev_story_location"
|
||||
context_path: "{config_source}:dev_story_location"
|
||||
run_until_complete: "{config_source}:run_until_complete"
|
||||
run_tests_command: "{config_source}:run_tests_command"
|
||||
date: system-generated
|
||||
|
||||
story_file: "" # Explicit story path; auto-discovered if empty
|
||||
# Context file uses same story_key as story file (e.g., "1-2-user-authentication.context.md")
|
||||
context_file: "{story_dir}/{{story_key}}.context.md"
|
||||
# Context file uses same story_key as story file (e.g., "1-2-user-authentication.context.xml")
|
||||
context_file: "{story_dir}/{{story_key}}.context.xml"
|
||||
|
||||
# Workflow components
|
||||
installed_path: "{project-root}/bmad/bmm/workflows/4-implementation/dev-story"
|
||||
|
||||
@@ -55,7 +55,7 @@
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Resolve story context file and specification inputs">
|
||||
<action>Locate story context file: Under Dev Agent Record → Context Reference, read referenced path(s). If missing, search {{output_folder}} for files matching pattern "story-{{epic_num}}.{{story_num}}*.context.md" and use the most recent.</action>
|
||||
<action>Locate story context file: Under Dev Agent Record → Context Reference, read referenced path(s). If missing, search {{output_folder}} for files matching pattern "story-{{epic_num}}.{{story_num}}*.context.xml" and use the most recent.</action>
|
||||
<action if="no story context file found">Continue but record a WARNING in review notes: "No story context file found"</action>
|
||||
|
||||
<action>Locate Epic Tech Spec: Search {{tech_spec_search_dir}} with glob {{tech_spec_glob_template}} (resolve {{epic_num}})</action>
|
||||
|
||||
@@ -49,6 +49,6 @@ variables:
|
||||
recommended_inputs:
|
||||
- story: "Path to the story file (auto-discovered if omitted - finds first story with status 'review')"
|
||||
- tech_spec: "Epic technical specification document (auto-discovered)"
|
||||
- story_context_file: "Story context file (.context.md) (auto-discovered)"
|
||||
- story_context_file: "Story context file (.context.xml) (auto-discovered)"
|
||||
|
||||
web_bundle: false
|
||||
|
||||
@@ -9,7 +9,7 @@
|
||||
<critical>If story_path is provided, use it. Otherwise, find the first story with status "drafted" in sprint-status.yaml. If none found, HALT.</critical>
|
||||
<critical>Check if context file already exists. If it does, ask user if they want to replace it, verify it, or cancel.</critical>
|
||||
|
||||
<critical>DOCUMENT OUTPUT: Technical context file (.context.md). Concise, structured, project-relative paths only.</critical>
|
||||
<critical>DOCUMENT OUTPUT: Technical context file (.context.xml). Concise, structured, project-relative paths only.</critical>
|
||||
|
||||
<workflow>
|
||||
<step n="1" goal="Find drafted story and check for existing context" tag="sprint-status">
|
||||
|
||||
@@ -25,6 +25,6 @@ variables:
|
||||
|
||||
# Output configuration
|
||||
# Uses story_key from sprint-status.yaml (e.g., "1-2-user-authentication")
|
||||
default_output_file: "{story_dir}/{{story_key}}.context.md"
|
||||
default_output_file: "{story_dir}/{{story_key}}.context.xml"
|
||||
|
||||
web_bundle: false
|
||||
|
||||
@@ -1,343 +0,0 @@
|
||||
# Workflow Audit Report
|
||||
|
||||
**Workflow:** story-ready
|
||||
**Audit Date:** 2025-10-25
|
||||
**Auditor:** Audit Workflow (BMAD v6)
|
||||
**Workflow Type:** Action (status update workflow)
|
||||
**Module:** BMM (BMad Method)
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
**Overall Status:** EXCELLENT
|
||||
|
||||
- Critical Issues: 2
|
||||
- Important Issues: 2
|
||||
- Cleanup Recommendations: 0
|
||||
|
||||
**Pass Rate:** 94% (66/70 checks passed)
|
||||
|
||||
The story-ready workflow is well-structured and follows most BMAD v6 conventions. The workflow correctly uses `web_bundle: false` (intentional for local-only workflow). Critical issues relate to variable inconsistencies and undeclared config variables that are used in instructions.
|
||||
|
||||
---
|
||||
|
||||
## 1. Standard Config Block Validation
|
||||
|
||||
**Status:** ⚠️ CRITICAL ISSUES FOUND
|
||||
|
||||
### Required Variables Check:
|
||||
|
||||
✅ `config_source` is defined and points to correct module config path
|
||||
✅ Uses {project-root} variable correctly
|
||||
✅ `output_folder` pulls from config_source
|
||||
✅ `user_name` pulls from config_source
|
||||
✅ `communication_language` pulls from config_source
|
||||
✅ `date` is set to system-generated
|
||||
✅ Standard config comment present: "Critical variables from config"
|
||||
|
||||
### Critical Issues:
|
||||
|
||||
#### Issue 1: Missing Config Variables in YAML
|
||||
|
||||
**Severity:** CRITICAL
|
||||
**Location:** workflow.yaml
|
||||
|
||||
The instructions.md file uses the following config variables that are NOT declared in workflow.yaml:
|
||||
|
||||
1. `{user_skill_level}` - Used in line 5: "language MUST be tailored to {user_skill_level}"
|
||||
2. `{document_output_language}` - Used in line 6: "Generate all documents in {document_output_language}"
|
||||
|
||||
**Impact:** These variables will not be resolved by the workflow engine, potentially causing confusion or errors.
|
||||
|
||||
**Fix Required:**
|
||||
|
||||
```yaml
|
||||
# Critical variables from config
|
||||
config_source: '{project-root}/bmad/bmm/config.yaml'
|
||||
output_folder: '{config_source}:output_folder'
|
||||
user_name: '{config_source}:user_name'
|
||||
communication_language: '{config_source}:communication_language'
|
||||
user_skill_level: '{config_source}:user_skill_level' # ADD THIS
|
||||
document_output_language: '{config_source}:document_output_language' # ADD THIS
|
||||
date: system-generated
|
||||
```
|
||||
|
||||
#### Issue 2: Variable Path Inconsistency
|
||||
|
||||
**Severity:** CRITICAL
|
||||
**Location:** instructions.md line 3
|
||||
|
||||
Instructions reference `{project_root}` (underscore) but workflow.yaml uses `{project-root}` (hyphen).
|
||||
|
||||
**Current:** `<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml</critical>`
|
||||
|
||||
**Should be:** `<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>`
|
||||
|
||||
**Impact:** Variable will not resolve correctly, breaking the reference path.
|
||||
|
||||
---
|
||||
|
||||
## 2. YAML/Instruction/Template Alignment
|
||||
|
||||
**Status:** ✅ GOOD (with minor observations)
|
||||
|
||||
### Variables Analyzed:
|
||||
|
||||
**Workflow.yaml variables (excluding standard config):**
|
||||
|
||||
- `story_path` - Used in instructions ✓
|
||||
- `story_dir` - Used in instructions ✓
|
||||
|
||||
**Variables Used in Instructions (not in YAML):**
|
||||
|
||||
- `{{story_key}}` - Generated dynamically, output via parsing ✓
|
||||
- `{{drafted_count}}` - Generated dynamically ✓
|
||||
- `{{list_of_drafted_story_keys}}` - Generated dynamically ✓
|
||||
- `{{non_interactive}}` - Conditional logic variable (may be from agent context)
|
||||
- `{{story_file}}` - Generated dynamically ✓
|
||||
- `{{story_id}}` - Extracted from story file ✓
|
||||
- `{{story_title}}` - Extracted from story file ✓
|
||||
|
||||
### Summary:
|
||||
|
||||
- **Variables in YAML:** 2 (story_path, story_dir)
|
||||
- **Used in Instructions:** 2/2 (100%)
|
||||
- **Unused (Bloat):** 0
|
||||
- **Dynamic Variables:** 7 (appropriate for action workflow)
|
||||
|
||||
**Status:** Excellent - No bloat detected, all YAML variables are used appropriately.
|
||||
|
||||
---
|
||||
|
||||
## 3. Config Variable Usage
|
||||
|
||||
**Status:** ⚠️ IMPORTANT ISSUES FOUND
|
||||
|
||||
### Communication Language Check:
|
||||
|
||||
✅ Instructions use {communication_language} in critical header (line 5)
|
||||
⚠️ However, the instruction says "Communicate all responses in {communication_language}" but the actual workflow outputs don't explicitly enforce language adaptation
|
||||
|
||||
### User Name Check:
|
||||
|
||||
✅ User name properly used in final output (line 87): "**Story Marked Ready for Development, {user_name}!**"
|
||||
✅ Appropriate personalization in workflow completion message
|
||||
|
||||
### Output Folder Check:
|
||||
|
||||
✅ Output folder referenced correctly: `{{output_folder}}/sprint-status.yaml` (lines 18, 70)
|
||||
✅ No hardcoded paths detected
|
||||
✅ All file operations use proper variable references
|
||||
|
||||
### Date Usage Check:
|
||||
|
||||
✅ Date is available for agent awareness
|
||||
✅ Not used in outputs (appropriate for action workflow with no document generation)
|
||||
|
||||
### User Skill Level Check:
|
||||
|
||||
❌ **CRITICAL:** Variable used but not declared in workflow.yaml (line 5)
|
||||
|
||||
### Document Output Language Check:
|
||||
|
||||
❌ **CRITICAL:** Variable used but not declared in workflow.yaml (line 6)
|
||||
|
||||
**Config Variable Summary:**
|
||||
|
||||
- `communication_language`: ✅ Properly declared and used
|
||||
- `user_name`: ✅ Properly declared and used
|
||||
- `output_folder`: ✅ Properly declared and used
|
||||
- `date`: ✅ Properly declared (available but not used - appropriate)
|
||||
- `user_skill_level`: ❌ Used but NOT declared
|
||||
- `document_output_language`: ❌ Used but NOT declared
|
||||
|
||||
---
|
||||
|
||||
## 4. Web Bundle Validation
|
||||
|
||||
**Status:** ✅ CORRECT (N/A)
|
||||
|
||||
**Web Bundle Present:** No (`web_bundle: false`)
|
||||
|
||||
**Analysis:** The workflow correctly sets `web_bundle: false`. This is appropriate because:
|
||||
|
||||
1. This is a local-only action workflow
|
||||
2. It directly modifies files in the project (sprint-status.yaml, story files)
|
||||
3. It requires access to the specific project's file system
|
||||
4. It cannot be executed in a web bundle context where file system access is sandboxed
|
||||
|
||||
**Finding:** The absence of web bundle configuration is **EXPECTED and CORRECT** for this workflow type.
|
||||
|
||||
**No issues found.**
|
||||
|
||||
---
|
||||
|
||||
## 5. Bloat Detection
|
||||
|
||||
**Status:** ✅ EXCELLENT
|
||||
|
||||
### Bloat Analysis:
|
||||
|
||||
**Total YAML Fields (excluding metadata and standard config):** 2
|
||||
|
||||
- `story_path`
|
||||
- `story_dir`
|
||||
|
||||
**Used Fields:** 2
|
||||
**Unused Fields:** 0
|
||||
|
||||
**Bloat Percentage:** 0%
|
||||
|
||||
### Hardcoded Values Check:
|
||||
|
||||
✅ No hardcoded file paths (uses {output_folder})
|
||||
✅ No hardcoded greetings (uses {user_name})
|
||||
✅ No language-specific text (uses {communication_language})
|
||||
✅ No static dates (date variable available)
|
||||
|
||||
### Redundant Configuration:
|
||||
|
||||
✅ No duplicate fields between sections
|
||||
✅ No commented-out variables
|
||||
✅ No metadata repetition
|
||||
|
||||
**Bloat Summary:** Zero bloat detected. Workflow is lean and efficient.
|
||||
|
||||
---
|
||||
|
||||
## 6. Template Variable Mapping
|
||||
|
||||
**Status:** N/A (Not a document workflow)
|
||||
|
||||
This workflow is an action workflow (status update), not a document workflow, so template validation does not apply.
|
||||
|
||||
**No template.md file required or expected.**
|
||||
|
||||
---
|
||||
|
||||
## 7. Additional Quality Checks
|
||||
|
||||
### Instruction Quality:
|
||||
|
||||
✅ Steps properly numbered (n="1", n="2", n="3")
|
||||
✅ Each step has clear goal attribute
|
||||
✅ XML tags used correctly (<action>, <ask>, <check>, <output>, <anchor>)
|
||||
✅ Conditional logic properly implemented (if attributes)
|
||||
✅ Flow control is clear and logical
|
||||
✅ Steps are focused on single goals
|
||||
✅ Specific, actionable instructions provided
|
||||
✅ Critical sections properly marked with <critical> tags
|
||||
|
||||
### Special Features:
|
||||
|
||||
✅ Anchor tag used correctly: `<anchor id="mark_ready" />` (line 59)
|
||||
✅ Proper GOTO logic: "GOTO mark_ready" (line 15)
|
||||
✅ Conditional user interaction: `<ask if="{{non_interactive}} == false">` (line 53)
|
||||
✅ Auto-selection for non-interactive mode (line 54)
|
||||
|
||||
### File References:
|
||||
|
||||
✅ sprint-status.yaml referenced with proper variable path
|
||||
✅ Story files referenced with proper directory variable
|
||||
✅ Preservation instructions included (line 74): "Save file, preserving ALL comments and structure including STATUS DEFINITIONS"
|
||||
|
||||
---
|
||||
|
||||
## Recommendations
|
||||
|
||||
### Critical (Fix Immediately)
|
||||
|
||||
**1. Add Missing Config Variables to workflow.yaml**
|
||||
|
||||
```yaml
|
||||
user_skill_level: '{config_source}:user_skill_level'
|
||||
document_output_language: '{config_source}:document_output_language'
|
||||
```
|
||||
|
||||
**2. Fix Variable Path Inconsistency**
|
||||
Change line 3 in instructions.md from:
|
||||
|
||||
```
|
||||
{project_root}/bmad/core/tasks/workflow.xml
|
||||
```
|
||||
|
||||
to:
|
||||
|
||||
```
|
||||
{project-root}/bmad/core/tasks/workflow.xml
|
||||
```
|
||||
|
||||
### Important (Address Soon)
|
||||
|
||||
**3. Clarify non_interactive Variable Source**
|
||||
The `{{non_interactive}}` variable is used in line 53-54 but not defined in workflow.yaml. Either:
|
||||
|
||||
- Add to workflow.yaml if it's a workflow-specific variable
|
||||
- Document that it comes from agent context
|
||||
- Remove if not implemented yet
|
||||
|
||||
**4. Document user_skill_level and document_output_language Usage**
|
||||
If these variables are standard across all BMM workflows:
|
||||
|
||||
- Ensure they exist in the module's config.yaml
|
||||
- Add comments explaining their purpose
|
||||
- Verify they're actually needed for this action workflow (this workflow generates no documents, so document_output_language may not be necessary)
|
||||
|
||||
### Cleanup (Nice to Have)
|
||||
|
||||
**No cleanup recommendations** - The workflow is already lean and efficient.
|
||||
|
||||
---
|
||||
|
||||
## Validation Checklist
|
||||
|
||||
Use this checklist to verify fixes:
|
||||
|
||||
- [ ] user_skill_level added to workflow.yaml standard config block
|
||||
- [ ] document_output_language added to workflow.yaml standard config block
|
||||
- [ ] {project_root} changed to {project-root} in instructions.md line 3
|
||||
- [ ] non_interactive variable source documented or defined
|
||||
- [ ] All standard config variables present and correct
|
||||
- [ ] No unused yaml fields (bloat removed) ✓ (already clean)
|
||||
- [ ] Config variables used appropriately in instructions ✓
|
||||
- [ ] Web bundle configuration correct ✓ (intentionally false)
|
||||
- [ ] File structure follows v6 conventions ✓
|
||||
|
||||
---
|
||||
|
||||
## Overall Assessment
|
||||
|
||||
### Strengths:
|
||||
|
||||
1. **Zero bloat** - Every YAML variable is used, no waste
|
||||
2. **Clear workflow logic** - Simple, focused status update process
|
||||
3. **Proper file handling** - Uses variables for all paths, preserves file structure
|
||||
4. **Good UX** - Helpful output messages, clear next steps
|
||||
5. **Conditional logic** - Supports both interactive and non-interactive modes
|
||||
6. **Proper web_bundle setting** - Correctly set to false for local-only workflow
|
||||
|
||||
### Weaknesses:
|
||||
|
||||
1. Uses config variables not declared in workflow.yaml (user_skill_level, document_output_language)
|
||||
2. Variable naming inconsistency (project_root vs project-root)
|
||||
3. Unclear source of non_interactive variable
|
||||
|
||||
### Overall Grade: **A-** (94%)
|
||||
|
||||
This is a well-crafted workflow that follows BMAD v6 conventions closely. The critical issues are minor and easily fixable. Once the missing config variables are added and the path inconsistency is resolved, this workflow will be production-ready.
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Immediate:** Add user_skill_level and document_output_language to workflow.yaml
|
||||
2. **Immediate:** Fix {project_root} → {project-root} in instructions.md
|
||||
3. **Soon:** Clarify or remove non_interactive variable usage
|
||||
4. **Soon:** Verify these config variables exist in src/modules/bmm/config.yaml (when it's created)
|
||||
5. **Optional:** Re-run audit after fixes to verify 100% pass rate
|
||||
|
||||
---
|
||||
|
||||
**Audit Complete** - Generated by audit-workflow v1.0
|
||||
**Report Location:** /Users/brianmadison/dev/BMAD-METHOD/src/modules/bmm/workflows/4-implementation/story-ready/AUDIT-REPORT.md
|
||||
Reference in New Issue
Block a user