pan-wizard 2.8.1

package/commands/pan/add-phase.md

@@ -0,0 +1,44 @@
+---
+name: pan:add-phase
+group: Phase Management
+description: Add phase to end of current milestone in roadmap
+argument-hint: <description>
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+Add a new integer phase to the end of the current milestone in the roadmap.
+
+Routes to the add-phase workflow which handles:
+- Phase number calculation (next sequential integer)
+- Directory creation with slug generation
+- Roadmap structure updates
+- state.md roadmap evolution tracking
+</objective>
+
+<execution_context>
+@~/.claude/pan-wizard-core/workflows/add-phase.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (phase description)
+
+Roadmap and state are resolved in-workflow via `init phase-op` and targeted tool calls.
+</context>
+
+<process>
+**Follow the add-phase workflow** from `@~/.claude/pan-wizard-core/workflows/add-phase.md`.
+
+The workflow handles all logic including:
+1. Argument parsing and validation
+2. Roadmap existence checking
+3. Current milestone identification
+4. Next phase number calculation (ignoring decimals)
+5. Slug generation from description
+6. Phase directory creation
+7. Roadmap entry insertion
+8. state.md updates
+</process>

package/commands/pan/assumptions.md

@@ -0,0 +1,47 @@
+---
+name: pan:assumptions
+group: Phase Management
+description: Surface Claude's assumptions about a phase approach before planning
+argument-hint: "[phase]"
+allowed-tools:
+  - Read
+  - Bash
+  - Grep
+  - Glob
+---
+
+<objective>
+Analyze a phase and present Claude's assumptions about technical approach, implementation order, scope boundaries, risk areas, and dependencies.
+
+Purpose: Help users see what Claude thinks BEFORE planning begins - enabling course correction early when assumptions are wrong.
+Output: Conversational output only (no file creation) - ends with "What do you think?" prompt
+</objective>
+
+<execution_context>
+@~/.claude/pan-wizard-core/workflows/assumptions.md
+</execution_context>
+
+<context>
+Phase number: $ARGUMENTS (required)
+
+Project state and roadmap are loaded in-workflow using targeted reads.
+</context>
+
+<process>
+1. Validate phase number argument (error if missing or invalid)
+2. Check if phase exists in roadmap
+3. Follow assumptions.md workflow:
+   - Analyze roadmap description
+   - Surface assumptions about: technical approach, implementation order, scope, risks, dependencies
+   - Present assumptions clearly
+   - Prompt "What do you think?"
+4. Gather feedback and offer next steps
+</process>
+
+<success_criteria>
+
+- Phase validated against roadmap
+- Assumptions surfaced across five areas
+- User prompted for feedback
+- User knows next steps (discuss context, plan phase, or correct assumptions)
+  </success_criteria>

package/commands/pan/audit-deployment.md

@@ -0,0 +1,378 @@
+---
+name: pan:audit-deployment
+group: System
+description: Audit a PAN Wizard deployment — verify installation integrity, project health, and draft enhancement specs
+argument-hint: <target-directory> [--enhancements] [--repair]
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+<objective>
+Audit a directory where PAN Wizard was installed and a project was run. Verify installation integrity, validate project artifacts, assess workflow execution quality, and optionally produce a featureAI-format enhancement spec that superplan.md can consume for development planning.
+</objective>
+
+<execution_context>
+This command operates on a TARGET directory (not the PAN source repo). The target must be provided as the first argument.
+</execution_context>
+
+<process>
+
+<step name="parse_args">
+**Parse arguments:**
+
+Extract target directory path from the first argument. It is REQUIRED.
+
+```
+TARGET_DIR = first positional argument
+ENHANCEMENTS_FLAG = "--enhancements" present?
+REPAIR_FLAG = "--repair" present?
+```
+
+If no target directory is provided, ask the user:
+> Which directory should I audit? Provide the full path to the folder where PAN Wizard was installed and a project was run.
+
+Validate the directory exists before proceeding.
+</step>
+
+<step name="installation_audit">
+**Phase 1 — Installation Integrity Audit**
+
+Check the PAN Wizard installation artifacts in the target directory. Determine which runtime was used (Claude, Gemini, OpenCode, Codex, Copilot) by checking for config directories:
+
+```
+Claude:   <target>/.claude/
+Gemini:   <target>/.gemini/
+OpenCode: <target>/.opencode/
+Codex:    <target>/.codex/
+Copilot:  <target>/.copilot/ (or ~/.copilot/)
+GitHub:   <target>/.github/
+```
+
+For the detected runtime config directory (CONFIG_DIR), audit ALL of the following:
+
+**1.1 Core Files (CRITICAL)**
+- [ ] `CONFIG_DIR/pan-wizard-core/VERSION` exists — read and record version
+- [ ] `CONFIG_DIR/pan-wizard-core/CHANGELOG.md` exists
+- [ ] `CONFIG_DIR/pan-file-manifest.json` exists — parse and validate JSON
+- [ ] `CONFIG_DIR/package.json` exists — should contain `{"type":"commonjs"}`
+
+**1.2 Core Modules**
+- [ ] `CONFIG_DIR/pan-wizard-core/bin/pan-tools.cjs` exists (CLI dispatcher)
+- [ ] `CONFIG_DIR/pan-wizard-core/bin/lib/` directory exists
+- Count all `.cjs` files in `bin/lib/` — expect 14-16 modules
+
+**1.3 Workflows, Templates, References**
+- [ ] `CONFIG_DIR/pan-wizard-core/workflows/` — count files, expect 25+
+- [ ] `CONFIG_DIR/pan-wizard-core/templates/` — count files, expect 20+
+- [ ] `CONFIG_DIR/pan-wizard-core/references/` — count files, expect 10+
+
+**1.4 Commands**
+- For Claude/Gemini: `CONFIG_DIR/commands/pan/` — count `.md` files, expect 35+
+- For OpenCode: `CONFIG_DIR/command/` — count `pan-*.md` files
+- For Codex/Copilot: `CONFIG_DIR/skills/pan-*/SKILL.md` — count skill directories
+
+**1.5 Agents**
+- [ ] `CONFIG_DIR/agents/` — count agent files, expect 12
+- Verify key agents exist: pan-planner, pan-executor, pan-verifier, pan-debugger
+
+**1.6 Hooks**
+- [ ] `CONFIG_DIR/hooks/pan-statusline.js` exists
+- [ ] `CONFIG_DIR/hooks/pan-check-update.js` exists
+- [ ] `CONFIG_DIR/hooks/pan-context-monitor.js` exists
+
+**1.7 Settings/Config**
+- [ ] Settings file exists (settings.json / opencode.json / config.json)
+- [ ] Hooks are registered in settings (SessionStart, PostToolUse, statusLine)
+- [ ] Hook commands point to existing files
+
+**1.8 Manifest Integrity**
+- Read `pan-file-manifest.json`
+- For each file in the manifest, verify it exists on disk
+- Flag any MISSING files (manifest says exists, disk says no)
+- Flag any MODIFIED files (hash mismatch) — these are user customizations, not errors
+- Flag any ORPHANED files (on disk but not in manifest)
+
+Record all findings with severity: CRITICAL (missing core), WARNING (missing optional), INFO (modifications).
+</step>
+
+<step name="project_audit">
+**Phase 2 — Project Artifacts Audit**
+
+Check `.planning/` directory in the target:
+
+**2.1 Core Planning Files**
+- [ ] `.planning/config.json` — exists, valid JSON, has required keys (mode, depth, model_profile, workflow)
+- [ ] `.planning/project.md` — exists, has "What This Is", "Core Value", "Requirements" sections
+- [ ] `.planning/state.md` — exists, has "Current Position", "Performance Metrics" sections
+- [ ] `.planning/roadmap.md` — exists, has phase table
+- [ ] `.planning/requirements.md` — exists if project used requirements tracking
+
+**2.2 Phase Directories**
+- Scan for `phase_*` or `*-*` numbered directories
+- For each phase directory:
+  - [ ] PLAN.md exists (phase summary)
+  - [ ] At least one plan_*.md file exists
+  - [ ] verification.md exists (phase was verified)
+- Count: total phases, phases with plans, phases verified, phases with gaps
+
+**2.3 Research Artifacts** (if brownfield/research was enabled)
+- [ ] `.planning/research/` directory exists
+- Check for stack.md, features.md, architecture.md, pitfalls.md
+- [ ] `.planning/codebase/` directory exists (brownfield)
+
+**2.4 State Consistency**
+- Parse state.md "Current Position" — extract phase number
+- Count actual phase directories — do they match?
+- Check roadmap.md phase count vs actual directories
+- Verify no orphaned .continue-here-*.md files (paused but not resumed)
+
+**2.5 Config Sanity**
+- Validate config.json values are within expected ranges
+- mode: "yolo" | "interactive"
+- depth: "quick" | "standard" | "comprehensive"
+- model_profile: "quality" | "balanced" | "budget"
+- workflow agents: all boolean
+</step>
+
+<step name="workflow_quality_audit">
+**Phase 3 — Workflow Execution Quality**
+
+Assess how well the project workflow was followed:
+
+**3.1 Planning Quality**
+For each phase with a PLAN.md:
+- Does it have clear objectives?
+- Does it reference requirements?
+- Are plans sequential with dependencies noted?
+- Grade: Complete / Partial / Stub
+
+**3.2 Verification Coverage**
+- Count phases with verification.md vs total phases
+- Check if verifications have pass/fail outcomes
+- Flag phases that were executed but never verified
+
+**3.3 Commit History** (if git repo)
+- Check if `.planning/` is tracked in git (config.json commit_docs)
+- Look for atomic commit patterns (one commit per plan)
+- Check for PAN-style commit messages
+
+**3.4 Session Continuity**
+- Check for .continue-here-*.md files (indicates paused sessions)
+- Check state.md session logs for gaps
+- Look for evidence of context loss (repeated work, contradictory decisions)
+
+**3.5 Todo Management**
+- Check `.planning/todos/` directory
+- Count pending vs completed
+- Flag stale todos (captured but never addressed)
+</step>
+
+<step name="report">
+**Phase 4 — Generate Audit Report**
+
+Format findings as a structured report:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PAN Deployment Audit
+ Target: <target-directory>
+ Date: <YYYY-MM-DD>
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+## Summary
+
+| Category               | Status   | Score |
+|------------------------|----------|-------|
+| Installation Integrity | ✓/⚠/✗   | N/N   |
+| Project Artifacts      | ✓/⚠/✗   | N/N   |
+| Workflow Quality        | ✓/⚠/✗   | N/N   |
+| Overall                | HEALTHY / DEGRADED / BROKEN | N% |
+
+Runtime: <detected runtime>
+PAN Version: <version from VERSION file>
+Phases: <completed>/<total>
+Verification Coverage: <N>%
+
+## Installation Integrity
+
+### Critical Issues
+- [I-C01] <description> — <fix>
+
+### Warnings
+- [I-W01] <description> — <suggestion>
+
+### Info
+- [I-I01] <description>
+
+### Modified Files (User Customizations)
+- <file> — hash mismatch (expected: abc..., actual: def...)
+
+## Project Artifacts
+
+### Critical Issues
+- [P-C01] <description> — <fix>
+
+### Warnings
+- [P-W01] <description> — <suggestion>
+
+### Phase Health
+| Phase | PLAN.md | Plans | Verified | Status |
+|-------|---------|-------|----------|--------|
+| 01    | ✓       | 3     | ✓        | Complete |
+| 02    | ✓       | 5     | ✗        | Unverified |
+
+## Workflow Quality
+
+### Observations
+- Planning quality: <grade>
+- Verification coverage: <N>%
+- Commit discipline: <grade>
+- Session continuity: <grade>
+
+### Recommendations
+1. <actionable recommendation>
+2. <actionable recommendation>
+```
+
+If `--repair` flag was provided, attempt auto-fixes for repairable issues:
+- Regenerate missing settings.json with default hook config
+- Create missing .planning/config.json with defaults
+- Remove orphaned .continue-here-*.md files
+
+Report repairs performed.
+</step>
+
+<step name="enhancements">
+**Phase 5 — Enhancement Spec Generation** (only if `--enhancements` flag)
+
+Based on audit findings, generate a featureAI-format enhancement spec at `docs/specs/deployment_audit_findings_featureai.md` in the PAN SOURCE repository (NOT the target directory).
+
+The spec MUST follow this exact format to be consumable by superplan.md:
+
+```markdown
+# [Enhancement Title] — Feature Specification
+
+**Generated:** <YYYY-MM-DD>
+**Version:** 1.0
+**Status:** Proposed
+**Source:** Deployment audit of <target-directory>
+
+---
+
+## Problem Statement
+
+[Describe the problems discovered during the audit. What is broken, missing, or suboptimal in PAN Wizard based on real-world deployment evidence?]
+
+## Demand Evidence
+
+| Evidence Type | Source | Finding |
+|---|---|---|
+| Deployment audit | <target-dir> | <specific finding> |
+| ... | ... | ... |
+
+## Success Criteria
+
+```
+SC-1: <measurable criterion>
+SC-2: <measurable criterion>
+```
+
+## Design
+
+[Proposed changes to PAN Wizard to address the findings]
+
+### Architecture
+
+[How the fix/enhancement integrates with existing PAN architecture]
+
+## Feature Ladder
+
+| Version | Scope | Value | Effort |
+|---|---|---|---|
+| **v0 (MVP)** | <scope> | <value> | <effort> |
+| **v1** | <scope> | <value> | <effort> |
+
+## Implementation Tasks
+
+| # | ID | Title | Files | Effort | Pts | Priority |
+|---|---|---|---|---|---|---|
+| 1 | A.1 | <task> | <files> | S/M/L | N | P1-P4 |
+
+### Dependency Graph
+
+```
+A.1 ──> A.2 ──> A.3
+```
+
+## Test Plan
+
+| Level | Count | What It Catches |
+|---|---|---|
+| Unit | N+ | <description> |
+| Integration | N+ | <description> |
+
+## Risk Register
+
+| Risk | Probability | Impact | Mitigation |
+|---|---|---|---|
+| <risk> | Low/Med/High | Low/Med/High | <mitigation> |
+
+---
+
+*Generated by /pan:audit-deployment — <YYYY-MM-DD>*
+```
+
+Group findings into logical enhancement categories:
+1. **Installer gaps** — Missing files, broken hooks, manifest issues
+2. **Workflow gaps** — Missing verification, planning quality
+3. **Template gaps** — Templates that don't match real-world needs
+4. **Documentation gaps** — Unclear processes discovered during audit
+5. **Tooling gaps** — Features PAN should have but doesn't
+
+For each category with findings, generate a separate featureAI spec OR consolidate into one spec if findings are cohesive.
+
+Ask the user before writing specs:
+> The audit found N enhancement opportunities across M categories. Should I generate featureAI specs for superplan.md to plan development? [Yes/No]
+</step>
+
+<step name="final_summary">
+**Final Summary**
+
+Display a concise summary:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ Audit Complete
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Score: N% (HEALTHY / DEGRADED / BROKEN)
+Critical: N | Warnings: N | Info: N
+
+Installation: <status>
+Project: <status>
+Workflow: <status>
+
+Enhancements drafted: N specs → docs/specs/
+```
+
+If enhancements were generated:
+> Enhancement specs written. Run superplan.md or /pan:milestone-new to plan development work.
+
+If repairs were performed:
+> N issues auto-repaired. Re-run /pan:audit-deployment to verify.
+</step>
+
+</process>
+
+<constraints>
+- NEVER modify the target directory's .planning/ content unless --repair is explicitly passed
+- NEVER modify the target directory's PAN installation files (read-only audit)
+- Enhancement specs are written to the PAN SOURCE repo docs/specs/, NOT the target directory
+- If the target directory IS the PAN source repo, refuse with: "Cannot audit the PAN source repository. Use a separate deployment directory."
+- All file reads are defensive — missing files are findings, not crashes
+- Do not expose file hashes, absolute paths, or credentials in the report
+</constraints>

package/commands/pan/debug.md

@@ -0,0 +1,168 @@
+---
+name: pan:debug
+group: System
+description: Systematic debugging with persistent state across context resets
+argument-hint: [issue description]
+allowed-tools:
+  - Read
+  - Bash
+  - Task
+  - AskUserQuestion
+---
+
+<objective>
+Debug issues using scientific method with subagent isolation.
+
+**Orchestrator role:** Gather symptoms, spawn pan-debugger agent, handle checkpoints, spawn continuations.
+
+**Why subagent:** Investigation burns context fast (reading files, forming hypotheses, testing). Fresh 200k context per investigation. Main context stays lean for user interaction.
+</objective>
+
+<context>
+User's issue: $ARGUMENTS
+
+Check for active sessions:
+```bash
+ls .planning/debug/*.md 2>/dev/null | grep -v resolved | head -5
+```
+</context>
+
+<process>
+
+## 0. Initialize Context
+
+```bash
+INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state load)
+```
+
+Extract `commit_docs` from init JSON. Resolve debugger model:
+```bash
+DEBUGGER_MODEL=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs resolve-model pan-debugger --raw)
+```
+
+## 1. Check Active Sessions
+
+If active sessions exist AND no $ARGUMENTS:
+- List sessions with status, hypothesis, next action
+- User picks number to resume OR describes new issue
+
+If $ARGUMENTS provided OR user describes new issue:
+- Continue to symptom gathering
+
+## 2. Gather Symptoms (if new issue)
+
+Use AskUserQuestion for each:
+
+1. **Expected behavior** - What should happen?
+2. **Actual behavior** - What happens instead?
+3. **Error messages** - Any errors? (paste or describe)
+4. **Timeline** - When did this start? Ever worked?
+5. **Reproduction** - How do you trigger it?
+
+After all gathered, confirm ready to investigate.
+
+## 3. Spawn pan-debugger Agent
+
+Fill prompt and spawn:
+
+```markdown
+<objective>
+Investigate issue: {slug}
+
+**Summary:** {trigger}
+</objective>
+
+<symptoms>
+expected: {expected}
+actual: {actual}
+errors: {errors}
+reproduction: {reproduction}
+timeline: {timeline}
+</symptoms>
+
+<mode>
+symptoms_prefilled: true
+goal: find_and_fix
+</mode>
+
+<debug_file>
+Create: .planning/debug/{slug}.md
+</debug_file>
+```
+
+```
+Task(
+  prompt=filled_prompt,
+  subagent_type="pan-debugger",
+  model="{debugger_model}",
+  description="Debug {slug}"
+)
+```
+
+## 4. Handle Agent Return
+
+**If `## ROOT CAUSE FOUND`:**
+- Display root cause and evidence summary
+- Offer options:
+  - "Fix now" - spawn fix subagent
+  - "Plan fix" - suggest /pan:plan-phase --gaps
+  - "Manual fix" - done
+
+**If `## CHECKPOINT REACHED`:**
+- Present checkpoint details to user
+- Get user response
+- If checkpoint type is `human-verify`:
+  - If user confirms fixed: continue so agent can finalize/resolve/archive
+  - If user reports issues: continue so agent returns to investigation/fixing
+- Spawn continuation agent (see step 5)
+
+**If `## INVESTIGATION INCONCLUSIVE`:**
+- Show what was checked and eliminated
+- Offer options:
+  - "Continue investigating" - spawn new agent with additional context
+  - "Manual investigation" - done
+  - "Add more context" - gather more symptoms, spawn again
+
+## 5. Spawn Continuation Agent (After Checkpoint)
+
+When user responds to checkpoint, spawn fresh agent:
+
+```markdown
+<objective>
+Continue debugging {slug}. Evidence is in the debug file.
+</objective>
+
+<prior_state>
+<files_to_read>
+- .planning/debug/{slug}.md (Debug session state)
+</files_to_read>
+</prior_state>
+
+<checkpoint_response>
+**Type:** {checkpoint_type}
+**Response:** {user_response}
+</checkpoint_response>
+
+<mode>
+goal: find_and_fix
+</mode>
+```
+
+```
+Task(
+  prompt=continuation_prompt,
+  subagent_type="pan-debugger",
+  model="{debugger_model}",
+  description="Continue debug {slug}"
+)
+```
+
+</process>
+
+<success_criteria>
+- [ ] Active sessions checked
+- [ ] Symptoms gathered (if new)
+- [ ] pan-debugger spawned with context
+- [ ] Checkpoints handled correctly
+- [ ] Root cause confirmed before fixing
+</success_criteria>

package/commands/pan/discord.md

@@ -0,0 +1,19 @@
+---
+name: pan:discord
+group: Community
+description: Join the PAN Discord community
+---
+
+<objective>
+Display the Discord invite link for the PAN community server.
+</objective>
+
+<output>
+# Join the PAN Discord
+
+Connect with other PAN users, get help, share what you're building, and stay updated.
+
+**Invite link:** https://discord.gg/pan-wizard
+
+Click the link or paste it into your browser to join.
+</output>