pan-wizard 3.35.0 → 3.37.0

package/docs/USER-GUIDE.md

@@ -0,0 +1,1437 @@
+<div align="center">
+<img src="../assets/pan-avatar.png" alt="PanWizard" width="90" />
+</div>
+
+# PAN User Guide
+
+A detailed reference for workflows, troubleshooting, and configuration. For quick-start setup, see the [README](../README.md).
+
+**Other docs:** [FAQ](FAQ.md) · [Examples](EXAMPLES.md) · [Architecture](ARCHITECTURE.md) · [Development](DEVELOPMENT.md) · [CLI Reference](CLI-REFERENCE.md) · [Agents](AGENTS.md) · [Hooks](HOOKS.md)
+
+---
+
+## Table of Contents
+
+- [Getting Started](#getting-started)
+- [Workflow Diagrams](#workflow-diagrams)
+- [Command Reference](#command-reference)
+- [Configuration Reference](#configuration-reference)
+- [Usage Examples](#usage-examples)
+- [Advanced Features](#advanced-features)
+  - [Native Workflows (Claude Code only)](#native-workflows-claude-code-only)
+  - [The Evidence Loop](#the-evidence-loop)
+  - [Self-Improvement Loop](#self-improvement-loop)
+  - [AI Agent Guardrails](#ai-agent-guardrails)
+  - [Advanced Planning Options](#advanced-planning-options)
+  - [Execution Model](#execution-model)
+  - [Bot-army campaigns](#bot-army-campaigns-panarmy)
+  - [Army & project dashboard](#army--project-dashboard-panhud)
+  - [Git Integration](#git-integration)
+  - [Requirement Tracing](#requirement-tracing)
+  - [Global Defaults](#global-defaults)
+  - [Web Search](#web-search)
+  - [Debug Logging](#debug-logging)
+- [Troubleshooting](#troubleshooting)
+- [Recovery Quick Reference](#recovery-quick-reference)
+- [Multi-Runtime Reference](#multi-runtime-reference)
+- [Project File Structure](#project-file-structure)
+
+---
+
+## Getting Started
+
+A step-by-step walkthrough of your first PAN project, from initialization to verification.
+
+### Step 1: Initialize a New Project
+
+```text
+/pan:new-project
+```
+
+PAN asks you questions about your project — what you're building, who it's for, and what success looks like. This is a collaborative conversation, not a form.
+
+**What gets created:**
+- `.planning/project.md` — Your project brief
+- `.planning/requirements.md` — Scoped requirements with REQ-IDs
+- `.planning/roadmap.md` — Phased delivery plan
+- `.planning/config.json` — Project configuration
+- `.planning/state.md` — Progress tracker
+
+### Step 2: Plan a Phase
+
+```text
+/pan:plan-phase 1
+```
+
+PAN creates detailed execution plans for Phase 1 with specific tasks and validates them through a quality checker (with `--research`, or `workflow.research: true`, a researcher first answers the open questions that block building). Each plan targets a single concern with 2-3 atomic tasks, and carries a `## Review Focus` section: at most five untested inputs or failure modes, each tied to a task and a test (or `None — <reason>`). Before the checker runs, code checks send a broken plan set straight back to the planner: `verify plan-set`, `verify review-focus` and `verify decisions` (plans cite only the `DD-N` design decisions the design records, and every recorded one is cited). When the checker runs, `research lint` runs before it but never blocks: claims in the research's `## Claims` table with no source or checked date, and stale ones, go to the checker.
+
+**What gets created:**
+- `.planning/phases/01-{name}/01-01-plan.md` — First execution plan
+- Additional `{phase}-{plan}-plan.md` files if the phase needs multiple plans
+
+**Optional:** Run `/pan:discuss-phase 1` first to have PAN ask clarifying questions about your approach before planning.
+
+### Step 3: Execute the Phase
+
+```text
+/pan:exec-phase 1
+```
+
+PAN executes each plan's tasks in wave order — independent plans run in parallel, dependent plans run sequentially. Each task produces a git commit. If something breaks, PAN auto-fixes it (up to 3 attempts per task). An executor that finished but is unsure of something returns `DONE_WITH_CONCERNS` with each concern's reason and cost if wrong; the plan counts as complete and the concerns go to the reviewer, which judges the phase's diff against the plans' intent (`pan-tools review scope`).
+
+**What gets created:**
+- Your actual project files (code, config, etc.)
+- `.planning/phases/01-{name}/01-01-summary.md` — Execution report per plan, plus `01-review.md` (the code review) and `01-verification.md` (the phase verification)
+- Git commits for each completed task
+
+After each wave PAN reports the phase's spend when it nears or reaches the phase budget (`cost.phase_budget_usd`, $20 by default; it only warns). At the end, `phase complete` runs the phase gate: with the default `workflow.phase_gate: enforce` it refuses to mark the phase complete when a check fails, such as a plan with no summary, a missing, failing or stale verification, or an open critical or high finding, and shows each reason. See [Phase gate refuses to complete a phase](TROUBLESHOOTING.md#phase-gate-refuses-to-complete-a-phase).
+
+### Step 4: Verify the Work
+
+```text
+/pan:verify-phase 1
+```
+
+PAN re-runs goal-backward verification with a test-suite gate — checking that the codebase delivers what the phase promised — and lists the recommended fix plans. Create them with `/pan:plan-phase 1 --gaps`, then run `/pan:exec-phase 1 --gaps-only`.
+
+**What gets created:**
+- `.planning/phases/01-{name}/01-verification.md` — Verification results
+- Recommended fix plans in the report (written to disk by `/pan:plan-phase 1 --gaps`)
+
+### Step 5: Check Progress and Continue
+
+```text
+/pan:progress
+```
+
+Shows your overall project status and tells you what to do next — plan the next phase, execute remaining plans, or verify completed work. `/pan:progress`, `/pan:resume` and the phase transition all get that next step from one router, `pan-tools next-action`, which reads `roadmap.md` and the phase directories; run it yourself to see the suggestion as JSON.
+
+**Typical flow from here:**
+- Plan the next phase: `/pan:plan-phase 2`
+- If you need to pause: `/pan:pause`
+- If you're resuming later: `/pan:resume`
+
+### Tips for Your First Project
+
+- **Start small** — Pick a project with 3-5 phases for your first run
+- **Use `/pan:discuss-phase`** before planning if you're unsure about approach
+- **Check `/pan:progress`** whenever you lose track of where you are
+- **Use the `balanced` profile** (default) — the agents that plan, write and judge code are on the reasoning tier, which inherits the model you launched with (the researchers and the plan-checker run on the mid tier, and a few review agents pin their own model — see Model Profiles); switch to `budget` only when cost matters more than depth
+- **Run `/clear`** between major commands to keep context fresh
+
+### Capability-aware features
+
+PAN emits all of these unconditionally. They pay off in full on Claude Code with a frontier reasoning model (Opus, for example); elsewhere they degrade rather than error, as described below the list:
+
+- **Prompt caching** — the host caches each agent's prompt prefix by itself; nothing PAN runs can mark another agent's prompt for caching. What PAN controls is how much every agent re-reads: phase agents read their phase's roadmap slice instead of the whole roadmap and requirements, and `state compact` and `roadmap compact` keep the always-read planning files small (`/pan:hygiene` flags them when they grow). Requires a model/runtime that supports prompt caching.
+- **Effort-tuned reasoning** — every agent declares an `effort:` level (`AGENT_BASE_EFFORT` in `core.cjs`): the plan and design checkers, planner, designer, debugger and conductor run at `xhigh`, execution, verification, release, the hardener, the roadmapper and the remaining specialists (optimizer, previewer, counterfactual, integration checker, experiment runner) at `high`, research, knowledge, the distiller and the reviewer/meta-reviewer at `medium`, and the mechanical `pan-document_code` pass at `low`. Catches logic gaps earlier where it matters most.
+- **Single-shot map-codebase** — repos that fit the single-shot threshold (≤700K tokens, measured by `pan-tools codebase estimate-size`) map in a single agent instead of several parallel ones. Mode is chosen by repo size alone; holding a repo that large in one pass needs a model with a 1M-context window, so on smaller-context models prefer the sharded path (the command's hard-coded `estimate-size --threshold 700000` call decides the mode; lower that threshold in the command to force `sharded`).
+- **How a lesson reaches the next phase** — through what the phase agents already read: `.planning/state.md` (its decisions), the phase summaries, the code and its tests, and the project's own instructions (`CLAUDE.md` or `AGENTS.md`, outside PAN's section). A lesson that should hold for the rest of the project belongs in those instructions, or in a test that fails when it is broken.
+- **The agent memory store** — `.planning/memory/<agent>.md` keeps lessons you record (`memory append`, or the gated `memory record`) and `/pan:retro --write-memory`'s recurring gap patterns. **PAN's workflows do not load it into agents.** Harness runs found that a recorded lesson changed nothing that `state.md`, the summaries and the code did not already carry. Read it with `/pan:knowledge`.
+  - **What `memory select` leaves out:** a lesson that cites code (`memory append … --cites src/db.js#bulkInsert`) once that code is gone, and a lesson nobody has used for the expiry window.
+  - **Housekeeping:** `pan-tools memory prune --apply` archives what is left out, and `/pan:hygiene` reports it.
+  - **Inspect and trim:** `pan-tools memory list` shows the logs, and `pan-tools memory compact <agent> <max>` trims one (the entries it drops are kept in `.planning/memory/archive/<agent>.md`).
+- **Milestone retrospective** — `/pan:retro` reports estimation accuracy, verification pass rates and the gap patterns that recur. Take a pattern that matters into the next milestone's plans or the project's instructions. Run after every `/pan:milestone-done`.
+- **Capability-aware routing** — when a task needs thinking, the fast tier upgrades to mid; when cache is warm and context is small, mid downgrades to fast. The rules live in `adjustTierForCapabilities()` in `core.cjs`, which `resolveModelDetailed()` applies when a hint is present. They act only on hints passed to `pan-tools resolve-model --metadata`, and no workflow passes them today.
+- **Commands stay out of the model's listing** — on Claude Code PAN's commands carry `disable-model-invocation: true`, so their descriptions are not sent to the model on every turn; you invoke them as `/pan:<name>`. (Installs by PAN 3.29.0 and earlier also wrote flat `.claude/skills/pan-*.md` shims for this; Claude Code only loads `skills/<name>/SKILL.md` directories, so the shims were never read, and upgrading removes them.)
+
+On lower tiers (mid/fast models) and non-Claude runtimes, features degrade gracefully: on OpenCode, Gemini CLI and Copilot CLI the installer turns each agent's `effort:` into a prose "think step-by-step" preamble (Codex gets it as its native `model_reasoning_effort`, and Claude Code reads `effort:` natively whatever the tier), caching is a no-op, and the map-codebase command's `estimate-size --threshold 700000` call decides the map mode (lower it in the command to force the sharded path). None of this is gated at runtime — no feature, mode, or routing decision checks your model name before choosing a code path. (`/pan:cost` does look up the model ID recorded in the metrics log to price your token usage, but that only affects the number in a cost report, not what PAN runs. On Claude Code the context monitor reads the model ID to know the window it measures against; that decides only whether and when its note appears.) The one model-name check you'll notice is advisory and runs once: at the end of install, the installer looks up the `model` field in your `settings.json` against a hand-maintained table of known model IDs (`detectModelCapabilities()` in `bin/install-lib.cjs`) and prints a note if that model is known to lack 1M context or extended thinking. The table recognizes the current generations by name and deliberately fails forward — the per-family threshold is the last reduced-capability release it records, not the newest release it lists, so any Claude ID newer than that boundary (a new major, or a later point release inside a major it already lists) inherits that family's modern profile rather than reading as capability-less, and upgrading to a new flagship doesn't produce a bogus warning. An ID resolves either by matching an explicit branch in the table or — for Claude names — by carrying a family plus a readable release number strictly newer than that family's last reduced-capability release; anything that resolves neither way reads as `tier: 'unknown'` with every capability flag false. That result may trigger the note spuriously. Either way it's a hint, never a block. Pass `--skip-warnings` to silence it.
+
+### Spec B v2 features
+
+Spec B v2 (v3.0-v3.4) added a wave of new commands. Each has a clear single purpose. None modify the focus system. v3.5 added `/pan:learn`, `/pan:learn --optimize` and `/pan:git`, and the `security` and `distill` focus-auto categories.
+
+- **`/pan:cost` (v3.0)** — token usage + estimated cost across all PAN invocations. Three output formats (`json`/`table`/`chart`). Auto-populated since v3.4 by the SubagentStop hook on Claude Code, Codex and Copilot CLI (not Gemini CLI or OpenCode); no manual instrumentation needed. Time-windowed with `--since YYYY-MM-DD --until YYYY-MM-DD`. `pan-tools cost budget --phase N` shows a phase's spend against `cost.phase_budget_usd` ($20 by default, warn only).
+- **`/pan:preview phase <N> | phases | milestone` (v3.1)** — read-only foresight. Three modes:
+  - `phase N` — blast radius (files likely touched, tests at risk, risk score 1-10, migration flags) and a cost forecast (p10/p50/p90 per plan and per phase from this project's own cost ledger; `insufficient` until there are enough observations)
+  - `phases` — dependency graph (mermaid DAG + parallel batches + hidden coupling)
+  - `milestone` — ETA with confidence + bottleneck identification
+- **`/pan:review-deep <phase>` (v3.2)** — security audit (OWASP + STRIDE via `pan-hardener`) + cross-check by `pan-meta-reviewer`. Merges reviewer + hardener + meta findings into one verdict ladder. Recommended for phases touching auth/payment/PII/migrations/public APIs. Also invokable as `/pan:exec-phase <N> --deep-review`; `/pan:focus-auto --step exec --deep-review` runs the hardener and meta-reviewer on each high-stakes item's changed files and merges them under the item's id. Costs ~3× a normal review.
+- **`/pan:knowledge {ask|discuss|playbook}` (v3.2)** — three modes in one command:
+  - `ask "question"` — grounded Q&A with inline citations. Example: `/pan:knowledge ask "why does phase 4 have a race condition fix?"`
+  - `discuss <phase> "topic"` — multi-turn refinement with session state persistence. Benefits from prompt caching where the runtime and model support it.
+  - `playbook` — aggregate all agents' memory into `.planning/playbook.md` categorized by Conventions / Gotchas / Decisions / Tool choices / Anti-patterns / Recurring gaps.
+- **`/pan:what-if <phase> "scenario"` (v3.3)** — counterfactual phase replay in an isolated git worktree. Agent explores the alternative, report lands in `.planning/counterfactuals/<phase>-<slug>.md`, worktree auto-deleted. Requires git.
+
+#### Advanced flags and logging
+
+- **`--hierarchical` flag on `/pan:exec-phase` (v3.4)** — spawn `pan-conductor` as a top-level orchestrator that decomposes the phase and spawns executor/reviewer/verifier sub-agents in waves. Bounded by a safety harness (2-level nesting, 12-spawn cap, budget ceiling, abort file). Claude Code only — agents-spawn-agents needs native sub-agent spawning; on the other four runtimes the flag is a no-op that warns and falls back to flat exec. No model gate: `pan-conductor` inherits the model you launched the session with. Use for phases with ≥4 autonomous plans where wall-clock reduction justifies the ~20-30% orchestration tax.
+- **`--deep-review` flag on `/pan:exec-phase` and `/pan:focus-auto --step exec` (v3.4)** — on `/pan:exec-phase`, run the `/pan:review-deep` process inline after the normal reviewer step, before verification; on `/pan:focus-auto --step exec`, run the hardener and meta-reviewer on each high-stakes item's changed files and merge them under the item's id (no first-pass review). Recommended for high-stakes batches.
+- **Automatic cost logging (v3.4)** — `hooks/pan-cost-logger.js` registered as a SubagentStop hook. Every sub-agent completion appends a record to `.planning/metrics/tokens.jsonl`. Visible in `/pan:cost report` without any manual `cost append` calls.
+
+All Spec B v2 commands interoperate with the focus system via read boundaries and optional flags — no focus command was modified.
+
+---
+
+## Workflow Diagrams
+
+### Full Project Lifecycle
+
+```text
+  ┌──────────────────────────────────────────────────┐
+  │                   NEW PROJECT                    │
+  │  /pan:new-project                                │
+  │  Questions -> Requirements -> Roadmap (+research)│
+  └─────────────────────────┬────────────────────────┘
+                            │
+             ┌──────────────▼─────────────┐
+             │      FOR EACH PHASE:       │
+             │                            │
+             │  ┌────────────────────┐    │
+             │  │ /pan:discuss-phase │    │  <- Lock in preferences
+             │  └──────────┬─────────┘    │
+             │             │              │
+             │  ┌──────────▼─────────┐    │
+             │  │ /pan:design-phase  │    │  <- Architecture, ADR, threat-lite
+             │  └──────────┬─────────┘    │
+             │             │              │
+             │  ┌──────────▼─────────┐    │
+             │  │ /pan:plan-phase    │    │  <- Plan + Verify (research opt-in)
+             │  └──────────┬─────────┘    │
+             │             │              │
+             │  ┌──────────▼─────────┐    │
+             │  │ /pan:exec-phase │    │  <- Parallel execution
+             │  └──────────┬─────────┘    │
+             │             │              │
+             │  ┌──────────▼─────────┐    │
+             │  │ /pan:verify-phase   │    │  <- Goal-backward verify
+             │  └──────────┬─────────┘    │
+             │             │              │
+             │     Next Phase?────────────┘
+             │             │ No
+             └─────────────┼──────────────┘
+                            │
+            ┌───────────────▼──────────────┐
+            │  /pan:milestone-audit        │
+            │  /pan:milestone-done     │
+            └───────────────┬──────────────┘
+                            │
+                   Another milestone?
+                       │          │
+                      Yes         No -> Done!
+                       │
+               ┌───────▼──────────────┐
+               │  /pan:milestone-new  │
+               └──────────────────────┘
+```
+
+### Planning Agent Coordination
+
+```text
+  /pan:plan-phase N
+         │
+         ├── Phase Researcher (opt-in: --research)
+         │           │
+         │     ┌──────▼──────┐
+         │     │ research.md │
+         │     └──────┬──────┘
+         │            │
+         │     ┌──────▼──────┐
+         │     │   Planner   │  <- Reads state.md, the roadmap slice,
+         │     │             │     context.md, research.md
+         │     └──────┬──────┘
+         │            │
+         │     ┌──────▼───────────┐     ┌────────┐
+         │     │   Plan Checker   │────>│ PASS?  │
+         │     └──────────────────┘     └───┬────┘
+         │                                  │
+         │                             Yes  │  No
+         │                              │   │   │
+         │                              │   └───┘  (revise: once by default, 2x under quality)
+         │                              │
+         │                        ┌─────▼──────┐
+         │                        │ PLAN files │
+         │                        └────────────┘
+         └── Done
+```
+
+### Validation Architecture (Nyquist Layer)
+
+When the Nyquist layer is enabled (`workflow.nyquist_validation` — **off by
+default**; see below) and the phase is researched (`--research`, or
+`workflow.research: true`; research is off by default), plan-phase research maps
+automated test coverage to each phase requirement before any code is written.
+Without research the plan-phase warns and continues without a validation strategy. This ensures that when Claude's
+executor commits a task, a feedback mechanism already exists to verify it within seconds.
+
+The researcher detects your existing test infrastructure, maps each requirement to
+a specific test command, and identifies any test scaffolding that must be created
+before implementation begins (Wave 0 tasks).
+
+With it enabled, the plan-checker treats test coverage as an additional verification
+dimension: plans whose tasks lack automated verify commands are sent back for revision.
+
+**Output:** `{phase}-validation.md` -- the feedback contract for the phase.
+
+**Enable:** Set `workflow.nyquist_validation: true` in `/pan:settings`. It ships
+off by default; turn it on for phases where planning test coverage up front matters.
+
+### Execution Wave Coordination
+
+```text
+  /pan:exec-phase N
+         │
+         ├── Analyze plan dependencies
+         │
+         ├── Wave 1 (independent plans):
+         │     ├── Executor A (fresh context) -> commit
+         │     └── Executor B (fresh context) -> commit
+         │
+         ├── Wave 2 (depends on Wave 1):
+         │     └── Executor C (fresh context) -> commit
+         │
+         └── Verifier
+               └── Check codebase against phase goals
+                     │
+                     ├── PASS -> verification.md (success)
+                     └── FAIL -> gaps in verification.md -> /pan:plan-phase N --gaps
+```
+
+### Brownfield Workflow (Existing Codebase)
+
+```text
+  /pan:map-codebase
+         │
+         ▼
+  mapper agent(s)
+         │
+         ├── codebase/stack.md
+         ├── codebase/integrations.md
+         ├── codebase/architecture.md
+         ├── codebase/structure.md
+         ├── codebase/conventions.md
+         ├── codebase/testing.md
+         ├── codebase/concerns.md
+         ├── codebase/relationships.md
+         └── codebase/best-practices.md
+                │
+        ┌───────▼──────────┐
+        │ /pan:new-project │  <- Questions focus on what you're ADDING
+        └──────────────────┘
+```
+
+---
+
+## Command Reference
+
+### Renamed commands
+
+Some commands were folded into flags of another command. The old names keep working: the installer generates them as aliases.
+
+| Old command | Now |
+|-------------|-----|
+| `/pan:dashboard` | `/pan:hud` |
+| `/pan:milestone-cleanup` | `/pan:milestone-done --cleanup` |
+| `/pan:milestone-gaps` | `/pan:milestone-audit --gaps` |
+| `/pan:optimize` | `/pan:learn --optimize` |
+| `/pan:research-phase` | `/pan:plan-phase --research-only` |
+| `/pan:profile` | `/pan:settings --profile` |
+| `/pan:focus-doc-audit` | `/pan:focus-docs` |
+| `/pan:focus-sync` | `/pan:focus-docs --sync` |
+| `/pan:focus-scan`, `/pan:focus-plan`, `/pan:focus-exec`, `/pan:focus-drift-walking` | `/pan:focus-auto --step scan`, `plan`, `exec`, `drift` |
+
+`/pan:discord` and `/pan:mcp-bridge` were retired with no replacement. PAN's own MCP server is unaffected (see [MCP server registration](#mcp-server-registration)).
+
+### Core Workflow
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| `/pan:new-project` | Full project init: questions, research (opt-in), requirements, roadmap | Start of a new project |
+| `/pan:new-project --auto @idea.md` | Automated init from document | Have a PRD or idea doc ready |
+| `/pan:discuss-phase <N>` | Capture implementation decisions | Before planning, to shape how it gets built |
+| `/pan:design-phase <N>` | Design a phase — architecture, ADR, threat-lite — before planning | After discussing, before planning |
+| `/pan:plan-phase [N]` | Plan + verify (research with `--research`); `--research-only <N>` runs the research step alone | Before executing a phase; research only for a complex or unfamiliar domain |
+| `/pan:exec-phase <N>` | Execute all plans in parallel waves | After planning is complete |
+| `/pan:verify-phase [N] [--uat]` | Goal-backward re-verification with a test-suite gate; lists gaps for `--gaps`. `--uat` walks you through the phase's acceptance tests instead (every runtime; answers recorded through `pan-tools uat record`) | After execution completes |
+| `/pan:autodev [run\|resume\|status\|report\|replay]` | Unattended loop over the roadmap: a fresh host session per plan, execute and verify step (a lean phase: the engine plans it, then one session builds, reviews and verifies it), `phase complete` in the engine, stop reasons in code, a ledger per run in `.planning/autodev/` | When the roadmap is settled and you want phases built without supervision |
+| `/pan:milestone-audit` | Verify milestone met its definition of done; `--gaps` creates phases for the gaps it found | Before completing milestone |
+| `/pan:milestone-done <version>` | Archive milestone, tag release; `--cleanup` archives old phase directories from completed milestones | All phases verified |
+| `/pan:milestone-new [name]` | Start next version cycle | After completing a milestone |
+
+### Navigation
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| `/pan:progress` | Show status and next steps | Anytime -- "where am I?" |
+| `/pan:resume` | Restore full context from last session | Starting a new session |
+| `/pan:pause` | Save context handoff | Stopping mid-phase |
+| `/pan:help` | Show all commands | Quick reference |
+| `/pan:update` | Update PAN with changelog preview, reinstalling the runtime it runs in (for a `--config-dir` or `--unified-skills` install, re-run the installer with your original flags) | Check for new versions |
+
+### Phase Management
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| `/pan:add-phase <description>` | Append new phase to roadmap | Scope grows after initial planning |
+| `/pan:insert-phase <after> <description>` | Insert urgent work (decimal numbering) | Urgent fix mid-milestone |
+| `/pan:remove-phase <N>` | Remove future phase and renumber | Descoping a feature |
+| `/pan:assumptions <N>` | Preview Claude's intended approach | Before planning, to validate direction |
+
+### Brownfield & Utilities
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| `/pan:map-codebase` | Analyze existing codebase (one agent for small repos, several in parallel above the size threshold) | Before `/pan:new-project` on existing code |
+| `/pan:quick` | Ad-hoc task with PAN guarantees | Bug fixes, small features, config changes |
+| `/pan:debug [desc]` | Systematic debugging with persistent state | When something breaks |
+| `/pan:todo-add [desc]` | Capture an idea for later | Think of something during a session |
+| `/pan:todo-check` | List pending todos | Review captured ideas |
+| `/pan:settings` | Configure workflow toggles, model profile, branching and the phase budget; `--profile <profile>` is a quick profile switch | Change model, toggle agents, change the spend warning or the cost/quality tradeoff |
+| `/pan:patches` | Restore local modifications after update | After `/pan:update` if you had local edits |
+| `/pan:phase-budget` | Estimate context window utilization | Monitor context health during execution |
+| `/pan:health [--repair]` | Validate `.planning/` directory integrity | Diagnose and auto-repair directory issues |
+| `/pan:hygiene [--apply]` | Scan for PAN version drift + stale artifacts (legacy filenames, memory bloat and stale memory entries, poisoned ledgers, trace debris, an oversized state.md or roadmap.md, Claude Code's memory index); `--apply` executes the safe fixes, `state compact` and `roadmap compact` among them | Keep older projects aligned with the latest PAN |
+| `/pan:phase-tests <N> [instructions]` | Generate tests for a completed phase | After execution, to add test coverage |
+| `/pan:retro` | Milestone retrospective — estimation accuracy, gap patterns | After `/pan:milestone-done` |
+| `/pan:links [--strict]` | Validate the doc–code link graph: inline `[[<id>]]` refs, `// @pan:` source anchors, `require-code-mention` contracts (ADR-0027) | Renamed an ADR or moved a module — catch broken refs |
+
+### Spec B v2
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| `/pan:cost` | Token usage + estimated cost report (json/table/chart); `budget` (a phase's spend against `cost.phase_budget_usd`), `limits` (Claude Code's usage windows), and the `usage` census (`pan-tools usage`: which installed commands and agents this project has used) | Track AI costs across phases |
+| `/pan:preview phase <N>\|phases\|milestone` | Read-only foresight: blast radius / dependency graph / milestone ETA | Before exec — "what will this touch?" |
+| `/pan:review-deep <phase>` | Security audit (OWASP+STRIDE) + cross-checked by meta-reviewer | High-stakes phases (auth/payments/PII) |
+| `/pan:knowledge {ask\|discuss\|playbook}` | Grounded Q&A, multi-turn discussion, or aggregate memory into playbook | Reflection or design discussion |
+| `/pan:what-if <phase> "scenario"` | Counterfactual phase replay in isolated git worktree | Explore an alternative approach safely |
+
+### Optimization & Git
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| `/pan:learn` | Analyze the most recent trace session, generate optimization report; `--optimize {apply\|revert\|list\|stats\|trace}` records the report's suggestions, undoes an apply, lists reports, shows stats and manages trace sessions | After a phase or campaign — "what can PAN learn?" |
+| `/pan:git <subcommand>` | Phase-aware git workflow with safety guardrails (commit/branch/push/status/log/stash/diff/rollback/tag/sync) | Day-to-day git ops with branch-name conventions and safety checks |
+
+### Operations (Pre-Flight, Dashboard, Learnings, Dependencies)
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| `pan-tools preflight [target]` | Validate state, blockers, git, config before execution | Before starting work: "am I ready?" |
+| `pan-tools dashboard` | Aggregated project overview (JSON/text; for the visual HTML version see [`/pan:hud`](#army--project-dashboard-panhud)) | Quick status check: "where am I?" |
+| `pan-tools learnings extract` | Extract learnings from phase summaries (co-changed key files, `patterns-established`) and `patterns.md` error patterns | After sessions: capture what you learned |
+| `pan-tools learnings list` | List all extracted learnings | Review accumulated project knowledge |
+| `pan-tools learnings prune --days N` | Remove old learnings | Housekeeping: keep learnings relevant |
+| `pan-tools deps validate` | Cross-reference roadmap vs disk, find orphaned requirements | Project health: "is my plan consistent?" |
+
+`pan-tools` throughout this guide is shorthand for `node .claude/pan-wizard-core/bin/pan-tools.cjs`; the installer adds no `pan-tools` command to your PATH. Use your runtime's directory in place of `.claude` (`.codex`, `.gemini`, `.opencode`, `.github`), or its global config directory after a `--global` install.
+
+**Typical workflow:**
+```bash
+pan-tools preflight              # Ready to work?
+pan-tools dashboard              # Where am I?
+pan-tools deps validate          # Roadmap consistent with reality?
+pan-tools learnings extract      # Capture patterns from recent sessions
+pan-tools learnings list --raw   # Review what's been learned
+```
+
+### Focus (Strategic Project Management)
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| `/pan:focus-auto` | Continuous scan→plan→exec loop with a layered safety harness; `--step scan\|plan\|exec\|drift` runs one stage (classify work items, budget a batch, execute it, or repair doc-code drift) | Hands-off batch work across categories, or one stage at a time |
+| `/pan:focus-design` | Multi-phase strategic feature investigation | Before building a new feature |
+| `/pan:focus-docs` | Multi-dimensional document audit with weighted quality scoring; `--sync` detects stale documentation counts | Quality assurance: "how trustworthy are my docs?", or after changes to check docs match code |
+
+**Focus workflow:** `/pan:focus-auto --step scan` → `--step plan` → `--step exec`, then `/pan:focus-docs --sync`. Scan collects work from phases, todos, and error patterns. Plan budgets items using one of 4 modes (bugfix/balanced/features/full). Exec provides the execution pipeline. Sync verifies documentation stays current. Or use `focus-auto` to run continuous scan→plan→exec cycles across the supported categories (cleanup, tests, stability, features, docs, optimize, prompts, security, distill). Use `/pan:focus-auto --step drift` to detect and repair documentation-code drift across all directories. Use `/pan:focus-docs` for deep quality audits with per-file scoring. The `security` category targets OWASP Top 10 + STRIDE issues; the `distill` category targets AI-generated code bloat with a 5-pass deterministic→AST→graph→LLM→memory pipeline.
+
+### Standards Integration
+
+PAN includes a built-in catalog of industry standards (OWASP Top 10, WCAG 2.2, NIST SSDF, STRIDE, etc.). Standards are advisory — they guide agents during planning and verification but never block execution.
+
+**Quick start:**
+```bash
+pan-tools standards recommend          # Get recommendations based on your project type
+pan-tools standards select owasp-top10 # Add a standard
+pan-tools standards status             # Check compliance progress
+pan-tools validate health --standards  # Include in health reports
+```
+
+**Per-phase tracking:**
+```bash
+pan-tools standards phase-track 1      # Which standards matter for phase 1?
+pan-tools standards tools              # What external tools can help verify?
+pan-tools standards tools owasp-top10  # Tools for a specific standard
+```
+
+**How it works:** Selected standards are stored in `.planning/standards.md` as Markdown checklists. Agents naturally read this file as context. The verifier (Step 7b) runs per-phase standards tracking, auto-ticks checklist items it can confirm, and recommends external tools when coverage is low. The plan-checker's Standards Awareness dimension references selected standards when standards.md exists.
+
+**Available standards:** OWASP Top 10, OWASP ASVS L1, OWASP LLM Top 10, OWASP Agentic Top 10, WCAG 2.2, NIST SSDF, ISO 25010, STRIDE, CWE Top 25, SOC 2 Dev Controls, TOGAF ADM, Conventional Commits.
+
+### Doc-Code Link Graph
+
+PAN treats your planning surface — ADRs, specs, learnings, references, workflows — as an explicit graph and lints its integrity. Renaming an ADR or moving a module no longer silently strands references.
+
+**Two link types:**
+
+- **Forward links**: inline `[[<id>]]` body-text refs and frontmatter `must_haves.key_links` entries. Recognized doc-id forms: `ADR-NNNN` (resolves via glob), `<path>.md`, `<path>` (tries `.md` then `/README.md`), and any with `#section`.
+- **Backlinks**: `// @pan: <doc-id>` source-comment anchors (idiomatic per language: `//` for JS/TS/CJS, `#` for shell/Python, `<!--` for markdown/HTML). Anchors declare "this code is a load-bearing implementation of that doc."
+
+**Backlink contract:** any doc with `require-code-mention: true` in YAML frontmatter must be anchored by at least one `@pan:` comment under source roots. The lint enforces this (`B-001` finding); without the frontmatter flag, anchors are advisory.
+
+**Run it:**
+
+```text
+/pan:links                                  # advisory — errors fail, warnings pass
+/pan:links --strict                         # warnings also fail (B-002 single-source informational is exempt)
+pan-tools validate health --links           # attach link-graph summary to a health report
+pan-tools links validate --doc-root docs --source-root src  # your own layout; the flags replace the default roots and repeat
+```
+
+The default roots are PAN's own source layout: docs under `docs/`, `commands/`, `agents/` and parts of `pan-wizard-core/`, anchors under `pan-wizard-core/`, `bin/`, `hooks/` and `scripts/`. In your project, pass `--doc-root` and `--source-root` for your layout (`/pan:links` takes them too). Run bare in a project whose code lives under `src/`, it scans no source file and reports every `require-code-mention` doc as B-001; a run that scanned no doc or source files has misconfigured roots, not a clean graph.
+
+**Finding codes:** F-001/F-002 (broken inline / missing section), F-003/F-004 (key_links path / regex), B-001 (uncovered `require-code-mention`), B-002 (informational single-source), A-001/A-002/A-004 (stale anchor target / section / empty id).
+
+The convention is opt-in per doc — only docs with `require-code-mention: true` enforce backlinks; the rest are advisory. PAN's own ADR-0021, ADR-0026, and ADR-0027 are the canary opt-ins; their primary implementation files (`codebase.cjs`, `experiment.cjs`, `runner.cjs`, `links.cjs`) carry the matching `// @pan:` anchors. See [ADR-0027](decisions/ADR-0027-doc-code-link-graph.md) for design rationale and [docs/specs/doc_code_link_graph_featureai.md](specs/doc_code_link_graph_featureai.md) for the wire-level spec.
+
+---
+
+## Configuration Reference
+
+PAN stores project settings in `.planning/config.json`. Configure during `/pan:new-project` or update later with `/pan:settings`.
+
+### Full config.json Schema
+
+```json
+{
+  "model_profile": "balanced",
+  "commit_docs": true,
+  "search_gitignored": false,
+  "branching_strategy": "none",
+  "phase_branch_template": "pan/phase-{phase}-{slug}",
+  "milestone_branch_template": "pan/{milestone}-{slug}",
+  "workflow": {
+    "research": false,
+    "plan_check": true,
+    "verifier": true,
+    "nyquist_validation": false,
+    "phase_record_compact": false,
+    "phase_gate": "enforce",
+    "mutation_gate": "report",
+    "mutation_floor": 0.6,
+    "review_mode": "single",
+    "cross_family_review": "off",
+    "worktree_isolation": false,
+    "ceremony": "auto",
+    "lean_max_requirements": 5,
+    "phase_reports": { "enabled": false, "open": false, "theme": "auto", "index": true }
+  },
+  "parallelization": true,
+  "hooks": { "guard": "report" },
+  "cost": { "phase_budget_usd": 20 },
+  "brave_search": false,
+  "budget": {
+    "default_points": 50,
+    "micro_threshold_tasks": 3,
+    "micro_threshold_files": 2,
+    "enforce": false,
+    "verify_reserve": 0.15,
+    "max_usd_run": null,
+    "max_usd_day": null
+  },
+  "commit": {
+    "safety_checks": true,
+    "conventional_types": true,
+    "sensitive_patterns": ["\\.env$", "\\.pem$", "\\.key$", "credentials", "secret", "password", "token"]
+  },
+  "execution": {
+    "default_mode": "wave_order",
+    "rollback_snapshots": true,
+    "error_pattern_learning": true
+  },
+  "routing": {
+    "strategy": "static",
+    "provider": "auto",
+    "cascade_quality_gate": true,
+    "max_escalations": 1,
+    "complexity_thresholds": { "downgrade_max": 2, "upgrade_min": 6 }
+  }
+}
+```
+
+This is what `config-ensure-section` writes (`buildConfigDefaults()` in `config.cjs`). `/pan:new-project` writes a smaller config of its own (`mode`, `depth`, `parallelization`, `commit_docs`, `model_profile` and the `workflow` agent toggles, plus `workflow.auto_advance` under `--auto`; if you accept your saved defaults it writes those instead), and keys it leaves out read their hardcoded defaults. Only a config `config-ensure-section` creates starts `brave_search` at `true` when a Brave key is detected. The nested `planning.{commit_docs, search_gitignored}` and `git.{branching_strategy, …}` forms written by older versions are read only when the flat key is absent — configs `config-ensure-section` creates carry every flat key and `/pan:new-project` configs carry a flat `commit_docs`, so set the flat keys.
+
+### Core Settings
+
+| Setting | Options | Default | What it Controls |
+|---------|---------|---------|------------------|
+| `mode` | `interactive`, `yolo` | asked by `/pan:new-project` (`--auto`: `yolo`) | `yolo` auto-approves decisions; `interactive` confirms at each step |
+| `depth` | `quick`, `standard`, `comprehensive` | asked by `/pan:new-project` (`--auto`: `quick`) | Planning thoroughness: 3-5, 5-8, or 8-12 phases |
+| `model_profile` | `quality`, `balanced`, `budget` | `balanced` | Model tier for each agent (see table below), and how much ceremony: `balanced` and `budget` size each phase and quick task (a precisely specified one gets its plan from the engine, with no planner, plan-checker or test-generation agent; one code review pass, the verifier and every gate still run); `quality` runs the full ceremony on everything, every agent on the reasoning tier |
+| `workflow.ceremony` | `auto`, `full` | `auto` | `full` keeps the full ceremony on every piece of work without changing models; `--quality` does it for one run |
+| `workflow.lean_max_requirements` | number | `5` | The most tasks in one engine-written lean plan; a lean phase with more requirements is split into several plans run in order. Above three times this (15) a phase goes to the planner, since one session holds a lean phase |
+| `parallelization` | `true`, `false` | `true` | Execute independent plans within a wave in parallel |
+| `brave_search` | `true`, `false` | `false`; `true` in a config `config-ensure-section` creates while a Brave key is detected (`/pan:new-project` does not set it) | Make the phase researcher (`/pan:plan-phase`, `/pan:plan-phase --research-only`) search with Brave instead of the built-in web search; the `/pan:new-project` and `/pan:milestone-new` researchers never read it (the search needs the `BRAVE_API_KEY` env var; `~/.pan-wizard/brave_api_key` only pre-sets this key) |
+| `routing.strategy` | `static`, `complexity` | `static` | How model tiers are adjusted at runtime |
+| `routing.provider` | `auto`, `anthropic`, `openai`, `google` | `auto` | LLM provider for tier→model mapping |
+| `routing.max_escalations` | `0` or more | `1` | How many tiers a retry after a failure may climb (`fast → mid → reasoning`, never above the agent's quality tier). Only the `budget` profile runs agents low enough for it to matter; `/pan:exec-phase --gaps-only` retries on the escalated tier |
+
+### Planning Settings
+
+| Setting | Options | Default | What it Controls |
+|---------|---------|---------|------------------|
+| `commit_docs` | `true`, `false` | `true` | Whether `.planning/` files are committed to git |
+| `search_gitignored` | `true`, `false` | `false` | Reserved — read by `loadConfig` and reported by `init map-codebase`, but no workflow or agent acts on it, so no search adds `--no-ignore` |
+| `memory.auto_optimize` | `true`, `false` | `true` | Reconcile the always-loaded project memory (dedupe / cap-with-archive state.md's append-heavy sections) automatically at the focus-auto checkpoint and normal-flow session record. No-op when already lean; opt out to reconcile only via `pan-tools memory optimize`. |
+| `budget.verify_reserve` | `0`–`0.5` | `0.15` | Fraction of the spawn budget held back for re-verification so the quality gate isn't starved. Surfaced as an indicator always; a hard early stop only when `budget.enforce` / `--enforce-budget` is on. Per-run override: `--verify-reserve`. |
+
+> **Note:** If `.planning/` is in `.gitignore`, `commit_docs` is automatically `false` regardless of the config value.
+
+### Workflow Toggles
+
+| Setting | Options | Default | What it Controls |
+|---------|---------|---------|------------------|
+| `workflow.research` | `true`, `false` | `false` | Research before planning each phase (opt-in): the workflow writes at most 5 open questions that block building and one researcher answers them, each with a source or a recorded assumption. A config that already says `true` keeps it; `/pan:plan-phase N --research` researches one phase |
+| `workflow.plan_check` | `true`, `false` | `true` | Plan verification loop: 2 checks (one revision) on the sized ceremony, 3 checks (2 revisions) under `quality`, `workflow.ceremony: full` or `--quality`; a lean phase is checked by the engine instead |
+| `workflow.verifier` | `true`, `false` | `true` | Post-execution verification against phase goals |
+| `workflow.nyquist_validation` | `true`, `false` | `false` | Validation architecture research during plan-phase; adds the Nyquist plan-check dimension. Off by default — opt-in via `pan-tools config-set workflow.nyquist_validation true`. |
+| `workflow.auto_advance` | `true`, `false` | `false` | Chain discuss → plan → execute → verify → transition without prompting. **Scope:** within a phase the chain is automatic; at a phase boundary a chain that `/pan:plan-phase` drives stops (it runs exec-phase with `--no-transition`) and prints the next command; PAN's stop guard then blocks the session's stop once and tells the agent to spawn the next phase; a direct `/pan:exec-phase --auto` hands over to `transition.md`, which spawns the next phase as a Task subagent and, at the end of the milestone, turns `auto_advance` off and stops, showing `/pan:milestone-done` as the next step. Equivalent to passing `--auto` to `/pan:discuss-phase`, `/pan:plan-phase` and `/pan:exec-phase`. |
+| `hooks.guard` | `off`, `report`, `enforce` | `report` | The pre-tool guard hook (Claude Code, Codex, Gemini CLI, Copilot CLI). `report` logs each credential written into a file, direct write to PAN's state, or edit to a test the phase does not declare, to `.planning/guard.jsonl`; `enforce` also denies the credential write, the direct state write (state.md goes through `pan-tools state` verbs), and a judge agent's write outside `.planning/`. |
+| `workflow.phase_gate` | `enforce`, `warn` | `enforce` | The phase gate `phase complete` runs first: summaries for every plan, a passing and fresh verification, approved human items, a clean reconcile, no open critical or high finding, no committed stub, no weakened test. `warn` marks the phase complete and reports what failed (exec-phase then does not auto-advance); `enforce` refuses until each reason is fixed, or until `phase complete <N> --force --reason "<why>"`, which records the override. `pan-tools phase gate <N>` runs the gate alone. |
+| `workflow.mutation_gate` | `off`, `report`, `gate` | `report` | The mutation report `/pan:verify-phase` runs on the phase's changed lines once the test gate passes (`pan-tools verify mutate`). `report` lists the mutants the suite did not kill and never refuses; `off` runs nothing; `gate` (opt-in) turns a score below `workflow.mutation_floor` into gaps: the verification goes to `gaps_found`, and `verify reconcile` refuses a passed one |
+| `workflow.mutation_floor` | 0 to 1 | `0.6` | The share of sampled mutants the suite must kill in `gate` mode |
+| `workflow.review_mode` | `single`, `lenses` | `single` | `lenses` runs the code reviewer once per lens (correctness, security, maintainability) and keeps the findings a quorum of passes reported (`pan-tools review vote`) |
+| `workflow.cross_family_review` | `off`, `claude`, `codex`, `copilot`, `gemini`, `opencode` | `off` | A host to run one more, read-only review on during `/pan:review-deep`, so a second model family checks the change (`pan-tools review cross-family`). The host's CLI must be installed and signed in; the run spends on that host |
+| `workflow.worktree_isolation` | `true`, `false` | `false` | On Claude Code, the native `/pan-exec-waves` script runs each executor in its own git worktree (`agent({isolation: "worktree"})`). Plans of a wave that share a file always run one after the other |
+| `budget.max_usd_run`, `budget.max_usd_day` | dollars or `null` | `null` | `/pan:autodev`'s spend caps per run and per day; a run needs a run cap, here or as `--max-usd` |
+| `workflow.phase_record_compact` | `true`, `false` | `false` | When combined with the lightweight-phase bypass (1-plan trivial phases, which already skip per-phase research), plan-phase writes one `${N}-record.md` (goal, locked decisions, plan summary, must_haves) in place of a per-phase context.md; execution still writes each plan's summary.md. Substantive phases (more than one plan, or more than scaffolding, config, docs or a single-file feature) ignore this flag. |
+| `workflow.phase_reports` | object: `enabled`, `open`, `theme`, `index` | `{ "enabled": false, "open": false, "theme": "auto", "index": true }` | With `enabled: true`, `/pan:exec-phase` writes the phase's HTML report (as `/pan:report phase` does) at the verify→complete gate, plus the timeline index `.planning/report-index.html` when `index` is true, and adds them to the completion commit; `/pan:focus-auto` checkpoints and `/pan:army` missions render them too. `open` and `theme` are written but not read, and no automatic run opens a browser. |
+| `workflow.stop_guard` | `true`, `false` | absent (guard on) | `false` turns off PAN's stop guard, which otherwise blocks a session's stop once while `workflow.auto_advance` is true or `mode` is `yolo` and unbuilt roadmap phases remain, unless state.md records failed verification, gaps or a blocker (Claude Code, Codex, Gemini CLI, Copilot CLI) |
+
+Disable these to speed up phases in familiar domains or when conserving tokens.
+
+### Budget Settings
+
+| Setting | Options | Default | What it Controls |
+|---------|---------|---------|------------------|
+| `budget.default_points` | number | `50` | The point budget `init execute-phase` reports as `total_budget_points` (and `budget_exceeded` when the plans' estimated points pass it); `pan-conductor` (`/pan:exec-phase --hierarchical`) takes its points budget from `total_budget_points`; no workflow reads either field, and the focus commands keep their own defaults (no range validation) |
+| `budget.micro_threshold_tasks` | number | `3` | Task-count ceiling (inclusive) at or below which — together with `micro_threshold_files` — `init execute-phase` classifies a plan as MICRO (`classifyPlanTier`); an explicit plan `tier:` overrides |
+| `budget.micro_threshold_files` | number | `2` | File-count ceiling for the same MICRO classification |
+| `budget.enforce` | `true`, `false` | `false` | Make the point budget a hard stop; advisory (tracked, never stops a run) by default |
+| `cost.phase_budget_usd` | dollars, `0` = off | `20` | Spend per phase PAN warns about, in API-equivalent dollars: `near` from 80%, `over` at the budget, reported after each exec-phase wave and in plan-phase's final status. It only warns, never stops. Set it with `/pan:settings`; `pan-tools cost budget --phase N` shows it |
+| `cost.weekly_limit_stop_pct` | `0`–`100` | `90` | Stop a `/pan:focus-auto` run (resumable) or an `/pan:army` campaign once Claude Code's 7-day usage window reaches this share, as the status line last saw it (`pan-tools cost limits`); `0` turns it off. Interactive Claude Code sessions on a subscription only: headless runs and other runtimes have no reading, so nothing stops on it there |
+
+### Commit Safety Settings
+
+| Setting | Options | Default | What it Controls |
+|---------|---------|---------|------------------|
+| `commit.safety_checks` | `true`, `false` | `true` | Enable deleted-file and sensitive-file checks before commit |
+| `commit.conventional_types` | `true`, `false` | `true` | Reserved — written by the defaults but not read; `--type` is always accepted and validated against `feat`, `fix`, `docs`, `test`, `refactor`, `perf`, `chore` |
+| `commit.sensitive_patterns` | array of regex | See default | File patterns blocked from commits (`.env`, `.pem`, etc.) |
+
+### Execution Settings
+
+| Setting | Options | Default | What it Controls |
+|---------|---------|---------|------------------|
+| `execution.default_mode` | `wave_order` | `wave_order` | Reserved — `init execute-phase` reports it as `execution_mode`, which no workflow reads; plans always run in wave order |
+| `execution.rollback_snapshots` | `true`, `false` | `true` | Reserved — written by the defaults but not read; no workflow creates rollback tags, so run `pan-tools rollback-snapshot <phase>` yourself before a risky phase |
+| `execution.error_pattern_learning` | `true`, `false` | `true` | Tool-failure capture: the trace hook records the failed tool calls in each subagent's own transcript (redacted) as `error/tool_error` events for `/pan:learn`. `false` turns the capture off (see [The evidence loop](#the-evidence-loop)) |
+
+### Git Branching
+
+| Setting | Options | Default | What it Controls |
+|---------|---------|---------|------------------|
+| `branching_strategy` | `none`, `phase`, `milestone` | `none` | When and how branches are created |
+| `phase_branch_template` | Template string | `pan/phase-{phase}-{slug}` | Branch name for phase strategy |
+| `milestone_branch_template` | Template string | `pan/{milestone}-{slug}` | Branch name for milestone strategy |
+
+**Branching strategies explained:**
+
+| Strategy | Creates Branch | Scope | Best For |
+|----------|---------------|-------|----------|
+| `none` | Never | N/A | Solo development, simple projects |
+| `phase` | At each `exec-phase` | One phase per branch | Code review per phase, granular rollback |
+| `milestone` | At first `exec-phase` | All phases share one branch | Release branches, PR per version |
+
+**Template variables:** `{phase}` = zero-padded number (e.g., "03"), `{slug}` = lowercase hyphenated name, `{milestone}` = version (e.g., "v1.0").
+
+### Model Profiles (Per-Agent Breakdown)
+
+PAN uses abstract tier names (`reasoning`, `mid`, `fast`) that map to provider-specific models. On Anthropic: reasoning → `inherit` (the model your session runs on), mid → Sonnet, fast → Haiku. On OpenAI/Google: reasoning → inherit, mid/fast → provider equivalents. Under OpenCode, mid/fast resolve to OpenCode's `provider/model` ids, with the provider taken from the `model` in the project's `opencode.json` or `.opencode/opencode.json` (a model set only in OpenCode's global config is not read) when neither `routing.provider` nor `PAN_PROVIDER` names one (and from the runtime directories, where `.opencode/` alone counts as OpenAI, when that names none either).
+
+| Agent | `quality` | `balanced` | `budget` |
+|-------|-----------|------------|----------|
+| pan-planner | reasoning | reasoning | mid |
+| pan-roadmapper | reasoning | reasoning | mid |
+| pan-executor | reasoning | reasoning | mid |
+| pan-phase-researcher | reasoning | mid | fast |
+| pan-project-researcher | reasoning | mid | fast |
+| pan-debugger | reasoning | reasoning | mid |
+| pan-document_code | reasoning | reasoning | fast |
+| pan-verifier | reasoning | reasoning | fast |
+| pan-plan-checker | reasoning | mid | fast |
+| pan-integration-checker | reasoning | reasoning | fast |
+| pan-reviewer | reasoning | reasoning | fast |
+
+The table shows the core agents. Every other agent is on `reasoning` under `quality` and `balanced` too; `MODEL_PROFILES` in `core.cjs` has each one's `budget` tier. `balanced` differs from `quality` only in the researchers and the plan-checker (mid tier) and in the ceremony it runs (see `model_profile` above).
+
+**Profile philosophy (cost reset):**
+- **quality** and **balanced** -- Every agent runs on the `reasoning` tier, i.e. **`inherit` — the model you launched with** (under `balanced`, the researchers and the plan-checker run on the mid tier; a few review agents pin their own model; see the note below). PAN respects your model choice by default and does not silently demote agents to cheaper models; context isolation (each subagent in its own window), not a weaker model, is what keeps the main conversation clean.
+- **budget** -- The opt-in cheap mode: mid for code-writing agents, fast for research and verification. Choose it explicitly for high-volume or less-critical work. Cheapness is opt-in, not the default.
+
+> Model tiering takes effect where a PAN workflow passes the resolved tier as a Task spawn's `model` (from `init` or `resolve-model`), and it is what `pan-tools estimate-cost` (shown by `/pan:settings --profile`) prices — `/pan:cost` does not use it, since the hooks take each record's tier from the model id they record; a spawn that passes no model uses the agent file's static `model:` — unset means `inherit`. A few security-review agents deliberately pin `model: opus` in their own frontmatter; `grep -l '^model: opus' .claude/agents/*.md` lists them (`~/.claude/agents/` in a global install).
+
+### Routing Strategies
+
+The `routing.strategy` setting controls how tiers are adjusted at runtime:
+
+- **static** (default) -- Profile assigns fixed tiers. Predictable, no surprises.
+- **complexity** -- Adjusts tiers up or down from task metadata (file count, wave count, requirements, architecture flag) passed to `pan-tools resolve-model --metadata`. No workflow passes that metadata today, so a first attempt resolves as it does under `static`. Under `budget` it also cancels the `/pan:exec-phase --gaps-only` escalation: the retry carries only its attempt number, scores as a simple task and drops a tier before it climbs one.
+
+### Cost Estimation
+
+Run `pan-tools estimate-cost` to see relative cost multipliers before switching (`/pan:settings --profile <profile>` shows them after it switches). Cost tiers: reasoning = 15×, mid = 3×, fast = 1×.
+
+### Per-Phase Model Override
+
+`pan-tools resolve-model <agent> --metadata '{"phaseNum":"3"}'` reads a per-phase tier from an HTML comment in that phase's roadmap section. No workflow passes the phase today: `init plan-phase` and `init execute-phase` resolve every agent without it, so the comment does not change the model a phase's agents run on. Use `model_overrides` to change an agent's tier. The comment looks like this:
+
+```markdown
+## Phase 3: Quick UI polish
+**Goal:** Style cleanup
+<!-- model_tier: fast -->
+```
+
+Per-phase overrides sit between per-agent overrides (highest priority) and profile lookup (lowest priority).
+
+---
+
+## Usage Examples
+
+### New Project (Full Cycle)
+
+```bash
+claude --dangerously-skip-permissions
+/pan:new-project            # Answer questions, configure, approve roadmap
+/clear
+/pan:discuss-phase 1        # Lock in your preferences
+/pan:plan-phase 1           # Plan + verify (add --research to research first)
+/pan:exec-phase 1        # Parallel execution
+/pan:verify-phase 1          # Goal-backward verify + test gate
+/clear
+/pan:discuss-phase 2        # Repeat for each phase
+...
+/pan:milestone-audit        # Check everything shipped
+/pan:milestone-done 1.0 # Archive, tag, done
+```
+
+### New Project from Existing Document
+
+```bash
+/pan:new-project --auto @prd.md   # Requirements and roadmap from your doc (research only with --research), then chains discuss → plan → execute → verify for phase 1
+/clear
+/pan:discuss-phase 2 --auto       # the next command the chain prints, if the run stopped at the boundary (the stop guard first blocks one stop and tells the agent to spawn the next phase); for step-by-step runs set Auto-advance to No in /pan:settings and workflow.stop_guard to false (--auto writes mode: yolo, which keeps the stop guard armed)
+```
+
+### Existing Codebase
+
+```bash
+/pan:map-codebase           # Analyze what exists (one agent, or several in parallel above the size threshold)
+/pan:new-project            # Questions focus on what you're ADDING
+# (normal phase workflow from here)
+```
+
+### Quick Bug Fix
+
+```bash
+/pan:quick
+> "Fix the login button not responding on mobile Safari"
+```
+
+### Resuming After a Break
+
+```bash
+/pan:progress               # See where you left off and what's next
+# or
+/pan:resume            # Full context restoration from last session
+```
+
+### Preparing for Release
+
+```bash
+/pan:milestone-audit        # Check requirements coverage, detect stubs
+/pan:milestone-audit --gaps    # If audit found gaps, create phases to close them
+/pan:milestone-done 1.0 # Archive, tag, done
+```
+
+### Speed vs Quality Presets
+
+| Scenario | Mode | Depth | Profile | Research | Plan Check | Verifier |
+|----------|------|-------|---------|----------|------------|----------|
+| Prototyping | `yolo` | `quick` | `budget` | off | off | off |
+| Normal dev | `interactive` | `standard` | `balanced` | off (the default) | on | on |
+| Production | `interactive` | `comprehensive` | `quality` (full ceremony, every agent on the reasoning tier) | on (`workflow.research: true`) | on | on |
+
+### Mid-Milestone Scope Changes
+
+```bash
+/pan:add-phase "Add audit logging"   # Append a new phase to the roadmap
+# or
+/pan:insert-phase 3 "Hotfix rate limiter"   # Insert urgent work between phases 3 and 4
+# or
+/pan:remove-phase 7         # Descope phase 7 and renumber
+```
+
+---
+
+## Advanced Features
+
+### Native Workflows (Claude Code only)
+
+Claude Code can run orchestration as a **script** rather than as prose the model follows: the script holds the loop, the fan-out and the intermediate results, so the model's context holds only the final answer, and a step cannot be skimmed past. PAN ships a small set of these to `.claude/workflows/` on every Claude install (and inside the Claude plugin), each a deterministic port of one PAN protocol:
+
+| Command | Ports | What it does |
+|---|---|---|
+| `/pan-review-pipeline [phase or change set]` | `/pan:review-deep` | Reviewer and security hardener in parallel, then the meta-reviewer merges and issues one verdict |
+| `/pan-map-codebase` | `/pan:map-codebase` | Discovers the top-level areas, documents each in parallel, synthesises one overview |
+| `/pan-exec-waves <phase>` | `/pan:exec-phase` wave dispatch | Reads the plan index, runs one executor per plan wave by wave (parallel within a wave unless `parallelization` is off), halts before the next wave on a failed plan, then runs the phase verifier unless `workflow.verifier` is off (then it says verification was skipped) |
+| `/pan-diagnose-issues <phase>` | the `diagnose-issues` protocol (`workflows/diagnose-issues.md`, which `/pan:verify-phase N --uat` follows on every runtime for the gaps it records) | One debugger per failed UAT truth, in parallel, root cause only; writes the diagnoses back into the UAT gaps |
+
+Two rules govern them. **They are additive**: the markdown commands remain the portable path and the only path on the other four runtimes, and the scripts never replace them. **They only port protocols whose control flow is known before the run** — a fixed fan-out, a wave that is genuinely a barrier. A step that depends on reading the last result stays in markdown, and a script never pretends to pause for you: `/pan-exec-waves` refuses a phase that contains checkpoint plans and tells you to run `/pan:exec-phase` instead.
+
+**Measured, not assumed.** PAN's behavioural harness ran both paths on the same two-plan seed, five reps each (September 2026, Claude Code `2.1.233`): the markdown `/pan:exec-phase` completed every rep, and so did `/pan-exec-waves`, with the phase verifier's file written every time, about 15% faster and a few percent cheaper per rep. On Claude Code the native workflow is the recommended way to run a checkpoint-free phase; the markdown command stays the portable path and the fallback for phases with checkpoints. One caveat for headless or CI use: `claude -p` waits at most ten minutes for a background workflow before stopping it and dropping its result — set `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS=0` (or a higher ceiling) when driving these workflows from a script. Interactive sessions are unaffected.
+
+**Host controls that shape these runs** (Claude Code; each checked against the official Claude Code documentation on 2026-09-28):
+
+- **Concurrency.** `CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS` caps how many agents a workflow script runs at once. The value is an integer from 1 to 256; the default is 16, or fewer on a machine with fewer CPUs. A wide wave in `/pan-exec-waves` queues behind this cap rather than failing, so lower it when parallel executors contend for a shared resource such as a database or a port.
+- **Permissions for headless runs.** A headless run has nobody to approve a tool. When its permission mode does not already allow the Workflow tool, add a permission rule: `Workflow` for every workflow, or `Workflow(pan-exec-waves)` for one by name.
+- **Cache visibility.** `/usage` includes a `Prompt cache (main)` line with the hit ratio, the miss count, whether the cache is warm or cold, and the likely cause of the last miss. Read it next to `/pan:cost` when a long session costs more than it should.
+- **Scripted plugin installs.** `claude plugin install <plugin> --json` prints one JSON object (the outcome, a message and, on failure, a failure code) instead of text, for setup scripts that install the PAN plugin.
+
+Each script names the markdown protocol it ports, and a test pins the pair so they cannot drift apart silently. Run them like any other slash command; `/workflows` shows progress per phase and per agent.
+
+### The Evidence Loop
+
+PAN's judges decide whether work passed: the plan checker, the reviewer, the design checker and the verifier. Their verdicts, what they found, and what was done about each finding are kept on record in `.planning/findings.jsonl`. The optimisation loop sees the failures that happen inside subagents.
+
+- **Verdicts on the record.** Each judge's report ends with a machine-readable verdict: a fenced `pan-verdict` block, or the verifier's verification.md frontmatter. The workflows save each report in the phase directory (`NN-review.md`, `NN-plan-check.md`, `NN-design-check.md`, `NN-verification.md`) and record it with `pan-tools findings record`. They branch on the verdict the record prints and fall back to the old heading or `status:` read when a report has no valid verdict; exec-phase's auto-advance decision comes from the phase gate that `phase complete` runs (`pan-tools phase gate`).
+- **Fix rounds close their findings on evidence.** A re-verification after a gap-closure round is the next attempt. The gaps it lists under `re_verification.gaps_closed` (or that a judge answers `resolved` with evidence) are marked fixed, and the retry is logged. A finding the new report neither repeats nor answers stays open.
+- **Nothing is continued past silently.** When a phase moves on past open review, plan-check or design findings, the workflow records the reason. Findings nothing disposes stay `open` until you dispose them: the rows of a plain `PASS` review or a passing plan or design check, `unrequested` work, and human-verification items (a `PASS_WITH_WARNINGS` review defers all its open rows, INFO included). Examples of recorded reasons: warnings accepted at review, "continue anyway" at `NEEDS_FIXES`, "force proceed" after the third plan check. You can dispose findings yourself, too: `pan-tools findings dispose <id> --as deferred|dismissed|decision --reason "…"`. A reason is required.
+- **A dismissal teaches the ledger, until the file changes.** After you dismiss a finding, the same judge raising it again is filtered while its file is unchanged: in that phase at first, and in every phase once you have dismissed it in two. When the file changes, the finding comes back. Security and logic findings, and findings that name no file, are never filtered. `pan-tools findings suppressions` lists what is being filtered.
+- **Milestone audits read the record.** `/pan:milestone-audit` takes its tech debt from `pan-tools findings debt`, the deferred findings with their reasons. It lists the findings nobody disposed, instead of reconstructing either from prose.
+- **Unrequested work is a finding.** The verifier runs `pan-tools verify scope <phase>`, which lists the files the phase changed that no plan declared. Whatever it judges to be work nobody asked for is recorded as `unrequested`. That finding does not fail the phase; keeping or removing the work is your decision.
+- **Failures inside subagents reach `/pan:learn`.** On Claude Code the trace hook records the failed tool calls in a subagent's own transcript, redacted and grouped by tool and message (capped per spawn; the completion keeps the total): a failing test run, a missing file, a refused permission. `/pan:learn` ranks them by how often they recur across spawns and sessions. `/pan:learn --sessions 5` pools the last five sessions, so a suggestion rests on a pattern, not on one run's accident.
+- **Applies can be undone.** `/pan:learn --optimize apply` records exactly what it wrote. `/pan:learn --optimize revert <apply_id>` (or `--last`) undoes one apply byte for byte, and refuses files someone edited since. Applying the same report twice writes nothing the second time.
+
+`pan-tools findings list` shows the ledger, filtered by phase, agent, status, class or milestone. MCP clients read the same data as `pan://findings`.
+
+### Self-Improvement Loop
+
+PAN Wizard ships a **cross-project meta-learning loop** that lets PAN itself get smarter every release. Run experiments against fresh ideas in isolated folders, harvest the resulting telemetry back to the source repo, promote generalizable findings into shipped artifacts that future installs read automatically.
+
+**The loop:**
+
+```bash
+# 1. Capture an idea (use the template at pan-wizard-core/templates/idea.md)
+echo "# Idea: <title>
+## Problem
+...
+## Success Criteria
+...
+## Scope
+...
+## Constraints
+..." > my-idea.md
+
+# 2. Scaffold an isolated experiment
+pan-tools experiment new my-idea --idea my-idea.md --runtime claude --budget 60
+
+# 3. Run the external session (autonomous; observation-only watchdog)
+pan-tools experiment run my-idea
+
+# 4. Harvest telemetry back to <source-repo>/experiments/my-idea/
+pan-tools experiment harvest my-idea
+
+# 5. Analyze with pan-optimizer
+/pan:learn --experiment my-idea
+
+# 6. Promote select findings (manual gate by design — no auto-promote yet)
+pan-tools learn promote --pattern P-007 --scope universal --topic exec-patterns \
+  --summary "..." --rule "..." --evidence "..." --source-experiments my-idea
+
+# 7. Validate the patterns store (catches duplicates, dangling refs, scope leaks)
+pan-tools learn lint --raw
+
+# 8. Refresh the topic→agent index so workflows can budget-load relevant patterns
+pan-tools learn build-index --raw
+```
+
+**Two-tier learnings layout:**
+
+- `pan-wizard-core/learnings/universal/` — ships to all 5 runtimes; consumed by user-project workflows. Includes patterns like atomic-state, concurrency, idempotency, secret-handling, test-patterns.
+- `pan-wizard-core/learnings/internal/` — source-only; PAN-development patterns that should NOT leak to user installs.
+- `pan-wizard-core/learnings/index.json` — generated topic→agent-relevance map. Workflows query it via `pan-tools learn topics-for --agent <role> --cue "<the task>" --token-budget N` to load only the topics that match the task, falling back to the role's tagged topics when none does, instead of skim-everything (avoids the distractor-density anti-pattern from external research).
+
+The installer (`bin/install.js`) explicitly strips `learnings/internal/` from each install dir. A negative test in `tests/scenarios/learnings-installed.test.cjs` enforces this.
+
+**Patterns-store maintenance commands:**
+
+| Command | Purpose |
+|---------|---------|
+| `pan-tools learn promote --pattern <id> --scope <s> --topic <t>` | Append a finding to `learnings/{scope}/{topic}.md` |
+| `pan-tools learn unpromote --pattern <id> --scope <s> --topic <t>` | Remove a finding |
+| `pan-tools learn list-promoted` | Inventory of all patterns across both scopes |
+| `pan-tools learn lint [--strict]` | Integrity checks (L-001..L-007); exits non-zero on errors |
+| `pan-tools learn build-index` | Generate/refresh `learnings/index.json` |
+| `pan-tools learn topics-for --agent <role> [--cue <task>]` | Budget-aware topic selection for an agent; with `--cue`, the topics that match the task |
+
+**Subcommands of `/pan:experiment`:**
+
+| Subcommand | Wave | Purpose |
+|------------|------|---------|
+| `new <slug>` | W1 | Scaffold an experiment folder |
+| `list` | W1 | Enumerate experiments |
+| `manifest <slug>` | W1 | Read scaffold metadata |
+| `run <slug>` | W2 | Spawn external AI session, observe |
+| `status <slug>` | W2 | Read run-state.json snapshot |
+| `stop <slug>` | W2 | Reconcile a run's state after the fact; it cannot halt a run in flight (the synchronous runner records no pid until the run exits) |
+| `harvest <slug>` | W3 | Copy telemetry back to source repo |
+| `prune <slug>` | W3 | Soft-rename or hard-delete the experiment folder |
+
+**Runtime support:**
+
+The experiment runner uses `spawnSync` to invoke external AI runtimes headlessly:
+- ✅ Claude Code (`claude -p <prompt>`)
+- ✅ Codex CLI (`codex exec <prompt>`)
+- ✅ Gemini CLI (`gemini -p <prompt>`)
+- ✅ OpenCode (`opencode <prompt>`)
+- ❌ GitHub Copilot CLI — the runner has no adapter for it (`RUNTIME_RUNNERS.copilot` is `null`), so `experiment run` refuses it; scaffold and harvest still work
+
+**Spec & ADR:**
+
+- Design: `docs/specs/self_improvement_loop_featureai.md`
+- Decisions: `docs/decisions/ADR-0026-self-improvement-loop.md`
+
+### AI Agent Guardrails
+
+PAN Wizard ships `references/guardrails.md` — a consolidated rules doc that the phase workflows (`new-project`, `plan-phase`, `exec-phase`, `execute-plan`, `verify-phase`) and the planner, designer and reviewer agents load. It encodes anti-patterns (silent model swaps, skipping verification, scope creep), the **Code Preservation Principle** (surgical edits only — preserve config values, comments, formatting outside the user's explicit target), and the **Stop-the-Line Rule** (regressions halt feature work, no "I'll circle back").
+
+This doc is read by your AI coding agent (Claude, Codex, Gemini, OpenCode, Copilot) at the start of every phase. You don't need to interact with it directly, but you can review the installed copy at:
+
+| Runtime | Path |
+|---------|------|
+| Claude  | `.claude/pan-wizard-core/references/guardrails.md` |
+| Codex   | `.codex/pan-wizard-core/references/guardrails.md` |
+| Gemini  | `.gemini/pan-wizard-core/references/guardrails.md` |
+| OpenCode | `.opencode/pan-wizard-core/references/guardrails.md` |
+| GitHub Copilot | `.github/pan-wizard-core/references/guardrails.md` |
+
+The long workflows (`exec-phase`, `plan-phase`, `verify-phase`, `execute-plan`) gain `## Re-Read Checkpoints` sections that direct the agent to re-read specific sections at boundaries — preventing context-compaction drift across long sessions. `new-project.md` gates scaffolding behind a mandatory Phase 0 clarify step (problem / success / scope / constraints).
+
+If your agent ever skips `/pan:verify-phase` "because tests passed" or silently changes a model, point it at this reference.
+
+### Advanced Planning Options
+
+The `/pan:plan-phase` command accepts several flags to customize planning behavior:
+
+| Flag | Purpose |
+|------|---------|
+| `--prd <file>` | Use a PRD/acceptance criteria file instead of discuss-phase. Parses requirements into context.md automatically. Skips discussion entirely. |
+| `--skip-research` | Skip research phase, go straight to planning (useful for familiar domains) |
+| `--research` | Research this phase (research is opt-in); also re-researches when research.md already exists |
+| `--gaps` | Gap closure mode: reads verification.md and creates fix plans |
+| `--skip-verify` | Skip the plan verification loop |
+
+Example:
+
+```bash
+/pan:plan-phase 3 --prd specs/auth-requirements.md
+```
+
+### Execution Model
+
+**Wave-Based Parallelization:**
+
+Plans within a phase are grouped by wave number (from plan.md frontmatter `wave: N`). Waves execute sequentially, but plans within a wave execute in parallel (when `parallelization: true` in config).
+
+Wave 1 plans have no dependencies. Wave 2 plans depend on Wave 1 output. This is how PAN safely parallelizes work.
+
+**Deviation Rules:**
+
+During execution, the pan-executor automatically handles unexpected issues:
+
+| Rule | Trigger | Action | Example |
+|------|---------|--------|---------|
+| Rule 1 | Bug in code | Auto-fix | Logic errors, null pointers, type errors |
+| Rule 2 | Missing critical functionality | Auto-add | Missing validation, error handling, auth checks |
+| Rule 3 | Blocking issue | Auto-fix | Missing dependency, broken imports, build errors |
+| Rule 4 | Architectural change needed | STOP and ask | New DB table, schema changes, library switches |
+
+Rules 1-3 are applied automatically (up to 3 fix attempts per task). Rule 4 creates a checkpoint requiring user decision.
+
+**Gap Closure:**
+
+After verification reports `gaps_found`, run `/pan:plan-phase N --gaps` to create the fix plans (`gap_closure: true`), then `/pan:exec-phase N --gaps-only` to execute only those.
+
+**Checkpoint Automation:**
+
+When `workflow.auto_advance: true` in config:
+
+| Checkpoint | Behavior |
+|------------|----------|
+| `checkpoint:human-verify` | Auto-approved (skips visual verification) |
+| `checkpoint:decision` | Takes the option the task's `auto_select` names; stops for you when it has none |
+| `checkpoint:human-action` | Still stops (auth gates cannot be automated) |
+
+### Bot-army campaigns (`/pan:army`)
+
+**This is PAN's headline capability — ship a whole project, not just a phase.** `/pan:army` runs PAN's agents as a coordinated army: **Mission Control** (the reasoning-tier conductor) plans the mission and delegates to specialist squads, parallel builders each work an isolated git worktree, and nothing reaches your main branch without green checks and your approval (ADR-0032 squads · ADR-0033 campaign). It composes the pieces you already use: the `pan-conductor` safety harness, the focus-auto work loop, git worktrees, and the `/pan:retro` and `/pan:learn` reports.
+
+**Taking on an existing project.** The army never plans blind. On a brownfield repo, Phase 0 runs an onboarding gate: if existing code has no codebase map yet, it stops and routes you through `/pan:map-codebase` (its `pan-document_code` mappers — workers in `pan-tools squad list`, not Architecture squad members — map the system into `.planning/codebase/`) and `/pan:new-project` (builds `roadmap.md` / `requirements.md` *against the existing system*), then you re-run `/pan:army`. From there, the Architecture squad reads the existing contracts before Build touches anything, and every Build agent forks its `army/<task>` branch from the commit you have checked out (`worktree create` bases it on `HEAD`) — so the existing code is never edited in place. For a greenfield repo, you go straight to the plan.
+
+**The tiers.** Mission Control — the reasoning-tier `pan-conductor`, elevated to campaign scope — plans the goal and delegates rather than implementing. Work flows to the squads, each carrying an intended access contract:
+
+| Squad | Role | Access |
+|-------|------|--------|
+| Architecture | Design the contract before code | `read-only` |
+| Build | Turn the contract into committed code | `read-write-bash` |
+| Quality | Adversarially break what Build makes | `read-only` |
+| Release | Ship behind a human gate | `always-ask` |
+
+Inspect the roster any time with `pan-tools squad list` and `pan-tools squad show <name>`.
+
+**What the Access column is.** The `access` values `pan-tools squad list` reports — a role contract PAN's prompts assign, not a sandbox. `squads.cjs` is a registry that "modifies no agent and changes no execution path", so a label can differ from what an agent may actually do: several `read-only` squad members hold `Write` because they emit planning or verification artifacts. What actually constrains an agent is its own `tools:` frontmatter (`grep '^tools:' .claude/agents/*.md`, or `~/.claude/agents/*.md` in a global install), and Mission Control's grant includes `Write` and `Bash` — "delegates rather than implements" is how it is instructed to behave, not something the runtime prevents. The rail the grant does enforce is delegation depth: `grep -l '^tools:.*Task' .claude/agents/*.md` names every agent able to spawn another, so a squad agent cannot fan out further. For the irreversible step, branch protection on your own repo is what makes the human merge gate unbypassable.
+
+**Parallel builds without collisions.** When the Build squad runs several tasks at once, each builder gets its own `army/<task>` branch in an isolated git worktree (`pan-tools worktree list` shows them), so two agents never edit the same working tree. Use `--no-build-worktrees` for small or strictly-serial projects; set `concurrency.serial_build: true` in `.planning/config.json` if your build tree corrupts under concurrent builds.
+
+**Where those worktrees live, and how they leave.** Army worktrees are created as **siblings of your project directory** — a project at `~/code/myapp` gets `~/code/pan-army-<slug>/` — deliberately outside your tree so builders can never dirty it. They are scaffolding, not deliverables: the squash-merge into your protected branch is the permanent artifact. The campaign tears them down in two ways:
+
+- **Per task, after its merge lands** (Phase 5): `pan-tools worktree remove <worktree_path> --branch <branch>`, the two values `worktree create` returned (`../pan-army-<slug>` and `army/<slug>`, the task name slugified). The `--branch` half matters — a squash-merged branch never looks merged to git, so deleting it explicitly is the only way it ever goes away.
+- **At campaign end, and after any abort:** `pan-tools worktree cleanup`. The sweep removes every registered army worktree and its branch, prunes stale registrations, and deletes orphaned `army/*` branches — but it is deliberately cautious by default: a worktree with uncommitted changes, or a branch whose commits aren't reachable from your current branch (which may be the only copy of aborted work), is **kept and listed with the exact command to remove it**. `--force` sweeps those too. It never touches worktrees or branches outside the `army/` namespace.
+
+A finished campaign should leave `pan-tools worktree list` empty. If it doesn't, run the sweep — leftover `pan-army-*` directories are a defect, not a souvenir.
+
+**The loop.** Each cycle runs plan → delegate → execute → review → integrate → learn. Quality must return green before integration; the Release agent (`pan-release`) then prepares the squash-merge, runs your configured `verification` command, and surfaces an `always-ask` approval — a human merges to the protected branch, not a bot. Recovery is always `git revert` or redeploying the previous tag. Between missions, the campaign's learn step runs `/pan:retro` (and `/pan:learn` when traces exist) and names the recurring patterns in the plan for the next mission. Agent memory does not carry them, because PAN does not load it into agents.
+
+**Running it:**
+
+```text
+/pan:army "ship the v1 reporting module" --source backlog --max-cycles 5
+/pan:army "harden auth across the app" --squads architecture,build,quality --clean-seal
+/pan:army "<goal>" --dry-run     # show the plan + squad delegation, run nothing
+/pan:army --status               # campaign progress
+/pan:army --stop                 # graceful halt, state preserved
+```
+
+The same caps that bound hierarchical exec bound the campaign — delegation-depth cap, per-cycle spawn/budget ceiling, and the `.planning/orchestration/abort` kill-switch — so a long campaign never relaxes a single safety rail. Campaign mode is built for Claude Code, because the squads are spawned as native sub-agents. Unlike `/pan:exec-phase --hierarchical`, which warns and runs flat on the other four runtimes, `/pan:army` has no runtime check or fallback of its own, so on those runtimes use the flat phase commands. That's a runtime constraint, not a model one — no model gate exists, and Mission Control runs on whatever model you launched with.
+
+**Running it over days (scheduled, self-resuming).** `--schedule` arms a campaign that advances the backlog on a cadence instead of in one sitting ([ADR-0034](decisions/ADR-0034-scheduled-campaigns.md)):
+
+```text
+/pan:army "burn down the v1 backlog" --schedule daily --daily-budget 200
+```
+
+This writes a schedule descriptor (`.planning/orchestration/schedule.json`) — PAN does **not** run itself in the background (it's not a daemon). You wire an external trigger that polls `pan-tools campaign due` and runs `/pan:army --continue` when it reports due: a host scheduler (Claude Code routines / cron / scheduled tasks) or a `/loop`. Nothing surfaces a due campaign when you next open the project (ADR-0034's session-open nudge is not built), so without a trigger it waits until you run `/pan:army --continue`. The `--daily-budget` is advisory (it surfaces the day's spend) unless the schedule is armed with `--enforce-budget` (`/pan:army --schedule … --enforce-budget`, or `pan-tools campaign schedule --enforce-budget`), which pauses a due run once the day's spend is used up; `--advisory-budget` turns that back off. Manage it with `pan-tools campaign status` (active/paused, spent today, next-due) and `campaign schedule --pause | --resume | --disable`.
+
+**The one thing scheduling never changes:** the merge to a protected branch stays an `always-ask` human gate. A scheduled campaign runs the backlog down to staged, reviewed, green PRs unattended — and waits for you at every merge. Autonomy runs up to the irreversible step, a human at the step.
+
+### Army & project dashboard (`/pan:hud`)
+
+`/pan:hud` (the old name `/pan:dashboard` still works) renders the whole picture of your project and its bot army as a **single, self-contained HTML page** — no server, no network, no external CSS or JS. It's a read-only *view*: every panel aggregates state PAN already tracks (`state.md`, the roadmap/phases on disk, the squad registry, the campaign schedule, army worktrees, the cost ledger, `requirements.md`, verification artifacts, and git history). The command writes only the rendered file, so it can never corrupt planning data.
+
+```text
+/pan:hud                  # write .planning/hud.html
+/pan:hud --open           # write it and launch in your default browser
+/pan:hud --out status.html
+/pan:hud --stdout > dashboard.html   # print HTML instead of writing a file
+```
+
+**What you see:** a mission banner (project, status, version/milestone, and metric cards for progress, current phase, requirements, and spend), the full roadmap with per-phase status, telemetry (spend, tokens, cache-hit rate, by-squad breakdown), requirements-and-quality with the latest verification artifacts, and recent commits.
+
+**On an army project**, four extra panels appear: a command stack showing Mission Control over the four squads with per-squad agent drill-down, the campaign panel (cadence, next-due, daily-budget bar, run history), the safety harness (merge gate, abort switch, active worktrees, budget, concurrency), and the active `army/*` worktrees. These army panels self-hide on a plain (non-army) project, so you always get a complete, useful page (graceful degradation per [ADR-0035](decisions/ADR-0035-army-hud-dashboard.md)).
+
+The file is fully self-contained — send `.planning/hud.html` to anyone and it opens with no dependencies. During a campaign, re-run after each cycle to watch squads, budget, worktrees, and committed output evolve.
+
+**Per-phase reports (`/pan:report`).** Where `/pan:hud` renders the whole project at once, `/pan:report` (`pan-tools report phase <N> | index | all`) reuses the HUD's rendering to produce per-phase HTML reports — one page per phase, plus a project-level timeline index that links them together. Same self-contained, read-only, view-only guarantees as the dashboard.
+
+### Git Integration
+
+**Commit Format:**
+
+PAN uses conventional commits with phase-plan scope:
+
+```text
+{type}({phase}-{plan}): {description}
+```
+
+Types for task commits: `feat`, `fix`, `test`, `refactor`, `perf`, `chore` (`references/git-integration.md`; `workflows/execute-plan.md`, which the executor loads, also lists `docs` and `style`). Planning-doc commits use `docs(...)` through `pan-tools commit`, whose `--type` accepts only `feat`, `fix`, `docs`, `test`, `refactor`, `perf`, `chore`
+
+Example: `feat(03-02): add login endpoint`
+
+**What Gets Committed:**
+
+| Event | Commit |
+|-------|--------|
+| Each completed task | Individual commit by default (the executor may fold adjacent trivial tasks of one type, never `feat` or `fix`, into one commit) |
+| Plan completion | Metadata commit (`docs(XX-YY): complete <plan-name> plan`) |
+| Project init | `docs: initialize project`, `chore: add project config`, `docs: complete project research` (when research runs), `docs: define v1 requirements`, then `docs: create roadmap (N phases)` |
+| Planning docs | Controlled by `commit_docs` config |
+
+**Branching Strategies (Detailed):**
+
+When `branching_strategy: "phase"`:
+- A branch is created at exec-phase start using `phase_branch_template`
+- Example: `pan/phase-03-authentication`
+- All plan commits go to that branch
+- User merges branches after phase completion
+- Template variables: `{phase}` (zero-padded), `{slug}` (hyphenated name)
+
+When `branching_strategy: "milestone"`:
+- First exec-phase of milestone creates milestone branch using `milestone_branch_template`
+- Example: `pan/v1.0-mvp`
+- All phases commit to same branch
+- After `/pan:milestone-done`, merge the milestone branch yourself (the command archives; it does not merge). Recommended options:
+
+| Option | Git command | Result |
+|--------|-------------|--------|
+| Squash merge | `git merge --squash` | Single clean commit |
+| Merge with history | `git merge --no-ff` | Preserves all commits |
+| Delete without merging | `git branch -D` | Discard branch work |
+| Keep branches | (none) | Manual handling |
+
+**Planning Doc Commits:**
+
+When `commit_docs: false` or `.planning/` is gitignored, PAN automatically skips git operations for planning files. The `pan-tools commit` CLI handles this transparently.
+
+### Requirement Tracing
+
+PAN traces requirements from definition through implementation to verification:
+
+```text
+requirements.md (checklist + traceability table)
+    ↓ REQ-01, REQ-02 assigned to phases in roadmap.md
+    ↓ Referenced in plan.md frontmatter: requirements: [REQ-01]
+    ↓ Auto-marked complete when the plan that lists them completes
+    ↓ Traceability table updated: Pending → Complete
+```
+
+When each plan completes, the executor runs `pan-tools requirements mark-complete` for that plan's requirement IDs, updating both the checklist and the traceability table.
+
+### Global Defaults
+
+PAN supports global defaults at `~/.pan-wizard/defaults.json`. They seed each new project's `config.json` (when `config-ensure-section` creates it, or when you accept them in `/pan:new-project`); an existing project's config is not changed, and a key missing from a project's config falls back to the hardcoded default.
+
+**Precedence:** `~/.pan-wizard/defaults.json` > hardcoded defaults when a config is created; after that PAN reads only the project's `.planning/config.json`, with the hardcoded default for any key it lacks
+
+Example `~/.pan-wizard/defaults.json`:
+
+```json
+{
+  "model_profile": "budget",
+  "parallelization": false,
+  "workflow": {
+    "research": false
+  }
+}
+```
+
+A config seeded from this file starts on the budget profile, with sequential execution and per-phase research off. Individual projects can override these in their own config.json.
+
+**Brave Search API key:** a file at `~/.pan-wizard/brave_api_key` (one line, the key only) makes a config that `config-ensure-section` creates (`/pan:settings` or `/pan:settings --profile` in a project with no config.json) start with `brave_search: true`; `/pan:new-project` does not set `brave_search`, so enable it with `pan-tools config-set brave_search true`. The search itself still needs `BRAVE_API_KEY` in the environment.
+
+### Web Search
+
+PAN research agents can search the web via Brave Search API.
+
+**Setup:**
+
+1. Get a free API key from [Brave Search API](https://brave.com/search/api/)
+2. Set the `BRAVE_API_KEY` environment variable — the only place the `websearch` verb reads it
+3. Turn it on with `pan-tools config-set brave_search true` (`/pan:new-project` does not set it; saving the key to `~/.pan-wizard/brave_api_key` only pre-sets it in a config `config-ensure-section` creates)
+
+When configured, the phase researcher (`/pan:plan-phase`, `/pan:plan-phase --research-only`) searches with Brave instead of the built-in web search; the `/pan:new-project` and `/pan:milestone-new` researchers never receive the setting. The `brave_search` config option (default `false`; `true` only in a config `config-ensure-section` creates while a key is detected) controls whether this is enabled.
+
+### Debug Logging
+
+Every `pan-tools` command accepts `--verbose`:
+
+```bash
+node pan-tools.cjs state load --verbose
+```
+
+This sets `PAN_VERBOSE=1`. Few code paths use it: the archived-phase lookup writes a `[pan-tools]` line to stderr when `.planning/milestones/` cannot be read, and `drift-check` adds a `per_file` breakdown to its output. Most commands, `state load` included, print nothing extra.
+
+---
+
+## Troubleshooting
+
+### "Project already initialized"
+
+You ran `/pan:new-project` but `.planning/project.md` already exists. This is a safety check. If you want to start over, delete the `.planning/` directory first.
+
+### Context Degradation During Long Sessions
+
+Clear your context window between major commands: `/clear` in Claude Code. PAN is designed around fresh contexts -- every subagent gets a clean context window. If quality is dropping in the main session, clear and use `/pan:resume` or `/pan:progress` to restore state.
+
+### Plans Seem Wrong or Misaligned
+
+Run `/pan:discuss-phase N` before planning. Most plan quality issues come from Claude making assumptions that `context.md` would have prevented. You can also run `/pan:assumptions N` to see what Claude intends to do before committing to a plan.
+
+### Execution Fails or Produces Stubs
+
+Check that the plan was not too ambitious. Plans should have 2-3 tasks maximum. If tasks are too large, they exceed what a single context window can produce reliably. Re-plan with smaller scope.
+
+### Lost Track of Where You Are
+
+Run `/pan:progress`. It reads all state files and tells you exactly where you are and what to do next.
+
+### Need to Change Something After Execution
+
+Do not re-run `/pan:exec-phase`. Use `/pan:quick` for targeted fixes, or `/pan:verify-phase` to re-verify the phase and list gaps, then `/pan:plan-phase N --gaps`.
+
+### Model Costs Too High
+
+Switch to budget profile: `/pan:settings --profile budget`. Research is already off by default; disable the plan-check agent via `/pan:settings` if the domain is familiar. Pin one agent to a cheaper tier with `model_overrides` in config.json, for example `"model_overrides": {"pan-verifier": "fast"}`. Complexity routing and per-phase `<!-- model_tier: fast -->` comments are no cost lever today: no workflow passes the task metadata or the phase they need. Complexity routing's one effect on a workflow is under `budget`, where it keeps a `/pan:exec-phase --gaps-only` retry on the tier that left the gaps instead of escalating it.
+
+### Working on a Sensitive/Private Project
+
+Set `commit_docs: false` during `/pan:new-project` or with `pan-tools config-set commit_docs false` (`/pan:settings` has no `commit_docs` question). Add `.planning/` to your `.gitignore`. Planning artifacts stay local and never touch git.
+
+### PAN Update Overwrote My Local Changes
+
+The installer backs up locally modified files to `pan-local-patches/`. Run `/pan:patches` to merge your changes back.
+
+### Subagent Appears to Fail but Work Was Done
+
+A known workaround exists for a Claude Code classification bug. PAN's orchestrators (exec-phase, quick) spot-check actual output before reporting failure. If you see a failure message but commits were made, check `git log` -- the work may have succeeded.
+
+### Phase Execution Hangs or Takes Too Long
+
+**Cause:** Complex plans with many dependencies, or agent model too weak for the task.
+**Fix:** Check the plan complexity (number of tasks, wave count). If you're on the `budget` profile, the executor is running a mid-tier model — switch back to `balanced` (`/pan:settings --profile balanced`) so it inherits your session model, or lift just that agent with `"model_overrides": {"pan-executor": "opus"}` in `.planning/config.json` (override values are tiers: `opus` means the reasoning tier, so the executor inherits your session model rather than switching to Opus). Conversely, if simple tasks feel slow, the reasoning tier is the cost: the `budget` profile or a `model_overrides` entry trades depth for speed. (`quality` and `balanced` resolve the executor identically; the two differ only in the researchers and the plan-checker, and in how much ceremony a phase gets.)
+
+### Plan Rejected by Checker Multiple Times
+
+**Cause:** Plan-checker found structural issues the planner keeps reproducing.
+**Fix:** Run `/pan:discuss-phase N` to capture more context, then re-plan. Or disable the checker temporarily: set `workflow.plan_check: false` in `/pan:settings`. Check plan.md manually for missing `verify` commands on tasks or empty `must_haves` sections. A send-back before any checker runs comes from the code checks (`verify plan-set`, `verify review-focus`, `verify decisions`); run the named command on the phase to see the failing plan (see [Plans sent back for Review Focus or design decisions](TROUBLESHOOTING.md#plans-sent-back-for-review-focus-or-design-decisions)).
+
+### Research Phase Returns Irrelevant Results
+
+**Cause:** Phase goal is too vague, or domain is highly specialized.
+**Fix:** Run `/pan:discuss-phase N` first to sharpen requirements. Or leave research off (it is off by default; `--research` turns it on for one phase) if you already know the domain well.
+
+### Verification Found Issues After Execution
+
+**Cause:** Verifier detected gaps between phase goals and actual implementation.
+**Fix:** Read `.planning/phases/XX-name/XX-verification.md` for details. Run `/pan:plan-phase N --gaps` to create the gap-closure plans, then `/pan:exec-phase N --gaps-only` to execute only those.
+
+### Git Commits Not Appearing
+
+**Cause:** `commit_docs: false` in config, or `.planning/` is in `.gitignore`.
+**Fix:** Check `commit_docs` in `.planning/config.json` (`/pan:settings` does not show it). If you want planning docs committed, set `commit_docs: true` and remove `.planning/` from `.gitignore`. Code commits (task completions) are always created regardless of this setting.
+
+### Context Monitor Warnings Not Showing
+
+**Cause:** Hooks not installed, the session not yet near its compaction point (the note comes only when about a third of the room before compaction is left), or a runtime the monitor cannot measure. Gemini CLI and OpenCode run no context monitor. PAN registers the monitor only on Claude Code. On Codex there is no PAN status line and the monitor cannot read Codex's transcript. On Copilot CLI the hook payload names the session `sessionId`, which the monitor never read. In both cases it measured nothing, so PAN no longer registers it there (see [Feature Availability](#feature-availability)).
+**Fix:** Re-run `npx pan-wizard` to reinstall hooks. Check `.claude/settings.json` (local install) or `~/.claude/settings.json` (global) for hook registration. On Claude Code the monitor reads PAN's status line bridge (`<os-tmpdir>/pan-hooks-{uid}/claude-ctx-{session_id}.json`) when it is fresh, and the session transcript otherwise, so headless `claude -p` runs are covered. Read from the transcript, a native-1M model on Bedrock, Google Cloud or Foundry gives no note while it runs a 200K window there, because the transcript cannot tell that window from 1M; on a 1M window the note still comes, since a context past 200K tokens can only be in a 1M window.
+
+### Wrong Model Being Used for Agents
+
+**Cause:** Profile override or stale config.
+**Fix:** Check current profile: review `.planning/config.json` for `model_profile`, `model_overrides`, and `routing` settings. Switch profiles with `/pan:settings --profile balanced`. Per-agent overrides in `model_overrides` take precedence over profile, per-phase overrides, and routing strategy.
+
+### Phase Will Not Complete (Phase Gate Refused)
+
+**Cause:** `phase complete` runs the phase gate, and `workflow.phase_gate` defaults to `enforce` (a config without the key reads as `enforce`): a plan without a summary, a missing, failing or stale verification, an open critical or high finding, a committed stub or a weakened test refuses the completion with `phase_gate_refused`.
+**Fix:** `pan-tools phase gate <N>` lists each reason and its fix. Fix them and complete again, or override once with `pan-tools phase complete <N> --force --reason "<why>"` (recorded as a decision), or make the gate advisory with `pan-tools config-set workflow.phase_gate warn`. See [Phase gate refuses to complete a phase](TROUBLESHOOTING.md#phase-gate-refuses-to-complete-a-phase).
+
+### Decimal Phase Numbering Issues
+
+**Cause:** Inserted phases (e.g., 3.1) may not sort correctly in some views.
+**Fix:** PAN handles decimal phases natively. Use `/pan:insert-phase 3 "description"` to create them properly. Phase sorting uses numeric comparison, not string sorting (so 3.2 < 3.10).
+
+---
+
+## Recovery Quick Reference
+
+| Problem | Solution |
+|---------|----------|
+| Lost context / new session | `/pan:resume` or `/pan:progress` |
+| Phase went wrong | `git revert` the phase commits, then re-plan |
+| Need to change scope | `/pan:add-phase`, `/pan:insert-phase`, or `/pan:remove-phase` |
+| Milestone audit found gaps | `/pan:milestone-audit --gaps` |
+| Something broke | `/pan:debug "description"` |
+| Quick targeted fix | `/pan:quick` |
+| Plan doesn't match your vision | `/pan:discuss-phase N` then re-plan |
+| Costs running high | `/pan:settings --profile budget`, `model_overrides` for one agent, toggle agents off via `/pan:settings` |
+| Update broke local changes | `/pan:patches` |
+| Phase gate refused completion | `pan-tools phase gate <N>`, fix the reasons; or `phase complete <N> --force --reason "<why>"` |
+
+---
+
+## Multi-Runtime Reference
+
+PAN supports five runtimes. The core workflow is identical across all — the differences are in command syntax, file locations, and format.
+
+### Command Syntax
+
+| Runtime | Prefix | Example |
+|---------|--------|---------|
+| Claude Code | `/pan:` | `/pan:new-project` |
+| OpenCode | `/pan-` | `/pan-new-project` |
+| Gemini CLI | `/pan:` | `/pan:new-project` |
+| Codex | `$pan-` | `$pan-new-project` |
+| Copilot CLI | `/pan-` | `/pan-new-project` |
+
+### Installation Locations
+
+| Runtime | Global | Local |
+|---------|--------|-------|
+| Claude Code | `~/.claude/` | `./.claude/` |
+| OpenCode | `~/.config/opencode/` | `./.opencode/` |
+| Gemini CLI | `~/.gemini/` | `./.gemini/` |
+| Codex | `~/.codex/` | `./.codex/` |
+| Copilot CLI | `~/.copilot/` | `./.github/` |
+
+> **Gemini CLI audience change:** from June 18, 2026, Google's Gemini CLI serves Gemini Code Assist (Standard/Enterprise) customers; individual free / AI Pro / Ultra accounts are directed to Antigravity CLI instead. PAN's `--gemini` install targets Gemini CLI and continues to work for those customers. Antigravity CLI is not yet a PAN install target, but it reads the shared `.agents/skills/` tree natively — install with `--unified-skills` (below) and PAN's command set is usable from Antigravity in the same project.
+
+### MCP server registration
+
+Every install also registers PAN's **MCP bridge**, which exposes the `pan-tools` engine
+to any MCP client as tools and resources. This happens automatically — there is no flag —
+and it writes **one file outside the runtime's own directory** for Claude Code, so it is
+worth knowing about:
+
+| Runtime | File written | Key |
+|---|---|---|
+| Claude Code | **`.mcp.json` at your project root** | `mcpServers` |
+| Copilot CLI | `.github/mcp.json` | `mcpServers` |
+| Gemini CLI | `.gemini/settings.json` (merged alongside hooks) | `mcpServers` |
+| OpenCode | `.opencode/opencode.json` (merged alongside permissions) | `mcp` |
+| Codex | *nothing* — a copy-pasteable TOML snippet is printed instead | — |
+
+The merge is non-destructive: any MCP servers you already had are preserved, and a config
+file PAN cannot parse is **left untouched** and reported rather than rewritten. Uninstall
+removes only PAN's `pan` entry, deleting the file only if PAN was its sole occupant.
+
+Two deliberate exceptions. **Codex** keeps MCP config in `config.toml`, and PAN is
+zero-dependency with no TOML merger — hand-editing your config is riskier than printing a
+snippet, so it prints one. **A global Claude install writes nothing**, because user-scope
+MCP config lives in `~/.claude.json`, a file keyed by every project you have ever opened;
+the installer prints the `claude mcp add` command instead.
+
+Claude Code prompts once to approve a project-scoped server. Verify a registration with
+`pan-tools validate deployment` — its `mcp` block tells you whether the entry is present,
+parseable, and pointing at a server that exists.
+
+### Unified skills tree (`--unified-skills`, ADR-0028 Phase 1 — alpha)
+
+Adding `--unified-skills` to any install compiles PAN's commands **once** into the runtime-neutral `.agents/skills/` tree (project root for local installs, `~/.agents/skills/` for global) instead of the per-runtime command formats below. The tree follows the Agent Skills standard (`SKILL.md` per skill directory) and the proprietary command surface is swept so commands don't resolve twice. Codex, Gemini CLI, OpenCode, Copilot CLI and Antigravity CLI list `.agents/skills/` among their skill locations. **Claude Code does not** — its skills documentation names only `.claude/skills/<name>/SKILL.md` locations, plugin skills and the legacy `.claude/commands/` — so for Claude the installer also copies every compiled skill, unchanged, into `.claude/skills/`, and PAN's commands there are `/pan-<name>` rather than `/pan:<name>`. On Gemini CLI skills have no slash command of their own; the model activates one when a request matches its description, and `/skills list` shows what loaded. Agents, hooks, and settings still install per-runtime.
+
+```bash
+npx pan-wizard --claude --local --unified-skills
+```
+
+Unified installs also ship a shared `pan-wizard-core` copy at `.agents/pan-wizard-core/`, which the compiled skills resolve against — so the tree's content is the same no matter which runtime installed it, and several runtimes can share one install safely. Uninstalls are ref-counted: the shared tree stays until the last runtime tracking it uninstalls. Alpha status reflects that per-runtime discovery of the installed skills hasn't been live-verified on every runtime yet — see ADR-0028.
+
+### File Format Differences
+
+| Component | Claude Code | OpenCode | Gemini | Codex | Copilot CLI |
+|-----------|------------|----------|--------|-------|-------------|
+| Commands | `commands/pan/*.md` | `commands/pan-*.md` | `commands/pan/*.toml` | `.agents/skills/pan-*/SKILL.md`¹ | `skills/pan-*/SKILL.md` |
+| Agents | `agents/*.md` | `agents/*.md` | `agents/*.md` | `agents/*.toml` | `agents/*.agent.md` |
+| Hooks | `hooks/*.js` in settings.json | Not supported | `hooks/*.js` in settings.json | `hooks/*.js`, registered in `.codex/hooks.json`¹ | `hooks/*.js`, registered in `.github/hooks/pan.json`² |
+| Config | `settings.json` | `opencode.json` | `settings.json` | `config.toml` | `.github/copilot/settings.json` (local) / `~/.copilot/settings.json` (global) |
+
+Codex and Copilot CLI use a "skills" format rather than slash commands. Each command becomes a skill directory with a `SKILL.md` file. Copilot CLI agents use `.agent.md` extension. The content is equivalent — only the container format differs.
+
+¹ **Codex (since June 2026):** skills install to the shared `.agents/skills/` tree at the project root (local installs) or `~/.agents/skills/` (global installs) — Codex no longer reads `$CODEX_HOME/skills`. Codex agents are standalone TOML files in `.codex/agents/` (required fields `name`/`description`/`developer_instructions`; PAN's per-agent `effort` maps to `model_reasoning_effort`). Note that project-scoped `.codex/` configuration only loads once the project is **trusted** in Codex — the installer prints a reminder.
+
+² **Copilot CLI (since June 2026):** hook registration lives in `.github/hooks/pan.json` (Copilot CLI's `version: 1` schema with `type: "command"` entries), not in `config.json`. PAN's hooks are Node.js scripts invoked via the cross-platform `command` key, so they run on Windows and Unix alike. Reinstalling migrates any hook registrations left in `config.json` by older PAN versions.
+
+### Feature Availability
+
+| Feature | Claude Code | OpenCode | Gemini | Codex | Copilot CLI |
+|---------|------------|----------|--------|-------|-------------|
+| All commands | Yes | Yes | Yes | Yes | Yes |
+| All agents | Yes | Yes | Yes | Yes | Yes |
+| Hooks: update check, context monitor, cost + trace loggers | Yes | No | Update check only (Gemini has no context metric or subagent event for the others) | Update check and loggers (no context monitor: it cannot measure on Codex) | Update check and loggers (no context monitor: it cannot measure on Copilot) |
+| Statusline (the context bridge the monitor reads) | Yes | No | No (Gemini CLI has no statusline command) | No | Yes (the monitor does not read it there) |
+| Stop guard (auto-advance boundary) | Yes | No | Yes | Yes | Yes |
+| State re-injection after context compaction | Yes | Yes (a plugin adds PAN's position to the compaction prompt) | Yes (two steps: `PreCompress` marks, `AfterTool` injects) | Yes | Yes (two steps: `preCompact` marks, `postToolUse` injects) |
+| Model profiles | Yes | Yes | Yes | Yes | Yes |
+| Wave-based parallel execution | Yes | Depends on runtime | Depends on runtime | Yes | Yes |
+| Hierarchical exec (`/pan:exec-phase --hierarchical`) | Yes | No (flat fallback) | No (flat fallback) | No (flat fallback) | No (flat fallback) |
+| Bot-army campaigns (`/pan:army`) | Yes | No gate or fallback | No gate or fallback | No gate or fallback | No gate or fallback |
+| `--dangerously-skip-permissions` | Yes | N/A | N/A | N/A | N/A |
+
+Hooks are supported by Claude Code, Gemini CLI, Codex (since June 2026, via `.codex/hooks.json` with Claude-compatible event names), and Copilot CLI. OpenCode runs no command hooks; instead PAN installs one OpenCode plugin, `.opencode/plugins/pan-wizard.js`, which adds PAN's position to the compaction prompt. On Gemini CLI PAN registers the update check (`SessionStart`), the stop guard (`AfterAgent`, Gemini's end-of-turn event) and the state re-injection's two steps (`PreCompress` and `AfterTool`). Gemini exposes no context-window usage to hooks and has no subagent-completion event, so the context monitor and the cost and trace loggers do not run there. Two trust gates can keep registered hooks from running: headless Copilot (`copilot -p`) loads repository hooks only in a trusted folder (see [Troubleshooting](TROUBLESHOOTING.md#pans-hooks-do-not-run-under-copilot--p)), and Codex skips a new or changed hook until you trust it in `/hooks` — repeat that after a PAN upgrade that changes the hooks.
+
+**Copilot CLI interaction handling:** Copilot CLI has no structured input controls (no checkboxes, radio buttons, or multi-select). PAN Wizard's install-time converter automatically rewrites `AskUserQuestion` blocks into numbered text menus with clear selection instructions. Single-select questions show "Type a number or label to choose", multi-select shows "Type the numbers you want, separated by commas (e.g., 1,3)". This runs transparently during installation — no user configuration needed.
+
+---
+
+## Project File Structure
+
+For reference, here is what PAN creates in your project:
+
+```text
+.planning/
+  project.md              # Project vision and context (always loaded)
+  requirements.md         # Scoped v1/v2 requirements with IDs
+  roadmap.md              # Phase breakdown with status tracking
+  state.md                # Decisions, blockers, session memory
+  state-history.md        # Settled state history, archived by state compact
+  roadmap-history.md      # Shipped phases' full sections, archived by roadmap compact
+  memory/                 # Agent memory logs (recorded by hand; no workflow loads them), archive/, quarantine.md
+  config.json             # Workflow configuration
+  milestones.md           # Index of completed milestones
+  milestones/             # Per-version archives (v{version}-roadmap.md, v{version}-requirements.md) from /pan:milestone-done
+  patterns.md             # Error patterns (PAT-NNN), read when present; nothing PAN ships writes it
+  session-history.md      # Session summaries, counted when present; nothing PAN ships writes it
+  research/               # Answers to open questions, only with /pan:new-project --research
+  todos/
+    pending/              # Captured ideas awaiting work
+    completed/            # Todos completed via /pan:todo-check or `pan-tools todo complete`
+  debug/                  # Active debug sessions
+    resolved/             # Archived debug sessions
+  codebase/               # Brownfield codebase mapping (from /pan:map-codebase)
+  quick/                  # Quick mode task plans and summaries
+  phases/
+    XX-phase-name/
+      XX-YY-plan.md       # Atomic execution plans
+      XX-YY-summary.md    # Execution outcomes and decisions
+      XX-context.md       # Your implementation preferences
+      XX-research.md      # Answers to the phase's open questions (only with --research)
+      XX-roadmap-slice.md # This phase's roadmap and requirements lines, read by phase agents
+      XX-validation.md    # Test coverage mapping (Nyquist layer)
+      XX-verification.md  # Post-execution verification results
+      XX-uat.md           # User acceptance testing results (/pan:verify-phase --uat)
+      XX-review.md        # Code review report, saved by exec-phase
+      XX-plan-check.md    # Plan-checker report, saved by plan-phase
+      XX-design.md        # Phase design (architecture, phase ADR, threat-lite), written by /pan:design-phase
+      XX-design-check.md  # Design-checker report, saved by /pan:design-phase (the judges' findings go to .planning/findings.jsonl)
+```
+
+### File Details
+
+| File | Created by | Purpose | Size guidance |
+|------|-----------|---------|---------------|
+| `project.md` | `/pan:new-project` | Project vision, goals, constraints. Always loaded into agent context. | No set limit; `/pan:hygiene` warns when it grows large |
+| `requirements.md` | `/pan:new-project` | Scoped requirements (v1/v2/out-of-scope) with unique IDs for traceability. | No limit |
+| `roadmap.md` | `/pan:new-project` | Phase breakdown with status (Not started / In progress / Complete / Deferred). The single source of truth for progress. | No limit |
+| `state.md` | `/pan:new-project` | Decisions made, blockers, cross-session memory. Updated after every plan and at each phase transition. | Keep under 100 lines (`templates/state.md`); `state compact` moves settled history to `state-history.md` |
+| `state-history.md` | `pan-tools state compact --apply` (or `/pan:hygiene --apply`) | Settled state history moved out of state.md, so it stops being re-read on every agent call. | Append-only archive |
+| `roadmap-history.md` | `pan-tools roadmap compact --apply` (or `/pan:hygiene --apply`) | Shipped phases' full sections; roadmap.md keeps a stub, and `roadmap get-phase` reads the full section back from here. | Append-only archive |
+| `memory/` | `memory append` / `memory record`, `/pan:retro --write-memory`, `memory optimize` | Agent memory logs, their `archive/`, and PAN's archives (`quarantine.md`, `state-archive.md`). No workflow loads them into agents; `/pan:knowledge` reads the logs. | `/pan:hygiene` reports stale entries |
+| `config.json` | `/pan:new-project` | Workflow configuration (mode, depth, profile, toggles). See [Configuration Reference](#configuration-reference). | Auto-managed |
+| `milestones.md` + `milestones/` | `/pan:milestone-done` | Index of completed milestones with dates and summaries, plus the per-version `v{version}-roadmap.md` / `v{version}-requirements.md` archives. | Append-only |
+| `patterns.md` | Nothing PAN ships (`appendErrorPattern()` has no caller); `learnings extract`, `preflight` and `/pan:focus-auto --step scan` read it when it exists | Error patterns (PAT-NNN) for cross-session learning. | Append-only, auto-increment |
+| `session-history.md` | Nothing PAN ships (`appendSessionSummary()` has no caller); `pan-tools progress health` counts its entries when it exists | Session summaries with phase, test counts, decisions. | Keeps last 20 entries |
+| `research/` | `/pan:new-project --research` | `questions.md` (at most 5 open questions that block building) and `research-summary.md` (one answer per question, with its source, plus v2 ideas). Only when research was asked for. | Read-only after creation |
+| `codebase/` | `/pan:map-codebase` | Brownfield analysis — the codebase-map documents (`stack.md`, `integrations.md`, `architecture.md`, `structure.md`, `conventions.md`, `testing.md`, `concerns.md`, `relationships.md`, `best-practices.md`). | Read-only after creation |
+| `XX-context.md` | `/pan:discuss-phase` | Your implementation preferences for a phase. Feeds into research and planning. | No set limit |
+| `XX-research.md` | `/pan:plan-phase --research` (or `workflow.research: true`) | Answers to the phase's open questions, each with a source or a recorded assumption. | Read-only after creation |
+| `XX-roadmap-slice.md` | `/pan:plan-phase`, `/pan:plan-phase --research-only`, `/pan:exec-phase`, `/pan:verify-phase` | The phase's section of roadmap.md, its dependencies' goals and its requirement lines; the researcher, planner, checker, executors and verifier read it instead of the whole files. | Rewritten when it changes |
+| `XX-YY-plan.md` | `/pan:plan-phase` | Atomic execution plan with XML-structured tasks, verification steps. | 2-3 tasks per plan |
+| `XX-validation.md` | `/pan:plan-phase` | Test coverage mapping — which tests verify which requirements. | Auto-generated |
+| `XX-YY-summary.md` | `/pan:exec-phase` | What was built, files changed, decisions made during execution. | Auto-generated |
+| `XX-verification.md` | `/pan:exec-phase`, `/pan:verify-phase` | Goal-backward check — did the phase deliver what it promised? | Auto-generated |
+| `XX-uat.md` | `/pan:verify-phase --uat` (the walkthrough scaffolds it and records each of your answers through `pan-tools uat record`); its diagnosis step, or the native `/pan-diagnose-issues` script on Claude Code, writes root causes into its gaps | Manual acceptance-test record. | One entry per acceptance test |
+
+### Privacy
+
+By default, `.planning/` is committed to git. To keep it private:
+
+1. Set `commit_docs: false` in config.json
+2. Add `.planning/` to `.gitignore`
+3. If previously tracked: `git rm -r --cached .planning/ && git commit -m "chore: stop tracking planning docs"`