speccore 6.76.1 → 6.77.1

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

@@ -0,0 +1,214 @@
+---
+name: spec-pr
+description: >
+  代码提交与 PR 专属 Skill。在调用 speccore ask 之前，执行参数提取、
+  前置校验（分支安全检查、未提交变更检测、ANALYSIS.md 路径校验、冲突检测），
+  参数缺失时输出交互式提示。不影响 speccore ask 的意图识别能力。
+allowed-tools: ["Bash", "Read"]
+disable-model-invocation: false
+---
+
+# spec-pr — 代码提交与 PR（专属逻辑）
+
+> **定位**：`/pr` 快捷入口的专属预处理层
+> **原则**：不影响 `speccore ask` 的意图识别能力
+
+---
+
+## 调用方式
+
+```
+/pr [参数]
+/pr --task Task-001 --commit
+/pr --task Task-001 --force
+/pr --task Task-001 --prompt
+```
+
+---
+
+## 执行流程
+
+```
+用户输入 /pr [参数]
+        │
+        ▼
+┌───────────────────────────────────────┐
+│ Step 1: 参数提取                        │
+│ 从用户输入提取 task/iteration/commit 等  │
+└───────────────┬───────────────────────┘
+                │
+        参数缺失？
+                │
+        是 ──► 输出交互式提示
+                │
+        否 ──► 继续
+                │
+                ▼
+┌───────────────────────────────────────┐
+│ Step 2: 前置校验（安全检查）              │
+│ - 当前分支不是 main/master？             │
+│ - 有未提交的变更？                      │
+│ - ANALYSIS.md 是否存在？                │
+│ - 是否有合并冲突？                      │
+└───────────────┬───────────────────────┘
+                │
+        校验失败？
+                │
+        是 ──► 输出问题 + 修复建议
+                │
+        否 ──► 继续
+                │
+                ▼
+┌───────────────────────────────────────┐
+│ Step 3: 调用 speccore ask               │
+└───────────────────────────────────────┘
+```
+
+---
+
+## Step 1: 参数提取
+
+| 参数 | 短名 | 长名 | 必填 | 说明 |
+|:---|:---|:---|:---|:---|
+| task | -t | --task | 否 | 目标 Task（默认 current）|
+| iteration | -i | --iteration | 否 | 目标迭代名 |
+| base | -b | --base | 否 | PR 目标分支（默认 main）|
+| draft | -d | --draft | 否 | 创建 Draft PR |
+| title | - | --title | 否 | PR 标题 |
+| commit | -c | --commit | 否 | 只提交不创建远程 PR |
+| force | -f | --force | 否 | 非交互自动提交（流水线用）|
+| confirm | - | --confirm | 否 | 确认提交（覆盖安全检查）|
+| prompt | -p | --prompt | 否 | 输出 PR 分析 Prompt |
+| response | -r | --response | 否 | 接收 AI 分析结果（JSON）|
+
+---
+
+## Step 2: 参数缺失 → 交互式提示
+
+```
+🔀 speccore pr — 代码提交与 PR
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📋 当前环境
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+迭代: Iteration-001-meeting-system（从 context.json 读取）
+当前分支: feature/Task-001-user-login
+保护分支: main（不可直接推送）
+未提交变更: 3 个文件
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📖 可用参数
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  -t, --task <id>           目标 Task（默认: current）
+  -i, --iteration <name>    目标迭代（默认: 当前迭代）
+  -b, --base <branch>       PR 目标分支（默认: main）
+  -d, --draft               创建 Draft PR
+      --title <title>       PR 标题
+  -c, --commit              只提交不创建远程 PR
+  -f, --force               非交互自动提交（流水线用）
+      --confirm             确认提交（覆盖安全检查）
+  -p, --prompt              输出 PR 分析 Prompt
+  -r, --response <json>     接收 AI 分析结果
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+💡 使用示例
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  /pr -t Task-001                           # 提交 Task-001 的变更
+  /pr -t Task-001 --commit                  # 只提交不推远程
+  /pr -t Task-001 --force                   # 自动提交（流水线用）
+  /pr -t Task-001 --prompt                  # 生成 PR 分析 Prompt
+  /pr -t Task-001 -r '{...json...}'         # 应用 AI 分析结果
+  /pr -t Task-001 --base develop            # 目标分支为 develop
+
+请补充参数后重新调用，或直接调用 /pr 提交当前变更。
+```
+
+---
+
+## Step 3: 前置校验（安全检查）
+
+### 3.1 分支安全检查
+```bash
+# 检查当前分支
+# 如果是 main/master → 阻止提交，提示创建 feature 分支
+# 如果是 feature/Task-XXX → 正常通过
+```
+
+### 3.2 未提交变更检测
+```bash
+# 检查 git status
+# 如果没有变更 → 提示没有可提交的内容
+# 如果有变更 → 列出变更文件摘要
+```
+
+### 3.3 ANALYSIS.md 路径校验
+```bash
+# 检查 020-specs/ANALYSIS.md 或 030-tasks/Task-XXX/00-specs/REQ.md
+# 如果不存在 → 提示缺少分析文档（PR 描述质量会降低）
+```
+
+### 3.4 冲突检测
+```bash
+# 检查 git diff --check（空白冲突）
+# 检查是否有未解决的合并标记（<<<<<<<）
+```
+
+### 3.5 远程仓库检查
+```bash
+# 检查是否配置了远程仓库 origin
+# 如果没有 → 提示先配置远程仓库
+```
+
+---
+
+## Step 4: 调用 speccore ask
+
+```bash
+execute_command("speccore ask '提交 Task-XXX 的代码...'")
+```
+
+> ⚠️ 最终仍然调用 `speccore ask`，不要绕过 ask 引擎。
+
+---
+
+## 核心流程（保留）
+
+```
+用户说 "提交 Task-001"
+        │
+        ▼
+┌─ 1. Prompt 模式 ─────────────────────────────┐
+│  speccore pr --prompt -t Task-001              │
+│  → CLI 收集 git diff + 读取 ANALYSIS.md       │
+│  → 输出 PR 分析 Prompt 给 AI                   │
+└───────────────┬────────────────────────────────┘
+                │
+                ▼
+┌─ 2. AI 分析 ─────────────────────────────────┐
+│  AI 返回 JSON:                                 │
+│  {                                             │
+│    "commitMsg": "提交信息（中文，<72字）",      │
+│    "analysisMatch": true|false,               │
+│    "mismatchReason": "...",                   │
+│    "recommendation": "auto-commit|confirm-first"│
+│  }                                             │
+└───────────────┬────────────────────────────────┘
+                │
+                ▼
+┌─ 3. 安全检查 ────────────────────────────────┐
+│  analysisMatch=false → 提示用户确认            │
+│  analysisMatch=true  → 自动提交               │
+└───────────────┬────────────────────────────────┘
+                │
+                ▼
+┌─ 4. 执行提交 ────────────────────────────────┐
+│  git add -A → git commit -m "..." → git push  │
+│  保护分支检查：main/master 不推送               │
+└───────────────────────────────────────────────┘
+```
+
+## 铁律
+
+1. **绝不提交到 main/master** — 必须通过 PR 合并
+2. **analysisMatch=false 时必须确认** — 防止变更超出分析范围
+3. **无变更时不执行** — 避免空提交

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` 执行核心逻辑