wize-dev-kit 0.11.0 → 0.12.0

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

@@ -0,0 +1,184 @@
+---
+code: wize-changelog
+description: "Use quando precisar gerar ou atualizar o changelog no formato Keep a Changelog a partir das stories concluídas."
+name: Changelog
+phase: 4-implementation
+owner: wize-agent-dev   # Shuri
+status: ready
+---
+
+# Changelog
+
+**Goal.** Gerar `CHANGELOG.md` no formato [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) a partir das stories concluídas no sprint, agrupadas por epic e categoria.
+
+Shuri executa. O changelog é gerado em pt-BR (texto voltado ao usuário) e segue a convenção do projeto.
+
+## Inputs
+
+- `.wize/implementation/sprint-status.yaml` — stories concluídas
+- `.wize/solutioning/stories/{epic}/*.md` — detalhes das stories
+- `.wize/solutioning/epics/*.md` — nomes legíveis dos epics
+- `CHANGELOG.md` — changelog existente (se houver)
+- `git tag --list 'v*' --sort=-v:refname | head -1` — última tag
+
+## Output
+
+- `CHANGELOG.md` criado ou atualizado com a nova entrada pré-pendida
+
+## Formato Keep a Changelog
+
+Seguir estritamente o formato [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/):
+
+```markdown
+# Changelog
+
+All notable changes to this project are documented here.
+Format inspired by [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [0.12.0] — 2026-08-08
+
+### Added
+- **Epic 09 — UX / intent:** Release e changelog skills (`wize-release`, `wize-changelog`). #E09-S07
+
+### Changed
+- **Epic 09 — UX / intent:** Roteamento por intenção expandido com release/changelog. #E09-S03
+
+### Fixed
+- **Epic 09 — UX / intent:** Descrições de skill corrigidas (block scalars). #E09-S01
+
+### Security
+- (vazio se não houver stories de segurança)
+```
+
+### Regras de categoria
+
+| Categoria | Quando usar |
+|---|---|
+| **Added** | Nova feature, nova skill, nova funcionalidade |
+| **Changed** | Mudança em funcionalidade existente, alteração de comportamento |
+| **Deprecated** | Funcionalidade que será removida em breve |
+| **Removed** | Funcionalidade removida |
+| **Fixed** | Correção de bug |
+| **Security** | Correção de vulnerabilidade, melhoria de segurança |
+
+### Regras de agrupamento
+
+- Agrupar por **epic** dentro de cada categoria.
+- Cada linha começa com `- **Epic NN — Nome:**` seguido da descrição e `#story_id`.
+- Stories sem epic definido vão sob `- **Geral:**`.
+- Se uma categoria não tiver stories, escrever `- (vazio)` ou omitir (consistente com o changelog existente).
+
+## Steps
+
+### 1. Coletar stories concluídas
+
+Ler `sprint-status.yaml`. Para cada story com status `done`:
+
+1. Localizar o arquivo em `.wize/solutioning/stories/{epic}/{story}.md`
+2. Extrair do frontmatter: `story_id`, `epic`
+3. Extrair do corpo: título (linha `# Story:`) e primeira frase da seção `## Context` como sumário
+
+Se o arquivo da story não existir, usar apenas o `story_id` como referência.
+
+### 2. Classificar por categoria
+
+Para cada story, determinar a categoria com base no conteúdo:
+
+| Padrão no título/contexto | Categoria |
+|---|---|
+| "Adicionar", "Criar", "Novo", "Added", "Add" | Added |
+| "Corrigir", "Consertar", "Bug", "Fix", "Hotfix", "Correção" | Fixed |
+| "Alterar", "Mudar", "Refatorar", "Change", "Update" | Changed |
+| "Remover", "Deprecar" | Removed / Deprecated |
+| "Segurança", "Vulnerabilidade", "Security", "CVE" | Security |
+
+Se ambíguo, default `Added` para stories novas, `Changed` para alterações.
+
+### 3. Agrupar por epic
+
+Para cada story, resolver o nome do epic:
+
+1. Se o frontmatter tem `epic: NN-nome`, usar `Epic NN — Nome`
+2. Buscar em `.wize/solutioning/epics/{epic}.md` o título (`# Epic NN: Nome`)
+3. Fallback: `Epic {epic_id}`
+
+Agrupar stories por epic, depois por categoria.
+
+### 4. Gerar entrada do changelog
+
+Montar a entrada no formato:
+
+```markdown
+## [{version}] — {YYYY-MM-DD}
+
+{descrição curta do release — 1-2 frases sobre o que esta versão entrega}
+
+### Added
+- **{epic_nome}:** {descrição}. #{story_id}
+
+### Changed
+- **{epic_nome}:** {descrição}. #{story_id}
+
+### Fixed
+- **{epic_nome}:** {descrição}. #{story_id}
+
+### Security
+- **{epic_nome}:** {descrição}. #{story_id}
+```
+
+### 5. Atualizar CHANGELOG.md
+
+Se `CHANGELOG.md` não existir, criar com o cabeçalho padrão:
+
+```markdown
+# Changelog
+
+All notable changes to this project are documented here.
+Format inspired by [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+> **Language:** entries are written in **Portuguese (pt-BR)**.
+
+## [Unreleased]
+```
+
+Se existir:
+1. Localizar a linha `## [Unreleased]`
+2. Inserir a nova entrada entre `## [Unreleased]` e a primeira `## [versão]` existente
+3. Se não houver `## [Unreleased]`, inserir após o cabeçalho
+
+### 6. Verificar formatação
+
+- A data está no formato `YYYY-MM-DD`
+- A versão segue semver (`X.Y.Z`)
+- Cada story tem referência ao `#story_id`
+- Categorias vazias foram omitidas
+- O link do Keep a Changelog está presente
+
+## Exemplo de saída
+
+```markdown
+## [0.12.0] — 2026-08-08
+
+Release do cluster de ship: skills de release e changelog para o perfil core, roteamento por intenção expandido.
+
+### Added
+- **Epic 09 — UX / intent:** Skill `wize-release` para bump de versão, changelog e tag git a partir das stories gated. #E09-S07
+- **Epic 09 — UX / intent:** Skill `wize-changelog` para geração de changelog no formato Keep a Changelog. #E09-S07
+
+### Changed
+- **Epic 09 — UX / intent:** Tabela de roteamento por intenção expandida com release, changelog, lançar, publicar, notas de versão. #E09-S03
+```
+
+## Anti-patterns
+
+- Changelog escrito à mão sem referência às stories — perde rastreabilidade.
+- Categoria "Added" para correção de bug — usar "Fixed".
+- Data fora do formato ISO — usar `YYYY-MM-DD`.
+- Pular stories concluídas — toda story `done` no sprint entra no changelog.
+- Escrever changelog em inglês quando o projeto usa pt-BR — seguir o idioma do changelog existente.
+
+## Hand-off
+
+> Changelog atualizado em `CHANGELOG.md`. {count} stories de {epic_count} epics registradas. Próximo: `/wize-release` para bump de versão e tag, ou revisão manual do changelog.

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

@@ -1,5 +1,7 @@
 ---
+
 code: wize-checkpoint-preview
+description: "Use quando uma story estiver parcialmente implementada e precisar de preview de checkpoint para validar direção antes de continuar."
 name: Checkpoint Preview
 phase: 4-implementation
 owner: wize-agent-dev   # Shuri (+ wize-agent-architect Tony on call)

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

@@ -1,5 +1,7 @@
 ---
+
 code: wize-code-review
+description: "Use quando um PR estiver aberto e precisar de revisão de código por pares focada em saúde do código."
 name: Code Review
 phase: 4-implementation
 owner: wize-agent-dev   # Shuri (peer review)

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

@@ -1,5 +1,7 @@
 ---
+
 code: wize-correct-course
+description: "Use quando o projeto desviar do plano e precisar de correção de curso com decisão documentada."
 name: Correct Course
 phase: 4-implementation
 owner: wize-agent-pm   # Maria Hill, with wize-orchestrator

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

@@ -1,5 +1,7 @@
 ---
+
 code: wize-create-story
+description: "Use quando um epic estiver definido e precisar criar uma story individual com acceptance criteria detalhados."
 name: Create Story
 phase: 4-implementation
 owner: wize-agent-architect   # Tony writes; Shuri may refine

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

@@ -1,5 +1,7 @@
 ---
+
 code: wize-dev-story
+description: "Use quando uma story estiver pronta para implementação e precisar ser desenvolvida com TDD e commits rastreáveis."
 name: Dev Story
 phase: 4-implementation
 owner: wize-agent-dev   # Shuri
@@ -14,7 +16,7 @@ Shuri drives. Hawkeye observes (test design is binding). Tony stays available fo
 
 ## 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`).
+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 mission` or `/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.

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

@@ -1,5 +1,7 @@
 ---
+
 code: wize-investigate
+description: "Use quando um bug ou comportamento inesperado surgir e precisar de investigação estruturada com root cause analysis."
 name: Investigate
 phase: 4-implementation
 owner: wize-agent-dev   # Shuri (+ wize-agent-test-architect Hawkeye on call)

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

@@ -1,5 +1,7 @@
 ---
+
 code: wize-quick-dev
+description: "Use quando a demanda for pequena e bem delimitada (bug fix, copy edit, refactor) e não justificar o ciclo completo."
 name: Quick Dev (lifecycle shortcut)
 phase: 4-implementation
 owner: wize-agent-dev   # Shuri

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

@@ -0,0 +1,162 @@
+---
+code: wize-release
+description: "Use quando todas as stories do sprint estiverem gated e você precisar gerar release: bump de versão, changelog e tag git."
+name: Release
+phase: 4-implementation
+owner: wize-agent-dev   # Shuri + Maria Hill
+status: ready
+---
+
+# Release
+
+**Goal.** Bump de versão, changelog a partir das stories gated e tag git. O release é o passo entre "todas as stories passaram no gate" e a retrospectiva.
+
+Shuri executa. Maria Hill confirma o escopo (quais epics entram).
+
+## Pré-requisitos
+
+Antes de iniciar, verificar:
+
+1. **Sprint ativo** — `sprint-status.yaml` deve ter `development_status` com stories.
+2. **Todas as stories gated** — cada story no sprint ativo deve estar `done` no `sprint-status.yaml`. Stories com gate `FAIL` bloqueiam o release. Stories com `CONCERNS` precisam de waiver documentado.
+3. **Git limpo** — `git status --porcelain` deve estar vazio (ou conter apenas arquivos não rastreados que não fazem parte do release).
+4. **Branch main** — releases saem da `main`. Se estiver em feature branch, abortar e orientar merge via PR.
+
+Se qualquer pré-requisito falhar, reportar o bloqueio e parar. Não fazer release parcial.
+
+## Inputs
+
+- `.wize/implementation/sprint-status.yaml` — stories concluídas
+- `.wize/solutioning/stories/{epic}/*.md` — detalhes das stories
+- `package.json` — versão atual
+- `CHANGELOG.md` — changelog existente (se houver)
+- `git tag --list 'v*'` — tags existentes
+
+## Outputs
+
+- `package.json` com versão atualizada
+- `CHANGELOG.md` atualizado com a nova versão
+- Tag git `v{semver}`
+- `sprint-status.yaml` atualizado (sprint marcado como concluído)
+- Resumo do release no terminal
+
+## Steps
+
+### 1. Verificar pré-requisitos
+
+```bash
+git status --porcelain  # deve estar vazio
+git branch --show-current  # deve ser main
+```
+
+Ler `sprint-status.yaml` e validar que todas as stories do sprint ativo estão `done`. Se houver stories `backlog`, `ready-for-dev`, `in-progress` ou `review`, listar cada uma e abortar.
+
+### 2. Coletar stories concluídas
+
+Varrer `development_status` no `sprint-status.yaml`. Para cada story com status `done`:
+
+1. Localizar o arquivo da story em `.wize/solutioning/stories/{epic}/{story}.md`
+2. Extrair do frontmatter: `story_id`, `epic`, `status`
+3. Extrair do corpo: título (linha `# Story:`), acceptance criteria
+
+Agrupar por epic. Se o epic tiver `epic_id` no `sprint-status.yaml`, usar o nome do arquivo do epic em `.wize/solutioning/epics/` para obter o título legível.
+
+### 3. Determinar o bump de versão
+
+Ler a versão atual de `package.json`:
+
+```
+Versão atual: 0.11.0
+Qual o bump?
+  1. patch (0.11.1) — correções, hotfix, docs
+  2. minor (0.12.0) — novas features compatíveis
+  3. major (1.0.0) — breaking changes
+```
+
+Em modo interativo, perguntar ao usuário. Em modo não-interativo, usar o primeiro argumento (`patch`, `minor` ou `major`). Se nenhum argumento for passado, default `patch`.
+
+Calcular a nova versão com `semver.inc(current, bump)` — usar Node built-in (regex parse + increment, sem dependência externa).
+
+### 4. Gerar changelog
+
+Delegar a geração do changelog ao `wize-changelog`:
+
+1. Invocar o fluxo do `wize-changelog` com a nova versão e a lista de stories coletadas no passo 2.
+2. O changelog é gerado no formato Keep a Changelog e pré-pendido ao `CHANGELOG.md`.
+
+Se `CHANGELOG.md` não existir, criar com o cabeçalho padrão.
+
+### 5. Bump de versão
+
+Atualizar o campo `version` em `package.json` com a nova versão. Preservar a formatação existente (indentação, aspas duplas).
+
+### 6. Commit e tag
+
+```bash
+git add package.json CHANGELOG.md
+git commit -m "chore: release v{version}"
+git tag v{version} -m "Release v{version}"
+```
+
+A mensagem de commit deve listar os epics incluídos no release.
+
+### 7. Atualizar sprint-status.yaml
+
+Adicionar ao `sprint-status.yaml`:
+
+```yaml
+release:
+  version: "{version}"
+  date: "{YYYY-MM-DD}"
+  sprint: "{active_cycle}"
+  stories_released: {count}
+```
+
+Marcar o sprint como concluído e adicionar entrada de retrospectiva pendente.
+
+### 8. Resumo
+
+Emitir no terminal:
+
+```
+✓ Release v{version} criado
+
+Epics incluídos:
+  - {epic_name} ({story_count} stories)
+
+Changelog: CHANGELOG.md
+Tag: v{version}
+Commit: {commit_hash}
+
+Próximos passos:
+  - git push origin main --tags
+  - /wize-retrospective
+```
+
+**Não executar `git push` automaticamente.** O push é sempre manual — o desenvolvedor revisa antes de publicar.
+
+## Bump semver (built-in, zero-dep)
+
+```js
+function bumpVersion(current, type) {
+  const [major, minor, patch] = current.split('.').map(Number);
+  switch (type) {
+    case 'major': return `${major + 1}.0.0`;
+    case 'minor': return `${major}.${minor + 1}.0`;
+    case 'patch': return `${major}.${minor}.${patch + 1}`;
+    default: throw new Error(`Tipo de bump inválido: ${type}. Use patch, minor ou major.`);
+  }
+}
+```
+
+## Anti-patterns
+
+- Fazer release com stories não gated — o gate existe para proteger a main.
+- Fazer release de feature branch — releases saem da main.
+- Push automático — o desenvolvedor revisa antes de publicar.
+- Pular o changelog — "depois eu escrevo" = nunca escreve.
+- Bump manual de versão — usar o bump semver para evitar off-by-one.
+
+## Hand-off
+
+> Release v{version} criado. Changelog atualizado, tag aplicada. Execute `git push origin main --tags` quando revisar. Depois: `/wize-retrospective`.

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

@@ -1,5 +1,7 @@
 ---
+
 code: wize-retrospective
+description: "Use quando o sprint terminar e precisar de retrospectiva facilitada com todo o time."
 name: Retrospective
 phase: 4-implementation
 owner: wize-orchestrator   # Wizer facilitates; whole team contributes

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

@@ -1,5 +1,7 @@
 ---
+
 code: wize-sprint-planning
+description: "Use quando um novo sprint começar e precisar planejar as stories, prioridades e capacidade do time."
 name: Sprint Planning
 phase: 4-implementation
 owner: wize-agent-pm   # Maria Hill

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

@@ -1,5 +1,7 @@
 ---
+
 code: wize-sprint-status
+description: "Use quando precisar verificar o status atual do sprint — stories concluídas, em progresso e bloqueios."
 name: Sprint Status
 phase: 4-implementation
 owner: wize-agent-pm   # Maria Hill

package/src/method-skills/module.yaml

@@ -99,21 +99,30 @@ agents:
 
 # Notable skills shipped by method (discovery is automatic via workflow.md/skill.md walkers).
 skills:
+  - code: wize-research
+    name: "Research"
+    description: "Use quando precisar pesquisar algo mas não souber qual tipo de pesquisa se aplica."
   - code: wize-market-research
     name: "Market Research"
-    description: "Competition and customer research for the product brief and PRD."
+    description: "Use quando precisar pesquisar mercado, concorrentes, tendências ou posicionamento."
   - code: wize-domain-research
     name: "Domain Research"
-    description: "Industry, regulatory, and technical-trend research."
+    description: "Use quando precisar pesquisar um domínio de negócio, indústria ou setor."
   - code: wize-technical-research
     name: "Technical Research"
-    description: "Technology, architecture, and implementation-pattern research."
+    description: "Use quando precisar pesquisar tecnologias, stacks, bibliotecas ou decisões técnicas."
   - code: wize-create-architecture
     name: "Create Architecture"
     description: "Collaborative step-by-step architecture design with 8 steps."
   - code: wize-code-review
     name: "Code Review"
     description: "Adversarial code review with parallel layers and structured triage."
+  - code: wize-release
+    name: "Release"
+    description: "Use quando todas as stories estiverem gated e precisar gerar release: bump de versão, changelog e tag git."
+  - code: wize-changelog
+    name: "Changelog"
+    description: "Use quando precisar gerar ou atualizar o changelog no formato Keep a Changelog a partir das stories concluídas."
 
 # Phase directories (declarative discovery for the installer):
 phases:

package/src/orchestrator-skills/module.yaml

@@ -13,9 +13,12 @@ agents:
     description: "Knows the user deeply, parses raw demand, routes to the right specialist. Speaks like a thoughtful host: warm welcome, sharp question, clear handoff."
 
 skills:
+  - code: wize
+    name: "Wizer"
+    description: "Primary entry point. Alias for wize-help. Project-state-aware help. Reads .wize/ and tells the user what to do next."
   - code: wize-help
     name: "Help (Wizer)"
-    description: "Project-state-aware help. Reads .wize/ and tells the user what to do next. Modes: default, next, status, personas."
+    description: "Canonical help skill. Project-state-aware help. Reads .wize/ and tells the user what to do next. Modes: default, next, status, personas."
   - code: wize-onboarding
     name: "Onboarding"
     description: "Post-install triage: greenfield vs brownfield, profile, objective. Delegates to specialists."

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

@@ -0,0 +1,164 @@
+---
+
+code: wize
+description: "Use quando o usuário invocar /wize — alias canônico para /wize-help com o mesmo comportamento."
+name: Wizer
+module: orchestrator
+owner: wize-orchestrator
+status: ready
+aliases: [wize-help]
+---
+
+# Wizer · `/wize`
+
+You are **Wizer**, the orchestrator. The user invoked `/wize` (canonical alias: `/wize-help`). Don't dump a menu — read the project's state and give a short, actionable answer in the user's voice.
+
+This is a thin alias for `/wize-help`. Delegate all behavior to the `wize-help` skill. The two invocations are identical in every way.
+
+## Modes
+
+| Invocation | What to do |
+|---|---|
+| `/wize` (no argument) | Greeting + project snapshot + the **single best next step**. |
+| `/wize next` | Just the next step. Skip the snapshot. |
+| `/wize status` | Snapshot only. For full sprint detail, route `/wize-sprint-status` (Maria Hill). |
+| `/wize personas` | List only the personas relevant to the active profiles. |
+| `/wize 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 if they exist (absence is information too):
+
+| Path | Tells you |
+|---|---|
+| `.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`, `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, trivially scoped, 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 routing below: intent first, phase heuristic as fallback. |
+
+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.
+
+### Step 2a — intent-based routing (check first)
+
+When the user's message contains a clear intent phrase, route directly to the matching skill. The intent table maps user language to skills. Match is case-insensitive and substring-based — "quero pesquisar concorrência" matches `wize-market-research` because "pesquisar concorrência" is in the table.
+
+If multiple intents match, pick the most specific (longest phrase match). If still ambiguous, ask one clarifying question. In text-only harnesses, ask that question. In rich-UI harnesses, offer a menu of the matching options.
+
+**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.
+
+### Step 2b — phase heuristic (fallback)
+
+When intent is ambiguous or no intent phrase matches, 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`).
+
+### Intent routing table
+
+See the full intent routing table in `wize-help/skill.md` (Step 2a). The same table applies to `/wize` — intent-based routing is checked first, phase heuristic is the fallback.
+
+## 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 |
+
+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 shape (3 lines; greet by `user.name` when present):
+
+```
+Welcome back, [name]. {project} — {profiles}.
+You're at: {phase + last artifact}.
+Next: /{workflow} ({persona}).
+```
+
+For `status`, return a table (Phase / Profiles / Last TEA gate / In-flight stories / Active sprint / TEA policy).
+
+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 **Natasha Romanoff** (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) · "Want me to grill you first (`wize-grill`)?" (fuzzy demand heading into an authoring step).
+
+## Mission contract (`/wize 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 next` → just the next step, one line. `/wize status` → the table, no actions. `/wize mission` → the filled Mission contract only.