# Wize Development Kit > **Kit de desarrollo asistido por IA, de ciclo completo** — lleva un proyecto del brief a la implementación testeada mediante 10 agentes especializados, con un Test Architect, un estudio de UX Whiteport y un Pentester de IA integrados. Funciona dentro de tu IDE con 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)](#estado) [![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)](README.pt-BR.md) · **Español** --- ## Resumen rápido ```bash npx wize-dev-kit install ``` Elige tus perfiles y tu IDE; luego, en tu IDE con IA, di *"Activa a Wizer y dale el briefing del proyecto."* Wizer te guía por el agente adecuado en cada fase — brief, PRD, UX, arquitectura, código testeado — y (opcionalmente) ejecuta un pentest de IA sobre tu aplicación. --- ## Qué es Wize Development Kit (WDK) es un **stack de agentes de IA** instalable que funciona dentro de tu IDE con IA (Claude Code, Cursor, Windsurf, Codex y otros) y escribe artefactos estructurados en una carpeta oculta `.wize/` de tu repositorio. Lleva un proyecto de **brief → PRD → estrategia de UX → arquitectura → implementación testeada**, y también puede **hacer pentest de la app en ejecución y planificar el sprint de remediación**. Es **file-first y zero-runtime**: los agentes son skills en Markdown que tu IDE lee; el tooling es Node puro (una única dependencia npm — `prompts`, usada solo por el instalador; nada se añade a tu proyecto). Nada está simulado — cada paso lee el artefacto anterior y escribe uno real. ### Perfiles (combinables en monorepos) | Perfil | Qué añade | |---|---| | **Wize Dev Core** | Ciclo completo (análisis → plan → solución → implementación) + Test Architect + UX Whiteport + Agent Builder. Siempre instalado. | | **Wize Web Dev** *(overlay)* | Scaffolds web, SEO, analytics, playbook WCAG para Mantis, Playwright/Vitest para Hawkeye. | | **Wize App Development** *(overlay)* | Scaffolds móviles, ficha de tienda, gate de revisión de App Store (auditoría de rechazo al publicar), directrices de plataforma (HIG / Material 3), Detox/Maestro para Hawkeye. | | **Wize Security** *(overlay)* | **Pentester de IA.** Pipeline de pentest file-first (recon → enumerate → SAST → DAST → report) conducido por **Natasha Romanoff**, la persona `red-teamer`, con gate de alcance, clasificación OWASP/CVSS e informe ejecutivo. | --- ## Instalación En cualquier repositorio, nuevo o existente (greenfield o brownfield): ```bash npx wize-dev-kit install ``` O directamente desde GitHub (sin necesidad de npm): ```bash npx github:qwize-br/wize-development-kit install ``` El instalador pregunta: 1. **Nombre del proyecto** — escrito en `.wize/config/project.toml`. 2. **Perfil(es)** — Core / +Web / +App / +Security (selección múltiple). 3. **IDE(s) objetivo** — Claude Code, Cursor, Windsurf, Codex, Continue, Kimi Code, Hermes, Kiro, OpenCode, Antigravity o fallback genérico (selección múltiple). 4. **Idiomas** — comunicación + salida de documentos. 5. **Tu nombre** — cómo deben dirigirse a ti los agentes (guardado en `user.toml`). 6. **Brownfield** — ofrece ejecutar `wize-document-project` para crear la baseline del código existente. Tras instalar, abre tu IDE y di: > "Activa a Wizer y dale el briefing del proyecto." --- ## Harnesses soportados Los 11 IDEs objetivo se renderizan desde la misma fuente; el formato y la mecánica varían por harness. **OpenCode** recibe la integración más profunda — la separación persona/workflow del kit se mapea sobre las primitivas propias de OpenCode (`mode: primary|subagent`, `agent:`, `subtask:`) en lugar de aplanarse en un único tipo de archivo. | Harness | Salida | Destacado | |---|---|---| | **OpenCode** 🆕 | `.opencode/agents/` + `.opencode/commands/` | `mode: primary\|subagent` nativo; los comandos se vinculan automáticamente a su persona propietaria (`agent:`); los workers de fan-out corren aislados (`subtask: true`). [Docs →](docs/harnesses/opencode.md) | | **Claude Code** | `.claude/skills/*/SKILL.md` | Formato Skill de Anthropic; fan-out ad-hoc vía Task/Agent tool (`wize-code-review`). [Docs →](docs/harnesses/claude-code.md) | | **Codex** | `.agents/skills/*/SKILL.md` | Mismo formato Skill + `AGENTS.md` en la raíz. [Docs →](docs/harnesses/codex.md) | | **Kimi Code** | `.kimi/skills/*/SKILL.md` | Mismo formato Skill; autodetecta árboles de skills de Claude/Codex. [Docs →](docs/harnesses/kimi-code.md) | | **Hermes Agent** 🆕 | `.hermes/skills/*/SKILL.md` | Mismo formato Skill, project-local; trust gate (`hermes skills trust`); las skills del proyecto sobreescriben las de perfil. [Docs →](docs/harnesses/hermes.md) | | **Kiro — AWS** 🆕 | `.kiro/skills/*/SKILL.md` | Estándar Agent Skills (agentskills.io); las skills de workspace sobrescriben las globales; activación automática por descripción, o `/wize-{code}`. [Docs →](docs/harnesses/kiro.md) | | **Antigravity** | `.agent/skills/*/SKILL.md` | Mismo formato Skill + `AGENTS.md` en la raíz. [Docs →](docs/harnesses/antigravity.md) | | **Cursor** | `.cursor/rules/*.mdc` | Reglas on-demand (`alwaysApply: false`), emparejadas por descripción. [Docs →](docs/harnesses/cursor.md) | | **Windsurf** | `.windsurf/rules/*.md` | Markdown plano; el modo de activación se define dentro del IDE. [Docs →](docs/harnesses/windsurf.md) | | **Continue.dev** | `.continue/prompts/*.prompt` | Slash commands con `invokable: true`. [Docs →](docs/harnesses/continue.md) | | **Fallback genérico** | `.wize/agents/*.md` + `AGENTS.md` en la raíz | Para cualquier IDE sin adapter dedicado. [Docs →](docs/harnesses/generic.md) | --- ## El elenco | # | Persona | Código | Rol | |---|---|---|---| | 1 | **Wizer** | `wize-orchestrator` | Orquestador, base de conocimiento, briefing, enrutamiento | | 2 | **Pepper Potts** | `wize-agent-analyst` | Analista de Negocio + WDS Saga (brief de producto, trigger map) | | 3 | **Peggy Carter** | `wize-agent-tech-writer` | Redactora Técnica (transversal) | | 4 | **Maria Hill** | `wize-agent-pm` | Product Manager (PRD, epics, sprints) | | 5 | **Mantis** | `wize-agent-ux-designer` | UX Designer + WDS Freya (escenarios, diseño, design system) | | 6 | **Nick Fury** | `wize-agent-solution-strategist` | Estrategia de Solución, visión técnica, principios de NFR | | 7 | **Tony Stark** | `wize-agent-architect` | Arquitecto de Sistemas (arquitectura, ADRs, epics, stories) | | 8 | **Hawkeye** | `wize-agent-test-architect` | Test Architect — 6 gates (risk, design, trace, nfr, review, gate) | | 9 | **Shuri** | `wize-agent-dev` | Desarrolladora Senior (TDD, código, refactor) | | 10 | **Natasha Romanoff** | `wize-sec-red-teamer` (overlay de seguridad) | Red-Teamer / Pentester de IA — recon, SAST/DAST, pruebas ofensivas con alcance, informe | Consulta [`ROSTER.md`](ROSTER.md) para personas, estilos y equivalencias con BMAD. --- ## Recorrido — un proyecto completo, de principio a fin Cada paso es un slash command en tu IDE; cada persona lee el artefacto anterior antes de escribir el suyo. ``` 1. /wize-orchestrator Wizer saluda, lee config, detecta el estado y enruta. 2. /wize-grill Cualquier persona te entrevista hasta un entendimiento compartido antes de redactar — una pregunta a la vez, cada una con respuesta recomendada (ofrecida, nunca impuesta). /wize-product-brief Pepper convierte la demanda bruta en brief.md. /wize-trigger-map Pepper mapea psicología del usuario → metas de negocio (WDS). /wize-research Pepper sintetiza evidencia externa (opcional). 3. /wize-create-prd Maria Hill escribe prd.md (metas, alcance, ACs). /wize-validate-prd Maria Hill (+ Mantis/Fury) aprueba. 4. /wize-ux-scenarios Mantis conduce el diálogo WDS de 8 preguntas. /wize-ux-design Mantis escribe specs de pantalla (un .md por pantalla). 5. /wize-tech-vision Fury elige la familia de stack + innegociables. /wize-nfr-principles Fury escribe el presupuesto de NFR (perf, seg, a11y…). 6. /wize-create-architecture Tony escribe architecture.md + ADRs (8 pasos). /wize-design-system Mantis escribe design-system/ (tokens + componentes). /wize-create-epics-and-stories Tony divide epics → stories (cada una con ACs). 7. /wize-sprint-planning Maria Hill abre el sprint desde los epics/stories. /wize-tea-risk Hawkeye construye el perfil global de riesgo. /wize-tea-design Hawkeye escribe el test design de la próxima story. /wize-create-story Tony escribe la siguiente story con los campos de contrato: fuentes de verdad, restricciones, validación, done-means. /wize-dev-story Shuri implementa (TDD, IDs de AC en los commits) con loop auto-verificable y guarda de 3 ciclos. /wize-tea-trace Hawkeye mapea cada AC → tests. /wize-tea-review Hawkeye ejecuta la revisión de la story. /wize-tea-gate Hawkeye emite PASS / CONCERNS / FAIL / WAIVED. 8. /wize-sprint-status Maria Hill mantiene el snapshot diario actualizado. /wize-retrospective Wizer facilita la retro al final de cada sprint. Transversales: /wize-help Wizer te enruta: `next` (única acción siguiente), `status` (snapshot del proyecto), `mission` (un contrato de misión lleno para la persona ejecutora). /wize-check Checklist de avance de la demanda en vuelo: hecho (con evidencia), en curso, lo que falta — luego retoma el trabajo interrumpido. /wize-update Revisa si el kit está desactualizado, muestra el changelog, confirma y aplica la actualización. /wize-grill Entrevista-hasta-entendimiento antes de cualquier paso de autoría. /wize-no-ai-slop Higiene de escrita para texto de usuario final: elimina patrones de "AI slop" y palabras de relleno preservando la voz del autor. También detecta slop. /wize-quick-dev Shuri toma un arreglo pequeño sin el ciclo completo. /wize-pre-pr-check Corre lint/format/build/tests unitarios localmente antes de abrir un PR — falla rápido, cero costo de runner. /wize-correct-course Re-planifica cuando un gate falla o el loop se estanca (auto-disparado por la guarda de max-cycles; también manual). /wize-code-review Revisión adversarial antes del gate TEA de Hawkeye. /wize-party-mode Wizer reúne multi-persona para decisiones difíciles. ``` > Usa `/wize-help next` cuando tengas dudas — inspecciona `.wize/` y te dice la única acción siguiente. --- ## 🛡️ Overlay de seguridad — Pentester de IA Con el perfil **Wize Security** instalado, **Natasha Romanoff** (`wize-sec-red-teamer`, la persona red-teamer) ejecuta un pentest file-first de tu proyecto y produce un informe listo para stakeholders. ### Cómo funciona 1. **Autoriza el objetivo.** Declaras hosts/URLs permitidos en un `.wize/security/scope.md` firmado (integridad por SHA-256). Cualquier cosa fuera de la allowlist es **rechazada y auditada** — la herramienta nunca toca un objetivo que no autorizaste. 2. **Ejecuta el pipeline.** ``` /wize-sec-pentest # pasivo por defecto (chequeos read-only) /wize-sec-pentest --active # habilita tooling ofensivo (sqlmap, ffuf) ``` Encadena: **recon** (nmap) → **enumerate** (superficie HTTP) → **SAST** (secrets con gitleaks + deps con osv-scanner/grype) → **DAST** (nuclei, nikto, sqlmap, ffuf) → **report**. 3. **Lee el informe.** `report.md` + un `report.html` self-contained (offline, WCAG 2.2 AA) con: - **Puntuación de riesgo 0–100** + **briefing** ejecutivo (qué significa el riesgo para el negocio), - hallazgos clasificados por **CVSS v3.1** y **OWASP Top 10**, con secrets redactados, - **cobertura honesta** ("audit confidence" — qué se probó y qué no), - un **plan de acción priorizado** (P0/P1/P2). 4. **Planifica la corrección.** El scan genera `security-backlog.md` (epics de remediación agrupados por tema, trazables a los hallazgos) e imprime el comando exacto para convertirlo en un sprint: ``` /wize-create-epics-and-stories --from .wize/security/security-backlog.md ``` ### Garantías de diseño - **Cero runtime propio** — solo built-ins de Node; ninguna dependencia npm nueva; el overlay nunca invoca una skill (imprime el comando para que tú/el agente lo ejecuten). - **Los datos quedan locales** — informes y hallazgos se escriben en `.wize/security/`, nunca se suben a ningún lado. - **Las herramientas se detectan, nunca se auto-instalan** — un preflight comprueba tu toolchain y genera un `install-pentest-tools.sh` consciente del SO (apt para nmap/nikto/sqlmap; releases de GitHub para gitleaks/nuclei/ffuf/osv-scanner; script oficial para grype). Una herramienta ausente degrada solo ese chequeo — el pipeline continúa. - **Pasivo por defecto** — el tooling ofensivo (sqlmap/ffuf) solo corre con `--active`; flags peligrosas (`--dump`, `--os-shell`) son vetadas por una allowlist independiente del input. > ⚠️ **Herramienta de doble uso.** Prueba solo sistemas que poseas o estés explícitamente autorizado a probar. --- ## Estructura de salida (en el repositorio objetivo) ``` .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 y referencias de larga duración ├── security/ # scope.md, report.{md,html}, security-backlog.md (overlay de seguridad) └── custom/ # agents/skills/workflows creados por Agent Builder ``` --- ## Comandos de la CLI ```bash npx wize-dev-kit install # setup interactivo npx wize-dev-kit update # actualiza un kit instalado a la versión actual npx wize-dev-kit sync # re-renderiza los adapters de IDE tras editar la config npx wize-dev-kit list # lista agentes, skills y workflows instalados npx wize-dev-kit agent list # lista agentes nativos + personalizados npx wize-dev-kit agent create # crea un nuevo agente personalizado (validado + dry-run) npx wize-dev-kit agent edit # sobrescribe un agente nativo npx wize-dev-kit workflow list # lista workflows nativos + personalizados npx wize-dev-kit workflow create # crea un nuevo workflow personalizado npx wize-dev-kit doctor # diagnostica kit / proyecto / adapters / gates npx wize-dev-kit validate # chequeos estructurales en los assets del kit npx wize-dev-kit document-project [quick|initial_scan|full_rescan|deep_dive] [--resume] [--target ] npx wize-dev-kit uninstall # elimina .wize/ (tu código queda intacto) npx wize-dev-kit help # referencia de comandos npx wize-dev-kit version # imprime la versión instalada del kit npx wize-dev-kit version-check [--json] # instalada vs. más reciente (con caché; scriptable; nunca bloquea) ``` --- ## Documentación - [`ARCH.md`](ARCH.md) — arquitectura completa: distribución, flujos, layout, instalador. - [`ROSTER.md`](ROSTER.md) — personas con estilo, rol, equivalencias BMAD. - [`AGENTS.md`](AGENTS.md) — el roster generado + el contexto operativo que las IDEs leen en la raíz del repo. - [`DECISIONS.md`](DECISIONS.md) — registro de decisiones. - [`CHANGELOG.md`](CHANGELOG.md) — historial de releases. - [`docs/harnesses/`](docs/harnesses/) — un doc por [harness soportado](#harnesses-soportados), en inglés + [pt-BR](README.pt-BR.md#harnesses-suportadas). --- ## Estado **v0.12.1 — beta.** El método nunca produce estimaciones de desarrollo — ni horas, ni puntos, ni tallas de camiseta; una story se dimensiona solo por si cabe en un único PR. El ciclo completo (análisis → plan → solución → implementación) está montado con 10 agentes y una biblioteca estructurada de skills. Los releases recientes suman **contratos de misión** (`/wize-help mission`), **`wize-grill`** (entrevista-hasta-entendimiento antes de cualquier paso de autoría), **`wize-pre-pr-check`** (gate local de lint/format/build/tests unitarios antes de abrir un PR — cero costo de runner de CI) y **loop verification** en `wize-dev-story` (un loop de implementación auto-verificable con guarda de max-cycles que escala a `wize-correct-course`). El `security-overlay` (Pentester de IA) entrega un pipeline de pentest completo, un informe ejecutivo (puntuación de riesgo + briefing + plan de acción por IA) y planificación de remediación post-scan — validado de principio a fin contra una aplicación Laravel/PHP real. Los adapters de IDE para Claude Code, Cursor, Windsurf, Codex, Continue, Kimi Code, Hermes, OpenCode y Antigravity se regeneran automáticamente — [OpenCode](docs/harnesses/opencode.md) recibe wiring nativo de `mode`/`agent`/`subtask`, la integración más profunda de las 10. --- ## Inspiración y créditos - [BMAD Method](https://github.com/bmad-code-org/BMAD-METHOD) por Brian (BMad) Madison — ciclo ágil de IA, personas de agentes, patrón de instalador, sistema de módulos. - [Whiteport Design Studio expansion](https://github.com/bmad-code-org/bmad-method-wds-expansion) — metodología UX-first, panteón nórdico (Saga, Freya), estructura de fases. - [No AI Slop](https://github.com/petergyang/no-ai-slop) por Peter Yang — higiene de escrita que elimina patrones de AI slop sin aplanar la voz del autor; la inspiración para `/wize-no-ai-slop`. - [apple-appstore-reviewer (awesome-copilot)](https://github.com/github/awesome-copilot/blob/main/skills/apple-appstore-reviewer/SKILL.md) — auditoría con mentalidad de reviewer para la submisión a App Store; la inspiración para `wize-app-store-review` (gate de publicación del overlay). Wize Development Kit es una **adaptación independiente** — no afiliada ni respaldada por los autores de BMAD o WDS. Los nombres de personas Marvel se usan como referencias creativas bajo uso nominativo justo. --- ## Licencia MIT — consulta [`LICENSE`](LICENSE). --- ## 🤖 Prerrequisito para colaborar con agentes de IA Antes de abrir este repo en cualquier agente (Claude Code, Cursor, Codex, Antigravity, OpenCode, Kimi, Qwen, …), instala el Wize Dev Kit: ```bash npx wize-dev-kit@latest install ``` Por qué: - Inyecta las skills `/wize-*` (analista, PM, arquitecto, dev, TEA, orquestador) que le dan estructura al ciclo de vida del proyecto. - Crea/actualiza una baseline brownfield en `.wize/knowledge/document-project/` — la fuente canónica a consultar antes de decidir cambios. - Habilita el seguimiento de actividad en `.wize/implementation/` — cada story, plan y gate queda auditable. - Estandariza idiomas y quality gates entre agentes vía `.wize/config/`. Sin el kit, el agente trabaja sin contexto histórico, sin gates y sin trazabilidad. Esto vale para cualquier agente de IA usado en el proyecto. Para Claude Code: empieza con `/wize-help` para un diagnóstico y el siguiente paso recomendado.