@jaimevalasek/aioson 1.5.1 → 1.7.0

package/template/.aioson/rules/data-format-convention.md

@@ -0,0 +1,136 @@
+---
+name: data-format-convention
+description: Which file format to use when producing or consuming structured data — YAML for agent-readable reference data, Markdown for narrative, JSON for machine-consumed data
+priority: 8
+version: 1.0.0
+---
+
+# Data Format Convention
+
+Use the right format for the right consumer. The same data structure reads very differently depending on who (or what) will consume it next.
+
+## The three formats and their consumers
+
+### YAML — structured data consumed by agents
+
+Use `.yaml` when the output is structured reference data that **another agent or squad executor will read field-by-field** to make decisions or produce content.
+
+LLMs read YAML more accurately than JSON for structured reference data because YAML allows comments, avoids excessive punctuation, and mirrors natural document structure.
+
+**Use YAML for:**
+- ICP definitions, persona profiles, audience segments
+- Offer sheets, product definitions, pricing structures
+- Brand guidelines (structured parts: tone, values, vocabulary, positioning)
+- Competitive analysis snapshots (structured fields)
+- Briefing data that a copy squad or design squad will consume
+- Entity catalogs referenced across multiple sessions
+
+**Naming:** `{slug}.yaml` in the relevant squad output or context directory.
+
+**Example — ICP profile (`icp-primary.yaml`):**
+```yaml
+# ICP — Primary Audience
+# Created by: @research-squad | Updated: 2026-04-02
+
+profile:
+  name: "Empreendedor Refém"
+  description: "Dono de negócio que depende de agências ou devs externos"
+
+pain_points:
+  - Perda de controle sobre o produto
+  - Atrasos e custos imprevisíveis
+  - Não consegue validar qualidade do que recebe
+
+desired_outcome: "Autonomia e velocidade — entregar sem depender de terceiros"
+
+buying_trigger: "Prazo vencendo ou fatura chegando de dev que atrasou"
+
+messaging:
+  primary: "Retome o controle do seu produto"
+  objection_1: "Não preciso saber programar?"
+  objection_1_answer: "Não. Você vai orquestrar, não digitar código."
+
+channels: [instagram, linkedin, youtube]
+```
+
+---
+
+### Markdown — narrative content consumed by humans and agents linearly
+
+Use `.md` when the output is narrative — content that flows as text and benefits from headers, lists, and prose.
+
+**Use Markdown for:**
+- Reports, analyses, article drafts
+- Scripts, hooks, copy blocks
+- Agent instructions and rules (this file is an example)
+- Specs, PRDs, discovery documents
+- Any output meant to be read from top to bottom
+
+**Never use YAML or JSON for:** articles, scripts, agent instructions, PRDs, analysis narratives, README files.
+
+---
+
+### JSON — structured data consumed by machines
+
+Use `.json` when the output is consumed by code — CLIs, APIs, webhooks, dashboards, or configuration parsers.
+
+**Use JSON for:**
+- `squad.manifest.json` — consumed by the AIOSON CLI and dashboard
+- `content.json` — consumed by the webhook server and dashboard
+- API payloads and webhook responses
+- CLI configuration files
+- Any file that `JSON.parse()` will read programmatically
+
+**Never change to YAML:** `squad.manifest.json`, `content.json`, `squad.json`, `aioson-models.json`. These are machine-consumed and must stay JSON for CLI compatibility.
+
+---
+
+## Decision rule (apply in this order)
+
+```
+Will a machine (CLI, API, webhook, dashboard) consume this file?
+  YES → JSON
+
+Will a human or agent read this top-to-bottom as narrative?
+  YES → Markdown
+
+Will an agent reference specific fields to make decisions or produce content?
+  YES → YAML
+```
+
+If uncertain: prefer Markdown. Only use YAML when the structured fields are the point — not the prose.
+
+---
+
+## Squad executor guidance
+
+When a squad executor produces output, choose the format based on what happens next:
+
+| Output type | Format | Example |
+|---|---|---|
+| Report, article, script | `.md` | `output/content-squad/ep-001/script.md` |
+| ICP, persona, audience profile | `.yaml` | `output/research-squad/icp-primary.yaml` |
+| Brand data, offer sheet | `.yaml` | `output/brand-squad/offer-advanced.yaml` |
+| Competitive analysis (structured) | `.yaml` | `output/research-squad/competitors.yaml` |
+| Competitive analysis (narrative) | `.md` | `output/research-squad/market-report.md` |
+| Webhook payload, API response | `.json` | handled by `content.json` convention |
+| Squad manifest, config | `.json` | `squad.manifest.json` (do not change) |
+
+**Cross-squad consumption:** when Squad A produces data that Squad B will consume, prefer YAML for structured reference data. The receiving squad's executor can reference `output/squad-a/{file}.yaml` directly and access fields with precision — more reliable than parsing a Markdown table.
+
+---
+
+## What NOT to change
+
+- Files with `.json` extension consumed by the AIOSON CLI or dashboard
+- Agent instruction files (`agents/*.md`) — narrative, not data
+- Existing specs and context files (`spec-*.md`, `discovery.md`, `architecture.md`) — mixed narrative + structure, Markdown is correct
+- YAML frontmatter inside `.md` files — this is already the right pattern for metadata
+
+---
+
+## Why this matters
+
+The same structured content stored as JSON or Markdown loses precision when an agent reads it. A JSON blob requires the agent to mentally parse brackets and quotes while tracking field relationships. A Markdown table requires the agent to infer column semantics from headers. A YAML document makes field names, nesting, and relationships immediately legible — the LLM spends its attention on the content, not the syntax.
+
+For squads that pass structured data between executors across sessions, this compounds: each session starts fresh, and a YAML profile loads faster and more accurately into working context than an equivalent JSON or Markdown representation.

package/template/.aioson/rules/example-monetary-values.md

@@ -0,0 +1,30 @@
+---
+name: monetary-values
+description: All monetary values must be stored as integer cents, never as floats
+agents: [dev, architect, qa]
+priority: 5
+version: 1.0.0
+---
+
+# Monetary Values Convention
+
+All monetary values in this project MUST be stored and calculated as integer cents.
+
+## Rule
+
+- NEVER use float or decimal types for money fields
+- Store as integer: `1000` = R$ 10,00 or USD $10.00
+- Display formatting is a UI concern only — format at the presentation layer, never in persistence or business logic
+- This applies to: database columns, API payloads, internal calculations, test fixtures
+
+## Rationale
+
+Float arithmetic produces rounding errors in financial calculations.
+Example: `0.1 + 0.2 === 0.30000000000000004` in most languages.
+Using integer cents eliminates this class of bug entirely.
+
+## Applies to
+
+- Database migrations: column type must be integer or bigint, not decimal/float
+- API contracts: monetary fields must be documented as integer cents
+- @qa: test fixtures must use integer cents; any float in a money field is a bug

package/template/.aioson/schemas/squad-manifest.schema.json

@@ -98,9 +98,9 @@
           "title": { "type": "string" },
           "type": {
             "type": "string",
-            "enum": ["worker", "agent", "clone", "assistant", "human-gate"],
+            "enum": ["worker", "agent", "clone", "assistant", "human-gate", "research", "reviewer", "skill"],
             "default": "agent",
-            "description": "Executor type: worker (deterministic script, no LLM), agent (LLM with defined role), clone (cognitive replica of real person), assistant (domain specialist with behavioral profile), human-gate (human approval checkpoint)"
+            "description": "Executor type: worker (deterministic script, no LLM), agent (LLM with defined role), clone (cognitive replica of real person), assistant (domain specialist with behavioral profile), human-gate (human approval checkpoint), research (web research with cache, no LLM), reviewer (cross-AI review synthesis), skill (external Agent Skills Standard skill)"
           },
           "role": { "type": "string" },
           "file": { "type": "string" },
@@ -121,6 +121,14 @@
             "type": "string",
             "description": "Script path for worker executors"
           },
+          "skill": {
+            "type": "string",
+            "description": "Agent Skills Standard skill identifier (for type: 'skill'). E.g. '@anthropic/code-review'"
+          },
+          "source": {
+            "type": "string",
+            "description": "Skill source path or package. E.g. 'npm:@org/skill', './skills/my-skill/'"
+          },
           "domain": {
             "type": "string",
             "description": "Specialized domain for assistant executors"
@@ -198,11 +206,85 @@
                 "order": { "type": "integer", "minimum": 1 },
                 "file": { "type": "string", "description": "Path to the task .md file" },
                 "input": { "type": "string", "description": "What this task receives" },
-                "output": { "type": "string", "description": "What this task produces" }
+                "output": { "type": "string", "description": "What this task produces" },
+                "review_loop": {
+                  "type": "boolean",
+                  "default": false,
+                  "description": "Enable evaluator-optimizer loop: dev implements, qa evaluates, repeat up to max_review_iterations"
+                },
+                "review_criteria": {
+                  "type": "array",
+                  "items": { "type": "string" },
+                  "description": "Criteria the evaluator uses to PASS/FAIL the output (used with review_loop: true)"
+                },
+                "max_review_iterations": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "maximum": 5,
+                  "default": 3,
+                  "description": "Maximum dev→qa iterations before escalating to human (used with review_loop: true)"
+                },
+                "voting": {
+                  "type": "object",
+                  "description": "Sampling-and-Voting: run N parallel instances and reach consensus. Best for critical decisions.",
+                  "properties": {
+                    "instances": {
+                      "type": "integer",
+                      "minimum": 2,
+                      "maximum": 10,
+                      "default": 3,
+                      "description": "Number of parallel instances to spawn"
+                    },
+                    "threshold": {
+                      "type": "number",
+                      "minimum": 0.5,
+                      "maximum": 1,
+                      "default": 0.66,
+                      "description": "Minimum consensus fraction to accept result (0.66 = 66%)"
+                    },
+                    "on_no_consensus": {
+                      "type": "string",
+                      "enum": ["escalate", "use_majority", "fail"],
+                      "default": "escalate",
+                      "description": "What to do when consensus < threshold"
+                    }
+                  }
+                }
               }
             },
             "description": "Granular tasks within this executor, executed in order"
           },
+          "research": {
+            "type": "object",
+            "description": "Configuration for research executor type (type: 'research')",
+            "properties": {
+              "topic": { "type": "string", "description": "Cache key / topic slug (e.g. 'youtube-shorts-2026')" },
+              "urls": {
+                "type": "array",
+                "items": { "type": "string" },
+                "description": "URLs to scrape for this research topic"
+              },
+              "cache_hours": { "type": "integer", "default": 168, "description": "Cache TTL in hours (default 168 = 7 days)" },
+              "cache_dir": { "type": "string", "default": "researchs/", "description": "Base directory for research cache" },
+              "max_sources": { "type": "integer", "default": 5, "description": "Maximum number of URLs to scrape" }
+            }
+          },
+          "cross_ai": {
+            "type": "boolean",
+            "description": "If true (for reviewer type), send to multiple AI CLIs and synthesize responses"
+          },
+          "review": {
+            "type": "object",
+            "description": "Configuration for reviewer executor type",
+            "properties": {
+              "detect_clis": {
+                "type": "array",
+                "items": { "type": "string", "enum": ["claude", "gemini", "codex"] }
+              },
+              "exclude_current": { "type": "boolean", "default": true },
+              "synthesize_to": { "type": "string", "description": "Output path for REVIEWS.md" }
+            }
+          },
           "formats": {
             "type": "array",
             "items": { "type": "string" },
@@ -705,5 +787,44 @@
       }
     }
   },
+  "depends_on": {
+    "type": "array",
+    "description": "Inter-squad dependencies: this squad will consume published events from these squads before starting a run",
+    "items": {
+      "type": "object",
+      "required": ["squad", "event"],
+      "properties": {
+        "squad": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9-]*[a-z0-9]$",
+          "description": "Slug of the squad whose events this squad depends on"
+        },
+        "event": {
+          "type": "string",
+          "description": "Event pattern to subscribe to (e.g. 'episode.created', 'review.*', '*')"
+        },
+        "input_mapping": {
+          "type": "object",
+          "description": "Maps event payload fields to task context fields",
+          "additionalProperties": { "type": "string" }
+        }
+      }
+    }
+  },
+  "hooks": {
+    "type": "object",
+    "description": "Hook scripts that gate squad execution (exit 0=allow, exit 2=deny)",
+    "properties": {
+      "pre_run": {
+        "type": "string",
+        "description": "Shell command to run before squad:autorun starts. Exit code 2 aborts the run."
+      }
+    }
+  },
+  "subscriptions": {
+    "type": "array",
+    "description": "Event patterns this squad subscribes to (consumed at the start of each autorun). Short form of depends_on[*].event.",
+    "items": { "type": "string" }
+  },
   "additionalProperties": true
 }

package/template/.aioson/skills/design/aurora-command-ui/SKILL.md

@@ -0,0 +1,243 @@
+---
+name: aurora-command-ui
+description: Aurora Command UI is a hybrid design system fusing command-center structure with dark glass surfaces over a mandatory aurora gradient substrate. Use it when `design_skill: aurora-command-ui` is set in project.context.md OR when the user explicitly asks for "aurora command", "dark glass dashboard", "glass command center", "aurora dark UI", "teal violet glass", "dark frosted panels", "aurora infra dashboard", or similar. Ideal for SOC platforms, AI tools, security dashboards, dev platforms, CRM with presence, and any product where operational authority and visual depth must coexist. Dark by default with a light aurora option. Do NOT use this skill unless explicitly selected.
+---
+
+# Aurora Command UI
+
+Aurora Command UI lives at the intersection of **military-grade data command center** and **layered glass depth**. It is built from the structural DNA of Cognitive Core (mono rails, dense stat numbers, section zones, command shell) fused with the glass substrate engine of Glassmorphism (backdrop-filter surfaces, aurora gradient, luminous borders, ::before reflections).
+
+The result: a dark glass shell where every panel reveals the aurora gradient underneath, operational data reads with precision, and the interface feels simultaneously tactical and premium.
+
+**This is one visual system.** Never combine it with another design skill.
+
+## Package structure
+
+```text
+.aioson/skills/design/aurora-command-ui/
+  SKILL.md                      ← you are here (load this first)
+  references/
+    art-direction.md            ← intent, 5 expression modes, signature library, anti-generic tests
+    design-tokens.md            ← CSS variables dark + light, glass tokens, typography, spacing, shadows
+    components.md               ← 22+ components (glass variants + command structure)
+    patterns.md                 ← Page layouts: aurora app shell, dashboard, detail, settings, auth, list-detail
+    dashboards.md               ← 5 dashboard presets + chart palette + glass panel rules
+    websites.md                 ← Aurora landing page patterns, hero variants, section patterns
+    motion.md                   ← Animations: glass entrances, aurora-aware motion, command transitions
+```
+
+## Activation rules
+
+- Apply this package **only** when `project.context.md` contains `design_skill: "aurora-command-ui"` or the user explicitly chooses it.
+- If another design skill is selected, do **not** load this package.
+- Never auto-select this skill — always require explicit confirmation.
+- If no skill is set yet, the active agent must ask or confirm before applying.
+
+## Responsibility boundary
+
+This skill defines:
+- Visual direction and aesthetic DNA (dark glass over aurora gradient, command structure)
+- Design tokens (glass surfaces, accent fusion, shadows, typography, spacing, radius)
+- Component vocabulary and anatomy (22+ components — glass shell + command mono rails)
+- Page composition patterns (aurora substrate → glass shell → glass panels → mono section rails → content)
+- Theme switching behavior (dark default / light aurora option)
+
+This skill does **not** decide:
+- Stack (React, Vue, Blade, HTML, etc.)
+- Output format (single file, multi-file, CSS modules, Tailwind, etc.)
+- Icon library choice
+- Whether a theme toggle exists in the product (the agent decides)
+- Animation library (CSS or JS — motion.md is stack-agnostic)
+
+## Loading guide
+
+Always load only what the current task needs:
+
+| Task | Load |
+|---|---|
+| Any UI work | `references/design-tokens.md` |
+| Reusable components | `references/design-tokens.md` + `references/components.md` |
+| Dashboard or admin panel | `references/art-direction.md` + `references/design-tokens.md` + `references/components.md` + `references/patterns.md` + `references/dashboards.md` |
+| Detail / profile page | `references/art-direction.md` + `references/design-tokens.md` + `references/components.md` + `references/patterns.md` |
+| Landing page or website | `references/art-direction.md` + `references/design-tokens.md` + `references/components.md` + `references/websites.md` |
+| Motion / animation | add `references/motion.md` when animation materially improves the result |
+| Full UI build | all seven reference files |
+
+## Visual signature — three pillars
+
+1. **Aurora depth** — A dark aurora gradient (`linear-gradient(135deg, #060910 0%, #0A0818 30%, #060C1A 70%, #08060F 100%)`) is the mandatory substrate. Dark glass panels (`rgba(10,14,26,0.65)` with `backdrop-filter`) float over it, revealing the aurora below. The gradient is not decoration — it is structurally required. Remove it and the glass has nothing to reveal.
+2. **Command authority** — Mono uppercase rails on every section. Dense stat numbers. Compact density that communicates operational mastery. The information structure feels like a mission control panel: labeled zones, one focal block per viewport, restrained accent usage.
+3. **Teal-violet fusion** — A single accent gradient `linear-gradient(135deg, #00C8E8, #7C3AED)` used on CTAs, active states, stat numbers, borders, and glow shadows. Teal-electric (`#00C8E8`) is the operational signal. Violet (`#7C3AED`) is the highlight and CTA. They only appear as a gradient pair — never in isolation except for semantic purposes.
+
+## Hybrid DNA
+
+**From cognitive-core-ui (structure side):**
+- Command center shell with mono section rails
+- Dense stat numbers (text-4xl, tabular-nums)
+- Top bar + sidebar + tab navigation structure
+- Compact density system for dashboards and admin
+- Section headers with mono labels and icon rails
+- Sidebar active item: border-left 3px accent + elevated surface
+
+**From glassmorphism-ui (glass side):**
+- `backdrop-filter: blur()` on all major surfaces
+- Aurora gradient substrate — mandatory, not decorative
+- Luminous borders: `rgba(255,255,255,0.10)` on dark glass
+- Top reflection `::before` on every glass card
+- `@supports (backdrop-filter: blur(1px))` fallback always required
+- Glass levels: shell → surface → elevated (3 distinct opacity layers)
+
+**New in aurora-command-ui (hybrid elements):**
+- Dark tinted glass: panels use `rgba(10,14,26,0.65)` — NOT white-transparent. The aurora shows through dark glass, not bright glass.
+- Accent gradient on stat numbers, not just CTAs
+- Teal-electric glow shadows: `0 0 30px rgba(0,200,232,0.12)`
+- Aurora glow behind hero metric panels: `radial-gradient(circle at 50% 0%, rgba(0,200,232,0.08), transparent 70%)`
+
+## Theme system
+
+```html
+<div data-theme="dark">   <!-- or data-theme="light" -->
+```
+
+- **Dark (default)**: All operational products — dashboards, monitoring, security, AI tools, dev platforms. The aurora gradient is deep navy + deep violet. Glass is dark tinted.
+- **Light**: Client-facing apps, institutional variants, content-heavy pages. The aurora gradient is soft lavender-gray. Glass is white tinted.
+
+If the user does not specify: default to **dark with a theme toggle** in the top bar.
+
+## Visual DNA — dark theme
+
+### Aurora substrate (mandatory)
+```css
+background: linear-gradient(135deg, #060910 0%, #0A0818 30%, #060C1A 70%, #08060F 100%);
+background-attachment: fixed;
+```
+
+### Dark glass surfaces
+- Shell (sidebar, top bar): `rgba(8, 12, 22, 0.75)` + `backdrop-filter: blur(24px)`
+- Surface cards: `rgba(10, 14, 26, 0.65)` + `backdrop-filter: blur(16px)`
+- Elevated (hover, nested): `rgba(14, 20, 36, 0.75)` + `backdrop-filter: blur(16px)`
+
+### Accents
+- Teal-electric: `#00C8E8` (operational signals, active states, glow)
+- Violet: `#7C3AED` (CTAs, highlights, gradient endpoint)
+- Accent gradient: `linear-gradient(135deg, #00C8E8, #7C3AED)`
+- Glow shadow: `0 0 30px rgba(0,200,232,0.12), 0 8px 24px rgba(0,0,0,0.40)`
+
+### Typography
+- Headings: `Inter`, weight 700, `letter-spacing: -0.02em`
+- Body: `Inter`, weight 400, `line-height: 1.6`
+- Mono rails: `JetBrains Mono`, weight 600, uppercase, `letter-spacing: 0.12em`, `font-size: 0.675rem`
+- Stats: `Inter`, weight 700, `font-size: var(--text-4xl)`, gradient text on hero metric
+
+## Layout structure (aurora app shell)
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│            AURORA GRADIENT BACKGROUND (substrate, fixed)        │
+│  ┌──────────────────────────────────────────────────────────┐   │
+│  │ GLASS TOP BAR — backdrop-blur-lg, glass-shell            │   │
+│  │ [Logo] ─── [Tab Nav Center] ─── [Actions + Toggle]      │   │
+│  ├─────────────────┬────────────────────────────────────────┤   │
+│  │ GLASS SIDEBAR   │  CONTENT AREA                         │   │
+│  │ 200-220px       │  [MONO SECTION HEADER]                │   │
+│  │ backdrop-blur   │  [GLASS STAT CARDS — aurora showing]  │   │
+│  │ glass-shell     │  [GLASS DATA TABLE]                   │   │
+│  │ glass-border    │  [GLASS CHART CONTAINER]              │   │
+│  │ aurora visible  │                                       │   │
+│  │                 │                                       │   │
+│  └─────────────────┴────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Signature details
+- Glass cards always have `::before` top reflection: `linear-gradient(180deg, rgba(255,255,255,0.07) 0%, transparent 50%)`
+- Teal-electric bottom border on active tabs: `3px solid #00C8E8`
+- Sidebar active item: `border-left: 3px solid var(--accent-primary)` + `background: var(--glass-elevated)`
+- Mono section headers always precede content zones
+- Hero stat card: gradient text on main number (`background: var(--accent-gradient); -webkit-background-clip: text`)
+- Every glass container uses `@supports (backdrop-filter: blur(1px))` fallback
+
+## Application rules
+
+- Treat `references/design-tokens.md` as the source of truth for ALL tokens.
+- Treat `references/art-direction.md` as the source of truth for expression, signature, and anti-generic decisions.
+- The aurora gradient substrate is **non-negotiable** — never place glass panels over a solid background.
+- Dark glass opacity must be enough to reveal the aurora. If panels are too opaque, reduce `rgba` alpha toward 0.55.
+- Limit glass nesting to 3 levels max. Each `backdrop-filter` is a composite layer.
+- Always include `@supports (backdrop-filter: blur(1px))` fallbacks.
+- Mono rails are the structural backbone — use them for section headers, stat labels, and metadata rails ONLY. Do not mono-label paragraphs, nav links, or body copy.
+- The teal-violet gradient is the single accent family. Do not introduce secondary accent colors.
+- Never combine this package with `cognitive-core-ui`, `glassmorphism-ui`, `interface-design`, or any other design skill.
+- Adapt code examples to the active stack. Reference snippets are design specifications, not copy-paste code.
+- Accessibility, responsiveness, and production semantics are the agent's responsibility (not this skill).
+
+## Intent before visuals
+
+Before choosing layout, answer all three:
+
+1. Who is the human using this page right now?
+2. What is the main action or decision they must complete?
+3. How should this interface feel in concrete words, not generic labels?
+
+Bad answers:
+- "for users"
+- "manage data"
+- "dark and cool"
+
+Good answers:
+- "security analyst identifying active threats during a live incident"
+- "AI platform admin comparing agent performance across production workloads"
+- "surgical, atmospheric, authoritative — the aurora background communicates depth, the mono rails communicate precision"
+
+## Workflow discipline
+
+1. Confirm the aurora gradient substrate is in place before building any component.
+2. Choose one expression mode from `references/art-direction.md`.
+3. Name one signature glass+command move and repeat it intentionally across the page.
+4. Run the Glass Test: remove `backdrop-filter` from all cards — if the UI looks fine without it, glass is decorative, not structural. Fix: reduce dark glass opacity so the aurora is clearly visible behind panels.
+5. Build from tokens first, then components, then page composition.
+6. Validate state parity: default, hover, active, focus, disabled — all glass token transitions.
+7. Validate contrast: dark glass surfaces must meet WCAG AA. Increase opacity on body text surfaces if needed.
+
+## Non-negotiable quality gates
+
+- The aurora gradient substrate is non-negotiable. No gradient = no glass system.
+- Dark glass must reveal the aurora — opacity must stay at or below 0.75. Do not "solidify" panels.
+- Never use saturated neon colors. Teal-electric is at the saturation limit — do not push beyond it.
+- Never nest more than 3 glass layers (performance + visual confusion).
+- Shadows must be tinted with teal-electric, not plain black. `rgba(0,200,232,0.12)` is the glow baseline.
+- Fallback without `backdrop-filter` must be tested: use `rgba(8,12,22,0.95)` solid for dark, `rgba(255,255,255,0.95)` for light.
+- Every page must pass the **Glass Test**: backdrop-blur is structural, aurora is visible behind panels.
+- Every page must pass the **Command Test**: mono rails appear on section headers, stat labels, and metadata only — not overused.
+- Every page must pass the **Depth Test**: squinting reveals at least 3 depth layers (substrate → glass panel → content).
+- Sameness is failure. If the result looks like a default dark admin with blur added, iterate on composition before finishing.
+
+## Positioning vs parent skills
+
+| Aspect | aurora-command-ui | cognitive-core-ui | glassmorphism-ui |
+|--------|------------------|-------------------|-----------------|
+| Surfaces | Dark glass (rgba dark tinted) | Solid surfaces (bg-surface) | White glass (rgba light tinted) |
+| Background | Aurora gradient (mandatory) | Solid void/base | Lavender aurora gradient |
+| Accent | Teal-electric + Violet gradient | Teal/cyan only | Violet-blue |
+| Default theme | Dark | Dark | Light |
+| Depth model | Blur layers (dark) | Border/shadow depth | Blur layers (light) |
+| Mono usage | Section rails + stats | Section rails + stats | None (uses plain sans) |
+| Best for | SOC, AI platforms, dev tools | Command centers, SaaS | Fintech, mobile, media |
+
+## Delivery modes
+
+### Greenfield
+1. Choose expression mode (Eclipse Command, Deep Analytics, Void Editorial, Quantum Workspace, Crystal Intelligence)
+2. Establish aurora gradient background substrate first
+3. Load relevant references
+4. Apply token scope from `design-tokens.md` (glass tokens are the foundation)
+5. Compose layout from `patterns.md` or `websites.md`
+6. Build components from `components.md`
+
+### Brownfield
+1. Audit existing UI before rewriting
+2. Check if the aurora gradient background can be introduced without breaking existing work
+3. Map Aurora Command tokens onto the existing component library
+4. Add glass surfaces progressively: start with top bar + sidebar, then cards
+5. Consolidate duplicate variants before introducing new ones
+6. Prefer targeted upgrades over full rewrites unless the user asks for a redesign