pan-wizard 2.8.1 → 2.9.1

package/pan-wizard-core/references/model-profiles.md

@@ -1,52 +1,142 @@
-# Model Profiles
+# Model Profiles & Routing
 
-Model profiles control which Claude model each PAN agent uses. This allows balancing quality vs token spend.
+Model profiles control which model tier each PAN agent uses. The routing system maps abstract tiers to provider-specific models, allowing PAN to work across Anthropic, OpenAI, and Google providers.
+
+---
+
+## Tier System
+
+PAN uses three abstract tiers instead of hardcoded model names:
+
+| Tier | Purpose | Anthropic | OpenAI | Google |
+|------|---------|-----------|--------|--------|
+| `reasoning` | Architecture, planning, complex decisions | inherit (Opus) | inherit | inherit |
+| `mid` | Execution, research, verification | Sonnet | mid | mid |
+| `fast` | Read-only extraction, budget tasks | Haiku | fast | fast |
+
+**Why `inherit` for reasoning?** Host runtimes map "opus" to a specific model version. PAN returns `inherit` for reasoning-tier agents, so they use whatever top-tier model the user has configured. This avoids version conflicts and silent fallbacks.
+
+### Legacy Aliases
+
+For backward compatibility, legacy Anthropic model names still work:
+
+| Legacy Name | Maps To | Tier |
+|-------------|---------|------|
+| `opus` | `reasoning` | Top-tier |
+| `sonnet` | `mid` | Mid-tier |
+| `haiku` | `fast` | Budget |
+
+---
 
 ## Profile Definitions
 
 | Agent | `quality` | `balanced` | `budget` |
 |-------|-----------|------------|----------|
-| pan-planner | opus | opus | sonnet |
-| pan-roadmapper | opus | sonnet | sonnet |
-| pan-executor | opus | sonnet | sonnet |
-| pan-phase-researcher | opus | sonnet | haiku |
-| pan-project-researcher | opus | sonnet | haiku |
-| pan-research-synthesizer | opus | sonnet | haiku |
-| pan-debugger | opus | sonnet | sonnet |
-| pan-document_code | opus | haiku | haiku |
-| pan-verifier | opus | sonnet | haiku |
-| pan-plan-checker | opus | sonnet | haiku |
-| pan-integration-checker | opus | sonnet | haiku |
-| pan-reviewer | opus | haiku | haiku |
-
-## Profile Philosophy
-
-**quality** - Maximum reasoning power (Opus 4.6 for everything)
-- Opus for ALL agents — no exceptions
-- Use when: quota available, critical architecture work, maximum quality desired
-
-**balanced** (default) - Smart allocation
-- Opus only for planning (where architecture decisions happen)
-- Sonnet for execution and research (follows explicit instructions)
-- Sonnet for verification (needs reasoning, not just pattern matching)
-- Use when: normal development, good balance of quality and cost
-
-**budget** - Minimal Opus usage
-- Sonnet for anything that writes code
-- Haiku for research and verification
-- Use when: conserving quota, high-volume work, less critical phases
-
-## Resolution Logic
-
-Orchestrators resolve model before spawning:
+| pan-planner | reasoning | reasoning | mid |
+| pan-roadmapper | reasoning | mid | mid |
+| pan-executor | reasoning | mid | mid |
+| pan-phase-researcher | reasoning | mid | fast |
+| pan-project-researcher | reasoning | mid | fast |
+| pan-research-synthesizer | reasoning | mid | fast |
+| pan-debugger | reasoning | mid | mid |
+| pan-document_code | reasoning | fast | fast |
+| pan-verifier | reasoning | mid | fast |
+| pan-plan-checker | reasoning | mid | fast |
+| pan-integration-checker | reasoning | mid | fast |
+| pan-reviewer | reasoning | fast | fast |
+
+### Profile Philosophy
+
+**quality** — Maximum reasoning power
+- Reasoning tier for ALL agents. Use when quota is available, critical architecture work, or maximum quality is desired.
+
+**balanced** (default) — Smart allocation
+- Reasoning only for planning (where architecture decisions happen). Mid for execution. Fast for read-only tasks. Good balance of quality and cost.
+
+**budget** — Minimal token spend
+- Mid for anything that writes code. Fast for research and verification. Use for high-volume work or less critical phases.
+
+### Cost Multipliers
+
+Relative cost per tier (fast = 1× baseline):
+
+| Tier | Multiplier |
+|------|------------|
+| reasoning | 15× |
+| mid | 3× |
+| fast | 1× |
+
+Use `/pan:profile <profile>` to see estimated cost differences before switching.
 
+---
+
+## Routing Pipeline
+
+Model resolution follows this priority chain:
+
+```
+1. Per-agent override (model_overrides in config.json)     ← highest priority
+2. Per-phase override (<!-- model_tier: X --> in roadmap)
+3. Complexity routing (if strategy = "complexity")
+4. Profile lookup (MODEL_PROFILES[agent][profile])          ← lowest priority
+```
+
+### Provider Detection
+
+PAN auto-detects the LLM provider to map tiers to the right model names:
+
+1. **Explicit config** — `routing.provider` in config.json (if not `"auto"`)
+2. **Environment variable** — `PAN_PROVIDER` env var
+3. **Runtime directory** — `.claude/` → Anthropic, `.codex/` → OpenAI, `.gemini/` → Google
+4. **Fallback** — Default provider map (Anthropic-style names)
+
+---
+
+## Routing Strategies
+
+Set in `.planning/config.json` under the `routing` section:
+
+### Static (default)
+
+```json
+{
+  "routing": {
+    "strategy": "static"
+  }
+}
 ```
-1. Read .planning/config.json
-2. Check model_overrides for agent-specific override
-3. If no override, look up agent in profile table
-4. Pass model parameter to Task call
+
+Every agent always gets the tier assigned by its profile. Predictable and simple.
+
+### Complexity
+
+```json
+{
+  "routing": {
+    "strategy": "complexity",
+    "complexity_thresholds": {
+      "downgrade_max": 2,
+      "upgrade_min": 6
+    }
+  }
+}
 ```
 
+Adjusts tiers up or down based on task metadata:
+
+| Factor | Score 0 | Score 1 | Score 2 | Score 3 |
+|--------|---------|---------|---------|---------|
+| fileCount | ≤5 | 6–15 | >15 | — |
+| waveCount | ≤1 | 2–3 | >3 | — |
+| requirementCount | ≤2 | 3–5 | >5 | — |
+| isArchitectural | false | — | — | true |
+
+- Score ≤ `downgrade_max` (default 2): tier steps down one level (e.g., mid → fast)
+- Score ≥ `upgrade_min` (default 6): tier steps up one level (e.g., mid → reasoning)
+- Otherwise: tier stays as assigned by profile
+
+---
+
 ## Per-Agent Overrides
 
 Override specific agents without changing the entire profile:
@@ -61,51 +151,90 @@ Override specific agents without changing the entire profile:
 }
 ```
 
-Overrides take precedence over the profile. Valid values: `opus`, `sonnet`, `haiku`.
+Overrides accept tier names (`reasoning`, `mid`, `fast`) or legacy names (`opus`, `sonnet`, `haiku`). They take highest priority — above per-phase overrides, complexity routing, and profile lookup.
 
-## Switching Profiles
+---
 
-Runtime: `/pan:profile <profile>`
+## Per-Phase Overrides
+
+Override the model tier for all agents within a specific roadmap phase by adding an HTML comment to the phase section:
+
+```markdown
+## Phase 3: Quick UI polish
+**Goal:** Style cleanup
+<!-- model_tier: fast -->
+```
+
+When an orchestrator passes `phaseNum` in task metadata, the routing pipeline checks the roadmap phase for a `model_tier` comment. This lets you use a cheaper tier for simple phases without changing the global profile.
+
+Valid values: `reasoning`, `mid`, `fast`, `opus`, `sonnet`, `haiku`.
+
+---
+
+## Configuration Reference
+
+Full routing config in `.planning/config.json`:
 
-Per-project default: Set in `.planning/config.json`:
 ```json
 {
-  "model_profile": "balanced"
+  "model_profile": "balanced",
+  "model_overrides": {
+    "pan-executor": "opus"
+  },
+  "routing": {
+    "strategy": "static",
+    "provider": "auto",
+    "cascade_quality_gate": true,
+    "complexity_thresholds": {
+      "downgrade_max": 2,
+      "upgrade_min": 6
+    }
+  }
 }
 ```
 
-### Downgrade Confirmation
+| Field | Values | Default | Description |
+|-------|--------|---------|-------------|
+| `model_profile` | `quality`, `balanced`, `budget` | `balanced` | Base tier assignment for all agents |
+| `model_overrides` | `{ agent: tier }` | `{}` | Per-agent tier override |
+| `routing.strategy` | `static`, `complexity` | `static` | How tiers are adjusted at runtime |
+| `routing.provider` | `auto`, `anthropic`, `openai`, `google` | `auto` | LLM provider for tier→model mapping |
+| `routing.cascade_quality_gate` | `true`, `false` | `true` | Reserved for future cascade routing |
+| `routing.complexity_thresholds.downgrade_max` | number | `2` | Max complexity score to downgrade tier |
+| `routing.complexity_thresholds.upgrade_min` | number | `6` | Min complexity score to upgrade tier |
+
+---
+
+## Switching Profiles
 
-When switching to a **lower-tier** profile, PAN asks for confirmation:
+Runtime: `/pan:profile <profile>`
+
+### Downgrade Confirmation
 
 | Direction | Example | Behavior |
 |-----------|---------|----------|
-| Downgrade | quality → balanced | ⚠️ Confirmation required |
-| Downgrade | balanced → budget | ⚠️ Confirmation required |
-| Upgrade | budget → balanced | ✓ Proceeds silently |
-| Upgrade | balanced → quality | ✓ Proceeds silently |
-| Same | balanced → balanced | ✓ Proceeds silently |
+| Downgrade | quality → balanced | Confirmation required |
+| Downgrade | balanced → budget | Confirmation required |
+| Upgrade | budget → balanced | Proceeds silently |
+| Same | balanced → balanced | Proceeds silently |
 
 **Tier Order:** `quality` (3) > `balanced` (2) > `budget` (1)
 
-This prevents accidental quality reductions. Upgrades proceed without prompting since higher quality is always safe.
+---
 
 ## Design Rationale
 
-**Why Opus for pan-planner?**
+**Why reasoning for pan-planner?**
 Planning involves architecture decisions, goal decomposition, and task design. This is where model quality has the highest impact.
 
-**Why Sonnet for pan-executor?**
+**Why mid for pan-executor?**
 Executors follow explicit PLAN.md instructions. The plan already contains the reasoning; execution is implementation.
 
-**Why Sonnet (not Haiku) for verifiers in balanced?**
-Verification requires goal-backward reasoning - checking if code *delivers* what the phase promised, not just pattern matching. Sonnet handles this well; Haiku may miss subtle gaps.
+**Why mid (not fast) for verifiers in balanced?**
+Verification requires goal-backward reasoning — checking if code *delivers* what the phase promised, not just pattern matching.
 
-**Why Haiku for pan-document_code?**
+**Why fast for pan-document_code?**
 Read-only exploration and pattern extraction. No reasoning required, just structured output from file contents.
 
-**Why Haiku for pan-reviewer in balanced?**
-Code review is pattern-matching against known conventions and security rules. Haiku handles checklist-style verification efficiently. Quality profile uses Sonnet for nuanced review when accuracy matters most.
-
-**Why `inherit` instead of passing `opus` directly?**
-Claude Code's `"opus"` alias maps to a specific model version. Organizations may block older opus versions while allowing newer ones. PAN returns `"inherit"` for opus-tier agents, causing them to use whatever opus version the user has configured in their session. This avoids version conflicts and silent fallbacks to Sonnet.
+**Why fast for pan-reviewer in balanced?**
+Code review is pattern-matching against known conventions and security rules. Fast handles checklist-style verification efficiently.

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

@@ -52,6 +52,12 @@ Best for: existing projects, ongoing maintenance, iterative improvement, batch w
 /pan:focus-scan                          # Re-scan to pick up new tasks
 ```
 
+**Documentation quality commands:**
+```
+/pan:focus-drift-walking                 # Walk project tree, detect doc-code drift
+/pan:focus-doc-audit                     # Deep document audit with quality scoring
+```
+
 ---
 
 ## Brownfield Quick-Start (Adding Features to an Existing Project)
@@ -202,7 +208,7 @@ The Focus workflow is a **scan → plan → exec → sync** pipeline. Each step
 
 ---
 
-## All Commands (37)
+## All Commands (42)
 
 ### Getting Started
 | Command | Description |
@@ -255,7 +261,10 @@ The Focus workflow is a **scan → plan → exec → sync** pipeline. Each step
 | `/pan:focus-plan` | Step 2: Budget items into an execution batch |
 | `/pan:focus-exec` | Step 3: Implement, test, verify, commit |
 | `/pan:focus-sync` | Step 4: Synchronize documentation after changes |
+| `/pan:focus-auto` | Continuous scan→plan→exec loop with safety harness |
 | `/pan:focus-design <desc>` | Standalone: Deep feature investigation and spec |
+| `/pan:focus-drift-walking` | Walk project tree, detect doc-code drift, auto-repair |
+| `/pan:focus-doc-audit` | Deep document audit with quality scoring |
 
 ### System
 | Command | Description |
@@ -267,6 +276,7 @@ The Focus workflow is a **scan → plan → exec → sync** pipeline. Each step
 | `/pan:debug` | Systematic debugging with persistent state |
 | `/pan:todo-add` | Capture idea as todo |
 | `/pan:todo-check` | List and select pending todos |
+| `/pan:audit-deployment <dir>` | Audit a PAN installation for integrity and health |
 
 ### Community
 | Command | Description |

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

@@ -79,7 +79,7 @@ Write updated config back to `.planning/config.json`.
 </step>
 
 <step name="confirm">
-Display confirmation with model table for selected profile:
+Display confirmation with model table and cost estimate for selected profile:
 
 ```
 ✓ Model profile set to: $ARGUMENTS.profile
@@ -96,6 +96,13 @@ Example:
 | pan-verifier | haiku |
 | ... | ... |
 
+Cost estimate:
+[Run: node ~/.claude/pan-wizard-core/bin/pan-tools.cjs estimate-cost]
+Show the average cost multiplier for each profile (quality/balanced/budget)
+and highlight the selected profile. Example:
+  quality: 15.0× avg | balanced: 4.3× avg | budget: 2.2× avg
+                                              ^^^^^^^^^^^^^^^^ selected
+
 Next spawned agents will use the new profile.
 ```
 

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

@@ -30,6 +30,7 @@ Parse current values (default to `true` if not present):
 - `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`)
+- `routing.strategy` — how model tiers are adjusted at runtime (default: `static`)
 - `git.branching_strategy` — branching approach (default: `"none"`)
 </step>
 
@@ -102,6 +103,15 @@ AskUserQuestion([
       { 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})" }
     ]
+  },
+  {
+    question: "Model routing strategy?",
+    header: "Routing",
+    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." }
+    ]
   }
 ])
 ```
@@ -123,6 +133,9 @@ Merge new settings into existing config.json:
   },
   "git": {
     "branching_strategy": "none" | "phase" | "milestone"
+  },
+  "routing": {
+    "strategy": "static" | "complexity"
   }
 }
 ```
@@ -190,6 +203,7 @@ Display:
 | Auto-Advance         | {On/Off} |
 | Nyquist Validation   | {On/Off} |
 | Git Branching        | {None/Per Phase/Per Milestone} |
+| Routing Strategy     | {Static/Complexity} |
 | Saved as Defaults    | {Yes/No} |
 
 These settings apply to future /pan:plan-phase and /pan:exec-phase runs.