wize-dev-kit 0.16.0 → 0.16.1

package/src/method-skills/1-analysis/wize-technical-research/technical-steps/step-03-integration-patterns.md

@@ -0,0 +1,39 @@
+# Step 3: Integration Patterns
+
+## Rules
+
+- 🌐 Search the web to verify claims.
+- 📝 Write findings to the document immediately.
+- ✅ Speak in `{communication_language}`; write artifacts in `{document_output_language}`.
+
+## Task
+
+Analyze integration patterns for {{research_topic}}.
+
+## Execution
+
+Search for:
+
+- "{{research_topic}} API design patterns"
+- "{{research_topic}} service integration"
+- "{{research_topic}} data integration"
+
+Synthesize and append:
+
+```markdown
+## Integration Patterns
+
+### API Design Patterns
+...
+
+### Service Integration
+...
+
+### Data Integration
+...
+
+### Source Citations
+...
+```
+
+Update `stepsCompleted: [1, 2, 3]` and load `./technical-steps/step-04-architectural-patterns.md`.

package/src/method-skills/1-analysis/wize-technical-research/technical-steps/step-04-architectural-patterns.md

@@ -0,0 +1,39 @@
+# Step 4: Architectural Patterns
+
+## Rules
+
+- 🌐 Search the web to verify claims.
+- 📝 Write findings to the document immediately.
+- ✅ Speak in `{communication_language}`; write artifacts in `{document_output_language}`.
+
+## Task
+
+Analyze architectural patterns for {{research_topic}}.
+
+## Execution
+
+Search for:
+
+- "{{research_topic}} system architecture"
+- "{{research_topic}} architectural patterns"
+- "{{research_topic}} scalability patterns"
+
+Synthesize and append:
+
+```markdown
+## Architectural Patterns
+
+### Common Architectural Styles
+...
+
+### Scalability Patterns
+...
+
+### Security Patterns
+...
+
+### Source Citations
+...
+```
+
+Update `stepsCompleted: [1, 2, 3, 4]` and load `./technical-steps/step-05-implementation-research.md`.

package/src/method-skills/1-analysis/wize-technical-research/technical-steps/step-05-implementation-research.md

@@ -0,0 +1,42 @@
+# Step 5: Implementation Research
+
+## Rules
+
+- 🌐 Search the web to verify claims.
+- 📝 Write findings to the document immediately.
+- ✅ Speak in `{communication_language}`; write artifacts in `{document_output_language}`.
+
+## Task
+
+Research implementation approaches and best practices for {{research_topic}}.
+
+## Execution
+
+Search for:
+
+- "{{research_topic}} best practices"
+- "{{research_topic}} implementation guide"
+- "{{research_topic}} production readiness"
+
+Synthesize and append:
+
+```markdown
+## Implementation Research
+
+### Development Methodologies
+...
+
+### Code Organization
+...
+
+### Quality Assurance
+...
+
+### Deployment Practices
+...
+
+### Source Citations
+...
+```
+
+Update `stepsCompleted: [1, 2, 3, 4, 5]` and load `./technical-steps/step-06-research-synthesis.md`.

package/src/method-skills/1-analysis/wize-technical-research/technical-steps/step-06-research-synthesis.md

@@ -0,0 +1,46 @@
+# Step 6: Technical Research Synthesis and Completion
+
+## Rules
+
+- 🌐 Search the web to verify claims.
+- 📝 Replace the Research Overview placeholder and append synthesis.
+- ✅ Speak in `{communication_language}`; write artifacts in `{document_output_language}`.
+
+## Task
+
+Produce the final technical research synthesis.
+
+## Execution
+
+Replace `[Research overview and methodology will be appended here.]` with a concise summary.
+
+Append:
+
+```markdown
+## Research Synthesis
+
+### Key Findings
+1. ...
+2. ...
+
+### Recommended Stack / Pattern
+...
+
+### Trade-offs
+...
+
+### Risks and Mitigations
+...
+
+### Still Open
+- ...
+
+### Sources
+...
+```
+
+Update frontmatter `stepsCompleted: [1, 2, 3, 4, 5, 6]` and `status: complete`.
+
+## On complete
+
+Run `{workflow.on_complete}` if non-empty.

package/src/method-skills/1-analysis/wize-technical-research/workflow.md

@@ -0,0 +1,60 @@
+---
+code: wize-technical-research
+name: Technical Research
+phase: 1-analysis
+owner: wize-agent-analyst   # Pepper Potts
+status: ready
+description: "Use quando precisar pesquisar tecnologias, stacks, bibliotecas ou decisões técnicas."
+---
+
+> **Variante de pesquisa.** Para outros tipos de pesquisa, veja:
+> - Mercado/concorrência → `/wize-market-research`
+> - Domínio/indústria → `/wize-domain-research`
+> - Técnica/stack → `/wize-technical-research`
+> - Pesquisa geral (dispatcher) → `/wize-research`
+
+# Technical Research
+
+**Goal.** Conduct technical research on technologies, tools, and architecture patterns to inform stack decisions.
+
+Pepper Potts drives. Tony Stark consumes the output directly. Peggy Carter edits prose.
+
+Output lands in `.wize/planning/research/technical-{slug}-research-{date}.md`.
+
+## When to use
+
+- "Should we use X or Y?"
+- "What is the current state of Z technology?"
+- "I need a technical comparison of..."
+
+## Inputs
+
+- Open questions from `.wize/planning/brief.md` or `.wize/planning/tech-vision.md`
+- User-provided technology or architectural topic
+- Web search access
+
+## Outputs
+
+- `.wize/planning/research/technical-{slug}-research-{date}.md`
+
+## Workflow architecture
+
+Step-file architecture with six steps:
+
+1. Scope confirmation
+2. Technical overview
+3. Integration patterns
+4. Architectural patterns
+5. Implementation research
+6. Research synthesis
+
+## On activation
+
+1. Load `.wize/config/project.toml` and `.wize/config/user.toml`.
+2. Ask for the technical topic if not provided.
+3. Derive `{research_topic_slug}` and create the output file from `research.template.md`.
+4. Read fully and follow `./technical-steps/step-01-init.md`.
+
+## Hand-off
+
+> Technical research is in `.wize/planning/research/`. Fury and Tony can use it for stack family decisions; open questions route back to Wizer.

package/src/method-skills/1-analysis/wize-trigger-map/workflow.md

@@ -1,20 +1,26 @@
 ---
+
 code: wize-trigger-map
+description: "Use quando precisar mapear gatilhos psicológicos dos usuários para objetivos de negócio — a ponte entre o brief e o PRD."
 name: Trigger Map
 phase: 1-analysis
 owner: wize-agent-analyst   # Pepper Potts
 absorbs: "WDS Saga — Phase 2 (Trigger Mapping)"
-status: stub
+status: ready
 ---
 
 # Trigger Map
 
-**Goal.** Map user psychology to business goals. For each user action we want to drive, identify the **trigger** (need/anxiety/desire) and the **business outcome** it unlocks.
+**Goal.** Map user psychology to business goals. For each user action the product wants to drive, name the **trigger** (the need/anxiety/desire that precedes it), the **friction** that blocks it today, the **business outcome** unlocked, and the **signal** that confirms it happened.
+
+This is the bridge between Pepper's brief and Maria Hill's PRD: it forces the team to argue *why* users would do the thing before *what* the team will build.
+
+Pepper drives. Output lands in `.wize/planning/ux/trigger-map.md`.
 
 ## Inputs
 
-- `.wize/planning/brief.md`
-- `.wize/planning/research.md` (if exists)
+- `.wize/planning/brief.md` (vision + audience + success criteria).
+- `.wize/planning/research.md` (when present — strengthens triggers with evidence).
 
 ## Outputs
 
@@ -22,19 +28,79 @@ status: stub
 
 ## Steps
 
-1. **List target user actions.** From the brief, list the 3–8 actions we want users to take.
-2. **For each action**, fill the row:
-   - **Trigger** — what state of mind/need precedes this action?
-   - **Friction** — what stops users from doing it today?
-   - **Business outcome** — what changes for the business when this action happens?
-   - **Signal** — what telemetry/event proves it happened?
-3. **Validate.** Cite research or mark `hypothesis`.
-4. **Hand off to Mantis** for UX Scenarios.
+### 1. List target user actions
+
+From the brief, list **3–8 actions** users must take for the product to succeed. Verb-led. Concrete.
+
+- ✓ "Sign up using a work email."
+- ✓ "Add a teammate."
+- ✓ "Confirm the first invoice."
+- ✗ "Get value." (too abstract)
+
+If you have more than 8, you're conflating products. Trim.
+
+### 2. Per row: trigger / friction / business outcome / signal
+
+For each action, fill four cells. Each cell ≤ 1 sentence.
+
+| Field | What goes here |
+|---|---|
+| **Trigger** | The mental state preceding the action. *Need / anxiety / desire.* What makes the user think "I need to do this now"? |
+| **Friction** | The cost of doing it today (in the current workaround or competitor). What stops them? |
+| **Business outcome** | What changes for the business when this action happens. Revenue, retention, cost, NPS, risk reduction. |
+| **Signal** | The telemetry event/state-change proving it happened. Name it like an event (`signup_succeeded`), not a phrase ("user signs up"). |
+
+### 3. Mark each row evidence-backed or hypothesis
+
+Every cell must be tagged:
+
+- `evidence:<source>` — when based on an interview, survey, analytics or a citable doc.
+- `hypothesis` — when we believe it but haven't proven it.
+
+Hypotheses are fine. Hidden hypotheses are not. Force the label.
+
+### 4. Wire to success criteria
 
-## Trigger Map template
+For each of Pepper's success criteria in the brief, identify **which row of the map is the load-bearing one**. If a criterion has no row mapped to it, either it's not a real success criterion or the map is missing an action.
+
+### 5. Hand off
+
+Mark `status: ready-for-prd`. Tell Wizer the next step is Maria Hill.
+
+## Output template
 
 ```markdown
-| Action | Trigger | Friction | Business outcome | Signal | Evidence |
-|---|---|---|---|---|---|
-| … | … | … | … | … | research:/hypothesis |
+---
+status: ready-for-prd | draft
+owner: Pepper Potts
+created: YYYY-MM-DD
+---
+
+# Trigger Map — {{project_name}}
+
+## Actions
+
+| # | Action | Trigger | Friction | Business outcome | Signal | Evidence |
+|---|---|---|---|---|---|---|
+| 1 | Sign up with work email | "We need a tool we can hand to the team next week." | Existing tool requires manual SSO; we want self-serve. | New paid-team conversion. | `signup_completed` | research:user-interview-2026-04 |
+| 2 | Invite first teammate | Won't move forward solo. | Email + reminder loops cost manager 10min. | Activation. | `teammate_invited` | hypothesis |
+| … | … | … | … | … | … | … |
+
+## Coverage of brief success criteria
+
+- **Criterion 1** ("TTI ≤ 1.5s on Android by Q3") → covered by row 4 (`page_loaded`).
+- **Criterion 2** ("…") → covered by row 1.
+- …
 ```
+
+## Anti-patterns Pepper rejects
+
+- **Triggers written as features.** "Wants the dashboard." Wrong layer. Reword to the emotion/need: "Wants to know if the team is okay."
+- **Friction in vague language.** "It's confusing." Wrong. Name the step that breaks: "After invite, no email arrives for 4 hours."
+- **Business outcomes with no metric.** "Drives engagement." Wrong. "Reduces churn by ≥ 1pp in cohort C." If you can't measure it, it's not an outcome — it's a hope.
+- **Signals that fire on intent, not completion.** `signup_button_clicked` is intent. `signup_completed` is the signal.
+- **Same row repeated for two actions.** Each row must justify a distinct action. If you can collapse them, do it.
+
+## Hand-off
+
+> Trigger map is in `.wize/planning/ux/trigger-map.md`. Hill, the PRD goals should anchor on rows 1, 3, and 5 — they map to the success criteria in the brief.

package/src/method-skills/2-plan-workflows/wize-create-prd/workflow.md

@@ -1,57 +1,169 @@
 ---
+
 code: wize-create-prd
+description: "Use quando o brief + research + trigger map estiverem prontos e precisar convertê-los em um PRD com escopo e acceptance criteria."
 name: Create PRD
 phase: 2-plan
 owner: wize-agent-pm   # Maria Hill
-status: stub
+status: ready
 ---
 
 # Create PRD
 
-**Goal.** Turn brief + research + trigger-map into a Product Requirements Document the team can build from.
+**Goal.** Turn brief + research + trigger map into a Product Requirements Document the team can build from. The PRD names *what* and *why* with measurable boundaries. Mantis, Fury, Tony will read it. Shuri ships against the acceptance criteria.
+
+Maria Hill drives. Peggy edits prose. Output lands in `.wize/planning/prd.md`.
+
+Before drafting: if goals, scope, or ACs would need guessing beyond what the brief + trigger map answer, offer a `wize-grill` pass with the user first — decisions land in the PRD fields, leftovers in *Open questions*. Don't guess scope; ask.
 
 ## Inputs
-- `.wize/planning/brief.md`
-- `.wize/planning/research.md`
-- `.wize/planning/ux/trigger-map.md`
+
+- `.wize/planning/brief.md` (vision, audience, success criteria).
+- `.wize/planning/research.md` (when present).
+- `.wize/planning/ux/trigger-map.md` (every PRD goal references rows of this map).
+- `.wize/planning/prfaq.md` (when present — PRD scope mirrors FAQ Q5 "what's in/out").
 
 ## Outputs
+
 - `.wize/planning/prd.md`
+- `.wize/solutioning/epics/` — coarse epic outlines Tony refines later.
 
 ## Steps
-1. **Goals.** Pull the success criteria from the brief; restate as PRD goals.
-2. **Scope (in / out).** Explicit list of in-scope and out-of-scope items.
-3. **User stories backbone.** "As a … I want … so that …" — coarse, will be sliced by Tony.
-4. **Acceptance criteria per scope item.** Each scope item gets ACs Hawkeye can test.
-5. **Constraints + assumptions.** From brief and Fury (if Fury has run already).
-6. **Open questions.** Owners assigned.
-7. **Hand-off.** Trigger Mantis to start UX scenarios.
 
-## PRD template
+### 1. Goals (3–5)
+
+Pull the success criteria from the brief; restate as PRD goals. Each goal is:
+- One sentence.
+- Measurable (named metric + target + deadline).
+- Tied to a trigger-map row.
+
+Example: *"Reduce signup time from 3.5min to 1min by Q3 (signal: `signup_completed` median; row 1)."*
+
+### 2. Scope — in / out (explicit)
+
+| In | Out (for now) |
+|---|---|
+| First-team signup flow | Multi-team admin roles |
+| Self-serve invite | SSO via SAML |
+| English (US) | Other locales |
+
+If a stakeholder asked for it and it isn't here, they will ask again at gate review. Put their item in **Out** with a one-line reason, not silence.
+
+### 3. User stories backbone
+
+Coarse stories that map to scope items. "As a {role}, I want to {action}, so that {outcome}." Each story will be sliced finer by Tony in `wize-create-epics-and-stories`.
+
+Use the trigger-map rows as backbone:
+- Row 1 (Sign up) → "As a team admin, I want to sign up with my work email, so that I can invite my team within 5 minutes."
+
+### 4. Acceptance criteria per scope item
+
+For every In-scope item, write 3–7 ACs Hawkeye can test.
+
+Format: `Given … When … Then …` or a numbered behavioral list.
+
+ACs are **observable**. ✓ "If the user enters an invalid email, the input shows error text within 200ms." ✗ "The form validates emails correctly."
+
+Each AC gets an ID: `AC-{epic}-{n}`. Hawkeye references these in `tea-trace.md`.
+
+### 5. Constraints + assumptions
+
+Pull constraints from the brief. Add:
+- **Assumptions** that, if wrong, change scope.
+- **Dependencies** on other teams/services with name + deadline.
+
+Each assumption is one line + verification plan. *"Assumption: Stripe Connect onboarding average 7 days. Verification: confirm with Stripe by 2026-07-01."*
+
+### 6. NFR pointer
+
+Don't redefine NFRs in the PRD. Reference `.wize/planning/nfr-principles.md` (Fury's) once. Note any project-specific tightening.
+
+### 7. Open questions
+
+What still needs deciding before solutioning starts. Each with an owner + deadline. Blockers can't carry into Phase 3.
+
+### 8. Hand off
+
+- Mark `status: ready-for-validation`.
+- Run `wize-validate-prd` (Maria Hill + Mantis + Fury sign-off).
+- Then Mantis starts `wize-ux-scenarios`.
+
+## Output template
 
 ```markdown
+---
+status: draft | ready-for-validation | validated
+owner: Maria Hill
+created: YYYY-MM-DD
+---
+
 # PRD — {{project_name}}
 
 ## Goals
-1. …
+1. {{goal}} (metric: …, target: …, deadline: …, trigger-map row: …)
+2. …
 
 ## Scope
+
 ### In scope
-- …
+- {{item}} — {{2–3 lines of detail}}
+
 ### Out of scope
-- …
+- {{item}} — {{one-line reason: not now / not us / not yet}}
 
-## Backbone (user stories)
-- …
+## Backbone (coarse stories)
+- E01: As a {{role}}, I want to {{action}}, so that {{outcome}}.
+- E02: …
 
 ## Acceptance criteria
-| Item | ACs |
-|---|---|
-| … | AC1 …; AC2 … |
 
-## Constraints / assumptions
+### E01 — Sign-up
+- **AC-01-1:** Given a new visitor on `/signup`, When they submit a valid work email + password, Then an account is created and they land on `/onboarding` within 1.5s.
+- **AC-01-2:** Given an invalid email, When the user blurs the field, Then error text appears within 200ms identifying which rule failed.
+- **AC-01-3:** Given a duplicate email, When the user submits, Then they see a "Sign in instead?" CTA and the request returns HTTP 409.
 - …
 
+## Constraints
+- Deadline: …
+- Budget: …
+- Compliance: GDPR, LGPD, SOC2.
+
+## Assumptions
+- Stripe Connect onboarding ≤ 7 days avg. — verify by …
+- Auth0 free tier sufficient for first 6 months. — verify by …
+
+## Dependencies
+- Design system tokens from Mantis by {{date}}.
+- Database from infra team by {{date}}.
+
+## NFR pointer
+See `.wize/planning/nfr-principles.md`. Project tightening: p95 LCP ≤ 2.0s (vs. global 2.5s) on signup pages.
+
 ## Open questions
-- [ ] … (owner: …)
+- [ ] (blocker) Pricing tier exposed pre-payment? — *owner: NAME, by: DATE*
+- [ ] (important) Brazil-only beta or global launch? — *owner: NAME, by: DATE*
 ```
+
+## INVEST checklist (per AC group)
+
+Maria Hill validates every story's ACs against INVEST:
+
+- **I**ndependent: no implicit dependency on another story being built first.
+- **N**egotiable: details can move; intent can't.
+- **V**aluable: a real outcome to a real user.
+- **S**mall: ≤ 1 PR worth (sliced finer in Phase 3 if not) — the only sizing test. INVEST's "Estimable" is dropped on purpose: we don't produce time or point estimates.
+- **T**estable: every AC is observable.
+
+If any letter fails, fix the story before it leaves Plan.
+
+## Anti-patterns Maria Hill rejects
+
+- **PRD as wishlist.** Pages of "the system shall…" with no Out-of-Scope. Force the cut.
+- **ACs as descriptions.** "The form is responsive." → no. *"At 360px, the form fits in the viewport with no horizontal scroll."*
+- **Open questions with no owner / no deadline.** They never get answered.
+- **Constraint hidden in prose.** Pull to its own bullet.
+- **PRD without a version + status.** Reviewers can't tell what they're reviewing.
+
+## Hand-off
+
+> PRD draft is at `.wize/planning/prd.md`. Two open blockers; CEO and Sales Lead have until Friday. Mantis — once we're `validated`, you start with the trigger map + PRD. Fury — your call on stack family.

package/src/method-skills/2-plan-workflows/wize-edit-prd/workflow.md

@@ -0,0 +1,110 @@
+---
+
+code: wize-edit-prd
+description: "Use quando o PRD existir e precisar de alteração pontual com registro de changelog."
+name: Edit PRD
+phase: 2-plan
+owner: wize-agent-pm   # Maria Hill
+status: ready
+---
+
+# Edit PRD
+
+**Goal.** Update `.wize/planning/prd.md` without rewriting from scratch. Every change is recorded in `.wize/planning/prd-changelog.md` so the team can see *what* changed, *when*, *why*, and *by whom*.
+
+Maria Hill drives. Peggy polishes prose on the diff. Wizer is on call for cross-cutting impacts (architecture, NFR, scope).
+
+## When to run
+
+- A new AC is needed (new requirement from the user, market shift, regulator).
+- An AC is no longer correct (validated learning, scoping mistake).
+- An item moves in-scope ↔ out-of-scope.
+- A non-goal is added or removed.
+- A new decision is made that affects the PRD (e.g., cut a feature).
+
+## When NOT to run
+
+- Rewriting the PRD from scratch → use `/wize-create-prd`.
+- Validating the PRD → use `/wize-validate-prd`.
+
+## Inputs
+
+- `.wize/planning/prd.md` (current)
+- A free-form change request from the user.
+
+## Output
+
+- Updated `.wize/planning/prd.md`.
+- New row in `.wize/planning/prd-changelog.md` (one row per change).
+
+## Steps
+
+### 1. Read the current PRD
+
+Parse the PRD frontmatter (`status`, `owner`, `created`, `last_updated`) and the body. Confirm the change is in scope of "edit" (not a rewrite). If the change touches > 25% of the PRD, route to `/wize-create-prd` instead.
+
+### 2. Classify the edit
+
+Pick exactly one type:
+
+- **A** — Add or change an AC.
+- **B** — Move item in-scope ↔ out-of-scope.
+- **C** — Add or remove a non-goal.
+- **D** — Register a decision that affects the PRD (link to ADR or sprint decision).
+
+One edit per run. Re-run for additional edits.
+
+### 3. Apply the edit
+
+Make the change in `prd.md`. Mark the changed section with a trailing note: `(edited 2026-06-15, see changelog row 4)`.
+
+Update frontmatter: `last_updated` to today; `status` stays the same (only `/wize-validate-prd` flips it to `validated`).
+
+### 4. Append to changelog
+
+Add a row to `prd-changelog.md`:
+
+```markdown
+| Date | Type | Section | Change | Author |
+|---|---|---|---|---|
+| 2026-06-15 | A | AC-04-2 | Added: "rate limit per team" | Hill |
+| 2026-06-15 | B | Out of scope | Removed "bulk invite" (now in scope per E04-S02) | Hill |
+```
+
+### 5. Cross-cutting check
+
+Wizer flags any downstream impact:
+
+- New AC → check that the epic + stories covering it exist. If not, route to `/wize-create-epics-and-stories`.
+- New non-goal → check that no in-flight story assumes the opposite. If yes, flag the story.
+- In-scope move → trigger a fresh `/wize-sprint-planning` consideration.
+
+### 6. Hand off
+
+Notify the next workflow:
+
+- If AC changed → `/wize-validate-prd` to confirm consistency.
+- If epic + stories need refresh → `/wize-create-epics-and-stories`.
+- If sprint needs re-prioritization → `/wize-sprint-planning`.
+
+## Output template — `prd-changelog.md`
+
+```markdown
+# PRD changelog
+
+| # | Date | Type | Section | Change | Author |
+|---|---|---|---|---|---|
+| 1 | 2026-06-15 | A | AC-04-2 | Added: "rate limit per team" | Hill |
+| 2 | 2026-06-15 | B | Out of scope | Removed "bulk invite" | Hill |
+```
+
+## Anti-patterns Hill rejects
+
+- Editing the PRD without recording the change in the changelog. (Source-of-truth drift.)
+- Bundling 4 edits in one run. (One edit per run keeps blame clean.)
+- Editing the PRD without checking downstream impact. (Wizer’s cross-cutting step is mandatory.)
+- Re-running `/wize-create-prd` to "keep things tidy." The changelog exists for that.
+
+## Hand-off
+
+> "PRD updated at `.wize/planning/prd.md`. Changelog row N appended. Next: `/wize-validate-prd` (re-validate) or `/wize-create-epics-and-stories` (refresh stories)."