wize-dev-kit 0.16.0 → 0.16.1

package/src/method-skills/3-solutioning/wize-create-architecture/steps/step-07-validation.md

@@ -0,0 +1,124 @@
+# Step 7: Architecture Validation & Completion
+
+## Mandatory execution rules
+
+- 🛑 Never generate content without user input.
+- ✅ Validate all requirements are covered by architectural decisions.
+- ⚠️ No time estimates.
+- ✅ Speak in `{communication_language}`; write artifacts in `{document_output_language}`.
+
+## Execution protocols
+
+- 🎯 Show analysis before taking action.
+- ✅ Run validation checks on the complete architecture.
+- ⚠️ Present A/P/C menu after generating validation results.
+- 💾 Only save when the user chooses C.
+- 📖 Update frontmatter `stepsCompleted: [1, 2, 3, 4, 5, 6, 7]` before loading the next step.
+
+## Collaboration menu (A/P/C)
+
+- **A (Advanced Elicitation)** — address complex architectural issues found.
+- **P (Party Mode)** — review validation from multiple perspectives.
+- **C (Continue)** — save validation results and complete the architecture.
+
+## Context boundaries
+
+- Complete architecture document is available.
+- All decisions, patterns, and structure are defined.
+- Focus on validation, gap analysis, and coherence.
+
+## Task
+
+Validate the complete architecture for coherence, completeness, and readiness.
+
+## Validation sequence
+
+### 1. Coherence validation
+
+- Decision compatibility
+- Pattern consistency
+- Structure alignment
+
+### 2. Requirements coverage validation
+
+- Epic/feature coverage
+- Functional requirements coverage
+- Non-functional requirements coverage
+
+### 3. Implementation readiness validation
+
+- Decision completeness
+- Structure completeness
+- Pattern completeness
+
+### 4. Gap analysis
+
+Identify critical, important, and nice-to-have gaps.
+
+### 5. Generate validation content
+
+Append to `architecture.md`:
+
+```markdown
+## Architecture Validation Results
+
+### Coherence Validation
+...
+
+### Requirements Coverage Validation
+...
+
+### Implementation Readiness Validation
+...
+
+### Gap Analysis Results
+...
+
+### Validation Issues Addressed
+...
+
+### Architecture Completeness Checklist
+
+**Requirements Analysis**
+- [ ] Project context thoroughly analyzed
+- [ ] Scale and complexity assessed
+- [ ] Technical constraints identified
+- [ ] Cross-cutting concerns mapped
+
+**Architectural Decisions**
+- [ ] Critical decisions documented with versions
+- [ ] Technology stack fully specified
+- [ ] Integration patterns defined
+- [ ] Performance considerations addressed
+
+**Implementation Patterns**
+- [ ] Naming conventions established
+- [ ] Structure patterns defined
+- [ ] Communication patterns specified
+- [ ] Process patterns documented
+
+**Project Structure**
+- [ ] Complete directory structure defined
+- [ ] Component boundaries established
+- [ ] Integration points mapped
+- [ ] Requirements to structure mapping complete
+
+### Architecture Readiness Assessment
+
+**Overall Status:** [READY FOR IMPLEMENTATION / READY WITH MINOR GAPS / NOT READY]
+**Confidence Level:** [high/medium/low]
+**Key Strengths:** ...
+**Areas for Future Enhancement:** ...
+
+### Implementation Handoff
+
+**AI Agent Guidelines:**
+- Follow all architectural decisions exactly as documented.
+- Use implementation patterns consistently.
+- Respect project structure and boundaries.
+- Refer to this document for all architectural questions.
+```
+
+## Next step
+
+After C, load `./step-08-complete.md`.

package/src/method-skills/3-solutioning/wize-create-architecture/steps/step-08-complete.md

@@ -0,0 +1,59 @@
+# Step 8: Architecture Completion & Handoff
+
+## Mandatory execution rules
+
+- 🛑 Never generate content without user input.
+- ✅ Treat this as collaborative completion.
+- 🎯 Provide clear next steps for implementation.
+- ⚠️ No time estimates.
+- ✅ Speak in `{communication_language}`; write artifacts in `{document_output_language}`.
+
+## Execution protocols
+
+- 🎯 Show completion summary and implementation guidance.
+- 📖 Update frontmatter with final workflow state.
+- 🚫 This is the final step.
+
+## Task
+
+Complete the architecture workflow and guide the user to the next phase.
+
+## Completion sequence
+
+### 1. Summarize achievements
+
+Congratulate the user and summarize what was built together:
+
+- Architecture document path
+- Number of ADRs produced
+- Key decisions made
+- Patterns defined
+- Validation status
+
+### 2. Update frontmatter
+
+```yaml
+status: ready-for-stories
+owner: Tony Stark
+updated: "{{date}}"
+stepsCompleted: [1, 2, 3, 4, 5, 6, 7, 8]
+workflowType: architecture
+lastStep: 8
+```
+
+### 3. Next steps guidance
+
+```
+Architecture complete. Next:
+1. Hawkeye: run wize-tea-risk to build the global risk profile.
+2. Tony: run wize-create-epics-and-stories to slice the work.
+3. Use `/wize` (or `/wize-help`) anytime to check what comes next.
+```
+
+## On complete
+
+Run `{workflow.on_complete}` if non-empty.
+
+## Workflow complete
+
+The architecture is now the single source of truth for all technical decisions, ensuring consistent implementation across the project lifecycle.

package/src/method-skills/3-solutioning/wize-create-architecture/workflow.md

@@ -1,64 +1,71 @@
 ---
+
 code: wize-create-architecture
+description: "Use quando o PRD e UX design estiverem prontos e precisar projetar a arquitetura do sistema com componentes, sequências e ADRs."
 name: Create Architecture
 phase: 3-solutioning
 owner: wize-agent-architect   # Tony Stark
-status: stub
+status: ready
 ---
 
 # Create Architecture
 
-**Goal.** Design the system inside Fury's frame. Components, sequences, data flows, ADRs. Concrete enough that Shuri can implement and Hawkeye can test.
+**Goal.** Design the system inside Fury's frame through collaborative, step-by-step discovery. Produces `.wize/solutioning/architecture.md` + `.wize/solutioning/adrs/` that multiple AI agents can implement consistently.
+
+Tony Stark drives. Pepper Potts and Nick Fury may be invoked via `wize-party-mode` or `wize-advanced-elicitation` at any step.
 
 ## Inputs
-- `.wize/planning/prd.md`
-- `.wize/planning/ux/ux-design/`
-- `.wize/planning/tech-vision.md` (Fury)
-- `.wize/planning/nfr-principles.md` (Fury)
-- `.wize/solutioning/design-system/` (Mantis)
-- `.wize/knowledge/document-project/` (if brownfield)
+
+- `.wize/planning/prd.md` (required)
+- `.wize/planning/ux/ux-scenarios.md` and `.wize/planning/ux/ux-design/` (when available)
+- `.wize/planning/tech-vision.md`
+- `.wize/planning/nfr-principles.md`
+- `.wize/solutioning/design-system/` (when available)
+- Stack catalogs from active overlays
+- `.wize/knowledge/document-project/` (brownfield only)
 
 ## Outputs
+
 - `.wize/solutioning/architecture.md`
-- `.wize/solutioning/adrs/{ADR-NNN}-{slug}.md`
+- `.wize/solutioning/adrs/ADR-NNN-{slug}.md`
+
+## Workflow architecture
+
+This skill uses **micro-file architecture**:
+
+- Each step is a self-contained file with embedded rules.
+- Sequential progression with user control at each step.
+- Document state tracked in frontmatter (`stepsCompleted`).
+- Append-only document building through the conversation.
+- Never proceed to a step file if the current step indicates the user must approve continuation.
+
+## On activation
+
+1. Load `.wize/config/project.toml` and `.wize/config/user.toml`.
+2. Resolve `user_name`, `communication_language`, `document_output_language`, `output_folder`, and the active profiles.
+3. Greet the user in `communication_language`.
+4. Read fully and follow `./steps/step-01-init.md`.
 
 ## Steps
-1. **Stack interview.** Tony asks the user (via Wizer) about preferences: language, runtime, deployment target. Consults overlay stack catalogs (web/app) if active. Records decisions.
-2. **Components.** List components, responsibilities, boundaries.
-3. **Sequences.** For each critical scenario from Mantis, write a sequence (text or PlantUML).
-4. **Data model.** Tables / collections / contracts.
-5. **Cross-cutting.** Auth, logging, observability, error handling.
-6. **ADRs.** Every significant trade-off becomes its own ADR: context, options, decision, consequences.
-7. **Validate against NFRs.** Check each Fury principle.
-8. **Hand-off to epics.**
-
-## Architecture doc template
-
-```markdown
-# Architecture — {{project_name}}
-
-## Stack
-- Language: …
-- Runtime: …
-- Storage: …
-- Deploy: …
-
-## Components
-| Component | Responsibility | Boundary |
-|---|---|---|
-
-## Data model
-…
-
-## Cross-cutting
-- Auth: …
-- Observability: …
-- Errors: …
-
-## NFR check
-- Performance: …
-- Security: …
-- Reliability: …
-- Accessibility: …
-- Cost: …
-```
+
+1. `step-01-init.md` — detect continuation, discover inputs, create `architecture.md` from template.
+2. `step-02-context.md` — analyze PRD, UX, and research for architectural implications.
+3. `step-03-starter.md` — discover technical preferences and evaluate starter templates.
+4. `step-04-decisions.md` — make core architectural decisions (data, auth, API, frontend, infra).
+5. `step-05-patterns.md` — define implementation patterns that prevent agent conflicts.
+6. `step-06-structure.md` — map requirements to concrete project structure and boundaries.
+7. `step-07-validation.md` — validate coherence, coverage, and implementation readiness.
+8. `step-08-complete.md` — finalize frontmatter and hand off to implementation.
+
+## Global step rules
+
+- Always read the complete step file before acting.
+- Speak in `communication_language`.
+- Write artifacts in `document_output_language`.
+- Never generate content without user input or confirmation.
+- Every code reference uses CWD-relative `path:line` format.
+- No time estimates — AI development speed has fundamentally changed.
+
+## Hand-off
+
+> Architecture and ADRs are in `.wize/solutioning/`. Sequences hit the NFR targets. Hawkeye can write `tea-risk.md` against this. Tony continues with `wize-create-epics-and-stories`.

package/src/method-skills/3-solutioning/wize-create-epics-and-stories/workflow.md

@@ -1,24 +1,101 @@
 ---
+
 code: wize-create-epics-and-stories
+description: "Use quando a arquitetura estiver definida e precisar fatiar o escopo em epics e stories com acceptance criteria."
 name: Create Epics and Stories
 phase: 3-solutioning
 owner: wize-agent-architect   # Tony Stark
-status: stub
+status: ready
 ---
 
 # Create Epics and Stories
 
-**Goal.** Slice the PRD + architecture into epics (each ships value) and stories (each is one focused PR-sized unit).
+**Goal.** Slice the PRD + architecture into **epics** (each ships value end-to-end) and **stories** (each is one focused PR-sized unit Shuri can implement and Hawkeye can test).
+
+Tony drives. Output lands in `.wize/solutioning/epics/` and `.wize/solutioning/stories/`.
+
+> **No estimates.** Epics and stories never carry a time or effort estimate (hours, days, story points, S/M/L/XL) — at any step. AI development speed has made them noise that only burns time and tokens. The only sizing question is binary: **does a story fit one PR?** If not, slice it.
+
+When slicing raises decisions the PRD doesn't answer — priority order, sequencing, protected behaviors, what's out of a story — offer a short `wize-grill` pass with the user instead of guessing. Decisions land in the epic/story fields; unresolved ones become open questions with owners.
 
 ## Inputs
-- `.wize/planning/prd.md`
+
+Read central docs first, then expand by dependency — don't load unrelated files for padding:
+
+- `AGENTS.md` + `.wize/config/project.toml` — active profiles, languages, conventions.
+- `.wize/planning/prd.md` — the AC source (never reword ACs downstream).
 - `.wize/solutioning/architecture.md`
+- `.wize/planning/ux/ux-design/` (every story references one or more screens)
+- `.wize/knowledge/document-project/` — brownfield baseline, if present.
 
 ## Outputs
+
 - `.wize/solutioning/epics/{NN}-{slug}.md`
-- `.wize/solutioning/stories/{NN}-{slug}/{story-id}.md`
+- `.wize/solutioning/stories/{epic-NN}/{story-id}.md`
+
+## Epic shape
+
+An epic:
+- Ships **value** on its own (a user can do the thing after this epic, even if the next one improves it).
+- Lasts 1–3 sprints when in flight.
+- Has 3–10 stories.
+- Has a single trigger-map row as its anchor.
+
+Epic file:
+
+```markdown
+---
+epic_id: 01-onboarding
+status: ready
+owner: Tony Stark + Maria Hill
+linked_prd: E01
+trigger_map_row: 1
+priority: 1
+---
+
+# Epic 01: Sign-up + first invite
+
+## Outcome
+A first-time team admin signs up, lands in onboarding, and invites at least one teammate within 5 minutes (trigger-map row 1 + 2).
+
+## Stories
+- E01-S01: Sign-up empty + happy path (AC-01-1, AC-01-2)
+- E01-S02: Sign-up error states (AC-01-3, AC-01-4)
+- E01-S03: Onboarding step 1 — invite first teammate (AC-02-1, AC-02-2)
+- E01-S04: Email delivery + retry (AC-02-3)
+- E01-S05: Team list empty + with first member (AC-03-1, AC-03-2)
+
+## Dependencies
+- Design tokens by Mantis (S0 — already done)
+- Resend account configured (Tony, before S04)
+
+## Success
+All ACs of all stories PASS gate. Telemetry shows `teammate_invited` ≥ 80% of `signup_completed` users within 24h in the beta cohort.
+```
+
+## Story shape — INVEST
+
+Each story passes:
+- **I**ndependent — can be implemented without waiting for another in-flight story.
+- **N**egotiable — wording can move; intent stays.
+- **V**aluable — a real outcome to a real user (or a clear test path that proves a slice).
+- **S**mall — fits in one PR, tests included. This is the *only* sizing test; no time or point estimate (see **No estimates** above).
+- **T**estable — every AC is observable.
+
+If a story is XL, slice it before merging it to `stories/`.
 
-## Story template
+## Slicing patterns (Tony's defaults)
+
+| Pattern | When |
+|---|---|
+| Walking skeleton | When you need the full user path to exist (even with stubs) before going deep on any single screen. |
+| By user role | Admin vs member often slice naturally. |
+| By acceptance criterion | One AC = one PR when ACs are independent. |
+| By happy / error path | Ship happy path first; error states next story. |
+| By back-end / front-end | Avoid unless the back-end can ship usable without UI; otherwise it bundles. |
+| By feature flag | When a story partially ships, use a flag and write the flag retirement story now. |
+
+## Story file template
 
 ```markdown
 ---
@@ -26,23 +103,85 @@ story_id: E01-S03
 epic: 01-onboarding
 status: ready-for-dev
 priority: 2
-estimate: M
-linked_screen: ux-design/signin.md
+linked_screens: [onboarding-step-1, invite-modal]
+linked_acs: [AC-02-1, AC-02-2]
 ---
 
-# Story: Sign-in with email + magic link
+# Story: Onboarding step 1 — invite first teammate
 
 ## Context
-…
+Comes right after sign-up. The user lands here with no team yet. The screen is the moment-of-truth from S1: if the user invites a teammate here, the product earned its value moment.
+
+## Sources of truth (Shuri reads before coding)
+- `AGENTS.md` + `.wize/config/project.toml` · `.wize/knowledge/document-project/*`.
+- `prd.md` (AC source) · `architecture.md` · `ux-design/onboarding-step-1.md` · parent epic `01-onboarding.md`.
+- The TEA test contract for this story · related code + tests already on this path.
 
 ## Acceptance criteria
-- AC-1 …
-- AC-2 …
+- **AC-02-1:** Given a new admin on `/onboarding`, When they enter a valid email and click "Send invite", Then a `teammate_invited` event fires and the screen advances to "Invite sent" within 1s.
+- **AC-02-2:** Given an invalid email, When the user blurs the field, Then error text appears (200ms) identifying which rule failed.
 
-## Out of scope
-- …
+## Restrictions
+- **Out of scope:** bulk invite → E01-S07; custom invite message → E02-S03.
+- **Protected behaviors:** existing sign-up + session flow must not change.
+- **Compatibility:** `(team_id, email)` idempotency key — don't break existing invite rows.
+- **Security:** validate email at the server boundary; auth context required on `inviteTeammate`.
 
 ## Notes for Shuri (Dev)
-- Touch points: …
-- Tests required: …
+- Touch points: `app/(onboarding)/invite/page.tsx`, new server action `inviteTeammate`, `lib/email/send-invite.ts`.
+- Reuse `Button`, `Input`, `Banner` from design system.
+- Add `data-testid="invite-form"`, `"invite-email"`, `"invite-cta"` (Hawkeye depends on these).
+
+## Validation contract
+- **AC → test:** AC-02-1 → E2E `invite happy path` + unit `validateInviteEmail`; AC-02-2 → unit `invalid email` + component error-state.
+- **Required checks:** the unit/integration/E2E split Hawkeye declares below, plus lint, format, type-check, build. Authz asserted on the server action.
+- **States:** loading, empty, error rendered and asserted.
+
+## Notes for Hawkeye (TEA)
+- Tests required: 2 unit (validation), 1 integration (server action calls mailer with right args), 1 E2E (happy path on Playwright).
+- Mocks: outbound email via MSW; auth context via fixture.
+- NFR sample: response p95 ≤ 800ms locally (NFR 1.A allows up to 1s end-to-end).
+
+## Done means
+Every AC has a passing test (mapped above), gate PASS/CONCERNS, story `status: ready-for-review`, knowledge axes updated if touched.
 ```
+
+## Steps
+
+### 1. From PRD backbone → epics
+
+Each backbone story in the PRD becomes one epic. Name epics by outcome, not by feature: "Sign-up + first invite," not "Auth screens."
+
+### 2. From scenarios → stories
+
+For each epic, walk the linked scenarios in `ux-scenarios.md`. Slice into stories by the patterns above. Aim for 3–7 stories per epic.
+
+### 3. ACs map exactly
+
+Every story declares the AC IDs it advances (from PRD). The union of stories per epic equals the AC set of that epic — no gaps, no overlap.
+
+### 3.5 Fill the contract fields
+
+Each story carries its own **sources of truth**, **restrictions** (out-of-scope + protected behaviors + compatibility + security), and a **validation contract** (AC → test map + required checks). These aren't optional prose — they are what makes AC → code → test → gate traceable. A story missing them is not ready for dev.
+
+### 4. Slice check (no estimates)
+
+Don't estimate stories — size them by one question: does each fit a single PR? Anything that doesn't gets sliced before it lands in `stories/`. If most stories feel too big to slice cleanly, the slicing pattern is too coarse; revisit it.
+
+### 5. Hand off
+
+- Mark all epics + stories `status: ready-for-dev`.
+- Trigger `wize-check-implementation-readiness` (Tony, with Hawkeye on risk profile).
+- After ready, Hill runs sprint planning.
+
+## Anti-patterns Tony rejects
+
+- **Stories without AC links.** No traceability → no gate later.
+- **Stories that "ship a back-end."** Bundle with the front-end consumer unless a different team uses it independently.
+- **XL stories.** Slice further or split into two PRs.
+- **"Epic" that is one story.** Then it's a story.
+- **Stories that share `testid` namespace.** They'll collide.
+
+## Hand-off
+
+> Epics and stories at `.wize/solutioning/`. 5 epics, 28 stories. All have ACs from the PRD. Run `wize-check-implementation-readiness`; Hawkeye, `tea-risk.md` next.