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

package/src/modules/xmc/workflows/3-solutioning/architecture/steps/step-02-context.md

@@ -0,0 +1,223 @@
+# Step 2: Project Context Analysis
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ ALWAYS treat this as collaborative discovery between architectural peers
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- 💬 FOCUS on understanding project scope and requirements for architecture
+- 🎯 ANALYZE loaded documents, don't assume or generate requirements
+- ⚠️ ABSOLUTELY NO TIME ESTIMATES - AI development speed has fundamentally changed
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- ⚠️ Present A/P/C menu after generating project context analysis
+- 💾 ONLY save when user chooses C (Continue)
+- 📖 Update frontmatter `stepsCompleted: [1, 2]` before loading next step
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## COLLABORATION MENUS (A/P/C):
+
+This step will generate content and present choices:
+
+- **A (Advanced Elicitation)**: Use discovery protocols to develop deeper insights about project context and architectural implications
+- **P (Party Mode)**: Bring multiple perspectives to analyze project requirements from different architectural angles
+- **C (Continue)**: Save the content to the document and proceed to next step
+
+## PROTOCOL INTEGRATION:
+
+- When 'A' selected: Execute {project-root}/{xiaoma_folder}/core/tasks/advanced-elicitation.xml
+- When 'P' selected: Execute {project-root}/{xiaoma_folder}/core/workflows/party-mode/workflow.md
+- PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed
+- User accepts/rejects protocol changes before proceeding
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from step 1 are available
+- Input documents already loaded are in memory (PRD, epics, UX spec, etc.)
+- Focus on architectural implications of requirements
+- No technology decisions yet - pure analysis phase
+
+## YOUR TASK:
+
+Fully read and Analyze the loaded project documents to understand architectural scope, requirements, and constraints before beginning decision making.
+
+## CONTEXT ANALYSIS SEQUENCE:
+
+### 1. Review Project Requirements
+
+**From PRD Analysis:**
+
+- Extract and analyze Functional Requirements (FRs)
+- Identify Non-Functional Requirements (NFRs) like performance, security, compliance
+- Note any technical constraints or dependencies mentioned
+- Count and categorize requirements to understand project scale
+
+**From Epics/Stories (if available):**
+
+- Map epic structure and user stories to architectural components
+- Extract acceptance criteria for technical implications
+- Identify cross-cutting concerns that span multiple epics
+- Estimate story complexity for architectural planning
+
+**From UX Design (if available):**
+
+- Extract architectural implications from UX requirements:
+  - Component complexity (simple forms vs rich interactions)
+  - Animation/transition requirements
+  - Real-time update needs (live data, collaborative features)
+  - Platform-specific UI requirements
+  - Accessibility standards (WCAG compliance level)
+  - Responsive design breakpoints
+  - Offline capability requirements
+  - Performance expectations (load times, interaction responsiveness)
+
+### 2. Project Scale Assessment
+
+Calculate and present project complexity:
+
+**Complexity Indicators:**
+
+- Real-time features requirements
+- Multi-tenancy needs
+- Regulatory compliance requirements
+- Integration complexity
+- User interaction complexity
+- Data complexity and volume
+
+### 3. Reflect Understanding
+
+Present your analysis back to user for validation:
+
+"I'm reviewing your project documentation for {{project_name}}.
+
+{if_epics_loaded}I see {{epic_count}} epics with {{story_count}} total stories.{/if_epics_loaded}
+{if_no_epics}I found {{fr_count}} functional requirements organized into {{fr_category_list}}.{/if_no_epics}
+{if_ux_loaded}I also found your UX specification which defines the user experience requirements.{/if_ux_loaded}
+
+**Key architectural aspects I notice:**
+
+- [Summarize core functionality from FRs]
+- [Note critical NFRs that will shape architecture]
+- {if_ux_loaded}[Note UX complexity and technical requirements]{/if_ux_loaded}
+- [Identify unique technical challenges or constraints]
+- [Highlight any regulatory or compliance requirements]
+
+**Scale indicators:**
+
+- Project complexity appears to be: [low/medium/high/enterprise]
+- Primary technical domain: [web/mobile/api/backend/full-stack/etc]
+- Cross-cutting concerns identified: [list major ones]
+
+This analysis will help me guide you through the architectural decisions needed to ensure AI agents implement this consistently.
+
+Does this match your understanding of the project scope and requirements?"
+
+### 4. Generate Project Context Content
+
+Prepare the content to append to the document:
+
+#### Content Structure:
+
+```markdown
+## Project Context Analysis
+
+### Requirements Overview
+
+**Functional Requirements:**
+{{analysis of FRs and what they mean architecturally}}
+
+**Non-Functional Requirements:**
+{{NFRs that will drive architectural decisions}}
+
+**Scale & Complexity:**
+{{project_scale_assessment}}
+
+- Primary domain: {{technical_domain}}
+- Complexity level: {{complexity_level}}
+- Estimated architectural components: {{component_count}}
+
+### Technical Constraints & Dependencies
+
+{{known_constraints_dependencies}}
+
+### Cross-Cutting Concerns Identified
+
+{{concerns_that_will_affect_multiple_components}}
+```
+
+### 5. Present Content and Menu
+
+Show the generated content and present choices:
+
+"I've drafted the Project Context Analysis based on your requirements. This sets the foundation for our architectural decisions.
+
+**Here's what I'll add to the document:**
+
+[Show the complete markdown content from step 4]
+
+**What would you like to do?**
+[A] Advanced Elicitation - Let's dive deeper into architectural implications
+[P] Party Mode - Bring different perspectives to analyze requirements
+[C] Continue - Save this analysis and begin architectural decisions"
+
+### 6. Handle Menu Selection
+
+#### If 'A' (Advanced Elicitation):
+
+- Execute {project-root}/{xiaoma_folder}/core/tasks/advanced-elicitation.xml with the current context analysis
+- Process the enhanced architectural insights that come back
+- Ask user: "Accept these enhancements to the project context analysis? (y/n)"
+- If yes: Update content with improvements, then return to A/P/C menu
+- If no: Keep original content, then return to A/P/C menu
+
+#### If 'P' (Party Mode):
+
+- Execute {project-root}/{xiaoma_folder}/core/workflows/party-mode/workflow.md with the current project context
+- Process the collaborative improvements to architectural understanding
+- Ask user: "Accept these changes to the project context analysis? (y/n)"
+- If yes: Update content with improvements, then return to A/P/C menu
+- If no: Keep original content, then return to A/P/C menu
+
+#### If 'C' (Continue):
+
+- Append the final content to `{output_folder}/architecture.md`
+- Update frontmatter: `stepsCompleted: [1, 2]`
+- Load `./step-03-starter.md`
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the content directly to the document using the structure from step 4.
+
+## SUCCESS METRICS:
+
+✅ All input documents thoroughly analyzed for architectural implications
+✅ Project scope and complexity clearly assessed and validated
+✅ Technical constraints and dependencies identified
+✅ Cross-cutting concerns mapped for architectural planning
+✅ User confirmation of project understanding
+✅ A/P/C menu presented and handled correctly
+✅ Content properly appended to document when C selected
+
+## FAILURE MODES:
+
+❌ Skimming documents without deep architectural analysis
+❌ Missing or misinterpreting critical NFRs
+❌ Not validating project understanding with user
+❌ Underestimating complexity indicators
+❌ Generating content without real analysis of loaded documents
+❌ Not presenting A/P/C menu after content generation
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## NEXT STEP:
+
+After user selects 'C' and content is saved to document, load `./step-03-starter.md` to evaluate starter template options.
+
+Remember: Do NOT proceed to step-03 until user explicitly selects 'C' from the A/P/C menu and content is saved!

package/src/modules/xmc/workflows/3-solutioning/architecture/steps/step-03-starter.md

@@ -0,0 +1,330 @@
+# Step 3: Starter Template Evaluation
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+- ✅ ALWAYS treat this as collaborative discovery between architectural peers
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- 💬 FOCUS on evaluating starter template options with current versions
+- 🌐 ALWAYS verify current versions using WebSearch - NEVER trust hardcoded versions
+- ⚠️ ABSOLUTELY NO TIME ESTIMATES - AI development speed has fundamentally changed
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete architecture
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- 🌐 Use WebSearch to verify current versions and options
+- ⚠️ Present A/P/C menu after generating starter template analysis
+- 💾 ONLY save when user chooses C (Continue)
+- 📖 Update frontmatter `stepsCompleted: [1, 2, 3]` before loading next step
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## COLLABORATION MENUS (A/P/C):
+
+This step will generate content and present choices:
+
+- **A (Advanced Elicitation)**: Use discovery protocols to explore unconventional starter options or custom approaches
+- **P (Party Mode)**: Bring multiple perspectives to evaluate starter trade-offs for different use cases
+- **C (Continue)**: Save the content to the document and proceed to next step
+
+## PROTOCOL INTEGRATION:
+
+- When 'A' selected: Execute {project-root}/{xiaoma_folder}/core/tasks/advanced-elicitation.xml
+- When 'P' selected: Execute {project-root}/{xiaoma_folder}/core/workflows/party-mode/workflow.md
+- PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed
+- User accepts/rejects protocol changes before proceeding
+
+## CONTEXT BOUNDARIES:
+
+- Project context from step 2 is available and complete
+- Project context file from step-01 may contain technical preferences
+- No architectural decisions made yet - evaluating foundations
+- Focus on technical preferences discovery and starter evaluation
+- Consider project requirements and existing preferences when evaluating options
+
+## YOUR TASK:
+
+Discover technical preferences and evaluate starter template options, leveraging existing technical preferences and establishing solid architectural foundations.
+
+## STARTER EVALUATION SEQUENCE:
+
+### 0. Check Technical Preferences & Context
+
+**Check Project Context for Existing Technical Preferences:**
+"Before we dive into starter templates, let me check if you have any technical preferences already documented.
+
+{{if_project_context_exists}}
+I found some technical rules in your project context file:
+{{extracted_technical_preferences_from_project_context}}
+
+**Project Context Technical Rules Found:**
+
+- Languages/Frameworks: {{languages_frameworks_from_context}}
+- Tools & Libraries: {{tools_from_context}}
+- Development Patterns: {{patterns_from_context}}
+- Platform Preferences: {{platforms_from_context}}
+
+{{else}}
+No existing technical preferences found in project context file. We'll establish your technical preferences now.
+{{/if_project_context}}"
+
+**Discover User Technical Preferences:**
+"Based on your project context, let's discuss your technical preferences:
+
+{{primary_technology_category}} Preferences:
+
+- **Languages**: Do you have preferences between TypeScript/JavaScript, Python, Go, Rust, etc.?
+- **Frameworks**: Any existing familiarity or preferences (React, Vue, Angular, Next.js, etc.)?
+- **Databases**: Any preferences or existing infrastructure (PostgreSQL, MongoDB, MySQL, etc.)?
+
+**Development Experience:**
+
+- What's your team's experience level with different technologies?
+- Are there any technologies you want to learn vs. what you're comfortable with?
+
+**Platform/Deployment Preferences:**
+
+- Cloud provider preferences (AWS, Vercel, Railway, etc.)?
+- Container preferences (Docker, Serverless, Traditional)?
+
+**Integrations:**
+
+- Any existing systems or APIs you need to integrate with?
+- Third-party services you plan to use (payment, authentication, analytics, etc.)?
+
+These preferences will help me recommend the most suitable starter templates and guide our architectural decisions."
+
+### 1. Identify Primary Technology Domain
+
+Based on project context analysis and technical preferences, identify the primary technology stack:
+
+- **Web application** → Look for Next.js, Vite, Remix, SvelteKit starters
+- **Mobile app** → Look for React Native, Expo, Flutter starters
+- **API/Backend** → Look for NestJS, Express, Fastify, Supabase starters
+- **CLI tool** → Look for CLI framework starters (oclif, commander, etc.)
+- **Full-stack** → Look for T3, RedwoodJS, Blitz, Next.js starters
+- **Desktop** → Look for Electron, Tauri starters
+
+### 2. UX Requirements Consideration
+
+If UX specification was loaded, consider UX requirements when selecting starter:
+
+- **Rich animations** → Framer Motion compatible starter
+- **Complex forms** → React Hook Form included starter
+- **Real-time features** → Socket.io or WebSocket ready starter
+- **Design system** → Storybook-enabled starter
+- **Offline capability** → Service worker or PWA configured starter
+
+### 3. Research Current Starter Options
+
+Use WebSearch to find current, maintained starter templates:
+
+```
+WebSearch: {{primary_technology}} starter template CLI create command latest 2024
+WebSearch: {{primary_technology}} boilerplate generator latest options 2024
+WebSearch: {{primary_technology}} production-ready starter best practices 2024
+```
+
+### 4. Investigate Top Starter Options
+
+For each promising starter found, investigate details:
+
+```
+WebSearch: {{starter_name}} default setup technologies included latest
+WebSearch: {{starter_name}} project structure file organization
+WebSearch: {{starter_name}} production deployment capabilities
+WebSearch: {{starter_name}} recent updates maintenance status 2024
+```
+
+### 5. Analyze What Each Starter Provides
+
+For each viable starter option, document:
+
+**Technology Decisions Made:**
+
+- Language/TypeScript configuration
+- Styling solution (CSS, Tailwind, Styled Components, etc.)
+- Testing framework setup
+- Linting/Formatting configuration
+- Build tooling and optimization
+- Project structure and organization
+
+**Architectural Patterns Established:**
+
+- Code organization patterns
+- Component structure conventions
+- API layering approach
+- State management setup
+- Routing patterns
+- Environment configuration
+
+**Development Experience Features:**
+
+- Hot reloading and development server
+- TypeScript configuration
+- Debugging setup
+- Testing infrastructure
+- Documentation generation
+
+### 6. Present Starter Options
+
+Based on user skill level and project needs:
+
+**For Expert Users:**
+"Found {{starter_name}} which provides:
+{{quick_decision_list_of_key_decisions}}
+
+This would establish our base architecture with these technical decisions already made. Use it?"
+
+**For Intermediate Users:**
+"I found {{starter_name}}, which is a well-maintained starter for {{project_type}} projects.
+
+It makes these architectural decisions for us:
+{{decision_list_with_explanations}}
+
+This gives us a solid foundation following current best practices. Should we use it?"
+
+**For Beginner Users:**
+"I found {{starter_name}}, which is like a pre-built foundation for your project.
+
+Think of it like buying a prefab house frame instead of cutting each board yourself.
+
+It makes these decisions for us:
+{{friendly_explanation_of_decisions}}
+
+This is a great starting point that follows best practices and saves us from making dozens of small technical choices. Should we use it?"
+
+### 7. Get Current CLI Commands
+
+If user shows interest in a starter, get the exact current commands:
+
+```
+WebSearch: {{starter_name}} CLI command options flags latest 2024
+WebSearch: {{starter_name}} create new project command examples
+```
+
+### 8. Generate Starter Template Content
+
+Prepare the content to append to the document:
+
+#### Content Structure:
+
+````markdown
+## Starter Template Evaluation
+
+### Primary Technology Domain
+
+{{identified_domain}} based on project requirements analysis
+
+### Starter Options Considered
+
+{{analysis_of_evaluated_starters}}
+
+### Selected Starter: {{starter_name}}
+
+**Rationale for Selection:**
+{{why_this_starter_was_chosen}}
+
+**Initialization Command:**
+
+```bash
+{{full_starter_command_with_options}}
+```
+````
+
+**Architectural Decisions Provided by Starter:**
+
+**Language & Runtime:**
+{{language_typescript_setup}}
+
+**Styling Solution:**
+{{styling_solution_configuration}}
+
+**Build Tooling:**
+{{build_tools_and_optimization}}
+
+**Testing Framework:**
+{{testing_setup_and_configuration}}
+
+**Code Organization:**
+{{project_structure_and_patterns}}
+
+**Development Experience:**
+{{development_tools_and_workflow}}
+
+**Note:** Project initialization using this command should be the first implementation story.
+
+```
+
+### 9. Present Content and Menu
+
+Show the generated content and present choices:
+
+"I've analyzed starter template options for {{project_type}} projects.
+
+**Here's what I'll add to the document:**
+
+[Show the complete markdown content from step 8]
+
+**What would you like to do?**
+[A] Advanced Elicitation - Explore custom approaches or unconventional starters
+[P] Party Mode - Evaluate trade-offs from different perspectives
+[C] Continue - Save this decision and move to architectural decisions"
+
+### 10. Handle Menu Selection
+
+#### If 'A' (Advanced Elicitation):
+
+- Execute {project-root}/{xiaoma_folder}/core/tasks/advanced-elicitation.xml with current starter analysis
+- Process enhanced insights about starter options or custom approaches
+- Ask user: "Accept these changes to the starter template evaluation? (y/n)"
+- If yes: Update content, then return to A/P/C menu
+- If no: Keep original content, then return to A/P/C menu
+
+#### If 'P' (Party Mode):
+
+- Execute {project-root}/{xiaoma_folder}/core/workflows/party-mode/workflow.md with starter evaluation context
+- Process collaborative insights about starter trade-offs
+- Ask user: "Accept these changes to the starter template evaluation? (y/n)"
+- If yes: Update content, then return to A/P/C menu
+- If no: Keep original content, then return to A/P/C menu
+
+#### If 'C' (Continue):
+
+- Append the final content to `{output_folder}/architecture.md`
+- Update frontmatter: `stepsCompleted: [1, 2, 3]`
+- Load `./step-04-decisions.md`
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the content directly to the document using the structure from step 8.
+
+## SUCCESS METRICS:
+
+✅ Primary technology domain correctly identified from project context
+✅ Current, maintained starter templates researched and evaluated
+✅ All versions verified using WebSearch, not hardcoded
+✅ Architectural implications of starter choice clearly documented
+✅ User provided with clear rationale for starter selection
+✅ A/P/C menu presented and handled correctly
+✅ Content properly appended to document when C selected
+
+## FAILURE MODES:
+
+❌ Not verifying current versions with WebSearch
+❌ Ignoring UX requirements when evaluating starters
+❌ Not documenting what architectural decisions the starter makes
+❌ Failing to consider maintenance status of starter templates
+❌ Not providing clear rationale for starter selection
+❌ Not presenting A/P/C menu after content generation
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## NEXT STEP:
+
+After user selects 'C' and content is saved to document, load `./step-04-decisions.md` to begin making specific architectural decisions.
+
+Remember: Do NOT proceed to step-04 until user explicitly selects 'C' from the A/P/C menu and content is saved!
+```