speccrew 0.5.8 → 0.5.10

package/docs/GETTING-STARTED.en.md

@@ -62,7 +62,82 @@ Supported IDEs: `qoder`, `cursor`, `claude`, `codex`
 
 ---
 
-## 2. Workflow Overview
+## 2. Your First 5 Minutes
+
+After running `speccrew init`, follow these steps to get productive immediately:
+
+### Step 1: Choose Your IDE
+
+| IDE | Init Command | Best For |
+|-----|-------------|----------|
+| **Qoder** (Recommended) | `speccrew init --ide qoder` | Full agent orchestration, parallel workers |
+| **Cursor** | `speccrew init --ide cursor` | Composer-based workflows |
+| **Claude Code** | `speccrew init --ide claude` | CLI-first development |
+| **Codex** | `speccrew init --ide codex` | OpenAI ecosystem integration |
+
+### Step 2: Initialize Knowledge Base (Recommended)
+
+For existing projects, initialize knowledge base first so agents understand your codebase:
+
+```
+@speccrew-team-leader Initialize technical knowledge base
+```
+
+Then:
+
+```
+@speccrew-team-leader Initialize business knowledge base
+```
+
+### Step 3: Start Your First Task
+
+```
+@speccrew-product-manager I have a new requirement: [describe your feature]
+```
+
+> **Tip**: If unsure what to do, just say `@speccrew-team-leader Help me get started` — the Team Leader will auto-detect your project status and guide you.
+
+---
+
+## 3. Quick Decision Tree
+
+Not sure what to do? Find your scenario below:
+
+- **I have a new feature requirement**
+  → `@speccrew-product-manager I have a new requirement: [describe your feature]`
+
+- **I want to scan existing project knowledge**
+  → `@speccrew-team-leader initialize technical knowledge base`
+  → Then: `@speccrew-team-leader initialize business knowledge base`
+
+- **I want to continue previous work**
+  → `@speccrew-team-leader what is the current progress?`
+
+- **I want to check system health**
+  → Run in terminal: `speccrew doctor`
+
+- **I'm not sure what to do**
+  → `@speccrew-team-leader help me get started`
+  → Team Leader will auto-detect your project status and guide you
+
+---
+
+## 4. Agent Quick Reference
+
+| Role | Agent | Responsibilities | Example Command |
+|------|-------|-----------------|-----------------|
+| Team Leader | `@speccrew-team-leader` | Project navigation, knowledge init, status check | "Help me get started" |
+| Product Manager | `@speccrew-product-manager` | Requirements analysis, PRD generation | "I have a new requirement: ..." |
+| Feature Designer | `@speccrew-feature-designer` | Feature analysis, spec design, API contracts | "Start feature design for iteration X" |
+| System Designer | `@speccrew-system-designer` | Architecture design, platform-specific design | "Start system design for iteration X" |
+| System Developer | `@speccrew-system-developer` | Development coordination, code generation | "Start development for iteration X" |
+| Test Manager | `@speccrew-test-manager` | Test planning, case design, execution | "Start testing for iteration X" |
+
+> **Note**: You don't need to remember all agents. Just talk to `@speccrew-team-leader` and it will route your request to the right agent.
+
+---
+
+## 5. Workflow Overview
 
 ### Complete Flowchart
 
@@ -89,11 +164,11 @@ flowchart LR
 
 ---
 
-## 3. Step Zero: Knowledge Base Initialization
+## 6. Step Zero: Knowledge Base Initialization
 
 Before starting the formal engineering process, you need to initialize the project knowledge base.
 
-### 3.1 Technical Knowledge Base Initialization
+### 6.1 Technical Knowledge Base Initialization
 
 **Conversation Example**:
 ```
@@ -115,7 +190,7 @@ speccrew-workspace/knowledges/techs/{platform-id}/
 └── INDEX.md               # Index file
 ```
 
-### 3.2 Business Knowledge Base Initialization
+### 6.2 Business Knowledge Base Initialization
 
 **Conversation Example**:
 ```
@@ -139,9 +214,9 @@ speccrew-workspace/knowledges/bizs/
 
 ---
 
-## 4. Phase-by-Phase Conversation Guide
+## 7. Phase-by-Phase Conversation Guide
 
-### 4.1 Phase 1: Requirements Analysis (Product Manager)
+### 7.1 Phase 1: Requirements Analysis (Product Manager)
 
 **How to Start**:
 ```
@@ -168,7 +243,7 @@ iterations/{number}-{type}-{name}/01.product-requirement/
 
 ---
 
-### 4.2 Phase 2: Feature Design (Feature Designer)
+### 7.2 Phase 2: Feature Design (Feature Designer)
 
 **How to Start**:
 ```
@@ -195,7 +270,7 @@ iterations/{iter}/02.feature-design/
 
 ---
 
-### 4.3 Phase 3: System Design (System Designer)
+### 7.3 Phase 3: System Design (System Designer)
 
 **How to Start**:
 ```
@@ -226,7 +301,7 @@ iterations/{iter}/03.system-design/
 
 ---
 
-### 4.4 Phase 4: Development Implementation (System Developer)
+### 7.4 Phase 4: Development Implementation (System Developer)
 
 **How to Start**:
 ```
@@ -257,7 +332,7 @@ iterations/{iter}/04.development/
 
 ---
 
-### 4.5 Phase 5: System Testing (Test Manager)
+### 7.5 Phase 5: System Testing (Test Manager)
 
 **How to Start**:
 ```
@@ -292,7 +367,7 @@ iterations/{iter}/05.system-test/
 
 ---
 
-### 4.6 Phase 6: Archive
+### 7.6 Phase 6: Archive
 
 Iterations are automatically archived upon completion:
 
@@ -308,9 +383,9 @@ speccrew-workspace/iteration-archives/
 
 ---
 
-## 5. Knowledge Base Overview
+## 8. Knowledge Base Overview
 
-### 5.1 Business Knowledge Base (bizs)
+### 8.1 Business Knowledge Base (bizs)
 
 **Purpose**: Store project business function descriptions, module divisions, API characteristics
 
@@ -325,7 +400,7 @@ knowledges/bizs/
 
 **Usage Scenarios**: Product Manager, Feature Designer
 
-### 5.2 Technical Knowledge Base (techs)
+### 8.2 Technical Knowledge Base (techs)
 
 **Purpose**: Store project technology stack, architecture conventions, development specifications, testing specifications
 
@@ -343,11 +418,11 @@ knowledges/techs/{platform-id}/
 
 ---
 
-## 6. Workflow Progress Management
+## 9. Workflow Progress Management
 
 The SpecCrew virtual team follows a strict stage-gating mechanism where each phase must be confirmed by the user before proceeding to the next. It also supports resumable execution — when restarted after interruption, it automatically continues from where it left off.
 
-### 6.1 Three-Layer Progress Files
+### 9.1 Three-Layer Progress Files
 
 The workflow automatically maintains three types of JSON progress files, located in the iteration directory:
 
@@ -357,7 +432,7 @@ The workflow automatically maintains three types of JSON progress files, located
 | `.checkpoints.json` | Under each phase directory | Records user checkpoint confirmation status |
 | `DISPATCH-PROGRESS.json` | Under each phase directory | Records item-by-item progress for parallel tasks (multi-platform/multi-module) |
 
-### 6.2 Stage Status Flow
+### 9.2 Stage Status Flow
 
 Each phase follows this status flow:
 
@@ -370,7 +445,7 @@ pending → in_progress → completed → confirmed
 - **completed**: Agent execution completed, awaiting user confirmation
 - **confirmed**: User confirmed through final checkpoint, next phase can start
 
-### 6.3 Resumable Execution
+### 9.3 Resumable Execution
 
 When restarting an Agent for a phase:
 
@@ -378,7 +453,7 @@ When restarting an Agent for a phase:
 2. **Checkpoint recovery**: Reads `.checkpoints.json`, skips passed checkpoints, continues from the last interruption point
 3. **Parallel task recovery**: Reads `DISPATCH-PROGRESS.json`, only re-executes tasks with `pending` or `failed` status, skips `completed` tasks
 
-### 6.4 Viewing Current Progress
+### 9.4 Viewing Current Progress
 
 View the pipeline panorama status through the Team Leader Agent:
 
@@ -397,13 +472,13 @@ Pipeline Status: i001-user-management
   05 System Test:    ⏳ Pending
 ```
 
-### 6.5 Backward Compatibility
+### 9.5 Backward Compatibility
 
 The progress file mechanism is fully backward compatible — if progress files do not exist (e.g., in legacy projects or new iterations), all Agents will execute normally according to the original logic.
 
 ---
 
-## 7. Frequently Asked Questions (FAQ)
+## 10. Frequently Asked Questions (FAQ)
 
 ### Q1: What if the Agent doesn't work as expected?
 
@@ -479,7 +554,7 @@ Re-initialization is required in the following situations:
 
 ---
 
-## 8. Quick Reference
+## 11. Quick Reference
 
 ### Agent Start Quick Reference
 

package/docs/GETTING-STARTED.md

@@ -62,7 +62,82 @@ speccrew init --ide qoder
 
 ---
 
-## 2. 工作流程总览
+## 2. 安装后5分钟快速开始
+
+执行 `speccrew init` 后，按以下步骤快速进入工作状态：
+
+### 第1步：选择你的 IDE
+
+| IDE | 初始化命令 | 适用场景 |
+|-----|-----------|----------|
+| **Qoder**（推荐） | `speccrew init --ide qoder` | 完整Agent编排、并行Worker |
+| **Cursor** | `speccrew init --ide cursor` | 基于Composer的工作流 |
+| **Claude Code** | `speccrew init --ide claude` | CLI优先开发 |
+| **Codex** | `speccrew init --ide codex` | OpenAI生态集成 |
+
+### 第2步：初始化知识库（推荐）
+
+对于已有源码的项目，建议先初始化知识库，让Agent理解你的代码库：
+
+```
+@speccrew-team-leader 初始化技术知识库
+```
+
+然后：
+
+```
+@speccrew-team-leader 初始化业务知识库
+```
+
+### 第3步：开始你的第一个任务
+
+```
+@speccrew-product-manager 我有一个新需求：[描述你的功能需求]
+```
+
+> **提示**：如果不确定该做什么，直接说 `@speccrew-team-leader 帮我开始` — Team Leader 会自动检测项目状态并引导你。
+
+---
+
+## 3. 快速决策树
+
+不确定该做什么？找到你的场景：
+
+- **我有新的功能需求**
+  → `@speccrew-product-manager 我有一个新需求：[描述你的功能需求]`
+
+- **我想扫描现有项目的知识**
+  → `@speccrew-team-leader 初始化技术知识库`
+  → 然后：`@speccrew-team-leader 初始化业务知识库`
+
+- **我想继续之前的工作**
+  → `@speccrew-team-leader 当前进度是什么？`
+
+- **我想检查系统健康状态**
+  → 在终端运行：`speccrew doctor`
+
+- **我不确定该做什么**
+  → `@speccrew-team-leader 帮我开始`
+  → Team Leader 会自动检测项目状态并引导你
+
+---
+
+## 4. Agent 快速参考
+
+| 角色 | Agent | 职责 | 示例指令 |
+|------|-------|------|----------|
+| 团队负责人 | `@speccrew-team-leader` | 项目导航、知识库初始化、状态查看 | "帮我开始" |
+| 产品经理 | `@speccrew-product-manager` | 需求分析、PRD 生成 | "我有一个新需求：..." |
+| 功能设计师 | `@speccrew-feature-designer` | 功能分析、规格设计、API 契约 | "开始迭代X的功能设计" |
+| 系统设计师 | `@speccrew-system-designer` | 架构设计、平台详细设计 | "开始迭代X的系统设计" |
+| 系统开发者 | `@speccrew-system-developer` | 开发协调、代码生成 | "开始迭代X的开发" |
+| 测试经理 | `@speccrew-test-manager` | 测试规划、用例设计、执行 | "开始迭代X的测试" |
+
+> **提示**：你不需要记住所有 Agent。只需与 `@speccrew-team-leader` 对话，它会将你的请求路由到合适的 Agent。
+
+---
+
+## 5. 工作流程总览
 
 ### 完整流程图
 
@@ -89,11 +164,11 @@ flowchart LR
 
 ---
 
-## 3. 第零步：知识库初始化
+## 6. 第零步：知识库初始化
 
 在开始正式工程流程前，需要先初始化项目知识库。
 
-### 3.1 技术知识库初始化
+### 6.1 技术知识库初始化
 
 **对话示例**：
 ```
@@ -115,7 +190,7 @@ speccrew-workspace/knowledges/techs/{platform-id}/
 └── INDEX.md               # 索引文件
 ```
 
-### 3.2 业务知识库初始化
+### 6.2 业务知识库初始化
 
 **对话示例**：
 ```
@@ -139,9 +214,9 @@ speccrew-workspace/knowledges/bizs/
 
 ---
 
-## 4. 逐阶段对话指南
+## 7. 逐阶段对话指南
 
-### 4.1 阶段一：需求分析（Product Manager）
+### 7.1 阶段一：需求分析（Product Manager）
 
 **如何启动**：
 ```
@@ -168,7 +243,7 @@ iterations/{序号}-{类型}-{名称}/01.product-requirement/
 
 ---
 
-### 4.2 阶段二：功能设计（Feature Designer）
+### 7.2 阶段二：功能设计（Feature Designer）
 
 **如何启动**：
 ```
@@ -195,7 +270,7 @@ iterations/{iter}/02.feature-design/
 
 ---
 
-### 4.3 阶段三：系统设计（System Designer）
+### 7.3 阶段三：系统设计（System Designer）
 
 **如何启动**：
 ```
@@ -226,7 +301,7 @@ iterations/{iter}/03.system-design/
 
 ---
 
-### 4.4 阶段四：开发实现（System Developer）
+### 7.4 阶段四：开发实现（System Developer）
 
 **如何启动**：
 ```
@@ -257,7 +332,7 @@ iterations/{iter}/04.development/
 
 ---
 
-### 4.5 阶段五：系统测试（Test Manager）
+### 7.5 阶段五：系统测试（Test Manager）
 
 **如何启动**：
 ```
@@ -292,7 +367,7 @@ iterations/{iter}/05.system-test/
 
 ---
 
-### 4.6 阶段六：归档
+### 7.6 阶段六：归档
 
 迭代完成后自动归档：
 
@@ -308,9 +383,9 @@ speccrew-workspace/iteration-archives/
 
 ---
 
-## 5. 知识库说明
+## 8. 知识库说明
 
-### 5.1 业务知识库（bizs）
+### 8.1 业务知识库（bizs）
 
 **作用**：存储项目的业务功能描述、模块划分、API 特征
 
@@ -325,7 +400,7 @@ knowledges/bizs/
 
 **使用场景**：Product Manager、Feature Designer
 
-### 5.2 技术知识库（techs）
+### 8.2 技术知识库（techs）
 
 **作用**：存储项目的技术栈、架构约定、开发规约、测试规约
 
@@ -343,11 +418,11 @@ knowledges/techs/{platform-id}/
 
 ---
 
-## 6. 流水线进度管理
+## 9. 流水线进度管理
 
 SpecCrew 虚拟团队遵循严格的阶段门控机制，每个阶段必须经过用户确认后才能推进到下一阶段。同时支持断点续传 —— 中断后重新启动时，自动从上次停止的位置继续。
 
-### 6.1 三层进度文件
+### 9.1 三层进度文件
 
 工作流自动维护三类 JSON 进度文件，位于迭代目录下：
 
@@ -357,7 +432,7 @@ SpecCrew 虚拟团队遵循严格的阶段门控机制，每个阶段必须经
 | `.checkpoints.json` | 各阶段目录下 | 记录用户确认点（Checkpoint）通过状态 |
 | `DISPATCH-PROGRESS.json` | 各阶段目录下 | 记录并行任务（多平台/多模块）的逐项进度 |
 
-### 6.2 阶段状态流转
+### 9.2 阶段状态流转
 
 每个阶段遵循以下状态流转：
 
@@ -370,7 +445,7 @@ pending → in_progress → completed → confirmed
 - **completed**：Agent 执行完成，等待用户确认
 - **confirmed**：用户通过最终 Checkpoint 确认，下一阶段可以启动
 
-### 6.3 断点续传
+### 9.3 断点续传
 
 当重新启动某个阶段的 Agent 时：
 
@@ -378,7 +453,7 @@ pending → in_progress → completed → confirmed
 2. **恢复 Checkpoint**：读取 `.checkpoints.json`，跳过已通过的确认点，从上次中断处继续
 3. **恢复并行任务**：读取 `DISPATCH-PROGRESS.json`，只重新执行 `pending` 或 `failed` 状态的任务，跳过已 `completed` 的任务
 
-### 6.4 查看当前进度
+### 9.4 查看当前进度
 
 通过 Team Leader Agent 查看流水线全景状态：
 
@@ -397,13 +472,13 @@ Pipeline Status: i001-user-management
   05 System Test:    ⏳ Pending
 ```
 
-### 6.5 向下兼容
+### 9.5 向下兼容
 
 进度文件机制完全向下兼容 —— 如果进度文件不存在（如旧项目或全新迭代），所有 Agent 将按照原有逻辑正常执行。
 
 ---
 
-## 7. 常见问题（FAQ）
+## 10. 常见问题（FAQ）
 
 ### Q1: Agent 不按预期工作怎么办？
 
@@ -479,7 +554,7 @@ npm install -g speccrew@0.5.6
 
 ---
 
-## 8. 快速参考
+## 11. 快速参考
 
 ### Agent 启动速查表