@jaimevalasek/aioson 1.5.1 → 1.6.0

package/template/.aioson/skills/process/design-hybrid-forge/references/pair-compatibility.md

@@ -0,0 +1,117 @@
+# Pair Compatibility — design-hybrid-forge
+
+Load when choosing which two base skills to combine this week.
+
+---
+
+## The tension principle
+
+The best hybrid pairs have **creative tension** — they pull in different directions, and the hybrid resolves the tension into something neither parent could be alone.
+
+Two skills that are too similar produce a redundant hybrid. Two skills that are completely incompatible (same aesthetic, same structure, same depth model) produce noise, not synthesis.
+
+**Rule:** choose pairs where one skill is structure-dominant and the other is aesthetic-dominant, OR where they share a dimension but differ radically in another.
+
+---
+
+## Skill taxonomy
+
+Each base skill has a primary role:
+
+| Skill | Role | Structure model | Aesthetic model | Default theme |
+|---|---|---|---|---|
+| `cognitive-core-ui` | Structure | Command center, dense, mono rails | Solid dark surfaces, teal accent | Dark |
+| `clean-saas-ui` | Structure | Systematic B2B, medium density | Neutral solid surfaces, blue accent | Light |
+| `neo-brutalist-ui` | Structure | Raw grid, brutal honesty | Hard borders, yellow accent, zero blur | Light |
+| `bold-editorial-ui` | Structure + Aesthetic | Editorial rhythm, section contrast | Dark cinematic, red-orange accent | Dark |
+| `glassmorphism-ui` | Aesthetic | Glass layers, gradient substrate | Transparent surfaces, violet-blue | Light |
+| `warm-craft-ui` | Aesthetic | Breathable, serif-driven | Warm solid surfaces, terracotta | Light |
+| `premium-command-center-ui` | Structure + Aesthetic | Tri-rail, operational | Aurora-glass, graphite | Dark |
+| `interface-design` | Neutral | Flexible | Flexible | Adaptive |
+
+---
+
+## Compatibility matrix
+
+`✦` = High tension, strong hybrid potential
+`◈` = Medium tension, viable
+`○` = Low tension, too similar or too incompatible
+`✕` = Avoid, redundant (same family)
+
+| | cognitive-core | clean-saas | neo-brutalist | bold-editorial | glassmorphism | warm-craft | premium-command | interface-design |
+|---|---|---|---|---|---|---|---|---|
+| **cognitive-core** | — | ◈ | ✦ | ✦ | ✦ | ✦ | ✕ | ◈ |
+| **clean-saas** | ◈ | — | ✦ | ◈ | ✦ | ✦ | ◈ | ○ |
+| **neo-brutalist** | ✦ | ✦ | — | ✦ | ✦ | ✦ | ◈ | ◈ |
+| **bold-editorial** | ✦ | ◈ | ✦ | — | ✦ | ◈ | ◈ | ◈ |
+| **glassmorphism** | ✦ | ✦ | ✦ | ✦ | — | ✦ | ✕ | ◈ |
+| **warm-craft** | ✦ | ✦ | ✦ | ◈ | ✦ | — | ◈ | ◈ |
+| **premium-command** | ✕ | ◈ | ◈ | ◈ | ✕ | ◈ | — | ○ |
+| **interface-design** | ◈ | ○ | ◈ | ◈ | ◈ | ◈ | ○ | — |
+
+---
+
+## Completed hybrids (do not repeat)
+
+| Pair | Hybrid name | Shipped |
+|---|---|---|
+| cognitive-core-ui × glassmorphism-ui | `aurora-command-ui` | 2026-03-29 |
+
+---
+
+## Recommended next pairs (high tension, not yet done)
+
+**Tier 1 — Maximum tension, clear identity:**
+
+| Pair | Anticipated identity | Best for |
+|---|---|---|
+| `neo-brutalist-ui` × `glassmorphism-ui` | Raw structural grid over a frosted aurora — brutal honesty made luminous | Indie dev tools, open source dashboards |
+| `warm-craft-ui` × `cognitive-core-ui` | Earthy command center — serifs + mono rails, terracotta + teal tension | AI agent platforms with human focus, productivity SaaS |
+| `neo-brutalist-ui` × `cognitive-core-ui` | Cold data brutalism — raw borders, dense mono, no decoration, only signal | Infrastructure monitoring, CLI-adjacent tools |
+| `bold-editorial-ui` × `glassmorphism-ui` | Dark glass editorial — cinematic depth through transparency, editorial scale | SaaS marketing, product launches, AI platforms |
+| `warm-craft-ui` × `glassmorphism-ui` | Warm aurora — soft glass over warm gradients, terracotta glow, humanized depth | Wellness, productivity, note-taking, B2C SaaS |
+| `clean-saas-ui` × `glassmorphism-ui` | Crystalline enterprise — minimal glass, disciplined structure, enterprise-grade glass | B2B SaaS with premium feel, enterprise admin |
+
+**Tier 2 — Strong but more constrained:**
+
+| Pair | Anticipated identity |
+|---|---|
+| `bold-editorial-ui` × `cognitive-core-ui` | Dark editorial command — large display type + mono rails, red-orange × teal tension |
+| `neo-brutalist-ui` × `warm-craft-ui` | Crafted brutalism — raw structure + handmade warmth, artisan dev aesthetic |
+| `clean-saas-ui` × `bold-editorial-ui` | Enterprise editorial — clean precision + cinematic moments, professional drama |
+
+---
+
+## Pair selection questions
+
+Before committing to a pair, answer:
+
+1. **Can you name the creative tension in one sentence?** If not, the pair may be too similar.
+2. **Which skill wins the substrate?** One parent's background model must dominate — it cannot be 50/50.
+3. **What is genuinely new?** Name one element that exists in neither parent and will only exist in the hybrid.
+4. **Who uses this?** If the target user is identical to both parent skills, the hybrid is redundant.
+5. **Does the name suggest a third thing?** The hybrid's name must not sound like "A + B" but like a new concept.
+
+---
+
+## Optional modifier lane
+
+After the core pair is chosen, you may optionally add up to 2 modifier skills. A 3rd modifier is allowed only when the user explicitly enables advanced mode or the active variation preset carries `modifier_policy: "up_to_3_modifiers"`.
+
+Modifier rules:
+- Modifiers are optional. The hybrid must still stand on the 2 primary parents alone.
+- Modifiers cannot own substrate, layout system, navigation model, or density baseline.
+- Modifiers may influence only accent refinement, motion, website narrative patterns, or one small component family.
+- If a modifier makes the identity harder to describe in one sentence, remove it.
+- `interface-design` is allowed as a modifier, but is too neutral to be a primary parent.
+
+---
+
+## Anti-pairs
+
+Avoid these regardless of aesthetic appeal:
+
+- `cognitive-core-ui` × `premium-command-center-ui` — same domain, same depth model, redundant
+- `glassmorphism-ui` × `premium-command-center-ui` — too similar (both glass + aurora)
+- `interface-design` × any skill — interface-design is a neutral craft package, hybrids require distinct DNA poles
+- Any skill with itself — obvious

package/template/.aioson/skills/process/design-hybrid-forge/references/quality-gates.md

@@ -0,0 +1,188 @@
+# Quality Gates — design-hybrid-forge
+
+Load when validating a hybrid before shipping (Phase 6).
+
+Run all gates in order. A hybrid that fails any gate is not done — return to the phase indicated.
+
+---
+
+## Gate A — Identity clarity
+
+**Question:** Can you describe this hybrid in one sentence without naming its parents?
+
+Pass: The sentence names a specific vibe, specific user, specific use case.
+> "A dark glass command center where operational precision lives inside an aurora gradient — for teams running security operations or AI platforms."
+
+Fail: The sentence is vague, generic, or only makes sense by referencing the parents.
+> "It combines dark dashboard style with glass effects."
+
+**If fail:** Return to Phase 2 (crossover spec) — the identity is not clear enough.
+
+---
+
+## Gate B — The third thing test
+
+**Question:** Name 3 elements in the hybrid that exist in NEITHER parent.
+
+Pass: You can name 3 specific CSS values, interaction patterns, or composition rules that are genuinely new.
+
+Fail: Every element in the hybrid can be traced back to parent A or parent B — the hybrid is a mashup, not a synthesis.
+
+**If fail:** Return to Phase 3 — identify at minimum 3 new elements before writing files.
+
+---
+
+## Gate C — Accent fusion test
+
+**Question:** Is the accent gradient a genuine fusion, or is it just parent A's color + parent B's color next to each other?
+
+Run this test: Cover the gradient label. Show only the gradient swatch to someone who knows both parents. Would they say "oh, that's just A and B stacked"?
+
+Pass: The gradient produces a new color perception. The transition between the two endpoints creates a third color that is the hybrid's identity.
+
+Fail: The gradient is jarring or reads as "two separate accents." No new color emerges.
+
+**If fail:** Adjust the gradient angle, midpoint color, or one endpoint. The goal is a gradient that reads as one accent, not two.
+
+---
+
+## Gate D — Substrate visibility test
+
+**Question:** Is the substrate visible through the glass/surface panels?
+
+Test procedure:
+1. Open the dashboard preview.
+2. Look at the glass stat cards. Can you see the background gradient through them?
+3. Look at the sidebar. Can you see the gradient?
+
+Pass: The aurora/gradient is clearly visible through at least 60% of glass surfaces. The interface "lives inside" the background.
+
+Fail: The glass panels are too opaque — the background looks like a solid dark or light color behind the panels, not a visible gradient.
+
+**If fail:** Reduce glass surface opacity. For dark glass: stay at or below `rgba(r,g,b,0.75)`. For white glass: stay at or below `rgba(255,255,255,0.70)`. Do not "solidify" the panels.
+
+---
+
+## Gate E — Structure legibility test
+
+**Question:** Does the command/layout structure read clearly, or does the aesthetic overwhelm the hierarchy?
+
+Test procedure:
+1. Open the dashboard preview.
+2. Blur your eyes. Can you still see: top bar / sidebar / content area / section headers?
+3. Without reading text, can you identify which element is the stat number vs body copy vs section label?
+
+Pass: The layout structure is clear at a glance, even through the glass/aesthetic treatment.
+
+Fail: The blur/gradient/texture treatment makes sections bleed into each other. Hierarchy is lost.
+
+**If fail:** Increase contrast between structure-defining elements (top bar, sidebar, section headers) and content areas. The glass treatment must respect structure, not obscure it.
+
+---
+
+## Gate F — Sameness test
+
+**Question:** Could this hybrid be mistaken for a default AI dashboard, a Tailwind UI starter, or a generic dark theme?
+
+Test procedure:
+1. Remove all brand names from the preview.
+2. Show it alongside 3 other dark UI screenshots.
+3. Does it have at least one immediately distinctive visual element?
+
+Pass: There is one element that could not exist in a generic dashboard — something that is clearly the result of this specific hybrid pairing.
+
+Fail: The design looks like "dark + blur" with no further identity.
+
+**If fail:** Identify the signature move and amplify it. Make it appear in at least 5 places. The signature should be the first thing you notice.
+
+---
+
+## Gate G — Parent distinction test
+
+**Question:** Is the hybrid visually distinct from BOTH parents?
+
+Test procedure:
+1. Open the dashboard preview alongside `cognitive-core-ui.html` and `glassmorphism-ui.html` (or the two actual parents).
+2. Does the hybrid look like parent A? If yes — the aesthetic from parent B was not applied strongly enough.
+3. Does the hybrid look like parent B? If yes — the structure from parent A was not applied strongly enough.
+
+Pass: Looking at all three side by side, the hybrid is clearly different from both parents while sharing DNA with each.
+
+Fail: The hybrid looks like a minor variant of one parent.
+
+**If fail:** Identify which parent is dominant and push the contribution from the other parent harder. Usually this means making the new elements (Gate B) more prominent.
+
+---
+
+## Gate H — Preview completeness
+
+**Question:** Do both HTML previews satisfy all requirements from `output-contract.md`?
+
+Checklist (dashboard preview):
+- [ ] Substrate background visible through glass panels
+- [ ] Command strip or equivalent live indicator (if structure parent warrants it)
+- [ ] Top bar + sidebar + stat row + chart + feed/alert + data table
+- [ ] Hybrid accent gradient on ≥3 visible elements
+- [ ] `::before` reflection on glass cards
+- [ ] AIOSON badge with hybrid accent
+
+Checklist (landing preview):
+- [ ] Full-page substrate background
+- [ ] Glass navigation bar
+- [ ] Hero section (not a generic centered CTA)
+- [ ] Atmospheric element (orb, gradient blob)
+- [ ] Proof rail + feature grid + pricing (3 tiers, featured card distinct)
+- [ ] Footer with glass treatment
+- [ ] AIOSON badge
+
+Pass: All items checked.
+Fail: Return to Phase 5 and complete the missing elements.
+
+---
+
+## Gate I — Metadata integrity
+
+**Question:** Does `.skill-meta.json` accurately describe the hybrid?
+
+Checklist:
+- [ ] `source` is `generated`
+- [ ] `generation_mode` is `project-local`
+- [ ] `parents.primary` contains exactly 2 skills
+- [ ] `parents.modifiers` contains at most 2 skills by default, or at most 3 only when advanced mode was explicitly enabled
+- [ ] `author.name` is filled when the user provided it
+- [ ] `generator.skill` is `design-hybrid-forge`
+- [ ] `generator.model` is recorded when the runtime exposed it
+- [ ] `variation_profile.modifier_policy` matches the generation mode when a preset was used
+
+Pass: The metadata is present and matches the generated skill.
+Fail: Return to Phase 4 and fix the metadata before distribution.
+
+---
+
+## Final ship checklist — project-local mode
+
+Before marking the project-local hybrid as done:
+
+- [ ] All 8 skill files written (SKILL.md + 7 references)
+- [ ] `.skill-meta.json` written
+- [ ] Both HTML previews written inside `previews/`
+- [ ] Variation overlay reflected in previews and metadata when one was selected
+- [ ] Active preset removed or archived from `.aioson/context/design-variation-preset.md` after successful generation
+- [ ] History snapshot preserved in `.aioson/context/history/design-variation-presets/`
+- [ ] `AGENTS.md` updated when it exists
+- [ ] Tool-native mirrors updated if the directories exist
+- [ ] All quality gates A through I passed
+
+When all are checked: the project-local hybrid is shipped.
+
+## Final ship checklist — core-promotion mode
+
+Only for explicit promotion back to AIOSON core:
+
+- [ ] Project-local checklist already passed
+- [ ] `.aioson/skills/design/{slug}/` prepared in the core repo
+- [ ] `docs/design-previews/index.html` updated with `✦ Hybrid` badge
+- [ ] `naming-registry.md` updated with the new hybrid entry
+- [ ] `pair-compatibility.md` updated (add pair to completed list)
+
+When all are checked: the hybrid is ready for PR / marketplace curation.

package/template/.aioson/skills/process/design-hybrid-forge/references/variation-library.md

@@ -0,0 +1,125 @@
+# Variation Library — design-hybrid-forge
+
+Load when the user wants the hybrid to feel more unique, extravagant, classic, animated, CSS-forward, or otherwise less "default SaaS".
+
+Updated from a current web scan on **March 30, 2026**. Use these directions as overlays on top of the hybrid's core DNA, never as a replacement for the 2 primary parents.
+
+---
+
+## How to use this file
+
+1. Choose **1–2 style modes**
+2. Choose **0–2 layout moves**
+3. Choose **0–2 motion directions**
+4. Choose **0–2 material / texture signals**
+5. Choose **1–2 typography moves**
+6. Choose **0–3 advanced CSS techniques**
+7. Choose **2 anti-sameness guardrails**
+
+If you choose too many items from every category, the result becomes a moodboard instead of a skill.
+
+---
+
+## Style modes
+
+| Mode | Use when | Core signal |
+|---|---|---|
+| **Classic editorial** | The user wants timeless, cultured, authoritative UI | Serif-forward hierarchy, measured spacing, mature rhythm |
+| **Extravagant / maximalist** | The user wants a bold, high-personality result | Layered color, dense composition, deliberate abundance |
+| **Cinematic / immersive** | The site should feel like a scene or story world | Atmospheric contrast, chapter-based sections, dramatic reveals |
+| **Playful / dopamine** | The brand benefits from joy and energy | Saturated accents, elastic details, expressive components |
+| **Neo-brutalist / anti-design** | The user wants structure with edge and friction | Hard borders, visible hierarchy, unapologetic layout honesty |
+| **Retrofuturist** | The user wants nostalgic future energy | Chrome, glow, arcade optimism, sci-fi nostalgia |
+| **Luxury modern** | The product needs premium restraint | Selective ornament, wide spacing, exact finishing |
+| **Collage / handmade** | The user wants warmth and irregularity | Mixed media rhythm, visible craft, controlled imperfection |
+
+## Layout moves
+
+| Move | What it changes |
+|---|---|
+| **Asymmetric composition** | Breaks center-aligned sameness with controlled tension |
+| **Narrative scroll scenes** | Turns long pages into chapters instead of repeated sections |
+| **Experimental navigation** | Allows map-like, layered, or unconventional entry patterns |
+| **Dense mosaic** | Uses varied card scales and collage logic for dashboards or showcases |
+| **Split-screen contrast** | Maintains tension between two persistent visual zones |
+| **Signature hero structure** | Forces a memorable opening move instead of a generic hero |
+
+## Motion directions
+
+| Direction | Best for |
+|---|---|
+| **Restrained microinteractions** | Mature B2B, precise tools, classic systems |
+| **Kinetic typography** | Editorial, launch pages, cinematic brands |
+| **Scroll-driven scenes** | Storytelling pages, showcases, immersive marketing |
+| **View transitions** | App-like navigation continuity, single-page polish |
+| **Cursor-reactive motion** | Experimental / premium interactions with pointer-rich UX |
+| **Gamified feedback** | Playful products, onboarding, consumer-facing experiences |
+
+## Material / texture signals
+
+| Signal | Effect |
+|---|---|
+| **Glass layers** | Depth through substrate and translucency |
+| **Grain / noise** | Breaks sterile smoothness and adds tactility |
+| **Paper / editorial tactility** | Print-inspired warmth and cultural depth |
+| **Chrome / metallic** | Reflective future-luxury finish |
+| **Soft tactile UI** | More touchable, product-like controls |
+| **Collage / cutout** | Handmade, layered, artsy expression |
+
+## Typography moves
+
+| Move | Why it helps |
+|---|---|
+| **Bold display type** | Establishes identity fast |
+| **Variable font axes** | Makes typography itself part of the motion/shape system |
+| **Serif revival** | Adds warmth, authority, or cultural depth |
+| **Mono rails** | Adds technical rhythm and operational precision |
+| **Compressed headlines** | Creates cinematic or editorial drama |
+| **Mixed type system** | Distinguishes roles across hero/body/meta layers |
+
+## Advanced CSS techniques
+
+Use only when they reinforce the chosen identity:
+
+- **Scroll-driven animations** — scene logic tied to progress, not generic reveal-once behavior
+- **View Transition API** — continuity between states/routes
+- **Masks / clip-path** — non-rectangular reveals, ornamental cuts, unusual framing
+- **SVG filters / noise** — texture, distortion, displacement, controlled grit
+- **Backdrop filters** — glass depth and layered translucency
+- **3D transforms** — perspective, stacked depth, immersive hero moments
+- **Sticky storytelling** — pinned chapters and staged reveals
+
+## Anti-sameness guardrails
+
+Pick at least 2 and enforce them:
+
+- No generic centered SaaS hero
+- At least one uneven rhythm move
+- At least one domain-specific ornament or motif
+- At least one unmistakable surface treatment
+- Motion must communicate meaning, not filler
+- Typography must do more than label content
+
+---
+
+## Implementation rule
+
+The variation overlay modifies the hybrid's **expression**, not its **core DNA**.
+
+Priority order:
+1. Primary parents define substrate and structure
+2. Variation overlay defines expression and anti-sameness pressure
+3. Modifiers, if any, stay inside their narrow lane
+
+---
+
+## Current source scan
+
+- Figma resource library on current web design directions:
+  https://www.figma.com/resource-library/web-design-trends/
+- Webflow on variable fonts as active web typography tooling:
+  https://help.webflow.com/hc/en-us/articles/33961307448979-Variable-fonts
+- web.dev on same-document view transitions entering Baseline on October 16, 2025:
+  https://web.dev/blog/same-document-view-transitions-are-now-baseline-newly-available
+- web.dev coverage of Interop 2026, including scroll-driven animations:
+  https://web.dev/blog/interop-2026?hl=en

package/template/AGENTS.md

@@ -16,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`, `@deyvin`, `@dev`, `@squad`, `@genome`, `@profiler-researcher`
+Examples: `@setup`, `@deyvin`, `@dev`, `@squad`, `@genome`, `@profiler-researcher`, `@design-hybrid-forge`
 
 **Option 2 — Natural language:**
 Describe your intent. The agent system will match and execute.
@@ -40,6 +40,7 @@ Describe your intent. The agent system will match and execute.
 | @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" |
+| @design-hybrid-forge | "create hybrid design skill", "combine two design skills", "use the design-hybrid-forge agent" |
 
 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.
@@ -90,6 +91,27 @@ When running Codex directly (without `aioson workflow:next`), these rules apply:
 - @profiler-researcher → `.aioson/agents/profiler-researcher.md`
 - @profiler-enricher → `.aioson/agents/profiler-enricher.md`
 - @profiler-forge → `.aioson/agents/profiler-forge.md`
+- @design-hybrid-forge → `.aioson/agents/design-hybrid-forge.md`
+
+## Process skill: aioson-spec-driven
+
+Located at: `.aioson/skills/process/aioson-spec-driven/SKILL.md`
+
+This is a first-party process skill. It teaches agents how phases connect, when to apply which depth, and how to prepare clean handoffs.
+
+Agents that load it: @product, @analyst, @architect, @sheldon, @dev, @deyvin
+When to load: at the start of any spec work (PRD, requirements, architecture, implementation)
+What to load: `SKILL.md` first, then only the `references/` file relevant to the current phase
+
+## Process skill: design-hybrid-forge
+
+Located at: `.aioson/skills/process/design-hybrid-forge/SKILL.md`
+
+This is a first-party process skill for generating project-local hybrid design skills from 2 primary design parents.
+
+Activated by: @design-hybrid-forge
+Default output: `.aioson/installed-skills/{hybrid-name}/`
+What to load: `SKILL.md` first, then only the `references/` file relevant to the current phase
 
 ## Session protocol
 If `.aioson/context/spec.md` exists, read it at session start and update it at session end.

package/template/CLAUDE.md

@@ -31,6 +31,7 @@ You operate as AIOSON.
 - /profiler-researcher -> `.aioson/agents/profiler-researcher.md`
 - /profiler-enricher -> `.aioson/agents/profiler-enricher.md`
 - /profiler-forge -> `.aioson/agents/profiler-forge.md`
+- /design-hybrid-forge -> `.aioson/agents/design-hybrid-forge.md`
 
 ## Workflow enforcement