speccore 6.76.1 → 6.77.1

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

@@ -0,0 +1,214 @@
+---
+name: spec-done
+description: >
+  任务归档收尾专属 Skill。在调用 speccore ask 之前，执行参数提取、
+  前置校验（Task 状态检查、依赖完成性检查、feature 分支合并检查），
+  参数缺失时输出交互式提示。不影响 speccore ask 的意图识别能力。
+allowed-tools: ["Bash", "Read"]
+disable-model-invocation: false
+---
+
+# spec-done — 任务归档收尾（专属逻辑）
+
+> **定位**：`/done` 快捷入口的专属预处理层
+> **原则**：不影响 `speccore ask` 的意图识别能力
+
+---
+
+## 调用方式
+
+```
+/done [参数]
+/done --task Task-001
+/done --all -I Iteration-001
+/done --task Task-001 --interactive
+```
+
+---
+
+## 执行流程
+
+```
+用户输入 /done [参数]
+        │
+        ▼
+┌───────────────────────────────────────┐
+│ Step 1: 参数提取                        │
+│ 从用户输入提取 task/iteration/all 等     │
+└───────────────┬───────────────────────┘
+                │
+        参数缺失？
+                │
+        是 ──► 输出交互式提示
+                │
+        否 ──► 继续
+                │
+                ▼
+┌───────────────────────────────────────┐
+│ Step 2: 前置校验                        │
+│ - Task 是否存在？                       │
+│ - 依赖任务是否已完成？                  │
+│ - feature 分支是否已合并？              │
+│ - 代码是否已提交？                      │
+└───────────────┬───────────────────────┘
+                │
+        校验失败？
+                │
+        是 ──► 输出问题 + 修复建议
+                │
+        否 ──► 继续
+                │
+                ▼
+┌───────────────────────────────────────┐
+│ Step 3: 调用 speccore ask               │
+└───────────────────────────────────────┘
+```
+
+---
+
+## Step 1: 参数提取
+
+| 参数 | 短名 | 长名 | 必填 | 说明 |
+|:---|:---|:---|:---|:---|
+| task | -t | --task | 否 | 目标 Task（支持逗号分隔批量）|
+| iteration | -i | --iteration | 否 | 目标迭代名 |
+| all | -a | --all | 否 | 自动扫描已完成任务批量归档 |
+| skipValidate | - | --skip-validate | 否 | 跳过校验 |
+| skipSync | - | --skip-sync | 否 | 跳过全局同步 |
+| interactive | - | --interactive | 否 | 交互式确认 |
+| prompt | -p | --prompt | 否 | 输出验收总结 Prompt |
+| response | -r | --response | 否 | 接收 AI 验收总结 |
+
+---
+
+## Step 2: 参数缺失 → 交互式提示
+
+```
+✅ speccore done — 任务归档收尾
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📋 当前环境
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+迭代: Iteration-001-meeting-system（从 context.json 读取）
+已完成任务: 2 个（Task-001, Task-002）
+待归档任务: 1 个（Task-003）
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📖 可用参数
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  -t, --task <id>           目标 Task（支持逗号分隔批量）
+  -i, --iteration <name>    目标迭代（默认: 当前迭代）
+  -a, --all                 自动扫描已完成任务批量归档
+      --skip-validate       跳过校验
+      --skip-sync           跳过全局同步
+      --interactive         交互式确认（推荐首次使用）
+  -p, --prompt              输出验收总结 Prompt
+  -r, --response <json>     接收 AI 验收总结
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+💡 使用示例
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  /done -t Task-001                         # 归档单个任务
+  /done -t Task-001,Task-002                # 批量归档
+  /done --all                               # 归档所有已完成任务
+  /done --all --interactive                 # 交互式确认
+  /done -t Task-001 --skip-validate         # 跳过校验直接归档
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🔄 执行流程
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  1. validate  — 规范合规校验
+  2. archive   — 任务归档
+  3. merge     — 新增需求合并回原文档
+  4. sync      — 同步到全局层
+  5. audit     — 生成审计摘要
+
+请补充参数后重新调用。
+```
+
+---
+
+## Step 3: 前置校验
+
+### 3.1 Task 存在性检查
+```bash
+# 检查 030-tasks/ 下是否存在该 Task
+# 如果不存在 → 提示可用 Task 列表
+```
+
+### 3.2 依赖任务完成性检查
+```bash
+# 读取 Task/.meta/dependencies
+# 检查依赖的 Task 是否已完成（status=done）
+# 如果有未完成依赖 → 提示用户先完成依赖任务
+```
+
+### 3.3 feature 分支合并检查
+```bash
+# 检查 feature/Task-XXX 分支是否已合并到 main
+# 如果未合并 → 提示用户先合并或创建 PR
+```
+
+### 3.4 代码提交检查
+```bash
+# 检查 Task 对应的 feature 分支是否有未提交代码
+# 如果有 → 提示用户先提交代码（speccore pr）
+```
+
+### 3.5 扫描已完成任务（--all 模式）
+```bash
+# 扫描 030-tasks/ 下 status=done 的任务
+# 列出可归档的任务清单
+```
+
+---
+
+## Step 4: 调用 speccore ask
+
+```bash
+execute_command("speccore ask '归档 Task-XXX...'")
+```
+
+> ⚠️ 最终仍然调用 `speccore ask`，不要绕过 ask 引擎。
+
+---
+
+## 核心流程（保留）
+
+```
+用户说 "归档 Task-001"
+        │
+        ▼
+┌─ 1. 前置校验 ────────────────────────────────┐
+│  - Task 存在？                               │
+│  - 依赖任务已完成？                           │
+│  - feature 分支已合并？                       │
+│  - 代码已提交？                              │
+└───────────────┬────────────────────────────────┘
+                │
+                ▼
+┌─ 2. 执行收尾（5 步）─────────────────────────┐
+│  1. validate  — 规范合规校验                  │
+│     → 发现问题？warn 并继续（可 --strict 阻断）│
+│  2. archive   — 任务归档                      │
+│     → 移动 Task 到归档目录                     │
+│  3. merge     — 新增需求合并回原文档            │
+│     → 更新 REQUIREMENT.md                     │
+│  4. sync      — 同步到全局层                   │
+│     → 更新 GLOBAL/INDEX.md                    │
+│  5. audit     — 生成审计摘要                   │
+│     → 生成 RETRO.md                          │
+└───────────────┬────────────────────────────────┘
+                │
+                ▼
+┌─ 3. 后续引导 ────────────────────────────────┐
+│  归档完成 → 引导用户 "可以开始 retro 复盘"     │
+│  或 "开始下一个 Task"                         │
+└───────────────────────────────────────────────┘
+```
+
+## 铁律
+
+1. **依赖任务必须先完成** — 不允许跳过依赖直接归档
+2. **feature 分支必须先合并** — 防止代码丢失
+3. **validate 发现问题要提示** — 即使不阻断也要明确告知

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

@@ -1,13 +1,156 @@
 ---
 name: spec-execute
-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-execute — 执行开发（专属逻辑）
 
-不要输出命令文本，不要分析意图，一切交给 speccore ask。
+> **定位**：`/execute` 快捷入口的专属预处理层
+> **原则**：不影响 `speccore ask` 的意图识别能力，只在调用 ask 之前做参数校验和上下文准备
+
+---
+
+## 调用方式
+
+```
+/execute [参数]
+/execute -t Task-001
+/execute -I Iteration-001 --all
+```
+
+---
+
+## 执行流程
+
+```
+用户输入 /execute [参数]
+        │
+        ▼
+┌───────────────────────────────────────┐
+│ Step 1: 参数提取                        │
+│ 从用户输入提取 iteration/task/all 等     │
+└───────────────┬───────────────────────┘
+                │
+        参数缺失？
+                │
+        是 ──► 输出交互式提示
+                │
+        否 ──► 继续
+                │
+                ▼
+┌───────────────────────────────────────┐
+│ Step 2: 前置校验                        │
+│ - 任务是否存在？                        │
+│ - 上游文档是否有更新？                  │
+│ - 代码模式读取（.speccore/PATTERNS/）   │
+└───────────────┬───────────────────────┘
+                │
+                ▼
+┌───────────────────────────────────────┐
+│ Step 3: 调用 speccore ask               │
+└───────────────────────────────────────┘
+```
+
+---
+
+## Step 1: 参数提取
+
+| 参数 | 短名 | 长名 | 必填 | 说明 |
+|:---|:---|:---|:---|:---|
+| iteration | -i | --iteration | 否 | 目标迭代名 |
+| task | -t | --task | 否 | 指定任务（与 --all 互斥）|
+| all | -a | --all | 否 | 全部待执行任务 |
+| force | -f | --force | 否 | 跳过确认直接执行 |
+| resume | -r | --resume | 否 | 断点续跑 |
+| batch-size | -b | --batch-size | 否 | 每批任务数（默认 3）|
+| verify | -v | --verify | 否 | 执行后自动验证 |
+| agent | - | --agent | 否 | 外部 AI 工具 |
+
+---
+
+## Step 2: 参数缺失 → 交互式提示
+
+```
+🔨 speccore execute — 执行开发
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📋 当前环境
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+迭代: Iteration-001-meeting-system（从 context.json 读取）
+待执行任务: 3 个（Task-001, Task-002, Task-003）
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📖 可用参数
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  -I, --iteration <name>    目标迭代（默认: 当前迭代）
+  -t, --task <id>           指定任务（如 Task-001）
+  -a, --all                 全部待执行任务
+  -f, --force               跳过确认直接执行
+  -r, --resume              断点续跑（从上次中断处继续）
+      --batch-size <n>      每批任务数（默认 3）
+      --verify              执行后自动运行测试验证
+      --agent <tool>        外部 AI 工具（copilot/claude/cursor/trae/qoder）
+      --ignore-upstream-update  跳过上游变更检测
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+💡 使用示例
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  /execute -t Task-001                    # 执行单个任务
+  /execute --all                          # 执行全部待完成任务
+  /execute --all --force                  # 全部执行，跳过确认
+  /execute --resume                       # 断点续跑
+  /execute --all --batch-size 5           # 每批 5 个任务
+  /execute -t Task-001 --verify           # 执行后自动验证
+
+请补充参数后重新调用。
+```
+
+---
+
+## Step 3: 前置校验
+
+### 3.1 检查任务是否存在
+```bash
+# 扫描 030-tasks/ 目录
+# 如果 Task 不存在 → 提示用户
+```
+
+### 3.2 检查任务状态
+```bash
+# 读取 Task/.meta/status
+# 如果状态为 done → 提示用户是否重新执行
+# 如果状态为 pending → 正常执行
+```
+
+### 3.3 上游变更检测
+```bash
+# 比较 020-specs/ 和 Task/00-specs/ 的 mtime
+# 如果有更新 → 提示用户建议重新拆分
+```
+
+### 3.4 读取代码模式
+```bash
+# 读取 .speccore/PATTERNS/ 中匹配的代码模式
+# 为 AI 提供参考代码片段
+```
+
+---
+
+## Step 4: 调用 speccore ask
+
+```bash
+execute_command("speccore ask '执行 Task-XXX 的开发...'")
+```
+
+> ⚠️ 最终仍然调用 `speccore ask`，不要绕过 ask 引擎。
+
+---
 
 ## 📦 批次执行模式（防止上下文溢出）
 
@@ -38,7 +181,7 @@ speccore execute --response '<代码JSON>' --task=<任务ID> -i <迭代名>
 3. 在新对话中，先读取 `<path>` 文件恢复上下文（约 1K tokens，包含已完成任务摘要、待执行任务、依赖关系）
 4. 然后执行提示的命令继续下一批次
 
-> 💡 “文件即记忆”机制：每个任务完成后，CLI 自动将进度、产出摘要、依赖关系写入摘要文件。
+> 💡 "文件即记忆"机制：每个任务完成后，CLI 自动将进度、产出摘要、依赖关系写入摘要文件。
 > 新会话只需读取这个文件（~1K tokens）就能恢复全局视角，无需重新扫描全部文件。
 
 ### 为什么需要批次执行？

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 引擎。