@zeyue0329/xiaoma-cli 1.0.48 → 6.0.0-alpha.13

package/src/modules/xmc/workflows/3-solutioning/implementation-readiness/checklist.md

@@ -0,0 +1,169 @@
+# Implementation Readiness Validation Checklist
+
+## Document Completeness
+
+### Core Planning Documents
+
+- [ ] PRD exists and is complete
+- [ ] PRD contains measurable success criteria
+- [ ] PRD defines clear scope boundaries and exclusions
+- [ ] Architecture document exists (architecture\*.md)
+- [ ] Technical Specification exists with implementation details
+- [ ] Epic and story breakdown document exists
+- [ ] All documents are dated and versioned
+
+### Document Quality
+
+- [ ] No placeholder sections remain in any document
+- [ ] All documents use consistent terminology
+- [ ] Technical decisions include rationale and trade-offs
+- [ ] Assumptions and risks are explicitly documented
+- [ ] Dependencies are clearly identified and documented
+
+## Alignment Verification
+
+### PRD to Architecture Alignment
+
+- [ ] Every functional requirement in PRD has architectural support documented
+- [ ] All non-functional requirements from PRD are addressed in architecture
+- [ ] Architecture doesn't introduce features beyond PRD scope
+- [ ] Performance requirements from PRD match architecture capabilities
+- [ ] Security requirements from PRD are fully addressed in architecture
+- [ ] If architecture.md: Implementation patterns are defined for consistency
+- [ ] If architecture.md: All technology choices have verified versions
+- [ ] If UX spec exists: Architecture supports UX requirements
+
+### PRD to Stories Coverage
+
+- [ ] Every PRD requirement maps to at least one story
+- [ ] All user journeys in PRD have complete story coverage
+- [ ] Story acceptance criteria align with PRD success criteria
+- [ ] Priority levels in stories match PRD feature priorities
+- [ ] No stories exist without PRD requirement traceability
+
+### Architecture to Stories Implementation
+
+- [ ] All architectural components have implementation stories
+- [ ] Infrastructure setup stories exist for each architectural layer
+- [ ] Integration points defined in architecture have corresponding stories
+- [ ] Data migration/setup stories exist if required by architecture
+- [ ] Security implementation stories cover all architecture security decisions
+
+## Story and Sequencing Quality
+
+### Story Completeness
+
+- [ ] All stories have clear acceptance criteria
+- [ ] Technical tasks are defined within relevant stories
+- [ ] Stories include error handling and edge cases
+- [ ] Each story has clear definition of done
+- [ ] Stories are appropriately sized (no epic-level stories remaining)
+
+### Sequencing and Dependencies
+
+- [ ] Stories are sequenced in logical implementation order
+- [ ] Dependencies between stories are explicitly documented
+- [ ] No circular dependencies exist
+- [ ] Prerequisite technical tasks precede dependent stories
+- [ ] Foundation/infrastructure stories come before feature stories
+
+### Greenfield Project Specifics
+
+- [ ] Initial project setup and configuration stories exist
+- [ ] If using architecture.md: First story is starter template initialization command
+- [ ] Development environment setup is documented
+- [ ] CI/CD pipeline stories are included early in sequence
+- [ ] Database/storage initialization stories are properly placed
+- [ ] Authentication/authorization stories precede protected features
+
+## Risk and Gap Assessment
+
+### Critical Gaps
+
+- [ ] No core PRD requirements lack story coverage
+- [ ] No architectural decisions lack implementation stories
+- [ ] All integration points have implementation plans
+- [ ] Error handling strategy is defined and implemented
+- [ ] Security concerns are all addressed
+
+### Technical Risks
+
+- [ ] No conflicting technical approaches between stories
+- [ ] Technology choices are consistent across all documents
+- [ ] Performance requirements are achievable with chosen architecture
+- [ ] Scalability concerns are addressed if applicable
+- [ ] Third-party dependencies are identified with fallback plans
+
+## UX and Special Concerns (if applicable)
+
+### UX Coverage
+
+- [ ] UX requirements are documented in PRD
+- [ ] UX implementation tasks exist in relevant stories
+- [ ] Accessibility requirements have story coverage
+- [ ] Responsive design requirements are addressed
+- [ ] User flow continuity is maintained across stories
+
+### Special Considerations
+
+- [ ] Compliance requirements are fully addressed
+- [ ] Internationalization needs are covered if required
+- [ ] Performance benchmarks are defined and measurable
+- [ ] Monitoring and observability stories exist
+- [ ] Documentation stories are included where needed
+
+## Overall Readiness
+
+### Ready to Proceed Criteria
+
+- [ ] All critical issues have been resolved
+- [ ] High priority concerns have mitigation plans
+- [ ] Story sequencing supports iterative delivery
+- [ ] Team has necessary skills for implementation
+- [ ] No blocking dependencies remain unresolved
+
+### Quality Indicators
+
+- [ ] Documents demonstrate thorough analysis
+- [ ] Clear traceability exists across all artifacts
+- [ ] Consistent level of detail throughout documents
+- [ ] Risks are identified with mitigation strategies
+- [ ] Success criteria are measurable and achievable
+
+## Assessment Completion
+
+### Report Quality
+
+- [ ] All findings are supported by specific examples
+- [ ] Recommendations are actionable and specific
+- [ ] Severity levels are appropriately assigned
+- [ ] Positive findings are highlighted
+- [ ] Next steps are clearly defined
+
+### Process Validation
+
+- [ ] All expected documents were reviewed
+- [ ] Cross-references were systematically checked
+- [ ] Project level considerations were applied correctly
+- [ ] Workflow status was checked and considered
+- [ ] Output folder was thoroughly searched for artifacts
+
+---
+
+## Issue Log
+
+### Critical Issues Found
+
+<!-- checklist of critical issues or N/A -->
+
+### High Priority Issues Found
+
+<!-- checklist of high priority issues or N/A -->
+
+### Medium Priority Issues Found
+
+<!-- checklist of medium priority issues or N/A -->
+
+---
+
+_Use this checklist to ensure comprehensive validation of implementation readiness_

package/src/modules/xmc/workflows/3-solutioning/implementation-readiness/instructions.md

@@ -0,0 +1,332 @@
+# Implementation Readiness - Workflow Instructions
+
+<critical>The workflow execution engine is governed by: {project-root}/{xiaoma_folder}/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {project-root}/{xiaoma_folder}/xmc/workflows/3-solutioning/implementation-readiness/workflow.yaml</critical>
+<critical>Communicate all findings and analysis in {communication_language} throughout the assessment</critical>
+<critical>Input documents specified in workflow.yaml input_file_patterns - workflow engine handles fuzzy matching, whole vs sharded document discovery automatically</critical>
+<critical>⚠️ ABSOLUTELY NO TIME ESTIMATES - NEVER mention hours, days, weeks, months, or ANY time-based predictions. AI has fundamentally changed development speed - what once took teams weeks/months can now be done by one person in hours. DO NOT give ANY time estimates whatsoever.</critical>
+<critical>⚠️ CHECKPOINT PROTOCOL: After EVERY <template-output> tag, you MUST follow workflow.xml substep 2c: SAVE content to file immediately → SHOW checkpoint separator (━━━━━━━━━━━━━━━━━━━━━━━) → DISPLAY generated content → PRESENT options [a]Advanced Elicitation/[c]Continue/[p]Party-Mode/[y]YOLO → WAIT for user response. Never batch saves or skip checkpoints.</critical>
+
+<workflow>
+
+<step n="0" goal="Validate workflow readiness" tag="workflow-status">
+<action>Check if {workflow_status_file} exists</action>
+
+<check if="status file not found">
+  <output>No workflow status file found. Implementation Readiness check can run standalone or as part of XMC workflow path.</output>
+  <output>**Recommended:** Run `workflow-init` first for project context tracking and workflow sequencing.</output>
+  <ask>Continue in standalone mode or exit to run workflow-init? (continue/exit)</ask>
+  <check if="continue">
+    <action>Set standalone_mode = true</action>
+  </check>
+  <check if="exit">
+    <action>Exit workflow</action>
+  </check>
+</check>
+
+<check if="status file found">
+  <action>Load the FULL file:  {workflow_status_file}</action>
+  <action>Parse workflow_status section</action>
+  <action>Check status of "implementation-readiness" workflow</action>
+  <action>Get {selected_track} (quick-flow, xiaoma-cli, or enterprise-xiaoma-cli)</action>
+  <action>Find first non-completed workflow (next expected workflow)</action>
+
+<action>Based on the selected_track, understand what artifacts should exist: - quick-flow: Tech spec and simple stories in an epic only (no PRD, minimal solutioning) - xiaoma-cli and enterprise-xiaoma-cli: PRD, UX design, epics/stories, architecture</action>
+
+  <check if="implementation-readiness status is file path (already completed)">
+    <output>⚠️ Implementation readiness check already completed: {{implementation-readiness status}}</output>
+    <ask>Re-running will create a new validation report. Continue? (y/n)</ask>
+    <check if="n">
+      <output>Exiting. Use workflow-status to see your next step.</output>
+      <action>Exit workflow</action>
+    </check>
+  </check>
+
+  <check if="implementation-readiness is not the next expected workflow">
+    <output>⚠️ Next expected workflow: {{next_workflow}}. Implementation readiness check is out of sequence.</output>
+    <ask>Continue with readiness check anyway? (y/n)</ask>
+    <check if="n">
+      <output>Exiting. Run {{next_workflow}} instead.</output>
+      <action>Exit workflow</action>
+    </check>
+  </check>
+
+<action>Set standalone_mode = false</action>
+</check>
+
+<template-output>project_context</template-output>
+</step>
+
+<step n="0.5" goal="Discover and load input documents">
+<invoke-protocol name="discover_inputs" />
+<note>After discovery, these content variables are available: {prd_content}, {epics_content}, {architecture_content}, {ux_design_content}, {tech_spec_content}, {document_project_content}</note>
+</step>
+
+<step n="1" goal="Inventory loaded project artifacts">
+<action>Review the content loaded by Step 0.5 and create an inventory</action>
+
+<action>Inventory of available documents:
+
+- PRD: {prd_content} (loaded if available)
+- Architecture: {architecture_content} (loaded if available)
+- Epics: {epics_content} (loaded if available)
+- UX Design: {ux_design_content} (loaded if available)
+- Tech Spec: {tech_spec_content} (loaded if available, Quick Flow track)
+- Brownfield docs: {document_project_content} (loaded via INDEX_GUIDED if available)
+  </action>
+
+<action>For each loaded document, extract:
+
+- Document type and purpose
+- Brief description of what it contains
+- Flag any expected documents that are missing as potential issues
+  </action>
+
+<template-output>document_inventory</template-output>
+</step>
+
+<step n="2" goal="Deep analysis of core planning documents">
+<action>Thoroughly analyze each loaded document to extract:
+  - Core requirements and success criteria
+  - Architectural decisions and constraints
+  - Technical implementation approaches
+  - User stories and acceptance criteria
+  - Dependencies and sequencing requirements
+  - Any assumptions or risks documented
+</action>
+
+<action>For PRD analysis, focus on:
+
+- User requirements and use cases
+- Functional and non-functional requirements
+- Success metrics and acceptance criteria
+- Scope boundaries and explicitly excluded items
+- Priority levels for different features
+  </action>
+
+<action>For Architecture/Tech Spec analysis, focus on:
+
+- System design decisions and rationale
+- Technology stack and framework choices
+- Integration points and APIs
+- Data models and storage decisions
+- Security and performance considerations
+- Any architectural constraints that might affect story implementation
+  </action>
+
+<action>For Epic/Story analysis, focus on:
+
+- Coverage of PRD requirements
+- Story sequencing and dependencies
+- Acceptance criteria completeness
+- Technical tasks within stories
+- Estimated complexity and effort indicators
+  </action>
+
+<template-output>document_analysis</template-output>
+</step>
+
+<step n="3" goal="Cross-reference validation and alignment check">
+
+<action>PRD ↔ Architecture Alignment:
+
+- Verify every PRD requirement has corresponding architectural support
+- Check that architectural decisions don't contradict PRD constraints
+- Identify any architectural additions beyond PRD scope (potential gold-plating)
+- Ensure non-functional requirements from PRD are addressed in architecture document
+- If using new architecture workflow: verify implementation patterns are defined
+  </action>
+
+<action>PRD ↔ Stories Coverage:
+
+- Map each PRD requirement to implementing stories
+- Identify any PRD requirements without story coverage
+- Find stories that don't trace back to PRD requirements
+- Validate that story acceptance criteria align with PRD success criteria
+  </action>
+
+<action>Architecture ↔ Stories Implementation Check:
+
+- Verify architectural decisions are reflected in relevant stories
+- Check that story technical tasks align with architectural approach
+- Identify any stories that might violate architectural constraints
+- Ensure infrastructure and setup stories exist for architectural components
+  </action>
+
+<template-output>alignment_validation</template-output>
+</step>
+
+<step n="4" goal="Gap and risk analysis">
+<action>Identify and categorize all gaps, risks, and potential issues discovered during validation</action>
+
+<action>Check for Critical Gaps:
+
+- Missing stories for core requirements
+- Unaddressed architectural concerns
+- Absent infrastructure or setup stories for greenfield projects
+- Missing error handling or edge case coverage
+- Security or compliance requirements not addressed
+  </action>
+
+<action>Identify Sequencing Issues:
+
+- Dependencies not properly ordered
+- Stories that assume components not yet built
+- Parallel work that should be sequential
+- Missing prerequisite technical tasks
+  </action>
+
+<action>Detect Potential Contradictions:
+
+- Conflicts between PRD and architecture approaches
+- Stories with conflicting technical approaches
+- Acceptance criteria that contradict requirements
+- Resource or technology conflicts
+  </action>
+
+<action>Find Gold-Plating and Scope Creep:
+
+- Features in architecture not required by PRD
+- Stories implementing beyond requirements
+- Technical complexity beyond project needs
+- Over-engineering indicators
+  </action>
+
+<action>Check Testability Review (if test-design exists in Phase 3):
+
+**Note:** test-design is recommended for XiaoMa Method, required for Enterprise Method
+
+- Check if {output_folder}/test-design-system.md exists
+- If exists: Review testability assessment (Controllability, Observability, Reliability)
+- If testability concerns documented: Flag for gate decision
+- If missing AND track is Enterprise: Flag as CRITICAL gap
+- If missing AND track is Method: Note as recommendation (not blocker)
+  </action>
+
+<template-output>gap_risk_analysis</template-output>
+</step>
+
+<step n="5" goal="UX and special concerns validation" optional="true">
+  <check if="UX artifacts exist or UX workflow in active path">
+    <action>Review UX artifacts and validate integration:
+      - Check that UX requirements are reflected in PRD
+      - Verify stories include UX implementation tasks
+      - Ensure architecture supports UX requirements (performance, responsiveness)
+      - Identify any UX concerns not addressed in stories
+    </action>
+
+    <action>Validate accessibility and usability coverage:
+      - Check for accessibility requirement coverage in stories
+      - Verify responsive design considerations if applicable
+      - Ensure user flow completeness across stories
+    </action>
+
+  </check>
+
+<template-output>ux_validation</template-output>
+</step>
+
+<step n="6" goal="Generate comprehensive readiness assessment">
+<action>Compile all findings into a structured readiness report with:
+- Executive summary of readiness status
+- Project context and validation scope
+- Document inventory and coverage assessment
+- Detailed findings organized by severity (Critical, High, Medium, Low)
+- Specific recommendations for each issue
+- Overall readiness recommendation (Ready, Ready with Conditions, Not Ready)
+</action>
+
+<action>Provide actionable next steps:
+
+- List any critical issues that must be resolved
+- Suggest specific document updates needed
+- Recommend additional stories or tasks required
+- Propose sequencing adjustments if needed
+  </action>
+
+<action>Include positive findings:
+
+- Highlight well-aligned areas
+- Note particularly thorough documentation
+- Recognize good architectural decisions
+- Commend comprehensive story coverage where found
+  </action>
+
+<template-output>readiness_assessment</template-output>
+</step>
+
+<step n="7" goal="Update status and complete" tag="workflow-status">
+<check if="standalone_mode != true">
+  <action>Load the FULL file: {workflow_status_file}</action>
+  <action>Find workflow_status key "implementation-readiness"</action>
+  <critical>ONLY write the file path as the status value - no other text, notes, or metadata</critical>
+  <action>Update workflow_status["implementation-readiness"] = "{output_folder}/implementation-readiness-report-{{date}}.md"</action>
+  <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
+
+<action>Find first non-completed workflow in workflow_status (next workflow to do)</action>
+<action>Determine next agent from path file based on next workflow</action>
+</check>
+
+<action>Determine overall readiness status from the readiness_assessment (Ready, Ready with Conditions, or Not Ready)</action>
+
+<output>**✅ Implementation Readiness Check Complete!**
+
+**Assessment Report:**
+
+- Readiness assessment saved to: {output_folder}/implementation-readiness-report-{{date}}.md
+
+{{#if standalone_mode != true}}
+**Status Updated:**
+
+- Progress tracking updated: implementation-readiness marked complete
+- Next workflow: {{next_workflow}}
+  {{else}}
+  **Note:** Running in standalone mode (no progress tracking)
+  {{/if}}
+
+**Next Steps:**
+
+{{#if standalone_mode != true}}
+
+- **Next workflow:** {{next_workflow}} ({{next_agent}} agent)
+- Review the assessment report and address any critical issues before proceeding
+
+Check status anytime with: `workflow-status`
+{{else}}
+Since no workflow is in progress:
+
+- Refer to the XMC workflow guide if unsure what to do next
+- Or run `workflow-init` to create a workflow path and get guided next steps
+  {{/if}}
+  </output>
+
+<check if="overall readiness status is Ready OR Ready with Conditions">
+  <output>**🚀 Ready for Implementation!**
+
+Your project artifacts are aligned and complete. You can now proceed to Phase 4: Implementation.
+</output>
+
+<ask>Would you like to run the **sprint-planning** workflow to initialize your sprint tracking and prepare for development? (yes/no)</ask>
+
+  <check if="yes">
+    <action>Inform user that sprint-planning workflow will be invoked</action>
+    <invoke-workflow path="{project-root}/{xiaoma_folder}/xmc/workflows/4-implementation/sprint-planning/workflow.yaml" />
+  </check>
+  <check if="no">
+    <output>You can run sprint-planning later when ready: `sprint-planning`</output>
+  </check>
+</check>
+
+<check if="overall readiness status is Not Ready">
+  <output>**⚠️ Not Ready for Implementation**
+
+Critical issues must be resolved before proceeding. Review the assessment report and address the identified gaps.
+
+Once issues are resolved, re-run implementation-readiness to validate again.
+</output>
+</check>
+
+<template-output>status_update_result</template-output>
+</step>
+
+</workflow>

package/src/modules/xmc/workflows/3-solutioning/implementation-readiness/template.md

@@ -0,0 +1,146 @@
+# Implementation Readiness Assessment Report
+
+**Date:** {{date}}
+**Project:** {{project_name}}
+**Assessed By:** {{user_name}}
+**Assessment Type:** Phase 3 to Phase 4 Transition Validation
+
+---
+
+## Executive Summary
+
+{{readiness_assessment}}
+
+---
+
+## Project Context
+
+{{project_context}}
+
+---
+
+## Document Inventory
+
+### Documents Reviewed
+
+{{document_inventory}}
+
+### Document Analysis Summary
+
+{{document_analysis}}
+
+---
+
+## Alignment Validation Results
+
+### Cross-Reference Analysis
+
+{{alignment_validation}}
+
+---
+
+## Gap and Risk Analysis
+
+### Critical Findings
+
+{{gap_risk_analysis}}
+
+---
+
+## UX and Special Concerns
+
+{{ux_validation}}
+
+---
+
+## Detailed Findings
+
+### 🔴 Critical Issues
+
+_Must be resolved before proceeding to implementation_
+
+{{critical_issues}}
+
+### 🟠 High Priority Concerns
+
+_Should be addressed to reduce implementation risk_
+
+{{high_priority_concerns}}
+
+### 🟡 Medium Priority Observations
+
+_Consider addressing for smoother implementation_
+
+{{medium_priority_observations}}
+
+### 🟢 Low Priority Notes
+
+_Minor items for consideration_
+
+{{low_priority_notes}}
+
+---
+
+## Positive Findings
+
+### ✅ Well-Executed Areas
+
+{{positive_findings}}
+
+---
+
+## Recommendations
+
+### Immediate Actions Required
+
+{{immediate_actions}}
+
+### Suggested Improvements
+
+{{suggested_improvements}}
+
+### Sequencing Adjustments
+
+{{sequencing_adjustments}}
+
+---
+
+## Readiness Decision
+
+### Overall Assessment: {{overall_readiness_status}}
+
+{{readiness_rationale}}
+
+### Conditions for Proceeding (if applicable)
+
+{{conditions_for_proceeding}}
+
+---
+
+## Next Steps
+
+{{recommended_next_steps}}
+
+### Workflow Status Update
+
+{{status_update_result}}
+
+---
+
+## Appendices
+
+### A. Validation Criteria Applied
+
+{{validation_criteria_used}}
+
+### B. Traceability Matrix
+
+{{traceability_matrix}}
+
+### C. Risk Mitigation Strategies
+
+{{risk_mitigation_strategies}}
+
+---
+
+_This readiness assessment was generated using the XiaoMa Method Implementation Readiness workflow (v6-alpha)_