name: spec-task
description: OpenSpec 任务生命周期管理。触发词：「开始任务」「开始做」「新任务」「执行任务」「完成任务」「结束任务」「归档任务」「任务完成」「任务状态」。自动维护项目根目录的"任务清单.md"文件，记录任务开始/完成时间、效率指标，并提供阶段流转提示。

Spec Task

基于 OpenSpec 的任务生命周期管理 skill，将 proposal → apply → archive 三阶段封装为统一的任务流程，并自动维护任务清单与效率指标。

任务生命周期

开始任务 ──▶ proposal 阶段 ──▶ 记录到任务清单.md ──▶ 用户审批
                │                      │
                ▼                      ▼
           评估复杂度            初始化交互轮次
                                       │
                                       ▼
完成归档 ◀── archive 阶段 ◀── 验证完成 ◀── apply 阶段
    │                                       │
    ▼                                       ▼
计算效率得分                           累计交互轮次
更新任务清单.md                        记录返工次数

效率指标体系

核心指标

效率得分公式

效率得分 = min(100, 基准分 × (标准轮次 / 实际轮次) × (1 - 返工次数 × 0.1))

复杂度基准参数：

返工惩罚：每次返工扣 10%（如 1 次返工，乘以 0.9）

效率等级：
- 🟢 优秀：≥ 80 分（高效完成，超预期）
- 🟡 良好：60-79 分（正常效率）
- 🔴 待改进：< 60 分（需要复盘改进）

计算示例：3星任务、8轮交互、0返工 → min(100, 80×(8/8)×1) = 80 分（优秀）

触发方式

自然语言触发（包含以下任意关键词即触发）：

显式命令触发：
- /spec-task start <描述> - 开始新任务
- /spec-task apply <change-id> - 执行已审批的任务
- /spec-task complete <change-id> - 归档已验证的任务
- /spec-task status - 查看所有任务状态

工作流程

阶段 0：需求分析（可选预处理）

在开始任务前，可调用 requirements-analysis skill 进行专业需求分析：

触发条件（满足任意一条即触发）：
- 用户明确说"分析需求"或"需求分析"
- 需求描述模糊（少于 20 字或缺少明确目标）
- 任务复杂度预估 ≥ ⭐⭐⭐⭐

触发方式：
- 自动触发："开始任务：xxx"（系统判断需要分析时）
- 手动触发："分析需求：xxx" 或 "需求分析：xxx"
- 跳过分析："快速开始任务：xxx"

需求分析流程：
1. 5W2H 澄清 - 全面理解需求背景
2. 用户故事拆解 - 转化为可执行的用户故事
3. INVEST 检验 - 确保用户故事质量
4. MoSCoW 排序 - 确定优先级和 MVP 范围
5. 验收标准定义 - Given-When-Then 格式

输出：
- 生成 requirements.md 文件
- 作为后续 proposal 的输入基础
- 用户故事自动映射到 tasks.md

详细方法论参考 requirements-analysis skill。

阶段 1：开始任务 (Start)

当用户说"开始任务"或类似触发语时：

1. 判断是否需要需求分析
2. 检查需求描述清晰度
3. 复杂任务建议先进行需求分析

4. 用户可选择跳过

5. 调用 openspec-proposal 工作流

6. 按照 .agent/workflows/openspec-proposal.md 的步骤执行
7. 如有 requirements.md，基于其内容创建 proposal

8. 创建 proposal.md, tasks.md, design.md（如需）和 spec deltas

9. 评估任务复杂度

10. 根据任务范围、技术难度、影响面评估 1-5 星

11. 评估标准：

    • ⭐ 简单修改，单文件，无风险
    • ⭐⭐ 小功能，2-3 文件，低风险
    • ⭐⭐⭐ 中等功能，多文件，需测试
    • ⭐⭐⭐⭐ 复杂功能，跨模块，需设计
    • ⭐⭐⭐⭐⭐ 大型变更，架构级，高风险

12. 记录到任务清单

13. 在项目根目录创建或更新 任务清单.md

14. 添加新任务条目，包含：

    • change-id、任务摘要
    • 开始时间
    • 复杂度评分
    • 交互轮次初始值
    • 状态：待审批

15. 提示用户下一步

16. 告知用户 proposal 已创建
17. 提示："请审阅 proposal，审批后说'执行任务 '"

阶段 2：执行任务 (Apply)

当用户说"执行任务"或审批通过后：

1. 检测任务状态
2. 读取 任务清单.md 确认任务存在且状态为 待审批

3. 验证 proposal 已通过审批

4. 调用 openspec-apply 工作流

5. 按照 .agent/workflows/openspec-apply.md 的步骤执行

6. 依次完成 tasks.md 中的任务项

7. 更新效率指标

8. 状态更新为：执行中 → 待验证
9. 累计交互轮次（每次用户消息 +1）

10. 如有验证失败需返工，返工次数 +1

11. 提示用户下一步

12. 告知用户实现已完成
13. 提示："请验证功能，确认后说'完成任务 '"

阶段 3：完成归档 (Complete/Archive)

当用户说"完成任务"或"归档任务"时：

1. 检测任务状态

2. 读取 任务清单.md 确认任务存在且状态为 待验证

3. 调用 openspec-archive 工作流

4. 按照 .agent/workflows/openspec-archive.md 的步骤执行

5. 归档 change 并更新 specs

6. 采集最终指标

7. 执行 git diff --stat 统计代码变更量
8. 记录最终交互轮次
9. 统计返工次数（以下情况各算 1 次返工）：
   • 用户反馈 bug 需要修复
   • 用户指出问题需要修改已完成的代码
   • 测试/验证失败需要返回修复
   • API 500 错误或运行时错误需要修复

10. 注意：正常的迭代优化（如"添加更多功能"）不算返工

11. 计算效率得分
    效率得分 = (复杂度 × 100) / (交互轮次 × (1 + 返工次数 × 0.5))

12. 根据得分确定效率等级（🟢/🟡/🔴）

13. 更新任务清单

14. 将任务从"进行中"移动到"已完成"
15. 记录完成时间、耗时
16. 记录所有效率指标和最终得分

17. 更新效率统计汇总表

18. 输出任务完成摘要

19. 展示任务完成信息和效率得分

20. 同步到 Team Skill Platform（自动执行）

21. 检查配置文件 <skill-dir>/.sync_config.json 中的 email 和 password
22. 如配置有效（非占位符），执行同步：
    bash cd <skill-dir> && python sync.py -f <project>/任务清单.md
23. 同步成功提示：「✅ 已同步到 Team Skill Platform」
24. 未配置则跳过：「ℹ️ 未配置平台凭据，已跳过同步」
25. 注意：<skill-dir> 是当前 SKILL.md 所在目录

任务清单.md 格式

# 任务清单

## 📊 效率统计

| 指标 | 本周 | 本月 | 累计 |
|------|------|------|------|
| 完成任务数 | 3 | 12 | 45 |
| 平均效率得分 | 42.5 | 38.2 | 40.1 |
| 首次通过率 | 66.7% | 75% | 71.1% |

---

## 进行中

- [ ] **add-user-auth** - 添加用户认证功能
  - 开始时间: 2026-01-21 21:30
  - 状态: 待审批
  - 复杂度: ⭐⭐⭐ (3/5)
  - 交互轮次: 2
  - Proposal: [proposal.md](openspec/changes/add-user-auth/proposal.md)

- [/] **fix-login-bug** - 修复登录验证问题
  - 开始时间: 2026-01-21 14:00
  - 状态: 执行中
  - 复杂度: ⭐⭐ (2/5)
  - 交互轮次: 6
  - 返工次数: 0
  - Proposal: [proposal.md](openspec/changes/fix-login-bug/proposal.md)

---

## 已完成

- [x] **improve-search** - 优化搜索性能
  - 开始时间: 2026-01-20 10:00
  - 完成时间: 2026-01-20 15:30
  - 耗时: 5.5 小时
  - 复杂度: ⭐⭐⭐ (3/5)
  - 交互轮次: 8
  - 返工次数: 1
  - 代码变更: +120 / -45
  - **效率得分: 25.0** 🟡
  - Proposal: [proposal.md](openspec/changes/archive/improve-search/proposal.md)

状态检测与提示

每次对话开始时，如果项目存在 任务清单.md：

1. 检测当前状态
2. 读取任务清单，识别进行中的任务

3. 检查每个任务的当前阶段

4. 智能提示

5. 如有 待审批 任务 → "有待审批的 proposal：，审批后可说'执行任务 '"
6. 如有 执行中 任务 → "任务 正在执行中，当前交互轮次：N"
7. 如有 待验证 任务 → "任务 待验证，确认后可说'完成任务 '"

辅助操作

查看任务状态

当用户说"查看任务状态"或"任务清单"时：
- 读取并展示 任务清单.md 的内容
- 按状态分组显示
- 突出显示效率统计和需要用户操作的任务

取消任务

当用户说"取消任务 "时：
- 从 任务清单.md 中移除该任务
- 可选：删除对应的 openspec/changes/ 目录
- 需要用户确认

效率报告

当用户说"效率报告"或"查看效率统计"时：
- 展示效率统计汇总表
- 按时间维度（本周/本月/累计）展示趋势
- 识别效率瓶颈并给出改进建议

注意事项

1. 任务清单位置：始终在项目根目录的 任务清单.md
2. 时间格式：使用 YYYY-MM-DD HH:mm 格式
3. 状态标记：
4. [ ] 未开始或待审批
5. [/] 进行中
6. [x] 已完成
7. 耗时计算：以小时为单位，保留一位小数
8. 效率得分：保留一位小数，附带效率等级图标
9. 交互轮次计数：从用户说"开始任务"开始，到"完成任务"结束
10. 与 OpenSpec 工作流协同：此 skill 是对现有工作流的封装，不替代它们
11. 平台同步配置（可选）：
12. 依赖：pip install requests
13. 配置文件：<skill-dir>/.sync_config.json
json { "email": "<请填写你的邮箱>", "password": "<请填写你的密码>", "api": "<请填写API地址>" }
14. 脚本位置：sync.py（与 SKILL.md 同目录）
15. 未配置或凭据为占位符时自动跳过，不影响现有流程