@zeyue0329/xiaoma-cli 1.0.49 → 1.6.5

package/docs/explanation/why-solutioning-matters.md

@@ -0,0 +1,77 @@
+---
+title: "Why Solutioning Matters"
+description: Understanding why the solutioning phase is critical for multi-epic projects
+sidebar:
+  order: 3
+---
+
+
+Phase 3 (Solutioning) translates **what** to build (from Planning) into **how** to build it (technical design). This phase prevents agent conflicts in multi-epic projects by documenting architectural decisions before implementation begins.
+
+## The Problem Without Solutioning
+
+```text
+Agent 1 implements Epic 1 using REST API
+Agent 2 implements Epic 2 using GraphQL
+Result: Inconsistent API design, integration nightmare
+```
+
+When multiple agents implement different parts of a system without shared architectural guidance, they make independent technical decisions that may conflict.
+
+## The Solution With Solutioning
+
+```text
+architecture workflow decides: "Use GraphQL for all APIs"
+All agents follow architecture decisions
+Result: Consistent implementation, no conflicts
+```
+
+By documenting technical decisions explicitly, all agents implement consistently and integration becomes straightforward.
+
+## Solutioning vs Planning
+
+| Aspect   | Planning (Phase 2)      | Solutioning (Phase 3)             |
+| -------- | ----------------------- | --------------------------------- |
+| Question | What and Why?           | How? Then What units of work?     |
+| Output   | FRs/NFRs (Requirements) | Architecture + Epics/Stories      |
+| Agent    | PM                      | Architect → PM                    |
+| Audience | Stakeholders            | Developers                        |
+| Document | PRD (FRs/NFRs)          | Architecture + Epic Files         |
+| Level    | Business logic          | Technical design + Work breakdown |
+
+## Key Principle
+
+**Make technical decisions explicit and documented** so all agents implement consistently.
+
+This prevents:
+- API style conflicts (REST vs GraphQL)
+- Database design inconsistencies
+- State management disagreements
+- Naming convention mismatches
+- Security approach variations
+
+## When Solutioning is Required
+
+| Track | Solutioning Required? |
+|-------|----------------------|
+| Quick Flow | No - skip entirely |
+| XiaoMa Method Simple | Optional |
+| XiaoMa Method Complex | Yes |
+| Enterprise | Yes |
+
+:::tip[Rule of Thumb]
+If you have multiple epics that could be implemented by different agents, you need solutioning.
+:::
+
+## The Cost of Skipping
+
+Skipping solutioning on complex projects leads to:
+
+- **Integration issues** discovered mid-sprint
+- **Rework** due to conflicting implementations
+- **Longer development time** overall
+- **Technical debt** from inconsistent patterns
+
+:::caution[Cost Multiplier]
+Catching alignment issues in solutioning is 10× faster than discovering them during implementation.
+:::

package/docs/how-to/customize-xiaoma.md

@@ -0,0 +1,172 @@
+---
+title: "How to Customize XiaoMa"
+description: Customize agents, workflows, and modules while preserving update compatibility
+sidebar:
+  order: 7
+---
+
+Use the `.customize.yaml` files to tailor agent behavior, personas, and menus while preserving your changes across updates.
+
+## When to Use This
+
+- You want to change an agent's name, personality, or communication style
+- You need agents to remember project-specific context
+- You want to add custom menu items that trigger your own workflows or prompts
+- You want agents to perform specific actions every time they start up
+
+:::note[Prerequisites]
+- XiaoMa installed in your project (see [How to Install XiaoMa](./install-xiaoma.md))
+- A text editor for YAML files
+:::
+
+:::caution[Keep Your Customizations Safe]
+Always use the `.customize.yaml` files described here rather than editing agent files directly. The installer overwrites agent files during updates, but preserves your `.customize.yaml` changes.
+:::
+
+## Steps
+
+### 1. Locate Customization Files
+
+After installation, find one `.customize.yaml` file per agent in:
+
+```text
+_xiaoma/_config/agents/
+├── core-xiaoma-master.customize.yaml
+├── xmc-dev.customize.yaml
+├── xmc-pm.customize.yaml
+└── ... (one file per installed agent)
+```
+
+### 2. Edit the Customization File
+
+Open the `.customize.yaml` file for the agent you want to modify. Every section is optional -- customize only what you need.
+
+| Section            | Behavior | Purpose                                         |
+| ------------------ | -------- | ----------------------------------------------- |
+| `agent.metadata`   | Replaces | Override the agent's display name               |
+| `persona`          | Replaces | Set role, identity, style, and principles       |
+| `memories`         | Appends  | Add persistent context the agent always recalls |
+| `menu`             | Appends  | Add custom menu items for workflows or prompts  |
+| `critical_actions` | Appends  | Define startup instructions for the agent       |
+| `prompts`          | Appends  | Create reusable prompts for menu actions        |
+
+Sections marked **Replaces** overwrite the agent's defaults entirely. Sections marked **Appends** add to the existing configuration.
+
+**Agent Name**
+
+Change how the agent introduces itself:
+
+```yaml
+agent:
+  metadata:
+    name: 'Spongebob' # Default: "Amelia"
+```
+
+**Persona**
+
+Replace the agent's personality, role, and communication style:
+
+```yaml
+persona:
+  role: 'Senior Full-Stack Engineer'
+  identity: 'Lives in a pineapple (under the sea)'
+  communication_style: 'Spongebob annoying'
+  principles:
+    - 'Never Nester, Spongebob Devs hate nesting more than 2 levels deep'
+    - 'Favor composition over inheritance'
+```
+
+The `persona` section replaces the entire default persona, so include all four fields if you set it.
+
+**Memories**
+
+Add persistent context the agent will always remember:
+
+```yaml
+memories:
+  - 'Works at Krusty Krab'
+  - 'Favorite Celebrity: David Hasslehoff'
+  - 'Learned in Epic 1 that it is not cool to just pretend that tests have passed'
+```
+
+**Menu Items**
+
+Add custom entries to the agent's display menu. Each item needs a `trigger`, a target (`workflow` path or `action` reference), and a `description`:
+
+```yaml
+menu:
+  - trigger: my-workflow
+    workflow: 'my-custom/workflows/my-workflow.yaml'
+    description: My custom workflow
+  - trigger: deploy
+    action: '#deploy-prompt'
+    description: Deploy to production
+```
+
+**Critical Actions**
+
+Define instructions that run when the agent starts up:
+
+```yaml
+critical_actions:
+  - 'Check the CI Pipelines with the XYZ Skill and alert user on wake if anything is urgently needing attention'
+```
+
+**Custom Prompts**
+
+Create reusable prompts that menu items can reference with `action="#id"`:
+
+```yaml
+prompts:
+  - id: deploy-prompt
+    content: |
+      Deploy the current branch to production:
+      1. Run all tests
+      2. Build the project
+      3. Execute deployment script
+```
+
+### 3. Apply Your Changes
+
+After editing, recompile the agent to apply changes:
+
+```bash
+npx xiaoma-cli install
+```
+
+The installer detects the existing installation and offers these options:
+
+| Option                       | What It Does                                                        |
+| ---------------------------- | ------------------------------------------------------------------- |
+| **Quick Update**             | Updates all modules to the latest version and recompiles all agents |
+| **Recompile Agents**         | Applies customizations only, without updating module files          |
+| **Modify XiaoMa Installation** | Full installation flow for adding or removing modules               |
+
+For customization-only changes, **Recompile Agents** is the fastest option.
+
+## Troubleshooting
+
+**Changes not appearing?**
+
+- Run `npx xiaoma-cli install` and select **Recompile Agents** to apply changes
+- Check that your YAML syntax is valid (indentation matters)
+- Verify you edited the correct `.customize.yaml` file for the agent
+
+**Agent not loading?**
+
+- Check for YAML syntax errors using an online YAML validator
+- Ensure you did not leave fields empty after uncommenting them
+- Try reverting to the original template and rebuilding
+
+**Need to reset an agent?**
+
+- Clear or delete the agent's `.customize.yaml` file
+- Run `npx xiaoma-cli install` and select **Recompile Agents** to restore defaults
+
+## Workflow Customization
+
+Customization of existing XiaoMa Method workflows and skills is coming soon.
+
+## Module Customization
+
+Guidance on building expansion modules and customizing existing modules is coming soon.

package/docs/how-to/established-projects.md

@@ -0,0 +1,117 @@
+---
+title: "Established Projects"
+description: How to use XiaoMa Method on existing codebases
+sidebar:
+  order: 6
+---
+
+Use XiaoMa Method effectively when working on existing projects and legacy codebases.
+
+This guide covers the essential workflow for onboarding to existing projects with XiaoMa Method.
+
+:::note[Prerequisites]
+- XiaoMa Method installed (`npx xiaoma-cli install`)
+- An existing codebase you want to work on
+- Access to an AI-powered IDE (Claude Code or Cursor)
+:::
+
+## Step 1: Clean Up Completed Planning Artifacts
+
+If you have completed all PRD epics and stories through the XiaoMa process, clean up those files. Archive them, delete them, or rely on version history if needed. Do not keep these files in:
+
+- `docs/`
+- `_xiaoma-output/planning-artifacts/`
+- `_xiaoma-output/implementation-artifacts/`
+
+## Step 2: Create Project Context
+
+:::tip[Recommended for Existing Projects]
+Generate `project-context.md` to capture your existing codebase patterns and conventions. This ensures AI agents follow your established practices when implementing changes.
+:::
+
+Run the generate project context workflow:
+
+```bash
+xiaoma-generate-project-context
+```
+
+This scans your codebase to identify:
+- Technology stack and versions
+- Code organization patterns
+- Naming conventions
+- Testing approaches
+- Framework-specific patterns
+
+You can review and refine the generated file, or create it manually at `_xiaoma-output/project-context.md` if you prefer.
+
+[Learn more about project context](../explanation/project-context.md)
+
+## Step 3: Maintain Quality Project Documentation
+
+Your `docs/` folder should contain succinct, well-organized documentation that accurately represents your project:
+
+- Intent and business rationale
+- Business rules
+- Architecture
+- Any other relevant project information
+
+For complex projects, consider using the `xiaoma-document-project` workflow. It offers runtime variants that will scan your entire project and document its actual current state.
+
+## Step 3: Get Help
+
+### XiaoMa-Help: Your Starting Point
+
+**Run `xiaoma-help` anytime you're unsure what to do next.** This intelligent guide:
+
+- Inspects your project to see what's already been done
+- Shows options based on your installed modules
+- Understands natural language queries
+
+```
+xiaoma-help I have an existing Rails app, where should I start?
+xiaoma-help What's the difference between quick-flow and full method?
+xiaoma-help Show me what workflows are available
+```
+
+XiaoMa-Help also **automatically runs at the end of every workflow**, providing clear guidance on exactly what to do next.
+
+### Choosing Your Approach
+
+You have two primary options depending on the scope of changes:
+
+| Scope                          | Recommended Approach                                                                                                          |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
+| **Small updates or additions** | Use `xiaoma-quick-flow-solo-dev` to create a tech-spec and implement the change. The full four-phase XiaoMa Method is likely overkill. |
+| **Major changes or additions** | Start with the XiaoMa Method, applying as much or as little rigor as needed.                                                    |
+
+### During PRD Creation
+
+When creating a brief or jumping directly into the PRD, ensure the agent:
+
+- Finds and analyzes your existing project documentation
+- Reads the proper context about your current system
+
+You can guide the agent explicitly, but the goal is to ensure the new feature integrates well with your existing system.
+
+### UX Considerations
+
+UX work is optional. The decision depends not on whether your project has a UX, but on:
+
+- Whether you will be working on UX changes
+- Whether significant new UX designs or patterns are needed
+
+If your changes amount to simple updates to existing screens you are happy with, a full UX process is unnecessary.
+
+### Architecture Considerations
+
+When doing architecture, ensure the architect:
+
+- Uses the proper documented files
+- Scans the existing codebase
+
+Pay close attention here to prevent reinventing the wheel or making decisions that misalign with your existing architecture.
+
+## More Information
+
+- **[Quick Fixes](./quick-fixes.md)** - Bug fixes and ad-hoc changes
+- **[Established Projects FAQ](../explanation/established-projects-faq.md)** - Common questions about working on established projects

package/docs/how-to/get-answers-about-xiaoma.md

@@ -0,0 +1,134 @@
+---
+title: "How to Get Answers About XiaoMa"
+description: Use an LLM to quickly answer your own XiaoMa questions
+sidebar:
+  order: 4
+---
+
+## Start Here: XiaoMa-Help
+
+**The fastest way to get answers about XiaoMa is `/xiaoma-help`.** This intelligent guide will answer upwards of 80% of all questions and is available to you directly in your IDE as you work.
+
+XiaoMa-Help is more than a lookup tool — it:
+- **Inspects your project** to see what's already been completed
+- **Understands natural language** — ask questions in plain English
+- **Varies based on your installed modules** — shows relevant options
+- **Auto-runs after workflows** — tells you exactly what to do next
+- **Recommends the first required task** — no guessing where to start
+
+### How to Use XiaoMa-Help
+
+Run it with just the skill name:
+
+```
+/xiaoma-help
+```
+
+Or combine it with a natural language query:
+
+```
+/xiaoma-help I have a SaaS idea and know all the features. Where do I start?
+/xiaoma-help What are my options for UX design?
+/xiaoma-help I'm stuck on the PRD workflow
+/xiaoma-help Show me what's been done so far
+```
+
+XiaoMa-Help responds with:
+- What's recommended for your situation
+- What the first required task is
+- What the rest of the process looks like
+
+---
+
+## When to Use This Guide
+
+Use this section when:
+- You want to understand XiaoMa's architecture or internals
+- You need answers outside of what XiaoMa-Help provides
+- You're researching XiaoMa before installing
+- You want to explore the source code directly
+
+## Steps
+
+### 1. Choose Your Source
+
+| Source               | Best For                                  | Examples                     |
+| -------------------- | ----------------------------------------- | ---------------------------- |
+| **`_xiaoma` folder**   | How XiaoMa works—agents, workflows, prompts | "What does the PM agent do?" |
+| **Full GitHub repo** | History, installer, architecture          | "What changed in v6?"        |
+| **`llms-full.txt`**  | Quick overview from docs                  | "Explain XiaoMa's four phases" |
+
+The `_xiaoma` folder is created when you install XiaoMa. If you don't have it yet, clone the repo instead.
+
+### 2. Point Your AI at the Source
+
+**If your AI can read files (Claude Code, Cursor, etc.):**
+
+- **XiaoMa installed:** Point at the `_xiaoma` folder and ask directly
+- **Want deeper context:** Clone the [full repo](https://github.com/xiaoma-code-org/XiaoMa-Cli)
+
+**If you use ChatGPT or Claude.ai:**
+
+Fetch `llms-full.txt` into your session:
+
+```text
+https://xiaoma-code-org.github.io/XiaoMa-Cli/llms-full.txt
+```
+
+
+### 3. Ask Your Question
+
+:::note[Example]
+**Q:** "Tell me the fastest way to build something with XiaoMa"
+
+**A:** Use Quick Flow: Run `xiaoma-quick-spec` to write a technical specification, then `xiaoma-quick-dev` to implement it—skipping the full planning phases.
+:::
+
+## What You Get
+
+Direct answers about XiaoMa—how agents work, what workflows do, why things are structured the way they are—without waiting for someone else to respond.
+
+## Tips
+
+- **Verify surprising answers** — LLMs occasionally get things wrong. Check the source file or ask on Discord.
+- **Be specific** — "What does step 3 of the PRD workflow do?" beats "How does PRD work?"
+
+## Still Stuck?
+
+Tried the LLM approach and still need help? You now have a much better question to ask.
+
+| Channel                   | Use For                                     |
+| ------------------------- | ------------------------------------------- |
+| `#xiaoma-cli-help`       | Quick questions (real-time chat)            |
+| `help-requests` forum     | Detailed questions (searchable, persistent) |
+| `#suggestions-feedback`   | Ideas and feature requests                  |
+| `#report-bugs-and-issues` | Bug reports                                 |
+
+**Discord:** [discord.gg/gk8jAdXWmj](https://discord.gg/gk8jAdXWmj)
+
+**GitHub Issues:** [github.com/xiaoma-code-org/XiaoMa-Cli/issues](https://github.com/xiaoma-code-org/XiaoMa-Cli/issues) (for clear bugs)
+
+*You!*
+        *Stuck*
+             *in the queue—*
+                      *waiting*
+                              *for who?*
+
+*The source*
+        *is there,*
+                *plain to see!*
+
+*Point*
+     *your machine.*
+              *Set it free.*
+
+*It reads.*
+        *It speaks.*
+                *Ask away—*
+
+*Why wait*
+        *for tomorrow*
+                *when you have*
+                        *today?*
+
+*—Claude*

package/docs/how-to/install-xiaoma.md

@@ -0,0 +1,107 @@
+---
+title: "How to Install XiaoMa"
+description: Step-by-step guide to installing XiaoMa in your project
+sidebar:
+  order: 1
+---
+
+Use the `npx xiaoma-cli install` command to set up XiaoMa in your project with your choice of modules and AI tools.
+
+If you want to use a non interactive installer and provide all install options on the command line, see [this guide](./non-interactive-installation.md).
+
+## When to Use This
+
+- Starting a new project with XiaoMa
+- Adding XiaoMa to an existing codebase
+- Update the existing XiaoMa Installation
+
+:::note[Prerequisites]
+- **Node.js** 20+ (required for the installer)
+- **Git** (recommended)
+- **AI tool** (Claude Code, Cursor, or similar)
+:::
+
+## Steps
+
+### 1. Run the Installer
+
+```bash
+npx xiaoma-cli install
+```
+
+:::tip[Bleeding edge]
+To install the latest from the main branch (may be unstable):
+```bash
+npx github:xiaoma-code-org/XiaoMa-Cli install
+```
+:::
+
+### 2. Choose Installation Location
+
+The installer will ask where to install XiaoMa files:
+
+- Current directory (recommended for new projects if you created the directory yourself and ran from within the directory)
+- Custom path
+
+### 3. Select Your AI Tools
+
+Pick which AI tools you use:
+
+- Claude Code
+- Cursor
+- Others
+
+Each tool has its own way of integrating skills. The installer creates tiny prompt files to activate workflows and agents — it just puts them where your tool expects to find them.
+
+:::note[Enabling Skills]
+Some platforms require skills to be explicitly enabled in settings before they appear. If you install XiaoMa and don't see the skills, check your platform's settings or ask your AI assistant how to enable skills.
+:::
+
+### 4. Choose Modules
+
+The installer shows available modules. Select whichever ones you need — most users just want **XiaoMa Method** (the software development module).
+
+### 5. Follow the Prompts
+
+The installer guides you through the rest — custom content, settings, etc.
+
+## What You Get
+
+```text
+your-project/
+├── _xiaoma/
+│   ├── xmc/            # Your selected modules
+│   │   └── config.yaml # Module settings (if you ever need to change them)
+│   ├── core/           # Required core module
+│   └── ...
+├── _xiaoma-output/       # Generated artifacts
+├── .claude/            # Claude Code skills (if using Claude Code)
+│   └── skills/
+│       ├── xiaoma-help/
+│       ├── xiaoma-persona/
+│       └── ...
+└── .cursor/            # Cursor skills (if using Cursor)
+    └── skills/
+        └── ...
+```
+
+## Verify Installation
+
+Run `xiaoma-help` to verify everything works and see what to do next.
+
+**XiaoMa-Help is your intelligent guide** that will:
+- Confirm your installation is working
+- Show what's available based on your installed modules
+- Recommend your first step
+
+You can also ask it questions:
+```
+xiaoma-help I just installed, what should I do first?
+xiaoma-help What are my options for a SaaS project?
+```
+
+## Troubleshooting
+
+**Installer throws an error** — Copy-paste the output into your AI assistant and let it figure it out.
+
+**Installer worked but something doesn't work later** — Your AI needs XiaoMa context to help. See [How to Get Answers About XiaoMa](./get-answers-about-xiaoma.md) for how to point your AI at the right sources.