pan-wizard 3.36.0 → 3.37.0

package/docs/AGENTS.md

@@ -0,0 +1,917 @@
+# PAN Agent System
+
+PAN uses specialized agents, each running as a subagent in a fresh context window. Agents are spawned by workflow orchestrators via the `Task` tool (on Claude Code, also by the native workflow scripts in `.claude/workflows/` through their `agent()` calls) and communicate exclusively through `.planning/` files (and, since v3.0, `.planning/bus/<channel>.jsonl` for hierarchical coordination). They never communicate directly with each other.
+
+**Other docs:** [Architecture](ARCHITECTURE.md) · [Hooks](HOOKS.md) · [CLI Reference](CLI-REFERENCE.md) · [Development](DEVELOPMENT.md)
+
+---
+
+## Table of Contents
+
+- [Agent Inventory](#agent-inventory)
+- [Squad model](#squad-model-adr-0032)
+- [Agent Lifecycle](#agent-lifecycle)
+- [Agent Architecture](#agent-architecture)
+- [Agent Deep Dives](#agent-deep-dives)
+  - [pan-project-researcher](#pan-project-researcher)
+  - [pan-roadmapper](#pan-roadmapper)
+  - [pan-document_code](#pan-document_code)
+  - [pan-phase-researcher](#pan-phase-researcher)
+  - [pan-planner](#pan-planner)
+  - [pan-plan-checker](#pan-plan-checker)
+  - [pan-executor](#pan-executor)
+  - [pan-verifier](#pan-verifier)
+  - [pan-reviewer](#pan-reviewer)
+  - [pan-integration-checker](#pan-integration-checker)
+  - [pan-debugger](#pan-debugger)
+- [Model Profiles](#model-profiles)
+- [Cross-Phase Agent Memory](#cross-phase-agent-memory-e-4)
+- [Hierarchical Orchestration](#hierarchical-orchestration)
+- [Per-agent profile override](#per-agent-profile-override)
+- [How Agents Collaborate](#how-agents-collaborate)
+- [Parallel Execution Patterns](#parallel-execution-patterns)
+- [Agent Design Principles](#agent-design-principles)
+- [Customizing Agents](#customizing-agents)
+
+---
+
+## Agent Inventory
+
+| Agent | Role | Spawned By | Tools | Color |
+|-------|------|-----------|-------|-------|
+| `pan-project-researcher` | Answers at most five open questions a brief leaves unanswered and that block building (only when research is asked for) | `/pan:new-project`, `/pan:milestone-new` | Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, Context7 | cyan |
+| `pan-roadmapper` | Creates phased roadmaps from requirements | `/pan:new-project`, `/pan:milestone-new` | Read, Write, Bash, Glob, Grep | purple |
+| `pan-document_code` | Analyzes existing codebase (6 focus areas, or the whole repo in one single-shot pass) | `/pan:map-codebase` (x6 parallel, or one agent in single-shot mode); native `/pan-map-codebase` script on Claude Code (one per discovered area) | Read, Bash, Grep, Glob, Write | cyan |
+| `pan-designer` | Designs a phase before planning — architecture, ADR, threat-lite; records only decisions that pass its three-question test, each with a `DD-N` id plans cite | `/pan:design-phase` | Read, Write, Bash, Glob, Grep, WebFetch, Context7 | green |
+| `pan-design-checker` | Independently verifies a design before planning; spawned by /pan:design-phase and /pan:focus-design | `/pan:design-phase`, `/pan:focus-design` | Read, Bash, Glob, Grep | green |
+| `pan-phase-researcher` | Answers at most five open questions that block planning a phase (only when research is asked for) | `/pan:plan-phase`, `/pan:plan-phase --research-only` | Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, Context7 | cyan |
+| `pan-planner` | Creates executable plan.md files with task breakdown | `/pan:plan-phase`, `/pan:quick` | Read, Write, Edit, Bash, Glob, Grep, WebFetch, Context7 | green |
+| `pan-plan-checker` | Validates plans against phase goals across multiple dimensions | `/pan:plan-phase`, `/pan:quick --full` | Read, Bash, Glob, Grep | green |
+| `pan-executor` | Executes plans with atomic commits and deviation handling | `/pan:exec-phase`, `/pan:quick`, `/pan:army`, native `/pan-exec-waves` script (Claude Code) | Read, Write, Edit, Bash, Grep, Glob | yellow |
+| `pan-verifier` | Verifies phase delivered what it promised | `/pan:exec-phase` and the native `/pan-exec-waves` script on Claude Code (both skip it when `workflow.verifier` is false), autodev's `exec-lean` workflow (lean phase), `/pan:quick --full` | Read, Write, Bash, Grep, Glob | green |
+| `pan-reviewer` | Read-only code review (conventions, security, quality) | `/pan:exec-phase`, autodev's `exec-lean` workflow (lean phase), native `/pan-review-pipeline` script (Claude Code) | Read, Grep, Glob, Bash | yellow |
+| `pan-integration-checker` | Verifies cross-phase wiring and E2E flows | `/pan:milestone-audit` | Read, Bash, Grep, Glob | blue |
+| `pan-debugger` | Systematic bug investigation with persistent state | `/pan:debug`, `/pan:verify-phase --uat` (the `diagnose-issues` workflow), native `/pan-diagnose-issues` script (Claude Code) | Read, Write, Edit, Bash, Grep, Glob, WebSearch | orange |
+
+### Spec B v2 agents
+
+| Agent | Purpose | Spawned by | Tools | Color |
+|-------|---------|-----------|-------|-------|
+| `pan-previewer` | Foresight — blast radius / dependency graph / milestone ETA in one agent (3 modes); a phase preview carries a `## Cost` section (p50 and p10–p90 per phase and per plan) taken only from the cost forecast, which reports `insufficient` below five past runs | `/pan:preview` | Read, Bash, Glob, Grep, Write | cyan |
+| `pan-hardener` | OWASP Top 10 + STRIDE security audit on files changed in a phase; reports every security finding, since the findings ledger never suppresses one | `/pan:review-deep` (also `--deep-review` on exec-phase and `/pan:focus-auto --step exec`), `/pan:focus-auto` Pass 3, native `/pan-review-pipeline` script (Claude Code) | Read, Grep, Glob, Bash, Write | red |
+| `pan-meta-reviewer` | Reviews the reviewer + hardener output; flags missed issues, disputes overstated severities | `/pan:review-deep` (also `--deep-review` on exec-phase and `/pan:focus-auto --step exec`, where it reviews the hardener's report alone), native `/pan-review-pipeline` script (Claude Code) | Read, Grep, Glob, Bash, Write | pink |
+| `pan-knowledge` | Grounded Q&A / multi-turn discussion / playbook generation (3 modes) | `/pan:knowledge` | Read, Grep, Glob, Bash, Write | cyan |
+| `pan-counterfactual` | Explores alternative phase approaches in isolated git worktree | `/pan:what-if` | Read, Write, Edit, Bash, Grep, Glob | purple |
+| `pan-conductor` | Top-level orchestrator for hierarchical exec — decomposes a phase, spawns sub-agents in waves, enforces safety harness | `/pan:exec-phase --hierarchical`, `/pan:army` | Read, Write, Bash, Glob, Grep, Task | orange |
+
+### Optimization agents
+
+| Agent | Purpose | Spawned by | Tools | Color |
+|-------|---------|-----------|-------|-------|
+| `pan-optimizer` | Reads trace events; identifies error/gap/redundancy patterns; writes a ranked optimization report whose suggestions each name where a person should make the fix | `/pan:learn` (`/pan:learn --optimize apply` records its suggestions) | Read, Glob, Grep, Write | cyan |
+| `pan-distiller` | Read-only LLM judgment on AI code-bloat findings — receives only flagged spans (max 50 lines context per finding); validates pattern, refines safety tier (safe/review_required/risky), proposes minimal diff rewrite | `/pan:focus-auto --category distill` | Read, Grep, Glob | cyan |
+
+### Self-Improvement Loop agents
+
+| Agent | Purpose | Spawned by | Tools | Color |
+|-------|---------|-----------|-------|-------|
+| `pan-experiment-runner` | Drives an external AI coding session against an experiment folder. Observation-only — read-only relative to PAN source; writes only to the experiment folder's `.planning/`. Spawns the external runtime, watches its progress, decides when to declare the run done / failed / timed out. | — (no shipped command spawns it directly; `/pan:experiment run` drives the runtime through `runner.cjs`; listed among the tier-2 `workers` Mission Control may delegate to under `/pan:army`) | Read, Bash, Glob, Grep | orange |
+
+### Bot-army agents (ADR-0032/0033)
+
+| Agent | Purpose | Spawned by | Tools | Color |
+|-------|---------|-----------|-------|-------|
+| `pan-release` | Release squad. Ships approved, green work behind a human gate — prepares the squash-merge, runs the configured verification, surfaces an `always-ask` approval request, tags the release, and rolls back via `git revert` / previous tag. Instructed not to write code and not to merge to a protected branch itself — with `Bash` in the grant beside this cell, that is prompt discipline rather than a runtime block, so read it as the behaviour PAN asks for and branch protection as the rail that holds. | `/pan:army` (release phase) | Read, Grep, Glob, Bash | orange |
+
+---
+
+## Squad model (ADR-0032)
+
+For a bot-army campaign (`/pan:army`), the agents are organized into role-scoped **squads** under the `pan-conductor` coordinator. A squad is a named grouping with an `access` label and a model tier; resolve it at runtime with `pan-tools squad list` / `squad show <name>` rather than hardcoding rosters.
+
+| Squad | Role | Tier | `access` | Agents |
+|-------|------|------|--------|--------|
+| Architecture | Design before code, contract-first | reasoning | `read-only` | roadmapper, planner, designer, plan-checker, design-checker, project/phase researchers |
+| Build | Turn design into committed code | reasoning | `read-write-bash` | executor (one `army/<task>` branch + worktree per agent) |
+| Quality | Adversarially break what Build makes | mid | `read-only` | reviewer, hardener, meta-reviewer, verifier, integration-checker, debugger |
+| Release | Ship safely behind a human gate | mid | `always-ask` | `pan-release` |
+
+**The `access` column is advisory, and does not always match the tool grant.** `squads.cjs` describes itself as "a registry + resolver only — it modifies no agent and changes no execution path", so these values are the contract the conductor's prompt is written around, not a sandbox the runtime imposes. Compare them against the real grants with `grep '^tools:' agents/*.md` and expect divergence: several agents in a `read-only` squad hold `Write` because they emit planning or verification artifacts. What the grants *do* enforce is delegation depth — `grep -l '^tools:.*Task' agents/*.md` names every agent able to spawn another, so squad members cannot fan out further.
+
+**Squad tier is not profile tier.** The tier column above is a `squads.cjs` grouping attribute — what `pan-tools squad list` reports — and it is not an agent's profile tier, which is what `resolve-model` reports from the active `model_profile` (`quality` is `reasoning` for every agent; `balanced` runs the researchers and the plan checker on `mid`; `budget` down-tiers further). `/pan:army` applies neither: its spawns pass no model, so a squad agent runs on its own `model:` pin, else the session model, under every profile. So the `mid` on the Quality and Release rows does not describe what those agents run. See [Model Profiles](#model-profiles) for the per-agent matrix.
+
+Outside the squads sit the coordinator (`pan-conductor`, Tier 0) and the worker/utility agents — `pan-document_code`, `pan-distiller` (narrow, high-volume jobs — the `budget` profile is the only one that drops them to the fast tier), plus `pan-optimizer`, `pan-knowledge`, `pan-counterfactual`, `pan-previewer` (invoked directly by their own commands, not delegated through a squad) and `pan-experiment-runner` (no shipped command spawns it — see its row above). A drift test pins squad roster ⇄ agent files ⇄ `AGENT_BASE_EFFORT`, so every shipped agent is accounted for in exactly one place.
+
+---
+
+## Agent Lifecycle
+
+```text
+Orchestrator (command/workflow)
+  │
+  ├── 1. Loads context (project.md, roadmap.md, plan.md, etc.)
+  ├── 2. Resolves model via pan-tools.cjs resolve-model <agent-type>
+  ├── 3. Spawns agent via Task tool with:
+  │      - Agent type (maps to agents/*.md)
+  │      - Prompt with <files_to_read> block
+  │      - Model parameter (`inherit`/`sonnet`/`haiku` as `resolve-model` emits on Anthropic, provider equivalents elsewhere; `opus`/`sonnet`/`haiku` are accepted as legacy tier aliases, and the reviewer-class agents pin `model: opus` in frontmatter, honoured on Claude Code only)
+  │
+  Agent (fresh context)
+  │
+  ├── 4. Reads all files listed in <files_to_read>
+  ├── 5. Executes its specialized task
+  ├── 6. Writes output (plan.md, summary.md, verification.md, etc.)
+  └── 7. Returns result to orchestrator
+```
+
+Every agent starts with zero context and receives only what it needs. This is the key to PAN's quality — agents never suffer from context degradation.
+
+---
+
+## Agent Architecture
+
+Each agent `.md` file is YAML frontmatter followed by XML-tagged sections. Every agent opens with `<role>`; the sections after it vary by agent — `pan-planner`, for example:
+
+```markdown
+---
+name: pan-planner
+description: Creates executable phase plans with task breakdown...
+tools: Read, Write, Edit, Bash, Glob, Grep, WebFetch, mcp__context7__*
+color: green
+effort: xhigh
+---
+
+<role>
+What the agent does, when it's spawned, and critical behavioral constraints.
+</role>
+
+<project_context>
+How to discover project context on startup — which files to read first,
+how to detect project type, framework, conventions.
+</project_context>
+
+<plan_format>
+What files to create, their structure, and where to write them.
+Frontmatter schemas, section templates, validation requirements.
+</plan_format>
+
+<execution_flow>
+Step-by-step procedure with XML-structured steps.
+The core logic of the agent lives here.
+</execution_flow>
+```
+
+The `tools` field in frontmatter controls which tools the agent can access when it is spawned under its own type — which every shipped spawn of a PAN agent now does. The `general-purpose` spawns that remain (`grep -n 'subagent_type="general-purpose"' pan-wizard-core/workflows/*.md`) hand a whole orchestrator to a fresh session — `/pan:plan-phase --auto` to the exec-phase orchestrator, `/pan:exec-phase` to the phase-tests workflow, and the auto-advance chain in `discuss-phase.md` and `transition.md` to the next phase's discuss or plan orchestrator — and spawn no PAN agent themselves. Read-only agents (plan-checker, design-checker, reviewer, integration-checker) don't get Write/Edit access; the verifier holds Write to emit verification.md. Research agents get WebSearch/WebFetch and Context7 for external knowledge.
+
+---
+
+## Agent Deep Dives
+
+Agents are ordered by workflow stage: project init → brownfield → phase planning → execution → verification → utility.
+
+---
+
+### pan-project-researcher
+
+**Purpose:** Answers the open questions a project brief leaves unanswered and that block building, at most five, which the orchestrator writes to `.planning/research/questions.md`. Research is opt-in (`/pan:new-project --research`, or idea frontmatter `research_enabled: true`); it settles decisions and never adds scope. It replaced a four-way parallel survey (stack, features, architecture, pitfalls) and the `pan-research-synthesizer` that merged it, whose catalogue never finished and grew v1 (2026-10-25).
+
+**Spawned by:** `/pan:new-project` (step 6) and `/pan:milestone-new` (step 8), one researcher, only when research was asked for
+
+**Tools:** Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, Context7
+
+**Inputs:** `.planning/research/questions.md`, `.planning/project.md`
+
+**Outputs:** `.planning/research/research-summary.md` — a table `| # | Question | Answer | Source | Confidence | Decision it settles |`, one row per question (or `unknown — assume: …`), and a separate `## Ideas (v2 candidates)` list. In market mode (`--research market`) also a `| Product | What users get | What the brief does not cover |` table of at most five comparable products, whose gaps become v2 candidates for the user to accept.
+
+**Key Behaviors:**
+- At most 4 searches or fetches per question, then stop: an unsettled question is marked `unknown` with the assumption the plan should use
+- Done means every listed question has a row; no surveys, no catalogues, no questions of its own
+- Runs `pan-tools research check` before returning; the orchestrator runs it again, sends the errors back once, then proceeds with the unknowns recorded
+- Findings settle decisions only: no idea moves into v1 by itself
+- Tool order per question: Context7 → official docs → WebSearch; confidence HIGH, MEDIUM or LOW by source
+
+---
+
+### pan-roadmapper
+
+**Purpose:** Transforms requirements into a phased delivery plan. Every v1 requirement maps to exactly one phase. Every phase has observable success criteria.
+
+**Spawned by:** `/pan:new-project`, `/pan:milestone-new`
+
+**Tools:** Read, Write, Bash, Glob, Grep
+
+**Inputs:**
+- `project.md` — Project vision and constraints
+- `requirements.md` — Scoped requirements with REQ-IDs
+- `.planning/research/research-summary.md` — Research findings and phase suggestions
+
+**Outputs:**
+| File | Contents |
+|------|----------|
+| `roadmap.md` | Phase checklist + detail sections with success criteria, progress table |
+| `state.md` | Initialized project memory (decisions, blockers, position) |
+| `requirements.md` | Updated traceability section (requirement → phase mapping) |
+
+**Key Behaviors:**
+- Derives phases from requirements (not template imposition) — "the requirements tell us what phases are needed"
+- Validates 100% requirement coverage — no orphaned requirements
+- Goal-backward success criteria: observable user behaviors, not implementation tasks
+- Calibrates depth from `config.json`: Quick (3-5 phases), Standard (5-8), Comprehensive (8-12)
+- Prefers vertical slices over horizontal layers (better parallelization during execution)
+- Writes roadmap.md, state.md and requirements.md first (one Write per file, P-1808); the orchestrator then presents the written roadmap for approval before committing, and re-spawns the roadmapper in revision mode if changes are requested; it rewrites each changed file with one Write (it has no Edit tool)
+
+**Phase Numbering:** Integers (1, 2, 3) for planned work. Decimals (2.1, 2.2) reserved for urgent insertions via `/pan:insert-phase`.
+
+---
+
+### pan-document_code
+
+**Purpose:** Explores an existing codebase and writes structured analysis documents. `/pan:map-codebase` first sizes the repo (`pan-tools codebase estimate-size`): at or below the threshold one agent maps the whole repo in a single pass (`single-shot`); above it six run in parallel, one focus area each (`sharded`).
+
+**Spawned by:** `/pan:map-codebase` (x6 parallel instances in sharded mode, one in single-shot mode)
+
+**Tools:** Read, Bash, Grep, Glob, Write
+
+**Inputs:**
+- Focus area assignment from orchestrator: `tech`, `arch`, `quality`, `concerns`, `relationships`, or `practices`
+- The project's source files
+
+**Outputs** (written directly to `.planning/codebase/`):
+
+| Focus | Documents Created |
+|-------|------------------|
+| `tech` | `stack.md` (languages, frameworks, versions), `integrations.md` (external services, APIs, auth) |
+| `arch` | `architecture.md` (system design, patterns), `structure.md` (directory layout, "where do I put this?") |
+| `quality` | `conventions.md` (coding patterns, naming, style), `testing.md` (test infrastructure, patterns, examples) |
+| `concerns` | `concerns.md` (tech debt, risks, improvement opportunities) |
+| `relationships` | `relationships.md` (module dependency graph, circular dependencies, coupling analysis) |
+| `practices` | `best-practices.md` (scored assessment across error handling, testing, naming, security, performance) |
+
+**Key Behaviors:**
+- Prescriptive, not descriptive: "Use camelCase" not "some functions use camelCase"
+- Always includes backticked file paths (`src/services/user.ts`) as evidence
+- Documents current state only — never what was considered or what might change
+- Never reads sensitive files (`.env`, credentials, secrets, private keys)
+- Writes documents directly to disk (minimal return to orchestrator, reducing context load)
+
+---
+
+### pan-phase-researcher
+
+**Purpose:** Answers the open questions a phase's requirements leave unanswered and that block planning, at most five, which the plan-phase orchestrator writes to `{phase_dir}/{padded_phase}-research-questions.md`. Research is opt-in: `/pan:plan-phase N --research`, `workflow.research: true` (false by default), or `/pan:plan-phase --research-only`.
+
+**Spawned by:** `/pan:plan-phase` (one researcher, only when research was asked for) or `/pan:plan-phase --research-only`
+
+**Tools:** Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, Context7
+
+**Inputs:**
+- The questions file, the phase's roadmap slice and `context.md` (if it exists: locked decisions are not open questions)
+- `.planning/research/research-summary.md` (if it exists: a question it already answers is copied, not searched again)
+
+**Outputs:**
+- `.planning/phases/XX-name/{phase_num}-research.md` — `<user_constraints>` (when context.md exists), the answers table `| # | Question | Answer | Source | Confidence | Decision it settles |`, `## Ideas (v2 candidates)`, and `## Validation Architecture` only when `nyquist_validation` is on (the plan-phase orchestrator, step 5.5, then writes `{padded_phase}-validation.md` from `templates/validation.md`)
+
+**Key Behaviors:**
+- At most 4 searches or fetches per question, then stop: an unsettled question is `unknown` with the assumption the plan uses
+- Done means every listed question has a row; no standard-stack survey, pitfall catalogue or code-example collection
+- Runs `pan-tools research check <questions> <research>`; the orchestrator sends its errors back once, then plans with the unknowns recorded
+- `pan-tools research lint` reads the answered rows as claims (the date in the source cell), so `/pan:plan-phase` still hands the plan-checker stale or undated claims
+- The planner uses the answers to settle decisions and never plans an item from the Ideas list
+
+---
+
+### pan-planner
+
+**Purpose:** Creates executable plan.md files with task breakdown, dependency analysis, and goal-backward verification. Plans are small enough for a single executor to implement in a fresh context window.
+
+**Spawned by:** `/pan:plan-phase` (standard, gap closure, or revision mode), `/pan:quick` (quick mode)
+
+**Tools:** Read, Write, Edit, Bash, Glob, Grep, WebFetch, Context7
+
+**Inputs:**
+- `state.md` and the phase's roadmap slice (`{phase}-roadmap-slice.md`); the whole roadmap.md or requirements.md only for something the slice leaves out
+- `context.md` (locked user decisions)
+- `{phase}-design.md` when `/pan:design-phase` produced one — the approved design the plans implement
+- `research.md` (phase-specific findings)
+- research.md's `## Validation Architecture` section (if Nyquist enabled)
+- Previous verification.md (in gap closure mode)
+
+**Outputs:**
+- `.planning/phases/XX-name/{phase}-{plan}-plan.md` — One per plan (the planning depth suggests 1-3, 3-5 or 5-10 plans per phase)
+
+**Plan Structure:**
+```yaml
+# Frontmatter (templates/phase-prompt.md)
+phase: 01-name
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified: []
+autonomous: true
+requirements: [REQ-01, REQ-02]   # must not be empty
+user_setup: []
+must_haves:
+  truths: []       # derived from goal-backward analysis
+  artifacts: []
+  key_links: []
+```
+Each plan contains 2-3 XML-structured tasks with: `<name>`, `<files>`, `<action>`, `<verify>` (automated command + success criteria), `<done>` criteria.
+
+**Key Behaviors:**
+- Goal-backward planning: "What must be TRUE for this phase to succeed?" → derive must-haves → derive tasks
+- Honors locked decisions from context.md (non-negotiable)
+- Cites the design's `DD-N` id in `## Plan Decisions` for each design decision a plan implements (`pan-tools verify decisions` checks the citations)
+- Writes a `## Review Focus` section in every plan: at most five inputs or failure modes no test covers yet, each pinned to a task and its test, or `None — <why>` (`pan-tools verify review-focus` checks the structure)
+- Optimizes for parallel execution through wave assignment and dependency graphs
+- Task types: `auto` (fully automated) and `checkpoint` (pauses for user input)
+- TDD support via dedicated `type: tdd` plans (RED → GREEN → REFACTOR)
+- Gap closure mode: reads verification.md, creates fix plans for identified gaps
+- Revision mode: incorporates plan-checker feedback and revises (one revision on the sized ceremony, two under full ceremony — `MAX_CHECKS` in `plan-phase.md`)
+
+---
+
+### pan-plan-checker
+
+**Purpose:** Validates that plans WILL achieve the phase goal before execution begins. Catches structural issues that would waste executor context windows.
+
+**Spawned by:** `/pan:plan-phase` (after planner creates plan.md; `MAX_CHECKS`: 2 checks, one revision, on the sized ceremony, 3 checks, two revisions, under `quality`, `workflow.ceremony: full` or `--quality`) and `/pan:quick --full` (on the quick task's plan, 2 checks, one revision)
+
+**Tools:** Read, Bash, Glob, Grep (read-only — cannot modify plans)
+
+**Inputs:**
+- plan.md files created by planner
+- The phase's roadmap slice (phase goal, success criteria and requirement lines); the whole roadmap.md only if the slice is missing
+- context.md (locked decisions)
+- research.md's `## Validation Architecture` section (if Nyquist enabled)
+- A `<research_claims>` block: `pan-tools research lint` over the phase's research
+
+**Outputs:**
+- Structured issues report returned to orchestrator, ending with a `pan-verdict` block (`references/verdict-contract.md`); `/pan:plan-phase` saves it to `{phase_dir}/{padded_phase}-plan-check.md` and branches on `pan-tools findings record`, which also adds the issues to the findings ledger
+- Issues categorized by severity: **blocker** (must fix), **warning** (should fix), **info** (suggestion)
+
+**Verification Dimensions** (the agent file is the canonical source — `agents/pan-plan-checker.md`):
+
+| # | Dimension | What It Checks |
+|---|-----------|---------------|
+| 1 | Requirement Coverage | Every requirement has task(s) addressing it |
+| 2 | Task Completeness | Every task has Files, Action, Verify, Done fields |
+| 3 | Dependency Correctness | Valid DAG, no circular refs, proper wave numbering |
+| 4 | Key Links Planned | Artifacts wired end-to-end (Component → API → DB → Response) |
+| 5 | Scope Sanity | 2-3 tasks per plan target; 4 → warning, 5+ → blocker |
+| 6 | Verification Derivation | must_haves trace back to phase goal |
+| 7 | Context Compliance | Plans honor all locked decisions from context.md |
+| 8 | Test Coverage Alignment | Planned test tier matches each must-have's behavioral level |
+| 9 | Nyquist Compliance | Automated verify commands present, test coverage mapped |
+| 10 | Standards Awareness | Plans address selected industry standards (advisory) |
+| 11 | Spec Sufficiency for Handoff | Plan complete enough that the executor cannot diverge in the implicit space (P-RES-004 — Specification Gap; arXiv:2603.24284) |
+| (cond.) | Design Conformance | Plans conform to the phase `design.md` when one exists |
+| 12 | Decision Trace Completeness | Plan's `## Plan Decisions` section is well-formed — Locked / Open / Considered+rejected buckets present, locked items unambiguous, downstream agents have enough reasoning context to act without re-deriving the upstream choices (P-RES-003 — Cognition's "Don't build multi-agents" anti-multi-agent argument: silent decisions force blind reconciliation) |
+| 13 | Review Focus | Each plan's `## Review Focus` names real untested inputs or failure modes, owned by the named task and caught by the named test (structure already checked by `pan-tools verify review-focus`) |
+| 14 | Decision Spine | When design.md exists, plans make no design-level choice that is neither a recorded `DD-N` nor a locked decision (citation checks already run by `pan-tools verify decisions`) |
+| 15 | Research Freshness | Plans do not rest on research claims that `pan-tools research lint` reports as unsourced, undated or stale |
+
+**Reasoning-trace handoff (P-RES-003):** plan-checker, planner, executor, and verifier exchange decisions explicitly via the `## Plan Decisions` section in plan.md and `## Implementation Decisions` in summary.md. Schema lives in `references/handoff-decisions.md`. Three buckets: Locked (binding, executor must obey), Open (executor's discretion), Considered+rejected (paths the planner already weighed and dismissed — saves the executor from re-arguing them).
+
+**Key Behaviors:**
+- Plans can describe intent while missing delivery — the checker catches the gap
+- Context compliance is strict: locked decisions are non-negotiable, "Claude's Discretion" items are flexible, deferred ideas must be excluded
+- Returns issues to planner for revision (once on the sized ceremony, twice under full ceremony; issues left after the last check go to the user)
+
+---
+
+### pan-executor
+
+**Purpose:** Executes plan.md files atomically — one task at a time, one commit per task (consecutive trivial tasks may share one), with automatic deviation handling and checkpoint protocols.
+
+**Spawned by:** `/pan:exec-phase` (wave-based), `/pan:quick`, `/pan:army` (Build squad, one per worktree)
+
+**Tools:** Read, Write, Edit, Bash, Grep, Glob
+
+**Inputs:**
+- plan.md (the plan to execute)
+- `## Plan Decisions` section in plan.md — read first (P-RES-003 reasoning-trace handoff). Locked items are binding; Open items are executor's discretion; Considered+rejected items must NOT be re-argued.
+- `project.md`, the phase's roadmap slice and `state.md` (project context); a plan that still names `roadmap.md` gets the slice in its place
+- `CLAUDE.md` and project-specific skills/conventions
+
+**Outputs:**
+| Output | Location |
+|--------|----------|
+| summary.md | `.planning/phases/XX-name/{phase}-{plan}-summary.md` (carries `## Implementation Decisions` section per P-RES-003 — records every deviation from the plan and why) |
+| Git commits | One per task, except that consecutive trivial tasks of one type may share a commit (P-1605; never `feat`/`fix`): `{type}({phase}-{plan}): {description}` |
+| state.md updates | Via pan-tools CLI (advance-plan, update-progress, record-metric) |
+| roadmap.md updates | Progress table updated |
+
+**Deviation Rules:**
+
+| Rule | Trigger | Action | Example |
+|------|---------|--------|---------|
+| Rule 1 | Bug in code | Auto-fix (Rules 1-3 share a per-task cap of 3 attempts; leftovers go to summary.md "Deferred Issues") | Logic errors, null pointers, type errors |
+| Rule 2 | Missing critical functionality | Auto-add | Missing validation, error handling |
+| Rule 3 | Blocking issue | Auto-fix | Missing dependency, broken imports |
+| Rule 4 | Architectural change needed | **STOP and ask** | New DB table, schema change, library switch |
+
+**Checkpoint Types:**
+- `human-verify` — Needs visual/functional confirmation ("Does the login page look right?")
+- `decision` — Needs user choice between options
+- `human-action` — Unavoidable manual step (e.g., create API key, configure OAuth)
+
+**Key Behaviors:**
+- Reads project context and conventions before starting any work
+- Per-task atomic commits with conventional commit format
+- TDD execution when flagged: RED (write failing test) → GREEN (minimal implementation) → REFACTOR
+- Self-check verification before updating state.md
+- Documents all deviations in summary.md (what changed, why, and its cost if wrong: low / medium / high)
+- Lists what it finished but is unsure of under the summary's `## Concerns` (each with a cost if wrong), and then returns `## DONE_WITH_CONCERNS` instead of `## PLAN COMPLETE`
+- Authentication gates recognized as normal flow, not failures
+- Never edits a test to make it pass: when a test and the task cannot both hold, it stops and returns `## BLOCKED_SPEC_CONFLICT`
+
+**Return statuses:** `## PLAN COMPLETE`, `## DONE_WITH_CONCERNS` (complete, with concerns listed), `## CHECKPOINT REACHED` (checkpoint or auth gate, with its type) and `## BLOCKED_SPEC_CONFLICT` (a test conflicts with the task).
+
+---
+
+### pan-verifier
+
+**Purpose:** Verifies that a phase achieved its GOAL, not just completed its TASKS. Works backwards from what the phase should deliver and checks that it actually exists, is substantive, and is wired correctly.
+
+**Spawned by:** Verification workflow after `/pan:exec-phase` (skipped, and said so, when `workflow.verifier` is false); also `/pan:quick --full`, and the `exec-lean` workflow autodev runs for a lean phase (one session does the executor's work, then one reviewer pass, then this verifier)
+
+**Tools:** Read, Write, Bash, Grep, Glob
+
+**Inputs:**
+- plan.md files (must_haves, requirements)
+- The phase's goal and success criteria (from `roadmap get-phase`) and its requirement lines (from the roadmap slice), not the whole roadmap.md
+- summary.md files (claimed completions)
+- The actual codebase
+
+**Outputs:**
+- `.planning/phases/XX-name/{phase_num}-verification.md` — Observable Truths table, Required Artifacts, Key Links, Requirements Coverage, Anti-Patterns, Human Verification items, Unrequested Work, Gaps Summary
+
+**Three-Level Artifact Verification:**
+
+| Level | Question | Failure Example |
+|-------|----------|-----------------|
+| **Exists** | Is the file/function there? | Component file missing entirely |
+| **Substantive** | Is it real code, not a stub? | Empty `return <div/>`, `TODO: implement` |
+| **Wired** | Is it connected and used? | Component exists but never imported/rendered |
+
+**Stub Detection Patterns:** Empty React returns, API handlers returning empty arrays, event handlers with only `preventDefault()`, functions with only `console.log`.
+
+**Key Behaviors:**
+- Does NOT trust summary.md claims — verifies actual code
+- Goal-backward: starts from what must be TRUE, not what was DONE
+- Re-verification mode: if previous verification.md exists, focuses on previously failed items
+- Runs the project's test suite as a gate (verify-phase's `run_test_suite`) and records `test_gate: passed | failed | skipped`; a gate it could not run goes in `not_checked` with the reason, so a pass never hides missing tests
+- Structures `gaps`, `human_verification` and `unrequested` (work no plan asked for, found with `pan-tools verify scope`) in YAML frontmatter; `/pan:plan-phase --gaps` consumes the gaps, and `pan-tools findings record` reads those keys and `status` into the findings ledger — the verifier's machine contract, in place of a `pan-verdict` block
+- Identifies items requiring human verification (visual appearance, UX, real-time behavior, external services)
+- Scans for anti-patterns: TODOs, FIXMEs, empty implementations, dead code
+
+**Per-check statuses:** VERIFIED (all checks pass), FAILED (missing/stub/unwired artifacts), UNCERTAIN (needs human judgment). The report-level `status:` is `passed`, `gaps_found` or `human_needed`.
+
+---
+
+### pan-reviewer
+
+**Purpose:** Performs read-only code review on files changed during phase execution. Checks convention compliance, security patterns, and code quality before verification begins.
+
+**Spawned by:** `/pan:exec-phase` (after test generation, before verification — skippable via `--skip-review` or `--fast`; a lean phase skips only the test-generation agent and keeps this pass), and the `exec-lean` workflow autodev runs for a lean phase (one pass, one fix round)
+
+**Tools:** Read, Grep, Glob, Bash (read-only — cannot modify files)
+
+**Inputs:**
+- Changed file list from executor summary.md files (key-files.created + key-files.modified)
+- Phase context from orchestrator
+- Project conventions from CLAUDE.md and `.agents/skills/`
+- An `<intent>` block (the `review scope` JSON): each plan's objective, must_haves and `review_focus`, the claimed requirements' text, and `unlisted` changed files no summary lists
+- An `<executor_concerns>` block when executors returned concerns, each with its cost if wrong
+- On a re-check, an `<open_findings>` block: its earlier open findings on the phase, each of which it must answer in the verdict's `resolutions` list (`resolved` with evidence, `still_present` or `cannot_tell`)
+
+**Outputs:**
+- Structured review report returned to orchestrator, ending with a `pan-verdict` block (`references/verdict-contract.md`); `/pan:exec-phase` saves it to `{phase_dir}/{phase_number}-review.md`, which `/pan:review-deep` reads, and branches on `pan-tools findings record`, which also adds the findings to the findings ledger
+- Findings categorized by severity: **error** (must fix), **warning** (should fix), **info** (suggestion)
+
+**Review Dimensions:**
+
+| Category | What It Checks |
+|----------|---------------|
+| Convention Compliance | Consistency with the conventions the reviewer discovers from `./CLAUDE.md`, `.agents/skills/` and existing code — no fixed rule set |
+| Security Patterns | No `eval`/`Function`, no shell injection, no hardcoded secrets, path traversal prevention, no absolute paths in output, no stack traces or internal names in user-facing errors |
+| Code Quality | Function length (>50 lines flagged), nesting depth (>3 levels flagged), dead imports, duplicate code (>10 identical lines), new TODO/FIXME/HACK instances |
+| Scope (Unrequested) | Behaviour no plan task or requirement asked for — WARNING, or ERROR when it changes existing behaviour without a plan saying so; supporting code the tasks need is not a finding |
+| Design smells (baseline) | A fixed list of twelve smells from Fowler's *Refactoring* (Feature Envy, Shotgun Surgery, Speculative Generality and others), each INFO and phrased "possible …"; a project standard or established pattern that endorses one suppresses it, and none changes the verdict on its own |
+
+**Verdict Options:**
+- **PASS**: Zero errors, zero warnings
+- **PASS_WITH_WARNINGS**: Zero errors, warnings present
+- **NEEDS_FIXES**: Any errors present — orchestrator presents findings to user
+
+**Key Behaviors:**
+- Strictly read-only — inspects but never modifies code
+- Only reviews files changed in the current phase (scoped via summary.md), plus any `unlisted` file the intent block names
+- Checks each plan's Review Focus items first, and the high-cost executor concerns against the code
+- Reports every finding, including ones dismissed before: the recorder filters a dismissed finding while its file is unchanged (learned suppressions, `pan-tools findings suppressions`), and never filters security or logic findings
+- Reports every finding with its file path and line number, style-only ones included at INFO; the severity tiers, the verdict and `/pan:review-deep`'s meta-reviewer do the filtering
+- Skips pure documentation files (.md) unless they contain code blocks
+
+---
+
+### pan-integration-checker
+
+**Purpose:** Verifies that phases work together as a system — not just individually. Checks cross-phase wiring (exports used, APIs called, data flows) and traces end-to-end user flows.
+
+**Spawned by:** Milestone auditor (during `/pan:milestone-audit`)
+
+**Tools:** Read, Bash, Grep, Glob (read-only)
+
+**Inputs:**
+- summary.md files from all completed phases
+- The actual codebase
+- The milestone's requirement IDs, with descriptions and assigned phases, which the auditor takes from requirements.md's traceability table and passes in the prompt
+
+**Outputs:**
+- Structured report returned to milestone auditor (not a file on disk)
+- Wiring status: connected exports, orphaned exports, missing connections
+- Flow status: complete flows, broken flows with specific break points
+
+**E2E Flow Verification:**
+- **Auth Flow:** form → API → session/token → redirect
+- **Data Display:** component → fetch → state → render
+- **Form Submission:** form → handler → API → response → feedback
+
+**Key Behaviors:**
+- Existence ≠ Integration: files can exist without being connected
+- Checks both directions: export exists AND import exists AND the import is actually used
+- Traces full paths: Component → API → DB → Response → Display
+- Identifies specific break points: "Component renders but never calls the API at line X"
+- Maps requirements to cross-phase wiring paths (identifies requirements with no cross-phase touchpoints)
+
+---
+
+### pan-debugger
+
+**Purpose:** Investigates bugs using systematic scientific method with persistent state that survives context resets. The user is the reporter (knows symptoms); Claude is the investigator (finds root cause).
+
+**Spawned by:** `/pan:debug`; `/pan:verify-phase --uat`, whose `uat-walkthrough` workflow follows the `diagnose-issues` workflow for the gaps it records (one debugger per failed UAT truth, root cause only); on Claude Code also the native `/pan-diagnose-issues` script, which ports that workflow
+
+**Tools:** Read, Write, Edit, Bash, Grep, Glob, WebSearch
+
+**Inputs:**
+- Bug description from user
+- Existing debug session file (if resuming)
+- The codebase
+
+**Outputs:**
+- `.planning/debug/{slug}.md` — Persistent debug session file with structured sections
+
+**Debug File Structure (State Machine):**
+| Section | Behavior | Contents |
+|---------|----------|----------|
+| Current Focus | Overwritten on updates | Active hypothesis, test, expected result, next action |
+| Symptoms | Immutable after gathering | Expected vs actual, errors, reproduction steps |
+| Reproduction | Written before the first hypothesis; overwritten only to shrink it | A command the debugger ran that fails on the symptom (or `none`, with what was tried); the fix is verified when it passes |
+| Eliminated | Append-only | Disproven hypotheses with evidence and timestamp |
+| Evidence | Append-only | Observations with implications |
+| Resolution | Overwritten as understanding evolves | Root cause, fix, verification, files changed |
+
+**Status Progression:** `gathering` → `investigating` → `fixing` → `verifying` → `awaiting_human_verify` → `resolved` (a `find_root_cause_only` session stops at `diagnosed` after `investigating`)
+
+**Investigation Techniques:**
+- Binary Search — narrow the problem space by halving
+- Rubber Duck — explain the system to find assumptions
+- Minimal Reproduction — strip to smallest failing case
+- Working Backwards — start from error, trace to cause
+- Differential Debugging — compare working vs broken state
+- Git Bisect — find the commit that introduced the bug
+
+**Key Behaviors:**
+- Never asks the user to diagnose — asks about symptoms, investigates causes
+- Treats own code as foreign (meta-debugging discipline)
+- Actively avoids cognitive biases: confirmation, anchoring, availability, sunk cost
+- Changes one variable at a time — no shotgun debugging
+- When to restart: 2+ hours no progress, 3+ failed fixes, can't explain behavior
+- Persistent debug file survives `/clear` — full context restoration on resume
+
+**Modes:**
+- `symptoms_prefilled` — Skip gathering, go straight to investigation
+- `find_root_cause_only` — Diagnose but don't fix
+- `find_and_fix` — Complete cycle (default)
+
+---
+
+## Model Profiles
+
+Each agent is assigned a model tier based on the active profile in `.planning/config.json`. PAN uses abstract tiers (`reasoning`, `mid`, `fast`) that map to provider-specific models:
+
+**Source of truth:** `MODEL_PROFILES` in `pan-wizard-core/bin/lib/core.cjs`. Since right-sized ceremony (`docs/specs/right-sized-ceremony.md`), `balanced` runs the plan-checker and the researchers on the mid tier and `quality` keeps every agent on the reasoning tier, with the full ceremony on every piece of work. The table below mirrors that source by hand — no script or test regenerates it — so when in doubt, `core.cjs` wins.
+
+| Agent | `quality` | `balanced` | `budget` |
+|-------|-----------|------------|----------|
+| pan-planner | reasoning | reasoning | mid |
+| pan-roadmapper | reasoning | reasoning | mid |
+| pan-executor | reasoning | reasoning | mid |
+| pan-designer | reasoning | reasoning | mid |
+| pan-design-checker | reasoning | reasoning | fast |
+| 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 |
+| pan-conductor | reasoning | reasoning | mid |
+| pan-counterfactual | reasoning | reasoning | mid |
+| pan-hardener | reasoning | reasoning | fast |
+| pan-meta-reviewer | reasoning | reasoning | fast |
+| pan-knowledge | reasoning | reasoning | fast |
+| pan-previewer | reasoning | reasoning | fast |
+| pan-optimizer | reasoning | reasoning | fast |
+| pan-distiller | reasoning | reasoning | fast |
+| pan-experiment-runner | reasoning | reasoning | fast |
+| pan-release | reasoning | reasoning | fast |
+
+**Resolution order** (`resolveModelDetailed()` in `core.cjs`): a `model_overrides` entry for the agent wins, then a per-phase tier from the roadmap, then the profile column above (an agent missing from the table gets `mid`, unadjusted). Only a profile-derived tier is then adjusted — by `routing.strategy: complexity`, by the capability hints below, and on a retry (`attempt > 1`) by escalation toward the agent's `quality` tier; a pinned tier is never adjusted.
+
+**Tier mapping by provider:** Anthropic: reasoning → `inherit` (the model your session runs on), mid → Sonnet, fast → Haiku. OpenAI/Google: reasoning → inherit, mid/fast → provider equivalents. Legacy names (`opus`, `sonnet`, `haiku`) still work as aliases.
+
+**Design rationale (cost reset 2026-07, right-sized ceremony 2026-10-24):**
+- **quality inherits everywhere; balanced inherits for the agents that plan, write and judge code** — those run on the model you launched with, and since right-sized ceremony `balanced` runs only the researchers and the plan checker on the mid tier. The other exceptions are `pan-reviewer`, `pan-hardener` and `pan-meta-reviewer`, which pin `model: opus` in their own frontmatter. On Claude Code the pin holds where a spawn passes no model (`/pan:review-deep`, `/pan:focus-auto`); `/pan:exec-phase` passes the resolved tier, so under `budget` its review spawns run on the fast tier. The installer drops the pin from the other runtimes' agent files, so there these agents inherit the session model like the rest. Context isolation, not a weaker model, keeps the main conversation clean.
+- **budget is the opt-in cheap mode** — mid for the planning, orchestration and code-writing agents, fast for research, review, verification and the utility agents; choose it explicitly for high-volume work.
+- 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 → `inherit`).
+
+### Reasoning effort (adaptive-thinking era)
+
+Agents declare `effort:` in frontmatter (`low`/`medium`/`high`/`xhigh`) — the within-model reasoning-depth dial on current models, consumed natively by Claude Code. Codex maps it to its native `model_reasoning_effort` field (`convertClaudeAgentToCodexToml`); OpenCode, Gemini CLI and Copilot CLI get an effort-scaled prose preamble injected by the installer (`stripThinkingFrontmatter`; legacy `thinking_budget` directives still translate via a budget→effort mapping). `pan-tools resolve-model` reports a profile-adjusted effort: `budget` steps each agent down one level (floor `low`), and `.planning/config.json → effort_overrides` wins (`resolveEffortInternal()`). No spawn applies it: an agent spawned under its own type (every shipped spawn of a PAN agent) runs at the `effort:` in its own file.
+
+| Agent | effort | Rationale |
+|-------|--------|-----------|
+| `pan-plan-checker` | xhigh | Highest — catching logic gaps before execution avoids the most rework |
+| `pan-debugger` | xhigh | Hypothesis-tree generation and Bayesian prior ranking |
+| `pan-conductor` | xhigh | Decomposition + safety-harness enforcement decisions |
+| `pan-designer` | xhigh | Architecture, ADR, and threat-lite design before planning |
+| `pan-design-checker` | xhigh | Independent design verification before planning |
+| `pan-verifier` | high | Goal-backward analysis across phase artifacts |
+| `pan-integration-checker` | high | Cross-phase wiring verification |
+| `pan-previewer` | high | Multi-mode synthesis of structured foresight inputs |
+| `pan-hardener` | high | Threat-model reasoning across OWASP + STRIDE frameworks |
+| `pan-counterfactual` | high | Comparison reasoning in isolated worktree |
+| `pan-release` | high | Release-safety judgment: merge readiness, rollback targets |
+| `pan-reviewer` | medium | Convention + security review on changed files |
+| `pan-meta-reviewer` | medium | Cross-check of reviewer + hardener output |
+| `pan-knowledge` | medium | Retrieval ranking + citation synthesis |
+| `pan-planner` | xhigh | Task decomposition, wave assignment and decision traces |
+| `pan-executor` | high | Thorough but bounded implementation of one plan |
+| `pan-roadmapper` | high | Phase breakdown against requirements |
+| `pan-experiment-runner` | high | Observing and judging an external run |
+| `pan-optimizer` | high | Clustering trace events into patterns |
+| `pan-phase-researcher` | medium | At most five bounded questions for one phase |
+| `pan-project-researcher` | medium | At most five bounded questions for a project or milestone |
+| `pan-distiller` | medium | Judging flagged bloat spans only |
+| `pan-document_code` | low | Mechanical, scoped documentation pass |
+
+The table mirrors `AGENT_BASE_EFFORT` in `core.cjs`; an agent absent from it resolves to `medium` (`resolveEffortInternal`). The older `THINKING_BUDGETS` table in `constants.cjs` is no longer consumed by any code path.
+
+### Capability-aware routing (E-7)
+
+The tier resolved by profile can be adjusted by capability hints passed as `pan-tools resolve-model <agent> --metadata '{"context_estimate":…,"needs_thinking":…,"cache_warm":…}'` (applied by `adjustTierForCapabilities` in `core.cjs`):
+
+- `context_estimate > 700000` (`LARGE_CONTEXT_TOKEN_THRESHOLD`) → force the reasoning tier, i.e. refuse to down-tier and let the agent run on the session model. PAN doesn't verify that model's real window — it just stops nominating a cheaper one for work this large.
+- `needs_thinking` on a fast-tier agent → upgrade fast → mid
+- `cache_warm + !needs_thinking + context_estimate < 50000` on a mid-tier agent → downgrade mid → fast (cheap, cached, simple)
+
+See `/pan:settings --profile` for the full decision tree.
+
+---
+
+## Cross-Phase Agent Memory (E-4)
+
+Since v2.10.0, each agent has an append-only memory log at `.planning/memory/<agent>.md` managed by the `memory.cjs` core module.
+
+**PAN's workflows do not load it into agents** (ADR-0036, amended `2026-10-04`). exec-phase and plan-phase stopped injecting it, and nothing writes it automatically, after harness runs found that a recorded lesson changed no phase's work beyond what `state.md`, the summaries and the code already carried. The store and its commands remain for lessons recorded by hand, and `/pan:knowledge` reads it. A lesson an agent must see belongs in the project's instructions (`CLAUDE.md` or `AGENTS.md`, outside PAN's section).
+
+**Files:** one per agent, stable frontmatter (`agent`, `created`) + `## Entries` section with dated bullets.
+
+**CLI:**
+- `pan-tools memory read <agent>` — list entries
+- `pan-tools memory append <agent> <text> [--cites <path[#symbol]>,...]` — append a lesson (auto-dated); each citation must hold in the working tree
+- `pan-tools memory list` — the agent logs with entry counts, the files in `.planning/memory/` that are not read as memory (`not_loaded`), and usage: entries with evidence, cited, used and never used
+- `pan-tools memory compact <agent> [max]` — trim to last N (default 500); the dropped entries go to `.planning/memory/archive/<agent>.md`
+- `pan-tools memory select <agent> [--cue <text>] [--token-budget N] [--recency-floor N] [--all] [--mark-used] [--days N]` — budget-aware, cue-ranked subset; leaves out entries whose cited code is gone or that went unused for N days (default 60); `--mark-used` records today as each selected entry's last use
+- `pan-tools memory record <agent> --lesson <text> (--finding <id> | --trace <session>) --cites <path[#symbol]>` — the gated write: a corrected failure with a citation that holds
+- `pan-tools memory budget` — what the whole store would add to an agent's prompt
+- `pan-tools memory prune [<agent>] [--apply] [--days N]` — archive the entries `memory select` leaves out (cited code gone, or unused for N days, default 60) to `.planning/memory/archive/<agent>.md`; a dry run without `--apply`
+- `pan-tools memory optimize [--apply] [--keep N]` — reconcile the always-loaded project memory
+- `pan-tools memory rebuild [--apply]` — regenerate the derived tools-memory (AGENTS.md section, CLAUDE.md bridge) and state.md's frontmatter
+
+**On request:** `/pan:retro --write-memory` extracts top-N gap patterns as lessons for `pan-planner`, and writes a verifier lesson when first-try rate drops below 60% over ≥3 runs. `/pan:retro` passes the flag on to `pan-tools retro` only when you give it; no workflow passes it on its own.
+
+**Safety:** agent names validated against `^[a-zA-Z0-9_-]+$` to block path traversal. Compaction is bounded by `DEFAULT_MAX_ENTRIES=500`; `memory append` auto-compacts back to that cap once a file reaches twice it (`MEMORY_SOFT_CAP_MULT`, ADR-0036).
+
+---
+
+## Hierarchical Orchestration
+
+Since v3.4.0, `/pan:exec-phase <N> --hierarchical` spawns `pan-conductor` as a top-level orchestrator that decomposes the phase and spawns sub-agents (executors, reviewers, verifiers) in waves. **This is opt-in behind a flag, not the default.** Flat exec remains the standard path.
+
+**Safety harness (hard caps, enforced before every spawn):**
+
+| Cap | Value | Behavior at limit |
+|-----|-------|-------------------|
+| Nesting depth | 2 levels (conductor → sub-agent) | Sub-agents may NOT spawn further agents |
+| Spawns per phase | 12 total | Continue without further spawning; document skipped work |
+| Points budget | `total_budget_points` from `pan-tools init execute-phase <N>` (config `budget.default_points`, default 50) | Stop when remaining < next spawn's estimate |
+| Abort file | `.planning/orchestration/abort` | Immediate stop, no graceful rollback |
+
+**Audit trail:** every spawn and completion is logged to `.planning/orchestration/trace.json` (authoritative) and published to the `orchestrator` bus channel (`.planning/bus/orchestrator.jsonl`) for observability.
+
+**Runtime gating:** Claude Code only — agents-spawn-agents needs native sub-agent spawning, which the other runtimes don't support cleanly. There they fall back to flat exec with a warning. The gate is purely the runtime: `pan-conductor` ships no `model:` frontmatter, so it inherits your session model, and no model check exists anywhere in the path. [ADR-0024](decisions/ADR-0024-spec-b-v2-completion.md) records the original decision; its note that the flag needs a particular model and falls back silently predates the 3.23.0 correction (CHANGELOG), which found no model gate in the code.
+
+**When to use:**
+- Phases with ≥4 autonomous plans that genuinely parallelize
+- Phases large enough that orchestration overhead is amortized
+- Accept ~20-30% higher total cost vs flat exec in exchange for wall-clock reduction
+
+**When to skip:**
+- Single-plan phases (pointless orchestration tax)
+- Phases with many checkpoints
+- First-time runs in a new codebase (flat exec telemetry more informative)
+
+See [commands/pan/exec-phase.md](../commands/pan/exec-phase.md) for the flag documentation, and [agents/pan-conductor.md](../agents/pan-conductor.md) for the agent's full contract including decomposition strategy.
+
+### Campaign mode (the army coordinator, ADR-0033)
+
+When invoked by `/pan:army`, `pan-conductor` runs as **Mission Control** for a whole-project campaign rather than a single phase — same safety harness, wider scope. In this mode it delegates to **squads, not bare agents**, resolving the roster at runtime via `pan-tools squad list` / `squad show <name>`. Each mission is routed to the squad that owns its lifecycle role: Architecture (design), Build (code, read/write/bash), Quality (adversarial review), Release (`pan-release`, always-ask). Those role labels are the contract the conductor's prompt assigns — `squads.cjs` publishes them as advisory metadata and "changes no execution path", so the binding grant stays each agent's own `tools:` frontmatter.
+
+- **Build parallelizes by worktree — and Mission Control tears the worktrees down.** Each concurrent `pan-executor` gets its own `army/<slug>` branch and isolated worktree (`pan-tools worktree create "<task>"` slugifies the task name) so builders never share a tree or file. After a task's squash-merge lands, the conductor removes its worktree *and* branch (`pan-tools worktree remove <worktree_path> --branch <branch>`, the two values `worktree create` returned); at campaign end or on any abort, `pan-tools worktree cleanup` sweeps the strays. Leftover `pan-army-*` sibling directories are a campaign defect.
+- **Integration is human-gated** — the conductor is instructed never to merge to a protected branch; the Release squad prepares the merge and surfaces an `always-ask` approval. Branch protection on the repo is what makes that unbypassable rather than merely instructed. Recovery is `git revert` / previous tag, never force-push.
+- **The loop carries learnings** — after each mission, squad summaries return to the conductor, `/pan:retro` reports the recurring patterns (the "Dreaming" step), and the conductor carries them into the next mission's plan. Agent memory is not loaded into agents, so the conductor hands them on itself.
+
+Every Tier-0 safety cap (nesting depth 2, spawn/budget ceiling, `.planning/orchestration/abort` kill-switch) still applies, unchanged. See [agents/pan-conductor.md](../agents/pan-conductor.md) `<campaign_mode>` and [ADR-0033](decisions/ADR-0033-army-campaign.md).
+
+---
+
+## Per-agent profile override
+
+Override specific agents without changing the profile. Values are tiers (`reasoning`, `mid`, `fast`) or their legacy aliases (`opus`, `sonnet`, `haiku`), so `opus` below means the reasoning tier — `inherit` — and an unrecognised value falls back to `mid`:
+```json
+{
+  "model_profile": "budget",
+  "model_overrides": {
+    "pan-executor": "opus"
+  }
+}
+```
+
+---
+
+## How Agents Collaborate
+
+Agents never communicate directly. The orchestrator mediates all data flow through `.planning/` files:
+
+```text
+                 Writes research.md
+Researcher ──────────────────────────┐
+                                     │
+                 Reads research.md   ▼
+Planner    ──────────────────────── .planning/
+                                     │
+                 Reads plan.md       │
+Executor   ──────────────────────────┤
+                                     │
+                 Reads codebase      │
+Verifier   ──────────────────────────┘
+                 Writes verification.md
+```
+
+### Full Workflow Sequence
+
+```text
+/pan:new-project
+  │
+  ├── pan-project-researcher (one, only with --research: at most 5 questions)
+  └── pan-roadmapper
+
+/pan:map-codebase (existing code; re-run to refresh)
+  │
+  └── pan-document_code (x6 parallel when sharded: tech, arch, quality, concerns, relationships, practices; one agent in single-shot mode)
+
+/pan:plan-phase N
+  │
+  ├── pan-phase-researcher (only with --research or workflow.research: at most 5 questions → research.md)
+  ├── pan-planner
+  └── pan-plan-checker (after planner; 2 checks on the sized ceremony, 3 under full ceremony)
+
+/pan:exec-phase N
+  │
+  ├── pan-executor (per plan, wave-based parallelism)
+  ├── /pan:phase-tests (auto test generation, skippable; a lean phase skips it)
+  ├── pan-reviewer (code review, skippable; a lean phase keeps it)
+  └── pan-verifier (after all executors complete, with test gate)
+
+autodev, lean phase (one session, workflows/exec-lean.md)
+  │
+  ├── the session does the executor's work itself
+  ├── pan-reviewer (one pass, one fix round)
+  └── pan-verifier
+
+/pan:milestone-audit
+  │
+  └── pan-integration-checker (cross-phase verification)
+
+/pan:debug
+  │
+  └── pan-debugger (standalone, persistent state)
+```
+
+This file-mediated communication means:
+- Agents can run in parallel (researchers, codebase mappers, executors in the same wave)
+- Failed agents can be re-run without losing other agents' work
+- Every intermediate artifact is inspectable on disk
+- The orchestrator's context window stays light — heavy work happens in agent contexts
+
+---
+
+## Parallel Execution Patterns
+
+### Research Phase
+```text
+/pan:plan-phase N
+  └── pan-phase-researcher
+       │
+       └── Writes research.md
+```
+
+### Codebase Mapping (6 parallel, or one single-shot pass)
+```text
+/pan:map-codebase
+  ├── pan-document_code (tech)           → stack.md, integrations.md
+  ├── pan-document_code (arch)           → architecture.md, structure.md
+  ├── pan-document_code (quality)        → conventions.md, testing.md
+  ├── pan-document_code (concerns)       → concerns.md
+  ├── pan-document_code (relationships)  → relationships.md
+  └── pan-document_code (practices)      → best-practices.md
+```
+
+### Plan Execution (wave-based)
+```text
+/pan:exec-phase N
+  Wave 1 (independent plans):
+    ├── pan-executor (Plan 01) → commit
+    └── pan-executor (Plan 02) → commit
+  Wave 2 (depends on Wave 1):
+    └── pan-executor (Plan 03) → commit
+  Post-execution:
+    └── pan-verifier → verification.md
+```
+
+---
+
+## Agent Design Principles
+
+Four principles are shared across all agents:
+
+### 1. Goal-Backward Thinking
+Start from what must be TRUE when the work is done, then work backwards to what must be built. This prevents the common failure of completing tasks without achieving goals.
+
+Used by: `pan-planner` (must_haves derivation), `pan-verifier` (Observable Truths), `pan-plan-checker` (verification derivation), `pan-roadmapper` (success criteria).
+
+### 2. Professional Skepticism
+Verify actual state — don't trust claims. The verifier checks real code, not summary.md. The plan-checker validates plans deliver goals, not just describe them. Researchers treat training data as hypothesis.
+
+Used by: `pan-verifier` ("DO NOT trust summary.md"), `pan-phase-researcher` (confidence levels), `pan-plan-checker` (multi-dimension validation).
+
+### 3. Structured Returns
+Every agent returns data in machine-parseable formats (YAML frontmatter, structured markdown sections, JSON). This enables orchestrators to route results programmatically and enables downstream agents to parse inputs reliably.
+
+Used by: All agents — plan.md frontmatter, verification.md gap YAML, the `pan-verdict` block that ends every plan-checker, reviewer and design-checker report, debug session state machine.
+
+### 4. File-Mediated Communication
+Agents never call each other. All data flows through `.planning/` files on disk. This makes every intermediate artifact inspectable, enables parallel execution, and means failed agents can be re-run without losing sibling work.
+
+Used by: All agents — researchers write research.md, planner reads it; executor writes code, verifier checks it.
+
+---
+
+## Customizing Agents
+
+Agent files are installed alongside commands. Location depends on runtime and install scope:
+
+| Runtime | Global | Local |
+|---------|--------|-------|
+| Claude Code | `~/.claude/agents/*.md` | `.claude/agents/*.md` |
+| OpenCode | `~/.config/opencode/agents/*.md` | `.opencode/agents/*.md` |
+| Gemini CLI | `~/.gemini/agents/*.md` | `.gemini/agents/*.md` |
+| Codex | `~/.codex/agents/*.toml` | `.codex/agents/*.toml` |
+| Copilot CLI | `~/.copilot/agents/*.agent.md` | `.github/agents/*.agent.md` |
+
+> **Note:** Copilot CLI uses the `.agent.md` extension; Codex uses standalone `.toml` agent files (markdown in `.codex/agents/` is not recognized). Claude, OpenCode, and Gemini use `.md`.
+
+### Common Customizations
+
+- Add domain-specific constraints to the agent's procedure section — `<execution_flow>`, `<process>`, `<verification_process>`, `<reasoning_protocol>` or `<review_checks>` for most agents; the tag varies by agent (e.g., "Always use TypeScript strict mode")
+- Modify output format requirements in the agent's output section — `<output_format>`, `<output>`, `<output_contract>` or `<structured_returns>` for most agents; for plan.md it is `pan-planner`'s `<plan_format>` (e.g., custom plan.md sections)
+- Add project-specific patterns to `<project_context>` (e.g., "This project uses a monorepo with pnpm workspaces")
+
+### Preserving Customizations
+
+After a PAN update (`npx pan-wizard@latest`), local modifications may be overwritten. The installer backs up modified files to `pan-local-patches/` before overwriting. Run `/pan:patches` to restore your changes.