# Wize Development Kit > **Full-lifecycle AI-assisted development kit** β€” takes a project from brief to tested implementation through 10 specialized agents, with a Test Architect, a Whiteport UX studio, and an AI Pentester embedded. Runs inside your AI IDE. [![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) **🌐 Languages:** **English** Β· [PortuguΓͺs (pt-BR)](README.pt-BR.md) Β· [EspaΓ±ol](README.es.md) --- ## TL;DR ```bash npx wize-dev-kit install ``` Pick your profiles and IDE, then in your AI IDE say *"Activate Wizer and brief him on the project."* Wizer routes you through the right agent for each phase β€” brief, PRD, UX, architecture, tested code β€” and (optionally) runs an AI pentest of your app. --- ## What it is Wize Development Kit (WDK) is an installable **AI agent stack** that runs inside your AI IDE (Claude Code, Cursor, Windsurf, Codex, and others) and writes structured artifacts to a hidden `.wize/` folder in your repo. It takes a project from **brief β†’ PRD β†’ UX strategy β†’ architecture β†’ tested implementation**, and can also **pentest the running app and plan the remediation sprint**. It is **file-first and zero-runtime**: the agents are Markdown skills your IDE reads; the tooling is plain Node (a single runtime dependency, `prompts`, powers the interactive installer β€” nothing is added to your project). Nothing is mocked β€” every step reads the previous artifact and writes a real one. ### Profiles (combinable in monorepos) | Profile | What it adds | |---|---| | **Wize Dev Core** | Full lifecycle (analysis β†’ plan β†’ solution β†’ implementation) + Test Architect + Whiteport UX + Agent Builder. Always installed. | | **Wize Web Dev** *(overlay)* | Web scaffolds, SEO, analytics, WCAG playbook for Mantis, Playwright/Vitest for Hawkeye. | | **Wize App Development** *(overlay)* | Mobile scaffolds, store listing, App Store review gate (rejection-risk audit at publication), platform guidelines (HIG / Material 3), Detox/Maestro for Hawkeye. | | **Wize Security** *(overlay)* | **AI Pentester.** File-first pentest pipeline (recon β†’ enumerate β†’ SAST β†’ DAST β†’ report) driven by **Natasha Romanoff**, the `red-teamer` persona, with a scope gate, OWASP/CVSS classification, and a stakeholder report. | --- ## Install In any greenfield or brownfield repo: ```bash npx wize-dev-kit install ``` Or straight from GitHub (no npm needed): ```bash npx github:qwize-br/wize-development-kit install ``` The installer asks: 1. **Project name** β€” written into `.wize/config/project.toml`. 2. **Profile(s)** β€” Core / +Web / +App / +Security (multi-select). 3. **IDE target(s)** β€” Claude Code, Cursor, Windsurf, Codex, Continue, Kimi Code, Hermes, Kiro, OpenCode, Antigravity, or generic fallback (multi-select). 4. **Languages** β€” communication + document output. 5. **Your name** β€” how the agents should address you (saved to `user.toml`). 6. **Brownfield** β€” offers to run `wize-document-project` to baseline the existing codebase. After install, open your IDE and say: > "Activate Wizer and brief him on the project." --- ## Supported harnesses All 11 IDE targets render from the same source; format and mechanics differ per harness. **OpenCode** gets the deepest integration β€” the kit's persona/workflow split maps onto OpenCode's own primitives (`mode: primary|subagent`, `agent:`, `subtask:`) instead of being flattened into one file type. | Harness | Output | Notable | |---|---|---| | **OpenCode** πŸ†• | `.opencode/agents/` + `.opencode/commands/` | Native `mode: primary\|subagent`; commands auto-bind to their owning persona (`agent:`); fan-out workers run isolated (`subtask: true`). [Docs β†’](docs/harnesses/opencode.md) | | **Claude Code** | `.claude/skills/*/SKILL.md` | Anthropic Skill format; ad-hoc Task/Agent-tool fan-out (`wize-code-review`). [Docs β†’](docs/harnesses/claude-code.md) | | **Codex** | `.agents/skills/*/SKILL.md` | Same Skill format + root `AGENTS.md`. [Docs β†’](docs/harnesses/codex.md) | | **Kimi Code** | `.kimi/skills/*/SKILL.md` | Same Skill format; auto-detects Claude/Codex skill trees. [Docs β†’](docs/harnesses/kimi-code.md) | | **Hermes Agent** πŸ†• | `.hermes/skills/*/SKILL.md` | Same Skill format, project-local; trust gate (`hermes skills trust`); project skills override profile ones. [Docs β†’](docs/harnesses/hermes.md) | | **Kiro β€” AWS** πŸ†• | `.kiro/skills/*/SKILL.md` | Agent Skills standard (agentskills.io); workspace skills override global ones; auto-activates by description, or `/wize-{code}`. [Docs β†’](docs/harnesses/kiro.md) | | **Antigravity** | `.agent/skills/*/SKILL.md` | Same Skill format + root `AGENTS.md`. [Docs β†’](docs/harnesses/antigravity.md) | | **Cursor** | `.cursor/rules/*.mdc` | On-demand rules (`alwaysApply: false`), matched by description. [Docs β†’](docs/harnesses/cursor.md) | | **Windsurf** | `.windsurf/rules/*.md` | Plain markdown; activation mode set inside the IDE. [Docs β†’](docs/harnesses/windsurf.md) | | **Continue.dev** | `.continue/prompts/*.prompt` | `invokable: true` slash commands. [Docs β†’](docs/harnesses/continue.md) | | **Generic fallback** | `.wize/agents/*.md` + root `AGENTS.md` | For any IDE without a dedicated adapter. [Docs β†’](docs/harnesses/generic.md) | --- ## The roster | # | Persona | Code | Role | |---|---|---|---| | 1 | **Wizer** | `wize-orchestrator` | Orchestrator, knowledge base, briefing, routing | | 2 | **Pepper Potts** | `wize-agent-analyst` | Business Analyst + WDS Saga (product brief, trigger map) | | 3 | **Peggy Carter** | `wize-agent-tech-writer` | Technical Writer (transversal) | | 4 | **Maria Hill** | `wize-agent-pm` | Product Manager (PRD, epics, sprints) | | 5 | **Mantis** | `wize-agent-ux-designer` | UX Designer + WDS Freya (scenarios, design, design system) | | 6 | **Nick Fury** | `wize-agent-solution-strategist` | Solution Strategy, tech vision, NFR principles | | 7 | **Tony Stark** | `wize-agent-architect` | System Architect (architecture, ADRs, epics, stories) | | 8 | **Hawkeye** | `wize-agent-test-architect` | Test Architect β€” 6 gates (risk, design, trace, nfr, review, gate) | | 9 | **Shuri** | `wize-agent-dev` | Senior Developer (TDD, code, refactor) | | 10 | **Natasha Romanoff** | `wize-sec-red-teamer` (security overlay) | Red-Teamer / AI Pentester β€” recon, SAST/DAST, scoped offensive testing, reporting | See [`ROSTER.md`](ROSTER.md) for personas, styles and BMAD equivalences. --- ## Walkthrough β€” a full project, end to end Each step is a slash command in your IDE; each persona reads the previous artifact before writing its own. ``` 1. /wize-orchestrator Wizer greets, reads config, detects state, routes you. 2. /wize-grill Any persona interviews you to shared understanding before drafting β€” one question at a time, each with a recommended answer (offered, never forced). /wize-product-brief Pepper turns raw demand into brief.md. /wize-trigger-map Pepper maps user psychology β†’ business goals (WDS). /wize-research Pepper synthesizes external evidence (optional). 3. /wize-create-prd Maria Hill writes prd.md (goals, scope, ACs). /wize-validate-prd Maria Hill (+ Mantis/Fury) signs off. 4. /wize-ux-scenarios Mantis runs the 8-question WDS dialog. /wize-ux-design Mantis writes page specs (one .md per screen). 5. /wize-tech-vision Fury picks the stack family + non-negotiables. /wize-nfr-principles Fury writes the NFR budget (perf, sec, a11y…). 6. /wize-create-architecture Tony writes architecture.md + ADRs (8 steps). /wize-design-system Mantis writes design-system/ (tokens + components). /wize-create-epics-and-stories Tony slices epics β†’ stories (each has ACs). 7. /wize-sprint-planning Maria Hill opens the sprint from the epics/stories. /wize-tea-risk Hawkeye builds the global risk profile. /wize-tea-design Hawkeye writes test design for the next story. /wize-create-story Tony writes the next story (contract fields: sources of truth, restrictions, validation, done-means). /wize-dev-story Shuri implements (TDD, AC IDs in commits) with a self-verifying loop and a 3-cycle escalation guard. /wize-tea-trace Hawkeye maps each AC β†’ tests. /wize-tea-review Hawkeye runs story review. /wize-tea-gate Hawkeye emits PASS / CONCERNS / FAIL / WAIVED. 8. /wize-sprint-status Maria Hill keeps the daily snapshot updated. /wize-retrospective Wizer facilitates retro at end of each sprint. Cross-cutting: /wize-help Wizer routes you: `next` (single next action), `status` (project snapshot), `mission` (a filled mission contract for the executing persona). /wize-check Progress checklist for the demand in flight: done (with evidence), in progress, what's left β€” then resumes the interrupted work. /wize-update Checks kit version skew, shows the changelog jump, confirms, then applies the update. /wize-grill Interview-to-understanding before any authoring step. /wize-eli5 Explain anything to anyone β€” vocabulary, analogies, tone, depth and framing calibrated to the audience (age, role, relationship). /wize-no-ai-slop Writing hygiene for end-user-facing prose: removes AI-slop patterns and filler while preserving the writer's voice. Detects slop on request. /wize-quick-dev Shuri takes a small fix without the full ride. /wize-pre-pr-check Run lint/format/build/unit tests locally before opening a PR β€” fail fast, zero CI runner cost. /wize-correct-course Re-plan when a gate fails or a loop stalls (auto- triggered by the max-cycles guard; also manual). /wize-code-review Adversarial peer review before Hawkeye's TEA gate. /wize-party-mode Wizer convenes multi-persona for hard calls. ``` > Use `/wize-help next` whenever you're unsure β€” it inspects `.wize/` and tells you the single next action. --- ## πŸ›‘οΈ Security overlay β€” AI Pentester When the **Wize Security** profile is installed, **Natasha Romanoff** (`wize-sec-red-teamer`, the red-teamer persona) runs a file-first pentest of your project and produces a stakeholder-ready report. ### How it works 1. **Authorize the target.** You declare allowed hosts/URLs in a signed `.wize/security/scope.md` (SHA-256 integrity). Anything outside the allowlist is **refused and audited** β€” the tool never touches a target you didn't authorize. 2. **Run the pipeline.** ``` /wize-sec-pentest # passive by default (read-only checks) /wize-sec-pentest --active # enables active exploit tooling (sqlmap, ffuf) ``` It chains: **recon** (nmap) β†’ **enumerate** (HTTP surface) β†’ **SAST** (gitleaks secrets + osv-scanner/grype deps) β†’ **DAST** (nuclei, nikto, sqlmap, ffuf) β†’ **report**. 3. **Read the report.** `report.md` + a self-contained `report.html` (offline, WCAG 2.2 AA) with: - **Risk score 0–100** + executive **briefing** (what the risk means for the business), - findings classified by **CVSS v3.1** and **OWASP Top 10**, with redacted secrets, - **honest coverage** ("audit confidence" β€” what was and wasn't tested), - a **prioritized action plan** (P0/P1/P2). 4. **Plan the fix.** The scan emits `security-backlog.md` (remediation epics grouped by theme, traceable to findings) and prints the exact command to turn it into a sprint: ``` /wize-create-epics-and-stories --from .wize/security/security-backlog.md ``` ### Design guarantees - **Zero runtime of its own** β€” Node built-ins only; no new npm dependency; the overlay never invokes a skill (it prints the command for you/the agent to run). - **Data stays local** β€” reports and findings are written under `.wize/security/`, never uploaded anywhere. - **Tools are detected, never auto-installed** β€” a preflight checks your toolchain and generates an OS-aware `install-pentest-tools.sh` (apt for nmap/nikto/sqlmap; GitHub releases for gitleaks/nuclei/ffuf/osv-scanner; official script for grype). Missing tools degrade a single check gracefully β€” the pipeline keeps going. - **Default passive** β€” offensive tooling (sqlmap/ffuf) runs only with `--active`; dangerous flags (`--dump`, `--os-shell`) are vetoed by an allowlist regardless of input. > ⚠️ **Dual-use tool.** Only test systems you own or are explicitly authorized to test. --- ## Output layout (in the target repo) ``` .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/ # long-lived docs and references β”œβ”€β”€ security/ # scope.md, report.{md,html}, security-backlog.md (security overlay) └── custom/ # agents/skills/workflows created by Agent Builder ``` --- ## CLI commands ```bash npx wize-dev-kit install # interactive setup npx wize-dev-kit update # bring an installed kit up to the current version npx wize-dev-kit sync # re-render IDE adapters after editing config npx wize-dev-kit list # list installed agents, skills and workflows npx wize-dev-kit agent list # list built-in + custom agents npx wize-dev-kit agent create # scaffold a new custom agent (validated + dry-run) npx wize-dev-kit agent edit # override a built-in agent npx wize-dev-kit workflow # scaffold or list custom workflows npx wize-dev-kit doctor # diagnose kit / project / adapters / gates npx wize-dev-kit validate # structural checks on the kit assets npx wize-dev-kit document-project [quick|initial_scan|full_rescan|deep_dive] [--resume] [--target ] npx wize-dev-kit uninstall # remove .wize/ (your code is left untouched) npx wize-dev-kit help # command reference npx wize-dev-kit version # print the installed kit version npx wize-dev-kit version-check [--json] # installed vs latest (cached; scriptable; never blocks) ``` --- ## Documentation - [`ARCH.md`](ARCH.md) β€” full architecture: distribution, flows, layout, installer. - [`ROSTER.md`](ROSTER.md) β€” personas with style, role, BMAD equivalences. - [`AGENTS.md`](AGENTS.md) β€” the generated roster + operating context IDEs read at the repo root. - [`DECISIONS.md`](DECISIONS.md) β€” decisions log. - [`CHANGELOG.md`](CHANGELOG.md) β€” release history. - [`docs/harnesses/`](docs/harnesses/) β€” one doc per [supported harness](#supported-harnesses), in English + [pt-BR](README.pt-BR.md#harnesses-suportadas). --- ## Status **v0.12.1 β€” beta.** The method never produces development estimates β€” no hours, points, or t-shirt sizes; a story is sized only by whether it fits a single PR. The full lifecycle (analysis β†’ plan β†’ solution β†’ implementation) is wired with 10 agents and a structured skill library. Recent releases add **mission contracts** (`/wize-help mission`), **`wize-grill`** (interview-to-shared-understanding before any authoring step), **`wize-pre-pr-check`** (local lint/format/build/unit-test gate before opening a PR β€” zero CI runner cost), and **loop verification** in `wize-dev-story` (a self-checking implementation loop with a max-cycles guard that escalates to `wize-correct-course`). The `security-overlay` (AI Pentester) ships a complete pentest pipeline, a stakeholder report (risk score + briefing + AI action plan), and post-scan remediation planning β€” validated end-to-end against a real Laravel/PHP app. IDE adapters for Claude Code, Cursor, Windsurf, Codex, Continue, Kimi Code, Hermes, OpenCode, and Antigravity are regenerated automatically β€” [OpenCode](docs/harnesses/opencode.md) gets native `mode`/`agent`/`subtask` wiring, the deepest integration of the 10. --- ## Inspiration & credits - [BMAD Method](https://github.com/bmad-code-org/BMAD-METHOD) by Brian (BMad) Madison β€” agile AI lifecycle, agent personas, installer pattern, module system. - [Whiteport Design Studio expansion](https://github.com/bmad-code-org/bmad-method-wds-expansion) β€” UX-first methodology, Norse pantheon (Saga, Freya), phase structure. - [ELI5](https://github.com/dreambigou/eli5) by Andrew Ou β€” audience-calibrated explanations; the inspiration for `/wize-eli5`. - [No AI Slop](https://github.com/petergyang/no-ai-slop) by Peter Yang β€” writing hygiene that removes AI-slop patterns without flattening the writer's voice; the inspiration for `/wize-no-ai-slop` (Peggy Carter & Mantis apply it to end-user-facing prose). - [awesome-copilot's apple-appstore-reviewer](https://github.com/github/awesome-copilot/blob/main/skills/apple-appstore-reviewer/SKILL.md) β€” reviewer-mindset audit for App Store submission; the inspiration for `wize-app-store-review` (the app-overlay publication gate). Wize Development Kit is an **independent adaptation** β€” not affiliated with or endorsed by BMAD or WDS authors. Marvel persona names are used as creative references under nominative fair use. --- ## License MIT β€” see [`LICENSE`](LICENSE). --- ## πŸ€– Prerequisite for collaborating with AI agents Before opening this repo in any agent (Claude Code, Cursor, Codex, Antigravity, OpenCode, Kimi, Qwen, …), install the Wize Dev Kit: ```bash npx wize-dev-kit@latest install ``` Why: - Injects the `/wize-*` skills (analyst, PM, architect, dev, TEA, orchestrator) that give the project lifecycle its structure. - Creates/updates a brownfield baseline in `.wize/knowledge/document-project/` β€” the canonical source to consult before deciding on changes. - Enables activity tracking in `.wize/implementation/` β€” every story, plan, and gate stays auditable. - Standardizes languages and quality gates across agents via `.wize/config/`. Without the kit, the agent works with no historical context, no gates, and no traceability. This holds for every AI agent used on the project. For Claude Code: start with `/wize-help` for a diagnosis and the recommended next step.