wize-dev-kit 0.8.0 → 0.9.0

package/AGENTS.md

@@ -4,9 +4,25 @@ This repo is wired with the [`wize-dev-kit`](https://www.npmjs.com/package/wize-
 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
 
 - **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/ARCH.md

@@ -9,7 +9,7 @@
 ## 1. Identidade
 
 - **Nome do pacote npm:** `wize-dev-kit`
-- **CLI:** `wize-dev-kit` (subcomandos: `install`, `update`, `uninstall`, `agent`, `workflow`, `sync`)
+- **CLI:** `wize-dev-kit` (subcomandos: `install`, `update`, `uninstall`, `list`, `sync`, `agent`, `workflow`, `validate`, `doctor`, `document-project`)
 - **Namespace de arquivos/agentes/skills:** `wize-*`
 - **Licença:** MIT — open-source desde o dia 1.
 - **Tema visual do roster:** Marvel.
@@ -19,15 +19,16 @@
 
 ## 2. Modelo de distribuição
 
-**1 pacote, 3 perfis selecionáveis, overlays combináveis.**
+**1 pacote, 4 perfis selecionáveis, overlays combináveis.**
 
 ```
 wize-dev-kit (pacote npm)
 │
 ├── Wize Dev Core      ← base completa (sempre instalada)
 ├── Wize Web Dev       ← overlay opt-in
-└── Wize App Development ← overlay opt-in
-                     (Web + App podem coexistir no mesmo repo)
+├── Wize App Development ← overlay opt-in
+└── Wize Security Overlay ← overlay opt-in (AI Pentester / red-teamer)
+                     (overlays podem coexistir no mesmo repo)
 ```
 
 - Selecionar perfil no installer aplica Core + overlay correspondente.
@@ -36,7 +37,7 @@ wize-dev-kit (pacote npm)
 
 ---
 
-## 3. Roster final (9 personas Marvel)
+## 3. Roster final (9 core personas + 1 overlay persona)
 
 | Persona | Code | Papel | Fase principal |
 |---|---|---|---|
@@ -49,6 +50,7 @@ wize-dev-kit (pacote npm)
 | Tony Stark | `wize-agent-architect` | System Architect | 3 (Solutioning) |
 | Hawkeye | `wize-agent-test-architect` | Test Architect (TEA) | Gates 2/3/4 |
 | Shuri | `wize-agent-dev` | Senior Developer | 4 (Implementation) |
+| red-teamer | `wize-sec-red-teamer` | AI Pentester (security-overlay, opt-in) | Transversal |
 
 ---
 
@@ -162,12 +164,12 @@ E nos IDE-targets (selecionáveis no install):
 ```
 .claude/skills/wize-*           (Claude Code)
 .cursor/rules/wize-*.mdc        (Cursor)
-.windsurf/...                   (Windsurf)
-.codex/...                      (Codex)
-.continue/...                   (Continue)
-.kimi/...                       (Kimi Code)
-.opencode/...                   (OpenCode)
-.antigravity/...                (Antigravity CLI/IDE)
+.windsurf/rules/wize-*.md       (Windsurf)
+.agents/skills/wize-*           (Codex — .codex/ foi revertido na 0.7.3)
+.continue/prompts/wize-*.prompt (Continue)
+.kimi/skills/wize-*             (Kimi Code)
+.opencode/agents/ + .opencode/commands/  (OpenCode)
+.agent/skills/wize-*            (Antigravity CLI/IDE)
 .wize/agents/                   (fallback genérico)
 ```
 
@@ -196,7 +198,7 @@ wize-dev-kit install
   ├─ Detecta: greenfield vs brownfield
   ├─ Pergunta: perfil(s) — Core / +Web / +App
   ├─ Pergunta: IDE targets — multi-select
-  ├─ Pergunta: idioma e output_folder
+  ├─ Pergunta: idioma (output folder é fixo: .wize/)
   ├─ Cria .wize/ + adapters IDE
   ├─ Se brownfield: oferece `wize-document-project`
   └─ Se ok: dispara onboarding (Wizer → Pepper/Mantis/Tony)
@@ -268,7 +270,7 @@ wize-dev-kit sync     # regera adapters IDE
 
 - 3 skills meta: `wize-create-agent`, `wize-create-skill`, `wize-create-workflow`.
 - Customização de built-ins via `.wize/custom/{tipo}/{code}/customize.toml` (override sem fork).
-- Validação obrigatória: schema → lint → dry-run.
+- Validação: checks estruturais (validação de schema via Ajv pendente de orçamento de dependências).
 - Auto-sync: regera adapters de todos os IDEs ativos a cada criação/edição.
 
 ---
@@ -295,7 +297,7 @@ wize-dev-kit/
 ├── ROSTER.md                   # ← quadro Marvel
 │
 ├── src/
-│   ├── core-skills/            # Core (advanced-elicitation, brainstorming, party-mode, etc)
+│   ├── core-skills/            # Core (advanced-elicitation, brainstorming, spec, etc)
 │   │   └── wize-*/
 │   ├── method-skills/          # AI Agile dev: 1-analysis, 2-plan, 3-solutioning, 4-implementation
 │   │   ├── 1-analysis/
@@ -347,12 +349,19 @@ wize-dev-kit/
 │   │   └── wize-create-workflow/
 │   ├── web-overlay/            # Wize Web Dev overlay
 │   │   ├── wize-web-scaffold/
+│   │   ├── wize-web-deploy/
 │   │   ├── wize-web-seo-audit/
 │   │   └── module.yaml
-│   └── app-overlay/            # Wize App Development overlay
-│       ├── wize-app-scaffold/
-│       ├── wize-app-release-channels/
-│       └── module.yaml
+│   ├── app-overlay/            # Wize App Development overlay
+│   │   ├── wize-app-scaffold/
+│   │   ├── wize-app-release-channels/
+│   │   ├── wize-app-store-listing/
+│   │   └── module.yaml
+│   └── security-overlay/       # Wize Security Overlay (AI Pentester, opt-in)
+│       ├── agents/             # red-teamer (wize-sec-red-teamer)
+│       ├── skills/
+│       ├── data/
+│       └── _shared/
 │
 ├── adapters/                   # IDE adapters
 │   ├── claude-code/
@@ -371,6 +380,12 @@ wize-dev-kit/
 │       ├── detect.js           # greenfield/brownfield detector
 │       ├── onboarding.js
 │       ├── sync.js
+│       ├── render-shared.js
+│       ├── baseline.js
+│       ├── version-check.js
+│       ├── setup-helpers.js
+│       ├── commands/
+│       ├── document-project/
 │       └── validators/         # schema, lint, dry-run
 │
 └── test/                       # specs validating skills + workflows

package/CHANGELOG.md

@@ -5,6 +5,44 @@ Format inspired by [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [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).
+
+### Fixed
+
+- **`/wize-help` roteava contra o arquivo errado.** Lia `.wize/implementation/sprint-status.md`, mas o canônico é `sprint-status.yaml` — toda detecção de Fase 4 falhava e projetos em sprint eram re-roteados para o começo. Reescrito e re-renderizado para todos os adapters: agora lê o `.yaml`, conhece o atalho `wize-quick-dev`, inclui os gates `wize-validate-prd` e `wize-check-implementation-readiness`, a persona `red-teamer` e os workflows de overlay, tem branch para gate FAIL → `wize-correct-course`, e não anuncia mais o alias `/wize` inexistente. Mais conciso (heurístico em tabela única).
+- **Schemas rejeitavam os assets do security-overlay já publicados.** `agent.schema.json` passa a aceitar `code: wize-sec-*` e `module: security-overlay`; `workflow.schema.json` aceita `overlay: security`.
+
+### Docs
+
+- **Baseline `wize-document-project` atualizado** (estava congelado em v0.3.0 apesar do "refresh" de 2026-07-04): versão, contagem de agentes (10), core skills (10), testes (24 arquivos / 246), LOC, commits e subcomandos de CLI. Riscos e perguntas obsoletas removidos.
+- **README.es** trazido à paridade com en/pt-BR (estava em 0.7.0, sem a seção de harnesses). Nos três READMEs: removida a pergunta de "output folder" (o instalador não pergunta), corrigida a afirmação sobre dependências npm (`prompts`), e documentados os comandos `list` e `workflow`.
+- **ARCH.md / DECISIONS.md / ROSTER.md / AGENTS.md e os 9 READMEs de adapter** atualizados para 4 profiles, a 10ª persona (`red-teamer`) e os paths reais de cada adapter; decisão Fase 9 registrada.
+- **PRD / architecture / readiness**: contagem de ACs corrigida (30), stubs de template vazios removidos, notas de snapshot 0.6.0.
+
+### Cycle
+
+- **Registro ágil reconciliado.** `sprint-status.yaml` regenerado contra a árvore real (8 epics / 27 stories, todas `done`); epics `01`–`07` fechados; releases 0.7.x/0.8.0 registradas em `quick-dev-log.md` e `sprint-status.md`; `backlog.md` atualizado.
+- **Épico E09 aberto** ("Melhor aproveitamento de components e intenção do usuário") em `.wize/solutioning/epics/09-ux-intent.md`, com 8 stories verificadas contra o código; relatório completo em `REVIEW-2026-07-11.md`.
+
 ## [0.8.0] — 2026-07-04
 
 ### Added

package/DECISIONS.md

@@ -148,6 +148,11 @@
 - **D8.4 — Versionamento dos workflows antigos:** cópias dos `workflow.md` monolíticos de `wize-create-architecture` e `wize-code-review` são arquivadas em `.wize/knowledge/decisions/` para referência, não mantidas em produção.
 - **D8.5 — Registro em catálogos:** skills adicionados a `src/core-skills/module.yaml` e `src/method-skills/module.yaml`; fluxos refletidos no `README.md`.
 
+### Fase 9 — Security Overlay + OpenCode nativo (2026-07-11)
+
+- **D9.1 — Security Overlay neste kit:** o perfil `security-overlay` (AI Pentester) passa a ser distribuído **dentro do `wize-dev-kit`** como 4º perfil opt-in do installer, com a persona **red-teamer** (`wize-sec-red-teamer`) em `src/security-overlay/`. _Supersede parcialmente D1.1 (3 perfis → 4 perfis), D3.2 (9 papéis → 9 core + 1 overlay) e D3.5 (security deixava de ser reservado para kit futuro)._ As entradas históricas permanecem inalteradas como registro.
+- **D9.2 — OpenCode com wiring nativo (0.8.0):** o adapter OpenCode passa a gerar **agents e commands nativos** (`.opencode/agents/` + `.opencode/commands/`), com commands vinculados à persona dona e workers de fan-out isolados — em vez do fallback genérico.
+
 ## Perguntas em aberto
 
 _(serão preenchidas conforme a entrevista avança)_

package/README.es.md

@@ -25,7 +25,7 @@ Elige tus perfiles y tu IDE; luego, en tu IDE con IA, di *"Activa a Wizer y dale
 
 Wize Development Kit (WDK) es un **stack de agentes de IA** instalable que funciona dentro de tu IDE con IA (Claude Code, Cursor, Windsurf, Codex y otros) y escribe artefactos estructurados en una carpeta oculta `.wize/` de tu repositorio. Lleva un proyecto de **brief → PRD → estrategia de UX → arquitectura → implementación testeada**, y también puede **hacer pentest de la app en ejecución y planificar el sprint de remediación**.
 
-Es **file-first y zero-runtime**: los agentes son skills en Markdown que tu IDE lee; el tooling es Node puro (sin nuevas dependencias npm). Nada está simulado — cada paso lee el artefacto anterior y escribe uno real.
+Es **file-first y zero-runtime**: los agentes son skills en Markdown que tu IDE lee; el tooling es Node puro (una única dependencia npm — `prompts`, usada solo por el instalador; nada se añade a tu proyecto). Nada está simulado — cada paso lee el artefacto anterior y escribe uno real.
 
 ### Perfiles (combinables en monorepos)
 
@@ -57,8 +57,7 @@ El instalador pregunta:
 1. **Perfil(es)** — Core / +Web / +App / +Security (selección múltiple).
 2. **IDE(s) objetivo** — Claude Code, Cursor, Windsurf, Codex, Continue, Kimi Code, OpenCode, Antigravity o fallback genérico (selección múltiple).
 3. **Idiomas** — comunicación + salida de documentos.
-4. **Carpeta de salida** — por defecto `.wize/`.
-5. **Brownfield** — ofrece ejecutar `wize-document-project` para crear la baseline del código existente.
+4. **Brownfield** — ofrece ejecutar `wize-document-project` para crear la baseline del código existente.
 
 Tras instalar, abre tu IDE y di:
 
@@ -66,6 +65,24 @@ Tras instalar, abre tu IDE y di:
 
 ---
 
+## Harnesses soportados
+
+Los 9 IDEs objetivo se renderizan desde la misma fuente; el formato y la mecánica varían por harness. **OpenCode** recibe la integración más profunda — la separación persona/workflow del kit se mapea sobre las primitivas propias de OpenCode (`mode: primary|subagent`, `agent:`, `subtask:`) en lugar de aplanarse en un único tipo de archivo.
+
+| Harness | Salida | Destacado |
+|---|---|---|
+| **OpenCode** 🆕 | `.opencode/agents/` + `.opencode/commands/` | `mode: primary\|subagent` nativo; los comandos se vinculan automáticamente a su persona propietaria (`agent:`); los workers de fan-out corren aislados (`subtask: true`). [Docs →](docs/harnesses/opencode.md) |
+| **Claude Code** | `.claude/skills/*/SKILL.md` | Formato Skill de Anthropic; fan-out ad-hoc vía Task/Agent tool (`wize-code-review`). [Docs →](docs/harnesses/claude-code.md) |
+| **Codex** | `.agents/skills/*/SKILL.md` | Mismo formato Skill + `AGENTS.md` en la raíz. [Docs →](docs/harnesses/codex.md) |
+| **Kimi Code** | `.kimi/skills/*/SKILL.md` | Mismo formato Skill; autodetecta árboles de skills de Claude/Codex. [Docs →](docs/harnesses/kimi-code.md) |
+| **Antigravity** | `.agent/skills/*/SKILL.md` | Mismo formato Skill + `AGENTS.md` en la raíz. [Docs →](docs/harnesses/antigravity.md) |
+| **Cursor** | `.cursor/rules/*.mdc` | Reglas on-demand (`alwaysApply: false`), emparejadas por descripción. [Docs →](docs/harnesses/cursor.md) |
+| **Windsurf** | `.windsurf/rules/*.md` | Markdown plano; el modo de activación se define dentro del IDE. [Docs →](docs/harnesses/windsurf.md) |
+| **Continue.dev** | `.continue/prompts/*.prompt` | Slash commands con `invokable: true`. [Docs →](docs/harnesses/continue.md) |
+| **Fallback genérico** | `.wize/agents/*.md` + `AGENTS.md` en la raíz | Para cualquier IDE sin adapter dedicado. [Docs →](docs/harnesses/generic.md) |
+
+---
+
 ## El elenco
 
 | # | Persona | Código | Rol |
@@ -186,9 +203,12 @@ Con el perfil **Wize Security** instalado, la persona `red-teamer` ejecuta un pe
 npx wize-dev-kit install         # setup interactivo
 npx wize-dev-kit update          # actualiza un kit instalado a la versión actual
 npx wize-dev-kit sync            # re-renderiza los adapters de IDE tras editar la config
+npx wize-dev-kit list            # lista agentes, skills y workflows instalados
 npx wize-dev-kit agent list      # lista agentes nativos + personalizados
 npx wize-dev-kit agent create    # crea un nuevo agente personalizado (validado + dry-run)
 npx wize-dev-kit agent edit <code>  # sobrescribe un agente nativo
+npx wize-dev-kit workflow list   # lista workflows nativos + personalizados
+npx wize-dev-kit workflow create # crea un nuevo workflow personalizado
 npx wize-dev-kit doctor          # diagnostica kit / proyecto / adapters / gates
 npx wize-dev-kit validate        # chequeos estructurales en los assets del kit
 npx wize-dev-kit document-project [quick|initial_scan|full_rescan|deep_dive] [--resume] [--target <path>]
@@ -203,12 +223,13 @@ npx wize-dev-kit uninstall       # elimina .wize/ (tu código queda intacto)
 - [`ROSTER.md`](ROSTER.md) — personas con estilo, rol, equivalencias BMAD.
 - [`DECISIONS.md`](DECISIONS.md) — registro de decisiones.
 - [`CHANGELOG.md`](CHANGELOG.md) — historial de releases.
+- [`docs/harnesses/`](docs/harnesses/) — un doc por [harness soportado](#harnesses-soportados), en inglés.
 
 ---
 
 ## Estado
 
-**v0.7.0 — beta.** El ciclo completo (análisis → plan → solución → implementación) está montado con 10 agentes y una biblioteca estructurada de skills. El `security-overlay` (Pentester de IA) entrega un pipeline de pentest completo, un informe ejecutivo (puntuación de riesgo + briefing + plan de acción por IA) y planificación de remediación post-scan — validado de principio a fin contra una aplicación Laravel/PHP real. Los adapters de IDE para Claude Code, Cursor, Windsurf, Codex, Continue, Kimi Code, OpenCode y Antigravity se regeneran automáticamente.
+**v0.8.0 — beta.** El ciclo completo (análisis → plan → solución → implementación) está montado con 10 agentes y una biblioteca estructurada de skills. El `security-overlay` (Pentester de IA) entrega un pipeline de pentest completo, un informe ejecutivo (puntuación de riesgo + briefing + plan de acción por IA) y planificación de remediación post-scan — validado de principio a fin contra una aplicación Laravel/PHP real. Los adapters de IDE para Claude Code, Cursor, Windsurf, Codex, Continue, Kimi Code, OpenCode y Antigravity se regeneran automáticamente — [OpenCode](docs/harnesses/opencode.md) recibe wiring nativo de `mode`/`agent`/`subtask`, la integración más profunda de las 9.
 
 ---
 

package/README.md

@@ -25,7 +25,7 @@ Pick your profiles and IDE, then in your AI IDE say *"Activate Wizer and brief h
 
 Wize Development Kit (WDK) is an installable **AI agent stack** that runs inside your AI IDE (Claude Code, Cursor, Windsurf, Codex, and others) and writes structured artifacts to a hidden `.wize/` folder in your repo. It takes a project from **brief → PRD → UX strategy → architecture → tested implementation**, and can also **pentest the running app and plan the remediation sprint**.
 
-It is **file-first and zero-runtime**: the agents are Markdown skills your IDE reads; the tooling is plain Node (no new npm dependencies). Nothing is mocked — every step reads the previous artifact and writes a real one.
+It is **file-first and zero-runtime**: the agents are Markdown skills your IDE reads; the tooling is plain Node (a single runtime dependency, `prompts`, powers the interactive installer — nothing is added to your project). Nothing is mocked — every step reads the previous artifact and writes a real one.
 
 ### Profiles (combinable in monorepos)
 
@@ -57,8 +57,7 @@ The installer asks:
 1. **Profile(s)** — Core / +Web / +App / +Security (multi-select).
 2. **IDE target(s)** — Claude Code, Cursor, Windsurf, Codex, Continue, Kimi Code, OpenCode, Antigravity, or generic fallback (multi-select).
 3. **Languages** — communication + document output.
-4. **Output folder** — default `.wize/`.
-5. **Brownfield** — offers to run `wize-document-project` to baseline the existing codebase.
+4. **Brownfield** — offers to run `wize-document-project` to baseline the existing codebase.
 
 After install, open your IDE and say:
 
@@ -204,9 +203,11 @@ When the **Wize Security** profile is installed, the `red-teamer` persona runs a
 npx wize-dev-kit install         # interactive setup
 npx wize-dev-kit update          # bring an installed kit up to the current version
 npx wize-dev-kit sync            # re-render IDE adapters after editing config
+npx wize-dev-kit list            # list built-in + custom agents
 npx wize-dev-kit agent list      # list built-in + custom agents
 npx wize-dev-kit agent create    # scaffold a new custom agent (validated + dry-run)
 npx wize-dev-kit agent edit <code>  # override a built-in agent
+npx wize-dev-kit workflow <create|list>  # scaffold or list custom workflows
 npx wize-dev-kit doctor          # diagnose kit / project / adapters / gates
 npx wize-dev-kit validate        # structural checks on the kit assets
 npx wize-dev-kit document-project [quick|initial_scan|full_rescan|deep_dive] [--resume] [--target <path>]
@@ -243,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/README.pt-BR.md

@@ -25,7 +25,7 @@ Escolha os perfis e a IDE; depois, na sua IDE com IA, diga *"Ative o Wizer e dê
 
 O Wize Development Kit (WDK) é uma **stack de agentes de IA** instalável que roda dentro da sua IDE com IA (Claude Code, Cursor, Windsurf, Codex e outras) e grava artefatos estruturados em uma pasta oculta `.wize/` no seu repositório. Leva um projeto de **brief → PRD → estratégia de UX → arquitetura → implementação testada** e também pode **fazer pentest da aplicação rodando e planejar a sprint de correção**.
 
-É **file-first e zero-runtime**: os agentes são skills em Markdown que sua IDE lê; o tooling é Node puro (sem novas dependências npm). Nada é simulado — cada passo lê o artefato anterior e grava um real.
+É **file-first e zero-runtime**: os agentes são skills em Markdown que sua IDE lê; o tooling é Node puro (uma única dependência de runtime, `prompts`, usada pelo instalador interativo — nada é adicionado ao seu projeto). Nada é simulado — cada passo lê o artefato anterior e grava um real.
 
 ### Perfis (combináveis em monorepos)
 
@@ -57,8 +57,7 @@ O instalador pergunta:
 1. **Perfil(is)** — Core / +Web / +App / +Security (múltipla escolha).
 2. **IDE(s) alvo** — Claude Code, Cursor, Windsurf, Codex, Continue, Kimi Code, OpenCode, Antigravity ou fallback genérico (múltipla escolha).
 3. **Idiomas** — comunicação + saída de documentos.
-4. **Pasta de saída** — padrão `.wize/`.
-5. **Brownfield** — oferece rodar `wize-document-project` para criar a baseline do código existente.
+4. **Brownfield** — oferece rodar `wize-document-project` para criar a baseline do código existente.
 
 Após instalar, abra sua IDE e diga:
 
@@ -204,9 +203,11 @@ Com o perfil **Wize Security** instalado, a persona `red-teamer` roda um pentest
 npx wize-dev-kit install         # setup interativo
 npx wize-dev-kit update          # atualiza um kit instalado para a versão atual
 npx wize-dev-kit sync            # re-renderiza os adapters de IDE após editar a config
+npx wize-dev-kit list            # lista agentes nativos + customizados
 npx wize-dev-kit agent list      # lista agentes nativos + customizados
 npx wize-dev-kit agent create    # cria um novo agente customizado (validado + dry-run)
 npx wize-dev-kit agent edit <code>  # sobrescreve um agente nativo
+npx wize-dev-kit workflow <create|list>  # cria ou lista workflows customizados
 npx wize-dev-kit doctor          # diagnostica kit / projeto / adapters / gates
 npx wize-dev-kit validate        # checagens estruturais nos assets do kit
 npx wize-dev-kit document-project [quick|initial_scan|full_rescan|deep_dive] [--resume] [--target <path>]

package/ROSTER.md

@@ -10,16 +10,24 @@
 | 1 | **Wizer** | `wize-orchestrator` | Orchestrator / Knowledge Base / Briefing | All | "I know the qwize methodology, I know the project — I activate the right agent." Style: host, picks, routes. Tools: global. | (none — orchestrator role surfaces only in BMAD's `party-mode`) |
 | 2 | **Pepper Potts** | `wize-agent-analyst` | Business Analyst | 1 — Analysis | "Relentless efficiency." Brainstorming, market research, product brief, PR/FAQ, ROI, stakeholder map. Style: pragmatic, anticipates, connects business → tech. | Mary (`bmad-agent-analyst`) |
 | 3 | **Peggy Carter** | `wize-agent-tech-writer` | Technical Writer | Transversal (1–4) | "Structure, audience, clarity." DITA, CommonMark, OpenAPI, READMEs, runbooks. Style: organized, didactic, technical but accessible. | Paige (`bmad-agent-tech-writer`) |
-| 4 | **Maria Hill** | `wize-agent-pm` | Product Manager | 2 — Planning | "Mission first." PRD, epics, sprint planning, deadline enforcement. Style: military discipline, no excuses, outcome-focused. | John (`bmad-agent-pm`) |
+| 4 | **Maria Hill** | `wize-agent-pm` | Product Manager | 2 — Planning | "Mission first." PRD, validation, sprint planning, sprint status, correct-course, deadline enforcement (epics/stories are Tony's). Style: military discipline, no excuses, outcome-focused. | John (`bmad-agent-pm`) |
 | 5 | **Mantis** | `wize-agent-ux-designer` | UX Designer (Whiteport Strategic UX v0.4.3) | 2–3 | "I feel the user before I sketch." Jobs-to-be-done, journeys, empathy mapping, design tokens, IA, design system. Style: research-heavy, qualitative, empathic narrative. | Sally (`bmad-agent-ux-designer`) — replaced with Whiteport methodology |
 | 6 | **Nick Fury** | `wize-agent-solution-strategist` | Solution Strategy / Tech Vision | 2 → 3 (boundary) | "People > Objective." Big-picture, NFRs, stack family, principles, strategic trade-offs. Style: authoritative, direct, few words. | (partial) Winston — strategic side |
 | 7 | **Tony Stark** | `wize-agent-architect` | System Architect | 3 — Solutioning | "I build the thing." System design, components, ADRs, prototyping, pattern selection. Style: confident, irreverent, shows with code. | Winston (`bmad-agent-architect`) — systemic side |
 | 8 | **Hawkeye** | `wize-agent-test-architect` | Test Architect (TEA) | Transversal (gates in 2, 3, 4) | "I always hit where it hurts." Risk profile, test design, traceability, NFR assessment, review, gate decision. Style: pragmatic, edge-case hunter, focused on what matters. | (new — does not exist in BMAD core; inspired by BMAD-Method v5 TEA) |
 | 9 | **Shuri** | `wize-agent-dev` | Senior Developer | 4 — Implementation | "Wakanda forever — now it compiles." TDD red-green-refactor, security, performance. Style: genius innovator, fast, clean code, protective of the ecosystem. | Amelia (`bmad-agent-dev`) |
 
+## Security overlay (opt-in)
+
+Installs only with the `security-overlay` profile.
+
+| # | Persona | Code | Role | Phase | Motto / Style | BMAD equiv. |
+|---|---|---|---|---|---|---|
+| 10 | **red-teamer** | `wize-sec-red-teamer` | AI Pentester | Overlay | "Only what you're authorized to touch." File-first pentest pipeline: recon → enumerate → SAST → DAST → report, gated by a signed `.wize/security/scope.md`. Default passive; exploits opt-in via `--active`; every refusal audited. Hawkeye/TEA validates the overlay's implementation stories. | (new — no BMAD core equivalent) |
+
 ## Notes
 
 - **Visual theme:** emoji icons (📊 🛡️ 🦾 etc.) are placeholders; a full visual identity will be consolidated in a later phase.
 - **Agent Builder:** decided as a **skill** (`wize-create-agent`), not an agent. Wizer invokes the skill when a new persona or custom module needs to be registered.
-- **Teams:** default team is `software-development`. Optional teams (`web-dev`, `app-dev`) activate variants of Tony and Shuri per profile.
-- **Future Marvel personas (out of dev-kit scope):** Pepper is already Analyst here, Fury is already Strategist. Other Marvel personas (Black Panther, Wanda, Falcon, Vision, Riri Williams, Kamala Khan) remain reserved for future kits (Wize Ops Kit, Wize Data Kit, Wize Security Kit, etc.).
+- **Overlays add skills, not persona variants.** Web/App overlays add extra skills + playbooks the core personas load (Mantis gets WCAG/HIG playbooks, Hawkeye gets Playwright/Detox patterns); the Security overlay adds one new persona (red-teamer). There are no per-profile "variants" of Tony or Shuri in code.
+- **Future Marvel personas (out of dev-kit scope):** Pepper is already Analyst here, Fury is already Strategist. Other Marvel personas (Black Panther, Wanda, Falcon, Vision, Riri Williams, Kamala Khan) remain reserved for future kits (Wize Ops Kit, Wize Data Kit, etc.). The Security overlay's red-teamer already lives in this kit.

package/adapters/README.md

@@ -8,12 +8,12 @@ Each adapter renders the kit's agents/skills/workflows into the file layout that
 |---|---|---|---|
 | `claude-code` | `.claude/skills/wize-*/` | `SKILL.md` per agent/workflow | Default. Uses Claude Code skill folder pattern. |
 | `cursor` | `.cursor/rules/wize-*.mdc` | MDC | Each agent/skill becomes a rule file. |
-| `windsurf` | `.windsurf/agents/wize-*.md` | Markdown | Cascade-friendly. |
+| `windsurf` | `.windsurf/rules/wize-*.md` | Markdown | Cascade-friendly. |
 | `codex` | `.agents/skills/wize-*/` | `SKILL.md` per agent/workflow | OpenAI Codex. |
-| `continue` | `.continue/agents/wize-*.md` | Markdown | Continue agent slot. |
-| `kimi-code` | `.kimi/agents/wize-*.md` | Markdown | Moonshot Kimi Code. |
-| `opencode` | `.opencode/agents/wize-*.md` | Markdown | OpenCode CLI. |
-| `antigravity` | `.antigravity/agents/wize-*.md` | Markdown | Antigravity CLI + IDE. |
+| `continue` | `.continue/prompts/wize-*.prompt` | `.prompt` | Continue prompt slot. |
+| `kimi-code` | `.kimi/skills/wize-*/` | `SKILL.md` per agent/workflow | Moonshot Kimi Code. |
+| `opencode` | `.opencode/agents/wize-*.md` + `.opencode/commands/wize-*.md` | Markdown | OpenCode CLI. Native agents + commands. |
+| `antigravity` | `.agent/skills/wize-*/` | `SKILL.md` per agent/workflow | Antigravity CLI + IDE. |
 | `generic` | `.wize/agents/wize-*.md` | Markdown | Fallback for any agent that can read a folder of markdown. |
 
 ## Adapter shape

package/adapters/antigravity/README.md

@@ -1,9 +1,9 @@
 # Adapter — antigravity
 
-Antigravity CLI + IDE.
+Antigravity CLI + IDE skills.
 
-- **Target path:** `.antigravity/agents/`
-- **File pattern:** `wize-*.md`
-- **Format:** markdown
+- **Target path:** `.agent/skills/`
+- **File pattern:** `wize-*/SKILL.md`
+- **Format:** Anthropic-compatible `SKILL.md`
 
-This v0.1 adapter ships the descriptor only. Actual rendering of `wize-*` agents/skills/workflows into the target IDE format is on the v0.2 roadmap.
+Renders the Wize skills directly into the folder Antigravity loads at startup.

package/adapters/claude-code/README.md

@@ -6,4 +6,4 @@ Native Claude Code skills.
 - **File pattern:** `wize-*/SKILL.md`
 - **Format:** markdown
 
-This v0.1 adapter ships the descriptor only. Actual rendering of `wize-*` agents/skills/workflows into the target IDE format is on the v0.2 roadmap.
+Renders the Wize skills directly into the folder Claude Code loads at startup.

package/adapters/continue/README.md

@@ -1,9 +1,9 @@
 # Adapter — continue
 
-Continue agent slot.
+Continue prompt files.
 
-- **Target path:** `.continue/agents/`
-- **File pattern:** `wize-*.md`
-- **Format:** markdown
+- **Target path:** `.continue/prompts/`
+- **File pattern:** `wize-*.prompt`
+- **Format:** Continue `.prompt` (markdown with frontmatter)
 
-This v0.1 adapter ships the descriptor only. Actual rendering of `wize-*` agents/skills/workflows into the target IDE format is on the v0.2 roadmap.
+Renders each Wize agent/skill/workflow as a prompt file that Continue loads.

package/adapters/cursor/README.md

@@ -4,6 +4,6 @@ Cursor MDC rules.
 
 - **Target path:** `.cursor/rules/`
 - **File pattern:** `wize-*.mdc`
-- **Format:** markdown
+- **Format:** MDC (markdown with frontmatter)
 
-This v0.1 adapter ships the descriptor only. Actual rendering of `wize-*` agents/skills/workflows into the target IDE format is on the v0.2 roadmap.
+Renders each Wize agent/skill/workflow as an MDC rule file that Cursor picks up automatically.

package/adapters/generic/README.md

@@ -6,4 +6,4 @@ Generic markdown fallback for any AI agent runtime that can read a folder of mar
 - **File pattern:** `wize-*.md`
 - **Format:** markdown
 
-This v0.1 adapter ships the descriptor only. Actual rendering of `wize-*` agents/skills/workflows into the target IDE format is on the v0.2 roadmap.
+Renders each Wize agent/skill/workflow as a plain markdown file that any runtime can read.

package/adapters/kimi-code/README.md

@@ -1,9 +1,9 @@
 # Adapter — kimi-code
 
-Moonshot Kimi Code agents.
+Moonshot Kimi Code skills.
 
-- **Target path:** `.kimi/agents/`
-- **File pattern:** `wize-*.md`
-- **Format:** markdown
+- **Target path:** `.kimi/skills/`
+- **File pattern:** `wize-*/SKILL.md`
+- **Format:** Anthropic-compatible `SKILL.md`
 
-This v0.1 adapter ships the descriptor only. Actual rendering of `wize-*` agents/skills/workflows into the target IDE format is on the v0.2 roadmap.
+Renders the Wize skills directly into the folder Kimi Code loads at startup.

package/adapters/opencode/README.md

@@ -1,9 +1,9 @@
 # Adapter — opencode
 
-OpenCode CLI agents.
+OpenCode CLI native agents and commands.
 
-- **Target path:** `.opencode/agents/`
+- **Target paths:** `.opencode/agents/` and `.opencode/commands/`
 - **File pattern:** `wize-*.md`
 - **Format:** markdown
 
-This v0.1 adapter ships the descriptor only. Actual rendering of `wize-*` agents/skills/workflows into the target IDE format is on the v0.2 roadmap.
+Renders each Wize agent as a native OpenCode agent in `.opencode/agents/` and each skill/workflow as a command in `.opencode/commands/`, bound to its owning persona.

package/adapters/windsurf/README.md

@@ -1,9 +1,9 @@
 # Adapter — windsurf
 
-Windsurf Cascade-friendly markdown agents.
+Windsurf Cascade-friendly markdown rules.
 
-- **Target path:** `.windsurf/agents/`
+- **Target path:** `.windsurf/rules/`
 - **File pattern:** `wize-*.md`
 - **Format:** markdown
 
-This v0.1 adapter ships the descriptor only. Actual rendering of `wize-*` agents/skills/workflows into the target IDE format is on the v0.2 roadmap.
+Renders each Wize agent/skill/workflow as a rules file that Windsurf Cascade loads.

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "wize-dev-kit",
-  "version": "0.8.0",
+  "version": "0.9.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/schemas/agent.schema.json

@@ -6,12 +6,12 @@
   "required": ["code", "name", "title", "module", "description"],
   "additionalProperties": true,
   "properties": {
-    "code": { "type": "string", "pattern": "^wize-(agent|orchestrator)-[a-z0-9-]+$|^wize-orchestrator$" },
+    "code": { "type": "string", "pattern": "^wize-(agent|orchestrator|sec)-[a-z0-9-]+$|^wize-orchestrator$" },
     "name": { "type": "string", "minLength": 1 },
     "title": { "type": "string", "minLength": 1 },
     "icon": { "type": "string" },
     "team": { "type": "string" },
-    "module": { "enum": ["orchestrator", "method", "tea", "builder", "core", "web-overlay", "app-overlay", "custom"] },
+    "module": { "enum": ["orchestrator", "method", "tea", "builder", "core", "web-overlay", "app-overlay", "security-overlay", "custom"] },
     "phase": { "type": "string" },
     "description": { "type": "string", "minLength": 10 },
     "style": {

package/schemas/workflow.schema.json

@@ -11,7 +11,7 @@
     "phase": { "type": "string" },
     "owner": { "type": "string" },
     "absorbs": { "type": "string" },
-    "overlay": { "enum": ["web", "app"] },
+    "overlay": { "enum": ["web", "app", "security"] },
     "status": { "enum": ["stub", "draft", "ready", "stable"] },
     "gate": { "enum": ["risk", "design", "trace", "nfr", "review", "gate"] },
     "when": { "type": "string" }

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

@@ -14,9 +14,13 @@ Tony drives. Output lands in `.wize/solutioning/epics/` and `.wize/solutioning/s
 
 ## 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 +109,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 +157,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-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`
@@ -107,10 +117,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).
@@ -151,6 +162,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

@@ -14,120 +14,132 @@ You are **Wizer**, the orchestrator. The user invoked `/wize-help`. Don't dump a
 
 | Invocation | What to do |
 |---|---|
-| `/wize-help` or `/wize` (no argument) | Greeting + project snapshot + the **single best next step**. |
+| `/wize-help` (no argument) | Greeting + project snapshot + the **single best next step**. |
 | `/wize-help next` | Just the next step. Skip the snapshot. |
-| `/wize-help status` | Snapshot only — phase, last TEA gate, in-flight stories. |
+| `/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
 
-Read these files if they exist (they may not — that's information too):
+Read these if they exist (absence is information too):
 
 | Path | Tells you |
 |---|---|
-| `.wize/config/project.toml` | Active profiles, IDE targets, communication & document languages, project name. |
-| `.wize/config/user.toml` | Per-developer preferences. Use `[user] name` to greet the user by name. Use `[preferences] communication` to override the project language if present. |
+| `.wize/config/project.toml` | Active profiles, IDE targets, languages, project name, `kit_version`. |
+| `.wize/config/user.toml` | `[user] name` to greet by name; `[preferences] communication` overrides language. |
 | `.wize/config/tea.toml` | TEA gate policy (advisory vs enforcing). |
-| `.wize/planning/brief.md` | Whether Phase 1 (Pepper) started. |
-| `.wize/planning/research.md` | Whether research was done. |
-| `.wize/planning/ux/trigger-map.md` | Whether WDS trigger map exists. |
-| `.wize/planning/prd.md` | Whether Phase 2 (Maria Hill) PRD exists. |
-| `.wize/planning/ux/ux-scenarios.md`, `.wize/planning/ux/ux-design/**` | Whether Mantis ran UX. |
-| `.wize/planning/tech-vision.md`, `nfr-principles.md` | Whether Fury set tech strategy. |
-| `.wize/solutioning/architecture.md` | Whether Tony's architecture exists. |
-| `.wize/solutioning/stories/**/*.md` | Whether stories are sliced. |
-| `.wize/implementation/tea/risk-profile.md` | Whether Hawkeye's risk profile is in place. |
-| `.wize/implementation/tea/**/gate.md` | Last gate decisions per story. |
-| `.wize/implementation/sprint-status.md` | Active sprint state. |
-
-## Step 2 — determine current phase
-
-Apply this heuristic, top-down. Stop at the first match.
-
-1. **No `.wize/` folder.** → Tell the user the kit isn't installed; suggest `npx wize-dev-kit install`.
-2. **No `brief.md`.** → Phase 1. Next: **Pepper / `wize-product-brief`**.
-3. **`brief.md` exists, no `trigger-map.md`.** → Still Phase 1. Next: **Pepper / `wize-trigger-map`**.
-4. **No `prd.md`.** → Phase 2. Next: **Maria Hill / `wize-create-prd`**.
-5. **`prd.md` exists, no `ux-scenarios.md`.** → Phase 2 UX. Next: **Mantis / `wize-ux-scenarios`**.
-6. **`ux-design/` empty.** → Phase 2 UX continues. Next: **Mantis / `wize-ux-design`**.
-7. **No `tech-vision.md` or `nfr-principles.md`.** → Phase 2→3 boundary. Next: **Fury / `wize-tech-vision`** then `wize-nfr-principles`.
-8. **No `architecture.md`.** → Phase 3. Next: **Tony / `wize-create-architecture`**.
-9. **No `stories/**/*.md`.** → Phase 3 still. Next: **Tony / `wize-create-epics-and-stories`**.
-10. **No `tea/risk-profile.md`.** → Phase 3 closeout. Next: **Hawkeye / `wize-tea-risk`**.
-11. **Has stories but `sprint-status.md` shows no active sprint.** → Phase 4 start. Next: **Maria Hill / `wize-sprint-planning`**.
-12. **Has active sprint, oldest in-flight story has no `tea/.../design.md`.** → Next: **Hawkeye / `wize-tea-design`** for that story.
-13. **In-flight story exists, no implementation commits.** → Next: **Shuri / `wize-dev-story`** on that story.
-14. **In-flight story exists with code, no `gate.md`.** → Next: **Hawkeye / `wize-tea-trace` → `wize-tea-review` → `wize-tea-gate`** for that story.
-15. **All sprint stories gated `PASS`/`CONCERNS`, backlog has no `ready-for-dev` left.** → Sprint ended. Next: **Wizer / `wize-retrospective`** + **Pepper+Peggy / `wize-refresh-knowledge`** (the inline knowledge notes pile up over the sprint; the refresh consolidates them into the baseline docs).
-16. **All stories gated and no new epic pulled.** → Plan next epic with Tony + Hill, or run a roadmap session.
-
-For brownfield repos where `.wize/knowledge/document-project/` is missing, prepend: "Run `wize-document-project` first to baseline the codebase."
-
-## Step 2.5 — version-skew detection (proactive)
-
-Before routing, compare:
-- `kit_version` in `.wize/config/project.toml`
-- The version of the installed kit (from `node_modules/wize-dev-kit/package.json` — *or* the version baked into the activated skills if you don't have a node-side check)
-
-If you have access to the user's terminal (Claude Code Bash tool, Codex exec, OpenCode), additionally check the npm registry with a 2-second timeout:
-
-```bash
-npm view wize-dev-kit version 2>/dev/null
-```
-
-Cases:
-- **Installed version > project.toml's `kit_version`** → suggest `npx wize-dev-kit update` (no `@latest` needed; the installed version is already newer).
-- **Registry > installed version** → suggest `npx wize-dev-kit@latest update` to pick up the newer release.
-- **All three match** → no message; carry on.
-
-Phrase it as one short line, not a banner. Example:
-
-> *"Heads up: registry has 0.2.3, you're on 0.2.2. Want me to run `npx wize-dev-kit@latest update`? (it preserves your `user.toml` and re-renders adapters)"*
+| `.wize/planning/brief.md`, `ux/trigger-map.md` | Phase 1 (Pepper) progress. |
+| `.wize/planning/prd.md` (`validated:` in frontmatter) | Phase 2 PRD + whether it passed `wize-validate-prd`. |
+| `.wize/planning/ux/ux-scenarios.md`, `ux/ux-design/**` | Whether Mantis ran UX. |
+| `.wize/planning/tech-vision.md`, `nfr-principles.md` | Whether Fury set strategy. |
+| `.wize/solutioning/architecture.md`, `stories/**/*.md`, `readiness-*.md` | Phase 3 artifacts + the readiness gate. |
+| `.wize/implementation/tea/risk-profile.md`, `tea/**/gate.md` | Risk profile + last gate per story. |
+| `.wize/implementation/sprint-status.yaml` | **Canonical** active-sprint state (NOT `.md`). |
+| `.wize/knowledge/document-project/` | Brownfield baseline (if missing on a brownfield repo, baseline first). |
+| `.wize/security/scope.md`, `report.md` | Security overlay: authorized scope + last pentest. |
+
+## Step 2 — route
+
+**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.
+
+Otherwise apply this heuristic top-down; stop at the first match:
+
+| # | State | Next step |
+|---|---|---|
+| 1 | No `.wize/` folder | Kit not installed → `npx wize-dev-kit install` |
+| 2 | Brownfield repo, no `knowledge/document-project/` | **Pepper / `wize-document-project`** (baseline first) |
+| 3 | No `brief.md` | **Pepper / `wize-product-brief`** |
+| 4 | `brief.md`, no `trigger-map.md` | **Pepper / `wize-trigger-map`** |
+| 5 | No `prd.md` | **Maria Hill / `wize-create-prd`** |
+| 6 | `prd.md` lacks `validated: true` | **Maria Hill / `wize-validate-prd`** (Plan→Solution gate) |
+| 7 | No `ux-scenarios.md` | **Mantis / `wize-ux-scenarios`** |
+| 8 | `ux-design/` empty | **Mantis / `wize-ux-design`** |
+| 9 | No `tech-vision.md`/`nfr-principles.md` | **Fury / `wize-tech-vision`** → `wize-nfr-principles` |
+| 10 | No `architecture.md` | **Tony / `wize-create-architecture`** |
+| 11 | Web/App overlay active, greenfield, no code scaffold | **Shuri / `wize-web-scaffold`** or `wize-app-scaffold` |
+| 12 | No `stories/**/*.md` | **Tony / `wize-create-epics-and-stories`** |
+| 13 | No `readiness-*.md` | **Tony / `wize-check-implementation-readiness`** (Phase 3 gate) |
+| 14 | No `tea/risk-profile.md` | **Hawkeye / `wize-tea-risk`** |
+| 15 | Stories exist, `sprint-status.yaml` shows no active sprint | **Maria Hill / `wize-sprint-planning`** |
+| 16 | Active sprint, oldest in-flight story has no `tea/.../design.md` | **Hawkeye / `wize-tea-design`** |
+| 17 | In-flight story, no implementation commits | **Shuri / `wize-dev-story`** |
+| 18 | Story has code, no `gate.md` | **Hawkeye / `wize-tea-trace` → `wize-tea-review` → `wize-tea-gate`** |
+| 19 | A story gated **FAIL**, or sprint drifting (blocked/overdue) | **Shuri fix + Maria Hill / `wize-correct-course`** |
+| 20 | All stories gated PASS/CONCERNS, no `ready-for-dev` left | Sprint ended → **Wizer / `wize-retrospective`** + **Pepper+Peggy / `wize-refresh-knowledge`** |
+| 21 | All gated, no new epic pulled | Plan next epic (Tony + Maria Hill), or a roadmap session |
+
+**Overlay ship stages** (when the profile is active): web-overlay adds `wize-web-deploy` / `wize-web-seo-audit`; app-overlay adds `wize-app-release-channels` / `wize-app-store-listing`; security-overlay adds `wize-sec-pentest` (recon → enumerate → SAST → DAST → report, gated by `.wize/security/scope.md`).
+
+## Step 2.5 — version skew (proactive)
+
+Compare `kit_version` (project.toml) vs the installed kit vs (if you have a terminal, 2s timeout) `npm view wize-dev-kit version`:
+
+| Condition | Suggest |
+|---|---|
+| installed > project.toml | `npx wize-dev-kit update` |
+| registry > installed | `npx wize-dev-kit@latest update` |
+| all match | nothing |
 
-If the user says yes and you can execute Bash, run it in the project root and stream output. Otherwise, print the command for them to run.
+Phrase as one short line, not a banner. If the user agrees and you have Bash, run it in the project root.
 
 ## Step 3 — respond
 
-Default response shape (3 lines). When `user.toml` provides a `[user] name`, include it in the greeting:
+Default shape (3 lines; greet by `user.name` when present):
 
 ```
-Welcome back{{, <user.name> when present}}. {project name} — {profiles, e.g., "Core + Web"}.
-You're at: {phase + last completed artifact}.
-Next: /{next workflow} ({persona}).
+Welcome back, [name]. {project} — {profiles}.
+You're at: {phase + last artifact}.
+Next: /{workflow} ({persona}).
 ```
 
-Concrete example with personalization filled in:
+For `status`, return a table (Phase / Profiles / Last TEA gate / In-flight stories / Active sprint / TEA policy).
 
-> Welcome back, [USER_NAME]. wize-development-kit — Core + Web.
-> You're at: Phase 3 closeout — architecture signed, no risk profile yet.
-> Next: `/wize-tea-risk` (Hawkeye).
+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 `status`, return a markdown table:
+For `mission`, emit the filled **Mission contract** (see the section below) from the Step-2 class + current project state — nothing else.
 
-```
-| Item | State |
-|---|---|
-| Phase | … |
-| Profiles | … |
-| Last TEA gate | … (PASS/CONCERNS/FAIL/WAIVED) |
-| In-flight stories | … |
-| Active sprint | … |
-| TEA policy | advisory / enforcing |
-```
+## Step 4 — offer to act
 
-For `personas`, list only personas whose role applies to active profiles. Always include Wizer, Pepper, Peggy, Maria Hill, Mantis, Fury, Tony, Hawkeye, Shuri (all are profile-independent core roles). If `web-overlay` active, note that **Mantis** has the WCAG/responsive playbook loaded and **Hawkeye** has Playwright/Vitest patterns. If `app-overlay` active, note HIG/Material 3 for Mantis and Detox/Maestro for Hawkeye.
+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).
 
-## Step 4 — offer to act
+## Mission contract (`/wize-help mission`)
 
-End every response with one of:
+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.
+
+```
+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.
+```
 
-- "Want me to call {persona}?" — if the next step is clear.
-- "Want me to baseline the repo first?" — if brownfield + no document-project.
-- "Want me to call a party-mode with {persona1} + {persona2}?" — if the next step has a cross-cutting decision.
+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 in the user's `communication` language (from `.wize/config/project.toml`).
-- One sharp question is better than three sentences of advice.
-- If the user invoked `/wize-help next`, give them just the next step in one line and stop.
-- If user invoked `/wize-help status`, give the table and stop. Don't suggest actions.
+- 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 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',
     ''
   ];