wize-dev-kit 0.3.1 → 0.4.0

package/src/method-skills/3-solutioning/wize-create-architecture/steps/step-05-patterns.md

@@ -0,0 +1,109 @@
+# Step 5: Implementation Patterns & Consistency Rules
+
+## Mandatory execution rules
+
+- 🛑 Never generate content without user input.
+- ✅ Treat this as collaborative discovery.
+- 🎯 Focus on patterns that prevent AI agent implementation conflicts.
+- 🎯 Emphasize what agents could decide differently if not specified.
+- ⚠️ No time estimates.
+- ✅ Speak in `{communication_language}`; write artifacts in `{document_output_language}`.
+
+## Execution protocols
+
+- 🎯 Show analysis before taking action.
+- ⚠️ Present A/P/C menu after generating patterns content.
+- 💾 Only save when the user chooses C.
+- 📖 Update frontmatter `stepsCompleted: [1, 2, 3, 4, 5]` before loading the next step.
+
+## Collaboration menu (A/P/C)
+
+- **A (Advanced Elicitation)** — develop additional consistency patterns.
+- **P (Party Mode)** — identify conflict points from multiple perspectives.
+- **C (Continue)** — save and move to project structure.
+
+## Context boundaries
+
+- Core decisions from step 4 are complete.
+- Technology stack is decided.
+- Focus on HOW agents should implement, not WHAT.
+
+## Task
+
+Define implementation patterns and consistency rules so multiple AI agents write compatible code.
+
+## Pattern categories
+
+### Naming patterns
+
+- Database table/column naming
+- API endpoint naming
+- File and directory naming
+- Component/function/variable naming
+- Route parameter formats
+
+### Structure patterns
+
+- Where tests live
+- How components are organized
+- Where utilities and helpers go
+- Configuration file organization
+
+### Format patterns
+
+- API response wrappers
+- Error response structures
+- Date/time formats
+- JSON field naming (snake_case vs camelCase)
+
+### Communication patterns
+
+- Event naming conventions
+- Event payload structures
+- State update patterns
+- Action naming conventions
+- Logging formats and levels
+
+### Process patterns
+
+- Loading state handling
+- Error recovery
+- Retry implementation
+- Authentication flow
+- Validation timing and methods
+
+## Generate patterns content
+
+Append to `architecture.md`:
+
+```markdown
+## Implementation Patterns & Consistency Rules
+
+### Naming Patterns
+...
+
+### Structure Patterns
+...
+
+### Format Patterns
+...
+
+### Communication Patterns
+...
+
+### Process Patterns
+...
+
+### Enforcement Guidelines
+
+**All AI agents MUST:**
+- ...
+
+### Pattern Examples
+**Good:** ...
+**Anti-patterns:** ...
+```
+
+## Next step
+
+After C, load `./step-06-structure.md`.

package/src/method-skills/3-solutioning/wize-create-architecture/steps/step-06-structure.md

@@ -0,0 +1,97 @@
+# Step 6: Project Structure & Boundaries
+
+## Mandatory execution rules
+
+- 🛑 Never generate content without user input.
+- ✅ Treat this as collaborative discovery.
+- 🗺️ Create a complete project tree, not generic placeholders.
+- 🗺️ Map requirements/epics to architectural components.
+- ⚠️ No time estimates.
+- ✅ Speak in `{communication_language}`; write artifacts in `{document_output_language}`.
+
+## Execution protocols
+
+- 🎯 Show analysis before taking action.
+- ⚠️ Present A/P/C menu after generating project structure.
+- 💾 Only save when the user chooses C.
+- 📖 Update frontmatter `stepsCompleted: [1, 2, 3, 4, 5, 6]` before loading the next step.
+
+## Collaboration menu (A/P/C)
+
+- **A (Advanced Elicitation)** — explore innovative project organization.
+- **P (Party Mode)** — evaluate structure trade-offs.
+- **C (Continue)** — save and move to validation.
+
+## Context boundaries
+
+- All previous decisions are complete.
+- Implementation patterns are defined.
+- Focus on physical project structure and component boundaries.
+
+## Task
+
+Define the complete project structure and architectural boundaries based on all decisions made.
+
+## Structure sequence
+
+### 1. Analyze requirements mapping
+
+Map epics or FR categories to directories/services.
+
+### 2. Define project directory structure
+
+Create a complete, technology-specific tree:
+
+- Root configuration files
+- Source code organization
+- Test organization
+- Build and distribution
+
+### 3. Define integration boundaries
+
+- API boundaries
+- Component boundaries
+- Service boundaries
+- Data boundaries
+
+### 4. Map requirements to structure
+
+For each epic or feature cluster:
+
+```markdown
+Epic: User Management
+- Components: src/components/features/users/
+- Services: src/services/users/
+- API Routes: src/app/api/users/
+- Database: prisma/migrations/...
+- Tests: tests/features/users/
+```
+
+## Generate structure content
+
+Append to `architecture.md`:
+
+```markdown
+## Project Structure & Boundaries
+
+### Complete Project Directory Structure
+```
+{{tree}}
+```
+
+### Architectural Boundaries
+...
+
+### Requirements to Structure Mapping
+...
+
+### Integration Points
+...
+
+### File Organization Patterns
+...
+```
+
+## Next step
+
+After C, load `./step-07-validation.md`.

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-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

@@ -8,225 +8,62 @@ 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 write `tea-design.md` for every story.
+**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 drives. Output lands in `.wize/solutioning/architecture.md` + `.wize/solutioning/adrs/`.
+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` (validated)
-- `.wize/planning/ux/ux-design/` (every architectural decision should make at least one screen possible)
-- `.wize/planning/tech-vision.md` (the frame)
-- `.wize/planning/nfr-principles.md` (the budget)
-- `.wize/solutioning/design-system/` (Mantis' tokens, when available)
-- Stack catalogs (overlays): `web-overlay/stack-catalog.md`, `app-overlay/stack-catalog.md`
+- `.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` (one ADR per meaningful trade-off)
+- `.wize/solutioning/adrs/ADR-NNN-{slug}.md`
 
-## Steps
-
-### 1. Stack interview (Tony asks; Wizer relays)
-
-Resolve every "TBD" the tech-vision left for Tony. Walk the stack catalog (active overlay) and decide, in order:
-
-- Language(s) + runtime(s).
-- Front-end framework + state lib + form lib.
-- Back-end framework or BaaS.
-- DB + ORM/query builder.
-- Auth.
-- Hosting + CI/CD.
-- Observability stack.
-- Test stack (links to `playwright-vitest.md` or `detox-maestro.md`).
-
-Decisions Tony makes silently are ADR candidates; decisions Fury already fixed don't get their own ADR.
-
-### 2. Components
-
-List components with one-line responsibility each. Boundaries before internals. Examples (web SaaS):
-
-| Component | Responsibility | Boundary |
-|---|---|---|
-| `web` | Server-rendered fullstack app (Next.js) | HTTPS to clients; SQL to db; HTTPS to auth-provider |
-| `db` | Source of truth for users, teams, billing (Postgres) | SQL only via PgBouncer |
-| `auth` | Identity provider (Supabase Auth) | OIDC to `web` |
-| `mailer` | Outbound transactional email | HTTPS to Resend |
-| `worker` | Outbox processor + scheduled jobs (pg_cron) | SQL to db; HTTPS to external APIs |
-
-### 3. Sequences (the critical ones)
-
-For each "moment of truth" in `.wize/planning/ux/ux-scenarios.md`, draw a sequence. Mermaid is fine; ASCII is fine.
-
-```mermaid
-sequenceDiagram
-  participant U as User
-  participant W as web
-  participant A as auth
-  participant D as db
-  U->>W: POST /signup
-  W->>A: signUp(email, password)
-  A-->>W: { user_id, session }
-  W->>D: INSERT user_id INTO accounts
-  D-->>W: ok
-  W-->>U: 302 /onboarding (sets cookie)
-  Note over W,U: total p95 ≤ 1s (NFR 1.A)
-```
-
-Annotate each sequence with the NFR target it must hit.
-
-### 4. Data model
-
-For every entity:
-
-- Name, columns, types, indexes.
-- Foreign keys + cascade behavior.
-- RLS policies if the stack supports them (Supabase, etc.).
-- Soft-delete vs hard-delete.
-
-Include a mini ERD (Mermaid `erDiagram`).
-
-### 5. Cross-cutting concerns
+## Workflow architecture
 
-For each, name the pattern and the library/component:
+This skill uses **micro-file architecture**:
 
-- **Auth & session** — token shape, refresh, multi-device.
-- **Errors** — error class hierarchy, mapping to HTTP, user-facing copy.
-- **Logging** — structured (JSON), correlation IDs, sampling.
-- **Observability** — metrics emitter, traces, dashboards.
-- **Config** — env vars, secrets, feature flags.
-- **Background jobs** — outbox / queue / scheduler.
-- **Idempotency** — keys on write endpoints.
-- **i18n** — string source, translation pipeline.
-- **A11y** — token + library choices that uphold WCAG.
+- 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.
 
-### 6. NFR check (every category)
+## On activation
 
-Walk Fury's NFRs. For each non-negotiable, write *how* the architecture achieves it.
+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`.
 
-- Perf: LCP ≤ 2.5s → edge runtime + RSC + image policy.
-- Security: PII in EU → DB in `eu-central-1`; backups in same region.
-- Reliability: 99.9% → single-region with multi-AZ; failover playbook in `adrs/ADR-007-failover.md`.
-- A11y: WCAG AA → Radix primitives + axe in CI.
-
-### 7. ADRs
-
-One ADR per meaningful trade-off. Format below. Number sequentially. Don't gold-plate; an ADR is a few paragraphs.
-
-### 8. Hand off
-
-Mark `architecture.md` `status: ready-for-stories`. Tony continues with `wize-create-epics-and-stories`.
-
-## Architecture doc template
-
-```markdown
----
-status: ready-for-stories
-owner: Tony Stark
-created: YYYY-MM-DD
----
-
-# Architecture — {{project_name}}
-
-## Summary
-{{One paragraph: stack family, runtime, primary data store, deploy target. The frame.}}
-
-## Stack
-- Language: TypeScript
-- Front-end: Next.js (App Router, RSC, edge runtime)
-- Back-end: Server Actions + Route Handlers
-- DB: Supabase Postgres + Drizzle ORM
-- Auth: Supabase Auth
-- Hosting: Vercel
-- Observability: Vercel + PostHog
-- Test: Vitest + Playwright (see playbook)
-
-## Components
-| Component | Responsibility | Boundary |
-|---|---|---|
-
-## Data model
-- `users` (id PK, email UNIQUE, created_at)
-- `teams` (id PK, name, owner_id FK users)
-- `memberships` (user_id, team_id, role)
-- RLS: `auth.uid() = user_id` on all user-scoped tables.
-
-```mermaid
-erDiagram
-  USERS ||--o{ MEMBERSHIPS : has
-  TEAMS ||--o{ MEMBERSHIPS : has
-```
-
-## Sequences
-
-### S1: Sign-up
-{{sequence diagram + NFR annotation}}
-
-### S2: Invite teammate
-{{sequence diagram}}
-
-## Cross-cutting
-- Auth & session: …
-- Errors: …
-- Logging: …
-- Observability: …
-- Config: …
-- Background jobs: …
-- Idempotency: …
-- i18n: …
-- A11y: …
-
-## NFR check
-- Perf (1.A): how
-- Security (2.A): how
-- Reliability (3.A): how
-- Maintainability (4.A): how
-- A11y (5.A): how
-- Cost (6.A): how
-
-## ADRs
-See `.wize/solutioning/adrs/`.
-```
-
-## ADR template
-
-```markdown
----
-status: accepted | superseded | deprecated
-date: YYYY-MM-DD
-deciders: Tony, Fury
-supersedes: ADR-XXX
----
-
-# ADR-007: {{slug}}
-
-## Context
-{{2–4 sentences: what forced the decision, what constraint is binding.}}
-
-## Options
-1. {{Option A}} — pros / cons / cost
-2. {{Option B}} — pros / cons / cost
-3. {{Option C}} — pros / cons / cost
-
-## Decision
-{{The pick. One sentence.}}
+## Steps
 
-## Consequences
-- **Now:** what we gain, what we accept.
-- **Later:** what we'll likely revisit and when.
-- **Related ADRs:** ADR-005, ADR-009.
-```
+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.
 
-## Anti-patterns Tony rejects
+## Global step rules
 
-- **Architecture without sequences.** A diagram with boxes is half a doc.
-- **NFR check left as "TBD".** Each non-negotiable answers *how*.
-- **ADRs for trivial choices** (which CSS file name) — saves nothing, costs trust.
-- **No ADR for genuinely contested choices** (auth provider, DB selection) — future-readers will re-litigate.
-- **Diagrams in proprietary format only.** Mermaid/ASCII version always present in markdown.
+- 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 6 ADRs at `.wize/solutioning/`. Sequences hit the NFR targets. Hawkeye, you can write `tea-risk.md` against this. Tony continues with `wize-create-epics-and-stories`.
+> 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/4-implementation/wize-code-review/customize.toml

@@ -0,0 +1,21 @@
+# Wize Dev Kit — overrides for the built-in workflow "wize-code-review".
+# DO NOT EDIT in the installed kit; copy to .wize/custom/workflows/wize-code-review/
+# for project-level overrides.
+
+[workflow]
+
+# Steps to run before standard activation (config load, greet).
+activation_steps_prepend = []
+
+# Steps to run after greet but before the workflow begins.
+activation_steps_append = []
+
+# Persistent facts the workflow keeps in mind for the whole run.
+persistent_facts = [
+  "file:{project-root}/.wize/knowledge/document-project/conventions.md",
+]
+
+# Scalar executed when the workflow reaches its final step,
+# after review findings are presented and sprint status is synced.
+# Override wins. Leave empty for no custom post-completion behavior.
+on_complete = ""