wize-dev-kit 0.16.0 → 0.17.0

package/schemas/workflow.schema.json

@@ -11,7 +11,7 @@
     "phase": { "type": "string" },
     "owner": { "type": "string" },
     "absorbs": { "type": "string" },
-    "overlay": { "enum": ["web", "app"] },
+    "overlay": { "enum": ["web", "app", "security"] },
     "status": { "enum": ["stub", "draft", "ready", "stable"] },
     "gate": { "enum": ["risk", "design", "trace", "nfr", "review", "gate"] },
     "when": { "type": "string" }

package/src/app-overlay/wize-app-release-channels/workflow.md

@@ -1,5 +1,7 @@
 ---
+
 code: wize-app-release-channels
+description: "Use quando o app estiver pronto para distribuição e precisar configurar canais de release (beta, produção)."
 name: App Release Channels
 overlay: app
 owner: wize-agent-pm   # Maria Hill

package/src/app-overlay/wize-app-scaffold/workflow.md

@@ -1,5 +1,7 @@
 ---
+
 code: wize-app-scaffold
+description: "Use quando precisar criar o scaffold inicial de um projeto mobile com a stack aprovada pelo Fury."
 name: App Scaffold
 overlay: app
 owner: wize-agent-architect   # Tony

package/src/app-overlay/wize-app-store-listing/workflow.md

@@ -1,5 +1,7 @@
 ---
+
 code: wize-app-store-listing
+description: "Use quando o app estiver próximo do lançamento e precisar preparar a listagem na loja (copy, assets, metadados)."
 name: App Store Listing
 overlay: app
 owner: wize-agent-analyst   # Pepper (copy) + Mantis (visual brief)

package/src/builder-skills/wize-create-agent/workflow.md

@@ -1,5 +1,7 @@
 ---
+
 code: wize-create-agent
+description: "Use quando precisar criar um novo agente customizado sob .wize/custom/agents/."
 name: Create Agent
 owner: builder
 status: stub

package/src/builder-skills/wize-create-skill/workflow.md

@@ -1,5 +1,7 @@
 ---
+
 code: wize-create-skill
+description: "Use quando precisar criar uma nova skill single-step sob .wize/custom/skills/."
 name: Create Skill
 owner: builder
 status: stub

package/src/builder-skills/wize-create-workflow/workflow.md

@@ -1,5 +1,7 @@
 ---
+
 code: wize-create-workflow
+description: "Use quando precisar criar um novo workflow multi-step sob .wize/custom/workflows/."
 name: Create Workflow
 owner: builder
 status: stub

package/src/core-skills/wize-advanced-elicitation/skill.md

@@ -1,5 +1,7 @@
 ---
+
 code: wize-advanced-elicitation
+description: "Use quando uma resposta do usuário parecer subespecificada e precisar de técnicas de elicitação (5 Whys, laddering, premortem) para aprofundar o entendimento."
 name: Advanced Elicitation
 module: core
 status: stub

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

@@ -1,5 +1,7 @@
 ---
+
 code: wize-brainstorming
+description: "Use quando precisar gerar ideias divergentes e convergir para as melhores opções em qualquer fase de decisão."
 name: Brainstorming
 module: core
 status: stub

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

@@ -0,0 +1,116 @@
+---
+
+code: wize-customize
+description: "Use quando precisar personalizar um agente, skill ou workflow built-in sem alterar os arquivos originais do kit."
+name: Customize
+module: core
+status: ready
+---
+
+# Customize
+
+**Goal.** Guide the user through creating an override (customize.toml) for a built-in agent, skill, or workflow. The override lives at `.wize/custom/{type}/{code}/customize.toml` and is loaded by the adapter at sync time.
+
+Wizer drives. Tony on call for agent structure.
+
+## When to use
+
+- "Override the persona of `wize-agent-pm`."
+- "Customize the wording in `wize-product-brief`."
+- "Add a tool to `wize-orchestrator`."
+
+## When NOT to use
+
+- Creating a brand-new agent/skill/workflow → use `wize-create-agent` (or `wize-create-skill` / `wize-create-workflow`).
+- Updating built-ins directly (the kit does not support forking built-ins; the next update would clobber your changes).
+
+## Inputs
+
+- A target: agent code, skill code, or workflow code.
+- A scope: what to override (name, title, persona, tools, body).
+
+## Output
+
+- A new file at `.wize/custom/{type}/{code}/customize.toml` (or update of an existing one).
+- A re-run of `wize-dev-kit sync` to apply the override.
+
+## Steps
+
+### 1. Identify the target
+
+The user names the code (e.g., `wize-agent-pm`). The skill validates:
+
+- Code shape: `wize-{kind}-{slug}`.
+- Exists in the kit's built-in roster.
+
+If the target does not exist, suggest `wize-create-agent` instead.
+
+### 2. Inspect the existing override
+
+If `.wize/custom/{type}/{code}/customize.toml` exists, read it. The user is updating; otherwise creating.
+
+### 3. Ask what to change
+
+The skill asks the user to pick from the overrideable fields:
+
+- `name` (display name)
+- `title` (job title)
+- `persona` (markdown body)
+- `tools` (list of tool names the agent can call)
+- `icon` (emoji)
+
+One field per run. Re-run for additional fields.
+
+### 4. Generate the customize.toml
+
+Write the new (or merged) customize.toml. Keep the structure as comments so the user can see the template.
+
+```toml
+# Override for {code} — generated by /wize-customize
+# Re-running the skill merges; lines you delete are restored on next install.
+
+[persona]
+# name = "Your name here"
+# title = "Your title here"
+
+[tools]
+# Add tool names the agent can call. Empty = default set.
+# tools = []
+```
+
+### 5. Re-sync
+
+Run `wize-dev-kit sync` (or instruct the user to). The override is loaded by the adapter and emitted to the IDE targets.
+
+### 6. Hand off
+
+Notify the user of:
+
+- File written: `.wize/custom/{type}/{code}/customize.toml`.
+- Sync completed (or instructions to run it).
+- Where to verify the override (e.g., `.claude/skills/{code}/SKILL.md`).
+
+## Output template
+
+The skill does not write a markdown output; it writes the customize.toml and re-syncs.
+
+```toml
+# Override for wize-agent-pm — generated by /wize-customize
+
+[persona]
+name = "Hill"  # shortened from "Maria Hill"
+
+[tools]
+# tools = []   # default set
+```
+
+## Anti-patterns Wizer rejects
+
+- Suggesting direct edits to built-in files in `node_modules/wize-dev-kit/`. (Next update clobbers.)
+- Creating a customize.toml with no overrideable fields filled. (Empty = no-op.)
+- Auto-running `wize-dev-kit sync` silently. (Confirm with the user first.)
+- Customizing the same field twice in one run. (One field per run.)
+
+## Hand-off
+
+> "Override written at `.wize/custom/{type}/{code}/customize.toml`. Sync applied. Verify in `.claude/skills/{code}/SKILL.md` (or your IDE target)."

package/src/core-skills/wize-editorial-review-prose/skill.md

@@ -0,0 +1,94 @@
+---
+
+code: wize-editorial-review-prose
+description: "Use quando um artefato Wize (brief, PRD, ADR, gate) precisar de revisão de prosa — clareza, tom, jargão e precisão."
+name: Editorial Review — Prose
+module: core
+status: ready
+---
+
+# Editorial Review — Prose
+
+**Goal.** Catch prose drift in Wize artifacts (brief, PRD, ADR, gate, story, retrospective). Peggy Carter runs the review; the user applies the fixes.
+
+Peggy drives. Wizer is on call for the call to action ("rewrite the whole section" or "leave it").
+
+## When to use
+
+- "Review the prose in this PRD."
+- "Find jargon and hedging in the brief."
+- "Is this gate file clear?"
+
+## When NOT to use
+
+- Spelling/grammar (use a linter; out of scope here).
+- Structure (missing sections, wrong ordering) → use `wize-editorial-review-structure`.
+- Tone change (tone is intentional; leave it).
+
+## Inputs
+
+- A markdown file under `.wize/`.
+- A line range (optional; default = whole file).
+
+## Output
+
+- A markdown review with line-level findings, each tagged with severity (nit / suggest / recommend).
+
+## Steps
+
+### 1. Read
+
+Read the file (or line range). Skip code blocks. Skip frontmatter.
+
+### 2. Hunt (4 areas)
+
+- **Voice.** Active voice preferred. Flag passive constructions ("was decided by", "is being implemented").
+- **Jargon.** Acronyms not defined on first use. Discipline-specific terms (e.g., "JTBD", "NFR") that are not in the project glossary.
+- **Hedging.** Softeners that hide commitment: "might", "could possibly", "we should consider", "it would be nice". Suggest a stronger verb.
+- **Pronouns.** Ambiguous "this", "it", "they" without a clear referent. Suggest a specific noun.
+
+### 3. Rank
+
+Per finding:
+
+- **Nit** — minor; user can ignore.
+- **Suggest** — worth a 5-second fix.
+- **Recommend** — blocks the artifact's clarity; should be fixed.
+
+### 4. Hand off
+
+Output is a markdown list. The user applies or rejects each finding. Peggy does not auto-edit.
+
+## Output template
+
+```markdown
+---
+date: 2026-06-17
+file: planning/prd.md
+author: Peggy
+---
+
+# Prose review — prd.md
+
+## Recommendations
+- L42: "we should consider using a token bucket" → "we use a token bucket". Hedging hides the decision. **[recommend]**
+- L78: "this might affect the user" → "this affects new signups". Pronoun + hedging. **[recommend]**
+
+## Suggests
+- L15: "rate-limit" appears 4 times. First use: spell out "rate-limit (per-IP cap on request rate)". **[suggest]**
+- L23: passive "is implemented by" → active "we implement". **[suggest]**
+
+## Nits
+- L88: comma splice. **[nit]**
+```
+
+## Anti-patterns Peggy rejects
+
+- Auto-editing the source file. (Suggest; never write.)
+- Commenting on tone or style preference. (Tone is intentional; structure is a separate review.)
+- Marking everything as recommend. (Cap at 5 recommends per review.)
+- Reviewing code blocks. (Out of scope.)
+
+## Hand-off
+
+> "Prose review complete for `{file}`. {N} findings. {M} recommends, {K} suggests, {L} nits. Apply or reject per finding."

package/src/core-skills/wize-editorial-review-structure/skill.md

@@ -0,0 +1,99 @@
+---
+
+code: wize-editorial-review-structure
+description: "Use quando um artefato Wize precisar de revisão estrutural — seções obrigatórias, ordenação e níveis de heading."
+name: Editorial Review — Structure
+module: core
+status: ready
+---
+
+# Editorial Review — Structure
+
+**Goal.** Catch structural drift in Wize artifacts: missing required sections, wrong ordering, inconsistent heading levels. Peggy Carter runs the review; the user applies the fixes.
+
+Peggy drives. Tony on call for architecture artifacts; Maria Hill for PRD; Hawkeye for gates.
+
+## When to use
+
+- "Review the structure of this PRD."
+- "Is this ADR complete?"
+- "Does this gate file have all required sections?"
+
+## When NOT to use
+
+- Prose quality → use `wize-editorial-review-prose`.
+- Content correctness (does the AC actually hold?) → use `wize-tea-review` or `wize-validate-prd`.
+
+## Inputs
+
+- A markdown file under `.wize/`.
+- (Optional) the artifact type (PRD, ADR, gate, story, brief) — auto-detected from path.
+
+## Output
+
+- A markdown review with section-level findings (missing, misordered, mistyped).
+
+## Steps
+
+### 1. Detect
+
+Infer the artifact type from the path:
+
+| Path | Type |
+|---|---|
+| `planning/brief.md` | brief |
+| `planning/prd.md` | prd |
+| `solutioning/adrs/ADR-*.md` | adr |
+| `solutioning/architecture.md` | architecture |
+| `implementation/tea/{epic}/{story}/gate.md` | gate |
+| `solutioning/stories/*/*.md` | story |
+| `solutioning/epics/*/*.md` | epic |
+
+### 2. Check against the template
+
+Each type has a required set of H2 sections. Use the template in the relevant workflow file (e.g., for PRD, see `wize-create-prd/workflow.md`). Compare against the file.
+
+### 3. Hunt (4 areas)
+
+- **Missing sections.** Required H2 not present.
+- **Misordered sections.** H2 present but in wrong order relative to the template.
+- **Inconsistent heading levels.** H3 used where H2 is expected (or vice versa).
+- **Empty sections.** H2 with no content (a heading and nothing else).
+
+### 4. Hand off
+
+Output is a markdown list with section-level findings. Severity: **must-fix** (missing) / **should-fix** (misordered) / **nit** (heading level).
+
+## Output template
+
+```markdown
+---
+date: 2026-06-17
+file: planning/prd.md
+type: prd
+author: Peggy
+---
+
+# Structure review — prd.md (PRD)
+
+## Must-fix
+- Missing H2: "Out of scope".
+- Missing H2: "Open questions".
+
+## Should-fix
+- H2 "Success criteria" appears after "Non-goals"; should be before (per template).
+
+## Nits
+- H3 used in "Constraints" where H4 would match the rest of the doc.
+```
+
+## Anti-patterns Peggy rejects
+
+- Suggesting a different section order than the template. (The template is the source of truth.)
+- Reviewing prose. (Use the prose skill.)
+- Marking optional sections (e.g., "Glossary" in PRD) as missing.
+- Auto-rewriting the file. (Suggest; never write.)
+
+## Hand-off
+
+> "Structure review complete for `{file}` ({type}). {M} must-fix, {K} should-fix, {L} nits. Apply or reject per finding."

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

@@ -0,0 +1,77 @@
+---
+
+code: wize-grill
+description: "Use quando uma demanda chegar vaga e precisar de entrevista exaustiva para alcançar entendimento compartilhado antes de produzir qualquer artefato."
+name: Grill
+module: core
+status: ready
+---
+
+# Grill
+
+**Goal.** Interview the user exhaustively about a demand until both sides reach **shared understanding** — before any artifact is drafted. Sharper answers make a sharper brief, PRD, epic, story, or plan. Grill is an input-quality tool, not an artifact of its own.
+
+Any persona about to author an artifact can invoke it: Pepper before a brief, Maria Hill before a PRD, Tony before epics/stories/architecture, Wizer when a demand arrives fuzzy. Wizer also **suggests** it from `/wize` (or `/wize-help`) — always suggest, never force.
+
+## The five rules
+
+1. **One question at a time.** Ask, then wait for the answer. A batch of questions is bewildering and produces shallow answers.
+2. **Every question ships with a recommendation.** State your recommended answer and a one-line reason. The user confirms or corrects — far cheaper than answering from scratch.
+3. **Facts are looked up; decisions are asked.** If the answer lives in the repo, `.wize/`, or the environment (stack, existing behavior, conventions, prior artifacts), fetch it — never ask. Only genuine decisions — trade-offs, priorities, scope calls — go to the user.
+4. **Walk the decision tree in dependency order.** Resolve upstream decisions before the downstream ones that depend on them. Don't ask about scope before the problem is agreed.
+5. **No drafting until confirmed.** Close with a compact summary of every decision made and ask for confirmation of shared understanding. Only then hand back to the authoring workflow.
+
+## Question ladder (dependency order)
+
+Climb top-down; **skip any rung an existing artifact already answers** (brief, trigger map, PRD, architecture — check first, rule 3).
+
+| Rung | Resolves | Feeds |
+|---|---|---|
+| 1. Problem | What hurts, for whom, what's the evidence it hurts | Brief vision / story context |
+| 2. Outcome | The observable result that means "solved" — metric, target, deadline | Success criteria / PRD goals |
+| 3. Audience | Primary user (role + JTBD), who else is affected | Brief audience / trigger map |
+| 4. Scope | What's in, what's explicitly out, non-goals | PRD scope table / story restrictions |
+| 5. Constraints | Deadline, budget, compliance, integrations, protected behaviors | Brief constraints / restrictions |
+| 6. Risks & assumptions | What, if wrong, changes the plan | PRD assumptions / risk profile |
+| 7. Validation | How we'll verify — which checks, which ACs, what "done" means | ACs / validation contract |
+
+When an answer comes back vague, apply a technique from `wize-advanced-elicitation` (5 Whys, laddering, premortem) to that one rung before moving on.
+
+## Calibration — how hard to grill
+
+| Demand class | Depth |
+|---|---|
+| **Quick Dev** (bug fix, copy edit, dep bump) | Don't grill. One clarifying question max — grilling a typo fix is theater. |
+| **Full Lifecycle, incremental** (new story in a known epic) | Short pass: rungs 4, 5, 7 only — the upstream rungs live in the PRD. |
+| **Full Lifecycle, new value** (new feature, new product, new plan) | Full ladder. |
+
+Momentum shortcut: after **three consecutive "as you recommend"** answers, switch to batch mode — state the remaining recommendations as one list and ask for a single confirmation. Respect the user's time; the point is clarity, not ceremony.
+
+## Where answers land
+
+Grill produces no separate file. Route each decision to its home:
+
+- **Decisions** → the target artifact's fields (brief sections, PRD scope/ACs, story restrictions/validation contract) — in the artifact's own words, not chat quotes.
+- **Unresolved questions** → the artifact's *Open questions*, each with owner + priority (`blocker` / `important` / `nice-to-know`).
+- **Load-bearing trade-offs** → the artifact's decision log (or `DECISIONS.md` / an ADR when architectural).
+
+## Stop conditions
+
+Stop grilling when **any** of these hits:
+
+- Every relevant rung is resolved or explicitly parked as an open question with an owner.
+- The user says "enough" / "just go" — park the rest as open questions and proceed with your recommendations, flagged as assumptions.
+- The summary is confirmed — shared understanding reached.
+
+## Anti-patterns
+
+- Multiple questions in one message.
+- Asking a fact `grep` or `.wize/` would answer.
+- A question without a recommendation ("So… what do you want?").
+- Grilling a Quick Dev demand.
+- Re-opening a confirmed decision without new information.
+- Continuing to interrogate after confirmation — grill is a phase, not a personality.
+
+## Hand-off
+
+> Shared understanding confirmed: {n} decisions captured, {m} open questions parked with owners. Handing back to {persona} / `{workflow}` to draft the {artifact}.

package/src/core-skills/wize-index-docs/skill.md

@@ -0,0 +1,119 @@
+---
+
+code: wize-index-docs
+description: "Use quando precisar reconstruir o índice da base de conhecimento (.wize/knowledge/index.md) a partir da árvore real de artefatos."
+name: Index Docs
+module: core
+status: ready
+---
+
+# Index Docs
+
+**Goal.** Rebuild `.wize/knowledge/index.md` from the actual tree. One file that lists every artifact with a one-line description and a relative link. New devs read this file first.
+
+Wizer drives. Peggy polishes the one-line descriptions on the second pass.
+
+## When to run
+
+- After any major artifact is created or moved.
+- Before sprint planning (to confirm what exists).
+- When onboarding a new team member.
+
+## When NOT to run
+
+- Inside an IDE target folder (`.claude/`, `.cursor/`, etc.) — out of scope.
+- As a CI step on every commit (too noisy; manual).
+
+## Inputs
+
+- The `.wize/` tree (read-only scan).
+- A user message: "Rebuild the index" or similar.
+
+## Output
+
+- `.wize/knowledge/index.md` with sections: Planning, Solutioning, Implementation, Knowledge, Custom.
+
+## Steps
+
+### 1. Scan
+
+Walk `.wize/` recursively. Skip hidden directories (`.DS_Store` etc.). For each file:
+
+- Read its YAML frontmatter.
+- If `description` is present, use it.
+- Else use the first `# Heading` line.
+- Else use the file name (kebab-case to title case).
+
+### 2. Group
+
+Sort into 5 sections by file path:
+
+| Section | Path prefix |
+|---|---|
+| Planning | `.wize/planning/` |
+| Solutioning | `.wize/solutioning/` |
+| Implementation | `.wize/implementation/` |
+| Knowledge | `.wize/knowledge/` (excluding the index file itself) |
+| Custom | `.wize/custom/` |
+
+### 3. Write
+
+Generate `.wize/knowledge/index.md` with:
+
+- YAML frontmatter (`generated`, `last_updated`, `total_files`).
+- One H2 per section.
+- One bullet per file: `- [{title}]({relative_path}) — {one-line description}`.
+- A footer with the total file count and the timestamp.
+
+If a section is empty, omit the heading.
+
+### 4. Hand off
+
+Output is the index file. The user can review and adjust manually if the one-liners are stale. Re-run to overwrite.
+
+## Output template
+
+```markdown
+---
+generated: 2026-06-17
+last_updated: 2026-06-17
+total_files: 24
+---
+
+# Wize artifacts index
+
+## Planning (5)
+- [Brief — site-qwize](planning/brief.md) — Pepper's one-pager for the site.
+- [PRD — site-qwize](planning/prd.md) — Maria Hill's PRD for v1.
+- [Trigger map](planning/trigger-map.md) — WDS user-psychology map.
+- [UX scenarios](planning/ux/ux-scenarios.md) — Mantis's 8-question dialog.
+- [Tech vision](planning/tech-vision.md) — Fury's stack pick.
+
+## Solutioning (4)
+- [Architecture](solutioning/architecture.md) — Tony's 8-step architecture.
+- [ADR-001](solutioning/adrs/ADR-001-...) — ...
+...
+
+## Implementation (8)
+- [Sprint 1 status](implementation/sprint-status.md) — closed.
+- [Risk profile](implementation/tea/risk-profile.md) — 13 risks mitigated.
+...
+
+## Knowledge (6)
+- [Document project overview](knowledge/document-project/overview.md) — ...
+...
+
+## Custom (1)
+- [Agent: runbooks](custom/agents/wize-agent-runbooks/agent.yaml) — ...
+```
+
+## Anti-patterns Wizer rejects
+
+- Including IDE target folders (`.claude/`, `.cursor/`, `.kimi/`, etc.) in the index.
+- Dumping file contents (just the description + link).
+- Auto-running on every commit (manual or scheduled only).
+- Mixing in files outside `.wize/`.
+
+## Hand-off
+
+> "Index rebuilt at `.wize/knowledge/index.md`. {N} files indexed across 5 sections. Next: `/wize` (or `/wize-help`) reads this file when answering."