@zeyue0329/xiaoma-cli 1.6.4 → 1.7.0

package/src/xmc/workflows/3-solutioning/xiaoma-create-epics-and-stories/steps/step-02-design-epics.md

@@ -0,0 +1,212 @@
+# Step 2: Design Epic List
+
+## STEP GOAL:
+
+To design and get approval for the epics_list that will organize all requirements into user-value-focused epics.
+
+## 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
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a product strategist and technical specifications writer
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring product strategy and epic design expertise
+- ✅ User brings their product vision and priorities
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on creating the epics_list
+- 🚫 FORBIDDEN to create individual stories in this step
+- 💬 Organize epics around user value, not technical layers
+- 🚪 GET explicit approval for the epics_list
+- 🔗 **CRITICAL: Each epic must be standalone and enable future epics without requiring future epics to function**
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Design epics collaboratively based on extracted requirements
+- 💾 Update {{epics_list}} in {planning_artifacts}/epics.md
+- 📖 Document the FR coverage mapping
+- 🚫 FORBIDDEN to load next step until user approves epics_list
+
+## EPIC DESIGN PROCESS:
+
+### 1. Review Extracted Requirements
+
+Load {planning_artifacts}/epics.md and review:
+
+- **Functional Requirements:** Count and review FRs from Step 1
+- **Non-Functional Requirements:** Review NFRs that need to be addressed
+- **Additional Requirements:** Review technical and UX requirements
+
+### 2. Explain Epic Design Principles
+
+**EPIC DESIGN PRINCIPLES:**
+
+1. **User-Value First**: Each epic must enable users to accomplish something meaningful
+2. **Requirements Grouping**: Group related FRs that deliver cohesive user outcomes
+3. **Incremental Delivery**: Each epic should deliver value independently
+4. **Logical Flow**: Natural progression from user's perspective
+5. **🔗 Dependency-Free Within Epic**: Stories within an epic must NOT depend on future stories
+
+**⚠️ CRITICAL PRINCIPLE:**
+Organize by USER VALUE, not technical layers:
+
+**✅ CORRECT Epic Examples (Standalone & Enable Future Epics):**
+
+- Epic 1: User Authentication & Profiles (users can register, login, manage profiles) - **Standalone: Complete auth system**
+- Epic 2: Content Creation (users can create, edit, publish content) - **Standalone: Uses auth, creates content**
+- Epic 3: Social Interaction (users can follow, comment, like content) - **Standalone: Uses auth + content**
+- Epic 4: Search & Discovery (users can find content and other users) - **Standalone: Uses all previous**
+
+**❌ WRONG Epic Examples (Technical Layers or Dependencies):**
+
+- Epic 1: Database Setup (creates all tables upfront) - **No user value**
+- Epic 2: API Development (builds all endpoints) - **No user value**
+- Epic 3: Frontend Components (creates reusable components) - **No user value**
+- Epic 4: Deployment Pipeline (CI/CD setup) - **No user value**
+
+**🔗 DEPENDENCY RULES:**
+
+- Each epic must deliver COMPLETE functionality for its domain
+- Epic 2 must not require Epic 3 to function
+- Epic 3 can build upon Epic 1 & 2 but must stand alone
+
+### 3. Design Epic Structure Collaboratively
+
+**Step A: Identify User Value Themes**
+
+- Look for natural groupings in the FRs
+- Identify user journeys or workflows
+- Consider user types and their goals
+
+**Step B: Propose Epic Structure**
+For each proposed epic:
+
+1. **Epic Title**: User-centric, value-focused
+2. **User Outcome**: What users can accomplish after this epic
+3. **FR Coverage**: Which FR numbers this epic addresses
+4. **Implementation Notes**: Any technical or UX considerations
+
+**Step C: Create the epics_list**
+
+Format the epics_list as:
+
+```
+## Epic List
+
+### Epic 1: [Epic Title]
+[Epic goal statement - what users can accomplish]
+**FRs covered:** FR1, FR2, FR3, etc.
+
+### Epic 2: [Epic Title]
+[Epic goal statement - what users can accomplish]
+**FRs covered:** FR4, FR5, FR6, etc.
+
+[Continue for all epics]
+```
+
+### 4. Present Epic List for Review
+
+Display the complete epics_list to user with:
+
+- Total number of epics
+- FR coverage per epic
+- User value delivered by each epic
+- Any natural dependencies
+
+### 5. Create Requirements Coverage Map
+
+Create {{requirements_coverage_map}} showing how each FR maps to an epic:
+
+```
+### FR Coverage Map
+
+FR1: Epic 1 - [Brief description]
+FR2: Epic 1 - [Brief description]
+FR3: Epic 2 - [Brief description]
+...
+```
+
+This ensures no FRs are missed.
+
+### 6. Collaborative Refinement
+
+Ask user:
+
+- "Does this epic structure align with your product vision?"
+- "Are all user outcomes properly captured?"
+- "Should we adjust any epic groupings?"
+- "Are there natural dependencies we've missed?"
+
+### 7. Get Final Approval
+
+**CRITICAL:** Must get explicit user approval:
+"Do you approve this epic structure for proceeding to story creation?"
+
+If user wants changes:
+
+- Make the requested adjustments
+- Update the epics_list
+- Re-present for approval
+- Repeat until approval is received
+
+## CONTENT TO UPDATE IN DOCUMENT:
+
+After approval, update {planning_artifacts}/epics.md:
+
+1. Replace {{epics_list}} placeholder with the approved epic list
+2. Replace {{requirements_coverage_map}} with the coverage map
+3. Ensure all FRs are mapped to epics
+
+### 8. Present MENU OPTIONS
+
+Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue"
+
+#### Menu Handling Logic:
+
+- IF A: Invoke the `xiaoma-advanced-elicitation` skill
+- IF P: Invoke the `xiaoma-party-mode` skill
+- IF C: Save approved epics_list to {planning_artifacts}/epics.md, update frontmatter, then read fully and follow: ./step-03-create-stories.md
+- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#8-present-menu-options)
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- After other menu items execution completes, redisplay the menu
+- User can chat or ask questions - always respond when conversation ends, redisplay the menu options
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN C is selected and the approved epics_list is saved to document, will you then read fully and follow: ./step-03-create-stories.md to begin story creation step.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Epics designed around user value
+- All FRs mapped to specific epics
+- epics_list created and formatted correctly
+- Requirements coverage map completed
+- User gives explicit approval for epic structure
+- Document updated with approved epics
+
+### ❌ SYSTEM FAILURE:
+
+- Epics organized by technical layers
+- Missing FRs in coverage map
+- No user approval obtained
+- epics_list not saved to document
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/xmc/workflows/3-solutioning/xiaoma-create-epics-and-stories/steps/step-03-create-stories.md

@@ -0,0 +1,255 @@
+# Step 3: Generate Epics and Stories
+
+## STEP GOAL:
+
+To generate all epics with their stories based on the approved epics_list, following the template structure exactly.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: Process epics sequentially
+- 📋 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 a product strategist and technical specifications writer
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring story creation and acceptance criteria expertise
+- ✅ User brings their implementation priorities and constraints
+
+### Step-Specific Rules:
+
+- 🎯 Generate stories for each epic following the template exactly
+- 🚫 FORBIDDEN to deviate from template structure
+- 💬 Each story must have clear acceptance criteria
+- 🚪 ENSURE each story is completable by a single dev agent
+- 🔗 **CRITICAL: Stories MUST NOT depend on future stories within the same epic**
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Generate stories collaboratively with user input
+- 💾 Append epics and stories to {planning_artifacts}/epics.md following template
+- 📖 Process epics one at a time in sequence
+- 🚫 FORBIDDEN to skip any epic or rush through stories
+
+## STORY GENERATION PROCESS:
+
+### 1. Load Approved Epic Structure
+
+Load {planning_artifacts}/epics.md and review:
+
+- Approved epics_list from Step 2
+- FR coverage map
+- All requirements (FRs, NFRs, additional, **UX Design requirements if present**)
+- Template structure at the end of the document
+
+**UX Design Integration**: If UX Design Requirements (UX-DRs) were extracted in Step 1, ensure they are visible during story creation. UX-DRs must be covered by stories — either within existing epics (e.g., accessibility fixes for a feature epic) or in a dedicated "Design System / UX Polish" epic.
+
+### 2. Explain Story Creation Approach
+
+**STORY CREATION GUIDELINES:**
+
+For each epic, create stories that:
+
+- Follow the exact template structure
+- Are sized for single dev agent completion
+- Have clear user value
+- Include specific acceptance criteria
+- Reference requirements being fulfilled
+
+**🚨 DATABASE/ENTITY CREATION PRINCIPLE:**
+Create tables/entities ONLY when needed by the story:
+
+- ❌ WRONG: Epic 1 Story 1 creates all 50 database tables
+- ✅ RIGHT: Each story creates/alters ONLY the tables it needs
+
+**🔗 STORY DEPENDENCY PRINCIPLE:**
+Stories must be independently completable in sequence:
+
+- ❌ WRONG: Story 1.2 requires Story 1.3 to be completed first
+- ✅ RIGHT: Each story can be completed based only on previous stories
+- ❌ WRONG: "Wait for Story 1.4 to be implemented before this works"
+- ✅ RIGHT: "This story works independently and enables future stories"
+
+**STORY FORMAT (from template):**
+
+```
+### Story {N}.{M}: {story_title}
+
+As a {user_type},
+I want {capability},
+So that {value_benefit}.
+
+**Acceptance Criteria:**
+
+**Given** {precondition}
+**When** {action}
+**Then** {expected_outcome}
+**And** {additional_criteria}
+```
+
+**✅ GOOD STORY EXAMPLES:**
+
+_Epic 1: User Authentication_
+
+- Story 1.1: User Registration with Email
+- Story 1.2: User Login with Password
+- Story 1.3: Password Reset via Email
+
+_Epic 2: Content Creation_
+
+- Story 2.1: Create New Blog Post
+- Story 2.2: Edit Existing Blog Post
+- Story 2.3: Publish Blog Post
+
+**❌ BAD STORY EXAMPLES:**
+
+- Story: "Set up database" (no user value)
+- Story: "Create all models" (too large, no user value)
+- Story: "Build authentication system" (too large)
+- Story: "Login UI (depends on Story 1.3 API endpoint)" (future dependency!)
+- Story: "Edit post (requires Story 1.4 to be implemented first)" (wrong order!)
+
+### 3. Process Epics Sequentially
+
+For each epic in the approved epics_list:
+
+#### A. Epic Overview
+
+Display:
+
+- Epic number and title
+- Epic goal statement
+- FRs covered by this epic
+- Any NFRs or additional requirements relevant
+- Any UX Design Requirements (UX-DRs) relevant to this epic
+
+#### B. Story Breakdown
+
+Work with user to break down the epic into stories:
+
+- Identify distinct user capabilities
+- Ensure logical flow within the epic
+- Size stories appropriately
+
+#### C. Generate Each Story
+
+For each story in the epic:
+
+1. **Story Title**: Clear, action-oriented
+2. **User Story**: Complete the As a/I want/So that format
+3. **Acceptance Criteria**: Write specific, testable criteria
+
+**AC Writing Guidelines:**
+
+- Use Given/When/Then format
+- Each AC should be independently testable
+- Include edge cases and error conditions
+- Reference specific requirements when applicable
+
+#### D. Collaborative Review
+
+After writing each story:
+
+- Present the story to user
+- Ask: "Does this story capture the requirement correctly?"
+- "Is the scope appropriate for a single dev session?"
+- "Are the acceptance criteria complete and testable?"
+
+#### E. Append to Document
+
+When story is approved:
+
+- Append it to {planning_artifacts}/epics.md following template structure
+- Use correct numbering (Epic N, Story M)
+- Maintain proper markdown formatting
+
+### 4. Epic Completion
+
+After all stories for an epic are complete:
+
+- Display epic summary
+- Show count of stories created
+- Verify all FRs for the epic are covered
+- Get user confirmation to proceed to next epic
+
+### 5. Repeat for All Epics
+
+Continue the process for each epic in the approved list, processing them in order (Epic 1, Epic 2, etc.).
+
+### 6. Final Document Completion
+
+After all epics and stories are generated:
+
+- Verify the document follows template structure exactly
+- Ensure all placeholders are replaced
+- Confirm all FRs are covered
+- **Confirm all UX Design Requirements (UX-DRs) are covered by at least one story** (if UX document was an input)
+- Check formatting consistency
+
+## TEMPLATE STRUCTURE COMPLIANCE:
+
+The final {planning_artifacts}/epics.md must follow this structure exactly:
+
+1. **Overview** section with project name
+2. **Requirements Inventory** with all three subsections populated
+3. **FR Coverage Map** showing requirement to epic mapping
+4. **Epic List** with approved epic structure
+5. **Epic sections** for each epic (N = 1, 2, 3...)
+   - Epic title and goal
+   - All stories for that epic (M = 1, 2, 3...)
+     - Story title and user story
+     - Acceptance Criteria using Given/When/Then format
+
+### 7. Present FINAL MENU OPTIONS
+
+After all epics and stories are complete:
+
+Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue"
+
+#### Menu Handling Logic:
+
+- IF A: Invoke the `xiaoma-advanced-elicitation` skill
+- IF P: Invoke the `xiaoma-party-mode` skill
+- IF C: Save content to {planning_artifacts}/epics.md, update frontmatter, then read fully and follow: ./step-04-final-validation.md
+- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#7-present-final-menu-options)
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- After other menu items execution, return to this menu
+- User can chat or ask questions - always respond and then end with display again of the menu options
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN [C continue option] is selected and [all epics and stories saved to document following the template structure exactly], will you then read fully and follow: `./step-04-final-validation.md` to begin final validation phase.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- All epics processed in sequence
+- Stories created for each epic
+- Template structure followed exactly
+- All FRs covered by stories
+- Stories appropriately sized
+- Acceptance criteria are specific and testable
+- Document is complete and ready for development
+
+### ❌ SYSTEM FAILURE:
+
+- Deviating from template structure
+- Missing epics or stories
+- Stories too large or unclear
+- Missing acceptance criteria
+- Not following proper formatting
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/xmc/workflows/3-solutioning/xiaoma-create-epics-and-stories/steps/step-04-final-validation.md

@@ -0,0 +1,131 @@
+# Step 4: Final Validation
+
+## STEP GOAL:
+
+To validate complete coverage of all requirements and ensure stories are ready for development.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: Process validation sequentially without skipping
+- 📋 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 a product strategist and technical specifications writer
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring validation expertise and quality assurance
+- ✅ User brings their implementation priorities and final review
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on validating complete requirements coverage
+- 🚫 FORBIDDEN to skip any validation checks
+- 💬 Validate FR coverage, story completeness, and dependencies
+- 🚪 ENSURE all stories are ready for development
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Validate every requirement has story coverage
+- 💾 Check story dependencies and flow
+- 📖 Verify architecture compliance
+- 🚫 FORBIDDEN to approve incomplete coverage
+
+## CONTEXT BOUNDARIES:
+
+- Available context: Complete epic and story breakdown from previous steps
+- Focus: Final validation of requirements coverage and story readiness
+- Limits: Validation only, no new content creation
+- Dependencies: Completed story generation from Step 3
+
+## VALIDATION PROCESS:
+
+### 1. FR Coverage Validation
+
+Review the complete epic and story breakdown to ensure EVERY FR is covered:
+
+**CRITICAL CHECK:**
+
+- Go through each FR from the Requirements Inventory
+- Verify it appears in at least one story
+- Check that acceptance criteria fully address the FR
+- No FRs should be left uncovered
+
+### 2. Architecture Implementation Validation
+
+**Check for Starter Template Setup:**
+
+- Does Architecture document specify a starter template?
+- If YES: Epic 1 Story 1 must be "Set up initial project from starter template"
+- This includes cloning, installing dependencies, initial configuration
+
+**Database/Entity Creation Validation:**
+
+- Are database tables/entities created ONLY when needed by stories?
+- ❌ WRONG: Epic 1 creates all tables upfront
+- ✅ RIGHT: Tables created as part of the first story that needs them
+- Each story should create/modify ONLY what it needs
+
+### 3. Story Quality Validation
+
+**Each story must:**
+
+- Be completable by a single dev agent
+- Have clear acceptance criteria
+- Reference specific FRs it implements
+- Include necessary technical details
+- **Not have forward dependencies** (can only depend on PREVIOUS stories)
+- Be implementable without waiting for future stories
+
+### 4. Epic Structure Validation
+
+**Check that:**
+
+- Epics deliver user value, not technical milestones
+- Dependencies flow naturally
+- Foundation stories only setup what's needed
+- No big upfront technical work
+
+### 5. Dependency Validation (CRITICAL)
+
+**Epic Independence Check:**
+
+- Does each epic deliver COMPLETE functionality for its domain?
+- Can Epic 2 function without Epic 3 being implemented?
+- Can Epic 3 function standalone using Epic 1 & 2 outputs?
+- ❌ WRONG: Epic 2 requires Epic 3 features to work
+- ✅ RIGHT: Each epic is independently valuable
+
+**Within-Epic Story Dependency Check:**
+For each epic, review stories in order:
+
+- Can Story N.1 be completed without Stories N.2, N.3, etc.?
+- Can Story N.2 be completed using only Story N.1 output?
+- Can Story N.3 be completed using only Stories N.1 & N.2 outputs?
+- ❌ WRONG: "This story depends on a future story"
+- ❌ WRONG: Story references features not yet implemented
+- ✅ RIGHT: Each story builds only on previous stories
+
+### 6. Complete and Save
+
+If all validations pass:
+
+- Update any remaining placeholders in the document
+- Ensure proper formatting
+- Save the final epics.md
+
+**Present Final Menu:**
+**All validations complete!** [C] Complete Workflow
+
+HALT — wait for user input before proceeding.
+
+When C is selected, the workflow is complete and the epics.md is ready for development.
+
+Epics and Stories complete. Invoke the `xiaoma-help` skill.
+
+Upon Completion of task output: offer to answer any questions about the Epics and Stories.

package/src/xmc/workflows/3-solutioning/xiaoma-create-epics-and-stories/templates/epics-template.md

@@ -0,0 +1,61 @@
+---
+stepsCompleted: []
+inputDocuments: []
+---
+
+# {{project_name}} - Epic Breakdown
+
+## Overview
+
+This document provides the complete epic and story breakdown for {{project_name}}, decomposing the requirements from the PRD, UX Design if it exists, and Architecture requirements into implementable stories.
+
+## Requirements Inventory
+
+### Functional Requirements
+
+{{fr_list}}
+
+### NonFunctional Requirements
+
+{{nfr_list}}
+
+### Additional Requirements
+
+{{additional_requirements}}
+
+### UX Design Requirements
+
+{{ux_design_requirements}}
+
+### FR Coverage Map
+
+{{requirements_coverage_map}}
+
+## Epic List
+
+{{epics_list}}
+
+<!-- Repeat for each epic in epics_list (N = 1, 2, 3...) -->
+
+## Epic {{N}}: {{epic_title_N}}
+
+{{epic_goal_N}}
+
+<!-- Repeat for each story (M = 1, 2, 3...) within epic N -->
+
+### Story {{N}}.{{M}}: {{story_title_N_M}}
+
+As a {{user_type}},
+I want {{capability}},
+So that {{value_benefit}}.
+
+**Acceptance Criteria:**
+
+<!-- for each AC on this story -->
+
+**Given** {{precondition}}
+**When** {{action}}
+**Then** {{expected_outcome}}
+**And** {{additional_criteria}}
+
+<!-- End story repeat -->