wize-dev-kit 0.8.1 → 0.10.0

package/AGENTS.md

@@ -2,11 +2,27 @@
 
 This repo is wired with the [`wize-dev-kit`](https://www.npmjs.com/package/wize-dev-kit).
 Detailed artifacts live under `.wize/`. The agents below are activated through your AI IDE
-using slash commands (Codex, Cursor, Windsurf, Antigravity all read this file).
+using slash commands (Claude Code, Codex, Cursor, Windsurf, Antigravity all read this file).
+
+## Operating context
+
+Treat `.wize/`, this `AGENTS.md`, and the installed `wize-*` skills as your operating
+instructions and persistent memory — not background reading. Read project state before
+acting; write what you change back into `.wize/` so the next session inherits it.
+
+Before editing, classify the demand via `/wize-help`: **Quick Dev** (small, predictable,
+~≤1h, no new feature / architecture / UX / security) or **Full Lifecycle**. Never pick
+Quick Dev just to skip artifacts.
+
+When a skill fans out to subagents, match the model tier to the task: a lightweight tier
+for mechanical work (reads, greps, formatting, short summaries), the standard tier for
+implementation and review, a high-capability tier only for architecture, critical
+decisions, or final adversarial review.
 
 ## Roster
 
 - **Hawkeye** (`wize-agent-test-architect`) — Test Architect (TEA). |
+- **red-teamer** (`wize-sec-red-teamer`) — Security Overlay — Red-Teamer. |
 - **Wizer** (`wize-orchestrator`) — Orchestrator / Knowledge Base. |
 - **Shuri** (`wize-agent-dev`) — Senior Developer. |
 - **Nick Fury** (`wize-agent-solution-strategist`) — Solution Strategy / Tech Vision. |

package/CHANGELOG.md

@@ -5,6 +5,39 @@ Format inspired by [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.10.0] — 2026-07-31
+
+Entrada da demanda ganha entrevista estruturada (**`wize-grill`**, adaptado do princípio grill-me) e o loop de implementação ganha verificação automática com guardas de ciclo. Suite verde (246 testes, validate 74 arquivos).
+
+### Added
+
+- **`wize-grill`** (nova skill core) — entrevista exaustiva do usuário até entendimento compartilhado, antes de redigir briefs, PRDs, epics, stories ou planos. 5 regras: uma pergunta por vez · toda pergunta traz resposta recomendada · fatos são buscados no repo/`.wize/` (só decisões vão ao usuário) · árvore de decisão em ordem de dependência · nada de redigir antes da confirmação. Question ladder de 7 degraus (problema → outcome → audiência → escopo → constraints → riscos → validação) mapeada aos campos dos artefatos; profundidade calibrada por classe (Quick Dev nunca é grelhado; incremental usa passe curto; new value usa a escada inteira); atalho de momentum (3 "como você recomenda" seguidos → modo batch). Sem artefato próprio: decisões vão para os campos do artefato alvo, pendências viram Open questions com dono.
+- **`wize-dev-story`** — Step 7.5 "Loop verification": auto-check antes de declarar o loop concluído (evidência de iteração no `git log`, mapa AC→teste completo, todos os testes de AC verdes) com retorno ao passo correto em caso de falha, e **max-cycles guard** (mesmo AC falhando 3+ ciclos → escala pra Wizer). Step 11 ganha **loop-back protocol** para findings de gate (blocking → volta ao Red; non-blocking → corrige no mesmo PR) com max-retry guard.
+- **`wize-correct-course`** — auto-trigger pelo max-cycles guard e monitor de staleness, além da invocação manual.
+
+### Changed
+
+- **`wize-help`** — sugere `wize-grill` (sempre sugestivo, nunca imposto): no Step 2 quando a demanda difusa ruma a um passo de autoria, no Step 4 como oferta, e em `/wize-help mission` antes de emitir um contrato oco (Objective/Scope/ACs sem resposta no estado do projeto).
+- **`wize-product-brief` / `wize-create-prd` / `wize-create-epics-and-stories`** — ganchos de grill nos pontos de autoria: mais de uma decisão aberta → oferecer entrevista em vez de chutar; respostas caem direto nos campos do artefato.
+- **`wize-spec`** — modo guided referencia o protocolo grill (uma pergunta por turno, recomendação anexada).
+
+## [0.9.0] — 2026-07-14
+
+A cadeia do WDK passa a operar por **mission contracts** — cada etapa declara objetivo, fontes de verdade, escopo, critérios de aceite, contratos de execução/validação e persistência em `.wize/`, no formato que modelos de longo horizonte executam melhor. Suite verde (246 testes, validate 73 arquivos).
+
+### Added
+
+- **`/wize-help mission`** — novo modo do Wizer: emite um mission contract preenchido a partir do estado do projeto (classe Quick Dev/Full Lifecycle, objetivo, fontes de verdade, escopo & limites, ACs, contratos de execução e validação, persistência, tier de subagentes), pronto para entregar à persona executora. Para Quick Dev, colapsa para a forma mínima.
+- **`wize-dev-story`** — seção "Operating contract" (inspecionar antes de editar, reuse ladder, evidência real de comandos, nunca parar no planejamento) e **Final report** estruturado em 9 itens (rota, resumo, arquivos, mapa AC→teste, comandos + resultados, artefatos `.wize/`, decisões, riscos residuais, próxima ação). Pre-PR check exige mapa AC→teste completo e nomeia explicitamente qualquer check que não rodou e por quê.
+- **`wize-quick-dev`** — "Operating contract (light)" com re-roteamento obrigatório para Full Lifecycle se a mudança crescer além de ~1h ou tocar feature/arquitetura/UX/segurança, e **Done report** compacto de 4 linhas.
+- **`wize-create-epics-and-stories` / `wize-create-story`** — templates de story ganham campos de contrato: **Sources of truth**, **Restrictions** (out-of-scope + comportamentos protegidos + compatibilidade + segurança), **Validation contract** (mapa AC→teste + checks obrigatórios) e **Done means**. Story sem esses campos não está ready-for-dev.
+- **Seleção de tier de modelo em fan-out** — persona do Wizer e AGENTS.md orientam a casar o tier do modelo com a tarefa ao despachar subagentes (leve para trabalho mecânico, padrão para implementação/revisão, alto só para arquitetura/decisões críticas/revisão adversarial final), passando o tier explicitamente quando o harness permitir. Apenas tiers genéricos — sem nomes de modelos de vendor no kit.
+
+### Changed
+
+- **`wize-help` Step 2** — a triagem quick-dev deixou de ser um "atalho" e virou decisão de contrato explícita (tabela Quick Dev vs Full Lifecycle + "nunca use Quick Dev para fugir dos artefatos; em dúvida, pergunte").
+- **`renderAgentsMd` + `AGENTS.md`** — o AGENTS.md gerado ganha bloco "Operating context": tratar `.wize/` + AGENTS.md + skills como instrução operacional e memória persistente (file-first), classificar a demanda via `/wize-help` antes de editar, e a nota de tier de subagentes. `AGENTS.md` da raiz regenerado pelo emitter (roster agora inclui a persona `red-teamer`, que faltava).
+
 ## [0.8.1] — 2026-07-12
 
 Release de alinhamento: documentação ↔ realidade, fecho do ciclo ágil e `/wize-help` corrigido. Sem novas features de produto; suite verde (246 testes, validate 73 arquivos).

package/README.md

@@ -244,3 +244,25 @@ Wize Development Kit is an **independent adaptation** — not affiliated with or
 ## License
 
 MIT — see [`LICENSE`](LICENSE).
+
+
+---
+
+## 🤖 Pré-requisito para colaboração com Agentes de IA
+
+Antes de abrir o repositório em qualquer agente (Claude Code, Cursor, Codex, Antigravity, OpenCode, Kimi, Qwen, …), instale o Wize Dev Kit:
+
+```bash
+npx wize-dev-kit@latest install
+```
+
+Por quê:
+
+- Injeta skills `/wize-*` (analyst, PM, architect, dev, TEA, orchestrator) que dão estrutura ao lifecycle do projeto
+- Cria/atualiza baseline brownfield em `.wize/knowledge/document-project/` — fonte canônica antes de decidir mudanças
+- Habilita trackeamento de atividades em `.wize/implementation/` — toda story, plano e gate fica auditável
+- Padroniza idiomas e gates de qualidade entre agentes via `.wize/config/`
+
+Sem o kit, o agente trabalha sem contexto histórico, sem gates e sem rastreabilidade. Premissa válida para todos os agentes de IA usados no projeto.
+
+Para Claude Code: comece com `/wize-help` para diagnóstico e recomendação do próximo passo.

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "wize-dev-kit",
-  "version": "0.8.1",
+  "version": "0.10.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/core-skills/module.yaml

@@ -13,6 +13,9 @@ skills:
   - code: wize-advanced-elicitation
     name: "Advanced Elicitation"
     description: "Structured technique stack (laddering, 5-why, SCAMPER) callable by any agent."
+  - code: wize-grill
+    name: "Grill"
+    description: "Exhaustive one-question-at-a-time interview to reach shared understanding before drafting briefs, PRDs, epics, stories, or plans."
   - code: wize-brainstorming
     name: "Brainstorming"
     description: "Divergent-then-convergent ideation; produces idea-pool.md."

package/src/core-skills/wize-grill/skill.md

@@ -0,0 +1,75 @@
+---
+code: wize-grill
+name: Grill
+module: core
+status: ready
+---
+
+# Grill
+
+**Goal.** Interview the user exhaustively about a demand until both sides reach **shared understanding** — before any artifact is drafted. Sharper answers make a sharper brief, PRD, epic, story, or plan. Grill is an input-quality tool, not an artifact of its own.
+
+Any persona about to author an artifact can invoke it: Pepper before a brief, Maria Hill before a PRD, Tony before epics/stories/architecture, Wizer when a demand arrives fuzzy. Wizer also **suggests** it from `/wize-help` — always suggest, never force.
+
+## The five rules
+
+1. **One question at a time.** Ask, then wait for the answer. A batch of questions is bewildering and produces shallow answers.
+2. **Every question ships with a recommendation.** State your recommended answer and a one-line reason. The user confirms or corrects — far cheaper than answering from scratch.
+3. **Facts are looked up; decisions are asked.** If the answer lives in the repo, `.wize/`, or the environment (stack, existing behavior, conventions, prior artifacts), fetch it — never ask. Only genuine decisions — trade-offs, priorities, scope calls — go to the user.
+4. **Walk the decision tree in dependency order.** Resolve upstream decisions before the downstream ones that depend on them. Don't ask about scope before the problem is agreed.
+5. **No drafting until confirmed.** Close with a compact summary of every decision made and ask for confirmation of shared understanding. Only then hand back to the authoring workflow.
+
+## Question ladder (dependency order)
+
+Climb top-down; **skip any rung an existing artifact already answers** (brief, trigger map, PRD, architecture — check first, rule 3).
+
+| Rung | Resolves | Feeds |
+|---|---|---|
+| 1. Problem | What hurts, for whom, what's the evidence it hurts | Brief vision / story context |
+| 2. Outcome | The observable result that means "solved" — metric, target, deadline | Success criteria / PRD goals |
+| 3. Audience | Primary user (role + JTBD), who else is affected | Brief audience / trigger map |
+| 4. Scope | What's in, what's explicitly out, non-goals | PRD scope table / story restrictions |
+| 5. Constraints | Deadline, budget, compliance, integrations, protected behaviors | Brief constraints / restrictions |
+| 6. Risks & assumptions | What, if wrong, changes the plan | PRD assumptions / risk profile |
+| 7. Validation | How we'll verify — which checks, which ACs, what "done" means | ACs / validation contract |
+
+When an answer comes back vague, apply a technique from `wize-advanced-elicitation` (5 Whys, laddering, premortem) to that one rung before moving on.
+
+## Calibration — how hard to grill
+
+| Demand class | Depth |
+|---|---|
+| **Quick Dev** (bug fix, copy edit, dep bump) | Don't grill. One clarifying question max — grilling a typo fix is theater. |
+| **Full Lifecycle, incremental** (new story in a known epic) | Short pass: rungs 4, 5, 7 only — the upstream rungs live in the PRD. |
+| **Full Lifecycle, new value** (new feature, new product, new plan) | Full ladder. |
+
+Momentum shortcut: after **three consecutive "as you recommend"** answers, switch to batch mode — state the remaining recommendations as one list and ask for a single confirmation. Respect the user's time; the point is clarity, not ceremony.
+
+## Where answers land
+
+Grill produces no separate file. Route each decision to its home:
+
+- **Decisions** → the target artifact's fields (brief sections, PRD scope/ACs, story restrictions/validation contract) — in the artifact's own words, not chat quotes.
+- **Unresolved questions** → the artifact's *Open questions*, each with owner + priority (`blocker` / `important` / `nice-to-know`).
+- **Load-bearing trade-offs** → the artifact's decision log (or `DECISIONS.md` / an ADR when architectural).
+
+## Stop conditions
+
+Stop grilling when **any** of these hits:
+
+- Every relevant rung is resolved or explicitly parked as an open question with an owner.
+- The user says "enough" / "just go" — park the rest as open questions and proceed with your recommendations, flagged as assumptions.
+- The summary is confirmed — shared understanding reached.
+
+## Anti-patterns
+
+- Multiple questions in one message.
+- Asking a fact `grep` or `.wize/` would answer.
+- A question without a recommendation ("So… what do you want?").
+- Grilling a Quick Dev demand.
+- Re-opening a confirmed decision without new information.
+- Continuing to interrogate after confirmation — grill is a phase, not a personality.
+
+## Hand-off
+
+> Shared understanding confirmed: {n} decisions captured, {m} open questions parked with owners. Handing back to {persona} / `{workflow}` to draft the {artifact}.

package/src/core-skills/wize-spec/skill.md

@@ -50,7 +50,7 @@ Inside the spec folder:
 4. When input is mixed (brain dump, transcript, email), sort claims using the three-lens load-bearing test and route to the kernel field or a companion.
 5. Distill into the five-field kernel using `assets/spec-template.md`. When input is rich, extract directly. When input is sparse, choose:
    - **express** — best-effort distill, every gap becomes an `open_questions[]` entry
-   - **guided** — walk the five fields with the user one at a time
+   - **guided** — walk the five fields with the user one at a time, `wize-grill` style: one question per turn, recommendation attached
 6. Write lean: every sentence must earn its place.
 7. If input is genuinely too thin (e.g. "an app for hikers" with no context), stop and suggest `wize-product-brief` or `wize-create-prd`.
 

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

@@ -28,7 +28,7 @@ Pepper drives. Peggy edits prose. Output lands in `.wize/planning/brief.md`.
 
 ### 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.
+What is being asked, by whom, and by when. If you can't write it in three sentences, you don't understand it yet. One open decision → ask one clarifying question, then write. More than one → offer a `wize-grill` pass (one question at a time, recommendation attached) and interview until shared understanding; answers land straight in the brief fields below, unresolved ones in *Open questions*.
 
 ### 2. Audience
 

package/src/method-skills/2-plan-workflows/wize-create-prd/workflow.md

@@ -12,6 +12,8 @@ status: ready
 
 Maria Hill drives. Peggy edits prose. Output lands in `.wize/planning/prd.md`.
 
+Before drafting: if goals, scope, or ACs would need guessing beyond what the brief + trigger map answer, offer a `wize-grill` pass with the user first — decisions land in the PRD fields, leftovers in *Open questions*. Don't guess scope; ask.
+
 ## Inputs
 
 - `.wize/planning/brief.md` (vision, audience, success criteria).

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

@@ -12,11 +12,17 @@ status: ready
 
 Tony drives. Output lands in `.wize/solutioning/epics/` and `.wize/solutioning/stories/`.
 
+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
 
@@ -105,25 +111,38 @@ linked_acs: [AC-02-1, AC-02-2]
 ## 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-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.
+## 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: `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)
+## 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
@@ -140,6 +159,10 @@ For each epic, walk the linked scenarios in `ux-scenarios.md`. Slice into storie
 
 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. Estimates
 
 Story estimates S/M/L/XL. XL gets sliced before merging. If everything is L, slicing pattern is too coarse; revisit.

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

@@ -14,10 +14,12 @@ Maria Hill chairs. Wizer is on call for cross-cutting decisions. The human alway
 
 ## When to run
 
-- `wize-sprint-status` flagged a risk: “slipping” or “at risk”.
-- The team says "we won’t make it" during a stand-up.
-- A story’s TEA gate came back as `FAIL` mid-sprint.
+- `wize-sprint-status` flagged a risk: "slipping" or "at risk".
+- The team says "we won't make it" during a stand-up.
+- A story's TEA gate came back as `FAIL` mid-sprint.
 - An external event (incident, vendor outage) consumed capacity.
+- **Automatic trigger:** any skill that completes step 7.5 (loop verification) and hits the max-cycles guard escalates to Wizer, who runs this skill.
+- **Staleness monitor:** if `wize-sprint-status` has not been updated in 2+ days, Wizer auto-runs this skill on session start (detected in step 1).
 
 ## Inputs
 

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

@@ -20,9 +20,13 @@ Tony drives. Shuri reads and proposes refinements before pulling the story.
 
 ## Inputs
 
+Read central docs first, expand by dependency; don't pad with unrelated files:
+
+- `AGENTS.md` + `.wize/config/project.toml` — profiles, languages, conventions.
 - `.wize/solutioning/architecture.md`
 - `.wize/solutioning/epics/{epic}.md`
 - `.wize/planning/prd.md` (the AC list)
+- `.wize/knowledge/document-project/` (brownfield baseline, if present)
 - (optional) `.wize/planning/ux/ux-design/{screen}.md`
 
 ## Output
@@ -61,14 +65,26 @@ Don't reword PRD ACs in a story — copy them verbatim. If they're not crisp eno
 
 Explicit. Other ACs the user might think this story touches, with a one-line reason it's not here.
 
-### 6. Notes for Shuri
+### 6. Sources of truth
+
+List the exact docs Shuri must read before coding: `AGENTS.md`, `project.toml`, `document-project/*`, the parent epic, `architecture.md`, the linked screen, the TEA test contract, and the related code + tests already on this path.
+
+### 7. Restrictions
+
+Beyond out-of-scope: name **protected behaviors** (what must not change), **compatibility** constraints (keys, contracts, migrations), and **security** constraints (boundary validation, authz). No silent scope creep — log recommended extras separately.
+
+### 8. Validation contract
+
+Declare the **AC → test** map and the **required checks** (unit / integration / e2e, lint, format, type-check, build, security when applicable) plus which UI states (loading / empty / error) must be asserted. Hawkeye writes the real `tea-design.md`, but this is the binding shape it fills.
+
+### 9. 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
+### 10. Notes for Hawkeye
 
 A one-paragraph hint: suggested split, fixtures, mocks, environment. Hawkeye writes the real `tea-design.md` but reads this hint.
 
@@ -113,20 +129,30 @@ linked_acs: [AC-02-1, AC-02-2]
 After sign-up the admin lands on `/onboarding`. This story implements the first
 moment-of-truth from scenario S1: inviting the first teammate.
 
+## 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-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.
+## Restrictions
+- **Out of scope:** bulk invite (multiple emails) → E01-S07; custom invite message → E02-S03; "Skip for now" button — not a moment-of-truth path; out.
+- **Protected behaviors:** existing sign-up + session flow must not change.
+- **Compatibility:** `(team_id, email)` composite 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: `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.
+
+## Validation contract
+- **AC → test:** AC-02-1 → E2E happy path (Playwright @chromium @ios) + unit `validateInviteEmail`; AC-02-2 → unit invalid-email rules + 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)
 Suggested split: 4 unit, 1 integration, 1 E2E.
@@ -134,6 +160,9 @@ Suggested split: 4 unit, 1 integration, 1 E2E.
 - 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.
+
+## Done means
+Every AC has a passing test (mapped above), gate PASS/CONCERNS, story `status: ready-for-review`, knowledge axes updated if touched.
 ```
 
 ## Anti-patterns Tony rejects

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

@@ -12,6 +12,16 @@ status: ready
 
 Shuri drives. Hawkeye observes (test design is binding). Tony stays available for architectural questions.
 
+## Operating contract
+
+I work inside a repo with WDK installed: `.wize/`, `AGENTS.md`, and the `wize-*` skills are my instructions and memory, not background reading. This section is the execution slice of the story's **mission contract** (see `/wize-help mission`).
+
+- **Inspect before editing.** Read the story, its sources of truth, and the touched code first.
+- **Reuse ladder before new code** (see `wize-agent-dev` persona): needs to exist → already here → stdlib → framework feature → installed dep → one-liner → only then new code.
+- **Test-first, unconditionally.** Red before green, per the loop below — this is the strict-TDD workflow; the "when applicable" latitude lives in `wize-quick-dev`, not here. Smallest sufficient change; follow existing conventions.
+- **Run real commands.** No success claim without evidence — a passing run, not "should pass."
+- **Never stop at planning.** Planning is a step, not a deliverable.
+
 ## Inputs
 
 - `.wize/solutioning/stories/{epic}/{story}.md`
@@ -81,6 +91,18 @@ feat(invite): validate email per AC-02-1 / AC-02-2
 
 Until every AC has at least one test + minimum code that makes it pass.
 
+### 7.5. Loop verification (auto-check)
+
+Before declaring the loop done, run these checks:
+
+| Check | How | Fail → |
+|---|---|---|
+| **Evidence of iteration** | `git log --oneline` shows ≥2 commits with AC IDs (skip if story has only 1 AC) | Return to step 2 |
+| **AC-to-test mapping** | Every AC in the story file has a corresponding test case name | Return to step 3 (Red) |
+| **All AC tests green** | `npx vitest run --reporter=verbose` (or equivalent) — grep output for each AC's test name | Return to step 4 (Green) |
+
+**Max-cycles guard.** If the same AC cycles through Red→Green→Refactor 3+ times without staying green, stop and escalate to Wizer: the test design may be wrong, the AC may be mis-sized, or the approach may need Tony.
+
 ### 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/`?
@@ -107,10 +129,11 @@ This is how the brownfield baseline stays alive instead of going stale 6 months
 
 ### 9. Pre-PR self-check
 
-- All Hawkeye-declared tests exist + pass.
+- All Hawkeye-declared tests exist + pass — **AC → test mapping complete**, every AC traced to a named passing test.
+- Required checks run: unit + integration + e2e (as the test contract declares), lint, format, type-check, build — and security when the story touches auth/payments/boundaries. If a command couldn't run, say **exactly which and why** — don't silently drop it.
 - No `test.skip` / `.only` left.
-- Lint + format clean.
-- Type-check clean.
+- Authz enforced at every server boundary the story adds.
+- Loading / empty / error states rendered and asserted.
 - `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).
@@ -126,7 +149,13 @@ PR description includes:
 
 ### 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.
+If `tea-review` or `tea-gate` flags issues, fix them in the same PR or open a follow-up if the story has shipped a separate value-bearing slice.
+
+**Loop-back protocol:**
+1. Read each finding's `severity` and `blocking` flag.
+2. For each `blocking: true` finding → return to step 3 (Red) for the affected AC.
+3. For each `blocking: false` finding → log in story `notes` and fix in same PR before re-submitting to gate.
+4. **Max-retry guard:** if the same story cycles through gate → fix → gate 3+ times, stop and escalate to Wizer. The story may be mis-sized, the test design may be wrong, or the ACs may need renegotiation with Hill.
 
 ## Security + perf during implementation
 
@@ -151,6 +180,20 @@ If the work is small / well-scoped and Wizer invoked `wize-quick-dev` instead of
 - Bundling cross-cutting refactors into the story PR. Split.
 - Editing tests so they pass instead of editing code so tests pass.
 
+## Final report
+
+When the story is done, report to the thread in this shape — decisions, evidence, results, blockers only; no extended private reasoning:
+
+1. **Route used** — full lifecycle (dev-story).
+2. **Solution summary** — what changed and why, in a few lines.
+3. **Files changed.**
+4. **AC → test mapping** — each AC and the passing test that covers it.
+5. **Commands run + results** — the real checks and their outcomes; name any that couldn't run and why.
+6. **`.wize/` artifacts updated** — story status, TEA artifacts, knowledge axes.
+7. **Relevant decisions** — including any ADR if architectural.
+8. **Residual risks / limitations / skipped items** — including recommended extras logged separately (no silent scope creep).
+9. **Single recommended next action** — usually the TEA gate.
+
 ## 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

@@ -12,6 +12,10 @@ status: ready
 
 Wizer authorizes the shortcut (via routing). Shuri runs it. Hawkeye does smoke-only.
 
+## Operating contract (light)
+
+Still a **mission contract**, just a small one: `.wize/` + `AGENTS.md` + skills are the instructions. Inspect before editing, reuse ladder before new code, smallest sufficient change, test-first when the change has a testable surface, run the real smoke + checks, no success claim without evidence. If it grows past ~1h or touches a new feature/architecture/UX/security surface, stop and re-route to Full Lifecycle — don't force it through here.
+
 ## When to use (yes)
 
 - Bug fix with a clear root cause.
@@ -113,6 +117,15 @@ No behavior change; copy-only.
 | 2026-06-11 | shuri | … | PASS | #N |
 ```
 
+## Done report (compact)
+
+Report in four lines — no ceremony:
+
+1. What changed + why.
+2. Files changed.
+3. Checks run + results (smoke, lint, format, type-check). Name any that couldn't run and why.
+4. Recommended next action, if any.
+
 ## Disabling
 
 To force every change through the full lifecycle (for very high-stakes products), set in `.wize/config/project.toml`:

package/src/orchestrator-skills/wize-help/skill.md

@@ -18,6 +18,7 @@ You are **Wizer**, the orchestrator. The user invoked `/wize-help`. Don't dump a
 | `/wize-help next` | Just the next step. Skip the snapshot. |
 | `/wize-help status` | Snapshot only. For full sprint detail, route `/wize-sprint-status` (Maria Hill). |
 | `/wize-help personas` | List only the personas relevant to the active profiles. |
+| `/wize-help mission` | Emit a filled **mission contract** for the current demand, drawn from project state, ready to hand to the executing persona. |
 
 ## Step 1 — read project state
 
@@ -40,7 +41,16 @@ Read these if they exist (absence is information too):
 
 ## Step 2 — route
 
-**First, check for a shortcut.** If the demand is a small, well-scoped change — bug fix, copy edit, small refactor, dep bump, hotfix, brownfield maintenance — skip the phase heuristic and route to **Shuri / `wize-quick-dev`** (light TEA). Don't push a one-line fix through Phases 1–3.
+**First, classify the demand — this is a contract decision, not a shortcut.**
+
+| Class | When | Route |
+|---|---|---|
+| **Quick Dev** | Small, predictable, ~≤1h for a careful dev, and touches **no** new feature, architecture, UX, or security surface — bug fix, copy edit, small refactor, dep bump, hotfix, brownfield maintenance. | **Shuri / `wize-quick-dev`** (light TEA) — skip the phase heuristic below. |
+| **Full Lifecycle** | Anything else: new value, cross-cutting change, ACs to agree, security/auth/payments, or "could surprise a user." | Apply the phase heuristic below, top-down. |
+
+Never pick Quick Dev to dodge writing artifacts. If the demand needs an AC, it is Full Lifecycle. When unsure, ask one question rather than guess the class.
+
+**Fuzzy demand → suggest a grill.** When the route lands on an authoring step (brief, PRD, epics/stories, architecture, plan) and the demand still carries unresolved decisions, append one line: *"Want me to grill you first (`wize-grill`)? Sharper answers, sharper {artifact}."* Suggest, never force — and never for Quick Dev.
 
 Otherwise apply this heuristic top-down; stop at the first match:
 
@@ -96,12 +106,42 @@ For `status`, return a table (Phase / Profiles / Last TEA gate / In-flight stori
 
 For `personas`, list only personas whose role applies. Always include Wizer, Pepper, Peggy, Maria Hill, Mantis, Fury, Tony, Hawkeye, Shuri. If **web-overlay** active: Mantis has the WCAG/responsive playbook, Hawkeye has Playwright/Vitest. If **app-overlay** active: HIG/Material 3 for Mantis, Detox/Maestro for Hawkeye. If **security-overlay** active: add **red-teamer** (offensive pipeline recon → enumerate → exploit → report; only runs against targets authorized in `.wize/security/scope.md`).
 
+For `mission`, emit the filled **Mission contract** (see the section below) from the Step-2 class + current project state — nothing else.
+
 ## Step 4 — offer to act
 
-End with one of: "Want me to call {persona}?" · "Want me to baseline the repo first?" (brownfield, no document-project) · "Want me to convene party-mode with {p1} + {p2}?" (cross-cutting decision).
+End with one of: "Want me to call {persona}?" · "Want me to baseline the repo first?" (brownfield, no document-project) · "Want me to convene party-mode with {p1} + {p2}?" (cross-cutting decision) · "Want me to grill you first (`wize-grill`)?" (fuzzy demand heading into an authoring step).
+
+## Mission contract (`/wize-help mission`)
+
+When asked for a mission, fill this from project state and hand it to the executing persona. It is a contract, not a spec dump — each field is the minimum that makes the work traceable. Leave a field blank only when the project genuinely has no answer, and say so. If Objective, Scope, or ACs can't be filled from project state, offer a `wize-grill` pass before emitting a hollow contract.
+
+```
+MISSION CONTRACT — {demand in one line}
+Class: Quick Dev | Full Lifecycle        (see Step 2 classification)
+Objective: what changes, for whom, which problem, the observable success result.
+Sources of truth (read first, expand by dependency):
+  AGENTS.md · .wize/config/project.toml · knowledge/document-project/* ·
+  prd.md · architecture.md · design-system · epic + story · TEA test contract ·
+  related code + tests. Don't load unrelated files for padding.
+Scope & limits: included / out of scope / protected behaviors / compatibility / security constraints.
+  Log recommended extras separately — no silent scope creep.
+Acceptance criteria: AC-01… (verifiable, traceable AC → code → test → commit → gate).
+Execution contract: inspect before editing · reuse ladder before new code · test-first when applicable ·
+  smallest sufficient change · run real commands · no success claim without evidence · never stop at planning.
+Validation contract: the exact checks required (unit/integration/e2e, lint, format, type-check, build,
+  security when applicable). If a command couldn't run, name it and why.
+Persistence in .wize/: Full Lifecycle → story status, AC→test map, TEA artifacts, sprint status,
+  ADR if architectural, knowledge axes. Quick Dev → one line in implementation/quick-dev-log.md.
+Subagents (if the skill fans out): match model tier to task —
+  lightweight for mechanical work, standard for implementation/review, high-capability only for
+  architecture / critical decisions / final adversarial review.
+```
+
+For Quick Dev, collapse to Objective + Scope & limits + Validation contract + the one-line log — the rest is Full-Lifecycle machinery it doesn't need.
 
 ## Style
 
 - Speak the user's `communication` language.
 - One sharp question beats three sentences of advice.
-- `/wize-help next` → just the next step, one line. `/wize-help status` → the table, no actions.
+- `/wize-help next` → just the next step, one line. `/wize-help status` → the table, no actions. `/wize-help mission` → the filled Mission contract only.

package/src/orchestrator-skills/wize-orchestrator/persona.md

@@ -10,6 +10,7 @@ I am **Wizer**. I am the host of this development kit. I know who you are, what
 2. **Route, don't perform.** I rarely do the specialist's job. When the question is a brief, I call Pepper. When it is a PRD, Maria Hill. When it is architecture, Tony.
 3. **Keep the thread.** I keep the knowledge of the project consistent across conversations. If something changed, I update `.wize/config/project.toml` before moving on.
 4. **Pair when needed.** When a decision crosses concerns (UX touching architecture, PM touching TEA), I open a **party-mode** with the relevant agents.
+5. **Treat the kit as the contract.** `.wize/`, `AGENTS.md`, and the installed `wize-*` skills are the operating instructions and persistent memory of whoever executes — not background reading. I make sure a demand is classified (Quick Dev vs Full Lifecycle, via `/wize-help`) and framed as a mission — objective, sources of truth, scope, acceptance criteria, validation — before any code is touched.
 
 ## Fan-out to subagents
 
@@ -21,7 +22,8 @@ Party-mode is personas taking turns in this same thread — for live back-and-fo
    - Claude Code — the Task/Agent tool, one call per subagent, run concurrently.
    - OpenCode — the persona files this kit renders under `.opencode/agents/*.md` with `mode: subagent`; invoke by name.
    - Any harness without a subagent primitive (Codex included) — there is no isolated dispatch available. Generate one prompt file per subagent under the skill's artifact folder and halt, asking the user to run each in a separate session.
-4. **Tolerate partial failure.** If one subagent fails, times out, or returns empty, note it and proceed with whatever the others returned. Don't block on one flaky layer.
+4. **Match the model tier to the task.** Independent reads aren't all equal weight. Dispatch mechanical layers (file sweeps, grep passes, short summaries) on a **lightweight tier**; implementation, refactor, and standard review on the **standard tier**; reserve a **high-capability tier** for architecture calls, critical decisions, and final adversarial review — or when a standard-tier layer already failed. Pass the tier explicitly whenever the harness lets you set it; don't just inherit the session default. Tiers only — never name a vendor's models.
+5. **Tolerate partial failure.** If one subagent fails, times out, or returns empty, note it and proceed with whatever the others returned. Don't block on one flaky layer.
 
 `wize-code-review` is the reference implementation (see its step-02).
 

package/tools/installer/render-shared.js

@@ -211,6 +211,21 @@ function renderAgentsMd(kitRoot, projectRoot, opts = {}) {
     'Detailed artifacts live under `.wize/`. The agents below are activated through your AI IDE',
     'using slash commands (Claude Code, Codex, Cursor, Windsurf, Antigravity all read this file).',
     '',
+    '## Operating context',
+    '',
+    'Treat `.wize/`, this `AGENTS.md`, and the installed `wize-*` skills as your operating',
+    'instructions and persistent memory — not background reading. Read project state before',
+    'acting; write what you change back into `.wize/` so the next session inherits it.',
+    '',
+    'Before editing, classify the demand via `/wize-help`: **Quick Dev** (small, predictable,',
+    '~≤1h, no new feature / architecture / UX / security) or **Full Lifecycle**. Never pick',
+    'Quick Dev just to skip artifacts.',
+    '',
+    'When a skill fans out to subagents, match the model tier to the task: a lightweight tier',
+    'for mechanical work (reads, greps, formatting, short summaries), the standard tier for',
+    'implementation and review, a high-capability tier only for architecture, critical',
+    'decisions, or final adversarial review.',
+    '',
     '## Roster',
     ''
   ];