eliteforge-task-progress-tracker

任务进度跟踪器

目标

对于每项具体要求，在选定的任务目录下保留一个 Markdown 任务文件，并随着工作进展更新。默认目录为 docs/tasks/。 任务文件也用作中断恢复锚点：每次有意义的更改后，都创建一个 Git 提交，并将提交 ID 写入相关步骤说明。

在以下情况下使用此技能

• 用户希望 Agent 在编码前制定计划。
• 用户希望将待办事项、当前状态或进度保存在代码库中。
• 用户要求 Agent 在工作期间持续更新任务状态。
• 用户希望工作在中断后可以恢复。

文件规则

• 默认目录：docs/tasks/
• 如果用户或其他已启用的技能明确指定了任务目录，则原样使用该目录，不要同时在 docs/tasks/ 下创建重复文件。
• 已知例外：当 $eliteforge-google-stitch-onboarding 处于启用状态时，将其跟踪文件放在 docs/tasks/google-stitch-onboarding/ 下。
• 文件名：<task-description>.md
• task-description 应是对需求的简短 kebab-case 概述。
• task-description 优先使用 ASCII；如果请求使用中文，则转换为简短的英文 slug。
• 除非用户明确要求，否则不要添加 -status-process、-task 或 -todo 等固定后缀。
• 如果已有匹配的任务文件，则更新该文件，而不是创建重复文件。
• 切勿覆盖无关的任务文件。
• 任务文件必须与实际的 Git 检查点状态保持一致。

允许的状态值

• notrun
• running
• waiting_human_decision（等待人类决策：当前思路已完整，必须暂停工作，直到收到人类的决策）
• finished
• cancel

Git 检查点规则

• 将每次有意义的更改视为一个检查点。开始下一项更改前，先创建一个 git commit。
• 提交创建后，每条步骤说明都必须记录最新的相关提交 ID，使用 commit: abc1234 这样的简短格式。
• 如果某个步骤跨越多个提交，则按顺序追加记录，例如 commits: abc1234, def5678。
• 任务文件更新之间，不要留下多个互不相关的未提交修改。
• 仅记录已有提交 ID 的任务文件事务性更新本身不构成新的步骤检查点。应将其纳入下一个工作提交，或在任务暂停时纳入一个最终事务性提交。
• 如果工作区不是 Git 仓库，或无法创建提交，则在当前步骤说明和更新日志中记录阻碍，然后在继续进行更多无法恢复的更改之前告知用户。
• 恢复中断的工作时，读取最新的匹配任务文件，在相关步骤说明中找到最近记录的提交 ID，并以该提交作为恢复基线，然后再进行新的更改。

工作流

1. 开展实质性工作前，创建或更新任务文件，其中包含：
   • 需求摘要
   • 完成条件
   • 步骤列表
   • 初始 status: notrun
   • 初始 process: 0%
   • 已准备好用于记录提交 ID 的步骤备注
2. 开始实际执行时，立即更新：
   • status: running
   • process: 5%
   • 将 current_step 设为第一个活动步骤
   • 确认工作区可以创建 git 提交，以便检查点恢复
3. 每完成一个有意义的里程碑，就更新同一文件：
   • 验收标准复选框及任何现有任务复选框
   • 步骤状态
   • current_step
   • process
   • 简短的进度日志条目
   • 创建提交后记录相关提交 ID，并在下一次工作提交或最终记账提交中写回
4. 最终回复前，最后更新一次文件：
   • 成功完成：status: finished、process: 100%、所有有意义的更改均已提交，所有已完成的验收标准均已勾选
   • 需要人工决策：status: waiting_human_decision、process 保持当前有意义的百分比，并在活动步骤备注和更新日志中记录需要做出的具体决策
   • 用户停止或放弃任务：status: cancel
5. 如果任务中断，恢复时：
   • 读取所选任务目录下最新的匹配任务文件
   • 检查 current_step、最新步骤备注和最新更新日志条目
   • 从最近记录的提交 ID 继续，不要猜测当前状态

进度规则

• process 必须采用百分比格式，例如 5%、35%、100%。
• 保持进度单调递增；除非用户明确更改范围，否则不要降低进度。
• 优先采用反映实际里程碑的增量，不要虚报精确度。
• 只有在实现和验证都实际完成后，才能设为 100%。

必需模板

除非仓库已有更强的规范，否则使用此结构：

# Task: <title>

## Requirement
<short requirement summary>

## Acceptance Criteria
- [ ] <condition 1>
- [ ] <condition 2>

## Overall Status
- status: notrun
- process: 0%
- current_step: not started

## Steps
| step | description | status | note |
| --- | --- | --- | --- |
| 1 | <step 1> | notrun | commit: pending |
| 2 | <step 2> | notrun | commit: pending |

## Update Log
| time | status | process | update |
| --- | --- | --- | --- |
| <timestamp> | notrun | 0% | task initialized |

更新规则

• 步骤列表就是 TODO 列表。不要在其他位置另设一份互不关联的 TODO 清单。
• 将 Markdown 复选框视为实时状态，而非静态文本。完成某项标准或 TODO 时，应在同一轮更新中将 [ ] 改为 [x]。
• 如果工作仅部分完成或尚未验证，保持复选框未勾选，并在步骤备注或更新日志中说明尚未解决的问题。
• 如果范围变更或出现回归，导致先前已完成的项目不再有效，则将其恢复为 [ ]，并在更新日志中记录原因。
• 回复成功前，确保复选框状态与实际实现和验证状态一致。不要让已完成的项目仍未勾选。
• current_step 必须始终与 ## Steps 中的某一行一致，或设为 completed。
• 步骤状态变为 finished 时，其备注至少应包含一个提交 ID，除非用户明确要求在检查点前停止。
• 如果在现有步骤中添加了更多提交，应更新该步骤的备注和更新日志，不要留下过时的提交信息。
• 仅用于记录现有提交 ID 的记账式任务文件编辑不需要新增步骤；只需确保该编辑在下一次可用提交中持久化。
• 范围变更时，先更新 ## Requirement、## Acceptance Criteria 和 ## Steps，再继续执行。
• 如果因技术故障受阻，保持 status: running，并在步骤备注和更新日志中记录阻碍。
• 如果分析已完成，而下一步需要人工选择，则设为 status: waiting_human_decision，记录需要做出的具体决策，并暂停后续执行，直到用户作出决定。
• 为便于中断恢复，确保最新的步骤备注和更新日志条目告知下一位执行者要继续做什么，以及应从哪个提交继续。
• 条目应简洁、客观。

响应行为

• 在进度更新或最终回复中，酌情提及任务文件路径。
• 如果用户要求继续现有任务，请先搜索选定的任务目录，并从最新匹配文件及其中最近记录的提交 ID 继续。
• 如果工作在 Git 仓库之外进行，或无法创建提交，请在回复中明确说明这一限制。