swain-do

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Execution Tracking

执行跟踪

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

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

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

首次使用前： 阅读skills/swain-do/references/tk-cheatsheet.md获取完整的命令语法、标志、ID格式和反模式说明。

Artifact handoff protocol

工件移交协议

This skill receives handoffs from swain-design based on a four-tier tracking model:

Tier	Artifacts	This skill's role
Implementation	SPEC	Create a tracked implementation plan and task breakdown before any code is written
Coordination	EPIC, VISION, JOURNEY	Do not track directly — swain-design 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 swain-design to create child SPECs first, then create plans for those children.

本技能基于四层跟踪模型接收来自swain-design的工件移交：

层级	工件	本技能的角色
实现层	SPEC	在编写任何代码之前，创建可跟踪的实施计划和任务分解
协调层	EPIC、VISION、JOURNEY	不直接跟踪——需先由swain-design将其分解为子工件，再移交子工件
研究层	SPIKE	当研究内容复杂到可从任务分解中受益时，创建可跟踪计划
参考层	ADR、PERSONA、RUNBOOK	无需跟踪

如果直接在未分解的协调层工件（EPIC、VISION、JOURNEY）上调用本技能，需先委托swain-design创建子SPEC，再为这些子工件创建计划。

Term mapping

术语映射

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

tk

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

其他技能使用以下抽象术语。本技能将它们映射到当前后端（

tk

）：

抽象术语	含义	tk命令
implementation plan	为某个spec工件分组所有任务的顶级容器	`tk create "Title" -t epic --external-ref <SPEC-ID>`
task	计划中的单个工作单元	`tk create "Title" -t task --parent <epic-id>`
origin ref	从计划到生成它的spec的不可变链接	创建epic时使用 `--external-ref <ID>` 标志
spec tag	将任务与其影响的所有spec关联的可变标签	创建时使用 `--tags spec:<ID>`
dependency	任务之间的顺序约束	`tk dep <child> <parent>` （子任务依赖父任务）
ready work	未被阻塞、可承接的任务	`tk ready`
claim	原子性地获取任务所有权	`tk claim <id>`
complete	将任务标记为已完成	先执行 `tk add-note <id> "reason"` ，再执行 `tk close <id>`
abandon	关闭将不会完成的任务	先执行 `tk add-note <id> "Abandoned: <why>"` ，再执行 `tk close <id>`
escalate	放弃任务并调用swain-design更新上游工件	先执行放弃操作，再调用swain-design技能

Configuration and bootstrap

配置与引导

Config stored in

.agents/execution-tracking.vars.json

(created on first run). Read references/configuration.md for first-run setup questions, config keys, and the 6-step bootstrap workflow.

配置存储在

.agents/execution-tracking.vars.json

（首次运行时创建）。阅读references/configuration.md获取首次运行设置问题、配置键和6步引导流程。

Statuses

状态

tk accepts exactly three status values:

open

in_progress

closed

. Use the

status

command to set arbitrary statuses, but the dependency graph (

ready

blocked

) only evaluates these three.

To express abandonment, use

tk add-note <id> "Abandoned: ..."

then

tk close <id>

— see Escalation.

tk仅接受三种状态值：

open

、

in_progress

、

closed

。可使用

status

命令设置任意状态，但依赖图（

ready

、

blocked

）仅评估这三种状态。

如需标记任务为已放弃，先执行

tk add-note <id> "Abandoned: ..."

再执行

tk close <id>

——详见升级处理。

Operating rules

操作规则

Always include
--description
(or
```
-d
```
) 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 tracker useful as a live dashboard rather than a post-hoc record.
Keep task titles short and action-oriented — they appear in
```
tk ready
```
output, tree views, and notifications where space is limited.
Store handoff notes using
```
tk add-note <id> "context"
```
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 tags (e.g.,
```
spec:SPEC-003
```
) — this enables querying all work touching a given spec.
Prefix abandonment reasons with
Abandoned:
when closing incomplete tasks — this convention makes abandoned work findable so nothing silently disappears.
Use
ticket-query
for structured output — when you need JSON for programmatic use, pipe through
```
ticket-query
```
(available in the vendored
```
bin/
```
directory) instead of parsing human-readable output. Example:
```
ticket-query '.status == "open"'
```

创建任务时始终包含
--description
（或
-d
）——仅标题会丢失任务背后的“原因”。未来承接工作的Agent（或未来的你）需要足够的上下文来开展工作，无需重新调研。
在工作开始时、每个重要里程碑后以及最终响应前，创建/更新任务——这能让跟踪器作为实时仪表盘发挥作用，而非事后记录。
保持任务标题简短且以行动为导向——它们会出现在
```
tk ready
```
输出、树形视图和通知中，这些场景空间有限。
使用
```
tk add-note <id> "context"
```
存储移交说明，而非临时聊天上下文——聊天记录会在会话间丢失，但任务备注会持久保存，且对所有Agent或观察者可见。
在标签中包含相关工件ID的引用（例如
```
spec:SPEC-003
```
）——这能查询所有涉及特定spec的工作。
关闭未完成任务时，放弃原因需以
Abandoned:
开头——此约定可让已放弃的工作可被找到，避免工作无声消失。
使用
ticket-query
获取结构化输出——当需要用于编程的JSON时，通过
```
ticket-query
```
（在 vendored
```
bin/
```
目录中可用）处理，而非解析人类可读的输出。示例：
```
ticket-query '.status == "open"'
```

TDD enforcement

TDD强制执行

Strict RED-GREEN-REFACTOR with anti-rationalization safeguards and completion verification. Read references/tdd-enforcement.md for the anti-rationalization table, task ordering rules, and evidence requirements.

严格遵循RED-GREEN-REFACTOR流程，并带有反合理化保护和完成验证。阅读references/tdd-enforcement.md获取反合理化表格、任务排序规则和证据要求。

Spec lineage tagging

Spec谱系标签

Use

--external-ref SPEC-NNN

on plan epics (immutable origin) and

--tags spec:SPEC-NNN

on child tasks (mutable). Query:

ticket-query '.tags and (.tags | contains("spec:SPEC-003"))'

. Cross-plan links:

tk link <task-a> <task-b>

在计划epic上使用

--external-ref SPEC-NNN

（不可变来源），在子任务上使用

--tags spec:SPEC-NNN

（可变）。查询示例：

ticket-query '.tags and (.tags | contains("spec:SPEC-003"))'

。跨计划链接：

tk link <task-a> <task-b>

。

Escalation

升级处理

When work cannot proceed as designed, abandon tasks and escalate to swain-design. Read references/escalation.md for the triage table, abandonment commands, escalation workflow, and cross-spec handling.

当工作无法按设计推进时，放弃任务并升级至swain-design。阅读references/escalation.md获取分类表格、放弃命令、升级流程和跨spec处理方式。

"What's next?" flow

“下一步工作”流程

Run

tk ready

for unblocked tasks and

ticket-query '.status == "in_progress"'

for in-flight work. If

.tickets/

is empty or missing, defer to

bash "$(find "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" -path '*/swain-design/scripts/chart.sh' -print -quit 2>/dev/null)" ready

for artifact-level guidance.

运行

tk ready

查看未被阻塞的任务，运行

ticket-query '.status == "in_progress"'

查看进行中的工作。如果

.tickets/

目录为空或不存在，可调用

bash "$(find "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" -path '*/swain-design/scripts/chart.sh' -print -quit 2>/dev/null)" ready

获取工件级指导。

Context on claim

认领任务时的上下文

When claiming a task tagged with

spec:<ID>

, show the Vision ancestry breadcrumb to provide strategic context. Run

bash "$(find "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" -path '*/swain-design/scripts/chart.sh' -print -quit 2>/dev/null)" scope <SPEC-ID> 2>/dev/null | head -5

to display the parent chain. This tells the agent/operator how the current task connects to project strategy.

当认领带有

spec:<ID>

标签的任务时，显示Vision祖先面包屑以提供战略上下文。运行

bash "$(find "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" -path '*/swain-design/scripts/chart.sh' -print -quit 2>/dev/null)" scope <SPEC-ID> 2>/dev/null | head -5

显示父链。这能让Agent/操作者了解当前任务与项目战略的关联。

Artifact/tk reconciliation

工件/tk一致性校验

When specwatch detects mismatches (

TK_SYNC

TK_ORPHAN

.agents/specwatch.log

), read references/reconciliation.md for the mismatch types, resolution commands, and reconciliation workflow.

当specwatch检测到不匹配（

.agents/specwatch.log

中的

TK_SYNC

、

TK_ORPHAN

）时，阅读references/reconciliation.md获取不匹配类型、解决命令和一致性校验流程。

Session bookmark

会话书签

After state-changing operations, update the bookmark:

bash "$(find . .claude .agents -path '*/swain-session/scripts/swain-bookmark.sh' -print -quit 2>/dev/null)" "<action> <task-description>"

在执行状态变更操作后，更新书签：

bash "$(find . .claude .agents -path '*/swain-session/scripts/swain-bookmark.sh' -print -quit 2>/dev/null)" "<action> <task-description>"

Superpowers skill chaining

超能力技能链

When superpowers is installed, swain-do must invoke these skills at the right moments — do not skip them or inline the work:

Before writing code for any task: Invoke the
```
test-driven-development
```
skill. Write a failing test first (RED), then make it pass (GREEN), then refactor. This applies to every task, not just the first one.
When dispatching parallel work: Invoke
```
subagent-driven-development
```
(if subagents are available and tasks are independent) or
```
executing-plans
```
(if serial). Read references/execution-strategy.md for the decision tree.
Before claiming any task or plan is complete: Invoke
```
verification-before-completion
```
. Run the verification commands, read the output, and only then assert success. No completion claims without fresh evidence.

Detection:

ls .agents/skills/test-driven-development/SKILL.md .claude/skills/test-driven-development/SKILL.md 2>/dev/null

— if at least one path exists, superpowers is available. Cache the result for the session.

When superpowers is NOT installed, swain-do uses its built-in TDD enforcement (see references/tdd-enforcement.md) and serial execution.

当安装了超能力（superpowers）时，swain-do 必须在合适的时机调用以下技能——不得跳过或内联工作：

为任何任务编写代码前： 调用
```
test-driven-development
```
技能。先编写失败的测试（RED），再让测试通过（GREEN），最后重构。这适用于所有任务，而非仅第一个任务。
分配并行工作时： 调用
```
subagent-driven-development
```
（如果子Agent可用且任务独立）或
```
executing-plans
```
（如果任务是串行的）。阅读references/execution-strategy.md获取决策树。
认领任务或宣布计划完成前： 调用
```
verification-before-completion
```
。运行验证命令，读取输出，然后再断言成功。无新鲜证据不得宣布完成。

检测方式：

ls .agents/skills/test-driven-development/SKILL.md .claude/skills/test-driven-development/SKILL.md 2>/dev/null

——如果至少有一个路径存在，则超能力可用。将结果缓存到当前会话中。

当未安装超能力时，swain-do使用内置的TDD强制执行机制（详见references/tdd-enforcement.md）和串行执行方式。

Plan ingestion (superpowers integration)

计划导入（超能力集成）

When a superpowers plan file exists, use the ingestion script (

skills/swain-do/scripts/ingest-plan.py

) instead of manual task decomposition. Read references/plan-ingestion.md for usage, format requirements, and when NOT to use it.

当超能力计划文件存在时，使用导入脚本（

skills/swain-do/scripts/ingest-plan.py

）而非手动分解任务。阅读references/plan-ingestion.md获取用法、格式要求和不适用场景。

Execution strategy

执行策略

Selects serial vs. subagent-driven execution based on superpowers availability and task complexity. Read references/execution-strategy.md for the decision tree, detection commands, and worktree-artifact mapping.

根据超能力可用性和任务复杂度选择串行或子Agent驱动的执行方式。阅读references/execution-strategy.md获取决策树、检测命令和工作树-工件映射。

Pre-plan implementation detection

预计划实现检测

Before creating a plan for a SPEC, check whether it is already implemented. Perform all three steps:

Step 1 — Check git history for the spec ID:

bash

git log --oneline --all | grep -i "<SPEC-ID>"

Matching commits are a strong signal.

Step 2 — Check whether deliverable files exist: Read the spec artifact to identify described deliverables (files, scripts, configs). Check whether those files exist using

ls

Glob

Step 3 — Re-run tests fresh (REQUIRED if tests are mentioned in the spec): Do NOT trust any prior claim or cached result. Run the tests now and read the actual output. This is the critical evidence gate.

Decision:

2 or more signals confirm implementation → offer the retroactive-close path (below)
1 signal → proceed with normal plan creation; note the signal in the first task's description
0 signals → proceed normally

Retroactive-close path:

Do NOT create a full task decomposition.

Create a single tracking task:

tk create "Retroactive verification: <SPEC-ID>" -t task --external-ref <SPEC-ID>

Claim it:
```
tk claim <id>
```
Run
```
verification-before-completion
```
(if superpowers installed) or re-run the spec's tests manually.
If verification passes: add a note with the evidence, close the task, then invoke swain-design to transition the spec to Complete.
If verification fails: fall back to normal plan creation — the prior implementation was incomplete.

Anti-rationalization safeguard (CRITICAL): The agent MUST re-run tests during detection — it cannot assume prior passing results are current. "Tests passed before" or "I implemented this earlier" is NOT evidence. Fresh test execution output is evidence.

为SPEC创建计划前，需检查它是否已实现。执行以下三个步骤：

步骤1——检查git历史中的spec ID：

bash

git log --oneline --all | grep -i "<SPEC-ID>"

匹配的提交是强信号。

步骤2——检查交付文件是否存在： 读取spec工件以识别描述的交付物（文件、脚本、配置）。使用

ls

或

Glob

检查这些文件是否存在。

步骤3——重新运行测试（如果spec中提到测试则为必填项）： 不得信任任何先前的声明或缓存结果。立即运行测试并读取实际输出。这是关键的证据关卡。

决策：

2个或更多信号确认已实现 → 提供追溯关闭路径（如下）
1个信号 → 按正常流程创建计划；在第一个任务的描述中记录该信号
0个信号 → 按正常流程推进

追溯关闭路径：

无需创建完整的任务分解。

创建单个跟踪任务：

tk create "Retroactive verification: <SPEC-ID>" -t task --external-ref <SPEC-ID>

认领任务：
```
tk claim <id>
```
运行
```
verification-before-completion
```
（如果已安装超能力）或手动重新运行spec的测试。
如果验证通过：添加包含证据的备注，关闭任务，然后调用swain-design将spec转换为已完成状态。
如果验证失败：回到正常计划创建流程——先前的实现不完整。

反合理化保护（至关重要）： Agent在检测过程中必须重新运行测试——不得假设先前的通过结果仍然有效。“之前测试通过”或“我之前已实现”不能作为证据。新鲜的测试执行输出才是证据。

Worktree isolation preamble

工作树隔离前置检查

Before any implementation or execution operation (plan creation, task claim, code writing, execution handoff), run this detection:

bash

GIT_COMMON=$(git rev-parse --git-common-dir 2>/dev/null)
GIT_DIR=$(git rev-parse --git-dir 2>/dev/null)
[ "$GIT_COMMON" != "$GIT_DIR" ] && IN_WORKTREE=yes || IN_WORKTREE=no

Read-only operations (

tk ready

tk show

, status checks, task queries) skip this check entirely — proceed in the current context.

If
IN_WORKTREE=yes
: already isolated. Proceed normally.

If
IN_WORKTREE=no
(main worktree) and the operation is implementation or execution:

Use the
```
EnterWorktree
```
tool to create an isolated worktree. This is the only mechanism that actually changes the agent's working directory — manual
```
git worktree add
```
+
```
cd
```
does not persist across tool calls.

After entering, re-run tab naming to reflect the new branch:

bash

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$REPO_ROOT/skills/swain-session/scripts/swain-tab-name.sh" --path "$(pwd)" --auto

If EnterWorktree
fails — stop. Surface the error to the operator. Do not begin implementation work.

Note: swain-session auto-enters a worktree at startup (Step 1.5), so this preamble is a fallback for sessions that skipped isolation or where the operator exited the worktree mid-session.

When all tasks in the plan complete, or when the operator requests, call

ExitWorktree

to return to the main checkout.

在执行任何实现或执行操作（计划创建、任务认领、代码编写、执行移交）前，运行以下检测：

bash

GIT_COMMON=$(git rev-parse --git-common-dir 2>/dev/null)
GIT_DIR=$(git rev-parse --git-dir 2>/dev/null)
[ "$GIT_COMMON" != "$GIT_DIR" ] && IN_WORKTREE=yes || IN_WORKTREE=no

只读操作（

tk ready

、

tk show

、状态检查、任务查询）完全跳过此检查——在当前上下文中继续执行。

如果
IN_WORKTREE=yes
：已处于隔离状态。正常推进。

如果
IN_WORKTREE=no
（主工作树）且操作是实现或执行类型：

使用
```
EnterWorktree
```
工具创建隔离的工作树。这是唯一能实际改变Agent工作目录的机制——手动
```
git worktree add
```
+
```
cd
```
无法跨工具调用持久生效。

进入工作树后，重新运行标签命名以反映新分支：

bash

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$REPO_ROOT/skills/swain-session/scripts/swain-tab-name.sh" --path "$(pwd)" --auto

如果**
```
EnterWorktree
```
失败**——停止操作。向操作者报告错误。不得开始实现工作。

注意： swain-session在启动时会自动进入工作树（步骤1.5），因此此前置检查是针对跳过隔离或操作者在会话中途退出工作树的情况的回退机制。

当计划中的所有任务完成，或操作者要求时，调用

ExitWorktree

返回主检出目录。

Fallback

回退方案

tk

cannot be found 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.

如果找不到

tk

或

tk

不可用：

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