wize-dev-kit 0.16.0 → 0.17.0

package/src/method-skills/3-solutioning/wize-create-epics-and-stories/workflow.md

@@ -1,24 +1,101 @@
 ---
+
 code: wize-create-epics-and-stories
+description: "Use quando a arquitetura estiver definida e precisar fatiar o escopo em epics e stories com acceptance criteria."
 name: Create Epics and Stories
 phase: 3-solutioning
 owner: wize-agent-architect   # Tony Stark
-status: stub
+status: ready
 ---
 
 # Create Epics and Stories
 
-**Goal.** Slice the PRD + architecture into epics (each ships value) and stories (each is one focused PR-sized unit).
+**Goal.** Slice the PRD + architecture into **epics** (each ships value end-to-end) and **stories** (each is one focused PR-sized unit Shuri can implement and Hawkeye can test).
+
+Tony drives. Output lands in `.wize/solutioning/epics/` and `.wize/solutioning/stories/`.
+
+> **No estimates.** Epics and stories never carry a time or effort estimate (hours, days, story points, S/M/L/XL) — at any step. AI development speed has made them noise that only burns time and tokens. The only sizing question is binary: **does a story fit one PR?** If not, slice it.
+
+When slicing raises decisions the PRD doesn't answer — priority order, sequencing, protected behaviors, what's out of a story — offer a short `wize-grill` pass with the user instead of guessing. Decisions land in the epic/story fields; unresolved ones become open questions with owners.
 
 ## Inputs
-- `.wize/planning/prd.md`
+
+Read central docs first, then expand by dependency — don't load unrelated files for padding:
+
+- `AGENTS.md` + `.wize/config/project.toml` — active profiles, languages, conventions.
+- `.wize/planning/prd.md` — the AC source (never reword ACs downstream).
 - `.wize/solutioning/architecture.md`
+- `.wize/planning/ux/ux-design/` (every story references one or more screens)
+- `.wize/knowledge/document-project/` — brownfield baseline, if present.
 
 ## Outputs
+
 - `.wize/solutioning/epics/{NN}-{slug}.md`
-- `.wize/solutioning/stories/{NN}-{slug}/{story-id}.md`
+- `.wize/solutioning/stories/{epic-NN}/{story-id}.md`
+
+## Epic shape
+
+An epic:
+- Ships **value** on its own (a user can do the thing after this epic, even if the next one improves it).
+- Lasts 1–3 sprints when in flight.
+- Has 3–10 stories.
+- Has a single trigger-map row as its anchor.
+
+Epic file:
+
+```markdown
+---
+epic_id: 01-onboarding
+status: ready
+owner: Tony Stark + Maria Hill
+linked_prd: E01
+trigger_map_row: 1
+priority: 1
+---
+
+# Epic 01: Sign-up + first invite
+
+## Outcome
+A first-time team admin signs up, lands in onboarding, and invites at least one teammate within 5 minutes (trigger-map row 1 + 2).
+
+## Stories
+- E01-S01: Sign-up empty + happy path (AC-01-1, AC-01-2)
+- E01-S02: Sign-up error states (AC-01-3, AC-01-4)
+- E01-S03: Onboarding step 1 — invite first teammate (AC-02-1, AC-02-2)
+- E01-S04: Email delivery + retry (AC-02-3)
+- E01-S05: Team list empty + with first member (AC-03-1, AC-03-2)
+
+## Dependencies
+- Design tokens by Mantis (S0 — already done)
+- Resend account configured (Tony, before S04)
+
+## Success
+All ACs of all stories PASS gate. Telemetry shows `teammate_invited` ≥ 80% of `signup_completed` users within 24h in the beta cohort.
+```
+
+## Story shape — INVEST
+
+Each story passes:
+- **I**ndependent — can be implemented without waiting for another in-flight story.
+- **N**egotiable — wording can move; intent stays.
+- **V**aluable — a real outcome to a real user (or a clear test path that proves a slice).
+- **S**mall — fits in one PR, tests included. This is the *only* sizing test; no time or point estimate (see **No estimates** above).
+- **T**estable — every AC is observable.
+
+If a story is XL, slice it before merging it to `stories/`.
 
-## Story template
+## Slicing patterns (Tony's defaults)
+
+| Pattern | When |
+|---|---|
+| Walking skeleton | When you need the full user path to exist (even with stubs) before going deep on any single screen. |
+| By user role | Admin vs member often slice naturally. |
+| By acceptance criterion | One AC = one PR when ACs are independent. |
+| By happy / error path | Ship happy path first; error states next story. |
+| By back-end / front-end | Avoid unless the back-end can ship usable without UI; otherwise it bundles. |
+| By feature flag | When a story partially ships, use a flag and write the flag retirement story now. |
+
+## Story file template
 
 ```markdown
 ---
@@ -26,23 +103,85 @@ story_id: E01-S03
 epic: 01-onboarding
 status: ready-for-dev
 priority: 2
-estimate: M
-linked_screen: ux-design/signin.md
+linked_screens: [onboarding-step-1, invite-modal]
+linked_acs: [AC-02-1, AC-02-2]
 ---
 
-# Story: Sign-in with email + magic link
+# Story: Onboarding step 1 — invite first teammate
 
 ## Context
-…
+Comes right after sign-up. The user lands here with no team yet. The screen is the moment-of-truth from S1: if the user invites a teammate here, the product earned its value moment.
+
+## Sources of truth (Shuri reads before coding)
+- `AGENTS.md` + `.wize/config/project.toml` · `.wize/knowledge/document-project/*`.
+- `prd.md` (AC source) · `architecture.md` · `ux-design/onboarding-step-1.md` · parent epic `01-onboarding.md`.
+- The TEA test contract for this story · related code + tests already on this path.
 
 ## Acceptance criteria
-- AC-1 …
-- AC-2 …
+- **AC-02-1:** Given a new admin on `/onboarding`, When they enter a valid email and click "Send invite", Then a `teammate_invited` event fires and the screen advances to "Invite sent" within 1s.
+- **AC-02-2:** Given an invalid email, When the user blurs the field, Then error text appears (200ms) identifying which rule failed.
 
-## Out of scope
-- …
+## Restrictions
+- **Out of scope:** bulk invite → E01-S07; custom invite message → E02-S03.
+- **Protected behaviors:** existing sign-up + session flow must not change.
+- **Compatibility:** `(team_id, email)` idempotency key — don't break existing invite rows.
+- **Security:** validate email at the server boundary; auth context required on `inviteTeammate`.
 
 ## Notes for Shuri (Dev)
-- Touch points: …
-- Tests required: …
+- Touch points: `app/(onboarding)/invite/page.tsx`, new server action `inviteTeammate`, `lib/email/send-invite.ts`.
+- Reuse `Button`, `Input`, `Banner` from design system.
+- Add `data-testid="invite-form"`, `"invite-email"`, `"invite-cta"` (Hawkeye depends on these).
+
+## Validation contract
+- **AC → test:** AC-02-1 → E2E `invite happy path` + unit `validateInviteEmail`; AC-02-2 → unit `invalid email` + component error-state.
+- **Required checks:** the unit/integration/E2E split Hawkeye declares below, plus lint, format, type-check, build. Authz asserted on the server action.
+- **States:** loading, empty, error rendered and asserted.
+
+## Notes for Hawkeye (TEA)
+- Tests required: 2 unit (validation), 1 integration (server action calls mailer with right args), 1 E2E (happy path on Playwright).
+- Mocks: outbound email via MSW; auth context via fixture.
+- NFR sample: response p95 ≤ 800ms locally (NFR 1.A allows up to 1s end-to-end).
+
+## Done means
+Every AC has a passing test (mapped above), gate PASS/CONCERNS, story `status: ready-for-review`, knowledge axes updated if touched.
 ```
+
+## Steps
+
+### 1. From PRD backbone → epics
+
+Each backbone story in the PRD becomes one epic. Name epics by outcome, not by feature: "Sign-up + first invite," not "Auth screens."
+
+### 2. From scenarios → stories
+
+For each epic, walk the linked scenarios in `ux-scenarios.md`. Slice into stories by the patterns above. Aim for 3–7 stories per epic.
+
+### 3. ACs map exactly
+
+Every story declares the AC IDs it advances (from PRD). The union of stories per epic equals the AC set of that epic — no gaps, no overlap.
+
+### 3.5 Fill the contract fields
+
+Each story carries its own **sources of truth**, **restrictions** (out-of-scope + protected behaviors + compatibility + security), and a **validation contract** (AC → test map + required checks). These aren't optional prose — they are what makes AC → code → test → gate traceable. A story missing them is not ready for dev.
+
+### 4. Slice check (no estimates)
+
+Don't estimate stories — size them by one question: does each fit a single PR? Anything that doesn't gets sliced before it lands in `stories/`. If most stories feel too big to slice cleanly, the slicing pattern is too coarse; revisit it.
+
+### 5. Hand off
+
+- Mark all epics + stories `status: ready-for-dev`.
+- Trigger `wize-check-implementation-readiness` (Tony, with Hawkeye on risk profile).
+- After ready, Hill runs sprint planning.
+
+## Anti-patterns Tony rejects
+
+- **Stories without AC links.** No traceability → no gate later.
+- **Stories that "ship a back-end."** Bundle with the front-end consumer unless a different team uses it independently.
+- **XL stories.** Slice further or split into two PRs.
+- **"Epic" that is one story.** Then it's a story.
+- **Stories that share `testid` namespace.** They'll collide.
+
+## Hand-off
+
+> Epics and stories at `.wize/solutioning/`. 5 epics, 28 stories. All have ACs from the PRD. Run `wize-check-implementation-readiness`; Hawkeye, `tea-risk.md` next.

package/src/method-skills/3-solutioning/wize-design-system/workflow.md

@@ -1,36 +1,198 @@
 ---
+
 code: wize-design-system
+description: "Use quando o UX design estiver avançando e precisar estabelecer a baseline do design system (tokens, componentes, grids)."
 name: Design System
 phase: 3-solutioning
 owner: wize-agent-ux-designer   # Mantis (WDS Freya — Phase 7)
 absorbs: "WDS Freya — Phase 7 (Design System)"
-status: stub
+status: ready
 ---
 
 # Design System
 
-**Goal.** Establish design tokens and a baseline component library that Shuri implements consistently across the product.
+**Goal.** Establish design tokens and a baseline component library Shuri implements consistently. Mantis defines what; Tony picks the runtime; Shuri builds. Hawkeye verifies a11y and consistency at gate.
+
+Mantis drives. Output lands in `.wize/solutioning/design-system/`.
 
 ## Inputs
-- `.wize/planning/ux/ux-design/`
+
+- `.wize/planning/ux/ux-design/` (every component the specs use)
+- `.wize/planning/nfr-principles.md` (a11y and perf budgets)
+- Overlay playbooks (active):
+  - `web-overlay/playbooks/wcag-aa.md`, `responsive-breakpoints.md`, `semantic-html.md`
+  - `app-overlay/playbooks/apple-hig.md`, `material-design-3.md`, `touch-targets-and-gestures.md`
 
 ## Outputs
-- `.wize/solutioning/design-system/tokens.json`
-- `.wize/solutioning/design-system/components/{Component}.md`
-- `.wize/solutioning/design-system/README.md`
-
-## Tokens covered
-- color (semantic + raw scale)
-- typography (family, sizes, weights, line-heights)
-- spacing scale
-- radii
-- motion (durations, easings)
-- shadows / elevation
-- z-index layers
-
-## Component baseline
-Buttons, inputs, selects, modals, dialogs, tabs, cards, notifications. Enough for the first epic; expand as stories require.
-
-## Overlays
-- **Web overlay** active → responsive token variants, REM-based typography.
-- **App overlay** active → platform-token sets (iOS / Android), touch-friendly spacing scale.
+
+- `.wize/solutioning/design-system/tokens.json` — single source of truth.
+- `.wize/solutioning/design-system/components/{Component}.md` — one per component.
+- `.wize/solutioning/design-system/README.md` — index + theming guide.
+
+## Tokens (the only acceptable way to ship styles)
+
+Mantis defines the tokens; Tony picks the runtime (Tailwind, CSS modules, Vanilla Extract, Compose theme, SwiftUI tokens). The names below are framework-agnostic.
+
+### Color (semantic + raw scale)
+
+| Semantic | Light | Dark | Contrast pair |
+|---|---|---|---|
+| `surface.base` | #FFFFFF | #0B0F14 | text.primary |
+| `surface.raised` | #F5F7FA | #121821 | text.primary |
+| `text.primary` | #0B0F14 | #E5E7EB | surface.base |
+| `text.secondary` | #4B5563 | #9CA3AF | surface.base |
+| `accent.brand` | #6F49FF | #8B6FFF | text.onAccent |
+| `text.onAccent` | #FFFFFF | #FFFFFF | accent.brand |
+| `success` | #058E5C | #34D399 | text.onSuccess |
+| `warning` | #C9621E | #F59E0B | text.onWarning |
+| `error` | #B42318 | #FCA5A5 | text.onError |
+| `border.default` | #E5E7EB | #2A313A | — |
+| `border.focus` | accent.brand | accent.brand | — |
+
+Validate every pair against WCAG AA (≥ 4.5:1 normal, ≥ 3:1 large). Run before you commit.
+
+### Typography
+
+| Token | Family | Size | Weight | Line | Letter |
+|---|---|---|---|---|---|
+| `display.l` | Inter Display | clamp(2.5rem, 5vw, 3.5rem) | 700 | 1.05 | -0.02em |
+| `display.m` | Inter Display | clamp(2rem, 4vw, 2.5rem) | 700 | 1.1 | -0.01em |
+| `heading.l` | Inter | clamp(1.5rem, 3vw, 2rem) | 600 | 1.2 | -0.01em |
+| `heading.m` | Inter | 1.25rem | 600 | 1.3 | 0 |
+| `heading.s` | Inter | 1rem | 600 | 1.4 | 0 |
+| `body.l` | Inter | 1.125rem | 400 | 1.6 | 0 |
+| `body.m` | Inter | 1rem | 400 | 1.55 | 0 |
+| `body.s` | Inter | 0.875rem | 400 | 1.5 | 0 |
+| `caption` | Inter | 0.75rem | 500 | 1.4 | 0.01em |
+
+Use rem for body; clamp() for fluid headings (see `responsive-breakpoints.md`).
+
+### Spacing scale (4px base, geometric)
+
+`0` 0 · `1` 4 · `2` 8 · `3` 12 · `4` 16 · `5` 24 · `6` 32 · `7` 48 · `8` 64 · `9` 96 · `10` 128
+
+### Radius
+
+`none` 0 · `sm` 4 · `md` 8 · `lg` 12 · `xl` 16 · `pill` 999.
+
+### Elevation
+
+| Token | Light | Dark (tonal) |
+|---|---|---|
+| `e1` | 0 1px 2px rgba(0,0,0,.06) | surface.raised |
+| `e2` | 0 2px 4px rgba(0,0,0,.08) | surface.raised + 4% |
+| `e3` | 0 4px 12px rgba(0,0,0,.10) | surface.raised + 8% |
+| `e4` | 0 12px 24px rgba(0,0,0,.12) | surface.raised + 12% |
+
+App overlay: prefer tonal elevation per Material 3.
+
+### Motion
+
+| Token | Duration | Easing |
+|---|---|---|
+| `motion.micro` | 100ms | `ease-out` |
+| `motion.transition` | 200ms | `cubic-bezier(0.2, 0, 0, 1)` |
+| `motion.page` | 300ms | `cubic-bezier(0.4, 0, 0.2, 1)` |
+| `motion.spring.subtle` | (spring) | mass 1, stiff 350, damp 30 |
+
+Honor `prefers-reduced-motion`. Replace transforms with fades.
+
+## Components — the baseline set
+
+Each component has its own `.md` doc with: purpose, anatomy, states (default/hover/focus/active/disabled/loading), variants, accessibility, do/don't, snippets.
+
+| Component | Mandatory states | Notes |
+|---|---|---|
+| Button | default, hover, focus, active, disabled, loading | variants: primary, secondary, tertiary, destructive, ghost |
+| Input | default, focus, error, disabled, success | always has visible label |
+| Select | default, open, focus, disabled | native first; custom only when needed |
+| Textarea | as Input | auto-grow optional |
+| Checkbox | unchecked, checked, indeterminate, focus, disabled | native input + custom skin |
+| Radio | unchecked, checked, focus, disabled | grouped under fieldset |
+| Toggle/Switch | off, on, focus, disabled | `role="switch" aria-checked` |
+| Card | default, raised, interactive | elevation tokens |
+| Modal / Dialog | open, closing | focus trap + ESC + restore |
+| Sheet (app) | half / full | drag handle |
+| Tabs | active, inactive, focus | keyboard arrows |
+| Accordion | collapsed, expanded, focus | `<details>` when possible |
+| Toast / Snackbar | info, success, warning, error | `role="status"` or `alert` |
+| Tooltip | hidden, visible | `aria-describedby`, touch alt |
+| Menu | closed, open, focus | keyboard navigation |
+| Dropdown | (synonym of Menu / Combobox) | follow ARIA combobox |
+| Badge | default, success, warning, error | contrast ≥ 4.5:1 |
+| Avatar | image, initials, placeholder | 1:1 ratio, alt text |
+| Skeleton | static, shimmer | respect reduced-motion |
+| Empty state | default | message + primary action |
+| Loading | spinner / progress | accessible announcement |
+
+## Component template (one per component)
+
+```markdown
+---
+component: Button
+status: ready
+owner: Mantis
+linked_screens: [signup-empty, team-list-empty, …]
+---
+
+# Button
+
+## Purpose
+Trigger an action. Never use for navigation between routes.
+
+## Anatomy
+[icon?] [label] [icon?] · padding by size · radius `md`
+
+## Variants
+- `primary` — main action; one per screen region.
+- `secondary` — alternative action.
+- `tertiary` — text-only.
+- `destructive` — irreversible action.
+- `ghost` — minimal chrome, e.g., toolbar.
+
+## Sizes
+- `sm` (height 32, label `body.s`)
+- `md` (height 40, label `body.m`)
+- `lg` (height 48, label `body.m`)
+
+## States
+
+| State | Treatment |
+|---|---|
+| default | accent.brand bg, text.onAccent label |
+| hover | accent.brand 10% darker |
+| focus | 2px outline `border.focus`, offset 2px |
+| active | accent.brand 15% darker |
+| disabled | opacity 0.4, `aria-disabled="true"`, cursor not-allowed |
+| loading | spinner replaces icon; label unchanged; click ignored |
+
+## Accessibility
+- Native `<button>`.
+- `aria-label` when icon-only.
+- Visible focus ring always (don't override).
+- 24×24 px hit area minimum (web), 44pt (iOS), 48dp (Android).
+- Min contrast on label ≥ 4.5:1.
+
+## Don't
+- Use `<div onclick>`.
+- Remove the focus ring without replacement.
+- Use destructive for "Continue".
+- Stack > 2 primary buttons on a screen.
+```
+
+## Theming + overlays
+
+- **Web overlay:** tokens emit as CSS custom properties; dark mode toggled via `[data-theme="dark"]` on `<html>`.
+- **App overlay (iOS):** tokens as SwiftUI environment values; dark mode auto.
+- **App overlay (Android):** tokens as Compose `MaterialTheme` extensions; honor `dynamicColorScheme` when allowed.
+
+## Anti-patterns Mantis rejects
+
+- **Hex in components.** Everything via tokens.
+- **One-off components shipped without doc.** Add to the system or refuse to merge.
+- **Component matrix without states.** A button without disabled+loading isn't a button.
+- **Component that fails axe.** Failed at definition; don't ship.
+
+## Hand-off
+
+> Tokens + 20 components at `.wize/solutioning/design-system/`. Tony picks the runtime (Tailwind / Vanilla Extract / SwiftUI tokens / Compose theme); Shuri implements. Hawkeye references this in `tea-design.md`: a11y + visual regression hooks point at these tokens.

package/src/method-skills/3-solutioning/wize-nfr-principles/workflow.md

@@ -1,33 +1,161 @@
 ---
+
 code: wize-nfr-principles
+description: "Use quando o PRD estiver validado e precisar definir os princípios de NFR (perf, segurança, confiabilidade, acessibilidade, custo) que guiarão a arquitetura."
 name: NFR Principles
-phase: 2-to-3-boundary
+phase: 3-solutioning
 owner: wize-agent-solution-strategist   # Nick Fury
-status: stub
+status: ready
 ---
 
 # NFR Principles
 
-**Goal.** Define non-functional non-negotiables Tony must design against and Hawkeye must verify.
+**Goal.** Define non-functional non-negotiables Tony must design against and Hawkeye must verify. Hill defers to this when sizing scope. Mantis respects the a11y/perf bars in UX specs. Shuri implements with these targets in hand.
+
+Fury drives. Output lands in `.wize/planning/nfr-principles.md`.
+
+## Inputs
+
+- `.wize/planning/prd.md`
+- `.wize/planning/tech-vision.md`
+- `.wize/planning/brief.md` (compliance constraints, audience implications)
+- Overlay perf playbooks if active:
+  - `web-overlay/playbooks/web-perf-budgets.md`
+  - `app-overlay/playbooks/mobile-perf-budgets.md`
+  - `web-overlay/playbooks/wcag-aa.md`
+  - `app-overlay/playbooks/apple-hig.md`, `material-design-3.md`
+
+## Outputs
 
-## Output
 - `.wize/planning/nfr-principles.md`
 
-## Categories
-- **Performance** — targets (LCP, p95, throughput).
-- **Security** — auth model, data classes, threat surface posture.
-- **Reliability** — uptime, error budget, retry/idempotency policy.
-- **Maintainability** — coding standards, tech-debt allowance.
-- **Accessibility** — WCAG / platform guidelines minimums.
-- **Cost** — monthly envelope and degradation strategy.
+## Categories (always cover these six)
+
+For each, write **non-negotiable** + **stretch** + **deferred** (with trigger). Use the playbooks as starting points; **tighten** if PRD demands, never loosen below playbook recommendations.
+
+### 1. Performance
+
+| Tier | Targets |
+|---|---|
+| Non-negotiable | LCP ≤ 2.5s mobile, INP ≤ 200ms, CLS ≤ 0.1 (web) — cold start ≤ 1.5s mid-range (app) |
+| Stretch | LCP ≤ 1.8s, INP ≤ 100ms |
+| Deferred | Server-side LCP for edge regions — revisit when audience > 30% non-NA |
+
+### 2. Security
+
+| Tier | Items |
+|---|---|
+| Non-negotiable | OWASP Top 10 covered; auth via {{vendor}}; tokens never logged; secrets via {{provider}}; RLS on every table with user_id |
+| Stretch | SOC2 type-I controls in place by {{date}} |
+| Deferred | SOC2 type-II — revisit at $1M ARR |
+
+### 3. Reliability
+
+| Tier | Targets |
+|---|---|
+| Non-negotiable | 99.9% uptime in primary region; error budget 0.1%/month; retries idempotent with deduplication key |
+| Stretch | 99.95% uptime |
+| Deferred | Multi-region active/active — revisit per tech-vision deferred |
+
+### 4. Maintainability
+
+| Tier | Items |
+|---|---|
+| Non-negotiable | Lint + format on commit; > 80% test coverage on logic modules; ADRs for every architectural decision; deps audited monthly |
+| Stretch | < 5% files over 300 LOC; cyclomatic complexity < 15 per function |
+| Deferred | Auto-doc generation — revisit when API consumers > 3 |
+
+### 5. Accessibility
+
+| Tier | Items |
+|---|---|
+| Non-negotiable | WCAG 2.2 AA on every shipped page; keyboard-complete; axe in CI |
+| Stretch | AAA on critical flows (signup, billing) |
+| Deferred | Full screen-reader manual audit every release — revisit at next compliance review |
+
+### 6. Cost
+
+| Tier | Targets |
+|---|---|
+| Non-negotiable | Total infra ≤ ${{X}}/month under {{load}}; degradation strategy documented for 10× spike |
+| Stretch | Cost-per-active-user ≤ ${{Y}} |
+| Deferred | Per-feature cost attribution — revisit when finance asks |
+
+## Steps
+
+### 1. Read the playbooks first
+
+If web/app overlays are active, the perf and a11y playbooks already hold real targets calibrated to mid-range device + 3G fast. Use them as starting point.
+
+### 2. Tighten by audience
+
+Mid-range mobile is the playbook baseline. If your PRD audience is *more* constrained (emerging markets, kiosk hardware, healthcare older devices), tighten. Don't loosen.
+
+### 3. Map every non-negotiable to a verifier
+
+Every non-negotiable must answer the question: *Who and how do we verify this on every release?*
+
+- LCP → `web-perf-budgets.md` lighthouse-ci config.
+- WCAG → axe in CI + Hawkeye review.
+- Uptime → SLO defined in `.wize/solutioning/observability.md` (Tony).
+- Error budget → tracked in {{tool}}.
+
+A non-negotiable with no verifier is a wish.
+
+### 4. Tell the story (one paragraph)
+
+Open the doc with a paragraph: *why these numbers, and what trade-offs they imply.* Future readers re-litigate non-negotiables every six months; the story saves that hour.
+
+### 5. Hand off
+
+Mark `status: aligned`. Tony reads before architecture; Hawkeye reads before risk profile.
+
+## Output template
 
-## Template
 ```markdown
-# NFR Principles
+---
+status: aligned
+owner: Nick Fury
+created: YYYY-MM-DD
+---
+
+# NFR Principles — {{project_name}}
+
+## Why these numbers
+
+{{One paragraph: target audience, country mix, device class, compliance frame. Why we picked these targets specifically.}}
+
+## Performance
+| Tier | Targets | Verifier |
+|---|---|---|
+| Non-negotiable | LCP ≤ 2.5s mobile (CWV), INP ≤ 200ms, CLS ≤ 0.1 | lighthouse-ci + web-vitals beacon |
+| Stretch | LCP ≤ 1.8s | same |
+| Deferred | Multi-region LCP — trigger: EU DAU > 5k | — |
 
-| Category | Non-negotiable | Stretch | Deferred |
-|---|---|---|---|
-| Performance | … | … | … |
-| Security | … | … | … |
+## Security
+…
+
+## Reliability
+…
+
+## Maintainability
+…
+
+## Accessibility
+…
+
+## Cost
 …
 ```
+
+## Anti-patterns Fury rejects
+
+- **Targets without numbers.** "Fast." Wrong. "p95 server response ≤ 200ms."
+- **Stretch targets that are actually goals.** If you must hit it, it's non-negotiable.
+- **No verifier.** Every non-negotiable answers *who verifies, with what tool, on what cadence*.
+- **Loosening below the playbook.** Tightening is fine. Loosening is a smell — escalate.
+- **Cost left blank.** Cost is always an NFR.
+
+## Hand-off
+
+> NFRs at `.wize/planning/nfr-principles.md`. Tony, architecture must respect items 1.A and 4.A from day one (perf and ADR discipline). Hawkeye, your gate policy can stay advisory but NFR gate per epic is mandatory. Hill, scope must keep the budget headroom for item 6.A.