pan-wizard 3.7.10 → 3.10.0

package/README.md

@@ -117,7 +117,7 @@ npx pan-wizard --claude --local    # Install to ./.claude/
 # OpenCode (open source, free models)
 npx pan-wizard --opencode --global # Install to ~/.config/opencode/
 
-# Gemini CLI
+# Gemini CLI (enterprise — see note below)
 npx pan-wizard --gemini --global   # Install to ~/.gemini/
 
 # Codex (skills-first)
@@ -134,6 +134,9 @@ npx pan-wizard --all --global      # Install to all directories
 
 Use `--global` (`-g`) or `--local` (`-l`) to skip the location prompt.
 Use `--claude`, `--opencode`, `--gemini`, `--codex`, `--copilot`, or `--all` to skip the runtime prompt.
+Add `--unified-skills` to install commands as one shared `.agents/skills/` tree read natively by every runtime (and Antigravity CLI) instead of per-runtime formats — see the User Guide for details.
+
+> **Gemini CLI note:** from June 18, 2026, Google's Gemini CLI serves Gemini Code Assist (Standard/Enterprise) customers; individual free / AI Pro / Ultra accounts are directed to Antigravity CLI instead. PAN's `--gemini` target installs for Gemini CLI. Antigravity CLI is not yet a PAN install target, but it reads the shared `.agents/skills/` tree natively — install with `--unified-skills` and PAN's commands are usable from Antigravity in the same project.
 
 </details>
 
@@ -451,6 +454,24 @@ The orchestrator never does heavy lifting. It spawns agents, waits, integrates r
 
 **The result:** You can run an entire phase — deep research, multiple plans created and verified, thousands of lines of code written across parallel executors, automated verification against goals — and your main context window stays at 30-40%. The work happens in fresh subagent contexts. Your session stays fast and responsive.
 
+### Reasoning-Trace Handoff
+
+When agents hand work off via files, only OUTPUTS get passed by default — not the reasoning that produced them. Per Cognition's "Don't build multi-agents" research (June 2025), silent decisions force downstream agents to reconcile contradictions blindly. PAN passes the reasoning explicitly:
+
+- Plans carry a `## Plan Decisions` section (Locked / Open / Considered+rejected buckets) — the executor reads it before coding so it doesn't re-argue settled choices.
+- Summaries carry an `## Implementation Decisions` section — the verifier reads it to understand WHY the executor deviated from the plan, not just THAT it did.
+
+The plan-checker enforces this with two dedicated dimensions (Spec Sufficiency for Handoff, Decision Trace Completeness). Schema lives in `pan-wizard-core/references/handoff-decisions.md`.
+
+### Self-Improving Learnings
+
+PAN runs autonomous experiments in isolated folders, harvests the resulting telemetry, and promotes generalizable findings into a shipped patterns store at `pan-wizard-core/learnings/`:
+
+- `learnings/universal/<topic>.md` — patterns that ship to every install (atomic-state, concurrency, idempotency, secret-handling, test-patterns, …). Loaded by planner / executor / verifier agents during their work.
+- `learnings/internal/<topic>.md` — PAN-development patterns; source-only (stripped at install).
+- `learnings/index.json` — topic→agent-relevance map. Workflows call `pan-tools learn topics-for --agent <role> --token-budget N` to load only relevant patterns instead of skim-everything (avoids the distractor-density anti-pattern).
+- `pan-tools learn lint` — integrity check (duplicate IDs, dangling refs, scope leaks). Wired into `/check`.
+
 ### Atomic Git Commits
 
 Each task gets its own commit immediately after completion:
@@ -553,7 +574,8 @@ PAN is not a replacement for your IDE or AI agent — it's the orchestration lay
 | `/pan:todo-check` | List pending todos |
 | `/pan:debug [desc]` | Systematic debugging with persistent state |
 | `/pan:quick [--full]` | Execute ad-hoc task with PAN guarantees (`--full` adds plan-checking and verification) |
-| `/pan:health [--repair] [--standards]` | Validate `.planning/` directory integrity, auto-repair with `--repair`, standards compliance with `--standards` |
+| `/pan:health [--repair] [--standards] [--full] [--drift] [--links]` | Validate `.planning/` directory integrity. `--repair` auto-fixes; `--standards` checks compliance; `--full` runs tests + build; `--drift` runs convention drift; `--links` attaches doc-code link-graph summary |
+| `/pan:links [--strict]` | Validate the doc-code link graph: inline `[[<id>]]` refs, `// @pan:` source anchors, `require-code-mention` contracts (ADR-0027, v3.8.0+) |
 | `/pan:phase-tests [N]` | Generate tests for a completed phase based on UAT criteria |
 | `/pan:milestone-cleanup` | Archive accumulated phase directories from completed milestones |
 | `/pan:retro` | Milestone retrospective — estimation accuracy, verification patterns, gap analysis |

package/agents/pan-conductor.md

@@ -3,8 +3,7 @@ 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.7 only.
 tools: Read, Write, Bash, Glob, Grep, Task
 color: orange
-thinking: enabled
-thinking_budget: 8000
+effort: xhigh
 ---
 
 <role>

package/agents/pan-counterfactual.md

@@ -3,8 +3,7 @@ name: pan-counterfactual
 description: Explores a phase's alternative scenario in an isolated git worktree, compares against the original plan, and produces a structured report. Destructive-operation gated. Spawned by /pan:what-if.
 tools: Read, Write, Edit, Bash, Grep, Glob
 color: purple
-thinking: enabled
-thinking_budget: 6000
+effort: high
 ---
 
 <role>

package/agents/pan-debugger.md

@@ -3,8 +3,7 @@ name: pan-debugger
 description: Investigates bugs using scientific method, manages debug sessions, handles checkpoints. Spawned by /pan:debug orchestrator.
 tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch
 color: orange
-thinking: enabled
-thinking_budget: 8000
+effort: xhigh
 ---
 
 <role>

package/agents/pan-distiller.md

@@ -3,8 +3,7 @@ name: pan-distiller
 description: AI code-bloat detection and rewrite agent. Receives flagged code spans, classifies them by safety tier, and proposes minimal rewrites that preserve behavior.
 tools: Read, Grep, Glob
 color: cyan
-thinking: enabled
-thinking_budget: 4000
+effort: medium
 ---
 
 <role>

package/agents/pan-document_code.md

@@ -3,6 +3,7 @@ name: pan-document_code
 description: Explores codebase and writes structured analysis documents. Spawned by map-codebase with a focus area (tech, arch, quality, concerns, relationships, practices). Writes documents directly to reduce orchestrator context load.
 tools: Read, Bash, Grep, Glob, Write
 color: cyan
+effort: low
 ---
 
 <role>

package/agents/pan-executor.md

@@ -3,6 +3,7 @@ name: pan-executor
 description: Executes PAN plans with atomic commits, deviation handling, checkpoint protocols, and state management. Spawned by execute-phase orchestrator or execute-plan command.
 tools: Read, Write, Edit, Bash, Grep, Glob
 color: yellow
+effort: high
 ---
 
 <role>

package/agents/pan-experiment-runner.md

@@ -3,8 +3,7 @@ name: pan-experiment-runner
 description: 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. Used by the v3.7.0 self-improvement loop.
 tools: Read, Bash, Glob, Grep
 color: orange
-thinking: enabled
-thinking_budget: 6000
+effort: high
 ---
 
 <role>

package/agents/pan-hardener.md

@@ -3,8 +3,7 @@ name: pan-hardener
 description: Security audit agent — OWASP Top 10 + STRIDE threat modeling across files changed in a phase. Read-only. Spawned by /pan:review-deep.
 tools: Read, Grep, Glob, Bash
 color: red
-thinking: enabled
-thinking_budget: 6000
+effort: high
 ---
 
 <role>

package/agents/pan-integration-checker.md

@@ -3,8 +3,7 @@ name: pan-integration-checker
 description: Verifies cross-phase integration and E2E flows. Checks that phases connect properly and user workflows complete end-to-end.
 tools: Read, Bash, Grep, Glob
 color: blue
-thinking: enabled
-thinking_budget: 6000
+effort: high
 ---
 
 <role>

package/agents/pan-knowledge.md

@@ -3,8 +3,7 @@ name: pan-knowledge
 description: Knowledge agent for grounded Q&A, multi-turn discussion, and playbook generation. Single agent, three modes (ask/discuss/playbook). Spawned by /pan:knowledge.
 tools: Read, Grep, Glob, Bash, Write
 color: cyan
-thinking: enabled
-thinking_budget: 4000
+effort: medium
 ---
 
 <role>

package/agents/pan-meta-reviewer.md

@@ -3,8 +3,7 @@ name: pan-meta-reviewer
 description: Reviews the reviewer + hardener output. Flags things both missed, disputes findings that look overstated, and surfaces conflicts for human resolution. Spawned by /pan:review-deep.
 tools: Read, Grep, Glob, Bash
 color: magenta
-thinking: enabled
-thinking_budget: 4000
+effort: medium
 ---
 
 <role>

package/agents/pan-optimizer.md

@@ -3,6 +3,7 @@ name: pan-optimizer
 description: Circular optimization analyst. Reads execution trace data, identifies error/gap/redundancy patterns, and produces a structured optimization report with auto-applicable memory entries and manual review suggestions.
 tools: Read, Glob, Grep
 color: cyan
+effort: high
 ---
 
 <role>

package/agents/pan-phase-researcher.md

@@ -3,6 +3,7 @@ name: pan-phase-researcher
 description: Researches how to implement a phase before planning. Produces research.md consumed by pan-planner. Spawned by /pan:plan-phase orchestrator.
 tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*
 color: cyan
+effort: medium
 ---
 
 <role>

package/agents/pan-plan-checker.md

@@ -3,8 +3,7 @@ name: pan-plan-checker
 description: Verifies plans will achieve phase goal before execution. Goal-backward analysis of plan quality. Spawned by /pan:plan-phase orchestrator.
 tools: Read, Bash, Glob, Grep
 color: green
-thinking: enabled
-thinking_budget: 8000
+effort: xhigh
 ---
 
 <role>

package/agents/pan-planner.md

@@ -3,6 +3,7 @@ name: pan-planner
 description: Creates executable phase plans with task breakdown, dependency analysis, and goal-backward verification. Spawned by /pan:plan-phase orchestrator.
 tools: Read, Write, Bash, Glob, Grep, WebFetch, mcp__context7__*
 color: green
+effort: xhigh
 ---
 
 <role>

package/agents/pan-previewer.md

@@ -3,8 +3,7 @@ name: pan-previewer
 description: Read-only foresight agent. Given a phase, set of phases, or milestone, produces a structured forecast (blast radius, dependency graph, ETA). Spawned by /pan:preview.
 tools: Read, Bash, Glob, Grep, Write
 color: cyan
-thinking: enabled
-thinking_budget: 6000
+effort: high
 ---
 
 <role>

package/agents/pan-project-researcher.md

@@ -3,6 +3,7 @@ name: pan-project-researcher
 description: Researches domain ecosystem before roadmap creation. Produces files in .planning/research/ consumed during roadmap creation. Spawned by /pan:new-project or /pan:milestone-new orchestrators.
 tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*
 color: cyan
+effort: medium
 ---
 
 <role>
@@ -13,6 +14,11 @@ Answer "What does this domain ecosystem look like?" Write research files in `.pl
 **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.
 
+**CRITICAL: Write output files directly with the Write tool.** Never create
+helper scripts, temp files, or scratch artifacts inside `.planning/` — the
+synthesizer commits everything in research/, so any litter ships into the
+project history.
+
 Your files feed the roadmap:
 
 | File | How Roadmap Uses It |

package/agents/pan-research-synthesizer.md

@@ -3,6 +3,7 @@ name: pan-research-synthesizer
 description: Synthesizes research outputs from parallel researcher agents into summary.md. Spawned by /pan:new-project after 4 researcher agents complete.
 tools: Read, Write, Bash
 color: purple
+effort: medium
 ---
 
 <role>
@@ -24,6 +25,12 @@ If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool t
 - Identify confidence levels and gaps
 - Write summary.md
 - Commit ALL research files (researchers write but don't commit — you commit everything)
+
+**CRITICAL: Write output files directly with the Write tool.** Never create
+helper scripts, temp files, or scratch artifacts inside `.planning/` — your
+commit step commits everything in research/, so any litter ships into the
+project history. If you must use Bash for anything transient, do it outside
+`.planning/` and clean up before committing.
 </role>
 
 <downstream_consumer>

package/agents/pan-reviewer.md

@@ -3,8 +3,7 @@ name: pan-reviewer
 description: Read-only code review agent. Checks convention compliance, security patterns, and code quality for files changed during phase execution.
 tools: Read, Grep, Glob, Bash
 color: yellow
-thinking: enabled
-thinking_budget: 4000
+effort: medium
 ---
 
 <role>
@@ -111,6 +110,6 @@ Return a structured review report:
 <constraints>
 - READ-ONLY: Never use Edit or Write tools. You inspect, you do not modify.
 - SCOPE: Only review files listed in the prompt or found in summary.md key-files sections.
-- FOCUS: Report real issues, not style preferences. Every finding must cite file and line.
+- COVERAGE: Report every finding you identify, including ones you are uncertain about or judge low-severity — assign each the correct tier (ERROR / WARNING / INFO) rather than dropping it. Pure style preferences with no correctness or consistency impact belong in INFO, not omitted. Your job at this stage is coverage; the severity tiers, the verdict, and the downstream meta-reviewer (`/pan:review-deep`, which disputes overstated findings and removes duplicates) are the filter. It is better to surface a finding that later gets downgraded than to silently drop a real issue. Every finding must cite file and line.
 - EFFICIENCY: Skip files that are purely documentation (.md) unless they contain code blocks.
 </constraints>

package/agents/pan-roadmapper.md

@@ -3,6 +3,7 @@ name: pan-roadmapper
 description: Creates project roadmaps with phase breakdown, requirement mapping, success criteria derivation, and coverage validation. Spawned by /pan:new-project orchestrator.
 tools: Read, Write, Bash, Glob, Grep
 color: purple
+effort: high
 ---
 
 <role>

package/agents/pan-verifier.md

@@ -3,8 +3,7 @@ name: pan-verifier
 description: Verifies phase goal achievement through goal-backward analysis. Checks codebase delivers what phase promised, not just that tasks completed. Creates verification.md report.
 tools: Read, Write, Bash, Grep, Glob
 color: green
-thinking: enabled
-thinking_budget: 6000
+effort: high
 ---
 
 <role>