@zeyue0329/xiaoma-cli 1.0.48 → 1.6.4

package/XIAOMA-CLI-GUIDE.md

@@ -0,0 +1,512 @@
+# XiaoMa-Cli 使用指南
+
+> **XiaoMa-Cli** (`@zeyue0329/xiaoma-cli`) — AI 驱动的敏捷开发框架，通过专业化 AI Agent 和引导式工作流，帮助你从创意构思到代码实现，完成整个软件开发流程。
+
+---
+
+## 目录
+
+1. [项目概述](#项目概述)
+2. [环境要求](#环境要求)
+3. [安装与初始化](#安装与初始化)
+4. [核心概念](#核心概念)
+5. [Agent 角色一览](#agent-角色一览)
+6. [四阶段工作流](#四阶段工作流)
+7. [三种规划路径](#三种规划路径)
+8. [XiaoMa-Help 智能引导](#xiaoma-help-智能引导)
+9. [Phase 1: 分析阶段](#phase-1-分析阶段)
+10. [Phase 2: 规划阶段](#phase-2-规划阶段)
+11. [Phase 3: 方案设计阶段](#phase-3-方案设计阶段)
+12. [Phase 4: 实施阶段](#phase-4-实施阶段)
+13. [核心工具模块](#核心工具模块)
+14. [Quick Flow 快速开发](#quick-flow-快速开发)
+15. [项目上下文配置](#项目上下文配置)
+16. [工作流命令速查表](#工作流命令速查表)
+17. [常见问题](#常见问题)
+
+---
+
+## 项目概述
+
+XiaoMa-Cli 是一个通用 AI Agent 开发框架，基于 XiaoMa 方法论构建。它提供了 8+ 个专业化 AI Agent 角色和 35+ 个引导式工作流，覆盖从产品分析、需求规划、架构设计到代码实现的全生命周期。
+
+框架的核心理念是：通过 AI Agent 与人类协作的方式，让开发过程更加结构化、高效且高质量。每个 Agent 拥有独立的角色定位、专业知识和沟通风格，在各自擅长的领域提供专家级指导。
+
+**版本**: 1.6.4
+**协议**: MIT
+**包名**: `@zeyue0329/xiaoma-cli`
+
+---
+
+## 环境要求
+
+- **Node.js 20+** — 安装器运行所需
+- **Git** — 推荐用于版本管理
+- **AI IDE** — Claude Code（推荐）、Cursor 或其他支持自定义 system prompt 的 AI 编码工具
+- **一个项目想法** — 即使是简单的也可以用于学习
+
+---
+
+## 安装与初始化
+在项目根目录下执行安装命令：
+
+```bash
+npx xiaoma-cli install
+```
+
+安装过程中选择 **XiaoMa Method** 模块。安装完成后会创建两个目录：
+
+```
+your-project/
+├── _xiaoma/           # Agent、工作流、任务和配置文件
+│   ├── core/          # 核心平台模块（通用工作流和任务）
+│   └── xmc/           # XiaoMa Method 主模块（Agent 和专用工作流）
+├── _xiaoma-output/    # 产出物存放目录（初始为空）
+│   ├── planning-artifacts/        # 规划产出物（PRD、架构、Epics 等）
+│   ├── implementation-artifacts/  # 实施产出物（Sprint 状态、Story 文件）
+│   └── project-knowledge/         # 项目知识库
+└── ...
+```
+
+其他 CLI 命令：
+
+```bash
+npx xiaoma-cli uninstall   # 卸载
+npx xiaoma-cli install     # 重新安装/更新
+```
+
+---
+
+## 核心概念
+
+### 四阶段流程
+XiaoMa 将软件开发分为四个有序阶段：
+
+| 阶段 | 名称 | 说明 |
+|------|------|------|
+| Phase 1 | **Analysis（分析）** | 头脑风暴、市场/技术调研、产品简介（可选） |
+| Phase 2 | **Planning（规划）** | 创建 PRD 或技术规格（必需） |
+| Phase 3 | **Solutioning（方案设计）** | 架构设计、Epic/Story 拆分（XiaoMa Method/Enterprise） |
+| Phase 4 | **Implementation（实施）** | Sprint 规划，按 Epic → Story 逐个实现 |
+
+### Agent 驱动
+
+每个工作流由特定的 Agent 角色驱动。运行工作流时会自动加载对应的 Agent，你也可以直接与 Agent 对话进行自由交流。
+
+### Skill 调用机制
+
+每个工作流对应一个 Skill 命令（例如 `/xiaoma-create-prd`）。在 AI IDE 中调用 Skill 即可启动对应工作流，无需手动加载 Agent。
+
+### 重要原则
+
+- **每个工作流使用独立的新对话**：避免上下文溢出
+- **按阶段推进**：Planning → Solutioning → Implementation 有依赖关系
+- **XiaoMa-Help 随时可用**：不确定下一步做什么时，运行 `/xiaoma-help`
+
+---
+
+## Agent 角色一览
+XiaoMa 内置了 8 个专业化 Agent，各自负责开发流程中的不同环节：
+
+| 图标 | 名字 | 角色 | 核心能力 | 关键阶段 |
+|------|------|------|----------|----------|
+| 📊 | Mary | **Business Analyst（业务分析师）** | 市场调研、竞争分析、需求提炼、领域专业知识 | Phase 1 |
+| 📋 | John | **Product Manager（产品经理）** | PRD 创建、需求发现、利益相关方对齐、用户访谈 | Phase 2-3 |
+| 🎨 | Sally | **UX Designer（UX 设计师）** | 用户研究、交互设计、UI 模式、体验策略 | Phase 2 |
+| 🏗️ | Winston | **Architect（架构师）** | 分布式系统、云基础设施、API 设计、可扩展模式 | Phase 3 |
+| 🏃 | Bob | **Scrum Master** | Sprint 规划、Story 准备、敏捷仪式、Backlog 管理 | Phase 4 |
+| 💻 | Amelia | **Developer（开发者）** | Story 执行、测试驱动开发、代码实现 | Phase 4 |
+| 🧪 | Quinn | **QA Engineer（QA 工程师）** | 测试自动化、API 测试、E2E 测试、覆盖率分析 | Phase 4 |
+| 🚀 | Barry | **Quick Flow Solo Dev（快速开发者）** | 快速规格创建、精益实现、最少流程 | 任何时候 |
+
+此外还有功能性角色：
+
+- **Tech Writer（技术写作者）** — 文档撰写、标准更新、Mermaid 图表生成、文档验证
+- **XiaoMa Master** — 主执行器、知识管家、工作流编排
+- **Party Mode Facilitator** — 多 Agent 讨论编排
+- **XiaoMa-Help** — 智能引导，检测项目状态并推荐下一步操作
+
+> **直接加载 Agent**: 除了通过工作流自动加载 Agent 外，你也可以用斜杠命令直接加载任何 Agent 进行自由对话，例如 `/xiaoma-pm`（加载 PM 智能体 John）、`/xiaoma-architect`（加载架构师 Winston）等。完整命令列表见[工作流命令速查表](#工作流命令速查表)。
+
+---
+
+## 四阶段工作流
+
+### Phase 1: 分析阶段
+此阶段的所有工作流均为**可选**，用于在正式规划前理清思路。
+
+| 代码 | 工作流 | 命令 | Agent | 说明 |
+|------|--------|------|-------|------|
+| BP | Brainstorm Project | `/xiaoma-brainstorming` | Analyst (Mary) | 专家引导的头脑风暴，支持多种技术 |
+| MR | Market Research | `/xiaoma-market-research` | Analyst (Mary) | 市场分析、竞争格局、客户需求和趋势 |
+| DR | Domain Research | `/xiaoma-domain-research` | Analyst (Mary) | 行业领域深度调研、专业术语 |
+| TR | Technical Research | `/xiaoma-technical-research` | Analyst (Mary) | 技术可行性、架构选项、实现方案 |
+| CB | Create Brief | `/xiaoma-create-product-brief` | Analyst (Mary) | 引导式产品简介创建 |
+
+### Phase 2: 规划阶段
+
+此阶段包含**必需**的核心工作流（PRD 创建）。
+
+| 代码 | 工作流 | 命令 | Agent | 说明 |
+|------|--------|------|-------|------|
+| CP | Create PRD ⭐ | `/xiaoma-create-prd` | PM (John) | 专家引导创建产品需求文档（必需） |
+| VP | Validate PRD | `/xiaoma-validate-prd` | PM (John) | 验证 PRD 完整性和一致性 |
+| EP | Edit PRD | `/xiaoma-edit-prd` | PM (John) | 改进和增强现有 PRD |
+| CU | Create UX | `/xiaoma-create-ux-design` | UX Designer (Sally) | UX 设计（有 UI 的项目推荐） |
+
+### Phase 3: 方案设计阶段
+仅适用于 XiaoMa Method 和 Enterprise 路径。
+
+| 代码 | 工作流 | 命令 | Agent | 说明 |
+|------|--------|------|-------|------|
+| CA | Create Architecture ⭐ | `/xiaoma-create-architecture` | Architect (Winston) | 引导式架构设计（必需） |
+| CE | Create Epics & Stories ⭐ | `/xiaoma-create-epics-and-stories` | PM (John) | Epic 和 Story 拆分（必需） |
+| IR | Implementation Readiness ⭐ | `/xiaoma-check-implementation-readiness` | Architect (Winston) | 实施就绪检查（强烈推荐） |
+
+**执行顺序**: Create Architecture → Create Epics & Stories → Implementation Readiness Check
+
+> V6 改进：Epics 和 Stories 现在在架构设计**之后**创建，这样可以根据架构决策（数据库、API 模式、技术栈）产出更高质量的 Story。
+
+### Phase 4: 实施阶段
+
+这是实际编码阶段，按 Sprint → Epic → Story 的层级逐步推进。
+
+| 代码 | 工作流 | 命令 | Agent | 说明 |
+|------|--------|------|-------|------|
+| SP | Sprint Planning ⭐ | `/xiaoma-sprint-planning` | SM (Bob) | 生成 Sprint 计划（必需，启动实施） |
+| SS | Sprint Status | `/xiaoma-sprint-status` | SM (Bob) | 汇总 Sprint 状态并路由到下一个工作流 |
+| CS | Create Story ⭐ | `/xiaoma-create-story` | SM (Bob) | 为实现准备 Story 文件（必需） |
+| VS | Validate Story | `/xiaoma-create-story` (Validate) | SM (Bob) | 验证 Story 就绪度 |
+| DS | Dev Story ⭐ | `/xiaoma-dev-story` | Dev (Amelia) | 执行 Story 实现和测试（必需） |
+| CR | Code Review | `/xiaoma-code-review` | Dev (Amelia) | 代码审查 |
+| QA | QA Test | `/xiaoma-qa-generate-e2e-tests` | QA (Quinn) | 生成自动化测试 |
+| ER | Retrospective | `/xiaoma-retrospective` | SM (Bob) | Epic 完成后回顾 |
+**Story 构建循环**:
+
+```
+CS (Create Story) → VS (Validate Story) → DS (Dev Story) → CR (Code Review)
+     ↑                                                            │
+     └────── 如果 Review 通过 → 下一个 Story ──────────────────────┘
+             如果 Review 不通过 → 返回 DS 修复
+```
+
+完成一个 Epic 的所有 Story 后，运行 `ER` (Retrospective)，然后开始下一个 Epic。
+
+---
+
+## 三种规划路径
+
+根据项目复杂度选择合适的规划路径：
+
+### Quick Flow（快速流程）
+
+**适用场景**: Bug 修复、简单功能、明确范围（1-15 个 Story）
+
+- 使用 `/xiaoma-quick-spec` 创建技术规格
+- 使用 `/xiaoma-quick-dev` 直接开发
+- 跳过 PRD 和架构设计，最少流程开销
+- 由 Quick Flow Solo Dev (Barry) 统一处理
+
+### XiaoMa Method（标准方法）
+
+**适用场景**: 产品开发、平台构建、复杂功能（10-50+ 个 Story）
+
+- 完整四阶段流程
+- 产出物：PRD + 架构文档 + UX 设计 + Epics/Stories
+- 由多个专业 Agent 协作完成
+
+### Enterprise（企业级）
+
+**适用场景**: 合规要求、多租户系统（30+ 个 Story）
+
+- 基于 XiaoMa Method 扩展
+- 额外产出物：安全审查 + DevOps 规划
+- 更严格的审查和验证流程
+
+> Story 数量仅供参考，不是硬性标准。根据规划需要选择路径，而非 Story 数量。
+---
+
+## XiaoMa-Help 智能引导
+
+XiaoMa-Help 是最快上手的方式。它会自动检测项目状态，告诉你下一步该做什么。
+
+**使用方式**:
+
+```
+/xiaoma-help
+```
+
+或附带问题：
+
+```
+/xiaoma-help 我有一个 SaaS 产品的想法，应该从哪里开始？
+```
+
+**它能做什么**:
+
+- 检查项目中已完成的步骤
+- 根据安装的模块显示可用选项
+- 推荐下一个必需的任务
+- 回答关于 XiaoMa Method 的问题
+- 在每个工作流结束时自动运行，引导下一步
+
+---
+
+## 核心工具模块
+
+除了主要的四阶段工作流，XiaoMa 还提供一系列可在任意时候使用的工具：
+### 随时可用的工作流
+
+| 代码 | 工作流 | 命令 | 说明 |
+|------|--------|------|------|
+| DP | Document Project | `/xiaoma-document-project` | 分析现有项目，生成有用的文档 |
+| GPC | Generate Project Context | `/xiaoma-generate-project-context` | 扫描代码库生成 LLM 优化的 project-context.md |
+| QS | Quick Spec | `/xiaoma-quick-spec` | Quick Flow 技术规格（快速小任务） |
+| QD | Quick Dev | `/xiaoma-quick-dev` | Quick Flow 快速开发（无需复杂规划） |
+| QQ | Quick Dev New Preview | `/xiaoma-quick-dev-new-preview` | 统一快速流程（实验性）：澄清→计划→实现→审查 |
+| CC | Correct Course | `/xiaoma-correct-course` | 应对重大变更，可能需要重做 PRD/架构/Sprint |
+| WD | Write Document | 直接与 Tech Writer 对话 | 按文档最佳实践撰写文档 |
+| US | Update Standards | 直接与 Tech Writer 对话 | 更新文档标准配置 |
+| MG | Mermaid Generate | 直接与 Tech Writer 对话 | 生成 Mermaid 图表 |
+| VD | Validate Document | 直接与 Tech Writer 对话 | 按标准和最佳实践审查文档 |
+| EC | Explain Concept | 直接与 Tech Writer 对话 | 用示例和图表解释复杂技术概念 |
+
+### 核心平台工具
+
+| 代码 | 工具 | 命令 | 说明 |
+|------|------|------|------|
+| BH | XiaoMa-Help | `/xiaoma-help` | 智能引导，随时获取帮助 |
+| BSP | Brainstorming | `/xiaoma-brainstorming` | 交互式创意生成 |
+| PM | Party Mode | `/xiaoma-party-mode` | 多 Agent 讨论编排 |
+| ID | Index Docs | `/xiaoma-index-docs` | 为 LLM 创建轻量级文档索引 |
+| SD | Shard Document | `/xiaoma-shard-doc` | 将大文档拆分为小文件 |
+| EP | Editorial Review - Prose | `/xiaoma-editorial-review-prose` | 行文清晰度、语气审查 |
+| ES | Editorial Review - Structure | `/xiaoma-editorial-review-structure` | 文档结构优化 |
+| AR | Adversarial Review | `/xiaoma-review-adversarial-general` | 对抗性审查，发现问题和弱点 |
+| ECH | Edge Case Hunter | `/xiaoma-review-edge-case-hunter` | 边界条件和边缘情况检测 |
+| AE | Advanced Elicitation | `/xiaoma-advanced-elicitation` | 推动 LLM 重新审视并改进其输出 |
+| VW | Validate Workflow | `/xiaoma-validate-workflow` | 验证工作流定义的完整性和正确性 |
+
+### 直接加载 Agent 命令
+
+你可以通过以下命令直接加载任意 Agent 进行自由对话（无需启动工作流）：
+
+| 命令 | Agent |
+|------|-------|
+| `/xiaoma-master` | XiaoMa Master 🧙 |
+| `/xiaoma-analyst` | Analyst (Mary) 📊 |
+| `/xiaoma-pm` | PM (John) 📋 |
+| `/xiaoma-ux-designer` | UX Designer (Sally) 🎨 |
+| `/xiaoma-architect` | Architect (Winston) 🏗️ |
+| `/xiaoma-sm` | SM (Bob) 🏃 |
+| `/xiaoma-dev` | Developer (Amelia) 💻 |
+| `/xiaoma-qa` | QA Engineer (Quinn) 🧪 |
+| `/xiaoma-tech-writer` | Tech Writer (Paige) 📚 |
+| `/xiaoma-quick-flow-solo-dev` | Quick Flow Solo Dev (Barry) 🚀 |
+
+---
+
+## Quick Flow 快速开发
+Quick Flow 是为简单任务设计的精简路径，跳过复杂的多阶段规划流程。
+
+**适用场景**:
+- Bug 修复和小型补丁
+- 简单功能添加
+- 工具脚本编写
+- 在成熟项目中添加遵循已有模式的功能
+
+**使用方式**:
+
+1. **创建技术规格**: `/xiaoma-quick-spec` — 通过 Barry (Quick Flow Solo Dev) 引导，快速生成技术规格
+2. **快速开发**: `/xiaoma-quick-dev` — 基于技术规格直接实现
+
+或者使用统一的实验性工作流：
+
+```
+/xiaoma-quick-dev-new-preview
+```
+
+此命令将澄清意图、计划、实现、审查合并为一个连续流程。
+
+> 如果用户在使用过程中觉得标准 XiaoMa Method 流程过于繁重，可以随时切换到 Quick Flow。
+
+---
+
+## 项目上下文配置
+
+`project-context.md` 是一个可选但推荐的配置文件，用于记录项目的技术偏好和实现规则，确保所有 AI Agent 在整个开发过程中遵循一致的约定。
+
+**创建方式**:
+
+- **自动生成**（推荐）: 运行 `/xiaoma-generate-project-context`，Analyst Agent 会扫描现有代码库自动生成
+- **手动创建**: 在 `_xiaoma-output/project-context.md` 手动编写
+
+**典型内容**:
+- 使用的编程语言和框架
+- 代码规范和命名约定
+- 项目结构规则
+- 测试策略偏好
+- 已有的架构模式
+
+**尤其推荐用于**:
+- 棕地项目（已有代码库的项目）
+- Quick Flow 开发（帮助 Barry 理解项目规范）
+
+---
+
+## 工作流命令速查表
+### 完整生命周期（XiaoMa Method 路径）
+
+```
+安装 → xiaoma-help → 选择路径
+         │
+         ├── Quick Flow 路径:
+         │     quick-spec → quick-dev → 完成
+         │
+         └── XiaoMa Method 路径:
+               │
+               ├── Phase 1 (可选):
+               │     brainstorming → research → create-product-brief
+               │
+               ├── Phase 2 (必需):
+               │     create-prd → [validate-prd] → [create-ux-design]
+               │
+               ├── Phase 3 (必需):
+               │     create-architecture → create-epics-and-stories → check-implementation-readiness
+               │
+               └── Phase 4 (必需):
+                     sprint-planning → { create-story → dev-story → code-review } × N → retrospective
+```
+
+### 按 Agent 分类
+
+**Analyst (Mary) 📊**
+| 命令 | 说明 |
+|------|------|
+| `/xiaoma-brainstorming` | 头脑风暴 |
+| `/xiaoma-market-research` | 市场调研 |
+| `/xiaoma-domain-research` | 领域调研 |
+| `/xiaoma-technical-research` | 技术调研 |
+| `/xiaoma-create-product-brief` | 创建产品简介 |
+| `/xiaoma-document-project` | 文档化项目 |
+| `/xiaoma-generate-project-context` | 生成项目上下文 |
+**PM (John) 📋**
+| 命令 | 说明 |
+|------|------|
+| `/xiaoma-create-prd` | 创建 PRD（必需） |
+| `/xiaoma-validate-prd` | 验证 PRD |
+| `/xiaoma-edit-prd` | 编辑 PRD |
+| `/xiaoma-create-epics-and-stories` | 创建 Epic 和 Story |
+
+**UX Designer (Sally) 🎨**
+| 命令 | 说明 |
+|------|------|
+| `/xiaoma-create-ux-design` | 创建 UX 设计 |
+
+**Architect (Winston) 🏗️**
+| 命令 | 说明 |
+|------|------|
+| `/xiaoma-create-architecture` | 创建架构文档（必需） |
+| `/xiaoma-check-implementation-readiness` | 实施就绪检查 |
+
+**Scrum Master (Bob) 🏃**
+| 命令 | 说明 |
+|------|------|
+| `/xiaoma-sprint-planning` | Sprint 规划（必需） |
+| `/xiaoma-sprint-status` | Sprint 状态汇总 |
+| `/xiaoma-create-story` | 创建 Story（必需） |
+| `/xiaoma-correct-course` | 应对重大变更 |
+| `/xiaoma-retrospective` | Epic 回顾 |
+
+**Developer (Amelia) 💻**
+| 命令 | 说明 |
+|------|------|
+| `/xiaoma-dev-story` | 实现 Story（必需） |
+| `/xiaoma-code-review` | 代码审查 |
+**QA Engineer (Quinn) 🧪**
+| 命令 | 说明 |
+|------|------|
+| `/xiaoma-qa-generate-e2e-tests` | 生成自动化 API/E2E 测试 |
+
+**Quick Flow Solo Dev (Barry) 🚀**
+| 命令 | 说明 |
+|------|------|
+| `/xiaoma-quick-spec` | 快速技术规格 |
+| `/xiaoma-quick-dev` | 快速开发 |
+| `/xiaoma-quick-dev-new-preview` | 统一快速流程（实验性） |
+
+**XiaoMa Master 🧙**
+| 命令 | 说明 |
+|------|------|
+| `/xiaoma-master` | 主执行器、知识管家、工作流编排 |
+| `/xiaoma-advanced-elicitation` | 推动 LLM 重新审视并改进输出 |
+| `/xiaoma-validate-workflow` | 验证工作流定义 |
+
+---
+
+## 常见问题
+
+**Q: 是否一定需要架构设计？**
+只有 XiaoMa Method 和 Enterprise 路径需要。Quick Flow 从技术规格直接进入实现阶段。
+
+**Q: 规划完成后可以修改吗？**
+可以。使用 SM Agent 的 `/xiaoma-correct-course` 工作流处理范围变更，它会评估是否需要更新 PRD、重做架构、调整 Sprint 计划等。
+
+**Q: 想先头脑风暴怎么办？**
+运行 `/xiaoma-brainstorming`，Analyst Agent (Mary) 会引导你通过多种技术进行创意探索，生成结构化的头脑风暴报告。
+
+**Q: 必须严格按顺序执行吗？**
+不是绝对的。一旦熟悉流程后，你可以直接使用命令速查表中的任何工作流。但 Phase 2-4 的核心工作流有依赖关系，建议按序推进。
+
+**Q: 如何在已有项目上使用？**
+1. 在项目根目录运行 `npx xiaoma-cli install`
+2. 运行 `/xiaoma-generate-project-context` 让 AI 理解现有代码
+3. 根据需要从任意阶段开始
+
+**Q: Party Mode 是什么？**
+Party Mode (`/xiaoma-party-mode`) 让你编排多个 Agent 同时参与讨论。当你需要多视角分析某个问题时非常有用，例如让 PM、Architect 和 Dev 一起讨论技术方案。
+
+**Q: 遇到困难怎么办？**
+随时运行 `/xiaoma-help`，它会检测项目当前状态并告诉你最合适的下一步操作。
+
+---
+
+## 产出物目录结构
+完整项目开发后的典型产出结构：
+
+```
+your-project/
+├── _xiaoma/                                    # XiaoMa 配置（安装生成）
+│   ├── core/                                   # 核心平台模块
+│   │   ├── workflows/                          # 通用工作流（brainstorming, party-mode 等）
+│   │   └── tasks/                              # 通用任务（index-docs, shard-doc 等）
+│   ├── xmc/                                    # XiaoMa Method 主模块
+│   │   ├── agents/                             # Agent 定义文件
+│   │   ├── workflows/                          # 阶段工作流
+│   │   │   ├── 1-analysis/                     # 分析阶段工作流
+│   │   │   ├── 2-plan-workflows/               # 规划阶段工作流
+│   │   │   ├── 3-solutioning/                  # 方案设计工作流
+│   │   │   ├── 4-implementation/               # 实施阶段工作流
+│   │   │   └── xiaoma-quick-flow/              # Quick Flow 工作流
+│   │   └── data/                               # 模板和数据文件
+│   └── _memory/                                # Agent 记忆存储
+├── _xiaoma-output/                             # 所有产出物
+│   ├── planning-artifacts/                     # 规划产出
+│   │   ├── PRD.md                              # 产品需求文档
+│   │   ├── architecture.md                     # 架构设计文档
+│   │   ├── ux-design.md                        # UX 设计文档
+│   │   └── epics/                              # Epic 和 Story 文件
+│   │       ├── epic-1/
+│   │       │   ├── story-1.md
+│   │       │   └── story-2.md
+│   │       └── epic-2/
+│   ├── implementation-artifacts/               # 实施产出
+│   │   └── sprint-status.yaml                  # Sprint 追踪状态
+│   ├── project-knowledge/                      # 项目知识库
+│   └── project-context.md                      # 项目上下文（可选）
+└── ...                                         # 你的项目代码
+```
+
+---
+
+*本文档基于 XiaoMa-Cli v1.6.4 编写。如需获取最新信息，请运行 `/xiaoma-help` 或查看项目文档。*

package/{.idea/XiaoMa-Cli.iml → XiaoMa-Cli.iml}

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<module type="JAVA_MODULE" version="4">
+<module type="WEB_MODULE" version="4">
   <component name="NewModuleRootManager" inherit-compiler-output="true">
     <exclude-output />
     <content url="file://$MODULE_DIR$" />

package/custom/src/agents/commit-poet/commit-poet.agent.yaml

@@ -0,0 +1,129 @@
+agent:
+  metadata:
+    id: .xiaoma/agents/commit-poet/commit-poet.md
+    name: "Inkwell Von Comitizen"
+    title: "Commit Message Artisan"
+    icon: "📜"
+    type: simple
+
+  persona:
+    role: |
+      I am a Commit Message Artisan - transforming code changes into clear, meaningful commit history.
+
+    identity: |
+      I understand that commit messages are documentation for future developers. Every message I craft tells the story of why changes were made, not just what changed. I analyze diffs, understand context, and produce messages that will still make sense months from now.
+
+    communication_style: "Poetic drama and flair with every turn of a phrase. I transform mundane commits into lyrical masterpieces, finding beauty in your code's evolution."
+
+    principles:
+      - Every commit tells a story - the message should capture the "why"
+      - Future developers will read this - make their lives easier
+      - Brevity and clarity work together, not against each other
+      - Consistency in format helps teams move faster
+
+  prompts:
+    - id: write-commit
+      content: |
+        <instructions>
+        I'll craft a commit message for your changes. Show me:
+        - The diff or changed files, OR
+        - A description of what you changed and why
+
+        I'll analyze the changes and produce a message in conventional commit format.
+        </instructions>
+
+        <process>
+        1. Understand the scope and nature of changes
+        2. Identify the primary intent (feature, fix, refactor, etc.)
+        3. Determine appropriate scope/module
+        4. Craft subject line (imperative mood, concise)
+        5. Add body explaining "why" if non-obvious
+        6. Note breaking changes or closed issues
+        </process>
+
+        Show me your changes and I'll craft the message.
+
+    - id: analyze-changes
+      content: |
+        <instructions>
+        - Let me examine your changes before we commit to words.
+        - I'll provide analysis to inform the best commit message approach.
+        - Diff all uncommited changes and understand what is being done.
+        - Ask user for clarifications or the what and why that is critical to a good commit message.
+        </instructions>
+
+        <analysis_output>
+        - **Classification**: Type of change (feature, fix, refactor, etc.)
+        - **Scope**: Which parts of codebase affected
+        - **Complexity**: Simple tweak vs architectural shift
+        - **Key points**: What MUST be mentioned
+        - **Suggested style**: Which commit format fits best
+        </analysis_output>
+
+        Share your diff or describe your changes.
+
+    - id: improve-message
+      content: |
+        <instructions>
+        I'll elevate an existing commit message. Share:
+        1. Your current message
+        2. Optionally: the actual changes for context
+        </instructions>
+
+        <improvement_process>
+        - Identify what's already working well
+        - Check clarity, completeness, and tone
+        - Ensure subject line follows conventions
+        - Verify body explains the "why"
+        - Suggest specific improvements with reasoning
+        </improvement_process>
+
+    - id: batch-commits
+      content: |
+        <instructions>
+        For multiple related commits, I'll help create a coherent sequence. Share your set of changes.
+        </instructions>
+
+        <batch_approach>
+        - Analyze how changes relate to each other
+        - Suggest logical ordering (tells clearest story)
+        - Craft each message with consistent voice
+        - Ensure they read as chapters, not fragments
+        - Cross-reference where appropriate
+        </batch_approach>
+
+        <example>
+        Good sequence:
+        1. refactor(auth): extract token validation logic
+        2. feat(auth): add refresh token support
+        3. test(auth): add integration tests for token refresh
+        </example>
+
+  menu:
+    - trigger: write
+      action: "#write-commit"
+      description: "Craft a commit message for your changes"
+
+    - trigger: analyze
+      action: "#analyze-changes"
+      description: "Analyze changes before writing the message"
+
+    - trigger: improve
+      action: "#improve-message"
+      description: "Improve an existing commit message"
+
+    - trigger: batch
+      action: "#batch-commits"
+      description: "Create cohesive messages for multiple commits"
+
+    - trigger: conventional
+      action: "Write a conventional commit (feat/fix/chore/refactor/docs/test/style/perf/build/ci) with proper format: <type>(<scope>): <subject>"
+      description: "Specifically use conventional commit format"
+
+    - trigger: story
+      action: "Write a narrative commit that tells the journey: Setup → Conflict → Solution → Impact"
+      description: "Write commit as a narrative story"
+
+    - trigger: haiku
+      action: "Write a haiku commit (5-7-5 syllables) capturing the essence of the change"
+      description: "Compose a haiku commit message"

package/custom/src/agents/commit-poet/installation-guide.md

@@ -0,0 +1,36 @@
+# Custom Agent Installation
+
+## Quick Install
+
+```bash
+# Interactive
+npx xiaoma-cli agent-install
+
+# Non-interactive
+npx xiaoma-cli agent-install --defaults
+```
+
+## Install Specific Agent
+
+```bash
+# From specific source file
+npx xiaoma-cli agent-install --source ./my-agent.agent.yaml
+
+# With default config (no prompts)
+npx xiaoma-cli agent-install --source ./my-agent.agent.yaml --defaults
+
+# To specific destination
+npx xiaoma-cli agent-install --source ./my-agent.agent.yaml --destination ./my-project
+```
+
+## Batch Install
+
+1. Copy agent YAML to `{xiaoma folder}/custom/src/agents/` OR `custom/src/agents` at your project folder root
+2. Run `npx xiaoma-cli install` and select `Compile Agents` or `Quick Update`
+
+## What Happens
+
+1. Source YAML compiled to .md
+2. Installed to `custom/agents/{agent-name}/`
+3. Added to agent manifest
+4. Backup saved to `_cfg/custom/agents/`