pan-wizard 3.33.0 → 3.34.0

package/pan-wizard-core/workflows/plan-phase.md

@@ -1,5 +1,5 @@
 <purpose>
-Create executable phase prompts (plan.md files) for a roadmap phase with integrated research and verification. Default flow: Research (if needed) -> Plan -> Verify -> Done. Orchestrates pan-phase-researcher, pan-planner, and pan-plan-checker agents with a revision loop (max 3 iterations).
+Create executable phase prompts (plan.md files) for a roadmap phase with integrated research and verification. Default flow: Research (if needed) -> Plan -> Verify -> Done. Orchestrates pan-phase-researcher, pan-planner, and pan-plan-checker agents with a revision loop (at most 2 revisions, up to 3 checks).
 </purpose>
 
 <required_reading>
@@ -8,7 +8,7 @@ Read all files referenced by the invoking prompt's execution_context before star
 @~/.claude/pan-wizard-core/references/ui-brand.md
 @~/.claude/pan-wizard-core/references/guardrails.md
 
-> **Also see:** `~/.claude/pan-wizard-core/learnings/universal/` — AI-derived patterns from prior experiments. **Don't skim the whole folder.** Run `pan-tools learn topics-for --agent planner --token-budget 5000 --raw` to load only the topics tagged relevant for planning at the configured budget. Per P-RES-002 (distractor-density research), reading every topic degrades reasoning even at modest token counts.
+> **Also see:** `~/.claude/pan-wizard-core/learnings/universal/` — AI-derived patterns from prior experiments. **Don't skim the whole folder.** Run `pan-tools learn topics-for --agent planner --cue "<phase goal; the files it touches>" --token-budget 5000 --raw` to load the topics that match this task, within the budget; if none matches, it falls back to the topics tagged relevant for planning. Per P-RES-002 (distractor-density research), reading every topic degrades reasoning even at modest token counts.
 </required_reading>
 
 ## Phase 0 — Clarify Phase Scope (recommended)
@@ -19,7 +19,7 @@ Before drafting the phase plan, confirm:
 2. **What's deliberately out of scope?**
 3. **Any constraints or dependencies on other phases?**
 
-If the answers aren't already in `.planning/requirements.md` or the phase context file, ask the user. A 2-minute clarification prevents 30-minute rework downstream.
+If the answers aren't already in the phase's roadmap section and requirement lines (`pan-tools roadmap slice <phase> --raw` prints them) or the phase context file, ask the user — except with `--auto` or `workflow.auto_advance: true`, where you proceed with what the files hold (as step 4 does). A 2-minute clarification prevents 30-minute rework downstream.
 
 ## Re-Read Checkpoints
 
@@ -44,7 +44,7 @@ INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs init plan-phase "$PHASE"
 
 Parse JSON for: `researcher_model`, `planner_model`, `checker_model`, `research_enabled`, `plan_checker_enabled`, `nyquist_validation_enabled`, `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_research`, `has_context`, `has_plans`, `plan_count`, `planning_exists`, `roadmap_exists`, `phase_req_ids`.
 
-**File paths (for <files_to_read> blocks):** `state_path`, `roadmap_path`, `requirements_path`, `context_path`, `research_path`, `verification_path`, `uat_path`. These are null if files don't exist.
+**File paths (for <files_to_read> blocks):** `state_path`, `roadmap_path`, `requirements_path`, `context_path`, `research_path`, `verification_path`, `uat_path`. The first three are always set, even when the file is missing; the other four are absent (treat as null) when their file does not exist.
 
 **If `planning_exists` is false:** Error — run `/pan:new-project` first.
 
@@ -63,9 +63,9 @@ Extract `--prd <filepath>` from $ARGUMENTS. If present, set PRD_FILE to the file
 
 **If no phase number:** Detect next unplanned phase from roadmap.
 
-**If `phase_found` is false:** Validate phase exists in roadmap.md. If valid, create the directory using `phase_slug` and `padded_phase` from init:
+**If `phase_found` is false:** Validate phase exists in roadmap.md. If valid, create the directory (scaffold pads the number and honours the planning root) and use the path it prints as `phase_dir`:
 ```bash
-mkdir -p ".planning/phases/${padded_phase}-${phase_slug}"
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs scaffold phase-dir --phase "${PHASE}" --name "{phase_name}" --raw
 ```
 
 **Existing artifacts from init:** `has_research`, `has_plans`, `plan_count`.
@@ -78,6 +78,14 @@ PHASE_INFO=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap get-phase
 
 **If `found` is false:** Error with available phases. **If `found` is true:** Extract `phase_number`, `phase_name`, `goal` from JSON.
 
+## 3.1. Write the Phase's Roadmap Slice
+
+```bash
+SLICE_PATH=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap slice "${PHASE}" --write --raw)
+```
+
+`SLICE_PATH` (`{slice_path}` below) is what this phase needs from roadmap.md and requirements.md: a line for every phase, this phase's section, the goals of the phases it depends on, and its requirement lines. The researcher, planner and checker read it instead of the whole files, which a long project re-read on every turn of every spawn. Plans name it in their `<context>` too, so executors read it rather than the whole roadmap. **If `SLICE_PATH` is empty** (no roadmap section, or no phase directory yet), list `{roadmap_path}` and `{requirements_path}` wherever `{slice_path}` appears below.
+
 ## 3.5. Handle PRD Express Path
 
 **Skip if:** No `--prd` flag in arguments.
@@ -214,15 +222,15 @@ If "Run discuss-phase first": Display `/pan:discuss-phase {X}` and exit workflow
 
 **P-1401 lightweight-phase bypass (v3.7.3+):** Also skip per-phase research when ALL three are true:
 
-1. The phase has only **1 plan** (read `plan_count` from init JSON)
-2. The plan's `change_class` is in `[chore, docs, feat-trivial]` (i.e., scaffolding, config, single-file feat with ≤3 tasks)
+1. The phase's roadmap section expects no more than one plan (`**Plans:** 1 plan`, or the `TBD` / `0 plans` the roadmapper and `phase add`/`insert` write before any planning); init's `plan_count` counts plans already written, which is 0 before the first planning run
+2. The phase is scaffolding, config, docs or a single-file feature with ≤3 tasks (judge from its goal; no plan field records this)
 3. Project-level `research/architecture.md`, `features.md`, `stack.md` already exist (so the planner has broad context to draw from)
 
 In that case, log a `decision` trace event (`type: "decision", category: "skip-research-trivial"`) and proceed directly to step 6 (planning). Saves ~3 commits and ~5 minutes per trivial phase. Surfaced by panloop run: Phase 1 (project setup, scaffolding only) over-ceremonialized.
 
 This is a workflow-level optimization — the planner still produces a plan, just without per-phase research.md. Phase 2+ phases with substantive build work still go through full research.
 
-**P-1602 phase_record_compact (v3.7.5+):** When `workflow.phase_record_compact: true` AND the lightweight-phase bypass above triggers, also skip per-phase context.md creation (step 4) and emit a single combined `${PHASE_NUM}-record.md` after planning containing: goal, locked decisions (from project-level context), plan summary, must_haves. Reduces the planning output (context, research, plan) to a record and a plan for trivial phases; execution still writes the plan's summary. Off by default — opt-in via `pan-tools config-set workflow.phase_record_compact true`. Substantive phases (>1 plan or non-trivial change_class) still produce full per-phase artifacts regardless of this flag.
+**P-1602 phase_record_compact (v3.7.5+):** When `workflow.phase_record_compact: true` AND the lightweight-phase bypass above triggers, also skip per-phase context.md creation (step 4) and emit a single combined `${padded_phase}-record.md` after planning containing: goal, locked decisions (from project-level context), plan summary, must_haves. Reduces the planning output (context, research, plan) to a record and a plan for trivial phases; execution still writes the plan's summary. Off by default — opt-in via `pan-tools config-set workflow.phase_record_compact true`. Substantive phases (more than one plan, or more than scaffolding, config, docs or a single-file feature) still produce full per-phase artifacts regardless of this flag.
 
 **If `has_research` is true (from init) AND no `--research` flag:** Use existing, skip to step 6.
 
@@ -240,7 +248,7 @@ Display banner:
 ### Spawn pan-phase-researcher
 
 ```bash
-PHASE_DESC=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap get-phase "${PHASE}" | jq -r '.section')
+PHASE_DESC=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap get-phase "${PHASE}" --raw)   # --raw prints the phase's section
 ```
 
 Research prompt:
@@ -253,7 +261,7 @@ Answer: "What do I need to know to PLAN this phase well?"
 
 <files_to_read>
 - {context_path} (USER DECISIONS from /pan:discuss-phase)
-- {requirements_path} (Project requirements)
+- {slice_path} (This phase's roadmap and requirements)
 - {state_path} (Project decisions and history)
 </files_to_read>
 
@@ -266,7 +274,7 @@ Answer: "What do I need to know to PLAN this phase well?"
 </additional_context>
 
 <output>
-Write to: {phase_dir}/{phase_num}-research.md
+Write to: {phase_dir}/{padded_phase}-research.md
 </output>
 ```
 
@@ -306,7 +314,7 @@ node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs(phase-${PHASE}): a
 **If not found (and nyquist enabled):** Display warning:
 ```
 ⚠ Nyquist validation enabled but researcher did not produce a Validation Architecture section.
-  Continuing without validation strategy. Plans may fail Dimension 8 check.
+  Continuing without validation strategy. The plan checker skips Nyquist Compliance (Dimension 9).
 ```
 
 ## 6. Check Existing Plans
@@ -319,17 +327,7 @@ ls "${PHASE_DIR}"/*-plan.md 2>/dev/null
 
 ## 7. Use Context Paths from INIT
 
-Extract from INIT JSON:
-
-```bash
-STATE_PATH=$(echo "$INIT" | jq -r '.state_path // empty')
-ROADMAP_PATH=$(echo "$INIT" | jq -r '.roadmap_path // empty')
-REQUIREMENTS_PATH=$(echo "$INIT" | jq -r '.requirements_path // empty')
-RESEARCH_PATH=$(echo "$INIT" | jq -r '.research_path // empty')
-VERIFICATION_PATH=$(echo "$INIT" | jq -r '.verification_path // empty')
-UAT_PATH=$(echo "$INIT" | jq -r '.uat_path // empty')
-CONTEXT_PATH=$(echo "$INIT" | jq -r '.context_path // empty')
-```
+`state_path`, `roadmap_path`, `requirements_path`, `research_path`, `verification_path`, `uat_path` and `context_path` come straight from the INIT JSON; fill the `{…_path}` placeholders below with them. `state_path`, `roadmap_path` and `requirements_path` are always set, even when the file is missing; the other four are absent from the JSON when their file does not exist.
 
 ## 8. Spawn pan-planner Agent
 
@@ -351,8 +349,7 @@ Planner prompt:
 
 <files_to_read>
 - {state_path} (Project State)
-- {roadmap_path} (Roadmap)
-- {requirements_path} (Requirements)
+- {slice_path} (This phase's roadmap and requirements — read the whole roadmap.md or requirements.md only for something it leaves out)
 - {context_path} (USER DECISIONS from /pan:discuss-phase)
 - {research_path} (Technical Research)
 - {verification_path} (Verification Gaps - if --gaps)
@@ -396,8 +393,8 @@ Task(
 ## 9. Handle Planner Return
 
 - **`## PLANNING COMPLETE`:** Display plan count. If `--skip-verify` or `plan_checker_enabled` is false (from init): skip to step 13. Otherwise: step 10.
-- **`## CHECKPOINT REACHED`:** Present to user, get response, spawn continuation (step 12)
-- **`## PLANNING INCONCLUSIVE`:** Show attempts, offer: Add context / Retry / Manual
+- **`## GAP CLOSURE PLANS CREATED`:** (`--gaps` mode) Handle as `## PLANNING COMPLETE`.
+- **`## CHECKPOINT REACHED`:** Present to user, get response, spawn a fresh planner (step 8's Task) with the response added to its prompt
 
 ## 10. Spawn pan-plan-checker Agent
 
@@ -419,8 +416,7 @@ Checker prompt:
 
 <files_to_read>
 - {PHASE_DIR}/*-plan.md (Plans to verify)
-- {roadmap_path} (Roadmap)
-- {requirements_path} (Requirements)
+- {slice_path} (This phase's roadmap and requirements — read the whole roadmap.md or requirements.md only for something it leaves out)
 - {context_path} (USER DECISIONS from /pan:discuss-phase)
 - {research_path} (Technical Research — includes Validation Architecture)
 </files_to_read>
@@ -463,7 +459,7 @@ The fallback reads the heading when the report carries no valid `pan-verdict` bl
 
 Each re-check in the revision loop overwrites the same file and is recorded again as the next attempt. The issues a revision resolved are closed by that record.
 
-## 12. Revision Loop (Max 3 Iterations)
+## 12. Revision Loop (At Most 2 Revisions, 3 Checks)
 
 Track `iteration_count` (starts at 1 after initial plan + check).
 
@@ -512,7 +508,7 @@ Offer: 1) Force proceed, 2) Provide guidance and retry, 3) Abandon
 
 **On "Force proceed":** record that planning continues past the remaining issues. Execution and the milestone audit will see them as deferred, with this reason:
 ```bash
-node ~/.claude/pan-wizard-core/bin/pan-tools.cjs findings dispose --phase "${PHASE_NUMBER}" --agent pan-plan-checker --open --as deferred --reason "force proceed after 3 plan revision iterations"
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs findings dispose --phase "${PHASE_NUMBER}" --agent pan-plan-checker --open --as deferred --reason "force proceed after 3 plan checks"
 ```
 
 ## 13. Present Final Status
@@ -585,7 +581,7 @@ Task(
 
     <instructions>
     1. Read exec-phase.md from execution_context for your complete workflow
-    2. Follow ALL steps: initialize, handle_branching, validate_phase, discover_and_group_plans, execute_waves, aggregate_results, close_parent_artifacts, verify_phase_goal, update_roadmap
+    2. Follow ALL steps: initialize, handle_branching, validate_phase, discover_and_group_plans, execute_waves, checkpoint_handling, aggregate_results, generate_tests, code_review, close_parent_artifacts, verify_phase_goal, update_roadmap, offer_next
     3. The --no-transition flag means: after verification + roadmap update, STOP and return status. Do NOT run transition.md.
     4. When spawning executor agents, use subagent_type='pan-executor' with the existing @file pattern from the workflow
     5. When spawning verifier agents, use subagent_type='pan-verifier'
@@ -614,7 +610,8 @@ Task(
   Auto-advance stopped: Execution needs review.
 
   Review the output above and continue manually:
-  /pan:exec-phase ${PHASE}
+  /pan:plan-phase ${PHASE} --gaps   (verification found gaps)
+  /pan:exec-phase ${PHASE}          (execution did not finish)
   ```
 
 **If neither `--auto` nor config enabled:**

package/pan-wizard-core/workflows/profile.md

@@ -34,7 +34,7 @@ This creates `.planning/config.json` with defaults if missing and loads current
 Detect if this is a downgrade and confirm with user:
 
 ```
-TIER_MAP = { "quality": 3, "balanced": 2, "budget": 1 }
+TIER_MAP = { "quality": 2, "balanced": 2, "budget": 1 }   # quality and balanced resolve every agent to the same tier and effort
 current_profile = config.model_profile OR "balanced"
 new_profile = $ARGUMENTS.profile
 
@@ -86,7 +86,7 @@ Display confirmation with model table and cost estimate for selected profile:
 
 Agents will now use:
 
-[Show table from MODEL_PROFILES in pan-tools.cjs for selected profile]
+[Show table from MODEL_PROFILES in ~/.claude/pan-wizard-core/bin/lib/core.cjs for selected profile]
 
 Example (`budget` — the only profile that steps agents below the reasoning
 tier; `quality` and `balanced` put every agent on `reasoning`):

package/pan-wizard-core/workflows/progress.md

@@ -29,9 +29,9 @@ Exit.
 
 If missing state.md: suggest `/pan:new-project`.
 
-**If roadmap.md missing but project.md exists:**
+**If `.planning/requirements.md` is missing but roadmap.md and project.md exist:**
 
-This means a milestone was completed and archived. Go to **Route F** (between milestones).
+This means a milestone was completed and archived (`/pan:milestone-done` deletes requirements.md and keeps roadmap.md with the milestone collapsed). Go to **Route F** (between milestones).
 
 If missing both roadmap.md and project.md: suggest `/pan:new-project`.
 </step>
@@ -109,12 +109,10 @@ Plan [M] of [phase-total]: [status]
 CONTEXT: [✓ if has_context | - if not]
 
 ## Key Decisions Made
-- [extract from $STATE.decisions[]]
-- [e.g. jq -r '.decisions[].decision' from state-snapshot]
+- [extract from $STATE.decisions[]: each entry's summary]
 
 ## Blockers/Concerns
 - [extract from $STATE.blockers[]]
-- [e.g. jq -r '.blockers[].text' from state-snapshot]
 
 ## Pending Todos
 - [count] pending — /pan:todo-check to review
@@ -280,7 +278,7 @@ State: "Current phase is {X}. Milestone has {N} phases (highest: {Y})."
 
 **Route C: Phase complete, more phases remain**
 
-Read roadmap.md to get the next phase's name and goal.
+Take the next phase's name and goal from `$ROADMAP` (`roadmap analyze` lists every phase's `name` and `goal`).
 
 ```
 ---
@@ -333,7 +331,7 @@ All {N} phases finished!
 
 ---
 
-**Route F: Between milestones (roadmap.md missing, project.md exists)**
+**Route F: Between milestones (requirements.md missing, roadmap.md and project.md exist)**
 
 A milestone was completed and archived. Ready to start the next milestone cycle.
 

package/pan-wizard-core/workflows/quick.md

@@ -267,6 +267,7 @@ Execute quick task ${next_num}.
 - Commit each task atomically
 - Create summary at: ${QUICK_DIR}/${next_num}-summary.md
 - Do NOT update roadmap.md (quick tasks are separate from planned phases)
+- This is not a phase: skip `init execute-phase` and the state updates (advance-plan, update-progress, record-metric, record-session, roadmap update-plan-progress, requirements mark-complete); Step 7 of this workflow records the task in state.md
 </constraints>
 ",
   subagent_type="pan-executor",
@@ -381,7 +382,8 @@ Use `date` and `description_cell` from init. Write `description_cell` exactly as
 
 Use `date` and `description_cell` from init (one line, whatever the description held):
 ```
-Last activity: ${date} - Completed quick task ${next_num}: ${description_cell}
+**Last Activity:** ${date}
+**Last Activity Description:** Completed quick task ${next_num}: ${description_cell}
 ```
 
 Use Edit tool to make these changes atomically
@@ -449,8 +451,8 @@ Ready for next task: /pan:quick
 - [ ] User provides task description
 - [ ] `--full` flag parsed from arguments when present
 - [ ] Slug generated (lowercase, hyphens, max 40 chars)
-- [ ] Next number calculated (001, 002, 003...)
-- [ ] Directory created at `.planning/quick/NNN-slug/`
+- [ ] Next number taken from init (`next_num`: 1, 2, 3...)
+- [ ] Directory created at init's `task_dir` (`.planning/quick/{next_num}-{slug}/`)
 - [ ] `${next_num}-plan.md` created by planner
 - [ ] (--full) Plan checker validates plan, revision loop capped at 2
 - [ ] `${next_num}-summary.md` created by executor

package/pan-wizard-core/workflows/remove-phase.md

@@ -102,7 +102,7 @@ Extract from result: `removed`, `directory_deleted`, `renamed_directories`, `ren
 Stage and commit the removal:
 
 ```bash
-node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "chore: remove phase {target} ({original-phase-name})" --files .planning/
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "chore: remove phase {target} ({original-phase-name})" --files .planning/ --force
 ```
 
 The commit message preserves the historical record of what was removed.

package/pan-wizard-core/workflows/research-phase.md

@@ -35,7 +35,12 @@ If exists: Offer update/view/skip options.
 
 ```bash
 INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs init phase-op "${PHASE}")
-# Extract: phase_dir, padded_phase, phase_number, state_path, requirements_path, context_path
+# Extract: phase_dir, padded_phase, phase_slug, phase_number, state_path, requirements_path, context_path
+# phase_dir is null when the phase has no directory yet: create it (scaffold pads the number and honours the planning root) and use the printed path as phase_dir
+case "{phase_dir}" in ""|null) node ~/.claude/pan-wizard-core/bin/pan-tools.cjs scaffold phase-dir --phase "${PHASE}" --name "{phase_name}" --raw ;; esac
+
+# This phase's roadmap and requirements, written into the phase directory
+SLICE_PATH=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap slice "${PHASE}" --write --raw)
 ```
 
 ## Step 4: Spawn Researcher
@@ -48,7 +53,7 @@ Research implementation approach for Phase {phase}: {name}
 
 <files_to_read>
 - {context_path} (USER DECISIONS from /pan:discuss-phase)
-- {requirements_path} (Project requirements)
+- {slice_path} (This phase's roadmap and requirements; if SLICE_PATH is empty, {requirements_path} instead)
 - {state_path} (Project decisions and history)
 </files_to_read>
 
@@ -57,7 +62,7 @@ Phase description: {description}
 </additional_context>
 
 <output>
-Write to: .planning/phases/${PHASE}-{slug}/${PHASE}-research.md
+Write to: {phase_dir}/{padded_phase}-research.md
 </output>",
   subagent_type="pan-phase-researcher",
   model="{researcher_model}"
@@ -67,7 +72,6 @@ Write to: .planning/phases/${PHASE}-{slug}/${PHASE}-research.md
 ## Step 5: Handle Return
 
 - `## RESEARCH COMPLETE` — Display summary, offer: Plan/Dig deeper/Review/Done
-- `## CHECKPOINT REACHED` — Present to user, spawn continuation
-- `## RESEARCH INCONCLUSIVE` — Show attempts, offer: Add context/Try different mode/Manual
+- `## RESEARCH BLOCKED` — Display the blocker, offer: Provide context / Skip research / Abort
 
 </process>

package/pan-wizard-core/workflows/resume-project.md

@@ -252,12 +252,10 @@ Before proceeding to routed workflow, update session continuity:
 
 Update state.md:
 
-```markdown
-## Session Continuity
-
-Last session: [now]
-Stopped at: Session resumed, proceeding to [action]
-Resume file: [updated if applicable]
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state record-session \
+  --stopped-at "Session resumed, proceeding to [action]" \
+  --resume-file "[updated if applicable, else None]"
 ```
 
 This ensures if session ends unexpectedly, next resume knows the state.

package/pan-wizard-core/workflows/retro.md

@@ -22,6 +22,8 @@ Call pan-tools retro to gather all metrics:
 RETRO=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs retro)
 ```
 
+If the user passed `--write-memory` (and `--max N`), pass them on: `pan-tools retro --write-memory [--max N]`. It is the one flag that writes, appending recurring-pattern entries to the agent logs in `.planning/memory/`, and the JSON then carries `memory.wrote`. Never add it on your own.
+
 Parse JSON for: `phases_planned`, `phases_completed`, `phases_decimal`, `estimation_accuracy_pct`, `verifications_total`, `verifications_passed_first_try`, `verifications_gaps_found`, `verifications_human_needed`, `first_try_rate_pct`, `common_gap_patterns`.
 
 **If error:** Report "No roadmap found — run /pan:new-project first."
@@ -114,7 +116,7 @@ For each top pattern, suggest a preventive action:
 </process>
 
 <constraints>
-- Read-only: this workflow does not modify any files
+- Read-only: this workflow does not modify any files, unless the user passed `--write-memory` (then `pan-tools retro` appends to the agent logs in `.planning/memory/` and nothing else changes)
 - Data-driven: all assessments backed by quantitative metrics
 - Actionable: every finding includes a concrete recommendation
 - Non-judgmental: focus on systemic patterns, not individual decisions

package/pan-wizard-core/workflows/settings.md

@@ -24,7 +24,7 @@ Creates `.planning/config.json` with defaults if missing and loads current confi
 cat .planning/config.json
 ```
 
-Parse current values (default to `true` if not present):
+Parse current values (when a key is absent, use PAN's default: `true` for research, plan_check and verifier; `false` for nyquist_validation):
 - `workflow.research` — spawn researcher during plan-phase
 - `workflow.plan_check` — spawn plan checker during plan-phase
 - `workflow.verifier` — spawn verifier during execute-phase
@@ -110,7 +110,7 @@ AskUserQuestion([
     multiSelect: false,
     options: [
       { label: "Static (Recommended)", description: "Profile assigns fixed tiers to each agent. Predictable and simple." },
-      { label: "Complexity", description: "Adjust tiers up/down based on task complexity (file count, requirements, architecture). Saves tokens on simple phases." }
+      { label: "Complexity", description: "Adjust tiers by task complexity, only where a model is resolved with the task passed (resolve-model --metadata); the *_model values workflows pass are not, so it changes nothing there" }
     ]
   }
 ])
@@ -118,27 +118,18 @@ AskUserQuestion([
 </step>
 
 <step name="update_config">
-Merge new settings into existing config.json:
+Write each answer with `config-set`, which keeps every other key in the `workflow` and `routing` objects:
 
-```json
-{
-  ...existing_config,
-  "model_profile": "quality" | "balanced" | "budget",
-  "workflow": {
-    "research": true/false,
-    "plan_check": true/false,
-    "verifier": true/false,
-    "auto_advance": true/false,
-    "nyquist_validation": true/false
-  },
-  "branching_strategy": "none" | "phase" | "milestone",
-  "routing": {
-    "strategy": "static" | "complexity"
-  }
-}
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-set model_profile <quality|balanced|budget>
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-set workflow.research <true|false>
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-set workflow.plan_check <true|false>
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-set workflow.verifier <true|false>
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-set workflow.auto_advance <true|false>
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-set workflow.nyquist_validation <true|false>
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-set branching_strategy <none|phase|milestone>
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-set routing.strategy <static|complexity>
 ```
-
-Write updated config to `.planning/config.json`.
 </step>
 
 <step name="save_as_defaults">
@@ -179,7 +170,8 @@ Write `~/.pan-wizard/defaults.json` with:
     "verifier": <current>,
     "auto_advance": <current>,
     "nyquist_validation": <current>
-  }
+  },
+  "routing": { "strategy": <current> }
 }
 ```
 </step>
@@ -218,8 +210,8 @@ Quick commands:
 
 <success_criteria>
 - [ ] Current config read
-- [ ] User presented with 7 settings (profile + 5 workflow toggles + git branching)
-- [ ] Config updated with model_profile, workflow, and git sections
+- [ ] User presented with the settings above (model profile, workflow toggles, git branching, routing strategy)
+- [ ] Config updated with model_profile, workflow, branching_strategy and routing
 - [ ] User offered to save as global defaults (~/.pan-wizard/defaults.json)
 - [ ] Changes confirmed to user
 </success_criteria>

package/pan-wizard-core/workflows/todo-check.md

@@ -127,7 +127,7 @@ Use AskUserQuestion:
 ```bash
 node ~/.claude/pan-wizard-core/bin/pan-tools.cjs todo complete "[filename]"
 ```
-This moves it to `.planning/todos/completed/` with a `completed:` date — the directory `init todos` and `/pan:progress` count.
+This moves it out of `.planning/todos/pending/` (the directory `init todos` and `/pan:progress` count) into `.planning/todos/completed/` with a `completed:` date.
 Update state.md todo count. Present problem/solution context. Begin work or ask how to proceed.
 
 **Add to phase plan:**

package/pan-wizard-core/workflows/transition.md

@@ -4,7 +4,7 @@
 
 1. `.planning/state.md`
 2. `.planning/project.md`
-3. `.planning/roadmap.md`
+3. The current phase's roadmap slice (`.planning/phases/XX-current/XX-roadmap-slice.md`) — not the whole roadmap.md (Route A takes the next phase from `phase complete` and `roadmap get-phase`)
 4. Current phase's plan files (`*-plan.md`)
 5. Current phase's summary files (`*-summary.md`)
 
@@ -152,7 +152,7 @@ If found, delete them — phase is complete, handoffs are stale.
 **Delegate roadmap.md and state.md updates to pan-tools:**
 
 ```bash
-TRANSITION=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs phase complete "${current_phase}")
+TRANSITION=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs phase complete "${current_phase}")   # skip when exec-phase invoked this workflow: its `phase complete` already ran — reuse that result
 ```
 
 The CLI handles:
@@ -358,9 +358,9 @@ Then Edit state.md (still under the P-1604 batched-write policy — fold this Ed
 **Format:**
 
 ```markdown
-Last session: [today]
-Stopped at: Phase [X] complete, ready to plan Phase [X+1]
-Resume file: None
+**Last session:** [today]
+**Stopped At:** Phase [X] complete, ready to plan Phase [X+1]
+**Resume File:** None
 ```
 
 **Step complete when:**
@@ -396,12 +396,12 @@ This returns all phases with goals, disk status, and completion info.
 
 **Route A: More phases remain in milestone**
 
-Read roadmap.md to get the next phase's name and goal.
+Take the name from `next_phase_name` (the `phase complete` result) and the goal from `roadmap get-phase "${next_phase}"`, not the whole roadmap.md.
 
 **Check if next phase has context.md:**
 
 ```bash
-ls .planning/phases/*[X+1]*/*-context.md 2>/dev/null
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs init phase-op "${next_phase}"   # has_context is true when the next phase has a context.md
 ```
 
 **If next phase exists:**
@@ -448,8 +448,8 @@ Task(
     <instructions>
     1. Read plan-phase.md from execution_context for your complete workflow.
     2. Follow ALL steps: initialize, validate_phase, load context.md, handle research (P-1401 bypass if applicable), spawn pan-planner, optionally spawn pan-plan-checker, then auto-advance to exec-phase via Task (per plan-phase.md step 14).
-    3. After exec-phase completes and verification passes, exec-phase will return to its own auto-advance handler which spawns transition.md — that transition will spawn Phase ${NEXT_PHASE}+1 via this same pattern, recursing until milestone-done.
-    4. Do NOT use the Skill tool or /pan: commands. Do NOT exit early — let the recursion run.
+    3. plan-phase step 14 spawns exec-phase with --no-transition, so exec-phase returns without running transition.md and the chain ends there: on PHASE COMPLETE plan-phase prints `/pan:discuss-phase {next} --auto` as the next step; on GAPS FOUND it stops and reports the gaps.
+    4. Do NOT use the Skill tool or /pan: commands. Do NOT exit early — wait for the exec-phase Task to return.
     </instructions>
   ",
   subagent_type="general-purpose",
@@ -500,7 +500,7 @@ Task(
 ```
 
 **Handle next-phase Task return:**
-- **PHASE COMPLETE** (the spawned chain reached verification + roadmap update for ${NEXT_PHASE} and beyond, and either hit milestone-done or recursed further) → Done. Workflow chain finished.
+- **PHASE COMPLETE** (the spawned chain reached verification + roadmap update for ${NEXT_PHASE} and stopped at that phase's boundary; plan-phase printed `/pan:discuss-phase {next} --auto`) → Done. Workflow chain finished.
 - **GAPS FOUND / FAILED / TIMEOUT** → Display the failure, stop the recursion, return status to user. Do NOT attempt to skip ahead.
 
 </if>
@@ -574,10 +574,10 @@ Phase {X} marked complete.
 
 🎉 Milestone {version} is 100% complete — all {N} phases finished!
 
-⚡ Auto-continuing: Complete milestone and archive
+Auto-advance stops at the milestone boundary. Next: /pan:milestone-done {version}
 ```
 
-Exit skill and invoke SlashCommand("/pan:milestone-done {version}")
+Stop here and show `/pan:milestone-done {version}` as the next step: the milestone boundary ends the auto chain (auto-advance was cleared above).
 
 </if>
 

package/pan-wizard-core/workflows/update.md

@@ -24,19 +24,32 @@ case "$VERSION_FILE" in
   ./*) SCOPE="LOCAL" ;;
   *)   SCOPE="GLOBAL" ;;
 esac
+# The same templated path names the runtime: the installer rewrites ~/.claude/ to
+# this runtime's own directory. With no runtime flag the installer installs Claude
+# Code only, so the flag must be passed.
+case "$VERSION_FILE" in
+  *.codex/*)  RUNTIME="--codex" ;;
+  *.gemini/*) RUNTIME="--gemini" ;;
+  *opencode/*) RUNTIME="--opencode" ;;
+  *.github/*|*.copilot/*) RUNTIME="--copilot" ;;
+  *)          RUNTIME="--claude" ;;
+esac
 
 if [ -f "$VERSION_FILE" ] && [ -f "$MARKER_FILE" ] && grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+' "$VERSION_FILE"; then
   cat "$VERSION_FILE"
+  echo "$RUNTIME"
   echo "$SCOPE"
 else
   echo "UNKNOWN"
+  echo "$RUNTIME"
+  echo "$SCOPE"
 fi
 ```
 
-Parse output (there is ONE install; scope is derived from the shape of the single templated prefix):
-- If last line is "LOCAL": this install is local-scoped (templated prefix is `./`-relative); installed version is first line; use `--local`
-- If last line is "GLOBAL": this install is global-scoped (templated prefix is an absolute path); installed version is first line; use `--global`
-- If "UNKNOWN": the VERSION/marker files are missing or invalid; proceed to install step (treat as version 0.0.0)
+Parse output (there is ONE install; scope and runtime are derived from the single templated prefix). The output is three lines: the installed version (or `UNKNOWN`), the runtime flag (`--claude`, `--codex`, `--gemini`, `--opencode` or `--copilot`) and the scope. Remember the runtime flag: the install step writes it into its command.
+- If last line is "LOCAL": this install is local-scoped (templated prefix is `./`-relative); use `--local`
+- If last line is "GLOBAL": this install is global-scoped (templated prefix is an absolute path); use `--global`
+- If the first line is "UNKNOWN": the VERSION/marker files are missing or invalid; proceed to install step (treat as version 0.0.0) — the runtime and scope lines still apply
 
 **If VERSION file missing:**
 ```
@@ -63,7 +76,7 @@ npm view pan-wizard version 2>/dev/null
 ```
 Couldn't check for updates (offline or npm unavailable).
 
-To update manually: `npx pan-wizard --global`
+To update manually: `npx -y pan-wizard@latest {runtime_flag} --global` (`--local` for a local install), with the runtime flag and scope step 1 printed
 ```
 
 Exit.
@@ -155,28 +168,23 @@ Run the update using the install type detected in step 1:
 
 **If LOCAL install:**
 ```bash
-npx -y pan-wizard@latest --local
+npx -y pan-wizard@latest {runtime_flag} --local
 ```
 
-**If GLOBAL install (or unknown):**
+**If GLOBAL install:**
 ```bash
-npx -y pan-wizard@latest --global
+npx -y pan-wizard@latest {runtime_flag} --global
 ```
 
-Capture output. If install fails, show error and exit.
+`{runtime_flag}` is the runtime line step 1 printed: write the flag itself into the command. A variable set in step 1's shell call is gone in this one (each Bash call starts a new shell), and an empty `""` argument in its place installs Claude Code only. A `--config-dir` or `--unified-skills` install is not recognised from its path: for those, re-run the installer with your original flags instead.
 
-Clear the update cache so statusline indicator disappears:
+Capture output. If install fails, show error and exit.
 
-**If LOCAL install:**
-```bash
-rm -f ~/.claude/cache/pan-update-check.json
-```
+Clear the update cache so the statusline indicator disappears. The update-check hook keeps it under your home directory for every install, local or global, in the runtime's own config directory: `.claude` (Claude Code), `.codex` (Codex), `.gemini` (Gemini CLI) or `.copilot` (Copilot CLI); OpenCode runs no update-check hook, so there is nothing to clear there:
 
-**If GLOBAL install:**
 ```bash
-rm -f ~/.claude/cache/pan-update-check.json
+rm -f "$HOME/<config dir from the list above>/cache/pan-update-check.json"
 ```
-(Paths are templated at install time for runtime compatibility)
 </step>
 
 <step name="display_result">