Add Design Genome for divergent frontend art direction

README.md

@@ -45,6 +45,7 @@ flowchart LR
 | Scoped guidance | `*/AGENTS.md.template` | Folder-specific rules for frontend, backend, tests, ops, and more |
 | Project config | [`.codex/config.toml.template`](.codex/config.toml.template) | Safe, repo-scoped Codex defaults |
 | Automatic setup | [`skills/bootstrap-project/`](skills/bootstrap-project/) | Inspect, prepare, validate, then continue the original task |
+| Design Genome | [`skills/frontend-divergence/`](skills/frontend-divergence/) | Explore distinct art directions before frontend implementation |
 | Model strategy | [`CODEX_COST_AND_SAFETY_POLICY.md`](CODEX_COST_AND_SAFETY_POLICY.md) | Match capability and reasoning to task value |
 | Task workflows | [`CODEX_TASK_PROMPT_LIBRARY.md`](CODEX_TASK_PROMPT_LIBRARY.md) | Reusable implementation, debugging, research, and review prompts |
 | Quality gates | [`CODEX_PR_REVIEW_GUIDELINES.md`](CODEX_PR_REVIEW_GUIDELINES.md) | Review behavior and evidence requirements |
@@ -60,24 +61,32 @@ cd codex-flightdeck
 python scripts/validate.py
 ```
 
-### 2. Install the bootstrap skill
+### 2. Install the skills
 
 macOS/Linux:
 
 ```bash
 mkdir -p ~/.codex/skills
 cp -R skills/bootstrap-project ~/.codex/skills/bootstrap-project
+cp -R skills/frontend-divergence ~/.codex/skills/frontend-divergence
 ```
 
 PowerShell:
 
 ```powershell
 New-Item -ItemType Directory -Force "$HOME\.codex\skills" | Out-Null
 Copy-Item -Recurse .\skills\bootstrap-project "$HOME\.codex\skills\bootstrap-project"
+Copy-Item -Recurse .\skills\frontend-divergence "$HOME\.codex\skills\frontend-divergence"
 ```
 
 Restart Codex or start a new task so the skill list refreshes.
 
+`frontend-divergence` triggers for greenfield websites and visually significant
+redesigns. It generates structurally different directions, selects one design
+contract, and then hands that contract to the applicable frontend or taste
+skill. Invoke `$frontend-divergence` explicitly when a brief needs unusually
+high creative range.
+
 ### 3. Merge personal guidance
 
 Review [`GLOBAL_AGENTS.md.template`](GLOBAL_AGENTS.md.template), then merge the sections you want into `~/.codex/AGENTS.md`. Do not blindly replace an existing personal file.

scripts/validate.py

@@ -22,6 +22,10 @@
     ".codex/config.toml.template",
     "skills/bootstrap-project/SKILL.md",
     "skills/bootstrap-project/agents/openai.yaml",
+    "skills/frontend-divergence/SKILL.md",
+    "skills/frontend-divergence/agents/openai.yaml",
+    "skills/frontend-divergence/scripts/direction_lab.py",
+    "skills/frontend-divergence/references/creative-mechanics.md",
 )
 
 PUBLIC_RISK_PATTERNS = {
@@ -39,7 +43,11 @@ def text_files() -> list[Path]:
     return [
         path
         for path in ROOT.rglob("*")
-        if path.is_file() and ".git" not in path.parts and path.name != "LICENSE"
+        if path.is_file()
+        and ".git" not in path.parts
+        and "__pycache__" not in path.parts
+        and path.suffix != ".pyc"
+        and path.name != "LICENSE"
     ]
 
 
@@ -76,16 +84,28 @@ def validate_toml(errors: list[str]) -> None:
         errors.append(f"invalid TOML in {path.relative_to(ROOT)}: {exc}")
 
 
-def validate_skill(errors: list[str]) -> None:
-    path = ROOT / "skills" / "bootstrap-project" / "SKILL.md"
-    if not path.is_file():
-        return
-    content = path.read_text(encoding="utf-8")
-    if not content.startswith("---\n"):
-        errors.append("bootstrap skill is missing YAML frontmatter")
-    for field in ("name:", "description:"):
-        if field not in content.split("---", 2)[1]:
-            errors.append(f"bootstrap skill frontmatter is missing {field}")
+def validate_skills(errors: list[str]) -> None:
+    for directory in sorted((ROOT / "skills").iterdir()):
+        if not directory.is_dir():
+            continue
+        path = directory / "SKILL.md"
+        if not path.is_file():
+            errors.append(f"skill is missing SKILL.md: {directory.name}")
+            continue
+        content = path.read_text(encoding="utf-8")
+        if not content.startswith("---\n") or content.count("---") < 2:
+            errors.append(f"{directory.name} skill is missing YAML frontmatter")
+            continue
+        frontmatter = content.split("---", 2)[1]
+        for field in ("name:", "description:"):
+            if field not in frontmatter:
+                errors.append(f"{directory.name} skill frontmatter is missing {field}")
+        if f"name: {directory.name}\n" not in frontmatter:
+            errors.append(f"skill name does not match folder: {directory.name}")
+        if re.search(r"\[TODO|\bTODO:", content):
+            errors.append(f"unfinished TODO in skill: {directory.name}")
+        if not (directory / "agents" / "openai.yaml").is_file():
+            errors.append(f"skill is missing agents/openai.yaml: {directory.name}")
 
 
 def validate_markdown_links(errors: list[str]) -> None:
@@ -112,7 +132,7 @@ def main() -> int:
     validate_required(errors)
     validate_utf8_and_public_content(errors)
     validate_toml(errors)
-    validate_skill(errors)
+    validate_skills(errors)
     validate_markdown_links(errors)
 
     if errors:

skills/frontend-divergence/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: frontend-divergence
+description: Use before implementing a greenfield website, landing page, campaign page, portfolio, brand site, or visually significant redesign when Codex must avoid repeating familiar AI layouts and create a distinctive, brief-fit art direction. Generate and compare structurally different concepts, select one design contract, then hand it to the implementation or taste skill. Do not use for exact Figma/screenshot reproduction, routine product UI maintenance, or small component edits.
+---
+
+# Frontend Divergence: Design Genome
+
+Create difference before polishing quality. Existing frontend and taste skills
+may converge on good execution; this skill owns exploration and selection.
+
+## 1. Establish The Design Problem
+
+Extract these inputs from the brief and repository without asking unless a
+material decision is genuinely missing:
+
+- audience, desired action, and emotional effect;
+- content shape and strongest real asset;
+- brand constraints and existing visual equity;
+- accessibility, performance, framework, and delivery constraints;
+- designs from this repo or prior context that must not be repeated.
+
+Write a compact `Design premise` containing the user tension, visual
+opportunity, and one non-negotiable. Do not name a trendy style yet.
+
+## 2. Generate A Direction Slate
+
+Run the bundled engine before writing production UI:
+
+```bash
+python <skill-dir>/scripts/direction_lab.py generate \
+  --project "<project identifier>" \
+  --brief "<design premise and constraints>" \
+  --count 4
+```
+
+The engine uses a morphological matrix and past fingerprints to maximize
+structural distance. It is a provocation tool, not an aesthetic authority.
+Read `references/creative-mechanics.md` when adjusting the matrix, judging
+novelty, or explaining why this process exists.
+
+Turn each generated fingerprint into a short concept with:
+
+- thesis: the single visual idea;
+- first viewport: concrete composition, hierarchy, and media behavior;
+- system: type, color, surface, spatial rhythm, and motion grammar;
+- signature moment: one interaction or composition specific to this project;
+- risk: what could become gimmicky, inaccessible, or off-brief;
+- anti-reference: which familiar solution this direction refuses to become.
+
+Do not produce four recolors of one wireframe. Concepts must differ in at least
+five matrix axes, including composition and one of media or interaction.
+
+When web or image search is available and visual originality is important,
+triangulate only after generating the slate: inspect one same-domain reference,
+one adjacent-domain reference, and one far-domain reference. Extract a property
+from each (rhythm, crop, type behavior, material, or interaction), state what
+must not be copied, and contextualize it against the actual brief.
+
+## 3. Select, Do Not Average
+
+Score every concept from 1-5 on:
+
+- brief fit;
+- distinctiveness from recent work;
+- content truthfulness;
+- implementation feasibility;
+- accessibility and responsive resilience.
+
+Choose one direction and state why. You may transplant one strong trait from a
+runner-up only when it strengthens the thesis. Never average all directions
+into a generic compromise.
+
+If the top two are close and the choice materially changes the product, show
+the two concise options to the user. Otherwise choose autonomously.
+
+## 4. Freeze A Design Contract
+
+Before implementation, write a `Design contract` with exact decisions:
+
+- selected fingerprint and concept name;
+- layout grammar and responsive transformation;
+- type roles and scale behavior;
+- color/material rules;
+- image or illustration logic;
+- motion grammar and reduced-motion behavior;
+- three forbidden defaults for this project;
+- the signature moment and its fallback;
+- quality checks that prove the concept survived implementation.
+
+The contract overrides aesthetic defaults from other skills when they conflict.
+It never overrides accessibility, semantics, performance, existing brand
+requirements, or explicit user constraints.
+
+## 5. Implement And Challenge The Result
+
+Hand the contract to the applicable frontend, taste, image-generation, or UI
+skill. Preserve the chosen structure instead of letting implementation drift
+back to a centered hero, card grid, pills, generic gradient, or familiar
+fade-up sequence.
+
+At the first complete viewport and again before delivery, run a divergence
+check:
+
+1. Compare the result with the contract, not only with code quality rules.
+2. Identify the three most template-like decisions still visible.
+3. Replace at least one if it weakens the project-specific thesis.
+4. Verify mobile, keyboard, contrast, reduced motion, and content realism.
+5. Confirm that removing the logo would not make the page interchangeable with
+   an unrelated recent project.
+
+## 6. Record The Selected Fingerprint
+
+After the direction is selected, record the generated code shown in the slate:
+
+```bash
+python <skill-dir>/scripts/direction_lab.py record \
+  --project "<project identifier>" \
+  --direction "<concept name>" \
+  --code "<record code>"
+```
+
+The default user-level history stores a hash of the project identifier, not the
+project name. Use `--history <path>` when isolation or team sharing is needed.

skills/frontend-divergence/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Design Genome"
+  short_description: "Break repeated frontend design defaults"
+  default_prompt: "Use $frontend-divergence to explore genuinely different design directions before implementing this website."

skills/frontend-divergence/references/creative-mechanics.md

@@ -0,0 +1,51 @@
+# Creative Mechanics
+
+## Why This Skill Adds Friction
+
+Generative systems tend to reproduce dominant conventions. Microsoft Research
+describes productive friction as a mitigation for homogenization in web vibe
+coding. Experimental work on generative-AI-assisted ideation has also found
+greater fixation on initial examples and lower idea variety in some settings.
+
+This skill therefore separates divergence from implementation. It delays code,
+decomposes art direction into independent axes, creates distant combinations,
+and requires an explicit selection before quality-oriented skills converge.
+
+## Morphological Exploration
+
+The direction engine combines independent choices for composition, hero
+behavior, typography, media, color, surface, navigation, motion, and signature
+detail. Morphological charts are established tools for widening a design
+solution space, but combinations are prompts for judgment rather than answers.
+
+Use the engine to expose different regions of the space. Then judge each region
+against the real audience, content, brand, accessibility, and delivery context.
+Do not mistake random difference for useful originality.
+
+## Example Hygiene
+
+Examples can inspire or fixate. Research comparing example interfaces found
+that contextualizing examples in the problem space supported exploration better
+than presenting a flat list. Therefore:
+
+- analyze references by transferable property, not by copying whole pages;
+- mix near and far references from different domains;
+- state what each reference teaches and what must not be copied;
+- introduce screenshots after the design premise, not before it;
+- compare concepts in the context of the actual content and viewport.
+
+## Divergence Threshold
+
+Treat directions as distinct only when they differ on at least five axes. A
+palette swap, font swap, or reordered card grid is not a new direction.
+Composition plus either media logic or interaction grammar must change.
+
+Novelty is bounded by truthfulness: the direction must still communicate the
+right action, support real content, work responsively, and remain accessible.
+
+## Sources
+
+- [Interrogating Design Homogenization in Web Vibe Coding](https://www.microsoft.com/en-us/research/publication/interrogating-design-homogenization-in-web-vibe-coding/)
+- [The Effects of Generative AI on Design Fixation and Divergent Thinking](https://arxiv.org/abs/2403.11164)
+- [Formulating or Fixating: Effects of Examples on Problem Solving](https://arxiv.org/abs/2401.11022)
+- [Design Divergence Using the Morphological Chart](https://openjournals.ljmu.ac.uk/DesignTechnologyEducation/article/view/1474)