Pocket development

Pocket Development

Precise subagent delegation for task-by-task development execution. POCKET ensures every delegation has a complete contract (Pocket Packet) that specifies exactly what must be done, how to verify it, and when to escalate.

Core principle: Every delegation is a contract. The packet is the contract. No packet, no spawn.

Startup: Initialize Execution Log

Run this before the first task, every session:

npx -y pocketto-pi log init "<plan_dir>" --json --contract 2

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.md or execution-plan-phase-N.md file (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

Full command reference and update/close commands: see Execution Log section below.

---

When to Use

Use POCKET when ALL conditions are met:

• You have an implementation plan with 2+ independent tasks
• Tasks can be executed one-by-one (not requiring tight coupling)
• You need to delegate work to subagents

Decision flow:

Have implementation plan?
    │
    ├── Tasks mostly independent?
    │       │
    │       ├── YES → Use POCKET (this skill)
    │       │
    │       └── NO  → Manual execution or redesign plan
    │
    └── 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 — Flat plan (execution-plan.md)

• Produced by pocket-planning directly (≤6 tasks) or pocket-structuring pass-through
• No phase metadata in header
• Proceed normally through Entry Gate

Type B — Phase file (execution-plan-phase-N.md)

• Produced by pocket-structuring for plans with ≥7 tasks
• Header contains: Phase N of M, Prerequisite, Contains tasks, Unlocks next, ## Phase Completion Gate
• 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 prerequisite NOT confirmed COMPLETE → STOP. Report: PHASE_BLOCKED: Phase N of M | Prerequisite phase not confirmed complete. Verify Phase N-1 gate before proceeding.
• Track "Phase N of M" context throughout execution — surface it in all status reports
• Terminal step is a structured PHASE_COMPLETE or PHASE_BLOCKED report (see Phase Completion Protocol)

Main Agent Role (HARDENED)

Main agent = Delegator + Auditor only. This is non-negotiable.

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 pocket-review during execution (it's user-triggered post-phase)
Run quick audit after each implementer DONE	Do full two-stage review during development
Emit PHASE_COMPLETE handoff with pocket-review command	Take over a task because "it's faster to do it myself"

Full two-stage review (pocket-review) is user-triggered after ALL tasks are DONE — pocket-development does NOT invoke it. Per-task review during execution is a quick audit only (see Review section).

---

6 Iron Laws (MANDATORY)

These are non-negotiable. Violating any iron law leads to degraded delegation quality.

1. NO PACKET = NO SPAWN
   Never delegate without a structured Pocket Packet.
   WHY: The packet is the contract. Without it, expectations are unclear
   and subagents fill gaps with guesses.

2. NO SKIP THE GATE
   Entry gate checklist must pass before any spawn.
   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
   Every decision (task scope, verification approach, routing choice) must cite
   the specific reference that informed it.
   WHY: Without citation, we cannot audit decision quality or train improved judgment.
   HOW: Before constructing any packet or making routing decisions, load the
   relevant reference file(s) and cite the file in the Pocket Packet under SANDWICH CONTEXT.

Entry Gate Checklist

Before dispatching any subagent, ALL items must pass.

Phase File Pre-Gate (Type B input only — fires before items 1–6):

0. PHASE FILE CHECK
   - Input is execution-plan-phase-N.md?
   - If YES: phase metadata extracted? (N of M, prerequisite, task list, Completion Gate)
   - Prerequisite phase confirmed COMPLETE?
   FAIL → STOP. Emit PHASE_BLOCKED with prerequisite reason. Do not proceed to item 1.

1. TASK BOUNDED?
   - Scope clear? Deliverables defined? Stop conditions known?
   - NOT: "implement auth" but "Extract auth layer to auth_service.py"
   FAIL → KEEP LOCAL with reason

2. REFERENCES LOADED?
   - Relevant reference files read and cited in packet?
   - Packet includes REFERENCES LOADED section?
   FAIL → LOAD REFERENCES first, then reconstruct packet

3. PACKET CONSTRUCTIBLE?
   - Can you write a precise 7-field packet?
   - Must have: specific objective, exact verification criteria
   FAIL → KEEP LOCAL until task is clearer

4. TASK TYPE CLEAR?
   - Task = implementation → proceed with packet construction
   - Task = review/audit → route to review workflow
   UNCLEAR → Clarify task type before proceeding

5. PROMPT SANDWICH?
   - Critical instruction at START?
   - Key constraint at END?
   - Middle section free of filler/padding?
   FAIL → Restructure before spawn

6. VERIFICATION DEFINED?
   - Know exact criteria for "done"?
   - Can write 3-5 verification checklist items?
   FAIL → Define before spawn

ANY "NO" → KEEP LOCAL with reason written in task notes

Mandatory Reference Preloading

Before constructing any Pocket Packet, you MUST load the relevant reference file(s) and cite them in your packet. This enforces Iron Law #6: NO SILENT REFERENCE.

Task/Situation	Mandatory References to Load
Packet construction	references/pocket-packet.md, references/sandwich-prompt.md
Task decomposition unclear	references/task-decomposition.md
Entry gate fails	references/entry-gate.md, references/iron-laws.md
Plan has [parallel: TX] annotations	references/entry-gate.md (classification rules)
Status is BLOCKED/NEEDS_CONTEXT	references/status-handling.md

Citation Requirement

In every Pocket Packet, you MUST include a REFERENCES LOADED section:

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

Example:

## REFERENCES LOADED
references/task-decomposition.md — Guidelines for splitting complex tasks into bounded subtasks.

[CRITICAL] Without this citation, the Pocket Packet is incomplete and cannot proceed to spawn.

Pocket Packet Structure

Every subagent spawn requires this 7-field structure (plus an 8th WORKTREE field for tasks classified as PARALLEL GROUP at the Entry Gate — see Parallel Group Execution):

## OBJECTIVE
[Single bounded task - what MUST be done, not approach]

## REFERENCES LOADED
[Reference file name] — [Brief summary of what was learned]
[Reference file name] — [Brief summary of what was learned]
[CRITICAL: Without this section, packet is incomplete]

## WHY THIS APPROACH
[Justification for task scope and approach selection]
[Complexity assessment and any constraints that inform execution strategy]

## SANDWICH CONTEXT
[CRITICAL CONSTRAINT]      ← FIRST LINE, highest attention
[Role + Task + Constraint]
[Scene-setting: where fits, dependencies]
[Technical context needed]
[Key constraint REPEATED]   ← near END for long outputs

## DELIVERABLE
[Exact output format - Few-Shot example if format matters]
[Verification checklist - 3-5 specific items]

## QUALITY BAR
[Must-have | Must-not-have | Red flags to catch]

## STOP CONDITIONS
[Done when X | Uncertain when Y | Escalate when Z]

Worked Example: User Service Refactoring

Task: Extract authentication layer from monolithic user_service.py

## OBJECTIVE
Extract authentication logic from user_service.py into a new auth_service.py file.
Move: login(), logout(), verify_token(), refresh_token() functions.
Update imports in user_service.py to use auth_service.

## REFERENCES LOADED
references/pocket-packet.md — 9-field packet structure, must include REFERENCES LOADED section
references/sandwich-prompt.md — Critical constraint in FIRST LINE, repeat near END for long outputs
[CRITICAL: Without REFERENCES LOADED, packet is incomplete]

## WHY THIS APPROACH
[Integration task requiring multi-file changes with judgment calls]
[Standard complexity — requires cross-file coordination]

## SANDWICH CONTEXT
[CRITICAL: Do NOT modify any business logic, only extract and relocate]
You are implementing auth layer extraction for user service refactoring.
Files: user_service.py (source), auth_service.py (create), any tests
Dependencies: Must maintain existing function signatures
[key constraint: Auth logic stays identical, only location changes]

## DELIVERABLE
1. Create auth_service.py with extracted functions
2. Update user_service.py imports
3. Run existing tests → all must pass
4. Verify: git diff shows only relocations, no logic changes

## QUALITY BAR
Must-have:
  - All 4 auth functions in auth_service.py
  - Original function signatures preserved
  - user_service.py imports from auth_service
  - Test files updated if import paths changed

Must-not-have:
  - Any auth logic modifications
  - New dependencies added
  - Tests bypassed or modified

Red flags:
  - "While extracting, I improved the code" → REVERT
  - Missing function signatures → FIX

## STOP CONDITIONS
Done when: auth_service.py exists, tests pass, no logic changes
Uncertain when: Test failures after extraction
Escalate when: Auth logic intertwined with user data access

Delegation Strategy

Task Type Selection

Task	Workflow	Access
Implementation	Delegate to implementer	Read + Write
Review	pocket-review skill	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

When to Escalate

• Reasoning errors → Add constraints or split into smaller packets
• Context window overflow → Split into smaller packets
• Hallucination issues → Add specific constraints

The Process

digraph pocket_process {
    rankdir=TB;

    "Read plan, extract task N" -> "Run Entry Gate Checklist";
    "Run Entry Gate Checklist" -> { "KEEP 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";
    "KEEP LOCAL" -> "Handle locally, skip subagent";
    "Construct Pocket Packet" -> "Spawn implementer";
    "Spawn implementer" -> "Wait for status";

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

    "DONE" -> "Quick audit (git log + tests + DELIVERABLE check)";
    "Quick audit (git log + tests + DELIVERABLE check)" -> { "Audit pass" "Audit fail" };
    "Audit pass" -> "Mark task DONE in log";
    "Audit fail" -> "Re-dispatch implementer with failure reason";
    "Re-dispatch implementer with failure reason" -> "Wait for status";

    "NEEDS_CONTEXT" -> "Provide context -> Re-dispatch (no work)";
    "BLOCKED" -> "Categorize blocker -> Fix -> Re-dispatch";
    "DONE_WITH_CONCERNS" -> "Assess concerns -> Correctness risk? -> Address first or proceed to quick audit";

    "Mark task DONE in log" -> "More tasks?";
    "More tasks?" -> "Extract task N+1" [label="yes"];
    "More tasks?" -> "Emit PHASE_COMPLETE handoff" [label="no"];
    "Emit PHASE_COMPLETE handoff" -> "Phase file?";
    "Phase file?" -> "Evaluate Phase Completion Gate" [label="yes (Type B)"];
    "Phase file?" -> "Done" [label="no (Type A)"];
    "Evaluate Phase Completion Gate" -> { "PHASE_COMPLETE report" "PHASE_BLOCKED report" };
}

Parallel Group Execution

Activates when Entry Gate item 5 classifies tasks as PARALLEL GROUP. Subagents are spawned as twins/forks inheriting CWD; without isolation they collide on git status, git log, lockfiles, and shared registries. Worktree-per-task gives each subagent a clean checkout.

Classification happens in references/entry-gate.md. This section covers the execution mechanics once classification = PARALLEL GROUP.

Worktree Setup (main agent, before dispatch)

parent_sha=$(git rev-parse HEAD)        # latest merged task or baseline

# One-time per repo (idempotent):
grep -qxF '.worktree/' .gitignore || echo '.worktree/' >> .gitignore

# Per task in the group:
for task in group:
    git worktree add .worktree/<task_id> -b task/<task_id> $parent_sha

Path: <cwd>/.worktree/<task_id> — conventional location, auto-added to .gitignore of main branch on first parallel run.

Pocket Packet — WORKTREE Field (parallel tasks only)

Sequential tasks: omit. Parallel tasks: required.

## WORKTREE
Path:       <abs_path>/.worktree/<task_id>
Branch:     task/<task_id>
Parent SHA: <parent_sha>
[CRITICAL: ALL operations must run from this worktree.
 First action: `cd <abs_path>/.worktree/<task_id>`. Do NOT touch parent repo.]

SANDWICH CONTEXT enforces CWD twice (Iron Law #4):

FIRST LINE: [CRITICAL: cd <abs_worktree_path> BEFORE any file or git
             operation. Wrong CWD = audit fail.]

NEAR END:   [REPEAT: Final commit must land on branch task/<task_id>.
             Verify before reporting DONE:
               git -C <abs_worktree_path> branch --show-current]

Parallel Dispatch

Dispatch ALL tasks in the group in ONE batch — single message containing N parallel Agent calls. Same pattern pocket-review uses for its review subagents.

Never dispatch sequentially within a group. Concurrency is the entire point.

Per-Worktree Quick Audit (main agent)

When a subagent reports DONE, audit runs against ITS worktree:

WT=.worktree/<task_id>

# 1. CWD discipline — catches "subagent ignored cd"
[[ $(git -C $WT branch --show-current) == "task/<task_id>" ]] || AUDIT FAIL

# 2. At least one commit ahead of parent
[[ $(git -C $WT rev-list $parent_sha..HEAD --count) -gt 0 ]] || AUDIT FAIL

# 3. Tests (if plan specifies a test command) — inside worktree
git -C $WT <test_command>

# 4. DELIVERABLE checklist verified against worktree state

Audit fail → re-dispatch implementer with same WORKTREE field. Worktree RETAINED until audit passes.

Group Merge (main agent, after ALL group tasks audit-pass)

Main agent performs merges sequentially in plan order from the main repo:

for task in group_in_plan_order:                    # T5 → T6 → T7
    git merge --no-ff task/<task_id> \
              -m "Merge <task_id> (parallel group)"

    # On conflict:
    #   git merge --abort
    #   → BLOCKED: category=parallel-conflict
    #       Reason:   <task_id> conflicts with already-merged <prev_task>
    #       Files:    <conflicting files>
    #       Unblock:  User decides resolution strategy
    #       Halt — worktrees retained for diagnosis (do NOT log update)

    # Merge succeeded → log THIS task NOW, before the next merge. HEAD is
    # this task's merge commit, so done_sha = that commit.
    npx -y pocketto-pi log update <plan_dir> <phase_file> DONE --task <task_id> --json --contract 2

[CRITICAL] One task per loop iteration: git merge then log update, then the next task. NEVER merge the whole group first and log afterwards — every log update would capture the final merge commit, collapsing all tasks onto a single done_sha. That silently empties pocket-review's per-task diff range (<prev_sha>..<done_sha>) for the 2nd+ task, so it goes unreviewed. The CLI refuses a duplicate done_sha across sibling tasks in a phase (DUPLICATE_DONE_SHA, exit 1, nothing written). Recover by re-running with --sha <that task's own merge commit> (find it via git log --merges --oneline); only for a task that legitimately produced no new commit, pass --allow-duplicate-sha to record the duplicate anyway (pocket-review emits a skip stub for it).

Merge commit SHA becomes that task's done_sha in log.json — schema stays linear, pocket-review preflight unchanged.

Cleanup (main agent, after group fully merged + logged)

for task in group:
    git worktree remove .worktree/<task_id>
    git branch -d task/<task_id>

If ANY task in the group is BLOCKED → NO cleanup of any worktree in that group. Diagnosability over tidiness.

Risk Mitigations Built Into Flow

Risk	Mitigation
Subagent ignores cd instruction	Audit Step 1 verifies branch --show-current = task/<task_id>. Wrong branch = AUDIT FAIL — no human-trust gap
Lockfile / build artifact race	Each worktree builds independently. Shared caches (pnpm store, cargo target) are project-specific — handle in plan, not skill
.worktree/ polluting repo	Auto-added to .gitignore on first parallel run, auto-removed after merge
Conflict mid-merge	Sequential merge in plan order + --abort + structured BLOCKED with file list
log.json schema drift	done_sha = merge_sha keeps log linear; pocket-review untouched
Misclassified parallel/sequential	Caught at Entry Gate item 5 (classification), not here

Sample Flow

Plan: T5, T6, T7 — parallel group after T4

1. T4 merged. parent = git rev-parse HEAD (= T4's done_sha)

2. Entry Gate items 1-4 pass for each task individually.
   Item 5 classifies all three as PARALLEL GROUP.

3. Worktree setup:
   git worktree add .worktree/T5 -b task/T5 parent
   git worktree add .worktree/T6 -b task/T6 parent
   git worktree add .worktree/T7 -b task/T7 parent

4. Dispatch [T5, T6, T7] in ONE message — each packet has its WORKTREE field

5. All return DONE → audit each in its worktree → all pass

6. Main agent merges sequentially, logging each task BEFORE the next merge
   (one merge + one log update per iteration — never merge all three then log):
   git merge --no-ff task/T5  →  log update --task T5 DONE   # done_sha[T5] = T5 merge commit
   git merge --no-ff task/T6  →  log update --task T6 DONE   # done_sha[T6] = T6 merge commit
   git merge --no-ff task/T7  →  log update --task T7 DONE   # done_sha[T7] = T7 merge commit
   → each done_sha is a distinct merge commit; log stays linear

7. Cleanup: remove worktrees, delete branches

8. Continue to T9 (deps now satisfied)

Sandwich Prompt Rules

Every subagent prompt must follow these attention mechanics:

RULE 1: Critical instruction in FIRST LINE (U-shaped attention peak)
        → LLM attention is highest at start
        → Example: [CRITICAL: Auth logic must not change]

RULE 2: Key constraint REPEATED near END (counters attention drift)
        → For outputs >500 tokens, restate constraint before output
        → Example: [REPEAT: No auth logic modifications]

RULE 3: Middle section FREE of filler/padding
        → No "Certainly!", "Of course!", "Here's what I'll do:"
        → Direct instructions only

RULE 4: For long outputs, restate constraint before output section
        → Prevents mid-output attention drift

TEMPLATE:
[CRITICAL: worst-case if violated]
You are implementing [task]

[Context - scene setting, dependencies, technical]

[RESTATE KEY CONSTRAINT]  ← for long outputs

Your job:
1. [step]
2. [step]

Report: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED

Method Selection

Match prompting complexity to task complexity:

Task Type	Method	Tokens
Simple, well-specified	Zero-Shot	50-200
Format consistency needed	Few-Shot (2-3 examples)	200-800
Multi-step reasoning	Chain of Thought	100-500
Complex planning	Tree of Thoughts	500-2000+
High-stakes verification	Self-Consistency	500-3000+
Tool use required	ReAct	300-1000

Review

Two distinct review phases. Do NOT conflate them.

Per-Task Quick Audit (during execution)

When implementer reports DONE, main agent runs a quick audit inline — no subagent, no pocket-review:

1. Run git log --oneline -5 — confirm a commit exists for this task
2. Run tests if the plan specifies a test command — confirm green
3. Check the packet's DELIVERABLE checklist — all items must be met

Audit pass → mark task DONE in log, proceed to next task.

Audit fail → re-dispatch implementer with specific failure reason:

AUDIT FAILED: [what failed — missing commit / failing tests / DELIVERABLE item N not met]
Fix this specific issue. Do not scope-creep.

Do NOT mark task DONE until audit passes.

DONE_WITH_CONCERNS: Assess concerns first. If correctness risk → address before running quick audit. If observation only → proceed with quick audit normally (concerns go into the final pocket-review phase).

End-of-Execution Handoff (after all tasks done)

After ALL tasks are marked DONE in the log, emit a PHASE_COMPLETE handoff message. Do NOT invoke pocket-review directly.

PHASE_COMPLETE: All tasks marked DONE.

Full spec compliance + code quality review is a separate user-triggered step.

Run: /pocketto:pocket-review <plan_dir>/<phase_file>

pocket-review dispatches parallel reviewer subagents (one per task) and writes results to:
<plan_dir>/reviews/

Pocket Enterprise — create-pr offer (Story 2, user-triggered). Immediately after the handoff above, run:

npx -y pocketto-pi mode --json --contract 2

• If ok is false or data.enterprise is not strictly true → do nothing. No GitHub mention, no prompt. Non-enterprise handoff stays byte-identical to today (fail-closed).
• If ok is true and data.enterprise is true → append one line only:

Run: /pocketto:create-pr <plan_dir> [<phase_file>]

Do NOT invoke create-pr — same pattern as pocket-review: offer the command, user runs it when ready.

Pocket Enterprise — task checklist sync (same guard). Still inside the enterprise=true branch above, after the create-pr offer, sync the live task checklist to the linked GitHub issue:

1. Resolve spec_dir = docs/pocket/spec/<slug>/ where <slug> matches the plan directory basename, then read the linked issue:

   npx -y pocketto-pi meta get <spec_dir> github_issue.number --json --contract 2
   

   If data.value is null or missing, or the envelope is ok:false (e.g. error.code == "NOT_FOUND" — spec_dir doesn't exist) → emit one warning line "Task checklist sync skipped: no linked issue in .pocket-meta.json." and stop this step (no GitHub call).

2. Check gh auth status — not authenticated → emit one warning line and stop this step (the handoff itself already succeeded; never fail the phase over checklist sync).

3. Render the checklist body from log.json:

   npx -y pocketto-pi format tasklist <plan_dir> --json --contract 2
   

   Parse data.bodyFile and data.marker (<!-- pocket-tasklist -->).

4. Upsert exactly one marker-tagged comment on the issue (same pattern as pocket-review's summary upsert). Resolve <owner>/<repo> via gh repo view --json owner,name, then:

   gh api repos/<owner>/<repo>/issues/<issue_number>/comments --paginate
   

   Filter comments whose body starts with the marker (first line), sorted by id ascending:

   Matches	Action
   0	Create: gh api repos/<owner>/<repo>/issues/<issue_number>/comments -f body="$(cat <bodyFile>)"
   1	Update in place: gh api repos/<owner>/<repo>/issues/comments/<comment_id> --method PATCH -f body="$(cat <bodyFile>)"
   >1 (race)	Update the earliest; delete the later duplicates

   The GitHub issue now shows live per-phase task status — the team's progress view without any dashboard.

Status Handling

Status	Controller Action
DONE	Quick audit (git log + tests + DELIVERABLE check) → mark task DONE if pass; re-dispatch with failure reason if fail
DONE_WITH_CONCERNS	Assess concerns → correctness risk: address first; observation only: proceed to quick audit
NEEDS_CONTEXT	Provide context → Re-dispatch (NO work until answered)
BLOCKED	Categorize blocker type → Fix → Re-dispatch
REVIEW_FAIL (from pocket-review)	The phase already terminated at PHASE_COMPLETE — you are NOT mid-phase. Re-enter via /pocketto:pocket-correction <plan_dir>/<phase_file>: it delegates each fix to an implementer subagent (you stay Delegator + Auditor), records an append-only correction, then hands back for user-triggered re-review. Do NOT write the fix yourself; do NOT refresh done_sha.

REVIEW_FAIL is a post-phase verdict (not a subagent return status); it is handled by the standalone pocket-correction skill, keeping pocket-development one-shot.

After ALL tasks DONE: emit PHASE_COMPLETE handoff with the /pocketto:pocket-review <plan_dir> command. Do NOT invoke pocket-review directly — it is user-triggered. If pocketto-pi mode returns enterprise=true, append the one-line /pocketto:create-pr offer (do not invoke create-pr) and sync the task checklist comment to the linked issue (format tasklist + marker upsert).

BLOCKED Categorization

Blocker Type	Action
Context problem	Provide more context
Reasoning needs	Escalate review depth
Task too large	Split into smaller packets
Plan wrong	Escalate to human
Parallel-conflict	Group merge failed — abort merge, escalate to user with conflicting file list, retain worktrees for diagnosis

Every BLOCKED status must include:

1. What's blocked (specific)
2. Why it's blocked (root cause)
3. What would unblock it (action)

Bundle escalation (Type B phase files): If BLOCKED is unresolvable within pocket-development, emit PHASE_BLOCKED (see Phase Completion Protocol) and halt. Do not silently continue or skip the blocked task.

Execution Log

The pocketto-pi CLI manages the log — the agent runs commands, no inline file editing. Applies to all plans; log close is Type B only. Every call takes --json --contract 2; parse data and check ok.

log update — Update status

Update a phase:

npx -y pocketto-pi log update <plan_dir> <phase_file> <status> --json --contract 2

Update a task within a phase (add --task <task_id>):

npx -y pocketto-pi log update <plan_dir> <phase_file> <status> --task T1 --json --contract 2

Task status: WAITING → DONE | BLOCKED Phase status: WAITING → REVIEW → DONE | BLOCKED

log close — Close (after all phases complete)

npx -y pocketto-pi log close <plan_dir> --json --contract 2

Verifies all phases DONE, sets header status=DONE + date_completed. Returns ok: false (exit non-zero) if any phase is not DONE.

When to run

Moment	Command
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
Quick audit passes for a task	log update --task TN → DONE
Unresolvable BLOCKED (task)	log update --task TN → BLOCKED
All tasks in phase DONE → emit PHASE_COMPLETE handoff	log update (phase) → REVIEW
pocket-review passes (user runs it separately)	log update (phase) → DONE
Unresolvable BLOCKED (phase)	log update (phase) → BLOCKED
All phases complete (Type B only)	log close

IMPORTANT: NEVER set task status to DONE before quick audit (git log + tests + DELIVERABLE check) completes. 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.

---

Phase Completion Protocol

Activates only for Type B input (execution-plan-phase-N.md). Runs after all tasks reach DONE/DONE_WITH_CONCERNS and both review stages pass.

Step 1 — Evaluate Phase Completion Gate (copy conditions verbatim from phase file ## 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

Step 2 — Emit structured report:

If all conditions pass:

PHASE_COMPLETE: Phase N of M
Tasks: [T1, T2, T4] — all DONE
Commits: [commit message list]
Tests: green
Gate: PASS
→ pocket-structuring may proceed to Phase N+1

If any condition fails:

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

This report is the signal pocket-structuring polls for in its Handoff Protocol ("wait for explicit DONE confirmation").

---

Pressure Countermeasures

When delegation pressure threatens to bypass structure:

Pressure	Countermeasure
TIME	Cut niceties, not structure. Packet still required.
SUNK COST	Rewrite packet anyway. Bad packets must be rewritten.
AUTHORITY	Keep the law, not the shortcut. Process protects quality.
EXHAUSTION	Refuse delegation if packet cannot stay legible. KEEP LOCAL.

Red Flags

Main agent role violations (HARDENED — see Main Agent Role section):

• Implement code yourself instead of delegating to a subagent
• Invoke pocket-review directly — it is user-triggered post-phase, not called by pocket-development
• Mark task DONE in the log without running the quick audit first

Delegation violations:

• Delegate without a Pocket Packet
• Skip the Entry Gate Checklist
• Trust a subagent's report without verification (quick audit: git log + tests + DELIVERABLE)
• Give ambiguous prompts ("handle X", "fix Y")
• Proceed with BLOCKED status without categorizing
• 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
• Repeat until approved

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
references/iron-laws.md	Iron laws enforcement details or pressure countermeasure specifics	Full text of 6 iron laws with enforcement examples
references/entry-gate.md	Gate checklist fails, need decision matrix or KEEP LOCAL examples, OR 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 guide	Complete field definitions with examples
references/sandwich-prompt.md	Need attention mechanic details or method selection	Sandwich structure variations

| references/status-handling.md | BLOCKED/NEEDS_CONTEXT unclear, need categorization details | Blocker types and actions |