speccore 6.76.1 → 6.77.0

package/.agents/skills/spec-iteration-create/SKILL.md

@@ -1,15 +1,134 @@
 ---
 name: spec-iteration-create
-description: 创建 SpecCore 迭代
-allowed-tools: ["Bash"]
+description: >
+  创建迭代专属 Skill。在调用 speccore ask 之前，执行参数提取、
+  前置校验（迭代名是否已存在、主题词有效性），
+  参数缺失时输出交互式提示。不影响 speccore ask 的意图识别能力。
+allowed-tools: ["Bash", "Read"]
 disable-model-invocation: false
 ---
 
-用户说要创建迭代时:
-1. 从用户原话提取英文主题词（从中文名/AI 自己总结，如"会议系统"→"meeting-system"）
-2. execute_command("speccore iteration create -n '<名称>' --topic '<英文主题词>' --owner '<owner>'")
+# spec-iteration-create — 创建迭代（专属逻辑）
 
-示例:
-- "创建Q1会议系统迭代" → speccore iteration create -n Q1 --topic meeting-system --owner luzhaosheng
-- "新建个支付模块迭代" → speccore iteration create -n 支付 --topic payment --owner luzhaosheng
-- "创建V2.0" → speccore iteration create -n V2.0 --topic v2 --owner luzhaosheng
+> **定位**：`/iteration-create` 快捷入口的专属预处理层
+> **原则**：不影响 `speccore ask` 的意图识别能力
+
+---
+
+## 调用方式
+
+```
+/iteration-create [参数]
+/iteration-create -n Q2 --topic meeting-system --owner luzhaosheng
+```
+
+---
+
+## 执行流程
+
+```
+用户输入 /iteration-create [参数]
+        │
+        ▼
+┌───────────────────────────────────────┐
+│ Step 1: 参数提取                        │
+│ 从用户输入提取 name/topic/owner 等      │
+└───────────────┬───────────────────────┘
+                │
+        参数缺失？
+                │
+        是 ──► 输出交互式提示
+                │
+        否 ──► 继续
+                │
+                ▼
+┌───────────────────────────────────────┐
+│ Step 2: 参数补全                        │
+│ topic 缺失 → AI 从中文名提取英文主题词     │
+│ owner 缺失 → 读 git config user.name     │
+└───────────────┬───────────────────────┘
+                │
+                ▼
+┌───────────────────────────────────────┐
+│ Step 3: 前置校验                        │
+│ - 迭代名是否已存在？                    │
+│ - 主题词是否有效？                      │
+└───────────────┬───────────────────────┘
+                │
+                ▼
+┌───────────────────────────────────────┐
+│ Step 4: 调用 speccore ask               │
+└───────────────────────────────────────┘
+```
+
+---
+
+## Step 1: 参数提取
+
+| 参数 | 短名 | 长名 | 必填 | 说明 |
+|:---|:---|:---|:---|:---|
+| name | -n | --name | 是 | 迭代名称（如 Q1, V2.0, Sprint-3）|
+| topic | - | --topic | 否 | 英文主题词（用于目录命名）|
+| owner | -o | --owner | 否 | 迭代负责人 |
+| template | -t | --template | 否 | 模板名称（默认 standard）|
+
+---
+
+## Step 2: 参数缺失 → 交互式提示
+
+```
+📁 speccore iteration-create — 创建迭代
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📖 可用参数
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  -n, --name <name>         迭代名称（必填）
+                            如: Q1, V2.0, Sprint-3, 会议系统
+      --topic <topic>       英文主题词（如 meeting-system, payment）
+                            用于生成目录名，缺失时 AI 自动提取
+  -o, --owner <name>        迭代负责人（默认: git config user.name）
+  -t, --template <name>     模板名称（默认: standard）
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+💡 使用示例
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  /iteration-create -n Q1 --topic meeting-system    # 创建 Q1 迭代
+  /iteration-create -n "支付模块"                    # AI 自动提取主题词
+  /iteration-create -n V2.0 --owner luzhaosheng     # 指定负责人
+
+请补充 --name 参数后重新调用。
+```
+
+---
+
+## Step 3: 前置校验
+
+### 3.1 检查迭代名是否已存在
+```bash
+# 检查 .speccore/ITERATIONS/ 或项目根目录下是否已有同名迭代
+# 如果已存在 → 提示用户是否覆盖或改名
+```
+
+### 3.2 提取英文主题词
+```bash
+# 如果用户未提供 --topic，从 --name 提取英文主题词
+# "会议系统" → "meeting-system"
+# "Q1" → "q1"
+# "支付模块" → "payment"
+```
+
+### 3.3 检查 owner
+```bash
+# 如果未提供 --owner，读取 git config user.name
+# 如果 git 未配置 → 提示用户提供
+```
+
+---
+
+## Step 4: 调用 speccore ask
+
+```bash
+execute_command("speccore ask '创建 Iteration-XXX 迭代...'")
+```
+
+> ⚠️ 最终仍然调用 `speccore ask`，不要绕过 ask 引擎。

package/.agents/skills/spec-plan/SKILL.md

@@ -1,10 +1,129 @@
 ---
 name: spec-plan
-description: 路由到 speccore ask 引擎
-allowed-tools: ["Bash"]
+description: >
+  执行计划专属 Skill。在调用 speccore ask 之前，执行参数提取、
+  前置校验（任务是否已拆分、依赖关系检测、执行顺序优化），
+  参数缺失时输出交互式提示（参数说明 + 使用示例）。
+  不影响 speccore ask 的意图识别能力。
+allowed-tools: ["Bash", "Read"]
 disable-model-invocation: false
 ---
 
-直接执行: execute_command("speccore ask '用户原话'")
+# spec-plan — 执行计划（专属逻辑）
 
-不要输出命令文本，不要分析意图，一切交给 speccore ask。
+> **定位**：`/plan` 快捷入口的专属预处理层
+> **原则**：不影响 `speccore ask` 的意图识别能力，只在调用 ask 之前做参数校验和上下文准备
+
+---
+
+## 调用方式
+
+```
+/plan [参数]
+/plan -I Iteration-001 --task Task-001
+/plan -I Iteration-001 --all
+```
+
+---
+
+## 执行流程
+
+```
+用户输入 /plan [参数]
+        │
+        ▼
+┌───────────────────────────────────────┐
+│ Step 1: 参数提取                        │
+│ 从用户输入提取 iteration/task/all 等     │
+└───────────────┬───────────────────────┘
+                │
+        参数缺失？
+                │
+        是 ──► 输出交互式提示
+                │
+        否 ──► 继续
+                │
+                ▼
+┌───────────────────────────────────────┐
+│ Step 2: 前置校验                        │
+│ - 任务是否已拆分？                      │
+│ - 依赖关系是否完整？                    │
+│ - 执行顺序是否合理？                    │
+└───────────────┬───────────────────────┘
+                │
+                ▼
+┌───────────────────────────────────────┐
+│ Step 3: 调用 speccore ask               │
+└───────────────────────────────────────┘
+```
+
+---
+
+## Step 1: 参数提取
+
+| 参数 | 短名 | 长名 | 必填 | 说明 |
+|:---|:---|:---|:---|:---|
+| iteration | -i | --iteration | 否 | 目标迭代名 |
+| task | -t | --task | 否 | 指定任务（与 --all 互斥）|
+| all | -a | --all | 否 | 全部任务 |
+| batch-size | -b | --batch-size | 否 | 每批任务数（默认 3）|
+
+---
+
+## Step 2: 参数缺失 → 交互式提示
+
+```
+📋 speccore plan — 执行计划
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📖 可用参数
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  -I, --iteration <name>    目标迭代（默认: 当前迭代）
+  -t, --task <id>           指定任务（如 Task-001）
+  -a, --all                 全部任务
+      --batch-size <n>      每批任务数（默认 3）
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+💡 使用示例
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  /plan                                   # 计划当前迭代全部任务
+  /plan -I Q1                             # 计划指定迭代
+  /plan -t Task-001                       # 计划单个任务
+  /plan --all --batch-size 5              # 全部任务，每批 5 个
+
+请补充参数后重新调用，或直接调用 /plan 使用默认设置。
+```
+
+---
+
+## Step 3: 前置校验
+
+### 3.1 检查任务是否已拆分
+```bash
+# 扫描 030-tasks/ 目录
+# 如果没有 Task 目录 → 提示用户先执行 split
+```
+
+### 3.2 检查依赖关系
+```bash
+# 读取各 Task 的 dependencies
+# 检测循环依赖
+# 检测缺失的依赖任务
+```
+
+### 3.3 执行顺序优化
+```bash
+# 拓扑排序
+# 高优先级任务排在前面
+# 基础模块优先
+```
+
+---
+
+## Step 4: 调用 speccore ask
+
+```bash
+execute_command("speccore ask '生成 Iteration-XXX 的执行计划...'")
+```
+
+> ⚠️ 最终仍然调用 `speccore ask`，不要绕过 ask 引擎。

package/.agents/skills/spec-spec2doc/SKILL.md

@@ -1,10 +1,132 @@
 ---
 name: spec-spec2doc
-description: 路由到 speccore ask 引擎
-allowed-tools: ["Bash"]
+description: >
+  规格转文档专属 Skill。在调用 speccore ask 之前，执行参数提取、
+  前置校验（迭代/Task 存在性），参数缺失时输出交互式提示。
+  不影响 speccore ask 的意图识别能力。
+allowed-tools: ["Bash", "Read"]
 disable-model-invocation: false
 ---
 
-直接执行: execute_command("speccore ask '用户原话'")
+# spec-spec2doc — 规格转文档（专属逻辑）
 
-不要输出命令文本，不要分析意图，一切交给 speccore ask。
+> **定位**：`/spec2doc` 快捷入口的专属预处理层
+> **原则**：不影响 `speccore ask` 的意图识别能力
+
+---
+
+## 调用方式
+
+```
+/spec2doc [参数]
+/spec2doc -I Iteration-001 --task Task-001
+/spec2doc -I Iteration-001 --all
+```
+
+---
+
+## 执行流程
+
+```
+用户输入 /spec2doc [参数]
+        │
+        ▼
+┌───────────────────────────────────────┐
+│ Step 1: 参数提取                        │
+│ 从用户输入提取 iteration/task/format 等 │
+└───────────────┬───────────────────────┘
+                │
+        参数缺失？
+                │
+        是 ──► 输出交互式提示
+                │
+        否 ──► 继续
+                │
+                ▼
+┌───────────────────────────────────────┐
+│ Step 2: 前置校验                        │
+│ - 迭代是否存在？                        │
+│ - Task 是否存在？                       │
+└───────────────┬───────────────────────┘
+                │
+                ▼
+┌───────────────────────────────────────┐
+│ Step 3: 调用 speccore ask               │
+└───────────────────────────────────────┘
+```
+
+---
+
+## Step 1: 参数提取
+
+| 参数 | 短名 | 长名 | 必填 | 说明 |
+|:---|:---|:---|:---|:---|
+| iteration | -i | --iteration | 否 | 目标迭代名 |
+| task | -t | --task | 否 | 指定 Task（与 --all 互斥）|
+| all | -a | --all | 否 | 全部 Task |
+| format | -f | --format | 否 | 输出格式（md/pdf/html，默认 md）|
+| output | -o | --output | 否 | 输出文件路径 |
+
+---
+
+## Step 2: 参数缺失 → 交互式提示
+
+```
+📄 speccore spec2doc — 规格转文档
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📋 当前环境
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+迭代: Iteration-001-meeting-system（从 context.json 读取）
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📖 可用参数
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  -I, --iteration <name>    目标迭代（默认: 当前迭代）
+  -t, --task <id>           指定 Task（如 Task-001）
+  -a, --all                 全部 Task
+  -f, --format <format>     输出格式: md | pdf | html（默认 md）
+  -o, --output <path>       输出文件路径
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+💡 使用示例
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  /spec2doc -t Task-001                     # 导出单个 Task
+  /spec2doc --all                           # 导出全部 Task
+  /spec2doc --all -f pdf                    # 导出为 PDF
+  /spec2doc -t Task-001 -o ./output.md      # 指定输出路径
+
+请补充参数后重新调用。
+```
+
+---
+
+## Step 3: 前置校验
+
+### 3.1 检查迭代是否存在
+```bash
+# 检查迭代目录是否存在
+# 如果不存在 → 提示用户
+```
+
+### 3.2 检查 Task 是否存在
+```bash
+# 如果指定了 -t，检查 Task 目录是否存在
+# 如果不存在 → 列出可用 Task
+```
+
+### 3.3 检查输出格式
+```bash
+# 支持的格式: md, pdf, html
+# 如果格式不支持 → 提示可用格式
+```
+
+---
+
+## Step 4: 调用 speccore ask
+
+```bash
+execute_command("speccore ask '将规格转为文档...'")
+```
+
+> ⚠️ 最终仍然调用 `speccore ask`，不要绕过 ask 引擎。

package/.agents/skills/spec-split/SKILL.md

@@ -1,10 +1,220 @@
 ---
 name: spec-split
-description: 路由到 speccore ask 引擎
-allowed-tools: ["Bash"]
+description: >
+  任务拆分专属 Skill。在调用 speccore ask 之前，执行参数提取、
+  前置校验（analyze 是否完成、端列表提取、变更检测），
+  参数缺失时输出交互式提示（参数说明 + 使用示例）。
+  不影响 speccore ask 的意图识别能力。
+allowed-tools: ["Bash", "Read"]
 disable-model-invocation: false
 ---
 
-直接执行: execute_command("speccore ask '用户原话'")
+# spec-split — 任务拆分（专属逻辑）
 
-不要输出命令文本，不要分析意图，一切交给 speccore ask。
+> **定位**：`/split` 快捷入口的专属预处理层
+> **原则**：不影响 `speccore ask` 的意图识别能力，只在调用 ask 之前做参数校验和上下文准备
+
+---
+
+## 调用方式
+
+```
+/split [参数]
+/split -I Iteration-001 --platforms api,h5
+/split --modules "购物车,订单" --prune
+```
+
+---
+
+## 执行流程
+
+```
+用户输入 /split [参数]
+        │
+        ▼
+┌───────────────────────────────────────┐
+│ Step 1: 参数提取                        │
+│ 从用户输入提取 iteration/platforms/modules 等 │
+└───────────────┬───────────────────────┘
+                │
+        参数缺失？
+                │
+        是 ──► 输出交互式提示（参数说明 + 示例）
+                │ 让用户补充后重新调用
+                │
+        否 ──► 继续
+                │
+                ▼
+┌───────────────────────────────────────┐
+│ Step 2: 参数补全                        │
+│ iteration 缺失 → 读 context.json        │
+│ platforms 缺失 → 从 CONSTITUTION 检测   │
+└───────────────┬───────────────────────┘
+                │
+                ▼
+┌───────────────────────────────────────┐
+│ Step 3: 前置校验                        │
+│ - analyze 是否完成？                    │
+│ - 020-specs/ 是否有更新？               │
+│ - 已有 Task 结构扫描                    │
+└───────────────┬───────────────────────┘
+                │
+        校验失败？
+                │
+        是 ──► 输出问题 + 修复建议
+                │
+        否 ──► 继续
+                │
+                ▼
+┌───────────────────────────────────────┐
+│ Step 4: 生成专属 Prompt                 │
+│ 根据校验结果生成上下文丰富的 Prompt       │
+└───────────────┬───────────────────────┘
+                │
+                ▼
+┌───────────────────────────────────────┐
+│ Step 5: 调用 speccore ask               │
+│ execute_command("speccore ask '...'")   │
+└───────────────────────────────────────┘
+```
+
+---
+
+## Step 1: 参数提取
+
+从用户输入提取以下参数：
+
+| 参数 | 短名 | 长名 | 必填 | 说明 |
+|:---|:---|:---|:---|:---|
+| iteration | -i | --iteration | 否 | 目标迭代名 |
+| platforms | -p | --platforms | 否 | 逗号分隔的端列表 |
+| modules | - | --modules | 否 | 逗号分隔的功能模块名 |
+| prune | - | --prune | 否 | 清理旧任务 |
+| dev-guide | - | --dev-guide | 否 | 生成 DEV_GUIDE.md |
+| ignore-specs-update | - | --ignore-specs-update | 否 | 跳过变更检测 |
+| dry-run | - | --dry-run | 否 | 预览不创建 |
+
+**提取规则**：
+- 支持 `-I Q1`、`--iteration Sprint-3`、`迭代 Q1` 等多种形式
+- 支持 `--platforms api,h5`、`只拆 api 和 h5` 等自然语言形式
+
+---
+
+## Step 2: 参数缺失 → 交互式提示
+
+当用户调用 `/split` 但没有提供足够参数时，**不要直接报错**，而是输出友好的提示：
+
+```
+🎯 speccore split — 任务拆分
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📋 当前环境
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+迭代: Iteration-001-meeting-system（从 context.json 读取）
+已有任务: 0 个
+端列表: api, h5-mobile, admin-web（从 CONSTITUTION.md 读取）
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📖 可用参数
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  -I, --iteration <name>    目标迭代（默认: 当前迭代）
+  -p, --platforms <list>    只拆分指定端（如 api,h5）
+      --modules <list>      只拆分指定模块（如 "购物车,订单"）
+      --prune               清理不匹配的旧任务
+      --dev-guide           生成任务级 DEV_GUIDE.md
+      --ignore-specs-update 跳过变更检测
+      --dry-run             预览不创建
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+💡 使用示例
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  /split                                  # 拆分当前迭代全部端
+  /split -I Q1                            # 拆分指定迭代
+  /split --platforms api,h5               # 只拆 api 和 h5 端
+  /split --modules "购物车,订单"           # 只拆购物车和订单模块
+  /split --prune                          # 清理旧任务后重新拆分
+  /split --platforms api --dev-guide      # 拆 api 端 + 生成实现指南
+
+请补充参数后重新调用，或直接调用 /split 使用默认设置。
+```
+
+---
+
+## Step 3: 前置校验
+
+参数齐全后，执行以下校验（**不阻断，只提示**）：
+
+### 3.1 检查 analyze 是否完成
+```bash
+# 检查 ANALYSIS.md 是否存在
+if [ ! -f "Iteration-XXX/020-specs/ANALYSIS.md" ]; then
+  echo "⚠️  该迭代尚未分析，建议先执行:"
+  echo "   speccore analyze --auto -I Iteration-XXX"
+  echo ""
+  echo "   选项 1: 停止拆分，先执行 analyze"
+  echo "   选项 2: 继续拆分（基于 REQUIREMENT.md 直接拆）"
+fi
+```
+
+### 3.2 检查 020-specs/ 是否有更新（变更检测）
+```bash
+# 执行 speccore iteration split --dry-run 检测变更
+# 如果 020-specs/ 比 030-tasks/ 新，提示用户
+```
+
+### 3.3 扫描已有 Task 结构
+```bash
+# 读取 030-tasks/ 下的 Task 目录
+# 提取每个 Task 已有的端（10-backend/{端}, 20-frontend/{端}）
+# 用于增量拆分
+```
+
+### 3.4 检查端列表有效性
+```bash
+# 验证用户指定的 platforms 是否在 CONSTITUTION.md 的端列表中
+# 如果无效，提示可用端列表
+```
+
+---
+
+## Step 4: 生成专属 Prompt
+
+前置校验完成后，生成包含完整上下文的 Prompt：
+
+```
+speccore ask "拆分 Iteration-001 的任务。
+
+上下文信息：
+- 已有 Task: Task-001（已有端: h5）, Task-002（已有端: admin-web）
+- 本次拆分端: api
+- 020-specs/ 有更新（晚于上次拆分）
+- 功能模块: 全部
+
+请执行：speccore iteration split -I Iteration-001 --platforms api"
+```
+
+---
+
+## Step 5: 调用 speccore ask
+
+```bash
+execute_command("speccore ask '上述 Prompt'")
+```
+
+> ⚠️ **核心原则**：最终仍然调用 `speccore ask`，不要绕过 ask 引擎直接执行 CLI 命令。
+> 专属逻辑只做"参数校验 + 上下文准备"，真正的意图理解和执行交给 ask。
+
+---
+
+## 与 speccore-router 的关系
+
+| 场景 | 入口 | 处理方 |
+|:---|:---|:---|
+| "拆分 Iteration-001 的任务" | 自然语言 | speccore-router → speccore ask |
+| "/split -I Iteration-001" | 快捷命令 | spec-split Skill → 参数校验 → speccore ask |
+| "/split"（无参数） | 快捷命令 | spec-split Skill → 交互式提示 |
+
+**两者不冲突**：
+- router 负责自然语言的意图识别和参数提取
+- spec-split 负责快捷命令的参数校验和上下文准备
+- 最终都调用 `speccore ask` 执行核心逻辑