@zeyue0329/xiaoma-cli 1.6.5 → 1.8.0

package/docs/tutorials/getting-started.md

@@ -1,273 +0,0 @@
----
-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

@@ -1,220 +0,0 @@
-# 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

@@ -1,17 +0,0 @@
-# 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