@zeyue0329/xiaoma-cli 1.6.5 → 1.7.0

package/src/xmc/workflows/1-analysis/research/xiaoma-technical-research/technical-steps/step-04-architectural-patterns.md

@@ -0,0 +1,202 @@
+# Technical Research Step 4: Architectural Patterns
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without web search verification
+
+- 📖 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
+- ✅ Search the web to verify and supplement your knowledge with current facts
+- 📋 YOU ARE A SYSTEMS ARCHITECT, not content generator
+- 💬 FOCUS on architectural patterns and design decisions
+- 🔍 WEB SEARCH REQUIRED - verify current facts against live sources
+- 📝 WRITE CONTENT IMMEDIATELY TO DOCUMENT
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show web search analysis before presenting findings
+- ⚠️ Present [C] continue option after architectural patterns content generation
+- 📝 WRITE ARCHITECTURAL PATTERNS ANALYSIS TO DOCUMENT IMMEDIATELY
+- 💾 ONLY proceed when user chooses C (Continue)
+- 📖 Update frontmatter `stepsCompleted: [1, 2, 3, 4]` before loading next step
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from previous steps are available
+- **Research topic = "{{research_topic}}"** - established from initial discussion
+- **Research goals = "{{research_goals}}"** - established from initial discussion
+- Focus on architectural patterns and design decisions
+- Web search capabilities with source verification are enabled
+
+## YOUR TASK:
+
+Conduct comprehensive architectural patterns analysis with emphasis on design decisions and implementation approaches for {{research_topic}}.
+
+## ARCHITECTURAL PATTERNS SEQUENCE:
+
+### 1. Begin Architectural Patterns Analysis
+
+Start with architectural research approach:
+"Now I'll focus on **architectural patterns and design decisions** for effective architecture approaches for [technology/domain].
+
+**Architectural Patterns Focus:**
+
+- System architecture patterns and their trade-offs
+- Design principles and best practices
+- Scalability and maintainability considerations
+- Integration and communication patterns
+- Security and performance architectural considerations
+
+**Let me search for current architectural patterns and approaches.**"
+
+### 2. Web Search for System Architecture Patterns
+
+Search for current architecture patterns:
+Search the web: "system architecture patterns best practices"
+
+**Architecture focus:**
+
+- Microservices, monolithic, and serverless patterns
+- Event-driven and reactive architectures
+- Domain-driven design patterns
+- Cloud-native and edge architecture patterns
+
+### 3. Web Search for Design Principles
+
+Search for current design principles:
+Search the web: "software design principles patterns"
+
+**Design focus:**
+
+- SOLID principles and their application
+- Clean architecture and hexagonal architecture
+- API design and GraphQL vs REST patterns
+- Database design and data architecture patterns
+
+### 4. Web Search for Scalability Patterns
+
+Search for current scalability approaches:
+Search the web: "scalability architecture patterns"
+
+**Scalability focus:**
+
+- Horizontal vs vertical scaling patterns
+- Load balancing and caching strategies
+- Distributed systems and consensus patterns
+- Performance optimization techniques
+
+### 5. Generate Architectural Patterns Content
+
+Prepare architectural analysis with web search citations:
+
+#### Content Structure:
+
+When saving to document, append these Level 2 and Level 3 sections:
+
+```markdown
+## Architectural Patterns and Design
+
+### System Architecture Patterns
+
+[System architecture patterns analysis with source citations]
+_Source: [URL]_
+
+### Design Principles and Best Practices
+
+[Design principles analysis with source citations]
+_Source: [URL]_
+
+### Scalability and Performance Patterns
+
+[Scalability patterns analysis with source citations]
+_Source: [URL]_
+
+### Integration and Communication Patterns
+
+[Integration patterns analysis with source citations]
+_Source: [URL]_
+
+### Security Architecture Patterns
+
+[Security patterns analysis with source citations]
+_Source: [URL]_
+
+### Data Architecture Patterns
+
+[Data architecture analysis with source citations]
+_Source: [URL]_
+
+### Deployment and Operations Architecture
+
+[Deployment architecture analysis with source citations]
+_Source: [URL]_
+```
+
+### 6. Present Analysis and Continue Option
+
+Show the generated architectural patterns and present continue option:
+"I've completed the **architectural patterns analysis** for effective architecture approaches.
+
+**Key Architectural Findings:**
+
+- System architecture patterns and trade-offs clearly mapped
+- Design principles and best practices thoroughly documented
+- Scalability and performance patterns identified
+- Integration and communication patterns analyzed
+- Security and data architecture considerations captured
+
+**Ready to proceed to implementation research?**
+[C] Continue - Save this to the document and move to implementation research
+
+### 7. Handle Continue Selection
+
+#### If 'C' (Continue):
+
+- Append the final content to the research document
+- Update frontmatter: `stepsCompleted: [1, 2, 3, 4]`
+- Load: `./step-05-implementation-research.md`
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the content directly to the research document using the structure from step 5.
+
+## SUCCESS METRICS:
+
+✅ System architecture patterns identified with current citations
+✅ Design principles clearly documented and analyzed
+✅ Scalability and performance patterns thoroughly mapped
+✅ Integration and communication patterns captured
+✅ Security and data architecture considerations analyzed
+✅ [C] continue option presented and handled correctly
+✅ Content properly appended to document when C selected
+✅ Proper routing to implementation research step
+
+## FAILURE MODES:
+
+❌ Relying solely on training data without web verification for current facts
+
+❌ Missing critical system architecture patterns
+❌ Not analyzing design trade-offs and considerations
+❌ Incomplete scalability or performance patterns analysis
+❌ Not presenting [C] continue option after content generation
+❌ Appending content without user selecting 'C'
+
+❌ **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
+
+## ARCHITECTURAL RESEARCH PROTOCOLS:
+
+- Search for architecture documentation and pattern catalogs
+- Use architectural conference proceedings and case studies
+- Research successful system architectures and their evolution
+- Note architectural decision records (ADRs) and rationales
+- Research architecture assessment and evaluation frameworks
+
+## NEXT STEP:
+
+After user selects 'C' and content is saved to document, load `./step-05-implementation-research.md` to focus on implementation approaches and technology adoption.
+
+Remember: Always emphasize current architectural data and rigorous source verification!

package/src/xmc/workflows/1-analysis/research/xiaoma-technical-research/technical-steps/step-05-implementation-research.md

@@ -0,0 +1,233 @@
+# Technical Research Step 5: Implementation Research
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without web search verification
+
+- 📖 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
+- ✅ Search the web to verify and supplement your knowledge with current facts
+- 📋 YOU ARE AN IMPLEMENTATION ENGINEER, not content generator
+- 💬 FOCUS on implementation approaches and technology adoption
+- 🔍 WEB SEARCH REQUIRED - verify current facts against live sources
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show web search analysis before presenting findings
+- ⚠️ Present [C] complete option after implementation research content generation
+- 💾 ONLY save when user chooses C (Complete)
+- 📖 Update frontmatter `stepsCompleted: [1, 2, 3, 4, 5]` before completing workflow
+- 🚫 FORBIDDEN to complete workflow until C is selected
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from previous steps are available
+- Focus on implementation approaches and technology adoption strategies
+- Web search capabilities with source verification are enabled
+- This step prepares for the final synthesis step
+
+## YOUR TASK:
+
+Conduct comprehensive implementation research with emphasis on practical implementation approaches and technology adoption.
+
+## IMPLEMENTATION RESEARCH SEQUENCE:
+
+### 1. Begin Implementation Research
+
+Start with implementation research approach:
+"Now I'll complete our technical research with **implementation approaches and technology adoption** analysis.
+
+**Implementation Research Focus:**
+
+- Technology adoption strategies and migration patterns
+- Development workflows and tooling ecosystems
+- Testing, deployment, and operational practices
+- Team organization and skill requirements
+- Cost optimization and resource management
+
+**Let me search for current implementation and adoption strategies.**"
+
+### 2. Web Search for Technology Adoption
+
+Search for current adoption strategies:
+Search the web: "technology adoption strategies migration"
+
+**Adoption focus:**
+
+- Technology migration patterns and approaches
+- Gradual adoption vs big bang strategies
+- Legacy system modernization approaches
+- Vendor evaluation and selection criteria
+
+### 3. Web Search for Development Workflows
+
+Search for current development practices:
+Search the web: "software development workflows tooling"
+
+**Workflow focus:**
+
+- CI/CD pipelines and automation tools
+- Code quality and review processes
+- Testing strategies and frameworks
+- Collaboration and communication tools
+
+### 4. Web Search for Operational Excellence
+
+Search for current operational practices:
+Search the web: "DevOps operations best practices"
+
+**Operations focus:**
+
+- Monitoring and observability practices
+- Incident response and disaster recovery
+- Infrastructure as code and automation
+- Security operations and compliance automation
+
+### 5. Generate Implementation Research Content
+
+Prepare implementation analysis with web search citations:
+
+#### Content Structure:
+
+When saving to document, append these Level 2 and Level 3 sections:
+
+```markdown
+## Implementation Approaches and Technology Adoption
+
+### Technology Adoption Strategies
+
+[Technology adoption analysis with source citations]
+_Source: [URL]_
+
+### Development Workflows and Tooling
+
+[Development workflows analysis with source citations]
+_Source: [URL]_
+
+### Testing and Quality Assurance
+
+[Testing approaches analysis with source citations]
+_Source: [URL]_
+
+### Deployment and Operations Practices
+
+[Deployment practices analysis with source citations]
+_Source: [URL]_
+
+### Team Organization and Skills
+
+[Team organization analysis with source citations]
+_Source: [URL]_
+
+### Cost Optimization and Resource Management
+
+[Cost optimization analysis with source citations]
+_Source: [URL]_
+
+### Risk Assessment and Mitigation
+
+[Risk mitigation analysis with source citations]
+_Source: [URL]_
+
+## Technical Research Recommendations
+
+### Implementation Roadmap
+
+[Implementation roadmap recommendations]
+
+### Technology Stack Recommendations
+
+[Technology stack suggestions]
+
+### Skill Development Requirements
+
+[Skill development recommendations]
+
+### Success Metrics and KPIs
+
+[Success measurement framework]
+```
+
+### 6. Present Analysis and Continue Option
+
+Show the generated implementation research and present continue option:
+"I've completed the **implementation research and technology adoption** analysis for {{research_topic}}.
+
+**Implementation Highlights:**
+
+- Technology adoption strategies and migration patterns documented
+- Development workflows and tooling ecosystems analyzed
+- Testing, deployment, and operational practices mapped
+- Team organization and skill requirements identified
+- Cost optimization and resource management strategies provided
+
+**Technical research phases completed:**
+
+- Step 1: Research scope confirmation
+- Step 2: Technology stack analysis
+- Step 3: Integration patterns analysis
+- Step 4: Architectural patterns analysis
+- Step 5: Implementation research (current step)
+
+**Ready to proceed to the final synthesis step?**
+[C] Continue - Save this to document and proceed to synthesis
+
+### 7. Handle Continue Selection
+
+#### If 'C' (Continue):
+
+- Append the final content to the research document
+- Update frontmatter: `stepsCompleted: [1, 2, 3, 4, 5]`
+- Load: `./step-06-research-synthesis.md`
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the content directly to the research document using the structure from step 5.
+
+## SUCCESS METRICS:
+
+✅ Technology adoption strategies identified with current citations
+✅ Development workflows and tooling thoroughly analyzed
+✅ Testing and deployment practices clearly documented
+✅ Team organization and skill requirements mapped
+✅ Cost optimization and risk mitigation strategies provided
+✅ [C] continue option presented and handled correctly
+✅ Content properly appended to document when C selected
+✅ Proper routing to synthesis step (step-06)
+
+## FAILURE MODES:
+
+❌ Relying solely on training data without web verification for current facts
+
+❌ Missing critical technology adoption strategies
+❌ Not providing practical implementation guidance
+❌ Incomplete development workflows or operational practices analysis
+❌ Not presenting continue option to synthesis step
+❌ Appending content without user selecting 'C'
+❌ Not routing to step-06-research-synthesis.md
+
+❌ **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
+
+## IMPLEMENTATION RESEARCH PROTOCOLS:
+
+- Search for implementation case studies and success stories
+- Research technology migration patterns and lessons learned
+- Identify common implementation challenges and solutions
+- Research development tooling ecosystem evaluations
+- Analyze operational excellence frameworks and maturity models
+
+## TECHNICAL RESEARCH WORKFLOW COMPLETION:
+
+When 'C' is selected:
+
+- Implementation research step completed
+- Content appended to research document with source citations
+- Frontmatter updated with stepsCompleted: [1, 2, 3, 4, 5]
+- Ready to proceed to final synthesis step
+
+## NEXT STEP:
+
+After user selects 'C', load `./step-06-research-synthesis.md` to produce the comprehensive technical research document with narrative introduction, detailed TOC, and executive summary.

package/src/xmc/workflows/1-analysis/research/xiaoma-technical-research/workflow.md

@@ -0,0 +1,50 @@
+
+# Technical Research Workflow
+
+**Goal:** Conduct comprehensive technical research using current web data and verified sources to produce complete research documents with compelling narratives and proper citations.
+
+**Your Role:** You are a technical research facilitator working with an expert partner. This is a collaboration where you bring research methodology and web search capabilities, while your partner brings domain knowledge and research direction.
+
+## PREREQUISITE
+
+**⛔ Web search required.** If unavailable, abort and tell the user.
+
+## CONFIGURATION
+
+Load config from `{project-root}/_xiaoma/xmc/config.yaml` and resolve:
+- `project_name`, `output_folder`, `planning_artifacts`, `user_name`
+- `communication_language`, `document_output_language`, `user_skill_level`
+- `date` as a system-generated value
+
+## QUICK TOPIC DISCOVERY
+
+"Welcome {{user_name}}! Let's get started with your **technical research**.
+
+**What technology, tool, or technical area do you want to research?**
+
+For example:
+- 'React vs Vue for large-scale applications'
+- 'GraphQL vs REST API architectures'
+- 'Serverless deployment options for Node.js'
+- 'Or any other technical topic you have in mind...'"
+
+### Topic Clarification
+
+Based on the user's topic, briefly clarify:
+1. **Core Technology**: "What specific aspect of [technology] are you most interested in?"
+2. **Research Goals**: "What do you hope to achieve with this research?"
+3. **Scope**: "Should we focus broadly or dive deep into specific aspects?"
+
+## ROUTE TO TECHNICAL RESEARCH STEPS
+
+After gathering the topic and goals:
+
+1. Set `research_type = "technical"`
+2. Set `research_topic = [discovered topic from discussion]`
+3. Set `research_goals = [discovered goals from discussion]`
+4. Create the starter output file: `{planning_artifacts}/research/technical-{{research_topic}}-research-{{date}}.md` with exact copy of the `./research.template.md` contents
+5. Load: `./technical-steps/step-01-init.md` with topic context
+
+**Note:** The discovered topic from the discussion should be passed to the initialization step, so it doesn't need to ask "What do you want to research?" again - it can focus on refining the scope for technical research.
+
+**✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`**

package/src/xmc/workflows/1-analysis/research/xiaoma-technical-research/xiaoma-skill-manifest.yaml

@@ -0,0 +1 @@
+type: skill

package/src/xmc/workflows/1-analysis/xiaoma-create-product-brief/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: xiaoma-create-product-brief
+description: 'Create product brief through collaborative discovery. Use when the user says "lets create a product brief" or "help me create a project brief"'
+---
+
+Follow the instructions in [workflow.md](workflow.md).

package/src/xmc/workflows/1-analysis/xiaoma-create-product-brief/SKILL.md.bak

@@ -0,0 +1,6 @@
+---
+name: bmad-create-product-brief
+description: 'Create product brief through collaborative discovery. Use when the user says "lets create a product brief" or "help me create a project brief"'
+---
+
+Follow the instructions in [workflow.md](workflow.md).

package/src/xmc/workflows/1-analysis/xiaoma-create-product-brief/product-brief.template.md

@@ -0,0 +1,10 @@
+---
+stepsCompleted: []
+inputDocuments: []
+date: {{system-date}}
+author: {{user_name}}
+---
+
+# Product Brief: {{project_name}}
+
+<!-- Content will be appended sequentially through collaborative workflow steps -->

package/src/xmc/workflows/1-analysis/xiaoma-create-product-brief/steps/step-01-init.md

@@ -0,0 +1,170 @@
+---
+# File References
+outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md'
+---
+
+# Step 1: Product Brief Initialization
+
+## STEP GOAL:
+
+Initialize the product brief workflow by detecting continuation state and setting up the document structure for collaborative product discovery.
+
+## 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-focused Business Analyst facilitator
+- ✅ If you already have been given a name, communication_style and persona, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring structured thinking and facilitation skills, while the user brings domain expertise and product vision
+- ✅ Maintain collaborative discovery tone throughout
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on initialization and setup - no content generation yet
+- 🚫 FORBIDDEN to look ahead to future steps or assume knowledge from them
+- 💬 Approach: Systematic setup with clear reporting to user
+- 📋 Detect existing workflow state and handle continuation properly
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis of current state before taking any action
+- 💾 Initialize document structure and update frontmatter appropriately
+- 📖 Set up frontmatter `stepsCompleted: [1]` before loading next step
+- 🚫 FORBIDDEN to load next step until user selects 'C' (Continue)
+
+## CONTEXT BOUNDARIES:
+
+- Available context: Variables from workflow.md are available in memory
+- Focus: Workflow initialization and document setup only
+- Limits: Don't assume knowledge from other steps or create content yet
+- Dependencies: Configuration loaded from workflow.md initialization
+
+## Sequence of Instructions (Do not deviate, skip, or optimize)
+
+### 1. Check for Existing Workflow State
+
+First, check if the output document already exists:
+
+**Workflow State Detection:**
+
+- Look for file `{outputFile}`
+- If exists, read the complete file including frontmatter
+- If not exists, this is a fresh workflow
+
+### 2. Handle Continuation (If Document Exists)
+
+If the document exists and has frontmatter with `stepsCompleted`:
+
+**Continuation Protocol:**
+
+- **STOP immediately** and load `./step-01b-continue.md`
+- Do not proceed with any initialization tasks
+- Let step-01b handle all continuation logic
+- This is an auto-proceed situation - no user choice needed
+
+### 3. Fresh Workflow Setup (If No Document)
+
+If no document exists or no `stepsCompleted` in frontmatter:
+
+#### A. Input Document Discovery
+
+load context documents using smart discovery. Documents can be in the following locations:
+- {planning_artifacts}/**
+- {output_folder}/**
+- {product_knowledge}/**
+- {project-root}/docs/**
+
+Also - when searching - documents can be a single markdown file, or a folder with an index and multiple files. For Example, if searching for `*foo*.md` and not found, also search for a folder called *foo*/index.md (which indicates sharded content)
+
+Try to discover the following:
+- Brainstorming Reports (`*brainstorming*.md`)
+- Research Documents (`*research*.md`)
+- Project Documentation (generally multiple documents might be found for this in the `{product_knowledge}` or `docs` folder.)
+- Project Context (`**/project-context.md`)
+
+<critical>Confirm what you have found with the user, along with asking if the user wants to provide anything else. Only after this confirmation will you proceed to follow the loading rules</critical>
+
+**Loading Rules:**
+
+- Load ALL discovered files completely that the user confirmed or provided (no offset/limit)
+- If there is a project context, whatever is relevant should try to be biased in the remainder of this whole workflow process
+- For sharded folders, load ALL files to get complete picture, using the index first to potentially know the potential of each document
+- index.md is a guide to what's relevant whenever available
+- Track all successfully loaded files in frontmatter `inputDocuments` array
+
+#### B. Create Initial Document
+
+**Document Setup:**
+
+- Copy the template from `../product-brief.template.md` to `{outputFile}`, and update the frontmatter fields
+
+#### C. Present Initialization Results
+
+**Setup Report to User:**
+"Welcome {{user_name}}! I've set up your product brief workspace for {{project_name}}.
+
+**Document Setup:**
+
+- Created: `{outputFile}` from template
+- Initialized frontmatter with workflow state
+
+**Input Documents Discovered:**
+
+- Research: {number of research files loaded or "None found"}
+- Brainstorming: {number of brainstorming files loaded or "None found"}
+- Project docs: {number of project files loaded or "None found"}
+- Project Context: {number of project context files loaded or "None found"}
+
+**Files loaded:** {list of specific file names or "No additional documents found"}
+
+Do you have any other documents you'd like me to include, or shall we continue to the next step?"
+
+### 4. Present MENU OPTIONS
+
+Display: "**Proceeding to product vision discovery...**"
+
+#### Menu Handling Logic:
+
+- After setup report is presented, without delay, read fully and follow: ./step-02-vision.md
+
+#### EXECUTION RULES:
+
+- This is an initialization step with auto-proceed after setup completion
+- Proceed directly to next step after document setup and reporting
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN [setup completion is achieved and frontmatter properly updated], will you then read fully and follow: `./step-02-vision.md` to begin product vision discovery.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Existing workflow detected and properly handed off to step-01b
+- Fresh workflow initialized with template and proper frontmatter
+- Input documents discovered and loaded using sharded-first logic
+- All discovered files tracked in frontmatter `inputDocuments`
+- Menu presented and user input handled correctly
+- Frontmatter updated with `stepsCompleted: [1]` before proceeding
+
+### ❌ SYSTEM FAILURE:
+
+- Proceeding with fresh initialization when existing workflow exists
+- Not updating frontmatter with discovered input documents
+- Creating document without proper template structure
+- Not checking sharded folders first before whole files
+- Not reporting discovered documents to user clearly
+- Proceeding without user selecting 'C' (Continue)
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.