wize-dev-kit 0.1.5 → 0.2.5

package/src/method-skills/3-solutioning/wize-check-implementation-readiness/workflow.md

@@ -2,21 +2,111 @@
 code: wize-check-implementation-readiness
 name: Check Implementation Readiness
 phase: 3-solutioning
-owner: wize-agent-architect   # Tony Stark (with Hawkeye)
-status: stub
+owner: wize-agent-architect   # Tony Stark (with Hawkeye + Hill)
+status: ready
 ---
 
 # Check Implementation Readiness
 
-**Goal.** Before any story enters dev, confirm everything is in place.
+**Goal.** Before any story enters dev, confirm everything is in place. This is the **gate at the end of Phase 3**. Cheap; saves multiples of itself downstream.
 
-## Checklist
-- [ ] Architecture doc exists and is signed (Tony + Fury approved).
-- [ ] All in-scope screens have UX specs (Mantis).
-- [ ] Design system tokens exist (Mantis).
-- [ ] Stories are sliced with ACs (Tony).
-- [ ] Hawkeye risk profile exists.
-- [ ] `.wize/config/tea.toml` policy choice is recorded.
+Tony chairs. Hill and Hawkeye sign off. Pepper and Mantis answer if pulled in.
+
+## Inputs
+
+- `.wize/planning/prd.md` (validated)
+- `.wize/planning/ux/ux-design/` + `index.md`
+- `.wize/planning/tech-vision.md`
+- `.wize/planning/nfr-principles.md`
+- `.wize/solutioning/architecture.md`
+- `.wize/solutioning/adrs/`
+- `.wize/solutioning/design-system/`
+- `.wize/solutioning/epics/` + `stories/`
+- `.wize/implementation/tea/risk-profile.md` (Hawkeye)
+- `.wize/config/tea.toml` (policy choice)
+
+## Outputs
+
+- `.wize/solutioning/readiness-{YYYY-MM-DD}.md` — checklist result + signoffs.
+
+## Checklist (Tony chairs)
+
+### Planning artifacts
+- [ ] PRD `status: validated`.
+- [ ] All open questions in PRD resolved (no `blocker` open).
+- [ ] Trigger map covers every PRD goal.
+
+### UX
+- [ ] Every In-scope item has at least one screen spec.
+- [ ] UX design index maps every screen → scenario → AC.
+- [ ] Design system tokens + components needed by the UX exist.
+
+### Strategy
+- [ ] Tech vision `status: aligned`.
+- [ ] NFR principles `status: aligned`; verifiers named for every non-negotiable.
+
+### Architecture
+- [ ] Architecture doc `status: ready-for-stories`.
+- [ ] ADRs cover every meaningful trade-off.
+- [ ] NFR check section answers *how* for each non-negotiable.
+
+### Stories
+- [ ] Every epic has 3–10 stories.
+- [ ] Every story has AC IDs from the PRD; the union per epic equals the epic's AC set.
+- [ ] No story is XL.
+- [ ] Each story names touch-points + `testid` + reuse of design-system components.
+
+### TEA
+- [ ] `tea-risk.md` exists.
+- [ ] `.wize/config/tea.toml` policy is committed (advisory / enforcing).
+- [ ] First-story `tea-design.md` is drafted (proof Hawkeye's contract works).
+
+### Cross-cutting
+- [ ] CI runs tests + validators on every PR.
+- [ ] Lint/format on commit.
+- [ ] Branch protection on `main`.
+- [ ] Secrets vault wired; no secret in repo.
 
 ## Outcome
-Either `ready: true` or list of fix-asks.
+
+- **Ready** → write the readiness file, link from `sprint-planning`.
+- **Concerns** → list specifically what's missing, owner per item, deadline. Re-check.
+
+## Output template
+
+```markdown
+---
+status: ready | concerns
+date: YYYY-MM-DD
+chair: Tony Stark
+signoffs:
+  - Maria Hill (PM)
+  - Hawkeye (TEA)
+  - Mantis (UX) — async
+  - Fury (Strategy) — async
+---
+
+# Implementation Readiness — {{project_name}}
+
+## Result: Ready
+
+## Notes
+- Architecture covers 5 epics and 28 stories.
+- TEA policy: advisory; NFR gate per epic.
+- 2 ADRs accepted in this gate review (ADR-008, ADR-009).
+
+## Open items (carry forward, not blockers)
+- Marketing site for launch — separate track, owned by …
+- Stripe-Atlas back-office decision — by date X.
+```
+
+## Anti-patterns
+
+- "Looks ready" without running the checklist.
+- Signing off before Hawkeye has risk-profiled.
+- Closing concerns without re-checking.
+- Leaving CI configuration "for later" — never gets done.
+
+## Hand-off
+
+> Implementation readiness signed off. Hill, kick `wize-sprint-planning`. Hawkeye, your gate cadence is set: design per story, trace + review + gate per story, NFR per epic.

package/src/method-skills/3-solutioning/wize-create-architecture/workflow.md

@@ -3,62 +3,230 @@ code: wize-create-architecture
 name: Create Architecture
 phase: 3-solutioning
 owner: wize-agent-architect   # Tony Stark
-status: stub
+status: ready
 ---
 
 # Create Architecture
 
-**Goal.** Design the system inside Fury's frame. Components, sequences, data flows, ADRs. Concrete enough that Shuri can implement and Hawkeye can test.
+**Goal.** Design the system inside Fury's frame. Components, sequences, data flows, ADRs. Concrete enough that Shuri can implement and Hawkeye can write `tea-design.md` for every story.
+
+Tony drives. Output lands in `.wize/solutioning/architecture.md` + `.wize/solutioning/adrs/`.
 
 ## Inputs
-- `.wize/planning/prd.md`
-- `.wize/planning/ux/ux-design/`
-- `.wize/planning/tech-vision.md` (Fury)
-- `.wize/planning/nfr-principles.md` (Fury)
-- `.wize/solutioning/design-system/` (Mantis)
-- `.wize/knowledge/document-project/` (if brownfield)
+
+- `.wize/planning/prd.md` (validated)
+- `.wize/planning/ux/ux-design/` (every architectural decision should make at least one screen possible)
+- `.wize/planning/tech-vision.md` (the frame)
+- `.wize/planning/nfr-principles.md` (the budget)
+- `.wize/solutioning/design-system/` (Mantis' tokens, when available)
+- Stack catalogs (overlays): `web-overlay/stack-catalog.md`, `app-overlay/stack-catalog.md`
+- `.wize/knowledge/document-project/` (brownfield only)
 
 ## Outputs
+
 - `.wize/solutioning/architecture.md`
-- `.wize/solutioning/adrs/{ADR-NNN}-{slug}.md`
+- `.wize/solutioning/adrs/ADR-NNN-{slug}.md` (one ADR per meaningful trade-off)
 
 ## Steps
-1. **Stack interview.** Tony asks the user (via Wizer) about preferences: language, runtime, deployment target. Consults overlay stack catalogs (web/app) if active. Records decisions.
-2. **Components.** List components, responsibilities, boundaries.
-3. **Sequences.** For each critical scenario from Mantis, write a sequence (text or PlantUML).
-4. **Data model.** Tables / collections / contracts.
-5. **Cross-cutting.** Auth, logging, observability, error handling.
-6. **ADRs.** Every significant trade-off becomes its own ADR: context, options, decision, consequences.
-7. **Validate against NFRs.** Check each Fury principle.
-8. **Hand-off to epics.**
+
+### 1. Stack interview (Tony asks; Wizer relays)
+
+Resolve every "TBD" the tech-vision left for Tony. Walk the stack catalog (active overlay) and decide, in order:
+
+- Language(s) + runtime(s).
+- Front-end framework + state lib + form lib.
+- Back-end framework or BaaS.
+- DB + ORM/query builder.
+- Auth.
+- Hosting + CI/CD.
+- Observability stack.
+- Test stack (links to `playwright-vitest.md` or `detox-maestro.md`).
+
+Decisions Tony makes silently are ADR candidates; decisions Fury already fixed don't get their own ADR.
+
+### 2. Components
+
+List components with one-line responsibility each. Boundaries before internals. Examples (web SaaS):
+
+| Component | Responsibility | Boundary |
+|---|---|---|
+| `web` | Server-rendered fullstack app (Next.js) | HTTPS to clients; SQL to db; HTTPS to auth-provider |
+| `db` | Source of truth for users, teams, billing (Postgres) | SQL only via PgBouncer |
+| `auth` | Identity provider (Supabase Auth) | OIDC to `web` |
+| `mailer` | Outbound transactional email | HTTPS to Resend |
+| `worker` | Outbox processor + scheduled jobs (pg_cron) | SQL to db; HTTPS to external APIs |
+
+### 3. Sequences (the critical ones)
+
+For each "moment of truth" in `.wize/planning/ux/ux-scenarios.md`, draw a sequence. Mermaid is fine; ASCII is fine.
+
+```mermaid
+sequenceDiagram
+  participant U as User
+  participant W as web
+  participant A as auth
+  participant D as db
+  U->>W: POST /signup
+  W->>A: signUp(email, password)
+  A-->>W: { user_id, session }
+  W->>D: INSERT user_id INTO accounts
+  D-->>W: ok
+  W-->>U: 302 /onboarding (sets cookie)
+  Note over W,U: total p95 ≤ 1s (NFR 1.A)
+```
+
+Annotate each sequence with the NFR target it must hit.
+
+### 4. Data model
+
+For every entity:
+
+- Name, columns, types, indexes.
+- Foreign keys + cascade behavior.
+- RLS policies if the stack supports them (Supabase, etc.).
+- Soft-delete vs hard-delete.
+
+Include a mini ERD (Mermaid `erDiagram`).
+
+### 5. Cross-cutting concerns
+
+For each, name the pattern and the library/component:
+
+- **Auth & session** — token shape, refresh, multi-device.
+- **Errors** — error class hierarchy, mapping to HTTP, user-facing copy.
+- **Logging** — structured (JSON), correlation IDs, sampling.
+- **Observability** — metrics emitter, traces, dashboards.
+- **Config** — env vars, secrets, feature flags.
+- **Background jobs** — outbox / queue / scheduler.
+- **Idempotency** — keys on write endpoints.
+- **i18n** — string source, translation pipeline.
+- **A11y** — token + library choices that uphold WCAG.
+
+### 6. NFR check (every category)
+
+Walk Fury's NFRs. For each non-negotiable, write *how* the architecture achieves it.
+
+- Perf: LCP ≤ 2.5s → edge runtime + RSC + image policy.
+- Security: PII in EU → DB in `eu-central-1`; backups in same region.
+- Reliability: 99.9% → single-region with multi-AZ; failover playbook in `adrs/ADR-007-failover.md`.
+- A11y: WCAG AA → Radix primitives + axe in CI.
+
+### 7. ADRs
+
+One ADR per meaningful trade-off. Format below. Number sequentially. Don't gold-plate; an ADR is a few paragraphs.
+
+### 8. Hand off
+
+Mark `architecture.md` `status: ready-for-stories`. Tony continues with `wize-create-epics-and-stories`.
 
 ## Architecture doc template
 
 ```markdown
+---
+status: ready-for-stories
+owner: Tony Stark
+created: YYYY-MM-DD
+---
+
 # Architecture — {{project_name}}
 
+## Summary
+{{One paragraph: stack family, runtime, primary data store, deploy target. The frame.}}
+
 ## Stack
-- Language: …
-- Runtime: …
-- Storage: …
-- Deploy: …
+- Language: TypeScript
+- Front-end: Next.js (App Router, RSC, edge runtime)
+- Back-end: Server Actions + Route Handlers
+- DB: Supabase Postgres + Drizzle ORM
+- Auth: Supabase Auth
+- Hosting: Vercel
+- Observability: Vercel + PostHog
+- Test: Vitest + Playwright (see playbook)
 
 ## Components
 | Component | Responsibility | Boundary |
 |---|---|---|
 
 ## Data model
-…
+- `users` (id PK, email UNIQUE, created_at)
+- `teams` (id PK, name, owner_id FK users)
+- `memberships` (user_id, team_id, role)
+- RLS: `auth.uid() = user_id` on all user-scoped tables.
+
+```mermaid
+erDiagram
+  USERS ||--o{ MEMBERSHIPS : has
+  TEAMS ||--o{ MEMBERSHIPS : has
+```
+
+## Sequences
+
+### S1: Sign-up
+{{sequence diagram + NFR annotation}}
+
+### S2: Invite teammate
+{{sequence diagram}}
 
 ## Cross-cutting
-- Auth: …
-- Observability: …
+- Auth & session: …
 - Errors: …
+- Logging: …
+- Observability: …
+- Config: …
+- Background jobs: …
+- Idempotency: …
+- i18n: …
+- A11y: …
 
 ## NFR check
-- Performance: …
-- Security: …
-- Reliability: …
-- Accessibility: …
-- Cost: …
+- Perf (1.A): how
+- Security (2.A): how
+- Reliability (3.A): how
+- Maintainability (4.A): how
+- A11y (5.A): how
+- Cost (6.A): how
+
+## ADRs
+See `.wize/solutioning/adrs/`.
 ```
+
+## ADR template
+
+```markdown
+---
+status: accepted | superseded | deprecated
+date: YYYY-MM-DD
+deciders: Tony, Fury
+supersedes: ADR-XXX
+---
+
+# ADR-007: {{slug}}
+
+## Context
+{{2–4 sentences: what forced the decision, what constraint is binding.}}
+
+## Options
+1. {{Option A}} — pros / cons / cost
+2. {{Option B}} — pros / cons / cost
+3. {{Option C}} — pros / cons / cost
+
+## Decision
+{{The pick. One sentence.}}
+
+## Consequences
+- **Now:** what we gain, what we accept.
+- **Later:** what we'll likely revisit and when.
+- **Related ADRs:** ADR-005, ADR-009.
+```
+
+## Anti-patterns Tony rejects
+
+- **Architecture without sequences.** A diagram with boxes is half a doc.
+- **NFR check left as "TBD".** Each non-negotiable answers *how*.
+- **ADRs for trivial choices** (which CSS file name) — saves nothing, costs trust.
+- **No ADR for genuinely contested choices** (auth provider, DB selection) — future-readers will re-litigate.
+- **Diagrams in proprietary format only.** Mermaid/ASCII version always present in markdown.
+
+## Hand-off
+
+> Architecture and 6 ADRs at `.wize/solutioning/`. Sequences hit the NFR targets. Hawkeye, you can write `tea-risk.md` against this. Tony continues with `wize-create-epics-and-stories`.

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

@@ -3,22 +3,91 @@ code: wize-create-epics-and-stories
 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/`.
 
 ## Inputs
+
 - `.wize/planning/prd.md`
 - `.wize/solutioning/architecture.md`
+- `.wize/planning/ux/ux-design/` (every story references one or more screens)
 
 ## 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
+estimate: M
+---
+
+# 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).
+- **E**stimable — Tony can size: S/M/L/XL.
+- **S**mall — fits in one PR (≤ 1 day for an experienced dev, including tests).
+- **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
 ---
@@ -27,22 +96,68 @@ 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.
 
 ## 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
-- …
+- Bulk invite (multiple emails) — separate story E01-S07.
+- Custom invite message — defer to E02-S03.
 
 ## 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).
+
+## 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).
 ```
+
+## 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.
+
+### 4. Estimates
+
+Story estimates S/M/L/XL. XL gets sliced before merging. If everything is L, slicing pattern is too coarse; revisit.
+
+### 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.