ticks

Ticks 工作流

Ticks 是一款专为 AI Agent 设计的问题跟踪器。tk CLI 用于管理任务，tk board 提供用于监控的网页版看板；史诗由当前执行环境通过 references/agent-runner.md 中的共享协议及其 Claude、Codex、Pi 或 Prime Agent 适配器执行。

何时使用 Ticks，何时使用 TodoWrite

以下工作适合使用 Ticks（tk）：

• 跨多个会话或对话
• 依赖其他任务
• 在其他工作期间发现，需要跟踪
• 需要人工交接或审批关卡
• 能从持久化历史记录和备注中获益

以下工作适合使用 TodoWrite：

• 简单的单会话任务
• 将在当前对话中完成的工作
• 跟踪当前工作的进展

不要过度创建 tick，把每件小事都记下来。请自行判断。

技能工作流

调用时，请遵循以下工作流：

步骤 0：检查前置条件

1. Git 仓库：

git status 2>/dev/null || git init

2. 已初始化 Ticks：

ls .tick/ 2>/dev/null || tk init

3. 已安装 tk：

which tk || echo "Install: curl -fsSL https://ticks.sh/install | sh"

当前版本的 tk 也可以直接安装或更新此技能：tk skills install ticks，但即使从未运行该命令，此技能也能正常使用。

4. Git 跟踪（重要）：

.tick/ 目录应由 git 跟踪，而不是加入 git 忽略列表。Ticks 专为版本控制而设计，因此可通过常规 git 工作流在不同机器和团队成员之间同步。

如果你在项目的 .gitignore 中看到 .tick 或 .tick/，请将其移除。只有内部或本地文件应加入 git 忽略列表，这由 .tick/.gitignore 处理（忽略 .index.json 和 logs/）。

# Check if .tick is gitignored (should return nothing)
git check-ignore .tick/

# If it returns ".tick/", remove the entry from .gitignore

5. 项目级运行器配置（.tick/config.md）：

项目可以在由 git 跟踪的 .tick/ 目录中放置 .tick/config.md 文件，为受调度的实现者提供可靠且针对项目的指导。可识别的操作部分包括：

• 测试 — 精确的测试命令，包括针对特定软件包的精准调用。这能消除最常见的重复失败：每个新 Agent 都要重新推导（或错误猜测）如何运行测试。
• 收尾证据命令 — 仅可在收尾阶段执行、由控制器管理的严格命令；不得在实现子任务、单个 tick 验证、波次后门禁或最终审查测试中执行。
• 验收证据 — 可选的、由控制器管理的收尾授权。使用 - A<n>: \exact command`` 将每项稳定的验收条目精确映射一次。命令必须原样存在于“测试”或“收尾证据命令”中，且具有唯一性；跟踪器或模型中的文本绝不授权执行 shell 命令。重复、含糊、未知、注入、缺失或跨条目的证据都会导致安全失败。
• 环境 — 编排器在启动第 1 波前运行一次的预检：CLI 工具是否存在、服务是否运行、环境变量是否已设置。请将其写成用于验证条件的命令，而不是要求 Agent 向用户询问的指令。先测试，不要询问。
• 规则 — 针对实现者的项目专属约束（命名约定、禁止的模式、必需的审查步骤等）。

在使用时重新读取 — 规则与 .tick/learnings.md 相同。编排器在运行开始时读取此文件；实现者则从其工作树中读取。两者都不得内联先前会话中的过时副本。

缺少文件时的回退行为： 当前行为——实现者自行查找测试命令。此文件仅用于补充配置。

为什么不用 AGENTS.md 或 CLAUDE.md？ 这些文件用于指导各自运行环境中的交互式 Agent。.tick/config.md 是供受调度实现者使用、与运行器无关的约定，并由程序读取。项目可以交叉引用这些文件，但运行器配置不得依赖任何一家供应商的指令文件。

6. Pi 可执行扩展（在 Pi 中运行 epic 时）：

检查 Pi 是否已注册 /ticks-plan、/ticks-run、/ticks-status 和 /ticks-dashboard（RPC 客户端可以检查 get_commands）。如果这些命令不存在，请说明该技能提供了操作说明，但无法激活扩展代码，并推荐安装此软件包：

pi install git:github.com/pengelbrecht/ticks
# Local checkout:
pi install /absolute/path/to/ticks

不要声称加载或调用此技能即可启用这些命令。通用技能安装器可能只安装了 skills/ticks/。用户可以安装此软件包，或选择 references/pi-runner.md 中的手动 Pi 适配器流程。

步骤 1：收集已有信息

创建 ticks 前，先收集已有的需求：

• 现有文档 — 规范、PRD、设计文档、README 章节或问题描述（检查仓库根目录和 docs/，但遵循仓库使用的约定）
• 对话内容 — 用户已经告诉你的内容

阅读找到的内容。不要重复询问已经有答案的问题。

步骤 2：填补差距

判断你是否足够了解这项工作，可以将其拆解。你应该能够回答：

• 这解决了什么问题？面向哪些人？
• 哪些内容在范围内，哪些只是锦上添花？
• 有哪些技术限制或偏好？
• 怎样才算“完成”？

如果存在信息缺口，通过对话补齐：先让用户不受打断地描述完整想法，然后针对不清楚之处提出具体问题（AskUserQuestion 很适合快速做多选决策）。

按工作规模记录理解：

• 小型、明确的任务 — 在对话中简要重述范围即可；确认后继续
• 较大型的功能或史诗 — 将其记录下来（例如写入 SPEC.md 或更新现有文档），以便各任务项有稳定的参考；如果已有文档，就补齐其中的缺漏，而不是从头开始
• 包含多个史诗的项目 — 执行目标设计流程（references/goal-design.md）：重新阐述、访谈、事实表、回写。它会在规划任何史诗之前，产出可验证的项目目标

能够回答上述问题后，继续创建任务项。

创建高质量任务

每项任务都应是一个原子化、可提交且包含测试的工作单元。

理想的任务应：

• 有明确、单一的交付成果
• 可通过运行测试进行验证
• 产出可演示的软件，并在前序工作基础上构建
• 可在 1-3 次 Agent 迭代内完成

好的任务：

tk create "Add email validation to registration" \
  -d "Validate email format on blur, show error below input.

Test cases:
- [email protected] -> valid
- invalid@ -> invalid
- @nodomain.com -> invalid

Run: go test ./internal/validation/..." \
  --acceptance "All validation tests pass" \
  --parent <epic-id>

不好的任务：

tk create "Add email validation" -d "Make sure emails are valid"
# No test cases, no verification criteria - agent will guess

创建每项任务前，根据 references/tick-patterns.md 运行 就绪标准 检查清单；完整模式请参阅该文件。

步骤 3：根据需求创建任务项

在前沿层级进行规划调度。 拆解是史诗中杠杆效应最高的决策。始终在前沿层级进行综合，即使实施会使用成本更低的模型或较低的推理力度。只读探索支持时，使用并行方式。请参阅 references/agent-runner.md →“规划层级”以及当前启用的运行器适配器。

在安装了扩展包的 Pi 中，优先采用安全的自动化规划：

/ticks-plan <existing-childless-epic-id>                  # model-running dry-run
/ticks-plan --requirements "new epic requirements"        # model-running dry-run
/ticks-plan <target> --apply                              # explicit tracker apply

规划试运行并非空操作：它会运行已配置的只读侦察器和前沿规划器，保存日志和报告，并报告模型用量与成本，同时保证不会对任务跟踪器进行任何更改。规划提示会将相关的 Testing、Closeout Evidence Commands、Acceptance Evidence 和 Rules 部分作为上下文，但模型无法添加或授权可执行命令。--apply 是单独的显式选项，要求控制器状态干净且当前分支不是默认分支；它会在 TUI 中再次询问，并且是唯一会创建或提交任务项的模式。侦察器数量和并发数的覆盖值均有限制（--scouts 3..6、--scout-cap 2..4）。扩展会在任何更改发生前验证严格的版本化 JSON、依赖无环性、纵向验收以及同波次文件安全；EPIC-SKELETON 由控制器而非模型添加。恢复和非 TUI 确认语义请参阅 references/pi-runner.md。

将收集到的需求转化为按史诗组织的任务项。

全局概览 — 路线图、项目和日期

可选的结构约定（梯级、容器就绪标准、周期/里程碑/计划）：references/big-picture.md

大多数工作都从这里开始：一份包含排序后的史诗和依赖关系、除此之外没有其他内容的扁平路线图。这就是**“直接交付”**默认模式，也是单一工作流所需的一切。以下功能——项目、分组、target_date——可在工作规模扩大到需要时叠加使用。

层级：tick → epic → project

Ticks 只有一种递归容器类型。角色由结构和显式的 epic 标记决定：

有子项？	有 epic 标记？	子项包含	角色
否	否	—	tick — 原子工作
否	是	—	空 epic — 需要规划
是	是	任意	epic — 编排单元（波次、收尾、复盘）
是	否	全部为原子项	bucket — 仅用于被动分组
是	否	包含容器	project — 分组 + 人工检查点

核心原则：包含是免费的、被动的；编排则需显式选择。

• 任何含有子项的 tick 都是一个容器：它汇总进度并对后代项分组。不会产生执行成本。
• -t epic 标记会将容器变为编排单元：tk next 会按波次运行其子项；它会获得 EPIC-SKELETON 流程 tick（最终审查 + 收尾/复盘——见下文），并成为路线图节点。无论 epic 为空还是已填充，该标记的含义都相同——绝不能仅从结构推断出来。将现有容器提升为 epic（tk update <id> -t epic）会立即触发 EPIC-SKELETON 检查——提升会绕过正常的规划流程，因此要在提升时，而不是之后，核实或创建这两个流程 tick。
• 一个没有标记且只有原子子项的容器是 bucket——其子项会各自进入正常就绪队列，绝不会作为一个整体进行协调。当你想将一批无关任务分组以便查看，但不想像 epic 那样运行它们时，请使用 bucket。
• 一个没有标记且至少包含一个其他容器的容器是 project。project 用于分组并提供人工检查点（见下文的延续部分）。“initiative” 只是由多个 project 组成的 project——类型相同，惯例不同。

Epic 完成定义（强烈建议）

为每个 epic 明确指定完成定义：说明整个 epic 完成时从外部可观察到的、面向用户的条件——而不只是其子 tick 已关闭。将其存储为 epic 的 --acceptance：

tk create "Auth foundation" -t epic -d "<rough scope>" \
  --acceptance "New user can sign up, log in, and see their profile end-to-end against a real DB. \`go test ./internal/auth/...\` and the e2e signup test pass. No auth route 5xxs on the happy path."

这是可选项，但强烈建议使用——它是唯一能让运行判断何时真正完成，而不只是没有剩余 tick 的内容。Epic-close 复盘会逐项根据此定义验证代码（references/agent-runner.md → 外部验证）；如果没有此定义，复盘就会回过头来从 epic 的描述中重新推导范围。

确保目标兼容。 如果 Agent 无需人工介入即可确认已达成，则完成定义是目标兼容的：

• 可检查——每一项都是可运行的命令或可观察的行为，绝不能写成“运行良好”或“感觉精致”。
• 有界定——明确说明范围并设定终点；“以及用户想要的其他任何内容”不算完成定义。
• 从外部出发——描述用户可见的行为及证明该行为的命令，而不是内部实现细节。

目标兼容的完成定义能让 epic 安全地交接并放手（见目标就绪交接）。确实需要人工判断的事项（“看起来合适”“感觉很快”）可以写下来，但应将它们置于 --awaiting 门控之后，而不是指望自主运行来解决。

Project 目标（目标设计）

Project 在上一级也应采用同样的处理方式：在 project 的描述中写明目标陈述，并将事实表——以 [A<n>] 标记的、离散且可测试的结果陈述——作为 project 的 --acceptance。在规划子 epic 之前，先依据 references/goal-design.md 中的流程与人工共同设计目标（重新表述 → 访谈 → 事实表 → 写回）。这些事实会将 project 检查点从“暂停查看”转变为逐项目标验证，并使自主运行能够合理地跨越 project 边界——或在确有缺口时停止。确保容器间的 A<n> ID 唯一（epic 和其所属 project 不能同时使用 A1）。

路线图边

如果规格涵盖多个史诗，请用排序边将它们关联起来。有两种类型，正确选择是核心决策：

• --blocked-by = 硬依赖（可行性）。 在阻塞项关闭之前，下游史诗永远不会就绪。仅在史诗确实需要其前置项时使用——包括为避免同一文件的合并冲突而选择的排序方式（这是真实约束，不是偏好）。
• --after = 软排序（偏好）。 它会排序，但绝不会阻止就绪。tk next 会将软延后的候选项排在最后，但绝不会隐藏它们——当首选史诗不可行时，选择会自然跳到第一个可行的史诗。缺失或已关闭的 --after 目标会被忽略。

tk roadmap 根据两种边类型的并集将史诗分层为多个波次，并分别标注（← blocked by: 与较软的 ← after:）；排队状态仅取决于硬边——唯一开放前置项为软依赖的史诗仍处于就绪／活跃状态。

只有最前面的史诗会有子任务 tick。下游史诗只作为父级 tick 存在——为每个史诗提供粗略的范围说明（一段文字加一份交付项列表），而非详细任务。这就是即时细化：未来的史诗可以低成本地重新排序或调整范围。

# Create the roadmap up front — only epic A gets child ticks now
tk create "Auth foundation" -t epic -d "<rough scope>"                      # A — flesh out now
tk create "Team workspaces" -t epic -d "<rough scope>" --blocked-by <A>    # B — genuinely needs A's auth model
tk create "Billing" -t epic -d "<rough scope>" --after <B>                 # C — preferred order only, no real dependency

EPIC-SKELETON 不变量：每个可运行的史诗都以两个流程 tick 结尾——先是最终审查 tick，然后是收尾 tick。 在规划时创建这两个 tick；每当史诗获得子任务 tick 时，都应紧接在实现 tick 之后立即创建（现在为最前面的史诗；下游史诗则在其收尾细化时创建）：

# 1. Final review — blocked by every last-wave implementation tick
tk create "Final review of <epic A> diff" \
  --parent <A> --role review \
  --blocked-by <last-wave-tick-1> --blocked-by <last-wave-tick-2>   # every last-wave tick

# 2. Close-out — blocked by the final review, always the last child
tk create "Close out <epic A>: run epic retro, then flesh out the next feasible epic into ticks" \
  --parent <A> --role closeout \
  --blocked-by <final-review-tick>

--role review|closeout 标志使骨架具有结构性：tk graph <epic> --json 会根据此字段报告 missing_process_ticks（没有任何子项承担的角色），因此缺失或不完整的骨架可以通过机械方式检测，而非通过标题匹配来判断。如果史诗已有这些 tick 但没有角色，请用 tk update <id> --role review|closeout 修复。

最终审查 tick 的工作是审查史诗的完整差异，并在收尾解除阻塞之前解决或分派发现的问题（完整语义见 references/agent-runner.md → “Meta-work ticks”）。执行收尾意味着：运行史诗收尾回顾（参见 references/agent-runner.md），然后按软排序选择下一个可行史诗——跳过任何被硬阻塞或设有门控的史诗——阅读其粗略范围，将其拆分为子任务 tick，包括其自身的 EPIC-SKELETON 配对 tick，然后继续执行 tk graph <that-epic>。史诗边界通过结构处理——无需酌情交接，也无需人工重新提示。

tk 的规划触发信号。 三种 CLI 信号会告诉你某个史诗现在需要规划或修复：

• tk next <roadmap-epic> --json 会在下一个项目是未阻塞且没有子项的史诗时返回 {"action":"plan",...}。人类可读的输出类似 <id> P<n> epic <title> (needs planning — no child ticks)。action 字段会出现在所有 tk next --json 结果中：就绪任务为 implement，无法规划的史诗为 plan，而 --awaiting 模式的结果为 await——因此编排可以直接据此分支处理。
• tk graph <epic> --json 会在该史诗当前可规划时（子项数量为零且未阻塞）返回 {"needs_planning": true,...}。被阻塞且没有子项的史诗，以及其子项全部关闭的史诗，会返回 false，并附带解释性的人类可读输出。
• tk graph <epic> --json 会在史诗有子项但其 EPIC-SKELETON 不完整时返回 missing_process_ticks（例如 ["review","closeout"]）——没有任何子项承担相应的 --role。解决方法是修复，而不是重新规划：创建缺失的流程 tick（使用上方的模板）。空数组表示骨架完整；对于没有子项的史诗，数组也为空，因为此时 needs_planning 才是信号，而且规划会创建骨架。

当任一信号触发时，应将史诗细化为子任务 tick（遵循上述路线图指南以及 references/tick-patterns.md 中的基础优先流程），然后继续执行 tk graph <epic>。 路线图级别的变更——添加、删除或重新排序史诗——必须由人类决定。 Agent 可以在复盘报告中提出此类变更，但不得擅自执行。

此规则也适用于分阶段的规格：重点只为当前阶段和下一阶段创建任务项。未来阶段属于路线图中的后续史诗——仅保留父级节点，范围粗略描述，暂不创建详细任务。

继续与停止

默认情况下，史诗会自动跨越史诗边界继续执行。项目边界会暂停执行，等待人工检查点——项目的最后一个子项默认带有 --awaiting checkpoint，因此运行会暂停，等待人类检查后再开始下一个项目。

# Auto-continue into epic B (default) — hard edge because B genuinely needs A
tk create "Team workspaces" -t epic -d "<rough scope>" --blocked-by <A>

# Force a human review before starting epic C — soft ordering plus a gate
tk create "Billing" -t epic -d "<rough scope>" --after <B> --awaiting checkpoint

若要在所有项目检查点都不暂停、全程自动执行，请向 tk next 传入 --autonomous，或在 .tick/config.json 中设置 policy.autonomous_mode: true。其他等待类型（work、approval、input，等等）在自主模式下仍会阻止执行——只有检查点边界会继续通过。

可交接的目标

当最前面的史诗有与目标兼容的完成定义（见上文）时，计划便可交接：运行可以细化计划、实施、审查、关闭该史诗，并沿着路线图继续推进，无需人工确认。规划完成后，应与用户一起明确作出此决定，而不是直接进入运行：

• 完成定义与目标兼容 → 建议采用放手执行的方式，并给出一条命令：从运行器运行该史诗（步骤 5）；同时向 tk next 添加 --autonomous（或设置 policy.autonomous_mode: true），以便顺利通过项目检查点。
• 缺少完成定义，或其与目标不兼容 → 说明哪些内容尚不明确，提议先完善完成定义，或者使用默认设置，在每个项目边界暂停等待人工检查点。

在这里，你可以决定运行在停止等待你之前要推进多远——一个史诗、一个项目，还是整个路线图——而不是等运行中途才发现。

同样的决定也适用于项目：如果项目的所有目标事实都可通过经批准的验收证据映射自动验证（见上文项目目标和 references/goal-design.md），就可以安全地端到端交接——运行会在项目边界验证目标，只有遇到实际缺口时才会停止。若项目包含需要人工判断的事实，无论是否启用自主模式，都会在检查点停止。

目标日期与延期信号

任何任务项都可以带有可选的 target_date（精确到 ISO 日期）。该信号是派生得出的，不会存储，因此不会过时或引发合并冲突：

• 已逾期——超过 target_date，且至少有一个未完成的后代任务项。
• 进展正常——设有 target_date，且日期尚未过去。
• （无日期）——无信号；工作完全由依赖关系驱动。

日期不会阻止执行，只会生成供人类查看和筛选查询使用的标记。

tk create "v2.0 launch" -d "<release outcome>" --target-date 2026-09-30
tk update <id> --target-date 2026-10-15   # revise the date
tk list --overdue                          # past target_date with open work
tk list --due-before 2026-08-01           # target_date strictly before this date
tk list --sort target_date                # ascending; undated ticks sort last

示例

示例 1——带日期的发布分组史诗（一个项目）

# "v2.0 launch" is created without -t epic, so it is a project — it groups and
# provides a checkpoint boundary but is not "run as a unit" itself.
# Its epics run exactly as epics do today.
tk create "v2.0 launch" -d "<release outcome>" --target-date 2026-09-30
tk create "Auth revamp" -t epic --parent <v2>                    # front epic — flesh out now
tk create "Billing"     -t epic --parent <v2> --after <auth>     # downstream — rough scope only
tk create "Dashboard"   -t epic --parent <v2> --after <billing>

# Epics auto-continue into each other. When the last one closes, the v2.0
# project boundary stops for human sign-off. target_date feeds the overdue /
# on-track signal; it never gates execution.

示例 2——嵌套项目（Linear 所称的“计划”——纯粹是一种约定）

tk create "Q3 Platform" --target-date 2026-09-30                  # top-level project
tk create "Payments"    --parent <q3> --target-date 2026-08-15    # sub-project (milestone-ish)
tk create "Auth revamp" -t epic --parent <payments>               # epic under the sub-project

# Each sub-project boundary is its own checkpoint; the engine ascends the tree as
# each level completes.

示例 3——被动分组（分组但不编排）

# No -t epic means a bucket. Groups for visibility and rolls up a count;
# the bugs inside flow through the normal ready queue independently, never
# coordinated as a unit.
tk create "Q3 bug triage"
tk create "Fix flaky login test"       --parent <triage>
tk create "Dashboard chart off-by-one" --parent <triage>

为并行执行而设计

同一波次中不存在阻塞关系的任务会并发运行，每个任务都在各自的 Git 工作树中执行。工作树可避免 Agent 在执行过程中互相覆盖，但如果两个任务都修改同一个文件，分支合并时仍会冲突；如果两个任务的测试访问同一个无法隔离的资源（例如一个测试数据库或固定端口），也会破坏彼此的运行结果。

按约束面划分。 如果两个交付项会共用一个文件或资源，那么这个共享对象——即 约束面——应决定任务边界，而不是功能列表。按以下顺序处理每个共享面（操作步骤见 references/tick-patterns.md）：

• 双方都会修改的接缝文件 → 交给一个任务。 一个负责人不会与自己冲突；将其拆分成两个任务并排序，只会推迟冲突。只有在合并后的任务会过大时，才使用 --blocked-by 进行拆分和排序——可预见的合并冲突是硬依赖，绝不能使用 --after。
• 共享的、无法隔离的资源（一个测试数据库、固定端口）→ 每个波次中最多只能有一个任务访问它，即使这意味着要将跨功能的工作合并在一起。
• 锁文件和生成文件也属于接缝： 同一波次中，两个分别添加依赖的任务都会改写 pnpm-lock.yaml/go.sum——将所有依赖添加操作放到一个较早的任务中，或将它们串行化。

在每个约束组内进行纵向切片。 按用户可见的能力（从头到尾完成一个功能）划分任务，而不是按层划分（先完成所有架构，再完成所有 API，最后完成所有 UI），这样每个任务结束时，系统都能正常运行并进行演示。纵向切片与约束面冲突时，以约束面为准。完整说明见 references/tick-patterns.md。

先定义共享契约。 如果多个任务会使用同一个接口（API 结构、数据库架构、共享类型），就创建一个任务来定义它，并让其他任务通过 --blocked-by 依赖它。提前稳定契约，可以让依赖它的任务基于明确的结构并行开展，而不是靠猜测；也能让它们在描述中使用一致的名称。

合理排序，快速发现问题。 排列任务时，应确保每个任务完成后，构建都保持通过，应用都能运行；同时将风险最高或最不确定的任务放在前面——应在第 2 个任务而不是第 12 个任务时发现假设有误。对于希望检查后再继续的阶段边界，创建一个 --awaiting checkpoint 任务；对于确实尚无定论的问题，创建一个 --awaiting input 任务，而不要猜测。

运行前，检查 Epic 的任务。 创建任务后，快速检查一遍：

1. 覆盖范围——逐项检查从已收集的理解中得出的要求（针对当前阶段），并指出由哪个任务实现。为任何遗漏补充任务。
2. 任务规模——拆分标题中需要用到“以及”的任务，或验收标准无法在 3 条要点中写清的任务。
3. 命名一致性——同一接口在各任务描述中应使用相同名称；一个任务中将契约命名为 clearLayers，另一个任务中却称为 clearFullLayers，就是一个潜在缺陷。
4. 波次安全性——运行 tk graph <epic>，确认同一波次中的任意两个任务都不会共用文件或无法隔离的资源。

这项检查成本很低，却能发现分区错误；一旦 Agent 开始运行，这些错误就很难修正。

步骤 4：指导用户完成阻塞性的人工任务

如果人工任务会阻塞自动化任务，请在运行 Agent 前指导用户完成这些任务。

# Check for blocking human tasks
tk list --awaiting work
tk blocked  # See what's waiting

指导用户完成每项阻塞任务，然后将其关闭：

tk close <id> --reason "Completed: connection string in .env"

第 5 步：运行 Epic

在当前 harness 中执行 Epic。先阅读 references/agent-runner.md，然后阅读对应的 harness 适配器：如果在 Codex 中运行，则阅读 references/codex-runner.md；如果在 Claude Code 中运行，则阅读 references/claude-runner.md；如果在 Pi 中运行，则阅读 references/pi-runner.md；如果在 Prime Agent 中运行，则阅读 references/prime-runner.md。适配器决定由谁负责编排；另一个独立选择决定如何调度工作者——即 substrate，可以是 harness 自带的子 Agent，也可以是异构的 herdr 集群（references/herdr-runner.md，须与 harness 适配器一同阅读，不能用它替代适配器）。.tick/runners.toml 中的 [orchestration].substrate（herdr | harness | auto，默认值为 auto）决定采用哪种方式；如果指定了 herdr 但不可用，则会明确降级为 harness 调度——相关语义见 references/runners-config.md。如果还没决定，请在启动前先确定 目标就绪移交（上文）的决策：本次运行应该推进到什么程度，才停下来交给人工处理？流程如下：

1. tk graph <epic-id> --json — 获取执行波次和可并行运行的任务数。如果结果包含 "needs_planning": true，说明 Epic 还没有子 tick——先补全其内容（参见上文“大局”部分），然后重新运行 tk graph。
2. EPIC-SKELETON 预检——如果同一结果包含非空的 missing_process_ticks，则在第 1 波之前，使用 --role 创建缺失的流程 tick（模板见上文“大局”部分）。
3. 对于每个波次，为每个就绪 tick 启动一个实现者，并让每个实现者使用各自独立的 git worktree，使用适配器的并行调度原语。
4. 使用适配器的完成原语等待，并暂时合并每个已验证的分支；保留分支和 worktree，推迟成功的 tracker 状态转换。
5. 将测试门禁持久化，并在完全合并后的代码树上运行。只有测试成功，才能持久地关闭该波次并清理；如果失败，则保持所有受影响的 tick 为打开状态，保留修复状态，并阻塞依赖项。然后进入下一波；实现波次完成后，最终审查和收尾 tick 会依次解除阻塞。

所有 tick 状态均由你负责；实现者只在各自的 worktree 中编写代码。除非遇到实际阻塞，否则应连续推进各个波次。

快速参考

创建 Tick

tk create "Title" -d "Description" --acceptance "Tests pass"  # Task
tk create "Title" -t epic                                     # Epic
tk create "Title" --parent <epic-id>                          # Under epic
tk create "Title" --blocked-by <task-id>                      # Blocked (hard dependency)
tk create "Title" --after <task-id>                           # Soft ordering preference (never blocks)
tk create "Title" --awaiting work                             # Human task
tk create "Title" --requires approval                         # Needs approval gate
tk create "Title" --parent <epic> --role review               # Epic's final-review process tick
tk create "Title" --parent <epic> --role closeout             # Epic's close-out process tick

Epic 也支持 --acceptance——请用它定义 Epic 的完成标准（强烈建议；参见 Epic 完成标准）。与目标相符的完成标准能让你顺利移交 Epic，然后放心离开。

tk 的长选项使用标准的双连字符。-acceptance/-parent/-blocked-by（单连字符）不可用——请使用 --acceptance/--parent/--blocked-by。-d、-t、-p、-l、-b 等单字母简写可以使用。

查询

tk list                      # All open ticks
tk list -t epic              # Epics only
tk list --parent <epic-id>   # Tasks in epic
tk ready                     # Unblocked tasks
tk next <epic-id>            # Next task for agent
tk next <epic-id> --json     # JSON: action field is "implement" | "plan" | "await"
tk blocked                   # Blocked tasks
tk list --awaiting=          # Tasks awaiting human
tk graph <epic-id>           # Dependency graph with parallelization
tk graph <epic-id> --json    # JSON output; needs_planning:true means epic needs child ticks;
                             # non-empty missing_process_ticks means EPIC-SKELETON needs repair

管理

tk show <id>                                           # Show details
tk close <id> --reason "Completed: <one-line summary>" # Close tick — always pass --reason
tk note <id> "text"                                    # Add note
tk approve <id>                                        # Approve awaiting tick
tk reject <id> "feedback"                              # Reject with required feedback

**关闭原因约定：**关闭时始终使用 --reason 并提供具体摘要。 tk close <id> --reason "Completed: <one-line summary of what landed>" — 绝不要只运行 tk close。

**执行者约定（编排运行）：**在运行开始时导出 TK_ACTOR=<runner>:orchestrator，例如 claude:orchestrator、codex:orchestrator、pi:orchestrator 或 prime:orchestrator，以便活动记录保留运行器来源。使用 --actor <name> 可覆盖单次调用的执行者。 优先级：--actor 标志 > TK_ACTOR 环境变量 > tick 所有者默认值。

运行 Epic

从当前运行框架启动执行（共享详情见 references/agent-runner.md；然后根据所用环境查看 codex-runner.md（Codex）、claude-runner.md（Claude Code）、pi-runner.md（Pi）或 prime-runner.md（Prime Agent））。

然后选择调度基础设施——运行框架原生子 Agent，或由一组 herdr 独立工作进程组成的舰队（references/herdr-runner.md，作为运行框架适配器的补充）。该设置来自 .tick/runners.toml 的 [orchestration].substrate（herdr | harness | auto，默认值为 auto；只读探测发现 herdr 时使用 herdr，否则使用运行框架）；references/runners-config.md 中有决策表和明确降级规则。

# 1. Get the dependency graph (waves + max parallelism)
tk graph <epic-id> --json

# 2. Select the role tier, then launch one isolated implementer per ready tick.
#    Planning and final review use frontier settings. Implementation uses the
#    adapter's economy/balanced/strong mapping.
#
# 3. Wait using the adapter's native primitive, then integrate each tick:
git diff --name-only HEAD...<agent-branch> -- .tick/   # boundary check: must be empty
git merge <agent-branch>   # if it conflicts: abort, have the agent rebase + resolve in its worktree
tk close <tick-id> --reason "Completed: <one-line summary of what landed>"

# 4. After the wave's merges land, run the test suite before launching the next wave

规划并行执行

启动 Agent 前，使用 tk graph 了解并行情况：

tk graph <epic-id>        # Human-readable wave breakdown
tk graph <epic-id> --json # Machine-readable for orchestration

图表显示：

• 波次：可以并行运行的 tick 分组
• 最大并行数：最宽波次中可同时启动的子 Agent 数量
• 关键路径：完成该 Epic 所需的最少连续波次数
• 依赖项：每个 tick 被哪些事项阻塞

每个波次最多启动 max_parallel 个子 Agent（如需控制成本或减少干扰，可降低数量），并在开始下一个波次前合并当前波次的工作，确保依赖项基于已完成的工作继续推进。

完整参考请见 references/tk-commands.md。

协助处理待处理的 Tick

以交互方式工作时，帮助用户处理待处理的 tick：

tk list --awaiting=   # Find ticks awaiting human
tk next --awaiting=   # Next one needing attention

使用 AskUserQuestion 帮助用户作出决定，然后执行：

# User approves
tk approve <id>

# User rejects
tk reject <id> "feedback here"

# User provides input
tk note <id> "Use sliding window algorithm" --from human
tk approve <id>

代表用户添加备注时，始终使用 --from human。