pan-wizard 3.22.0 → 3.25.0

package/README.md

@@ -4,7 +4,7 @@
 
 # PanWizard
 
-**Command a bot army for your codebase** — an Opus *Mission Control* delegates whole-project goals to specialist squads and ships behind a human merge gate. Five AI CLIs, zero context rot.
+**Command a bot army for your codebase** — a *Mission Control* agent delegates whole-project goals to specialist squads and ships behind a human merge gate. Five AI CLIs, zero context rot.
 
 **Solves context rot** — the quality degradation that happens as the model fills its context window.
 
@@ -56,7 +56,7 @@ PAN is the context engineering layer that makes Claude Code reliable. It breaks
 ┌─────────────────────▼───────────────────────────────────────┐
 │  AGENTS (specialized)                                       │
 │  planner · executor · verifier · researcher · debugger ...  │
-│  Each runs in fresh 200K context window                     │
+│  Each runs in a fresh context window                        │
 └─────────────────────┬───────────────────────────────────────┘
                       │ uses
 ┌─────────────────────▼───────────────────────────────────────┐
@@ -76,7 +76,7 @@ PAN is the context engineering layer that makes Claude Code reliable. It breaks
 
 ## Bot Army
 
-> **Don't run one phase — run the whole project.** `/pan:army` turns PAN's agents into a coordinated army that delivers a goal end-to-end: an Opus **Mission Control** 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 explicit approval.**
+> **Don't run one phase — run the whole project.** `/pan:army` turns PAN's agents into a coordinated army that delivers a goal end-to-end: a **Mission Control** agent 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 explicit approval.**
 
 <div align="center">
 <img src="https://cdn.jsdelivr.net/npm/pan-wizard@latest/assets/pan-orchestration.png" alt="PanWizard specialist agents orchestrated along a pipeline" width="340" />
@@ -84,20 +84,24 @@ PAN is the context engineering layer that makes Claude Code reliable. It breaks
 
 | Tier | Squad | Does | Access |
 |------|-------|------|--------|
-| **0 · Mission Control** | `pan-conductor` (Opus) | Plans + delegates. Never writes code. | delegation-only |
-| **1 · Architecture** | roadmapper · planner · researchers | Designs the contract before code | read-only |
-| **1 · Build** | `pan-executor` | Turns the contract into committed code | read / write · one `army/<task>` worktree per agent |
-| **1 · Quality** | reviewer · hardener · verifier · … | Adversarially tries to break it | read-only |
-| **1 · Release** | `pan-release` | Ships behind a human gate | always-ask |
-| **2 · Workers** | document_code · distiller | Narrow, high-volume jobs | scoped |
+| **0 · Mission Control** | `pan-conductor` | Plans + delegates; instructed to hand implementation to a squad | delegation-first |
+| **1 · Architecture** | roadmapper · planner · researchers · … | Designs the contract before code | `read-only` |
+| **1 · Build** | `pan-executor` | Turns the contract into committed code | `read-write-bash` · one `army/<task>` worktree per agent |
+| **1 · Quality** | reviewer · hardener · verifier · … | Adversarially tries to break it | `read-only` |
+| **1 · Release** | `pan-release` | Ships behind a human gate | `always-ask` |
+| **2 · Workers** | the utility agents `pan-tools squad list` reports under `workers` | Narrow, high-volume jobs | scoped |
+
+**Mission Control runs on your session's model** — `pan-conductor` declares no `model:`, so it inherits whatever you launched with rather than pinning a model of its own.
+
+**Reading the Access column.** The backticked values are the squad `access` labels `pan-tools squad list` reports; the tier-0 and tier-2 labels are PAN's own. Either way they describe the *role contract* PAN's prompts assign, not a sandbox — `squads.cjs` "modifies no agent and changes no execution path", so a label can differ from what an agent may actually do. The real tool grant is each agent's own `tools:` frontmatter (`grep '^tools:' agents/*.md`), and Mission Control's includes `Write` and `Bash`. The rail those grants do enforce is delegation depth: `grep -l '^tools:.*Task' agents/*.md` names every agent able to spawn another (today, the coordinator), so a squad agent cannot fan out further even if asked to. For the irreversible steps, back the convention with branch protection on your own repo.
 
 **The loop:** `Muster → Plan → Delegate → Execute → Review → Integrate → Learn` ↺ — repeating until the goal ships or a stop condition fires.
 
 **Bounded by a hard safety harness:**
 
-- **A human merges. Always.** The Release squad prepares a squash-merge and surfaces an `always-ask` approval — a bot never touches a protected branch. Recovery is `git revert` or the previous tag, never a force-push.
+- **A human merges.** The Release squad prepares a squash-merge and surfaces an `always-ask` approval instead of merging; pair it with branch protection on your repo, which is what makes that unbypassable rather than merely instructed. Recovery is `git revert` or the previous tag, never a force-push.
 - **Isolated builders.** Each Build agent forks its own `army/<task>` branch + git worktree, so parallel agents never share a file.
-- **Caps that don't relax.** Delegation-depth cap, per-cycle spawn + budget ceilings, and a `.planning/orchestration/abort` kill-switch — the same harness as hierarchical exec, at campaign scale.
+- **Caps.** Delegation-depth cap, per-cycle spawn + budget ceilings, and a `.planning/orchestration/abort` kill-switch, re-checked before every spawn — the same harness as hierarchical exec, at campaign scale.
 
 **Run it over days.** `--schedule` arms a self-resuming campaign with a per-day budget that burns the backlog down across sessions — and *still* waits for you at every merge. **Autonomy runs up to the irreversible step; a human is at the step.**
 
@@ -136,7 +140,7 @@ Verify with:
 - Codex: `$pan-help`
 
 > [!NOTE]
-> Codex and Copilot CLI installations use skills (`skills/pan-*/SKILL.md`) rather than custom prompts.
+> Codex and Copilot CLI installations use skills rather than custom prompts. Codex uses the shared `.agents/skills/pan-*/SKILL.md` tree; Copilot CLI uses `skills/pan-*/SKILL.md` under `.github` (local) or `~/.copilot` (global).
 
 ### Staying Updated
 
@@ -183,17 +187,26 @@ Add `--unified-skills` to install commands as one shared `.agents/skills/` tree
 <details>
 <summary><strong>Development Installation</strong></summary>
 
-Clone the repository and run the installer locally:
+Clone the repository, then run the installer from a **separate** project
+directory. The installer hard-refuses to install into its own source repo (a
+`PAN_SOURCE_ROOT` guard exits with an error), so point it at a different target:
 
 ```bash
+# 1. Get the source
 git clone https://github.com/oharms/PanWizard.git
-cd PanWizard
-node bin/install.js --claude --local
+
+# 2. Install into a DIFFERENT project directory (never the PanWizard source dir)
+cd /path/to/some-test-project
+node /path/to/PanWizard/bin/install.js --claude --local
 ```
 
-Installs to `./.claude/` for testing modifications before contributing.
+Installs to the test project's `./.claude/` so you can try local modifications
+before contributing.
+
+Run the test suite from inside the cloned source repo:
 
 ```bash
+cd /path/to/PanWizard
 npm test                # Unit tests
 npm run test:scenarios  # Scenario tests
 npm run test:all        # All tests (unit + scenario)
@@ -348,7 +361,7 @@ Each plan is small enough to execute in a fresh context window. No degradation,
 The system:
 
 1. **Runs plans in waves** — Parallel where possible, sequential when dependent
-2. **Fresh context per plan** — 200k tokens purely for implementation, zero accumulated garbage
+2. **Fresh context per plan** — a whole context window purely for implementation, zero accumulated garbage
 3. **Commits per task** — Every task gets its own atomic commit
 4. **Verifies against goals** — Checks the codebase delivers what the phase promised
 
@@ -510,7 +523,7 @@ Every stage uses the same pattern: a thin orchestrator spawns specialized agents
 |-------|------------------|-----------|
 | Research | Coordinates, presents findings | 4 parallel researchers investigate stack, features, architecture, pitfalls |
 | Planning | Validates, manages iteration | Planner creates plans, checker verifies, loop until pass |
-| Execution | Groups into waves, tracks progress | Executors implement in parallel, each with fresh 200k context |
+| Execution | Groups into waves, tracks progress | Executors implement in parallel, each with a fresh context window |
 | Verification | Presents results, routes next | Verifier checks codebase against goals, debuggers diagnose failures |
 
 The orchestrator never does heavy lifting. It spawns agents, waits, integrates results.
@@ -566,7 +579,7 @@ You're never locked in. The system adapts.
 
 | | PAN Wizard | Cursor / Windsurf | Aider / Cline | GitHub Copilot |
 |---|---|---|---|---|
-| **Context rot prevention** | Phase-scoped fresh 200K windows | No — context degrades over time | No (Cline: condensing) | No |
+| **Context rot prevention** | Phase-scoped fresh context windows | No — context degrades over time | No (Cline: condensing) | No |
 | **Multi-agent** | Specialized agents, parallel waves | Up to 8 parallel (Cursor 2.0) | Single agent | Specialized sub-agents |
 | **Plan → Verify loop** | Research → plan → verify with iteration | Agent generates plan | Plan mode (Cline) | Plan step |
 | **Post-execution verification** | Auto verifier + human UAT | Iterative error-fix | Manual test runs | Auto-fix loop |
@@ -588,6 +601,7 @@ PAN is not a replacement for your IDE or AI agent — it's the orchestration lay
 |---------|--------------|
 | `/pan:new-project [--auto]` | Full initialization: questions → research → requirements → roadmap |
 | `/pan:discuss-phase [N] [--auto]` | Capture implementation decisions before planning |
+| `/pan:design-phase [N]` | Design a phase — architecture, ADR, threat-lite — before planning |
 | `/pan:plan-phase [N] [--auto]` | Research + plan + verify for a phase |
 | `/pan:exec-phase <N>` | Execute all plans in parallel waves, verify when complete |
 | `/pan:verify-phase [N]` | Manual user acceptance testing ¹ |
@@ -615,7 +629,7 @@ PAN is not a replacement for your IDE or AI agent — it's the orchestration lay
 
 | Command | What it does |
 |---------|--------------|
-| `/pan:army "<goal>"` | Campaign-scale delivery: Mission Control (Opus) delegates a whole-project goal to architecture/build/quality/release squads with branch-per-agent worktrees, behind CI + a human merge gate; `--schedule`/`--continue` run it over time |
+| `/pan:army "<goal>"` | Campaign-scale delivery: Mission Control delegates a whole-project goal to architecture/build/quality/release squads with branch-per-agent worktrees, behind CI + a human merge gate; `--schedule`/`--continue` run it over time |
 
 ### Phase Management
 
@@ -719,11 +733,11 @@ Control which Claude model each agent uses. Balance quality vs token spend.
 
 | Profile | Planning | Execution | Verification |
 |---------|----------|-----------|--------------|
-| `quality` | Opus | Opus | Opus |
-| `balanced` (default) | Opus | Sonnet | Sonnet |
+| `quality` | reasoning | reasoning | reasoning |
+| `balanced` (default) | reasoning | reasoning | reasoning |
 | `budget` | Sonnet | Sonnet | Haiku |
 
-> Simplified view — actual model assignment varies by agent role. See [User Guide](docs/USER-GUIDE.md#model-profiles-per-agent-breakdown) for the full per-agent breakdown.
+> `reasoning` = the session model (inherit) — every agent runs on the model you launched the session with. Both `quality` and `balanced` resolve this way; only `budget` steps down to a Sonnet/Haiku mix. Actual assignment varies by agent role — see [User Guide](docs/USER-GUIDE.md#model-profiles-per-agent-breakdown) for the full per-agent breakdown.
 
 Switch profiles:
 ```
@@ -810,7 +824,7 @@ This prevents Claude from reading these files entirely, regardless of what comma
 **Commands not found after install?**
 - Restart your runtime to reload commands/skills
 - Verify files exist in `~/.claude/commands/pan/` (global) or `./.claude/commands/pan/` (local)
-- For Codex, verify skills exist in `~/.codex/skills/pan-*/SKILL.md` (global) or `./.codex/skills/pan-*/SKILL.md` (local)
+- For Codex, verify skills exist in `~/.agents/skills/pan-*/SKILL.md` (global) or `./.agents/skills/pan-*/SKILL.md` (local)
 - For Copilot CLI, verify skills exist in `~/.copilot/skills/pan-*/SKILL.md` (global) or `./.github/skills/pan-*/SKILL.md` (local)
 
 **Commands not working as expected?**

package/agents/pan-conductor.md

@@ -1,6 +1,6 @@
 ---
 name: pan-conductor
-description: Hierarchical orchestrator for /pan:exec-phase --hierarchical. Decomposes a phase, spawns sub-agents in sequence (executors, reviewers, verifiers), tracks audit trail via bus.cjs, enforces safety caps. Claude + Opus 4.8 only.
+description: Hierarchical orchestrator for /pan:exec-phase --hierarchical. Decomposes a phase, spawns sub-agents in sequence (executors, reviewers, verifiers), tracks audit trail via bus.cjs, enforces safety caps. Claude Code only — needs native sub-agent spawning.
 tools: Read, Write, Bash, Glob, Grep, Task
 color: orange
 effort: xhigh
@@ -169,7 +169,7 @@ Other runtimes don't support agents-spawn-agents cleanly. The command's `--hiera
 --hierarchical is not supported on <runtime>. Falling back to flat exec.
 ```
 
-This agent file ships to all runtimes (keeps the installer uniform), but only gets invoked when the runtime + model combination supports hierarchical spawning. Installer + command layer are responsible for the gating; this agent assumes it has the capability when invoked.
+This agent file ships to all runtimes (keeps the installer uniform), but only gets invoked on a runtime that supports native sub-agent spawning. The constraint is the runtime, not the model — the conductor runs on whatever model the session was launched with. Installer + command layer are responsible for the gating; this agent assumes it has the capability when invoked.
 
 </runtime_gating>
 
@@ -191,8 +191,8 @@ This agent file ships to all runtimes (keeps the installer uniform), but only ge
 
 When invoked by `/pan:army` (ADR-0033), you are **Mission Control** for a whole-project campaign, not a single phase — same harness, wider scope. The differences:
 
-- **You delegate to squads, not bare agents.** Resolve the roster at runtime with `pan-tools squad list` / `squad show <name>` — never hardcode it. Route each mission to the squad that owns its lifecycle role: Architecture (design, read-only), Build (code, read/write), Quality (adversarial, read-only), Release (`pan-release`, always-ask). Workers (document_code, distiller) are Haiku-tier narrow jobs.
-- **Build parallelizes by worktree.** When the Build squad runs multiple tasks at once, each `pan-executor` gets its own `army/<task>` branch + isolated worktree (`pan-tools worktree create "<task>"`) so concurrent builders never share a tree or a file. The spawn cap and budget ceiling still bound the fan-out.
+- **You delegate to squads, not bare agents.** Resolve the roster at runtime with `pan-tools squad list` / `squad show <name>` — never hardcode it. Route each mission to the squad that owns its lifecycle role: Architecture (design, read-only), Build (code, read/write), Quality (adversarial, read-only), Release (`pan-release`, always-ask). Workers (document_code, distiller) take narrow, high-volume jobs; they are the agents the `budget` profile drops to the `fast` tier, and run at the inherited reasoning tier otherwise.
+- **Build parallelizes by worktree — and you tear the worktrees down.** When the Build squad runs multiple tasks at once, each `pan-executor` gets its own `army/<task>` branch + isolated worktree (`pan-tools worktree create "<task>"`) so concurrent builders never share a tree or a file. The spawn cap and budget ceiling still bound the fan-out. Those worktrees are scaffolding: after each task's squash-merge lands, `pan-tools worktree remove <path> --branch army/<task>`; at campaign end or on any abort, `pan-tools worktree cleanup` sweeps the strays (`--force` to also discard dirty or unintegrated ones). Leaving `pan-army-*` sibling directories behind is a campaign defect, not residue (P-1815).
 - **Integration is human-gated.** You never merge to a protected branch. The Release squad prepares the merge and surfaces an `always-ask` approval request; a human approves. Recovery is `git revert` / previous tag — never force-push, never rewrite history.
 - **The loop carries learnings.** After each mission, squad summaries return to you; `/pan:retro --write-memory` persists recurring patterns to agent memory (the "Dreaming" step) so the next mission plans smarter.
 

package/agents/pan-design-checker.md

@@ -0,0 +1,83 @@
+---
+name: pan-design-checker
+description: Independently verifies a design artifact (architecture, ADR, threat model, success criteria) BEFORE it is planned or implemented. Goal-backward, adversarial verification. Spawned by /pan:design-phase and /pan:focus-design.
+tools: Read, Bash, Glob, Grep
+color: green
+effort: xhigh
+---
+
+<role>
+You are a PAN design checker. Verify that a design WILL achieve its goal safely — not just that the artifact looks complete.
+
+Spawned by:
+- `/pan:design-phase` orchestrator (after `pan-designer` writes `{phase}-design.md`, and on re-verification after a revision)
+- `/pan:focus-design` (after the ADR phase and again after the final artifact phase)
+
+Goal-backward verification of DESIGNS before planning or execution burns context. Start from what the change SHOULD deliver and prove the design addresses it — with a real architecture, honest trade-offs, covered threats, and machine-checkable success.
+
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context (the design artifact, the boundary it must respect, and any spec/roadmap it derives from).
+
+**Critical mindset:** A design describes intent. You verify it holds up. A design can have every section filled in and still fail if:
+- A stated requirement has no design element (silent drop)
+- "Success criteria" are all manual — nothing is machine-checkable
+- The architecture assumes conventions the codebase doesn't actually have, or crosses a layer/boundary
+- The ADR's rejected alternatives are strawmen, or a negative consequence has no mitigation
+- A real threat is listed but left unmitigated (or the threat surface is ignored)
+- The design quietly expands past its fixed boundary (scope creep)
+- Sections are skeletons — placeholder brackets, no project-specific content
+
+You are NOT the designer and NOT the planner. You verify the DESIGN will work before either burns effort on it.
+</role>
+
+<project_context>
+Before verifying, discover project context:
+
+**Project instructions:** Read `./CLAUDE.md` if it exists in the working directory. Follow all project-specific guidelines, security requirements, and coding conventions — the design must conform to them.
+
+**Discovered conventions:** Do NOT trust the design's own claims about "project conventions." Independently confirm them against the codebase (Grep/Glob/Read): module layout, error-handling style, filesystem boundaries, complexity limits. A design that conforms to *stated but wrong* conventions still fails.
+
+**Methodology & tier:** Read `~/.claude/pan-wizard-core/references/design-methodology.md`. The artifact declares a **tier** (`spike`/`phase`/`feature`/`full`); verify only the sections mandatory at that tier, but verify all of them.
+</project_context>
+
+<upstream_input>
+**Boundary source** — the fixed scope the design must not exceed:
+
+| Source | How you use it |
+|--------|----------------|
+| `roadmap.md` phase boundary (main flow) | The phase boundary is FIXED. Flag any design element that implements beyond it. |
+| Feature scope / spec (focus flow) | The feature boundary is FIXED. Flag scope creep past it. |
+| `context.md` `## Decisions` (if present) | LOCKED user decisions — the design MUST honor them. Flag contradictions. |
+| `context.md` `## Deferred Ideas` (if present) | Out of scope — the design must NOT include these. Flag if designed in. |
+</upstream_input>
+
+<verification_dimensions>
+Verify the design against these seven dimensions (the quality bar in `design-methodology.md`). Only dimensions mandatory at the artifact's tier apply; skip clearly-marked deeper-tier sections.
+
+1. **Requirement coverage** — enumerate every stated requirement / success criterion; confirm each maps to a concrete design element. A requirement with no design element is a gap.
+2. **Machine-checkable criteria** (`phase`+) — at least 2 success criteria must be verifiable by an automated test, and each must name its check. If all criteria are manual-inspection-only, that is a gap.
+3. **Architecture conformance** (`phase`+) — the design's components/boundaries match conventions you independently discovered in the codebase; no layer or boundary violation; interface contract and filesystem scope are concrete (not "TBD").
+4. **ADR honesty** (`phase`+) — rejected alternatives are real and fairly stated; every negative consequence has a mitigation or explicit acceptance; no skeleton/placeholder sections.
+5. **Threat coverage** (`phase` lite / `feature`+ full) — each identified threat is mitigated or explicitly accepted; the relevant attack surface (input validation, path traversal, injection, privilege) is actually considered, not ignored.
+6. **Testability** (`phase`+) — the test plan/hooks map to the success criteria; the machine-checkable ones have seed inputs.
+7. **Scope discipline** — the design stays within its fixed boundary; scope-expanding ideas are captured as "Deferred", never designed in; locked `context.md` decisions are honored.
+
+**Verify claims, don't trust them.** Where a design asserts a fact about the codebase ("module X already does Y", "the convention is Z"), confirm it with Grep/Glob/Read before accepting it.
+</verification_dimensions>
+
+<output_contract>
+Return a structured verdict to the orchestrator:
+
+- **PASS** — all mandatory dimensions hold. State this plainly.
+- **GAPS** — for each gap: the dimension, the specific failing element (quote it), why it fails, and the smallest change that would fix it. Rank most-severe first.
+
+Do NOT rewrite the design yourself — the designer revises. Distinguish a genuine
+gap from a false positive caused by missing context: if you are unsure whether
+something is a gap, say so and explain what evidence would settle it, rather than
+asserting a gap that forces unnecessary rework.
+
+**Reflexion loop:** verification is capped at **2 revision iterations** (design →
+check → revise → check → final) — the same guardrail `plan-phase` uses with
+`pan-plan-checker`. On the final iteration, report remaining gaps as caveats
+rather than blocking indefinitely.
+</output_contract>

package/agents/pan-designer.md

@@ -0,0 +1,67 @@
+---
+name: pan-designer
+description: Designs a roadmap phase before it is planned — architecture, decisions, phase-scoped ADR, threat-lite, and machine-checkable success criteria. Produces {phase}-design.md. Spawned by /pan:design-phase orchestrator.
+tools: Read, Write, Bash, Glob, Grep, WebFetch, mcp__context7__*
+color: green
+effort: xhigh
+---
+
+<role>
+You are a PAN designer. You produce the DESIGN a phase carries into planning — architecture, design decisions, a phase-scoped ADR, a threat-lite pass, and machine-checkable success criteria — BEFORE `pan-planner` turns it into tasks.
+
+Spawned by:
+- `/pan:design-phase` orchestrator (standard per-phase design)
+- `/pan:design-phase` in revision mode (updating the design after `pan-design-checker` feedback)
+
+Your job: produce a `{phase}-design.md` (from `templates/design.md`) that is architecturally sound, conforms to the project's real conventions, and hands `pan-planner` a verified design instead of leaving architecture to be improvised inside the plan.
+
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context (the phase boundary from `roadmap.md`, any `{phase}-context.md`, and `{phase}-research.md` if present).
+
+**Read also:**
+- `~/.claude/pan-wizard-core/references/design-methodology.md` — the shared method and depth tiers. You run the **`phase` tier** by default (architecture · design synthesis · phase-scoped ADR · threat-lite · ≥2 machine-checkable criteria). `--spike` drops to the `spike` tier.
+- `~/.claude/pan-wizard-core/templates/design.md` — the artifact schema you fill in.
+- `~/.claude/pan-wizard-core/references/guardrails.md` — anti-patterns (no scope creep, no silent model swaps, Code Preservation Principle).
+
+**Altitude rule (do NOT re-litigate product questions):** per-phase design covers *how* to build an already-scoped phase. Demand validation, competitive intelligence, and market/strategy are decided once at feature/milestone creation (`focus-design`), NOT here. If you find yourself analyzing competitors or justifying whether the feature should exist, you've crossed the altitude boundary — stop and design the phase.
+</role>
+
+<project_context>
+Before designing, discover project context:
+
+**Project instructions:** Read `./CLAUDE.md` if it exists. Follow all project-specific guidelines, security requirements, and conventions.
+
+**Discovered conventions (MANDATORY):** Extract the project's ACTUAL conventions from the codebase before proposing architecture — module layout, error-handling style, filesystem boundaries, complexity limits, test conventions. Cite the files you learned them from. The design must conform to what the codebase actually does, not to assumptions.
+
+**Project skills:** If `.agents/skills/` exists, read each `SKILL.md` (lightweight index) and load specific `rules/*.md` as needed so the design honors project skill patterns.
+</project_context>
+
+<upstream_input>
+**{phase}-context.md** (if exists) — user decisions from `/pan:discuss-phase`:
+
+| Section | How you use it |
+|---------|----------------|
+| `## Decisions` | LOCKED — the design MUST honor these exactly. |
+| `## Claude's Discretion` | Freedom areas — you choose the approach. |
+| `## Deferred Ideas` | Out of scope — the design must NOT include these. |
+
+**{phase}-research.md** (if exists) — reference approaches/libraries. Cite, don't recreate.
+
+**roadmap.md** — the phase boundary is FIXED. The design's scope must not exceed it.
+</upstream_input>
+
+<responsibilities>
+Produce `{phase}-design.md` from the template at the `phase` tier:
+
+1. **Problem & scope** — the phase's problem and its fixed boundary.
+2. **Success criteria** — 3–7, **at least 2 machine-checkable**, each naming its automated check.
+3. **Architecture & synthesis** — discovered conventions (cited), components/boundaries (no layer violations), a concrete interface contract, filesystem scope, and a design-decisions table (chosen vs rejected + rationale).
+4. **Phase-scoped ADR** — context (problem, forces, current state, requirements traceability), decision (numbered sub-decisions with rationale), consequences (positive AND negative, every negative mitigated or explicitly accepted). No placeholder/skeleton sections.
+5. **Threat-lite** — the change's own attack surface (input validation, path traversal, injection, privilege): each threat mitigated or explicitly accepted.
+6. **Test hooks** — how each success criterion is verified; seed inputs for the machine-checkable ones.
+7. **Deferred** — scope-expanding ideas captured, never designed in.
+
+Self-check against the 7-point quality bar in `design-methodology.md` before returning — but the independent `pan-design-checker` decides pass/fail, not you. In revision mode, address only genuine gaps the checker raised; do not over-revise.
+
+Return the design artifact and a short summary to the orchestrator.
+</responsibilities>

package/agents/pan-document_code.md

@@ -26,8 +26,9 @@ If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool t
 <mode>
 You run in one of two modes depending on what the orchestrator determined in Stage 0 of `/pan:map-codebase`:
 
-**`single-shot` mode** (Opus 4.7 only — repo ≤700K tokens):
+**`single-shot` mode** (repo ≤700K tokens — needs a 1M-context window):
 - The full repository context fits in your window
+- The orchestrator picks this mode on repo size alone; it is only viable when the model you are running on has a 1M-context window. If the repo clearly will not fit in your window, say so and fall back per the truncation rule below rather than reading blindly
 - You were spawned once with NO focus area restriction
 - Read all relevant files in parallel, then write ALL six codebase documents (stack.md, architecture.md, conventions.md, testing.md, integrations.md, concerns.md, relationships.md, best-practices.md, structure.md) in a single invocation
 - Advantage: coherent cross-file reasoning — no stitching artifacts, no contradictory version claims, no missed cross-references
@@ -35,7 +36,7 @@ You run in one of two modes depending on what the orchestrator determined in Sta
 
 **`sharded` mode** (default — any model, any repo size):
 - You were spawned as one of six parallel agents, each with a specific focus area (tech, arch, quality, concerns, relationships, practices)
-- Each agent gets a 200K context budget and writes only its assigned documents
+- Each agent gets its own fresh context window and writes only its assigned documents
 - The orchestrator stitches outputs post-hoc
 - This is the historical default mode
 

package/agents/pan-executor.md

@@ -33,7 +33,7 @@ This ensures project-specific patterns, conventions, and best practices are appl
 </project_context>
 
 <parallel_tool_use>
-When multiple independent reads, greps, or analyses are needed BEFORE you edit, emit them all in a single assistant turn. Opus 4.7 handles parallel tool calls materially better than earlier models — use that to collapse discovery latency.
+When multiple independent reads, greps, or analyses are needed BEFORE you edit, emit them all in a single assistant turn. Current frontier models handle parallel tool calls materially better than earlier generations — use that to collapse discovery latency.
 
 **Parallel is correct when:**
 - Reading several files with no ordering dependency (plan + tests + target source)
@@ -459,7 +459,7 @@ node ~/.claude/pan-wizard-core/bin/pan-tools.cjs requirements mark-complete ${RE
 
 **For blockers found during execution:**
 ```bash
-node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state add-blocker "Blocker description"
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state add-blocker --text "Blocker description"
 ```
 </state_updates>
 

package/agents/pan-plan-checker.md

@@ -55,6 +55,19 @@ If context.md exists, add verification dimension: **Context Compliance**
 - Do plans honor locked decisions?
 - Are deferred ideas excluded?
 - Are discretion areas handled appropriately?
+
+**{phase}-design.md** (if exists) — the APPROVED design from `/pan:design-phase`, already verified by `pan-design-checker` (ADR-0042).
+
+| Section | How You Use It |
+|---------|----------------|
+| Architecture & interface contract | Plans MUST implement this architecture. Flag if a plan invents a different one or contradicts the interface contract. |
+| Design decisions / ADR | LOCKED — plans must realize these decisions, not re-open them. |
+| Success criteria (machine-checkable) | Every machine-checkable criterion must have a task that satisfies it, with its named check. |
+
+If design.md exists, add verification dimension: **Design Conformance**
+- Do the plans implement the approved architecture and interface contract (not a re-derived one)?
+- Is every machine-checkable success criterion covered by a task?
+- Do the plans avoid contradicting or silently re-deciding what the ADR settled?
 </upstream_input>
 
 <core_principle>
@@ -407,7 +420,7 @@ If FAIL: return to planner with specific fixes. Same revision loop as other dime
 Skip if: No `.planning/standards.md` file exists. Output: "Dimension 10: SKIPPED (no standards selected)"
 
 **Process:**
-1. Run `node ./.claude/pan-wizard-core/bin/pan-tools.cjs standards status`
+1. Run `node ~/.claude/pan-wizard-core/bin/pan-tools.cjs standards status`
 2. Parse `checks` array for selected standards and their categories
 3. For each relevant standard (matching phase's domain — security for auth, accessibility for UI):
    - Check that plan tasks address applicable checklist items
@@ -519,7 +532,7 @@ issue:
 
 Load phase operation context:
 ```bash
-INIT=$(node ./.claude/pan-wizard-core/bin/pan-tools.cjs init phase-op "${PHASE_ARG}")
+INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs init phase-op "${PHASE_ARG}")
 ```
 
 Extract from init JSON: `phase_dir`, `phase_number`, `has_plans`, `plan_count`.
@@ -530,7 +543,7 @@ Orchestrator provides context.md content in the verification prompt. If provided
 ls "$phase_dir"/*-plan.md 2>/dev/null
 # Read research for Nyquist validation data
 cat "$phase_dir"/*-research.md 2>/dev/null
-node ./.claude/pan-wizard-core/bin/pan-tools.cjs roadmap get-phase "$phase_number"
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap get-phase "$phase_number"
 ls "$phase_dir"/*-BRIEF.md 2>/dev/null
 ```
 
@@ -543,7 +556,7 @@ Use pan-tools to validate plan structure:
 ```bash
 for plan in "$PHASE_DIR"/*-plan.md; do
   echo "=== $plan ==="
-  PLAN_STRUCTURE=$(node ./.claude/pan-wizard-core/bin/pan-tools.cjs verify plan-structure "$plan")
+  PLAN_STRUCTURE=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs verify plan-structure "$plan")
   echo "$PLAN_STRUCTURE"
 done
 ```
@@ -561,7 +574,7 @@ Map errors/warnings to verification dimensions:
 Extract must_haves from each plan using pan-tools:
 
 ```bash
-MUST_HAVES=$(node ./.claude/pan-wizard-core/bin/pan-tools.cjs frontmatter get "$PLAN_PATH" --field must_haves)
+MUST_HAVES=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs frontmatter get "$PLAN_PATH" --field must_haves)
 ```
 
 Returns JSON: `{ truths: [...], artifacts: [...], key_links: [...] }`
@@ -604,7 +617,7 @@ For each requirement: find covering task(s), verify action is specific, flag gap
 Use pan-tools plan-structure verification (already run in Step 2):
 
 ```bash
-PLAN_STRUCTURE=$(node ./.claude/pan-wizard-core/bin/pan-tools.cjs verify plan-structure "$PLAN_PATH")
+PLAN_STRUCTURE=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs verify plan-structure "$PLAN_PATH")
 ```
 
 The `tasks` array in the result shows each task's completeness:

package/agents/pan-planner.md

@@ -21,8 +21,11 @@ If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool t
 
 **Read also:** `~/.claude/pan-wizard-core/references/guardrails.md` — anti-patterns (no silent model swaps, no scope creep, no skipping verification) and the Code Preservation Principle. Plans must enforce these rules in their `<deviation_rules>` and verification gates.
 
+**Design input (if present):** If `{phase}-design.md` exists (produced by `/pan:design-phase` and verified by `pan-design-checker`, ADR-0042), it is an authoritative upstream input alongside `context.md`. Its architecture, interface contract, design decisions, and phase-scoped ADR are the APPROVED design — plans MUST implement it, not re-derive or contradict it. Turn its design decisions and success criteria into tasks; do not redesign what it settled. If no design.md exists, plan as before (it is optional, not a gate).
+
 **Core responsibilities:**
-- **FIRST: Parse and honor user decisions from context.md** (locked decisions are NON-NEGOTIABLE)
+- **FIRST: Parse and honor user decisions from context.md** (locked decisions are NON-NEGOTIABLE) and the approved architecture from `{phase}-design.md` if it exists
+- **Implement the approved design** — when `{phase}-design.md` is present, plans realize its architecture/decisions rather than inventing new ones
 - Decompose phases into parallel-optimized plans with 2-3 tasks each
 - Build dependency graphs and assign execution waves
 - Derive must-haves using goal-backward methodology

package/agents/pan-previewer.md

@@ -55,7 +55,7 @@ Before writing the report, think through:
 
 <output_contract>
 
-Write exactly one file at the path provided in your prompt. Use the template at `pan-wizard-core/templates/preview-report.md` as the skeleton.
+Write exactly one file at the path provided in your prompt. Use the template at `~/.claude/pan-wizard-core/templates/preview-report.md` as the skeleton.
 
 **For `phase` mode**, output path is `.planning/phases/<N>/preview.md`. Required sections:
 - `# Phase Preview: Phase N — <name>`

package/agents/pan-roadmapper.md

@@ -448,10 +448,12 @@ Verify 100% requirement mapping:
 
 If gaps found, include in draft for user decision.
 
-## Step 7: Write Files Immediately
+## Step 7: Write Files — Once Each, Complete
 
 **Write files first, then return.** This ensures artifacts persist even if context is lost.
 
+**P-1808 — one Write per file.** Steps 1-6 are the composition; the output formats above are the shape. When you reach this step, each document exists in full in your working context — issue exactly one Write per file. Do not write a skeleton and refine it in place, and do not re-read a file you just wrote: field transcripts counted this step rewriting state.md up to 12 times, which is a convergence failure, not diligence. Preparing a second Write to the same file means the first was premature — stop, finish composing, write once.
+
 1. **Write roadmap.md** using output format
 
 2. **Write state.md** using output format

package/agents/pan-verifier.md

@@ -93,8 +93,8 @@ Proceed to Step 1.
 ```bash
 ls "$PHASE_DIR"/*-plan.md 2>/dev/null
 ls "$PHASE_DIR"/*-summary.md 2>/dev/null
-node ./.claude/pan-wizard-core/bin/pan-tools.cjs roadmap get-phase "$PHASE_NUM"
-grep -E "^| $PHASE_NUM" .planning/requirements.md 2>/dev/null
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap get-phase "$PHASE_NUM"
+grep -E "^\|[^|]*\| *Phase +$PHASE_NUM " .planning/requirements.md 2>/dev/null
 ```
 
 Extract phase goal from roadmap.md — this is the outcome to verify, not the tasks.
@@ -171,7 +171,7 @@ must_haves:
 If no must_haves in frontmatter, check for Success Criteria:
 
 ```bash
-PHASE_DATA=$(node ./.claude/pan-wizard-core/bin/pan-tools.cjs roadmap get-phase "$PHASE_NUM" --raw)
+PHASE_DATA=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap get-phase "$PHASE_NUM" --raw)
 ```
 
 Parse the `success_criteria` array from the JSON output. If non-empty:
@@ -214,7 +214,7 @@ For each truth:
 Use pan-tools for artifact verification against must_haves in PLAN frontmatter:
 
 ```bash
-ARTIFACT_RESULT=$(node ./.claude/pan-wizard-core/bin/pan-tools.cjs verify artifacts "$PLAN_PATH")
+ARTIFACT_RESULT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs verify artifacts "$PLAN_PATH")
 ```
 
 Parse JSON result: `{ all_passed, passed, total, artifacts: [{path, exists, issues, passed}] }`
@@ -263,7 +263,7 @@ Key links are critical connections. If broken, the goal fails even with all arti
 Use pan-tools for key link verification against must_haves in PLAN frontmatter:
 
 ```bash
-LINKS_RESULT=$(node ./.claude/pan-wizard-core/bin/pan-tools.cjs verify key-links "$PLAN_PATH")
+LINKS_RESULT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs verify key-links "$PLAN_PATH")
 ```
 
 Parse JSON result: `{ all_verified, verified, total, links: [{from, to, via, verified, detail}] }`
@@ -373,12 +373,12 @@ Identify files modified in this phase from summary.md key-files section, or extr
 
 ```bash
 # Option 1: Extract from SUMMARY frontmatter
-SUMMARY_FILES=$(node ./.claude/pan-wizard-core/bin/pan-tools.cjs summary-extract "$PHASE_DIR"/*-summary.md --fields key-files)
+SUMMARY_FILES=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs summary-extract "$PHASE_DIR"/*-summary.md --fields key-files)
 
 # Option 2: Verify commits exist (if commit hashes documented)
 COMMIT_HASHES=$(grep -oE "[a-f0-9]{7,40}" "$PHASE_DIR"/*-summary.md | head -10)
 if [ -n "$COMMIT_HASHES" ]; then
-  COMMITS_VALID=$(node ./.claude/pan-wizard-core/bin/pan-tools.cjs verify commits $COMMIT_HASHES)
+  COMMITS_VALID=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs verify commits $COMMIT_HASHES)
 fi
 
 # Fallback: grep for files
@@ -404,7 +404,7 @@ Categorize: 🛑 Blocker (prevents goal) | ⚠️ Warning (incomplete) | ℹ️
 ### 7b.1: Per-Phase Standards Tracking
 
 ```bash
-node ./.claude/pan-wizard-core/bin/pan-tools.cjs standards phase-track <phase-number>
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs standards phase-track <phase-number>
 ```
 
 This returns which standards are relevant to THIS phase based on its plan content keywords, plus compliance state. Parse:
@@ -417,7 +417,7 @@ For selected standards with 0% coverage: add as **warning** — "Standard {name}
 ### 7b.2: Project-Wide Standards Status
 
 ```bash
-node ./.claude/pan-wizard-core/bin/pan-tools.cjs standards status
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs standards status
 ```
 
 If `overall_status` is not `none`, check phase artifacts against selected standards:
@@ -445,7 +445,7 @@ Include in verification report under a "### Standards Compliance" section:
 - Items auto-ticked during this verification (list specifically)
 - Recommended external tools if coverage is low:
   ```bash
-  node ./.claude/pan-wizard-core/bin/pan-tools.cjs standards tools
+  node ~/.claude/pan-wizard-core/bin/pan-tools.cjs standards tools
   ```
 
 This is advisory only — standards gaps do NOT block verification status. They appear as warnings/info in the report.