@sienklogic/plan-build-run 2.18.1 → 2.19.1

package/plugins/pbr/hooks/hooks.json

@@ -1,6 +1,11 @@
 {
-  "$schema": "../scripts/hooks-schema.json",
+  "$schema": "./hooks-schema.json",
   "description": "Plan-Build-Run workflow hooks for state tracking, validation, and auto-continuation",
+  "$bootstrap": {
+    "why": "Claude Code expands ${CLAUDE_PLUGIN_ROOT} before shell execution. On Windows+Git Bash this produces an MSYS path like /d/Repos/... which Node.js cannot resolve. The one-liner converts /d/Repos/... to D:\\Repos\\... before requiring run-hook.js.",
+    "pattern": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'scripts','run-hook.js'))\" {script}.js",
+    "run-hook": "scripts/run-hook.js handles MSYS path fix, argv normalization, and require() isolation"
+  },
   "hooks": {
     "SessionStart": [
       {
@@ -8,39 +13,52 @@
           {
             "type": "command",
             "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'scripts','run-hook.js'))\" progress-tracker.js",
-            "statusMessage": "Loading project state..."
+            "statusMessage": "◆ PBR: Loading project state..."
           }
         ]
       }
     ],
-    "PostToolUse": [
+    "InstructionsLoaded": [
       {
-        "matcher": "Write|Edit",
         "hooks": [
           {
             "type": "command",
-            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'scripts','run-hook.js'))\" post-write-dispatch.js",
-            "statusMessage": "Validating write output..."
+            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'scripts','run-hook.js'))\" hook-server-client.js instructions-loaded",
+            "statusMessage": "◆ PBR: Detecting instruction reload..."
           }
         ]
-      },
+      }
+    ],
+    "WorktreeCreate": [
       {
-        "matcher": "Write|Edit",
         "hooks": [
           {
             "type": "command",
-            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'scripts','run-hook.js'))\" post-write-quality.js",
-            "statusMessage": "Running quality checks..."
+            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'scripts','run-hook.js'))\" hook-server-client.js worktree-create",
+            "statusMessage": "◆ PBR: Initializing worktree planning..."
           }
         ]
-      },
+      }
+    ],
+    "WorktreeRemove": [
       {
-        "matcher": "Task",
         "hooks": [
           {
             "type": "command",
-            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'scripts','run-hook.js'))\" check-subagent-output.js",
-            "statusMessage": "Validating agent output..."
+            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'scripts','run-hook.js'))\" hook-server-client.js worktree-remove",
+            "statusMessage": "◆ PBR: Cleaning up worktree state..."
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Read|Glob|Grep",
+        "hooks": [
+          {
+            "type": "http",
+            "url": "http://localhost:19836/hook/PostToolUse/Read",
+            "statusMessage": "◆ PBR: Tracking context usage..."
           }
         ]
       },
@@ -48,19 +66,39 @@
         "matcher": "Write|Edit",
         "hooks": [
           {
-            "type": "command",
-            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'scripts','run-hook.js'))\" suggest-compact.js",
-            "statusMessage": "Checking context budget..."
+            "type": "http",
+            "url": "http://localhost:19836/hook/PostToolUse/Write",
+            "statusMessage": "◆ PBR: Checking plan/state sync..."
           }
         ]
       },
       {
-        "matcher": "Read",
+        "matcher": "Bash",
         "hooks": [
           {
-            "type": "command",
-            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'scripts','run-hook.js'))\" track-context-budget.js",
-            "statusMessage": "Tracking context budget..."
+            "type": "http",
+            "url": "http://localhost:19836/hook/PostToolUse/Bash",
+            "statusMessage": "◆ PBR: Analyzing test results..."
+          }
+        ]
+      },
+      {
+        "matcher": "Task",
+        "hooks": [
+          {
+            "type": "http",
+            "url": "http://localhost:19836/hook/PostToolUse/Task",
+            "statusMessage": "◆ PBR: Validating agent deliverables..."
+          }
+        ]
+      },
+      {
+        "matcher": "AskUserQuestion",
+        "hooks": [
+          {
+            "type": "http",
+            "url": "http://localhost:19836/hook/PostToolUse/AskUserQuestion",
+            "statusMessage": "◆ PBR: Tracking user gate..."
           }
         ]
       }
@@ -69,21 +107,31 @@
       {
         "hooks": [
           {
-            "type": "command",
-            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'scripts','run-hook.js'))\" log-tool-failure.js",
-            "statusMessage": "Logging tool failure..."
+            "type": "http",
+            "url": "http://localhost:19836/hook/PostToolUseFailure/failure",
+            "statusMessage": "⚠ PBR: Recording tool failure..."
           }
         ]
       }
     ],
     "PreToolUse": [
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "type": "http",
+            "url": "http://localhost:19836/hook/PreToolUse/Read",
+            "statusMessage": "◆ PBR: Guarding skill context..."
+          }
+        ]
+      },
       {
         "matcher": "Bash",
         "hooks": [
           {
-            "type": "command",
-            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'scripts','run-hook.js'))\" pre-bash-dispatch.js",
-            "statusMessage": "Validating Bash command..."
+            "type": "http",
+            "url": "http://localhost:19836/hook/PreToolUse/Bash",
+            "statusMessage": "◆ PBR: Checking Bash safety..."
           }
         ]
       },
@@ -91,9 +139,9 @@
         "matcher": "Write|Edit",
         "hooks": [
           {
-            "type": "command",
-            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'scripts','run-hook.js'))\" pre-write-dispatch.js",
-            "statusMessage": "Checking write rules..."
+            "type": "http",
+            "url": "http://localhost:19836/hook/PreToolUse/Write",
+            "statusMessage": "◆ PBR: Enforcing write policies..."
           }
         ]
       },
@@ -101,9 +149,9 @@
         "matcher": "Task",
         "hooks": [
           {
-            "type": "command",
-            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'scripts','run-hook.js'))\" validate-task.js",
-            "statusMessage": "Validating Task() call..."
+            "type": "http",
+            "url": "http://localhost:19836/hook/PreToolUse/Task",
+            "statusMessage": "◆ PBR: Validating agent dispatch..."
           }
         ]
       },
@@ -111,9 +159,9 @@
         "matcher": "Skill",
         "hooks": [
           {
-            "type": "command",
-            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'scripts','run-hook.js'))\" validate-skill-args.js",
-            "statusMessage": "Validating skill arguments..."
+            "type": "http",
+            "url": "http://localhost:19836/hook/PreToolUse/Skill",
+            "statusMessage": "◆ PBR: Parsing skill arguments..."
           }
         ]
       },
@@ -121,9 +169,9 @@
         "matcher": "EnterPlanMode",
         "hooks": [
           {
-            "type": "command",
-            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'scripts','run-hook.js'))\" intercept-plan-mode.js",
-            "statusMessage": "Checking plan mode compatibility..."
+            "type": "http",
+            "url": "http://localhost:19836/hook/PreToolUse/EnterPlanMode",
+            "statusMessage": "◆ PBR: Checking plan mode..."
           }
         ]
       }
@@ -132,9 +180,20 @@
       {
         "hooks": [
           {
-            "type": "command",
-            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'scripts','run-hook.js'))\" context-budget-check.js",
-            "statusMessage": "Preserving state before compaction..."
+            "type": "http",
+            "url": "http://localhost:19836/hook/PreCompact/PreCompact",
+            "statusMessage": "◆ PBR: Preserving state for compaction..."
+          }
+        ]
+      }
+    ],
+    "PostCompact": [
+      {
+        "hooks": [
+          {
+            "type": "http",
+            "url": "http://localhost:19836/hook/PostCompact/PostCompact",
+            "statusMessage": "◆ PBR: Restoring context after compaction..."
           }
         ]
       }
@@ -145,7 +204,7 @@
           {
             "type": "command",
             "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'scripts','run-hook.js'))\" auto-continue.js",
-            "statusMessage": "Checking for auto-continue..."
+            "statusMessage": "◆ PBR: Checking auto-continue..."
           }
         ]
       }
@@ -154,9 +213,9 @@
       {
         "hooks": [
           {
-            "type": "command",
-            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'scripts','run-hook.js'))\" log-subagent.js start",
-            "statusMessage": "Logging agent spawn..."
+            "type": "http",
+            "url": "http://localhost:19836/hook/SubagentStart/SubagentStart",
+            "statusMessage": "◆ PBR: Agent spawning..."
           }
         ]
       }
@@ -165,29 +224,31 @@
       {
         "hooks": [
           {
-            "type": "command",
-            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'scripts','run-hook.js'))\" log-subagent.js stop",
-            "statusMessage": "Logging agent completion..."
+            "type": "http",
+            "url": "http://localhost:19836/hook/SubagentStop/SubagentStop",
+            "statusMessage": "✓ PBR: Agent completed"
           }
         ]
-      },
+      }
+    ],
+    "TaskCompleted": [
       {
         "hooks": [
           {
-            "type": "command",
-            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'scripts','run-hook.js'))\" event-handler.js",
-            "statusMessage": "Checking for auto-verification..."
+            "type": "http",
+            "url": "http://localhost:19836/hook/TaskCompleted/TaskCompleted",
+            "statusMessage": "✓ PBR: Processing task result..."
           }
         ]
       }
     ],
-    "TaskCompleted": [
+    "ConfigChange": [
       {
         "hooks": [
           {
-            "type": "command",
-            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'scripts','run-hook.js'))\" task-completed.js",
-            "statusMessage": "Processing task completion..."
+            "type": "http",
+            "url": "http://localhost:19836/hook/ConfigChange/ConfigChange",
+            "statusMessage": "◆ PBR: Validating config..."
           }
         ]
       }
@@ -196,9 +257,31 @@
       {
         "hooks": [
           {
-            "type": "command",
-            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'scripts','run-hook.js'))\" session-cleanup.js",
-            "statusMessage": "Cleaning up session..."
+            "type": "http",
+            "url": "http://localhost:19836/hook/SessionEnd/SessionEnd",
+            "statusMessage": "◆ PBR: Session cleanup..."
+          }
+        ]
+      }
+    ],
+    "Notification": [
+      {
+        "hooks": [
+          {
+            "type": "http",
+            "url": "http://localhost:19836/hook/Notification/Notification",
+            "statusMessage": "◆ PBR: Logging notification..."
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "http",
+            "url": "http://localhost:19836/hook/UserPromptSubmit/UserPromptSubmit",
+            "statusMessage": "◆ PBR: Routing prompt..."
           }
         ]
       }

package/plugins/pbr/references/agent-contracts.md

@@ -66,7 +66,7 @@ conflicts: N              # integer count of contradictions found
 
 ## Contract: Planner -> Executor
 
-**File**: `.planning/phases/{NN}-{slug}/PLAN-{NN}.md`
+**File**: `.planning/phases/{NN}-{slug}/{NN}-{MM}-PLAN.md`
 **Direction**: Planner writes, Executor reads and executes sequentially
 
 ### Required Frontmatter
@@ -84,17 +84,19 @@ must_haves:
   key_links: ["{connection description}"]
 provides: ["{exported item}"]
 consumes: ["{required item}"]
-requirement_ids: []
+implements: []          # REQ-IDs this plan satisfies (replaces deprecated requirement_ids)
 ---
 ```
 
-### Required Body: XML Tasks (each task needs all 5 elements)
+### Required Body: XML Tasks (each task needs all 7 elements)
 
 ```xml
 <task id="{plan}-T{n}" type="{type}" tdd="{bool}" complexity="{simple|medium|complex}">
 <name>{imperative verb phrase}</name>
+<read_first>{files executor must read before editing — specific paths, no globs}</read_first>
 <files>{file paths, one per line}</files>
 <action>{numbered steps}</action>
+<acceptance_criteria>{grep-verifiable conditions — shell commands returning 0/non-0}</acceptance_criteria>
 <verify>{executable shell command}</verify>
 <done>{observable outcome}</done>
 </task>
@@ -111,13 +113,13 @@ requirement_ids: []
 
 ## Contract: Planner -> Plan-Checker
 
-**File**: Same `PLAN-{NN}.md` files (read-only)
+**File**: Same `{NN}-{MM}-PLAN.md` files (read-only)
 **Direction**: Planner writes, Plan-Checker reads and returns text assessment
 **Returns**: Inline text report (no file output)
 
 ### Expected Input
 
-Plan-Checker reads plan frontmatter + XML tasks and evaluates across 9 dimensions (D1-D9). Optionally receives CONTEXT.md path.
+Plan-Checker reads plan frontmatter + XML tasks and evaluates across 10 dimensions (D1-D10). Optionally receives CONTEXT.md path.
 
 ### Output Format
 
@@ -178,11 +180,13 @@ must_haves:
 ```yaml
 ---
 status: passed|gaps_found|human_needed
-attempt: N
-must_haves_total: N
+phase: "{phase-slug}"
+checked_at: "{ISO-8601 timestamp}"
+must_haves_checked: N
 must_haves_passed: M
-gaps: ["gap description"]
-overrides: []
+must_haves_failed: K
+gaps: ["gap description"]       # optional
+overrides: []                   # optional
 ---
 ```
 
@@ -295,3 +299,30 @@ No YAML frontmatter required — these are reference documents with markdown tab
 - Codebase-Mapper does NOT commit — the orchestrator handles commits
 - Researcher treats these as S0 (highest confidence) local prior research
 - One focus area per invocation
+
+---
+
+## Completion Markers
+
+Every agent MUST end its output with exactly one completion marker. Orchestrating skills pattern-match on these markers to route results. Omitting a marker causes silent routing failures.
+
+| Agent | Markers |
+|-------|---------|
+| executor | `## PLAN COMPLETE` / `## PLAN FAILED` / `## CHECKPOINT: {TYPE}` |
+| planner | `## PLANNING COMPLETE` / `## PLANNING FAILED` / `## PLANNING INCONCLUSIVE` |
+| verifier | `## VERIFICATION COMPLETE` (status in VERIFICATION.md frontmatter) |
+| researcher | `## RESEARCH COMPLETE` / `## RESEARCH BLOCKED` |
+| synthesizer | `## SYNTHESIS COMPLETE` / `## SYNTHESIS BLOCKED` |
+| plan-checker | `## CHECK PASSED` / `## ISSUES FOUND` |
+| debugger | `## DEBUG COMPLETE` / `## ROOT CAUSE FOUND` / `## DEBUG SESSION PAUSED` |
+| codebase-mapper | `## MAPPING COMPLETE` |
+| integration-checker | `## INTEGRATION CHECK COMPLETE` |
+| general | `## TASK COMPLETE` / `## TASK FAILED` |
+| audit | `## AUDIT COMPLETE` |
+
+### Rules
+
+- Exactly ONE marker per agent invocation — never zero, never multiple
+- Marker must be the LAST heading in output (content may follow on same line)
+- Skills check for markers with regex: `/^## (PLAN COMPLETE|PLAN FAILED|CHECKPOINT)/m`
+- If an agent cannot determine outcome, use the FAILED/BLOCKED variant with explanation

package/plugins/pbr/references/agent-teams.md

@@ -5,12 +5,12 @@ Agent Teams enable parallel specialist perspectives for critical phases. Teams a
 ## Activation
 
 - **Global**: Set `parallelization.use_teams: true` in `.planning/config.json`
-- **Per-invocation**: Use `--teams` flag on `/pbr:plan`, `/pbr:review`, or `/pbr:build --team`
+- **Per-invocation**: Use `--teams` flag on `/pbr:plan-phase`, `/pbr:verify-work`, or `/pbr:execute-phase --team`
 - Per-invocation flag takes precedence over global config
 
 ## Planning Teams
 
-When `/pbr:plan <N> --teams` is invoked, three specialist agents run in parallel:
+When `/pbr:plan-phase <N> --teams` is invoked, three specialist agents run in parallel:
 
 | Role | Agent | Focus | Output File |
 |------|-------|-------|-------------|
@@ -24,7 +24,7 @@ After all three complete, the synthesizer agent reads all team outputs and produ
 
 ## Review Teams
 
-When `/pbr:review <N>` runs with teams enabled, three review agents run in parallel:
+When `/pbr:verify-work <N>` runs with teams enabled, three review agents run in parallel:
 
 | Role | Agent | Focus | Output File |
 |------|-------|-------|-------------|

package/plugins/pbr/references/archive/checkpoints.md

@@ -0,0 +1,189 @@
+# Checkpoints Reference
+
+How Plan-Build-Run uses checkpoint tasks to pause execution and involve the human.
+
+---
+
+## What Are Checkpoints?
+
+Checkpoints are special task types that cause the executor agent to **stop execution** and return control to the orchestrator (or the human). They exist because some tasks require human judgment, manual action, or verification that cannot be automated.
+
+Checkpoints are defined in plan task XML via the `type` attribute. When the executor encounters a checkpoint task, it follows a specific protocol depending on the checkpoint type.
+
+---
+
+## Checkpoint Types
+
+Plan-Build-Run supports three checkpoint types:
+
+### checkpoint:human-verify
+
+**Purpose**: The executor has completed work, but a human needs to visually inspect or manually test the result before proceeding.
+
+**Executor behavior**:
+1. Execute the task's `<action>` steps normally
+2. Commit the changes
+3. **STOP execution**
+4. Return a structured `CHECKPOINT: HUMAN-VERIFY` response containing:
+   - What was done (summary of action taken)
+   - What to verify (from the task's `<done>` condition)
+   - How to verify (instructions derived from `<verify>`)
+   - Completed tasks table
+   - Remaining tasks list
+
+**Use when**: The result requires subjective judgment (UI looks correct, behavior feels right, output makes sense) that automated verification cannot cover.
+
+**Example scenario**: A template was created and needs visual review in the browser, or an API integration needs manual testing with real credentials.
+
+### checkpoint:decision
+
+**Purpose**: The plan reaches a point where a human decision is needed before the executor can continue. The task is NOT executed — execution pauses before the task starts.
+
+**Executor behavior**:
+1. **STOP before executing the task**
+2. Return a structured `CHECKPOINT: DECISION` response containing:
+   - The decision that needs to be made (from `<action>`)
+   - Available options
+   - Context to help the human decide
+   - Completed tasks table
+
+**Use when**: The plan has a fork point where different approaches are possible and the right choice depends on human preference, business context, or information the planner could not determine.
+
+**Example scenario**: Choosing between two authentication providers, deciding whether to use a specific third-party library or build in-house.
+
+### checkpoint:human-action
+
+**Purpose**: The task requires something the executor cannot do — a manual step that involves the human interacting with external systems, creating accounts, or performing physical actions.
+
+**Executor behavior**:
+1. **STOP before executing the task**
+2. Return a structured `CHECKPOINT: HUMAN-ACTION` response containing:
+   - What the human needs to do (from `<action>`)
+   - Step-by-step instructions
+   - Prompt to tell the executor when done
+   - Completed tasks table
+
+**Use when**: External setup is required — creating API keys, configuring DNS, setting up OAuth applications, or any action that requires credentials or permissions the agent does not have.
+
+**Example scenario**: The human needs to create a Discord application in the Developer Portal and paste the client ID and secret into `.env`.
+
+---
+
+## Checkpoint in Plan Format
+
+Checkpoints are declared in the task's `type` attribute in the plan XML:
+
+```xml
+<task id="02-01-T3" type="checkpoint:human-verify" tdd="false">
+  <name>Verify OAuth login flow in browser</name>
+  <files>...</files>
+  <action>...</action>
+  <verify>Open browser to localhost:3000/auth/login and complete the flow</verify>
+  <done>User can log in via Discord OAuth and see their profile</done>
+</task>
+```
+
+Valid checkpoint type values:
+- `checkpoint:human-verify`
+- `checkpoint:decision`
+- `checkpoint:human-action`
+
+Non-checkpoint task types use `type="auto"`.
+
+---
+
+## Autonomous vs Non-Autonomous Plans
+
+The plan frontmatter field `autonomous: true|false` indicates whether a plan contains checkpoint tasks:
+
+| Value | Meaning |
+|-------|---------|
+| `autonomous: true` | No checkpoint tasks. The executor can complete all tasks without human intervention. |
+| `autonomous: false` | Contains at least one checkpoint task. Execution will pause at some point. |
+
+The build orchestrator uses this field to determine execution strategy:
+- Autonomous plans can be executed in parallel with other autonomous plans in the same wave
+- Non-autonomous plans may block the wave while waiting for human input
+- The orchestrator tracks checkpoint state in `.checkpoint-manifest.json`
+
+---
+
+## Continuation Protocol
+
+After a checkpoint is resolved (human provides their answer, completes their action, or confirms verification), the orchestrator spawns a **fresh continuation executor** to resume from where the checkpoint paused.
+
+The continuation executor receives:
+1. The full plan content
+2. A table of completed tasks with their commit hashes
+3. The checkpoint resolution (what the human decided or confirmed)
+4. The task number to resume from
+5. The same project context as the original executor
+
+**Key rules for continuation**:
+- The continuation executor does NOT re-execute completed tasks
+- It reads the partial SUMMARY.md if one exists
+- It verifies prior commits exist via `git log`
+- It resumes from the next uncompleted task after the checkpoint
+
+---
+
+## Authentication Gate (Implicit Checkpoint)
+
+The executor also supports an implicit checkpoint for authentication failures. If the executor encounters an authentication error (missing API key, expired token, invalid credentials) during any task, it immediately stops and returns a `CHECKPOINT: AUTH-GATE` response.
+
+This is not declared in the plan — it triggers automatically when an auth error is detected. The response includes:
+- Which task was blocked
+- What credential is needed
+- Where to configure it
+- The actual error message
+
+---
+
+## Architectural Deviation (Implicit Checkpoint)
+
+Similarly, if the executor discovers that the plan's approach cannot work (API changed, framework limitation, dependency conflict), it stops with a `CHECKPOINT: ARCHITECTURAL-DEVIATION` response. This follows Deviation Rule 4 from the executor's deviation handling protocol.
+
+---
+
+## Best Practices for Planners
+
+When creating plans that include checkpoints:
+
+1. **Minimize checkpoint tasks** — each one pauses execution and requires human attention
+2. **Place checkpoints at natural boundaries** — after a feature is complete, not in the middle of wiring
+3. **Group manual actions** — combine related human actions into a single checkpoint rather than multiple stops
+4. **Provide clear instructions** — the `<action>` and `<verify>` elements should give the human everything they need
+5. **Consider autonomous alternatives** — if a task CAN be verified automatically, prefer `type="auto"` with a robust `<verify>` command
+6. **Set `autonomous: false`** in the plan frontmatter when any task is a checkpoint
+
+---
+
+## Automation-First Philosophy
+
+### 5 Golden Rules
+1. If Claude CAN run it, Claude MUST run it
+2. If Claude CAN verify it, Claude MUST verify it
+3. Only checkpoint for things requiring human senses or credentials
+4. Group manual actions to minimize checkpoint count
+5. Never ask the user to do something automatable
+
+### Automatable Quick Reference
+
+| Action | Automatable? | Notes |
+|--------|-------------|-------|
+| Run tests | YES | `npm test`, `pytest`, etc. |
+| Start dev server | YES | `npm run dev` (check port) |
+| Check environment variables | YES | `env \| grep KEY` |
+| Build project | YES | `npm run build` |
+| Run linting | YES | `npm run lint` |
+| Database migrations | YES | CLI commands |
+| Click email verification link | NO | Requires browser + inbox |
+| 3DS payment verification | NO | Requires card + phone |
+| OAuth consent screen | NO | Requires browser interaction |
+| Hardware token/YubiKey | NO | Physical device |
+
+### Anti-Patterns
+- Asking user to "start the dev server" — just run it
+- Asking user to "check if tests pass" — run `npm test`
+- Saying "please verify the output" without running verification commands first
+- Creating a checkpoint for `mkdir` or `npm install`