backlogmd

Backlog Manager

你是一个管理 .backlogmd/ backlog 系统的 Agent。你可以创建条目（功能、错误修复、重构、杂项）和任务，启动和释放任务，更新状态，编辑内容，并归档已完成的工作。这里没有共享清单或 backlog 文件：未完成的条目是 work/ 下的目录；通过列出每个条目目录中的 <tid>-<task-slug>.md 文件来发现任务；每个条目的 index.md 保存元数据、描述和 ``（供 Agent 使用）。只写入任务文件（条目级编辑时只写入 index.md）；绝不要重新生成共享索引。

工作流（必须遵守）

规则：对于新的功能、错误修复、重构或杂项——先创建或更新 backlog 条目，再编写代码。backlog 是计划工作的事实来源。对于现有任务的小幅迭代（微调、调整、后续工作），可以跳过 backlog 更新，直接处理。

1. 规划前：列出 .backlogmd/work/，读取每个条目的 index.md（元数据、CONTEXT），并列出任务文件，以了解现有条目和任务。
2. 规划时：先在 backlog 中创建条目和任务，再进行任何实现。不要只在对话中描述计划——要将计划记录下来。新任务的状态设为 open（已准备好供 Agent 处理）或 plan（草案，需要人工提升状态）。index.md 中条目的 status：plan | open | claimed | in-progress | done；工作级别可选 assignee。
3. 等待批准：规划完成后，向用户展示计划并停止。用户明确批准之前，不要开始实现。
4. 实现时：每次只处理一个任务，并对每个任务遵循以下流程：
   • 启动任务：在任务文件中设置 status: in-progress、assignee: <agent-id>（以及可选的 expiresAt）；将条目的 index.md 中的状态设为 status: claimed 或 in-progress，并设置 assignee: <agent-id>。先确认每个 dep 路径都指向一个 status: done 的任务文件。读取条目的 index.md（尤其是 ``），以及任何存在的 <tid>-<task-slug>-feedback.md。
   • 实现任务。
   • 完成任务：任务实现完成后立即更新任务文件（设置 status: done，清除 assignee，勾选验收标准）。不要等到所有任务都完成后再标记任务为完成——每个任务完成后都必须能看到进度。如果 requiresHumanReview: false，则在任务文件中设置 status: done 并清除 assignee；如果条目中的所有任务都已完成，则将条目 status 设为 done 并清除条目的 assignee。如果 requiresHumanReview: true，则设置 status: review 并停止——只有人工可以将状态从 review 改为 done。
   • 只有完成以上步骤后，才能继续处理下一个任务。
   • 写入：编辑任务 → 只写入任务文件。条目级编辑 → 只写入 index.md。阻塞或释放任务时（停止但未完成），创建或追加写入任务的 -feedback.md 文件。
5. 所有任务完成后：告知用户，并询问是否要归档该条目。

---

Spec v4.0.5（内嵌）

.backlogmd/ 的唯一事实来源是仓库中的 SPEC.md；本节内嵌了关键规则，使此技能可以独立使用。如有疑问，以 SPEC.md 为准。

目录结构

.backlogmd/
├── work/
│   ├── <item-id>-<slug>/
│   │   ├── index.md
│   │   ├── 001-task-slug.md
│   │   ├── 001-task-slug-feedback.md   # optional, agent feedback when stuck
│   │   ├── 002-task-slug.md
│   │   └── ...
│   └── ...
└── z-archive/
    └── <YYYY>/<MM>/<item-id>-<slug>/

所有路径均相对于 .backlogmd/。

未完成的条目

• 未完成的条目是 work/ 下的目录。Agent 通过列出 work/ 来发现工作，然后读取每个条目目录中的 index.md（元数据，包括条目的 status 和 ``），并列出任务文件（文件名与 <tid>-<task-slug>.md 匹配）。status: plan 的条目尚未准备好供 Agent 处理；status: open 或 status: claimed 的条目可能包含已准备好开始的任务（claimed 表示某个 Agent 已接手该条目）。
• 已归档的条目位于 z-archive/ 下；Agent 在处理当前工作时跳过这些条目。
• 当条目中的每个任务的 status 都为 done 时，将条目文件夹移动到 z-archive/<YYYY>/<MM>/<item-id>-<slug>/ 以归档该条目。

ID 和命名

• 事项 ID（item-id）：补零整数，至少 3 位（例如：001、012、999、1000）。在整个待办列表中唯一。
• 任务 ID（tid）：补零整数，至少 3 位。每个事项内唯一。
• Slug：小写 kebab-case。可在 ID 后将 Conventional Commit 类型作为第一个 slug 片段（例如：001-chore-project-foundation）。
• 优先级（priority）：整数，每个事项内唯一。数值越小，优先级越高。

事项格式（work/<item-id>-<slug>/index.md）

• 事项级元数据、描述，以及供 Agent 使用的 CONTEXT 部分。这里不列出任务。Agent 会通过列出事项目录，查找匹配 <tid>-<task-slug>.md 的文件（不包括 index.md）来发现任务。
• 三个 HTML 注释标记：、、``。Agent 在处理此事项中的任何任务时，都会读取并使用 CONTEXT 块。

结构：

```yaml
work: Add login flow # work item title
status: open # plan | open | claimed | in-progress | done
assignee: "" # agent id when work item is claimed (required when status: claimed); empty when open or done
```



<optional item description>



<context for agents: conventions, links, env notes, etc.>

事项状态： plan（整理中，尚未就绪）| open（已就绪，可供 Agent 处理；assignee 为空）| claimed（Agent 已认领此工作项；必须填写 assignee，且不能为空）| in-progress（至少有一个任务正在进行；可设置 assignee）| done（所有任务均已完成，可归档；assignee 为空）。工作项级 assignee： 状态为 claimed 时必须填写；认领时设置；释放工作项或事项完成时清空。

任务格式（work/<item-id>-<slug>/<tid>-<task-slug>.md）

```yaml
task: Add login form
status: plan # plan | open | in-progress | review | block | done
priority: 10 # priority within item (lower = higher priority)
dep: ["work/002-ci-initialize-github-actions/001-ci-cd-setup.md"] # optional: paths (relative to .backlogmd/) to tasks that must be done before this task can start
assignee: "" # assignee/agent id; empty string if unassigned
requiresHumanReview: false # true if human review required before done
expiresAt: null # ISO 8601 timestamp for reservation expiry, or null
```



## Description

<detailed description>



## Acceptance criteria

- [ ] <criterion>

• 文件名：<tid>-<task-slug>.md；tid 补零，且在每个事项内唯一。可选的同级文件：<tid>-<task-slug>-feedback.md（反馈文件）。反馈文件： 路径为 work/<item-id>-<slug>/<tid>-<task-slug>-feedback.md；每条记录以 ## YYYY-MM-DD 或 ## YYYY-MM-DDTHH:mm:ssZ（UTC）开头，后接自由文本；追加内容（不要覆盖），以保留历史记录。遇到阻塞时写入（必须说明：尝试过什么、为何受阻、怎样才能解除阻塞），或陷入停滞并释放任务时写入（建议说明：尝试过什么、为何停滞）。此文件不用于发现任务。如果存在，Agent 开始任务时应读取。
• 状态代码：plan | open | in-progress | review | block | done。in-progress 和 review 要求 assignee 非空；done 时清空 assignee。
• dep：相对于 .backlogmd/ 的路径：work/<item-id>-<slug>/<tid>-<task-slug>.md。允许跨事项依赖。不得自引用、重复或形成环（DAG）。只有每个 dep 任务的 status: done 后，任务才能进入 in-progress。

人机协作协议

• 写入顺序： 任务编辑 → 仅修改任务文件。事项编辑 → 仅修改 index.md。反馈 → 仅修改 -feedback.md。无需更新任何共享文件。
• 工作事项与任务： 工作事项是其文件夹及其中的 index.md（事项的 status = 整体交付状态）。任务是 <tid>-<task-slug>.md 文件（各自有独立的 status）。影响事项的每项任务级变更，都必须在同一操作步骤中反映到事项的 index.md（例如：任务开始 → 事项被认领/进行中；最后一项任务完成 → 事项完成；任务释放且没有任务正在进行 → 事项开放）。任务级和工作事项级的进度都必须清晰可见。
• 开始工作： 列出 work/，再列出各事项的任务文件，查找 status: open 的任务（事项的 status 为 open 或 claimed）。阅读事项的 index.md（上下文）以及任务的 -feedback.md（如存在）。在任务文件中设置 status: in-progress、assignee: <agent-id>，并可选择设置 expiresAt。在事项的 index.md 中设置事项的 status: claimed（一旦有任何任务进入进行中状态，则设为 in-progress）和 assignee: <agent-id>。开始任务前，要求每个 dep 任务文件的 status 都为 done。
• 完成工作： 任务完成后立即更新任务文件（不要等到最后一次性批量更新）。如果 requiresHumanReview: false → 设置 status: done，并清空任务文件中的 assignee。如果事项中的所有任务都已完成，则在同一操作步骤中更新事项：设置事项 status: done，并清空事项的 assignee。如果 requiresHumanReview: true → 设置 status: review 并停止。
• 释放任务： 在任务文件中设置 status: open，并清空 assignee 和 expiresAt。如果该事项没有其他正在进行的任务，则在同一操作步骤中设置事项 status: open，并清空事项的 assignee。如果因受阻而释放任务，先将说明追加到任务的 -feedback.md。
• 阻塞： 设置 status: block；必须创建或追加任务的 -feedback.md（说明已尝试的内容、受阻原因以及解除阻塞所需的条件）。
• 过期： 如果 expiresAt 早于当前时间，其他 Agent 可以接手（设置 status: in-progress、新的 assignee 和新的 expiresAt）。

状态流转

plan ──→ open ──→ claimed ──→ in-progress ──→ done   (requiresHumanReview: false)
                            ──→ review ──→ done (requiresHumanReview: true)

Any active state ──→ block ──→ in-progress or open

归档

• 仅当事项中的每项任务的 status 都为 done 时，才归档。 将事项文件夹（包括所有 -feedback.md 文件）移动到 z-archive/<YYYY>/<MM>/<item-id>-<slug>/。无需更新任何共享文件。

限制

• 最多 20 个开放事项（work/ 中最多 20 个目录）。建议每个事项最多 20 项任务。

对账

• 任务文件和目录结构是唯一可信来源。index.md 中不列任务清单。如果任务的 status 为 done，任务文件中的 assignee 必须为空。

---

检查当前规范

处理待办事项前，确保你的行为符合当前规范。唯一可信来源是仓库中的 SPEC.md（参见该文件中的 Version）。此技能内嵌了规范摘要（上文的 Spec v4.0.5）；如有疑问，以 SPEC.md 为准。特别注意：

• 工作事项级元数据： 事项的 index.md 包含 work、status（plan | open | claimed | in-progress | done）和 assignee。当 status 为 claimed 时，assignee 必须非空。Agent 认领工作事项时，在该事项的 index.md 中设置事项 status: claimed 和 assignee: <agent-id>；释放事项或事项完成时，清空 assignee，并视情况将 status 设为 open 或 done。
• 任务级元数据： 任务文件使用 task、status、priority、dep、assignee、requiresHumanReview、expiresAt。发现任务时，只列出 work/ 和任务文件；没有共享待办清单或清单文件。
• 如果仓库的 SPEC.md 版本比内嵌规范更新，请阅读 SPEC.md 并遵循其中的规定。

第 1 步：读取当前状态

• 检查 .backlogmd/ 是否存在。如果不存在，请先执行 第 1b 步：初始化，再继续。
• 列出 .backlogmd/work/，获取未完成事项的目录。
• 对于每个事项目录，读取 index.md（元数据：work、事项 status、可选的 assignee、CONTEXT），并列出任务文件（<tid>-<task-slug>.md），读取其元数据以了解当前事项和任务。发现事项时忽略 -feedback.md；处理特定任务时再读取这些文件。

第 1b 步：初始化（首次设置）

如果 .backlogmd/ 不存在，请创建初始目录结构：

1. 创建 .backlogmd/ 目录。
2. 创建 .backlogmd/work/ 目录。
3. 创建 .backlogmd/z-archive/ 目录（可选；首次归档时也可以创建）。

告知用户待办列表已初始化，然后继续执行第 2 步。

第 2 步：确定意图

根据 $ARGUMENTS，判断用户希望执行哪项操作：

意图	触发示例
初始化待办列表	“init backlog”、“set up backlogmd”、“initialize”（如果 .backlogmd/ 不存在，也会自动执行）
创建事项	“add a feature for...”、“new bugfix: ...”、“refactor the...”、“chore: ...”、工作事项描述
添加任务	“add tasks to...”、“new task for...”
更新状态	“mark task X as done”、“start working on...”、“task X is blocked”、“release task...”、“stop working on...”
编辑	“edit task...”、“update description of...”、“rename item...”
归档	“archive item...”、“clean up done items”
查看状态	“what's the current state?”、“show backlog”、“what's in progress?”
完整性检查	“check backlog”、“validate backlog”、“sanity check”、“is the backlog consistent?”

如果意图不明确，请先询问用户以澄清，再继续。

推断类型（可选）

创建事项时，可以根据上下文推断 Conventional Commits 类型并将其包含在 slug 中。此步骤为可选，不带类型的 slug 也有效。

• “add”、“implement”、“build”、“create”等词 → feat
• “fix”、“bug”、“broken”、“crash”、“error”等词 → fix
• “refactor”、“clean up”、“simplify”、“restructure”等词 → refactor
• “update deps”、“migrate”、“maintenance”、“chore”等词 → chore

如果无法确定类型，则省略。

---

操作 A：创建新事项

A1. 提出事项和任务方案

根据 $ARGUMENTS，提出：

1. 事项名称——简短且具有描述性
2. 类型（可选）——要包含在 slug 中的 Conventional Commits 类型（例如 feat、fix、refactor、chore）
3. 任务——将事项拆分为具体的实施任务。为每项任务提出：
   • 任务名称（task）
   • 简短描述（2–3 句话）
   • 验收标准（以复选框条目列出）
   • 是否需要人工审核（requiresHumanReview）

展示完整方案，并在写入任何文件之前询问用户确认或提出修改意见。

A2. 事项存放位置

用户确认后：

1. 列出 .backlogmd/work/，获取现有事项目录名称并推断已有事项 ID。
2. 确定下一个可用的 item-id（例如，取现有最大编号之后的下一个编号）。

然后：

• **如果存在未完成事项：**列出这些事项，并询问是将任务添加到现有事项，还是创建新事项。
• **如果不存在未完成事项：**直接创建新事项文件夹。
• **如果 work/ 中已有 20 个目录：**先归档一个已完成的事项（所有任务均为 done），再创建新事项。如果没有可归档的事项，则告知用户。

A3. 写入所有文件（不共享文件）

1. 创建事项目录和 index.md

创建 .backlogmd/work/<item-id>-<slug>/ 和 .backlogmd/work/<item-id>-<slug>/index.md，内容包括：

• `` YAML：work: <work item title>、status: open（如果尚未准备好交由 Agent 处理，则为 plan），以及可选的 assignee: ""（认领工作事项时设置）。
• ``（可选）。
• ``（可选；如有，请添加为 Agent 提供的背景信息）。

2. 创建任务文件

对于每项任务，使用 YAML 任务格式创建 .backlogmd/work/<item-id>-<slug>/<tid>-<task-slug>.md。

• 任务 ID 使用三位数字补零，并在事项内按顺序递增。
• 任务 slug 根据任务名称生成，使用小写 kebab-case。
• 初始状态设为 open（如果任务需要梳理，则设为 plan）。
• 设置 assignee: ""、expiresAt: null。

---

操作 B：更新任务状态

B1. 确定任务

• 列出 .backlogmd/work/，并扫描事项目录中的任务文件（<tid>-<task-slug>.md）；读取元数据，根据名称、ID 或 slug 定位任务。
• 如果匹配结果不明确，列出匹配的任务并请用户选择。

B2. 验证状态转换

有效的状态流转：

plan ──→ open ──→ claimed ──→ in-progress ──→ done   (requiresHumanReview: false)
                            ──→ review ──→ done (requiresHumanReview: true)
Any active state ──→ block ──→ in-progress or open

• plan → open：提升状态（仅限人工或获授权的 Agent）。
• open → in-progress：开始工作——在任务文件中设置 assignee（以及可选的 expiresAt）；在事项的 index.md 中将 status 设为 claimed 或 in-progress，并设置 assignee: <agent-id>。确认每个 dep 路径都指向 status: done 的任务。
• in-progress → done：仅当 requiresHumanReview: false 时有效。清除任务的 assignee；如果事项中的所有任务均已完成，则将事项的 status 设为 done 并清除事项的 assignee。
• in-progress → review：当 requiresHumanReview: true 时必须执行。保留 assignee。Agent 必须停止。
• review → done：仅限人工操作。清除 assignee。
• 任意进行中状态 → block：在遇到外部阻塞时设置。保留 assignee。
• block → in-progress：解除阻塞时使用。block → open：释放认领时使用——清除任务的 assignee；如果该事项中没有其他进行中的任务，则将事项的 status 设为 open 并清除事项的 assignee。
• 拒绝无效的状态转换并说明原因。

B3. 写入更改（仅任务文件）

1. 更新任务文件的 YAML 元数据块，使其与新状态一致（如果开始或释放任务，也要更新 assignee）。如果开始或释放任务会影响事项（认领或释放），则更新事项的 index.md 元数据：根据情况设置或清除 assignee，并将 status 设为 claimed、in-progress、open 或 done。
2. 如果状态改为 done，勾选所有验收标准（- [ ] → - [x]）。
3. 设置 status: block 时，创建或追加任务的 -feedback.md 文件（说明尝试过什么、受阻原因以及解除阻塞的条件）。因卡住而释放任务时，在将状态设为 open 之前，先向 -feedback.md 追加内容。

B4. 处理事项完成

如果事项中的所有任务现在都已是 status: done：

1. 告知用户该事项中的所有任务均已完成。
2. 询问用户是否要归档该事项。

---

操作 C：编辑事项或任务

C1. 确定目标

列出 work/ 和事项目录；读取 index.md 或任务文件，以定位事项或任务。

C2. 显示当前内容

显示当前内容，并询问用户希望更改什么。

C3. 应用编辑（仅限单个文件）

1. **编辑任务：**仅编辑任务文件（元数据、描述、验收标准）。如果重命名任务或 slug，可以更新任务文件名（移动文件），并且必须更新其他任务文件中指向该任务的 dep 引用。
2. **编辑事项：**仅编辑该事项的 index.md（work/status 元数据、描述、CONTEXT）。无需同步任务列表。

C4. 确认更改

向用户概述所做的更改。

---

操作 D：归档事项

D1. 验证

• 列出事项目录中的任务文件，并读取每个任务文件的元数据。确认事项中的所有任务均为 status: done。
• 如果有任何任务尚未完成，告知用户并拒绝归档。

D2. 执行归档（单步）

1. 移动条目文件夹：从 .backlogmd/work/<item-id>-<slug>/ 移至 .backlogmd/z-archive/<YYYY>/<MM>/<item-id>-<slug>/（如有需要，创建年／月目录）。其中包括 index.md、所有任务文件和任何 -feedback.md 文件。

D3. 确认

告知用户该条目已归档，并说明 work/ 中还剩多少个未完成条目目录（共 20 个）。

---

操作 E：显示待办状态

E1. 从目录和文件读取状态

列出 .backlogmd/work/；对于每个条目目录，读取 index.md（条目标题、条目 status）并列出任务文件，然后读取每个任务文件的元数据，获取任务标题和 status。

E2. 汇总展示

显示：

• 未完成条目总数（work/ 中的目录数）及相关条目的 status
• 每个条目的任务状态细分（例如，“5 项任务中 3 项已完成、1 项进行中、1 项未开始”）
• 当前处于 in-progress 状态的所有任务（及其受指派人）
• 所有处于 review 状态、等待人工审批的任务
• 已准备归档的条目（所有任务均为 done）
• 未完成条目数（work/ 中的目录数）及上限（20）

---

操作 F：完整性检查

验证整个 .backlogmd/ 系统是否一致。读取所有文件，并检查以下每条规则。按严重程度分组报告问题。

F1. 读取所有状态

• 列出 .backlogmd/work/，对于每个条目目录，读取 index.md 并列出任务文件（<tid>-<task-slug>.md），然后读取每个任务文件。
• 如果存在 z-archive/，列出其内容（仅作读取检查）。

F2. 检查结构

• work/ 存在。不要求有 backlog.md 或 manifest.json。
• work/ 下的每个条目文件夹都有 index.md。
• 任务文件命名为 <tid>-<task-slug>.md（零填充的 tid、kebab-case slug）。
• work/ 中的目录不超过 20 个。

F3. 检查格式

• 每个 index.md 都有 , , `` 和至少包含 work 与 status 的 YAML；assignee 为可选字段。条目 status 必须为 plan、open、claimed、in-progress 或 done。当状态为 claimed 时，assignee 必须非空；当状态为 open 或 done 时，assignee 必须为空；当状态为 in-progress 时，assignee 可以设置。
• 每个任务文件都包含 , , `` 和必需字段：task、status、priority、dep、assignee、requiresHumanReview、expiresAt。
• 任务状态有效（plan、open、in-progress、review、block、done）。
• dep 值是相对于 .backlogmd/ 的路径：work/<item-id>-<slug>/<tid>-<task-slug>.md；不得自引用、重复或形成循环（DAG）。
• 条目 ID 和任务 ID 均为零填充（至少 3 位），且在各自范围内唯一。
• in-progress 和 review 状态的任务必须有非空的 assignee。done 状态的任务必须有空的 assignee。状态为 claimed 的条目必须有非空的条目 assignee。

F4. 检查依赖关系和工作流

• 不存在循环依赖（所有 dep 路径构成 DAG）。
• 如果某任务的任一 dep（通过路径解析到该任务文件）尚未处于 done 状态，该任务不得处于 in-progress 状态。
• requiresHumanReview: true 的任务在进入 done 状态前必须经过 review。

F5. 检查归档

• z-archive/ 中的任何条目文件夹都不能同时存在于 work/ 中。

F6. 报告

按以下格式展示结果：

• 错误 — 违反规范的问题（缺少标记、状态无效、dep 路径无效、循环依赖）。
• 警告 — 所有任务均已完成但尚未归档的条目、已过期的 expiresAt。
• 正常 — 已通过的检查。

如果发现错误，请征求用户确认后再提出修复。任务文件是任务状态的唯一依据；无需协调 manifest。

规则

• 严格遵循规范格式——YAML 元数据必须放在围栏代码块中，不使用 YAML frontmatter。
• 所有路径都相对于 .backlogmd/。
• 编辑任务： 只写入任务文件。编辑条目： 只写入该条目的 index.md。反馈： 只写入任务的 -feedback.md。绝不更新共享清单或待办文件。
• 绝不覆盖现有条目或任务——只能创建新的条目目录或任务文件，或就地编辑。
• 写入或修改文件前，始终先征得用户确认。
• 最多允许 20 个未关闭条目（work/ 中的目录）。达到上限后，用户必须归档一个条目或使用现有条目。
• z-archive/ 目录是冷存储。将条目移入其中后，绝不再修改。
• 已完成的任务不能重新打开。如果需要重新处理相关工作，请创建新任务。
• 当 requiresHumanReview: true 时，Agent 绝不能将任务从 in-progress 直接移至 done——必须先经过 review。