pan-wizard 2.8.1

package/commands/pan/focus-sync.md

@@ -0,0 +1,104 @@
+---
+name: focus-sync
+group: Focus
+description: Synchronize documentation after changes — check staleness and update counts
+allowed-tools:
+  - Read
+  - Bash
+  - Grep
+  - Glob
+  - Edit
+  - Write
+---
+
+# /pan:focus-sync — Documentation Synchronization
+
+Synchronize project documentation across all files. $ARGUMENTS
+
+**Goal:** Detect stale documentation (wrong counts, missing commands, outdated references) and optionally fix it. Documentation should reflect the actual codebase at all times.
+
+---
+
+## CRITICAL: Project Scope Boundary
+
+This command synchronizes the **host project's documentation** — NOT PAN Wizard's own infrastructure files.
+
+**NEVER sync, modify, or report staleness in these PAN directories:**
+- `.claude/`, `.github/copilot-instructions.md`, `.opencode/`, `.gemini/`, `.codex/` — PAN runtime directories
+- Any `pan-wizard-core/`, `pan-tools`, agent `.md`, or command `.md` files within PAN runtime directories
+
+**These directories are PAN's own tooling.** Documentation sync applies to the project's README, docs, guides, and code comments — not to PAN's installed agents or command definitions.
+
+---
+
+## Usage
+
+```
+/pan:focus-sync                  # Full sync check: report staleness
+/pan:focus-sync --readme         # Check README.md only
+/pan:focus-sync --docs           # Verify documentation matches implementations
+/pan:focus-sync --arch           # Verify architecture docs match actual structure
+/pan:focus-sync --all            # Full sync of everything + auto-fix
+```
+
+---
+
+## Sync Operations
+
+### README Sync
+1. Read `README.md`
+2. Cross-reference with `package.json` (or equivalent) for version, description
+3. Verify counts mentioned in README match actual project artifacts (e.g., source modules, API endpoints, components, commands)
+4. Update any stale counts or descriptions
+
+### Documentation Sync
+1. Read the project's primary documentation files (e.g., docs/, wiki, guides)
+2. Verify all public features/APIs are documented
+3. Verify descriptions match actual implementations
+4. Flag any missing or outdated entries
+
+### Source-to-Docs Cross-Reference
+1. List the project's main source modules/components
+2. Cross-reference with documentation references
+3. Verify each documented feature has a corresponding implementation
+4. Report orphaned documentation or undocumented features
+
+### Architecture Sync
+1. Read architecture documentation (if it exists)
+2. Verify component/module/service counts match actual
+3. Verify described patterns match implemented patterns
+4. Flag structural drift
+
+### CHANGELOG Sync
+1. Verify latest version entry matches `package.json` (or equivalent) version
+2. Check all recent features are documented
+
+---
+
+## Source of Truth Hierarchy
+
+```
+package.json              <- Version, description, entry points
+  |
+README.md                 <- Public documentation
+  |
+docs/USER-GUIDE.md        <- Detailed user guide
+  |
+CHANGELOG.md              <- Version history
+```
+
+---
+
+## Report
+
+Output via `pan-tools focus sync`:
+
+```
+| Area | Status | Finding |
+|------|--------|---------|
+| README | stale | Components: documented 12, actual 15 |
+| Docs | stale | Missing 3 recently added features |
+| Architecture | stale | Modules: documented 8, actual 10 |
+| CHANGELOG | current | Version matches |
+| Source-Docs | current | All features documented |
+```

package/commands/pan/health.md

@@ -0,0 +1,23 @@
+---
+name: pan:health
+group: System
+description: Diagnose planning directory health and optionally repair issues
+argument-hint: [--repair]
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - AskUserQuestion
+---
+<objective>
+Validate `.planning/` directory integrity and report actionable issues. Checks for missing files, invalid configurations, inconsistent state, and orphaned plans.
+</objective>
+
+<execution_context>
+@~/.claude/pan-wizard-core/workflows/health.md
+</execution_context>
+
+<process>
+Execute the health workflow from @~/.claude/pan-wizard-core/workflows/health.md end-to-end.
+Parse --repair flag from arguments and pass to workflow.
+</process>

package/commands/pan/help.md

@@ -0,0 +1,23 @@
+---
+name: pan:help
+group: System
+description: Show available PAN commands and usage guide
+---
+<objective>
+Display the complete PAN command reference.
+
+Output ONLY the reference content below. Do NOT add:
+- Project-specific analysis
+- Git status or file context
+- Next-step suggestions
+- Any commentary beyond the reference
+</objective>
+
+<execution_context>
+@~/.claude/pan-wizard-core/workflows/help.md
+</execution_context>
+
+<process>
+Output the complete PAN command reference from @~/.claude/pan-wizard-core/workflows/help.md.
+Display the reference content directly — no additions or modifications.
+</process>

package/commands/pan/insert-phase.md

@@ -0,0 +1,33 @@
+---
+name: pan:insert-phase
+group: Phase Management
+description: Insert urgent work as decimal phase (e.g., 72.1) between existing phases
+argument-hint: <after> <description>
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+Insert a decimal phase for urgent work discovered mid-milestone that must be completed between existing integer phases.
+
+Uses decimal numbering (72.1, 72.2, etc.) to preserve the logical sequence of planned phases while accommodating urgent insertions.
+
+Purpose: Handle urgent work discovered during execution without renumbering entire roadmap.
+</objective>
+
+<execution_context>
+@~/.claude/pan-wizard-core/workflows/insert-phase.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (format: <after-phase-number> <description>)
+
+Roadmap and state are resolved in-workflow via `init phase-op` and targeted tool calls.
+</context>
+
+<process>
+Execute the insert-phase workflow from @~/.claude/pan-wizard-core/workflows/insert-phase.md end-to-end.
+Preserve all validation gates (argument parsing, phase verification, decimal calculation, roadmap updates).
+</process>

package/commands/pan/map-codebase.md

@@ -0,0 +1,72 @@
+---
+name: pan:map-codebase
+group: Getting Started
+description: Analyze codebase with parallel mapper agents to produce .planning/codebase/ documents
+argument-hint: "[optional: specific area to map, e.g., 'api' or 'auth']"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - Task
+---
+
+<objective>
+Analyze existing codebase using parallel pan-document_code agents to produce structured codebase documents.
+
+Each mapper agent explores a focus area and **writes documents directly** to `.planning/codebase/`. The orchestrator only receives confirmations, keeping context usage minimal.
+
+Output: .planning/codebase/ folder with 7 structured documents about the codebase state.
+</objective>
+
+<execution_context>
+@~/.claude/pan-wizard-core/workflows/map-codebase.md
+</execution_context>
+
+<context>
+Focus area: $ARGUMENTS (optional - if provided, tells agents to focus on specific subsystem)
+
+**Load project state if exists:**
+Check for .planning/state.md - loads context if project already initialized
+
+**This command can run:**
+- Before /pan:new-project (brownfield codebases) - creates codebase map first
+- After /pan:new-project (greenfield codebases) - updates codebase map as code evolves
+- Anytime to refresh codebase understanding
+</context>
+
+<when_to_use>
+**Use map-codebase for:**
+- Brownfield projects before initialization (understand existing code first)
+- Refreshing codebase map after significant changes
+- Onboarding to an unfamiliar codebase
+- Before major refactoring (understand current state)
+- When state.md references outdated codebase info
+
+**Skip map-codebase for:**
+- Greenfield projects with no code yet (nothing to map)
+- Trivial codebases (<5 files)
+</when_to_use>
+
+<process>
+1. Check if .planning/codebase/ already exists (offer to refresh or skip)
+2. Create .planning/codebase/ directory structure
+3. Spawn 4 parallel pan-document_code agents:
+   - Agent 1: tech focus → writes STACK.md, INTEGRATIONS.md
+   - Agent 2: arch focus → writes ARCHITECTURE.md, STRUCTURE.md
+   - Agent 3: quality focus → writes CONVENTIONS.md, TESTING.md
+   - Agent 4: concerns focus → writes CONCERNS.md
+4. Wait for agents to complete, collect confirmations (NOT document contents)
+5. Verify all 7 documents exist with line counts
+6. Commit codebase map
+7. Offer next steps (typically: /pan:new-project or /pan:plan-phase)
+</process>
+
+<success_criteria>
+- [ ] .planning/codebase/ directory created
+- [ ] All 7 codebase documents written by mapper agents
+- [ ] Documents follow template structure
+- [ ] Parallel agents completed without errors
+- [ ] User knows next steps
+</success_criteria>

package/commands/pan/milestone-audit.md

@@ -0,0 +1,37 @@
+---
+name: pan:milestone-audit
+group: Milestone
+description: Audit milestone completion against original intent before archiving
+argument-hint: "[version]"
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+  - Task
+  - Write
+---
+<objective>
+Verify milestone achieved its definition of done. Check requirements coverage, cross-phase integration, and end-to-end flows.
+
+**This command IS the orchestrator.** Reads existing verification.md files (phases already verified during execute-phase), aggregates tech debt and deferred gaps, then spawns integration checker for cross-phase wiring.
+</objective>
+
+<execution_context>
+@~/.claude/pan-wizard-core/workflows/milestone-audit.md
+</execution_context>
+
+<context>
+Version: $ARGUMENTS (optional — defaults to current milestone)
+
+Core planning files are resolved in-workflow (`init milestone-op`) and loaded only as needed.
+
+**Completed Work:**
+Glob: .planning/phases/*/*-summary.md
+Glob: .planning/phases/*/*-verification.md
+</context>
+
+<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).
+</process>

package/commands/pan/milestone-cleanup.md

@@ -0,0 +1,19 @@
+---
+name: pan:milestone-cleanup
+group: Milestone
+description: Archive accumulated phase directories from completed milestones
+---
+<objective>
+Archive phase directories from completed milestones into `.planning/milestones/v{X.Y}-phases/`.
+
+Use when `.planning/phases/` has accumulated directories from past milestones.
+</objective>
+
+<execution_context>
+@~/.claude/pan-wizard-core/workflows/milestone-cleanup.md
+</execution_context>
+
+<process>
+Follow the cleanup workflow at @~/.claude/pan-wizard-core/workflows/milestone-cleanup.md.
+Identify completed milestones, show a dry-run summary, and archive on confirmation.
+</process>

package/commands/pan/milestone-done.md

@@ -0,0 +1,137 @@
+---
+type: prompt
+name: pan:milestone-done
+group: Milestone
+description: Archive completed milestone and prepare for next version
+argument-hint: <version>
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+Mark milestone {{version}} complete, archive to milestones/, and update roadmap.md and requirements.md.
+
+Purpose: Create historical record of shipped version, archive milestone artifacts (roadmap + requirements), and prepare for next milestone.
+Output: Milestone archived (roadmap + requirements), project.md evolved, git tagged.
+</objective>
+
+<execution_context>
+**Load these files NOW (before proceeding):**
+
+- @~/.claude/pan-wizard-core/workflows/milestone-done.md (main workflow)
+- @~/.claude/pan-wizard-core/templates/milestone-archive.md (archive template)
+  </execution_context>
+
+<context>
+**Project files:**
+- `.planning/roadmap.md`
+- `.planning/requirements.md`
+- `.planning/state.md`
+- `.planning/project.md`
+
+**User input:**
+
+- Version: {{version}} (e.g., "1.0", "1.1", "2.0")
+  </context>
+
+<process>
+
+**Follow milestone-done.md workflow:**
+
+0. **Check for audit:**
+
+   - Look for `.planning/v{{version}}-milestone-audit.md`
+   - If missing or stale: recommend `/pan:milestone-audit` first
+   - If audit status is `gaps_found`: recommend `/pan:milestone-gaps` first
+   - If audit status is `passed`: proceed to step 1
+
+   ```markdown
+   ## Pre-flight Check
+
+   {If no v{{version}}-milestone-audit.md:}
+   ⚠ No milestone audit found. Run `/pan:milestone-audit` first to verify
+   requirements coverage, cross-phase integration, and E2E flows.
+
+   {If audit has gaps:}
+   ⚠ Milestone audit found gaps. Run `/pan:milestone-gaps` to create
+   phases that close the gaps, or proceed anyway to accept as tech debt.
+
+   {If audit passed:}
+   ✓ Milestone audit passed. Proceeding with completion.
+   ```
+
+1. **Verify readiness:**
+
+   - Check all phases in milestone have completed plans (summary.md exists)
+   - Present milestone scope and stats
+   - Wait for confirmation
+
+2. **Gather stats:**
+
+   - Count phases, plans, tasks
+   - Calculate git range, file changes, LOC
+   - Extract timeline from git log
+   - Present summary, confirm
+
+3. **Extract accomplishments:**
+
+   - Read all phase summary.md files in milestone range
+   - Extract 4-6 key accomplishments
+   - Present for approval
+
+4. **Archive milestone:**
+
+   - Create `.planning/milestones/v{{version}}-roadmap.md`
+   - Extract full phase details from roadmap.md
+   - Fill milestone-archive.md template
+   - Update roadmap.md to one-line summary with link
+
+5. **Archive requirements:**
+
+   - Create `.planning/milestones/v{{version}}-requirements.md`
+   - Mark all v1 requirements as complete (checkboxes checked)
+   - Note requirement outcomes (validated, adjusted, dropped)
+   - Delete `.planning/requirements.md` (fresh one created for next milestone)
+
+6. **Update project.md:**
+
+   - Add "Current State" section with shipped version
+   - Add "Next Milestone Goals" section
+   - Archive previous content in `<details>` (if v1.1+)
+
+7. **Commit and tag:**
+
+   - Stage: milestones.md, project.md, roadmap.md, state.md, archive files
+   - Commit: `chore: archive v{{version}} milestone`
+   - Tag: `git tag -a v{{version}} -m "[milestone summary]"`
+   - Ask about pushing tag
+
+8. **Offer next steps:**
+   - `/pan:milestone-new` — start next milestone (questioning → research → requirements → roadmap)
+
+</process>
+
+<success_criteria>
+
+- Milestone archived to `.planning/milestones/v{{version}}-roadmap.md`
+- Requirements archived to `.planning/milestones/v{{version}}-requirements.md`
+- `.planning/requirements.md` deleted (fresh for next milestone)
+- roadmap.md collapsed to one-line entry
+- project.md updated with current state
+- Git tag v{{version}} created
+- Commit successful
+- User knows next steps (including need for fresh requirements)
+  </success_criteria>
+
+<critical_rules>
+
+- **Load workflow first:** Read milestone-done.md before executing
+- **Verify completion:** All phases must have summary.md files
+- **User confirmation:** Wait for approval at verification gates
+- **Archive before deleting:** Always create archive files before updating/deleting originals
+- **One-line summary:** Collapsed milestone in roadmap.md should be single line with link
+- **Context efficiency:** Archive keeps roadmap.md and requirements.md constant size per milestone
+- **Fresh requirements:** Next milestone starts with `/pan:milestone-new` which includes requirements definition
+  </critical_rules>

package/commands/pan/milestone-gaps.md

@@ -0,0 +1,35 @@
+---
+name: pan:milestone-gaps
+group: Milestone
+description: Create phases to close all gaps identified by milestone audit
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+<objective>
+Create all phases necessary to close gaps identified by `/pan:milestone-audit`.
+
+Reads milestone-audit.md, groups gaps into logical phases, creates phase entries in roadmap.md, and offers to plan each phase.
+
+One command creates all fix phases — no manual `/pan:add-phase` per gap.
+</objective>
+
+<execution_context>
+@~/.claude/pan-wizard-core/workflows/milestone-gaps.md
+</execution_context>
+
+<context>
+**Audit results:**
+Glob: .planning/v*-milestone-audit.md (use most recent)
+
+Original intent and current planning state are loaded on demand inside the workflow.
+</context>
+
+<process>
+Execute the plan-milestone-gaps workflow from @~/.claude/pan-wizard-core/workflows/milestone-gaps.md end-to-end.
+Preserve all workflow gates (audit loading, prioritization, phase grouping, user confirmation, roadmap updates).
+</process>

package/commands/pan/milestone-new.md

@@ -0,0 +1,45 @@
+---
+name: pan:milestone-new
+group: Milestone
+description: Start a new milestone cycle — update project.md and route to requirements
+argument-hint: "[milestone name, e.g., 'v1.1 Notifications']"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Task
+  - AskUserQuestion
+---
+<objective>
+Start a new milestone: questioning → research (optional) → requirements → roadmap.
+
+Brownfield equivalent of new-project. Project exists, project.md has history. Gathers "what's next", updates project.md, then runs requirements → roadmap cycle.
+
+**Creates/Updates:**
+- `.planning/project.md` — updated with new milestone goals
+- `.planning/research/` — domain research (optional, NEW features only)
+- `.planning/requirements.md` — scoped requirements for this milestone
+- `.planning/roadmap.md` — phase structure (continues numbering)
+- `.planning/state.md` — reset for new milestone
+
+**After:** `/pan:plan-phase [N]` to start execution.
+</objective>
+
+<execution_context>
+@~/.claude/pan-wizard-core/workflows/milestone-new.md
+@~/.claude/pan-wizard-core/references/questioning.md
+@~/.claude/pan-wizard-core/references/ui-brand.md
+@~/.claude/pan-wizard-core/templates/project.md
+@~/.claude/pan-wizard-core/templates/requirements.md
+</execution_context>
+
+<context>
+Milestone name: $ARGUMENTS (optional - will prompt if not provided)
+
+Project and milestone context files are resolved inside the workflow (`init new-milestone`) and delegated via `<files_to_read>` blocks where subagents are used.
+</context>
+
+<process>
+Execute the new-milestone workflow from @~/.claude/pan-wizard-core/workflows/milestone-new.md end-to-end.
+Preserve all workflow gates (validation, questioning, research, requirements, roadmap approval, commits).
+</process>

package/commands/pan/new-project.md

@@ -0,0 +1,43 @@
+---
+name: pan:new-project
+group: Getting Started
+description: Initialize a new project with deep context gathering and project.md
+argument-hint: "[--auto]"
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Task
+  - AskUserQuestion
+---
+<context>
+**Flags:**
+- `--auto` — Automatic mode. After config questions, runs research → requirements → roadmap without further interaction. Expects idea document via @ reference.
+</context>
+
+<objective>
+Initialize a new project through unified flow: questioning → research (optional) → requirements → roadmap.
+
+**Creates:**
+- `.planning/project.md` — project context
+- `.planning/config.json` — workflow preferences
+- `.planning/research/` — domain research (optional)
+- `.planning/requirements.md` — scoped requirements
+- `.planning/roadmap.md` — phase structure
+- `.planning/state.md` — project memory
+
+**After this command:** Run `/pan:plan-phase 1` to start execution.
+</objective>
+
+<execution_context>
+@~/.claude/pan-wizard-core/workflows/new-project.md
+@~/.claude/pan-wizard-core/references/questioning.md
+@~/.claude/pan-wizard-core/references/ui-brand.md
+@~/.claude/pan-wizard-core/templates/project.md
+@~/.claude/pan-wizard-core/templates/requirements.md
+</execution_context>
+
+<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).
+</process>

package/commands/pan/patches.md

@@ -0,0 +1,110 @@
+---
+description: Reapply local modifications after a PAN update
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+<purpose>
+After a PAN update wipes and reinstalls files, this command merges user's previously saved local modifications back into the new version. Uses intelligent comparison to handle cases where the upstream file also changed.
+</purpose>
+
+<process>
+
+## Step 1: Detect backed-up patches
+
+Check for local patches directory:
+
+```bash
+# Global install (path templated at install time)
+PATCHES_DIR=~/.claude/pan-local-patches
+# Local install fallback
+if [ ! -d "$PATCHES_DIR" ]; then
+  PATCHES_DIR=./.claude/pan-local-patches
+fi
+```
+
+Read `backup-meta.json` from the patches directory.
+
+**If no patches found:**
+```
+No local patches found. Nothing to reapply.
+
+Local patches are automatically saved when you run /pan:update
+after modifying any PAN workflow, command, or agent files.
+```
+Exit.
+
+## Step 2: Show patch summary
+
+```
+## Local Patches to Reapply
+
+**Backed up from:** v{from_version}
+**Current version:** {read VERSION file}
+**Files modified:** {count}
+
+| # | File | Status |
+|---|------|--------|
+| 1 | {file_path} | Pending |
+| 2 | {file_path} | Pending |
+```
+
+## Step 3: Merge each file
+
+For each file in `backup-meta.json`:
+
+1. **Read the backed-up version** (user's modified copy from `pan-local-patches/`)
+2. **Read the newly installed version** (current file after update)
+3. **Compare and merge:**
+
+   - If the new file is identical to the backed-up file: skip (modification was incorporated upstream)
+   - If the new file differs: identify the user's modifications and apply them to the new version
+
+   **Merge strategy:**
+   - Read both versions fully
+   - Identify sections the user added or modified (look for additions, not just differences from path replacement)
+   - Apply user's additions/modifications to the new version
+   - If a section the user modified was also changed upstream: flag as conflict, show both versions, ask user which to keep
+
+4. **Write merged result** to the installed location
+5. **Report status:**
+   - `Merged` — user modifications applied cleanly
+   - `Skipped` — modification already in upstream
+   - `Conflict` — user chose resolution
+
+## Step 4: Update manifest
+
+After reapplying, regenerate the file manifest so future updates correctly detect these as user modifications:
+
+```bash
+# The manifest will be regenerated on next /pan:update
+# For now, just note which files were modified
+```
+
+## Step 5: Cleanup option
+
+Ask user:
+- "Keep patch backups for reference?" → preserve `pan-local-patches/`
+- "Clean up patch backups?" → remove `pan-local-patches/` directory
+
+## Step 6: Report
+
+```
+## Patches Reapplied
+
+| # | File | Status |
+|---|------|--------|
+| 1 | {file_path} | ✓ Merged |
+| 2 | {file_path} | ○ Skipped (already upstream) |
+| 3 | {file_path} | ⚠ Conflict resolved |
+
+{count} file(s) updated. Your local modifications are active again.
+```
+
+</process>
+
+<success_criteria>
+- [ ] All backed-up patches processed
+- [ ] User modifications merged into new version
+- [ ] Conflicts resolved with user input
+- [ ] Status reported for each file
+</success_criteria>