pocket-development
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChinesePocket 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 once to understand execution flow and dependencies, then open individual task files () on demand when a task is ready to execute.
execution-plan/index.mdexecution-plan/tasks/T*-*.md执行已批准的 Pocket 计划时,可以一次处理一个任务,也可以按明确指定的并行组执行。Main Agent 负责协调工作、运行机械化检查,并分派独立的只读审查;代码修改由 implementer 负责。
核心原则: 每次委派都是一份契约。Packet 就是契约。没有 Packet,就没有 spawn。先读取一次 ,了解执行流程和依赖关系;然后在任务准备好执行时,再按需打开相应的任务文件()。
execution-plan/index.mdexecution-plan/tasks/T*-*.mdCore v4 lifecycle boundary
Core v4 生命周期边界
pocket-developmentghThe v4 lifecycle commands use . commits local state and an event, replays pending events in revision order without creating events, and repairs recoverable projection fields without emitting or dispatching an event. Active v3 plans with progress remain on v3; never silently convert their progress.
--json --contract 3lifecycle transitionlifecycle drainlifecycle repairlog.jsonpocket-developmentghv4 生命周期命令使用 。 提交本地状态和一个事件, 按 revision 顺序 replay pending 事件而不创建事件, 修复可恢复的 投影字段,不发出或分派事件。仍有进度的活跃 v3 计划继续使用 v3;绝不静默转换其进度。
--json --contract 3lifecycle transitionlifecycle drainlifecycle repairlog.jsonStartup: Initialize Execution Log
启动:初始化执行日志
Run this before the first task, every session:
bash
npx -y pocketto-pi log init "<plan_dir>" --json --contract 3No install step, PATH setup, or shell-specific guard — resolves the cross-platform binary and is idempotent, so this is safe to run unconditionally every session. Replace with the folder containing your execution plan (e.g. ).
npxlog init<plan_dir>docs/pocket/plans/2026-05-08-auth-refactor- No 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
log.json
Report and from the envelope. For a stacked plan, 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 (see the stacked branch check in ).
data.phase_branchesdata.branchlog initlog initlog.jsonreferences/entry-gate.mdFull command reference and update/close commands: see Execution Log section below.
Pocket Education guard. If the memory file in your context ( / ) has no heading, skip this paragraph. If it has one, confirm with . When is (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 or direct instruction to dispatch this plan counts as the answer.
CLAUDE.mdAGENTS.md## Pocket Educationnpx -y pocketto-pi edu --json --contract 3data.educationtruepocket-education每个 session 执行第一个任务前都要运行此命令:
bash
npx -y pocketto-pi log init "<plan_dir>" --json --contract 3无需安装步骤、PATH 设置或特定 shell 的保护机制—— 会解析跨平台 binary,而 是幂等的,因此每个 session 无条件运行此命令都是安全的。将 替换为包含执行计划的目录(例如 )。
npxlog init<plan_dir>docs/pocket/plans/2026-05-08-auth-refactor- 尚无 → 根据该目录中的计划文件创建它
log.json - 已有 但缺少任务 → 将任务迁移到现有阶段中(保留状态)
log.json - 已完整 → 报告“no migration needed”,且不写入任何内容
log.json
从 响应 envelope 中报告 和 。对于 stacked plan, 可能会自动创建并切换到 phase-1 branch;请在启动报告中说明这一点。后续阶段使用 中为其记录的 branch(参见 中的 stacked branch check)。
log initdata.phase_branchesdata.branchlog initlog.jsonreferences/entry-gate.md完整命令参考及更新/关闭命令:参见下方的 Execution Log 部分。
Pocket Education guard。 如果上下文中的 memory file( / )没有 标题,则跳过本段。如果存在该标题,则使用 进行确认。当 为 (或命令报错)时,询问用户希望采用带指导的实现方式还是使用 subagent——除非用户已经明确选择了 subagent 执行。 中的明确移交或直接分派本计划的指令均视为已经作出选择。
CLAUDE.mdAGENTS.md## Pocket Educationnpx -y pocketto-pi edu --json --contract 3data.educationtruepocket-educationWhen 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 rather than inventing one here. Tasks may be sequential, independent, or a mix.
pocket-planningTask count does not gate eligibility. routes every plan through
, which accepts any task count, so a one-task plan reaches here as a
legitimate Pocket plan. It is simply the degenerate case of — a group resolved to
size 1 — and runs the normal Entry Gate, packet, audit, and phase-pass path. Do not bounce
it to : is an entry-routing choice for small, clear work, not an escape
hatch once a full spec and plan already exist.
pocket-planningpocket-structuringSOLOhotfixhotfixRouting:
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 计划进入此处。它只是 的退化情形——即解析后大小为 1 的组——并会走正常的 Entry Gate、packet、audit 和 phase-pass 路径。不要将其转交给 : 是针对小型明确工作的入口路由选择,而不是已有完整 spec 和计划之后的逃生通道。
pocket-planningpocket-structuringSOLOhotfixhotfix路由:
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 ( or a flat source plan when the user explicitly chose to skip structuring)
execution-plan/index.md- Produced by pocket-planning / pocket-structuring (single-phase), or by an explicit user choice to use the flat source plan
- Canonical path: read once for summary, then open
execution-plan/index.mdwhen starting each taskexecution-plan/tasks/T*-*.md - 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 ( or legacy )
execution-plan/phase-N.mdexecution-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 for phase bounds, then opens
execution-plan/phase-N.mdon demand for each taskexecution-plan/tasks/T*-*.md - Before any task execution:
- Extract phase metadata from header: Phase N of M, prerequisite status, task list
- Confirm is satisfied
**Prerequisite:** Phase N-1 must be COMPLETE - If the prerequisite is not COMPLETE, inspect its log and review artifacts. If it is at , report that
REVIEWmust be invoked directly by the user; do not start this phase until it confirmspocket-closing. Otherwise report the exact gate or human dependency and do not start this phase.DONE
- 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 — 索引清单 / 扁平计划(,或用户明确选择跳过 structuring 时使用的扁平源计划)
execution-plan/index.md- 由 pocket-planning / pocket-structuring 生成(单阶段),或由用户明确选择使用扁平源计划
- 标准路径:读取一次 以获取摘要,然后在开始每个任务时打开
execution-plan/index.mdexecution-plan/tasks/T*-*.md - 覆盖/旧版路径:完整读取扁平源计划(接受由此产生的 context 成本)——不按任务拆分文件
- 正常进入 Entry Gate
Type B — 阶段文件( 或旧版 )
execution-plan/phase-N.mdexecution-plan-phase-N.md- 由 pocket-structuring 为包含多个阶段的计划生成
- 头部包含:、
Phase N of M、Prerequisite、Contains tasks、Unlocks next## Phase Completion Gate - 读取 以确定阶段边界,然后在执行每个任务时按需打开
execution-plan/phase-N.mdexecution-plan/tasks/T*-*.md - 执行任何任务之前:
- 从头部提取阶段元数据:Phase N of M、prerequisite status、task list
- 确认 已得到满足
**Prerequisite:** Phase N-1 must be COMPLETE - 如果 prerequisite 不是 COMPLETE,请检查其 log 和 review artifacts。如果它处于 状态,报告必须由用户直接调用
REVIEW;在它确认pocket-closing之前不要开始此阶段。否则,报告具体的 gate 或 human dependency,并且不要开始此阶段。DONE
- 在整个执行过程中跟踪“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 MUST | Main agent MUST NOT |
|---|---|
| Initialize and update pocket log | Write, edit, or create implementation code |
| Construct Pocket Packets and dispatch subagents | Invoke a separate per-task review workflow — dispatch the in-loop auditor instead |
| Run mechanical checks, then dispatch the independent auditor | Judge code quality or spec compliance itself |
Read task file | Read full plan / all task files upfront (avoid context blowout) |
| Emit PHASE_COMPLETE handoff | Claim a skipped or unrun review passed |
| Compile phase notes from recorded task, review, and user-decision evidence | Add 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 符合性 |
启动每个任务时按需读取任务文件 | 预先读取完整计划/所有任务文件(避免 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.mdSummary of Pre-Gate & Items:
0. PHASE FILE CHECK (Type B input only) — Phase metadata extracted and prerequisite phase confirmed COMPLETE?
- TASK BOUNDED? — Read task file on demand when starting TN.
execution-plan/tasks/TN-*.md - PACKET CONSTRUCTIBLE? — Can write precise 7-field packet (or 8-field with WORKTREE for PARALLEL GROUP)?
- TASK TYPE CLEAR? — Implementation vs review/audit.
- PROMPT SANDWICH? — Critical instruction at START, constraint at END.
- PARALLEL CLASSIFICATION — Classify as Foundation, Solo, or Parallel Group.
- VERIFICATION DEFINED? — Exact criteria for "done".
ANY "NO" → HOLD LOCAL: do not dispatch this packet yet.
HOLD LOCAL逐字运行 中规范性的 Entry Gate Checklist。
references/entry-gate.mdPre-Gate 与检查项摘要:
0. PHASE FILE CHECK(仅限 Type B 输入)——是否已提取阶段元数据,并确认 prerequisite phase 为 COMPLETE?
- TASK BOUNDED?——启动 TN 时,是否按需读取了任务文件 ?
execution-plan/tasks/TN-*.md - PACKET CONSTRUCTIBLE?——能否编写精确的 7 字段 packet(对于 PARALLEL GROUP,则为包含 WORKTREE 的 8 字段 packet)?
- TASK TYPE CLEAR?——是 implementation,还是 review/audit?
- PROMPT SANDWICH?——关键指令是否位于 START,约束是否位于 END?
- PARALLEL CLASSIFICATION——是否已分类为 Foundation、Solo 或 Parallel Group?
- VERIFICATION DEFINED?——“done”的准确标准是否已经定义?
任一项为“NO”→ HOLD LOCAL:暂不分派此 packet。
HOLD LOCALMandatory 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/Situation | Mandatory References to Load |
|---|---|
| Packet construction | |
| Entry gate fails | |
Plan has | |
| Status is BLOCKED/NEEDS_CONTEXT | |
| Per-task in-loop audit (after implementer DONE) | |
| Phase completion — all tasks in phase DONE | |
构建 Pocket Packet 之前,加载定义与该任务相关要求的参考文件,并在 packet 中引用其路径。不要加载无关参考文件,也不要增加多余的引用仪式。
| 任务/情况 | 必须加载的参考文件 |
|---|---|
| 构建 Packet | |
| Entry gate 失败 | |
计划包含 | |
| 状态为 BLOCKED/NEEDS_CONTEXT | |
| 任务级 in-loop audit(implementer DONE 之后) | |
| 阶段完成——阶段内所有任务均为 DONE | |
Packet Citation
Packet 引用
Include a section for the source references that materially shaped the packet:
REFERENCES LOADEDmarkdown
undefined为实质性影响 packet 任务范围或验证方式的来源参考文件加入 部分:
REFERENCES LOADEDmarkdown
undefinedREFERENCES 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 and construct all required fields; use 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.
references/pocket-packet.mdreferences/sandwich-prompt.mdFor 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 subagent to challenge material architectural assumptions; resolve disagreements with code or documentation evidence before dispatch. The task auditor independently checks the implemented result.
advisor每次分派之前,加载 并构建全部必需字段;当 prompt 结构需要澄清时,使用 。按源顺序保留每个行为型任务的 RED-cycle 意图和准确命令。Packet 参考文件是字段定义及测试意图处理方式的权威依据。
references/pocket-packet.mdreferences/sandwich-prompt.md对于架构敏感型工作,分派前应检查相关实现、配置、测试和调用路径。这属于 packet 与 context 验证;它不会让 Main Agent 成为实现 auditor。对于 framework、library 或 external API 行为,使用 Context7 检查已安装版本;如果不可用或信息不足,则查阅当前官方文档。将证据和来源路径放入 packet。请求一个全新的只读 subagent 质疑重大的架构假设;分派前,使用代码或文档证据解决分歧。任务 auditor 会独立检查实现结果。
advisorDelegation Strategy
委派策略
Task Type Selection
任务类型选择
| Task | Workflow | Access |
|---|---|---|
| Implementation | Delegate to implementer | Read + Write |
| Review | In-loop auditor subagent ( | Read-only |
| 任务 | 工作流 | 访问权限 |
|---|---|---|
| Implementation | 委派给 implementer | Read + Write |
| Review | in-loop auditor subagent( | Read-only |
Complexity Assessment
复杂度评估
Match execution approach to task complexity:
| Task Complexity | Approach | Example |
|---|---|---|
| Mechanical (1-2 files, clear spec) | Lightweight delegation | Move function, rename, simple refactor |
| Standard (2-5 files, some judgment) | Standard delegation | Extract module, restructure imports |
| Architectural (complex, high judgment) | Deep delegation with oversight | Design 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 to challenge the approach, then revise the packet
advisor - 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
- 推理错误 → 收集证据,请求全新的 质疑方案,然后修订 packet
advisor - Context window 溢出 → 将其拆分为更小的 packet,并按依赖顺序继续
- Hallucination 问题 → 根据 codebase 或与版本匹配的官方文档验证声明,然后携带证据重新分派
The Process
流程
Non-normative summary. For the authoritative in-loop audit contract, cite . For the phase-level pass contract, cite .
references/two-stage-review.mdreferences/phase-level-pass.mddot
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 合约请引用 。权威的 phase-level pass 合约请引用 。
references/two-stage-review.mdreferences/phase-level-pass.mddot
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 for worktree setup, parallel dispatch, audit, merge, recovery, logging, and cleanup. Do not apply its worktree procedure to FOUNDATION or SOLO tasks.
references/parallel-group.md当 Entry Gate 将准备就绪的任务分类为 PARALLEL GROUP 时,加载并遵循 ,完成 worktree 设置、并行分派、audit、merge、恢复、记录和清理。不要将其 worktree 流程应用于 FOUNDATION 或 SOLO 任务。
references/parallel-group.mdPrompt Construction
Prompt 构建
Build prompts from the Pocket Packet. Load only when the task needs prompt-structure guidance; the packet's constraints and deliverables take priority over generic prompt formulas.
references/sandwich-prompt.md根据 Pocket Packet 构建 prompt。仅当任务需要 prompt 结构指导时加载 ;packet 的约束和交付物优先于通用 prompt 公式。
references/sandwich-prompt.mdReview
审查
Each completed task receives the mechanical gate and independent read-only audit in . The main agent does not replace the auditor's code-quality or spec-compliance judgment.
references/two-stage-review.mdAfter all tasks pass, run the independent phase-level pass in for both flat and phased plans. Complete the handoff in Phase Completion Protocol; owns phase advancement from to .
references/phase-level-pass.mdpocket-closingREVIEWDONE每个已完成的任务都要在 中接受 mechanical gate 和独立只读 audit。Main Agent 不替代 auditor 对代码质量或 spec 符合性的判断。
references/two-stage-review.md所有任务通过后,针对扁平计划和 phased plan 运行 中的独立 phase-level pass。按照 Phase Completion Protocol 完成 handoff; 负责将阶段从 推进到 。
references/phase-level-pass.mdpocket-closingREVIEWDONECore lifecycle events and local recovery
Core 生命周期事件与本地恢复
Core uses lifecycle schema for unpatched documents and for stacked plans, and the neutral event vocabulary , , and . The approved-spec handoff uses ; phase and closure events are committed by the lifecycle-aware / transitions. A lifecycle event stores only artifact references in ; references identify artifacts by root, kind, relative path, and SHA-256 digest. Core emits only after the phase-level pass reaches , not when closing later changes the phase to .
12spec-approvedphase-completeplan-closedpocketto-pi lifecycle transition <spec_dir> spec-approved --artifact <root>:<kind>:<relative-path>:<sha256> --json --contract 3log updatelog closelifecycle.jsonphase-completeREVIEWDONEIf a projection write needs recovery, first run 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 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.
pocketto-pi lifecycle repair <spec_dir> --json --contract 3pocketto-pi lifecycle drain <spec_dir> --json --contract 3Core 对未修补文档使用 lifecycle schema ,对 stacked plan 使用 ,并使用中立的事件词汇 、 和 。Approved-spec handoff 使用 ;阶段和关闭事件由支持 lifecycle 的 / transition 提交。Lifecycle event 仅在 中存储 artifact references;references 通过 root、kind、relative path 和 SHA-256 digest 标识 artifacts。只有在 phase-level pass 到达 之后,Core 才会发出 ,而不是在后续关闭操作将 phase 改为 时发出。
12spec-approvedphase-completeplan-closedpocketto-pi lifecycle transition <spec_dir> spec-approved --artifact <root>:<kind>:<relative-path>:<sha256> --json --contract 3log updatelog closelifecycle.jsonREVIEWphase-completeDONE如果 projection 写入需要恢复,先运行 ,在保留 task state 的同时协调 lifecycle 所拥有的字段。Repair 不会发出事件或分派 adapter;如果 task state 无法恢复,则 fail closed。然后运行 ,按 revision 顺序 replay pending 事件;drain 不会创建新事件。如果没有注册 consumer,事件会持久保留在本地,且阶段完成不会因此受阻。
pocketto-pi lifecycle repair <spec_dir> --json --contract 3pocketto-pi lifecycle drain <spec_dir> --json --contract 3Status Handling
状态处理
Non-normative summary. For the authoritative in-loop audit contract, cite . For the phase-level pass contract, cite .
references/two-stage-review.mdreferences/phase-level-pass.md| Status | Controller Action |
|---|---|
| DONE | Run the in-loop audit cycle per |
| DONE_WITH_CONCERNS | Route per |
| NEEDS_CONTEXT | First inspect available sources and try to gather the missing context; ask the user only if it is unavailable there, then re-dispatch. |
| BLOCKED | Use 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 |
Before reporting a task or phase as , follow . 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.
BLOCKEDreferences/status-handling.md非规范性摘要。 权威的 in-loop audit 合约请引用 。权威的 phase-level pass 合约请引用 。
references/two-stage-review.mdreferences/phase-level-pass.md| 状态 | Controller 操作 |
|---|---|
| DONE | 按 |
| DONE_WITH_CONCERNS | 按 |
| NEEDS_CONTEXT | 首先检查可用来源并尝试补充缺失 context;只有无法从这些来源获得时才询问用户,然后重新分派。 |
| BLOCKED | 仅当需要人工决策、访问权限、信息或授权时使用;记录具体 dependency 和下一步操作。 |
| REVIEW_FAIL(task verdict artifact) | 通过 |
将任务或阶段报告为 BLOCKED 之前,遵循 。Subagent 的 BLOCKED 报告是恢复触发器,而不是面向用户的 verdict。只有当下一项安全操作需要人工介入时,才持久记录 BLOCKED;跳过依赖它的任务,在安全的情况下继续其他准备就绪的任务,并且绝不带着未解决的工作推进阶段。
references/status-handling.mdExecution Log
Execution Log
The CLI manages the log — the agent runs commands, no inline file editing. For every plan with an initialized execution log, closes it after all phases are DONE. Every call takes ; parse and check .
pocketto-pilog close--json --contract 3dataokpocketto-pilog close--json --contract 3dataoklog update
— Update status
log updatelog update
——更新状态
log updateUpdate a phase:
bash
npx -y pocketto-pi log update <plan_dir> <phase_file> <status> --json --contract 3Update 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 3Task status: → |
Phase status: → → |
WAITINGDONEBLOCKEDWAITINGREVIEWDONEBLOCKED更新 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 3Task status: → |
Phase status: → → |
WAITINGDONEBLOCKEDWAITINGREVIEWDONEBLOCKEDlog close
— Close (after all phases complete)
log closelog close
——关闭(所有阶段完成后)
log closebash
npx -y pocketto-pi log close <plan_dir> --json --contract 3Verifies all phases DONE, sets header + . Returns (exit non-zero) if any phase is not DONE.
status=DONEdate_completedok: falsebash
npx -y pocketto-pi log close <plan_dir> --json --contract 3验证所有阶段均为 DONE,将头部设置为 + 。如果任何阶段不是 DONE,则返回 (退出码非零)。
status=DONEdate_completedok: falseWhen to run
何时运行
| Moment | Command |
|---|---|
Session start (no | |
| Session start (log.json exists, tasks missing) | |
| In-loop audit passes for a task | |
| Unresolvable BLOCKED (task) | |
| After the phase-level pass records its result (all tasks already DONE) | |
| Unresolvable BLOCKED (phase) | |
| All phases complete (plan has an execution log) | |
Phase-completion ordering: dispatch the phase-level pass → record a clean or resolved result → write the phase completion note → set the phase to . The transition records the neutral event only after the pass result and its summary note are durable.
REVIEWREVIEWphase-completeIMPORTANT: NEVER set task status to before the in-loop audit completes and is passed. NEVER set task status to — that status is for phases only.
DONE--sha <audited_head>REVIEWlog.jsondocs/pocket/plans/{slug}/log.json| 时机 | 命令 |
|---|---|
Session 启动(无 | |
Session 启动(存在 | |
| 任务的 in-loop audit 通过 | |
| 任务存在无法解决的 BLOCKED | |
| Phase-level pass 记录结果后(所有任务已经 DONE) | |
| 阶段存在无法解决的 BLOCKED | |
| 所有阶段完成(计划具有 execution log) | |
阶段完成顺序: 分派 phase-level pass → 记录 clean 或 resolved 结果 → 编写 phase completion note → 将 phase 设置为 。只有在 pass 结果及其摘要 note 已持久化后, transition 才会记录中立的 事件。
REVIEWREVIEWphase-complete重要: 在 in-loop audit 完成并传入 之前,绝不要将 task status 设置为 DONE。绝不要将 task status 设置为 ——该状态仅用于 phase。
--sha <audited_head>REVIEWlog.jsondocs/pocket/plans/{slug}/log.jsonPhase 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 , 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.
## Phase Completion GateOrdering is fixed: dispatch the phase-level pass → record its result → write the phase completion note → set phase status → emit the handoff. The phase transition records the neutral event only after the pass result and note exist.
REVIEWPHASE_COMPLETEphase-completeStep 1 — Run the phase-level pass, then evaluate the Phase Completion Gate. Once every task is , dispatch the phase-level pass and let it record its result at (contract: ). Then evaluate the gate — copy the phase file's conditions verbatim, plus the pass condition:
DONE<plan_dir>/reviews/phase-pass-<phase_key>.jsonreferences/phase-level-pass.md## Phase Completion Gate[ ] 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 , then emit the structured report:
REVIEWIf all conditions pass — write per , then set the phase to ( (phase) → ). The note is a factual handoff for closing, not another verdict. Then report:
<plan_dir>/reviews/phase-notes-<phase_key>.jsonreferences/phase-completion-notes.mdREVIEWlog updateREVIEWPHASE_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 . After two materially different correction rounds with findings remaining, stop and report ; keep the phase out of , preserve findings, and ask whether the user authorizes another bounded window. This checkpoint is not . Use only when the next safe action itself requires a specific human decision, access, information, or authorization:
references/phase-level-pass.mdRECOVERY_CHECKPOINTREVIEWPHASE_BLOCKEDPHASE_BLOCKEDRECOVERY_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+1If findings remain after two phase-level correction rounds, stop automatic recovery and use as defined in . Do not exceed the cap or set solely because it was reached.
RECOVERY_CHECKPOINTreferences/phase-level-pass.mdPHASE_BLOCKEDWhen a human dependency is real, the pass record carries and the outstanding findings (). Report:
status: "PHASE_BLOCKED"references/phase-level-pass.mdPHASE_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 REVIEWAfter closing reports the phase , proceed to Phase N+1 only if the user's authorization covers the full plan; otherwise stop and report the next step.
DONE对于扁平或 phased 的每个计划阶段,在所有任务达到 DONE 且各自的任务级 in-loop audit 通过后运行本协议。当 Type B phase 文件提供 时,逐字评估其条件。对于没有该部分的扁平 Type A 计划,验证所有任务均为 DONE、其测试和 commits 满足计划要求,并且 phase-level pass 已取得 clean 或 resolved 结果。
## Phase Completion Gate顺序固定:分派 phase-level pass → 记录结果 → 编写 phase completion note → 将 phase status 设置为 → 输出 PHASE_COMPLETE handoff。 Phase transition 只有在 pass 结果和 note 均已存在后才会记录中立的 事件。
REVIEWphase-complete步骤 1——运行 phase-level pass,然后评估 Phase Completion Gate。 所有任务均为 后,分派 phase-level pass,并让它将结果记录到 (合约:)。然后评估 gate——逐字复制 phase 文件中的 条件,并附加以下 pass 条件:
DONE<plan_dir>/reviews/phase-pass-<phase_key>.jsonreferences/phase-level-pass.md## Phase Completion Gate[ ] 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如果所有条件均通过——按照 编写 ,然后将 phase 设置为 ((phase)→ )。该 note 是提供给 closing 的事实性 handoff,而不是另一个 verdict。然后报告:
references/phase-completion-notes.md<plan_dir>/reviews/phase-notes-<phase_key>.jsonREVIEWlog updateREVIEWPHASE_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.如果某项条件失败,使用 中有边界的恢复合约。经过两轮实质不同的 correction round 后仍有 findings,请停止并报告 ;将 phase 保持在 之外,保留 findings,并询问用户是否授权另一个有边界的处理窗口。此 checkpoint 不是 。仅当下一项安全操作本身需要具体的人工决策、访问权限、信息或授权时,才使用 :
references/phase-level-pass.mdRECOVERY_CHECKPOINTREVIEWPHASE_BLOCKEDPHASE_BLOCKEDRECOVERY_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 会携带 和未解决的 findings()。报告:
status: "PHASE_BLOCKED"references/phase-level-pass.mdPHASE_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 REVIEWClosing 报告 phase 为 后,只有当用户授权覆盖完整计划时才继续进入 Phase N+1;否则停止并报告下一步。
DONEUser 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 or , 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 , , and for recovery contracts.
NEEDS_CONTEXTBLOCKEDreferences/status-handling.mdreferences/two-stage-review.mdreferences/phase-level-pass.md当用户明确指令授权某种工作流选择或 gate 时,遵从该指令。简要说明重大影响,然后继续执行。如果用户期望 Pocket verification,应保留独立 review,并报告用户选择跳过的任何 gate;绝不能声称被跳过的 gate 已通过。
将 或 升级之前,检查 repository、plan、logs 和可用文档;当这些来源能够解决问题时,修复 packet 或分派一个全新的 subagent。Cycle count、retry count、可调查的不确定性或单独的 subagent failure 都不是 human blocker。恢复次数上限要求用户 checkpoint;它并不授权无限重试。恢复合约参见 、 和 。
NEEDS_CONTEXTBLOCKEDreferences/status-handling.mdreferences/two-stage-review.mdreferences/phase-level-pass.mdRed 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 on demand
execution-plan/tasks/T*-*.md - 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, lockfiles, shared registriesgit log - 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 each task — every update captures the final merge commit, collapsing all tasks onto one
log updateand silently voiding their per-task review scope. Merge + log one task at a time. The CLI hard-errors on the duplicate (done_sha); repair withDUPLICATE_DONE_SHA--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 and wait for explicit user authorization before another bounded window
RECOVERY_CHECKPOINT
遵循标准 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
- 未传入 就将任务标记为 DONE
--sha <audited_head>
委派违规:
- 未使用 Pocket Packet 就进行委派
- 跳过 Entry Gate Checklist
- 未经验证就信任 subagent 报告(应执行 mechanical gate,然后分派只读 auditor——Main Agent 绝不评判代码)
- 提供含糊的 prompt(“处理 X”“修复 Y”)
- 未识别 human dependency 和具体解阻操作就报告 BLOCKED
- 接受含糊的升级请求(只说“我卡住了”却不说明原因)
- 未先创建 worktree 就分派 parallel group——这会在 、
git status、lockfiles 和共享 registry 上产生冲突风险git log - 在组内所有任务都通过 audit 之前就 merge parallel group——部分 merge 会为其余任务产生不明确的 parent SHA
- Merge 整个 parallel group 后再逐一执行 ——每次更新都会捕获最终 merge commit,将所有任务压缩到同一个
log update上,并无声地作废各任务独立的 review scope。应逐任务执行 merge + log。CLI 会在重复时硬性报错(done_sha);使用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.
| Reference | When to Load | What You'll Learn |
|---|---|---|
| A specific delegation invariant needs clarification | Enforcement details and recovery examples |
| Gate checklist needs its decision matrix or classification examples; plan has | Decision tree for gate pass/fail; Foundation/Parallel-Group/Solo classification rules |
| Packet construction unclear, need field-by-field guide | Complete field definitions with examples |
| Need attention mechanic details or method selection | Sandwich structure variations |
| After implementer reports DONE; mechanical gate, auditor dispatch, fix/refactor, SHA pinning | Normative in-loop audit contract. Cite it; do not restate it. |
| All tasks in the phase are DONE — before the phase may become | Phase-level pass contract: dispatch, result record, recovery, append-only corrections, verdict fan-out. Cite it; do not restate it. |
| Phase gate passes, before setting phase status to | Durable factual handoff for per-phase closeout; does not replace task verdicts or the phase-level pass. |
| An implementer or reviewer reports NEEDS_CONTEXT/BLOCKED | Evidence gathering, recovery choices, and human-only escalation |
| Entry Gate classifies ready tasks as PARALLEL GROUP | Worktree setup, dispatch, audit, merge, recovery, and cleanup |
当 SKILL.md 提示“see reference for details”,或遇到边缘情况时,加载以下参考文件。根据 Iron Law #6,必须在每个 Pocket Packet 中注明已加载哪些参考文件。
| 参考文件 | 何时加载 | 可获得的信息 |
|---|---|---|
| 需要澄清某项具体的委派不变量 | 执行细节和恢复示例 |
| Gate checklist 的决策矩阵或分类示例需要说明;计划包含 | gate pass/fail 决策树;Foundation/Parallel-Group/Solo 分类规则 |
| Packet 构建不明确,需要逐字段指南 | 完整的字段定义及示例 |
| 需要 attention 机制细节或方法选择 | Sandwich 结构变体 |
| Implementer 报告 DONE 后;涉及 mechanical gate、auditor 分派、fix/refactor 和 SHA pinning | 规范性的 in-loop audit 合约。必须引用,不要重新表述。 |
| 阶段内所有任务均为 DONE——在 phase 变为 | Phase-level pass 合约:分派、结果记录、恢复、仅追加 corrections 和 verdict fan-out。必须引用,不要重新表述。 |
| Phase gate 通过后、设置 phase status 为 | 用于逐阶段关闭的持久事实性 handoff;不替代 task verdicts 或 phase-level pass。 |
| Implementer 或 reviewer 报告 NEEDS_CONTEXT/BLOCKED | 证据收集、恢复选择和仅限人工介入的升级处理 |
| Entry Gate 将准备就绪的任务分类为 PARALLEL GROUP | Worktree 设置、分派、audit、merge、恢复和清理 |