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

package/src/modules/xmb/docs/agents/understanding-agent-types.md

@@ -0,0 +1,184 @@
+# Understanding Agent Types: Architecture, Not Capability
+
+**CRITICAL DISTINCTION:** Agent types define **architecture and integration**, NOT capability limits.
+
+ALL agent types can:
+
+- ✓ Write to {output_folder}, {project-root}, or anywhere on system
+- ✓ Update artifacts and files
+- ✓ Execute bash commands
+- ✓ Use core variables ({xiaoma_folder}, {output_folder}, etc.)
+- ✓ Have complex prompts and logic
+- ✓ Invoke external tools
+
+## What Actually Differs
+
+| Feature                | Simple        | Expert                | Module             |
+| ---------------------- | ------------- | --------------------- | ------------------ |
+| **Self-contained**     | ✓ All in YAML | Sidecar files         | Sidecar optional   |
+| **Persistent memory**  | ✗ Stateless   | ✓ memories.md         | ✓ If needed        |
+| **Knowledge base**     | ✗             | ✓ sidecar/knowledge/  | Module/shared      |
+| **Domain restriction** | ✗ System-wide | ✓ Sidecar only        | Optional           |
+| **Personal workflows** | ✗             | ✓ Sidecar workflows\* | ✗                  |
+| **Module workflows**   | ✗             | ✗                     | ✓ Shared workflows |
+| **Team integration**   | Solo utility  | Personal assistant    | Team member        |
+
+\*Expert agents CAN have personal workflows in sidecar if critical_actions loads workflow engine
+
+## The Same Agent, Three Ways
+
+**Scenario:** Code Generator Agent
+
+### As Simple Agent (Architecture: Self-contained)
+
+```yaml
+agent:
+  metadata:
+    name: CodeGen
+    type: simple
+
+  prompts:
+    - id: generate
+      content: |
+        Ask user for spec details. Generate code.
+        Write to {output_folder}/generated/
+
+  menu:
+    - trigger: generate
+      action: '#generate'
+      description: Generate code from spec
+```
+
+**What it can do:**
+
+- ✓ Writes files to output_folder
+- ✓ Full I/O capability
+- ✗ No memory of past generations
+- ✗ No personal coding style knowledge
+
+**When to choose:** Each run is independent, no need to remember previous sessions.
+
+### As Expert Agent (Architecture: Personal sidecar)
+
+```yaml
+agent:
+  metadata:
+    name: CodeGen
+    type: expert
+
+  critical_actions:
+    - Load my coding standards from sidecar/knowledge/
+    - Load memories from sidecar/memories.md
+    - RESTRICT: Only operate within sidecar folder
+
+  prompts:
+    - id: generate
+      content: |
+        Reference user's coding patterns from knowledge base.
+        Remember past generations from memories.
+        Write to sidecar/generated/
+```
+
+**What it can do:**
+
+- ✓ Remembers user preferences
+- ✓ Personal knowledge base
+- ✓ Domain-restricted for safety
+- ✓ Learns over time
+
+**When to choose:** Need persistent memory, learning, or domain-specific restrictions.
+
+### As Module Agent (Architecture: Team integration)
+
+```yaml
+agent:
+  metadata:
+    name: CodeGen
+    module: xmc
+
+  menu:
+    - trigger: implement-story
+      workflow: '{xiaoma_folder}/xmc/workflows/dev-story/workflow.yaml'
+      description: Implement user story
+
+    - trigger: refactor
+      workflow: '{xiaoma_folder}/xmc/workflows/refactor/workflow.yaml'
+      description: Refactor codebase
+```
+
+**What it can do:**
+
+- ✓ Orchestrates full dev workflows
+- ✓ Coordinates with other XMC agents
+- ✓ Shared team infrastructure
+- ✓ Professional operations
+
+**When to choose:** Part of larger system, orchestrates workflows, team coordination.
+
+## Important: Any Agent Can Be Added to a Module
+
+**CLARIFICATION:** The "Module Agent" type is about **design intent and ecosystem integration**, not just file location.
+
+### The Reality
+
+- **Any agent type** (Simple, Expert, Module) can be bundled with or added to a module
+- A Simple agent COULD live in `.xiaoma/xmc/agents/`
+- An Expert agent COULD be included in a module bundle
+
+### What Makes a "Module Agent" Special
+
+A **Module Agent** is specifically:
+
+1. **Designed FOR** a particular module ecosystem (XMC, CIS, XMB, etc.)
+2. **Uses or contributes** that module's workflows
+3. **Included by default** in that module's bundle
+4. **Coordinates with** other agents in that module
+
+### Examples
+
+**Simple Agent added to XMC:**
+
+- Lives in `.xiaoma/xmc/agents/formatter.agent.yaml`
+- Bundled with XMC for convenience
+- But still stateless, self-contained
+- NOT a "Module Agent" - just a Simple agent in a module
+
+**Module Agent in XMC:**
+
+- Lives in `.xiaoma/xmc/agents/tech-writer.agent.yaml`
+- Orchestrates XMC documentation workflows
+- Coordinates with other XMC agents (PM, Dev, Analyst)
+- Included in default XMC bundle
+- IS a "Module Agent" - designed for XMC ecosystem
+
+**The distinction:** File location vs design intent and integration.
+
+## Choosing Your Agent Type
+
+### Choose Simple when:
+
+- Single-purpose utility (no memory needed)
+- Stateless operations (each run is independent)
+- Self-contained logic (everything in YAML)
+- No persistent context required
+
+### Choose Expert when:
+
+- Need to remember things across sessions
+- Personal knowledge base (user preferences, domain data)
+- Domain-specific expertise with restricted scope
+- Learning/adapting over time
+
+### Choose Module when:
+
+- Designed FOR a specific module ecosystem (XMC, CIS, etc.)
+- Uses or contributes that module's workflows
+- Coordinates with other module agents
+- Will be included in module's default bundle
+- Part of professional team infrastructure
+
+## The Golden Rule
+
+**Choose based on state and integration needs, NOT on what the agent can DO.**
+
+All three types are equally powerful. The difference is how they manage state, where they store data, and how they integrate with your system.

package/src/modules/xmb/docs/workflows/architecture.md

@@ -0,0 +1,220 @@
+# Standalone Workflow Builder Architecture
+
+This document describes the architecture of the standalone workflow builder system - a pure markdown approach to creating structured workflows.
+
+## Core Architecture Principles
+
+### 1. Micro-File Design
+
+Each workflow consists of multiple focused, self-contained files:
+
+```
+workflow-folder/
+├── workflow.md              # Main workflow configuration
+├── steps/                   # Step instruction files (focused, self-contained)
+│   ├── step-01-init.md
+│   ├── step-02-profile.md
+│   └── step-N-[name].md
+├── templates/               # Content templates
+│   ├── profile-section.md
+│   └── [other-sections].md
+└── data/                    # Optional data files
+    └── [data-files].csv/.json
+```
+
+### 2. Just-In-Time (JIT) Loading
+
+- **Single File in Memory**: Only the current step file is loaded
+- **No Future Peeking**: Step files must not reference future steps
+- **Sequential Processing**: Steps execute in strict order
+- **On-Demand Loading**: Templates load only when needed
+
+### 3. State Management
+
+- **Frontmatter Tracking**: Workflow state stored in output document frontmatter
+- **Progress Array**: `stepsCompleted` tracks completed steps
+- **Last Step Marker**: `lastStep` indicates where to resume
+- **Append-Only Building**: Documents grow by appending content
+
+### 4. Execution Model
+
+```
+1. Load workflow.md → Read configuration
+2. Execute step-01-init.md → Initialize or detect continuation
+3. For each step:
+   a. Load step file completely
+   b. Execute instructions sequentially
+   c. Wait for user input at menu points
+   d. Only proceed with 'C' (Continue)
+   e. Update document/frontmatter
+   f. Load next step
+```
+
+## Key Components
+
+### Workflow File (workflow.md)
+
+- **Purpose**: Entry point and configuration
+- **Content**: Role definition, goal, architecture rules
+- **Action**: Points to step-01-init.md
+
+### Step Files (step-NN-[name].md)
+
+- **Size**: Focused and concise (typically 5-10KB)
+- **Structure**: Frontmatter + sequential instructions
+- **Features**: Self-contained rules, menu handling, state updates
+
+### Frontmatter Variables
+
+Standard variables in step files:
+
+```yaml
+workflow_path: '{project-root}/{xiaoma_folder}/xmb/reference/workflows/[workflow-name]'
+thisStepFile: '{workflow_path}/steps/step-[N]-[name].md'
+nextStepFile: '{workflow_path}/steps/step-[N+1]-[name].md'
+workflowFile: '{workflow_path}/workflow.md'
+outputFile: '{output_folder}/[output-name]-{project_name}.md'
+```
+
+## Execution Flow
+
+### Fresh Workflow
+
+```
+workflow.md
+    ↓
+step-01-init.md (creates document)
+    ↓
+step-02-[name].md
+    ↓
+step-03-[name].md
+    ↓
+...
+    ↓
+step-N-[final].md (completes workflow)
+```
+
+### Continuation Workflow
+
+```
+workflow.md
+    ↓
+step-01-init.md (detects existing document)
+    ↓
+step-01b-continue.md (analyzes state)
+    ↓
+step-[appropriate-next].md
+```
+
+## Menu System
+
+### Standard Menu Pattern
+
+```
+Display: **Select an Option:** [A] [Action] [P] Party Mode [C] Continue
+
+#### Menu Handling Logic:
+- IF A: Execute {advancedElicitationTask}
+- IF P: Execute {partyModeWorkflow}
+- IF C: Save content, update frontmatter, load next step
+```
+
+### Menu Rules
+
+- **Halt Required**: Always wait for user input
+- **Continue Only**: Only proceed with 'C' selection
+- **State Persistence**: Save before loading next step
+- **Loop Back**: Return to menu after other actions
+
+## Collaborative Dialogue Model
+
+### Not Command-Response
+
+- **Facilitator Role**: AI guides, user decides
+- **Equal Partnership**: Both parties contribute
+- **No Assumptions**: Don't assume user wants next step
+- **Explicit Consent**: Always ask for input
+
+### Example Pattern
+
+```
+AI: "Tell me about your dietary preferences."
+User: [provides information]
+AI: "Thank you. Now let's discuss your cooking habits."
+[Continue conversation]
+AI: **Menu Options**
+```
+
+## CSV Intelligence (Optional)
+
+### Data-Driven Behavior
+
+- Configuration in CSV files
+- Dynamic menu options
+- Variable substitution
+- Conditional logic
+
+### Example Structure
+
+```csv
+variable,type,value,description
+cooking_frequency,choice,"daily|weekly|occasionally","How often user cooks"
+meal_type,multi,"breakfast|lunch|dinner|snacks","Types of meals to plan"
+```
+
+## Best Practices
+
+### File Size Limits
+
+- **Step Files**: Keep focused and reasonably sized (5-10KB typical)
+- **Templates**: Keep focused and reusable
+- **Workflow File**: Keep lean, no implementation details
+
+### Sequential Enforcement
+
+- **Numbered Steps**: Use sequential numbering (1, 2, 3...)
+- **No Skipping**: Each step must complete
+- **State Updates**: Mark completion in frontmatter
+
+### Error Prevention
+
+- **Path Variables**: Use frontmatter variables, never hardcode
+- **Complete Loading**: Always read entire file before execution
+- **Menu Halts**: Never proceed without 'C' selection
+
+## Migration from XML
+
+### Advantages
+
+- **No Dependencies**: Pure markdown, no XML parsing
+- **Human Readable**: Files are self-documenting
+- **Git Friendly**: Clean diffs and merges
+- **Flexible**: Easier to modify and extend
+
+### Key Differences
+
+| XML Workflows     | Standalone Workflows    |
+| ----------------- | ----------------------- |
+| Single large file | Multiple micro-files    |
+| Complex structure | Simple sequential steps |
+| Parser required   | Any markdown viewer     |
+| Rigid format      | Flexible organization   |
+
+## Implementation Notes
+
+### Critical Rules
+
+- **NEVER** load multiple step files
+- **ALWAYS** read complete step file first
+- **NEVER** skip steps or optimize
+- **ALWAYS** update frontmatter of the output file when a step is complete
+- **NEVER** proceed without user consent
+
+### Success Metrics
+
+- Documents created correctly
+- All steps completed sequentially
+- User satisfied with collaborative process
+- Clean, maintainable file structure
+
+This architecture ensures disciplined, predictable workflow execution while maintaining flexibility for different use cases.

package/src/modules/xmb/docs/workflows/common-workflow-tools.csv

@@ -0,0 +1,19 @@
+propose,type,tool_name,description,url,requires_install
+always,workflow,party-mode,"Enables collaborative idea generation by managing turn-taking, summarizing contributions, and synthesizing ideas from multiple AI personas in structured conversation sessions about workflow steps or work in progress.",{project-root}/{xiaoma_folder}/core/workflows/party-mode/workflow.md,no
+always,task,advanced-elicitation,"Employs diverse elicitation strategies such as Socratic questioning, role-playing, and counterfactual analysis to critically evaluate and enhance LLM outputs, forcing assessment from multiple perspectives and techniques.",{project-root}/{xiaoma_folder}/core/tasks/advanced-elicitation.xml,no
+always,task,brainstorming,"Facilitates idea generation by prompting users with targeted questions, encouraging divergent thinking, and synthesizing concepts into actionable insights through collaborative creative exploration.",{project-root}/{xiaoma_folder}/core/tasks/brainstorming.xml,no
+always,llm-tool-feature,web-browsing,"Provides LLM with capabilities to perform real-time web searches, extract relevant data, and incorporate current information into responses when up-to-date information is required beyond training knowledge.",,no
+always,llm-tool-feature,file-io,"Enables LLM to manage file operations such as creating, reading, updating, and deleting files, facilitating seamless data handling, storage, and document management within user environments.",,no
+always,llm-tool-feature,sub-agents,"Allows LLM to create and manage specialized sub-agents that handle specific tasks or modules within larger workflows, improving efficiency through parallel processing and modular task delegation.",,no
+always,llm-tool-feature,sub-processes,"Enables LLM to initiate and manage subprocesses that operate independently, allowing for parallel processing of complex tasks and improved resource utilization during long-running operations.",,no
+always,tool-memory,sidecar-file,"Creates a persistent history file that gets written during workflow execution and loaded on future runs, enabling continuity through session-to-session state management. Used for agent or workflow initialization with previous session context, learning from past interactions, and maintaining progress across multiple executions.",,no
+example,tool-memory,vector-database,"Stores and retrieves semantic information through embeddings for intelligent memory access, enabling workflows to find relevant past experiences, patterns, or context based on meaning rather than exact matches. Useful for complex learning systems, pattern recognition, and semantic search across workflow history.",https://github.com/modelcontextprotocol/servers/tree/main/src/rag-agent,yes
+example,mcp,context-7,"A curated knowledge base of API documentation and third-party tool references, enabling LLM to access accurate and current information for integration and development tasks when specific technical documentation is needed.",https://github.com/modelcontextprotocol/servers/tree/main/src/context-7,yes
+example,mcp,playwright,"Provides capabilities for LLM to perform web browser automation including navigation, form submission, data extraction, and testing actions on web pages, facilitating automated web interactions and quality assurance.",https://github.com/modelcontextprotocol/servers/tree/main/src/playwright,yes
+example,workflow,security-auditor,"Analyzes workflows and code for security vulnerabilities, compliance issues, and best practices violations, providing detailed security assessments and remediation recommendations for production-ready systems.",,no
+example,task,code-review,"Performs systematic code analysis with peer review perspectives, identifying bugs, performance issues, style violations, and architectural problems through adversarial review techniques.",,no
+example,mcp,git-integration,"Enables direct Git repository operations including commits, branches, merges, and history analysis, allowing workflows to interact with version control systems for code management and collaboration.",https://github.com/modelcontextprotocol/servers/tree/main/src/git,yes
+example,mcp,database-connector,"Provides direct database connectivity for querying, updating, and managing data across multiple database types, enabling workflows to interact with structured data sources and perform data-driven operations.",https://github.com/modelcontextprotocol/servers/tree/main/src/postgres,yes
+example,task,api-testing,"Automated API endpoint testing with request/response validation, authentication handling, and comprehensive reporting for REST, GraphQL, and other API types through systematic test generation.",,no
+example,workflow,deployment-manager,"Orchestrates application deployment across multiple environments with rollback capabilities, health checks, and automated release pipelines for continuous integration and delivery workflows.",,no
+example,task,data-validator,"Validates data quality, schema compliance, and business rules through comprehensive data profiling with detailed reporting and anomaly detection for data-intensive workflows.",,no

package/src/modules/xmb/docs/workflows/csv-data-file-standards.md

@@ -0,0 +1,206 @@
+# CSV Data File Standards for XIAOMA Workflows
+
+## Purpose and Usage
+
+CSV data files in XIAOMA workflows serve specific purposes for different workflow types:
+
+**For Agents:** Provide structured data that agents need to reference but cannot realistically generate (such as specific configurations, domain-specific data, or structured knowledge bases).
+
+**For Expert Agents:** Supply specialized knowledge bases, reference data, or persistent information that the expert agent needs to access consistently across sessions.
+
+**For Workflows:** Include reference data, configuration parameters, or structured inputs that guide workflow execution and decision-making.
+
+**Key Principle:** CSV files should contain data that is essential, structured, and not easily generated by LLMs during execution.
+
+## Intent-Based Design Principle
+
+**Core Philosophy:** The closer workflows stay to **intent** rather than **prescriptive** instructions, the more creative and adaptive the LLM experience becomes.
+
+**CSV Enables Intent-Based Design:**
+
+- **Instead of:** Hardcoded scripts with exact phrases LLM must say
+- **CSV Provides:** Clear goals and patterns that LLM adapts creatively to context
+- **Result:** Natural, contextual conversations rather than rigid scripts
+
+**Example - Advanced Elicitation:**
+
+- **Prescriptive Alternative:** 50 separate files with exact conversation scripts
+- **Intent-Based Reality:** One CSV row with method goal + pattern → LLM adapts to user
+- **Benefit:** Same method works differently for different users while maintaining essence
+
+**Intent vs Prescriptive Spectrum:**
+
+- **Highly Prescriptive:** "Say exactly: 'Based on my analysis, I recommend...'"
+- **Balanced Intent:** "Help the user understand the implications using your professional judgment"
+- **CSV Goal:** Provide just enough guidance to enable creative, context-aware execution
+
+## Primary Use Cases
+
+### 1. Knowledge Base Indexing (Document Lookup Optimization)
+
+**Problem:** Large knowledge bases with hundreds of documents cause context blowup and missed details when LLMs try to process them all.
+
+**CSV Solution:** Create a knowledge base index with:
+
+- **Column 1:** Keywords and topics
+- **Column 2:** Document file path/location
+- **Column 3:** Section or line number where relevant content starts
+- **Column 4:** Content type or summary (optional)
+
+**Result:** Transform from context-blowing document loads to surgical precision lookups, creating agents with near-infinite knowledge bases while maintaining optimal context usage.
+
+### 2. Workflow Sequence Optimization
+
+**Problem:** Complex workflows (e.g., game development) with hundreds of potential steps for different scenarios become unwieldy and context-heavy.
+
+**CSV Solution:** Create a workflow routing table:
+
+- **Column 1:** Scenario type (e.g., "2D Platformer", "RPG", "Puzzle Game")
+- **Column 2:** Required step sequence (e.g., "step-01,step-03,step-07,step-12")
+- **Column 3:** Document sections to include
+- **Column 4:** Specialized parameters or configurations
+
+**Result:** Step 1 determines user needs, finds closest match in CSV, confirms with user, then follows optimized sequence - truly optimal for context usage.
+
+### 3. Method Registry (Dynamic Technique Selection)
+
+**Problem:** Tasks need to select optimal techniques from dozens of options based on context, without hardcoding selection logic.
+
+**CSV Solution:** Create a method registry with:
+
+- **Column 1:** Category (collaboration, advanced, technical, creative, etc.)
+- **Column 2:** Method name and rich description
+- **Column 3:** Execution pattern or flow guide (e.g., "analysis → insights → action")
+- **Column 4:** Complexity level or use case indicators
+
+**Example:** Advanced Elicitation task analyzes content context, selects 5 best-matched methods from 50 options, then executes dynamically using CSV descriptions.
+
+**Result:** Smart, context-aware technique selection without hardcoded logic - infinitely extensible method libraries.
+
+### 4. Configuration Management
+
+**Problem:** Complex systems with many configuration options that vary by use case.
+
+**CSV Solution:** Configuration lookup tables mapping scenarios to specific parameter sets.
+
+## What NOT to Include in CSV Files
+
+**Avoid Web-Searchable Data:** Do not include information that LLMs can readily access through web search or that exists in their training data, such as:
+
+- Common programming syntax or standard library functions
+- General knowledge about widely used technologies
+- Historical facts or commonly available information
+- Basic terminology or standard definitions
+
+**Include Specialized Data:** Focus on data that is:
+
+- Specific to your project or domain
+- Not readily available through web search
+- Essential for consistent workflow execution
+- Too voluminous for LLM context windows
+
+## CSV Data File Standards
+
+### 1. Purpose Validation
+
+- **Essential Data Only:** CSV must contain data that cannot be reasonably generated by LLMs
+- **Domain Specific:** Data should be specific to the workflow's domain or purpose
+- **Consistent Usage:** All columns and data must be referenced and used somewhere in the workflow
+- **No Redundancy:** Avoid data that duplicates functionality already available to LLMs
+
+### 2. Structural Standards
+
+- **Valid CSV Format:** Proper comma-separated values with quoted fields where needed
+- **Consistent Columns:** All rows must have the same number of columns
+- **No Missing Data:** Empty values should be explicitly marked (e.g., "", "N/A", or NULL)
+- **Header Row:** First row must contain clear, descriptive column headers
+- **Proper Encoding:** UTF-8 encoding required for special characters
+
+### 3. Content Standards
+
+- **No LLM-Generated Content:** Avoid data that LLMs can easily generate (e.g., generic phrases, common knowledge)
+- **Specific and Concrete:** Use specific values rather than vague descriptions
+- **Verifiable Data:** Data should be factual and verifiable when possible
+- **Consistent Formatting:** Date formats, numbers, and text should follow consistent patterns
+
+### 4. Column Standards
+
+- **Clear Headers:** Column names must be descriptive and self-explanatory
+- **Consistent Data Types:** Each column should contain consistent data types
+- **No Unused Columns:** Every column must be referenced and used in the workflow
+- **Appropriate Width:** Columns should be reasonably narrow and focused
+
+### 5. File Size Standards
+
+- **Efficient Structure:** CSV files should be as small as possible while maintaining functionality
+- **No Redundant Rows:** Avoid duplicate or nearly identical rows
+- **Compressed Data:** Use efficient data representation (e.g., codes instead of full descriptions)
+- **Maximum Size:** Individual CSV files should not exceed 1MB unless absolutely necessary
+
+### 6. Documentation Standards
+
+- **Documentation Required:** Each CSV file should have documentation explaining its purpose
+- **Column Descriptions:** Each column must be documented with its usage and format
+- **Data Sources:** Source of data should be documented when applicable
+- **Update Procedures:** Process for updating CSV data should be documented
+
+### 7. Integration Standards
+
+- **File References:** CSV files must be properly referenced in workflow configuration
+- **Access Patterns:** Workflow must clearly define how and when CSV data is accessed
+- **Error Handling:** Workflow must handle cases where CSV files are missing or corrupted
+- **Version Control:** CSV files should be versioned when changes occur
+
+### 8. Quality Assurance
+
+- **Data Validation:** CSV data should be validated for correctness and completeness
+- **Format Consistency:** Consistent formatting across all rows and columns
+- **No Ambiguity:** Data entries should be clear and unambiguous
+- **Regular Review:** CSV content should be reviewed periodically for relevance
+
+### 9. Security Considerations
+
+- **No Sensitive Data:** Avoid including sensitive, personal, or confidential information
+- **Data Sanitization:** CSV data should be sanitized for security issues
+- **Access Control:** Access to CSV files should be controlled when necessary
+- **Audit Trail:** Changes to CSV files should be logged when appropriate
+
+### 10. Performance Standards
+
+- **Fast Loading:** CSV files must load quickly within workflow execution
+- **Memory Efficient:** Structure should minimize memory usage during processing
+- **Optimized Queries:** If data lookup is needed, optimize for efficient access
+- **Caching Strategy**: Consider whether data can be cached for performance
+
+## Implementation Guidelines
+
+When creating CSV data files for XIAOMA workflows:
+
+1. **Start with Purpose:** Clearly define why CSV is needed instead of LLM generation
+2. **Design Structure:** Plan columns and data types before creating the file
+3. **Test Integration:** Ensure workflow properly accesses and uses CSV data
+4. **Document Thoroughly:** Provide complete documentation for future maintenance
+5. **Validate Quality:** Check data quality, format consistency, and integration
+6. **Monitor Usage:** Track how CSV data is used and optimize as needed
+
+## Common Anti-Patterns to Avoid
+
+- **Generic Phrases:** CSV files containing common phrases or LLM-generated content
+- **Redundant Data:** Duplicating information easily available to LLMs
+- **Overly Complex:** Unnecessarily complex CSV structures when simple data suffices
+- **Unused Columns:** Columns that are defined but never referenced in workflows
+- **Poor Formatting:** Inconsistent data formats, missing values, or structural issues
+- **No Documentation:** CSV files without clear purpose or usage documentation
+
+## Validation Checklist
+
+For each CSV file, verify:
+
+- [ ] Purpose is essential and cannot be replaced by LLM generation
+- [ ] All columns are used in the workflow
+- [ ] Data is properly formatted and consistent
+- [ ] File is efficiently sized and structured
+- [ ] Documentation is complete and clear
+- [ ] Integration with workflow is tested and working
+- [ ] Security considerations are addressed
+- [ ] Performance requirements are met

package/src/modules/xmb/docs/workflows/index.md

@@ -0,0 +1,45 @@
+# XIAOMA Workflows Documentation
+
+Welcome to the XIAOMA Workflows documentation - a modern system for creating structured, collaborative workflows optimized for AI execution.
+
+## 📚 Core Documentation
+
+### [Terms](terms.md)
+
+Essential terminology and concepts for understanding XIAOMA workflows.
+
+### [Architecture & Execution Model](architecture.md)
+
+The micro-file architecture, JIT step loading, state management, and collaboration patterns that make XIAOMA workflows optimal for AI execution.
+
+### [Writing Workflows](./writing-workflows.md)
+
+Complete guide to creating workflows: workflow.md control files, step files, CSV data integration, and frontmatter design.
+
+### [Step Files & Dialog Patterns](./step-files.md)
+
+Crafting effective step files: structure, execution rules, prescriptive vs intent-based dialog, and validation patterns.
+
+### [Templates & Content Generation](./templates.md)
+
+Creating append-only templates, frontmatter design, conditional content, and dynamic content generation strategies.
+
+### [Workflow Patterns](./patterns.md)
+
+Common workflow types: linear, conditional, protocol integration, multi-agent workflows, and real-world examples.
+
+### [Migration Guide](./migration.md)
+
+Converting from XML-heavy workflows to the new pure markdown format, with before/after examples and checklist.
+
+### [Best Practices & Reference](./best-practices.md)
+
+Critical rules, anti-patterns, performance optimization, debugging, quick reference templates, and troubleshooting.
+
+## 🚀 Quick Start
+
+XIAOMA workflows are pure markdown, self-contained systems that guide collaborative processes through structured step files where the AI acts as a facilitator working with humans.
+
+---
+
+_This documentation covers the next generation of XIAOMA workflows - designed from the ground up for optimal AI-human collaboration._