wize-dev-kit 0.15.0 → 0.16.1

package/CHANGELOG.md

@@ -9,6 +9,19 @@ Format inspired by [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.16.1] — 2026-09-02
+
+**Publish fix.** The `0.16.0` release was published from a stale commit (missing the Hermes adapter and `wize-check`). `0.16.1` republishes the full `main` history plus `/wize-eli5`; `0.16.0` is deprecated on npm.
+
+## [0.16.0] — 2026-09-02
+
+**`/wize-eli5` — explain anything to anyone.** New core skill that detects the audience (age, grade level, job role, relationship) and calibrates vocabulary, analogies, tone, depth and framing to the listener — a concept, code, error, or decision explained for a 5-year-old, a manager, an engineer, or a client. Inspired by [ELI5](https://github.com/dreambigou/eli5) by Andrew Ou (credited in all 3 READMEs). Registered in the core module catalog; rendered by all 10 harness adapters (Claude Code, Antigravity, Codex, Kimi Code, Hermes, Cursor, Windsurf, Continue, OpenCode, Generic).
+
+### Added
+
+- **`wize-eli5` core skill** (`src/core-skills/wize-eli5/skill.md`) — audience detection → five-axis calibration (vocabulary, analogies, tone, depth, framing) → explanation → comprehension check; role-specific framing (manager, designer, engineer, client, child) and anti-patterns.
+- **READMEs (en/pt-BR/es)** — `/wize-eli5` listed in the cross-cutting commands walkthrough; ELI5 credited in the Inspiration & credits section.
+
 ## [0.15.0] — 2026-09-02
 
 **Hermes Agent is now the 10th supported harness.** New `hermes` IDE target renders the kit's agents/skills/workflows as project-local skills at `.hermes/skills/wize-{code}/SKILL.md` (Anthropic-compatible format, same as Claude Code/Codex/Kimi Code). Hermes discovers project skills at the git root, loads them only when the repo is trusted (`hermes skills trust`), and lets trusted project skills override same-named profile skills — vendored repo skills win inside their repo. Hermes also reads root `AGENTS.md` as project context, and its CLI (`hermes -z "<prompt>"`) is registered in the installer's brownfield baseline for headless runs. Highlighted in all 3 READMEs + `docs/harnesses/hermes.md` (+pt-BR); registered in the installer targets, `doctor`, `.gitignore` block, and 4 test suites.

package/README.md

@@ -155,6 +155,9 @@ Cross-cutting:
                                 done (with evidence), in progress, what's left —
                                 then resumes the interrupted work.
     /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-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.
@@ -259,6 +262,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`.
 
 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/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "wize-dev-kit",
-  "version": "0.15.0",
+  "version": "0.16.1",
   "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

@@ -16,6 +16,9 @@ skills:
   - code: wize-grill
     name: "Grill"
     description: "Exhaustive one-question-at-a-time interview to reach shared understanding before drafting briefs, PRDs, epics, stories, or plans."
+  - 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-brainstorming
     name: "Brainstorming"
     description: "Divergent-then-convergent ideation; produces idea-pool.md."

package/src/core-skills/wize-eli5/skill.md

@@ -0,0 +1,72 @@
+---
+code: wize-eli5
+description: "Use quando alguém pedir para explicar um conceito, trecho de código, erro ou decisão para um público específico — adapta vocabulário, analogias, tom, profundidade e framing ao ouvinte."
+name: ELI5
+module: core
+status: ready
+---
+
+# ELI5 — Explain Like I Am 5
+
+**Goal.** Explain anything to anyone — a concept, a piece of code, an error, an architecture decision, a business rule — calibrated to the listener. The same idea gets a different explanation for a 5-year-old, a manager, an engineer, or a client. ELI5 is a communication tool, not an artifact of its own: it produces the explanation in the conversation (or as a short doc when asked).
+
+Inspired by [ELI5](https://github.com/dreambigou/eli5) by Andrew Ou — adapted to the Wize method: audience detection first, explicit calibration, and a comprehension check before handing off.
+
+## Step 1 — Detect the audience
+
+Read the prompt for an explicit or implicit audience. If none is given, ask **one** question with a recommendation (rule 2 of `wize-grill`): "I'll explain it for a non-technical stakeholder — or would you prefer the engineering version?"
+
+| Category | Examples |
+|---|---|
+| **Ages** | 5, 10, 15, 20, 30, 40+ |
+| **Grade levels** | 5th grade, middle school, high school, college, graduate |
+| **Job roles** | Manager, engineer, designer, director, product manager, client, stakeholder |
+| **Relationships** | Wife, husband, parents, kids, friend, investor |
+
+## Step 2 — Calibrate on five axes
+
+| Axis | Non-technical / child | Technical / peer |
+|---|---|---|
+| **Vocabulary** | No jargon; everyday words; define any term you must use | Proper terminology, precise names |
+| **Analogies** | Toys, playground, kitchen, games | Systems, patterns, prior art, math |
+| **Tone** | Playful, warm, patient | Direct, professional, dense |
+| **Depth** | Short and sweet; one idea at a time | Nuanced; trade-offs; edge cases |
+| **Framing** | What it does for *them*, in their world | Impact/risk, architecture, constraints |
+
+Role-specific framing:
+- **Manager / director** → business outcome, cost, risk, timeline. No implementation detail unless asked.
+- **Designer** → user experience, flow, visual impact.
+- **Engineer** → mechanism, contracts, failure modes.
+- **Client / stakeholder** → what changes for them, what they must decide, what it costs.
+- **Child / layperson** → one concrete analogy, one sentence per idea, check understanding.
+
+## Step 3 — Explain
+
+1. **One idea per beat.** Short sentences. If the explanation needs more than ~5 beats, structure it (numbered steps or a tiny table).
+2. **Lead with the analogy for non-technical audiences** — then, only if asked, bridge to the real mechanism ("it's like a library card catalog… and the actual index is a B-tree").
+3. **For code**: show the *behavior* first (what it does), then the *why* (why it exists), then the *how* (mechanism) — in that order, stopping at the depth the audience needs.
+4. **For errors**: plain-language what happened → why it happened → what we do about it. Never dump a stack trace at a non-technical audience.
+5. **For decisions**: the decision → the reason → the alternative considered → the cost of being wrong.
+
+## Step 4 — Verify comprehension
+
+Close with a lightweight check, matched to the audience:
+
+- **Child / layperson**: "Does that make sense? Want me to say it with a different example?"
+- **Manager / client**: one-line summary + the single decision or action they own.
+- **Engineer**: offer the next level: "Want the implementation details / the failure modes / the alternatives?"
+
+If the listener asks a follow-up, re-calibrate — the audience may have shifted (a manager asking "how does that work technically?" is now an engineer).
+
+## Anti-patterns
+
+- Explaining to a 5-year-old with the same depth as a code review.
+- Dumping jargon at a non-technical audience ("it's a distributed consensus algorithm").
+- Over-simplifying for an engineer (no hand-waving at peers).
+- Skipping the audience check when the prompt is ambiguous.
+- Explaining *everything* — answer the question asked, then stop.
+- Using the same analogy for every audience (a playground analogy lands for a child, not for a CFO).
+
+## Hand-off
+
+> Explained {topic} for {audience} — calibrated on vocabulary, analogies, tone, depth and framing. Comprehension check: {result}. {One-line summary or next action for the listener.}

package/tools/check-eli5-all-adapters.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+// Verifica que o wize-eli5 é renderizado por TODOS os 10 adapters de harness.
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+const KIT = path.resolve(__dirname, '..');
+const EXPECT = [
+  { code: 'claude-code', file: '.claude/skills/wize-eli5/SKILL.md' },
+  { code: 'antigravity', file: '.agent/skills/wize-eli5/SKILL.md' },
+  { code: 'codex',       file: '.agents/skills/wize-eli5/SKILL.md' },
+  { code: 'kimi-code',   file: '.kimi/skills/wize-eli5/SKILL.md' },
+  { code: 'hermes',      file: '.hermes/skills/wize-eli5/SKILL.md' },
+  { code: 'cursor',      file: '.cursor/rules/wize-eli5.mdc' },
+  { code: 'windsurf',    file: '.windsurf/rules/wize-eli5.md' },
+  { code: 'continue',   file: '.continue/prompts/wize-eli5.prompt' },
+  { code: 'opencode',    file: '.opencode/commands/wize-eli5.md' },
+  { code: 'generic',     file: '.wize/agents/wize-eli5.md' },
+];
+
+let ok = 0, fail = 0;
+for (const a of EXPECT) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), `wize-eli5-${a.code}-`));
+  try {
+    const mod = require(path.join(KIT, 'adapters', a.code, 'render.js'));
+    mod.render(KIT, root, { profiles: ['core'] });
+    const f = path.join(root, a.file);
+    if (fs.existsSync(f)) {
+      const content = fs.readFileSync(f, 'utf-8');
+      if (/ELI5/.test(content) && /Explain Like I Am 5/.test(content)) {
+        console.log(`  ✓ ${a.code.padEnd(11)} -> ${a.file}`);
+        ok++;
+      } else {
+        console.log(`  ✖ ${a.code}: arquivo existe mas sem conteúdo wize-eli5`);
+        fail++;
+      }
+    } else {
+      console.log(`  ✖ ${a.code}: ${a.file} NÃO foi gerado`);
+      fail++;
+    }
+  } catch (e) {
+    console.log(`  ✖ ${a.code}: erro ao renderizar — ${e.message}`);
+    fail++;
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+console.log(`\n${ok}/10 harnesses com wize-eli5.`);
+process.exit(fail ? 1 : 0);