pan-wizard 2.8.1

package/commands/pan/focus-exec.md

@@ -0,0 +1,316 @@
+---
+name: focus-exec
+group: Focus
+description: Automated batch execution pipeline with 6 stages, 9 behavioral rules, 3 execution tiers
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Grep
+  - Glob
+  - Agent
+---
+
+# /pan:focus-exec — Automated Batch Execution Pipeline
+
+Execute items from the current focus batch with capacity-based sizing, full session lifecycle, and verification. $ARGUMENTS
+
+**Goal:** One-command pipeline that starts a session, loads the planned batch, implements items with tier-based execution protocols, verifies the work, syncs documentation, and closes the session cleanly.
+
+---
+
+## Pipeline Overview
+
+```
+/pan:focus-exec
+
+  Stage 1: SESSION START
+    - Check project status, record baseline
+
+  Stage 2: BATCH LOADING + VALIDATION
+    - Read batch file, validate items, confirm budget
+
+  Stage 3: EXECUTION (tier-based)
+    - Implement items with read->understand->code
+    - Build + test cadence per tier
+
+  Stage 4: VERIFICATION
+    - Verify all implemented items actually work
+    - Full test suite must pass
+
+  Stage 5: DOCUMENTATION SYNC
+    - Update docs, README, CHANGELOG
+
+  Stage 6: SESSION END
+    - Commit, record session, generate summary
+```
+
+---
+
+## CRITICAL: Project Scope Boundary
+
+This command executes work on the **host project's source code** — NOT on PAN Wizard's own infrastructure.
+
+**NEVER read, modify, or "fix" files in these PAN directories:**
+- `.claude/`, `.github/copilot-instructions.md`, `.opencode/`, `.gemini/`, `.codex/` — PAN runtime directories
+- Any `pan-wizard-core/`, `pan-tools`, agent `.md`, or command `.md` files within PAN runtime directories
+
+**These directories are PAN's own tooling installed into the project.** If a batch item targets a PAN infrastructure file, SKIP it with reason "PAN infrastructure — out of scope." Never modify PAN's agents, commands, core modules, or dispatcher as part of project work.
+
+---
+
+## MANDATORY: Execute ALL Stages Sequentially
+
+When `/pan:focus-exec` is invoked, run ALL 6 stages in order. Do NOT skip stages. Do NOT stop between stages unless a critical failure occurs (tests regress).
+
+**Flags:**
+- `--budget N` — Override capacity budget in points (default: 50, min: 5, max: 100)
+- `--mode MODE` — Execution mode (bugfix/balanced/features/full)
+- `--priority P0-P6` — Only pick items from these priority tiers
+- `--dry-run` — Run Stages 1-2 only (show what WOULD be executed)
+- `--no-commit` — Skip the commit step in Stage 6
+- `--continue` — Resume a previously interrupted execution
+
+---
+
+## Capacity Budget System
+
+| Size | Points | Per Session | Meaning |
+|------|--------|-------------|---------|
+| **XS** | 1 | Up to 40 | Config tweak, typo fix |
+| **S** | 2 | Up to 20 | Single-file bug fix, add tests |
+| **M** | 4 | Up to 10 | Multi-file feature, new test suite |
+| **L** | 10 | Up to 4 | Multi-module change, new command |
+| **XL** | 20 | Up to 2 | New subsystem, major refactor |
+
+---
+
+## AI Behavioral Rules (ALL 9 MANDATORY)
+
+### Rule 1: Read Before You Write (MANDATORY)
+Before changing ANY file, read it first. Understand context, callers, and invariants.
+
+### Rule 2: Understand the Root Cause (MANDATORY)
+Do NOT apply surface-level patches. Trace the code path, identify the actual defect.
+
+### Rule 3: One Change, One Test (MANDATORY)
+Every code change must be tested before moving to the next item.
+
+Test cadence by tier:
+- **MICRO (XS/S):** Run specific test after implementing. Batch up to 3 independent items before smoke.
+- **STANDARD (M):** Full test suite after EACH item.
+- **FULL (L/XL):** Build hooks + full test suite after EACH item.
+
+### Rule 4: Don't Invent — Follow the Plan (MANDATORY)
+Implement exactly what the batch says. No scope creep.
+
+### Rule 5: Cross-Platform Awareness (MANDATORY)
+- Use platform-agnostic path APIs (no hardcoded separators)
+- Follow the project's module format conventions (discover from existing code)
+- Use file-based input for shell-sensitive content when needed
+
+### Rule 6: Revert Fast, Don't Dig Deep (MANDATORY)
+If a fix doesn't work within 5 minutes, revert and move on. Failed items carry forward.
+
+### Rule 7: Verify Understanding Before Committing (MANDATORY)
+For M/L/XL items, state your understanding before writing code:
+```
+Item P2-3 — Add tests for billing module
+Understanding: billing module has 3 exported functions. Need to test
+generateInvoice, processPayment, and getBalance edge cases.
+Files: billing.ts, tests/billing.test.ts
+Confidence: HIGH
+```
+
+### Rule 8: Preserve Existing Test Expectations (MANDATORY)
+Never change an existing test's expected output to match broken code.
+
+### Rule 9: Commit Messages Must Be Accurate (MANDATORY)
+List ONLY items that are actually VERIFIED (passed tests). Include actual test counts.
+
+---
+
+## Stage 1: Session Start
+
+1. **Check Project Status** — git status, recent commits
+2. **Test Baseline** — run test suite, record current counts
+3. **Create rollback snapshot** — git tag for safety
+4. **Report** — Output session start summary
+
+**Record baseline:**
+```
+baseline_version: <from package.json>
+baseline_tests: <N/N passing>
+baseline_build: <pass/fail>
+baseline_commit: <current HEAD>
+```
+
+**Failure Gate:** If tests fail, STOP. Fix tests before proceeding.
+
+---
+
+## Stage 2: Batch Loading + Validation
+
+### 2.1 Find Active Batch
+Search for: `.planning/focus/batch-*.json`
+Pick the newest. If none exists, tell user to run `/pan:focus-plan` first.
+
+### 2.2 Read and Validate the Batch
+Extract all items: ID, Title, Priority, Effort, Points, Tier, Files.
+Verify total points within budget.
+
+### 2.3 Show Batch Table
+Display the execution batch to user, then continue automatically.
+
+---
+
+## Stage 3: Execution
+
+### 3.0 Pre-Execution Setup
+1. Cache project facts — do NOT re-read later
+2. Create/update progress tracker with the batch table
+
+### 3.1 Process Items by Tier
+
+#### MICRO Items (XS/S)
+```
+1. READ target file(s)
+2. IMPLEMENT the fix
+3. TEST — run specific test file
+4. CONFIRM — pass -> DONE | fail -> one fix attempt -> REVERT -> FAILED
+```
+
+#### STANDARD Items (M)
+```
+1. STATE UNDERSTANDING (Rule 7)
+2. READ target files + test files
+3. IMPLEMENT across necessary files
+4. TEST — full test suite
+5. CONFIRM — pass -> DONE | regresses -> REVERT -> FAILED
+```
+
+#### FULL Items (L/XL)
+```
+1. STATE UNDERSTANDING (detailed)
+2. READ WIDELY — target files, callers, tests, related code
+3. DESIGN — outline approach before coding
+4. IMPLEMENT in logical chunks
+5. BUILD — build hooks if hooks changed
+6. TEST — full test suite
+7. CONFIRM — all pass -> DONE | fail -> investigate (15 min max) -> REVERT -> FAILED
+```
+
+### 3.2 Failure Handling
+- Build breaks: fix typo or revert (5 min limit)
+- Test regression: identify cause, one fix attempt, else revert
+- **Never let a failed item block other items**
+
+### 3.3 Progress Tracking
+Update progress tracker after each item with status and budget tracking.
+
+---
+
+## Stage 4: Verification
+
+### 4.1 Full Suite Verification
+Run full test suite. All tests must pass. Compare against Stage 1 baseline.
+
+### 4.2 Build Verification (if applicable)
+Build hooks or compile step if applicable. All must pass.
+
+### 4.3 Verification Report
+```markdown
+## Verification Report
+
+### Item Results
+| # | ID | Title | Tests | Verdict |
+|---|----|-------|-------|---------|
+| 1 | P0-1 | Fix crash | pass | VERIFIED |
+| 2 | P2-3 | Add tests | pass | VERIFIED |
+
+### Regression Check
+| Test Suite | Before | After | Delta |
+|------------|--------|-------|-------|
+| Tests | N/N | M/M | +K |
+| Build | pass | pass | -- |
+```
+
+---
+
+## Stage 5: Documentation Sync
+
+### 5.1 Update Docs
+- Update README.md if public API changed
+- Update CHANGELOG.md with new entries
+- Update command/workflow files if behavior changed
+
+### 5.2 Update Scan
+Edit the active scan file:
+- Mark completed items with completed status
+- Mark failed items with failed status and reason
+
+---
+
+## Stage 6: Session End
+
+### 6.1 Commit Changes
+Unless `--no-commit`:
+1. Stage modified files (specific paths, not `git add -A`)
+2. Create commit with accurate message listing verified items
+3. Verify commit succeeded
+
+### 6.2 Record Session
+- Record session summary (items completed, tests before/after, budget used)
+- Append error patterns if any failures occurred
+
+### 6.3 Final Report
+
+```markdown
+## /pan:focus-exec Complete
+
+| Stage | Status |
+|-------|--------|
+| 1. Session Start | Baseline: N/N tests |
+| 2. Batch Loading | Mode: balanced, N items |
+| 3. Execution | N/M items completed |
+| 4. Verification | All verified |
+| 5. Doc Sync | Updated N docs |
+| 6. Session End | Committed |
+
+### Results
+- **Budget:** X/50 points used
+- **Items completed:** N (X pts)
+- **Items failed:** K (Y pts returned)
+- **Tests:** Before N -> After M (+K new)
+
+### Resume
+Run `/pan:focus-exec --continue` for remaining items.
+Run `/pan:focus-scan` to regenerate the scan.
+```
+
+---
+
+## NEVER DO
+
+- Skip reading files before editing them (Rule 1)
+- Apply symptom patches instead of root cause fixes (Rule 2)
+- Batch implement without testing between items (Rule 3)
+- Expand scope beyond the batch item (Rule 4)
+- Ignore cross-platform path issues (Rule 5)
+- Spend more than 5 minutes debugging a single failure (Rule 6)
+- Start coding without stating understanding for M+ items (Rule 7)
+- Change test expectations to match broken code (Rule 8)
+- Claim items are fixed without running tests (Rule 9)
+
+## ALWAYS DO
+
+- Read before write, understand before implement
+- Test after every item
+- Stay within budget and plan scope
+- Use platform-agnostic paths, file-based input for shell-sensitive content
+- Revert fast when stuck
+- Record baseline test counts BEFORE making changes
+- Save progress after each item
+- Record session at end
+- Report results with before/after comparison and budget usage

package/commands/pan/focus-plan.md

@@ -0,0 +1,101 @@
+---
+name: focus-plan
+group: Focus
+description: Create capacity-budgeted work batch with 4 execution modes
+allowed-tools:
+  - Read
+  - Bash
+  - Grep
+  - Glob
+---
+
+# /pan:focus-plan — Capacity-Budgeted Work Batch Planner
+
+Create a capacity-budgeted work batch from focus-scan results. $ARGUMENTS
+
+**Goal:** Select a right-sized batch of work items that fits within the session's point budget, ordered for maximum impact with minimum risk.
+
+---
+
+## CRITICAL: Project Scope Boundary
+
+This command plans work batches for the **host project** — NOT for PAN Wizard's own infrastructure.
+
+**NEVER include items targeting these PAN directories:**
+- `.claude/`, `.github/copilot-instructions.md`, `.opencode/`, `.gemini/`, `.codex/` — PAN runtime directories
+- Any `pan-wizard-core/`, `pan-tools`, agent `.md`, or command `.md` files within PAN runtime directories
+
+If a scan item points to a PAN infrastructure file, DROP it from the batch. PAN's files are not the project's responsibility.
+
+---
+
+## MANDATORY: Run focus-scan first
+
+If no recent scan exists, run `/pan:focus-scan` automatically before proceeding.
+
+**Flags:**
+- `--budget N` — Override capacity budget in points (default: 50, min: 5, max: 100)
+- `--mode MODE` — Execution mode. Default: `balanced`
+  - `bugfix` — P0->P1->smallest-first, no feature work (40 pts)
+  - `balanced` — **Default.** Mix of stability fixes + feature development, 60/40 split (50 pts)
+  - `features` — Feature-focused: 80% budget on P3-P5, P0 crashes still mandatory (50 pts)
+  - `full` — Full-spectrum: enhanced budget, all priorities equally weighted (60 pts)
+- `--priority P0-P6` — Only pick items from these priority tiers
+- `--lean` — Apply RS filtering: exclude items with RS < 1.5
+
+---
+
+## Capacity Budget System
+
+| Size | Points | Per Session | Meaning |
+|------|--------|-------------|---------|
+| **XS** | 1 | Up to 40 | Config tweak, typo fix |
+| **S** | 2 | Up to 20 | Single-file bug fix, add tests |
+| **M** | 4 | Up to 10 | Multi-file feature, new test suite |
+| **L** | 10 | Up to 4 | Multi-module change, new command |
+| **XL** | 20 | Up to 2 | New subsystem, major refactor |
+
+---
+
+## Execution Modes
+
+### `bugfix` — Stability-First
+- **Budget:** 40 pts
+- **Algorithm:** P0 mandatory -> P1 -> P2-P4 smallest-first
+- **Feature allocation:** None
+
+### `balanced` — Mix of Fixes + Features (DEFAULT)
+- **Budget:** 50 pts
+- **Stability pass (60%):** 30 pts for P0-P2
+- **Feature pass (40%):** 20 pts for P3-P6
+
+### `features` — Feature-Focused Sprint
+- **Budget:** 50 pts
+- **Mandatory pass:** All P0 items
+- **Feature pass (80%):** 40 pts for P3-P5
+- **Stability pass (20%):** 10 pts for P1-P2 quick wins
+
+### `full` — Full-Spectrum Marathon
+- **Budget:** 60 pts
+- **All priorities weighted equally, largest-impact-first**
+
+---
+
+## Output
+
+Produce a batch file at `.planning/focus/batch-<YYYY-MM-DD>.json` via `pan-tools focus plan`:
+
+```markdown
+## Focus Batch — <date>
+**Mode:** balanced | **Budget:** 50 pts | **Allocated:** N pts
+
+| # | ID | Title | Priority | Size | Pts | Tier | Track |
+|---|----|-------|----------|------|-----|------|-------|
+| 1 | P0-1 | Fix crash in state cmd | P0 | S | 2 | MICRO | Stability |
+| 2 | P2-3 | Add tests for milestone | P2 | M | 4 | STANDARD | Stability |
+| 3 | P3-1 | Add --json flag to phase | P3 | M | 4 | STANDARD | Feature |
+
+Execution Order: MICRO first, then STANDARD, then FULL
+```
+
+Ready for `/pan:focus-exec`.

package/commands/pan/focus-scan.md

@@ -0,0 +1,272 @@
+---
+name: focus-scan
+group: Focus
+description: Deep-dive strategic work scan with prioritized items and Reality Score filtering
+allowed-tools:
+  - Read
+  - Bash
+  - Grep
+  - Glob
+---
+
+# /pan:focus-scan — Deep-Dive Strategic Work Scan
+
+Survey the project for prioritized work items with evidence-based scoring. $ARGUMENTS
+
+**Goal:** Produce a comprehensive, evidence-based prioritized work list by deep-diving into ALL project files, code, and test results. Every item must link to source files and be actionable.
+
+---
+
+## CRITICAL: Project Scope Boundary
+
+This command scans the **host project's source code** for work items — NOT PAN Wizard's own infrastructure.
+
+**ALWAYS EXCLUDE these directories from scanning:**
+- `.claude/`, `.github/copilot-instructions.md`, `.opencode/`, `.gemini/`, `.codex/` — PAN runtime directories
+- `.planning/` — PAN planning state (read for context, but never report PAN planning files as "issues")
+- Any `pan-wizard-core/`, `pan-tools`, agent `.md`, or command `.md` files within PAN runtime directories
+
+**These directories are PAN's own tooling installed into the project.** Do not report TODO/FIXME items found in PAN files. Do not flag PAN files as lacking test coverage. Do not suggest improvements to PAN's agents, commands, or core modules.
+
+If a scan finding points to a file inside `.claude/`, `.github/`, `.opencode/`, `.gemini/`, or `.codex/` — DROP IT. It is not the project's responsibility.
+
+---
+
+## MANDATORY: Execute ALL Phases Automatically
+
+When `/pan:focus-scan` is invoked, execute ALL phases without stopping. Do NOT ask questions between phases. Do NOT skip phases. The output is a prioritized work list with Reality Score filtering.
+
+**Flags:**
+- `--focus <area>` — Weight items toward a specific area (e.g., `--focus commands`, `--focus hooks`, `--focus tests`)
+- `--quick` — Skip Phase 2 (strategic context) and Phase 6 (validation protocol)
+- `--refresh` — Force re-read all files even if recently cached
+- `--lean` — Apply aggressive Reality Score filtering: DROP items with RS < 1.5, DEFER items with RS < 3.0
+
+---
+
+## Phase 0: Orientation & Baseline Snapshot
+
+### 0.1 Read Current State
+Read these files to establish baseline:
+
+**Core Status:**
+- `package.json` — Version, description, entry points
+- `README.md` — Public documentation
+
+**Project Structure:**
+- All core modules in the project's source directories
+- All command definitions
+- All agent definitions
+- All workflow definitions
+- All hook source files
+
+**Planning State:**
+- `.planning/state.md` — Current state
+- `.planning/roadmap.md` — Phase progress
+- `.planning/config.json` — Project configuration
+- `.planning/patterns.md` — Known error patterns (if exists)
+
+### 0.2 Scan for Real Issues
+Run targeted code searches to find actual problems:
+
+```
+Search for: "TODO", "FIXME", "HACK", "STUB", "stub"
+In: source directories, hooks, tests
+```
+
+Cross-reference found issues with documented items — flag any UNDOCUMENTED issues as new findings.
+
+### 0.3 Check Test Results
+```bash
+npm test 2>&1
+```
+Record: total tests, passing, failing, suites.
+
+### 0.4 Baseline Snapshot Table
+
+```markdown
+| Metric | Value | Notes |
+|--------|-------|-------|
+| Version | X.Y.Z | |
+| Tests | N/N | M suites |
+| Build | OK/FAIL | |
+| Commands | N | |
+| Phases | N total, M incomplete | |
+| TODOs Found | N | |
+| Error Patterns | N | |
+```
+
+---
+
+## Phase 1: Priority Classification
+
+### Priority Framework (STRICT ORDER)
+
+| Priority | Focus | Criteria |
+|----------|-------|----------|
+| **P0: CRASH/ERROR** | Runtime errors, uncaught exceptions | Any command that throws or produces wrong output |
+| **P1: WRONG RESULTS** | Silent data corruption, incorrect output | Commands that succeed but produce bad data |
+| **P2: TEST GAPS** | Missing test coverage | Features without tests or low assertion density |
+| **P3: INCOMPLETE FEATURES** | Partially implemented commands or workflows | Commands that exist but lack full functionality |
+| **P4: NEW FEATURES** | Net-new functionality from roadmap | Features not yet started |
+| **P5: TOOLING** | Developer experience improvements | Hooks, CLI UX, error messages |
+| **P6: DOCUMENTATION** | Docs sync, reference updates | Documentation-only changes |
+
+### Classification Rules
+- **Crashes before correctness** — A thrown error is always higher priority than wrong output
+- **Correctness before coverage** — Wrong results are worse than missing tests
+- **Quick wins first within each tier** — S-effort items before L-effort items
+
+---
+
+## Phase 2: Strategic Context (skip with --quick)
+
+### 2.1 Read Strategy Documents
+- `README.md` — What's the public-facing story?
+- User guide / docs — What's documented for users?
+- `CHANGELOG.md` — What's the recent trajectory?
+
+### 2.2 Strategic Alignment Check
+For each P4+ item, note whether it:
+- Is on the critical path to the next milestone
+- Enables other high-value work (dependency unblocking)
+- Has been deferred multiple times
+
+---
+
+## Phase 2.5: Feature Reality Check (Market-Fit Scoring)
+
+Every feature-tier item (P3-P6) must pass a reality check.
+
+### Reality Score (RS)
+
+```
+RS = (User Value + Time Criticality + Risk Reduction) / Job Size
+```
+
+#### User Value (UV): 1-5
+| Score | Meaning |
+|-------|---------|
+| 5 | Core workflow feature — every user needs this |
+| 4 | Common usage — most projects need it |
+| 3 | Significant audience — power users need it |
+| 2 | Niche audience — specific use case |
+| 1 | Academic / completion-only |
+
+#### Time Criticality (TC): 1-5
+| Score | Meaning |
+|-------|---------|
+| 5 | Blocks users from adopting the tool |
+| 4 | Competitive table-stakes — other tools have it |
+| 3 | Unlocks a significant new use case |
+| 2 | Nice to have, users can work around |
+| 1 | No urgency |
+
+#### Risk Reduction (RR): 1-5
+| Score | Meaning |
+|-------|---------|
+| 5 | Removes a crash or correctness bug |
+| 4 | Unblocks 3+ downstream features |
+| 3 | Unblocks 1-2 features |
+| 2 | Incremental improvement |
+| 1 | Polish / docs |
+
+#### Job Size (JS)
+| Effort | JS Value |
+|--------|----------|
+| XS | 1 |
+| S | 2 |
+| M | 3 |
+| L | 5 |
+| XL | 8 |
+
+```
+RS >= 3.0  ->  DO       — Include in next sessions
+RS 1.5-2.9 ->  DEFER    — Include as deferred
+RS < 1.5   ->  BACKLOG  — Move to backlog appendix
+```
+
+---
+
+## Phase 3: Item Collection & Deduplication
+
+### 3.1 Collect ALL Items
+Gather items from:
+
+1. **Test failures** — each failure = 1 item
+2. **TODO/FIXME scan** — each finding = 1 item
+3. **Missing test coverage** — each uncovered module = 1 item
+4. **Incomplete commands** — each gap = 1 item
+5. **Missing features** — from roadmap/README promises
+6. **Documentation gaps** — each stale/missing doc = 1 item
+7. **Error pattern prevention** — from patterns.md
+
+### 3.2 Deduplicate
+- Same file + same issue = same item
+- Same feature described differently = same item
+
+---
+
+## Phase 4: Effort Estimation
+
+| Size | Time | Lines Changed | Files |
+|------|------|---------------|-------|
+| XS | < 15 min | < 20 | 1 |
+| S | 15-60 min | 20-100 | 1-2 |
+| M | 1-4 hours | 100-500 | 2-5 |
+| L | 4-8 hours | 500-2000 | 5-10 |
+| XL | 8+ hours | 2000+ | 10+ |
+
+---
+
+## Phase 5: Scan Assembly
+
+### 5.1 Output
+Return JSON via `pan-tools focus scan` with all items, or write to `.planning/focus/` for persistence.
+
+### 5.2 Document Structure
+
+The scan output includes:
+- Status Snapshot table
+- Items grouped by priority tier (P0-P6)
+- Each item: ID, title, symptom, root cause, fix guidance, files, effort
+- Summary statistics (items by priority x effort)
+- Recommended execution order (quick wins -> core fixes -> feature work)
+- Feature Reality Check table (RS scores for P3-P6 items)
+- Deferred items with rationale
+
+---
+
+## Phase 6: Validation Protocol (skip with --quick)
+
+### 6.1 Cross-Check Completeness
+Verify the scan covers:
+- [ ] All failing tests (if any)
+- [ ] All TODO/FIXME items from code scan
+- [ ] All modules without test coverage
+- [ ] All commands listed in README but not implemented
+- [ ] All error patterns that need prevention
+
+### 6.2 Sanity Check
+- No item should appear twice
+- Every P0-P2 item should have a specific file path
+- Deferred items should have clear "revisit when" criteria
+
+---
+
+## NEVER DO
+
+- Skip reading source files — the scan must be evidence-based
+- List items without file paths (for code items)
+- Create items with vague descriptions
+- Include items that are already complete
+- Include P3-P6 feature items without an RS score
+
+## ALWAYS DO
+
+- Deep-dive into actual code (grep for TODOs, read modules)
+- Cross-reference tests against implementations
+- Link every item to its source file
+- Provide specific fix guidance
+- Score every P3-P6 item with the RS formula
+- Sort the Feature Reality Check table by RS descending