wize-dev-kit 0.1.5 → 0.2.0

package/CHANGELOG.md

@@ -5,6 +5,44 @@ Format inspired by [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [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 +177,8 @@ 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.0...HEAD
+[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.0",
   "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,162 @@
 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.
+```
+
+## 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.
+
+## 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.

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

@@ -4,57 +4,128 @@ name: Product Brief
 phase: 1-analysis
 owner: wize-agent-analyst   # Pepper Potts
 absorbs: "WDS Saga — Phase 1"
-status: stub
+status: ready
 ---
 
 # Product Brief
 
-**Goal.** Turn raw demand into a concise, decision-ready brief that the rest of the team can ship from.
+**Goal.** Convert raw demand into a one-page brief the team can ship from. The brief is the single source of truth at this point — every other artifact (PRD, UX, architecture) references back to it.
+
+Pepper drives. Peggy edits prose. Output lands in `.wize/planning/brief.md`.
 
 ## Inputs
 
-- Raw demand (chat or file)
-- Optional existing materials (deck, doc, ticket, recording)
-- `.wize/config/project.toml`
+- Raw demand (chat message, doc, ticket, screenshot, recording).
+- Optional existing materials (deck, doc, prior brief).
+- `.wize/config/project.toml`.
 
 ## Outputs
 
 - `.wize/planning/brief.md`
+- Optionally `.wize/knowledge/research/` if Pepper pulled external sources.
 
 ## Steps
 
-1. **Frame.** One paragraph: what is being asked, by whom, by when.
-2. **Audience.** Primary user (1), secondary users (≤2), stakeholders (≤3).
-3. **Vision.** One sentence describing the desired future state.
-4. **Success criteria.** 3–5 measurable outcomes (numbers, not adjectives).
-5. **Non-goals.** What this is *not*. Cut ambiguity early.
-6. **Constraints.** Deadlines, budgets, compliance, integrations.
-7. **Open questions.** Ranked, each with the person who can answer.
-8. **Hand off.** Mark `status: ready-for-prd`; ping Wizer to call Maria Hill.
+### 1. Frame in one paragraph
+
+What is being asked, by whom, and by when. If you can't write it in three sentences, you don't understand it yet. Ask one clarifying question, then write.
+
+### 2. Audience
+
+- **Primary user** (one, name them by role + JTBD).
+- **Secondary users** (≤ 2).
+- **Stakeholders** (≤ 3 — the people whose lives change if this ships).
+
+If the user list overflows, the brief is too broad. Force the cut.
+
+### 3. Vision
+
+One sentence describing the desired future state. Future tense. Concrete. No buzzwords. Test: can a new dev one month from now repeat it after a 30-second read?
+
+### 4. Success criteria
+
+3–5 measurable outcomes. Numbers, not adjectives.
+
+Examples:
+- ✓ "Median TTI on the checkout page ≤ 1.5s on a mid-range Android by Q3."
+- ✗ "Faster checkout."
+
+### 5. Non-goals
+
+What this is *not*. Cut ambiguity early. If a feature isn't ruled in or out here, it will be in the PRD review.
+
+### 6. Constraints
+
+Hard limits. Pick from:
+- Deadline (and what slipping it means).
+- Budget envelope (one-time and run-rate).
+- Compliance (GDPR, LGPD, SOC2, PCI, HIPAA, etc.).
+- Integrations the product must speak to.
+- Team / hiring envelope.
+
+### 7. Open questions
 
-## Brief template (target file)
+Each with the human who can answer it. Each marked priority `blocker` / `important` / `nice-to-know`. Blockers must be resolved before the PRD starts.
+
+### 8. Hand-off
+
+- Mark `status: ready-for-prd` in the brief.
+- Notify Wizer: "Brief ready, hand to Hill."
+- Move to `wize-trigger-map` next (Pepper continues).
+
+## Brief template
 
 ```markdown
+---
+status: ready-for-prd | draft
+owner: Pepper Potts
+created: YYYY-MM-DD
+---
+
 # Brief — {{project_name}}
 
 ## Vision
 …
 
 ## Audience
-- Primary: …
-- Secondary: …
-- Stakeholders: …
+- **Primary:** … (one role + their JTBD)
+- **Secondary:** …
+- **Stakeholders:** …
 
 ## Success criteria
 1. …
 2. …
+3. …
 
 ## Non-goals
 - …
 
 ## Constraints
-- …
+- **Deadline:** …
+- **Budget:** …
+- **Compliance:** …
+- **Integrations:** …
 
 ## Open questions
-- [ ] … (owner: …)
+- [ ] **(blocker)** … — *owner: NAME*
+- [ ] **(important)** … — *owner: NAME*
+- [ ] **(nice-to-know)** … — *owner: NAME*
 ```
+
+## Anti-patterns Pepper rejects
+
+- "Make the product better." → no audience, no outcome, not a brief.
+- Pasting a stakeholder's slack message verbatim. Rewrite in the brief voice.
+- Success criteria like "increase engagement". Reword: which event, how much, by when.
+- Hidden assumptions ("everyone has fast internet"). Surface them in *Constraints* or *Open questions*.
+- Open questions with no owner. If nobody owns it, the answer never comes.
+
+## When to skip
+
+This workflow is **not optional** for new products / new features. For tiny fixes (typo, copy, dependency bump), use `wize-quick-dev` instead — Pepper isn't called.
+
+## Hand-off
+
+When the brief is approved, Pepper notifies Wizer:
+
+> Brief is ready in `.wize/planning/brief.md`. No blockers open. Hill, your call on PRD.