wize-dev-kit 0.1.5 → 0.2.5

package/CHANGELOG.md

@@ -5,6 +5,129 @@ Format inspired by [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.2.5] — 2026-06-12
+
+Fixes a real install-time bug that bit non-TTY users (CI smoke + anyone piping input into `wize-dev-kit install`).
+
+### Fixed
+
+- **Non-TTY prompt stall.** The CLI's `prompt()` helper created a new `readline.createInterface` per call and used `rl.question()`. Both choices misbehave in pipe mode: per-call interfaces close stdin on the first `rl.close()`, and even with a shared interface `readline.question` stalls when it has to read an empty line in non-TTY mode (Node 24 behavior). After step 1 of `install` (project name), every subsequent prompt would hang silently. Replaced with an event-based line reader: subscribe once to `line`, push waiters in order, propagate empty lines as `""`, treat EOF as "remaining waiters resolve empty". `printf '...\n\n\n\n\nName\n\n' | wize-dev-kit install` now runs cleanly to completion.
+
+### Notes
+
+This was the actual cause behind the CI smoke E2E loop. The 0.2.4 fix to the smoke script (using `npm install <tarball>` instead of `npx <tarball>`) was correct, but the underlying CLI couldn't accept piped input either, so the smoke kept failing at the second prompt. With both fixed, the smoke runs end-to-end.
+
+## [0.2.4] — 2026-06-12
+
+CI-only hotfix to actually unblock the publish pipeline. Surface area of wize-dev-kit unchanged.
+
+### Fixed
+
+- Smoke E2E step used `npx --yes "$tarball" install`. On the GitHub Actions runner that path is interpreted as a shell command, which tries to **execute the tarball directly** before npx ever extracts it — exit code 126, `Permission denied`. Rewrote the step to: install the tarball into a throwaway project via `npm install <tarball>`, then invoke `$NODE_MODULES/.bin/wize-dev-kit` directly. `npm install` extracts the archive properly and sets the bin executable bit, so the rest of the smoke (`install` → assertions → `update` → `agent list`) runs cleanly. Same coverage, named-per-check error messages, and now also sets `WIZE_DISABLE_UPDATE_CHECK=1` so the registry isn't probed mid-smoke.
+
+## [0.2.3] — 2026-06-11
+
+Hotfix: 0.2.1 and 0.2.2 publish workflows hung because `test/version-check.test.js` had a sync/async bug in its test scaffolding. CI's smoke E2E never started for those releases. This release fixes the test and re-runs the same smoke for 0.2.2 + 0.2.3.
+
+### Fixed
+
+- `withTempCacheHome` helper in `test/version-check.test.js` was synchronous (`return fn(dir)`), so its `finally` block restored the env var before the async callback's `writeCache` resolved. The cache lookup inside the callback then landed in the real `~/.cache/wize-dev-kit/`, contaminating subsequent test runs and intermittently failing the `getLatestVersion returns the cached value when fresh` assertion. Fix: make the helper `async` and `return await fn(dir)`. Confirmed locally + ensures CI doesn't get a stuck cache file across tags.
+
+### Notes
+
+No surface area changed; behavior of `wize-dev-kit` itself is identical to 0.2.2. The bump exists only so the publish workflow re-runs cleanly.
+
+## [0.2.2] — 2026-06-11
+
+Closes the "documentation always stale" gap: inline knowledge captures per story, Hawkeye enforces, sprint-end refresh consolidates. Plus auto-update nudges on the CLI and Wizer.
+
+### Added — knowledge stays current
+
+- **`wize-dev-story` step 8 — Knowledge update (inline).** After commits and before pre-PR check, Shuri checks whether the story touched any of the 5 baseline axes (architecture / conventions / risk-spots / dependencies / overview) and, if yes, adds 1–3 dated bullets to the matching `.wize/knowledge/document-project/*.md` file — same PR. ~60 seconds when applicable; skipped otherwise.
+- **`wize-quick-dev` step 5 — Knowledge update (only if applicable).** Quick-dev rarely touches axes; when it does (dep bump that shifts API, rename that breaks a contract), one line lands in the relevant doc.
+- **`wize-tea-review` step 5 — Knowledge update check.** Hawkeye walks the diff. Touched-but-not-updated stories get a `KN-NN` finding. `tea-review` frontmatter now carries `knowledge_axes_touched` + `knowledge_axes_updated`.
+- **`wize-tea-gate` decision rule extended.** When `knowledge_axes_touched ≠ knowledge_axes_updated`, recommendation flips to `CONCERNS` (advisory) or `FAIL` (enforcing). Example `KN-NN` finding shape documented in the canonical YAML.
+- **`wize-refresh-knowledge` (new workflow).** Sprint-end consolidation: Pepper + Peggy roll the dated bullets accumulated through the sprint into the narrative prose of each axis file, demote stale claims to a `Deprecated` section, freeze a snapshot at `.wize/knowledge/document-project/_history/{YYYY-Qn}/sprint-{N}.md`, and stamp `last_refreshed` in each file. Triggered when `wize-help next` detects the sprint emptied.
+- **`wize-document-project` — Update mode section.** Documents the two-cadence loop (inline-per-story + sprint-refresh) and the file frontmatter convention (`last_refreshed`).
+
+### Added — proactive nudges
+
+- **`wize-help` skill — version-skew detection.** Wizer now reads `kit_version` from `.wize/config/project.toml`, compares with the installed package version and (via Bash tool when available) the registry, and proactively suggests `npx wize-dev-kit@latest update` when behind. Worded as a single short line, never as a banner.
+- **`wize-help` skill — sprint-end detection.** Heuristic refined: when sprint-status shows all stories gated and no `ready-for-dev` left, the next-step recommendation is `wize-retrospective` + `wize-refresh-knowledge`, not just retro.
+- **CLI version check (camera 1).** `wize-dev-kit list / sync / agent / workflow / help` now print a one-line `↑ Update available: X → Y` at the top when a newer version sits in the npm registry. Cached for 1 hour, 1.5s network timeout, silent on offline / non-TTY / `WIZE_DISABLE_UPDATE_CHECK=1`. Never blocks. New module `tools/installer/version-check.js`.
+
+### Tests
+
+- Total: **104 passing** (was 94 in 0.2.1).
+- 10 new tests in `test/version-check.test.js` covering semver compare, cache freshness, fetch fallback (offline + non-2xx), TTY guard, env disable.
+
+### Files
+
+- `src/method-skills/1-analysis/wize-refresh-knowledge/workflow.md` (new).
+- `tools/installer/version-check.js` (new).
+- Edits to `wize-dev-story`, `wize-quick-dev`, `wize-tea-review`, `wize-tea-gate`, `wize-help` skill, `wize-document-project`, `tools/installer/wize-cli.js`.
+
+## [0.2.1] — 2026-06-11
+
+Focused polish: brownfield baseline finally runs end-to-end through a detected harness CLI, CI publishes without the deprecated-config warning, and every release is now smoke-tested before going up.
+
+### Added
+
+- **Brownfield baseline runs real now.** When the installer detects existing code and you accept the `Run wize-document-project?` prompt, it now scans your PATH for an AI harness CLI (Claude Code, then Codex, then OpenCode), prioritizes whichever you selected as an IDE target, asks you to confirm the headless invocation, and spawns it with the right flags (`claude -p`, `codex exec`, `opencode run`). If no harness CLI is on PATH, the installer prints the exact command you can run later in your IDE. Set `WIZE_SKIP_BASELINE=1` to disable the headless run entirely (used by CI and unattended setups).
+- `tools/installer/baseline.js` — exports `detectHarnessCli`, `runHeadlessBaseline`, `manualInstructions`, `defaultPrompt`. Self-contained, no extra deps; uses a manual PATH walk for hermetic, cross-platform detection.
+- 7 new unit tests covering detection priority, PATH isolation, the skip-baseline env, and instruction strings.
+
+### Fixed
+
+- CI publish workflow now strips the deprecated `always-auth=false` line from the runner's `.npmrc` before installing. Removes the `npm warn Unknown user config "always-auth"` noise that appeared in every 0.2.0 publish log. See actions/setup-node#1129.
+
+### Added — CI
+
+- **Smoke E2E before publish.** The workflow now packs the tarball, installs it in a temp git repo via `npx`, and asserts that `.wize/`, the Claude adapter SKILL.md, generic AGENTS-equivalent, `kit_version` in `project.toml`, `update`, and `agent list` all work — exactly like a user would experience. Fails the release if anything is off, so we never publish a broken tarball again.
+- Sets `WIZE_SKIP_BASELINE=1` in the smoke step so the harness-run prompt doesn't try to spawn `claude` inside GitHub's runner.
+
+### Tests
+
+- Total now **94 passing** (was 87 in 0.2.0).
+
+## [0.2.0] — 2026-06-11
+
+First release that delivers the lifecycle end-to-end. Workflows have real bodies; CLI commands work for real; the team has a Walkthrough to follow.
+
+### Added — CLI
+
+- **`wize-dev-kit update`** — refreshes an installed kit to the version resolved by `node_modules/wize-dev-kit`. Re-runs every active IDE adapter, preserves `.wize/config/user.toml`, re-applies the suggested `.gitignore` block, and writes the new `kit_version` into `.wize/config/project.toml`. Prints the relevant CHANGELOG excerpt between the previous and current version.
+- **`wize-dev-kit sync`** — re-renders adapter outputs for whatever `ide_targets` the project opted into. Cheap idempotent call after editing config or running `agent create`.
+- **`wize-dev-kit agent list`** — lists every built-in agent (9) plus any custom or override agents the project added.
+- **`wize-dev-kit agent create`** — interactive scaffold of a new custom agent. Validates `code` shape, checks for collisions with built-ins, does a dry-run write+read, then persists to `.wize/custom/agents/{code}/{agent.yaml, persona.md}`. Non-TTY callers can pass a spec via API (`fromSpec`).
+- **`wize-dev-kit agent edit <code>`** — writes a `customize.toml` override for an existing built-in agent into `.wize/custom/agents/{code}/`.
+
+### Added — UX
+
+- **End-of-install message** now ends with: "Restart your IDE — many harnesses load skills only at startup." plus a quick-reference to the new CLI commands (`update`, `sync`, `agent list`).
+- **README walkthrough** — a complete end-to-end slash-command map from `/wize-orchestrator` through `/wize-tea-gate`, plus a new "CLI commands" reference section.
+
+### Changed — workflows now have real bodies
+
+22 workflows that were ≈ 30–50-line stubs in 0.1.x now ship 100–250 lines of working method, examples, anti-patterns, and YAML schemas. Tone aligned with the 0.1.5 playbooks (dense, opinionated, citable).
+
+- **Analysis (Pepper):** `wize-product-brief`, `wize-trigger-map`, `wize-research`, `wize-prfaq`, `wize-document-project`.
+- **Plan (Maria Hill + Mantis):** `wize-create-prd`, `wize-validate-prd`, `wize-ux-scenarios`, `wize-ux-design`.
+- **Strategy + Solutioning (Fury + Tony + Mantis):** `wize-tech-vision`, `wize-nfr-principles`, `wize-create-architecture`, `wize-design-system`, `wize-create-epics-and-stories`, `wize-check-implementation-readiness`.
+- **TEA gates (Hawkeye):** `wize-tea-risk`, `wize-tea-design`, `wize-tea-trace`, `wize-tea-nfr`, `wize-tea-review`, `wize-tea-gate` — each with canonical YAML frontmatter + concrete examples.
+- **Implementation (Shuri + Hill + Wizer):** `wize-create-story`, `wize-dev-story`, `wize-quick-dev`, `wize-sprint-planning`, `wize-sprint-status`, `wize-retrospective`, `wize-code-review`.
+
+### Added — engineering
+
+- `tools/installer/commands/{update,sync,agent}.js` — modular command implementations with a minimal TOML reader for the `project.toml` subset.
+- `test/cli-commands.test.js` — coverage for update / sync / agent list / agent create / agent edit (10 tests).
+- `test/workflow-bodies.test.js` — guards that every workflow.md has ≥ 1.5 KB body and ≥ 4 H2 sections, with an explicit allow-list for intentionally short workflows (overlay scaffolds, builder helpers, orchestrator helpers).
+- Test count: **87 passing** (was 33).
+
+### Notes
+
+This release closes JTBD backlog categories 3 (CLI commands real) and 2 (workflows with body) plus 4 (end-of-install UX, README walkthrough). Categories 5 (CI hygiene incl. smoke E2E) and 6 (monorepo routing, TEA enforcing helper) remain on the roadmap.
+
 ## [0.1.5] — 2026-06-01
 
 ### Added — promises kept
@@ -139,7 +262,13 @@ Ignore (handled by the suggested block): `.wize/config/user.toml`, `.wize/scratc
 - Inspired by [BMAD Method v6.8.0](https://github.com/bmad-code-org/BMAD-METHOD).
 - WDS module inspired by [bmad-method-wds-expansion](https://github.com/bmad-code-org/bmad-method-wds-expansion).
 
-[Unreleased]: https://github.com/qwize-br/wize-development-kit/compare/v0.1.5...HEAD
+[Unreleased]: https://github.com/qwize-br/wize-development-kit/compare/v0.2.5...HEAD
+[0.2.5]: https://github.com/qwize-br/wize-development-kit/compare/v0.2.4...v0.2.5
+[0.2.4]: https://github.com/qwize-br/wize-development-kit/compare/v0.2.3...v0.2.4
+[0.2.3]: https://github.com/qwize-br/wize-development-kit/compare/v0.2.2...v0.2.3
+[0.2.2]: https://github.com/qwize-br/wize-development-kit/compare/v0.2.1...v0.2.2
+[0.2.1]: https://github.com/qwize-br/wize-development-kit/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/qwize-br/wize-development-kit/compare/v0.1.5...v0.2.0
 [0.1.5]: https://github.com/qwize-br/wize-development-kit/compare/v0.1.4...v0.1.5
 [0.1.4]: https://github.com/qwize-br/wize-development-kit/compare/v0.1.3...v0.1.4
 [0.1.3]: https://github.com/qwize-br/wize-development-kit/compare/v0.1.2...v0.1.3

package/README.md

@@ -72,6 +72,55 @@ See [`ROSTER.md`](ROSTER.md) for personas, styles and BMAD equivalences.
 
 ---
 
+## Walkthrough — a full project, end to end
+
+Below is the canonical flow Wizer drives in a real session. Each step is a slash command in your IDE; each persona reads the previous artifact before writing its own. Nothing is mocked.
+
+```
+1.  /wize-orchestrator          Wizer greets, reads .wize/config/{project,user}.toml.
+                                Detects the project state and routes you.
+
+2.  /wize-product-brief         Pepper turns raw demand into brief.md.
+    /wize-trigger-map           Pepper maps user psychology → business goals (WDS).
+    /wize-research              Pepper synthesizes external evidence (optional).
+
+3.  /wize-create-prd            Maria Hill writes prd.md (goals, scope, ACs).
+    /wize-validate-prd          Maria Hill (+ Mantis/Fury) signs off.
+
+4.  /wize-ux-scenarios          Mantis runs the 8-question WDS dialog.
+    /wize-ux-design             Mantis writes page specs (one .md per screen).
+
+5.  /wize-tech-vision           Fury picks the stack family + non-negotiables.
+    /wize-nfr-principles        Fury writes the NFR budget (perf, sec, a11y…).
+
+6.  /wize-create-architecture   Tony writes architecture.md + ADRs.
+    /wize-design-system         Mantis writes design-system/ (tokens + components).
+    /wize-create-epics-and-stories
+                                Tony slices epics → stories (each has ACs).
+
+7.  /wize-tea-risk              Hawkeye builds the global risk profile.
+    /wize-tea-design            Hawkeye writes test design for the next story.
+    /wize-dev-story             Shuri implements (TDD, AC IDs in commits).
+    /wize-tea-trace             Hawkeye maps each AC → tests.
+    /wize-tea-review            Hawkeye runs story review.
+    /wize-tea-gate              Hawkeye emits PASS / CONCERNS / FAIL / WAIVED.
+
+8.  /wize-sprint-status         Maria Hill keeps the daily snapshot updated.
+    /wize-retrospective         Wizer facilitates retro at end of each sprint.
+    /wize-tea-nfr               Hawkeye assesses NFRs at epic boundary.
+
+Cross-cutting:
+    /wize-help                  Wizer figures out where you are and proposes
+                                the next step (use anytime).
+    /wize-quick-dev             Shuri takes a small fix without the full ride.
+    /wize-party-mode            Wizer convenes multi-persona for hard calls.
+```
+
+> Use `/wize-help next` whenever you're unsure — it inspects `.wize/` and tells
+> you the single next action.
+
+---
+
 ## Output layout (in the target repo)
 
 ```
@@ -86,6 +135,21 @@ See [`ROSTER.md`](ROSTER.md) for personas, styles and BMAD equivalences.
 
 ---
 
+## CLI commands
+
+```bash
+npx wize-dev-kit install         # interactive setup
+npx wize-dev-kit update          # bring an installed kit up to the current package version
+npx wize-dev-kit sync            # re-render IDE adapters after editing config
+npx wize-dev-kit agent list      # list built-in + custom agents
+npx wize-dev-kit agent create    # scaffold a new custom agent (validated + dry-run)
+npx wize-dev-kit agent edit <code>  # override a built-in via .wize/custom/agents/<code>/customize.toml
+npx wize-dev-kit validate        # structural checks on the kit assets
+npx wize-dev-kit uninstall       # remove .wize/ (your code is left untouched)
+```
+
+---
+
 ## Documentation
 
 - [`ARCH.md`](ARCH.md) — full architecture: distribution, fluxos, layout, installer.

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "wize-dev-kit",
-  "version": "0.1.5",
+  "version": "0.2.5",
   "description": "Full-lifecycle AI-assisted development kit with Test Architect and Whiteport Design Studio embedded. Inspired by BMAD Method and WDS.",
   "keywords": [
     "ai",

package/src/method-skills/1-analysis/wize-document-project/workflow.md

@@ -2,35 +2,203 @@
 code: wize-document-project
 name: Document Project (brownfield baseline)
 phase: 1-analysis
-owner: wize-agent-analyst   # Pepper Potts (paired with Peggy Carter)
-status: stub
+owner: wize-agent-analyst   # Pepper Potts (paired with Peggy Carter and Tony Stark)
+status: ready
 ---
 
 # Document Project — Brownfield Baseline
 
-**Goal.** When the kit is installed in an existing codebase, baseline the current state so subsequent planning isn't blind. Produces an "as-is" snapshot that Tony reads before drawing the "to-be."
+**Goal.** When the kit is installed in an existing repo, baseline the **as-is** state so the rest of the lifecycle isn't blind. Produces a structured snapshot Tony can read before designing the *to-be*, and a knowledge base Wizer can answer questions from.
+
+Pepper drives discovery. Peggy edits prose. Tony validates architecture interpretation. Output lands in `.wize/knowledge/document-project/`.
 
 ## When to run
-- Installer detected `package.json` / `pubspec.yaml` / `Cargo.toml` / `go.mod` + non-trivial `src/` history.
-- User explicitly requests `/wize-document-project`.
+
+- The installer detected brownfield signals (`package.json`, `src/`, history) and offered to run this. ✓
+- The team is onboarding to a codebase nobody fully owns. ✓
+- A previous re-platforming decision left the docs stale. ✓
+
+Skip:
+- Greenfield (nothing to document yet).
+- Repos < 200 LOC.
 
 ## Inputs
-- The target repo (root)
-- `git log --oneline -50`
-- Existing READMEs / ARCHITECTURE / docs
+
+- The target repo (root).
+- `git log --since="1 year ago" --oneline | wc -l` to scope.
+- Any prior README / ARCHITECTURE / docs that exist.
 
 ## Outputs
-- `.wize/knowledge/document-project/overview.md`
-- `.wize/knowledge/document-project/architecture-snapshot.md`
-- `.wize/knowledge/document-project/conventions.md`
-- `.wize/knowledge/document-project/open-questions.md`
+
+- `.wize/knowledge/document-project/overview.md` — what the project is, who uses it, how big it is.
+- `.wize/knowledge/document-project/architecture-snapshot.md` — current components, integrations, data flow.
+- `.wize/knowledge/document-project/conventions.md` — coding/test/folder conventions actually used.
+- `.wize/knowledge/document-project/dependencies.md` — runtime deps + dev deps + their roles.
+- `.wize/knowledge/document-project/risk-spots.md` — areas of concentrated complexity, undocumented behavior, or known fragility.
+- `.wize/knowledge/document-project/open-questions.md` — things the code doesn't answer; route to humans.
 
 ## Steps
-1. **Inventory.** List packages, top-level modules, infra files, entry points.
-2. **Architecture snapshot.** Components and integrations as currently exist. Diagrams welcome.
-3. **Conventions.** Coding/test/folder conventions surfaced from a sample of files.
-4. **Open questions.** Things the code doesn't answer; route to humans.
-5. **Hand off.** Pepper to Wizer: "baseline ready." Then Wizer decides next agent.
-
-## Pairing
-Peggy Carter edits prose for clarity and structure. Tony Stark may be looped in to confirm architecture interpretation.
+
+### 1. Inventory (Pepper, mechanical)
+
+A first pass that requires no judgment, just listing.
+
+```
+ls -la                                  # top-level layout
+cat package.json | jq '.dependencies, .devDependencies, .scripts'
+git log --since="3 months ago" --oneline | wc -l
+git log --pretty=format:"%an" | sort | uniq -c | sort -rn | head
+find . -name "*.test.*" -o -name "*.spec.*" | wc -l
+find . -type f -name "*.md" | head
+```
+
+Write what you found in `overview.md` (no opinions yet).
+
+### 2. Architecture snapshot (Pepper + Tony)
+
+Walk the repo top-down. Identify:
+- **Entry points** (CLI, server, worker, build).
+- **Components** (where the boundaries are — by folder, by package, by feature).
+- **Integrations** (databases, queues, external APIs, third-party SDKs).
+- **Data flow** for at least one end-to-end critical path (e.g., a typical user request).
+
+Draw or describe. Diagrams in ASCII or Mermaid are fine — the point is shared mental model.
+
+Tony validates. If the snapshot misnames a pattern, fix it.
+
+### 3. Conventions (Peggy)
+
+Sample 5–10 files across the repo. Note:
+- Naming (camelCase / snake_case / kebab-case).
+- Folder structure (feature-first / layer-first).
+- Test placement (co-located / `__tests__` / `test/`).
+- Comment style (JSDoc / TSDoc / inline).
+- Import ordering (alphabetical / by source).
+- Logging / error handling patterns.
+- Linter / formatter config (eslint, prettier, etc.).
+
+Write the convention found, not the convention you'd prefer.
+
+### 4. Dependencies (Pepper)
+
+For each runtime dep, write one line:
+- Name, version, what it does in this repo, whether it's load-bearing.
+
+Flag:
+- Deps without a clear role.
+- Deps with known CVEs (run `npm audit --omit=dev` and capture).
+- Multiple deps doing the same job (`lodash` + `ramda`, both date libs, etc.).
+- Deps not maintained in > 2 years (link to last release).
+
+### 5. Risk spots (Pepper + Tony)
+
+For each, name the area + the symptom + the likely cause + how confident you are:
+
+| Area | Symptom | Likely cause | Confidence |
+|---|---|---|---|
+| `src/legacy/billing/` | 2k-line file with no tests | rushed migration in 2024 | high |
+| Webhooks handler | Silent retries | no idempotency layer | medium |
+| Auth middleware | Custom JWT parsing | predates the library that handles it | high |
+
+This is *not* a refactor backlog. It's a map. Tony decides what to fix; this just makes the choices visible.
+
+### 6. Open questions (everyone)
+
+Things the code does NOT answer:
+- Why was this choice made?
+- What's the SLA?
+- Who's the owner of feature X?
+- Are there secret configs we're missing?
+
+Each question gets an owner (a human Pepper will ask). Route back via Wizer.
+
+### 7. Hand-off
+
+- Mark all docs `status: baseline`.
+- Tell Wizer: *"Baseline complete. Tony can read it before architecture work; Hill can read it before scoping."*
+
+## Conventions doc — template
+
+```markdown
+---
+status: baseline
+owner: Pepper Potts + Peggy Carter
+created: YYYY-MM-DD
+sampled: 8 files across src/, tests/, scripts/
+---
+
+# Conventions (observed, not prescribed)
+
+## Naming
+- Files: kebab-case (e.g., `user-profile.ts`).
+- Classes: PascalCase.
+- Functions: camelCase, verb-led.
+- Constants: UPPER_SNAKE_CASE.
+
+## Folder structure
+Feature-first: `src/features/<feature>/{index.ts, api.ts, ui.tsx, *.spec.ts}`.
+Shared utilities in `src/shared/`.
+
+## Tests
+Co-located with the file under test. `.spec.ts` for unit; `.e2e.ts` for end-to-end (separate runner).
+
+## Lint/format
+`eslint.config.mjs` with `airbnb-base` + custom rules in `eslint.local.cjs`. Prettier with 2-space indent.
+
+## Observed deviations
+- `src/legacy/billing/` doesn't follow feature-first; it predates the convention.
+- Some files use `_test.ts` suffix instead of `.spec.ts` — older code.
+```
+
+## Update mode (how the baseline stays alive)
+
+The first run of this workflow produces the **baseline**. Two complementary mechanisms keep it current after:
+
+### 1. Inline updates per story (the daily cadence)
+
+Every `wize-dev-story` ends with a Knowledge Update step (step 8). If the story touched any of the 5 axes (architecture, conventions, risk-spots, dependencies, overview), Shuri appends 1–3 dated bullets to the matching `document-project/*.md` file **in the same PR**. Hawkeye verifies in `tea-review`; a touched-but-not-updated story gets a `KN-NN` finding at gate.
+
+`wize-quick-dev` has a lighter version: only when a dep bump or a public rename actually shifts the baseline.
+
+This produces dated bullets like:
+
+```markdown
+## 2026-06-12 — E01-S03
+- Conventions: `data-testid="invite-*"` published as public contract.
+- Risk: R-1 (mailer) mitigation confirmed.
+```
+
+### 2. Sprint-end refresh (the narrative cadence)
+
+`wize-refresh-knowledge` runs at sprint end (triggered by `wize-help next` when it detects the sprint emptied). Pepper + Peggy consolidate the inline bullets into the narrative prose of each axis file, demote stale claims to a "Deprecated" section, freeze a sprint snapshot in `_history/{YYYY-Qn}/sprint-{N}.md`, and stamp `last_refreshed` in each file.
+
+Result: the baseline reads like a single coherent document, not a chronological log. New devs can read it linearly and form a mental model. Forensics readers (six months later, asking "when did X change?") consult `_history/`.
+
+### File frontmatter convention
+
+Each `document-project/*.md` file ships with:
+
+```yaml
+---
+status: baseline
+owner: Pepper Potts + Peggy Carter
+created: 2026-04-02
+last_refreshed: 2026-06-25
+sampled: "wkly + sprint refresh"
+---
+```
+
+`last_refreshed` tells the reader how much to trust the file vs the inline bullets accumulating since.
+
+## Anti-patterns Pepper rejects
+
+- "TODO: document later." The baseline IS the documentation pass; later doesn't come.
+- Romanticizing the code ("clean, modular"). Describe what you see; let Tony judge.
+- Architecture diagrams that show what the team *wishes* exists. Diagram the real state.
+- Risk-spot table with no confidence label. Without confidence, readers can't act.
+- Open questions with no owner. They never get answered.
+- Treating the baseline as one-shot. The mode + refresh exist precisely because point-in-time docs lie within weeks.
+
+## Hand-off
+
+> Baseline is in `.wize/knowledge/document-project/`. Three risk spots flagged. Five open questions routed to the humans named per question. Tony can read this before drawing `architecture.md`; Hill can scope the PRD knowing what's already there.

package/src/method-skills/1-analysis/wize-prfaq/workflow.md

@@ -3,25 +3,164 @@ code: wize-prfaq
 name: PR/FAQ
 phase: 1-analysis
 owner: wize-agent-analyst   # Pepper Potts
-status: stub
+status: ready
 ---
 
-# PR/FAQ
+# PR/FAQ — Working Backwards
 
-**Goal.** Force alignment by drafting the "future press release + FAQ" before building. Amazon-style.
+**Goal.** Force alignment by writing the *future* press release and a tight FAQ **before** anyone builds anything. Amazon-style. If you can't write a compelling PR, you don't have a product yet.
+
+Pepper drives. Peggy polishes prose. Output lands in `.wize/planning/prfaq.md`.
+
+## When to run
+
+Run this:
+- New product or new strategic feature.
+- The team disagrees on the user-visible value.
+- You're about to commit > 1 month of engineering.
+
+Skip this:
+- Bug fix, copy edit, dependency bump → use `wize-quick-dev`.
+- The brief already crisply names the user-visible value and the team is aligned → write the PRD directly.
 
 ## Inputs
+
 - `.wize/planning/brief.md`
+- `.wize/planning/research.md` (optional)
 
 ## Outputs
+
 - `.wize/planning/prfaq.md`
 
+## Structure (the Amazon shape)
+
+A PR/FAQ has two parts: the **PR** (≤ 1 page) and the **FAQ** (≤ 2 pages).
+
+### The PR (write this first)
+
+| Section | Length | What goes in it |
+|---|---|---|
+| **Headline** | 1 line | Audience + benefit + product name. Reader-understandable. |
+| **Sub-headline** | 1 line | The non-obvious part of the benefit. |
+| **Summary paragraph** | 3–5 sentences | What it is, who it's for, what changes, where to get it. |
+| **Problem paragraph** | 3–5 sentences | Why this matters *now*, evidence the pain is real. |
+| **Solution paragraph** | 3–5 sentences | How the product solves the problem. Concrete, not abstract. |
+| **Internal quote** | 1 quote | A leader (founder/CEO) saying why this matters strategically. |
+| **How it works** | 3 sentences | Three lines max. Not implementation — the *user* mental model. |
+| **Customer quote** | 1 quote | An imagined real user saying the thing they'd say. Specific. |
+| **How to get started** | 2 lines | One sentence: where + how. One sentence: what's first. |
+
+If you find yourself writing more, cut. The discipline is the point.
+
+### The FAQ
+
+5–10 questions a sharp reader would actually ask. Crisp answers.
+
+**Mandatory questions** (always include):
+
+1. Who exactly is this for?
+2. What does this replace today?
+3. Why now? (Why not last year, why not next year?)
+4. How is this different from {{nearest competitor}}?
+5. What's *out* of scope at launch?
+6. What does success look like in 6 months? In 18 months?
+7. What are the top three risks?
+
+**Optional questions** (include when relevant):
+
+8. What's the pricing model?
+9. How does this work for non-English locales / accessibility / offline?
+10. What does the regulatory story look like?
+11. What's the launch sequence (geos / segments / preview)?
+
 ## Steps
-1. **Headline + subhead.** One sentence each. Reader must understand.
-2. **Quote (customer).** Why does this matter to a real user?
-3. **Quote (internal leader).** Why does this matter to the business?
-4. **How it works.** Three paragraphs max.
-5. **FAQ.** 5–10 most likely sharp questions, with crisp answers.
-
-## When to skip
-Skip this workflow for small fixes or features whose audience is obvious. Use for net-new products or strategic bets.
+
+### 1. Frame and freeze the audience
+
+Write the audience line at the top of your draft and don't move it. Every sentence is judged against "does this matter to the audience?"
+
+### 2. PR before FAQ
+
+Always. The discipline of writing the PR exposes vague thinking. The FAQ comes after, when you're forced to defend it.
+
+### 3. Show, don't market
+
+No "world-class," "revolutionary," "AI-powered" without a noun next to it. If you can replace the adjective with another and lose nothing, delete it.
+
+### 4. Numbers, not adjectives
+
+Every claim has a unit. "Reduces onboarding from 35 minutes to 7" beats "reduces onboarding significantly."
+
+### 5. Pre-mortem question
+
+Before sending, write the answer to: *"It's six months after launch and it failed. Why?"*. If the FAQ doesn't already cover the failure mode, add the question.
+
+### 6. Adversarial review
+
+Run `wize-review-adversarial` on the draft. Cut what survives only "trust me."
+
+### 7. Hand off
+
+The PR/FAQ is **not** the PRD. It's a strategic alignment doc. Marker `status: aligned`. Hill writes the PRD from this + the brief.
+
+## Output template
+
+```markdown
+---
+status: draft | aligned
+owner: Pepper Potts
+created: YYYY-MM-DD
+---
+
+# PR/FAQ — {{project_name}}
+
+## Press Release
+
+**Headline:** {{audience}} can now {{benefit}} with {{product_name}}.
+**Sub-headline:** {{the non-obvious twist}}.
+
+{{summary paragraph}}
+
+{{problem paragraph}}
+
+{{solution paragraph}}
+
+> "{{quote}}" — {{internal leader title}}
+
+How it works: {{three sentences}}
+
+> "{{customer quote}}" — {{persona}}
+
+Get started: {{where + first step}}
+
+## FAQ
+
+**Q1. Who exactly is this for?**
+…
+
+**Q2. What does this replace today?**
+…
+
+**Q3. Why now?**
+…
+
+(…through Q10 as needed)
+
+## Pre-mortem
+It's six months after launch and it failed. Why?
+1. …
+2. …
+3. …
+```
+
+## Anti-patterns Pepper rejects
+
+- PR longer than one page. Cut.
+- A press release with no user. ("Wize Foo unlocks synergies.") — say *who*.
+- A FAQ that dodges the hard question. The reader will ask it; better in your draft than in a launch review.
+- Pricing left vague when it's the load-bearing question.
+- Customer quote that sounds like marketing copy. Rewrite as a person speaking.
+
+## Hand-off
+
+> PR/FAQ is in `.wize/planning/prfaq.md`. Aligned with leadership. Hill, the PRD scope should anchor on FAQ Q5 (in/out). Mantis, the customer quote is your North Star for UX.