pan-wizard 3.35.0 → 3.37.0

package/docs/EXAMPLES.md

@@ -0,0 +1,584 @@
+# PAN Wizard -- Worked Examples
+
+Realistic command sequences showing common PAN Wizard workflows. Each example
+shows what you type, what PAN does behind the scenes, and what to expect.
+
+---
+
+## Example 1: New Project from Scratch (Full Lifecycle)
+
+A solo developer building a CLI task manager from zero.
+
+### Step 1 -- Initialize the project
+
+```text
+/pan:new-project
+```
+
+PAN asks a series of scoping questions: what you are building, who it is for,
+tech stack preferences, deployment targets, and rough scope. Answer
+conversationally -- PAN extracts structure from your responses.
+
+```text
+PAN: What are you building?
+You: A CLI task manager called "doto". It stores tasks in a local SQLite
+     database, supports priorities, due dates, and tags. Written in Python.
+
+PAN: Who is the primary audience?
+You: Developers who live in the terminal.
+
+PAN: Any technical constraints?
+You: Python 3.10+, no external service dependencies, single-file DB.
+     Ship as a pip-installable package.
+```
+
+When the conversation is complete PAN creates:
+
+- `.planning/project.md` -- vision and goals
+- `.planning/requirements.md` -- scoped functional and non-functional requirements
+- `.planning/roadmap.md` -- phased delivery plan (e.g., Phase 1: Core CRUD,
+  Phase 2: Filtering & Tags, Phase 3: Packaging & Docs)
+
+### Step 2 -- Discuss implementation preferences for Phase 1
+
+```text
+/pan:discuss-phase 1
+```
+
+PAN picks the gray areas of Phase 1 that would change what you get, such as
+output format, flag design and error handling, and asks about those. It does not
+ask about technical choices like the database schema or the CLI library; planning
+(and research, when you ask for it) settles those unless you state a preference. Your answers are
+recorded in `.planning/phases/01-{name}/01-context.md` as decisions.
+
+```text
+PAN: How should the commands and their flags look?
+You: Subcommands (doto add, doto list, doto done), each with its own --help. Use Typer.
+
+PAN: How should tasks be displayed?
+You: Rich tables for list view, plain text for single-task view.
+```
+
+### Step 3 -- Plan Phase 1
+
+```text
+/pan:plan-phase 1
+```
+
+A planner agent turns the phase's requirements and your context decisions
+into a concrete plan (research is opt-in: with `--research`, a researcher first
+answers at most five open questions that block building, such as which Typer
+pattern to use, each with a source), with a `## Review Focus` section
+naming the untested inputs the reviewer should check. Code checks
+(`verify plan-set`, `verify review-focus`, `verify decisions`) send a broken
+plan set back first; a plan-checker agent then reviews the plan for gaps,
+contradictions, and missing edge cases (one revision round by default; two
+under the `quality` profile or `--quality`). A phase whose requirements each
+say precisely what to build skips both agents: the engine writes one task per
+requirement and checks the plans in code.
+
+Result: `.planning/phases/01-{name}/01-01-plan.md` (and additional plans) containing ordered implementation steps,
+file-by-file change descriptions, and dependency notes.
+
+### Step 4 -- Execute Phase 1
+
+```text
+/pan:exec-phase 1
+```
+
+PAN reads the phase's plans and groups independent plans into parallel waves. Wave 1
+might create the project skeleton and database module simultaneously. Wave 2
+builds the CLI commands that depend on both. Each wave completes and its summaries are
+spot-checked before the next begins. After the last wave, `pan-reviewer` reviews the
+phase's diff against the plans' intent (`pan-tools review scope`), including any concerns
+an executor returned with `DONE_WITH_CONCERNS`, and the verifier checks the phase
+(unless `workflow.verifier` is off). Finally the phase gate decides whether the phase
+is marked complete: by default it refuses while a plan has no summary, the
+verification is missing or failing, or a critical or high finding is open, and
+lists each reason (`pan-tools phase gate 1` runs the same check).
+
+You see real-time progress as files are created and tests are run. Once the
+phase's spend reaches 80% of the phase budget (`cost.phase_budget_usd`, $20 by
+default), the wave report says so; it is a warning, and the run continues.
+
+### Step 5 -- Verify the work
+
+```text
+/pan:verify-phase 1
+```
+
+PAN re-runs goal-backward verification with a test-suite gate and writes
+`.planning/phases/01-{name}/01-verification.md`. If it reports `gaps_found`,
+run `/pan:plan-phase 1 --gaps` to plan the fixes, then `/pan:exec-phase 1 --gaps-only` to execute them.
+Manual acceptance testing (for example `doto add 'Buy milk' --priority high`
+followed by `doto list`) is yours to run: `/pan:verify-phase 1 --uat` walks you
+through it one test at a time on any runtime, records each answer in
+`01-uat.md` through `pan-tools uat record`, and diagnoses the issues you
+report for `/pan:plan-phase 1 --gaps`.
+
+### Step 6 -- Continue through the remaining phases
+
+```text
+/pan:discuss-phase 2
+/pan:plan-phase 2
+/pan:exec-phase 2
+/pan:verify-phase 2
+
+/pan:discuss-phase 3
+/pan:plan-phase 3
+/pan:exec-phase 3
+/pan:verify-phase 3
+```
+
+Repeat the cycle for Phase 2 (Filtering & Tags) and Phase 3 (Packaging & Docs).
+Each phase builds on the verified output of the previous one.
+
+### Step 7 -- Complete the milestone
+
+```text
+/pan:milestone-done 0.1.0
+```
+
+Once all three phases are verified, `/pan:milestone-done 0.1.0` archives the
+milestone's roadmap and requirements to `.planning/milestones/`, tags the release (`v0.1.0`), and updates
+`.planning/roadmap.md` to mark the milestone complete.
+
+---
+
+## Example 2: Adding Features to an Existing Codebase
+
+You have a Django web app and want to add a REST API layer.
+
+### Step 1 -- Map the existing codebase
+
+```text
+/pan:map-codebase
+```
+
+PAN maps the repository — one agent for a small repo, parallel mappers sharded by focus
+area for a large one. They
+catalog models, views, URL patterns, middleware, settings, test structure,
+dependency versions, module relationships, and best practices. The output is
+a structured understanding of what already exists, stored so that subsequent
+commands have full context.
+
+This matters because without mapping, PAN would ask generic questions during
+project setup. With mapping, it already knows your models, your auth setup,
+and your existing test patterns.
+
+### Step 2 -- Initialize the API project
+
+```text
+/pan:new-project
+```
+
+Because the codebase has been mapped, PAN tailors its questions to the
+brownfield scenario:
+
+```text
+PAN: I see a Django 4.2 app with 12 models and session-based auth.
+     What do you want to add?
+You: A REST API using Django REST Framework. Token auth for external
+     clients, session auth for the existing frontend.
+
+PAN: Which models need API endpoints?
+You: All of them except AuditLog and AdminConfig.
+
+PAN: Any versioning strategy?
+You: URL-based: /api/v1/
+```
+
+PAN generates requirements and a roadmap that reference your actual models
+by name and account for your existing URL structure.
+
+### Step 3 -- Plan and execute
+
+```text
+/pan:discuss-phase 1
+/pan:plan-phase 1
+/pan:exec-phase 1
+```
+
+The plan references real files in your codebase. Execution modifies existing
+files (adding serializers, viewsets, URL includes) rather than generating
+everything from scratch. Tests are written to match your existing test style.
+
+---
+
+## Example 3: Quick Bug Fix
+
+A user reports that dates are displayed in UTC instead of local time.
+
+```text
+/pan:quick
+```
+
+```text
+PAN: What do you need?
+You: The task list shows due dates in UTC. They should display in the
+     user's local timezone. The relevant code is in src/display.py.
+```
+
+PAN reads the file, identifies the formatting call, applies the fix, and
+runs existing tests. No research phase, plan checker or verifier (the test run is the check) -- a short plan and summary go to `.planning/quick/` -- just a focused
+change with verification.
+
+```text
+PAN: Fixed. Changed `task.due_date.strftime(...)` to
+     `task.due_date.astimezone(tz.tzlocal()).strftime(...)` in
+     src/display.py:47. All 23 tests pass.
+```
+
+For larger ad-hoc work, use `--full` to add a plan-checker pass (max 2
+iterations) and post-execution verification without the full phase ceremony:
+
+```text
+/pan:quick --full
+```
+
+```text
+You: Add CSV export to the task list command.
+```
+
+PAN plans the implementation, has the plan checked, executes it, and
+verifies -- all in one flow, without research and without creating a formal phase.
+
+---
+
+## Example 4: Resuming After a Break
+
+You stopped mid-session yesterday. Today you open the project and cannot
+remember where you left off.
+
+### Check current state
+
+```text
+/pan:progress
+```
+
+PAN reads `.planning/state.md` and `.planning/roadmap.md` and prints a
+summary:
+
+```text
+# doto
+
+**Progress:** [█████████████████░░░] 5/6 plans (83%)
+**Profile:** balanced
+
+## Recent Work
+- [Phase 2, Plan 1]: tags stored with each task, `doto add --tag`
+- [Phase 2, Plan 2]: tag filtering on `doto list`
+
+## Current Position
+Phase 2 of 3: Filtering & Tags
+Plan 3 of 3: not started
+CONTEXT: ✓
+
+## ▶ Next Up
+
+**02-03: Date filtering** — date-range filtering and the `doto filter` subcommand
+
+`/pan:exec-phase 2`
+```
+
+### Restore full context
+
+```text
+/pan:resume
+```
+
+PAN reloads project context, phase plan, decisions from discussion, and the
+execution state. It reconstructs what has been built, what remains, and any
+blockers noted in `state.md`. You are back to full working context without
+re-reading anything yourself.
+
+```text
+PAN: Context restored. Phase 2 execution is at wave 3 of 3.
+     Remaining work: date-range filtering and the `doto filter` subcommand.
+     Ready to continue with /pan:exec-phase 2
+```
+
+### Saving state before stopping
+
+When you need to stop mid-session:
+
+```text
+/pan:pause
+```
+
+PAN writes current progress, open decisions, and any partial work notes to
+a `.continue-here.md` handoff file in the active phase directory so that
+`/pan:resume` can pick up cleanly next time.
+
+---
+
+## Example 5: Cost-Conscious Development
+
+You are working on a side project and want to minimize token usage.
+
+### Switch to the budget profile
+
+```text
+/pan:settings --profile budget
+```
+
+This configures PAN to use cheaper models for research, planning and code-writing agents.
+The orchestrator keeps the model you launched the session with, but the
+parallel sub-agents use lighter ones.
+
+### Disable optional stages
+
+```text
+/pan:settings
+```
+
+```text
+PAN: Which model profile for agents?
+You: Budget
+PAN: Spawn Plan Researcher? (off by default; answers up to 5 open questions before planning)
+You: No
+PAN: Spawn Plan Checker? (verifies plans before execution)
+You: No
+PAN: Spawn Execution Verifier? (verifies phase completion)
+You: Yes
+(auto-advance, Nyquist, branching and phase-budget questions follow, each with your current value pre-selected)
+```
+
+With these off (research is already off by default), `plan-phase` skips the researcher agent and the
+plan-checker agent (the code checks on the plans still run; they cost no model call). Planning still happens, but it relies on the model's
+built-in knowledge instead of dedicated research passes.
+
+**Token savings:** A typical phase with research and plan-check might use
+80-120k tokens across the sub-agents. Disabling both reduces `plan-phase`
+to roughly 15-25k tokens -- a 70-80% reduction.
+
+### The workflow is identical
+
+```text
+/pan:discuss-phase 1
+/pan:plan-phase 1        # faster, cheaper -- no research or plan-check
+/pan:exec-phase 1
+/pan:verify-phase 1
+```
+
+The same commands, the same file structure, just fewer agent spawns. You can
+re-enable research for complex phases and disable it for straightforward ones.
+
+---
+
+## Example 6: Multi-Phase with Scope Changes
+
+You are three phases into a project when priorities shift.
+
+### Original roadmap
+
+```text
+Phase 1: User authentication     [complete]
+Phase 2: Dashboard               [complete]
+Phase 3: Reporting               [in progress]
+Phase 4: Notifications           [pending]
+Phase 5: Admin panel             [pending]
+```
+
+### Urgent work arrives mid-project
+
+The team needs a webhook integration before the next demo. Insert it as a
+new phase:
+
+```text
+/pan:insert-phase 3 "Webhook Integration"
+```
+
+The first argument is the phase to insert *after*. PAN uses decimal numbering
+and never renumbers existing phases: it inserts `Phase 3.1: Webhook Integration`
+right after Phase 3. Notifications stays at 4, Admin Panel stays at 5 — every
+existing phase number is preserved. The roadmap updates:
+
+```text
+Phase 1: User authentication     [complete]
+Phase 2: Dashboard               [complete]
+Phase 3: Reporting               [in progress]
+Phase 3.1: Webhook Integration   [pending]      <-- inserted (URGENT)
+Phase 4: Notifications           [pending]
+Phase 5: Admin panel             [pending]
+```
+
+### Descoping work that is no longer needed
+
+The admin panel has been deprioritized indefinitely:
+
+```text
+/pan:remove-phase 5
+```
+
+```text
+Phase 1: User authentication     [complete]
+Phase 2: Dashboard               [complete]
+Phase 3: Reporting               [in progress]
+Phase 3.1: Webhook Integration   [pending]
+Phase 4: Notifications           [pending]
+```
+
+The roadmap stays clean, phase numbers stay sequential, and all state
+references update automatically.
+
+### Continue normally
+
+```text
+/pan:exec-phase 3     # finish current work
+/pan:verify-phase 3
+/pan:discuss-phase 3.1     # move to the inserted phase
+/pan:plan-phase 3.1
+/pan:exec-phase 3.1
+```
+
+---
+
+## Example 7: From PRD to Code (--auto Mode)
+
+You have a product requirements document and want PAN to initialize the
+project without an interactive Q&A session.
+
+### Prepare your PRD
+
+Your file `prd.md` contains:
+
+```markdown
+# Doto -- CLI Task Manager
+
+## Overview
+A terminal-based task manager for developers. SQLite storage,
+pip-installable, Python 3.10+.
+
+## Features
+- Add, edit, delete, complete tasks
+- Priority levels (low, medium, high, critical)
+- Due dates with local timezone display
+- Tag-based organization
+- Rich table output for list views
+- CSV and JSON export
+
+## Technical Decisions
+- CLI framework: Typer
+- Database: SQLite via sqlite3 stdlib
+- Output: Rich library for tables
+- Packaging: setuptools with pyproject.toml
+
+## Non-Functional Requirements
+- Sub-100ms response for all commands
+- Database migrations via simple version table
+- 90%+ test coverage target
+```
+
+### Run automated initialization
+
+```text
+/pan:new-project --auto @prd.md
+```
+
+PAN reads the PRD, extracts goals, requirements, constraints, and technical
+decisions. Instead of asking you questions, it generates all planning
+artifacts directly (research only with `--research` or idea frontmatter `research_enabled: true`):
+
+```text
+PAN: Read prd.md (847 tokens). Extracting project structure...
+
+Created:
+  .planning/project.md       -- vision and goals from PRD
+  .planning/requirements.md  -- 14 functional, 3 non-functional requirements
+  .planning/roadmap.md       -- 3 phases: Core CRUD, Organization & Export,
+                                Packaging & Polish
+  .planning/config.json      -- default configuration
+
+AUTO-ADVANCING → DISCUSS PHASE 1
+(runs /pan:discuss-phase 1 --auto, which chains plan → execute for phase 1)
+```
+
+### Continue with the next phase
+
+`--auto` does not stop at the roadmap: `/pan:new-project` sets `workflow.auto_advance: true` and runs `/pan:discuss-phase 1 --auto`, which chains planning, execution and verification of phase 1 and then prints the next command (plan-phase runs exec-phase with `--no-transition`, so the chain ends at the phase boundary). When the session then tries to end, PAN's stop guard (Claude Code, Codex, Copilot CLI, Gemini CLI) blocks that stop once, because autonomy is armed and roadmap phases remain, and tells the agent to run the next phase; set `workflow.stop_guard: false` in `.planning/config.json` to stop at each phase instead. To continue by hand:
+
+```text
+/pan:discuss-phase 2 --auto   # the next phase, chained the same way
+```
+
+The `--auto` flag on `discuss-phase` and `plan-phase` chains each into the next step and persists `workflow.auto_advance: true`; it also tells PAN to make
+reasonable decisions from context rather than asking. Useful when your PRD
+is detailed enough to answer implementation questions.
+
+---
+
+## Quick Reference: Common Sequences
+
+| Scenario | Command sequence |
+|---|---|
+| Greenfield project | `new-project` > `discuss-phase` > `plan-phase` > `exec-phase` > `verify-phase` |
+| Brownfield project | `map-codebase` > `new-project` > `discuss-phase` > `plan-phase` > `exec-phase` > `verify-phase` |
+| Fast bug fix | `quick` |
+| Substantial ad-hoc work | `quick --full` |
+| Start of day | `progress` > `resume` |
+| End of day | `pause` |
+| New version cycle | `milestone-done` > `milestone-new` |
+| Automated from PRD | `new-project --auto @prd.md` (chains discuss → plan → execute → verify for phase 1, then prints `discuss-phase 2 --auto`; the stop guard blocks one stop and tells the agent to spawn phase 2) |
+
+---
+
+## Spec B v2 worked examples
+
+### Preview a risky phase before committing
+
+You've planned a database migration in phase 7. Before running `exec-phase`, sanity-check the blast radius.
+
+```text
+/pan:preview phase 7
+```
+
+The data layer scans `07-01-plan.md`, `07-02-plan.md`, etc., extracts file paths mentioned in backticks or under known source roots (`src/`, `tests/`, etc.), and runs the risk regex over the combined plan text. The `pan-previewer` agent then synthesizes a report at `.planning/phases/07-<slug>/preview.md`:
+
+- **Files likely touched** — `src/db/migrations.js`, `src/models/User.js`, `tests/migrations.test.cjs`
+- **Tests at risk** — 3 test files reference migration schemas
+- **Risk signals** — `drop: true`, `migrate: true`, `rename: true` → risk score 7/10
+- **Cost forecast** — p10/p50/p90 dollars per plan and for the phase, from this project's own cost ledger; `insufficient` until enough past runs back it
+- **Bottom line** — "Run in a feature branch with a rollback plan. Migration reverse is not documented in plan.md."
+
+If risk ≥ 7 or auth keywords hit, review the plan before `/pan:exec-phase`. Combine with `--deep-review` for auth/payment phases.
+
+### Deep-review an auth phase
+
+Phase 4 adds JWT authentication. Run exec-phase with deep-review enabled:
+
+```text
+/pan:exec-phase 04 --deep-review
+```
+
+Right after the normal review, before the verifier, exec-phase runs the `/pan:review-deep` process inline (its reports go under `.planning/reviews/04/`, named with the phase directory's number, so padding the argument is not needed); on `review_required` or `block` it stops before verification:
+
+1. **pan-hardener** (OWASP + STRIDE) writes `.planning/reviews/04/hardener.md`. Looks for missing authorization checks, credential storage weaknesses, session management gaps.
+2. **pan-meta-reviewer** reads both reviewer + hardener, writes `.planning/reviews/04/meta.md`. Flags what either missed, disputes overstated severities.
+3. Merge writes `.planning/reviews/04/deep-review.md` with verdict (`ok` / `ok_with_minor` / `fix_before_merge` / `review_required` / `block`) + findings table.
+
+Verdict `block` means a critical issue was found — don't merge until resolved. `review_required` means a high finding needs human sign-off.
+
+### Generate a team playbook after milestone-done
+
+After shipping a milestone, capture accumulated lessons for onboarding:
+
+```text
+/pan:milestone-done 0.1.0
+/pan:knowledge playbook
+```
+
+The playbook command reads every agent log in `.planning/memory/` (`memory list`) — the lessons someone recorded there for `pan-planner`, `pan-verifier` and other agents with `/pan:retro --write-memory`, `memory append` or `memory record` (PAN writes none on its own, so a project with none gets an empty playbook; the playbook is not scoped to one milestone) — and clusters entries into categories (Conventions / Gotchas / Decisions / Tool choices / Anti-patterns / Recurring gaps / General). Output at `.planning/playbook.md`:
+
+```markdown
+## Conventions
+- 2026-04-10: Prefer bulk Postgres writes over per-row commits _— from `pan-planner`_
+
+## Gotchas
+- 2026-04-12: Careful: async iterators finalize on throw; wrap in try/finally _— from `pan-verifier`_
+
+## Decisions
+- 2026-04-15: Chose Redis over Memcached — Redis AOF gives durability at our write rate _— from `pan-planner`_
+```
+
+New team members run `/pan:knowledge ask "what should I know before editing the cache layer?"` and get grounded answers citing the agents' memory files (the source the playbook is built from) plus relevant ADRs.