@zeyue0329/xiaoma-cli 1.0.49 → 1.0.66

package/.playwright-cli/console-2026-05-13T06-36-26-793Z.log

@@ -0,0 +1,2 @@
+[    1116ms] [LOG] %c %s color: yellow; background-color: black; [instance: default] appid: 20006317, userInfo:{"user_unique_id":"7639261564058707976","web_id":"7639261564058707976"} @ https://lf3-data.volccdn.com/obj/data-static/log-sdk/collect/5.0/collect-rangers-v5.2.11.js:0
+[    1116ms] [LOG] %c %s color: yellow; background-color: black; [instance: default] appid: 20006317, sdk is ready, version is 5.2.11_tob, you can report now !!! @ https://lf3-data.volccdn.com/obj/data-static/log-sdk/collect/5.0/collect-rangers-v5.2.11.js:0

package/.playwright-cli/page-2026-05-13T06-36-27-725Z.yml

@@ -0,0 +1 @@
+- img [ref=e7] [cursor=pointer]

package/CLAUDE.md

@@ -4,280 +4,108 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-XiaoMa-CLI is a Universal AI Agent Framework that provides structured prompts, templates, and workflows for AI agents to perform complex tasks in software development. The system supports both IDE environments (Cursor, VS Code, Claude Code) and web-based AI chat interfaces (ChatGPT, Gemini).
-
-**Core Concept**: The framework bundles AI agents with their dependencies (tasks, templates, checklists, data) to enable repeatable workflows for agile development, from ideation through implementation.
+XiaoMa-CLI (`@zeyue0329/xiaoma-cli`) is an AI-driven agile development framework/CLI tool. It installs specialized AI agent personas, workflows, and skills into a user's project directory for use with AI IDEs (Claude Code, Cursor, etc.). Node.js v20+ required.
 
 ## Common Commands
 
-### Build Commands
-```bash
-# Build all bundles (agents, teams, and expansion packs)
-npm run build
-
-# Build only agents
-npm run build:agents
-
-# Build only teams
-npm run build:teams
-
-# List available agents
-npm run list:agents
-```
-
-### Validation and Quality
-```bash
-# Validate all agent and team configurations
-npm run validate
-
-# Format code
-npm run format
-
-# Format check (CI/CD)
-npm run format:check
-
-# Lint code
-npm run lint
-
-# Fix linting issues
-npm run lint:fix
-
-# Auto-fix both formatting and linting
-npm run fix
-
-# Run all quality checks (validate + format:check + lint)
-npm run pre-release
-```
-
-### Version Management
-```bash
-# Bump version patch/minor/major
-npm run version:patch
-npm run version:minor
-npm run version:major
-
-# Bump all versions (including expansion packs)
-npm run version:all:patch
-npm run version:all:minor
-npm run version:all:major
-```
-
-### Installation
 ```bash
-# Interactive installation of xiaoma-core to a project
-npm run install:xiaoma
-# or
-npx @zeyue0329/xiaoma-cli install
+# Quality gate (run before commits — preferred over npm test)
+npm run quality
+
+# Individual checks
+npm run test:schemas        # Agent YAML schema validation (Zod-based)
+npm run test:install        # Installation component tests
+npm run test:refs           # Cross-file reference validation
+npm run validate:schemas    # Schema validation (separate from test)
+npm run validate:refs       # File reference validation (strict mode)
+npm run lint                # ESLint (JS + YAML), zero warnings allowed
+npm run lint:md             # Markdown linting
+npm run format:check        # Prettier check
+npm run format:fix          # Prettier auto-fix
+
+# Test coverage
+npm run test:coverage       # c8 coverage report for schema tests
+
+# Run the CLI locally
+npm run install:xiaoma      # Run install command
+npm run xiaoma:uninstall    # Run uninstall command
+
+# Run a single test file directly
+node test/test-agent-schema.js
+node test/test-file-refs-csv.js
+node test/test-installation-components.js
 ```
 
-### Release Management
-```bash
-# Trigger GitHub release workflow (requires gh CLI)
-npm run release:patch   # Trigger patch release
-npm run release:minor   # Trigger minor release
-npm run release:major   # Trigger major release
-npm run release:watch   # Watch the release workflow
-
-# Preview release notes before publishing
-npm run preview:release
-```
-
-### Utilities
-```bash
-# Flatten/aggregate codebase files for AI context
-npm run flatten
-
-# List all expansion packs
-node tools/cli.js list:expansions
-```
+`npm run quality` order: format:check → lint → lint:md → validate:schemas → test:schemas → test:install → validate:refs.
+`npm test` order: test:schemas → test:refs → test:install → validate:schemas → lint → lint:md → format:check.
 
 ## Architecture
 
-### Core Directory Structure
-
-```
-xiaoma-core/               # The brain of the operation - all agent definitions and resources
-├── agents/               # Individual AI agent definitions (.md files with YAML headers)
-│                         # Some agents also have .yaml files for additional config
-├── agent-teams/          # Team bundles that combine multiple agents (.yaml files)
-├── workflows/            # Prescribed sequences of steps for specific project types (.yaml)
-├── tasks/                # Reusable task definitions for agents to execute
-├── templates/            # Document templates (PRD, architecture, stories, etc.)
-├── checklists/           # Quality assurance checklists
-├── data/                 # Knowledge base and reference materials
-└── core-config.yaml      # Project configuration file
-
-common/                   # Shared resources across multiple contexts
-├── tasks/                # Common tasks shared by multiple agents
-└── utils/                # Utility scripts and helper documents
+### Two-Layer Structure
 
-tools/                    # Build and utility scripts
-├── cli.js                # Main CLI entry point
-├── xiaoma-npx-wrapper.js # NPX execution wrapper
-├── builders/             # Web bundle builders
-│   └── web-builder.js    # Bundles agents + dependencies into .txt files
-├── lib/                  # Core library modules
-│   ├── dependency-resolver.js  # Resolves agent dependencies recursively
-│   └── yaml-utils.js     # YAML parsing and extraction utilities
-├── installer/            # Installation tooling
-│   ├── bin/xiaoma.js     # Installer CLI entry point
-│   └── lib/              # Installer implementation
-├── flattener/            # Document processing utilities (aggregates files for AI)
-├── upgraders/            # Version migration tools (V3 to V4, etc.)
-└── shared/               # Shared utilities across tools
+1. **`src/`** — Content modules (YAML agents, Markdown workflows, skills)
+2. **`tools/`** — CLI implementation (Node.js/CommonJS, installer, validators)
 
-dist/                     # Build output (generated, not in git)
-├── agents/               # Individual agent bundles for web UIs (.txt files)
-└── teams/                # Team bundles for web UIs (.txt files)
-```
-
-### Agent System Architecture
-
-**Agents** are the fundamental building blocks. Each agent:
-- Is defined in a markdown file with embedded YAML configuration
-- Declares dependencies (tasks, templates, checklists, data files)
-- Has a persona, role, and set of commands it can execute
-- Can load project-specific documentation on startup
-
-**Agent Teams** bundle multiple agents together for comprehensive workflows (e.g., `team-all.yaml` includes all agents for full-stack development).
-
-**Build Process** (Web Bundle Creation):
-1. `web-builder.js` reads agent/team definitions
-2. Recursively resolves all dependencies
-3. Concatenates all required files into a single `.txt` bundle
-4. Outputs to `dist/` for upload to web UIs
-
-### Key Components
-
-**DependencyResolver** (`tools/lib/dependency-resolver.js`):
-- Resolves agent dependencies recursively
-- Handles wildcards (e.g., `"*"` includes all agents)
-- Maps dependency references to file paths
-
-**Template System**:
-- Templates are self-contained with embedded LLM instructions
-- Use `{{placeholders}}` for variables and `[[LLM: instructions]]` for AI directives
-- Processed by `create-doc.md` task or directly by agents
-
-**Configuration** (`xiaoma-core/core-config.yaml`):
-- Defines PRD/architecture file locations
-- Configures document sharding patterns
-- Sets up QA locations and dev workflow preferences
-
-## Development Workflow
-
-### When Making Changes to Agents
-
-1. Edit agent markdown files in `xiaoma-core/agents/`
-2. Ensure YAML configuration is valid
-3. Run validation: `npm run validate`
-4. Build bundles: `npm run build`
-5. Test in IDE or by uploading bundle from `dist/`
-
-### When Adding New Tasks/Templates
-
-1. Add file to appropriate `xiaoma-core/` subdirectory
-2. Update agent dependencies to reference new resource
-3. Validate configuration: `npm run validate`
-4. Rebuild: `npm run build`
-
-### When Modifying the Build System
+### Module System
 
-1. Changes to `tools/builders/web-builder.js` affect bundle generation
-2. Changes to `tools/lib/dependency-resolver.js` affect dependency resolution
-3. Test by running `npm run build` and verifying `dist/` output
-4. Validate with `npm run validate`
+Modules are defined by `module.yaml` files with configuration variables, prompts, and directory declarations. Variables use `{variable_name}` interpolation syntax and can reference each other (e.g., `{output_folder}` in path defaults). Core module variables (`user_name`, `communication_language`, etc.) are inherited by other modules:
+- **`src/core/`** — Shared skills and tasks (module code: `core`)
+- **`src/xmc/`** — XiaoMa Method module, the primary agile framework (module code: `xmc`)
+- **`src/utility/`** — Shared agent-components imported by other modules
 
-## Special Considerations
+### Agent System (`src/xmc/agents/`)
 
-### File Reference Conventions
+Agents are YAML files validated against a Zod schema (`tools/schema/`). Each agent defines:
+- `metadata` — id, name, title, icon, module, capabilities
+- `persona` — role, identity, communication_style, principles
+- `menu` — trigger commands pointing to workflow exec targets
+- `prompts` / `critical_actions` — optional
 
-In agent YAML configurations, dependencies are referenced by filename without extension:
-```yaml
-dependencies:
-  tasks:
-    - create-story  # References xiaoma-core/tasks/create-story.md
-```
-
-In web bundles, files are marked with path separators:
-```
-==================== START: .xiaoma-core/tasks/create-story.md ====================
-```
-
-### Agent Activation Flow
-
-When an agent is activated (IDE or Web):
-1. Read entire agent definition file
-2. Load `xiaoma-core/core-config.yaml` for project settings
-3. Adopt the role/persona defined in YAML
-4. Display available commands via `*help`
-5. Load dependencies only when needed for specific tasks
-
-### Expansion Packs
-
-The system supports expansion packs (in `expansion-packs/` directory) that extend core functionality. These are built separately and have their own versioning. Currently, no expansion packs are present in the repository (this is a planned feature).
+### Workflow System (`src/xmc/workflows/`)
 
-### Agent File Format
+Organized by development phase:
+- `1-analysis/` — Brainstorming, research, product brief
+- `2-plan-workflows/` — PRD creation/validation, UX design
+- `3-solutioning/` — Architecture, epics/stories, implementation readiness
+- `4-implementation/` — Sprint planning, story execution, code review, retros
 
-Agents are defined in Markdown files with embedded YAML configuration blocks:
-- **Primary format**: `.md` files in `xiaoma-core/agents/` containing both YAML config and agent instructions
-- **Alternative format**: Some agents have separate `.yaml` files with additional configuration
-- The YAML block defines: agent metadata (name, id, title), persona, commands, and dependencies
-- Dependencies reference other resources by filename without extension (e.g., `create-story` → `tasks/create-story.md`)
+Additional workflow categories:
+- `5-full-pipeline/` — End-to-end automated pipelines from requirements to delivery
+- `xiaoma-quick-flow/` — Lightweight flows for smaller projects (quick-dev, quick-spec)
+- `xiaoma-document-project/`, `xiaoma-generate-project-context/`, `xiaoma-qa-generate-e2e-tests/` — Utility workflows
 
-### Git Hooks and Pre-commit
+Each workflow has: `workflow.md` (entry point with metadata), `steps/` or `steps-{variant}/` directories, and optional `templates/` and `data/` directories.
 
-The project uses Husky and lint-staged for automated quality checks:
-- Pre-commit hooks run formatting and linting on staged files automatically
-- JavaScript/CJS files: ESLint fix + Prettier format
-- YAML files: ESLint fix + Prettier format
-- JSON/Markdown files: Prettier format only
+### CLI (`tools/cli/`)
 
-## Node Version
+- **Entry**: `xiaoma-cli.js` (Commander.js) → wrapped by `tools/xiaoma-npx-wrapper.js`
+- **Commands**: `tools/cli/commands/` — `install.js`, `status.js`, `uninstall.js`
+- **Shared lib**: `tools/cli/lib/` — config loading, file ops, UI helpers, YAML/XML utilities, agent analysis
+- **Installer** (`tools/cli/installers/lib/`): Layered architecture:
+  - `core/` — `installer.js` (main orchestrator), `manifest-generator.js`, `dependency-resolver.js`, `ide-config-manager.js`, `detector.js`
+  - `ide/` — IDE-specific adapters with `_base-ide.js` base class and `_config-driven.js` mixin; `manager.js` selects the right adapter
+  - `modules/` — `manager.js` and `external-manager.js` handle module discovery and external module loading
+  - `custom/` — `handler.js` for user-defined custom modules
+- **UI**: `@clack/prompts` for interactive terminal prompts
 
-This project requires Node.js >= 20.10.0 (see `package.json` engines field).
+### Skills (`src/core/skills/`)
 
-## Main Entry Points
+Reusable capabilities: `xiaoma-help`, `xiaoma-brainstorming`, `xiaoma-distillator`, `xiaoma-party-mode`, editorial review skills, etc.
 
-- **CLI Tool**: `tools/cli.js` (command-line interface for build/validate/upgrade commands)
-- **NPX Wrapper**: `tools/xiaoma-npx-wrapper.js` (entry point for `npx @zeyue0329/xiaoma-cli`)
-- **Web Builder**: `tools/builders/web-builder.js` (bundle generation engine)
-- **Installer**: `tools/installer/bin/xiaoma.js` (interactive project setup tool)
-- **Dependency Resolver**: `tools/lib/dependency-resolver.js` (core dependency resolution logic)
-- **Flattener**: `tools/flattener/main.js` (aggregates codebase files for AI context)
+## Code Conventions
 
-## CLI Commands Reference
-
-The main CLI (`tools/cli.js`) supports these commands:
-
-```bash
-# Build commands
-node tools/cli.js build [--agents-only] [--teams-only] [--expansions-only] [--no-expansions]
-node tools/cli.js build:expansions [--expansion <name>]
-
-# List commands
-node tools/cli.js list:agents
-node tools/cli.js list:expansions
-
-# Validation
-node tools/cli.js validate
-
-# Upgrade (V3 to V4)
-node tools/cli.js upgrade [--project <path>] [--dry-run] [--no-backup]
-```
+- **JS**: CommonJS (`require`/`module.exports`) for all CLI/tool code
+- **YAML**: `.yaml` extension enforced by ESLint (not `.yml`); double quotes preferred
+- **Formatting**: Prettier with 140 char print width, 2-space indent, double quotes in YAML, single quotes in JS
+- **Linting**: ESLint flat config with unicorn, node, yml plugins; `--max-warnings=0`
+- **Schema validation**: Zod for agent YAML validation at `tools/schema/agent.js`
+- **Git hooks**: Husky + lint-staged (runs lint:fix and format:fix on staged files)
+- **Agent triggers**: Must match compound format `"<SHORTCUT> or fuzzy match on <kebab-case>"` where shortcut is auto-derived from the kebab trigger
 
-## Available Agents
+## Testing
 
-Core agents in `xiaoma-core/agents/`:
-- **xiaoma-orchestrator**: Main orchestration agent for teams
-- **xiaoma-master**: Master control agent
-- **po** (Product Owner): PRD creation and product management
-- **pm** (Product Manager): Project management and planning
-- **architect**: System architecture and technical design
-- **dev**: Software development and implementation
-- **qa**: Quality assurance and testing
-- **ux-expert**: User experience and UI design
-- **sm** (Scrum Master): Agile process facilitation
-- **analyst**: Market research and competitive analysis
-- **automation-orchestrator**: Automated workflow coordination
-- **full-requirement-orchestrator**: End-to-end requirement management
+Tests are plain Node.js scripts (no test framework), located in `test/`:
+- `test-agent-schema.js` — Validates all agent YAML against Zod schema; 50 fixtures (18 valid, 32 invalid); targets 100% coverage
+- `test-installation-components.js` — Installation flow verification
+- `test-file-refs-csv.js` — Validates cross-file references in CSV data files
+- Fixtures in `test/fixtures/agent-schema/{valid,invalid}/`

package/LICENSE

@@ -0,0 +1,30 @@
+MIT License
+
+Copyright (c) 2025 BMad Code, LLC
+
+This project incorporates contributions from the open source community.
+See [CONTRIBUTORS.md](CONTRIBUTORS.md) for contributor attribution.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+TRADEMARK NOTICE:
+BMad™, BMad Method™, and BMad Core™ are trademarks of BMad Code, LLC, covering all
+casings and variations (including BMAD, bmad, BMadMethod, BMAD-METHOD, etc.). The use of
+these trademarks in this software does not grant any rights to use the trademarks
+for any other purpose. See [TRADEMARK.md](TRADEMARK.md) for detailed guidelines.

package/README.md

@@ -1,3 +1,128 @@
-伟大的 xiaoma
+# XiaoMa CLI
 
-test 通过
+XiaoMa CLI 是一个 AI 驱动的敏捷开发框架工具。它将专业的 AI 智能体、结构化工作流和可复用技能安装到你的项目中，配合 AI IDE（Claude Code、Cursor 等）使用，实现从需求分析到交付的全生命周期敏捷开发。
+
+## 能力边界
+
+### XiaoMa CLI 能做什么
+
+**智能体协作**
+
+XiaoMa 提供 8 个专业智能体，覆盖敏捷开发的核心角色：
+
+| 智能体 | 角色 | 职责 |
+|--------|------|------|
+| Analyst | 分析师 | 需求调研、产品简报、竞品分析 |
+| PM | 产品经理 | PRD 编写、需求验证、产品规划 |
+| UX Designer | UX 设计师 | 用户体验设计、交互方案 |
+| Architect | 架构师 | 技术架构设计、方案评审 |
+| Dev | 开发者 | 故事实现、代码编写 |
+| QA | 测试工程师 | 测试策略、端到端测试生成 |
+| SM | Scrum Master | Sprint 规划、进度跟踪、回顾 |
+| Quick Flow Solo Dev | 独立开发者 | 快速流程，适合小型项目 |
+
+**结构化工作流（34+）**
+
+按开发阶段组织，覆盖完整的软件交付生命周期：
+
+- **分析阶段** — 需求管道、产品简报创建、市场调研
+- **规划阶段** — PRD 创建/编辑/验证、UX 设计
+- **方案阶段** — 架构设计、Epic 和 Story 拆分、实施就绪检查
+- **实施阶段** — Sprint 规划、Story 开发、代码评审、回顾、Sprint 状态跟踪
+- **全流程管道** — 端到端自动化，从需求到交付一键执行
+
+**可复用技能（11 个）**
+
+| 技能 | 用途 |
+|------|------|
+| `xiaoma-help` | 智能导航，告诉你下一步该做什么 |
+| `xiaoma-brainstorming` | 结构化头脑风暴 |
+| `xiaoma-party-mode` | 多智能体协作讨论 |
+| `xiaoma-distillator` | 信息提炼和摘要 |
+| `xiaoma-editorial-review-prose` | 文案内容审校 |
+| `xiaoma-editorial-review-structure` | 文档结构审校 |
+| `xiaoma-review-adversarial-general` | 对抗性审查 |
+| `xiaoma-review-edge-case-hunter` | 边界场景审查 |
+| `xiaoma-advanced-elicitation` | 高级需求引导 |
+| `xiaoma-index-docs` | 文档索引 |
+| `xiaoma-shard-doc` | 文档分片处理 |
+
+**规模自适应**
+
+根据项目复杂度自动调整规划深度——从小型 Bug 修复到企业级系统，无需手动配置。
+
+### XiaoMa CLI 不能做什么
+
+- **不是代码生成器** — 不会直接生成完整的应用代码，而是通过结构化流程引导你和 AI 协作产出高质量代码
+- **不替代 AI IDE** — 需要配合 Claude Code、Cursor 等 AI IDE 使用，本身不提供代码编辑能力
+- **不是项目管理工具** — 不替代 Jira、Linear 等，而是补充敏捷流程中的 AI 协作环节
+- **不处理部署运维** — 聚焦于开发生命周期，不涉及 CI/CD 管道配置、服务器部署等运维任务
+- **不支持非 Node.js 环境** — 安装工具本身需要 Node.js v20+（但生成的工作产物不限语言）
+
+## 安装与使用
+
+### 环境要求
+
+- [Node.js](https://nodejs.org) v20 或更高版本
+
+### 快速安装
+
+```bash
+npx xiaoma-cli install
+```
+
+按照交互式提示选择模块和目标 IDE，安装完成后在项目目录中打开你的 AI IDE 即可开始使用。
+
+### 非交互式安装（CI/CD）
+
+```bash
+npx xiaoma-cli install --directory /path/to/project --modules xmc --tools claude-code --yes
+```
+
+### CLI 命令
+
+| 命令 | 说明 |
+|------|------|
+| `npx xiaoma-cli install` | 安装 XiaoMa 到目标项目 |
+| `npx xiaoma-cli status` | 查看当前安装状态 |
+| `npx xiaoma-cli uninstall` | 卸载 XiaoMa |
+
+### 使用流程
+
+1. **安装** — 在项目中运行 `npx xiaoma-cli install`
+2. **启动 AI IDE** — 打开 Claude Code、Cursor 等，进入项目目录
+3. **获取指引** — 使用 `xiaoma-help` 了解当前可用的工作流和下一步操作
+4. **按阶段推进** — 从分析到实施，按工作流引导逐步完成开发
+
+### 使用示例
+
+```
+# 在 AI IDE 中使用以下命令
+
+# 获取帮助
+xiaoma-help
+
+# 获取特定场景的帮助
+xiaoma-help 我刚完成了架构设计，接下来该做什么？
+
+# 创建产品简报
+@analyst create-product-brief
+
+# 创建 PRD
+@pm create-prd
+
+# 架构设计
+@architect create-architecture
+
+# Sprint 规划
+@sm sprint-planning
+
+# 开发 Story
+@dev dev-story
+
+# 代码评审
+@dev code-review
+
+# 多智能体协作讨论
+xiaoma-party-mode
+```

package/demo/xiaoma-bug-circle-resolve/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: xiaoma-bug-circle-resolve
+description: '循环处理所有AI测试平台推送的新增状态Bug，每次处理前清空上下文避免噪声干扰，逐个调用xiaoma-bug-resolve技能修复，直到所有新增Bug处理完毕。Use when the user says "循环处理bug", "批量修复bug", "resolve all bugs", or "circle resolve bugs".'
+---
+
+Follow the instructions in [workflow.md](workflow.md).