git:20260613.a8c0f41 to git:20260613.7bd4681

38 added, 201 removed. Audit A to A.

---

description: "3-solutioning: Create Architecture"

globs:

alwaysApply: false

---

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

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

- For each, name the pattern and the library/component:

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

- ### 6. NFR check (every category)

- Walk Fury's NFRs. For each non-negotiable, write *how* the architecture achieves it.

- - 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/`.

- ```

+ - `.wize/solutioning/adrs/ADR-NNN-{slug}.md`

- ## ADR template

+ ## Workflow architecture

- ```markdown

- ---

- status: accepted | superseded | deprecated

- date: YYYY-MM-DD

- deciders: Tony, Fury

- supersedes: ADR-XXX

- ---

+ This skill uses **micro-file architecture**:

- # ADR-007: {{slug}}

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

- ## Context

- {{2–4 sentences: what forced the decision, what constraint is binding.}}

+ ## On activation

- ## Options

- 1. {{Option A}} — pros / cons / cost

- 2. {{Option B}} — pros / cons / cost

- 3. {{Option C}} — pros / cons / cost

+ 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`.

- ## 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`.