wize-dev-kit 0.1.5 → 0.2.5

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,154 @@ 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. Knowledge update (inline, ~60s)
+
+Before opening the PR, ask: **did this story touch any of the 5 baseline axes** documented in `.wize/knowledge/document-project/`?
+
+| Axis | Touched when… | File to update |
+|---|---|---|
+| **Architecture** | new component, new sequence, changed data flow | `architecture-snapshot.md` |
+| **Conventions** | new naming/folder/test pattern published as public contract (incl. `testid`) | `conventions.md` |
+| **Risk-spots** | introduced a complexity hot spot OR resolved one | `risk-spots.md` |
+| **Dependencies** | added / removed / upgraded a runtime dep | `dependencies.md` |
+| **Overview** | new user-visible feature a new dev should know about | `overview.md` |
+
+If yes for any axis: open the file and add **1–3 lines** under a new dated bullet — in the same PR.
+
+```markdown
+## 2026-06-12 — E01-S03
+- Conventions: `data-testid="invite-*"` published as public contract; Hawkeye E2E depends on these.
+- Risk: R-1 (mailer) mitigation now confirmed (integration test covers retry policy).
+```
+
+If no axis was touched, you skip this step entirely — quick-dev-style changes don't need it. Hawkeye will check whether the call was correct in `tea-review`. A story that touched an axis but skipped the update gets a `KN-NN` finding in the gate (recommendation `CONCERNS` advisory, or `FAIL` enforcing).
+
+This is how the brownfield baseline stays alive instead of going stale 6 months in.
+
+### 9. 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).
+
+### 10. Open PR
+
+PR description includes:
+- Story link.
+- AC list with the test names that cover them.
+- Screenshots / recordings of happy + failure paths.
+- Knowledge update line (`Touched axis: <none|architecture|conventions|risk-spots|dependencies|overview>`).
+- TEA expected next: design → trace → review → gate.
+
+### 11. 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.

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

@@ -3,31 +3,134 @@ code: wize-quick-dev
 name: Quick Dev (lifecycle shortcut)
 phase: 4-implementation
 owner: wize-agent-dev   # Shuri
-status: stub
+status: ready
 ---
 
 # Quick Dev
 
-**Goal.** When the task is small and well-scoped (bug fix, copy edit, small refactor), skip the full lifecycle.
+**Goal.** When the task is small and well-scoped (bug fix, copy edit, small refactor, dep bump, brownfield maintenance), skip Phase 1–3 and execute with light TEA. Save the full lifecycle for new value.
 
-## When to use
-- Bug fix with clear root cause
-- Copy or content edit
-- Small refactor with no behavior change
-- Dependency bump
-- Brownfield maintenance
+Wizer authorizes the shortcut (via routing). Shuri runs it. Hawkeye does smoke-only.
 
-## When NOT to use
-- New feature
-- Cross-cutting change touching architecture
-- Anything where ACs need to be agreed
+## When to use (yes)
+
+- Bug fix with a clear root cause.
+- Copy or content edit.
+- Small refactor with no behavior change.
+- Dependency bump (security or minor).
+- Brownfield maintenance: rename, structural cleanup, dead-code removal.
+- Hotfix during incident response (post-mortem after).
+
+## When NOT to use (no)
+
+- New feature, even small.
+- Cross-cutting change touching architecture.
+- Changes where ACs need to be agreed.
+- Anything that should be a story.
+- Anything that touches security/auth/payments without senior review.
+
+## Decision tree
+
+```
+Question                              Yes              No
+Is there an AC to write?              → full lifecycle  → next
+Does it touch architecture?           → full lifecycle  → next
+Does it need UX input?                → full lifecycle  → next
+Could it surprise a user?             → full lifecycle  → next
+Is it ≤ 1 hour to a careful dev?      → quick-dev       → full lifecycle
+```
+
+## Inputs
+
+- Issue / Slack message / PR comment describing the problem.
+- Repo state.
+- `.wize/config/tea.toml` (smoke-only policy when `policy = "advisory"`).
+
+## Output
+
+- Code change (single PR).
+- Single-line entry appended to `.wize/implementation/quick-dev-log.md`.
+- Conventional commit.
 
 ## Steps
-1. **Frame.** One paragraph: what changes and why.
-2. **Implement.** TDD or smoke-test-and-fix, depending on risk.
-3. **Hawkeye lite.** Smoke test + lint only (no design/trace/nfr/review).
-4. **Gate.** Tiny `gate.md` (PASS or CONCERNS) appended to a rolling `.wize/implementation/quick-dev-log.md`.
-5. **Commit.** Conventional commit referencing the change.
+
+### 1. Frame in one paragraph
+
+What changes, why, and what could break. If the paragraph is hard to write, you're not in quick-dev territory.
+
+### 2. Implement
+
+- TDD when reasonable; smoke-test-and-fix when the cost of TDD is greater than the value.
+- Reuse existing components. Don't introduce new abstractions.
+
+### 3. Hawkeye lite
+
+- Smoke test: imports load, the changed flow doesn't break.
+- Lint + format + type-check clean.
+- No `tea-design / trace / review / nfr` written.
+- Single one-line gate entry instead of full `gate.md`.
+
+### 4. Log
+
+Append one line to `.wize/implementation/quick-dev-log.md`:
+
+```
+2026-06-11 | shuri | dep-bump zod 3.22→3.23 | smoke PASS | PR #418
+2026-06-11 | shuri | fix copy on /signin help link | smoke PASS | PR #419
+2026-06-11 | shuri | rename UserService → AccountService | smoke PASS | PR #420
+```
+
+### 5. Knowledge update (only if applicable)
+
+Most quick-dev changes don't touch the baseline axes (copy edit, small refactor, dep bump in a stable lib). When they do — typically a **dependency bump** or a **rename that breaks a public contract** — add **one line** to the matching `document-project/*.md` file:
+
+```markdown
+## 2026-06-11
+- Dependencies: bump zod 3.22 → 3.23. No API changes; validateInviteEmail unaffected.
+- Conventions: `AccountService` replaces `UserService` (rename); imports updated repo-wide.
+```
+
+Heuristic: *"would a new dev hitting `document-project/*.md` next week be misled if I don't add this?"* Yes → write. No → skip.
+
+### 6. Commit + open PR
+
+Conventional commit. PR description: the paragraph from step 1.
+
+```
+fix(auth): typo in error message for AC-04-2 follow-up
+
+The error shown after rate-limit said "Sloow down" — corrected to "Slow down".
+No behavior change; copy-only.
+```
+
+## Quick-dev log template
+
+```markdown
+# Quick-dev log
+
+| Date | Owner | What | Smoke | PR |
+|---|---|---|---|---|
+| 2026-06-11 | shuri | … | PASS | #N |
+```
 
 ## Disabling
-Set `quick_dev_enabled = false` in `.wize/config/project.toml` to force full lifecycle for everything.
+
+To force every change through the full lifecycle (for very high-stakes products), set in `.wize/config/project.toml`:
+
+```toml
+[install]
+quick_dev_enabled = false
+```
+
+Wizer respects this; quick-dev becomes unavailable; every change must go through Pepper → … → Hawkeye gate.
+
+## Anti-patterns Shuri rejects in herself
+
+- Reaching for quick-dev to skip writing an AC because she doesn't want to argue with Hill.
+- Quick-dev that touches security/auth/payments.
+- A "small refactor" that ends up changing behavior.
+- Skipping the log entry.
+
+## Hand-off
+
+> `dep-bump zod 3.23` is in. PR #418, smoke PASS. Logged. No further TEA artifacts; moving on.

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

@@ -3,34 +3,136 @@ code: wize-retrospective
 name: Retrospective
 phase: 4-implementation
 owner: wize-orchestrator   # Wizer facilitates; whole team contributes
-status: stub
+status: ready
 ---
 
 # Retrospective
 
-**Goal.** Capture what worked, what didn't, and what we change next sprint.
+**Goal.** Capture what worked, what didn't, what surprised, and **one concrete change for next sprint**. A retro that ends in a vibe is a retro that didn't ship a change.
+
+Wizer facilitates. Hill enforces output discipline. Everyone (including Pepper, Mantis, Fury) contributes.
+
+## When to run
+
+- End of every sprint (cadence).
+- After any incident (separate; pulls from incident timeline).
+- At major milestones (epic close, release, year-end).
 
 ## Inputs
+
 - `.wize/implementation/sprint-status.md` (current sprint)
 - All `gate.md` files from current sprint
+- `tea/nfr/{epic}.md` if an epic closed this sprint
+- Quick-dev log
+
+## Output
 
-## Outputs
 - `.wize/implementation/retrospective/{YYYY-MM-DD}.md`
 
-## Template
+## Format (60 minutes, fixed)
+
+| Minutes | Section |
+|---|---|
+| 0–5 | Frame: Wizer reads the sprint stats (capacity, shipped, slipped, gates). |
+| 5–15 | **Worked** — what we want to repeat. |
+| 15–25 | **Didn't work** — what we want to change. |
+| 25–35 | **Surprised us** — externalities, signals, anything not on plan. |
+| 35–45 | Pick **1–3 changes**. Vote with effort/impact dots. |
+| 45–55 | Each change gets an owner + deadline. |
+| 55–60 | Wizer reads back the doc; everyone confirms; close. |
+
+Going over 60 minutes is a sign the retro became therapy. Time-box.
+
+## Steps
+
+### 1. Open with stats
+
+Wizer reads the sprint dashboard from `sprint-status.md`:
+- Velocity vs commitment.
+- Number of gates: PASS / CONCERNS / FAIL / WAIVED.
+- Blockers and their resolution times.
+- Carry-over count.
+
+Stats anchor the retro in observations, not feelings.
+
+### 2. Worked / didn't / surprised
+
+Each engineer brings 2–3 items per section, written in advance ideally. Time-box discussion: any item that takes > 3 min becomes a follow-up.
+
+### 3. Changes (1–3 max)
+
+A change is:
+- **Specific:** "Pair-program for E04-S02 because R-3 is high" — not "communicate more."
+- **Owned:** a person.
+- **Bounded:** a deadline or a sprint to land it.
+
+If you pick 4+ changes, you'll execute 0. Choose.
+
+### 4. Write the doc
+
+Use the template; close the retro with the doc in front of the team.
+
+### 5. Trigger reads
+
+Wizer notifies Hill (who plugs the changes into next sprint planning), Hawkeye (who may revise risk profile), Fury (when an NFR principle change emerges).
+
+## Output template
 
 ```markdown
-# Retrospective — Sprint N
+---
+sprint: 7
+date: 2026-06-25
+facilitator: Wizer
+attendees: [Hill, Tony, Mantis, Pepper, Fury, Hawkeye, Shuri]
+---
+
+# Retrospective — Sprint 7
+
+## Sprint snapshot
+- Committed: 4 stories + 1 stretch
+- Shipped: 4 stories
+- Stretch: not pulled
+- Gates: 4 PASS, 1 CONCERNS, 0 FAIL
+- Blockers: 1 (vendor sandbox, resolved Day 5)
+- Carry-over to S8: 0
 
 ## Worked
-- …
+- Pairing on E03-S02 (auth refresh) — issue caught at integration test instead of in prod.
+- TEA design done at planning for R-3 stories paid off.
+- Mantis' "before/after" recordings in PRs accelerated review.
 
 ## Didn't work
-- …
+- Sprint-status entries went stale on Days 7–8 (Hill on vacation).
+- E02-S02 estimated M, actually L; we over-committed.
+- Vendor outage with no fallback caught us cold for 4h.
 
 ## Surprised us
-- …
+- A11y audit caught 3 issues on a screen Mantis had already signed off on (axe found dynamic-content edge cases).
+- Cost dashboard showed mailer spend doubled — outbox retry was too aggressive.
+
+## Changes for Sprint 8
+
+1. **Sprint-status delegation rotation** — when Hill is OOO, Wizer takes over. *Owner: Wizer. By: Sprint 8 Day 1.*
+2. **L estimates require justification** — any L gets one paragraph "why L not M" in the story file. *Owner: Tony. By: Sprint 8 planning.*
+3. **Vendor fallback drill** — quarterly, simulate top-3 vendor outages. *Owner: Hawkeye + Tony. By: end of Q3.*
+
+## Decisions made
+- Mailer retry policy updated (NFR-01-1).
+- Risk profile revised: R-1 mitigation now confirmed.
 
-## Changes next sprint (owner + due date)
-- [ ] … — owner: …
+## Notes for next sprint
+- Carry zero stories; everyone starts S8 fresh.
+- Stretch goal in S8: catch up on REV-01 (copy fix from S7).
 ```
+
+## Anti-patterns Wizer rejects (politely)
+
+- **A retro without a change.** Then it was venting.
+- **"We need to communicate better."** Specific or it doesn't count.
+- **Adopting > 3 changes.** None will land.
+- **No owner / no deadline.** Hopes, not plans.
+- **Skipping the retro to "save time."** The next sprint costs more.
+
+## Hand-off
+
+> Retro at `.wize/implementation/retrospective/2026-06-25.md`. 3 changes; owners assigned. Sprint 8 planning anchors on them. Hawkeye, please update `risk-profile.md` with the R-1 mitigation confirmed.