execution-tracking

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Execution Tracking

执行跟踪

Abstraction layer for agent execution tracking. Other skills (e.g., spec-management) express intent using abstract terms; this skill translates that intent into concrete CLI commands.

Before first use: Read references/bd-cheatsheet.md for complete command syntax, flags, ID formats, and anti-patterns.

用于Agent执行跟踪的抽象层。其他技能（例如spec-management）使用抽象术语表达意图；此技能将这些意图转换为具体的CLI命令。

首次使用前： 请阅读 references/bd-cheatsheet.md 了解完整的命令语法、参数、ID格式和反模式。

Artifact handoff protocol

工件交接协议

This skill receives handoffs from spec-management based on a four-tier tracking model:

Tier	Artifacts	This skill's role
Implementation	SPEC, STORY, BUG	Create a tracked implementation plan and task breakdown before any code is written
Coordination	EPIC, VISION, JOURNEY	Do not track directly — spec-management decomposes these into children first, then hands off the children
Research	SPIKE	Create a tracked plan when the research is complex enough to benefit from task breakdown
Reference	ADR, PERSONA, RUNBOOK	No tracking expected

If invoked directly on a coordination-tier artifact (EPIC, VISION, JOURNEY) without prior decomposition, defer to spec-management to create child SPECs or STORYs first, then create plans for those children.

本技能基于四层跟踪模型接收来自spec-management的交接：

层级	工件	本技能的角色
实现层	SPEC, STORY, BUG	编写任何代码前先创建可跟踪的实现计划和任务拆解
协调层	EPIC, VISION, JOURNEY	不直接跟踪——spec-management先将这些拆解为子项，再交接子项
研究层	SPIKE	当研究复杂度足够高，能从任务拆解中获益时，创建可跟踪的计划
参考层	ADR, PERSONA, RUNBOOK	无需跟踪

如果直接在未提前拆解的协调层工件（EPIC、VISION、JOURNEY）上调用本技能，请先委托spec-management创建子SPEC或STORY，再为这些子项创建计划。

Term mapping

术语映射

Other skills use these abstract terms. This skill maps them to the current backend (

bd

Abstract term	Meaning	bd command
implementation plan	Top-level container grouping all tasks for a spec artifact	`bd create "Title" -t epic --external-ref <SPEC-ID> --json`
task	An individual unit of work within a plan	`bd create "Title" -t task --parent <epic-id> --json`
origin ref	Immutable link from a plan to the spec that seeded it	`--external-ref <ID>` flag on epic creation
spec tag	Mutable label linking a task to every spec it affects	`--labels spec:<ID>` on create, `--add-label spec:<ID>` on update
dependency	Ordering constraint between tasks	`bd dep add <child> <parent>` (child depends on parent)
ready work	Unblocked tasks available for pickup	`bd ready --json` (NOT `bd list --ready` )
claim	Atomically take ownership of a task	`bd update <id> --claim --json`
complete	Mark a task as done	`bd close <id> --reason "..."`
abandon	Close a task that will not be completed	`bd close <id> --reason "Abandoned: <why>" --json`
escalate	Abandon + invoke spec-management to update upstream artifacts	Abandon, then invoke spec-management skill

其他技能使用如下抽象术语，本技能将其映射到当前后端（

bd

）：

抽象术语	含义	bd命令
实现计划	聚合某个规范工件所有任务的顶层容器	`bd create "Title" -t epic --external-ref <SPEC-ID> --json`
任务	计划内的单个工作单元	`bd create "Title" -t task --parent <epic-id> --json`
来源引用	计划到其生成来源规范的不可变链接	创建epic时使用 `--external-ref <ID>` 参数
规范标签	将任务关联到其影响的所有规范的可变标签	创建时使用 `--labels spec:<ID>` ，更新时使用 `--add-label spec:<ID>`
依赖	任务之间的顺序约束	`bd dep add <child> <parent>` （子任务依赖父任务）
可认领工作	未被阻塞、可以领取的任务	`bd ready --json` （不是 `bd list --ready` ）
认领	原子性获取任务所有权	`bd update <id> --claim --json`
完成	将任务标记为已完成	`bd close <id> --reason "..."`
废弃	关闭不会完成的任务	`bd close <id> --reason "Abandoned: <why>" --json`
升级	废弃任务 + 调用spec-management更新上游工件	先废弃，再调用spec-management技能

Configuration

配置

The skill stores persistent project-level configuration in

.agents/execution-tracking.vars.json

. This file is created on first run and checked on every subsequent invocation.

本技能将持久化的项目级配置存储在

.agents/execution-tracking.vars.json

中。该文件会在首次运行时创建，每次调用时都会读取校验。

First-run setup

首次运行设置

.agents/execution-tracking.vars.json

does not exist, create it by asking the user the questions below (use sensible defaults if the user says "just use defaults"):

Key	Type	Default	Question
`use_dolt`	boolean	`false`	"Should bd use Dolt for remote sync? (Requires a running Dolt server)"
`auto_prime`	boolean	`true`	"Run `bd prime` automatically on bootstrap to load workflow context?"
`fallback_format`	`"jsonl"` \| `"markdown"`	`"jsonl"`	"If bd is unavailable, use JSONL or Markdown for the fallback ledger?"

Write the file as pretty-printed JSON:

json

{
  "use_dolt": false,
  "auto_prime": true,
  "fallback_format": "jsonl"
}

On subsequent runs, read the file and apply its values — don't re-ask.

如果

.agents/execution-tracking.vars.json

不存在，通过询问用户以下问题创建该文件（如果用户说「直接用默认值」则使用合理默认值）：

键	类型	默认值	问题
`use_dolt`	布尔值	`false`	"bd是否应该使用Dolt进行远程同步？（需要运行中的Dolt服务器）"
`auto_prime`	布尔值	`true`	"引导启动时自动运行 `bd prime` 加载工作流上下文？"
`fallback_format`	`"jsonl"` \| `"markdown"`	`"jsonl"`	"如果bd不可用，使用JSONL还是Markdown作为降级台账格式？"

将文件写为格式化的易读JSON：

json

{
  "use_dolt": false,
  "auto_prime": true,
  "fallback_format": "jsonl"
}

后续运行时直接读取该文件并应用配置，不要重复询问。

Applying config

配置应用

use_dolt
: When
```
false
```
, skip all
```
bd dolt *
```
commands (start, stop, push, pull). When
```
true
```
, run
```
bd dolt start
```
during bootstrap and
```
bd dolt push
```
at session end.
auto_prime
: When
```
true
```
, run
```
bd prime
```
at bootstrap step 7. When
```
false
```
, skip it.
fallback_format
: Controls the format used by the Fallback section.

use_dolt
：值为
```
false
```
时，跳过所有
```
bd dolt *
```
命令（start、stop、push、pull）；值为
```
true
```
时，在引导启动阶段运行
```
bd dolt start
```
，会话结束时运行
```
bd dolt push
```
。
auto_prime
：值为
```
true
```
时，在引导步骤7运行
```
bd prime
```
；值为
```
false
```
时跳过该步骤。
fallback_format
：控制降级方案部分使用的格式。

Bootstrap workflow

引导工作流

Load config: Read
```
.agents/execution-tracking.vars.json
```
. If missing, run first-run setup above.
Check availability:
```
command -v bd
```
If missing, install:
- macOS:
```
brew install beads
```
- Linux:
```
cargo install beads
```
- If install fails, go to Fallback.
Check for existing database: look for
```
.beads/
```
directory.
If no
.beads/
, initialize:
```
bd init
```
.
Validate:
```
bd doctor --json
```
. If errors, try
```
bd doctor --fix
```
.
If
use_dolt
is
true
: start the Dolt server with
```
bd dolt start
```
.
If
git status
shows modified
.beads/dolt-*.pid
or
.beads/dolt-server.activity
: these are ephemeral runtime files that were tracked by mistake. See
```
.beads/README.md
```
§ "Remediation: Untrack Ephemeral Runtime Files" for the fix.
If
auto_prime
is
true
:
```
bd prime
```
for dynamic workflow context.

加载配置： 读取
```
.agents/execution-tracking.vars.json
```
，如果不存在则运行上述首次运行设置。
检查可用性： 执行
```
command -v bd
```
。
如果不存在则安装：
- macOS:
```
brew install beads
```
- Linux:
```
cargo install beads
```
- 如果安装失败，进入降级方案。
检查现有数据库： 查找
```
.beads/
```
目录。
如果没有
.beads/
则初始化：执行
```
bd init
```
。
校验： 执行
```
bd doctor --json
```
，如果有错误尝试运行
```
bd doctor --fix
```
。
如果
use_dolt
为
true
：执行
```
bd dolt start
```
启动Dolt服务器。
如果
git status
显示有修改的
.beads/dolt-*.pid
或
.beads/dolt-server.activity
：这些是被错误追踪的临时运行时文件，参考
```
.beads/README.md
```
§「修复：取消追踪临时运行时文件」解决。
如果
auto_prime
为
true
：执行
```
bd prime
```
加载动态工作流上下文。

Statuses

状态

bd accepts exactly four status values:

open

in_progress

blocked

closed

. It rejects aliases like

todo

done

. See the cheatsheet for the full status table and valid values.

To express abandonment, use

bd close <id> --reason "Abandoned: ..."

— see Escalation.

bd仅接受四种状态值：

open

、

in_progress

、

blocked

、

closed

，会拒绝

todo

、

done

等别名。完整状态表和合法值请参考速查手册。

要表示任务废弃，请使用

bd close <id> --reason "Abandoned: ..."

——参考升级流程。

Operating rules

操作规则

Always use
--json
on create/update/close — bd's human-readable output varies between versions, but JSON is stable and machine-parseable. Capture issue IDs from the JSON response so subsequent commands can reference them reliably.
Always include
--description
when creating issues — a title alone loses the "why" behind a task. Future agents (or your future self) picking up this work need enough context to act without re-researching.
Create/update tasks at the start of work, after each major milestone, and before final response — this keeps the external tracker useful as a live dashboard rather than a post-hoc record.
Keep task titles short and action-oriented — they appear in
```
bd ready
```
output, tree views, and notifications where space is limited.
Store handoff notes in task notes (
```
--notes
```
or
```
--append-notes
```
) rather than ephemeral chat context — chat history is lost between sessions, but task notes persist and are visible to any agent or observer.
Include references to related artifact IDs in labels (e.g.,
```
spec:SPEC-003
```
) — this makes it possible to query all work touching a given spec with
```
bd list -l spec:SPEC-003
```
.
Never use
bd edit
— it opens
```
$EDITOR
```
(vim/nano) which blocks agents. Use
```
bd update
```
with inline flags instead.
Prefix abandonment reasons with
Abandoned:
when closing incomplete tasks — this convention makes abandoned work queryable (
```
bd search "Abandoned:"
```
) so nothing silently disappears.

所有创建/更新/关闭操作**必须使用
```
--json
```
**参数——bd的人类可读输出会随版本变化，但JSON格式稳定且可被机器解析。从JSON响应中捕获工单ID，后续命令可以可靠引用这些ID。
创建工单时必须包含
--description
——仅标题会丢失任务背后的「为什么」。后续处理该工作的Agent（或未来的你）需要足够的上下文来执行，无需重复调研。
在工作开始前、每个重要里程碑完成后、最终响应前创建/更新任务——这能让外部追踪器作为实时看板使用，而非事后记录。
任务标题保持简短、面向动作——它们会出现在
```
bd ready
```
输出、树状视图、通知等空间有限的场景中。
将交接笔记存储在任务笔记中（
```
--notes
```
或
```
--append-notes
```
），不要放在临时聊天上下文里——会话之间会丢失聊天历史，但任务笔记会持久化，所有Agent或观察者都可见。
在标签中包含关联工件ID的引用（例如
```
spec:SPEC-003
```
）——这样可以通过
```
bd list -l spec:SPEC-003
```
查询关联某个规范的所有工作。
绝对不要使用
bd edit
——它会打开
```
$EDITOR
```
（vim/nano）阻塞Agent执行，改用带内联参数的
```
bd update
```
。
关闭未完成任务时，在废弃原因前加上
Abandoned:
前缀——这个约定让废弃工作可被查询（
```
bd search "Abandoned:"
```
），避免工作项无声消失。

Spec lineage tagging

规范谱系标签

When creating tasks that implement a spec artifact:

bash

undefined

创建实现某个规范工件的任务时：

bash

undefined

Create epic with immutable origin ref

创建带不可变来源引用的epic

bd create "Implement auth" -t epic --external-ref SPEC-003 --json

Create child tasks with spec label

创建带规范标签的子任务

bd create "Add JWT middleware" -t task
--parent <epic-id> --labels spec:SPEC-003 --json

Add cross-spec impact later

后续添加跨规范影响标签

bd update <task-id> --add-label spec:SPEC-007

Query all work for a spec

查询某个规范关联的所有工作

bd list -l spec:SPEC-003

Bidirectional link between tasks in different plans

不同计划中任务的双向关联

bd dep relate <task-a> <task-b>

undefined

bd dep relate <task-a> <task-b>

undefined

Escalation

升级流程

When work cannot proceed as designed, use this protocol to abandon tasks and flow control back to spec-management for upstream changes before re-planning.

当工作无法按设计推进时，使用此协议废弃任务，将流程交回spec-management进行上游变更，之后再重新规划。

Triage table

分诊表

Scope	Situation	Action
Single task	Alternative approach exists	Abandon task, create replacement under same plan
Single task	Spec assumption is wrong	Abandon task, invoke spec-management to update SPEC, create replacement task
Multiple tasks	Direction change needed	Abandon affected tasks, create ADR + update SPEC via spec-management, seed new tasks
Entire plan	Fundamental rethink required	Abandon all tasks, abandon SPEC (and possibly EPIC) via spec-management, create new SPEC if needed

范围	场景	操作
单个任务	存在替代实现方案	废弃任务，在同一计划下创建替代任务
单个任务	规范假设错误	废弃任务，调用spec-management更新SPEC，创建替代任务
多个任务	需要调整方向	废弃受影响的任务，通过spec-management创建ADR + 更新SPEC，生成新任务
整个计划	需要彻底重新思考	废弃所有任务，通过spec-management废弃SPEC（可能包含EPIC），必要时创建新的SPEC

Abandoning tasks

废弃任务

bash

undefined

bash

undefined

Single task

单个任务

bd close <id> --reason "Abandoned: <why>" --json

Batch — close all open tasks under an epic

批量关闭某个epic下所有未完成的任务

for id in $(bd list --parent <epic-id> --status=open --json | jq -r '.[].id'); do bd close "$id" --reason "Abandoned: <why>" --json done

Preserve in-progress notes before closing

关闭前保留进行中的笔记

bd update <id> --append-notes "Abandoning: <context about partial work>" bd close <id> --reason "Abandoned: <why>" --json

undefined

bd update <id> --append-notes "Abandoning: <context about partial work>" bd close <id> --reason "Abandoned: <why>" --json

undefined

Escalation workflow

升级工作流

Record the blocker. Append notes to the plan epic explaining why work cannot proceed:
bash
```
bd update <epic-id> --append-notes "Blocked: <description of blocker>"
```
Invoke spec-management. Choose the appropriate scope:
- Spec tweak — update the SPEC's assumptions or requirements, then return here.
- Design pivot — create an ADR documenting the decision change, update affected SPECs, then return here.
- Full abandon — transition the SPEC (and possibly EPIC) to Abandoned phase via spec-management.
Seed replacement plan from the updated spec. Create a new implementation plan linked to the same (or new) SPEC via origin ref:
bash
```
bd create "Implement <updated approach>" -t epic --external-ref <SPEC-ID> --json
```
Link lineage. Preserve traceability between abandoned and replacement work:
- Use the same
```
spec:<SPEC-ID>
```
  labels on new tasks.
- Reference abandoned task IDs in the new epic's description or notes:
  bash
```
bd update <new-epic-id> --append-notes "Replaces abandoned tasks: <old-id-1>, <old-id-2>"
```

记录阻塞原因。 向计划epic追加笔记，说明工作无法推进的原因：
bash
```
bd update <epic-id> --append-notes "Blocked: <description of blocker>"
```
调用spec-management。 选择合适的处理范围：
- 规范微调——更新SPEC的假设或需求，然后返回本流程。
- 设计转向——创建ADR记录决策变更，更新受影响的SPEC，然后返回本流程。
- 完全废弃——通过spec-management将SPEC（可能包含EPIC）转为废弃阶段。
基于更新后的规范生成替代计划。 创建新的实现计划，通过来源引用关联到同一个（或新的）SPEC：
bash
```
bd create "Implement <updated approach>" -t epic --external-ref <SPEC-ID> --json
```
链接谱系。 保留废弃工作和替代工作之间的可追溯性：
- 新任务使用相同的
```
spec:<SPEC-ID>
```
  标签。
- 在新epic的描述或笔记中引用废弃任务ID：
  bash
```
bd update <new-epic-id> --append-notes "Replaces abandoned tasks: <old-id-1>, <old-id-2>"
```

Cross-spec escalation

跨规范升级

When abandoned tasks carry multiple

spec:

labels, each referenced spec may need upstream changes. Check every spec label on the abandoned tasks and invoke spec-management for each affected spec before re-planning.

bash

undefined

当废弃任务带有多个

spec:

标签时，每个被引用的规范可能都需要上游变更。检查废弃任务上的所有规范标签，重新规划前为每个受影响的规范调用spec-management。

bash

undefined

List spec labels on an abandoned task

列出废弃任务上的规范标签

bd show <id> --json | jq -r '.labels[]' | grep '^spec:'

undefined

bd show <id> --json | jq -r '.labels[]' | grep '^spec:'

undefined

"What's next?" flow

「下一步做什么？」流程

When asked what to work on next, show ready work from the execution backend:

bash

undefined

当被询问下一步应该做什么时，展示执行后端的可认领工作：

bash

undefined

Check for bd availability and initialization

检查bd可用性和初始化状态

command -v bd && [ -d .beads ]

Show unblocked tasks (blocker-aware)

展示未被阻塞的任务（感知依赖阻塞）

bd ready --json

If there are in-progress tasks, show those too

如果有进行中的任务，也一并展示

bd list --status=in_progress --json


If bd is initialized and has tasks, present the results. If bd is not initialized or has no tasks, report that and defer to the spec-management skill's `specgraph.sh next` for artifact-level guidance.

When invoked from the spec-management skill's combined "what's next?" flow, this skill provides the **task layer** — concrete claimable work items — complementing the spec layer's artifact-level readiness view.

bd list --status=in_progress --json


如果bd已初始化且有任务，展示结果。如果bd未初始化或没有任务，报告该情况，委托spec-management技能的`specgraph.sh next`提供工件级别的指导。

当从spec-management技能的组合「下一步做什么？」流程中调用时，本技能提供**任务层**——具体可认领的工作项，补充规范层的工件级就绪视图。

Observer pattern expectations

观察者模式预期

Maintain compact current-status view:
```
bd status
```
and
```
bd list --pretty
```
.
Ensure blockers are explicit:
```
bd blocked
```
shows issues with unsatisfied deps.
Use consistent labels so supervisors can filter by stream, owner, or phase.

维护简洁的当前状态视图：
```
bd status
```
和
```
bd list --pretty
```
。
确保阻塞原因明确：
```
bd blocked
```
展示未满足依赖的工单。
使用统一的标签，便于管理者按业务线、负责人或阶段过滤。

Plan ingestion (superpowers integration)

计划导入（superpowers集成）

When a superpowers plan file exists (produced by the

writing-plans

skill), use the ingestion script instead of manually decomposing tasks. The script parses the plan's

### Task N:

blocks and registers them in bd with full spec lineage.

Script location:

scripts/ingest-plan.py

(relative to this skill)

当存在superpowers计划文件（由

writing-plans

技能生成）时，使用导入脚本而非手动拆解任务。该脚本会解析计划的

### Task N:

区块，将其注册到bd中，并保留完整的规范谱系。

脚本位置：

scripts/ingest-plan.py

（相对于本技能的路径）

When to use

适用场景

A superpowers plan file exists at
```
docs/plans/YYYY-MM-DD-<name>.md
```
The plan follows the
```
writing-plans
```
format (header +
```
### Task N:
```
blocks)
You have an origin-ref artifact ID to link the plan to

```
docs/plans/YYYY-MM-DD-<name>.md
```
路径下存在superpowers计划文件
计划遵循
```
writing-plans
```
格式（头部 +
```
### Task N:
```
区块）
你有来源引用工件ID可以关联到计划

Usage

使用方法

bash

undefined

bash

undefined

Parse and register in bd

解析并注册到bd

python3 scripts/ingest-plan.py <plan-file> <origin-ref>

Parse only (preview without creating bd tasks)

仅解析（预览，不创建bd任务）

python3 scripts/ingest-plan.py <plan-file> <origin-ref> --dry-run

With additional labels

带额外标签

python3 scripts/ingest-plan.py <plan-file> <origin-ref> --labels epic:EPIC-009

undefined

python3 scripts/ingest-plan.py <plan-file> <origin-ref> --labels epic:EPIC-009

undefined

What it does

功能说明

Parses the plan header (title, goal, architecture, tech stack)
Splits on
```
### Task N:
```
boundaries
Creates a bd epic with
```
--external-ref <origin-ref>
```
Creates child tasks with
```
--labels spec:<origin-ref>
```
and full task body as description
Wires sequential dependencies (Task N+1 depends on Task N)

解析计划头部（标题、目标、架构、技术栈）
按
```
### Task N:
```
边界拆分内容
创建带
```
--external-ref <origin-ref>
```
的bd epic
创建子任务，附带
```
--labels spec:<origin-ref>
```
，将完整任务内容作为描述
建立顺序依赖（任务N+1依赖任务N）

When NOT to use

不适用场景

The plan file doesn't follow superpowers format — fall back to manual task breakdown
You need non-sequential dependencies — use the script, then adjust deps manually with
```
bd dep add
```
The plan is very short (1-2 tasks) — manual creation is faster

计划文件不遵循superpowers格式——降级为手动任务拆解
需要非顺序依赖——先用脚本，再通过
```
bd dep add
```
手动调整依赖
计划非常短（1-2个任务）——手动创建更快

Fallback

降级方案

bd

cannot be installed or is unavailable:

Log the failure reason.
Fall back to a neutral text task ledger (JSONL or Markdown checklist) in the working directory.
Use the same status model (
```
open
```
,
```
in_progress
```
,
```
blocked
```
,
```
closed
```
) and keep updates externally visible.

如果

bd

无法安装或不可用：

记录失败原因。
降级为工作目录下的中性文本任务台账（JSONL或Markdown检查清单）。
使用相同的状态模型（
```
open
```
、
```
in_progress
```
、
```
blocked
```
、
```
closed
```
），保持更新对外可见。