@devo-bmad-custom/agent-orchestration 1.0.0

package/src/bmb/workflows/workflow/steps-v/step-10-report-complete.md

@@ -0,0 +1,154 @@
+---
+name: 'step-10-report-complete'
+description: 'Finalize validation report - check for plan file, summarize all findings, present to user'
+
+targetWorkflowPath: '{workflow_folder_path}'
+validationReportFile: '{workflow_folder_path}/validation-report-{datetime}.md'
+workflowPlanFile: '{workflow_folder_path}/workflow-plan.md'
+planValidationStep: './step-11-plan-validation.md'
+---
+
+# Validation Step 10: Report Complete
+
+## STEP GOAL:
+
+To check if a plan file exists (and run plan validation if it does), then summarize all validation findings and present to the user.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ⚙️ If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context
+
+### Step-Specific Rules:
+
+- 🎯 This is the final validation step - present findings
+- 🚫 DO NOT modify the workflow without user request
+- 💬 Present summary and ask what changes are needed
+- 🚪 This ends validation - user decides next steps
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Load the complete validation report
+- 💾 Summarize ALL findings
+- 📖 Update report status to COMPLETE
+- 🚫 DO NOT proceed without user review
+
+## CONTEXT BOUNDARIES:
+
+- All 10 previous validation steps have completed
+- Report contains findings from all checks
+- User needs to see summary and decide on changes
+- This step DOES NOT auto-proceed
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip or shortcut.
+
+### 1. Check for Plan File
+
+Before finalizing the report, check if a plan file exists:
+
+**Check if {workflowPlanFile} exists:**
+- **IF YES:** Run plan validation first
+  - Load, read entire file, then execute {planValidationStep}
+  - The plan validation will append its findings to the report
+  - Then return to this step to finalize the report
+- **IF NO:** Proceed to finalize the report (no plan to validate)
+
+### 2. Load Complete Validation Report
+
+After plan validation (if applicable), load {validationReportFile} and read ALL findings from every validation step.
+
+### 3. Create Summary Section
+
+At the end of {validationReportFile}, replace "## Summary *Pending...*" with a comprehensive summary that includes:
+
+- Validation completion date
+- Overall status assessment (based on all validation steps)
+- List of all validation steps completed with their individual results
+- Summary of critical issues that must be fixed (or note if none found)
+- Summary of warnings that should be addressed (or note if none found)
+- Key strengths identified during validation
+- Overall assessment of workflow quality
+- Recommendation on readiness (ready to use / needs tweaks / needs revision / major rework needed)
+- Suggested next steps for the user
+
+Present this information in a clear, readable format - the exact structure is flexible as long as it covers all these points.
+
+### 4. Update Report Status
+
+Update the frontmatter of {validationReportFile} to set validationStatus to COMPLETE and add the completionDate. Keep existing fields like validationDate, workflowName, and workflowPath unchanged.
+
+### 5. Present Summary to User
+
+Present a clear summary to the user that includes:
+
+- Confirmation that validation is complete
+- Overall status of the workflow
+- Quick results overview showing each validation step and its result
+- Count of critical issues and warnings (or note if none found)
+- Recommendation on workflow readiness
+- Path to the full validation report
+- Options for next steps (review detailed findings, make changes, explain results, or other actions)
+
+Present this information in a natural, conversational way - the exact format doesn't matter as long as all this information is clearly communicated.
+
+### 6. Present MENU OPTIONS
+
+Display: **Validation Complete! Select an Option:** [R] Review Detailed Findings [F] Fix Issues [X] Exit Validation
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- User chooses their next action
+
+#### Menu Handling Logic:
+
+- IF R: Walk through the validation report section by section, explaining findings, then redisplay menu
+- IF F: "What issues would you like to fix?" → Discuss specific changes needed → User can make edits manually OR you can help edit files
+- IF X: "Validation complete. Your workflow is at: {targetWorkflowPath}. You can make changes and re-run validation anytime."
+- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#5-present-menu-options)
+
+### 7. If User Wants to Fix Issues
+
+Explain the available options for fixing issues:
+
+- Manual edits: User edits files directly, then re-runs validation
+- Guided edits: User specifies what to fix, help create specific edits for user approval
+- Edit workflow: If the workflow has steps-e/, use the edit workflow to make systematic changes
+
+The exact format doesn't matter - just ensure the user understands their options for addressing issues.
+
+### 8. Update Plan with Validation Status
+
+If a plan file exists at {workflowPlanFile}, update its frontmatter to include the validation status (COMPLETE), the current validation date, and a reference to the validation report file.
+
+## CRITICAL STEP COMPLETION NOTE
+
+This is the final validation step. User reviews findings and decides whether to make changes. Validation workflow ends here.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- All validation findings summarized
+- Complete report presented to user
+- Summary section added to report
+- Report status updated to COMPLETE
+- User can review findings and decide on changes
+- Plan updated with validation status
+
+### ❌ SYSTEM FAILURE:
+
+- Not summarizing all findings
+- Not presenting complete report to user
+- Not updating report status
+- Not giving user clear options for next steps
+
+**Master Rule:** Validation is complete. User reviews findings and decides what changes to make. Provide clear summary and options.

package/src/bmb/workflows/workflow/steps-v/step-11-plan-validation.md

@@ -0,0 +1,237 @@
+---
+name: 'step-11-plan-validation'
+description: 'Validate plan quality - ensure all user intent and requirements are implemented'
+
+targetWorkflowPath: '{workflow_folder_path}'
+validationReportFile: '{workflow_folder_path}/validation-report-{datetime}.md'
+workflowPlanFile: '{workflow_folder_path}/workflow-plan.md'
+---
+
+# Validation Step 11: Plan Quality Validation
+
+## STEP GOAL:
+
+To validate that a workflow plan (if it exists) has been fully implemented - all user intent captured, all requirements met with high quality.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 DO NOT BE LAZY - LOAD AND REVIEW EVERY FILE
+- 📖 CRITICAL: Read the complete step file before taking any action
+- ✅ This validation step only runs if a plan file exists
+- ⚙️ If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
+
+### Step-Specific Rules:
+
+- 🎯 Validate plan requirements using subprocess optimization - separate subprocess per requirement area for deep analysis
+- 🚫 DO NOT skip checking any requirement from the plan - DO NOT BE LAZY
+- 💬 Subprocess must either update validation report directly OR return structured findings to parent for aggregation
+- 🚪 This ensures the build actually delivered what was planned
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Load plan and extract all requirements/intent using subprocess optimization when available - separate subprocess per requirement area for deep analysis
+- 💾 Subprocesses validate implementation against plan requirements and return findings for aggregation
+- 📖 Document gaps and quality issues
+- 🚫 Only run this step if workflowPlanFile exists
+
+## CONTEXT BOUNDARIES:
+
+- This step runs AFTER the workflow is built
+- Compares what was planned vs what was implemented
+- Checks for: missing features, quality gaps, unmet user intent
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Only run this step if {workflowPlanFile} exists. If it doesn't exist, skip to final summary.
+
+### 1. Check if Plan Exists
+
+First, check if {workflowPlanFile} exists:
+
+**IF plan file does NOT exist:**
+- Skip this validation step
+- Proceed to summary with note: "No plan file found - workflow may have been built without BMAD create-workflow process"
+
+**IF plan file exists:**
+- Load the complete plan file
+- Proceed with validation
+
+### 2. Extract Plan Requirements
+
+**DO NOT BE LAZY - Extract EVERY requirement from the plan:**
+
+**SUBPROCESS EXECUTION PATTERN:**
+
+Launch a subprocess that:
+1. Loads {workflowPlanFile}
+2. Extracts all requirements from each section (Discovery, Classification, Requirements, Design, Tools)
+3. Returns structured requirements list to parent
+
+**SUBPROCESS RETURNS:**
+Structured requirements list organized by section (discovery, classification, requirements, design, tools) with all extracted items and a count of total requirements.
+
+**If subprocess unavailable:** Load {workflowPlanFile} in main context and extract requirements (larger context but still functional - demonstrates graceful fallback).
+
+---
+
+### 3. Validate Each Requirement Against Built Workflow
+
+**DO NOT BE LAZY - For EACH requirement area, launch a subprocess that:**
+
+1. Loads relevant workflow files (workflow.md, step files, etc.)
+2. Validates that specific requirement area is implemented correctly
+3. Assesses quality of implementation
+4. **EITHER** updates validation report directly with findings
+5. **OR** returns structured validation results to parent for aggregation
+
+**PATTERN 2: Separate subprocess per requirement area for deep analysis**
+
+Each subprocess gets full context to deeply understand that requirement area and validate implementation quality:
+
+---
+
+**SUBPROCESS 1: Discovery Validation**
+
+**Subprocess analyzes:**
+- ✅ Built workflow addresses the original problem?
+- ✅ Vision from discovery is reflected in final workflow?
+
+**Subprocess returns:**
+Discovery validation results indicating whether the original problem and vision from the plan are addressed in the built workflow, with quality assessment, status (✅/❌), and any gaps identified.
+
+---
+
+**SUBPROCESS 2: Classification Validation**
+
+**Subprocess analyzes:**
+- ✅ Document output matches plan (yes/no)?
+- ✅ Module affiliation correct?
+- ✅ Continuable support as specified?
+- ✅ Tri-modal structure as specified?
+
+**Subprocess returns:**
+Classification validation results for each classification attribute (document output, module, continuable, tri-modal) comparing what was specified vs what was implemented, with overall quality assessment, status (✅/❌), and any gaps.
+
+---
+
+**SUBPROCESS 3: Requirements Validation**
+
+**Subprocess analyzes:**
+- ✅ Flow structure matches plan?
+- ✅ User interaction style as specified?
+- ✅ All required inputs configured?
+- ✅ Output format matches specification?
+- ✅ Success criteria achievable?
+
+**Subprocess returns:**
+Requirements validation results for flow structure, interaction style, inputs, outputs, and success criteria comparing what was specified vs what was implemented, with overall quality assessment, status (✅/❌), and any gaps.
+
+---
+
+**SUBPROCESS 4: Design Validation**
+
+**Subprocess analyzes:**
+- ✅ All steps from design present in workflow?
+- ✅ Step purposes match design?
+- ✅ Flow follows design diagram?
+- ✅ Interaction patterns as specified?
+
+**Subprocess returns:**
+Design validation results for each step from the plan checking if it exists in the workflow and if the purpose matches, along with whether the flow follows the design diagram and interaction patterns match, with overall quality assessment, status (✅/❌), and any gaps.
+
+---
+
+**SUBPROCESS 5: Tools Validation**
+
+**Subprocess analyzes:**
+- ✅ Specified tools configured in workflow?
+- ✅ Data files created as specified?
+
+**Subprocess returns:**
+Tools validation results checking which specified tools are configured and which data files were created, with overall quality assessment, status (✅/❌), and any gaps.
+
+---
+
+**If subprocess unavailable:** Validate each requirement area sequentially in main context (larger context but still functional - demonstrates graceful fallback).
+
+---
+
+### 4. Aggregate Findings and Update Report
+
+After ALL requirement area subprocesses complete, aggregate findings into validation report.
+
+Document the following information:
+
+**Plan Information:**
+- Plan file location
+- Whether a plan was found
+- Total number of requirements extracted from the plan
+
+**Implementation Coverage:**
+For each requirement area from the plan (Discovery/Vision, Classification attributes, Requirements specifications, Design elements, Tools):
+- What was specified in the plan
+- Whether it was implemented in the workflow
+- Quality assessment (High/Medium/Low)
+- Implementation status
+
+**Implementation Gaps:**
+List any requirements from the plan that are NOT present in the built workflow
+
+**Quality Issues:**
+List any requirements that are implemented but with quality concerns
+
+**Plan-Reality Alignment:**
+Describe where the built workflow doesn't match what was planned
+
+**Overall Assessment:**
+- Plan implementation score (percentage)
+- Overall status (Fully Implemented/Partially Implemented/Poorly Implemented/Missing Critical Items)
+
+**Quality Assessment Framework:**
+For each implemented requirement, assess quality:
+- **High Quality**: Implementation follows best practices, would facilitate effectively
+- **Medium Quality**: Functional but has issues or gaps
+- **Low Quality**: Minimal/barely working, would not facilitate well
+
+Examples:
+- Plan specifies "Highly collaborative, intent-based facilitation" and implementation has A/P menus with intent-based language = High Quality
+- Plan specifies "Continuable workflow with session resume" and implementation has step-01b-continue.md tracking stepsCompleted = High Quality
+
+### 5. Append to Report
+
+Append the aggregated findings to {validationReportFile} after the "## Cohesive Review" section.
+
+### 6. Save and Complete
+
+Save the validation report. This is the final validation step.
+
+**Display:**
+"**Plan Quality validation complete.** Validation report finalized."
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Plan file loaded completely (in subprocess or main context)
+- Every requirement extracted and validated using subprocess optimization when available
+- Each requirement area analyzed in separate subprocess (or main context with graceful fallback)
+- Implementation gaps documented with structured findings
+- Quality assessed for each requirement
+- Findings aggregated and appended to report
+- Context saved via subprocess pattern (return only findings, not full file contents)
+
+### ❌ SYSTEM FAILURE:
+
+- Not loading complete plan
+- Skipping requirement checks
+- Not validating each requirement area deeply
+- Not using subprocess optimization when available
+- Not documenting implementation gaps
+- Not assessing quality
+- Loading full file contents into parent instead of returning only findings
+
+**Master Rule:** Validation is systematic and thorough. DO NOT BE LAZY. Check EVERY requirement from the plan. Use subprocess optimization (Pattern 2: per-requirement deep analysis) when available. Document all gaps. Return only findings to parent, not full file contents.

package/src/bmb/workflows/workflow/templates/minimal-output-template.md

@@ -0,0 +1,11 @@
+---
+stepsCompleted: []
+lastStep: ''
+date: ''
+user_name: ''
+project_name: ''
+---
+
+# {{document_title}}
+
+[Content will be progressively appended by workflow steps]

package/src/bmb/workflows/workflow/templates/step-01-init-continuable-template.md

@@ -0,0 +1,241 @@
+# BMAD Continuable Step 01 Init Template
+
+This template provides the standard structure for step-01-init files that support workflow continuation. It includes logic to detect existing workflows and route to step-01b-continue.md for resumption.
+
+Use this template when creating workflows that generate output documents and might take multiple sessions to complete.
+
+<!-- TEMPLATE START -->
+
+---
+
+name: 'step-01-init'
+description: 'Initialize the [workflow-type] workflow by detecting continuation state and creating output document'
+
+<!-- Path Definitions -->
+
+workflow\*path: `{project-root}/_bmad/[module-path]/workflows/[workflow-name]`
+
+# File References (all use {variable} format in file)
+
+thisStepFile: `./step-01-init.md`
+nextStepFile: `./step-02-[step-name].md`
+workflowFile: `{workflow_path}/workflow.md`
+outputFile: `{output_folder}/[output-file-name]-{project_name}.md`
+continueFile: `./step-01b-continue.md`
+templateFile: `{workflow_path}/templates/[main-template].md`
+
+# Template References
+
+# This step doesn't use content templates, only the main template
+
+---
+
+# Step 1: Workflow Initialization
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+
+### Role Reinforcement:
+
+- ✅ You are a [specific role, e.g., "business analyst" or "technical architect"]
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring [your expertise], user brings [their expertise], and together we produce something better than we could on our own
+- ✅ Maintain collaborative [adjective] tone throughout
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on initialization and setup
+- 🚫 FORBIDDEN to look ahead to future steps
+- 💬 Handle initialization professionally
+- 🚪 DETECT existing workflow state and handle continuation properly
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show analysis before taking any action
+- 💾 Initialize document and update frontmatter
+- 📖 Set up frontmatter `stepsCompleted: [1]` before loading next step
+- 🚫 FORBIDDEN to load next step until setup is complete
+
+## CONTEXT BOUNDARIES:
+
+- Variables from workflow.md are available in memory
+- Previous context = what's in output document + frontmatter
+- Don't assume knowledge from other steps
+- Input document discovery happens in this step
+
+## STEP GOAL:
+
+To initialize the [workflow-type] workflow by detecting continuation state, creating the output document, and preparing for the first collaborative session.
+
+## INITIALIZATION SEQUENCE:
+
+### 1. Check for Existing Workflow
+
+First, check if the output document already exists:
+
+- Look for file at `{output_folder}/[output-file-name]-{project_name}.md`
+- If exists, read the complete file including frontmatter
+- If not exists, this is a fresh workflow
+
+### 2. Handle Continuation (If Document Exists)
+
+If the document exists and has frontmatter with `stepsCompleted`:
+
+- **STOP here** and load `./step-01b-continue.md` immediately
+- Do not proceed with any initialization tasks
+- Let step-01b handle the continuation logic
+
+### 3. Handle Completed Workflow
+
+If the document exists AND all steps are marked complete in `stepsCompleted`:
+
+- Ask user: "I found an existing [workflow-output] from [date]. Would you like to:
+  1. Create a new [workflow-output]
+  2. Update/modify the existing [workflow-output]"
+- If option 1: Create new document with timestamp suffix
+- If option 2: Load step-01b-continue.md
+
+### 4. Fresh Workflow Setup (If No Document)
+
+If no document exists or no `stepsCompleted` in frontmatter:
+
+#### A. Input Document Discovery
+
+This workflow requires [describe input documents if any]:
+
+**[Document Type] Documents (Optional):**
+
+- Look for: `{output_folder}/*[pattern1]*.md`
+- Look for: `{output_folder}/*[pattern2]*.md`
+- If found, load completely and add to `inputDocuments` frontmatter
+
+#### B. Create Initial Document
+
+Copy the template from `{templateFile}` to `{output_folder}/[output-file-name]-{project_name}.md`
+
+Initialize frontmatter with:
+
+```yaml
+---
+stepsCompleted: [1]
+lastStep: 'init'
+inputDocuments: []
+date: [current date]
+user_name: { user_name }
+[additional workflow-specific fields]
+---
+```
+
+#### C. Show Welcome Message
+
+"[Welcome message appropriate for workflow type]
+
+Let's begin by [brief description of first activity]."
+
+## ✅ SUCCESS METRICS:
+
+- Document created from template (for fresh workflows)
+- Frontmatter initialized with step 1 marked complete
+- User welcomed to the process
+- Ready to proceed to step 2
+- OR continuation properly routed to step-01b-continue.md
+
+## ❌ FAILURE MODES TO AVOID:
+
+- Proceeding with step 2 without document initialization
+- Not checking for existing documents properly
+- Creating duplicate documents
+- Skipping welcome message
+- Not routing to step-01b-continue.md when needed
+
+### 5. Present MENU OPTIONS
+
+Display: **Proceeding to [next step description]...**
+
+#### EXECUTION RULES:
+
+- This is an initialization step with no user choices
+- Proceed directly to next step after setup
+- Use menu handling logic section below
+
+#### Menu Handling Logic:
+
+- After setup completion, immediately load, read entire file, then execute `{nextStepFile}` to begin [next step description]
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Document created from template (for fresh workflows)
+- update frontmatter `stepsCompleted` to add 1 at the end of the array before loading next step
+- Frontmatter initialized with `stepsCompleted: [1]`
+- User welcomed to the process
+- Ready to proceed to step 2
+- OR existing workflow properly routed to step-01b-continue.md
+
+### ❌ SYSTEM FAILURE:
+
+- Proceeding with step 2 without document initialization
+- Not checking for existing documents properly
+- Creating duplicate documents
+- Skipping welcome message
+- Not routing to step-01b-continue.md when appropriate
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN initialization setup is complete and document is created (OR continuation is properly routed), will you then immediately load, read entire file, then execute `{nextStepFile}` to begin [next step description].
+
+<!-- TEMPLATE END -->
+
+## Customization Guidelines
+
+When adapting this template for your specific workflow:
+
+### 1. Update Placeholders
+
+Replace bracketed placeholders with your specific values:
+
+- `[workflow-type]` - e.g., "nutrition planning", "project requirements"
+- `[module-path]` - e.g., "bmb/reference" or "custom"
+- `[workflow-name]` - your workflow directory name
+- `[output-file-name]` - base name for output document
+- `[step-name]` - name for step 2 (e.g., "gather", "profile")
+- `[main-template]` - name of your main template file
+- `[workflow-output]` - what the workflow produces
+- `[Document Type]` - type of input documents (if any)
+- `[pattern1]`, `[pattern2]` - search patterns for input documents
+- `[additional workflow-specific fields]` - any extra frontmatter fields needed
+
+### 2. Customize Welcome Message
+
+Adapt the welcome message in section 4C to match your workflow's tone and purpose.
+
+### 3. Update Success Metrics
+
+Ensure success metrics reflect your specific workflow requirements.
+
+### 4. Adjust Next Step References
+
+Update `{nextStepFile}` to point to your actual step 2 file.
+
+## Implementation Notes
+
+1. **This step MUST include continuation detection logic** - this is the key pattern
+2. **Always include `continueFile` reference** in frontmatter
+3. **Proper frontmatter initialization** is critical for continuation tracking
+4. **Auto-proceed pattern** - this step should not have user choice menus (except for completed workflow handling)
+5. **Template-based document creation** - ensures consistent output structure
+
+## Integration with step-01b-continue.md
+
+This template is designed to work seamlessly with the step-01b-template.md continuation step. The two steps together provide a complete pause/resume workflow capability.