pan-wizard 2.8.1

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

@@ -0,0 +1,306 @@
+<trigger>
+Use this workflow when:
+- Starting a new session on an existing project
+- User says "continue", "what's next", "where were we", "resume"
+- Any planning operation when .planning/ already exists
+- User returns after time away from project
+</trigger>
+
+<purpose>
+Instantly restore full project context so "Where were we?" has an immediate, complete answer.
+</purpose>
+
+<required_reading>
+@~/.claude/pan-wizard-core/references/continuation-format.md
+</required_reading>
+
+<process>
+
+<step name="initialize">
+Load all context in one call:
+
+```bash
+INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs init resume)
+```
+
+Parse JSON for: `state_exists`, `roadmap_exists`, `project_exists`, `planning_exists`, `has_interrupted_agent`, `interrupted_agent_id`, `commit_docs`.
+
+**If `state_exists` is true:** Proceed to load_state
+**If `state_exists` is false but `roadmap_exists` or `project_exists` is true:** Offer to reconstruct state.md
+**If `planning_exists` is false:** This is a new project - route to /pan:new-project
+</step>
+
+<step name="load_state">
+
+Read and parse state.md, then project.md:
+
+```bash
+cat .planning/state.md
+cat .planning/project.md
+```
+
+**From state.md extract:**
+
+- **Project Reference**: Core value and current focus
+- **Current Position**: Phase X of Y, Plan A of B, Status
+- **Progress**: Visual progress bar
+- **Recent Decisions**: Key decisions affecting current work
+- **Pending Todos**: Ideas captured during sessions
+- **Blockers/Concerns**: Issues carried forward
+- **Session Continuity**: Where we left off, any resume files
+
+**From project.md extract:**
+
+- **What This Is**: Current accurate description
+- **Requirements**: Validated, Active, Out of Scope
+- **Key Decisions**: Full decision log with outcomes
+- **Constraints**: Hard limits on implementation
+
+</step>
+
+<step name="check_incomplete_work">
+Look for incomplete work that needs attention:
+
+```bash
+# Check for continue-here files (mid-plan resumption)
+ls .planning/phases/*/.continue-here*.md 2>/dev/null
+
+# Check for plans without summaries (incomplete execution)
+for plan in .planning/phases/*/*-plan.md; do
+  summary="${plan/PLAN/SUMMARY}"
+  [ ! -f "$summary" ] && echo "Incomplete: $plan"
+done 2>/dev/null
+
+# Check for interrupted agents (use has_interrupted_agent and interrupted_agent_id from init)
+if [ "$has_interrupted_agent" = "true" ]; then
+  echo "Interrupted agent: $interrupted_agent_id"
+fi
+```
+
+**If .continue-here file exists:**
+
+- This is a mid-plan resumption point
+- Read the file for specific resumption context
+- Flag: "Found mid-plan checkpoint"
+
+**If PLAN without SUMMARY exists:**
+
+- Execution was started but not completed
+- Flag: "Found incomplete plan execution"
+
+**If interrupted agent found:**
+
+- Subagent was spawned but session ended before completion
+- Read agent-history.json for task details
+- Flag: "Found interrupted agent"
+  </step>
+
+<step name="present_status">
+Present complete project status to user:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PROJECT STATUS                                               ║
+╠══════════════════════════════════════════════════════════════╣
+║  Building: [one-liner from project.md "What This Is"]         ║
+║                                                               ║
+║  Phase: [X] of [Y] - [Phase name]                            ║
+║  Plan:  [A] of [B] - [Status]                                ║
+║  Progress: [██████░░░░] XX%                                  ║
+║                                                               ║
+║  Last activity: [date] - [what happened]                     ║
+╚══════════════════════════════════════════════════════════════╝
+
+[If incomplete work found:]
+⚠️  Incomplete work detected:
+    - [.continue-here file or incomplete plan]
+
+[If interrupted agent found:]
+⚠️  Interrupted agent detected:
+    Agent ID: [id]
+    Task: [task description from agent-history.json]
+    Interrupted: [timestamp]
+
+    Resume with: Task tool (resume parameter with agent ID)
+
+[If pending todos exist:]
+📋 [N] pending todos — /pan:todo-check to review
+
+[If blockers exist:]
+⚠️  Carried concerns:
+    - [blocker 1]
+    - [blocker 2]
+
+[If alignment is not ✓:]
+⚠️  Brief alignment: [status] - [assessment]
+```
+
+</step>
+
+<step name="determine_next_action">
+Based on project state, determine the most logical next action:
+
+**If interrupted agent exists:**
+→ Primary: Resume interrupted agent (Task tool with resume parameter)
+→ Option: Start fresh (abandon agent work)
+
+**If .continue-here file exists:**
+→ Primary: Resume from checkpoint
+→ Option: Start fresh on current plan
+
+**If incomplete plan (PLAN without SUMMARY):**
+→ Primary: Complete the incomplete plan
+→ Option: Abandon and move on
+
+**If phase in progress, all plans complete:**
+→ Primary: Transition to next phase
+→ Option: Review completed work
+
+**If phase ready to plan:**
+→ Check if context.md exists for this phase:
+
+- If context.md missing:
+  → Primary: Discuss phase vision (how user imagines it working)
+  → Secondary: Plan directly (skip context gathering)
+- If context.md exists:
+  → Primary: Plan the phase
+  → Option: Review roadmap
+
+**If phase ready to execute:**
+→ Primary: Execute next plan
+→ Option: Review the plan first
+</step>
+
+<step name="offer_options">
+Present contextual options based on project state:
+
+```
+What would you like to do?
+
+[Primary action based on state - e.g.:]
+1. Resume interrupted agent [if interrupted agent found]
+   OR
+1. Execute phase (/pan:exec-phase {phase})
+   OR
+1. Discuss Phase 3 context (/pan:discuss-phase 3) [if context.md missing]
+   OR
+1. Plan Phase 3 (/pan:plan-phase 3) [if context.md exists or discuss option declined]
+
+[Secondary options:]
+2. Review current phase status
+3. Check pending todos ([N] pending)
+4. Review brief alignment
+5. Something else
+```
+
+**Note:** When offering phase planning, check for context.md existence first:
+
+```bash
+ls .planning/phases/XX-name/*-context.md 2>/dev/null
+```
+
+If missing, suggest discuss-phase before plan. If exists, offer plan directly.
+
+Wait for user selection.
+</step>
+
+<step name="route_to_workflow">
+Based on user selection, route to appropriate workflow:
+
+- **Execute plan** → Show command for user to run after clearing:
+  ```
+  ---
+
+  ## ▶ Next Up
+
+  **{phase}-{plan}: [Plan Name]** — [objective from plan.md]
+
+  `/pan:exec-phase {phase}`
+
+  <sub>`/clear` first → fresh context window</sub>
+
+  ---
+  ```
+- **Plan phase** → Show command for user to run after clearing:
+  ```
+  ---
+
+  ## ▶ Next Up
+
+  **Phase [N]: [Name]** — [Goal from roadmap.md]
+
+  `/pan:plan-phase [phase-number]`
+
+  <sub>`/clear` first → fresh context window</sub>
+
+  ---
+
+  **Also available:**
+  - `/pan:discuss-phase [N]` — gather context first
+  - `/pan:research-phase [N]` — investigate unknowns
+
+  ---
+  ```
+- **Transition** → ./transition.md
+- **Check todos** → Read .planning/todos/pending/, present summary
+- **Review alignment** → Read project.md, compare to current state
+- **Something else** → Ask what they need
+</step>
+
+<step name="update_session">
+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]
+```
+
+This ensures if session ends unexpectedly, next resume knows the state.
+</step>
+
+</process>
+
+<reconstruction>
+If state.md is missing but other artifacts exist:
+
+"state.md missing. Reconstructing from artifacts..."
+
+1. Read project.md → Extract "What This Is" and Core Value
+2. Read roadmap.md → Determine phases, find current position
+3. Scan \*-summary.md files → Extract decisions, concerns
+4. Count pending todos in .planning/todos/pending/
+5. Check for .continue-here files → Session continuity
+
+Reconstruct and write state.md, then proceed normally.
+
+This handles cases where:
+
+- Project predates state.md introduction
+- File was accidentally deleted
+- Cloning repo without full .planning/ state
+  </reconstruction>
+
+<quick_resume>
+If user says "continue" or "go":
+- Load state silently
+- Determine primary action
+- Execute immediately without presenting options
+
+"Continuing from [state]... [action]"
+</quick_resume>
+
+<success_criteria>
+Resume is complete when:
+
+- [ ] state.md loaded (or reconstructed)
+- [ ] Incomplete work detected and flagged
+- [ ] Clear status presented to user
+- [ ] Contextual next actions offered
+- [ ] User knows exactly where project stands
+- [ ] Session continuity updated
+      </success_criteria>

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

@@ -0,0 +1,121 @@
+<purpose>
+Milestone retrospective — analyze historical .planning/ data for process improvement insights.
+
+Run after milestone completion to reflect on estimation accuracy, verification patterns, and common gaps.
+</purpose>
+
+<core_principle>
+**Process learning through quantitative analysis**
+
+Retrospectives are not blame sessions. They identify systemic patterns that improve future planning:
+- Were estimates accurate? (planned phases vs actual including gap closures)
+- Did verification catch issues? (first-try pass rate)
+- What gaps recur? (common patterns across phases)
+</core_principle>
+
+<process>
+
+<step name="gather_data" priority="first">
+Call pan-tools retro to gather all metrics:
+
+```bash
+RETRO=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs retro)
+```
+
+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."
+</step>
+
+<step name="analyze_estimation">
+**Estimation Accuracy Analysis**
+
+```
+Planned phases: {phases_planned}
+Completed: {phases_completed}
+Gap closure phases: {phases_decimal}
+Estimation accuracy: {estimation_accuracy_pct}%
+```
+
+| Accuracy | Assessment | Recommendation |
+|----------|-----------|----------------|
+| ≥ 90% | Excellent estimation | Keep current approach |
+| 70-89% | Good, some gaps expected | Minor calibration needed |
+| 50-69% | Under-estimated scope | Add buffer phases or break work smaller |
+| < 50% | Significant under-estimation | Review requirements gathering process |
+</step>
+
+<step name="analyze_verification">
+**Verification Pattern Analysis**
+
+```
+Verifications: {verifications_total}
+Passed first try: {verifications_passed_first_try} ({first_try_rate_pct}%)
+Gaps found: {verifications_gaps_found}
+Human needed: {verifications_human_needed}
+```
+
+| First-try rate | Assessment | Recommendation |
+|---------------|-----------|----------------|
+| ≥ 80% | Strong execution quality | Current workflow is effective |
+| 60-79% | Moderate gap rate | Improve plan detail or must_haves quality |
+| < 60% | High gap rate | Review plan-checker effectiveness, add more explicit must_haves |
+</step>
+
+<step name="analyze_patterns">
+**Common Gap Patterns**
+
+If `common_gap_patterns` is non-empty:
+
+```
+Top recurring gap types:
+1. {pattern} — appeared {count} times
+2. {pattern} — appeared {count} times
+...
+```
+
+For each top pattern, suggest a preventive action:
+- Missing wiring → "Add explicit key_links to must_haves"
+- Stub detection → "Strengthen plan-checker substance checks"
+- Test failures → "Add test gate earlier in verification"
+- Missing files → "Require artifact existence in plan verify steps"
+</step>
+
+<step name="present_report">
+**Retrospective Report**
+
+```markdown
+## Milestone Retrospective
+
+### Estimation
+- Phases: {completed}/{planned} ({decimal} gap closures)
+- Accuracy: {accuracy}% — {assessment}
+- Recommendation: {recommendation}
+
+### Verification Quality
+- First-try pass rate: {rate}% — {assessment}
+- Gap phases needed: {gaps_found}
+- Human verification: {human_needed}
+- Recommendation: {recommendation}
+
+### Common Gap Patterns
+{pattern_list_with_recommendations}
+
+### Key Takeaways
+1. {takeaway based on data}
+2. {takeaway based on data}
+3. {takeaway based on data}
+
+### Next Milestone Adjustments
+- {specific adjustment for next milestone planning}
+```
+</step>
+
+</process>
+
+<constraints>
+- Read-only: this workflow does not modify any files
+- Data-driven: all assessments backed by quantitative metrics
+- Actionable: every finding includes a concrete recommendation
+- Non-judgmental: focus on systemic patterns, not individual decisions
+</constraints>

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

@@ -0,0 +1,213 @@
+<purpose>
+Interactive configuration of PAN workflow agents (research, plan_check, verifier) and model profile selection via multi-question prompt. Updates .planning/config.json with user preferences. Optionally saves settings as global defaults (~/.pan-wizard-core/defaults.json) for future projects.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="ensure_and_load_config">
+Ensure config exists and load current state:
+
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-ensure-section
+INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state load)
+```
+
+Creates `.planning/config.json` with defaults if missing and loads current config values.
+</step>
+
+<step name="read_current">
+```bash
+cat .planning/config.json
+```
+
+Parse current values (default to `true` if not present):
+- `workflow.research` — spawn researcher during plan-phase
+- `workflow.plan_check` — spawn plan checker during plan-phase
+- `workflow.verifier` — spawn verifier during execute-phase
+- `workflow.nyquist_validation` — validation architecture research during plan-phase
+- `model_profile` — which model each agent uses (default: `balanced`)
+- `git.branching_strategy` — branching approach (default: `"none"`)
+</step>
+
+<step name="present_settings">
+Use AskUserQuestion with current values pre-selected:
+
+```
+AskUserQuestion([
+  {
+    question: "Which model profile for agents?",
+    header: "Model",
+    multiSelect: false,
+    options: [
+      { label: "Quality", description: "Opus everywhere except verification (highest cost)" },
+      { label: "Balanced (Recommended)", description: "Opus for planning, Sonnet for execution/verification" },
+      { label: "Budget", description: "Sonnet for writing, Haiku for research/verification (lowest cost)" }
+    ]
+  },
+  {
+    question: "Spawn Plan Researcher? (researches domain before planning)",
+    header: "Research",
+    multiSelect: false,
+    options: [
+      { label: "Yes", description: "Research phase goals before planning" },
+      { label: "No", description: "Skip research, plan directly" }
+    ]
+  },
+  {
+    question: "Spawn Plan Checker? (verifies plans before execution)",
+    header: "Plan Check",
+    multiSelect: false,
+    options: [
+      { label: "Yes", description: "Verify plans meet phase goals" },
+      { label: "No", description: "Skip plan verification" }
+    ]
+  },
+  {
+    question: "Spawn Execution Verifier? (verifies phase completion)",
+    header: "Verifier",
+    multiSelect: false,
+    options: [
+      { label: "Yes", description: "Verify must-haves after execution" },
+      { label: "No", description: "Skip post-execution verification" }
+    ]
+  },
+  {
+    question: "Auto-advance pipeline? (discuss → plan → execute automatically)",
+    header: "Auto",
+    multiSelect: false,
+    options: [
+      { label: "No (Recommended)", description: "Manual /clear + paste between stages" },
+      { label: "Yes", description: "Chain stages via Task() subagents (same isolation)" }
+    ]
+  },
+  {
+    question: "Enable Nyquist Validation? (researches test coverage during planning)",
+    header: "Nyquist",
+    multiSelect: false,
+    options: [
+      { label: "Yes (Recommended)", description: "Research automated test coverage during plan-phase. Adds validation requirements to plans. Blocks approval if tasks lack automated verify." },
+      { label: "No", description: "Skip validation research. Good for rapid prototyping or no-test phases." }
+    ]
+  },
+  {
+    question: "Git branching strategy?",
+    header: "Branching",
+    multiSelect: false,
+    options: [
+      { label: "None (Recommended)", description: "Commit directly to current branch" },
+      { label: "Per Phase", description: "Create branch for each phase (pan/phase-{N}-{name})" },
+      { label: "Per Milestone", description: "Create branch for entire milestone (pan/{version}-{name})" }
+    ]
+  }
+])
+```
+</step>
+
+<step name="update_config">
+Merge new settings into existing config.json:
+
+```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
+  },
+  "git": {
+    "branching_strategy": "none" | "phase" | "milestone"
+  }
+}
+```
+
+Write updated config to `.planning/config.json`.
+</step>
+
+<step name="save_as_defaults">
+Ask whether to save these settings as global defaults for future projects:
+
+```
+AskUserQuestion([
+  {
+    question: "Save these as default settings for all new projects?",
+    header: "Defaults",
+    multiSelect: false,
+    options: [
+      { label: "Yes", description: "New projects start with these settings (saved to ~/.pan-wizard-core/defaults.json)" },
+      { label: "No", description: "Only apply to this project" }
+    ]
+  }
+])
+```
+
+If "Yes": write the same config object (minus project-specific fields like `brave_search`) to `~/.pan-wizard-core/defaults.json`:
+
+```bash
+mkdir -p ~/.gsd
+```
+
+Write `~/.pan-wizard-core/defaults.json` with:
+```json
+{
+  "mode": <current>,
+  "depth": <current>,
+  "model_profile": <current>,
+  "commit_docs": <current>,
+  "parallelization": <current>,
+  "branching_strategy": <current>,
+  "workflow": {
+    "research": <current>,
+    "plan_check": <current>,
+    "verifier": <current>,
+    "auto_advance": <current>,
+    "nyquist_validation": <current>
+  }
+}
+```
+</step>
+
+<step name="confirm">
+Display:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PAN ► SETTINGS UPDATED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+| Setting              | Value |
+|----------------------|-------|
+| Model Profile        | {quality/balanced/budget} |
+| Plan Researcher      | {On/Off} |
+| Plan Checker         | {On/Off} |
+| Execution Verifier   | {On/Off} |
+| Auto-Advance         | {On/Off} |
+| Nyquist Validation   | {On/Off} |
+| Git Branching        | {None/Per Phase/Per Milestone} |
+| Saved as Defaults    | {Yes/No} |
+
+These settings apply to future /pan:plan-phase and /pan:exec-phase runs.
+
+Quick commands:
+- /pan:profile <profile> — switch model profile
+- /pan:plan-phase --research — force research
+- /pan:plan-phase --skip-research — skip research
+- /pan:plan-phase --skip-verify — skip plan check
+```
+</step>
+
+</process>
+
+<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 offered to save as global defaults (~/.pan-wizard-core/defaults.json)
+- [ ] Changes confirmed to user
+</success_criteria>