wize-dev-kit 0.1.4 → 0.2.0

package/src/method-skills/3-solutioning/wize-tech-vision/workflow.md

@@ -3,41 +3,147 @@ code: wize-tech-vision
 name: Tech Vision
 phase: 2-to-3-boundary
 owner: wize-agent-solution-strategist   # Nick Fury
-status: stub
+status: ready
 ---
 
 # Tech Vision
 
-**Goal.** State the technical north star in one page. Stack family, language, runtime envelope, build/buy/borrow calls. Not libraries — *shape*.
+**Goal.** State the technical north star in one page. Stack family, runtime envelope, build/buy/borrow calls, non-negotiables. Fury sets the **shape**, not the libraries — Tony fills in inside the frame.
+
+Output lands in `.wize/planning/tech-vision.md`. Tony reads this before drawing architecture. Hill references it when scoping. Hawkeye uses it when picking gate granularity.
+
+## Inputs
+
+- `.wize/planning/prd.md` (validated)
+- `.wize/planning/ux/ux-design/` (so the runtime envelope respects the UX)
+- `.wize/knowledge/document-project/` (brownfield only)
+- Stack catalogs (per active overlay):
+  - `src/web-overlay/stack-catalog.md`
+  - `src/app-overlay/stack-catalog.md`
+
+## Outputs
 
-## Output
 - `.wize/planning/tech-vision.md`
 
-## Template
+## Steps
+
+### 1. Pick the stack family
+
+By order of constraint:
+
+1. **Audience reach.** Public + SEO-critical? Authenticated app? Native mobile required?
+2. **Latency budget.** Sub-1s LCP on 3G or richer-but-slower OK?
+3. **Team familiarity.** Favor what the team has shipped before unless the project truly demands new.
+4. **Backend coupling.** Separate API / fullstack monolith / BaaS?
+5. **Deploy target.** Edge / container / self-managed.
+
+Don't pick libraries here. Pick the *shape*: "Next.js-class SSR fullstack on edge" or "React Native + Expo with a Supabase backend" or "Compose Multiplatform with Kotlin services."
+
+### 2. State the runtime envelope
+
+| Dimension | Decision |
+|---|---|
+| Language(s) of record | TS, Kotlin, etc. |
+| Runtime(s) | Browser / Node / Edge / Native iOS / Native Android / JVM |
+| Persistence | Postgres / SQLite / KV / cloud-native |
+| Deploy target | Vercel / Cloudflare / Fly / EKS / EAS / etc. |
+| Edge vs origin | Edge-first / origin-first |
+
+### 3. Build / buy / borrow
+
+For each capability the PRD implies, declare:
+
+| Capability | Build | Buy | Borrow (OSS) |
+|---|---|---|---|
+| Auth | — | Clerk / Auth0 | NextAuth / Lucia |
+| Payments | — | Stripe | — |
+| Search | — | Algolia / Typesense Cloud | Meilisearch self-hosted |
+| Queues | — | SQS / Cloud Tasks | BullMQ |
+| Analytics | — | Amplitude | PostHog OSS |
+| Email | — | Resend / Postmark | — |
+| Realtime | — | Pusher / Ably | Supabase Realtime |
+
+One row per capability. Empty cells are explicit choices.
+
+### 4. Non-negotiables
+
+The 2–5 things the team will not compromise on.
+
+Examples:
+- *"All endpoint responses ≤ 200ms p95 from the user's region."*
+- *"Single source of truth for user data — no shadow stores."*
+- *"PII never leaves the EU."*
+- *"On-call burden ≤ 0.5 pages per engineer per week."*
+
+These outrank PRD goals. If they conflict, Fury escalates.
+
+### 5. Deferred (with triggers)
+
+What we won't decide yet, and what would trigger the decision. Don't list "could be revisited"; list the *signal* that forces the decision.
+
+- *"Multi-region storage: revisit when EU+US daily active users > 5k."*
+- *"WebSockets vs SSE: revisit when realtime updates < 500ms become a PRD goal."*
+
+### 6. Hand off
+
+Mark `status: aligned`. Tony reads it as the frame; he can argue specific decisions but not redraw the family without escalating.
+
+## Output template
+
 ```markdown
-# Tech Vision
+---
+status: aligned
+owner: Nick Fury
+created: YYYY-MM-DD
+---
 
-## Stack family
-- {Web|Mobile|Hybrid}
+# Tech Vision — {{project_name}}
 
-## Language(s) of record
-- …
+## Stack family
+Next.js-class SSR fullstack on edge, with Supabase Postgres as the system of record.
 
 ## Runtime envelope
-- {Browser|Node|Edge|Native iOS|Native Android}
+| Dimension | Decision |
+|---|---|
+| Language | TypeScript end-to-end |
+| Runtime | Edge (Vercel Edge Functions) + Node (server actions) |
+| Persistence | Supabase Postgres (RLS) + PgBouncer |
+| Deploy target | Vercel for app; Supabase managed for data |
+| Edge vs origin | Edge-first for reads; origin for writes |
 
-## Build vs buy vs borrow
-| Capability | Decision | Why |
-|---|---|---|
-| Auth | … | … |
-| Payments | … | … |
-| Search | … | … |
-| Queues | … | … |
-| Analytics | … | … |
+## Build / buy / borrow
+| Capability | Decision |
+|---|---|
+| Auth | Buy — Supabase Auth |
+| Payments | Buy — Stripe |
+| Search | Buy — Algolia (1st year), revisit |
+| Queues | Borrow — pg_cron + outbox pattern |
+| Analytics | Borrow — PostHog OSS |
+| Email | Buy — Resend |
 
 ## Non-negotiables
-- …
+1. PII (incl. emails) stored in the user's region only.
+2. p95 server response ≤ 200ms in the user's region.
+3. Single auth identity per human (no shadow accounts).
+4. On-call rotation never exceeds 0.5 pages/eng/week.
+
+## Deferred
+- Multi-region writes: revisit when EU active users > 2k.
+- Native mobile clients: revisit when web TTI > 4s on > 20% of sessions or PRD demands offline.
 
-## Deferred (revisit when)
-- … (trigger: …)
+## Constraints that drove this
+- Brief constraint #2 (LGPD/GDPR) ruled out global-replica DBs.
+- PRD goal G1 ruled in edge-first reads.
+- Hiring tail in TypeScript ruled out Compose Multiplatform.
 ```
+
+## Anti-patterns Fury rejects
+
+- **Picking a library here.** That's Tony. Pick the *family*.
+- **Non-negotiables that are aspirations.** "Always 100% uptime." Wrong. "Error budget ≤ 0.1% in EU region."
+- **Deferred items with no trigger.** That's procrastination.
+- **A non-negotiable that contradicts a PRD constraint silently.** Surface it, escalate it, decide it.
+
+## Hand-off
+
+> Tech vision at `.wize/planning/tech-vision.md`. Tony, build the architecture inside this frame. Hill, scope the PRD against the non-negotiables (item 1 means the global launch is back on the table only after EU baseline holds). Hawkeye, pick gate granularity assuming `policy = advisory`.

package/src/method-skills/4-implementation/wize-code-review/workflow.md

@@ -3,22 +3,117 @@ code: wize-code-review
 name: Code Review
 phase: 4-implementation
 owner: wize-agent-dev   # Shuri (peer Shuri — done at PR open time)
-status: stub
+status: ready
 ---
 
 # Code Review
 
-**Goal.** Self/peer review focused on code health. Separate from Hawkeye's story review.
+**Goal.** Audit **code health** on the PR. Separate from Hawkeye's `tea-review` (which audits AC fulfillment). Both run on every story PR; they're complementary.
+
+Shuri reviews peer PRs. Tony reviews when architecture is at stake.
+
+## When to run
+
+Every PR that ships code. Quick-dev PRs get a lighter review (skip code-architecture checks unless they touched architecture).
+
+## Inputs
+
+- The PR (diff + tests).
+- Story file (for context — what the PR is supposed to accomplish).
+- Linked design system (when components change).
+
+## Output
+
+- Inline comments on the PR.
+- Final review verdict: `approve` / `request-changes` / `comment`.
 
 ## What this checks
-- Naming, structure, dead code
-- Test coverage and quality (not just presence)
-- Security obvious-misses
-- Performance obvious-misses
-- Architectural drift (call Tony if found)
+
+### Naming + structure
+- Are types, functions, variables named for **what they are**, not **how they're used**?
+- Are files in the right folder per the architecture?
+- Are exports minimal? Module boundaries respected?
+- Are there new abstractions justified by the story or premature?
+
+### Tests
+- Do tests cover the changed behavior (not just coverage %)?
+- Are they fast and isolated?
+- Are mocks at the boundary, not inside the unit?
+- Any `test.skip` / `.only` left in?
+
+### Security (obvious-misses)
+- Input validation at boundaries.
+- Tokens / secrets / PII never logged.
+- SQL parameterized, not concatenated.
+- New deps audited; no known CVEs introduced.
+- Auth context checked on every server entry point.
+
+### Performance (obvious-misses)
+- No N+1 queries.
+- No `await` in tight loops without batching.
+- No new sync I/O on hot paths.
+- Bundle delta acceptable (size of new front-end imports).
+
+### Architectural drift
+- Story didn't quietly introduce a new layer / new pattern.
+- If it did, an ADR was opened or a comment justifies it.
+- Components reused from design system; new components added to system if reusable.
+
+### Style + convention
+- Follows lint / format / type rules.
+- Comments explain *why*, not *what*.
+- Dead code removed.
+- TODOs have an owner + a ticket.
 
 ## What this does NOT check
-- AC fulfillment — that's Hawkeye's `trace` + `review` + `gate`.
 
-## Outputs
-- Inline comments / suggestions on the diff.
+- Whether ACs are met — that's Hawkeye's `tea-review`.
+- Whether the design is right — that's reviewed in pull-request walk-through, ADR review, or party-mode.
+
+Don't conflate. Two reviewers, two scopes.
+
+## Comment style
+
+Use these prefixes:
+
+| Prefix | Meaning |
+|---|---|
+| `nit:` | Cosmetic; non-blocking |
+| `q:` | Question; might be a misunderstanding |
+| `praise:` | Real call-outs; teams need them |
+| `suggestion:` | Idea, the author decides |
+| `blocking:` | Must change before merge |
+| `out-of-scope:` | Real issue, separate story |
+
+Never `LGTM` without scanning. Never `LGTM` with `blocking:` open.
+
+## Verdict
+
+- **approve** — all blockings resolved.
+- **request-changes** — at least one `blocking:`.
+- **comment** — reviewed, no opinion (rare; used for early-draft PRs).
+
+## PR-open checklist (Shuri's self-review)
+
+Before opening, Shuri runs through:
+
+- [ ] CI green locally.
+- [ ] Lint + format clean.
+- [ ] Type-check clean.
+- [ ] No `console.log` / `dbg!` / debug printf.
+- [ ] No `test.skip` / `.only`.
+- [ ] Reading the diff right now, can I explain every line?
+- [ ] Self-walk: open the changed screen / call the changed endpoint.
+- [ ] Story status flipped to `ready-for-review`.
+
+## Anti-patterns Shuri rejects in herself
+
+- Approving without reading.
+- Approving on the basis of green CI alone.
+- "Big PR; will trust" — refuse and ask for slicing.
+- Inline suggestions for full rewrites — open a follow-up instead.
+- Demanding stylistic preferences not in the lint config.
+
+## Hand-off
+
+> Reviewed PR #418 (E02-S02). 2 nits, 1 blocking on auth-context check missing in one new route. Shuri to fix; re-review needed; then Hawkeye runs `tea-review`.

package/src/method-skills/4-implementation/wize-create-story/workflow.md

@@ -3,25 +3,146 @@ code: wize-create-story
 name: Create Story
 phase: 4-implementation
 owner: wize-agent-architect   # Tony writes; Shuri may refine
-status: stub
+status: ready
 ---
 
 # Create Story
 
-**Goal.** Author one Pull-Request-sized story unit with crisp acceptance criteria.
+**Goal.** Author one Pull-Request-sized story with crisp acceptance criteria, named touch-points, and a contract for Hawkeye's `tea-design.md`. This is the single most-edited artifact in the lifecycle; make it useful.
+
+Tony drives. Shuri reads and proposes refinements before pulling the story.
+
+## When to use
+
+- New story splits from an epic (most common — done in `wize-create-epics-and-stories`).
+- A story that comes in mid-sprint and needs a quick scaffold.
+- A `tea-gate` waived rationale created a follow-up story.
 
 ## Inputs
+
 - `.wize/solutioning/architecture.md`
 - `.wize/solutioning/epics/{epic}.md`
-- (optional) UX screen reference
+- `.wize/planning/prd.md` (the AC list)
+- (optional) `.wize/planning/ux/ux-design/{screen}.md`
+
+## Output
 
-## Outputs
 - `.wize/solutioning/stories/{epic}/{story-id}.md`
 
-## Story template
-(See `wize-create-epics-and-stories` for the canonical template.)
+## Steps
+
+### 1. Name it by outcome
+
+Verb-led, user-visible. *"Onboarding: invite first teammate"* not *"Build invite form."*
+
+### 2. Frontmatter
+
+```yaml
+---
+story_id: E01-S03
+epic: 01-onboarding
+status: ready-for-dev
+priority: 2          # 1=now, 2=next, 3=later
+estimate: M          # S | M | L  (XL → slice further before merging here)
+linked_screens: [onboarding-step-1, invite-modal]
+linked_acs: [AC-02-1, AC-02-2]
+---
+```
+
+### 3. Context (3–5 lines)
+
+What place this story occupies in the user journey, why it matters here, what it depends on.
+
+### 4. ACs (lifted from PRD; not reworded)
+
+Don't reword PRD ACs in a story — copy them verbatim. If they're not crisp enough, fix in the PRD first.
+
+### 5. Out of scope
+
+Explicit. Other ACs the user might think this story touches, with a one-line reason it's not here.
+
+### 6. Notes for Shuri
+
+- Touch points: files Shuri will likely edit.
+- Reuse: components from `design-system` already named.
+- `testid` map: names Hawkeye expects.
+- Edge cases worth flagging (only ones not derivable from ACs).
+
+### 7. Notes for Hawkeye
+
+A one-paragraph hint: suggested split, fixtures, mocks, environment. Hawkeye writes the real `tea-design.md` but reads this hint.
+
+## INVEST rules
+
+Every story passes:
+
+- **I**ndependent.
+- **N**egotiable.
+- **V**aluable.
+- **E**stimable (Tony sizes).
+- **S**mall (≤ 1 PR).
+- **T**estable.
+
+If any letter fails, fix before queueing.
+
+## Estimation rough guide
+
+- **S** ≤ 4h.
+- **M** 4h–1d.
+- **L** 1–2d.
+- **XL** > 2d → split.
+
+These are intervals, not commitments. Hill plans capacity against M-median.
+
+## Full story template
+
+```markdown
+---
+story_id: E01-S03
+epic: 01-onboarding
+status: ready-for-dev
+priority: 2
+estimate: M
+linked_screens: [onboarding-step-1, invite-modal]
+linked_acs: [AC-02-1, AC-02-2]
+---
+
+# Story: Onboarding step 1 — invite first teammate
+
+## Context
+After sign-up the admin lands on `/onboarding`. This story implements the first
+moment-of-truth from scenario S1: inviting the first teammate.
+
+## Acceptance criteria
+- **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
+- Bulk invite (multiple emails) — separate story E01-S07.
+- Custom invite message — defer to E02-S03.
+- "Skip for now" button — not a moment-of-truth path; out.
+
+## Notes for Shuri (Dev)
+- Touch points: `app/(onboarding)/invite/page.tsx`, `lib/email/send-invite.ts`, new server action `inviteTeammate`.
+- Reuse: `Button` (primary), `Input`, `Banner` (success/error) from design-system.
+- testid: `invite-form`, `invite-email`, `invite-cta`, `invite-sent-banner`.
+- Idempotency: use `(team_id, email)` composite key.
+
+## Notes for Hawkeye (TEA)
+Suggested split: 4 unit, 1 integration, 1 E2E.
+- Unit: validateInviteEmail, mailer payload, server action error mapping, retry policy.
+- Integration: server action calls mailer with right args (MSW on Resend).
+- E2E: happy path on Playwright @chromium @ios.
+- Risk: R-1 (mailer) — extra E2E asserts banner within 1s of click.
+```
+
+## Anti-patterns Tony rejects
+
+- **ACs reworded from PRD.** Source-of-truth drift.
+- **Stories with no touch points.** Shuri spends an hour finding the files.
+- **No notes for Hawkeye.** TEA designs in the dark.
+- **Stories named by feature** ("Add invite button") — name by **outcome**.
+
+## Hand-off
 
-## Rules
-- One story = one PR. If two, split.
-- Each AC must be testable. If Hawkeye can't write a test for it, rewrite the AC.
-- "Out of scope" is mandatory. Force the cut.
+> Story E01-S03 ready. Shuri, pull when sprint allows. Hawkeye, `tea-design.md` for this story whenever you're ready.

package/src/method-skills/4-implementation/wize-dev-story/workflow.md

@@ -3,31 +3,129 @@ code: wize-dev-story
 name: Dev Story
 phase: 4-implementation
 owner: wize-agent-dev   # Shuri
-status: stub
+status: ready
 ---
 
 # Dev Story
 
-**Goal.** Implement one story under TDD discipline.
+**Goal.** Implement one story under TDD discipline. Tests first; minimum code to pass; refactor with green. Each commit cites an AC ID. The PR ends in a clean gate, not a "looks good to me."
+
+Shuri drives. Hawkeye observes (test design is binding). Tony stays available for architectural questions.
 
 ## Inputs
-- `.wize/solutioning/stories/{epic}/{story-id}.md`
+
+- `.wize/solutioning/stories/{epic}/{story}.md`
 - `.wize/solutioning/architecture.md`
-- `.wize/implementation/tea/{epic}/{story-id}/design.md` (Hawkeye must have produced this)
+- `.wize/solutioning/design-system/` (use existing components)
+- `.wize/implementation/tea/{epic}/{story}/design.md` (the test contract)
 
 ## Outputs
-- Code + tests in the target repo
-- Commit messages reference AC IDs
-- Story file updated to `status: ready-for-review`
-
-## Steps (TDD loop)
-1. **Read.** Story ACs and Hawkeye's design.
-2. **Red.** Write the failing test first.
-3. **Green.** Minimum code to pass.
-4. **Refactor.** Clean — only with green tests.
-5. **Repeat** until every AC has at least one test.
-6. **Self-check.** Security, perf, dead code, naming.
-7. **Hand-off.** Ping Hawkeye for trace + review.
+
+- Code + tests in the target repo.
+- Commit messages reference AC IDs.
+- Story file updated to `status: ready-for-review`.
+
+## The loop (TDD, story-scoped)
+
+### 1. Read
+
+Story ACs, out-of-scope, notes, `tea-design.md`. Confirm the test split. If the design doesn't match the story (mismatch on test count, mock, environment), ping Hawkeye **before** writing code.
+
+### 2. Slice the story into micro-cycles
+
+Each cycle is one AC (or part of one) and produces a green test + small code change. Don't try to ship the whole story in one commit.
+
+### 3. Red
+
+Write the failing test first. Match the assertion shape in `design.md`. Don't write code yet.
+
+```ts
+// red — first run, fails
+test('valid email returns ok', () => {
+  expect(validateInviteEmail('a@b.co')).toEqual({ ok: true });
+});
+```
+
+### 4. Green
+
+Write the **minimum** code that turns the test green. No anticipated branches; no "just-in-case" handling.
+
+```ts
+// green — minimum to pass
+export const validateInviteEmail = (s: string) => ({ ok: /@/.test(s) });
+```
+
+### 5. Refactor
+
+Now harden, with the test as safety net.
+
+```ts
+// refactor — same green tests, real logic
+import { z } from 'zod';
+const schema = z.string().email();
+export const validateInviteEmail = (s: string) =>
+  schema.safeParse(s).success ? { ok: true } : { ok: false, code: 'invalid_format', field: 'email' };
+```
+
+### 6. Commit
+
+Conventional commits, AC IDs referenced.
+
+```
+feat(invite): validate email per AC-02-1 / AC-02-2
+- add validateInviteEmail with zod
+- add 4 unit tests covering valid + invalid rules
+```
+
+### 7. Repeat
+
+Until every AC has at least one test + minimum code that makes it pass.
+
+### 8. Pre-PR self-check
+
+- All Hawkeye-declared tests exist + pass.
+- No `test.skip` / `.only` left.
+- Lint + format clean.
+- Type-check clean.
+- `data-testid` matches story's "notes for Hawkeye".
+- Story file frontmatter → `status: ready-for-review`.
+- Self-walk the screen (web) or smoke a tab on simulator (app).
+
+### 9. Open PR
+
+PR description includes:
+- Story link.
+- AC list with the test names that cover them.
+- Screenshots / recordings of happy + failure paths.
+- TEA expected next: design → trace → review → gate.
+
+### 10. Address gate findings
+
+If `tea-review` flags issues, fix them in the same PR or open a follow-up if the story has shipped a separate value-bearing slice.
+
+## Security + perf during implementation
+
+Shuri thinks both at write time, not at review time:
+
+- Auth context on every server entry point — confirm via Tony's middleware pattern.
+- Tokens never logged.
+- Inputs validated at the boundary; trusted by the time they reach domain.
+- Network calls in handlers wrapped with timeout + retry policy from architecture.
+- Don't `await` in a loop without batching.
+- Don't ship dead code (`isFooEnabled = true` always).
 
 ## Quick-dev exception
-If invoked via `wize-quick-dev`, the design step is replaced by smoke-test-only commitment.
+
+If the work is small / well-scoped and Wizer invoked `wize-quick-dev` instead of this workflow, the design step is replaced by smoke-test-only commitment and the gate is a single one-line entry in `quick-dev-log.md`.
+
+## Anti-patterns Shuri rejects in her own work
+
+- Writing code first and tests "after the bug fix" — that's not TDD; that's regression-tests.
+- Commits that don't cite an AC.
+- "Refactor while green" turning into "rewrite while green."
+- Bundling cross-cutting refactors into the story PR. Split.
+- Editing tests so they pass instead of editing code so tests pass.
+
+## Hand-off
+
+> Story E01-S03 implemented. All ACs covered by tests; CI green. PR opened (#412). Hawkeye, ready for trace + review. Notes section of the story has the testid map you'll use.