@zeyue0329/xiaoma-cli 1.0.49 → 6.0.0-alpha.14

package/src/modules/xmc/workflows/4-implementation/correct-course/instructions.md

@@ -0,0 +1,206 @@
+# Correct Course - Sprint Change Management 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/4-implementation/correct-course/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>
+
+<critical>DOCUMENT OUTPUT: Updated epics, stories, or PRD sections. Clear, actionable changes. User skill level ({user_skill_level}) affects conversation style ONLY, not document updates.</critical>
+
+<workflow>
+
+<step n="1" goal="Initialize Change Navigation">
+  <action>Confirm change trigger and gather user description of the issue</action>
+  <action>Ask: "What specific issue or change has been identified that requires navigation?"</action>
+  <action>Verify access to required project documents:</action>
+    - PRD (Product Requirements Document)
+    - Current Epics and Stories
+    - Architecture documentation
+    - UI/UX specifications
+  <action>Ask user for mode preference:</action>
+    - **Incremental** (recommended): Refine each edit collaboratively
+    - **Batch**: Present all changes at once for review
+  <action>Store mode selection for use throughout workflow</action>
+
+<action if="change trigger is unclear">HALT: "Cannot navigate change without clear understanding of the triggering issue. Please provide specific details about what needs to change and why."</action>
+
+<action if="core documents are unavailable">HALT: "Need access to project documents (PRD, Epics, Architecture, UI/UX) to assess change impact. Please ensure these documents are accessible."</action>
+</step>
+
+<step n="0.5" goal="Discover and load project 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="2" goal="Execute Change Analysis Checklist">
+  <action>Load and execute the systematic analysis from: {checklist}</action>
+  <action>Work through each checklist section interactively with the user</action>
+  <action>Record status for each checklist item:</action>
+    - [x] Done - Item completed successfully
+    - [N/A] Skip - Item not applicable to this change
+    - [!] Action-needed - Item requires attention or follow-up
+  <action>Maintain running notes of findings and impacts discovered</action>
+  <action>Present checklist progress after each major section</action>
+
+<action if="checklist cannot be completed">Identify blocking issues and work with user to resolve before continuing</action>
+</step>
+
+<step n="3" goal="Draft Specific Change Proposals">
+<action>Based on checklist findings, create explicit edit proposals for each identified artifact</action>
+
+<action>For Story changes:</action>
+
+- Show old → new text format
+- Include story ID and section being modified
+- Provide rationale for each change
+- Example format:
+
+  ```
+  Story: [STORY-123] User Authentication
+  Section: Acceptance Criteria
+
+  OLD:
+  - User can log in with email/password
+
+  NEW:
+  - User can log in with email/password
+  - User can enable 2FA via authenticator app
+
+  Rationale: Security requirement identified during implementation
+  ```
+
+<action>For PRD modifications:</action>
+
+- Specify exact sections to update
+- Show current content and proposed changes
+- Explain impact on MVP scope and requirements
+
+<action>For Architecture changes:</action>
+
+- Identify affected components, patterns, or technology choices
+- Describe diagram updates needed
+- Note any ripple effects on other components
+
+<action>For UI/UX specification updates:</action>
+
+- Reference specific screens or components
+- Show wireframe or flow changes needed
+- Connect changes to user experience impact
+
+<check if="mode is Incremental">
+  <action>Present each edit proposal individually</action>
+  <ask>Review and refine this change? Options: Approve [a], Edit [e], Skip [s]</ask>
+  <action>Iterate on each proposal based on user feedback</action>
+</check>
+
+<action if="mode is Batch">Collect all edit proposals and present together at end of step</action>
+
+</step>
+
+<step n="4" goal="Generate Sprint Change Proposal">
+<action>Compile comprehensive Sprint Change Proposal document with following sections:</action>
+
+<action>Section 1: Issue Summary</action>
+
+- Clear problem statement describing what triggered the change
+- Context about when/how the issue was discovered
+- Evidence or examples demonstrating the issue
+
+<action>Section 2: Impact Analysis</action>
+
+- Epic Impact: Which epics are affected and how
+- Story Impact: Current and future stories requiring changes
+- Artifact Conflicts: PRD, Architecture, UI/UX documents needing updates
+- Technical Impact: Code, infrastructure, or deployment implications
+
+<action>Section 3: Recommended Approach</action>
+
+- Present chosen path forward from checklist evaluation:
+  - Direct Adjustment: Modify/add stories within existing plan
+  - Potential Rollback: Revert completed work to simplify resolution
+  - MVP Review: Reduce scope or modify goals
+- Provide clear rationale for recommendation
+- Include effort estimate, risk assessment, and timeline impact
+
+<action>Section 4: Detailed Change Proposals</action>
+
+- Include all refined edit proposals from Step 3
+- Group by artifact type (Stories, PRD, Architecture, UI/UX)
+- Ensure each change includes before/after and justification
+
+<action>Section 5: Implementation Handoff</action>
+
+- Categorize change scope:
+  - Minor: Direct implementation by dev team
+  - Moderate: Backlog reorganization needed (PO/SM)
+  - Major: Fundamental replan required (PM/Architect)
+- Specify handoff recipients and their responsibilities
+- Define success criteria for implementation
+
+<action>Present complete Sprint Change Proposal to user</action>
+<action>Write Sprint Change Proposal document to {default_output_file}</action>
+<ask>Review complete proposal. Continue [c] or Edit [e]?</ask>
+</step>
+
+<step n="5" goal="Finalize and Route for Implementation">
+<action>Get explicit user approval for complete proposal</action>
+<ask>Do you approve this Sprint Change Proposal for implementation? (yes/no/revise)</ask>
+
+<check if="no or revise">
+  <action>Gather specific feedback on what needs adjustment</action>
+  <action>Return to appropriate step to address concerns</action>
+  <goto step="3">If changes needed to edit proposals</goto>
+  <goto step="4">If changes needed to overall proposal structure</goto>
+
+</check>
+
+<check if="yes the proposal is approved by the user">
+  <action>Finalize Sprint Change Proposal document</action>
+  <action>Determine change scope classification:</action>
+
+- **Minor**: Can be implemented directly by development team
+- **Moderate**: Requires backlog reorganization and PO/SM coordination
+- **Major**: Needs fundamental replan with PM/Architect involvement
+
+<action>Provide appropriate handoff based on scope:</action>
+
+</check>
+
+<check if="Minor scope">
+  <action>Route to: Development team for direct implementation</action>
+  <action>Deliverables: Finalized edit proposals and implementation tasks</action>
+</check>
+
+<check if="Moderate scope">
+  <action>Route to: Product Owner / Scrum Master agents</action>
+  <action>Deliverables: Sprint Change Proposal + backlog reorganization plan</action>
+</check>
+
+<check if="Major scope">
+  <action>Route to: Product Manager / Solution Architect</action>
+  <action>Deliverables: Complete Sprint Change Proposal + escalation notice</action>
+
+<action>Confirm handoff completion and next steps with user</action>
+<action>Document handoff in workflow execution log</action>
+</check>
+
+</step>
+
+<step n="6" goal="Workflow Completion">
+<action>Summarize workflow execution:</action>
+  - Issue addressed: {{change_trigger}}
+  - Change scope: {{scope_classification}}
+  - Artifacts modified: {{list_of_artifacts}}
+  - Routed to: {{handoff_recipients}}
+
+<action>Confirm all deliverables produced:</action>
+
+- Sprint Change Proposal document
+- Specific edit proposals with before/after
+- Implementation handoff plan
+
+<action>Report workflow completion to user with personalized message: "✅ Correct Course workflow complete, {user_name}!"</action>
+<action>Remind user of success criteria and next steps for implementation team</action>
+</step>
+
+</workflow>

package/src/modules/xmc/workflows/4-implementation/correct-course/workflow.yaml

@@ -0,0 +1,58 @@
+# Correct Course - Sprint Change Management Workflow
+name: "correct-course"
+description: "Navigate significant changes during sprint execution by analyzing impact, proposing solutions, and routing for implementation"
+author: "XiaoMa Method"
+
+config_source: "{project-root}/{xiaoma_folder}/xmc/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"
+date: system-generated
+sprint_artifacts: "{config_source}:sprint_artifacts"
+sprint_status: "{sprint_artifacts}/sprint-status.yaml || {output_folder}/sprint-status.yaml"
+
+# Smart input file references - handles both whole docs and sharded docs
+# Priority: Whole document first, then sharded version
+# Strategy: Load project context for impact analysis
+input_file_patterns:
+  prd:
+    description: "Product requirements for impact analysis"
+    whole: "{output_folder}/*prd*.md"
+    sharded: "{output_folder}/*prd*/*.md"
+    load_strategy: "FULL_LOAD"
+  epics:
+    description: "All epics to analyze change impact"
+    whole: "{output_folder}/*epic*.md"
+    sharded: "{output_folder}/*epic*/*.md"
+    load_strategy: "FULL_LOAD"
+  architecture:
+    description: "System architecture and decisions"
+    whole: "{output_folder}/*architecture*.md"
+    sharded: "{output_folder}/*architecture*/*.md"
+    load_strategy: "FULL_LOAD"
+  ux_design:
+    description: "UX design specification (if UI impacts)"
+    whole: "{output_folder}/*ux*.md"
+    sharded: "{output_folder}/*ux*/*.md"
+    load_strategy: "FULL_LOAD"
+  tech_spec:
+    description: "Technical specification"
+    whole: "{output_folder}/tech-spec*.md"
+    load_strategy: "FULL_LOAD"
+  document_project:
+    description: "Brownfield project documentation (optional)"
+    sharded: "{output_folder}/index.md"
+    load_strategy: "INDEX_GUIDED"
+
+installed_path: "{project-root}/{xiaoma_folder}/xmc/workflows/4-implementation/correct-course"
+template: false
+instructions: "{installed_path}/instructions.md"
+validation: "{installed_path}/checklist.md"
+checklist: "{installed_path}/checklist.md"
+default_output_file: "{output_folder}/sprint-change-proposal-{date}.md"
+
+standalone: true
+
+web_bundle: false

package/src/modules/xmc/workflows/4-implementation/create-story/checklist.md

@@ -0,0 +1,358 @@
+# 🎯 Story Context Quality Competition Prompt
+
+## **🔥 CRITICAL MISSION: Outperform and Fix the Original Create-Story LLM**
+
+You are an independent quality validator in a **FRESH CONTEXT**. Your mission is to **thoroughly review** a story file that was generated by the create-story workflow and **systematically identify any mistakes, omissions, or disasters** that the original LLM missed.
+
+**Your purpose is NOT just to validate - it's to FIX and PREVENT LLM developer mistakes, omissions, or disasters!**
+
+### **🚨 CRITICAL MISTAKES TO PREVENT:**
+
+- **Reinventing wheels** - Creating duplicate functionality instead of reusing existing
+- **Wrong libraries** - Using incorrect frameworks, versions, or dependencies
+- **Wrong file locations** - Violating project structure and organization
+- **Breaking regressions** - Implementing changes that break existing functionality
+- **Ignoring UX** - Not following user experience design requirements
+- **Vague implementations** - Creating unclear, ambiguous implementations
+- **Lying about completion** - Implementing incorrectly or incompletely
+- **Not learning from past work** - Ignoring previous story learnings and patterns
+
+### **🚨 EXHAUSTIVE ANALYSIS REQUIRED:**
+
+You must thoroughly analyze **ALL artifacts** to extract critical context - do NOT be lazy or skim! This is the most important quality control function in the entire development process!
+
+### **🔬 UTILIZE SUBPROCESSES AND SUBAGENTS:**
+
+Use research subagents, subprocesses, or parallel processing if available to thoroughly analyze different artifacts **simultaneously and thoroughly**. Leave no stone unturned!
+
+### **🎯 COMPETITIVE EXCELLENCE:**
+
+This is a COMPETITION to create the **ULTIMATE story context** that makes LLM developer mistakes **IMPOSSIBLE**!
+
+## **🚀 HOW TO USE THIS CHECKLIST**
+
+### **When Running from Create-Story Workflow:**
+
+- The `{project_root}/{xiaoma_folder}/core/tasks/validate-workflow.xml` framework will automatically:
+  - Load this checklist file
+  - Load the newly created story file (`{story_file_path}`)
+  - Load workflow variables from `{installed_path}/workflow.yaml`
+  - Execute the validation process
+
+### **When Running in Fresh Context:**
+
+- User should provide the story file path being reviewed
+- Load the story file directly
+- Load the corresponding workflow.yaml for variable context
+- Proceed with systematic analysis
+
+### **Required Inputs:**
+
+- **Story file**: The story file to review and improve
+- **Workflow variables**: From workflow.yaml (story_dir, output_folder, epics_file, etc.)
+- **Source documents**: Epics, architecture, etc. (discovered or provided)
+- **Validation framework**: `validate-workflow.xml` (handles checklist execution)
+
+---
+
+## **🔬 SYSTEMATIC RE-ANALYSIS APPROACH**
+
+You will systematically re-do the entire story creation process, but with a critical eye for what the original LLM might have missed:
+
+### **Step 1: Load and Understand the Target**
+
+1. **Load the workflow configuration**: `{installed_path}/workflow.yaml` for variable inclusion
+2. **Load the story file**: `{story_file_path}` (provided by user or discovered)
+3. **Load validation framework**: `{project_root}/{xiaoma_folder}/core/tasks/validate-workflow.xml`
+4. **Extract metadata**: epic_num, story_num, story_key, story_title from story file
+5. **Resolve all workflow variables**: story_dir, output_folder, epics_file, architecture_file, etc.
+6. **Understand current status**: What story implementation guidance is currently provided?
+
+**Note:** If running in fresh context, user should provide the story file path being reviewed. If running from create-story workflow, the validation framework will automatically discover the checklist and story file.
+
+### **Step 2: Exhaustive Source Document Analysis**
+
+**🔥 CRITICAL: Treat this like YOU are creating the story from scratch to PREVENT DISASTERS!**
+**Discover everything the original LLM missed that could cause developer mistakes, omissions, or disasters!**
+
+#### **2.1 Epics and Stories Analysis**
+
+- Load `{epics_file}` (or sharded equivalents)
+- Extract **COMPLETE Epic {{epic_num}} context**:
+  - Epic objectives and business value
+  - ALL stories in this epic (for cross-story context)
+  - Our specific story's requirements, acceptance criteria
+  - Technical requirements and constraints
+  - Cross-story dependencies and prerequisites
+
+#### **2.2 Architecture Deep-Dive**
+
+- Load `{architecture_file}` (single or sharded)
+- **Systematically scan for ANYTHING relevant to this story:**
+  - Technical stack with versions (languages, frameworks, libraries)
+  - Code structure and organization patterns
+  - API design patterns and contracts
+  - Database schemas and relationships
+  - Security requirements and patterns
+  - Performance requirements and optimization strategies
+  - Testing standards and frameworks
+  - Deployment and environment patterns
+  - Integration patterns and external services
+
+#### **2.3 Previous Story Intelligence (if applicable)**
+
+- If `story_num > 1`, load the previous story file
+- Extract **actionable intelligence**:
+  - Dev notes and learnings
+  - Review feedback and corrections needed
+  - Files created/modified and their patterns
+  - Testing approaches that worked/didn't work
+  - Problems encountered and solutions found
+  - Code patterns and conventions established
+
+#### **2.4 Git History Analysis (if available)**
+
+- Analyze recent commits for patterns:
+  - Files created/modified in previous work
+  - Code patterns and conventions used
+  - Library dependencies added/changed
+  - Architecture decisions implemented
+  - Testing approaches used
+
+#### **2.5 Latest Technical Research**
+
+- Identify any libraries/frameworks mentioned
+- Research latest versions and critical information:
+  - Breaking changes or security updates
+  - Performance improvements or deprecations
+  - Best practices for current versions
+
+### **Step 3: Disaster Prevention Gap Analysis**
+
+**🚨 CRITICAL: Identify every mistake the original LLM missed that could cause DISASTERS!**
+
+#### **3.1 Reinvention Prevention Gaps**
+
+- **Wheel reinvention:** Areas where developer might create duplicate functionality
+- **Code reuse opportunities** not identified that could prevent redundant work
+- **Existing solutions** not mentioned that developer should extend instead of replace
+
+#### **3.2 Technical Specification DISASTERS**
+
+- **Wrong libraries/frameworks:** Missing version requirements that could cause compatibility issues
+- **API contract violations:** Missing endpoint specifications that could break integrations
+- **Database schema conflicts:** Missing requirements that could corrupt data
+- **Security vulnerabilities:** Missing security requirements that could expose the system
+- **Performance disasters:** Missing requirements that could cause system failures
+
+#### **3.3 File Structure DISASTERS**
+
+- **Wrong file locations:** Missing organization requirements that could break build processes
+- **Coding standard violations:** Missing conventions that could create inconsistent codebase
+- **Integration pattern breaks:** Missing data flow requirements that could cause system failures
+- **Deployment failures:** Missing environment requirements that could prevent deployment
+
+#### **3.4 Regression DISASTERS**
+
+- **Breaking changes:** Missing requirements that could break existing functionality
+- **Test failures:** Missing test requirements that could allow bugs to reach production
+- **UX violations:** Missing user experience requirements that could ruin the product
+- **Learning failures:** Missing previous story context that could repeat same mistakes
+
+#### **3.5 Implementation DISASTERS**
+
+- **Vague implementations:** Missing details that could lead to incorrect or incomplete work
+- **Completion lies:** Missing acceptance criteria that could allow fake implementations
+- **Scope creep:** Missing boundaries that could cause unnecessary work
+- **Quality failures:** Missing quality requirements that could deliver broken features
+
+### **Step 4: LLM-Dev-Agent Optimization Analysis**
+
+**CRITICAL STEP: Optimize story context for LLM developer agent consumption**
+
+**Analyze current story for LLM optimization issues:**
+
+- **Verbosity problems:** Excessive detail that wastes tokens without adding value
+- **Ambiguity issues:** Vague instructions that could lead to multiple interpretations
+- **Context overload:** Too much information not directly relevant to implementation
+- **Missing critical signals:** Key requirements buried in verbose text
+- **Poor structure:** Information not organized for efficient LLM processing
+
+**Apply LLM Optimization Principles:**
+
+- **Clarity over verbosity:** Be precise and direct, eliminate fluff
+- **Actionable instructions:** Every sentence should guide implementation
+- **Scannable structure:** Use clear headings, bullet points, and emphasis
+- **Token efficiency:** Pack maximum information into minimum text
+- **Unambiguous language:** Clear requirements with no room for interpretation
+
+### **Step 5: Improvement Recommendations**
+
+**For each gap identified, provide specific, actionable improvements:**
+
+#### **5.1 Critical Misses (Must Fix)**
+
+- Missing essential technical requirements
+- Missing previous story context that could cause errors
+- Missing anti-pattern prevention that could lead to duplicate code
+- Missing security or performance requirements
+
+#### **5.2 Enhancement Opportunities (Should Add)**
+
+- Additional architectural guidance that would help developer
+- More detailed technical specifications
+- Better code reuse opportunities
+- Enhanced testing guidance
+
+#### **5.3 Optimization Suggestions (Nice to Have)**
+
+- Performance optimization hints
+- Additional context for complex scenarios
+- Enhanced debugging or development tips
+
+#### **5.4 LLM Optimization Improvements**
+
+- Token-efficient phrasing of existing content
+- Clearer structure for LLM processing
+- More actionable and direct instructions
+- Reduced verbosity while maintaining completeness
+
+---
+
+## **🎯 COMPETITION SUCCESS METRICS**
+
+**You WIN against the original LLM if you identify:**
+
+### **Category 1: Critical Misses (Blockers)**
+
+- Essential technical requirements the developer needs but aren't provided
+- Previous story learnings that would prevent errors if ignored
+- Anti-pattern prevention that would prevent code duplication
+- Security or performance requirements that must be followed
+
+### **Category 2: Enhancement Opportunities**
+
+- Architecture guidance that would significantly help implementation
+- Technical specifications that would prevent wrong approaches
+- Code reuse opportunities the developer should know about
+- Testing guidance that would improve quality
+
+### **Category 3: Optimization Insights**
+
+- Performance or efficiency improvements
+- Development workflow optimizations
+- Additional context for complex scenarios
+
+---
+
+## **📋 INTERACTIVE IMPROVEMENT PROCESS**
+
+After completing your systematic analysis, present your findings to the user interactively:
+
+### **Step 5: Present Improvement Suggestions**
+
+```
+🎯 **STORY CONTEXT QUALITY REVIEW COMPLETE**
+
+**Story:** {{story_key}} - {{story_title}}
+
+I found {{critical_count}} critical issues, {{enhancement_count}} enhancements, and {{optimization_count}} optimizations.
+
+## **🚨 CRITICAL ISSUES (Must Fix)**
+
+{{list each critical issue with clear, actionable description}}
+
+## **⚡ ENHANCEMENT OPPORTUNITIES (Should Add)**
+
+{{list each enhancement with clear benefit description}}
+
+## **✨ OPTIMIZATIONS (Nice to Have)**
+
+{{list each optimization with benefit description}}
+
+## **🤖 LLM OPTIMIZATION (Token Efficiency & Clarity)**
+
+{{list each LLM optimization that will improve dev agent performance:
+- Reduce verbosity while maintaining completeness
+- Improve structure for better LLM processing
+- Make instructions more actionable and direct
+- Enhance clarity and reduce ambiguity}}
+```
+
+### **Step 6: Interactive User Selection**
+
+After presenting the suggestions, ask the user:
+
+```
+**IMPROVEMENT OPTIONS:**
+
+Which improvements would you like me to apply to the story?
+
+**Select from the numbered list above, or choose:**
+- **all** - Apply all suggested improvements
+- **critical** - Apply only critical issues
+- **select** - I'll choose specific numbers
+- **none** - Keep story as-is
+- **details** - Show me more details about any suggestion
+
+Your choice:
+```
+
+### **Step 7: Apply Selected Improvements**
+
+When user accepts improvements:
+
+- **Load the story file**
+- **Apply accepted changes** (make them look natural, as if they were always there)
+- **DO NOT reference** the review process, original LLM, or that changes were "added" or "enhanced"
+- **Ensure clean, coherent final story** that reads as if it was created perfectly the first time
+
+### **Step 8: Confirmation**
+
+After applying changes:
+
+```
+✅ **STORY IMPROVEMENTS APPLIED**
+
+Updated {{count}} sections in the story file.
+
+The story now includes comprehensive developer guidance to prevent common implementation issues and ensure flawless execution.
+
+**Next Steps:**
+1. Review the updated story
+2. Run `dev-story` for implementation
+```
+
+---
+
+## **💪 COMPETITIVE EXCELLENCE MINDSET**
+
+**Your goal:** Improve the story file with dev agent needed context that makes flawless implementation inevitable while being optimized for LLM developer agent consumption. Remember the dev agent will ONLY have this file to use.
+
+**Success Criteria:** The LLM developer agent that processes your improved story will have:
+
+- ✅ Clear technical requirements they must follow
+- ✅ Previous work context they can build upon
+- ✅ Anti-pattern prevention to avoid common mistakes
+- ✅ Comprehensive guidance for efficient implementation
+- ✅ **Optimized content structure** for maximum clarity and minimum token waste
+- ✅ **Actionable instructions** with no ambiguity or verbosity
+- ✅ **Efficient information density** - maximum guidance in minimum text
+
+**Every improvement should make it IMPOSSIBLE for the developer to:**
+
+- Reinvent existing solutions
+- Use wrong approaches or libraries
+- Create duplicate functionality
+- Miss critical requirements
+- Make implementation errors
+
+**LLM Optimization Should Make it IMPOSSIBLE for the developer agent to:**
+
+- Misinterpret requirements due to ambiguity
+- Waste tokens on verbose, non-actionable content
+- Struggle to find critical information buried in text
+- Get confused by poor structure or organization
+- Miss key implementation signals due to inefficient communication
+
+**Go create the ultimate developer implementation guide! 🚀**