@zeyue0329/xiaoma-cli 1.0.49 → 1.6.4

package/docs/how-to/non-interactive-installation.md

@@ -0,0 +1,171 @@
+---
+title: Non-Interactive Installation
+description: Install XiaoMa using command-line flags for CI/CD pipelines and automated deployments
+sidebar:
+  order: 2
+---
+
+Use command-line flags to install XiaoMa non-interactively. This is useful for:
+
+## When to Use This
+
+- Automated deployments and CI/CD pipelines
+- Scripted installations
+- Batch installations across multiple projects
+- Quick installations with known configurations
+
+:::note[Prerequisites]
+Requires [Node.js](https://nodejs.org) v20+ and `npx` (included with npm).
+:::
+
+## Available Flags
+
+### Installation Options
+
+| Flag | Description | Example |
+|------|-------------|---------|
+| `--directory <path>` | Installation directory | `--directory ~/projects/myapp` |
+| `--modules <modules>` | Comma-separated module IDs | `--modules xmc,bmb` |
+| `--tools <tools>` | Comma-separated tool/IDE IDs (use `none` to skip) | `--tools claude-code,cursor` or `--tools none` |
+| `--custom-content <paths>` | Comma-separated paths to custom modules | `--custom-content ~/my-module,~/another-module` |
+| `--action <type>` | Action for existing installations: `install` (default), `update`, `quick-update`, or `compile-agents` | `--action quick-update` |
+
+### Core Configuration
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--user-name <name>` | Name for agents to use | System username |
+| `--communication-language <lang>` | Agent communication language | English |
+| `--document-output-language <lang>` | Document output language | English |
+| `--output-folder <path>` | Output folder path | _xiaoma-output |
+
+### Other Options
+
+| Flag | Description |
+|------|-------------|
+| `-y, --yes` | Accept all defaults and skip prompts |
+| `-d, --debug` | Enable debug output for manifest generation |
+
+## Module IDs
+
+Available module IDs for the `--modules` flag:
+
+- `xmc` — XiaoMa Method Core
+- `bmb` — XiaoMa Builder
+
+Check the [XiaoMa registry](https://github.com/xiaoma-code-org) for available external modules.
+
+## Tool/IDE IDs
+
+Available tool IDs for the `--tools` flag:
+
+**Preferred:** `claude-code`, `cursor`
+
+Run `npx xiaoma-cli install` interactively once to see the full current list of supported tools, or check the [platform codes configuration](https://github.com/xiaoma-code-org/XiaoMa-Cli/blob/main/tools/cli/installers/lib/ide/platform-codes.yaml).
+
+## Installation Modes
+
+| Mode | Description | Example |
+|------|-------------|---------|
+| Fully non-interactive | Provide all flags to skip all prompts | `npx xiaoma-cli install --directory . --modules xmc --tools claude-code --yes` |
+| Semi-interactive | Provide some flags; XiaoMa prompts for the rest | `npx xiaoma-cli install --directory . --modules xmc` |
+| Defaults only | Accept all defaults with `-y` | `npx xiaoma-cli install --yes` |
+| Without tools | Skip tool/IDE configuration | `npx xiaoma-cli install --modules xmc --tools none` |
+
+## Examples
+
+### CI/CD Pipeline Installation
+
+```bash
+#!/bin/bash
+# install-xiaoma.sh
+
+npx xiaoma-cli install \
+  --directory "${GITHUB_WORKSPACE}" \
+  --modules xmc \
+  --tools claude-code \
+  --user-name "CI Bot" \
+  --communication-language English \
+  --document-output-language English \
+  --output-folder _xiaoma-output \
+  --yes
+```
+
+### Update Existing Installation
+
+```bash
+npx xiaoma-cli install \
+  --directory ~/projects/myapp \
+  --action update \
+  --modules xmc,bmb,custom-module
+```
+
+### Quick Update (Preserve Settings)
+
+```bash
+npx xiaoma-cli install \
+  --directory ~/projects/myapp \
+  --action quick-update
+```
+
+### Installation with Custom Content
+
+```bash
+npx xiaoma-cli install \
+  --directory ~/projects/myapp \
+  --modules xmc \
+  --custom-content ~/my-custom-module,~/another-module \
+  --tools claude-code
+```
+
+## What You Get
+
+- A fully configured `_xiaoma/` directory in your project
+- Compiled agents and workflows for your selected modules and tools
+- A `_xiaoma-output/` folder for generated artifacts
+
+## Validation and Error Handling
+
+XiaoMa validates all provided flags:
+
+- **Directory** — Must be a valid path with write permissions
+- **Modules** — Warns about invalid module IDs (but won't fail)
+- **Tools** — Warns about invalid tool IDs (but won't fail)
+- **Custom Content** — Each path must contain a valid `module.yaml` file
+- **Action** — Must be one of: `install`, `update`, `quick-update`, `compile-agents`
+
+Invalid values will either:
+1. Show an error and exit (for critical options like directory)
+2. Show a warning and skip (for optional items like custom content)
+3. Fall back to interactive prompts (for missing required values)
+
+:::tip[Best Practices]
+- Use absolute paths for `--directory` to avoid ambiguity
+- Test flags locally before using in CI/CD pipelines
+- Combine with `-y` for truly unattended installations
+- Use `--debug` if you encounter issues during installation
+:::
+
+## Troubleshooting
+
+### Installation fails with "Invalid directory"
+
+- The directory path must exist (or its parent must exist)
+- You need write permissions
+- The path must be absolute or correctly relative to the current directory
+
+### Module not found
+
+- Verify the module ID is correct
+- External modules must be available in the registry
+
+### Custom content path invalid
+
+Ensure each custom content path:
+- Points to a directory
+- Contains a `module.yaml` file in the root
+- Has a `code` field in the `module.yaml`
+
+:::note[Still stuck?]
+Run with `--debug` for detailed output, try interactive mode to isolate the issue, or report at <https://github.com/xiaoma-code-org/XiaoMa-Cli/issues>.
+:::

package/docs/how-to/project-context.md

@@ -0,0 +1,136 @@
+---
+title: "Manage Project Context"
+description: Create and maintain project-context.md to guide AI agents
+sidebar:
+  order: 7
+---
+
+Use the `project-context.md` file to ensure AI agents follow your project's technical preferences and implementation rules throughout all workflows.
+
+:::note[Prerequisites]
+- XiaoMa Method installed
+- Understanding of your project's technology stack and conventions
+:::
+
+## When to Use This
+
+- You have strong technical preferences before starting architecture
+- You've completed architecture and want to capture decisions for implementation
+- You're working on an existing codebase with established patterns
+- You notice agents making inconsistent decisions across stories
+
+## Step 1: Choose Your Approach
+
+**Manual creation** — Best when you know exactly what rules you want to document
+
+**Generate after architecture** — Best for capturing decisions made during solutioning
+
+**Generate for existing projects** — Best for discovering patterns in existing codebases
+
+## Step 2: Create the File
+
+### Option A: Manual Creation
+
+Create the file at `_xiaoma-output/project-context.md`:
+
+```bash
+mkdir -p _xiaoma-output
+touch _xiaoma-output/project-context.md
+```
+
+Add your technology stack and implementation rules:
+
+```markdown
+---
+project_name: 'MyProject'
+user_name: 'YourName'
+date: '2026-02-15'
+sections_completed: ['technology_stack', 'critical_rules']
+---
+
+# Project Context for AI Agents
+
+## Technology Stack & Versions
+
+- Node.js 20.x, TypeScript 5.3, React 18.2
+- State: Zustand
+- Testing: Vitest, Playwright
+- Styling: Tailwind CSS
+
+## Critical Implementation Rules
+
+**TypeScript:**
+- Strict mode enabled, no `any` types
+- Use `interface` for public APIs, `type` for unions
+
+**Code Organization:**
+- Components in `/src/components/` with co-located tests
+- API calls use `apiClient` singleton — never fetch directly
+
+**Testing:**
+- Unit tests focus on business logic
+- Integration tests use MSW for API mocking
+```
+
+### Option B: Generate After Architecture
+
+Run the workflow in a fresh chat:
+
+```bash
+xiaoma-generate-project-context
+```
+
+The workflow scans your architecture document and project files to generate a context file capturing the decisions made.
+
+### Option C: Generate for Existing Projects
+
+For existing projects, run:
+
+```bash
+xiaoma-generate-project-context
+```
+
+The workflow analyzes your codebase to identify conventions, then generates a context file you can review and refine.
+
+## Step 3: Verify Content
+
+Review the generated file and ensure it captures:
+
+- Correct technology versions
+- Your actual conventions (not generic best practices)
+- Rules that prevent common mistakes
+- Framework-specific patterns
+
+Edit manually to add anything missing or remove inaccuracies.
+
+## What You Get
+
+A `project-context.md` file that:
+
+- Ensures all agents follow the same conventions
+- Prevents inconsistent decisions across stories
+- Captures architecture decisions for implementation
+- Serves as a reference for your project's patterns and rules
+
+## Tips
+
+:::tip[Focus on the Unobvious]
+Document patterns agents might miss such as "Use JSDoc style comments on every public class, function and variable", not universal practices like "use meaningful variable names" which LLMs know at this point.
+:::
+
+:::tip[Keep It Lean]
+This file is loaded by every implementation workflow. Long files waste context. Do not include content that only applies to narrow scope or specific stories or features.
+:::
+
+:::tip[Update as Needed]
+Edit manually when patterns change, or re-generate after significant architecture changes.
+:::
+
+:::tip[Works for All Project Types]
+Just as useful for Quick Flow as for full XiaoMa Method projects.
+:::
+
+## Next Steps
+
+- [**Project Context Explanation**](../explanation/project-context.md) — Learn more about how it works
+- [**Workflow Map**](../reference/workflow-map.md) — See which workflows load project context

package/docs/how-to/quick-fixes.md

@@ -0,0 +1,123 @@
+---
+title: "Quick Fixes"
+description: How to make quick fixes and ad-hoc changes
+sidebar:
+  order: 5
+---
+
+Use the **DEV agent** directly for bug fixes, refactorings, or small targeted changes that don't require the full XiaoMa Method or Quick Flow.
+
+## When to Use This
+
+- Bug fixes with a clear, known cause
+- Small refactorings (rename, extract, restructure) contained within a few files
+- Minor feature tweaks or configuration changes
+- Exploratory work to understand an unfamiliar codebase
+
+:::note[Prerequisites]
+- XiaoMa Method installed (`npx xiaoma-cli install`)
+- An AI-powered IDE (Claude Code, Cursor, or similar)
+:::
+
+## Choose Your Approach
+
+| Situation | Agent | Why |
+| --- | --- | --- |
+| Fix a specific bug or make a small, scoped change | **DEV agent** | Jumps straight into implementation without planning overhead |
+| Change touches several files or you want a written plan first | **Quick Flow Solo Dev** | Creates a quick-spec before implementation so the agent stays aligned to your standards |
+
+If you are unsure, start with the DEV agent. You can always escalate to Quick Flow if the change grows.
+
+## Steps
+
+### 1. Invoke the DEV Agent
+
+Start a **fresh chat** in your AI IDE and invoke the DEV agent skill:
+
+```text
+xiaoma-dev
+```
+
+This loads the agent's persona and capabilities into the session. If you decide you need Quick Flow instead, invoke the **Quick Flow Solo Dev** agent skill in a fresh chat:
+
+```text
+xiaoma-quick-flow-solo-dev
+```
+
+Once the Solo Dev agent is loaded, describe your change and ask it to create a **quick-spec**. The agent drafts a lightweight spec capturing what you want to change and how. After you approve the quick-spec, tell the agent to start the **Quick Flow dev cycle** -- it will implement the change, run tests, and perform a self-review, all guided by the spec you just approved.
+
+:::tip[Fresh Chats]
+Always start a new chat session when loading an agent. Reusing a session from a previous workflow can cause context conflicts.
+:::
+
+### 2. Describe the Change
+
+Tell the agent what you need in plain language. Be specific about the problem and, if you know it, where the relevant code lives.
+
+:::note[Example Prompts]
+**Bug fix** -- "Fix the login validation bug that allows empty passwords. The validation logic is in `src/auth/validate.ts`."
+
+**Refactoring** -- "Refactor the UserService to use async/await instead of callbacks."
+
+**Configuration change** -- "Update the CI pipeline to cache node_modules between runs."
+
+**Dependency update** -- "Upgrade the express dependency to the latest v5 release and fix any breaking changes."
+:::
+
+You don't need to provide every detail. The agent will read the relevant source files and ask clarifying questions when needed.
+
+### 3. Let the Agent Work
+
+The agent will:
+
+- Read and analyze the relevant source files
+- Propose a solution and explain its reasoning
+- Implement the change across the affected files
+- Run your project's test suite if one exists
+
+If your project has tests, the agent runs them automatically after making changes and iterates until tests pass. For projects without a test suite, verify the change manually (run the app, hit the endpoint, check the output).
+
+### 4. Review and Verify
+
+Before committing, review what changed:
+
+- Read through the diff to confirm the change matches your intent
+- Run the application or tests yourself to double-check
+- If something looks wrong, tell the agent what to fix -- it can iterate in the same session
+
+Once satisfied, commit the changes with a clear message describing the fix.
+
+:::caution[If Something Breaks]
+If a committed change causes unexpected issues, use `git revert HEAD` to undo the last commit cleanly. Then start a fresh chat with the DEV agent to try a different approach.
+:::
+
+## Learning Your Codebase
+
+The DEV agent is also useful for exploring unfamiliar code. Load it in a fresh chat and ask questions:
+
+:::note[Example Prompts]
+"Explain how the authentication system works in this codebase."
+
+"Show me where error handling happens in the API layer."
+
+"What does the `ProcessOrder` function do and what calls it?"
+:::
+
+Use the agent to learn about your project, understand how components connect, and explore unfamiliar areas before making changes.
+
+## What You Get
+
+- Modified source files with the fix or refactoring applied
+- Passing tests (if your project has a test suite)
+- A clean commit describing the change
+
+No planning artifacts are produced -- that's the point of this approach.
+
+## When to Upgrade to Formal Planning
+
+Consider using [Quick Flow](../explanation/quick-flow.md) or the full XiaoMa Method when:
+
+- The change affects multiple systems or requires coordinated updates across many files
+- You are unsure about the scope and need a spec to think it through
+- The fix keeps growing in complexity as you work on it
+- You need documentation or architectural decisions recorded for the team

package/docs/how-to/shard-large-documents.md

@@ -0,0 +1,78 @@
+---
+title: "Document Sharding Guide"
+description: Split large markdown files into smaller organized files for better context management
+sidebar:
+  order: 8
+---
+
+Use the `xiaoma-shard-doc` tool if you need to split large markdown files into smaller, organized files for better context management.
+
+:::caution[Deprecated]
+This is no longer recommended, and soon with updated workflows and most major LLMs and tools supporting subprocesses this will be unnecessary.
+:::
+
+## When to Use This
+
+Only use this if you notice your chosen tool / model combination is failing to load and read all the documents as input when needed.
+
+## What is Document Sharding?
+
+Document sharding splits large markdown files into smaller, organized files based on level 2 headings (`## Heading`).
+
+### Architecture
+
+```text
+Before Sharding:
+_xiaoma-output/planning-artifacts/
+└── PRD.md (large 50k token file)
+
+After Sharding:
+_xiaoma-output/planning-artifacts/
+└── prd/
+    ├── index.md                    # Table of contents with descriptions
+    ├── overview.md                 # Section 1
+    ├── user-requirements.md        # Section 2
+    ├── technical-requirements.md   # Section 3
+    └── ...                         # Additional sections
+```
+
+## Steps
+
+### 1. Run the Shard-Doc Tool
+
+```bash
+/xiaoma-shard-doc
+```
+
+### 2. Follow the Interactive Process
+
+```text
+Agent: Which document would you like to shard?
+User: docs/PRD.md
+
+Agent: Default destination: docs/prd/
+       Accept default? [y/n]
+User: y
+
+Agent: Sharding PRD.md...
+       ✓ Created 12 section files
+       ✓ Generated index.md
+       ✓ Complete!
+```
+
+## How Workflow Discovery Works
+
+XiaoMa workflows use a **dual discovery system**:
+
+1. **Try whole document first** - Look for `document-name.md`
+2. **Check for sharded version** - Look for `document-name/index.md`
+3. **Priority rule** - Whole document takes precedence if both exist - remove the whole document if you want the sharded to be used instead
+
+## Workflow Support
+
+All BMM workflows support both formats:
+
+- Whole documents
+- Sharded documents
+- Automatic detection
+- Transparent to user

package/docs/how-to/upgrade-to-v6.md

@@ -0,0 +1,100 @@
+---
+title: "How to Upgrade to v6"
+description: Migrate from XiaoMa v4 to v6
+sidebar:
+  order: 3
+---
+
+Use the XiaoMa installer to upgrade from v4 to v6, which includes automatic detection of legacy installations and migration assistance.
+
+## When to Use This
+
+- You have XiaoMa v4 installed (`.xiaoma-cli` folder)
+- You want to migrate to the new v6 architecture
+- You have existing planning artifacts to preserve
+
+:::note[Prerequisites]
+- Node.js 20+
+- Existing XiaoMa v4 installation
+:::
+
+## Steps
+
+### 1. Run the Installer
+
+Follow the [Installer Instructions](./install-xiaoma.md).
+
+### 2. Handle Legacy Installation
+
+When v4 is detected, you can:
+
+- Allow the installer to back up and remove `.xiaoma-cli`
+- Exit and handle cleanup manually
+
+If you named your xiaoma method folder something else - you will need to manually remove the folder yourself.
+
+### 3. Clean Up IDE Skills
+
+Manually remove legacy v4 IDE commands/skills - for example if you have Claude Code, look for any nested folders that start with xiaoma and remove them:
+
+- `.claude/commands/`
+
+The new v6 skills are installed to:
+
+- `.claude/skills/`
+
+### 4. Migrate Planning Artifacts
+
+**If you have planning documents (Brief/PRD/UX/Architecture):**
+
+Move them to `_xiaoma-output/planning-artifacts/` with descriptive names:
+
+- Include `PRD` in filename for PRD documents
+- Include `brief`, `architecture`, or `ux-design` accordingly
+- Sharded documents can be in named subfolders
+
+**If you're mid-planning:** Consider restarting with v6 workflows. Use your existing documents as inputs—the new progressive discovery workflows with web search and IDE plan mode produce better results.
+
+### 5. Migrate In-Progress Development
+
+If you have stories created or implemented:
+
+1. Complete the v6 installation
+2. Place `epics.md` or `epics/epic*.md` in `_xiaoma-output/planning-artifacts/`
+3. Run the Scrum Master's `xiaoma-sprint-planning` workflow
+4. Tell the SM which epics/stories are already complete
+
+## What You Get
+
+**v6 unified structure:**
+
+```text
+your-project/
+├── _xiaoma/               # Single installation folder
+│   ├── _config/         # Your customizations
+│   │   └── agents/      # Agent customization files
+│   ├── core/            # Universal core framework
+│   ├── xmc/             # XiaoMa Method module
+│   ├── bmb/             # XiaoMa Builder
+│   └── cis/             # Creative Intelligence Suite
+└── _xiaoma-output/        # Output folder (was doc folder in v4)
+```
+
+## Module Migration
+
+| v4 Module                     | v6 Status                                 |
+| ----------------------------- | ----------------------------------------- |
+| `.xiaoma-2d-phaser-game-dev`    | Integrated into BMGD Module               |
+| `.xiaoma-2d-unity-game-dev`     | Integrated into BMGD Module               |
+| `.xiaoma-godot-game-dev`        | Integrated into BMGD Module               |
+| `.xiaoma-infrastructure-devops` | Deprecated — new DevOps agent coming soon |
+| `.xiaoma-creative-writing`      | Not adapted — new v6 module coming soon   |
+
+## Key Changes
+
+| Concept       | v4                                    | v6                                   |
+| ------------- | ------------------------------------- | ------------------------------------ |
+| **Core**      | `_xiaoma-core` was actually XiaoMa Method | `_xiaoma/core/` is universal framework |
+| **Method**    | `_xiaoma-cli`                        | `_xiaoma/xmc/`                         |
+| **Config**    | Modified files directly               | `config.yaml` per module             |
+| **Documents** | Sharded or unsharded required setup   | Fully flexible, auto-scanned         |

package/docs/ide-info/auggie.md

@@ -0,0 +1,31 @@
+# XIAOMA Method - Auggie CLI Instructions
+
+## Activating Agents
+
+XIAOMA agents can be installed in multiple locations based on your setup.
+
+### Common Locations
+
+- User Home: `~/.augment/commands/`
+- Project: `.augment/commands/`
+- Custom paths you selected
+
+### How to Use
+
+1. **Type Trigger**: Use `@{agent-name}` in your prompt
+2. **Activate**: Agent persona activates
+3. **Tasks**: Use `@task-{task-name}` for tasks
+
+### Examples
+
+```
+@dev - Activate development agent
+@architect - Activate architect agent
+@task-setup - Execute setup task
+```
+
+### Notes
+
+- Agents can be in multiple locations
+- Check your installation paths
+- Activation syntax same across all locations

package/docs/ide-info/claude-code.md

@@ -0,0 +1,25 @@
+# XIAOMA Method - Claude Code Instructions
+
+## Activating Agents
+
+XIAOMA agents are installed as slash commands in `.claude/commands/xiaoma/`.
+
+### How to Use
+
+1. **Type Slash Command**: Start with `/` to see available commands
+2. **Select Agent**: Type `/xiaoma-{agent-name}` (e.g., `/xiaoma-dev`)
+3. **Execute**: Press Enter to activate that agent persona
+
+### Examples
+
+```
+/xiaoma:xmc:agents:dev - Activate development agent
+/xiaoma:xmc:agents:architect - Activate architect agent
+/xiaoma:xmc:workflows:dev-story - Execute dev-story workflow
+```
+
+### Notes
+
+- Commands are autocompleted when you type `/`
+- Agent remains active for the conversation
+- Start a new conversation to switch agents

package/docs/ide-info/cline.md

@@ -0,0 +1,31 @@
+# XIAOMA Method - Cline Instructions
+
+## Activating Agents
+
+XIAOMA agents are installed as **toggleable rules** in `.clinerules/` directory.
+
+### Important: Rules are OFF by default
+
+- Rules are NOT automatically loaded to avoid context pollution
+- You must manually enable the agent you want to use
+
+### How to Use
+
+1. **Open Rules Panel**: Click the rules icon below the chat input
+2. **Enable an Agent**: Toggle ON the specific agent rule you need (e.g., `01-core-dev`)
+3. **Activate in Chat**: Type `@{agent-name}` to activate that persona
+4. **Disable When Done**: Toggle OFF to free up context
+
+### Best Practices
+
+- Only enable 1-2 agents at a time to preserve context
+- Disable agents when switching tasks
+- Rules are numbered (01-, 02-) for organization, not priority
+
+### Example
+
+```
+Toggle ON: 01-core-dev.md
+In chat: "@dev help me refactor this code"
+When done: Toggle OFF the rule
+```