pan-wizard 2.9.0 → 3.4.1

package/commands/pan/mcp-bridge.md

@@ -0,0 +1,145 @@
+---
+name: pan:mcp-bridge
+group: External tools
+description: Discover available MCP tools and recommend which ones apply to a phase. Discovery-only; auto-invocation deferred.
+argument-hint: "list | recommend <phase> | cache [--servers <json>] [--runtime <name>]"
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+---
+
+<objective>
+Surface Model Context Protocol (MCP) tools visible to the host runtime and recommend which ones might apply to a specific phase plan.
+
+Reduced scope from Spec B v1's X-7: **discovery and recommendation only**. Auto-injection of MCP tools into planner context and auto-invocation from executor agents are deliberately deferred (likely Wave 5+ or v3.5). This keeps v3.3 narrow and avoids coupling PAN to Claude Code's MCP schema stability.
+</objective>
+
+<execution_context>
+@~/.claude/pan-wizard-core/bin/lib/bridge.cjs
+</execution_context>
+
+<subcommands>
+
+### `list`
+
+Show cached MCP tools with server grouping and schemas.
+
+```
+/pan:mcp-bridge list
+```
+
+**Output (JSON):**
+```json
+{
+  "cached_at": "2026-04-18T12:34:56Z",
+  "runtime": "claude",
+  "server_count": 3,
+  "tool_count": 12,
+  "tools": [
+    { "server": "linear", "name": "linear.updateTicket", "description": "...", "schema": {...} },
+    ...
+  ],
+  "source": "cache" | "empty"
+}
+```
+
+When `source: "empty"`, either no MCP servers are configured or the host runtime hasn't populated the cache yet. See the `cache` subcommand for manual seeding.
+
+### `recommend <phase>`
+
+Given a phase number, match cached MCP tools against the phase's plan text and return tools ranked by keyword relevance.
+
+```
+/pan:mcp-bridge recommend 7
+/pan:mcp-bridge recommend 12 --max 5 --min-score 2
+```
+
+**Flags:**
+- `--max N` — cap recommendations (default 10)
+- `--min-score N` — minimum keyword hit count (default 1)
+
+**Output (JSON):**
+```json
+{
+  "phase": "7",
+  "phase_name": "API refactor",
+  "runtime": "claude",
+  "total_candidates": 12,
+  "recommendations": [
+    {
+      "server": "linear",
+      "name": "linear.updateTicket",
+      "description": "Update a Linear issue",
+      "score": 3,
+      "hits": ["linear", "ticket", "update"]
+    }
+  ]
+}
+```
+
+Scoring is naive keyword frequency with word boundaries — not semantic embeddings. A tool's name and description are tokenized into keywords (≥3 chars); each match in the phase plan text scores 1 point.
+
+### `cache`
+
+Write or inspect the MCP tools cache at `.planning/bridge/available-tools.json`.
+
+```
+# Inspect current cache (same as `list` but raw)
+/pan:mcp-bridge cache
+
+# Seed cache from scripted discovery (for testing or external pipeline)
+/pan:mcp-bridge cache --runtime claude --servers '[{"name":"linear","tools":[{"name":"linear.updateTicket","description":"Update ticket"}]}]'
+```
+
+Normally the host runtime writes this file. The CLI path exists for test fixtures and external-script integration.
+
+</subcommands>
+
+<workflow>
+
+**New to a project with MCP tools?** Run `/pan:mcp-bridge list` to see what's available. If empty, check the host runtime's MCP config — `.claude/settings.json` for Claude Code, or the runtime's equivalent.
+
+**Planning a phase that might touch external systems?** Run `/pan:mcp-bridge recommend <phase>` to get a ranked shortlist. Copy relevant tool names into the phase plan's "External tools" section so the executor knows to invoke them.
+
+**Pre-milestone review:** walk through each remaining phase with `/pan:mcp-bridge recommend` to catch "we should have automated this via Linear/Slack/etc." realizations before shipping.
+
+</workflow>
+
+<caveats>
+
+**Discovery is a cache, not a live probe.** The host runtime owns populating `.planning/bridge/available-tools.json`. PAN does not query MCP servers directly — that would require runtime-specific HTTP or IPC integration this command deliberately avoids.
+
+**Keyword scoring is crude.** "Postgres" and "PostgreSQL" are different tokens; `postgresql` in a plan won't match a `postgres.query` tool unless the plan also says "postgres." Tune your plan language or expand tool descriptions to improve matches.
+
+**Claude Code is the primary target.** MCP is a Claude-first protocol. Other runtimes may have their own tool-discovery mechanisms; the cache schema is intentionally generic so a future Codex/Gemini equivalent could populate the same file.
+
+**No automatic invocation.** This command never calls MCP tools. It tells you what's available and what might apply. The actual invocation happens via the host runtime's normal tool-use flow (Claude Code's tool calls, etc.) when the executor agent decides to use a recommended tool.
+
+</caveats>
+
+<runtime_compatibility>
+
+| Runtime | list | recommend | cache |
+|---------|------|-----------|-------|
+| Claude Code | Full | Full | Full (host-populated) |
+| OpenCode | Stub (empty cache returns gracefully) | Stub | CLI write works |
+| Gemini CLI | Stub | Stub | CLI write works |
+| Codex CLI | Stub | Stub | CLI write works |
+| Copilot CLI | Stub | Stub | CLI write works |
+
+On non-Claude runtimes, the aggregator and recommendation logic still work — they just report zero tools until something populates the cache.
+
+</runtime_compatibility>
+
+<future_scope>
+
+Explicitly deferred from v3.3 (documented in ADR-0023 / Spec B v2 notes):
+
+1. **Auto-inject recommended tools into planner context** — requires a stable MCP schema contract and a plan-template extension. Candidate for v3.5.
+2. **Auto-invoke MCP tools from executor agent** — requires permission-gating and per-tool safety review. Candidate for v3.5+.
+3. **Cross-runtime tool discovery** — generic MCP-like protocol for non-Claude runtimes. No timeline; needs ecosystem signal.
+
+Until those land, this command is the minimum viable integration: you see what's there, you get suggestions, you decide manually.
+
+</future_scope>

package/commands/pan/milestone-audit.md

@@ -31,6 +31,29 @@ Glob: .planning/phases/*/*-summary.md
 Glob: .planning/phases/*/*-verification.md
 </context>
 
+<citation_requirement>
+Every coverage judgment in the audit MUST cite evidence from the codebase.
+
+**Before writing any requirement as "covered" or "not covered", verify by reading the code.**
+
+**Grounding rules:**
+- "Covered" requires: file:line where the requirement is implemented + verification.md or test evidence
+- "Partially covered" requires: file:line showing what exists + specific gap description with expected location
+- "Not covered" requires: grep showing the expected functionality doesn't exist (show the search and empty result)
+- Cross-phase integration claims require: file:line in phase A's output + file:line in phase B's consumer
+
+**Anti-pattern:**
+```
+BAD:  "Requirement R3 is covered — the billing module handles this"
+      → Which file? Which function? How do you know?
+GOOD: "Requirement R3 is covered — generateInvoice() at src/billing.ts:42 implements line-item
+       calculation. Verified in phase-2-verification.md (line 18). Integration: called from
+       src/api/orders.ts:156 (phase 3)."
+```
+
+Do not trust summary files at face value. If a verification.md says "all tests pass" but you haven't confirmed the test count, that claim is ungrounded. Spot-check at least 2 verification files by running the actual tests.
+</citation_requirement>
+
 <process>
 Execute the audit-milestone workflow from @~/.claude/pan-wizard-core/workflows/milestone-audit.md end-to-end.
 Preserve all workflow gates (scope determination, verification reading, integration check, requirements coverage, routing).

package/commands/pan/new-project.md

@@ -37,6 +37,70 @@ Initialize a new project through unified flow: questioning → research (optiona
 @~/.claude/pan-wizard-core/templates/requirements.md
 </execution_context>
 
+<progressive_context>
+Load context in layers — do NOT read everything upfront. Each layer builds on the previous.
+
+**Layer 1: Manifest (always load first)**
+- package.json / Cargo.toml / pyproject.toml — project identity, deps, scripts
+- .planning/ existence check — is this a fresh start or existing project?
+- README.md first 50 lines — what the project claims to be
+
+**Layer 2: Structure (load during questioning)**
+- Directory tree (Glob top-level patterns) — understand project shape
+- Entry points — main files, index files, server files
+- Test infrastructure — test framework, test directory
+
+**Layer 3: Hotspots (load during research, if research is enabled)**
+- Most-changed files (git log --name-only) — where active work happens
+- Largest files — complexity centers
+- Import graph roots — most-depended-on modules
+
+**Layer 4: Baselines (load only when generating requirements/roadmap)**
+- Test count + pass rate
+- Build status
+- Dependency audit (outdated, vulnerable)
+
+**Why layered:** Loading everything at Layer 1 wastes 40-60% of context on information not needed until later. For greenfield projects, Layers 3-4 are empty and should be skipped entirely.
+</progressive_context>
+
+<routing_decision_tree>
+Use this decision tree to select the correct path. Evaluate conditions top-to-bottom; take the FIRST match.
+
+```
+IF .planning/ already exists AND contains project.md:
+  → WARN: "Project already initialized. Use /pan:resume to continue."
+  → STOP (do not overwrite existing project)
+
+ELSE IF --auto flag AND @ reference document provided:
+  → ASK config questions only (commit_docs, model_profile)
+  → SKIP interactive questioning (use the @ document as project context)
+  → RUN research automatically
+  → GENERATE requirements from research + @ document
+  → GENERATE roadmap from requirements
+  → No further interaction until complete
+
+ELSE IF --auto flag WITHOUT @ reference:
+  → ERROR: "--auto requires an @ referenced idea document"
+  → STOP
+
+ELSE (interactive mode — default):
+  → RUN questioning flow (5-area deep questioning)
+  → ASK: "Should I research the domain ecosystem?" (Y/N)
+    → IF Y: spawn researchers → synthesize → continue
+    → IF N: skip research → continue
+  → PRESENT requirements for approval
+  → PRESENT roadmap for approval
+  → COMMIT if commit_docs=true
+```
+
+**Research routing:**
+```
+IF user says research: spawn pan-project-researcher agents
+IF user declines research: skip directly to requirements generation
+IF codebase already has substantial code: suggest skipping research (existing code IS the context)
+```
+</routing_decision_tree>
+
 <process>
 Execute the new-project workflow from @~/.claude/pan-wizard-core/workflows/new-project.md end-to-end.
 Preserve all workflow gates (validation, approvals, commits, routing).

package/commands/pan/pause.md

@@ -27,13 +27,54 @@ Routes to the pause-work workflow which handles:
 State and phase progress are gathered in-workflow with targeted reads.
 </context>
 
+<handoff_schema>
+The `.continue-here.md` file MUST contain ALL of the following sections. Missing sections cause resume failures.
+
+```yaml
+# Required fields for .continue-here.md
+session_id: "{date}-{slug}"           # Unique session identifier
+paused_at: "{ISO-8601 timestamp}"     # When work was paused
+phase: "{phase number and name}"      # Current phase being worked on
+plan: "{plan file path}"              # Which plan was active
+
+position:
+  last_completed_task: "{task ID}"    # Last task that was fully done
+  next_task: "{task ID}"              # What to do next
+  wave: "{wave number, if applicable}"
+
+progress:
+  tasks_done: [{id, title, status}]   # All completed tasks this session
+  tasks_remaining: [{id, title}]      # What's left in the plan
+  test_baseline: "{N passing}"        # Test count when session started
+  test_current: "{N passing}"         # Test count at pause time
+
+decisions:
+  - "{decision made and why}"         # Choices that affect remaining work
+
+blockers:
+  - "{blocker description}"           # Anything preventing progress
+
+context:
+  files_modified: ["{paths}"]         # Files changed this session
+  key_findings: ["{findings}"]        # Non-obvious discoveries
+  next_action: "{specific action}"    # Exact first step on resume
+```
+
+**Why every field matters:**
+- `position` → resume agent knows WHERE to start (not re-reading the whole plan)
+- `progress` → resume agent knows test baseline (detects regressions vs pre-existing)
+- `decisions` → resume agent won't re-debate settled questions
+- `blockers` → resume agent can flag to user immediately instead of rediscovering
+- `context.next_action` → resume agent's first action is productive, not exploratory
+</handoff_schema>
+
 <process>
 **Follow the pause-work workflow** from `@~/.claude/pan-wizard-core/workflows/pause.md`.
 
 The workflow handles all logic including:
 1. Phase directory detection
 2. State gathering with user clarifications
-3. Handoff file writing with timestamp
+3. Handoff file writing with timestamp — **using the schema from `<handoff_schema>`**
 4. Git commit
 5. Confirmation with resume instructions
 </process>

package/commands/pan/plan-phase.md

@@ -40,6 +40,101 @@ Phase number: $ARGUMENTS (optional — auto-detects next unplanned phase if omit
 Normalize phase input in step 2 before any directory lookups.
 </context>
 
+<reflexion_loop>
+During the plan-checker verification iteration:
+1. Read the plan-checker's critique carefully
+2. For each identified gap: verify it is a genuine gap by re-reading the relevant requirement
+3. Do not blindly accept all critiques — some may be false positives from missing context
+4. Revise the plan to address genuine gaps only
+5. Maximum 2 revision iterations (plan → check → revise → check → final)
+This prevents over-revision while ensuring real gaps are closed.
+</reflexion_loop>
+
+<completion_contract>
+Planning is complete when ALL conditions are met:
+1. At least one plan.md file created in the phase directory
+2. Plan-checker passed (or max 2 revision iterations exhausted with final approval)
+3. Each plan contains: objective, task breakdown with estimates, dependency ordering, and key file links
+4. Research.md exists (unless --skip-research was used)
+5. User presented with results and next-step options
+
+Planning FAILS if: phase not found in roadmap, or planner agent returns empty/malformed output after retries.
+</completion_contract>
+
+<common_mistakes>
+Avoid these planning anti-patterns:
+```
+BAD:  Plan has 25 tasks for a single phase → too granular, executor loses context
+GOOD: 5-8 tasks per plan, each with clear scope and testable outcome
+
+BAD:  Task says "Implement the feature" with no file links or acceptance criteria
+      → Executor guesses at scope, misses edge cases
+GOOD: Task says "Add retry logic to api/client.ts:fetchData() — 3 retries with exponential backoff, tested by tests/client.test.ts"
+
+BAD:  Plan-checker flags a gap → blindly add a task without re-reading the requirement
+      → False positive becomes unnecessary work
+GOOD: Re-read the requirement → confirm the gap is real → then add the task
+```
+</common_mistakes>
+
+<routing_decision_tree>
+Use this decision tree to select the correct path. Evaluate conditions top-to-bottom; take the FIRST match.
+
+```
+IF --gaps flag is set:
+  → SKIP research (gap closure uses verification.md instead)
+  → READ verification.md for the phase
+  → PLAN with gap context
+  → VERIFY (unless --skip-verify)
+
+ELSE IF --prd <file> flag is set:
+  → SKIP discuss-phase entirely
+  → PARSE PRD file into context.md
+  → SKIP research (PRD provides requirements)
+  → PLAN from parsed requirements
+  → VERIFY (unless --skip-verify)
+
+ELSE IF --skip-research flag is set:
+  → SKIP research
+  → PLAN directly (must have roadmap context)
+  → VERIFY (unless --skip-verify)
+
+ELSE IF research.md already exists AND --research NOT set:
+  → SKIP research (reuse existing)
+  → PLAN using existing research.md
+  → VERIFY (unless --skip-verify)
+
+ELSE (default path):
+  → RUN research (spawn pan-phase-researcher)
+  → PLAN from research results
+  → VERIFY (unless --skip-verify)
+```
+
+**Verification loop routing:**
+```
+IF --skip-verify:
+  → Present plan, done
+
+ELSE:
+  → Spawn pan-plan-checker
+  → IF checker PASSES: done
+  → IF checker finds gaps (iteration 1): revise plan, re-check
+  → IF checker finds gaps (iteration 2): final revision, present with caveats
+  → Max 2 revision iterations
+```
+</routing_decision_tree>
+
+<cache_priming>
+**Before spawning research + planner agents, prime the prompt cache.** All sub-agents spawned within the next 5 minutes hit cached context instead of re-reading project.md / requirements.md / roadmap.md / state.md / standards.md.
+
+Run once per invocation:
+```
+pan-tools cache prime --summary
+```
+
+Returns `{blocks: [{path, bytes, cache}], total_bytes, sha}`. On Claude Code with Opus 4.7, the host runtime translates these block references into `cache_control: ephemeral`. On non-Claude runtimes or older models this is a no-op — nothing breaks.
+</cache_priming>
+
 <process>
 Execute the plan-phase workflow from @~/.claude/pan-wizard-core/workflows/plan-phase.md end-to-end.
 Preserve all workflow gates (validation, research, planning, verification loop, routing).

package/commands/pan/preview.md

@@ -0,0 +1,114 @@
+---
+name: pan:preview
+group: Foresight
+description: Preview what will happen — phase blast radius, phase dependency graph, or milestone ETA
+argument-hint: "phase <N> | phases | milestone"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - Task
+---
+
+<objective>
+Read-only foresight. Given a phase, a set of phases, or a milestone, produce a structured forecast: what files get touched, which tests might break, which phases can parallelize, when the milestone will actually finish.
+
+Consolidates Spec B v1's architect + simulate + predict-milestone into one entry point with three modes. The data layer (`pan-tools preview …`) extracts structured inputs from `.planning/`; the `pan-previewer` agent analyzes and writes the report. No source code is modified.
+</objective>
+
+<execution_context>
+@~/.claude/pan-wizard-core/bin/lib/preview.cjs
+@~/.claude/pan-wizard-core/templates/preview-report.md
+</execution_context>
+
+<modes>
+
+### `phase <N>` — Blast radius of one phase
+
+```
+/pan:preview phase 7
+```
+
+**What it does:**
+1. `pan-tools preview phase <N>` returns `{files_mentioned, test_files_mentioned, risk_signals, risk_score, plans[], status}`.
+2. Spawn `pan-previewer` with the payload as `<preview_input>`.
+3. Agent writes `.planning/phases/<N>/preview.md` with files touched / tests at risk / migration steps / risk assessment / bottom line.
+
+**Output:** `.planning/phases/<N>/preview.md`
+
+### `phases` — Cross-phase dependency graph
+
+```
+/pan:preview phases
+```
+
+**What it does:**
+1. `pan-tools preview phases` returns `{phases[], parallel_batches, mermaid, hidden_coupling_count}`.
+2. Spawn `pan-previewer` with `mode: phases` in the payload.
+3. Agent writes `.planning/architecture/dependency-graph.md` with mermaid DAG + parallel batches + hidden-coupling flags.
+
+**Output:** `.planning/architecture/dependency-graph.md`
+
+**Opus 4.7 1M-context bonus:** when the full repo fits in a single agent window, the agent cross-references plan text with actual source imports to catch coupling the frontmatter missed. On smaller-context models, the agent relies on data-layer output alone.
+
+### `milestone` — Completion ETA
+
+```
+/pan:preview milestone
+```
+
+**What it does:**
+1. `pan-tools preview milestone` returns `{phases_total, completed, remaining, avg_phase_duration_days, eta_date, confidence_pct, bottleneck, sample_size}`.
+2. Spawn `pan-previewer` with `mode: milestone`.
+3. Agent writes `.planning/milestones/preview-<today>.md` with ETA + confidence + bottleneck + caveats + bottom line.
+
+**Output:** `.planning/milestones/preview-YYYY-MM-DD.md`
+
+</modes>
+
+<workflow>
+
+**Before committing to a phase:** run `/pan:preview phase <N>` to see blast radius. A `risk_score ≥ 7` or a migration signal on auth files should prompt a review before `/pan:exec-phase`.
+
+**Before committing to a milestone date externally:** run `/pan:preview milestone`. Look at `confidence_pct` and `sample_size`. If sample is <3, don't promise a date.
+
+**Before running phases in parallel:** run `/pan:preview phases`. Parallel batches from the data layer are based on declared `depends_on` only; `hidden_coupling_count > 0` means there are cross-phase references the author should promote to explicit deps before parallelizing.
+
+</workflow>
+
+<process>
+
+For all modes:
+
+1. Run the corresponding `pan-tools preview <mode>` subcommand.
+2. Parse its JSON output.
+3. Spawn `pan-previewer` with a prompt that includes:
+   - `<preview_input>` block carrying the full JSON payload (mode field set explicitly)
+   - `<output_path>` block with the target file path
+   - `<files_to_read>` block with any phase context files the agent should load
+4. Agent writes the report file and returns a short confirmation.
+5. Echo the output path to the user.
+
+The agent does not need workflow context beyond what the data layer provides. Keep spawned-agent prompts lean — the agent's context budget is for reasoning about the structured input, not for loading the whole project.
+
+</process>
+
+<output_contract>
+The command returns the path to the generated preview document. Never paste the report back into conversation output — the file is the deliverable; reference it by path.
+</output_contract>
+
+<runtime_compatibility>
+
+| Runtime | phase | phases | milestone |
+|---------|-------|--------|-----------|
+| Claude Code | Full, thinking enabled | Full, 1M-ctx bonus on Opus 4.7 | Full |
+| OpenCode | Full | Data-layer + simple report | Full |
+| Gemini CLI | Full | Data-layer + simple report | Full |
+| Codex CLI | Full | Data-layer + simple report | Full |
+| Copilot CLI | Full | Data-layer + simple report | Full |
+
+The data layer (`pan-tools preview …`) works identically on all runtimes. What varies is the quality of the agent's synthesis — Opus 4.7 with thinking catches subtler risks than smaller models.
+
+</runtime_compatibility>

package/commands/pan/profile.md

@@ -35,3 +35,40 @@ The workflow handles all logic including:
 5. Cost estimation display (relative cost multiplier per profile)
 6. Confirmation display
 </process>
+
+<tier_decision_tree>
+**Opus 4.7 capability-aware routing** (since v2.10.0 — E-7). Even within a single profile, PAN picks a tier per-call based on three hints: context estimate, whether the task needs extended thinking, and whether prompt cache is warm.
+
+The decision order `resolveModel` applies after the baseline profile pick:
+
+```
+Baseline tier (from MODEL_PROFILES[agent][profile])
+        │
+        ▼
+┌─────────────────────────────────────────────┐
+│ context_estimate > 700K tokens?             │── yes ──▶ force reasoning (only 1M-ctx tier)
+└─────────────────────────────────────────────┘
+        │ no
+        ▼
+┌─────────────────────────────────────────────┐
+│ needs_thinking AND tier == fast?            │── yes ──▶ upgrade fast → mid
+└─────────────────────────────────────────────┘
+        │ no
+        ▼
+┌─────────────────────────────────────────────┐
+│ cache_warm AND !needs_thinking              │── yes ──▶ downgrade mid → fast
+│ AND context_estimate < 50K AND tier == mid  │
+└─────────────────────────────────────────────┘
+        │ no
+        ▼
+Final tier → provider-native model name
+```
+
+**Quick guide:**
+- Heavy verification (plan-checker, verifier, integration-checker, reviewer, debugger): `needs_thinking: true` — baseline upgrades fast→mid.
+- Map-codebase single-shot mode on Opus 4.7: `context_estimate > 700K` — forced to reasoning.
+- Routine exec tasks with project.md cached: `cache_warm + small ctx` — mid gets downgraded to fast for a cost win.
+- All rules are additive to the `quality` / `balanced` / `budget` profile you pick here — profile sets the floor, capability hints adjust upward or downward within that floor's band.
+
+**Inspecting routing:** use `pan-tools resolve-model <agent> --metadata '{"context_estimate":900000,"needs_thinking":true}'` to see what tier a given hint set resolves to.
+</tier_decision_tree>

package/commands/pan/quick.md

@@ -39,4 +39,19 @@ Context files are resolved inside the workflow (`init quick`) and delegated via
 <process>
 Execute the quick workflow from @~/.claude/pan-wizard-core/workflows/quick.md end-to-end.
 Preserve all workflow gates (validation, task description, planning, execution, state updates, commits).
+
+**Scope Containment:**
+Implement only what was asked. Do not refactor surrounding code, add unrelated improvements, or create abstractions for one-time fixes.
+
+**State Intent Before Implementing:**
+Before coding, state: "I will modify [files], adding [what], to achieve [goal]."
+
+**Pre-Commit Verification Checklist — apply before the final commit:**
+1. Every modified file was read before editing
+2. `git diff --stat` contains only files related to the task
+3. Tests pass (run the project's test suite)
+4. Commit message accurately describes the verified change
+5. No secrets or credentials staged
+
+If any check fails: fix and re-verify before committing.
 </process>

package/commands/pan/resume.md

@@ -26,6 +26,66 @@ Routes to the resume-project workflow which handles:
 @~/.claude/pan-wizard-core/workflows/resume-project.md
 </execution_context>
 
+<handoff_consumption>
+When a `.continue-here.md` file exists, parse it as structured handoff data before presenting options.
+
+**Required extraction (in order):**
+1. `position.next_task` → This is the FIRST thing to tell the user
+2. `blockers` → If non-empty, surface BEFORE offering to continue
+3. `decisions` → Load into context so they are not re-debated
+4. `progress.test_baseline` + `progress.test_current` → Verify current test count matches `test_current` (detect drift since pause)
+5. `context.next_action` → Use as the default suggested action
+
+**Resume validation:**
+- If `test_current` at resume time differs from stored value → warn user: "Test count changed since pause ({stored} → {current}). Someone else may have committed."
+- If `position.next_task` references a task not in the plan → warn: plan may have been revised since pause
+- If `blockers` exist → present them and ask if resolved before continuing
+
+**Anti-pattern:**
+```
+BAD:  Resume reads .continue-here.md, ignores position, re-reads entire plan from scratch
+      → Wastes context on already-completed work, may re-implement done tasks
+GOOD: Resume extracts position.next_task, skips completed tasks, starts exactly where paused
+```
+</handoff_consumption>
+
+<routing_decision_tree>
+Use this decision tree to select the correct resumption path. Evaluate top-to-bottom; take the FIRST match.
+
+```
+IF .planning/ does not exist:
+  → "No project found. Run /pan:new-project to get started."
+  → STOP
+
+ELSE IF .continue-here.md exists:
+  → PARSE handoff file using <handoff_consumption> protocol
+  → PRESENT: position, blockers, next action
+  → ROUTE to the command that was paused (exec-phase, plan-phase, etc.)
+
+ELSE IF state.md exists AND has status "in_progress":
+  → FIND incomplete work: plans without summaries, phases mid-execution
+  → IF incomplete phase found:
+    → PRESENT phase status + what remains
+    → OFFER: continue execution (/pan:exec-phase) or verify (/pan:verify-phase)
+  → IF no incomplete work but active milestone:
+    → PRESENT milestone progress
+    → OFFER: next unplanned phase (/pan:plan-phase) or audit (/pan:milestone-audit)
+
+ELSE IF state.md exists AND has status "blocked":
+  → PRESENT blockers from state.md
+  → OFFER: debug (/pan:debug) or unblock manually
+
+ELSE IF state.md exists AND has status "completed":
+  → "Current milestone is complete. Run /pan:milestone-done or /pan:milestone-new."
+  → STOP
+
+ELSE (state.md missing or unreadable):
+  → ATTEMPT reconstruction from .planning/ artifacts
+  → IF reconstruction succeeds: re-enter tree above
+  → IF reconstruction fails: "State is corrupted. Run /pan:new-project or restore from git."
+```
+</routing_decision_tree>
+
 <process>
 **Follow the resume-project workflow** from `@~/.claude/pan-wizard-core/workflows/resume-project.md`.
 
@@ -33,9 +93,9 @@ The workflow handles all resumption logic including:
 
 1. Project existence verification
 2. state.md loading or reconstruction
-3. Checkpoint and incomplete work detection
+3. Checkpoint and incomplete work detection — **parse using `<handoff_consumption>` protocol**
 4. Visual status presentation
 5. Context-aware option offering (checks context.md before suggesting plan vs discuss)
-6. Routing to appropriate next command
+6. Routing to appropriate next command — **following `<routing_decision_tree>`**
 7. Session continuity updates
    </process>