---
name: pocket-development
description: Use when executing multi-task implementation plans. Trigger on execute plan, delegate tasks, dispatch subagents. Combines delegate handoff discipline with prompt-engineering attention mechanics.
---

# 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:**

```bash
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](#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:

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

**Example:**
```markdown
## 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](#parallel-group-execution)):

```markdown
## 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

```markdown
## 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

```dot
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)

```bash
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.

```markdown
## 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:

```bash
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:

```bash
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
warns when it detects a duplicate `done_sha` across sibling tasks in a phase.

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)

```bash
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:

```bash
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.

## 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 |

**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).

### 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**:
```bash
npx -y pocketto-pi log update <plan_dir> <phase_file> <status> --json --contract 2
```

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 2
```

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

### `log close` — Close (after all phases complete)

```bash
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](#main-agent-role-hardened) 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

**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 |