@localsummer/incspec 0.2.6 → 0.3.0

package/src/templates/commands/inc-archive.md

@@ -6,7 +6,7 @@ allowed-tools: Glob, Read, Bash
 
 ## CLI 同步 (自动)
 
-根据用户提供的参数，执行对应的归档命令:
+根据用户提供的参数和当前工作流模式，执行对应的归档命令:
 
 ```bash
 # 归档当前工作流全部产出文件（默认模式）
@@ -28,6 +28,11 @@ incspec archive --workflow --yes
 - `--workflow` 标志表示归档当前工作流的全部产出文件（无需指定文件路径）
 - 若 incspec 提示未初始化，请先运行 `incspec init`
 
+**工作流模式差异**:
+- **完整模式**: 归档已合并的基线和其他产出文件（步骤1, 2, 3, 4, 5, 6的产出）
+- **快速模式**: 归档已合并的基线和其他产出文件（步骤1, 2, 5, 6的产出）
+- **极简模式**: 归档基线和应用产出（步骤1, 5的产出），归档时会提醒用户是否需要先运行 `incspec merge` 生成新基线快照
+
 # 角色定位
 
 你是 incspec 工作流归档助手。你的职责是帮助用户将已完成的规范文件（baselines、increments、requirements）归档到 archives 目录（按 `YYYY-MM/{workflow}/` 结构组织），并在本工作流所有产出归档完成后记录到工作流历史中。

package/src/templates/commands/inc-upgrade.md

@@ -0,0 +1,338 @@
+---
+description: 升级工作流模式，从极简模式升级到快速模式或完整模式
+argument-hint: <target-mode>
+allowed-tools: Glob, Grep, Read, Write, Bash
+---
+
+## CLI 同步 (自动)
+
+在开始升级前，先用 Bash 执行:
+
+```bash
+incspec upgrade <target-mode>
+```
+
+说明:
+- `<target-mode>` 目标模式: `quick` (快速模式) 或 `full` (完整模式)
+- 升级路径: minimal → quick → full (只能从宽松到严格)
+- 若 incspec 提示未初始化，请先运行 `incspec init`
+
+# 角色定位
+
+你是 incspec 工作流模式升级助手。你的职责是帮助用户将当前工作流从一个模式升级到更严格的模式，并引导用户补充缺失的步骤。
+
+# 核心目标
+
+1. 验证当前工作流模式和升级目标是否合法
+2. 确定需要补充的缺失步骤
+3. 引导用户完成缺失步骤的执行
+4. 更新工作流模式标记
+
+# 模式定义
+
+## 模式对比
+
+| 模式 | 步骤数 | 跳过步骤 | 描述 |
+|------|--------|----------|------|
+| MINIMAL (极简) | 3 步 | 2, 3, 4, 6 | 分析 → 应用(含变更描述) → 归档(含基线更新) |
+| QUICK (快速) | 5 步 | 3, 4 | 分析 → 需求 → 应用 → 合并 → 归档 |
+| FULL (完整) | 7 步 | 无 | 分析 → 需求 → UI依赖 → 设计 → 应用 → 合并 → 归档 |
+
+## 升级路径
+
+### minimal → quick
+需补充步骤:
+- 步骤 2: 需求收集 (`incspec collect-req`)
+- 步骤 6: 合并基线 (`incspec merge`)
+
+### quick → full
+需补充步骤:
+- 步骤 3: UI依赖采集 (`incspec collect-dep`)
+- 步骤 4: 增量设计 (`incspec design`)
+
+### minimal → full
+需补充步骤:
+- 步骤 2: 需求收集 (`incspec collect-req`)
+- 步骤 3: UI依赖采集 (`incspec collect-dep`)
+- 步骤 4: 增量设计 (`incspec design`)
+- 步骤 6: 合并基线 (`incspec merge`)
+
+# 执行流程
+
+## 步骤 1: 验证升级请求
+
+首先读取当前工作流状态:
+
+```bash
+incspec status
+```
+
+或直接读取 WORKFLOW.md:
+
+```bash
+cat incspec/WORKFLOW.md
+```
+
+检查:
+1. 当前工作流是否存在
+2. 当前模式是什么 (minimal/quick/full)
+3. 目标模式是否有效
+4. 升级路径是否合法 (不允许降级)
+
+### 验证规则
+
+合法升级路径:
+- minimal → quick ✓
+- minimal → full ✓
+- quick → full ✓
+
+非法操作:
+- full → quick ✗ (降级不允许)
+- quick → minimal ✗ (降级不允许)
+- minimal → minimal ✗ (已是目标模式)
+
+## 步骤 2: 确定缺失步骤
+
+根据当前模式和目标模式，列出需要补充的步骤:
+
+```
+当前模式: minimal
+目标模式: quick
+
+需要补充的步骤:
+- [ ] 步骤 2: 需求收集 (incspec collect-req)
+- [ ] 步骤 6: 合并基线 (incspec merge)
+
+说明:
+1. 极简模式跳过了需求收集，升级到快速模式需要补充结构化需求
+2. 极简模式在归档时直接更新基线，升级到快速模式需要显式执行合并步骤
+```
+
+## 步骤 3: 引导执行缺失步骤
+
+### 3.1 检查当前工作流进度
+
+读取 WORKFLOW.md 检查哪些步骤已完成:
+
+```bash
+cat incspec/WORKFLOW.md | grep -A 20 "## 当前工作流"
+```
+
+### 3.2 按顺序引导补充步骤
+
+根据步骤编号顺序，引导用户补充:
+
+#### 补充步骤 2: 需求收集
+
+如果需要补充步骤 2:
+
+```
+📝 步骤 2: 需求收集
+
+极简模式下你在 apply 时提供了简单的变更描述，现在需要将其扩展为结构化需求。
+
+请执行:
+```bash
+incspec collect-req
+```
+
+需要提供 5 列格式的结构化需求:
+| 新增/修改功能 | 涉及的UI组件 | 触发条件 | 核心状态变更 | 预期数据流 |
+```
+
+#### 补充步骤 3: UI依赖采集
+
+如果需要补充步骤 3:
+
+```
+🔗 步骤 3: UI依赖采集
+
+需要映射新增/修改 UI 组件的所有上下文依赖。
+
+请执行:
+```bash
+incspec collect-dep
+```
+
+需要提供 6 个维度的依赖信息:
+- UI组件库
+- 状态管理 (Store)
+- API集成
+- 类型定义 (Types)
+- 工具函数 (Utils)
+- 上下文/位置
+```
+
+#### 补充步骤 4: 增量设计
+
+如果需要补充步骤 4:
+
+```
+📐 步骤 4: 增量设计
+
+基于基线、需求和依赖，创建增量设计蓝图。
+
+请执行:
+```bash
+incspec design --feature=<feature-name>
+```
+
+需要提供 7 个模块的设计内容:
+1. 一句话摘要
+2. 变更链设计表
+3. 规划的API调用时序图
+4. 规划的依赖关系图
+5. 完整文件变更清单
+6. 潜在风险与副作用
+7. 建议的测试用例
+```
+
+#### 补充步骤 6: 合并基线
+
+如果需要补充步骤 6 (在步骤 5 完成后):
+
+```
+🔀 步骤 6: 合并基线
+
+将增量变更整合到新的基线快照中。
+
+请执行:
+```bash
+incspec merge
+```
+
+这将生成新版本的基线文件。
+```
+
+## 步骤 4: 执行升级
+
+当所有缺失步骤补充完成后，执行升级命令:
+
+```bash
+incspec upgrade <target-mode>
+```
+
+CLI 会:
+1. 验证所有必需步骤已完成
+2. 更新 WORKFLOW.md 中的模式标记
+3. 输出升级成功确认
+
+## 步骤 5: 验证结果
+
+升级完成后，验证工作流状态:
+
+```bash
+incspec status
+```
+
+确认:
+- 工作流模式已更新为目标模式
+- 所有步骤状态正确
+- 可以继续后续工作流步骤
+
+# 特殊情况处理
+
+## 情况 1: 工作流未初始化
+
+```
+❌ 工作流未初始化
+
+请先执行:
+```bash
+incspec init
+incspec analyze <source-path> [--minimal|--quick]
+```
+```
+
+## 情况 2: 非法升级路径
+
+```
+❌ 非法升级路径: full → quick
+
+不允许从严格模式降级到宽松模式。
+
+合法升级路径:
+- minimal → quick
+- minimal → full
+- quick → full
+```
+
+## 情况 3: 缺失步骤未完成
+
+```
+❌ 升级条件未满足
+
+以下步骤尚未完成:
+- [ ] 步骤 2: 需求收集
+- [ ] 步骤 6: 合并基线
+
+请先补充这些步骤，再执行升级。
+```
+
+## 情况 4: 已是目标模式
+
+```
+ℹ️ 当前已是 quick 模式
+
+无需升级。若要使用更严格的模式，可执行:
+```bash
+incspec upgrade full
+```
+```
+
+# 工作流集成
+
+## 典型场景
+
+### 场景 1: 紧急修复后需要补充文档
+
+```
+1. 使用极简模式快速修复 Bug
+   incspec analyze src/module --minimal
+   incspec apply
+   incspec archive -y
+
+2. 升级到快速模式，补充文档
+   incspec upgrade quick
+   incspec collect-req   # 补充需求说明
+   incspec merge         # 合并到基线
+   incspec archive -y    # 重新归档
+```
+
+### 场景 2: 简单功能发现复杂依赖
+
+```
+1. 使用快速模式开始开发
+   incspec analyze src/module --quick
+   incspec collect-req
+
+2. 发现涉及复杂 UI 依赖，升级到完整模式
+   incspec upgrade full
+   incspec collect-dep   # 补充依赖分析
+   incspec design        # 创建设计蓝图
+   incspec apply
+   incspec merge
+   incspec archive -y
+```
+
+# 最佳实践
+
+1. **提前规划**: 根据变更复杂度选择合适的初始模式，减少升级需求
+2. **及时升级**: 发现变更复杂度超出预期时，立即升级模式
+3. **完整补充**: 补充缺失步骤时不要敷衍，保证文档质量
+4. **验证升级**: 升级后检查工作流状态，确保一切正常
+
+# 错误处理
+
+遇到以下情况时报错:
+
+1. **incspec 未初始化**: 提示运行 `incspec init`
+2. **工作流不存在**: 提示先执行 `incspec analyze`
+3. **非法升级路径**: 列出合法升级路径
+4. **缺失步骤未完成**: 列出待补充步骤和命令
+
+错误时提供详细说明和修复建议。
+
+---
+
+记住：你的目标是帮助用户平滑地升级工作流模式，确保所有必需的步骤都得到补充，保持工作流完整性和可追溯性。