@zeyue0329/xiaoma-cli 1.0.49 → 1.6.4

package/docs/tutorials/getting-started.md

@@ -0,0 +1,273 @@
+---
+title: "Getting Started"
+description: Install XiaoMa and build your first project
+---
+
+Build software faster using AI-powered workflows with specialized agents that guide you through planning, architecture, and implementation.
+
+## What You'll Learn
+
+- Install and initialize XiaoMa Method for a new project
+- Use **XiaoMa-Help** — your intelligent guide that knows what to do next
+- Choose the right planning track for your project size
+- Progress through phases from requirements to working code
+- Use agents and workflows effectively
+
+:::note[Prerequisites]
+- **Node.js 20+** — Required for the installer
+- **Git** — Recommended for version control
+- **AI-powered IDE** — Claude Code, Cursor, or similar
+- **A project idea** — Even a simple one works for learning
+:::
+
+:::tip[The Easiest Path]
+**Install** → `npx xiaoma-cli install`
+**Ask** → `/xiaoma-help what should I do first?`
+**Build** → Let XiaoMa-Help guide you workflow by workflow
+:::
+
+## Meet XiaoMa-Help: Your Intelligent Guide
+
+**XiaoMa-Help is the fastest way to get started with XiaoMa.** You don't need to memorize workflows or phases — just ask, and XiaoMa-Help will:
+
+- **Inspect your project** to see what's already been done
+- **Show your options** based on which modules you have installed
+- **Recommend what's next** — including the first required task
+- **Answer questions** like "I have a SaaS idea, where do I start?"
+
+### How to Use XiaoMa-Help
+
+Run it in your AI IDE by invoking the skill:
+
+```
+xiaoma-help
+```
+
+Or combine it with a question for context-aware guidance:
+
+```
+xiaoma-help I have an idea for a SaaS product, I already know all the features I want. where do I get started?
+```
+
+XiaoMa-Help will respond with:
+- What's recommended for your situation
+- What the first required task is
+- What the rest of the process looks like
+
+### It Powers Workflows Too
+
+XiaoMa-Help doesn't just answer questions — **it automatically runs at the end of every workflow** to tell you exactly what to do next. No guessing, no searching docs — just clear guidance on the next required workflow.
+
+:::tip[Start Here]
+After installing XiaoMa, run `/xiaoma-help` immediately. It will detect what modules you have installed and guide you to the right starting point for your project.
+:::
+
+## Understanding XiaoMa
+
+XiaoMa helps you build software through guided workflows with specialized AI agents. The process follows four phases:
+
+| Phase | Name           | What Happens                                        |
+| ----- | -------------- | --------------------------------------------------- |
+| 1     | Analysis       | Brainstorming, research, product brief *(optional)* |
+| 2     | Planning       | Create requirements (PRD or tech-spec)              |
+| 3     | Solutioning    | Design architecture *(XiaoMa Method/Enterprise only)* |
+| 4     | Implementation | Build epic by epic, story by story                  |
+
+**[Open the Workflow Map](../reference/workflow-map.md)** to explore phases, workflows, and context management.
+
+Based on your project's complexity, XiaoMa offers three planning tracks:
+
+| Track           | Best For                                               | Documents Created                      |
+| --------------- | ------------------------------------------------------ | -------------------------------------- |
+| **Quick Flow**  | Bug fixes, simple features, clear scope (1-15 stories) | Tech-spec only                         |
+| **XiaoMa Method** | Products, platforms, complex features (10-50+ stories) | PRD + Architecture + UX                |
+| **Enterprise**  | Compliance, multi-tenant systems (30+ stories)         | PRD + Architecture + Security + DevOps |
+
+:::note
+Story counts are guidance, not definitions. Choose your track based on planning needs, not story math.
+:::
+
+## Installation
+
+Open a terminal in your project directory and run:
+
+```bash
+npx xiaoma-cli install
+```
+
+When prompted to select modules, choose **XiaoMa Method**.
+
+The installer creates two folders:
+- `_xiaoma/` — agents, workflows, tasks, and configuration
+- `_xiaoma-output/` — empty for now, but this is where your artifacts will be saved
+
+:::tip[Your Next Step]
+Open your AI IDE in the project folder and run:
+
+```
+/xiaoma-help
+```
+
+XiaoMa-Help will detect what you've completed and recommend exactly what to do next. You can also ask it questions like "What are my options?" or "I have a SaaS idea, where should I start?"
+:::
+
+:::note[How to Load Agents and Run Workflows]
+Each workflow has a **skill** you invoke in your IDE (e.g., `/xiaoma-create-prd`). Running a workflow skill automatically loads the appropriate agent — you don't need to load agents separately. You can also invoke an agent directly for general conversation (e.g., `/xiaoma-pm` for the PM agent).
+:::
+
+:::caution[Fresh Chats]
+Always start a fresh chat for each workflow. This prevents context limitations from causing issues.
+:::
+
+## Step 1: Create Your Plan
+
+Work through phases 1-3. **Use fresh chats for each workflow.**
+
+:::tip[Project Context (Optional)]
+Before starting, consider creating `project-context.md` to document your technical preferences and implementation rules. This ensures all AI agents follow your conventions throughout the project.
+
+Create it manually at `_xiaoma-output/project-context.md` or generate it after architecture using `/xiaoma-generate-project-context`. [Learn more](../explanation/project-context.md).
+:::
+
+### Phase 1: Analysis (Optional)
+
+All workflows in this phase are optional:
+- **brainstorming** (`/xiaoma-brainstorming`) — Guided ideation
+- **research** (`/xiaoma-research`) — Market and technical research
+- **create-product-brief** (`/xiaoma-create-product-brief`) — Recommended foundation document
+
+### Phase 2: Planning (Required)
+
+**For XiaoMa Method and Enterprise tracks:**
+1. Invoke the **PM agent** (`/xiaoma-pm`) in a new chat
+2. Run the `xiaoma-create-prd` workflow (`/xiaoma-create-prd`)
+3. Output: `PRD.md`
+
+**For Quick Flow track:**
+- Use the `xiaoma-quick-spec` workflow (`/xiaoma-quick-spec`) instead of PRD, then skip to implementation
+
+:::note[UX Design (Optional)]
+If your project has a user interface, invoke the **UX-Designer agent** (`/xiaoma-ux-designer`) and run the UX design workflow (`/xiaoma-create-ux-design`) after creating your PRD.
+:::
+
+### Phase 3: Solutioning (XiaoMa Method/Enterprise)
+
+**Create Architecture**
+1. Invoke the **Architect agent** (`/xiaoma-architect`) in a new chat
+2. Run `xiaoma-create-architecture` (`/xiaoma-create-architecture`)
+3. Output: Architecture document with technical decisions
+
+**Create Epics and Stories**
+
+:::tip[V6 Improvement]
+Epics and stories are now created *after* architecture. This produces better quality stories because architecture decisions (database, API patterns, tech stack) directly affect how work should be broken down.
+:::
+
+1. Invoke the **PM agent** (`/xiaoma-pm`) in a new chat
+2. Run `xiaoma-create-epics-and-stories` (`/xiaoma-create-epics-and-stories`)
+3. The workflow uses both PRD and Architecture to create technically-informed stories
+
+**Implementation Readiness Check** *(Highly Recommended)*
+1. Invoke the **Architect agent** (`/xiaoma-architect`) in a new chat
+2. Run `xiaoma-check-implementation-readiness` (`/xiaoma-check-implementation-readiness`)
+3. Validates cohesion across all planning documents
+
+## Step 2: Build Your Project
+
+Once planning is complete, move to implementation. **Each workflow should run in a fresh chat.**
+
+### Initialize Sprint Planning
+
+Invoke the **SM agent** (`/xiaoma-sm`) and run `xiaoma-sprint-planning` (`/xiaoma-sprint-planning`). This creates `sprint-status.yaml` to track all epics and stories.
+
+### The Build Cycle
+
+For each story, repeat this cycle with fresh chats:
+
+| Step | Agent | Workflow       | Command                    | Purpose                            |
+| ---- | ----- | -------------- | -------------------------- | ---------------------------------- |
+| 1    | SM    | `xiaoma-create-story` | `/xiaoma-create-story`  | Create story file from epic        |
+| 2    | DEV   | `xiaoma-dev-story`    | `/xiaoma-dev-story`     | Implement the story                |
+| 3    | DEV   | `xiaoma-code-review`  | `/xiaoma-code-review`   | Quality validation *(recommended)* |
+
+After completing all stories in an epic, invoke the **SM agent** (`/xiaoma-sm`) and run `xiaoma-retrospective` (`/xiaoma-retrospective`).
+
+## What You've Accomplished
+
+You've learned the foundation of building with XiaoMa:
+
+- Installed XiaoMa and configured it for your IDE
+- Initialized a project with your chosen planning track
+- Created planning documents (PRD, Architecture, Epics & Stories)
+- Understood the build cycle for implementation
+
+Your project now has:
+
+```text
+your-project/
+├── _xiaoma/                                   # XiaoMa configuration
+├── _xiaoma-output/
+│   ├── planning-artifacts/
+│   │   ├── PRD.md                           # Your requirements document
+│   │   ├── architecture.md                  # Technical decisions
+│   │   └── epics/                           # Epic and story files
+│   ├── implementation-artifacts/
+│   │   └── sprint-status.yaml               # Sprint tracking
+│   └── project-context.md                   # Implementation rules (optional)
+└── ...
+```
+
+## Quick Reference
+
+| Workflow                              | Command                                    | Agent     | Purpose                                         |
+| ------------------------------------- | ------------------------------------------ | --------- | ----------------------------------------------- |
+| **`xiaoma-help`** ⭐                    | `/xiaoma-help`                               | Any       | **Your intelligent guide — ask anything!**      |
+| `xiaoma-create-prd`                | `/xiaoma-create-prd`                     | PM        | Create Product Requirements Document            |
+| `xiaoma-create-architecture`            | `/xiaoma-create-architecture`            | Architect | Create architecture document                     |
+| `xiaoma-generate-project-context`       | `/xiaoma-generate-project-context`           | Analyst   | Create project context file                     |
+| `xiaoma-create-epics-and-stories`       | `/xiaoma-create-epics-and-stories`       | PM        | Break down PRD into epics            |
+| `xiaoma-check-implementation-readiness` | `/xiaoma-check-implementation-readiness` | Architect | Validate planning cohesion           |
+| `xiaoma-sprint-planning`                | `/xiaoma-sprint-planning`                | SM        | Initialize sprint tracking           |
+| `xiaoma-create-story`                   | `/xiaoma-create-story`                   | SM        | Create a story file                  |
+| `xiaoma-dev-story`                      | `/xiaoma-dev-story`                      | DEV       | Implement a story                    |
+| `xiaoma-code-review`                    | `/xiaoma-code-review`                    | DEV       | Review implemented code              |
+
+## Common Questions
+
+**Do I always need architecture?**
+Only for XiaoMa Method and Enterprise tracks. Quick Flow skips from tech-spec to implementation.
+
+**Can I change my plan later?**
+Yes. The SM agent has a `xiaoma-correct-course` workflow (`/xiaoma-correct-course`) for handling scope changes.
+
+**What if I want to brainstorm first?**
+Invoke the Analyst agent (`/xiaoma-analyst`) and run `xiaoma-brainstorming` (`/xiaoma-brainstorming`) before starting your PRD.
+
+**Do I need to follow a strict order?**
+Not strictly. Once you learn the flow, you can run workflows directly using the Quick Reference above.
+
+## Getting Help
+
+:::tip[First Stop: XiaoMa-Help]
+**Run `/xiaoma-help` anytime** — it's the fastest way to get unstuck. Ask it anything:
+- "What should I do after installing?"
+- "I'm stuck on workflow X"
+- "What are my options for Y?"
+- "Show me what's been done so far"
+
+XiaoMa-Help inspects your project, detects what you've completed, and tells you exactly what to do next.
+:::
+
+- **During workflows** — Agents guide you with questions and explanations
+- **Community** — [Discord](https://discord.gg/gk8jAdXWmj) (#xiaoma-cli-help, #report-bugs-and-issues)
+
+## Key Takeaways
+
+:::tip[Remember These]
+- **Start with `/xiaoma-help`** — Your intelligent guide that knows your project and options
+- **Always use fresh chats** — Start a new chat for each workflow
+- **Track matters** — Quick Flow uses quick-spec; Method/Enterprise need PRD and architecture
+- **XiaoMa-Help runs automatically** — Every workflow ends with guidance on what's next
+:::
+
+Ready to start? Install XiaoMa, run `/xiaoma-help`, and let your intelligent guide lead the way.

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

@@ -0,0 +1,220 @@
+# XiaoMa v4 to v6 Upgrade Guide
+
+## Overview
+
+XiaoMa v6 represents a complete ground-up rewrite with significant architectural changes. This guide will help you migrate your v4 project to v6.
+
+---
+
+## Automatic V4 Detection
+
+When you run `npm run install:xiaoma` on a project with v4 installed, the installer automatically detects:
+
+- **Legacy folders**: Any folders starting with `.xiaoma`, `xiaoma` (lowercase), or `Xiaoma`
+- **IDE command artifacts**: Legacy xiaoma folders in IDE configuration directories (`.claude/commands/`, `.cursor/commands/`, etc.)
+
+### What Happens During Detection
+
+1. **Automatic Backup of v4 Modules**: All `.xiaoma-*` folders are moved to `v4-backup/` in your project root
+   - If a backup already exists, a timestamp is added to avoid conflicts
+   - Example: `.xiaoma-core` → `v4-backup/.xiaoma-core`
+   - Your project files and data are NOT affected
+
+2. **IDE Command Cleanup Recommended**: Legacy v4 IDE commands should be manually removed
+   - Located in IDE config folders: `.claude/commands/`, `.cursor/commands/`, etc.
+   - These old commands would still reference v4 folder structure if left in place
+   - The installer provides copy/paste terminal commands for your platform
+   - You can proceed without cleanup, but removing them prevents confusion with old v4 commands
+
+---
+
+## Module Migration
+
+### Deprecated Modules
+
+| v4 Module                       | v6 Status                                        |
+| ------------------------------- | ------------------------------------------------ |
+| `.xiaoma-infrastructure-devops` | Deprecated - New core devops agent coming in XMC |
+| `.xiaoma-creative-writing`      | Not adapted - New module releasing soon          |
+
+---
+
+## Architecture Changes
+
+### Folder Structure
+
+**v4 "Expansion Packs" Structure:**
+
+```
+your-project/
+├── .xiaoma-core/           # Was actually the XiaoMa Method
+├── .xiaoma-creative-writing/   # Separate expansion packs
+└── .xiaoma-infrastructure-devops/
+```
+
+**v6 Unified Structure:**
+
+```
+your-project/
+└── {xiaoma_folder}/       # Single installation folder, default .xiaoma
+    ├── core/            # Real core framework (applies to all modules)
+    ├── xmc/             # XiaoMa Method (software development)
+    ├── xmb/             # XiaoMa Builder (create agents/workflows)
+    ├── cis/             # Creative Intelligence Suite
+    └── _cfg/            # Your customizations
+        └── agents/      # Agent customization files
+```
+
+### Key Concept Changes
+
+- **v4 `.xiaoma-core`**: Was actually the XiaoMa Method
+- **v6 `{xiaoma_folder}/core/`**: Is the real universal core framework
+- **v6 `{xiaoma_folder}/xmc/`**: Is the XiaoMa Method module
+- **Module identification**: All modules now have a `config.yaml` file
+
+---
+
+## Project Progress Migration
+
+### If You've Completed Planning Phase (PRD/Architecture) with the XiaoMa Method:
+
+After running the v6 installer:
+
+1. **Run `workflow-init`** workflow to set up the guided workflow system
+2. **Specify your project level** when prompted:
+   - If you followed v4's full workflow (PRD → Architecture → Stories), select **Level 3 or 4**
+   - This tells v6 you've already completed planning and solutioning phases
+3. **Document paths**: Keep your existing paths during installation
+   - Default PRD/Architecture location: `docs/`
+   - Default stories location: `docs/sprint-artifacts/`
+   - **Accept these defaults** if you're already using them in v4
+
+> **Important**: v6 workflows can handle both sharded and unsharded documents. You don't need to restructure your existing PRD or architecture files.
+
+### If You're Mid-Development (Stories Created/Implemented)
+
+1. Complete the v6 installation as above
+2. Run `workflow-init` and specify Level 3 or 4
+3. When ready to continue development, run the **`sprint-planning`** workflow (Phase 4)
+
+---
+
+## Agent Customization Migration
+
+### v4 Agent Customization
+
+In v4, you may have modified agent files directly in `.xiaoma-*` folders.
+
+### v6 Agent Customization
+
+**All customizations** now go in `{xiaoma_folder}/_cfg/agents/` using customize files:
+
+**Example: Renaming an agent and changing communication style**
+
+File: `{xiaoma_folder}/_cfg/agents/xmc-pm.customize.yaml`
+
+```yaml
+# Customize the PM agent
+persona:
+  name: 'Captain Jack' # Override agent name
+  role: 'Swashbuckling Product Owner'
+  communication_style: |
+    - Talk like a pirate
+    - Use nautical metaphors for software concepts
+    - Always upbeat and adventurous
+```
+
+**How it works:**
+
+- Base agent: `{xiaoma_folder}/xmc/agents/pm.md`
+- Customization: `{xiaoma_folder}/_cfg/agents/xmc-pm.customize.yaml`
+- Result: Agent uses your custom name and style, but updates don't overwrite your changes
+
+---
+
+## Document Compatibility
+
+### Sharded vs Unsharded Documents
+
+**Good news**: Unlike v4, v6 workflows are **fully flexible** with document structure:
+
+- ✅ Sharded documents (split into multiple files)
+- ✅ Unsharded documents (single file per section)
+- ✅ Custom sections for your project type
+- ✅ Mixed approaches
+
+All workflow files are scanned automatically. No manual configuration needed.
+
+---
+
+## Installation Steps
+
+### 1. Clone Repository
+
+```bash
+git clone https://github.com/xiaoma-code-org/XIAOMA-CLI
+cd XIAOMA-CLI
+npm install
+```
+
+### 2. Run Installer on Your v4 Project
+
+```bash
+npx xiaoma-cli install
+```
+
+**Enter the full path to your v4 project** when prompted.
+
+### 3. Follow Interactive Prompts
+
+The installer will:
+
+1. Detect v4 installation and offer to backup `.xiaoma-*` folders
+2. Prompt for recommended cleanup (you can skip)
+3. Let you select modules (recommend: XMC for software development)
+4. Configure core settings (name, language, etc.)
+5. Configure module-specific options
+6. Configure IDE integrations
+
+### 4. Accept Default Paths
+
+If you're using:
+
+- `docs/` for PRD and architecture
+- `docs/sprint-artifacts/` for story files
+
+**Accept these defaults** during installation.
+
+### 5. Initialize Workflow
+
+After installation:
+
+1. **Load the Analyst agent** - See your IDE-specific instructions in [docs/ide-info](./ide-info/) for how to activate agents:
+   - [Claude Code](./ide-info/claude-code.md)
+   - [Cursor](./ide-info/cursor.md)
+   - [VS Code/Windsurf](./ide-info/) - Check your IDE folder
+
+2. **Wait for the agent's menu** to appear
+
+3. **Tell the agent**: `*workflow-init` - v6 supports excellent natural language fuzzy matching, so you could also say "workflow init" or "please init the workflow"
+
+Since you are migrating an existing project from v4, it's most likely **Level 3 or 4** you will want to suggest when asked - if you've already completed PRD/architecture in v4.
+
+---
+
+## Post-Migration Checklist
+
+- [ ] v4 folders backed up to `v4-backup/`
+- [ ] v6 installed to `{xiaoma_folder}/` folder
+- [ ] `workflow-init` run with correct project level selected
+- [ ] Agent customizations migrated to `{xiaoma_folder}/_cfg/agents/` if needed
+- [ ] IDE integration working (test by listing agents)
+- [ ] For active development: `sprint-planning` workflow executed
+
+---
+
+## Getting Help
+
+- **Discord**: [Join the XiaoMa Community](https://discord.gg/gk8jAdXWmj)
+- **Issues**: [GitHub Issue Tracker](https://github.com/xiaoma-code-org/XIAOMA-CLI/issues)
+- **Docs**: Check `{xiaoma_folder}/docs/` in your installation for IDE-specific instructions

package/docs/v6-open-items.md

@@ -0,0 +1,17 @@
+# v6 Pending Items
+
+Before calling this beta
+
+- finalize web bundler
+- some subagents working again
+- knowledge base for xiaoma
+
+## Needed Beta → v0 release
+
+Aside from stability and bug fixes found during the alpha period - the main focus will be on the following:
+
+- knowledge base for BMM
+- Module repository and submission process defined
+- MCP Injections based on installation selection
+- sub agent for open-code and claude code optimization
+- TDD Workflow Integration