@njeybe/nativ 2.5.1 → 2.7.0

package/templates/dot-ai/api_contracts.json

@@ -1,66 +1,66 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "version": "1.0.0",
-  "projectName": "{{PROJECT_NAME}}",
-  "updatedAt": "{{TIMESTAMP}}",
-  "baseUrl": "/api/v1",
-  "authScheme": "Bearer JWT",
-  "endpoints": [
-    {
-      "id": "health-check",
-      "path": "/health",
-      "method": "GET",
-      "description": "System health and runtime status check",
-      "auth": false,
-      "request": {
-        "headers": {},
-        "queryParams": {},
-        "pathParams": {},
-        "body": null
-      },
-      "responses": {
-        "200": {
-          "description": "System is healthy and operational",
-          "body": {
-            "status": "ok",
-            "uptime": "number",
-            "timestamp": "string"
-          }
-        }
-      }
-    },
-    {
-      "id": "example-entity-list",
-      "path": "/entities",
-      "method": "GET",
-      "description": "Demonstration collection endpoint. The architect updates this during Phase 1 API design.",
-      "auth": true,
-      "request": {
-        "headers": {
-          "Authorization": "Bearer <token>"
-        },
-        "queryParams": {
-          "limit": "integer (optional, default 20)",
-          "offset": "integer (optional, default 0)"
-        },
-        "pathParams": {},
-        "body": null
-      },
-      "responses": {
-        "200": {
-          "description": "List of entities matching query filter",
-          "body": {
-            "data": "array of example_entity",
-            "total": "integer"
-          }
-        },
-        "401": {
-          "description": "Unauthorized access missing or invalid token",
-          "body": {
-            "error": "Unauthorized"
-          }
-        }
-      }
-    }
-  ]
-}
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "version": "1.0.0",
+  "projectName": "{{PROJECT_NAME}}",
+  "updatedAt": "{{TIMESTAMP}}",
+  "baseUrl": "/api/v1",
+  "authScheme": "Bearer JWT",
+  "endpoints": [
+    {
+      "id": "health-check",
+      "path": "/health",
+      "method": "GET",
+      "description": "System health and runtime status check",
+      "auth": false,
+      "request": {
+        "headers": {},
+        "queryParams": {},
+        "pathParams": {},
+        "body": null
+      },
+      "responses": {
+        "200": {
+          "description": "System is healthy and operational",
+          "body": {
+            "status": "ok",
+            "uptime": "number",
+            "timestamp": "string"
+          }
+        }
+      }
+    },
+    {
+      "id": "example-entity-list",
+      "path": "/entities",
+      "method": "GET",
+      "description": "Demonstration collection endpoint. The architect updates this during Phase 1 API design.",
+      "auth": true,
+      "request": {
+        "headers": {
+          "Authorization": "Bearer <token>"
+        },
+        "queryParams": {
+          "limit": "integer (optional, default 20)",
+          "offset": "integer (optional, default 0)"
+        },
+        "pathParams": {},
+        "body": null
+      },
+      "responses": {
+        "200": {
+          "description": "List of entities matching query filter",
+          "body": {
+            "data": "array of example_entity",
+            "total": "integer"
+          }
+        },
+        "401": {
+          "description": "Unauthorized access missing or invalid token",
+          "body": {
+            "error": "Unauthorized"
+          }
+        }
+      }
+    }
+  ]
+}

package/templates/dot-ai/context.md

@@ -1,38 +1,38 @@
-# Project Context & Guardrails
-
-## 1. System Overview & Repository Profile
-- **Project Name:** {{PROJECT_NAME}}
-- **Repository Type:** {{REPOSITORY_TYPE}}
-- **Workspace Topology:** {{WORKSPACE_TOPOLOGY}}
-- **Primary Goal:** {{PROJECT_GOAL}}
-
-## 2. Technology Stack & Ecosystem Manifests
-- **Language / Runtime:** {{DETECTED_RUNTIME}}
-- **Framework:** {{DETECTED_FRAMEWORK}}
-- **Database / ORM:** {{DETECTED_DATABASE_ORM}}
-- **ORM / Migration Config:** {{DETECTED_ORM_CONFIG}}
-- **Styling / UI Library:** {{DETECTED_STYLING}}
-- **Testing Framework:** {{DETECTED_TESTING}}
-- **Package Manager:** {{DETECTED_PACKAGE_MANAGER}}
-- **Discovered Manifests:** {{ECOSYSTEM_MANIFESTS}}
-
-## 3. Architecture & Codebase Layout
-- **Source Root:** `{{SOURCE_ROOT}}`
-- **Core Pattern:** {{ARCHITECTURE_PATTERN}}
-- **Key Directories:**
-{{KEY_DIRECTORIES}}
-
-## 4. Engineering Guardrails & Constraints
-1. **Strict Role Pipeline (provider-agnostic):** Architect (designs contracts and resolves escalations) -> Project Manager (orchestrates the task loop) -> Workers (specialized sub-agents) -> Verifier (independent checks). Roles are fixed; the model or vendor behind a role is configurable. Claude Code is the default host for every role, and other agents can be plugged in.
-2. **Zero Breaking Changes:** Avoid breaking existing public interfaces, CLI options, or database contracts without explicit migration strategies.
-3. **Schema Authority:** Database modifications must strictly align with `.ai/db_schema.json`.
-4. **UI Fidelity:** User interface components must strictly match `.ai/ui_specs.md`.
-5. **Secrets & Security:** Never hardcode API keys, passwords, or tokens. Use environment variables. Validate all external inputs.
-6. **Testing Requirement:** Every newly introduced endpoint, service, or complex component must include automated tests before marking tasks completed in `.ai/master_plan.json`.
-
-## 5. Execution Boundaries (Sub-Agent Allocation)
-- **`backend`:** Core services, CLI logic, APIs, server runtime code, and route handlers.
-- **`frontend`:** Web application views, client components, or terminal UI presentation.
-- **`database`:** Schema definitions, ORM models, migrations, and seed scripts matching `.ai/db_schema.json`.
-- **`qa-tester`:** Unit tests, integration tests, and verification scripts.
-- **Specialized Units:** `flutter-developer`, `devops-agent`, `security-auditor`, `db-migration` when required.
+# Project Context & Guardrails
+
+## 1. System Overview & Repository Profile
+- **Project Name:** {{PROJECT_NAME}}
+- **Repository Type:** {{REPOSITORY_TYPE}}
+- **Workspace Topology:** {{WORKSPACE_TOPOLOGY}}
+- **Primary Goal:** {{PROJECT_GOAL}}
+
+## 2. Technology Stack & Ecosystem Manifests
+- **Language / Runtime:** {{DETECTED_RUNTIME}}
+- **Framework:** {{DETECTED_FRAMEWORK}}
+- **Database / ORM:** {{DETECTED_DATABASE_ORM}}
+- **ORM / Migration Config:** {{DETECTED_ORM_CONFIG}}
+- **Styling / UI Library:** {{DETECTED_STYLING}}
+- **Testing Framework:** {{DETECTED_TESTING}}
+- **Package Manager:** {{DETECTED_PACKAGE_MANAGER}}
+- **Discovered Manifests:** {{ECOSYSTEM_MANIFESTS}}
+
+## 3. Architecture & Codebase Layout
+- **Source Root:** `{{SOURCE_ROOT}}`
+- **Core Pattern:** {{ARCHITECTURE_PATTERN}}
+- **Key Directories:**
+{{KEY_DIRECTORIES}}
+
+## 4. Engineering Guardrails & Constraints
+1. **Strict Role Pipeline (provider-agnostic):** Architect (designs contracts and resolves escalations) -> Project Manager (orchestrates the task loop) -> Workers (specialized sub-agents) -> Verifier (independent checks). Roles are fixed; the model or vendor behind a role is configurable. Claude Code is the default host for every role, and other agents can be plugged in.
+2. **Zero Breaking Changes:** Avoid breaking existing public interfaces, CLI options, or database contracts without explicit migration strategies.
+3. **Schema Authority:** Database modifications must strictly align with `.ai/db_schema.json`.
+4. **UI Fidelity:** User interface components must strictly match `.ai/ui_specs.md`.
+5. **Secrets & Security:** Never hardcode API keys, passwords, or tokens. Use environment variables. Validate all external inputs.
+6. **Testing Requirement:** Every newly introduced endpoint, service, or complex component must include automated tests before marking tasks completed in `.ai/master_plan.json`.
+
+## 5. Execution Boundaries (Sub-Agent Allocation)
+- **`backend`:** Core services, CLI logic, APIs, server runtime code, and route handlers.
+- **`frontend`:** Web application views, client components, or terminal UI presentation.
+- **`database`:** Schema definitions, ORM models, migrations, and seed scripts matching `.ai/db_schema.json`.
+- **`qa-tester`:** Unit tests, integration tests, and verification scripts.
+- **Specialized Units:** `flutter-developer`, `devops-agent`, `security-auditor`, `db-migration` when required.

package/templates/dot-ai/db_schema.json

@@ -1,39 +1,39 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "version": "1.0.0",
-  "projectName": "{{PROJECT_NAME}}",
-  "updatedAt": "{{TIMESTAMP}}",
-  "engine": "{{DETECTED_DATABASE_ENGINE}}",
-  "tables": [
-    {
-      "name": "example_entity",
-      "description": "Demonstration table definition. The architect updates this during Phase 1A.",
-      "columns": [
-        {
-          "name": "id",
-          "type": "UUID",
-          "primaryKey": true,
-          "nullable": false,
-          "default": "gen_random_uuid()"
-        },
-        {
-          "name": "created_at",
-          "type": "TIMESTAMP",
-          "primaryKey": false,
-          "nullable": false,
-          "default": "NOW()"
-        },
-        {
-          "name": "updated_at",
-          "type": "TIMESTAMP",
-          "primaryKey": false,
-          "nullable": false,
-          "default": "NOW()"
-        }
-      ],
-      "indexes": [],
-      "foreignKeys": []
-    }
-  ],
-  "migrations": []
-}
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "version": "1.0.0",
+  "projectName": "{{PROJECT_NAME}}",
+  "updatedAt": "{{TIMESTAMP}}",
+  "engine": "{{DETECTED_DATABASE_ENGINE}}",
+  "tables": [
+    {
+      "name": "example_entity",
+      "description": "Demonstration table definition. The architect updates this during Phase 1A.",
+      "columns": [
+        {
+          "name": "id",
+          "type": "UUID",
+          "primaryKey": true,
+          "nullable": false,
+          "default": "gen_random_uuid()"
+        },
+        {
+          "name": "created_at",
+          "type": "TIMESTAMP",
+          "primaryKey": false,
+          "nullable": false,
+          "default": "NOW()"
+        },
+        {
+          "name": "updated_at",
+          "type": "TIMESTAMP",
+          "primaryKey": false,
+          "nullable": false,
+          "default": "NOW()"
+        }
+      ],
+      "indexes": [],
+      "foreignKeys": []
+    }
+  ],
+  "migrations": []
+}

package/templates/dot-ai/subagents/architect.md

@@ -16,6 +16,12 @@ You are the **Architect**. You design; you do not build. Turn a feature request
 4. **API contracts.** Propose endpoints, methods, parameters, request and response shapes, and auth.
 5. **UI and UX.** Work in this order:
    - Pick Quick, Standard or Full planning level (the human can override).
+   - Design Profile: fill that section of `.ai/ui_specs.md` before wireframes.
+     - Pick the profile with a one-line reason: `taste-v2` for sites, portfolios, redesigns; `taste-v1` for apps, dashboards; native mobile or terminal UI: no profile, leave the placeholder and say so.
+     - Read `package.json` for Stack notes.
+     - Web: always write the design read, the dials (taste-v2 section 1.B presets first), the design system and the redesign mode.
+     - Make Design Tokens obey `.ai/design/taste/v1/DIGEST.md` or `.ai/design/taste/v2/DIGEST.md`.
+     - STOP for approval together with the UI step.
    - Ask at most 5 discovery questions, only ones that change the design.
    - Check what can be reused (components, theme, icon set) before inventing.
    - Content first: the top 3 to 5 user tasks with frequency, and real sample data per screen.

package/templates/dot-ai/subagents/flutter-developer.md

@@ -54,16 +54,7 @@ Do not invent the layout.
 - Respect safe areas (notch, home bar) and the keyboard. A focused field stays visible.
 - Check small phones, large phones and tablets, in both orientations where the spec allows.
 
-## 7. Anti-generic rules
-These match the Anti-Generic Checklist in `.ai/ui_specs.md`:
-- No default Material seed blue, and no unthemed default widgets, without a reason.
-- No default type without a reason. Use the fonts in the style tile.
-- No rows of identical cards with pastel icon boxes.
-- No gradient-text hero and no decorative blobs.
-- No greeting banners ("Welcome back!"). Let the content speak.
-- No emojis anywhere in code or UI. Use icons from the icon set the spec names.
-
-## 8. States and access
+## 7. States and access
 - Loading: a skeleton with the same size as the loaded content, so nothing jumps.
 - Empty: a short explanation and a primary action.
 - Error: a plain-language cause and a Retry button, never a raw error dump.
@@ -77,7 +68,7 @@ These match the Anti-Generic Checklist in `.ai/ui_specs.md`:
 - Mutations: disable the submit while it runs and show progress next to it.
   On failure, roll back and show the error message from the spec with a Retry.
 
-## 9. Before you finish
+## 8. Before you finish
 1. Run the task's `verificationCommand`, plus `flutter analyze` and `flutter test`.
 2. Check the source for emojis. There must be none.
 3. Check the UI has no overflow stripes on small and large screens.

package/templates/dot-ai/subagents/frontend.md

@@ -18,6 +18,48 @@ settle it, escalate with `architectural_ambiguity`. Do not guess a direction.
 For Quick work, work with no screen, or a project with no design brief, match the existing
 components and `.ai/codebase_map.md` instead.
 
+## 2.6 Design profiles
+Read `## Design Profile` in `.ai/ui_specs.md` first.
+If the Profile is missing or still the placeholder, stop and escalate with
+`architectural_ambiguity` before writing UI code.
+
+Profiles are `taste-v1` or `taste-v2`. Read the digest at
+`.ai/design/taste/<v1|v2>/DIGEST.md`. Open `SKILL.md` beside it only for a
+section the digest points to.
+
+Order of authority, highest first:
+1. The task's `acceptanceCriteria`.
+2. `.ai/ui_specs.md` (tokens, wireframes, copy).
+3. The digest.
+4. `SKILL.md`.
+
+The settled conflicts below override the digest and `SKILL.md`. The digest is a faithful copy
+of upstream, so it may say things nativ overrides, such as "generate images first".
+1. Questions: never ask the user. Escalate with `architectural_ambiguity`.
+2. The design read and dials are set in the Design Profile. Do not change them. If values
+   are missing, that is a spec gap: escalate.
+3. Dependencies: a library the profile needs that is not in `package.json` is installed only
+   when `package.json` is in your targetFiles. Otherwise escalate with `dependency_conflict`.
+   Never import a package that is not installed.
+4. Icons: use the icon library named in Stack notes. Do not hand-draw SVG icons.
+5. Images: the spec decides imagery. Never call image generation yourself. Leave a labeled
+   placeholder and list the missing images in your report.
+6. Colors and fonts come from the Design Tokens. A token that breaks a profile rule is a
+   spec gap: escalate, do not fix it in code.
+7. Emojis are banned under every profile. Only the spec can allow them.
+8. Under `taste-v2`, no em dash or en dash as a separator in any text users see. Use a
+   hyphen or rewrite the sentence.
+9. Run Lighthouse and Core Web Vitals only when the task's `verificationCommand` does.
+
+Stack notes:
+- React 18: `motion` (from `motion/react`) and `framer-motion` share one API and work on
+  React 18 and 19. Keep the one installed. Do not migrate packages in a feature task.
+- Server Component rules apply only when Stack notes say Next.js App Router. In a
+  client-only React app skip them, but keep motion in small memoized leaf components.
+- Tailwind: follow the installed major version. Never mix v3 and v4 syntax.
+- `next/font` is for Next.js only. Elsewhere self-host fonts with `@font-face` and
+  `font-display: swap`.
+
 ## 3. Build from the design
 `.ai/ui_specs.md` is the source of truth. Use these parts of it:
 - **Design brief and chosen direction:** who uses it, the tone, what to avoid.
@@ -51,46 +93,7 @@ Do not invent the layout.
 - Check wide screens: do not stretch text or forms edge to edge.
 - Dialogs and drawers close with `Escape` and a backdrop click, and keep focus inside.
 
-## 6. Visual style (compressed)
-Follow the style the spec chose. If it names a known style, use these anchors:
-- **Minimalist:** hairline borders, very soft shadows, tight 4px/8px spacing, tabular numbers.
-- **Neo-brutalist:** thick solid borders, hard offset shadows with no blur, uppercase labels.
-- **Glass:** translucent surfaces with backdrop blur, thin light border, soft deep shadow.
-- **Bento:** grid of cards with uneven spans, one corner radius everywhere.
-- **Soft UI / clay:** surface matches the background, paired light and dark shadows,
-  puffy radii.
-- **Skeuomorphic / spatial / maximalist:** physical cues, layered depth, or bold color layers,
-  always through the tokens.
-
-Values come from the tokens and the style tile, never from this list.
-
-## 7. Anti-generic rules
-These match the Anti-Generic Checklist in `.ai/ui_specs.md`:
-- No default Inter or system-only type without a reason.
-- No default indigo or purple accent.
-- No rows of identical cards with pastel icon boxes.
-- No gradient-text hero and no decorative blobs.
-- No greeting banners ("Welcome back!"). Let the content speak.
-- No emojis anywhere in code or UI. Icons are inline vector SVG.
-
-### 7.1 Build-time details
-The font, color and layout choices are made at design time (the Anti-Generic Checklist in
-`.ai/ui_specs.md`). These are the details that go wrong while building:
-- One accent color and one corner-radius scale, from the tokens, on every component.
-  A button or link that needs a different color is a spec gap: escalate it.
-- Large display type with tight line height clips the tails of y, g, j, p and q, worst in
-  italics. Keep display line height at 1.1 or more.
-- Images come from the spec. If one is missing, leave a clearly labeled placeholder and
-  list the images still needed in your report. Never fake a product screenshot out of
-  boxes, and never fill space with hand-drawn illustrations.
-- Logos are real vector files, never a company name typed out as text.
-- Numbers shown in the UI come from the spec's content samples or real data. Do not
-  invent precise-looking figures such as "92%" or "4.1x".
-- One label per action: if the spec says "Contact us", do not add "Get in touch" elsewhere.
-- Marketing or landing page: also follow the Marketing pages part of the checklist, when
-  `.ai/ui_specs.md` has one.
-
-## 8. States and access
+## 6. States and access
 - Loading: a skeleton with the same size as the loaded content, so nothing jumps.
 - Empty: a short explanation and a primary action.
 - Error: a plain-language cause and a Retry button, never a raw error dump.
@@ -101,7 +104,7 @@ The font, color and layout choices are made at design time (the Anti-Generic Che
 - Mutations: disable the submit while it runs and show progress next to it.
   On failure, roll back and show the error message from the spec with a Retry.
 
-## 9. Before you finish
+## 7. Before you finish
 1. Run the task's `verificationCommand` (or `nativ verify <taskId>`).
 2. Check the source for emojis. There must be none.
 3. Check the UI has no sideways scrolling or clipping on phone, tablet and desktop widths.
@@ -109,8 +112,8 @@ The font, color and layout choices are made at design time (the Anti-Generic Che
 5. Pre-flight, all must pass:
    - Button labels, inputs, placeholders and form labels meet contrast: 4.5:1 for body
      text, 3:1 for large text.
-   - Button labels fit on one line at desktop width.
-   - The accent color and corner radius are the same everywhere.
    - Re-read every string you wrote that the spec did not give. Rewrite anything vague,
      broken or invented.
-   - Marketing or landing page: run the Marketing pages checks, when the checklist has them.
+6. Run the Pre-flight in the profile's DIGEST.md.
+7. Run `nativ design check <your UI files or folders>`. Fix every error. Fix each warning, or
+   explain it in your report. It reads the Design Profile in `.ai/ui_specs.md`.

package/templates/dot-ai/ui_specs.md

@@ -18,6 +18,21 @@ Pick one level and design track and write them here:
 
 ---
 
+## Design Profile
+The Architect picks one profile per project. Workers read the digest named here.
+Native mobile and terminal UI projects leave the placeholder.
+- **Profile:** taste-v1 | taste-v2
+- **Digest:** .ai/design/taste/<v1|v2>/DIGEST.md
+- **Design read:** Reading this as: <page kind> for <audience>, with a <vibe> language,
+  leaning toward <design system or aesthetic>.
+- **Dials:** DESIGN_VARIANCE <1-10> / MOTION_INTENSITY <1-10> / VISUAL_DENSITY <1-10>, and why
+- **Design system:** <official package from taste-v2 section 2.A, or "none: Tailwind and tokens">
+- **Stack notes:** React <major>, Next.js App Router yes/no, Tailwind <major>,
+  motion package <motion | framer-motion | none>, icon library <name>
+- **Redesign mode (taste-v2):** Greenfield | Preserve | Overhaul
+
+---
+
 ## Design Brief
 - **Who uses it:**
 - **The job they are doing:**
@@ -174,40 +189,6 @@ One or two. Everything else stays restrained.
 
 ---
 
-## Anti-Generic Checklist
-**Web**
-- [ ] No unconsidered font defaults. Consumer/brand: distinct curated typeface (e.g. Outfit, Plus Jakarta Sans, DM Sans). Data-dense B2B SaaS/utility: Inter, Roboto, or native system type permitted for density and zero-FOIT. No unstyled browser defaults without a reason.
-- [ ] No default indigo/purple accent.
-- [ ] No rows of identical cards with pastel icon boxes.
-- [ ] No gradient-text hero.
-- [ ] No decorative blobs.
-- [ ] No greeting banners.
-- [ ] No emojis. Icons are vector SVG.
-- [ ] No serif by default. A serif needs a stated reason (editorial, heritage) in the brief.
-- [ ] One font family, unless the tokens define a heading and body pairing.
-- [ ] No purple or blue glow gradients and no neon mesh backgrounds unless the brief asks.
-- [ ] No warm beige with brass accents as the automatic "premium" look. Pick it only on purpose.
-- [ ] One accent color and one palette temperature (warm or cool grays, not both).
-- [ ] One corner-radius scale for every surface.
-
-**Marketing pages** (landing, product and pricing pages)
-- [ ] The hero fits the first screen: headline of at most 2 lines, subtext of about 20 words, the main button visible without scrolling.
-- [ ] The hero holds at most 4 things: an optional small label, headline, subtext, buttons (one primary, at most one secondary). Logo walls go in their own section below.
-- [ ] No more than 2 image-and-text split sections in a row.
-- [ ] Small uppercase labels above headings: at most one for every 3 sections.
-- [ ] Each section layout (3-column cards, split, bento) appears once per page.
-- [ ] Real images and real vector logos. No mock screenshots built from boxes, no text-only page.
-- [ ] Sections stay short: a headline of about 8 words, about 25 words of text, one visual or one button. More than 5 items need a grid, tabs or a carousel.
-- [ ] Every figure comes from real data or is marked as a sample.
-- [ ] One label per action across the page ("Contact us" everywhere, not three variants).
-
-**Mobile**
-- [ ] No default Material seed blue.
-- [ ] No unthemed default widgets without a reason.
-- [ ] No emojis.
-
----
-
 ## States
 Every component and view covers these.
 
@@ -224,8 +205,6 @@ Every component and view covers these.
 ---
 
 ## Accessibility
-- **Transitions:** `transition: all 150ms cubic-bezier(0.4, 0, 0.2, 1);`
-- **Active state:** `transform: scale(0.98)`.
 - **Focus rings:** `:focus-visible { outline: 2px solid var(--brand); outline-offset: 2px; }`
 - **Dialogs and drawers:** close with `Escape` and backdrop click; lock background scroll.
 - **Labels:** `aria-label` on every icon-only button.