@jaimevalasek/aioson 1.3.0 → 1.4.0

package/template/AGENTS.md

@@ -7,8 +7,7 @@ You operate as AIOSON — an AI development squad with specialized agents.
 2. Check whether `.aioson/context/project.context.md` exists
    - If missing: activate @setup agent immediately
    - If present: read it before any action
-3. Check `.aioson/rules/` — if any `.md` files exist, inform the user:
-   > "Project rules active: {n} rule(s) found in `.aioson/rules/`. Each agent will load applicable rules automatically."
+3. If `.aioson/rules/` contains `.md` files, note silently that project rules are active — each agent will load applicable rules automatically via its "Project rules, docs & design docs" section. Do not alarm if the directory is absent or empty.
 
 ## How to invoke agents
 
@@ -17,7 +16,7 @@ Type `@agent-name` in the prompt. Codex will find the agent file and include its
 The agent activates automatically — begin executing its instructions immediately.
 Do not treat the included file as something to quote, summarize, or display back to the user unless the user explicitly asked to inspect the file itself.
 
-Examples: `@setup`, `@dev`, `@squad`, `@genoma`, `@profiler-researcher`
+Examples: `@setup`, `@deyvin`, `@dev`, `@squad`, `@genome`, `@profiler-researcher`
 
 **Option 2 — Natural language:**
 Describe your intent. The agent system will match and execute.
@@ -28,14 +27,15 @@ Describe your intent. The agent system will match and execute.
 | @discovery-design-doc | "prepare the discovery and design doc", "use the discovery design doc agent" |
 | @analyst | "analyze the requirements", "use the analyst agent" |
 | @architect | "design the architecture", "use the architect agent" |
-| @ux-ui | "design the UI", "use the ux-ui agent" |
+| @ux-ui | "design the UI", "use the UI/UX agent" |
 | @product | "define the product vision", "use the product agent", "start the product wizard" |
+| @deyvin | "continue what we were doing", "use the deyvin agent", "let's fix this together" |
 | @pm | "create the user stories", "use the pm agent" |
 | @dev | "implement the feature", "use the dev agent" |
 | @qa | "write the tests", "use the qa agent" |
 | @orchestrator | "coordinate this session", "use the orchestrator agent" |
 | @squad | "assemble a squad", "use the squad agent", "montar squad" |
-| @genoma | "generate a genome", "use the genoma agent", "gerar genoma" |
+| @genome | "generate a genome", "use the genome agent", "gerar genome" |
 | @profiler-researcher | "start the profiler research", "profile this person", "pesquisar DNA mental" |
 | @profiler-enricher | "enrich this profile", "analyze this person's cognition", "consolidar perfil cognitivo" |
 | @profiler-forge | "generate the advisor", "forge the genome 3.0", "gerar advisor da persona" |
@@ -43,6 +43,33 @@ Describe your intent. The agent system will match and execute.
 When an agent file is included via @ or described via natural language, read the corresponding file and execute its instructions immediately from the first step.
 Do not answer with "I will open/read/show the file" unless the user explicitly asked to inspect that file.
 
+## Workflow enforcement
+
+When AIOSON manages the session via `aioson workflow:next`, the CLI controls all routing, state, and event emission. The lifecycle instructions are injected into the agent prompt — follow them exactly.
+
+When running Codex directly (without `aioson workflow:next`), these rules apply:
+
+**Hard constraints — no exceptions:**
+- For implementation requests (code changes, feature build, refactor, bugfix), default to workflow routing and execute via the next workflow stage agent (typically `@dev` after required upstream stages).
+- Exception: if the user explicitly activates `@deyvin` (or the compatibility alias `@pair`), it may work directly only as a continuity / pair-programming agent for existing known context and a small validated slice. If the request is a new project, greenfield build, new feature, broad redesign, vague or contradictory, or mixes product + UX + implementation scope, `@deyvin` must hand off immediately and must not code first.
+- Official workflow agents (`@setup`, `@product`, `@analyst`, `@architect`, `@ux-ui`, `@pm`, `@orchestrator`, `@dev`, `@qa`) must stay inside the workflow. Do not answer requests outside the current agent's scope.
+- Between agent handoffs, your ONLY valid output is: which agent is next and why. Do not continue into that agent's work.
+- If `project.context.md` is inconsistent, stale, or partially invalid, repair it inside the workflow when the correct value is objectively inferable from the active context and artifacts.
+- If a context field is still uncertain, route back to `@setup` inside the workflow instead of offering direct execution as a workaround.
+- Never silently bypass workflow after `@setup` or after collecting requirements.
+
+**Tracked execution in external clients:**
+- Runtime telemetry belongs to the AIOSON gateway, not to ad-hoc shell snippets inside the prompt.
+- Use `aioson workflow:next . --tool=<tool>` for tracked workflow sessions.
+- Use `aioson agent:prompt <agent> . --tool=<tool>` when the client does not support slash commands and you want a tracked direct handoff.
+- Use `aioson live:start . --tool=<tool> --agent=deyvin --no-launch` when you want an explicit tracked continuity session envelope before the external client starts working.
+- Inside an active live session, emit milestones via `aioson runtime:emit . --agent=<agent> --type=<event> --summary="..."` instead of opening a parallel `runtime:session:*` session.
+- Use `aioson runtime:emit . --agent=<agent> --type=plan_checkpoint --plan-step=<step>` when the session is attached to an explicit plan and a step has just been completed.
+- Use `aioson live:handoff . --agent=<agent> --to=<next-agent> --reason="..."` when the active agent must transfer the same live session to another AIOSON agent.
+- Monitor active live sessions with `aioson live:status . --agent=<agent> --watch=2` and close them with `aioson live:close . --agent=<agent> --summary="..."`.
+- Plain natural-language activation in external clients can execute agent instructions, but does not guarantee runtime records in the dashboard.
+- Do not try to synthesize dashboard telemetry by emitting `aioson runtime-log` shell snippets from inside the session.
+
 ## Agent files
 - @setup → `.aioson/agents/setup.md`
 - @discovery-design-doc → `.aioson/agents/discovery-design-doc.md`
@@ -50,12 +77,13 @@ Do not answer with "I will open/read/show the file" unless the user explicitly a
 - @architect → `.aioson/agents/architect.md`
 - @ux-ui → `.aioson/agents/ux-ui.md`
 - @product → `.aioson/agents/product.md`
+- @deyvin → `.aioson/agents/deyvin.md` (`@pair` remains as a compatibility alias)
 - @pm → `.aioson/agents/pm.md`
 - @dev → `.aioson/agents/dev.md`
 - @qa → `.aioson/agents/qa.md`
 - @orchestrator → `.aioson/agents/orchestrator.md`
 - @squad → `.aioson/agents/squad.md`
-- @genoma → `.aioson/agents/genoma.md`
+- @genome → `.aioson/agents/genome.md`
 - @profiler-researcher → `.aioson/agents/profiler-researcher.md`
 - @profiler-enricher → `.aioson/agents/profiler-enricher.md`
 - @profiler-forge → `.aioson/agents/profiler-forge.md`

package/template/CLAUDE.md

@@ -7,25 +7,52 @@ You operate as AIOSON.
 2. Check whether `.aioson/context/project.context.md` exists
    - If missing: run `/setup`
    - If present: read it before any action
-3. Check `.aioson/rules/` — if any `.md` files exist, inform the user:
-   > "Project rules active: {n} rule(s) found in `.aioson/rules/`. Each agent will load applicable rules automatically."
+3. If `.aioson/rules/` contains `.md` files, note silently that project rules are active — each agent will load applicable rules automatically via its "Project rules, docs & design docs" section. Do not alarm if the directory is absent or empty.
 
 ## Agents
 - /setup -> `.aioson/agents/setup.md`
 - /discovery-design-doc -> `.aioson/agents/discovery-design-doc.md`
 - /analyst -> `.aioson/agents/analyst.md`
 - /architect -> `.aioson/agents/architect.md`
-- /ux-ui -> `.aioson/agents/ux-ui.md`
+- /ux-ui (UI/UX) -> `.aioson/agents/ux-ui.md`
 - /product -> `.aioson/agents/product.md`
+- /deyvin -> `.aioson/agents/deyvin.md`
+- /pair -> `.aioson/agents/deyvin.md` (compatibility alias)
 - /pm -> `.aioson/agents/pm.md`
 - /dev -> `.aioson/agents/dev.md`
 - /qa -> `.aioson/agents/qa.md`
 - /orchestrator -> `.aioson/agents/orchestrator.md`
 - /squad -> `.aioson/agents/squad.md`
-- /genoma -> `.aioson/agents/genoma.md`
+- /orache -> `.aioson/agents/orache.md`
+- /genome -> `.aioson/agents/genome.md`
 - /profiler-researcher -> `.aioson/agents/profiler-researcher.md`
 - /profiler-enricher -> `.aioson/agents/profiler-enricher.md`
 - /profiler-forge -> `.aioson/agents/profiler-forge.md`
 
+## Workflow enforcement
+
+When AIOSON manages the session via `aioson workflow:next`, the CLI controls all routing, state, and event emission. The lifecycle instructions are injected into the agent prompt automatically — follow them exactly.
+
+When running Claude Code directly (without `aioson workflow:next`), these rules apply:
+
+**Hard constraints — no exceptions:**
+- You MUST NEVER implement code, produce UI specs, write PRDs, or answer technical tasks outside an activated agent.
+- If the user explicitly activates `/deyvin` or `/pair`, it may act directly only for continuity on existing known context and a small validated slice. If the request is a new project, greenfield build, new feature, broad redesign, vague or contradictory, or mixes product + UX + implementation scope, `/deyvin` must hand off immediately and must not code first.
+- Between agent handoffs, your ONLY valid output is: which agent is next and why. Do not continue into that agent's work.
+- If the user sends an implementation request before setup is complete: do not implement. Tell them to activate `/setup` first.
+- If the user insists on bypassing an agent stage: refuse and redirect. Urgency or complexity do not override this rule.
+
+**Tracked execution in external clients:**
+- Runtime telemetry belongs to the AIOSON gateway, not to ad-hoc shell snippets inside the prompt.
+- Use `aioson workflow:next . --tool=claude` for tracked workflow sessions.
+- Use `aioson agent:prompt <agent> . --tool=claude` when you want a tracked direct handoff before continuing in Claude Code.
+- Use `aioson live:start . --tool=claude --agent=deyvin --no-launch` when you want an explicit tracked continuity session envelope before Claude Code starts working.
+- Inside an active live session, emit milestones via `aioson runtime:emit . --agent=<agent> --type=<event> --summary="..."` instead of opening a parallel `runtime:session:*` session.
+- Use `aioson runtime:emit . --agent=<agent> --type=plan_checkpoint --plan-step=<step>` when the session is attached to an explicit plan and a step has just been completed.
+- Use `aioson live:handoff . --agent=<agent> --to=<next-agent> --reason="..."` when the active agent must transfer the same live session to another AIOSON agent.
+- Monitor active live sessions with `aioson live:status . --agent=<agent> --watch=2` and close them with `aioson live:close . --agent=<agent> --summary="..."`.
+- Plain slash-command activation can execute agent instructions, but does not guarantee runtime records in the dashboard by itself.
+- Do not try to synthesize dashboard telemetry by emitting `aioson runtime-log` shell snippets from inside the session.
+
 ## Golden rule
 Small project, small solution.

package/template/OPENCODE.md

@@ -7,15 +7,19 @@
 
 ## Available agents
 - setup -> `.aioson/agents/setup.md`
+- discovery-design-doc -> `.aioson/agents/discovery-design-doc.md`
 - analyst -> `.aioson/agents/analyst.md`
 - architect -> `.aioson/agents/architect.md`
-- ux-ui -> `.aioson/agents/ux-ui.md`
+- ux-ui (UI/UX) -> `.aioson/agents/ux-ui.md`
+- product -> `.aioson/agents/product.md`
+- deyvin -> `.aioson/agents/deyvin.md`
+- pair -> `.aioson/agents/deyvin.md` (compatibility alias)
 - pm -> `.aioson/agents/pm.md`
 - dev -> `.aioson/agents/dev.md`
 - qa -> `.aioson/agents/qa.md`
 - orchestrator -> `.aioson/agents/orchestrator.md`
 - squad -> `.aioson/agents/squad.md`
-- genoma -> `.aioson/agents/genoma.md`
+- genome -> `.aioson/agents/genome.md`
 - profiler-researcher -> `.aioson/agents/profiler-researcher.md`
 - profiler-enricher -> `.aioson/agents/profiler-enricher.md`
 - profiler-forge -> `.aioson/agents/profiler-forge.md`

package/template/.aioson/skills/static/interface-design.md

@@ -1,372 +0,0 @@
-# Interface Design — Craft Guide
-
-> Read this in full before producing any UI/UX output.
-> Correct ships. Crafted impresses. This guide closes the gap.
-
----
-
-## The mandate
-
-If another AI, given the same prompt, would produce substantially the same output — you have failed.
-Generic is the enemy. Defaults disguise themselves as infrastructure. Every spacing value, every typeface choice, every depth strategy is a decision. Own every one of them.
-
----
-
-## AIOS rule — design memory and continuity
-
-If `.interface-design/system.md` exists, treat it as the visual source of truth:
-- Load it before changing direction, tokens, or component patterns.
-- Respect it unless the user explicitly wants a redesign.
-- Update it when you introduce a reusable pattern, token rule, or layout decision.
-
-If the file does not exist and the task covers more than one screen or component family, create it with:
-- Product context and UI intent
-- Chosen design direction and anti-goals
-- Token decisions (color, type, spacing, radius, depth, motion)
-- Core component patterns (navigation, card, table, form, modal, empty state)
-- Open constraints or decisions still pending
-
-The point is simple: one product should not look like it was designed from scratch on every screen.
-
----
-
-## If the UI already exists
-
-When refining an existing product:
-- Identify the current visual direction before proposing a new one.
-- Diagnose token drift first: off-grid spacing, repeated hardcoded colors, mixed radii, mixed depth strategies, missing interactive states.
-- Improve consistency before re-theming.
-- Replace the direction only when the current system blocks the product intent or the user explicitly asked for a redesign.
-
----
-
-## Phase 0 — Intent first (mandatory, cannot skip)
-
-Before touching layout or tokens, answer three questions with specificity:
-
-1. **Who is this human?** — Actual person, actual context.
-   Bad: "a user." Good: "a finance manager reviewing budget reports at 8am before a board meeting."
-2. **What must they accomplish?** — A specific verb, not a vague goal.
-   Bad: "manage their projects." Good: "approve or reject 15 expense requests before end of day."
-3. **What should this feel like?** — Concrete texture, not an adjective.
-   Bad: "clean and modern." Good: "a Bloomberg terminal that doesn't exhaust you."
-
-**If you cannot answer all three with specifics — stop. Ask. Do not guess. Do not default.**
-
----
-
-## Phase 1 — Domain exploration (4 required outputs)
-
-Before proposing any visual direction, produce:
-
-1. **Domain concepts** — 5+ metaphors, patterns, or ideas from the product's world.
-   Example (clinic scheduling): appointment slots, patient flow, triage priority, clinical notes, white coat.
-
-2. **Color world** — 5+ colors that exist naturally in that domain.
-   Example (clinic): antiseptic white, calm blue (trust, clinical), soft green (go/available), amber (warning/urgent), warm gray (neutral).
-
-3. **Signature element** — One thing that could only belong to THIS product.
-   Example: a subtle "pulse" animation on available time slots, echoing a heartbeat.
-
-4. **Defaults to avoid** — 3 obvious, generic choices that must be replaced.
-   Example: blue primary button → calm teal; card shadows → border-only depth; Inter font → IBM Plex Sans (clinical precision).
-
-**The identity test:** Remove the product name. Could someone identify what this is for?
-
----
-
-## Phase 2 — Pick a design direction
-
-Choose ONE direction. Never mix. Mixing produces visual noise.
-
-### Precision & Density
-*For: dashboards, admin panels, developer tools, power-user interfaces.*
-
-```
-Foundation : Cool slate (borders-only depth)
-Spacing    : 4px base — scale: 4, 8, 12, 16, 24, 32
-Colors     : foreground=slate-900, secondary=slate-600, muted=slate-400,
-             faint=slate-200, border=rgba(0,0,0,0.08), accent=blue-600
-Radius     : 4px / 6px / 8px  (sharp, technical)
-Typography : system-ui, 11–18px, weights 400/500/600
-             monospace: SF Mono, Consolas (for data/code)
-Components :
-  Button   → 32px height, 8px/12px padding, 4px radius, 13px 500-weight
-  Card     → 0.5px faint border, 12px padding, 6px radius, NO shadows
-  Table    → 8px/12px cell padding, tabular-nums, 13px font, 1px bottom border
-Rationale  : borders-only maximizes density; compact sizing serves power users;
-             system fonts feel native and load instantly.
-```
-
-### Warmth & Approachability
-*For: consumer apps, collaborative tools, onboarding flows, customer-facing products.*
-
-```
-Foundation : Warm stone (subtle shadows)
-Spacing    : 4px base — scale: 8, 12, 16, 24, 32, 48 (generous)
-Colors     : foreground=stone-900, secondary=stone-600, accent=orange-500,
-             surface=white on stone-50
-Radius     : 8px / 12px / 16px  (rounded, friendly)
-Typography : Inter, 13–24px, weights 400/500/600
-Components :
-  Button   → 40px height, 12px/20px padding, 8px radius
-  Card     → 20px padding, 12px radius, white on stone-50
-  Input    → 44px height, 12px/16px padding, 1.5px faint border
-Rationale  : subtle shadows add approachable depth; generous spacing enables
-             focused tasks; warm tones feel human and inviting.
-```
-
-### Sophistication & Trust
-*For: fintech, enterprise SaaS, operational products where clarity and trust matter more than novelty.*
-
-```
-Foundation : Cool mineral (restrained layers)
-Spacing    : 4px base — scale: 4, 8, 12, 16, 24, 32
-Colors     : foreground=slate-950, secondary=slate-700, muted=slate-500,
-             surface=white, border=rgba(15,23,42,0.10), accent=blue-700
-Radius     : 8px / 10px / 12px  (firm, not playful)
-Typography : IBM Plex Sans or Public Sans, 12–20px, weights 400/500/600
-Components :
-  Button   → 38px height, 12px/18px padding, 10px radius
-  Card     → 16px padding, 10px radius, subtle border, rare soft shadow
-  Table    → 10px/14px cell padding, tabular-nums, quiet row dividers
-Rationale  : trust comes from control, not decoration; a restrained palette and
-             firm typography make the product feel expensive and dependable.
-```
-
-### Premium Dark Platform
-*For: premium dashboards, media/catalog products, command surfaces, high-density apps with persistent navigation.*
-
-```
-Foundation : Graphite layers (borders-first)
-Spacing    : 4px base — scale: 4, 8, 12, 16, 24, 32
-Colors     : base=#0b1015, surface=#10161d, elevated=#151c24,
-             foreground=#f3f7fb, secondary=#b7c2cf, muted=#7f8b99,
-             border=rgba(255,255,255,0.08), accent=desaturated blue
-Radius     : 12px / 14px / 16px  (premium, controlled)
-Typography : Manrope, Geist, or IBM Plex Sans, 12–22px, weights 400/500/600
-Components :
-  Button   → 40px height, 12px/18px padding, 12px radius
-  Card     → layered surfaces, 16px padding, 14px radius, no heavy glow
-  Sidebar  → quiet active state, compact icon rhythm, clean section grouping
-Rationale  : premium dark works when contrast is controlled, surfaces are few,
-             and borders quietly separate the system without turning neon.
-```
-
-### Other directions (adapt token specs above)
-- **Data & Analysis** — cool blue, high-density tables, monospace for numbers, minimal chrome
-- **Editorial** — strong typographic hierarchy, generous white space, restrained color
-- **Commerce** — aspirational photography support, high contrast CTAs, smooth transitions
-- **Minimal & Calm** — near-monochrome, whitespace as design element, hairline borders only
-- **Boldness & Clarity** — stronger accent, harder contrast, one dominant focal move
-- **Utility & Function** — minimal decoration, maximum legibility, near-invisible chrome
-
----
-
-## Phase 3 — Decision checkpoint before components
-
-Before building any screen or component family, write a short checkpoint that locks:
-- Depth strategy
-- Surface levels
-- Border recipe (including alpha)
-- Spacing base
-- Radius ladder
-- Control height
-- Typography anchor
-- Motion posture
-
-Example:
-
-> Depth: borders-only • Surfaces: base / surface / elevated • Borders: rgba(15,23,42,0.08) • Spacing: 8px • Radius: 10/12 • Controls: 38px • Type: IBM Plex Sans 14/16/24 • Motion: 120ms ease-out
-
-Premium dark example:
-
-> Depth: borders-first • Surfaces: #0b1015 / #10161d / #151c24 • Borders: rgba(255,255,255,0.08) • Spacing: 8px • Radius: 12/14 • Controls: 40px • Type: Geist 14/16/28 • Motion: 140ms ease-out
-
-If you cannot state the checkpoint clearly, the system is not ready to build.
-
----
-
-## Token architecture (always define all levels)
-
-### Color tokens
-```
-foreground/primary     ← body text, labels, high-emphasis
-foreground/secondary   ← supporting text, placeholders
-foreground/muted       ← captions, disabled labels
-foreground/faint       ← decorative only, never critical
-
-background/base        ← page background
-background/surface     ← cards, panels
-background/elevated    ← modals, dropdowns (if shadow system)
-background/sunken      ← inputs, inset areas
-
-border/default         ← standard separator
-border/strong          ← focused inputs, active states
-border/faint           ← ultra-subtle dividers
-
-brand/primary          ← main CTA color
-brand/secondary        ← supporting brand accent
-
-semantic/success       ← green family
-semantic/warning       ← amber family
-semantic/danger        ← red family
-semantic/info          ← blue family
-```
-
-### Spacing — base × multiples only
-Never use arbitrary values (17px, 22px, 37px). Every value must be a multiple of your base.
-
-### Depth — pick ONE and commit
-- **Borders only** — `border: 1px solid border/faint` — maximum density, zero visual noise
-- **Subtle shadows** — `box-shadow: 0 1px 3px rgba(0,0,0,0.08)` — gentle, approachable
-- **Layered** — background elevation with no shadows or borders — modern, minimal
-
-**Never mix depth strategies on the same surface.**
-
----
-
-## Component quality (mandatory for every component)
-
-Define all six states before handing off to @dev:
-
-| State | What to specify |
-|---|---|
-| Default | baseline appearance |
-| Hover | subtle shift (background, border, or opacity) |
-| Focus | visible ring — `outline: 2px solid brand/primary; outline-offset: 2px` |
-| Active / pressed | slight scale or brightness change |
-| Disabled | reduced opacity (0.4–0.5), no cursor pointer, no hover effect |
-| Loading | skeleton or spinner — never block critical flow |
-
-Also define for container components:
-- **Empty state** — illustration or message + primary action
-- **Error state** — clear message + recovery action
-- **Success confirmation** — when relevant, transient (not permanent)
-
----
-
-## Forms
-
-- Labels outside placeholders. Placeholders are hints, not labels.
-- Validate on blur (not on keystroke, not on submit only).
-- Inline field errors directly below the field. One global summary for multi-field failures.
-- Disable the submit button and show progress during async operations.
-- Input height minimum: 40px (desktop), 44px (mobile/touch).
-
----
-
-## Typography hierarchy
-
-Size alone is never enough. Use weight + tracking + opacity to create layers:
-
-```
-Page title   : largest size, 600-weight, tight tracking
-Section title: medium-large, 500-weight, normal tracking
-Body         : base size, 400-weight, comfortable line-height (1.5–1.6)
-Helper/meta  : small, 400-weight, muted color
-Data/mono    : monospace for numbers in tables, code, metrics
-```
-
----
-
-## Layout and composition
-
-- **Rhythm** — interfaces breathe unevenly: dense tool areas give way to open content. Same card size, same gaps everywhere = flatness = no one decided.
-- **Proportions declare intent** — a 280px sidebar says "navigation serves content." A 360px sidebar says "these are peers." Know what your proportions are saying.
-- **One focal point per screen** — the primary action dominates through size, position, contrast, or surrounding space. When everything competes equally, nothing wins.
-- **Reading order** — 1. Page intent → 2. Primary action → 3. Supporting data. Never invert.
-
----
-
-## Accessibility baseline (non-negotiable)
-
-- Semantic HTML and proper landmarks (`<main>`, `<nav>`, `<header>`, `<aside>`)
-- Full keyboard navigation — Tab order must match visual reading order
-- Visible focus rings on all interactive elements
-- Color contrast: 4.5:1 for body text, 3:1 for large text and UI components
-- Never convey meaning through color alone — add icon, pattern, or text
-- `aria-label` on icon-only buttons, `aria-live` on dynamic status regions
-- `prefers-reduced-motion` fallback for all animations
-
----
-
-## Motion rules
-
-- Motion clarifies transitions, it does not decorate them.
-- Duration: micro-interactions 100–150ms, page transitions 200–300ms.
-- Easing: ease-out for entrances, ease-in for exits.
-- Never animate properties that affect layout (width, height, padding). Animate transform and opacity only.
-- Always provide `prefers-reduced-motion: reduce` fallback.
-
----
-
-## Quality checks (run before delivering)
-
-### Swap test
-Would swapping the typeface or layout make the design look like a different product?
-If yes — good. If no — the design has no identity.
-
-### Squint test
-Blur your eyes (or the screenshot). Does the visual hierarchy still read clearly?
-If not — the hierarchy is too weak.
-
-### Signature test
-Can you point to five specific decisions where your craft appears?
-If you cannot name five — you defaulted somewhere.
-
-### Token test
-Do your CSS variable names sound like they belong to THIS product?
-Generic: `--color-primary`. Specific: `--slot-available`, `--urgency-amber`.
-
----
-
-## Self-critique before delivery
-
-Walk through each section before handing off:
-
-1. **Composition** — Does the layout have rhythm? Are proportions intentional? Is there one clear focal point?
-2. **Craft** — Is every spacing value on-grid? Does typography use weight + tracking + size (not size alone)? Do surfaces whisper hierarchy without thick borders or dramatic shadows?
-3. **Content** — Does the spec tell one coherent story? Could a real person at a real company act on this?
-4. **Structure** — Are there any hacks? Negative-margin workarounds? Arbitrary pixel values? Fix them.
-
-**Ask yourself: "If a design lead reviewed this, what would they call out?" Fix that thing. Then ask again.**
-
----
-
-## Update design memory
-
-When the work introduces or changes reusable design decisions, update `.interface-design/system.md` with:
-- Final direction and anti-goals
-- Token block
-- Component pattern notes
-- New exceptions or constraints
-
-This file is the continuity layer between screens, agents, and future sessions.
-
----
-
-## Stack-specific notes
-
-| Stack | Priority |
-|---|---|
-| Laravel + TALL | Flux UI / Livewire primitives first; custom only for signature moves |
-| Filament | Built-in Filament components before any override |
-| Next.js + shadcn/ui | shadcn primitives + Tailwind tokens; keep component boundaries clean |
-| React + Tailwind | Design token CSS vars → Tailwind config → components |
-| Vue + Nuxt | Nuxt UI or PrimeVue first; avoid mixing component libraries |
-| Vanilla HTML | Define CSS custom properties at `:root`, semantic class names only |
-
----
-
-## Handoff to @dev
-
-The ui-spec.md must include:
-- Design token block (fonts, colors, spacing, radius, depth strategy, motion)
-- Per-screen layout notes with component names mapped to real library components
-- Full state matrix (default/hover/focus/active/disabled/loading/empty/error/success)
-- Responsive rules (mobile breakpoints first)
-- Accessibility checklist items
-- Any signature visual moves with implementation notes
-
-**Keep the spec concise enough to code from directly. Not a design document — a build contract.**