pan-wizard 3.36.0 → 3.37.0

package/docs/decisions/ADR-0001-strategic-feature-prioritization.md

@@ -0,0 +1,83 @@
+# ADR-0001: Strategic Feature Prioritization Based on Competitive Analysis
+
+## Status
+Partially Accepted — 3 of 5 features implemented (2026-02-28)
+
+## Date
+2026-02-28
+
+## Context
+
+PAN Wizard operates in a rapidly consolidating AI coding tool market. As of February 2026:
+
+- **Cursor 2.0** shipped multi-agent (8 parallel), Mission Control, background agents, and Plan Mode
+- **Windsurf Wave 13** added parallel multi-agent sessions, git worktrees, and Arena Mode
+- **GitHub Copilot** launched agent mode with specialized sub-agents (Explore, Task, Code Review, Plan) and Copilot CLI (GA Feb 2026)
+- **Devin 2.0** dropped pricing from $500/mo to $20/mo with interactive planning, Devin Search, and Devin Wiki
+- **Cline** added CLI 2.0 with parallel agents and headless CI/CD mode
+- **Continue.dev** pivoted to CI/CD background agents with shareable agent configurations
+
+PAN Wizard pioneered many of these patterns (multi-agent orchestration, plan-verify loops, wave-based parallel execution) but competitors are closing the gap. The question is: what should PAN build next to maintain and extend its lead?
+
+## Decision
+
+**Prioritize features that make PAN's invisible strengths visible and address the primary limitation of phase-scoped execution (lack of cross-session learning), rather than copying competitor features that belong to the host tool layer.**
+
+### Specifically:
+
+1. **Context Budget Tracking** (P0) — Make context engineering visible — **DONE** (`context-budget.cjs`, `/pan:context-budget` command)
+2. **Cross-Session Learning** (P1) — Extract patterns from completed phases — NOT STARTED
+3. **Live Project Health Dashboard** (P1) — Quality + velocity + risk scoring — **PARTIAL** (`progress health` subcommand with A-D grading)
+4. **Intelligent Phase Splitting** (P2) — Auto-decomposition based on context budget — NOT STARTED
+5. **Comparison & Benchmark Command** (P2) — Honest, factual self-comparison — **DONE** (`docs/COMPARISON.md`, 8-tool × 18-dimension matrix)
+
+### What we explicitly DO NOT build:
+
+- **Browser testing** — Cline's territory. Not PAN's job
+- **Autocomplete** — Host tool's job (Claude Code, OpenCode, etc.)
+- **IDE-level codebase indexing** — Cursor/Windsurf's domain. PAN has `map-codebase` which is sufficient
+- **Cloud sandboxed execution** — Devin's territory. PAN runs locally by design
+- **Real-time collaboration** — Not aligned with CLI-first architecture
+
+## Consequences
+
+### Positive
+- Context budget tracking makes PAN's #1 value prop (context rot prevention) tangible and measurable
+- Cross-session learning addresses the most common criticism of fresh-context-per-phase architecture
+- All features maintain zero-dependency constraint and cross-platform support (5 runtimes)
+- All features are additive — no breaking changes to existing workflows
+- Honest comparison command builds trust with evaluators
+
+### Negative
+- Static comparison data requires manual maintenance as competitors evolve rapidly
+- Context quality scoring is a novel concept with no established methodology to validate against
+- Cross-session patterns could become stale or misleading if not actively managed
+- Not building browser testing or autocomplete means PAN remains dependent on host tool capabilities
+
+### Neutral
+- These features strengthen PAN's position as an orchestration layer, not an IDE replacement
+- Compare command may be perceived as marketing rather than engineering (mitigated by factual framing)
+- Phase splitting advisor is advisory, not automatic — users retain control
+
+## Options Considered
+
+### Option A: Copy Competitors (Rejected)
+Add browser testing (from Cline), autocomplete (from Cursor), codebase indexing (from Windsurf).
+
+**Why rejected:** Violates PAN's layered architecture. Duplicates host tool capabilities. Would require runtime dependencies (Puppeteer, embedding models). Would narrow cross-platform support. Increases maintenance burden without strengthening core moat.
+
+### Option B: Focus on Visibility and Intelligence (Selected)
+Make existing strengths visible (context budget), add intelligence (pattern learning, health scoring), and enable informed decomposition (phase splitting).
+
+**Why selected:** Strengthens PAN's unique moat (context engineering) without scope creep. All features align with zero-dependency constraint. Each feature independently valuable. Clear implementation path through existing architecture.
+
+### Option C: Do Nothing (Rejected)
+Rely on existing differentiators and word-of-mouth.
+
+**Why rejected:** Competitors are actively closing the gap on multi-agent execution and planning. PAN's lead is real but not visible to evaluators. Without context budget tracking, users can't see WHY PAN works better. Without cross-session learning, the fresh-context-per-phase design has a real limitation that needs addressing.
+
+## Links
+- Feature spec: `docs/specs/industry_comparison_and_feature_gaps_featureai.md`
+- Related modules: all 14 core modules in `pan-wizard-core/bin/lib/`
+- Related commands: `/pan:progress`, `/pan:health`, `/pan:plan-phase`, `/pan:execute-phase`
+- Enables: v0.2.0 roadmap prioritization

package/docs/decisions/ADR-0002-copilot-cli-runtime.md

@@ -0,0 +1,71 @@
+# ADR-0002: GitHub Copilot CLI Runtime Support
+
+## Status
+Accepted — fully implemented (2026-02-28)
+
+## Context
+
+GitHub Copilot CLI went generally available on February 25, 2026, included in all Copilot plans (Free, Pro, Pro+, Business, Enterprise). It supports custom agents (`.agent.md`), skills (`SKILL.md`), hooks (7 event types), and MCP servers — concepts that map directly to PAN Wizard's architecture.
+
+PAN Wizard currently supports 4 terminal AI runtimes: Claude Code, OpenCode, Gemini CLI, and Codex. GitHub Copilot CLI represents the largest commercial AI developer tool ecosystem (150M+ GitHub developers) and shares structural similarities with PAN's existing runtime targets.
+
+The key forces at play:
+1. **Market timing** — First-mover advantage for structured workflow tools on a newly GA platform
+2. **Architecture fit** — Copilot CLI's skill/agent/hook model maps cleanly to PAN's existing patterns
+3. **Proven template** — PAN already handles 4 runtimes with format converters; a 5th follows the same pattern
+4. **User demand** — Direct user request in this conversation; Copilot CLI issue #783 requesting structured planning
+
+## Decision
+
+Add GitHub Copilot CLI as PAN Wizard's 5th supported runtime via installer enhancement.
+
+### Key design choices:
+
+1. **Skills, not commands** — Install PAN commands as `skills/pan-*/SKILL.md` (Copilot CLI's native format, similar to how Codex uses `skills/pan-*/SKILL.md`)
+
+2. **`.agent.md` extension** — Install PAN agents as `pan-*.agent.md` files (Copilot CLI convention, distinct from Claude Code's plain `.md`)
+
+3. **Native hooks** — Use Copilot CLI's own hook system (JSON config files with event types) rather than embedding in config.json
+
+4. **`/pan-` prefix** — Skills in Copilot CLI are invoked via `/skill-name`, so PAN commands become `/pan-new-project`, `/pan-plan-phase`, etc.
+
+5. **Global: `~/.copilot/`, Local: `.github/`** — Follow Copilot CLI's standard paths. Local installs to `.github/` (not `.copilot/`) because Copilot CLI reads skills/agents from `.github/` for project scope.
+
+6. **Installer-only change** — No modifications to core modules, pan-tools.cjs, or existing command/agent definitions. All conversion happens at install time.
+
+## Consequences
+
+### Positive
+- PAN Wizard covers 5 major terminal AI runtimes — unmatched multi-runtime support
+- Access to GitHub's massive developer ecosystem
+- First structured workflow tool available on Copilot CLI post-GA
+- Proven pattern — minimal risk, follows existing 4-runtime template
+- Hook support means statusline, context monitor, and update checker all work
+
+### Negative
+- Installer grows by ~200-300 lines (already 2,157 lines for 4 runtimes)
+- Another format converter to maintain (though Copilot CLI format is stable post-GA)
+- Must monitor GitHub Changelog for any format changes in early GA period
+
+### Neutral
+- Command count is 37, agent count stays at 11
+- No new user concepts — same PAN workflow, one more runtime option
+- Test suite grows by ~16 tests for installer coverage
+
+## Options Considered
+
+1. **Wait for Copilot CLI format to stabilize** — Rejected because the format is already stable at GA; waiting loses first-mover advantage.
+
+2. **Plugin distribution via `/plugin install`** — Deferred to v2. Requires GitHub repository packaging and marketplace registration. The installer approach works now and is consistent with other runtimes.
+
+3. **Hybrid: use Codex skill format for Copilot CLI** — Rejected. While both use `SKILL.md`, Copilot CLI has its own conventions (`.agent.md` for agents, different tool names, native hook system). A dedicated converter produces cleaner results.
+
+4. **Add as installer option (chosen)** — Consistent with how all 4 existing runtimes work. Proven pattern, minimal risk, maximum compatibility.
+
+## Links
+- Spec: `docs/specs/copilot_cli_runtime_featureai.md`
+- Related: `bin/install.js` (primary implementation file)
+- Related: ADR-0001 (strategic feature prioritization)
+- External: [Copilot CLI GA announcement](https://github.blog/changelog/2026-02-25-github-copilot-cli-is-now-generally-available/)
+- External: [Copilot CLI custom agents docs](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/create-custom-agents-for-cli)
+- External: [Copilot CLI skills docs](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/create-skills)

package/docs/decisions/ADR-0003-smart-execution.md

@@ -0,0 +1,84 @@
+# ADR-0003: Smart Execution System
+
+**Status:** Accepted
+**Date:** 2026-03-01
+**Context:** Workflow Integration Redesign — `docs/specs/workflow-integration-redesign.md`
+
+## Decision
+
+Implement a tiered execution system with budget tracking, commit safety, rollback snapshots, and error pattern learning to improve execution efficiency and safety.
+
+## Context
+
+The execute-phase workflow treated all plans identically regardless of complexity. A 1-task typo fix consumed the same agent lifecycle (spawn, execute, verify, summarize) as a 12-task multi-module refactor. This led to:
+
+- **Context waste:** Simple tasks consumed full 200K context windows unnecessarily
+- **No budget awareness:** Sessions could attempt more work than practically feasible
+- **No safety nets:** Sensitive files could be committed accidentally; no easy rollback
+- **No learning:** Repeated mistakes weren't captured across sessions
+
+## Approach
+
+### Tier Classification (MICRO / STANDARD / FULL)
+
+Plans are classified based on complexity signals from frontmatter:
+
+| Tier | Criteria | Agent Behavior |
+|------|----------|----------------|
+| MICRO | task_count <= 3 AND files_modified <= 2 | Minimal context, fast verification |
+| STANDARD | task_count <= 8 | Normal execution with full verification |
+| FULL | task_count > 8 OR autonomous=false | Extended context, human-in-loop possible |
+
+Explicit `tier` field in frontmatter overrides the algorithm.
+
+### Budget Point System
+
+| Effort | Points | Meaning |
+|--------|--------|---------|
+| XS | 1 | Config tweak, typo fix |
+| S | 2 | Single-file bug fix |
+| M | 4 | Multi-file feature |
+| L | 10 | Multi-module change |
+| XL | 20 | New subsystem |
+
+Default budget: 50 points per session. Configurable via `--budget N` (1-200) or `config.budget.default_points`.
+
+### Commit Safety
+
+Before committing, check for:
+1. **Deleted files** — warn unless `--force`
+2. **Sensitive files** — block `.env`, `.pem`, `.key`, `credentials`, etc.
+
+Patterns configurable via `config.commit.sensitive_patterns`.
+
+### Rollback Snapshots
+
+`rollback-snapshot <phase>` creates a git tag `pan-rollback-{phase}-{timestamp}` at current HEAD before execution begins. Easy `git reset --hard pan-rollback-...` to undo a failed execution.
+
+### Error Pattern Learning
+
+`readErrorPatterns()` and `appendErrorPattern()` manage `.planning/patterns.md` — a structured log of PAT-NNN entries capturing what went wrong, what's correct, and context. Patterns persist across sessions.
+
+### Session History
+
+`appendSessionSummary()` appends to `.planning/session-history.md`, keeping the last 20 entries. Tracks phase, plans executed, test counts before/after, and key decisions.
+
+## Consequences
+
+### Positive
+- XS/S tasks can complete in 1 agent round-trip (MICRO tier)
+- Budget prevents context exhaustion from over-ambitious sessions
+- Commit safety catches accidental secret leaks
+- Rollback tags provide easy recovery from failed executions
+- Error patterns enable cross-session learning
+
+### Negative
+- Additional complexity in plan frontmatter (tier, priority, effort fields)
+- Budget system requires effort estimation upfront
+- patterns.md and session-history.md add to planning directory size
+
+## Alternatives Considered
+
+1. **Dynamic tier detection at runtime** — Rejected; frontmatter-based classification is simpler and predictable
+2. **Token-based budget instead of points** — Rejected; token costs vary by model, points are stable
+3. **Automatic rollback on test failure** — Deferred; too aggressive for v0.3.0, may lose valid partial work

package/docs/decisions/ADR-0004-copilot-cli-interaction.md

@@ -0,0 +1,89 @@
+# ADR-0004: Copilot CLI Interactive Experience Optimization
+
+## Status
+Accepted (shipped in v1.0.0 — 2026-03-01)
+
+## Context
+PAN Wizard supports 5 AI CLI runtimes. Four of them (Claude Code, OpenCode, Gemini CLI, Codex)
+have either native structured input tools or adequate text-based equivalents for user interaction.
+The 5th runtime, GitHub Copilot CLI (GA 2026-02-25), has no structured input tool — there is no
+`ask_user` equivalent in the documented API, and the CLI is purely text-in/text-out.
+
+PAN's 37 commands contain 41 `AskUserQuestion` invocations across 15 workflow files, including
+3 multiSelect patterns (discuss-phase, new-project, new-milestone). When installed for Copilot CLI,
+these invocations are stripped (`AskUserQuestion: null` in tool mapping) and naively text-replaced
+(`AskUserQuestion` → `question` in some paths), producing unstructured prose questions that confuse
+users. The user-reported symptom: "On copilot the options are not coming up for select — you get
+a question sheet" with a wall of unstructured text.
+
+Competitive analysis of 6 AI coding tools (Aider, Cursor, Continue.dev, Cline, Windsurf,
+GitHub Copilot Workspace) shows that structured user interaction is underserved across the industry.
+Only Cline offers LLM-generated option buttons (single-select), and only Copilot Workspace offers
+file-level checkboxes. No tool offers CLI-native numbered multi-select. This is a differentiation
+opportunity.
+
+## Decision
+Enhance the install-time Copilot CLI converter in `bin/install.js` to:
+
+1. **Adapter header interaction guidance** — Add a "User interaction" section to
+   `getCopilotSkillAdapterHeader()` that teaches the model how to present structured choices
+   as numbered text menus, handle multi-select via comma-separated numbers, and always offer
+   a free-text fallback.
+
+2. **AskUserQuestion block rewriting** — Add a `rewriteAskUserQuestionForCopilot()` function
+   that uses regex to convert `AskUserQuestion` block patterns (with header/question/options)
+   into explicit numbered-menu instructions with response format guidance.
+
+3. **multiSelect handling** — Detect `multiSelect: true` patterns and add "type numbers
+   separated by commas" instructions in the rewritten output.
+
+4. **Inline reference cleanup** — Replace remaining `AskUserQuestion` text references with
+   conversational equivalents ("Ask the user with numbered options").
+
+This is an install-time conversion only. No runtime changes, no new commands, no new dependencies.
+
+## Consequences
+
+### Positive
+- Copilot CLI users get structured interaction matching the quality of other runtimes
+- All 41 interaction points across 15 workflows improved
+- Leverages the decades-old "numbered menu" text-UI pattern (familiar to all developers)
+- No runtime dependencies, hooks, or API changes needed
+- Zero new commands, zero new concepts — transparent enhancement
+- Establishes PAN as the reference implementation for text-based structured interaction in AI CLIs
+
+### Negative
+- Regex-based block rewriting is fragile — new AskUserQuestion patterns in future workflows
+  must follow the existing format or the regex won't match (graceful degradation: passes through unchanged)
+- Users must reinstall to get improvements (no auto-update for installed skill files)
+- Model still must interpret user responses (no programmatic validation — quality depends on the model)
+- Installed skill files become slightly larger (~500 bytes per file from added guidance)
+
+### Neutral
+- Install time increases by ~50ms (negligible)
+- Converter function complexity increases moderately (one new ~40 line function)
+- Pattern established here may need updating if Copilot CLI adds native structured input tools
+
+## Options Considered
+
+1. **Do nothing** — Accept Copilot CLI as a degraded runtime.
+   *Rejected:* User reported the problem directly, Copilot CLI is the largest commercial AI CLI,
+   and PAN's value proposition is runtime parity.
+
+2. **Runtime prompt engineering via hooks** — Copilot CLI hooks can only deny/allow tool use,
+   not modify prompts or inject context.
+   *Rejected:* Technically impossible with current Copilot CLI hook API.
+
+3. **Custom TUI framework** — Build ncurses-style widgets for Copilot CLI output.
+   *Rejected:* Over-engineering; Copilot CLI doesn't support custom TUI rendering;
+   not portable across terminals.
+
+4. **Install-time converter enhancement (chosen)** — Modify existing converter functions to
+   produce better output. Best fit for PAN's install-time architecture, zero runtime overhead,
+   consistent with how all other runtime conversions work.
+
+## Links
+- Related to: ADR-0002 (Copilot CLI runtime support — established the converter architecture)
+- Feature spec: `docs/specs/copilot_cli_interaction_featureai.md`
+- Affects: `bin/install.js` (converter functions), `tests/copilot-install.test.cjs`
+- AskUserQuestion reference: `pan-wizard-core/references/questioning.md`

package/docs/decisions/ADR-0005-command-naming.md

@@ -0,0 +1,80 @@
+# ADR-0005: Command Naming Restructure
+
+## Status
+Accepted (shipped in v1.0.0 — 2026-03-01)
+
+## Context
+
+PAN Wizard has grown to 32 user-facing commands under the `/pan:` namespace. The naming was organic — each command was named when it was created, without a systematic framework. This has produced:
+
+1. **Inconsistent patterns:** 22 verb-first (`add-phase`), 8 noun-only (`progress`), 2 adjective-noun (`context-budget`). No single convention dominates.
+2. **Overly long names:** `list-phase-assumptions` (28 chars with prefix), `complete-milestone` (23 chars), `reapply-patches` (21 chars). Mean invocation: 20.3 characters.
+3. **Flat help output:** All 32 commands listed alphabetically with no grouping. Users must scan the entire list to find what they need.
+4. **Implicit grouping not surfaced:** Phase commands (11), milestone commands (5), session commands (4) form natural groups but aren't presented that way.
+
+Industry precedent is strong: Docker restructured at ~20 commands (2017), gh CLI launched with noun-verb grouping, kubectl uses verb-resource with help categories. The inflection point where flat naming breaks down is well-documented at 20-25 commands.
+
+## Decision
+
+### 1. Rename 18 of 32 commands for consistency and brevity
+
+Key renames:
+- `execute-phase` → `exec-phase` (universally understood abbreviation)
+- `verify-work` → `verify-phase` (consistent with other phase commands)
+- `list-phase-assumptions` → `assumptions` (saves 12 chars; context obvious)
+- `pause-work` → `pause`, `resume-work` → `resume` (unambiguous without suffix)
+- Milestone commands → `milestone-*` prefix (`milestone-new`, `milestone-done`, `milestone-audit`, `milestone-gaps`, `milestone-cleanup`)
+- `add-todo` → `todo-add`, `check-todos` → `todo-check` (consistent pair)
+- `join-discord` → `discord`, `reapply-patches` → `patches` (shorter)
+
+### 2. Keep 14 commands unchanged
+
+Commands with clear, short, consistent names: `new-project`, `map-codebase`, `discuss-phase`, `plan-phase`, `research-phase`, `add-phase`, `insert-phase`, `remove-phase`, `progress`, `quick`, `settings`, `help`, `health`, `update`, `debug`.
+
+### 3. Create alias .md files for all renamed commands
+
+Each old name gets an alias .md file that loads the new command via `@execution_context`. Old invocations continue to work identically. Aliases marked for removal after 2 minor versions.
+
+### 4. Add `group` frontmatter field to all 32 commands
+
+7 groups: Getting Started, Phase Lifecycle, Phase Management, Session & Progress, Milestone, System, and a fallback "Other" for commands missing the field.
+
+### 5. Redesign help output to show groups
+
+`/pan:help` displays commands organized by group with descriptions, not a flat alphabetical list.
+
+## Consequences
+
+### Positive
+- Mean invocation length drops 25% (20.3 → 15.3 chars)
+- Grouped help makes discovery of related commands immediate
+- Milestone lifecycle visible: `milestone-new` → `milestone-audit` → `milestone-gaps` → `milestone-done` → `milestone-cleanup`
+- Predictable patterns help AI agents infer command names
+- Clear framework for naming future commands
+
+### Negative
+- 18 alias files to maintain during deprecation period
+- Users who've memorized old names see deprecation notes (mitigated: old names keep working)
+- `cleanup` → `milestone-cleanup` is longer (but grouped and discoverable)
+- `settings` → unchanged, breaking the milestone-* pattern for project config
+
+### Neutral
+- No core library changes (purely orchestration-layer)
+- No JSON output schema changes
+- No state.md or roadmap.md format changes
+- Installer needs converter updates for Codex/Copilot skill filenames
+
+## Options Considered
+
+1. **Full noun-verb restructuring (Docker-style)** — Rename ALL commands to `noun-verb` pattern (`phase-plan`, `phase-exec`, `project-init`). Rejected because: PAN has 11 phase commands, too many for one noun group; verb-first reads more naturally as imperative in slash commands; would rename 28 of 32 commands for marginal benefit over selective rename.
+
+2. **Selective rename (chosen)** — Rename 18 commands for consistency and brevity, keep 14 that already have good names. Creates aliases for backward compat. Best balance of improvement vs disruption.
+
+3. **No rename, only grouped help** — Add `group` frontmatter and redesign help output without renaming. Rejected because: long names (`list-phase-assumptions`) and inconsistent patterns remain; misses the opportunity to shorten frequent commands.
+
+4. **Dual namespace (Cursor-style)** — Add `@` prefix for context commands alongside `/` for action commands. Rejected because: PAN operates via slash commands only across 5 runtimes; introducing a second prefix adds complexity without clear benefit.
+
+## Links
+- Spec: `docs/specs/command_naming_optimization_featureai.md`
+- Related: All 32 command .md files in `commands/pan/`
+- Precedent: Docker CLI restructuring (2017), gh CLI design

package/docs/decisions/ADR-0006-focus-commands.md

@@ -0,0 +1,101 @@
+# ADR-0006: PAN Focus Commands — Strategic Project Management
+
+## Status
+Accepted (shipped in v1.0.0 — 2026-03-01)
+
+## Context
+
+PAN Wizard's shipped workflow operates at the **phase level**: plan a phase, execute a phase, verify a phase. This is effective for sequential development but leaves a gap when developers need to:
+
+1. **Decide what to work on** — No shipped prioritization framework. Users must manually read roadmap.md and guess what's most important.
+2. **Design features before building** — `/pan:discuss-phase` captures vision but doesn't do competitive research, produce ADRs, or create implementation task lists.
+3. **Budget work sessions** — No capacity system. Users either over-commit (start too much) or under-commit (miss easy wins).
+4. **Sync documentation** — After changes, docs drift. No automated detection of stale references.
+5. **Execute mixed-size work efficiently** — All work goes through full plan.md → exec-phase pipeline, even for XS fixes.
+
+These capabilities exist as custom `.claude/commands/` skills (superplan, execplan, featureAI, session-start/end, sync) developed during PAN Wizard's own build, but they don't ship to users. Meanwhile, competitors are filling this space:
+
+- **Claude Code plan mode** (2026) saves plan files to projects with DAG task dependencies
+- **Cline** separates plan/act modes with different model configs per mode
+
+PAN's architecture already has the building blocks: `classifyPlanTier()`, `effortToPoints()`, `readErrorPatterns()`, `appendSessionSummary()`, `shouldSkipTests()`, `cmdRollbackSnapshot()`. The custom skills proved these concepts work across 16 sessions and 800+ tests. What's needed is integration into the shipped product.
+
+## Decision
+
+Ship 5 new commands under a "Focus" group that bring the COMPLETE proven custom skill pipelines into PAN as first-class shipped commands — no shortcuts, no streamlining:
+
+| Command | Purpose | Derived From |
+|---------|---------|-------------|
+| `/pan:focus-scan` | Full 7-phase strategic work scan with P0-P6 prioritization, Reality Score formula, and validation | SuperPlan — ALL 7 phases (0-6) complete |
+| `/pan:focus-design` | Strategic feature investigation with 4 modes: `--full` (all 10 phases), `--internal` (skip competitive research), `--outward` (strategy focus, skip hardening), `--spike` (fast 4-phase proof-of-concept) | FeatureAI — ALL 10 phases available, mode controls which run. Modifiers: `--gate`, `--audit`, `--mvp` |
+| `/pan:focus-plan` | Create capacity-budgeted work batch with 4 execution modes | ExecPlan stage 2 — complete capacity budget system with all 4 modes (bugfix/balanced/features/full) |
+| `/pan:focus-exec` | Full 6-stage execution pipeline with 9 mandatory behavioral rules and 3 execution tiers | ExecPlan — ALL 6 stages (1-6) complete, ALL 9 rules, ALL 3 tiers (MICRO/STANDARD/FULL) |
+| `/pan:focus-sync` | Synchronize documentation after changes | Sync custom skill — complete |
+| `/pan:focus-drift-walking` | Walk directories, detect doc-code drift, score severity, create/repair docs | Drift killer — 8-phase directory-walking pipeline with severity scoring |
+| `/pan:focus-doc-audit` | Multi-dimensional document audit with 8-dimension scoring and auto-fix | Doc audit — claim extraction, fact verification, cross-consistency, structural linting |
+
+**Implementation approach:**
+- New `focus.cjs` core module (follows existing module pattern)
+- Integrates with existing modules (phase.cjs, init.cjs, frontmatter.cjs, commands.cjs)
+- Optional `priority:` (P0-P6) and `effort:` (XS-XL) fields in plan.md frontmatter
+- Batch/scan files stored in `.planning/focus/`
+- Two-phase delivery: v0 (scan+plan+sync), v1 (exec+design)
+- Reality Score formula (RS = (UV + TC + RR) / JS) shipped in focus-scan
+- All 4 execution modes (bugfix/balanced/features/full) shipped in focus-plan and focus-exec
+
+**What we explicitly chose NOT to build:**
+- Separate task/superplan file format (integrate into existing plan.md)
+- PanMonty status tracker (redundant with state.md)
+- Separate memory bank files (keep as dev-only)
+- PAN-Wizard-specific references (generalize for any project)
+
+## Consequences
+
+### Positive
+- Users get strategic project management without custom skill setup
+- Proven capabilities (16 sessions, 800+ tests) ship as real product
+- Focus commands compose with existing phase commands (not a parallel system)
+- Cross-platform (all 5 runtimes) from day one
+- Zero migration cost (all fields optional, all directories additive)
+
+### Negative
+- 5 more commands to learn (+15% command count, 32 → 37)
+- New .planning/focus/ directory adds to project structure
+- focus.cjs is a new module to maintain
+- Codebase TODO scanning adds ~200ms to scan time
+
+### Neutral
+- Priority/effort fields in plan.md frontmatter are optional — existing projects work unchanged
+- Focus commands can be completely ignored — the phase workflow remains the default path
+- The custom skills (.claude/commands/superplan.md, etc.) continue to work for PAN Wizard's own development
+
+## Options Considered
+
+### 1. Do nothing — keep custom skills internal
+**Pro:** Zero work, no added complexity.
+**Con:** PAN's most powerful capabilities remain invisible to users. Competitors fill the gap.
+
+### 2. Ship custom skills as-is (copy .md files to commands/pan/)
+**Pro:** Quick — just copy files.
+**Con:** Custom skills are PAN-Wizard-specific (reference test counts, module names). They're orchestration scripts, not integrated commands. No core module, no JSON output, no tests.
+
+### 3. Extend existing commands (add --scan to progress, --budget to exec-phase)
+**Pro:** No new commands to learn.
+**Con:** Overloads existing commands with unrelated functionality. progress becomes a 200-line workflow. exec-phase becomes even more complex.
+
+### 4. Ship 5 Focus commands (chosen)
+**Pro:** Clean separation. Integrated with core. Testable. Cross-platform. Composable pipeline.
+**Con:** 5 new commands. New module. But grouped under single "Focus" name.
+
+### 5. Ship as a separate `pan-focus` tool
+**Pro:** No impact on PAN's command count.
+**Con:** Separate installation. Separate update cycle. Can't share modules. Users must learn two tools.
+
+**Option 4 chosen** because it balances integration quality with minimal disruption. The Focus group name provides cognitive bundling (Miller's Law: one chunk, not five).
+
+## Links
+- Spec: `docs/specs/pan_focus_commands_featureai.md`
+- Prior analysis: `docs/specs/custom-skills-assessment.md`
+- Related ADRs: ADR-0003 (smart execution), ADR-0005 (command naming)
+- Custom skills: `.claude/commands/superplan.md`, `execplan.md`, `featureAI.md`
+- Competitor: [Taskmaster AI](https://github.com/eyaltoledano/claude-task-master)

package/docs/decisions/ADR-0007-ship-v1.md

@@ -0,0 +1,73 @@
+# ADR-0007: Ship v1.0.0 to npm
+
+## Status
+Accepted (shipped in v1.0.0 — 2026-03-01)
+
+## Context
+PAN Wizard has been in active development through 29 sessions, reaching 1483 tests,
+15 core modules, 42 commands, 11 agents, and 5 runtime targets. The codebase has
+zero TODO/FIXME markers, zero TOCTOU races, 200+ try-catch blocks for error handling,
+and passes CI across 3 OS x 4 Node versions (12 configurations).
+
+Despite this maturity, the package has never been published to npm. The README
+prominently features `npx pan-wizard@latest` as the install method, but this
+command currently returns a 404 error. The `pan-wizard` name is available on npm.
+
+Quality audit findings:
+- 1483 tests, 0 failures, 0 skipped
+- Zero TODO/FIXME/HACK markers in production code
+- Zero console.log leaks in library code
+- Zero .only()/.skip() in tests
+- Zero hardcoded paths
+- Zero runtime dependencies
+- All file I/O wrapped in try-catch (200+ blocks)
+- All TOCTOU races eliminated
+- Cross-platform CI: Ubuntu + Windows + macOS x Node 16/18/20/22
+
+Competitive analysis shows all comparable tools ship via standard package managers:
+Aider (pip), Continue.dev (npm), GitHub Copilot CLI (npm). PAN Wizard's 422KB
+packed size and zero runtime deps match the gold standard set by @github/copilot.
+
+## Decision
+Bump version from 0.3.0 to 1.0.0 and publish to npm.
+
+1.0.0 was chosen over 0.4.0 because:
+- The codebase is production-ready by every measurable metric
+- 0.x signals instability; PAN Wizard is demonstrably stable
+- Users need a clear signal that this is safe to adopt
+- Semantic versioning says 1.0.0 = "public API is stable"
+- The command naming restructure (Session 16) is a natural breaking-change boundary
+
+## Consequences
+
+### Positive
+- Users can install via the documented `npx pan-wizard@latest` method
+- npm download metrics provide adoption signal
+- npm search discoverability for 13 keywords
+- README badges (version, downloads) activate
+- Community growth becomes possible
+- Competitive positioning: lightest-weight AI workflow tool on npm (422KB, 0 deps, 5 runtimes)
+
+### Negative
+- 1.0.0 commits to backward compatibility for command names and JSON output schemas
+- Must follow semver strictly for any future breaking changes (major version bump)
+- Bug reports from real users will begin (support burden)
+- npm account security becomes critical (2FA required)
+
+### Neutral
+- Existing local installs are unaffected
+- `/pan:update` command already handles pulling latest from npm
+- No new code required — this is purely operational
+
+## Options Considered
+1. **Publish as 0.4.0** — rejected: sends wrong stability signal for a production-ready tool
+2. **Publish as 1.0.0** — chosen: clear, honest stability declaration
+3. **Wait for automated release pipeline** — rejected: blocks shipping for no immediate user benefit; automated releases are v1.1.0 scope
+4. **Use scoped name (@oharms/pan-wizard)** — rejected: `pan-wizard` is available and simpler
+
+## Links
+- Spec: docs/specs/production_readiness_ship_v1_featureai.md
+- package.json: complete metadata, bin entry, files whitelist
+- CI: .github/workflows/ci.yml (3 OS x 4 Node)
+- npm name availability: confirmed (404 = available)
+- Related: ADR-0005 (command naming — breaking change captured in 1.0.0)