wize-dev-kit 0.3.0 → 0.4.0

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

package/src/method-skills/4-implementation/wize-code-review/steps/step-01-gather-context.md

@@ -0,0 +1,64 @@
+---
+diff_output: ''
+spec_file: ''
+review_mode: ''
+story_key: ''
+---
+
+# Step 1: Gather Context
+
+## Rules
+
+- Speak in `{communication_language}`.
+- The prompt that triggered this workflow IS the intent.
+- Do not modify any files in this step. Read-only.
+
+## Instructions
+
+1. **Find the review target.** Check in this order and stop as soon as the target is identified:
+
+   **Tier 1 — Explicit argument.**
+   Did the user pass a PR, commit SHA, branch, spec file, or diff source?
+   - PR reference → resolve to branch/commit via `gh pr view`.
+   - Commit or branch → use directly.
+   - Spec file → set `{spec_file}` to the path. Check its frontmatter for `baseline_commit`.
+   - Diff-mode keywords: `staged`, `uncommitted`, `branch diff`, `commit range`, `this diff`.
+
+   **Tier 2 — Recent conversation.**
+   Look for refs in the last few messages.
+
+   **Tier 3 — Sprint tracking.**
+   Look for `*sprint-status*` files and find stories with status `review`.
+
+   **Tier 4 — Current git state.**
+   If not on the default branch, confirm whether to review the current branch.
+
+   **Tier 5 — Ask.**
+   Present options: uncommitted changes, staged changes, branch diff, commit range, provided diff.
+
+2. **Construct `{diff_output}`.**
+   - Staged only: `git diff --cached`
+   - Uncommitted: `git diff HEAD`
+   - Branch diff: `git diff <base>..<branch>`
+   - Commit range: `git diff <from>..<to>`
+   - Provided diff: validate and use verbatim
+   - File list: `git diff HEAD -- <files...>`, with untracked files included via `git diff --no-index /dev/null <path>`
+
+   If `{diff_output}` is empty, halt and say so.
+
+3. **Set the spec context.**
+   - If `{spec_file}` is set and readable, set `{review_mode}` = `"full"`.
+   - Otherwise ask: "Is there a spec or story file that provides context for these changes?"
+     - Yes → set `{spec_file}`, verify it, set `{review_mode}` = `"full"`.
+     - No → set `{review_mode}` = `"no-spec"`.
+
+4. **Sanity check.**
+   If the diff exceeds ~3000 lines, warn and offer to chunk.
+
+### Checkpoint
+
+Present a summary: diff stats, `{review_mode}`, loaded spec/context docs. Halt and wait for confirmation to proceed.
+
+## Next
+
+Read fully and follow `./step-02-review.md`.

package/src/method-skills/4-implementation/wize-code-review/steps/step-02-review.md

@@ -0,0 +1,38 @@
+---
+failed_layers: ''
+---
+
+# Step 2: Review
+
+## Rules
+
+- Speak in `{communication_language}`.
+- The Blind Hunter subagent receives **only** the diff — no project context.
+- The Edge Case Hunter subagent receives the diff and project read access.
+- The Acceptance Auditor subagent receives the diff, spec, and context docs.
+- All review subagents run at the same model capability as the current session.
+
+## Instructions
+
+1. If `{review_mode}` = `"no-spec"`, note: "Acceptance Auditor skipped — no spec file provided."
+
+2. Launch parallel subagents without conversation context:
+
+   - **Blind Hunter** — receives `{diff_output}` only. Invoke via `wize-review-adversarial`.
+     Prompt: "Review this diff cynically. Assume problems exist. Find at least ten issues. Output as a Markdown list with one-line titles."
+
+   - **Edge Case Hunter** — receives `{diff_output}` and read access to the project. Invoke via `wize-review-edge-case-hunter`.
+     Prompt: "Walk every branching path and boundary condition in this diff. Report only unhandled edge cases as a JSON array."
+
+   - **Acceptance Auditor** (only if `{review_mode}` = `"full"`) — receives `{diff_output}`, `{spec_file}` content, and context docs.
+     Prompt: "Review this diff against the spec. Check for violations of acceptance criteria, deviations from spec intent, and missing behavior. Output findings as a Markdown list with AC/constraint reference and evidence."
+
+3. If subagents are unavailable, generate prompt files in `{implementation_artifacts}` and halt, asking the user to run each in a separate session.
+
+4. If any subagent fails, times out, or returns empty, append the layer name to `{failed_layers}` and proceed with findings from the remaining layers.
+
+5. Collect all findings from completed layers.
+
+## Next
+
+Read fully and follow `./step-03-triage.md`.

package/src/method-skills/4-implementation/wize-code-review/steps/step-03-triage.md

@@ -0,0 +1,43 @@
+# Step 3: Triage
+
+## Rules
+
+- Speak in `{communication_language}`.
+- Be precise. When uncertain between categories, prefer the more conservative classification.
+
+## Instructions
+
+1. **Normalize** findings into a common format. Expected input formats:
+   - Blind Hunter: Markdown list of descriptions.
+   - Edge Case Hunter: JSON array with `location`, `trigger_condition`, `guard_snippet`, `potential_consequence`.
+   - Acceptance Auditor: Markdown list with title, AC/constraint reference, and evidence.
+
+   Convert all to a unified list with:
+   - `id` — sequential integer
+   - `source` — `blind`, `edge`, `auditor`, or merged (`blind+edge`, etc.)
+   - `title` — one-line summary
+   - `detail` — full description
+   - `location` — file and line reference if available
+
+2. **Deduplicate.** Merge findings that describe the same issue:
+   - Use the most specific finding as the base (prefer Edge Case Hunter JSON with location).
+   - Append unique detail, reasoning, or locations from other findings.
+   - Set `source` to merged sources.
+
+3. **Classify** each finding into exactly one bucket:
+   - **decision_needed** — ambiguous choice requiring human input. Only possible if `{review_mode}` = `"full"`.
+   - **patch** — code issue fixable without human input.
+   - **defer** — pre-existing issue not caused by this change.
+   - **dismiss** — noise, false positive, or handled elsewhere.
+
+   If `{review_mode}` = `"no-spec"` and a finding would be `decision_needed`, reclassify as `patch` or `defer`.
+
+4. **Drop** all `dismiss` findings. Record the dismiss count.
+
+5. If `{failed_layers}` is non-empty, report which layers failed. If zero findings remain and layers failed, warn the user that the review may be incomplete.
+
+6. If zero findings remain after triage, state: "✅ Clean review — all layers passed."
+
+## Next
+
+Read fully and follow `./step-04-present.md`.

package/src/method-skills/4-implementation/wize-code-review/steps/step-04-present.md

@@ -0,0 +1,100 @@
+---
+deferred_work_file: '{implementation_artifacts}/deferred-work.md'
+---
+
+# Step 4: Present and Act
+
+## Rules
+
+- Speak in `{communication_language}`.
+- When `{spec_file}` is set, always write findings to the story file before offering action choices.
+- `decision_needed` findings must be resolved before handling `patch` findings.
+
+## Instructions
+
+### 1. Clean review shortcut
+
+If zero findings remain after triage, state that and proceed to section 6 (Sprint Status Update).
+
+### 2. Write findings to the story file
+
+If `{spec_file}` exists and contains a Tasks/Subtasks section, append a `### Review Findings` subsection in this order:
+
+1. `decision_needed` (unchecked):
+   ```
+   - [ ] [Review][Decision] <Title> — <Detail>
+   ```
+2. `patch` (unchecked):
+   ```
+   - [ ] [Review][Patch] <Title> [<file>:<line>]
+   ```
+3. `defer` (checked):
+   ```
+   - [x] [Review][Defer] <Title> [<file>:<line>] — deferred, pre-existing
+   ```
+
+Also append each `defer` finding to `{deferred_work_file}` under `## Deferred from: code review ({date})`.
+
+### 3. Present summary
+
+```
+Code review complete.
+- decision_needed: {D}
+- patch: {P}
+- defer: {W}
+- dismissed: {R}
+```
+
+If `{spec_file}` is set, add: "Findings written to `{spec_file}`."
+
+### 4. Resolve decision_needed findings
+
+Present each `decision_needed` finding and ask the user to decide. Once resolved, each becomes a `patch`, `defer`, or is dismissed.
+
+If deferred, ask for a one-line reason and append it to both the story file bullet and the deferred-work file.
+
+### 5. Handle patch findings
+
+If `patch` findings exist, ask:
+
+```
+How would you like to handle the {P} patch findings?
+1. Apply every patch — fix all now, no per-finding confirmation.
+2. Leave as action items — they are already in the story file (only if spec_file set).
+3. Walk through each patch — show details before deciding.
+```
+
+Wait for the numbered choice. Do not proceed until selected.
+
+- **Apply every patch**: apply all patch findings. Afterward, present a summary of changes and check off patch items in the story file if applicable.
+- **Leave as action items**: done.
+- **Walk through each patch**: present each finding with detail and suggested fix, then re-offer the menu.
+
+### 6. Update story status and sync sprint tracking
+
+Skip if `{spec_file}` is not set.
+
+Determine `{new_status}`:
+- If all `decision_needed` and `patch` findings are resolved and no unresolved issues remain → `done`
+- If patch findings were left as action items or unresolved issues remain → `in-progress`
+
+Update the story file status and save it.
+
+If `{story_key}` is set and a sprint-status file exists, update the matching `development_status` entry.
+
+### 7. Next steps
+
+Present options:
+
+```
+What would you like to do next?
+1. Start the next story — run wize-dev-story to pick up the next ready-for-dev story.
+2. Re-run code review — address findings and review again.
+3. Done — end the workflow.
+```
+
+Wait for the numbered choice.
+
+## On complete
+
+Run `{workflow.on_complete}` if non-empty.