pocket-development

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Pocket Development

Pocket 开发

Execute an approved Pocket plan one task at a time or in explicitly parallel groups. The main agent coordinates work, runs mechanical checks, and dispatches independent read-only review; implementers own code changes.
Core principle: Every delegation is a contract. The packet is the contract. No packet, no spawn. Read
execution-plan/index.md
once to understand execution flow and dependencies, then open individual task files (
execution-plan/tasks/T*-*.md
) on demand when a task is ready to execute.
执行已批准的 Pocket 计划时,可以一次处理一个任务,也可以按明确指定的并行组执行。Main Agent 负责协调工作、运行机械化检查,并分派独立的只读审查;代码修改由 implementer 负责。
核心原则: 每次委派都是一份契约。Packet 就是契约。没有 Packet,就没有 spawn。先读取一次
execution-plan/index.md
,了解执行流程和依赖关系;然后在任务准备好执行时,再按需打开相应的任务文件(
execution-plan/tasks/T*-*.md
)。

Core v4 lifecycle boundary

Core v4 生命周期边界

pocket-development
is part of the local-first Core role. Core records neutral lifecycle events for approved specs, completed phases, and closed plans. Core does not call
gh
, does not merge pull requests, and does not close issues. A separately installed, optional adapter may consume durable events after a successful compatibility preflight. Core work and phase completion do not depend on that adapter; unavailable delivery leaves events pending for replay.
The v4 lifecycle commands use
--json --contract 3
.
lifecycle transition
commits local state and an event,
lifecycle drain
replays pending events in revision order without creating events, and
lifecycle repair
repairs recoverable
log.json
projection fields without emitting or dispatching an event. Active v3 plans with progress remain on v3; never silently convert their progress.
pocket-development
是 local-first Core 角色的一部分。Core 为已批准的 spec、已完成阶段和已关闭计划记录中立的生命周期事件。Core 不调用
gh
、不合并 pull request,也不关闭 issue。单独安装的可选 adapter 可以在兼容性 preflight 成功之后消费持久化事件。Core 工作和阶段完成不依赖该 adapter;如果交付不可用,事件会保持 pending 状态,以供后续 replay。
v4 生命周期命令使用
--json --contract 3
。
lifecycle transition
提交本地状态和一个事件,
lifecycle drain
按 revision 顺序 replay pending 事件而不创建事件,
lifecycle repair
修复可恢复的
log.json
投影字段,不发出或分派事件。仍有进度的活跃 v3 计划继续使用 v3;绝不静默转换其进度。

Startup: Initialize Execution Log

启动:初始化执行日志

Run this before the first task, every session:
bash
npx -y pocketto-pi log init "<plan_dir>" --json --contract 3
No install step, PATH setup, or shell-specific guard —
npx
resolves the cross-platform binary and
log init
is idempotent, so this is safe to run unconditionally every session. Replace
<plan_dir>
with the folder containing your execution plan (e.g.
docs/pocket/plans/2026-05-08-auth-refactor
).
  • No
    log.json
    yet → creates it from the plan files in that directory
  • log.json
    exists but tasks missing → migrates tasks into existing phases (status preserved)
  • log.json
    already complete → reports "no migration needed" and writes nothing
Report
data.phase_branches
and
data.branch
from the
log init
envelope. For a stacked plan,
log init
may create and switch to the phase-1 branch automatically; say so in the startup report. Later phases use the branch recorded for them in
log.json
(see the stacked branch check in
references/entry-gate.md
).
Full command reference and update/close commands: see Execution Log section below.
Pocket Education guard. If the memory file in your context (
CLAUDE.md
/
AGENTS.md
) has no
## Pocket Education
heading, skip this paragraph. If it has one, confirm with
npx -y pocketto-pi edu --json --contract 3
. When
data.education
is
true
(or the command errors), ask whether the user wants to implement with guidance or use subagents—unless the user already explicitly chose subagent execution. An explicit handover in
pocket-education
or direct instruction to dispatch this plan counts as the answer.

每个 session 执行第一个任务前都要运行此命令:
bash
npx -y pocketto-pi log init "<plan_dir>" --json --contract 3
无需安装步骤、PATH 设置或特定 shell 的保护机制——
npx
会解析跨平台 binary,而
log init
是幂等的,因此每个 session 无条件运行此命令都是安全的。将
<plan_dir>
替换为包含执行计划的目录(例如
docs/pocket/plans/2026-05-08-auth-refactor
)。
  • 尚无
    log.json
    → 根据该目录中的计划文件创建它
  • 已有
    log.json
    但缺少任务 → 将任务迁移到现有阶段中(保留状态)
  • log.json
    已完整 → 报告“no migration needed”,且不写入任何内容
从
log init
响应 envelope 中报告
data.phase_branches
和
data.branch
。对于 stacked plan,
log init
可能会自动创建并切换到 phase-1 branch;请在启动报告中说明这一点。后续阶段使用
log.json
中为其记录的 branch(参见
references/entry-gate.md
中的 stacked branch check)。
完整命令参考及更新/关闭命令:参见下方的 Execution Log 部分。
Pocket Education guard。 如果上下文中的 memory file(
CLAUDE.md
/
AGENTS.md
)没有
## Pocket Education
标题,则跳过本段。如果存在该标题,则使用
npx -y pocketto-pi edu --json --contract 3
进行确认。当
data.education
为
true
(或命令报错)时,询问用户希望采用带指导的实现方式还是使用 subagent——除非用户已经明确选择了 subagent 执行。
pocket-education
中的明确移交或直接分派本计划的指令均视为已经作出选择。

When to Use

何时使用

Use POCKET when the user asks to execute an implementation plan. A completed plan is required; if there is no plan, route to
pocket-planning
rather than inventing one here. Tasks may be sequential, independent, or a mix.
Task count does not gate eligibility.
pocket-planning
routes every plan through
pocket-structuring
, which accepts any task count, so a one-task plan reaches here as a legitimate Pocket plan. It is simply the degenerate case of
SOLO
— a group resolved to size 1 — and runs the normal Entry Gate, packet, audit, and phase-pass path. Do not bounce it to
hotfix
:
hotfix
is an entry-routing choice for small, clear work, not an escape hatch once a full spec and plan already exist.
Routing:
Have implementation plan?
    │
    ├── Exactly one task?
    │       │
    │       └── YES → Use POCKET (this skill) — the task is SOLO
    │
    ├── Plan has dependencies or parallel groups?
    │       │
    │       ├── YES → Use POCKET (this skill)
    │       │
    │       └── NO  → Execute ready tasks sequentially; split only if a task cannot be bounded
    │
    └── NO  → Use pocket-planning skill first (requires a spec from pocket-grinding)
当用户要求执行实施计划时使用 POCKET。必须已有完整计划;如果没有计划,应转入
pocket-planning
,而不是在此处自行编造。任务可以是顺序执行、彼此独立,或两者混合。
任务数量不会限制适用资格。
pocket-planning
会让每个计划都经过
pocket-structuring
,后者接受任意任务数量,因此只有一个任务的计划也可以作为合法的 Pocket 计划进入此处。它只是
SOLO
的退化情形——即解析后大小为 1 的组——并会走正常的 Entry Gate、packet、audit 和 phase-pass 路径。不要将其转交给
hotfix
:
hotfix
是针对小型明确工作的入口路由选择,而不是已有完整 spec 和计划之后的逃生通道。
路由:
Have implementation plan?
    │
    ├── Exactly one task?
    │       │
    │       └── YES → Use POCKET (this skill) — the task is SOLO
    │
    ├── Plan has dependencies or parallel groups?
    │       │
    │       ├── YES → Use POCKET (this skill)
    │       │
    │       └── NO  → Execute ready tasks sequentially; split only if a task cannot be bounded
    │
    └── NO  → Use pocket-planning skill first (requires a spec from pocket-grinding)

Input Types

输入类型

pocket-development receives two distinct input formats. Identify which type before proceeding.
Type A — Index manifest / Flat plan (
execution-plan/index.md
or a flat source plan when the user explicitly chose to skip structuring)
  • Produced by pocket-planning / pocket-structuring (single-phase), or by an explicit user choice to use the flat source plan
  • Canonical path: read
    execution-plan/index.md
    once for summary, then open
    execution-plan/tasks/T*-*.md
    when starting each task
  • Override/legacy path: read the flat source plan in full (context-cost accepted) — no per-task files
  • Proceed normally through Entry Gate
Type B — Phase file (
execution-plan/phase-N.md
or legacy
execution-plan-phase-N.md
)
  • Produced by pocket-structuring for plans with multiple phases
  • Header contains:
    Phase N of M
    ,
    Prerequisite
    ,
    Contains tasks
    ,
    Unlocks next
    ,
    ## Phase Completion Gate
  • Reads
    execution-plan/phase-N.md
    for phase bounds, then opens
    execution-plan/tasks/T*-*.md
    on demand for each task
  • Before any task execution:
    1. Extract phase metadata from header: Phase N of M, prerequisite status, task list
    2. Confirm
      **Prerequisite:** Phase N-1 must be COMPLETE
      is satisfied
    3. If the prerequisite is not COMPLETE, inspect its log and review artifacts. If it is at
      REVIEW
      , report that
      pocket-closing
      must be invoked directly by the user; do not start this phase until it confirms
      DONE
      . Otherwise report the exact gate or human dependency and do not start this phase.
  • Track "Phase N of M" context throughout execution — surface it in all status reports
  • Terminal step is a structured PHASE_COMPLETE, RECOVERY_CHECKPOINT, or PHASE_BLOCKED report (see Phase Completion Protocol)
pocket-development 接收两种不同的输入格式。继续之前,先确定属于哪一种。
Type A — 索引清单 / 扁平计划(
execution-plan/index.md
,或用户明确选择跳过 structuring 时使用的扁平源计划)
  • 由 pocket-planning / pocket-structuring 生成(单阶段),或由用户明确选择使用扁平源计划
  • 标准路径:读取一次
    execution-plan/index.md
    以获取摘要,然后在开始每个任务时打开
    execution-plan/tasks/T*-*.md
  • 覆盖/旧版路径:完整读取扁平源计划(接受由此产生的 context 成本)——不按任务拆分文件
  • 正常进入 Entry Gate
Type B — 阶段文件(
execution-plan/phase-N.md
或旧版
execution-plan-phase-N.md
)
  • 由 pocket-structuring 为包含多个阶段的计划生成
  • 头部包含:
    Phase N of M
    、
    Prerequisite
    、
    Contains tasks
    、
    Unlocks next
    、
    ## Phase Completion Gate
  • 读取
    execution-plan/phase-N.md
    以确定阶段边界,然后在执行每个任务时按需打开
    execution-plan/tasks/T*-*.md
  • 执行任何任务之前:
    1. 从头部提取阶段元数据:Phase N of M、prerequisite status、task list
    2. 确认
      **Prerequisite:** Phase N-1 must be COMPLETE
      已得到满足
    3. 如果 prerequisite 不是 COMPLETE,请检查其 log 和 review artifacts。如果它处于
      REVIEW
      状态,报告必须由用户直接调用
      pocket-closing
      ;在它确认
      DONE
      之前不要开始此阶段。否则,报告具体的 gate 或 human dependency,并且不要开始此阶段。
  • 在整个执行过程中跟踪“Phase N of M”上下文——在所有状态报告中都应体现该信息
  • 最后一步是结构化的 PHASE_COMPLETE、RECOVERY_CHECKPOINT 或 PHASE_BLOCKED 报告(参见 Phase Completion Protocol)

Main Agent Role

Main Agent 角色

For standard Pocket delegated execution, the main agent is the Delegator + Gate Runner: it coordinates implementers, runs mechanical checks, and dispatches a separate read-only auditor. The main agent does not implement tasks or judge code quality and spec compliance. The independent auditor owns those judgments; see
references/two-stage-review.md
.
Main agent MUSTMain agent MUST NOT
Initialize and update pocket logWrite, edit, or create implementation code
Construct Pocket Packets and dispatch subagentsInvoke a separate per-task review workflow — dispatch the in-loop auditor instead
Run mechanical checks, then dispatch the independent auditorJudge code quality or spec compliance itself
Read task file
execution-plan/tasks/T*-*.md
on demand per task
Read full plan / all task files upfront (avoid context blowout)
Emit PHASE_COMPLETE handoffClaim a skipped or unrun review passed
Compile phase notes from recorded task, review, and user-decision evidenceAdd an unrecorded obstacle, decision, or verification claim
If the user explicitly chooses a different implementation mode or asks to skip a Pocket gate, honor that instruction and state which Pocket checks will not run. Keep independent review when the user still expects Pocket verification.

对于标准的 Pocket 委派式执行,Main Agent 是 Delegator + Gate Runner:负责协调 implementer、运行机械化检查,并分派独立的只读 auditor。Main Agent 不负责实现任务,也不评判代码质量或 spec 符合性。这些判断由独立 auditor 负责;参见
references/two-stage-review.md
。
Main Agent 必须Main Agent 不得
初始化并更新 pocket log编写、编辑或创建实现代码
构建 Pocket Packet 并分派 subagent调用单独的任务级 review 工作流——应改为分派 in-loop auditor
运行机械化检查,然后分派独立 auditor自行评判代码质量或 spec 符合性
启动每个任务时按需读取任务文件
execution-plan/tasks/T*-*.md
预先读取完整计划/所有任务文件(避免 context 膨胀)
输出 PHASE_COMPLETE handoff声称被跳过或未运行的 review 已通过
根据已记录的任务、review 和用户决策证据汇编 phase notes添加未记录的 obstacle、decision 或 verification claim
如果用户明确选择了其他实现模式,或要求跳过某个 Pocket gate,应遵从该指令,并说明哪些 Pocket 检查不会运行。如果用户仍期望 Pocket verification,则应保留独立 review。

6 Iron Laws (MANDATORY)

6 条铁律(强制)

These defaults keep delegated work reviewable. Follow them for Pocket execution; when the user explicitly chooses another workflow or asks to skip a gate, honor that instruction and report which checks will not run.
1. PACKET BEFORE STANDARD DISPATCH
   Every task dispatched through the standard Pocket path gets a structured Pocket Packet.
   If the user explicitly chooses a simpler handoff, honor it and report that the packet gate was skipped.
   WHY: The packet is the contract. Without it, expectations are unclear
   and subagents fill gaps with guesses.

2. NO SILENT GATE SKIP
   Run the Entry Gate before standard Pocket dispatch. If the user explicitly chooses to bypass it, report the skipped check.
   WHY: Gate prevents unbounded tasks, wrong task type, and
   ambiguous prompts from reaching subagents.

3. NO TRUST WITHOUT EVIDENCE
   Always verify via read-only review.
   WHY: Subagent reports are self-assessments. Only read-only explore
   agents can verify actual code state.

4. NO AMBIGUOUS PROMPT
   Every prompt follows sandwich structure + attention rules.
   WHY: LLMs have attention drift. Sandwich structure places critical
   content at high-attention positions (start/end).

5. NO SILENT ESCALATION
   Every BLOCKED/NEEDS_CONTEXT has explicit reason + next action.
   WHY: "I'm stuck" without reason creates deadlock. Every status
   must include: what's blocked, why, and what would unblock.

6. NO SILENT REFERENCE
   Cite the Pocket reference that materially informs a packet's task scope or verification.
   WHY: Without citation, we cannot audit decision quality or train improved judgment.
   HOW: Before constructing any packet or making routing decisions, load the
   relevant references and list the ones that informed the packet in `REFERENCES LOADED`.
这些默认规则用于确保委派工作可审查。执行 Pocket 时必须遵循;如果用户明确选择其他工作流或要求跳过某项检查,应遵从该指令,并说明哪些检查不会运行。
1. PACKET BEFORE STANDARD DISPATCH
   Every task dispatched through the standard Pocket path gets a structured Pocket Packet.
   If the user explicitly chooses a simpler handoff, honor it and report that the packet gate was skipped.
   WHY: The packet is the contract. Without it, expectations are unclear
   and subagents fill gaps with guesses.

2. NO SILENT GATE SKIP
   Run the Entry Gate before standard Pocket dispatch. If the user explicitly chooses to bypass it, report the skipped check.
   WHY: Gate prevents unbounded tasks, wrong task type, and
   ambiguous prompts from reaching subagents.

3. NO TRUST WITHOUT EVIDENCE
   Always verify via read-only review.
   WHY: Subagent reports are self-assessments. Only read-only explore
   agents can verify actual code state.

4. NO AMBIGUOUS PROMPT
   Every prompt follows sandwich structure + attention rules.
   WHY: LLMs have attention drift. Sandwich structure places critical
   content at high-attention positions (start/end).

5. NO SILENT ESCALATION
   Every BLOCKED/NEEDS_CONTEXT has explicit reason + next action.
   WHY: "I'm stuck" without reason creates deadlock. Every status
   must include: what's blocked, why, and what would unblock.

6. NO SILENT REFERENCE
   Cite the Pocket reference that materially informs a packet's task scope or verification.
   WHY: Without citation, we cannot audit decision quality or train improved judgment.
   HOW: Before constructing any packet or making routing decisions, load the
   relevant references and list the ones that informed the packet in `REFERENCES LOADED`.

Entry Gate Checklist

Entry Gate Checklist

Run the normative Entry Gate Checklist verbatim from
references/entry-gate.md
.
Summary of Pre-Gate & Items: 0. PHASE FILE CHECK (Type B input only) — Phase metadata extracted and prerequisite phase confirmed COMPLETE?
  1. TASK BOUNDED? — Read task file
    execution-plan/tasks/TN-*.md
    on demand when starting TN.
  2. PACKET CONSTRUCTIBLE? — Can write precise 7-field packet (or 8-field with WORKTREE for PARALLEL GROUP)?
  3. TASK TYPE CLEAR? — Implementation vs review/audit.
  4. PROMPT SANDWICH? — Critical instruction at START, constraint at END.
  5. PARALLEL CLASSIFICATION — Classify as Foundation, Solo, or Parallel Group.
  6. VERIFICATION DEFINED? — Exact criteria for "done".
ANY "NO" → HOLD LOCAL: do not dispatch this packet yet.
HOLD LOCAL
pauses dispatch, not the whole task. Inspect the plan, repository, logs, and available documentation; repair the packet or gather missing context, then re-run the gate. Ask the user only when the next step requires a decision, access, information, or authorization that cannot be obtained from available sources. Do not implement under this delegated workflow; if the user explicitly chooses another mode, follow that instruction and make clear which Pocket checks are being bypassed.
逐字运行
references/entry-gate.md
中规范性的 Entry Gate Checklist。
Pre-Gate 与检查项摘要: 0. PHASE FILE CHECK(仅限 Type B 输入)——是否已提取阶段元数据,并确认 prerequisite phase 为 COMPLETE?
  1. TASK BOUNDED?——启动 TN 时,是否按需读取了任务文件
    execution-plan/tasks/TN-*.md
    ?
  2. PACKET CONSTRUCTIBLE?——能否编写精确的 7 字段 packet(对于 PARALLEL GROUP,则为包含 WORKTREE 的 8 字段 packet)?
  3. TASK TYPE CLEAR?——是 implementation,还是 review/audit?
  4. PROMPT SANDWICH?——关键指令是否位于 START,约束是否位于 END?
  5. PARALLEL CLASSIFICATION——是否已分类为 Foundation、Solo 或 Parallel Group?
  6. VERIFICATION DEFINED?——“done”的准确标准是否已经定义?
任一项为“NO”→ HOLD LOCAL:暂不分派此 packet。
HOLD LOCAL
会暂停分派,而不是暂停整个任务。检查计划、repository、logs 和可用文档;修复 packet 或补充缺失 context,然后重新运行 gate。只有当下一步需要作出无法从可用来源获得的决策、访问权限、信息或授权时,才询问用户。不要在委派式工作流下自行实现;如果用户明确选择了其他模式,应遵从该指令,并清楚说明绕过了哪些 Pocket 检查。

Mandatory Reference Preloading

强制参考文件预加载

Before constructing a Pocket Packet, load the references that define requirements relevant to that task and cite their paths in the packet. Do not load unrelated references or add citation ceremony.
Task/SituationMandatory References to Load
Packet construction
references/pocket-packet.md
; use
references/sandwich-prompt.md
only when useful
Entry gate fails
references/entry-gate.md
; use
references/iron-laws.md
for a specific law
Plan has
[parallel: TX]
annotations
references/entry-gate.md
; then load
references/parallel-group.md
if a group is ready
Status is BLOCKED/NEEDS_CONTEXT
references/status-handling.md
Per-task in-loop audit (after implementer DONE)
references/two-stage-review.md
Phase completion — all tasks in phase DONE
references/phase-level-pass.md
and
references/phase-completion-notes.md
构建 Pocket Packet 之前,加载定义与该任务相关要求的参考文件,并在 packet 中引用其路径。不要加载无关参考文件,也不要增加多余的引用仪式。
任务/情况必须加载的参考文件
构建 Packet
references/pocket-packet.md
;仅在有帮助时使用
references/sandwich-prompt.md
Entry gate 失败
references/entry-gate.md
;需要澄清某项具体铁律时使用
references/iron-laws.md
计划包含
[parallel: TX]
注解
references/entry-gate.md
;组准备就绪后再加载
references/parallel-group.md
状态为 BLOCKED/NEEDS_CONTEXT
references/status-handling.md
任务级 in-loop audit(implementer DONE 之后)
references/two-stage-review.md
阶段完成——阶段内所有任务均为 DONE
references/phase-level-pass.md
和
references/phase-completion-notes.md

Packet Citation

Packet 引用

Include a
REFERENCES LOADED
section for the source references that materially shaped the packet:
markdown
undefined
为实质性影响 packet 任务范围或验证方式的来源参考文件加入
REFERENCES LOADED
部分:
markdown
undefined

REFERENCES LOADED

REFERENCES LOADED

[Reference file name] — [Brief summary of what was learned] [Reference file name] — [Brief summary of what was learned]

Do not list a reference that was not read or does not inform the task.
[Reference file name] — [Brief summary of what was learned] [Reference file name] — [Brief summary of what was learned]

不要列出未读取或未对任务产生影响的参考文件。

Construct the Pocket Packet

构建 Pocket Packet

Before each dispatch, load
references/pocket-packet.md
and construct all required fields; use
references/sandwich-prompt.md
when prompt structure needs clarification. Preserve every behavioral task's RED-cycle intent and exact commands in source order. The packet reference is authoritative for field definitions and test-intent handling.
For architecture-sensitive work, inspect the relevant implementation, configuration, tests, and call paths before dispatch. This is packet and context verification; it does not make the main agent the implementation auditor. For framework, library, or external API behavior, check the installed version with Context7; if unavailable or insufficient, consult current official documentation. Put the evidence and source paths in the packet. Ask a fresh read-only
advisor
subagent to challenge material architectural assumptions; resolve disagreements with code or documentation evidence before dispatch. The task auditor independently checks the implemented result.
每次分派之前,加载
references/pocket-packet.md
并构建全部必需字段;当 prompt 结构需要澄清时,使用
references/sandwich-prompt.md
。按源顺序保留每个行为型任务的 RED-cycle 意图和准确命令。Packet 参考文件是字段定义及测试意图处理方式的权威依据。
对于架构敏感型工作,分派前应检查相关实现、配置、测试和调用路径。这属于 packet 与 context 验证;它不会让 Main Agent 成为实现 auditor。对于 framework、library 或 external API 行为,使用 Context7 检查已安装版本;如果不可用或信息不足,则查阅当前官方文档。将证据和来源路径放入 packet。请求一个全新的只读
advisor
subagent 质疑重大的架构假设;分派前,使用代码或文档证据解决分歧。任务 auditor 会独立检查实现结果。

Delegation Strategy

委派策略

Task Type Selection

任务类型选择

TaskWorkflowAccess
ImplementationDelegate to implementerRead + Write
ReviewIn-loop auditor subagent (
references/two-stage-review.md
)
Read-only
任务工作流访问权限
Implementation委派给 implementerRead + Write
Reviewin-loop auditor subagent(
references/two-stage-review.md
)
Read-only

Complexity Assessment

复杂度评估

Match execution approach to task complexity:
Task ComplexityApproachExample
Mechanical (1-2 files, clear spec)Lightweight delegationMove function, rename, simple refactor
Standard (2-5 files, some judgment)Standard delegationExtract module, restructure imports
Architectural (complex, high judgment)Deep delegation with oversightDesign patterns, major refactors
根据任务复杂度选择执行方式:
任务复杂度方法示例
Mechanical(1–2 个文件,spec 明确)轻量委派移动 function、重命名、简单 refactor
Standard(2–5 个文件,需要一定判断)标准委派提取 module、重构 imports
Architectural(复杂、高度依赖判断)深度委派并监督设计模式、大型 refactor

Recovery Before Escalation

升级前的恢复

  • Reasoning errors → Gather evidence, ask a fresh
    advisor
    to challenge the approach, then revise the packet
  • Context window overflow → Split into smaller packets and continue in dependency order
  • Hallucination issues → Verify claims against the codebase or version-matched official documentation, then re-dispatch with evidence
  • 推理错误 → 收集证据,请求全新的
    advisor
    质疑方案,然后修订 packet
  • Context window 溢出 → 将其拆分为更小的 packet,并按依赖顺序继续
  • Hallucination 问题 → 根据 codebase 或与版本匹配的官方文档验证声明,然后携带证据重新分派

The Process

流程

Non-normative summary. For the authoritative in-loop audit contract, cite
references/two-stage-review.md
. For the phase-level pass contract, cite
references/phase-level-pass.md
.
dot
digraph pocket_process {
    rankdir=TB;

    "Read plan index, extract task N" -> "Run Entry Gate Checklist";
    "Run Entry Gate Checklist" -> { "HOLD LOCAL" "Classify task" };
    "Classify task" -> { "FOUNDATION / SOLO" "PARALLEL GROUP" };
    "FOUNDATION / SOLO" -> "Construct Pocket Packet";
    "PARALLEL GROUP" -> "Run Parallel Group Execution";
    "Run Parallel Group Execution" -> "Construct Pocket Packets (incl. WORKTREE)";
    "Construct Pocket Packets (incl. WORKTREE)" -> "Spawn implementers (parallel batch)";
    "Spawn implementers (parallel batch)" -> "Wait for status";
    "HOLD LOCAL" -> "Inspect sources, repair packet/context -> re-run Entry Gate";
    "Construct Pocket Packet" -> "Spawn implementer";
    "Spawn implementer" -> "Wait for status";

    "Wait for status" -> { "DONE" "NEEDS_CONTEXT" "BLOCKED" "DONE_WITH_CONCERNS" };

    "DONE" -> "In-loop audit cycle (cite references/two-stage-review.md)";
    "In-loop audit cycle (cite references/two-stage-review.md)" -> { "Audit pass" "Recover with a different strategy" };

    "NEEDS_CONTEXT" -> "Inspect repository/docs/logs -> gather context -> re-dispatch or ask for human input";
    "BLOCKED" -> "Diagnose -> materially different recovery -> re-dispatch; report only a human dependency";
    "DONE_WITH_CONCERNS" -> "Attach concerns to auditor input -> mechanical gate -> auditor classifies";

    "Audit pass" -> "More tasks?";
    "More tasks?" -> "Extract task N+1" [label="yes"];
    "More tasks?" -> "Dispatch phase-level pass" [label="no"];
    "Dispatch phase-level pass" -> "Record pass result";
    "Record pass result" -> { "Pass clean or resolved" "Findings remain" };
    "Findings remain" -> { "Different recovery strategy" "Human dependency" };
    "Different recovery strategy" -> "Dispatch implementer/advisor -> confirm pass";
    "Pass clean or resolved" -> "Evaluate applicable Phase Completion Gate";
    "Human dependency" -> "PHASE_BLOCKED report";
    "Evaluate applicable Phase Completion Gate" -> { "PHASE_COMPLETE report" "RECOVERY_CHECKPOINT report" "PHASE_BLOCKED report" };
}
非规范性摘要。 权威的 in-loop audit 合约请引用
references/two-stage-review.md
。权威的 phase-level pass 合约请引用
references/phase-level-pass.md
。
dot
digraph pocket_process {
    rankdir=TB;

    "Read plan index, extract task N" -> "Run Entry Gate Checklist";
    "Run Entry Gate Checklist" -> { "HOLD LOCAL" "Classify task" };
    "Classify task" -> { "FOUNDATION / SOLO" "PARALLEL GROUP" };
    "FOUNDATION / SOLO" -> "Construct Pocket Packet";
    "PARALLEL GROUP" -> "Run Parallel Group Execution";
    "Run Parallel Group Execution" -> "Construct Pocket Packets (incl. WORKTREE)";
    "Construct Pocket Packets (incl. WORKTREE)" -> "Spawn implementers (parallel batch)";
    "Spawn implementers (parallel batch)" -> "Wait for status";
    "HOLD LOCAL" -> "Inspect sources, repair packet/context -> re-run Entry Gate";
    "Construct Pocket Packet" -> "Spawn implementer";
    "Spawn implementer" -> "Wait for status";

    "Wait for status" -> { "DONE" "NEEDS_CONTEXT" "BLOCKED" "DONE_WITH_CONCERNS" };

    "DONE" -> "In-loop audit cycle (cite references/two-stage-review.md)";
    "In-loop audit cycle (cite references/two-stage-review.md)" -> { "Audit pass" "Recover with a different strategy" };

    "NEEDS_CONTEXT" -> "Inspect repository/docs/logs -> gather context -> re-dispatch or ask for human input";
    "BLOCKED" -> "Diagnose -> materially different recovery -> re-dispatch; report only a human dependency";
    "DONE_WITH_CONCERNS" -> "Attach concerns to auditor input -> mechanical gate -> auditor classifies";

    "Audit pass" -> "More tasks?";
    "More tasks?" -> "Extract task N+1" [label="yes"];
    "More tasks?" -> "Dispatch phase-level pass" [label="no"];
    "Dispatch phase-level pass" -> "Record pass result";
    "Record pass result" -> { "Pass clean or resolved" "Findings remain" };
    "Findings remain" -> { "Different recovery strategy" "Human dependency" };
    "Different recovery strategy" -> "Dispatch implementer/advisor -> confirm pass";
    "Pass clean or resolved" -> "Evaluate applicable Phase Completion Gate";
    "Human dependency" -> "PHASE_BLOCKED report";
    "Evaluate applicable Phase Completion Gate" -> { "PHASE_COMPLETE report" "RECOVERY_CHECKPOINT report" "PHASE_BLOCKED report" };
}

Parallel Group Execution

并行组执行

When the Entry Gate classifies ready tasks as a PARALLEL GROUP, load and follow
references/parallel-group.md
for worktree setup, parallel dispatch, audit, merge, recovery, logging, and cleanup. Do not apply its worktree procedure to FOUNDATION or SOLO tasks.
当 Entry Gate 将准备就绪的任务分类为 PARALLEL GROUP 时,加载并遵循
references/parallel-group.md
,完成 worktree 设置、并行分派、audit、merge、恢复、记录和清理。不要将其 worktree 流程应用于 FOUNDATION 或 SOLO 任务。

Prompt Construction

Prompt 构建

Build prompts from the Pocket Packet. Load
references/sandwich-prompt.md
only when the task needs prompt-structure guidance; the packet's constraints and deliverables take priority over generic prompt formulas.
根据 Pocket Packet 构建 prompt。仅当任务需要 prompt 结构指导时加载
references/sandwich-prompt.md
;packet 的约束和交付物优先于通用 prompt 公式。

Review

审查

Each completed task receives the mechanical gate and independent read-only audit in
references/two-stage-review.md
. The main agent does not replace the auditor's code-quality or spec-compliance judgment.
After all tasks pass, run the independent phase-level pass in
references/phase-level-pass.md
for both flat and phased plans. Complete the handoff in Phase Completion Protocol;
pocket-closing
owns phase advancement from
REVIEW
to
DONE
.
每个已完成的任务都要在
references/two-stage-review.md
中接受 mechanical gate 和独立只读 audit。Main Agent 不替代 auditor 对代码质量或 spec 符合性的判断。
所有任务通过后,针对扁平计划和 phased plan 运行
references/phase-level-pass.md
中的独立 phase-level pass。按照 Phase Completion Protocol 完成 handoff;
pocket-closing
负责将阶段从
REVIEW
推进到
DONE
。

Core lifecycle events and local recovery

Core 生命周期事件与本地恢复

Core uses lifecycle schema
1
for unpatched documents and
2
for stacked plans, and the neutral event vocabulary
spec-approved
,
phase-complete
, and
plan-closed
. The approved-spec handoff uses
pocketto-pi lifecycle transition <spec_dir> spec-approved --artifact <root>:<kind>:<relative-path>:<sha256> --json --contract 3
; phase and closure events are committed by the lifecycle-aware
log update
/
log close
transitions. A lifecycle event stores only artifact references in
lifecycle.json
; references identify artifacts by root, kind, relative path, and SHA-256 digest. Core emits
phase-complete
only after the phase-level pass reaches
REVIEW
, not when closing later changes the phase to
DONE
.
If a projection write needs recovery, first run
pocketto-pi lifecycle repair <spec_dir> --json --contract 3
to reconcile lifecycle-owned fields while preserving task state. Repair does not emit an event or dispatch an adapter and fails closed if task state is unrecoverable. Then run
pocketto-pi lifecycle drain <spec_dir> --json --contract 3
to replay pending events in revision order; drain does not create a new event. With no registered consumer, events remain durable locally and phase completion is not blocked.
Core 对未修补文档使用 lifecycle schema
1
,对 stacked plan 使用
2
,并使用中立的事件词汇
spec-approved
、
phase-complete
和
plan-closed
。Approved-spec handoff 使用
pocketto-pi lifecycle transition <spec_dir> spec-approved --artifact <root>:<kind>:<relative-path>:<sha256> --json --contract 3
;阶段和关闭事件由支持 lifecycle 的
log update
/
log close
transition 提交。Lifecycle event 仅在
lifecycle.json
中存储 artifact references;references 通过 root、kind、relative path 和 SHA-256 digest 标识 artifacts。只有在 phase-level pass 到达
REVIEW
之后,Core 才会发出
phase-complete
,而不是在后续关闭操作将 phase 改为
DONE
时发出。
如果 projection 写入需要恢复,先运行
pocketto-pi lifecycle repair <spec_dir> --json --contract 3
,在保留 task state 的同时协调 lifecycle 所拥有的字段。Repair 不会发出事件或分派 adapter;如果 task state 无法恢复,则 fail closed。然后运行
pocketto-pi lifecycle drain <spec_dir> --json --contract 3
,按 revision 顺序 replay pending 事件;drain 不会创建新事件。如果没有注册 consumer,事件会持久保留在本地,且阶段完成不会因此受阻。

Status Handling

状态处理

Non-normative summary. For the authoritative in-loop audit contract, cite
references/two-stage-review.md
. For the phase-level pass contract, cite
references/phase-level-pass.md
.
StatusController Action
DONERun the in-loop audit cycle per
references/two-stage-review.md
.
DONE_WITH_CONCERNSRoute per
references/status-handling.md
§ DONE_WITH_CONCERNS (attach concerns verbatim; scope/context blockers → NEEDS_CONTEXT).
NEEDS_CONTEXTFirst inspect available sources and try to gather the missing context; ask the user only if it is unavailable there, then re-dispatch.
BLOCKEDUse only when a human decision, access, information, or authorization is required; record the specific dependency and next action.
REVIEW_FAIL (task verdict artifact)Fix through the correction path in
references/phase-level-pass.md
.
done_sha
NEVER moves.
Before reporting a task or phase as
BLOCKED
, follow
references/status-handling.md
. A subagent's BLOCKED report is a recovery trigger, not a user-facing verdict. Persist BLOCKED only when the next safe action requires a human dependency; skip tasks that depend on it, continue other ready tasks when safe, and never advance a phase with unresolved work.
非规范性摘要。 权威的 in-loop audit 合约请引用
references/two-stage-review.md
。权威的 phase-level pass 合约请引用
references/phase-level-pass.md
。
状态Controller 操作
DONE按
references/two-stage-review.md
运行 in-loop audit 周期。
DONE_WITH_CONCERNS按
references/status-handling.md
§ DONE_WITH_CONCERNS 路由(逐字附加 concerns;范围/context 阻塞项 → NEEDS_CONTEXT)。
NEEDS_CONTEXT首先检查可用来源并尝试补充缺失 context;只有无法从这些来源获得时才询问用户,然后重新分派。
BLOCKED仅当需要人工决策、访问权限、信息或授权时使用;记录具体 dependency 和下一步操作。
REVIEW_FAIL(task verdict artifact)通过
references/phase-level-pass.md
中的 correction path 修复。
done_sha
永不移动。
将任务或阶段报告为 BLOCKED 之前,遵循
references/status-handling.md
。Subagent 的 BLOCKED 报告是恢复触发器,而不是面向用户的 verdict。只有当下一项安全操作需要人工介入时,才持久记录 BLOCKED;跳过依赖它的任务,在安全的情况下继续其他准备就绪的任务,并且绝不带着未解决的工作推进阶段。

Execution Log

Execution Log

The
pocketto-pi
CLI manages the log — the agent runs commands, no inline file editing. For every plan with an initialized execution log,
log close
closes it after all phases are DONE. Every call takes
--json --contract 3
; parse
data
and check
ok
.
pocketto-pi
CLI 管理执行日志——由 Agent 运行命令,不直接内联编辑文件。对于每个已初始化 execution log 的计划,所有阶段均为 DONE 后,使用
log close
关闭日志。每次调用都使用
--json --contract 3
;解析
data
并检查
ok
。

log update
— Update status

log update
——更新状态

Update a phase:
bash
npx -y pocketto-pi log update <plan_dir> <phase_file> <status> --json --contract 3
Update a task within a phase (add
--task <task_id>
):
bash
npx -y pocketto-pi log update <plan_dir> <phase_file> <status> --task T1 --json --contract 3
Task status:
WAITING
→
DONE
|
BLOCKED
Phase status:
WAITING
→
REVIEW
→
DONE
|
BLOCKED
更新 phase:
bash
npx -y pocketto-pi log update <plan_dir> <phase_file> <status> --json --contract 3
更新 phase 内的 task(添加
--task <task_id>
):
bash
npx -y pocketto-pi log update <plan_dir> <phase_file> <status> --task T1 --json --contract 3
Task status:
WAITING
→
DONE
|
BLOCKED
Phase status:
WAITING
→
REVIEW
→
DONE
|
BLOCKED

log close
— Close (after all phases complete)

log close
——关闭(所有阶段完成后)

bash
npx -y pocketto-pi log close <plan_dir> --json --contract 3
Verifies all phases DONE, sets header
status=DONE
+
date_completed
. Returns
ok: false
(exit non-zero) if any phase is not DONE.
bash
npx -y pocketto-pi log close <plan_dir> --json --contract 3
验证所有阶段均为 DONE,将头部设置为
status=DONE
+
date_completed
。如果任何阶段不是 DONE,则返回
ok: false
(退出码非零)。

When to run

何时运行

MomentCommand
Session start (no
log.json
)
log init
— see Startup section above
Session start (log.json exists, tasks missing)
log init
— auto-migrates tasks into existing phases
In-loop audit passes for a task
log update --task TN DONE --sha <audited_head>
Unresolvable BLOCKED (task)
log update --task TN
→
BLOCKED
After the phase-level pass records its result (all tasks already DONE)
log update
(phase) →
REVIEW
Unresolvable BLOCKED (phase)
log update
(phase) →
BLOCKED
All phases complete (plan has an execution log)
log close
Phase-completion ordering: dispatch the phase-level pass → record a clean or resolved result → write the phase completion note → set the phase to
REVIEW
. The
REVIEW
transition records the neutral
phase-complete
event only after the pass result and its summary note are durable.
IMPORTANT: NEVER set task status to
DONE
before the in-loop audit completes and
--sha <audited_head>
is passed. NEVER set task status to
REVIEW
— that status is for phases only.
log.json
lives in
docs/pocket/plans/{slug}/log.json
— this is pocket-closing's primary input.

时机命令
Session 启动(无
log.json
)
log init
——参见上方的 Startup 部分
Session 启动(存在
log.json
,但缺少任务)
log init
——自动将任务迁移到现有阶段
任务的 in-loop audit 通过
log update --task TN DONE --sha <audited_head>
任务存在无法解决的 BLOCKED
log update --task TN
→
BLOCKED
Phase-level pass 记录结果后(所有任务已经 DONE)
log update
(phase)→
REVIEW
阶段存在无法解决的 BLOCKED
log update
(phase)→
BLOCKED
所有阶段完成(计划具有 execution log)
log close
阶段完成顺序: 分派 phase-level pass → 记录 clean 或 resolved 结果 → 编写 phase completion note → 将 phase 设置为
REVIEW
。只有在 pass 结果及其摘要 note 已持久化后,
REVIEW
transition 才会记录中立的
phase-complete
事件。
重要: 在 in-loop audit 完成并传入
--sha <audited_head>
之前,绝不要将 task status 设置为 DONE。绝不要将 task status 设置为
REVIEW
——该状态仅用于 phase。
log.json
位于
docs/pocket/plans/{slug}/log.json
——这是 pocket-closing 的主要输入。

Phase Completion Protocol

Phase Completion Protocol

Runs for every plan phase, flat or phased, after all tasks reach DONE and their per-task in-loop audits pass. When a Type B phase file supplies
## Phase Completion Gate
, evaluate its conditions verbatim. For a flat Type A plan without that section, verify all tasks are DONE, their tests and commits meet the plan's requirements, and the phase-level pass has a clean or resolved result.
Ordering is fixed: dispatch the phase-level pass → record its result → write the phase completion note → set phase status
REVIEW
→ emit the
PHASE_COMPLETE
handoff.
The phase transition records the neutral
phase-complete
event only after the pass result and note exist.
Step 1 — Run the phase-level pass, then evaluate the Phase Completion Gate. Once every task is
DONE
, dispatch the phase-level pass and let it record its result at
<plan_dir>/reviews/phase-pass-<phase_key>.json
(contract:
references/phase-level-pass.md
). Then evaluate the gate — copy the phase file's
## Phase Completion Gate
conditions verbatim, plus the pass condition:
[ ] Every task in this phase: status DONE
[ ] All tests pass
[ ] All commits created with correct format
[ ] No task has status BLOCKED or NEEDS_CONTEXT
[ ] Phase-level pass recorded a terminal result at
    <plan_dir>/reviews/phase-pass-<phase_key>.json
    (PHASE_PASS_CLEAN or PHASE_PASS_RESOLVED — references/phase-level-pass.md)
Step 2 — Write phase notes, set
REVIEW
, then emit the structured report:
If all conditions pass — write
<plan_dir>/reviews/phase-notes-<phase_key>.json
per
references/phase-completion-notes.md
, then set the phase to
REVIEW
(
log update
(phase) →
REVIEW
). The note is a factual handoff for closing, not another verdict. Then report:
PHASE_COMPLETE: Phase N of M
Tasks: [T1, T2, T4] — all DONE
Commits: [commit message list]
Verification: [observed checks and their results]
Phase-level pass: <PHASE_PASS_CLEAN | PHASE_PASS_RESOLVED> at
  <plan_dir>/reviews/phase-pass-<phase_key>.json
Phase notes: <plan_dir>/reviews/phase-notes-<phase_key>.json
Obstacles resolved: [recorded summary, or None recorded]
Decisions: [explicit user decisions and attributed implementation choices, or None recorded]
Suggestions: [evidence-based optional follow-up, or None]
Phase status: REVIEW
Gate: PASS
Next: run `/pocketto:pocket-closing <plan_dir>/<phase_file>`.
→ If the user's instruction explicitly covers end-to-end closeout, continue into pocket-closing; otherwise stop at this handoff.
If a condition fails, use the bounded recovery contract in
references/phase-level-pass.md
. After two materially different correction rounds with findings remaining, stop and report
RECOVERY_CHECKPOINT
; keep the phase out of
REVIEW
, preserve findings, and ask whether the user authorizes another bounded window. This checkpoint is not
PHASE_BLOCKED
. Use
PHASE_BLOCKED
only when the next safe action itself requires a specific human decision, access, information, or authorization:
RECOVERY_CHECKPOINT: Phase N of M
Unresolved findings: [from the phase-pass record]
Strategies tried: [two materially different strategies and evidence]
Next proposed strategy: [one concrete, bounded action]
Phase status: [must remain outside REVIEW]
→ Await the user's authorization before starting another recovery window.
For a genuine human dependency, report:
PHASE_BLOCKED: Phase N of M
Failed gate condition: [which condition]
Blocked task: TN | Blocker category: [type]
Unblocking action: [specific required action]
→ Do NOT proceed to Phase N+1
If findings remain after two phase-level correction rounds, stop automatic recovery and use
RECOVERY_CHECKPOINT
as defined in
references/phase-level-pass.md
. Do not exceed the cap or set
PHASE_BLOCKED
solely because it was reached.
When a human dependency is real, the pass record carries
status: "PHASE_BLOCKED"
and the outstanding findings (
references/phase-level-pass.md
). Report:
PHASE_BLOCKED: Phase N of M
Failed gate condition: The next safe correction requires a human decision or authorization
Pass record: <plan_dir>/reviews/phase-pass-<phase_key>.json (status PHASE_BLOCKED)
Outstanding findings: [from the pass record]
Unblocking action: human resolves the outstanding findings
→ Do NOT proceed to Phase N+1; phase status MUST NOT become REVIEW
After closing reports the phase
DONE
, proceed to Phase N+1 only if the user's authorization covers the full plan; otherwise stop and report the next step.

对于扁平或 phased 的每个计划阶段,在所有任务达到 DONE 且各自的任务级 in-loop audit 通过后运行本协议。当 Type B phase 文件提供
## Phase Completion Gate
时,逐字评估其条件。对于没有该部分的扁平 Type A 计划,验证所有任务均为 DONE、其测试和 commits 满足计划要求,并且 phase-level pass 已取得 clean 或 resolved 结果。
顺序固定:分派 phase-level pass → 记录结果 → 编写 phase completion note → 将 phase status 设置为
REVIEW
→ 输出 PHASE_COMPLETE handoff。
Phase transition 只有在 pass 结果和 note 均已存在后才会记录中立的
phase-complete
事件。
步骤 1——运行 phase-level pass,然后评估 Phase Completion Gate。 所有任务均为
DONE
后,分派 phase-level pass,并让它将结果记录到
<plan_dir>/reviews/phase-pass-<phase_key>.json
(合约:
references/phase-level-pass.md
)。然后评估 gate——逐字复制 phase 文件中的
## Phase Completion Gate
条件,并附加以下 pass 条件:
[ ] Every task in this phase: status DONE
[ ] All tests pass
[ ] All commits created with correct format
[ ] No task has status BLOCKED or NEEDS_CONTEXT
[ ] Phase-level pass recorded a terminal result at
    <plan_dir>/reviews/phase-pass-<phase_key>.json
    (PHASE_PASS_CLEAN or PHASE_PASS_RESOLVED — references/phase-level-pass.md)
步骤 2——编写 phase notes,设置
REVIEW
,然后输出结构化报告:
如果所有条件均通过——按照
references/phase-completion-notes.md
编写
<plan_dir>/reviews/phase-notes-<phase_key>.json
,然后将 phase 设置为
REVIEW
(
log update
(phase)→
REVIEW
)。该 note 是提供给 closing 的事实性 handoff,而不是另一个 verdict。然后报告:
PHASE_COMPLETE: Phase N of M
Tasks: [T1, T2, T4] — all DONE
Commits: [commit message list]
Verification: [observed checks and their results]
Phase-level pass: <PHASE_PASS_CLEAN | PHASE_PASS_RESOLVED> at
  <plan_dir>/reviews/phase-pass-<phase_key>.json
Phase notes: <plan_dir>/reviews/phase-notes-<phase_key>.json
Obstacles resolved: [recorded summary, or None recorded]
Decisions: [explicit user decisions and attributed implementation choices, or None recorded]
Suggestions: [evidence-based optional follow-up, or None]
Phase status: REVIEW
Gate: PASS
Next: run `/pocketto:pocket-closing <plan_dir>/<phase_file>`.
→ If the user's instruction explicitly covers end-to-end closeout, continue into pocket-closing; otherwise stop at this handoff.
如果某项条件失败,使用
references/phase-level-pass.md
中有边界的恢复合约。经过两轮实质不同的 correction round 后仍有 findings,请停止并报告
RECOVERY_CHECKPOINT
;将 phase 保持在
REVIEW
之外,保留 findings,并询问用户是否授权另一个有边界的处理窗口。此 checkpoint 不是
PHASE_BLOCKED
。仅当下一项安全操作本身需要具体的人工决策、访问权限、信息或授权时,才使用
PHASE_BLOCKED
:
RECOVERY_CHECKPOINT: Phase N of M
Unresolved findings: [from the phase-pass record]
Strategies tried: [two materially different strategies and evidence]
Next proposed strategy: [one concrete, bounded action]
Phase status: [must remain outside REVIEW]
→ Await the user's authorization before starting another recovery window.
如果存在真正的人工依赖,则 pass record 会携带
status: "PHASE_BLOCKED"
和未解决的 findings(
references/phase-level-pass.md
)。报告:
PHASE_BLOCKED: Phase N of M
Failed gate condition: The next safe correction requires a human decision or authorization
Pass record: <plan_dir>/reviews/phase-pass-<phase_key>.json (status PHASE_BLOCKED)
Outstanding findings: [from the pass record]
Unblocking action: human resolves the outstanding findings
→ Do NOT proceed to Phase N+1; phase status MUST NOT become REVIEW
Closing 报告 phase 为
DONE
后,只有当用户授权覆盖完整计划时才继续进入 Phase N+1;否则停止并报告下一步。

User Instructions and Recovery

用户指令与恢复

Follow the user's explicit instruction when it authorizes a workflow choice or gate. State a material consequence briefly, then proceed. Preserve independent review when the user expects Pocket verification, and report any gate the user chose to skip; never claim a skipped gate passed.
Before escalating
NEEDS_CONTEXT
or
BLOCKED
, inspect the repository, plan, logs, and available documentation; repair the packet or dispatch a fresh subagent when that can resolve the issue. A cycle count, retry count, uncertainty that can be investigated, or subagent failure alone is not a human blocker. A recovery cap requires a user checkpoint; it does not authorize endless retries. See
references/status-handling.md
,
references/two-stage-review.md
, and
references/phase-level-pass.md
for recovery contracts.
当用户明确指令授权某种工作流选择或 gate 时,遵从该指令。简要说明重大影响,然后继续执行。如果用户期望 Pocket verification,应保留独立 review,并报告用户选择跳过的任何 gate;绝不能声称被跳过的 gate 已通过。
将
NEEDS_CONTEXT
或
BLOCKED
升级之前,检查 repository、plan、logs 和可用文档;当这些来源能够解决问题时,修复 packet 或分派一个全新的 subagent。Cycle count、retry count、可调查的不确定性或单独的 subagent failure 都不是 human blocker。恢复次数上限要求用户 checkpoint;它并不授权无限重试。恢复合约参见
references/status-handling.md
、
references/two-stage-review.md
和
references/phase-level-pass.md
。

Red Flags

危险信号

While following the standard Pocket delegated path, avoid:
  • Implement code yourself instead of delegating to a subagent
  • Read full plan upfront instead of opening individual task files
    execution-plan/tasks/T*-*.md
    on demand
  • Invoke a separate per-task review workflow — per-task review is the in-loop auditor (see
    references/two-stage-review.md
    )
  • Mark task DONE in the log without a passing in-loop audit (mechanical gate + read-only auditor)
  • Mark a task DONE without passing
    --sha <audited_head>
Delegation violations:
  • Delegate without a Pocket Packet
  • Skip the Entry Gate Checklist
  • Trust a subagent's report without verification (mechanical gate, then dispatch the read-only auditor — the main agent never judges code)
  • Give ambiguous prompts ("handle X", "fix Y")
  • Report BLOCKED without identifying the human dependency and concrete unblock action
  • Accept vague escalation ("I'm stuck" without reason)
  • Dispatch a parallel group without creating worktrees first — collision risk on
    git status
    ,
    git log
    , lockfiles, shared registries
  • Merge a parallel group before ALL tasks in the group audit-pass — partial merges create ambiguous parent SHAs for the rest
  • Merge the whole parallel group, THEN
    log update
    each task — every update captures the final merge commit, collapsing all tasks onto one
    done_sha
    and silently voiding their per-task review scope. Merge + log one task at a time. The CLI hard-errors on the duplicate (
    DUPLICATE_DONE_SHA
    ); repair with
    --sha <that task's own merge commit>
If agent asks questions:
  • Answer clearly and completely
  • Provide additional context if needed
  • Don't rush into implementation
If reviewer finds issues:
  • Implementer fixes them
  • Reviewer reviews again
  • Use at most two materially different correction rounds, then stop at
    RECOVERY_CHECKPOINT
    and wait for explicit user authorization before another bounded window
遵循标准 Pocket 委派路径时,避免:
  • 自行实现代码,而不是委派给 subagent
  • 预先读取完整计划,而不是按需打开各个任务文件
    execution-plan/tasks/T*-*.md
  • 调用单独的任务级 review 工作流——任务级 review 应使用 in-loop auditor(参见
    references/two-stage-review.md
    )
  • 未通过 in-loop audit(mechanical gate + 只读 auditor)就将 log 中的任务标记为 DONE
  • 未传入
    --sha <audited_head>
    就将任务标记为 DONE
委派违规:
  • 未使用 Pocket Packet 就进行委派
  • 跳过 Entry Gate Checklist
  • 未经验证就信任 subagent 报告(应执行 mechanical gate,然后分派只读 auditor——Main Agent 绝不评判代码)
  • 提供含糊的 prompt(“处理 X”“修复 Y”)
  • 未识别 human dependency 和具体解阻操作就报告 BLOCKED
  • 接受含糊的升级请求(只说“我卡住了”却不说明原因)
  • 未先创建 worktree 就分派 parallel group——这会在
    git status
    、
    git log
    、lockfiles 和共享 registry 上产生冲突风险
  • 在组内所有任务都通过 audit 之前就 merge parallel group——部分 merge 会为其余任务产生不明确的 parent SHA
  • Merge 整个 parallel group 后再逐一执行
    log update
    ——每次更新都会捕获最终 merge commit,将所有任务压缩到同一个
    done_sha
    上,并无声地作废各任务独立的 review scope。应逐任务执行 merge + log。CLI 会在重复时硬性报错(
    DUPLICATE_DONE_SHA
    );使用
    --sha <that task's own merge commit>
    修复
如果 Agent 提出问题:
  • 清晰、完整地回答
  • 必要时提供额外 context
  • 不要急于进入实现
如果 reviewer 发现问题:
  • 由 implementer 修复
  • 由 reviewer 再次审查
  • 最多使用两轮实质不同的 correction round,然后停止在
    RECOVERY_CHECKPOINT
    ,等待用户明确授权后再开始另一个有边界的处理窗口

Reference Triggers

参考文件加载触发条件

Load these reference files when SKILL.md says "see reference for details" or when you encounter edge cases. Per Iron Law #6, you must cite which reference was loaded in every Pocket Packet.
ReferenceWhen to LoadWhat You'll Learn
references/iron-laws.md
A specific delegation invariant needs clarificationEnforcement details and recovery examples
references/entry-gate.md
Gate checklist needs its decision matrix or classification examples; plan has
[parallel: TX]
annotations
Decision tree for gate pass/fail; Foundation/Parallel-Group/Solo classification rules
references/pocket-packet.md
Packet construction unclear, need field-by-field guideComplete field definitions with examples
references/sandwich-prompt.md
Need attention mechanic details or method selectionSandwich structure variations
references/two-stage-review.md
After implementer reports DONE; mechanical gate, auditor dispatch, fix/refactor, SHA pinningNormative in-loop audit contract. Cite it; do not restate it.
references/phase-level-pass.md
All tasks in the phase are DONE — before the phase may become
REVIEW
, or a
REVIEW_FAIL
needs its correction path
Phase-level pass contract: dispatch, result record, recovery, append-only corrections, verdict fan-out. Cite it; do not restate it.
references/phase-completion-notes.md
Phase gate passes, before setting phase status to
REVIEW
Durable factual handoff for per-phase closeout; does not replace task verdicts or the phase-level pass.
references/status-handling.md
An implementer or reviewer reports NEEDS_CONTEXT/BLOCKEDEvidence gathering, recovery choices, and human-only escalation
references/parallel-group.md
Entry Gate classifies ready tasks as PARALLEL GROUPWorktree setup, dispatch, audit, merge, recovery, and cleanup
当 SKILL.md 提示“see reference for details”,或遇到边缘情况时,加载以下参考文件。根据 Iron Law #6,必须在每个 Pocket Packet 中注明已加载哪些参考文件。
参考文件何时加载可获得的信息
references/iron-laws.md
需要澄清某项具体的委派不变量执行细节和恢复示例
references/entry-gate.md
Gate checklist 的决策矩阵或分类示例需要说明;计划包含
[parallel: TX]
注解
gate pass/fail 决策树;Foundation/Parallel-Group/Solo 分类规则
references/pocket-packet.md
Packet 构建不明确,需要逐字段指南完整的字段定义及示例
references/sandwich-prompt.md
需要 attention 机制细节或方法选择Sandwich 结构变体
references/two-stage-review.md
Implementer 报告 DONE 后;涉及 mechanical gate、auditor 分派、fix/refactor 和 SHA pinning规范性的 in-loop audit 合约。必须引用,不要重新表述。
references/phase-level-pass.md
阶段内所有任务均为 DONE——在 phase 变为
REVIEW
之前,或
REVIEW_FAIL
需要 correction path 时
Phase-level pass 合约:分派、结果记录、恢复、仅追加 corrections 和 verdict fan-out。必须引用,不要重新表述。
references/phase-completion-notes.md
Phase gate 通过后、设置 phase status 为
REVIEW
之前
用于逐阶段关闭的持久事实性 handoff;不替代 task verdicts 或 phase-level pass。
references/status-handling.md
Implementer 或 reviewer 报告 NEEDS_CONTEXT/BLOCKED证据收集、恢复选择和仅限人工介入的升级处理
references/parallel-group.md
Entry Gate 将准备就绪的任务分类为 PARALLEL GROUPWorktree 设置、分派、audit、merge、恢复和清理