bmad-method 6.0.0-alpha.21 → 6.0.0-alpha.23

package/src/modules/bmb/workflows/module/steps-v/step-04-agent-specs.md

@@ -0,0 +1,152 @@
+---
+name: 'step-04-agent-specs'
+description: 'Validate agent specifications and built agents'
+
+nextStepFile: './step-05-workflow-specs.md'
+agentSpecTemplate: '../../templates/agent-spec-template.md'
+agentArchitectureFile: '../../data/agent-architecture.md'
+agentValidationWorkflow: '{project-root}/_bmad/bmb/workflows/agent/steps-v/step-01-validate.md'
+validationReportOutput: '{validation_report_output}'
+targetPath: '{validation_target_path}'
+---
+
+# Step 4: Agent Specs Validation
+
+## STEP GOAL:
+
+Validate agent specifications and/or built agents, distinguishing between placeholder specs and fully implemented agents.
+
+## MANDATORY EXECUTION RULES:
+
+### Universal Rules:
+- 📖 CRITICAL: Read the complete step file before taking any action
+- ✅ Speak in `{communication_language}`
+
+### Role Reinforcement:
+- ✅ You are the **Quality Assurance** — dual-mode checking
+- ✅ Specs are expected, built agents are great
+- ✅ Track status of each agent
+
+---
+
+## MANDATORY SEQUENCE
+
+### 1. Load Agent Files
+
+Find all agent files in `{targetPath}/agents/`:
+- `.spec.md` files (placeholder specs)
+- `.agent.yaml` files (built agents)
+
+### 2. Categorize Agents
+
+For each agent found, determine status:
+
+**Built Agents (.agent.yaml):**
+- Full implementation with complete persona, menu YAML
+- Can be validated in-depth via agent validation workflow
+
+**Spec Agents (.spec.md):**
+- High-level placeholder/blueprint
+- Awaiting creation via agent-builder workflow
+
+Track counts:
+- Total agents: {count}
+- Built agents: {count}
+- Spec agents: {count}
+
+### 3. Validate Spec Agents (.spec.md)
+
+For each spec agent, check:
+
+**Required Sections:**
+- [ ] Agent metadata (id, name, title, icon, module)
+- [ ] Role defined
+- [ ] Identity or communication style
+- [ ] Menu triggers documented
+- [ ] hasSidecar decision documented
+
+**Menu Triggers:**
+- [ ] At least one trigger per agent
+- [ ] Trigger → workflow mapping clear
+- [ ] No duplicate triggers (warn if found)
+
+**hasSidecar Documentation:**
+- [ ] Decision documented (true or false)
+- [ ] Rationale if true (why memory needed)
+
+**Placeholder Note:** These are specs awaiting agent-builder.
+
+### 4. Validate Built Agents (.agent.yaml)
+
+For each built agent, check:
+
+**Frontmatter Completeness:**
+- [ ] agent.metadata exists
+- [ ] agent.persona exists
+- [ ] agent.menu exists
+
+**YAML Structure:**
+- [ ] Valid YAML syntax
+- [ ] Required fields present
+
+**Status:** These are complete implementations and can be validated in detail via sub-process.
+
+### 5. Record Results
+
+Append to `{validationReportOutput}`:
+
+```markdown
+## Agent Specs Validation
+
+**Status:** {PASS/FAIL/WARNINGS}
+
+**Agent Summary:**
+- Total Agents: {count}
+- Built Agents: {count} {list}
+- Spec Agents: {count} {list}
+
+**Built Agents:**
+{for each built agent}
+- **{name}**: {status} - Ready for detailed validation via agent workflow
+
+**Spec Agents:**
+{for each spec agent}
+- **{name}**: {status} - Placeholder awaiting agent-builder
+
+**Issues Found:**
+{list any issues}
+
+**Recommendations:**
+{if specs exist}
+- Use `bmad:bmb:agents:agent-builder` to create {spec agent names}
+- After building agents, re-run validation to verify compliance
+{endif}
+```
+
+### 6. Note Sub-Process Opportunity
+
+**IF built agents exist:**
+
+"**The following built agents can be validated in detail:**"
+
+{list built agents}
+
+"**After this validation completes, I can spawn sub-processes to run the agent validation workflow on each built agent for deeper compliance checking.**"
+
+### 7. Auto-Proceed
+
+"**✓ Agent specs check complete.**"
+
+Proceeding to next validation...
+
+Load `{nextStepFile}`
+
+---
+
+## Success Metrics
+
+✅ All agent files checked
+✅ Status tracked (spec vs built)
+✅ hasSidecar decisions validated
+✅ Recommendations for specs documented
+✅ Sub-process opportunity noted

package/src/modules/bmb/workflows/module/steps-v/step-05-workflow-specs.md

@@ -0,0 +1,152 @@
+---
+name: 'step-05-workflow-specs'
+description: 'Validate workflow specifications and built workflows'
+
+nextStepFile: './step-06-documentation.md'
+workflowSpecTemplate: '../../templates/workflow-spec-template.md'
+workflowValidationWorkflow: '{project-root}/_bmad/bmb/workflows/workflow/steps-v/step-01-validate.md'
+validationReportOutput: '{validation_report_output}'
+targetPath: '{validation_target_path}'
+---
+
+# Step 5: Workflow Specs Validation
+
+## STEP GOAL:
+
+Validate workflow specifications and/or built workflows, distinguishing between placeholder specs and fully implemented workflows.
+
+## MANDATORY EXECUTION RULES:
+
+### Universal Rules:
+- 📖 CRITICAL: Read the complete step file before taking any action
+- ✅ Speak in `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are the **Quality Assurance** — dual-mode checking
+- ✅ Specs are expected, built workflows are great
+- ✅ Track status of each workflow
+
+---
+
+## MANDATORY SEQUENCE
+
+### 1. Load Workflow Files
+
+Find all workflow files in `{targetPath}/workflows/`:
+- `.spec.md` files (placeholder specs)
+- `workflow.md` files (built workflows)
+
+### 2. Categorize Workflows
+
+For each workflow found, determine status:
+
+**Built Workflows (workflow.md with steps/ folder):**
+- Full implementation with step files, data, templates
+- Can be validated in-depth via workflow validation workflow
+
+**Spec Workflows (.spec.md):**
+- High-level placeholder/blueprint
+- Awaiting creation via workflow-builder workflow
+
+Track counts:
+- Total workflows: {count}
+- Built workflows: {count}
+- Spec workflows: {count}
+
+### 3. Validate Spec Workflows (.spec.md)
+
+For each spec workflow, check:
+
+**Required Sections:**
+- [ ] Workflow goal defined
+- [ ] Description present
+- [ ] Workflow type indicated
+- [ ] Step list or outline present
+- [ ] Agent association clear
+
+**Inputs/Outputs:**
+- [ ] Input requirements documented
+- [ ] Output format specified
+
+**Agent Integration:**
+- [ ] Primary agent identified
+- [ ] Multi-agent collaboration noted (if applicable)
+
+**Placeholder Note:** These are specs awaiting workflow-builder.
+
+### 4. Validate Built Workflows (workflow.md)
+
+For each built workflow, check:
+
+**Workflow Structure:**
+- [ ] workflow.md exists with proper frontmatter
+- [ ] steps/ folder exists (steps-c/, steps-e/, steps-v/ as appropriate)
+- [ ] Step files follow naming conventions
+
+**Step File Compliance:**
+- [ ] Each step has proper frontmatter
+- [ ] Step files within size limits
+- [ ] Menu handling follows standards
+
+**Status:** These are complete implementations and can be validated in detail via sub-process.
+
+### 5. Record Results
+
+Append to `{validationReportOutput}`:
+
+```markdown
+## Workflow Specs Validation
+
+**Status:** {PASS/FAIL/WARNINGS}
+
+**Workflow Summary:**
+- Total Workflows: {count}
+- Built Workflows: {count} {list}
+- Spec Workflows: {count} {list}
+
+**Built Workflows:**
+{for each built workflow}
+- **{name}**: {status} - Ready for detailed validation via workflow workflow
+
+**Spec Workflows:**
+{for each spec workflow}
+- **{name}**: {status} - Placeholder awaiting workflow-builder
+
+**Issues Found:**
+{list any issues}
+
+**Recommendations:**
+{if specs exist}
+- Use `bmad:bmb:workflows:workflow` or `/workflow` to create {spec workflow names}
+- After building workflows, re-run validation to verify compliance
+{endif}
+```
+
+### 6. Note Sub-Process Opportunity
+
+**IF built workflows exist:**
+
+"**The following built workflows can be validated in detail:**"
+
+{list built workflows}
+
+"**After this validation completes, I can spawn sub-processes to run the workflow validation workflow on each built workflow for deeper compliance checking.**"
+
+### 7. Auto-Proceed
+
+"**✓ Workflow specs check complete.**"
+
+Proceeding to next validation...
+
+Load `{nextStepFile}`
+
+---
+
+## Success Metrics
+
+✅ All workflow files checked
+✅ Status tracked (spec vs built)
+✅ Agent associations validated
+✅ Recommendations for specs documented
+✅ Sub-process opportunity noted

package/src/modules/bmb/workflows/module/steps-v/step-06-documentation.md

@@ -0,0 +1,143 @@
+---
+name: 'step-06-documentation'
+description: 'Validate documentation (README.md, TODO.md, docs/)'
+
+nextStepFile: './step-07-installation.md'
+validationReportOutput: '{validation_report_output}'
+targetPath: '{validation_target_path}'
+moduleBriefPath: '{module_brief_path}'
+---
+
+# Step 6: Documentation Validation
+
+## STEP GOAL:
+
+Validate module documentation completeness, including user-facing docs in docs/ folder.
+
+## MANDATORY EXECUTION RULES:
+
+### Universal Rules:
+- 📖 CRITICAL: Read the complete step file before taking any action
+- ✅ Speak in `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are the **Quality Assurance** — checking docs
+- ✅ Documentation matters for usability
+- ✅ User docs can be generated from placeholder plans
+
+---
+
+## MANDATORY SEQUENCE
+
+### 1. Load Documentation Files
+
+Check for:
+- `{targetPath}/README.md` (module overview)
+- `{targetPath}/TODO.md` (development roadmap)
+- `{targetPath}/docs/` (user documentation folder)
+
+### 2. Validate README.md
+
+**Required Sections:**
+- [ ] Module name and description
+- [ ] Installation instructions
+- [ ] Components section (agents, workflows)
+- [ ] Usage examples or quick start
+- [ ] Module structure
+- [ ] Link to docs/ folder
+
+**Quality Checks:**
+- [ ] Clear description of what module does
+- [ ] Installation command shown
+- [ ] Agent/workflow lists complete
+- [ ] References user documentation
+
+### 3. Validate TODO.md
+
+**Required Content:**
+- [ ] Agent build checklist
+- [ ] Workflow build checklist
+- [ ] Testing section
+- [ ] Next steps
+
+### 4. Validate docs/ Folder
+
+**For Custom Modules:**
+- [ ] docs/ folder exists
+- [ ] Contains user-facing documentation
+- [ ] Documentation is clear and helpful
+
+**Valid docs/ Contents (may include):**
+- `getting-started.md` — Quick start guide
+- `agents.md` — Agent documentation
+- `workflows.md` — Workflow documentation
+- `examples.md` — Usage examples
+- `configuration.md` — Setup/configuration guide
+- `troubleshooting.md` — Common issues and solutions
+
+**Quality Check:**
+- [ ] Even with placeholder agent/workflow specs, user docs should provide useful information
+- [ ] Documentation references agents/workflows by name
+- [ ] Clear what functionality exists vs what is planned
+
+### 5. Generate User Docs Recommendation
+
+**IF docs/ missing or incomplete:**
+
+"**User documentation can be generated from module brief and agent/workflow specs.**"
+
+"**Even with placeholder plans, you can create helpful user documentation that describes:**
+- What each agent does and when to use it
+- What workflows are available and their purpose
+- How to get started with the module
+- Configuration options (from module.yaml)"
+
+### 6. Record Results
+
+Append to `{validationReportOutput}`:
+
+```markdown
+## Documentation Validation
+
+**Status:** {PASS/FAIL/WARNINGS}
+
+**Root Documentation:**
+- **README.md:** {present/missing} - {status}
+- **TODO.md:** {present/missing} - {status}
+
+**User Documentation (docs/):**
+- **docs/ folder:** {present/missing} - {status}
+- **Documentation files:** {count} files found
+
+**Docs Contents:**
+{list files in docs/ folder}
+
+**Issues Found:**
+{list any issues}
+
+**Recommendations:**
+{if docs/ missing or incomplete}
+- Generate user documentation from module brief and specs
+- Create getting-started.md, agents.md, workflows.md
+- User docs are valuable even with placeholder plans
+{endif}
+```
+
+### 7. Auto-Proceed
+
+"**✓ Documentation check complete.**"
+
+Proceeding to installation validation...
+
+Load `{nextStepFile}`
+
+---
+
+## Success Metrics
+
+✅ All documentation checked
+✅ Required sections validated
+✅ docs/ folder presence verified
+✅ User documentation quality assessed
+✅ Recommendations documented

package/src/modules/bmb/workflows/module/steps-v/step-07-installation.md

@@ -0,0 +1,113 @@
+---
+name: 'step-07-installation'
+description: 'Installation readiness check'
+
+nextStepFile: './step-08-report.md'
+moduleInstallerStandardsFile: '../../data/module-installer-standards.md'
+validationReportOutput: '{validation_report_output}'
+targetPath: '{validation_target_path}'
+---
+
+# Step 7: Installation Readiness
+
+## STEP GOAL:
+
+Check if the module is ready for installation.
+
+## MANDATORY EXECUTION RULES:
+
+### Universal Rules:
+- 📖 CRITICAL: Read the complete step file before taking any action
+- ✅ Speak in `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are the **Quality Assurance** — checking readiness
+- ✅ Installation should work
+
+---
+
+## MANDATORY SEQUENCE
+
+### 1. Check Installer
+
+**IF `_module-installer/` exists:**
+- [ ] `installer.js` present
+- [ ] Has valid `install()` function
+- [ ] Platform-specific handlers (if any IDEs supported)
+
+**IF `_module-installer/` doesn't exist:**
+- Note: Module may not need installer
+- Check if this is intentional
+
+### 2. Validate installer.js (if present)
+
+Load `{moduleInstallerStandardsFile}` and check:
+
+**Function Signature:**
+- [ ] `async function install(options)`
+- [ ] Accepts: projectRoot, config, installedIDEs, logger
+- [ ] Returns: Promise<boolean>
+
+**Error Handling:**
+- [ ] Try/catch block present
+- [ ] Error logging present
+
+**Platform Validation:**
+- [ ] Uses platformCodes for IDE validation
+- [ ] Graceful handling of unknown platforms
+
+### 3. Check module.yaml Install Variables
+
+**IF custom variables exist:**
+- [ ] All variables have prompts
+- [ ] Defaults are reasonable
+- [ ] Result templates are valid
+
+**Path Variables:**
+- [ ] Paths use `{project-root}/` prefix
+- [ ] Output paths are user-configurable
+
+### 4. Module Type Installation
+
+**IF Extension:**
+- [ ] `code:` matches base (for proper merge)
+- [ ] Folder name is unique
+
+**IF Global:**
+- [ ] `global: true` or documented
+- [ ] Global impact is minimal/intentional
+
+### 5. Record Results
+
+Append to `{validationReportOutput}`:
+
+```markdown
+## Installation Readiness
+
+**Status:** {PASS/FAIL/WARNINGS}
+
+**Installer:** {present/missing} - {status}
+**Install Variables:** {count} variables
+**Ready to Install:** {yes/no}
+
+**Issues Found:**
+{list any issues}
+```
+
+### 6. Auto-Proceed
+
+"**✓ Installation readiness check complete.**"
+
+Proceeding to final report...
+
+Load `{nextStepFile}`
+
+---
+
+## Success Metrics
+
+✅ Installation readiness assessed
+✅ Installer validated (if present)
+✅ Module type compatibility checked
+✅ Results recorded