@devo-bmad-custom/agent-orchestration 1.0.0

package/src/bmm/workflows/3-solutioning/check-implementation-readiness/steps/step-05-epic-quality-review.md

@@ -0,0 +1,196 @@
+---
+name: 'step-05-epic-quality-review'
+description: 'Validate epics and stories against create-epics-and-stories best practices'
+
+nextStepFile: './step-06-final-assessment.md'
+outputFile: '{planning_artifacts}/implementation-readiness-report-{{date}}.md'
+---
+
+# Step 5: Epic Quality Review
+
+## STEP GOAL:
+
+To validate epics and stories against the best practices defined in create-epics-and-stories workflow, focusing on user value, independence, dependencies, and implementation readiness.
+
+## Step-Specific Rules:
+
+- Apply create-epics-and-stories standards rigorously
+- Don't accept "technical milestones" as epics
+- Challenge every dependency on future work
+- Verify proper story sizing and structure
+
+## EPIC QUALITY REVIEW PROCESS:
+
+### 1. Initialize Best Practices Validation
+
+"Beginning **Epic Quality Review** against create-epics-and-stories standards.
+
+I will rigorously validate:
+
+- Epics deliver user value (not technical milestones)
+- Epic independence (Epic 2 doesn't need Epic 3)
+- Story dependencies (no forward references)
+- Proper story sizing and completeness
+
+Any deviation from best practices will be flagged as a defect."
+
+### 2. Epic Structure Validation
+
+#### A. User Value Focus Check
+
+For each epic:
+
+- **Epic Title:** Is it user-centric (what user can do)?
+- **Epic Goal:** Does it describe user outcome?
+- **Value Proposition:** Can users benefit from this epic alone?
+
+**Red flags (violations):**
+
+- "Setup Database" or "Create Models" - no user value
+- "API Development" - technical milestone
+- "Infrastructure Setup" - not user-facing
+- "Authentication System" - borderline (is it user value?)
+
+#### B. Epic Independence Validation
+
+Test epic independence:
+
+- **Epic 1:** Must stand alone completely
+- **Epic 2:** Can function using only Epic 1 output
+- **Epic 3:** Can function using Epic 1 & 2 outputs
+- **Rule:** Epic N cannot require Epic N+1 to work
+
+**Document failures:**
+
+- "Epic 2 requires Epic 3 features to function"
+- Stories in Epic 2 referencing Epic 3 components
+- Circular dependencies between epics
+
+### 3. Story Quality Assessment
+
+#### A. Story Sizing Validation
+
+Check each story:
+
+- **Clear User Value:** Does the story deliver something meaningful?
+- **Independent:** Can it be completed without future stories?
+
+**Common violations:**
+
+- "Setup all models" - not a USER story
+- "Create login UI (depends on Story 1.3)" - forward dependency
+
+#### B. Acceptance Criteria Review
+
+For each story's ACs:
+
+- **Given/When/Then Format:** Proper BDD structure?
+- **Testable:** Each AC can be verified independently?
+- **Complete:** Covers all scenarios including errors?
+- **Specific:** Clear expected outcomes?
+
+**Issues to find:**
+
+- Vague criteria like "user can login"
+- Missing error conditions
+- Incomplete happy path
+- Non-measurable outcomes
+
+### 4. Dependency Analysis
+
+#### A. Within-Epic Dependencies
+
+Map story dependencies within each epic:
+
+- Story 1.1 must be completable alone
+- Story 1.2 can use Story 1.1 output
+- Story 1.3 can use Story 1.1 & 1.2 outputs
+
+**Critical violations:**
+
+- "This story depends on Story 1.4"
+- "Wait for future story to work"
+- Stories referencing features not yet implemented
+
+#### B. Database/Entity Creation Timing
+
+Validate database creation approach:
+
+- **Wrong:** Epic 1 Story 1 creates all tables upfront
+- **Right:** Each story creates tables it needs
+- **Check:** Are tables created only when first needed?
+
+### 5. Special Implementation Checks
+
+#### A. Starter Template Requirement
+
+Check if Architecture specifies starter template:
+
+- If YES: Epic 1 Story 1 must be "Set up initial project from starter template"
+- Verify story includes cloning, dependencies, initial configuration
+
+#### B. Greenfield vs Brownfield Indicators
+
+Greenfield projects should have:
+
+- Initial project setup story
+- Development environment configuration
+- CI/CD pipeline setup early
+
+Brownfield projects should have:
+
+- Integration points with existing systems
+- Migration or compatibility stories
+
+### 6. Best Practices Compliance Checklist
+
+For each epic, verify:
+
+- [ ] Epic delivers user value
+- [ ] Epic can function independently
+- [ ] Stories appropriately sized
+- [ ] No forward dependencies
+- [ ] Database tables created when needed
+- [ ] Clear acceptance criteria
+- [ ] Traceability to FRs maintained
+
+### 7. Quality Assessment Documentation
+
+Document all findings by severity:
+
+#### 🔴 Critical Violations
+
+- Technical epics with no user value
+- Forward dependencies breaking independence
+- Epic-sized stories that cannot be completed
+
+#### 🟠 Major Issues
+
+- Vague acceptance criteria
+- Stories requiring future stories
+- Database creation violations
+
+#### 🟡 Minor Concerns
+
+- Formatting inconsistencies
+- Minor structure deviations
+- Documentation gaps
+
+### 8. Autonomous Review Execution
+
+This review runs autonomously to maintain standards:
+
+- Apply best practices without compromise
+- Document every violation with specific examples
+- Provide clear remediation guidance
+- Prepare recommendations for each issue
+
+## REVIEW COMPLETION:
+
+After completing epic quality review:
+
+- Update {outputFile} with all quality findings
+- Document specific best practices violations
+- Provide actionable recommendations
+- Load {nextStepFile} for final readiness assessment
+

package/src/bmm/workflows/3-solutioning/check-implementation-readiness/steps/step-06-final-assessment.md

@@ -0,0 +1,129 @@
+---
+name: 'step-06-final-assessment'
+description: 'Compile final assessment and polish the readiness report'
+
+outputFile: '{planning_artifacts}/implementation-readiness-report-{{date}}.md'
+---
+
+# Step 6: Final Assessment
+
+## STEP GOAL:
+
+To provide a comprehensive summary of all findings and give the report a final polish, ensuring clear recommendations and overall readiness status.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 📖 You are at the final step - complete the assessment
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are delivering the FINAL ASSESSMENT
+- ✅ Your findings are objective and backed by evidence
+- ✅ Provide clear, actionable recommendations
+- ✅ Success is measured by value of findings
+
+### Step-Specific Rules:
+
+- 🎯 Compile and summarize all findings
+- 🚫 Don't soften the message - be direct
+- 💬 Provide specific examples for problems
+- 🚪 Add final section to the report
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Review all findings from previous steps
+- 💾 Add summary and recommendations
+- 📖 Determine overall readiness status
+- 🚫 Complete and present final report
+
+## FINAL ASSESSMENT PROCESS:
+
+### 1. Initialize Final Assessment
+
+"Completing **Final Assessment**.
+
+I will now:
+
+1. Review all findings from previous steps
+2. Provide a comprehensive summary
+3. Add specific recommendations
+4. Determine overall readiness status"
+
+### 2. Review Previous Findings
+
+Check the {outputFile} for sections added by previous steps:
+
+- File and FR Validation findings
+- UX Alignment issues
+- Epic Quality violations
+
+### 3. Add Final Assessment Section
+
+Append to {outputFile}:
+
+```markdown
+## Summary and Recommendations
+
+### Overall Readiness Status
+
+[READY/NEEDS WORK/NOT READY]
+
+### Critical Issues Requiring Immediate Action
+
+[List most critical issues that must be addressed]
+
+### Recommended Next Steps
+
+1. [Specific action item 1]
+2. [Specific action item 2]
+3. [Specific action item 3]
+
+### Final Note
+
+This assessment identified [X] issues across [Y] categories. Address the critical issues before proceeding to implementation. These findings can be used to improve the artifacts or you may choose to proceed as-is.
+```
+
+### 4. Complete the Report
+
+- Ensure all findings are clearly documented
+- Verify recommendations are actionable
+- Add date and assessor information
+- Save the final report
+
+### 5. Present Completion
+
+Display:
+"**Implementation Readiness Assessment Complete**
+
+Report generated: {outputFile}
+
+The assessment found [number] issues requiring attention. Review the detailed report for specific findings and recommendations."
+
+## WORKFLOW COMPLETE
+
+The implementation readiness workflow is now complete. The report contains all findings and recommendations for the user to consider.
+
+Implementation Readiness complete. Read fully and follow: `{project-root}/_bmad/core/tasks/help.md`
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- All findings compiled and summarized
+- Clear recommendations provided
+- Readiness status determined
+- Final report saved
+
+### ❌ SYSTEM FAILURE:
+
+- Not reviewing previous findings
+- Incomplete summary
+- No clear recommendations

package/src/bmm/workflows/3-solutioning/check-implementation-readiness/templates/readiness-report-template.md

@@ -0,0 +1,4 @@
+# Implementation Readiness Assessment Report
+
+**Date:** {{date}}
+**Project:** {{project_name}}

package/src/bmm/workflows/3-solutioning/check-implementation-readiness/workflow.md

@@ -0,0 +1,54 @@
+---
+name: check-implementation-readiness
+description: 'Validate PRD, UX, Architecture and Epics specs are complete. Use when the user says "check implementation readiness".'
+---
+
+# Implementation Readiness
+
+**Goal:** Validate that PRD, Architecture, Epics and Stories are complete and aligned before Phase 4 implementation starts, with a focus on ensuring epics and stories are logical and have accounted for all requirements and planning.
+
+**Your Role:** You are an expert Product Manager and Scrum Master, renowned and respected in the field of requirements traceability and spotting gaps in planning. Your success is measured in spotting the failures others have made in planning or preparation of epics and stories to produce the users product vision.
+
+## WORKFLOW ARCHITECTURE
+
+### Core Principles
+
+- **Micro-file Design**: Each step of the overall goal is a self contained instruction file that you will adhere too 1 file as directed at a time
+- **Just-In-Time Loading**: Only 1 current step file will be loaded and followed to completion - never load future step files until told to do so
+- **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed
+- **State Tracking**: Document progress in output file frontmatter using `stepsCompleted` array when a workflow produces a document
+- **Append-Only Building**: Build documents by appending content as directed to the output file
+
+### Step Processing Rules
+
+1. **READ COMPLETELY**: Always read the entire step file before taking any action
+2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate
+3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection
+4. **CHECK CONTINUATION**: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue)
+5. **SAVE STATE**: Update `stepsCompleted` in frontmatter before loading next step
+6. **LOAD NEXT**: When directed, read fully and follow the next step file
+
+### Critical Rules (NO EXCEPTIONS)
+
+- 🛑 **NEVER** load multiple step files simultaneously
+- 📖 **ALWAYS** read entire step file before execution
+- 🚫 **NEVER** skip steps or optimize the sequence
+- 💾 **ALWAYS** update frontmatter of output files when writing the final output for a specific step
+- 🎯 **ALWAYS** follow the exact instructions in the step file
+- ⏸️ **ALWAYS** halt at menus and wait for user input
+- 📋 **NEVER** create mental todo lists from future steps
+
+---
+
+## INITIALIZATION SEQUENCE
+
+### 1. Module Configuration Loading
+
+Load and read full config from {project-root}/_bmad/bmm/config.yaml and resolve:
+
+- `project_name`, `output_folder`, `planning_artifacts`, `user_name`, `communication_language`, `document_output_language`
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### 2. First Step EXECUTION
+
+Read fully and follow: `./steps/step-01-document-discovery.md` to begin the workflow.

package/src/bmm/workflows/3-solutioning/create-architecture/architecture-decision-template.md

@@ -0,0 +1,12 @@
+---
+stepsCompleted: []
+inputDocuments: []
+workflowType: 'architecture'
+project_name: '{{project_name}}'
+user_name: '{{user_name}}'
+date: '{{date}}'
+---
+
+# Architecture Decision Document
+
+_This document builds collaboratively through step-by-step discovery. Sections are appended as we work through each architectural decision together._

package/src/bmm/workflows/3-solutioning/create-architecture/data/domain-complexity.csv

@@ -0,0 +1,13 @@
+domain,signals,complexity_level,suggested_workflow,web_searches
+e_commerce,"shopping,cart,checkout,payment,products,store",medium,standard,"ecommerce architecture patterns, payment processing, inventory management"
+fintech,"banking,payment,trading,finance,money,investment",high,enhanced,"financial security, PCI compliance, trading algorithms, fraud detection"
+healthcare,"medical,diagnostic,clinical,patient,hospital,health",high,enhanced,"HIPAA compliance, medical data security, FDA regulations, health tech"
+social,"social network,community,users,friends,posts,sharing",high,advanced,"social graph algorithms, feed ranking, notification systems, privacy"
+education,"learning,course,student,teacher,training,academic",medium,standard,"LMS architecture, progress tracking, assessment systems, video streaming"
+productivity,"productivity,workflow,tasks,management,business,tools",medium,standard,"collaboration patterns, real-time editing, notification systems, integration"
+media,"content,media,video,audio,streaming,broadcast",high,advanced,"CDN architecture, video encoding, streaming protocols, content delivery"
+iot,"IoT,sensors,devices,embedded,smart,connected",high,advanced,"device communication, real-time data processing, edge computing, security"
+government,"government,civic,public,admin,policy,regulation",high,enhanced,"accessibility standards, security clearance, data privacy, audit trails"
+process_control,"industrial automation,process control,PLC,SCADA,DCS,HMI,operational technology,control system,cyberphysical,MES,instrumentation,I&C,P&ID",high,advanced,"industrial process control architecture, SCADA system design, OT cybersecurity architecture, real-time control systems"
+building_automation,"building automation,BAS,BMS,HVAC,smart building,fire alarm,fire protection,fire suppression,life safety,elevator,DDC,access control,sequence of operations,commissioning",high,advanced,"building automation architecture, BACnet integration patterns, smart building design, building management system security"
+gaming,"game,gaming,multiplayer,real-time,interactive,entertainment",high,advanced,"real-time multiplayer, game engine architecture, matchmaking, leaderboards"

package/src/bmm/workflows/3-solutioning/create-architecture/data/project-types.csv

@@ -0,0 +1,7 @@
+project_type,detection_signals,description,typical_starters
+web_app,"website,web application,browser,frontend,UI,interface",Web-based applications running in browsers,Next.js, Vite, Remix
+mobile_app,"mobile,iOS,Android,app,smartphone,tablet",Native mobile applications,React Native, Expo, Flutter
+api_backend,"API,REST,GraphQL,backend,service,microservice",Backend services and APIs,NestJS, Express, Fastify
+full_stack,"full-stack,complete,web+mobile,frontend+backend",Applications with both frontend and backend,T3 App, RedwoodJS, Blitz
+cli_tool,"CLI,command line,terminal,console,tool",Command-line interface tools,oclif, Commander, Caporal
+desktop_app,"desktop,Electron,Tauri,native app,macOS,Windows",Desktop applications,Electron, Tauri, Flutter Desktop

package/src/bmm/workflows/3-solutioning/create-architecture/steps/step-01-init.md

@@ -0,0 +1,89 @@
+## Step 0: Load writing-skills
+
+Invoke `writing-skills` now. Do not proceed to Step 1 until writing-skills is loaded.
+
+---
+
+# Step 1: Architecture Workflow Initialization
+
+**Goal:** Detect continuation state, discover input documents, and set up the architecture document for collaborative decision making.
+
+**Rules:** Read this entire file before acting. Focus only on initialization — do not make architectural decisions here. Show analysis before taking action.
+
+- AUTONOMY OVERRIDE: If you have enough context to answer any discovery questions yourself, DO NOT ask the user. Make expert assumptions, generate the content, display it, and immediately proceed to {nextStepFile} without halting.
+---
+
+## INITIALIZATION SEQUENCE
+
+### 1. Check for Existing Workflow
+
+Look for `{planning_artifacts}/*architecture*.md`. If found with `stepsCompleted` in frontmatter, **immediately load and follow** `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-01b-continue.md` — do not proceed with fresh initialization.
+
+### 2. Fresh Workflow Setup
+
+If no document exists or no `stepsCompleted` in frontmatter:
+
+**A. Input Document Discovery**
+
+Search for documents in: `{planning_artifacts}/**`, `{output_folder}/**`, `{product_knowledge}/**`, `docs/**`
+
+A sharded document is a folder with `index.md` — if `*foo*.md` not found, also check `*foo*/index.md`.
+
+Discover:
+- Product Brief (`*brief*.md`)
+- PRD (`*prd*.md`)
+- UX Design (`*ux-design*.md`)
+- Research Documents (`*research*.md`)
+- Project Documentation (in `{product_knowledge}` or `docs/`)
+- Project Context (`**/project-context.md`)
+
+**Confirm what you found with the user and ask if they want to provide anything else. Wait for confirmation before loading.**
+
+**Loading rules:**
+- Load ALL confirmed files completely (no offset/limit)
+- For sharded folders, load ALL files (use index.md for structure)
+- Track all loaded files in frontmatter `inputDocuments` array
+- Bias toward project context rules throughout the workflow
+
+**B. Validate Required Inputs**
+
+- No PRD found: "Architecture requires a PRD. Please run the PRD workflow first or provide the PRD path." Do NOT proceed without PRD.
+- UX Spec if present: noted as providing UI/UX architectural requirements.
+
+**C. Create Initial Document**
+
+Copy `{installed_path}/architecture-decision-template.md` to `{planning_artifacts}/architecture.md`.
+
+**D. Report to User**
+
+"Welcome {user_name}! I've set up your Architecture workspace for {project_name}.
+
+**Documents Found:**
+- PRD: {count or "None found - REQUIRED"}
+- UX Design: {count or "None found"}
+- Research: {count or "None found"}
+- Project docs: {count or "None found"}
+- Project context: {rule count}
+
+**Files loaded:** {list of specific file names}
+
+Ready to begin architectural decision making. Any other documents to include?
+
+[AR] Adversarial Review [PL] Party Mode Loop [AL] Adversarial Review Loop [C] Continue to project context analysis"
+
+**Menu handling:**
+- **AR:** Execute `{project-root}/_bmad/core/tasks/review-adversarial-general.xml` — display findings, then redisplay menu
+- **C:** After setup is confirmed, load `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-02-context.md`
+
+DO NOT halt after generating the content. Automatically append the content and proceed to {nextStepFile} unless the user explicitly interrupts.
+
+---
+
+## SUCCESS METRICS
+
+- Existing workflow correctly detected and handed to step-01b
+- Fresh workflow initialized with template and frontmatter
+- Input documents discovered, confirmed, and loaded
+- All loaded files tracked in frontmatter `inputDocuments`
+- PRD requirement validated
+- User confirmed document setup before proceeding

package/src/bmm/workflows/3-solutioning/create-architecture/steps/step-01b-continue.md

@@ -0,0 +1,82 @@
+# Step 1b: Workflow Continuation Handler
+
+**Goal:** Handle workflow continuation by analyzing existing work and guiding the user to resume at the appropriate step.
+
+**Rules:** Read this entire file before acting. Maintain all existing document content — do not overwrite. Get user confirmation before navigating to any step.
+
+- AUTONOMY OVERRIDE: If you have enough context to answer any discovery questions yourself, DO NOT ask the user. Make expert assumptions, generate the content, display it, and immediately proceed to {nextStepFile} without halting.
+---
+
+## CONTINUATION SEQUENCE
+
+### 1. Analyze Current Document State
+
+Read the existing architecture document completely.
+
+**Frontmatter analysis:** `stepsCompleted`, `inputDocuments`, `lastStep`, project/user context.
+
+**Content analysis:** Which sections exist, what decisions have been made, what appears incomplete or has TODOs/placeholders.
+
+### 2. Present Continuation Summary
+
+"Welcome back {user_name}! I found your Architecture work for {project_name}.
+
+**Current Progress:**
+- Steps completed: {stepsCompleted list}
+- Last step: Step {lastStep}
+- Input documents: {inputDocuments count} files
+
+**Document Sections Found:**
+{list all H2/H3 sections}
+
+{if incomplete sections exist}
+**Incomplete Areas:** {areas with placeholders or TODOs}
+{/if}
+
+**What would you like to do?**
+[R] Resume from where we left off
+[AR] Adversarial Review [PL] Party Mode Loop [AL] Adversarial Review Loop [C] Continue to next logical step
+[O] Overview of all remaining steps
+[X] Start over (will overwrite existing work)"
+
+### 3. Handle User Choice
+
+**R (Resume):** Identify next step from `stepsCompleted`. If `stepsCompleted: [1, 2, 3]`, load step-04. Load the appropriate step file.
+
+**AR:** Execute `{project-root}/_bmad/core/tasks/review-adversarial-general.xml` — display findings, then redisplay menu.
+
+**C (Continue to next logical step):** Analyze content completeness for the current step. If complete, advance to next; if incomplete, suggest staying. Load the appropriate step file.
+
+**O (Overview):** Describe all remaining steps briefly, let user choose which to work on.
+
+**X (Start over):** Confirm — "This will delete all existing architectural decisions. Are you sure? (y/n)". If yes: delete document and load step-01-init. If no: return to this menu.
+
+### 4. Navigate to Selected Step
+
+- Update frontmatter `lastStep` before loading
+- Load the selected step file
+
+**Valid step files:**
+- `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-02-context.md`
+- `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-03-starter.md`
+- `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-04-decisions.md`
+- `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-05-patterns.md`
+- `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-06-structure.md`
+- `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-07-validation.md`
+- `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-08-complete.md`
+
+### 5. Special Cases
+
+- **`stepsCompleted` empty but document has content:** Ask user if they want to set the appropriate step status based on what's there.
+- **Document appears corrupted:** "Would you like me to try to recover what's here, or start fresh?"
+- **Document appears complete but not marked done:** "The architecture looks complete! Should I mark this workflow as finished, or is there more to work on?"
+
+---
+
+## SUCCESS METRICS
+
+- Existing document state properly analyzed
+- User presented with clear continuation options
+- User choice handled appropriately
+- Workflow state preserved and updated
+- Navigation to appropriate step handled smoothly