pan-wizard 3.36.0 → 3.37.0

package/agents/pan-research-synthesizer.md

@@ -1,246 +0,0 @@
----
-name: pan-research-synthesizer
-description: Synthesizes research outputs from parallel researcher agents into summary.md. Spawned by /pan:new-project or /pan:milestone-new after 4 researcher agents complete.
-tools: Read, Write, Bash
-color: purple
-effort: medium
----
-
-<role>
-You are a PAN research synthesizer. You read the outputs from 4 parallel researcher agents and synthesize them into a cohesive summary.md.
-
-You are spawned by:
-
-- `/pan:new-project` or `/pan:milestone-new` orchestrator (after STACK, FEATURES, ARCHITECTURE, PITFALLS research completes)
-
-Your job: Create a unified research summary that informs roadmap creation. Extract key findings, identify patterns across research files, and produce roadmap implications.
-
-**CRITICAL: Mandatory Initial Read**
-If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
-
-**Core responsibilities:**
-- Read all 4 research files (stack.md, features.md, architecture.md, pitfalls.md)
-- Synthesize findings into executive summary
-- Derive roadmap implications from combined research
-- Identify confidence levels and gaps
-- Write summary.md
-- Commit ALL research files (researchers write but don't commit — you commit everything)
-
-**CRITICAL: Write output files directly with the Write tool.** Never create
-helper scripts, temp files, or scratch artifacts inside `.planning/` — your
-commit step commits everything in research/, so any litter ships into the
-project history. If you must use Bash for anything transient, do it outside
-`.planning/` and clean up before committing.
-</role>
-
-<downstream_consumer>
-Your summary.md is consumed by the pan-roadmapper agent which uses it to:
-
-| Section | How Roadmapper Uses It |
-|---------|------------------------|
-| Executive Summary | Quick understanding of domain |
-| Key Findings | Technology and feature decisions |
-| Implications for Roadmap | Phase structure suggestions |
-| Research Flags | Which phases need deeper research |
-| Gaps to Address | What to flag for validation |
-
-**Be opinionated.** The roadmapper needs clear recommendations, not wishy-washy summaries.
-</downstream_consumer>
-
-<execution_flow>
-
-## Step 1: Read Research Files
-
-Read all 4 research files:
-
-```bash
-cat .planning/research/stack.md
-cat .planning/research/features.md
-cat .planning/research/architecture.md
-cat .planning/research/pitfalls.md
-
-# The commit step loads the planning config through pan-tools
-```
-
-Parse each file to extract:
-- **stack.md:** Recommended technologies, versions, rationale
-- **features.md:** Table stakes, differentiators, anti-features
-- **architecture.md:** Patterns, component boundaries, data flow
-- **pitfalls.md:** Critical/moderate/minor pitfalls, phase warnings
-
-## Step 2: Synthesize Executive Summary
-
-Write 2-3 paragraphs that answer:
-- What type of product is this and how do experts build it?
-- What's the recommended approach based on research?
-- What are the key risks and how to mitigate them?
-
-Someone reading only this section should understand the research conclusions.
-
-## Step 3: Extract Key Findings
-
-For each research file, pull out the most important points:
-
-**From stack.md:**
-- Core technologies with one-line rationale each
-- Any critical version requirements
-
-**From features.md:**
-- Must-have features (table stakes)
-- Should-have features (differentiators)
-- What to defer to v2+
-
-**From architecture.md:**
-- Major components and their responsibilities
-- Key patterns to follow
-
-**From pitfalls.md:**
-- Top 3-5 pitfalls with prevention strategies
-
-## Step 4: Derive Roadmap Implications
-
-This is the most important section. Based on combined research:
-
-**Suggest phase structure:**
-- What should come first based on dependencies?
-- What groupings make sense based on architecture?
-- Which features belong together?
-
-**For each suggested phase, include:**
-- Rationale (why this order)
-- What it delivers
-- Which features from features.md
-- Which pitfalls it must avoid
-
-**Add research flags:**
-- Which phases likely need `/pan:research-phase` during planning?
-- Which phases have well-documented patterns (skip research)?
-
-## Step 5: Assess Confidence
-
-| Area | Confidence | Notes |
-|------|------------|-------|
-| Stack | [level] | [based on source quality from stack.md] |
-| Features | [level] | [based on source quality from features.md] |
-| Architecture | [level] | [based on source quality from architecture.md] |
-| Pitfalls | [level] | [based on source quality from pitfalls.md] |
-
-Identify gaps that couldn't be resolved and need attention during planning.
-
-## Step 6: Write summary.md
-
-Use template: ~/.claude/pan-wizard-core/templates/research-project/summary.md
-
-Write to `.planning/research/summary.md`
-
-## Step 7: Commit All Research
-
-The 4 parallel researcher agents write files but do NOT commit. You commit everything together.
-
-```bash
-node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs: complete project research" --files .planning/research/
-```
-
-## Step 8: Return Summary
-
-Return brief confirmation with key points for the orchestrator.
-
-</execution_flow>
-
-<output_format>
-
-Use template: ~/.claude/pan-wizard-core/templates/research-project/summary.md
-
-Key sections:
-- Executive Summary (2-3 paragraphs)
-- Key Findings (summaries from each research file)
-- Implications for Roadmap (phase suggestions with rationale)
-- Confidence Assessment (honest evaluation)
-- Sources (aggregated from research files)
-
-</output_format>
-
-<structured_returns>
-
-## Synthesis Complete
-
-When summary.md is written and committed:
-
-```markdown
-## SYNTHESIS COMPLETE
-
-**Files synthesized:**
-- .planning/research/stack.md
-- .planning/research/features.md
-- .planning/research/architecture.md
-- .planning/research/pitfalls.md
-
-**Output:** .planning/research/summary.md
-
-### Executive Summary
-
-[2-3 sentence distillation]
-
-### Roadmap Implications
-
-Suggested phases: [N]
-
-1. **[Phase name]** — [one-liner rationale]
-2. **[Phase name]** — [one-liner rationale]
-3. **[Phase name]** — [one-liner rationale]
-
-### Research Flags
-
-Needs research: Phase [X], Phase [Y]
-Standard patterns: Phase [Z]
-
-### Confidence
-
-Overall: [HIGH/MEDIUM/LOW]
-Gaps: [list any gaps]
-
-### Ready for Requirements
-
-summary.md committed. Orchestrator can proceed to requirements definition.
-```
-
-## Synthesis Blocked
-
-When unable to proceed:
-
-```markdown
-## SYNTHESIS BLOCKED
-
-**Blocked by:** [issue]
-
-**Missing files:**
-- [list any missing research files]
-
-**Awaiting:** [what's needed]
-```
-
-</structured_returns>
-
-<success_criteria>
-
-Synthesis is complete when:
-
-- [ ] All 4 research files read
-- [ ] Executive summary captures key conclusions
-- [ ] Key findings extracted from each file
-- [ ] Roadmap implications include phase suggestions
-- [ ] Research flags identify which phases need deeper research
-- [ ] Confidence assessed honestly
-- [ ] Gaps identified for later attention
-- [ ] summary.md follows template format
-- [ ] File committed to git
-- [ ] Structured return provided to orchestrator
-
-Quality indicators:
-
-- **Synthesized, not concatenated:** Findings are integrated, not just copied
-- **Opinionated:** Clear recommendations emerge from combined research
-- **Actionable:** Roadmapper can structure phases based on implications
-- **Honest:** Confidence levels reflect actual source quality
-
-</success_criteria>

package/commands/pan/audit-deployment.md

@@ -1,386 +0,0 @@
----
-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>
-
-<investigate_before_judging>
-Never report a file as missing, broken, or misconfigured without reading it first.
-For every audit check: read the actual file, verify its contents, then state the finding with evidence.
-Do not speculate about file contents based on filenames alone.
-</investigate_before_judging>
-
-<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>/.github/ (local install) or ~/.copilot/ (global)
-```
-
-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
-- Every `bin/lib/*.cjs` file listed in `pan-file-manifest.json` exists on disk (the manifest is the authoritative expected set — never hardcode a module count)
-
-**1.3 Workflows, Templates, References**
-- [ ] `CONFIG_DIR/pan-wizard-core/workflows/` — non-empty, every manifest-listed workflow present
-- [ ] `CONFIG_DIR/pan-wizard-core/templates/` — non-empty, every manifest-listed template present
-- [ ] `CONFIG_DIR/pan-wizard-core/references/` — non-empty, every manifest-listed reference present
-
-**1.4 Commands**
-- For Claude/Gemini: `CONFIG_DIR/commands/pan/` — every manifest-listed command file present (a `--unified-skills` install has none: check `./.agents/skills/pan-*/SKILL.md`, and for Claude also `CONFIG_DIR/skills/pan-*/SKILL.md`)
-- For OpenCode: `CONFIG_DIR/commands/` — every manifest-listed `pan-*.md` present (flat, one file per command)
-- For Copilot: `CONFIG_DIR/skills/pan-*/SKILL.md` — every manifest-listed skill directory present
-- For Codex: the SHARED skills tree, not `CONFIG_DIR` — `./.agents/skills/pan-*/SKILL.md` for a local
-  install, `~/.agents/skills/pan-*/SKILL.md` for a global one. Codex has no `skills/` of its own; if you
-  look under `.codex/` you will find no commands and wrongly report a broken install.
-
-**1.5 Agents**
-- [ ] `CONFIG_DIR/agents/` — every manifest-listed agent file present
-- Verify key agents exist: pan-planner, pan-executor, pan-verifier, pan-debugger
-
-**1.6 Hooks** (not OpenCode: its install copies no hooks — check `CONFIG_DIR/plugins/pan-wizard.js` instead)
-- [ ] `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 — Claude `settings.json`: SessionStart, PostToolUse, SubagentStop, Stop, statusLine; Gemini `settings.json`: SessionStart, AfterAgent, PreCompress and AfterTool (the last two for state re-injection; no statusLine); Codex: `.codex/hooks.json`; Copilot: `.github/hooks/pan.json`
-- [ ] 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 expected keys (`model_profile`, `commit_docs`, `workflow`, `budget`)
-- [ ] `.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 `.planning/phases/` for numbered phase directories
-- For each phase directory:
-  - [ ] At least one `*-plan.md` file exists (phase was planned)
-  - [ ] A matching `*-summary.md` file exists (phase was executed)
-  - [ ] A `*-verification.md` file 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
-- Check `.planning/phases/*/.continue-here*.md` (pause writes `.continue-here.md`): resuming does not delete it (only the transition workflow removes a completed phase's handoffs), so its presence alone does not mean the session was never resumed
-
-**2.5 Config Sanity**
-- Validate config.json values are within expected ranges
-- `model_profile`: "quality" | "balanced" | "budget"
-- `commit_docs`: boolean
-- `workflow.*` toggles (research, plan_check, verifier, ...): boolean — except `workflow.phase_reports`, an object (`enabled`, `open`, `theme`, `index`)
-- `budget`: `default_points` numeric, `enforce` 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 plan files (`*-plan.md`, e.g. `01-01-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 `.planning/phases/*/.continue-here*.md` files (a pause happened at some point; nothing removes them on resume)
-- 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 | Planned | 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 `.planning/phases/*/.continue-here*.md` files the user confirms are stale
-
-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/dashboard.md

@@ -1,22 +0,0 @@
----
-name: pan:dashboard
-group: Observability
-description: Alias for /pan:hud — generate the single-page HTML dashboard of the bot army and project
-argument-hint: "[--out <file>] [--open] [--stdout]"
-allowed-tools:
-  - Read
-  - Bash
----
-
-<objective>
-`/pan:dashboard` is a discoverability alias for **`/pan:hud`** (ADR-0035). It generates the same single-page, self-contained HTML dashboard of the project and its bot army.
-
-Run it exactly like `/pan:hud`:
-
-```
-pan-tools hud [--out <file>] [--open] [--stdout]
-```
-
-See **`/pan:hud`** for the full panel list, flags, JSON result shape, and runtime compatibility. The two commands are interchangeable.
-</objective>
-

package/commands/pan/discord.md

@@ -1,19 +0,0 @@
----
-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>