wize-dev-kit 0.10.1 → 0.12.0

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
@@ -48,7 +50,7 @@ Going over 60 minutes is a sign the retro became therapy. Time-box.
 ### 1. Open with stats
 
 Wizer reads the sprint dashboard from `sprint-status.md`:
-- Velocity vs commitment.
+- Stories committed vs shipped (a count, not a velocity metric — we don't estimate).
 - Number of gates: PASS / CONCERNS / FAIL / WAIVED.
 - Blockers and their resolution times.
 - Carry-over count.
@@ -102,9 +104,9 @@ attendees: [Hill, Tony, Mantis, Pepper, Fury, Hawkeye, Shuri]
 - Mantis' "before/after" recordings in PRs accelerated review.
 
 ## Didn't work
-- Sprint-status entries went stale on Days 7–8 (Hill on vacation).
-- E02-S02 estimated M, actually L; we over-committed.
-- Vendor outage with no fallback caught us cold for 4h.
+- Sprint-status entries went stale mid-sprint (Hill on vacation).
+- E02-S02 was too big for one PR and should have been sliced; it stalled the sprint.
+- Vendor outage with no fallback caught us cold.
 
 ## Surprised us
 - A11y audit caught 3 issues on a screen Mantis had already signed off on (axe found dynamic-content edge cases).
@@ -113,7 +115,7 @@ attendees: [Hill, Tony, Mantis, Pepper, Fury, Hawkeye, Shuri]
 ## Changes for Sprint 8
 
 1. **Sprint-status delegation rotation** — when Hill is OOO, Wizer takes over. *Owner: Wizer. By: Sprint 8 Day 1.*
-2. **L estimates require justification** — any L gets one paragraph "why L not M" in the story file. *Owner: Tony. By: Sprint 8 planning.*
+2. **Slice-check every story at planning** — any story that can't be described as a single PR gets split before it's pulled. *Owner: Tony. By: Sprint 8 planning.*
 3. **Vendor fallback drill** — quarterly, simulate top-3 vendor outages. *Owner: Hawkeye + Tony. By: end of Q3.*
 
 ## Decisions made

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
@@ -12,6 +14,8 @@ status: ready
 
 Maria Hill chairs. Tony advises on slicing. Hawkeye flags risk. Shuri commits to the load.
 
+> **No estimates.** Plan by story count and priority, never by velocity, points, or person-day math. Estimates only burn time and tokens. Pull what fits, keep a buffer, and let shipped-vs-committed counts (not a velocity number) tell you next time.
+
 ## Inputs
 
 - Story backlog: `.wize/solutioning/stories/`
@@ -26,10 +30,10 @@ Maria Hill chairs. Tony advises on slicing. Hawkeye flags risk. Shuri commits to
 
 ## Steps
 
-1. **Look back** — what shipped, what slipped, what surprised.
-2. **Refresh capacity** — person-days × utilization − overhead.
+1. **Look back** — what shipped, what slipped, what surprised (counts, not velocity).
+2. **Gauge availability** — who's around this interval and who's out. No person-day math.
 3. **Pull stories** — continuation first, then priority, then risk.
-4. **Reserve 10–15% buffer** for unknowns.
+4. **Leave slack** for unknowns — pull fewer stories than feel possible, not a padded number.
 5. **Walk the gate plan** — design/trace/review/gate per story.
 6. **Commit** — verbal + written into YAML.
 
@@ -65,11 +69,12 @@ development_status:
 
 ## Anti-patterns
 
-- Optimistic velocity.
+- Estimating — velocity, points, or person-days. Just don't.
+- Over-committing because "it looks like it fits."
 - Stories without owners.
 - Stretch goals that are really plan.
 - Pulling blocked dependencies.
-- Zero buffer.
+- Zero slack.
 
 ## Hand-off
 
@@ -83,4 +88,4 @@ development_status:
 >
 > `/loop /wize-dev-story` drives one story at a time: TDD red-green-refactor, AC IDs in commits, `tea-design.md` contract, knowledge update on the 5 baseline axes, and a clean gate at the end. `/loop` keeps it going across the sprint's `ready-for-dev` queue until the user pauses.
 >
-> Next: `/wize-sprint-status` (Maria Hill) to acompanhar o progresso.
+> Next: `/wize-sprint-status` (Maria Hill) to track progress.

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.

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

@@ -1,9 +1,12 @@
 ---
+
 code: wize-help
+description: "Use quando o usuário invocar /wize-help para obter snapshot do projeto e o próximo passo recomendado."
 name: Help (Wizer)
 module: orchestrator
 owner: wize-orchestrator
 status: ready
+aliases: []
 ---
 
 # Wizer · `/wize-help`
@@ -41,18 +44,40 @@ Read these if they exist (absence is information too):
 
 ## Step 2 — route
 
+### Step 2a — first-run detection (check before anything else)
+
+If `.wize/planning/brief.md` does NOT exist AND `.wize/knowledge/document-project/` has no `.md` files, this is a **first run**. Do NOT apply the phase heuristic or intent routing. Instead:
+
+> "O que você está construindo?"
+
+Wait for the answer. Classify as greenfield or brownfield, then route:
+- **Greenfield** → **Pepper / `wize-product-brief`**
+- **Brownfield** → **Pepper / `wize-document-project`**
+
+If ambiguous, ask one clarifying question: "Is this a new project or an existing codebase?" Then route. Never show a menu on first run.
+
+### Step 2b — classify the demand (not a first run)
+
 **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. |
+| **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 2c — 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.
 
-Otherwise apply this heuristic top-down; stop at the first match:
+### Step 2d — 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 |
 |---|---|---|
@@ -75,11 +100,107 @@ Otherwise apply this heuristic top-down; stop at the first match:
 | 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 |
+| 20 | All stories gated PASS/CONCERNS, no `ready-for-dev` left, no release tag for this sprint | **Shuri + Maria Hill / `wize-release`** (bump + changelog + tag) |
+| 21 | Release tagged, retrospective not done | **Wizer / `wize-retrospective`** + **Pepper+Peggy / `wize-refresh-knowledge`** |
+| 22 | 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
+
+Match is case-insensitive, substring-based. Longest match wins. When no intent matches, fall back to the phase heuristic (Step 2b).
+
+**Research:**
+| Intent phrases | Skill |
+|---|---|
+| "pesquisar mercado", "market research", "concorrência", "competidores", "competition" | `wize-market-research` |
+| "pesquisar domínio", "domain research", "entender o domínio", "domain", "indústria", "industry" | `wize-domain-research` |
+| "pesquisar tecnologia", "tech research", "technical research", "stack research", "ferramentas" | `wize-technical-research` |
+| "pesquisar" (genérico, sem qualificador específico) | `wize-research` (dispatcher) |
+| "PR/FAQ", "press release", "working backwards" | `wize-prfaq` |
+| "documentar projeto", "baseline", "brownfield", "document project" | `wize-document-project` |
+| "trigger map", "mapear gatilhos", "trigger" | `wize-trigger-map` |
+| "refresh knowledge", "atualizar conhecimento", "consolidar docs" | `wize-refresh-knowledge` |
+
+**Planning:**
+| Intent phrases | Skill |
+|---|---|
+| "criar brief", "product brief", "briefing", "brief do produto" | `wize-product-brief` |
+| "criar prd", "PRD", "requisitos", "especificação", "product requirements" | `wize-create-prd` |
+| "validar prd", "revisar prd", "validate prd", "prd validation" | `wize-validate-prd` |
+| "editar prd", "atualizar prd", "mudar prd", "edit prd" | `wize-edit-prd` |
+| "cenários de UX", "ux scenarios", "cenários de uso", "user scenarios" | `wize-ux-scenarios` |
+| "design de interface", "ux design", "design system", "interface", "wireframe", "layout" | `wize-ux-design` |
+
+**Architecture:**
+| Intent phrases | Skill |
+|---|---|
+| "arquitetura", "architecture", "ADR", "decisão técnica", "design do sistema", "componentes" | `wize-create-architecture` |
+| "tech vision", "visão técnica", "north star", "stack decision", "stack family" | `wize-tech-vision` |
+| "NFR", "non-functional", "requisitos não-funcionais", "nfr principles", "performance", "segurança", "a11y", "accessibility" | `wize-nfr-principles` |
+| "epics", "stories", "histórias", "épicos", "slice", "fatiar", "criar stories" | `wize-create-epics-and-stories` |
+| "design system", "tokens", "component library", "biblioteca de componentes" | `wize-design-system` |
+| "project context", "contexto do projeto", "consolidar artefatos" | `wize-project-context` |
+| "readiness", "pronto para implementar", "implementation readiness", "gate de solução" | `wize-check-implementation-readiness` |
+
+**Implementation:**
+| Intent phrases | Skill |
+|---|---|
+| "corrigir bug", "bug fix", "consertar", "hotfix", "arrumar", "corrigir erro" | `wize-quick-dev` |
+| "implementar story", "dev story", "codar", "desenvolver", "implementar", "fazer story" | `wize-dev-story` |
+| "code review", "revisar código", "revisão de código", "peer review" | `wize-code-review` |
+| "investigar", "debug", "problema", "root cause", "causa raiz", "regressão" | `wize-investigate` |
+| "checkpoint", "validar direção", "mid-story check" | `wize-checkpoint-preview` |
+| "criar story", "nova story", "author story", "escrever story" | `wize-create-story` |
+| "sprint planning", "planejar sprint", "planejamento", "plan sprint" | `wize-sprint-planning` |
+| "sprint status", "status do sprint", "como está o sprint" | `wize-sprint-status` |
+| "correct course", "corrigir curso", "sprint drifting", "desbloquear" | `wize-correct-course` |
+| "release", "lançar", "publicar", "deploy core", "bump versão", "tag", "shipping" | `wize-release` |
+| "changelog", "notas de versão", "release notes", "gerar changelog" | `wize-changelog` |
+
+**Testing:**
+| Intent phrases | Skill |
+|---|---|
+| "test design", "tea design", "desenhar testes", "test contract", "contrato de teste" | `wize-tea-design` |
+| "gate decision", "tea gate", "decisão de gate", "pass/fail" | `wize-tea-gate` |
+| "risk profile", "perfil de risco", "matriz de risco", "tea risk" | `wize-tea-risk` |
+| "traceability", "trace", "rastreabilidade", "AC trace", "cobertura de AC" | `wize-tea-trace` |
+| "story review", "tea review", "revisão de story", "auditoria de AC" | `wize-tea-review` |
+| "NFR assessment", "avaliação de NFR", "tea nfr", "verificar NFR" | `wize-tea-nfr` |
+| "e2e", "end-to-end", "testes automatizados", "gerar testes e2e", "testes de interface" | `wize-qa-generate-e2e-tests` |
+
+**Security:**
+| Intent phrases | Skill |
+|---|---|
+| "pentest", "security test", "teste de segurança", "vulnerabilidade", "scan de segurança", "security scan" | `wize-sec-pentest` |
+| "security recon", "reconhecimento", "mapear superfície" | `wize-sec-recon` |
+| "enumerate", "enumeração", "surface enumeration", "levantar tech" | `wize-sec-enumerate` |
+| "criar escopo", "definir escopo", "scope security", "escopo de segurança", "scope de pentest" | `wize-sec-scope` |
+
+**Meta:**
+| Intent phrases | Skill |
+|---|---|
+| "help", "ajuda", "o que fazer", "próximo passo", "what next" | Show status + next step (no skill dispatch) |
+| "status", "como estamos", "onde estamos", "progresso" | Show sprint status / project snapshot |
+| "retrospective", "retrospectiva", "retro", "lições aprendidas" | `wize-retrospective` |
+| "personas", "quem faz o quê", "roster", "equipe" | List personas relevant to active profiles |
+| "mission", "missão", "contrato", "mission contract" | Emit filled mission contract |
+| "grill", "sabatinar", "questionar", "afiar", "elicitation" | `wize-grill` |
+| "brainstorm", "brainstorming", "ideias", "chuva de ideias" | `wize-brainstorming` |
+| "spec", "specification", "especificação formal" | `wize-spec` |
+| "adversarial review", "revisão adversarial", "ataque à solução" | `wize-review-adversarial` |
+| "edge case", "casos de borda", "edge case hunter" | `wize-review-edge-case-hunter` |
+| "editorial", "revisão de texto", "polir prosa", "polish prose" | `wize-editorial-review-prose` |
+| "editorial structure", "revisão estrutural", "estrutura do doc" | `wize-editorial-review-structure` |
+| "index docs", "indexar docs", "índice" | `wize-index-docs` |
+| "shard doc", "quebrar doc", "documento grande" | `wize-shard-doc` |
+| "customize", "customizar", "personalizar kit" | `wize-customize` |
+| "create agent", "criar agente", "novo agente" | `wize-create-agent` |
+| "create skill", "criar skill", "nova skill" | `wize-create-skill` |
+| "create workflow", "criar workflow", "novo workflow" | `wize-create-workflow` |
+| "onboarding", "instalar kit", "primeiro uso" | `wize-onboarding` |
+| "party mode", "multi-agent", "reunir agentes" | `wize-party-mode` |
+
 ## 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`:
@@ -112,7 +233,7 @@ For `mission`, emit the filled **Mission contract** (see the section below) from
 
 End with one of: "Want me to call {persona}?" · "Want me to baseline the repo first?" (brownfield, no document-project) · "Want me to convene party-mode with {p1} + {p2}?" (cross-cutting decision) · "Want me to grill you first (`wize-grill`)?" (fuzzy demand heading into an authoring step).
 
-## Mission contract (`/wize-help mission`)
+## Mission contract (`/wize mission` or `/wize-help mission`)
 
 When asked for a mission, fill this from project state and hand it to the executing persona. It is a contract, not a spec dump — each field is the minimum that makes the work traceable. Leave a field blank only when the project genuinely has no answer, and say so. If Objective, Scope, or ACs can't be filled from project state, offer a `wize-grill` pass before emitting a hollow contract.
 

package/src/orchestrator-skills/wize-onboarding/workflow.md

@@ -1,5 +1,7 @@
 ---
+
 code: wize-onboarding
+description: "Use quando o kit for instalado e precisar fazer a triagem inicial: greenfield vs brownfield, perfil, objetivo e roteamento para a persona correta."
 name: Onboarding
 owner: wize-orchestrator   # Wizer
 status: ready
@@ -83,7 +85,7 @@ Never auto-launch the next workflow. The user must confirm.
 - Launching the next workflow without confirmation.
 - Re-asking the user’s name when it’s already in `user.toml`.
 - Dumping the full project state to the user. Summarize in ≤ 5 bullets.
-- Suggesting `wize-onboarding` from `/wize-help` once onboarding is complete. (Help should bypass onboarding for return users.)
+- Suggesting `wize-onboarding` from `/wize` (or `/wize-help`) once onboarding is complete. (Help should bypass onboarding for return users.)
 
 ## Hand-off
 

package/src/orchestrator-skills/wize-orchestrator/agent.yaml

@@ -33,6 +33,7 @@ routes_to:
   - wize-agent-tech-writer     # for docs
 
 skills:
+  - wize
   - wize-onboarding
   - wize-party-mode
   - wize-help

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

@@ -7,10 +7,12 @@ I am **Wizer**. I am the host of this development kit. I know who you are, what
 ## Operating principles
 
 1. **Listen first.** Before routing, I make sure I understand the demand. One clarifying question is cheaper than three wrong hand-offs.
-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.
+2. **Route by intent, not just phase.** When the user's message contains a clear intent phrase ("quero pesquisar concorrência", "cria um PRD", "roda um pentest"), I route directly to the matching skill using the intent routing table. I use the phase heuristic only when intent is ambiguous or no intent phrase matches.
+3. **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.
+4. **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.
+5. **Pair when needed.** When a decision crosses concerns (UX touching architecture, PM touching TEA), I open a **party-mode** with the relevant agents.
+6. **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` or `/wize-help`) and framed as a mission — objective, sources of truth, scope, acceptance criteria, validation — before any code is touched.
+7. **Harness-aware interaction.** In text-only harnesses, I ask one clarifying question when intent is ambiguous. In rich-UI harnesses, I offer a menu of matching options.
 
 ## Fan-out to subagents
 
@@ -39,6 +41,29 @@ Before greeting, read `.wize/config/user.toml` if it exists. If it has `[user] n
 
 If `user.toml` is missing or has no `name`, fall back to a neutral greeting.
 
+## First-run detection
+
+Before greeting, check whether this is a first run:
+
+1. Read `.wize/planning/brief.md` — if it exists, this is NOT a first run.
+2. Read `.wize/knowledge/document-project/` — if it has content (any `.md` files), this is NOT a first run.
+3. If neither exists: **first run**.
+
+## First-run flow
+
+When first run is detected, do NOT show a menu. Ask one question:
+
+> "O que você está construindo?"
+
+Wait for the answer. Then classify:
+
+- **Greenfield** (new project, idea, feature, product): route to **Pepper / `wize-product-brief`**.
+- **Brownfield** (existing codebase, legacy system, "we already have X"): route to **Pepper / `wize-document-project`**.
+
+If the answer is ambiguous, ask one clarifying question: "Is this a new project or an existing codebase?" Then route.
+
+Never show a menu on first run. One question → classify → route.
+
 ## Greet
 
 > "Welcome back{{`, ` + user.name when present, else ''}}. What are we working on?"

package/src/orchestrator-skills/wize-party-mode/workflow.md

@@ -1,5 +1,7 @@
 ---
+
 code: wize-party-mode
+description: "Use quando uma decisão cruzar preocupações de múltiplos agentes e precisar de discussão multi-agente facilitada."
 name: Party Mode (multi-agent)
 owner: wize-orchestrator   # Wizer facilitates
 status: stub

package/src/security-overlay/_shared/backlog.js

@@ -27,13 +27,6 @@ function priorityFor(severity) {
   }
 }
 
-// Group size -> rough estimate.
-function estimateFor(count) {
-  if (count <= 2) return 'S';
-  if (count <= 10) return 'M';
-  return 'L';
-}
-
 // Human label + remediation intent per section.
 const SECTION_THEME = {
   secrets: { theme: 'Rotacionar e remover segredos expostos', owasp: 'A07:2021' },
@@ -121,8 +114,6 @@ function buildBacklog({ findings = [], actionPlan = [], scopeSha = '', generated
   const planByTheme = {};
   for (const a of (actionPlan || [])) planByTheme[(a.title || '').toLowerCase()] = a;
 
-  const actionable = groups.filter(g => g.worstSeverity !== 'Info-surface' || g.priority !== 'P2' ? true : true);
-
   if (groups.length === 0) {
     lines.push('## (sem itens)');
     lines.push('');
@@ -134,7 +125,6 @@ function buildBacklog({ findings = [], actionPlan = [], scopeSha = '', generated
   let epicN = 0;
   for (const g of groups) {
     epicN++;
-    const est = estimateFor(g.count);
     // Find a matching action-plan detail by theme keyword overlap.
     let planDetail = '';
     for (const [title, a] of Object.entries(planByTheme)) {
@@ -150,14 +140,13 @@ function buildBacklog({ findings = [], actionPlan = [], scopeSha = '', generated
     lines.push(`- **Prioridade:** ${g.priority} (pior severidade: ${g.worstSeverity})`);
     lines.push(`- **Findings cobertos:** ${g.count}`);
     if (g.owasp) lines.push(`- **OWASP:** ${g.owasp}`);
-    lines.push(`- **Estimativa:** ${est}`);
     if (planDetail) lines.push(`- **Como corrigir:** ${planDetail}`);
     lines.push('');
     lines.push('### Stories');
     lines.push('');
     // For large groups, a single remediation story + a verification story.
-    lines.push(`- **${g.theme}** (${g.priority}, est ${est}) — corrigir os ${g.count} finding(s) de \`${g.section}\`. _Origem: ${g.section} (${g.count} findings, ${g.worstSeverity})._`);
-    lines.push(`- **Verificar correção de ${g.section}** (${g.priority}, est S) — re-rodar \`/wize-sec-pentest\` e confirmar que os findings de \`${g.section}\` sumiram (DoD).`);
+    lines.push(`- **${g.theme}** (${g.priority}) — corrigir os ${g.count} finding(s) de \`${g.section}\`. _Origem: ${g.section} (${g.count} findings, ${g.worstSeverity})._`);
+    lines.push(`- **Verificar correção de ${g.section}** (${g.priority}) — re-rodar \`/wize-sec-pentest\` e confirmar que os findings de \`${g.section}\` sumiram (DoD).`);
     lines.push('');
     // Sample of source findings for traceability (cap at 5).
     const sample = g.findings.slice(0, 5);
@@ -177,4 +166,4 @@ function buildBacklog({ findings = [], actionPlan = [], scopeSha = '', generated
   return lines.join('\n');
 }
 
-module.exports = { buildBacklog, priorityFor, estimateFor, groupFindings, CTA_COMMAND };
+module.exports = { buildBacklog, priorityFor, groupFindings, CTA_COMMAND };