wize-dev-kit 0.17.0 → 0.19.0

package/CHANGELOG.md

@@ -7,7 +7,17 @@ Format inspired by [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 > **0.10.0 and earlier are in Brazilian Portuguese** and are kept verbatim as a
 > historical record (not back-translated).
 
-## [Unreleased]
+## [0.19.0] — 2026-09-18
+
+### Added
+
+- **`wize-no-ai-slop`** (core skill) — writing hygiene for end-user-facing prose, adapted from [no-ai-slop](https://github.com/petergyang/no-ai-slop) by Peter Yang (MIT, credited in the READMEs). Two jobs: apply while writing (17 AI-slop patterns to cut — binary contrasts, throat-clearing, faux-insight setups, importance puffery, weasel attribution, fake-profound kickers, formatting slop, etc. — plus banned filler words, voice preservation, portability test) and detect on request (name each pattern with a quoted line; no rewriting, no guessing AI authorship). Wired into Peggy Carter (`wize-agent-tech-writer`) and Mantis (`wize-agent-ux-designer`) agent skills + persona styles; registered in the core module catalog; rendered by all 11 harness adapters.
+
+## [0.18.0] — 2026-09-18
+
+### Added
+
+- **`wize-update`** (orchestrator skill) + **`wize-dev-kit version-check`** (CLI) — an agent-facing way to ask "is there a newer kit?" without hitting the network on every invocation. `version-check --json` reads a local 1h cache first, caps any registry call at ~1.5s, and degrades to `{"latest":null}` silently when offline; it honors `WIZE_DISABLE_UPDATE_CHECK=1` like the existing opportunistic hint. `wize-help`/`wize`'s proactive version-skew check (Step 2.5) now calls it instead of a live `npm view` on every invocation, says the hint at most once per conversation, and points to `/wize-update` — which shows the version jump + changelog excerpt, asks for a one-line confirmation, then runs `npx wize-dev-kit@latest update` and relays the result. Intent phrases: "atualizar o kit", "tem atualização", "nova versão do kit".
 
 ## [0.17.0] — 2026-09-08
 

package/README.es.md

@@ -157,8 +157,13 @@ Transversales:
     /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.
@@ -240,6 +245,7 @@ npx wize-dev-kit document-project [quick|initial_scan|full_rescan|deep_dive] [--
 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)
 ```
 
 ---
@@ -265,6 +271,7 @@ npx wize-dev-kit version         # imprime la versión instalada del kit
 
 - [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`.
 
 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.
 

package/README.md

@@ -155,10 +155,15 @@ Cross-cutting:
     /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.
@@ -238,6 +243,7 @@ npx wize-dev-kit document-project [quick|initial_scan|full_rescan|deep_dive] [--
 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)
 ```
 
 ---
@@ -264,6 +270,7 @@ npx wize-dev-kit version         # print the installed kit version
 - [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).
 
 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.
 

package/README.pt-BR.md

@@ -156,8 +156,16 @@ Transversais:
     /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.
@@ -238,6 +246,7 @@ npx wize-dev-kit document-project [quick|initial_scan|full_rescan|deep_dive] [--
 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)
 ```
 
 ---
@@ -263,6 +272,7 @@ npx wize-dev-kit version         # imprime a versão instalada do kit
 
 - [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`.
 
 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.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "wize-dev-kit",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "Full-lifecycle AI-assisted development kit with Test Architect and Whiteport Design Studio embedded. Inspired by BMAD Method and WDS.",
   "keywords": [
     "ai",

package/src/core-skills/module.yaml

@@ -19,6 +19,9 @@ skills:
   - code: wize-eli5
     name: "ELI5"
     description: "Explain anything to anyone — adapts vocabulary, analogies, tone, depth and framing to the audience (age, role, relationship)."
+  - code: wize-no-ai-slop
+    name: "No AI Slop"
+    description: "Writing hygiene for end-user-facing prose — removes 17 AI-generated patterns and banned words while preserving the writer's voice; also detects slop without rewriting."
   - code: wize-brainstorming
     name: "Brainstorming"
     description: "Divergent-then-convergent ideation; produces idea-pool.md."

package/src/core-skills/wize-no-ai-slop/skill.md

@@ -0,0 +1,83 @@
+---
+code: wize-no-ai-slop
+description: "Use quando qualquer agente for escrever ou editar texto para usuário final — READMEs, runbooks, microcopy, release notes, UX copy — para remover padrões de 'AI slop' sem achatar a voz do autor. Também detecta slop em rascunhos sem reescrever."
+name: No AI Slop
+module: core
+status: ready
+---
+
+# No AI Slop — human writing hygiene
+
+**Goal.** End-user-facing prose (READMEs, runbooks, release notes, UX microcopy, docs, announcements) that reads like a sharp human wrote it — not like a model's default register. Remove AI-generated patterns without flattening the writer's personal voice. This is a hygiene pass every Wize agent applies when the reader is outside the team; internal artifacts (PRD, ADR, gate) keep their own conventions.
+
+Adapted to the Wize method from [no-ai-slop](https://github.com/petergyang/no-ai-slop) by Peter Yang (MIT) — credited in the README.
+
+## Two jobs
+
+**Apply while writing (default for Peggy & Mantis).** When drafting or editing end-user text, run the rules below as you write — not as a retrospective cosmetic pass. Produce the text plus, on request, a short **What changed** section.
+
+**Detect.** When asked whether a piece "reads like AI", name each pattern found with a quoted line and a short fix. Do not rewrite, do not score, and do not guess whether AI wrote it — named patterns are evidence the reader can check. Offer to edit after.
+
+## Voice first
+
+- **Preserve the writer's real voice.** Notice vocabulary, cadence, bluntness, humor, uncertainty, digressions, polish. Keep the traits that feel personal. Do not make every paragraph equally tidy.
+- **Minimum effective edit.** Fix patterns, errors, repetition, unclear passages. Leave strong human sentences alone.
+- **Keep the meaning.** Never invent claims, examples, stats, or opinions. If something is unclear, ask.
+- **Preserve useful edge.** Strong opinions, blunt language, honest admissions ("I think", "maybe") stay when they carry real uncertainty or the writer's spoken rhythm.
+
+## Principles
+
+- **Lead with the point** when the setup adds nothing; keep personal setups that add context, tension, or character.
+- **Front-load only where it helps** — never force every section into the same point-detail-background shape.
+- **Every sentence earns its place.** Cut empty qualifiers and throat-clearing.
+- **Active voice, human subjects.** "The team shipped it Tuesday" beats "the decision emerged". Never let inanimate things do human verbs.
+- **Verbs do the work.** "Made a decision" → "decided". "Has the ability to" → "can". Prefer plain `is`/`has` over fake-strong verbs ("serves as a hub").
+- **Concrete beats abstract.** "Improved efficiency" → "cut deploy time from 40 min to 4". Names, numbers, dates, mechanisms, examples.
+- **Portability test.** A sentence that could move unchanged to another company or product is filler — cut it or replace it with something specific to this subject.
+- **Show, don't label.** Make facts carry the emphasis; delete commentary that tells the reader a point is important, surprising, or obvious.
+- **Protect the specific fact.** Don't smooth a real detail into generic importance.
+- **Untangle without flattening cadence.** Split genuinely hard sentences; keep clear spoken rhythm and fragments that belong to the voice.
+
+## Words to cut
+
+- **Banned:** delve, foster, leverage, utilize, facilitate, empower, streamline, robust, cutting-edge, paradigm shift, game changer, this is huge, this changes everything, tapestry, realm, beacon, multifaceted, meticulous, intricate, paramount, transformative, elevate, embark, supercharge, harness, ever-evolving.
+- **Often-empty adverbs** (cut unless they carry emphasis or uncertainty): just, literally, honestly, simply, actually, truly, fundamentally, importantly, crucially, inherently, inevitably.
+- **Often-empty phrases** (cut when they delay the point): it's worth noting, at the end of the day, when it comes to, at its core, in today's world, the reality is, in terms of, with regard to, in order to, going forward, let's dive in.
+
+## Patterns to cut
+
+1. **Binary contrasts** — "It's not X. It's Y." State Y directly.
+2. **Throat-clearing openers** — "Here's the thing", "Let me be clear". State the point.
+3. **Faux-insight setups** — "What nobody tells you", "The part everyone misses". Make the claim stand alone.
+4. **Colon reveals** — "The best part: it learns." Use colons for lists and labels, not fake drama.
+5. **Superficial analysis** — trailing "-ing" clauses that pretend to explain ("…, highlighting the team's commitment"). State the actual consequence.
+6. **Importance puffery** — "marks a pivotal moment", "a testament to". State the fact; let the reader judge.
+7. **Interpretive metadiscourse** — "That last part matters", "As you can see", "The key point is". Delete.
+8. **Weasel attribution** — "experts agree", "studies show". Name the source or cut; ask before inventing one.
+9. **Synonym cycling** — if the clear word is right, repeat it.
+10. **Negative listing** — "Not a X. Not a Y. A Z." → just say Z.
+11. **Dramatic fragments** — "That's it. That's the whole thing." Use complete sentences.
+12. **Robotic rhythm** — vary repeated sentence shapes and paragraph structures only when it helps the point.
+13. **Rhetorical setups** — "What if I told you…", "Think about it:", self-answered "Question? Answer."
+14. **Fake-profound kickers** — delete the cute final line; end on the clearest concrete sentence, takeaway, or next action.
+15. **Summary-recap endings** — "In conclusion", "Ultimately", restating the piece.
+16. **Formatting slop** — emoji in headings, bold sprinkled mid-sentence, bullets where two sentences of prose read better, headers over two-sentence sections.
+17. **Em dashes as a rhythm crutch** — none in short copy; 1–2 in long drafts only when they clearly beat commas or parentheses.
+
+## Self-check (eval)
+
+Before handing off end-user prose, answer:
+
+- Does it preserve the writer's point, voice, and useful edge — without invented claims? (pass/fail)
+- Is cutting proportional, leaving strong human sentences alone? (pass/fail)
+- Does every generic sentence survive the portability test? (pass/fail)
+- Are banned words, filler phrases, and the 17 patterns absent? (pass/fail)
+- Would the writer recognize it as their own voice when read to a sharp colleague? (pass/fail)
+
+If any check fails, fix and re-check before returning the draft.
+
+## When NOT to use
+
+- Internal Wize artifacts (PRD, ADR, story, gate) — they have their own editorial skills (`wize-editorial-review-prose` / `wize-editorial-review-structure`).
+- Spelling/grammar — use a linter.
+- The user wants audience calibration (age, role, depth) → that's `wize-eli5`; combine both when writing for a tuned audience.

package/src/method-skills/1-analysis/wize-agent-tech-writer/agent.yaml

@@ -17,6 +17,7 @@ style:
   approach: "structure > prose; audience-first"
 
 skills:
+  - wize-no-ai-slop             # hygiene pass on every end-user-facing draft
   - wize-editorial-review-prose
   - wize-editorial-review-structure
   - wize-document-project   # paired with Pepper in brownfield

package/src/method-skills/1-analysis/wize-agent-tech-writer/persona.md

@@ -16,6 +16,7 @@ I am **Peggy Carter**. I make the team's writing sound like one team. Structure,
 
 - I never write "this comprehensive solution." I cut filler.
 - Audience first: who reads this? what do they need? cut everything else.
+- I run the `wize-no-ai-slop` rules on everything end users will read: no AI slop patterns, no banned filler words — but I never flatten the writer's voice. Minimum effective edit; strongest human sentences stay.
 - Structure before sentences: I outline, then I write.
 - I quote sources. I show diagrams. I prefer a table over a paragraph.
 

package/src/method-skills/2-plan-workflows/wize-agent-ux-designer/agent.yaml

@@ -23,6 +23,7 @@ skills:
   - wize-ux-scenarios
   - wize-ux-design
   - wize-design-system
+  - wize-no-ai-slop             # UX copy and scenario prose that end users read
 
 inputs:
   - ".wize/planning/prd.md"

package/src/method-skills/2-plan-workflows/wize-agent-ux-designer/persona.md

@@ -12,9 +12,12 @@ I am **Mantis**. I feel what the user is going to feel before they feel it. Then
 
 ## Style
 
+- Empathy before pixels: feel the user, then design.
+- I show, I don't tell — in specs and in copy. No "revolutionary", no "game changer"; the interface demonstrates the value.
+- UI copy and scenario prose end users will read goes through the `wize-no-ai-slop` rules: concrete, active voice, writer's voice preserved.
 - Quiet, attentive. I ask what hurts before I propose.
 - I prefer scenarios over personas. People act; they aren't archetypes.
-- I show, then I tell. ASCII wireframes first, prose second.
+- ASCII wireframes first, prose second.
 - I cite research. If I don't have research, I say "this is a hypothesis."
 
 ## What I won't do

package/src/orchestrator-skills/module.yaml

@@ -22,6 +22,9 @@ skills:
   - code: wize-check
     name: "Check (Wizer)"
     description: "Progress checklist for the demand in flight: done (with evidence), in progress, left, blocked. Read-only — reports, then resumes the interrupted work."
+  - code: wize-update
+    name: "Update (Wizer)"
+    description: "Checks kit version skew, shows the changelog jump, confirms, then applies `wize-dev-kit update` and reports the result."
   - code: wize-onboarding
     name: "Onboarding"
     description: "Post-install triage: greenfield vs brownfield, profile, objective. Delegates to specialists."

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

@@ -99,15 +99,15 @@ See the full intent routing table in `wize-help/skill.md` (Step 2a). The same ta
 
 ## 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`:
+If you have Bash, run `npx wize-dev-kit version-check --json` once — it reads a local 1h cache before touching the network, caps any registry call at ~1.5s, and degrades to `{"latest":null}` silently if offline, so this never blocks the response. Compare its `installed` field against `kit_version` (project.toml):
 
 | Condition | Suggest |
 |---|---|
-| installed > project.toml | `npx wize-dev-kit update` |
-| registry > installed | `npx wize-dev-kit@latest update` |
-| all match | nothing |
+| `installed` > `kit_version` (project.toml) | `/wize-update` |
+| `latest` > `installed` | `/wize-update` |
+| everything matches, or `latest` is `null` | nothing |
 
-Phrase as one short line, not a banner. If the user agrees and you have Bash, run it in the project root.
+Phrase as one short line, not a banner — and only the **first time in this conversation**. If you already mentioned it earlier in this session, don't repeat it.
 
 ## Step 3 — respond
 

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

@@ -201,18 +201,19 @@ Match is case-insensitive, substring-based. Longest match wins. When no intent m
 | "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` |
+| "atualizar o kit", "tem atualização", "nova versão do kit", "update the kit", "wize update" | `wize-update` |
 
 ## 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`:
+If you have Bash, run `npx wize-dev-kit version-check --json` once — it reads a local 1h cache before touching the network, caps any registry call at ~1.5s, and degrades to `{"latest":null}` silently if offline, so this never blocks the response. Compare its `installed` field against `kit_version` (project.toml):
 
 | Condition | Suggest |
 |---|---|
-| installed > project.toml | `npx wize-dev-kit update` |
-| registry > installed | `npx wize-dev-kit@latest update` |
-| all match | nothing |
+| `installed` > `kit_version` (project.toml) | `/wize-update` |
+| `latest` > `installed` | `/wize-update` |
+| everything matches, or `latest` is `null` | nothing |
 
-Phrase as one short line, not a banner. If the user agrees and you have Bash, run it in the project root.
+Phrase as one short line, not a banner — and only the **first time in this conversation**. If you already mentioned it earlier in this session, don't repeat it.
 
 ## Step 3 — respond
 

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

@@ -0,0 +1,61 @@
+---
+
+code: wize-update
+description: "Use quando o usuário pedir para atualizar o Wize Dev Kit, perguntar se há uma versão nova, ou quando o Wizer notar version skew (Step 2.5) e ele confirmar o update."
+name: Update (Wizer)
+module: orchestrator
+owner: wize-orchestrator
+status: ready
+aliases: []
+---
+
+# Wizer · `/wize-update`
+
+**Goal.** Bring the installed kit up to date safely: check the real version skew, show what changes before anything runs, get a one-line confirmation, apply it, report the result. Never a surprise — this rewrites files under version control.
+
+## Step 1 — check version skew
+
+If you have Bash, run:
+
+```
+npx wize-dev-kit version-check --json
+```
+
+Cheap by design: it reads a local 1h cache before touching the network, caps any registry call at ~1.5s, and degrades to `{"latest":null}` silently if offline — it never blocks this step.
+
+Read `kit_version` from `.wize/config/project.toml` — that is the version **this project's** rendered skills are on. `version-check`'s `installed` field is the kit version currently resolved by `npx` (it can already be newer than what is rendered here, if someone bumped the resolved package without running `update`).
+
+| Condition | Meaning |
+|---|---|
+| `latest` (registry) > `installed` | A newer kit exists upstream. |
+| `installed` > project's `kit_version` | This project is behind what npx already resolves. |
+| everything matches, or `latest` is `null` | Nothing to do — say so in one line and stop. Do not continue to Step 2. |
+
+## Step 2 — show the jump, then confirm
+
+State the version jump plainly (`{from} → {to}`). If you have Bash, `sed -n`/`cat` the relevant excerpt of `CHANGELOG.md` between those versions for a one-line summary of what changed — or trust the excerpt `update` itself prints in Step 3 and summarize that instead.
+
+Ask one line: *"Atualizar o kit de {from} para {to}? Isso vai re-renderizar os adapters instalados (claude-code, generic, …) e regravar `kit_version` em `project.toml`."*
+
+Never run Step 3 without this confirmation — it rewrites rendered skill/command files that live under version control, and the resulting diff should land as the user's own reviewed commit, not an unreviewed surprise.
+
+## Step 3 — run it
+
+On confirmation:
+
+```
+npx wize-dev-kit@latest update
+```
+
+Relay its output — it already reports per-adapter results and a CHANGELOG excerpt. It is idempotent and additive: it never touches `.wize/config/user.toml`, never removes custom agents/skills under `.wize/custom/`, and only rewrites the `kit_version` line in `project.toml`.
+
+## Step 4 — close the loop
+
+- Flag any adapter the output reported as `skipped` or `error` — those need a manual look.
+- Repeat, in one line, that the IDE/harness needs a restart to pick up refreshed slash commands.
+- Suggest reviewing the diff (`git status` / `git diff`) before committing — this is a real file change, not a no-op.
+
+## When NOT to use
+
+- No `.wize/` folder at all → this is a fresh install, not an update. Route to `npx wize-dev-kit install` (see `wize-onboarding`).
+- The user only wants to know whether an update exists, without applying it → Step 1 alone answers that; do not push into Step 2/3 unasked.

package/tools/installer/commands/version-check.js

@@ -0,0 +1,39 @@
+// `wize-dev-kit version-check` — explicit, agent-friendly version check.
+//
+// The other CLI commands print an opportunistic hint (version-check.js's
+// printUpdateHintIfAny) that stays silent on a non-TTY stdout so it never
+// spams a pipe. This command is the opposite: it was asked for by name —
+// by a human, or by an AI agent shelling out from a skill instruction where
+// stdout is never a TTY — so it always answers, in `--json` when a caller
+// needs to parse it.
+
+'use strict';
+
+const { getVersionCheckResult } = require('../version-check.js');
+
+async function cmdVersionCheck({ currentVersion, json = false, log = console.log } = {}) {
+  const result = await getVersionCheckResult(currentVersion);
+
+  if (json) {
+    log(JSON.stringify(result));
+    return result;
+  }
+
+  if (result.disabled) {
+    log('Update check disabled (WIZE_DISABLE_UPDATE_CHECK=1).');
+    return result;
+  }
+  if (!result.latest) {
+    log(`wize-dev-kit ${result.installed} (could not reach the registry — offline or timed out).`);
+    return result;
+  }
+  if (result.updateAvailable) {
+    log(`↑ Update available: wize-dev-kit ${result.installed} → ${result.latest}`);
+    log('  Run `npx wize-dev-kit@latest update` in your project to refresh adapters — or `/wize-update` from inside your AI harness.');
+  } else {
+    log(`wize-dev-kit ${result.installed} is up to date.`);
+  }
+  return result;
+}
+
+module.exports = { cmdVersionCheck };

package/tools/installer/version-check.js

@@ -104,6 +104,25 @@ async function printUpdateHintIfAny(currentVersion, { log = console.log, isTTY =
   }
 }
 
+// Pure, TTY-agnostic version check. printUpdateHintIfAny above is an
+// opportunistic hint meant for a human's terminal (gated on isTTY so it
+// never spams a pipe or a script); this is the explicit-invocation
+// counterpart behind the `version-check` CLI command, which an AI agent
+// shells out to non-interactively — stdout there is never a TTY, so a
+// TTY-gated check would go silent exactly when it's needed. Always resolves
+// to a plain object, never throws, and shares the same 1h cache.
+async function getVersionCheckResult(currentVersion, { skipCache = false } = {}) {
+  if (process.env.WIZE_DISABLE_UPDATE_CHECK === '1') {
+    return { installed: currentVersion, latest: null, updateAvailable: false, disabled: true };
+  }
+  const latest = await getLatestVersion({ skipCache });
+  return {
+    installed: currentVersion,
+    latest: latest || null,
+    updateAvailable: latest ? semverGreater(latest, currentVersion) : false
+  };
+}
+
 module.exports = {
   CACHE_TTL_MS,
   NETWORK_TIMEOUT_MS,
@@ -113,5 +132,6 @@ module.exports = {
   fetchLatestFromRegistry,
   getLatestVersion,
   semverGreater,
-  printUpdateHintIfAny
+  printUpdateHintIfAny,
+  getVersionCheckResult
 };

package/tools/installer/wize-cli.js

@@ -19,6 +19,7 @@ const prompts = require('prompts');
 const { applyGitignore, generateUserToml } = require('./setup-helpers.js');
 const { cmdUpdate, loadProjectConfig } = require('./commands/update.js');
 const { printUpdateHintIfAny } = require('./version-check.js');
+const { cmdVersionCheck } = require('./commands/version-check.js');
 const { cmdSync: cmdSyncReal } = require('./commands/sync.js');
 const { cmdAgentList, cmdAgentCreate, cmdAgentEdit } = require('./commands/agent.js');
 const { cmdDoctor, adapterTargetPath } = require('./commands/doctor.js');
@@ -73,6 +74,7 @@ Usage:
 Commands:
   install                 Install the kit into the current repo (interactive).
   update                  Apply upstream diff while preserving customizations.
+  version-check [--json]  Check installed vs. latest version (scriptable; never blocks).
   uninstall               Remove the kit from the current repo (preserves code).
   list                    List installed agents, skills and workflows.
   sync                    Regenerate IDE adapters for active targets.
@@ -891,6 +893,8 @@ async function main() {
   switch (cmd) {
     case 'install':   return cmdInstall(rest);
     case 'update':    return cmdUpdate({ kitRoot: KIT_ROOT, projectRoot: process.cwd() });
+    case 'version-check':
+      return cmdVersionCheck({ currentVersion: KIT_VERSION, json: rest.includes('--json') });
     case 'uninstall': return cmdUninstall(rest);
     case 'list':      return cmdList();
     case 'sync':      return cmdSync();