implement-plan

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implement Plan

实施计划

Run an approved plan from
.agent-work/tasks/
as a sequence of independently verifiable phases. The plan is the implementation authority; the repository is the reality check. Maintain a phase ledger so completed, current, queued, and blocked work never blur together.
将
.agent-work/tasks/
中已批准的计划作为一系列可独立验证的阶段来执行。计划是实施工作的权威依据;代码仓库是实际情况的校验基准。维护 phase ledger,确保已完成、当前、排队中和受阻的工作始终泾渭分明。

1. Resolve the plan and requested range

1. 确定计划与请求范围

  1. If the user supplied a plan file, use it. If they supplied a task directory, inspect it with
    ls -La -- <task-directory>
    because
    .agent-work/tasks/
    may be a symlink. Select the numbered
    *-plan-*.md
    artifact; when more than one could be current, show the candidates and ask which one governs. Ask for a path only when neither a plan nor a resolvable task directory is present.
  2. Read the complete plan, its YAML frontmatter, and every repository instruction file that applies to the files it names. Extract:
    • repository, branch, and baseline SHA metadata;
    • every phase in order, including dependencies and stated scope;
    • every change item, automated check, and manual check;
    • existing checkbox state and any implementation notes.
  3. Resolve the requested range. An explicit phase or phase range wins. Otherwise, start with the first incomplete phase and stop after that phase. If every phase is complete, proceed to final reconciliation rather than reimplementing it.
This step is complete when exactly one plan and one ordered phase range are identified, and every plan item in that range has an entry in the phase ledger.
  1. 如果用户提供了计划文件,直接使用;如果提供了任务目录,则使用
    ls -La -- <task-directory>
    检查,因为
    .agent-work/tasks/
    可能是符号链接。选择带编号的
    *-plan-*.md
    工件;如果有多个都可能是当前计划,则展示候选项并询问以哪个为准。仅当既未提供计划,也无法解析出任务目录时,才询问路径。
  2. 完整读取计划、其 YAML frontmatter,以及适用于计划所列文件的每个仓库指令文件。提取:
    • 仓库、分支和 baseline SHA 元数据;
    • 按顺序排列的每个阶段,包括依赖关系和明确范围;
    • 每个变更项、自动化检查和人工检查;
    • 现有复选框状态及任何实施说明。
  3. 确定请求范围。用户明确指定的阶段或阶段范围优先。否则,从首个未完成阶段开始,并在该阶段结束后停止。如果所有阶段均已完成,则进入最终核对,而不是重新实施。
本步骤完成时,必须已确定唯一计划和有序阶段范围,且该范围内每个计划项都已在 phase ledger 中有对应条目。

2. Establish the repository baseline

2. 建立仓库 baseline

From the repository root, record the current branch, HEAD, Git directory, and working-tree status. Compare them with the plan frontmatter and inspect the diff before writing anything.
Read
.agent-work/workspace.json
and
.agent-work/workspace.local.json
when present, with the local file taking precedence. Use their disabled state, branch template, source reference, and worktree path only to interpret the checkout the workflow already prepared; implementation does not perform setup.
  • Treat the plan's branch and SHA as planning provenance, not as an instruction to switch. Work in the current checkout or worktree when it belongs to the planned repository and the plan SHA is reachable from its history. A task branch may legitimately differ because worktree or disabled-workspace setup happened after the plan was written.
  • Stay in an already-correct worktree. This skill creates neither a worktree nor an implicit branch switch. An unrelated branch, an unreachable baseline, or a repository mismatch is a gate: report it and get direction before editing.
  • When the current checkout is the repository's default branch and the user has not explicitly chosen to implement there, confirm the intended task branch or worktree before writing.
  • Treat existing modifications and untracked files as user-owned. Record which paths predate this run and keep phase edits separable from them.
  • Read the ticket and accepted upstream artifacts when the plan points to them. Resolve conflicts by recency: plan > structure outline > TDD > design discussion > research > ticket.
For a resumed plan, classify each phase as completed, partial, queued, or blocked. Trust checked work unless the repository, tests, or commit history provides concrete contradictory evidence. Manual checkboxes count only when the human confirmed them.
This step is complete when the correct repository and branch are confirmed, pre-existing changes are accounted for, and every selected phase has a current ledger state.
从仓库根目录记录当前分支、HEAD、Git 目录和工作树状态。写入任何内容之前,将这些信息与计划 frontmatter 比较,并检查 diff。
存在时读取
.agent-work/workspace.json
和
.agent-work/workspace.local.json
;若两者都存在,则以本地文件为准。仅使用其中的禁用状态、分支模板、源引用和 worktree 路径来解释工作流已准备好的 checkout;实施过程本身不执行环境设置。
  • 将计划中的分支和 SHA 视为规划来源,而不是切换分支的指令。当当前 checkout 或 worktree 属于计划指定的仓库,且计划 SHA 可从其历史中到达时,应在其中工作。任务分支可能合理地不同,因为 worktree 或 disabled-workspace 设置发生在计划编写之后。
  • 留在已经正确配置的 worktree 中。此 skill 既不创建 worktree,也不隐式切换分支。如果分支无关、baseline 不可达或仓库不匹配,则应将其视为 gate(关卡):报告问题并在编辑前获取指示。
  • 当当前 checkout 位于仓库默认分支,且用户未明确选择在默认分支上实施时,在写入前确认目标任务分支或 worktree。
  • 将已有修改和未跟踪文件视为用户资产。记录哪些路径早于本次运行存在,并使阶段编辑与这些改动保持可区分。
  • 当计划指向工单和已接受的上游工件时,读取它们。按新旧顺序解决冲突:计划 > 结构大纲 > TDD > 设计讨论 > 研究 > 工单。
对于恢复执行的计划,将每个阶段归类为已完成、部分完成、排队中或受阻。除非仓库、测试或提交历史提供了确凿的矛盾证据,否则应信任已勾选的工作。只有在人工确认后,人工检查复选框才视为完成。
本步骤完成时,必须已确认正确的仓库和分支、已记录所有预先存在的改动,并且每个选定阶段都有当前的 ledger 状态。

3. Execute one phase

3. 执行一个阶段

Default to a fresh
implementer-agent
subagent for each phase. When the host prefixes agent names, select the qualified variant whose local name is
implementer-agent
. Send a compact contract containing only:
text
Implement Phase <N> from <plan-path>.
Resume at <first incomplete item, when applicable>.
Stay within this phase, run its automated verification, update only completed
automated checkboxes in the plan, and stop with changed files, checks, manual
checks, and deviations.
The agent reads the plan and relevant code itself; duplicating plan content in the prompt creates a second source of truth. Use a new agent for the next phase so phase boundaries remain real.
When
implementer-agent
is unavailable, or the user explicitly requests direct execution, implement the phase inline under the same contract and say which mode is active. In either mode:
  • implement the phase's intent, not merely its example snippets;
  • keep changes inside the selected phase and preserve unrelated work;
  • update an automated checkbox only after its named condition passes;
  • leave manual checkboxes open until the human confirms them;
  • stop at the phase boundary.
If the plan and repository diverge, or execution becomes blocked, read
references/deviations-and-recovery.md
and follow the matching recovery branch before continuing.
This step is complete when every change item in the current phase is either implemented or explicitly blocked, all touched paths are reported, and no item has disappeared from the phase ledger.
默认情况下,每个阶段都使用全新的
implementer-agent
subagent。当 host 为 Agent 名称添加前缀时,应选择本地名称为
implementer-agent
的限定变体。仅发送以下精简约定:
text
Implement Phase <N> from <plan-path>.
Resume at <first incomplete item, when applicable>.
Stay within this phase, run its automated verification, update only completed
automated checkboxes in the plan, and stop with changed files, checks, manual
checks, and deviations.
让 Agent 自行读取计划和相关代码;在提示中重复计划内容会形成第二个事实来源。下一个阶段使用新的 Agent,以保持真实的阶段边界。
当
implementer-agent
不可用,或用户明确要求直接执行时,在当前会话中按照相同约定实施该阶段,并说明当前采用的模式。在任一模式下:
  • 实现阶段的意图,而不只是示例代码片段;
  • 将更改限制在选定阶段内,并保留无关工作;
  • 仅在指定条件通过后才更新自动化检查复选框;
  • 在人工确认之前保持人工检查复选框未勾选;
  • 在阶段边界处停止。
如果计划与仓库不一致,或者执行受阻,请阅读
references/deviations-and-recovery.md
,并遵循匹配的恢复分支后继续。
本步骤完成时,当前阶段中的每个变更项都必须已实现或被明确标记为受阻,所有涉及的文件路径都已被报告,并且 phase ledger 中没有任何条目丢失。

4. Prove the phase

4. 验证阶段

Review the implementation independently of the implementer report. Before declaring the phase ready, read and apply
references/verification-and-checkpoints.md
.
Run every automated criterion in the phase plus any focused checks required by the actual blast radius. Fix in-scope failures and rerun the affected checks. Distinguish failures introduced by the phase from reproducible baseline failures. Inspect the complete phase diff for omissions, accidental scope, debug residue, generated artifacts, and unsafe staging candidates.
This step is complete only when every change item and automated criterion maps to recorded evidence, every failure has a disposition, and the phase diff is within scope.
独立于实现 Agent 的报告审查实现结果。在宣布该阶段可以交付之前,读取并应用
references/verification-and-checkpoints.md
。
运行该阶段中的每项自动化标准,以及根据实际影响范围需要进行的针对性检查。修复范围内的失败,并重新运行受影响的检查。区分本阶段引入的失败与可复现的 baseline 失败。检查完整的阶段 diff,寻找遗漏、意外的范围扩张、调试残留、生成工件和不安全的暂存候选项。
只有当每个变更项和自动化标准都能对应到已记录的证据、每项失败都有明确处置,并且阶段 diff 未超出范围时,本步骤才算完成。

5. Cross the human gate

5. 通过 human gate(人工关卡)

Read
references/phase-handoffs.md
and use the matching phase-ready or blocked structure. Report what changed, the exact automated results, deviations, and every still-open manual check. Then pause for the human to review the phase, perform manual checks, report problems, and authorize continuation.
  • If the phase has no manual checks, human review is still the phase boundary.
  • If the user authorized a consecutive range, use a fresh implementer and repeat automated verification at every phase boundary. Defer the human pause to the end of the range only when no intermediate manual result is a prerequisite for later work.
  • If feedback requires corrections, keep the same phase current, implement and re-prove the correction, then present the gate again.
This step is complete when every required manual check has explicit human confirmation, its checkbox is updated to match that confirmation, and the human has approved the phase or selected range.
读取
references/phase-handoffs.md
,并使用匹配的 phase-ready 或 blocked 结构。报告变更内容、准确的自动化结果、偏差,以及每项仍未完成的人工检查。随后暂停,等待人工审查该阶段、执行人工检查、报告问题并授权继续。
  • 如果该阶段没有人工检查,人工审查仍然是阶段边界。
  • 如果用户授权了连续范围,使用新的实现 Agent,并在每个阶段边界重复自动化验证。只有当任何中间人工结果都不是后续工作的前置条件时,才可将人工暂停延后到范围结束时。
  • 如果反馈要求修正,保持同一阶段为当前阶段,实施并重新验证修正,然后再次提交 gate 审核。
本步骤完成时,每项必需的人工检查都必须获得明确的人工确认,其复选框状态必须与确认结果一致,并且人工必须已批准该阶段或所选范围。

6. Create the phase checkpoint

6. 创建阶段 checkpoint(检查点)

After approval, create the phase commit unless the user has requested an uncommitted workflow. Apply the staging and commit rules in
references/verification-and-checkpoints.md
. The
.agent-work/tasks/
tree is an external task artifact and stays outside the repository commit even when the plan was edited through its symlink.
Update the ledger with the commit hash, then continue only through the phase range the user authorized. Otherwise, stop with the next queued phase named.
This step is complete when the approved phase has either one verified scoped commit or an explicit user-approved uncommitted disposition, and the working tree still preserves all unrelated changes.
获得批准后,创建阶段 commit,除非用户要求采用不提交的工作流。应用
references/verification-and-checkpoints.md
中的 staging 和 commit 规则。
.agent-work/tasks/
目录树属于外部任务工件,即使通过符号链接编辑过计划,也应保持在仓库 commit 之外。
用 commit 哈希更新 ledger,然后仅在用户授权的阶段范围内继续。否则,停止并指出下一个排队中的阶段。
本步骤完成时,已批准的阶段必须具有一个经过验证且范围明确的 commit,或具有用户明确批准的不提交处置,并且工作树仍保留所有无关改动。

7. Reconcile the completed plan

7. 核对已完成的计划

After the last phase, compare the entire plan with the final implementation and account for every planned item, automated check, manual check, deviation, and checkpoint. Run the plan's final or integration checks, then inspect the full implementation diff or commit range against the recorded baseline.
If reconciliation requires a code change, reopen the phase that owns it and repeat execution, proof, human gate, and checkpointing. Reconciliation itself does not smuggle fixes past a phase boundary.
Full completion requires all of the following:
  • every phase is complete in the ledger;
  • every automated criterion passes or has an explicitly accepted disposition;
  • every required manual criterion has human confirmation;
  • every material deviation is disclosed;
  • the implementation diff contains no unexplained out-of-scope change;
  • checkpoint commits or the approved uncommitted state are recorded.
Only after all six conditions hold, read
references/implement_plan_final_answer.md
and use its final handoff structure exactly. A selected range that ends before the plan does receives a phase-gate report, not the final-completion handoff.
最后一个阶段结束后,将完整计划与最终实现进行比对,并逐一交代每个计划项、自动化检查、人工检查、偏差和 checkpoint。运行计划的最终检查或集成检查,然后根据记录的 baseline 检查完整实现 diff 或 commit 范围。
如果核对需要代码更改,则重新打开负责该改动的阶段,并重复执行、验证、人工 gate 和 checkpoint 流程。核对本身不能让修复绕过阶段边界。
完整完成必须满足以下所有条件:
  • phase ledger 中的每个阶段均已完成;
  • 每项自动化标准均已通过,或已有明确接受的处置;
  • 每项必需的人工标准均已获得人工确认;
  • 所有重大偏差均已披露;
  • 实现 diff 中不存在无法解释的范围外改动;
  • checkpoint commit 或已批准的不提交状态均已记录。
只有上述六项条件全部成立后,才读取
references/implement_plan_final_answer.md
,并严格使用其中的最终交接结构。如果所选范围在计划结束前结束,则应提供 phase-gate 报告,而不是最终完成交接。