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

package/src/modules/xmb/workflows-legacy/create-module/module-structure.md

@@ -0,0 +1,400 @@
+# XIAOMA Module Structure Guide
+
+## What is a Module?
+
+A XIAOMA module is a self-contained package of agents, workflows, tasks, and resources that work together to provide specialized functionality. Think of it as an expansion pack for the XIAOMA Method.
+
+## Module Architecture
+
+### Core Structure
+
+```
+# SOURCE MODULE (in XIAOMA-CLI project)
+src/modules/{module-code}/
+├── agents/                        # Agent definitions (.agent.yaml)
+├── workflows/                     # Workflow folders
+├── tasks/                         # Task files
+├── tools/                         # Tool files
+├── templates/                     # Shared templates
+├── data/                          # Static data
+├── _module-installer/             # Installation configuration
+│   ├── install-config.yaml  # Installation questions & config
+│   ├── installer.js              # Optional custom install logic
+│   └── assets/                   # Files to copy during install
+└── README.md                      # Module documentation
+
+# INSTALLED MODULE (in target project)
+{project-root}/{xiaoma_folder}/{module-code}/
+├── agents/                        # Compiled agent files (.md)
+├── workflows/                     # Workflow instances
+├── tasks/                         # Task files
+├── tools/                         # Tool files
+├── templates/                     # Templates
+├── data/                          # Module data
+├── config.yaml                    # Generated from install-config.yaml
+└── README.md                      # Module documentation
+```
+
+## Module Types by Complexity
+
+### Simple Module (1-2 agents, 2-3 workflows)
+
+Perfect for focused, single-purpose tools.
+
+**Example: Code Review Module**
+
+- 1 Reviewer Agent
+- 2 Workflows: quick-review, deep-review
+- Clear, narrow scope
+
+### Standard Module (3-5 agents, 5-10 workflows)
+
+Comprehensive solution for a domain.
+
+**Example: Project Management Module**
+
+- PM Agent, Scrum Master Agent, Analyst Agent
+- Workflows: sprint-planning, retrospective, roadmap, user-stories
+- Integrated component ecosystem
+
+### Complex Module (5+ agents, 10+ workflows)
+
+Full platform or framework.
+
+**Example: RPG Toolkit Module**
+
+- DM Agent, NPC Agent, Monster Agent, Loot Agent, Map Agent
+- 15+ workflows for every aspect of game management
+- Multiple interconnected systems
+
+## Module Naming Conventions
+
+### Module Code (kebab-case)
+
+- `data-viz` - Data Visualization
+- `team-collab` - Team Collaboration
+- `rpg-toolkit` - RPG Toolkit
+- `legal-assist` - Legal Assistant
+
+### Module Name (Title Case)
+
+- "Data Visualization Suite"
+- "Team Collaboration Platform"
+- "RPG Game Master Toolkit"
+- "Legal Document Assistant"
+
+## Component Guidelines
+
+### Agents per Module
+
+**Recommended Distribution:**
+
+- **Primary Agent (1)**: The main interface/orchestrator
+- **Specialist Agents (2-4)**: Domain-specific experts
+- **Utility Agents (0-2)**: Helper/support functions
+
+**Anti-patterns to Avoid:**
+
+- Too many overlapping agents
+- Agents that could be combined
+- Agents without clear purpose
+
+### Workflows per Module
+
+**Categories:**
+
+- **Core Workflows (2-3)**: Essential functionality
+- **Feature Workflows (3-5)**: Specific capabilities
+- **Utility Workflows (2-3)**: Supporting operations
+- **Admin Workflows (0-2)**: Maintenance/config
+
+**Workflow Complexity Guide:**
+
+- Simple: 3-5 steps, single output
+- Standard: 5-10 steps, multiple outputs
+- Complex: 10+ steps, conditional logic, sub-workflows
+
+### Tasks per Module
+
+Tasks should be used for:
+
+- Single-operation utilities
+- Shared subroutines
+- Quick actions that don't warrant workflows
+
+## Module Dependencies
+
+### Internal Dependencies
+
+- Agents can reference module workflows
+- Workflows can invoke module tasks
+- Tasks can use module templates
+
+### External Dependencies
+
+- Reference other modules via full paths
+- Declare dependencies in config.yaml
+- Version compatibility notes
+
+### Workflow Vendoring (Advanced)
+
+For modules that need workflows from other modules but want to remain standalone, use **workflow vendoring**:
+
+**In Agent YAML:**
+
+```yaml
+menu:
+  - trigger: command-name
+    workflow: '{project-root}/{xiaoma_folder}/SOURCE_MODULE/workflows/path/workflow.yaml'
+    workflow-install: '{project-root}/{xiaoma_folder}/THIS_MODULE/workflows/vendored/workflow.yaml'
+    description: 'Command description'
+```
+
+**What Happens:**
+
+- During installation, workflows are copied from `workflow` to `workflow-install` location
+- Vendored workflows get `config_source` updated to reference this module's config
+- Compiled agent only references the `workflow-install` path
+- Module becomes fully standalone - no source module dependency required
+
+**Use Cases:**
+
+- Specialized modules that reuse common workflows with different configs
+- Domain-specific adaptations (e.g., game dev using standard dev workflows)
+- Testing workflows in isolation
+
+**Benefits:**
+
+- Module independence (no forced dependencies)
+- Clean namespace (workflows in your module)
+- Config isolation (use your module's settings)
+- Customization ready (modify vendored workflows freely)
+
+## Installation Infrastructure
+
+### Required: module-installer/install-config.yaml
+
+This file defines both installation questions AND static configuration values:
+
+```yaml
+# Module metadata
+code: module-code
+name: 'Module Name'
+default_selected: false
+
+# Welcome message during installation
+prompt:
+  - 'Welcome to Module Name!'
+  - 'Brief description here'
+
+# Core values automatically inherited from installer:
+## user_name
+## communication_language
+## document_output_language
+## output_folder
+
+# INTERACTIVE fields (ask user during install)
+output_location:
+  prompt: 'Where should module outputs be saved?'
+  default: 'output/module-code'
+  result: '{project-root}/{value}'
+
+feature_level:
+  prompt: 'Which feature set?'
+  default: 'standard'
+  result: '{value}'
+  single-select:
+    - value: 'basic'
+      label: 'Basic - Core features only'
+    - value: 'standard'
+      label: 'Standard - Recommended features'
+    - value: 'advanced'
+      label: 'Advanced - All features'
+
+# STATIC fields (no prompt, just hardcoded values)
+module_version:
+  result: '1.0.0'
+
+data_path:
+  result: '{project-root}/{xiaoma_folder}/module-code/data'
+```
+
+**Key Points:**
+
+- File is named `install-config.yaml` (NOT install-config.yaml)
+- Supports both interactive prompts and static values
+- `result` field uses placeholders: `{value}`, `{project-root}`, `{directory_name}`
+- Installer generates final `config.yaml` from this template
+
+### Optional: module-installer/installer.js
+
+For complex installations requiring custom logic:
+
+```javascript
+/**
+ * @param {Object} options - Installation options
+ * @param {string} options.projectRoot - Target project directory
+ * @param {Object} options.config - Config from install-config.yaml
+ * @param {Array} options.installedIDEs - IDEs being configured
+ * @param {Object} options.logger - Logger (log, warn, error)
+ * @returns {boolean} - true if successful
+ */
+async function install(options) {
+  // Custom installation logic here
+  // - Database setup
+  // - API configuration
+  // - External downloads
+  // - Integration setup
+
+  return true;
+}
+
+module.exports = { install };
+```
+
+### Optional: module-installer/assets/
+
+Files to copy during installation:
+
+- External configurations
+- Documentation
+- Example files
+- Integration scripts
+
+## Module Lifecycle
+
+### Development Phases
+
+1. **Planning Phase**
+   - Define scope and purpose
+   - Identify components
+   - Design architecture
+
+2. **Scaffolding Phase**
+   - Create directory structure
+   - Generate configurations
+   - Setup installer
+
+3. **Building Phase**
+   - Create agents incrementally
+   - Build workflows progressively
+   - Add tasks as needed
+
+4. **Testing Phase**
+   - Test individual components
+   - Verify integration
+   - Validate installation
+
+5. **Deployment Phase**
+   - Package module
+   - Document usage
+   - Distribute/share
+
+## Best Practices
+
+### Module Cohesion
+
+- All components should relate to module theme
+- Clear boundaries between modules
+- No feature creep
+
+### Progressive Enhancement
+
+- Start with MVP (1 agent, 2 workflows)
+- Add components based on usage
+- Refactor as patterns emerge
+
+### Documentation Standards
+
+- Every module needs README.md
+- Each agent needs purpose statement
+- Workflows need clear descriptions
+- Include examples and quickstart
+
+### Naming Consistency
+
+- Use module code prefix for uniqueness
+- Consistent naming patterns within module
+- Clear, descriptive names
+
+## Example Modules
+
+### Example 1: Personal Productivity
+
+```
+productivity/
+├── agents/
+│   ├── task-manager.md      # GTD methodology
+│   └── focus-coach.md        # Pomodoro timer
+├── workflows/
+│   ├── daily-planning/       # Morning routine
+│   ├── weekly-review/        # Week retrospective
+│   └── project-setup/        # New project init
+└── config.yaml
+```
+
+### Example 2: Content Creation
+
+```
+content/
+├── agents/
+│   ├── writer.md            # Blog/article writer
+│   ├── editor.md            # Copy editor
+│   └── seo-optimizer.md     # SEO specialist
+├── workflows/
+│   ├── blog-post/           # Full blog creation
+│   ├── social-media/        # Social content
+│   ├── email-campaign/      # Email sequence
+│   └── content-calendar/    # Planning
+└── templates/
+    ├── blog-template.md
+    └── email-template.md
+```
+
+### Example 3: DevOps Automation
+
+```
+devops/
+├── agents/
+│   ├── deploy-master.md     # Deployment orchestrator
+│   ├── monitor.md           # System monitoring
+│   ├── incident-responder.md # Incident management
+│   └── infra-architect.md   # Infrastructure design
+├── workflows/
+│   ├── ci-cd-setup/         # Pipeline creation
+│   ├── deploy-app/          # Application deployment
+│   ├── rollback/            # Emergency rollback
+│   ├── health-check/        # System verification
+│   └── incident-response/   # Incident handling
+├── tasks/
+│   ├── check-status.md      # Quick status check
+│   └── notify-team.md       # Team notifications
+└── data/
+    └── runbooks/            # Operational guides
+```
+
+## Module Evolution Pattern
+
+```
+Simple Module → Standard Module → Complex Module → Module Suite
+     (MVP)          (Enhanced)        (Complete)      (Ecosystem)
+```
+
+## Common Pitfalls
+
+1. **Over-engineering**: Starting too complex
+2. **Under-planning**: No clear architecture
+3. **Poor boundaries**: Module does too much
+4. **Weak integration**: Components don't work together
+5. **Missing docs**: No clear usage guide
+
+## Success Metrics
+
+A well-designed module has:
+
+- ✅ Clear, focused purpose
+- ✅ Cohesive components
+- ✅ Smooth installation
+- ✅ Comprehensive docs
+- ✅ Room for growth
+- ✅ Happy users!

package/src/modules/xmb/workflows-legacy/create-module/workflow.yaml

@@ -0,0 +1,52 @@
+# Build Module Workflow Configuration
+name: create-module
+description: "Interactive workflow to build complete XIAOMA modules with agents, workflows, tasks, and installation infrastructure"
+author: "XiaoMa"
+
+# Critical variables load from config_source
+config_source: "{project-root}/{xiaoma_folder}/xmb/config.yaml"
+custom_module_location: "{config_source}:custom_module_location"
+communication_language: "{config_source}:communication_language"
+user_name: "{config_source}:user_name"
+
+# Reference guides for module building
+module_structure_guide: "{installed_path}/module-structure.md"
+installer_templates: "{installed_path}/installer-templates/"
+
+# Use existing build workflows
+agent_builder: "{project-root}/{xiaoma_folder}/xmb/workflows/create-agent/workflow.yaml"
+workflow_builder: "{project-root}/{xiaoma_folder}/xmb/workflows/create-workflow/workflow.yaml"
+brainstorming_workflow: "{project-root}/{xiaoma_folder}/core/workflows/brainstorming/workflow.yaml"
+brainstorming_context: "{installed_path}/brainstorm-context.md"
+
+# Reference examples - for learning patterns
+xmc_module_dir: "{project-root}/{xiaoma_folder}/xmc/"
+cis_module_dir: "{project-root}/{xiaoma_folder}/cis/"
+existing_agents_dir: "{project-root}/{xiaoma_folder}/*/agents/"
+existing_workflows_dir: "{project-root}/{xiaoma_folder}/*/workflows/"
+
+# Optional user inputs - discovered if they exist
+input_file_patterns:
+  module_brief:
+    description: "Module brief with vision and requirements (optional)"
+    whole: "{output_folder}/module-brief-*.md"
+    load_strategy: "FULL_LOAD"
+  brainstorming:
+    description: "Brainstorming session outputs (optional)"
+    whole: "{output_folder}/brainstorming-*.md"
+    load_strategy: "FULL_LOAD"
+
+# Module path and component files
+installed_path: "{project-root}/{xiaoma_folder}/xmb/workflows/create-module"
+template: false # This is an interactive scaffolding workflow
+instructions: "{installed_path}/instructions.md"
+validation: "{installed_path}/checklist.md"
+
+# Output configuration - creates entire module structure
+# Save to custom_module_location/{{module_code}}
+installer_output_folder: "{custom_module_location}/{{module_code}}"
+
+standalone: true
+
+# Web bundle configuration
+web_bundle: false # XMB workflows run locally in XIAOMA-CLI project

package/src/modules/xmb/workflows-legacy/edit-module/README.md

@@ -0,0 +1,187 @@
+# Edit Module Workflow
+
+Interactive workflow for editing existing XIAOMA modules, including structure, agents, workflows, configuration, and documentation.
+
+## Purpose
+
+This workflow helps you improve and maintain XIAOMA modules by:
+
+- Analyzing module structure against best practices
+- Managing agents and workflows within the module
+- Updating configuration and documentation
+- Ensuring cross-module integration works correctly
+- Maintaining installer configuration (for source modules)
+
+## When to Use
+
+Use this workflow when you need to:
+
+- Add new agents or workflows to a module
+- Update module configuration
+- Improve module documentation
+- Reorganize module structure
+- Set up cross-module workflow sharing
+- Fix issues in module organization
+- Update installer configuration
+
+## What You'll Need
+
+- Path to the module directory you want to edit
+- Understanding of what changes you want to make
+- Access to module documentation (loaded automatically)
+
+## Workflow Steps
+
+1. **Load and analyze target module** - Provide path to module directory
+2. **Analyze against best practices** - Automatic audit of module structure
+3. **Select editing focus** - Choose what aspect to edit
+4. **Load relevant documentation and tools** - Auto-loads guides and workflows
+5. **Perform edits** - Review and approve changes iteratively
+6. **Validate all changes** - Comprehensive validation checklist
+7. **Generate change summary** - Summary of improvements made
+
+## Editing Options
+
+The workflow provides 12 focused editing options:
+
+1. **Fix critical issues** - Address missing files, broken references
+2. **Update module config** - Edit config.yaml fields
+3. **Manage agents** - Add, edit, or remove agents
+4. **Manage workflows** - Add, edit, or remove workflows
+5. **Update documentation** - Improve README files and guides
+6. **Reorganize structure** - Fix directory organization
+7. **Add new agent** - Create and integrate new agent
+8. **Add new workflow** - Create and integrate new workflow
+9. **Update installer** - Modify installer configuration (source only)
+10. **Cross-module integration** - Set up workflow sharing with other modules
+11. **Remove deprecated items** - Delete unused agents, workflows, or files
+12. **Full module review** - Comprehensive analysis and improvements
+
+## Integration with Other Workflows
+
+This workflow integrates with:
+
+- **edit-agent** - For editing individual agents
+- **edit-workflow** - For editing individual workflows
+- **create-agent** - For adding new agents
+- **create-workflow** - For adding new workflows
+
+When you select options to manage agents or workflows, the appropriate specialized workflow is invoked automatically.
+
+## Module Structure
+
+A proper XIAOMA module has:
+
+```
+module-code/
+├── agents/              # Agent definitions
+│   └── *.agent.yaml
+├── workflows/           # Workflow definitions
+│   └── workflow-name/
+│       ├── workflow.yaml
+│       ├── instructions.md
+│       ├── checklist.md
+│       └── README.md
+├── config.yaml          # Module configuration
+└── README.md           # Module documentation
+```
+
+## Standard Module Config
+
+Every module config.yaml should have:
+
+```yaml
+module_name: 'Full Module Name'
+module_code: 'xyz'
+user_name: 'User Name'
+communication_language: 'english'
+output_folder: 'path/to/output'
+```
+
+Optional fields may be added for module-specific needs.
+
+## Cross-Module Integration
+
+Modules can share workflows:
+
+```yaml
+# In agent menu item:
+workflow: '{project-root}/{xiaoma_folder}/other-module/workflows/shared-workflow/workflow.yaml'
+```
+
+Common patterns:
+
+- XMC uses CIS brainstorming workflows
+- All modules can use core workflows
+- Modules can invoke each other's workflows
+
+## Output
+
+The workflow modifies module files in place, including:
+
+- config.yaml
+- Agent files
+- Workflow files
+- README and documentation files
+- Directory structure (if reorganizing)
+
+Changes are reviewed and approved by you before being applied.
+
+## Best Practices
+
+- **Start with analysis** - Let the workflow audit your module first
+- **Use specialized workflows** - Let edit-agent and edit-workflow handle detailed edits
+- **Update documentation** - Keep README files current with changes
+- **Validate thoroughly** - Use the validation step to catch structural issues
+- **Test after editing** - Invoke agents and workflows to verify they work
+
+## Tips
+
+- For adding agents/workflows, use options 7-8 to create and integrate in one step
+- For quick config changes, use option 2 (update module config)
+- Cross-module integration (option 10) helps set up workflow sharing
+- Full module review (option 12) is great for inherited or legacy modules
+- The workflow handles path updates when you reorganize structure
+
+## Source vs Installed Modules
+
+**Source modules** (in src/modules/):
+
+- Have installer files in tools/cli/installers/
+- Can configure web bundles
+- Are the development source of truth
+
+**Installed modules** (in {xiaoma_folder}/):
+
+- Are deployed to target projects
+- Use config.yaml for user customization
+- Are compiled from source during installation
+
+This workflow works with both, but installer options only apply to source modules.
+
+## Example Usage
+
+```
+User: I want to add a new workflow to XMC for API design
+Workflow: Analyzes XMC → You choose option 8 (add new workflow)
+          → Invokes create-workflow → Creates workflow
+          → Integrates it into module → Updates README → Done
+```
+
+## Activation
+
+Invoke via XiaoMa Builder agent:
+
+```
+/xiaoma:xmb:agents:xiaoma-builder
+Then select: *edit-module
+```
+
+Or directly via workflow.xml with this workflow config.
+
+## Related Resources
+
+- **Module Structure Guide** - Comprehensive module architecture documentation
+- **XMC Module** - Example of full-featured module
+- **XMB Module** - Example of builder/tooling module
+- **CIS Module** - Example of workflow library module