wize-dev-kit 0.16.0 → 0.17.0

package/src/method-skills/3-solutioning/wize-project-context/workflow.md

@@ -0,0 +1,120 @@
+---
+
+code: wize-project-context
+description: "Use quando precisar estabelecer ou atualizar o contexto do projeto (stack, convenções, restrições) para orientar a solução."
+name: Project Context
+phase: 3-solutioning
+owner: wize-agent-architect   # Tony Stark
+status: ready
+---
+
+# Project Context
+
+**Goal.** Consolidate the 5 foundational artifacts (brief, PRD, UX, architecture, risk profile) into a single `.wize/knowledge/project-context.md` so other agents (Shuri, Hawkeye, Mantis, Wizer) can read the project in one shot instead of stitching it from 5 files.
+
+Tony drives. Peggy polishes prose. Wizer is on call for cross-cutting drift.
+
+## When to run
+
+- After Phase 3 closeout (architecture + ADRs + risk profile all exist).
+- After any major change to brief / PRD / architecture (rerun).
+- Before sprint planning if context feels stale.
+
+## When NOT to run
+
+- During greenfield with no artifacts yet (run only after brief + PRD exist).
+- As a CI step (manual; expensive to run on every commit).
+
+## Inputs
+
+- `.wize/planning/brief.md` — Vision, Audience.
+- `.wize/planning/prd.md` — Goals, scope.
+- `.wize/planning/ux/ux-design/index.md` — UX stack, key screens.
+- `.wize/solutioning/architecture.md` — Tech stack, components.
+- `.wize/solutioning/adrs/*.md` — Key decisions.
+- `.wize/implementation/tea/risk-profile.md` — Active risks.
+
+## Output
+
+- `.wize/knowledge/project-context.md` (5 sections, YAML frontmatter, `last_updated` date).
+
+## Steps
+
+### 1. Vision and Audience
+
+Copy from `brief.md` (or `prd.md` if brief is missing). One paragraph each. Mark the source file in a comment.
+
+### 2. Tech stack
+
+From `architecture.md`, list: runtime, framework, database, key libraries, build tool. One bullet per item. Skip items that are "TBD".
+
+### 3. Key ADRs
+
+List the 5 most recent ADRs from `.wize/solutioning/adrs/`. For each: title, decision, why. Older ADRs are out of scope; refer to `adrs/index.md` for the full list.
+
+### 4. Active risks
+
+Copy from `risk-profile.md` the top 5 risks (highest prob × impact). One bullet per risk with the mitigation. Defer the rest.
+
+### 5. Active sprint
+
+Read `.wize/implementation/sprint-status.yaml` and include: sprint number, capacity, in-progress stories. Skip if no active sprint.
+
+### 6. Hand off
+
+Output is a markdown file. Wizer uses this file to seed `/wize`, `/wize-help`, `/wize-dev-story`, and `/wize-onboarding` reads.
+
+## Output template
+
+```markdown
+---
+generated: YYYY-MM-DD
+last_updated: YYYY-MM-DD
+sources:
+  - .wize/planning/brief.md
+  - .wize/planning/prd.md
+  - .wize/planning/ux/ux-design/index.md
+  - .wize/solutioning/architecture.md
+  - .wize/solutioning/adrs/
+  - .wize/implementation/tea/risk-profile.md
+---
+
+# Project Context — {project_name}
+
+## Vision
+{paragraph from brief.md}
+
+## Audience
+{paragraph from brief.md or prd.md}
+
+## Tech stack
+- Runtime: {value}
+- Framework: {value}
+- Database: {value}
+- Key libraries: {value}
+- Build: {value}
+
+## Key ADRs
+1. **{title}** — {decision}. Why: {why}.
+2. ...
+
+## Active risks
+1. **{R-id}** — {description}. Mitigation: {mitigation}.
+2. ...
+
+## Active sprint
+- Sprint: {N}
+- Capacity: {days}
+- In-progress: {stories}
+```
+
+## Anti-patterns Tony rejects
+
+- Reading all 6 sources in full and dumping them. Summarize in 5 sections.
+- Editing the project-context.md by hand. (Always re-run the workflow to keep `last_updated` honest.)
+- Skipping the frontmatter. Other agents parse it.
+- Including items marked "TBD". Surface them in the `Open questions` section instead.
+
+## Hand-off
+
+> "Project context updated at `.wize/knowledge/project-context.md`. {N} sources, 5 sections, {date}. Next: `/wize-onboarding` (Wizer) reads this for first contact."

package/src/method-skills/3-solutioning/wize-tech-vision/workflow.md

@@ -1,43 +1,151 @@
 ---
+
 code: wize-tech-vision
+description: "Use quando o PRD estiver validado e precisar definir o norte técnico: stack family, build-buy-borrow e non-negotiables."
 name: Tech Vision
-phase: 2-to-3-boundary
+phase: 3-solutioning
 owner: wize-agent-solution-strategist   # Nick Fury
-status: stub
+status: ready
 ---
 
 # Tech Vision
 
-**Goal.** State the technical north star in one page. Stack family, language, runtime envelope, build/buy/borrow calls. Not libraries — *shape*.
+**Goal.** State the technical north star in one page. Stack family, runtime envelope, build/buy/borrow calls, non-negotiables. Fury sets the **shape**, not the libraries — Tony fills in inside the frame.
+
+Output lands in `.wize/planning/tech-vision.md`. Tony reads this before drawing architecture. Hill references it when scoping. Hawkeye uses it when picking gate granularity.
+
+## Inputs
+
+- `.wize/planning/prd.md` (validated)
+- `.wize/planning/ux/ux-design/` (so the runtime envelope respects the UX)
+- `.wize/knowledge/document-project/` (brownfield only)
+- Stack catalogs (per active overlay):
+  - `src/web-overlay/stack-catalog.md`
+  - `src/app-overlay/stack-catalog.md`
+
+## Outputs
 
-## Output
 - `.wize/planning/tech-vision.md`
 
-## Template
+## Steps
+
+### 1. Pick the stack family
+
+By order of constraint:
+
+1. **Audience reach.** Public + SEO-critical? Authenticated app? Native mobile required?
+2. **Latency budget.** Sub-1s LCP on 3G or richer-but-slower OK?
+3. **Team familiarity.** Favor what the team has shipped before unless the project truly demands new.
+4. **Backend coupling.** Separate API / fullstack monolith / BaaS?
+5. **Deploy target.** Edge / container / self-managed.
+
+Don't pick libraries here. Pick the *shape*: "Next.js-class SSR fullstack on edge" or "React Native + Expo with a Supabase backend" or "Compose Multiplatform with Kotlin services."
+
+### 2. State the runtime envelope
+
+| Dimension | Decision |
+|---|---|
+| Language(s) of record | TS, Kotlin, etc. |
+| Runtime(s) | Browser / Node / Edge / Native iOS / Native Android / JVM |
+| Persistence | Postgres / SQLite / KV / cloud-native |
+| Deploy target | Vercel / Cloudflare / Fly / EKS / EAS / etc. |
+| Edge vs origin | Edge-first / origin-first |
+
+### 3. Build / buy / borrow
+
+For each capability the PRD implies, declare:
+
+| Capability | Build | Buy | Borrow (OSS) |
+|---|---|---|---|
+| Auth | — | Clerk / Auth0 | NextAuth / Lucia |
+| Payments | — | Stripe | — |
+| Search | — | Algolia / Typesense Cloud | Meilisearch self-hosted |
+| Queues | — | SQS / Cloud Tasks | BullMQ |
+| Analytics | — | Amplitude | PostHog OSS |
+| Email | — | Resend / Postmark | — |
+| Realtime | — | Pusher / Ably | Supabase Realtime |
+
+One row per capability. Empty cells are explicit choices.
+
+### 4. Non-negotiables
+
+The 2–5 things the team will not compromise on.
+
+Examples:
+- *"All endpoint responses ≤ 200ms p95 from the user's region."*
+- *"Single source of truth for user data — no shadow stores."*
+- *"PII never leaves the EU."*
+- *"On-call burden ≤ 0.5 pages per engineer per week."*
+
+These outrank PRD goals. If they conflict, Fury escalates.
+
+### 5. Deferred (with triggers)
+
+What we won't decide yet, and what would trigger the decision. Don't list "could be revisited"; list the *signal* that forces the decision.
+
+- *"Multi-region storage: revisit when EU+US daily active users > 5k."*
+- *"WebSockets vs SSE: revisit when realtime updates < 500ms become a PRD goal."*
+
+### 6. Hand off
+
+Mark `status: aligned`. Tony reads it as the frame; he can argue specific decisions but not redraw the family without escalating.
+
+## Output template
+
 ```markdown
-# Tech Vision
+---
+status: aligned
+owner: Nick Fury
+created: YYYY-MM-DD
+---
 
-## Stack family
-- {Web|Mobile|Hybrid}
+# Tech Vision — {{project_name}}
 
-## Language(s) of record
-- …
+## Stack family
+Next.js-class SSR fullstack on edge, with Supabase Postgres as the system of record.
 
 ## Runtime envelope
-- {Browser|Node|Edge|Native iOS|Native Android}
+| Dimension | Decision |
+|---|---|
+| Language | TypeScript end-to-end |
+| Runtime | Edge (Vercel Edge Functions) + Node (server actions) |
+| Persistence | Supabase Postgres (RLS) + PgBouncer |
+| Deploy target | Vercel for app; Supabase managed for data |
+| Edge vs origin | Edge-first for reads; origin for writes |
 
-## Build vs buy vs borrow
-| Capability | Decision | Why |
-|---|---|---|
-| Auth | … | … |
-| Payments | … | … |
-| Search | … | … |
-| Queues | … | … |
-| Analytics | … | … |
+## Build / buy / borrow
+| Capability | Decision |
+|---|---|
+| Auth | Buy — Supabase Auth |
+| Payments | Buy — Stripe |
+| Search | Buy — Algolia (1st year), revisit |
+| Queues | Borrow — pg_cron + outbox pattern |
+| Analytics | Borrow — PostHog OSS |
+| Email | Buy — Resend |
 
 ## Non-negotiables
-- …
+1. PII (incl. emails) stored in the user's region only.
+2. p95 server response ≤ 200ms in the user's region.
+3. Single auth identity per human (no shadow accounts).
+4. On-call rotation never exceeds 0.5 pages/eng/week.
+
+## Deferred
+- Multi-region writes: revisit when EU active users > 2k.
+- Native mobile clients: revisit when web TTI > 4s on > 20% of sessions or PRD demands offline.
 
-## Deferred (revisit when)
-- … (trigger: …)
+## Constraints that drove this
+- Brief constraint #2 (LGPD/GDPR) ruled out global-replica DBs.
+- PRD goal G1 ruled in edge-first reads.
+- Hiring tail in TypeScript ruled out Compose Multiplatform.
 ```
+
+## Anti-patterns Fury rejects
+
+- **Picking a library here.** That's Tony. Pick the *family*.
+- **Non-negotiables that are aspirations.** "Always 100% uptime." Wrong. "Error budget ≤ 0.1% in EU region."
+- **Deferred items with no trigger.** That's procrastination.
+- **A non-negotiable that contradicts a PRD constraint silently.** Surface it, escalate it, decide it.
+
+## Hand-off
+
+> Tech vision at `.wize/planning/tech-vision.md`. Tony, build the architecture inside this frame. Hill, scope the PRD against the non-negotiables (item 1 means the global launch is back on the table only after EU baseline holds). Hawkeye, pick gate granularity assuming `policy = advisory`.

package/src/method-skills/4-implementation/wize-agent-dev/persona.md

@@ -12,6 +12,18 @@ I am **Shuri**. Wakandan technologist. I implement the story Tony wrote, against
 4. **Security & perf.** I think about both at write-time, not at review-time.
 5. **Commit with AC IDs.** Every commit cites the story acceptance criteria it advances.
 
+## Before I write new code (the reuse ladder)
+
+At the "green" step, before typing a new function, I walk this ladder in order and stop at the first "yes":
+
+1. **Does this need to exist?** → no: skip it (YAGNI).
+2. **Already in this codebase?** → reuse it, don't rewrite it.
+3. **Does the stdlib do it?** → use the stdlib.
+4. **Native platform/framework feature?** → use that.
+5. **An installed dependency does it?** → use the dependency.
+6. **Is it one line?** → write the one line.
+7. **Only then** do I write the minimum new code that makes the test pass.
+
 ## Style
 
 - File paths, AC IDs, commit-message brevity.

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

@@ -0,0 +1,117 @@
+---
+
+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)
+status: ready
+---
+
+# Checkpoint Preview
+
+**Goal.** Pause mid-story to validate direction before continuing. For larger stories where the cost of going off-rail is high, a quick checkpoint catches drift before it becomes rework.
+
+Shuri drives. Tony on call for architectural drift. Hawkeye on call for test design drift.
+
+## When to run
+
+- Manually, when a story is running long or feels off-track.
+- After the first 2-3 commits of a larger story.
+- When a new constraint is mentioned (security review, perf budget, vendor change).
+
+## When NOT to run
+
+- Quick-dev / small stories (overhead exceeds the value).
+- When the story is < 50% done and no surprise has come up yet.
+
+## Inputs
+
+- The current story file: `.wize/solutioning/stories/{epic}/{story}.md`
+- The git diff: uncommitted + committed since story start
+- The `tea-design.md` for the story
+- The `design-system/` tokens used so far
+
+## Output
+
+- `.wize/implementation/checkpoints/{story_id}.md` (one file per checkpoint, append over time)
+- A decision: continue / pivot / stop
+
+## Steps
+
+### 1. Pause
+
+Stop writing code. Do not commit any pending work until the checkpoint is recorded.
+
+### 2. Snapshot
+
+Write 5 lines:
+
+- Files touched: (list, max 10)
+- ACs done vs. remaining: (X / Y)
+- Tests added: (count, by split)
+- New dependencies: (list)
+- Commits so far: (count)
+
+### 3. Sanity check (3 questions)
+
+- **Are we solving the right problem?** Compare the implementation with the story's Context and ACs. If the story's intent was misunderstood, pivot.
+- **Is the design holding?** Compare the code with the architecture. If a new pattern emerged without an ADR, flag it.
+- **Any new constraints?** Did anything new appear (security finding, perf regression, vendor change, new stakeholder)?
+
+### 4. Decide
+
+One of three:
+
+- **Continue** — the path is right. Record the snapshot; resume.
+- **Pivot** — change scope or approach. Open a follow-up story with `wize-create-story`; do not edit the current story's ACs.
+- **Stop** — the story is no longer worth it. Move it to `backlog` via `wize-correct-course`.
+
+One decision per checkpoint. Re-run for additional decisions.
+
+### 5. Hand off
+
+Notify the next workflow:
+
+- Continue → `/wize-dev-story` (resume).
+- Pivot → `/wize-create-story` (new story for the pivot).
+- Stop → `/wize-correct-course` (defer the original).
+
+## Output template
+
+```markdown
+---
+story_id: E04-S02
+checkpoint: 1
+date: 2026-06-16
+author: Shuri
+---
+
+# Checkpoint — E04-S02
+
+## Snapshot
+- Files touched: src/...
+- ACs done vs. remaining: 1 / 4
+- Tests added: 2 unit, 1 integration
+- New dependencies: none
+- Commits so far: 3
+
+## Sanity check
+- Right problem? Yes.
+- Design holding? Yes.
+- New constraints? Vendor X deprecated their API; need a different client lib.
+
+## Decision
+**Pivot** — see follow-up E04-S04 (client lib migration).
+```
+
+## Anti-patterns Shuri rejects
+
+- Skipping the snapshot to "save time" — the snapshot is the artifact.
+- Auto-pivoting (changing scope without an explicit checkpoint).
+- Recording "continue" without the sanity check answers.
+- Bundling multiple pivots in one checkpoint (one decision per run).
+
+## Hand-off
+
+> "Checkpoint recorded for **{story_id}** (decision: {continue|pivot|stop}). Next: `/wize-dev-story` / `/wize-create-story` / `/wize-correct-course`."

package/src/method-skills/4-implementation/wize-code-review/customize.toml

@@ -0,0 +1,21 @@
+# Wize Dev Kit — overrides for the built-in workflow "wize-code-review".
+# DO NOT EDIT in the installed kit; copy to .wize/custom/workflows/wize-code-review/
+# for project-level overrides.
+
+[workflow]
+
+# Steps to run before standard activation (config load, greet).
+activation_steps_prepend = []
+
+# Steps to run after greet but before the workflow begins.
+activation_steps_append = []
+
+# Persistent facts the workflow keeps in mind for the whole run.
+persistent_facts = [
+  "file:{project-root}/.wize/knowledge/document-project/conventions.md",
+]
+
+# Scalar executed when the workflow reaches its final step,
+# after review findings are presented and sprint status is synced.
+# Override wins. Leave empty for no custom post-completion behavior.
+on_complete = ""