# Wize Development Kit > **Kit de desenvolvimento assistido por IA, de ciclo completo** — leva um projeto do brief à implementação testada por meio de 10 agentes especializados, com um Test Architect, um estúdio de UX Whiteport e um Pentester de IA embarcados. Roda dentro da sua IDE com IA. [![npm version](https://img.shields.io/npm/v/wize-dev-kit?color=blue)](https://www.npmjs.com/package/wize-dev-kit) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) [![Status](https://img.shields.io/badge/status-beta-green)](#status) [![Repo](https://img.shields.io/badge/repo-qwize--br%2Fwize--development--kit-181717?logo=github)](https://github.com/qwize-br/wize-development-kit) **🌐 Idiomas:** [English](README.md) · **Português (pt-BR)** · [Español](README.es.md) --- ## Resumo rápido ```bash npx wize-dev-kit install ``` Escolha os perfis e a IDE; depois, na sua IDE com IA, diga *"Ative o Wizer e dê o briefing do projeto a ele."* O Wizer te conduz pelo agente certo em cada fase — brief, PRD, UX, arquitetura, código testado — e (opcionalmente) roda um pentest de IA na sua aplicação. --- ## O que é 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 (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) | Perfil | O que adiciona | |---|---| | **Wize Dev Core** | Ciclo completo (análise → plano → solução → implementação) + Test Architect + UX Whiteport + Agent Builder. Sempre instalado. | | **Wize Web Dev** *(overlay)* | Scaffolds web, SEO, analytics, playbook WCAG para o Mantis, Playwright/Vitest para o Hawkeye. | | **Wize App Development** *(overlay)* | Scaffolds mobile, listagem em loja, gate de revisão da App Store (auditoria de rejeição no momento da publicação), diretrizes de plataforma (HIG / Material 3), Detox/Maestro para o Hawkeye. | | **Wize Security** *(overlay)* | **Pentester de IA.** Pipeline de pentest file-first (recon → enumerate → SAST → DAST → report) conduzido por **Natasha Romanoff**, a persona `red-teamer`, com gate de escopo, classificação OWASP/CVSS e relatório executivo. | --- ## Instalação Em qualquer repositório, novo ou existente (greenfield ou brownfield): ```bash npx wize-dev-kit install ``` Ou direto do GitHub (sem precisar de npm): ```bash npx github:qwize-br/wize-development-kit install ``` O instalador pergunta: 1. **Nome do projeto** — gravado em `.wize/config/project.toml`. 2. **Perfil(is)** — Core / +Web / +App / +Security (múltipla escolha). 3. **IDE(s) alvo** — Claude Code, Cursor, Windsurf, Codex, Continue, Kimi Code, Hermes, Kiro, OpenCode, Antigravity ou fallback genérico (múltipla escolha). 4. **Idiomas** — comunicação + saída de documentos. 5. **Seu nome** — como os agentes devem te chamar (salvo em `user.toml`). 6. **Brownfield** — oferece rodar `wize-document-project` para criar a baseline do código existente. Após instalar, abra sua IDE e diga: > "Ative o Wizer e dê o briefing do projeto a ele." --- ## Harnesses suportadas Os 11 alvos de IDE são gerados a partir da mesma fonte; formato e mecânica mudam por harness. O **OpenCode** tem a integração mais profunda — a divisão persona/workflow do kit mapeia pras primitivas nativas do próprio OpenCode (`mode: primary|subagent`, `agent:`, `subtask:`) em vez de ser achatada num único tipo de arquivo. | Harness | Saída | Destaque | |---|---|---| | **OpenCode** 🆕 | `.opencode/agents/` + `.opencode/commands/` | `mode: primary\|subagent` nativo; commands se ligam à persona dona (`agent:`); workers de fan-out rodam isolados (`subtask: true`). [Docs →](docs/harnesses/opencode.pt-BR.md) | | **Claude Code** | `.claude/skills/*/SKILL.md` | Formato Skill da Anthropic; fan-out ad hoc via Task/Agent tool (`wize-code-review`). [Docs →](docs/harnesses/claude-code.pt-BR.md) | | **Codex** | `.agents/skills/*/SKILL.md` | Mesmo formato Skill + `AGENTS.md` na raiz. [Docs →](docs/harnesses/codex.pt-BR.md) | | **Kimi Code** | `.kimi/skills/*/SKILL.md` | Mesmo formato Skill; autodetecta as árvores do Claude/Codex. [Docs →](docs/harnesses/kimi-code.pt-BR.md) | | **Hermes Agent** 🆕 | `.hermes/skills/*/SKILL.md` | Mesmo formato Skill, project-local; trust gate (`hermes skills trust`); skills do projeto sobrescrevem as de perfil. [Docs →](docs/harnesses/hermes.pt-BR.md) | | **Kiro — AWS** 🆕 | `.kiro/skills/*/SKILL.md` | Padrão Agent Skills (agentskills.io); skills de workspace sobrescrevem as globais; ativação automática por descrição, ou `/wize-{code}`. [Docs →](docs/harnesses/kiro.pt-BR.md) | | **Antigravity** | `.agent/skills/*/SKILL.md` | Mesmo formato Skill + `AGENTS.md` na raiz. [Docs →](docs/harnesses/antigravity.pt-BR.md) | | **Cursor** | `.cursor/rules/*.mdc` | Rules sob demanda (`alwaysApply: false`), casadas por descrição. [Docs →](docs/harnesses/cursor.pt-BR.md) | | **Windsurf** | `.windsurf/rules/*.md` | Markdown puro; modo de ativação definido dentro da IDE. [Docs →](docs/harnesses/windsurf.pt-BR.md) | | **Continue.dev** | `.continue/prompts/*.prompt` | Slash commands via `invokable: true`. [Docs →](docs/harnesses/continue.pt-BR.md) | | **Fallback genérico** | `.wize/agents/*.md` + `AGENTS.md` na raiz | Para qualquer IDE sem adapter dedicado. [Docs →](docs/harnesses/generic.pt-BR.md) | --- ## O elenco | # | Persona | Código | Papel | |---|---|---|---| | 1 | **Wizer** | `wize-orchestrator` | Orquestrador, base de conhecimento, briefing, roteamento | | 2 | **Pepper Potts** | `wize-agent-analyst` | Analista de Negócio + WDS Saga (brief de produto, trigger map) | | 3 | **Peggy Carter** | `wize-agent-tech-writer` | Redatora Técnica (transversal) | | 4 | **Maria Hill** | `wize-agent-pm` | Product Manager (PRD, epics, sprints) | | 5 | **Mantis** | `wize-agent-ux-designer` | UX Designer + WDS Freya (cenários, design, design system) | | 6 | **Nick Fury** | `wize-agent-solution-strategist` | Estratégia de Solução, visão técnica, princípios de NFR | | 7 | **Tony Stark** | `wize-agent-architect` | Arquiteto de Sistemas (arquitetura, ADRs, epics, stories) | | 8 | **Hawkeye** | `wize-agent-test-architect` | Test Architect — 6 gates (risk, design, trace, nfr, review, gate) | | 9 | **Shuri** | `wize-agent-dev` | Desenvolvedora Sênior (TDD, código, refactor) | | 10 | **Natasha Romanoff** | `wize-sec-red-teamer` (overlay de segurança) | Red-Teamer / Pentester de IA — recon, SAST/DAST, testes ofensivos com escopo, relatório | Veja [`ROSTER.md`](ROSTER.md) para personas, estilos e equivalências com o BMAD. --- ## Passo a passo — um projeto completo, de ponta a ponta Cada passo é um slash command na sua IDE; cada persona lê o artefato anterior antes de escrever o seu. ``` 1. /wize-orchestrator Wizer cumprimenta, lê config, detecta estado e roteia. 2. /wize-grill Qualquer persona te entrevista até entendimento compartilhado antes de redigir — uma pergunta por vez, cada uma com resposta recomendada (oferecida, nunca imposta). /wize-product-brief Pepper transforma a demanda bruta em brief.md. /wize-trigger-map Pepper mapeia psicologia do usuário → metas de negócio (WDS). /wize-research Pepper sintetiza evidências externas (opcional). 3. /wize-create-prd Maria Hill escreve prd.md (metas, escopo, ACs). /wize-validate-prd Maria Hill (+ Mantis/Fury) aprova. 4. /wize-ux-scenarios Mantis conduz o diálogo WDS de 8 perguntas. /wize-ux-design Mantis escreve specs de tela (um .md por tela). 5. /wize-tech-vision Fury escolhe a família de stack + não-negociáveis. /wize-nfr-principles Fury escreve o orçamento de NFR (perf, seg, a11y…). 6. /wize-create-architecture Tony escreve architecture.md + ADRs (8 passos). /wize-design-system Mantis escreve design-system/ (tokens + componentes). /wize-create-epics-and-stories Tony fatia epics → stories (cada uma com ACs). 7. /wize-sprint-planning Maria Hill abre a sprint a partir dos epics/stories. /wize-tea-risk Hawkeye monta o perfil global de risco. /wize-tea-design Hawkeye escreve o test design da próxima story. /wize-create-story Tony escreve a próxima story (campos de contrato: fontes de verdade, restrições, validação, done-means). /wize-dev-story Shuri implementa (TDD, IDs de AC nos commits) com loop auto-verificável e guarda de 3 ciclos. /wize-tea-trace Hawkeye mapeia cada AC → testes. /wize-tea-review Hawkeye faz a revisão da story. /wize-tea-gate Hawkeye emite PASS / CONCERNS / FAIL / WAIVED. 8. /wize-sprint-status Maria Hill mantém o snapshot diário atualizado. /wize-retrospective Wizer facilita a retro no fim de cada sprint. Transversais: /wize-help Wizer te direciona: `next` (próxima ação única), `status` (snapshot do projeto), `mission` (contrato de missão preenchido para a persona executora). /wize-check Checklist de acompanhamento da demanda em voo: feito (com evidência), em andamento, o que falta — depois retoma o trabalho interrompido. /wize-update Verifica se o kit está desatualizado, mostra o changelog, confirma e aplica o update. /wize-grill Entrevista-até-entendimento antes de qualquer passo de autoria. /wize-eli5 Explique qualquer coisa a qualquer um — vocabulário, analogias, tom, profundidade e framing calibrados para o ouvinte (idade, papel, relação). /wize-no-ai-slop Higiene de escrita para texto de usuário final: remove padrões de "AI slop" e palavras de enchimento preservando a voz do autor. Também detecta slop. /wize-quick-dev Shuri pega uma correção pequena sem o ciclo completo. /wize-pre-pr-check Roda lint/format/build/testes unitários localmente antes de abrir um PR — falha cedo, zero custo de runner. /wize-correct-course Re-planeja quando um gate falha ou o loop trava (auto-disparado pela guarda de max-cycles; também manual). /wize-code-review Revisão adversarial antes do gate TEA do Hawkeye. /wize-party-mode Wizer reúne multi-persona para decisões difíceis. ``` > Use `/wize-help next` sempre que estiver em dúvida — ele inspeciona `.wize/` e diz a única próxima ação. --- ## 🛡️ Overlay de segurança — Pentester de IA Com o perfil **Wize Security** instalado, **Natasha Romanoff** (`wize-sec-red-teamer`, a persona red-teamer) roda um pentest file-first do seu projeto e produz um relatório pronto para stakeholders. ### Como funciona 1. **Autorize o alvo.** Você declara hosts/URLs permitidos em um `.wize/security/scope.md` assinado (integridade por SHA-256). Qualquer coisa fora da allowlist é **recusada e auditada** — a ferramenta nunca toca em um alvo que você não autorizou. 2. **Rode o pipeline.** ``` /wize-sec-pentest # passivo por padrão (checagens read-only) /wize-sec-pentest --active # habilita tooling ofensivo (sqlmap, ffuf) ``` Encadeia: **recon** (nmap) → **enumerate** (superfície HTTP) → **SAST** (secrets via gitleaks + deps via osv-scanner/grype) → **DAST** (nuclei, nikto, sqlmap, ffuf) → **report**. 3. **Leia o relatório.** `report.md` + um `report.html` self-contained (offline, WCAG 2.2 AA) com: - **Score de risco 0–100** + **briefing** executivo (o que o risco significa para o negócio), - findings classificados por **CVSS v3.1** e **OWASP Top 10**, com secrets redatados, - **cobertura honesta** ("audit confidence" — o que foi e o que não foi testado), - um **plano de ação priorizado** (P0/P1/P2). 4. **Planeje a correção.** O scan gera `security-backlog.md` (epics de remediação agrupados por tema, rastreáveis aos findings) e imprime o comando exato para virar uma sprint: ``` /wize-create-epics-and-stories --from .wize/security/security-backlog.md ``` ### Garantias de design - **Zero runtime próprio** — só built-ins do Node; nenhuma dependência npm nova; o overlay nunca invoca uma skill (ele imprime o comando para você/o agente rodar). - **Os dados ficam locais** — relatórios e findings são gravados em `.wize/security/`, nunca enviados a lugar nenhum. - **Ferramentas são detectadas, nunca auto-instaladas** — um preflight checa seu toolchain e gera um `install-pentest-tools.sh` ciente do SO (apt para nmap/nikto/sqlmap; releases do GitHub para gitleaks/nuclei/ffuf/osv-scanner; script oficial para grype). Ferramenta ausente degrada só aquela checagem — o pipeline continua. - **Passivo por padrão** — tooling ofensivo (sqlmap/ffuf) só roda com `--active`; flags perigosas (`--dump`, `--os-shell`) são vetadas por uma allowlist independente do input. > ⚠️ **Ferramenta dual-use.** Só teste sistemas que você possui ou está explicitamente autorizado a testar. --- ## Layout de saída (no repositório alvo) ``` .wize/ ├── config/ # project.toml, user.toml, tea.toml ├── planning/ # brief, research, ux/, prd, tech-vision, nfr-principles ├── solutioning/ # architecture, adrs, epics, stories ├── implementation/ # sprint-status, retrospective, tea/{gates} ├── knowledge/ # docs e referências de longa duração ├── security/ # scope.md, report.{md,html}, security-backlog.md (overlay de segurança) └── custom/ # agents/skills/workflows criados pelo Agent Builder ``` --- ## Comandos da CLI ```bash 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, skills e workflows instalados 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 # sobrescreve um agente nativo npx wize-dev-kit workflow # 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 ] npx wize-dev-kit uninstall # remove .wize/ (seu código permanece intacto) npx wize-dev-kit help # referência de comandos npx wize-dev-kit version # imprime a versão instalada do kit npx wize-dev-kit version-check [--json] # instalada vs. mais recente (com cache; scriptável; nunca bloqueia) ``` --- ## Documentação - [`ARCH.md`](ARCH.md) — arquitetura completa: distribuição, fluxos, layout, instalador. - [`ROSTER.md`](ROSTER.md) — personas com estilo, papel, equivalências BMAD. - [`AGENTS.md`](AGENTS.md) — o roster gerado + contexto operacional que as IDEs leem na raiz do repo. - [`DECISIONS.md`](DECISIONS.md) — log de decisões. - [`CHANGELOG.md`](CHANGELOG.md) — histórico de releases. - [`docs/harnesses/`](docs/harnesses/) — um doc por [harness suportada](#harnesses-suportadas), em português + [English](README.md#supported-harnesses). --- ## Status **v0.12.1 — beta.** O método nunca produz estimativas de desenvolvimento — nada de horas, pontos ou tamanhos de camiseta; uma story é dimensionada apenas por caber (ou não) em um único PR. O ciclo completo (análise → plano → solução → implementação) está montado com 10 agentes e uma biblioteca estruturada de skills. Releases recentes adicionam **contratos de missão** (`/wize-help mission`), **`wize-grill`** (entrevista-até-entendimento antes de qualquer passo de autoria), **`wize-pre-pr-check`** (gate local de lint/format/build/testes unitários antes de abrir um PR — zero custo de runner de CI) e **loop verification** no `wize-dev-story` (loop de implementação auto-verificável com guarda de max-cycles que escala para `wize-correct-course`). O `security-overlay` (Pentester de IA) entrega um pipeline de pentest completo, um relatório executivo (score de risco + briefing + plano de ação por IA) e planejamento de correção pós-scan — validado de ponta a ponta contra uma aplicação Laravel/PHP real. Os adapters de IDE para Claude Code, Cursor, Windsurf, Codex, Continue, Kimi Code, Hermes, OpenCode e Antigravity são regenerados automaticamente — o [OpenCode](docs/harnesses/opencode.pt-BR.md) tem a integração mais profunda das 10, com `mode`/`agent`/`subtask` nativos. --- ## Inspiração & créditos - [BMAD Method](https://github.com/bmad-code-org/BMAD-METHOD) por Brian (BMad) Madison — ciclo ágil de IA, personas de agentes, padrão de instalador, sistema de módulos. - [Whiteport Design Studio expansion](https://github.com/bmad-code-org/bmad-method-wds-expansion) — metodologia UX-first, panteão nórdico (Saga, Freya), estrutura de fases. - [No AI Slop](https://github.com/petergyang/no-ai-slop) por Peter Yang — higiene de escrita que elimina padrões de AI slop sem achatar a voz do autor; a inspiração para `/wize-no-ai-slop`. - [apple-appstore-reviewer (awesome-copilot)](https://github.com/github/awesome-copilot/blob/main/skills/apple-appstore-reviewer/SKILL.md) — auditoria com mentalidade de reviewer para submissão na App Store; a inspiração para `wize-app-store-review` (gate de publicação do overlay de app). O Wize Development Kit é uma **adaptação independente** — não afiliada nem endossada pelos autores do BMAD ou do WDS. Os nomes de personas Marvel são referências criativas sob uso nominativo justo. --- ## Licença MIT — veja [`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 as skills `/wize-*` (analista, PM, arquiteto, dev, TEA, orquestrador) que dão estrutura ao ciclo de vida do projeto. - Cria/atualiza a baseline brownfield em `.wize/knowledge/document-project/` — a fonte canônica a consultar antes de decidir mudanças. - Habilita trackeamento de atividade em `.wize/implementation/` — cada 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. Isso vale para qualquer agente de IA usado no projeto. Para Claude Code: comece com `/wize-help` para diagnóstico e recomendação do próximo passo.