@zeyue0329/xiaoma-cli 1.0.48 → 1.6.4

package/docs/ide-info/windsurf.md

@@ -0,0 +1,22 @@
+# XIAOMA Method - Windsurf Instructions
+
+## Activating Agents
+
+XIAOMA agents are installed as workflows in `.windsurf/workflows/`.
+
+### How to Use
+
+1. **Open Workflows**: Access via Windsurf menu or command palette
+2. **Select Workflow**: Choose the agent/task workflow
+3. **Execute**: Run to activate that agent persona
+
+### Workflow Types
+
+- **Agent workflows**: `{module}-{agent}.md` (auto_execution_mode: 3)
+- **Task workflows**: `task-{module}-{task}.md` (auto_execution_mode: 2)
+
+### Notes
+
+- Agents run with higher autonomy (mode 3)
+- Tasks run with guided execution (mode 2)
+- Workflows persist for the session

package/docs/index.md

@@ -0,0 +1,60 @@
+---
+title: Welcome to the XiaoMa Method
+description: AI-driven development framework with specialized agents, guided workflows, and intelligent planning
+---
+
+The XiaoMa Method (**B**uild **M**ore **A**rchitect **D**reams) is an AI-driven development framework module within the XiaoMa Method Ecosystem that helps you build software through the whole process from ideation and planning all the way through agentic implementation. It provides specialized AI agents, guided workflows, and intelligent planning that adapts to your project's complexity, whether you're fixing a bug or building an enterprise platform.
+
+If you're comfortable working with AI coding assistants like Claude, Cursor, or GitHub Copilot, you're ready to get started.
+
+:::note[🚀 V6 is Here and We're Just Getting Started!]
+Skills Architecture, XiaoMa Builder v1, Dev Loop Automation, and so much more in the works. **[Check out the Roadmap →](/roadmap/)**
+:::
+
+## New Here? Start with a Tutorial
+
+The fastest way to understand XiaoMa is to try it.
+
+- **[Get Started with XiaoMa](./tutorials/getting-started.md)** — Install and understand how XiaoMa works
+- **[Workflow Map](./reference/workflow-map.md)** — Visual overview of BMM phases, workflows, and context management
+
+:::tip[Just Want to Dive In?]
+Install XiaoMa and use the `xiaoma-help` skill — it will guide you through everything based on your project and installed modules.
+:::
+
+## How to Use These Docs
+
+These docs are organized into four sections based on what you're trying to do:
+
+| Section           | Purpose                                                                                                    |
+| ----------------- | ---------------------------------------------------------------------------------------------------------- |
+| **Tutorials**     | Learning-oriented. Step-by-step guides that walk you through building something. Start here if you're new. |
+| **How-To Guides** | Task-oriented. Practical guides for solving specific problems. "How do I customize an agent?" lives here.  |
+| **Explanation**   | Understanding-oriented. Deep dives into concepts and architecture. Read when you want to know *why*.       |
+| **Reference**     | Information-oriented. Technical specifications for agents, workflows, and configuration.                   |
+
+## Extend and Customize
+
+Want to expand XiaoMa with your own agents, workflows, or modules? The **[XiaoMa Builder](https://xiaoma-builder-docs.xiaoma-cli.org/)** provides the framework and tools for creating custom extensions, whether you're adding new capabilities to XiaoMa or building entirely new modules from scratch.
+
+## What You'll Need
+
+XiaoMa works with any AI coding assistant that supports custom system prompts or project context. Popular options include:
+
+- **[Claude Code](https://code.claude.com)** — Anthropic's CLI tool (recommended)
+- **[Cursor](https://cursor.sh)** — AI-first code editor
+- **[Codex CLI](https://github.com/openai/codex)** — OpenAI's terminal coding agent
+
+You should be comfortable with basic software development concepts like version control, project structure, and agile workflows. No prior experience with XiaoMa-style agent systems is required—that's what these docs are for.
+
+## Join the Community
+
+Get help, share what you're building, or contribute to XiaoMa:
+
+- **[Discord](https://discord.gg/gk8jAdXWmj)** — Chat with other XiaoMa users, ask questions, share ideas
+- **[GitHub](https://github.com/xiaoma-code-org/XiaoMa-Cli)** — Source code, issues, and contributions
+- **[YouTube](https://www.youtube.com/@XiaoMaCode)** — Video tutorials and walkthroughs
+
+## Next Step
+
+Ready to dive in? **[Get Started with XiaoMa](./tutorials/getting-started.md)** and build your first project.

package/docs/installers-bundlers/ide-injections.md

@@ -0,0 +1,186 @@
+# IDE Content Injection Standard
+
+## Overview
+
+This document defines the standard for IDE-specific content injection in XIAOMA modules. Each IDE can inject its own specific content into XIAOMA templates during installation without polluting the source files with IDE-specific code. The installation process is interactive, allowing users to choose what IDE-specific features they want to install.
+
+## Architecture
+
+### 1. Injection Points
+
+Files that support IDE-specific content define injection points using HTML comments:
+
+```xml
+<!-- IDE-INJECT-POINT: unique-point-name -->
+```
+
+### 2. Module Structure
+
+Each module that needs IDE-specific content creates a sub-module folder:
+
+```
+src/modules/{module-name}/sub-modules/{ide-name}/
+  ├── injections.yaml    # Injection configuration
+  ├── sub-agents/        # IDE-specific subagents (if applicable)
+  └── config.yaml        # Other IDE-specific config
+```
+
+### 3. Injection Configuration Format
+
+The `injections.yaml` file defines what content to inject where:
+
+```yaml
+# injections.yaml structure
+injections:
+  - file: 'relative/path/to/file.md' # Path relative to installation root
+    point: 'injection-point-name' # Must match IDE-INJECT-POINT name
+    requires: 'subagent-name' # Which subagent must be selected (or "any")
+    content: | # Content to inject (preserves formatting)
+      <llm>
+        <i>Instructions specific to this IDE</i>
+      </llm>
+
+# Subagents available for installation
+subagents:
+  source: 'sub-agents' # Source folder relative to this config
+  target: '.claude/agents' # Claude's expected location (don't change)
+  files:
+    - 'agent1.md'
+    - 'agent2.md'
+```
+
+### 4. Interactive Installation Process
+
+For Claude Code specifically, the installer will:
+
+1. **Detect available subagents** from the module's `injections.yaml`
+2. **Ask the user** about subagent installation:
+   - Install all subagents (default)
+   - Select specific subagents
+   - Skip subagent installation
+3. **Ask installation location** (if subagents selected):
+   - Project level: `.claude/agents/`
+   - User level: `~/.claude/agents/`
+4. **Copy selected subagents** to the chosen location
+5. **Inject only relevant content** based on selected subagents
+
+Other IDEs can implement their own installation logic appropriate to their architecture.
+
+## Implementation
+
+### IDE Installer Responsibilities
+
+Each IDE installer (e.g., `claude-code.js`) must:
+
+1. **Check for sub-modules**: Look for `sub-modules/{ide-name}/` in each installed module
+2. **Load injection config**: Parse `injections.yaml` if present
+3. **Process injections**: Replace injection points with configured content
+4. **Copy additional files**: Handle subagents or other IDE-specific files
+
+### Example Implementation (Claude Code)
+
+```javascript
+async processModuleInjections(projectDir, xiaomaDir, options) {
+  for (const moduleName of options.selectedModules) {
+    const configPath = path.join(
+      xiaomaDir, 'src/modules', moduleName,
+      'sub-modules/claude-code/injections.yaml'
+    );
+
+    if (exists(configPath)) {
+      const config = yaml.load(configPath);
+
+      // Interactive: Ask user about subagent installation
+      const choices = await this.promptSubagentInstallation(config.subagents);
+
+      if (choices.install !== 'none') {
+        // Ask where to install
+        const location = await this.promptInstallLocation();
+
+        // Process injections based on selections
+        for (const injection of config.injections) {
+          if (this.shouldInject(injection, choices)) {
+            await this.injectContent(projectDir, injection, choices);
+          }
+        }
+
+        // Copy selected subagents
+        await this.copySelectedSubagents(projectDir, config.subagents, choices, location);
+      }
+    }
+  }
+}
+```
+
+## Benefits
+
+1. **Clean Source Files**: No IDE-specific conditionals in source
+2. **Modular**: Each IDE manages its own injections
+3. **Scalable**: Easy to add support for new IDEs
+4. **Maintainable**: IDE-specific content lives with IDE config
+5. **Flexible**: Different modules can inject different content
+
+## Adding Support for a New IDE
+
+1. Create sub-module folder: `src/modules/{module}/sub-modules/{new-ide}/`
+2. Add `injections.yaml` with IDE-specific content
+3. Update IDE installer to process injections using this standard
+4. Test installation with and without the IDE selected
+
+## Example: XMC Module with Claude Code
+
+### File Structure
+
+```
+src/modules/xmc/
+├── agents/pm.md                         # Has injection point
+├── templates/prd.md                     # Has multiple injection points
+└── sub-modules/
+    └── claude-code/
+        ├── injections.yaml              # Defines what to inject
+        └── sub-agents/                  # Claude Code specific subagents
+            ├── market-researcher.md
+            ├── requirements-analyst.md
+            └── ...
+```
+
+### Injection Point in pm.md
+
+```xml
+<agent>
+  <persona>...</persona>
+  <!-- IDE-INJECT-POINT: pm-agent-instructions -->
+  <cmds>...</cmds>
+</agent>
+```
+
+### Injection Configuration
+
+```yaml
+injections:
+  - file: '{xiaoma_folder}/xmc/agents/pm.md'
+    point: 'pm-agent-instructions'
+    requires: 'any' # Injected if ANY subagent is selected
+    content: |
+      <llm critical="true">
+        <i>Use 'market-researcher' subagent for analysis</i>
+      </llm>
+
+  - file: '{xiaoma_folder}/xmc/templates/prd.md'
+    point: 'prd-goals-context-delegation'
+    requires: 'market-researcher' # Only if this specific subagent selected
+    content: |
+      <i>DELEGATE: Use 'market-researcher' subagent...</i>
+```
+
+### Result After Installation
+
+```xml
+<agent>
+  <persona>...</persona>
+  <llm critical="true">
+    <i>Use 'market-researcher' subagent for analysis</i>
+  </llm>
+  <cmds>...</cmds>
+</agent>
+```

package/docs/installers-bundlers/installers-modules-platforms-reference.md

@@ -0,0 +1,379 @@
+# XIAOMA Installation & Module System Reference
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Quick Start](#quick-start)
+3. [Architecture](#architecture)
+4. [Modules](#modules)
+5. [Configuration System](#configuration-system)
+6. [Platform Integration](#platform-integration)
+7. [Development Guide](#development-guide)
+8. [Troubleshooting](#troubleshooting)
+
+## Overview
+
+XiaoMa Core is a modular AI agent framework with intelligent installation, platform-agnostic support, and configuration inheritance.
+
+### Key Features
+
+- **Modular Design**: Core + optional modules (BMB, BMM, CIS)
+- **Smart Installation**: Interactive configuration with dependency resolution
+- **Clean Architecture**: Centralized `{xiaoma_folder}` directory add to project, no source pollution with multiple folders added
+
+## Architecture
+
+### Directory Structure upon installation
+
+```
+project-root/
+├── {xiaoma_folder}/             # Centralized installation
+│   ├── _cfg/                  # Configuration
+│   │   ├── agents/            # Agent configs
+│   │   └── agent-manifest.csv # Agent manifest
+│   ├── core/                  # Core module
+│   │   ├── agents/
+│   │   ├── tasks/
+│   │   └── config.yaml
+│   ├── xmc/                   # XiaoMa Method module
+│   │   ├── agents/
+│   │   ├── tasks/
+│   │   ├── workflows/
+│   │   └── config.yaml
+│   └── cis/                   # Creative Innovation Studio
+│       └── ...
+└── .claude/                   # Platform-specific (example)
+    └── agents/
+```
+
+### Installation Flow
+
+1. **Detection**: Check existing installation
+2. **Selection**: Choose modules interactively or via CLI
+3. **Configuration**: Collect module-specific settings
+4. **Installation**: Compile Process and copy files
+5. **Generation**: Create config files with inheritance
+6. **Post-Install**: Run module installers
+7. **Manifest**: Track installed components
+
+### Key Exclusions
+
+- `_module-installer/` directories are never copied to destination
+- `localskip="true"` agents are filtered out
+- Source `config.yaml` templates are replaced with generated configs
+
+## Modules
+
+### Core Module (Required)
+
+Foundation framework with C.O.R.E. (Collaboration Optimized Reflection Engine)
+
+- **Components**: Base agents, activation system, advanced elicitation
+- **Config**: `user_name`, `communication_language`
+
+### XMC Module
+
+XiaoMa Method for software development workflows
+
+- **Components**: PM agent, dev tasks, PRD templates, story generation
+- **Config**: `project_name`, `tech_docs`, `output_folder`, `story_location`
+- **Dependencies**: Core
+
+### CIS Module
+
+Creative Innovation Studio for design workflows
+
+- **Components**: Design agents, creative tasks
+- **Config**: `output_folder`, design preferences
+- **Dependencies**: Core
+
+### Module Structure
+
+```
+src/modules/{module}/
+├── _module-installer/       # Not copied to destination
+│   ├── installer.js        # Post-install logic
+│   └── install-config.yaml
+├── agents/
+├── tasks/
+├── templates/
+└── sub-modules/            # Platform-specific content
+    └── {platform}/
+        ├── injections.yaml
+        └── sub-agents/
+```
+
+## Configuration System
+
+### Collection Process
+
+Modules define prompts in `install-config.yaml`:
+
+```yaml
+project_name:
+  prompt: 'Project title?'
+  default: 'My Project'
+  result: '{value}'
+
+output_folder:
+  prompt: 'Output location?'
+  default: 'docs'
+  result: '{project-root}/{value}'
+
+tools:
+  prompt: 'Select tools:'
+  multi-select:
+    - 'Tool A'
+    - 'Tool B'
+```
+
+### Configuration Inheritance
+
+Core values cascade to ALL modules automatically:
+
+```yaml
+# core/config.yaml
+user_name: "Jane"
+communication_language: "English"
+
+# xmc/config.yaml (generated)
+project_name: "My App"
+tech_docs: "/path/to/docs"
+# Core Configuration Values (inherited)
+user_name: "Jane"
+communication_language: "English"
+```
+
+**Reserved Keys**: Core configuration keys cannot be redefined by other modules.
+
+### Path Placeholders
+
+- `{project-root}`: Project directory path
+- `{value}`: User input
+- `{module}`: Module name
+- `{core:field}`: Reference core config value
+
+### Config Generation Rules
+
+1. ALL installed modules get a `config.yaml` (even without prompts)
+2. Core values are ALWAYS included in module configs
+3. Module-specific values come first, core values appended
+4. Source templates are never copied, only generated configs
+
+## Platform Integration
+
+### Supported Platforms
+
+**Preferred** (Full Integration):
+
+- Claude Code
+- Cursor
+- Windsurf
+
+**Additional**:
+Cline, Roo, Rovo Dev,Auggie, GitHub Copilot, Codex, Gemini, Qwen, Trae, Kilo, Crush, iFlow
+
+### Platform Features
+
+1. **Setup Handler** (`tools/cli/installers/lib/ide/{platform}.js`)
+   - Directory creation
+   - Configuration generation
+   - Agent processing
+
+2. **Content Injection** (`sub-modules/{platform}/injections.yaml`)
+
+   ```yaml
+   injections:
+     - file: '{xiaoma_folder}/xmc/agents/pm.md'
+       point: 'pm-agent-instructions'
+       content: |
+         <i>Platform-specific instruction</i>
+
+   subagents:
+     source: 'sub-agents'
+     target: '.claude/agents'
+     files: ['agent.md']
+   ```
+
+3. **Interactive Config**
+   - Subagent selection
+   - Installation scope (project/user)
+   - Feature toggles
+
+### Injection System
+
+Platform-specific content without source modification:
+
+- Inject points marked in source: `<!-- IDE-INJECT-POINT:name -->`
+- Content added during installation only
+- Source files remain clean
+
+## Development Guide
+
+### Creating a Module
+
+1. **Structure**
+
+   ```
+   src/modules/mymod/
+   ├── _module-installer/
+   │   ├── installer.js
+   │   └── install-config.yaml
+   ├── agents/
+   └── tasks/
+   ```
+
+2. **Configuration** (`install-config.yaml`)
+
+   ```yaml
+   code: mymod
+   name: 'My Module'
+   prompt: 'Welcome message'
+
+   setting_name:
+     prompt: 'Configure X?'
+     default: 'value'
+   ```
+
+3. **Installer** (`installer.js`)
+   ```javascript
+   async function install(options) {
+     const { projectRoot, config, installedIDEs, logger } = options;
+     // Custom logic
+     return true;
+   }
+   module.exports = { install };
+   ```
+
+### Adding Platform Support
+
+1. Create handler: `tools/cli/installers/lib/ide/myplatform.js`
+2. Extend `BaseIdeSetup` class
+3. Add sub-module: `src/modules/{mod}/sub-modules/myplatform/`
+4. Define injections and platform agents
+
+### Agent Configuration
+
+Extractable config nodes:
+
+```xml
+<agent>
+  <setting agentConfig="true">
+    Default value
+  </setting>
+</agent>
+```
+
+Generated in: `xiaoma/_cfg/agents/{module}-{agent}.md`
+
+## Troubleshooting
+
+### Common Issues
+
+| Issue                   | Solution                                         |
+| ----------------------- | ------------------------------------------------ |
+| Existing installation   | Use `xiaoma update` or remove `{xiaoma_folder}/` |
+| Module not found        | Check `src/modules/` exists                      |
+| Config not applied      | Verify `{xiaoma_folder}/{module}/config.yaml`    |
+| Missing config.yaml     | Fixed: All modules now get configs               |
+| Agent unavailable       | Check for `localskip="true"`                     |
+| module-installer copied | Fixed: Now excluded from copy                    |
+
+### Debug Commands
+
+```bash
+xiaoma install -v     # Verbose installation
+xiaoma status -v      # Detailed status
+```
+
+### Best Practices
+
+1. Run from project root
+2. Backup `{xiaoma_folder}/_cfg/` before updates
+3. Use interactive mode for guidance
+4. Review generated configs post-install
+
+## Migration from v4
+
+| v4                  | v6                             |
+| ------------------- | ------------------------------ |
+| Scattered files     | Centralized `{xiaoma_folder}/` |
+| Monolithic          | Modular                        |
+| Manual config       | Interactive setup              |
+| Limited IDE support | 15+ platforms                  |
+| Source modification | Clean injection                |
+
+## Technical Notes
+
+### Dependency Resolution
+
+- Direct dependencies (module → module)
+- Agent references (cross-module)
+- Template dependencies
+- Partial module installation (only required files)
+- Workflow vendoring for standalone module operation
+
+## Workflow Vendoring
+
+**Problem**: Modules that reference workflows from other modules create dependencies, forcing users to install multiple modules even when they only need one.
+
+**Solution**: Workflow vendoring allows modules to copy workflows from other modules during installation, making them fully standalone.
+
+### How It Works
+
+Agents can specify both `workflow` (source location) and `workflow-install` (destination location) in their menu items:
+
+```yaml
+menu:
+  - trigger: create-story
+    workflow: '{project-root}/{xiaoma_folder}/xmc/workflows/4-implementation/create-story/workflow.yaml'
+    workflow-install: '{project-root}/{xiaoma_folder}/xmgd/workflows/4-production/create-story/workflow.yaml'
+    description: 'Create a game feature story'
+```
+
+**During Installation:**
+
+1. **Vendoring Phase**: Before copying module files, the installer:
+   - Scans source agent YAML files for `workflow-install` attributes
+   - Copies entire workflow folders from `workflow` path to `workflow-install` path
+   - Updates vendored `workflow.yaml` files to reference target module's config
+
+2. **Compilation Phase**: When compiling agents:
+   - If `workflow-install` exists, uses its value for the `workflow` attribute
+   - `workflow-install` is build-time metadata only, never appears in final XML
+   - Compiled agent references vendored workflow location
+
+3. **Config Update**: Vendored workflows get their `config_source` updated:
+
+   ```yaml
+   # Source workflow (in xmc):
+   config_source: "{project-root}/{xiaoma_folder}/xmc/config.yaml"
+
+   # Vendored workflow (in xmgd):
+   config_source: "{project-root}/{xiaoma_folder}/xmgd/config.yaml"
+   ```
+
+**Result**: Modules become completely standalone with their own copies of needed workflows, configured for their specific use case.
+
+### Benefits
+
+✅ **Module Independence** - No forced dependencies
+✅ **Clean Namespace** - Workflows live in their module
+✅ **Config Isolation** - Each module uses its own configuration
+✅ **Customization Ready** - Vendored workflows can be modified independently
+✅ **No User Confusion** - Avoid partial module installations
+
+### File Processing
+
+- Filters `localskip="true"` agents
+- Excludes `_module-installer/` directories
+- Replaces path placeholders at runtime
+- Injects activation blocks
+- Vendors cross-module workflows (see Workflow Vendoring below)
+
+### Web Bundling
+
+```bash
+xiaoma bundle --web           # Filter for web deployment
+npm run validate:bundles    # Validate bundles
+```