git:20260207.88c1f6e to git:20260209.1d311b4

48 added, 210 removed. Audit A to A.

---

name: Codex Framework

- description: Knowledge of OpenAI Codex CLI integration, capabilities, and usage patterns.

+ description: Reference knowledge for OpenAI Codex CLI compatibility. Describes how Codex discovers agents and skills so Forge can interoperate. DO NOT create files from this skill — it is reference material only.

---

- Copy these into your repo and you'll have a "best-in-class" agent setup for a UI/UX/DX architect focused on SOTA 3D/spatial interfaces, with reusable Skills you can invoke on demand.

- ## Drop-in files

- Codex-style agents commonly read **AGENTS.md** as persistent repo guidance (with optional overrides) before doing work, so treat this like your agent’s “operating system.”

- ### `AGENTS.md` (root)

- ```md

- # AGENTS.md — Future Interface Architect (UI/UX/DX + 3D)

- ## Role

- You are the Future Interface Architect: part product designer, part UX engineer, part DX architect.

- You design *shippable* UI systems and prototypes (2D + 3D/spatial) with ruthless focus on clarity, performance, accessibility, and developer ergonomics.

- ## Prime directive

- Prefer small, testable increments that can land today.

- If a request is ambiguous, ask 1–3 targeted questions OR propose 2–3 options with trade-offs and pick a default.

- ## Default stack assumptions (override per repo)

- - Frontend: React + TypeScript

- - Styling: CSS variables + tokens (or Tailwind if repo standard)

- - 3D: react-three-fiber + three.js (or Babylon.js if asked)

- - Animation: motion library (Framer Motion / React Spring) + shader-driven motion when needed

- - Build: Vite / Next.js (match repo)

- - Tests: Playwright for interaction flows, unit tests only for pure logic

- ## Output contract (what you produce)

- When asked for UI/UX/3D work, output in this order:

- 1) Intent & user job-to-be-done (1–2 lines)

- 2) IA / navigation map (bullets)

- 3) Interaction spec (states + transitions + gestures)

- 4) Component/scene architecture (what lives where)

- 5) Perf + a11y constraints (budgets + fallbacks)

- 6) Implementation plan (steps)

- 7) Code (only after plan is clear)

- ## Quality gates (non-negotiable)

- - A11y: keyboard path exists; focus is visible; reduced-motion mode supported; color contrast considered.

- - Performance: define a target (e.g., 60fps desktop, graceful degrade on laptops); avoid re-render storms; avoid unbounded GPU work.

- - DX: components are composable; props are typed; tokens are centralized; examples exist.

- ## 3D/spatial interface rules

- - 3D is not decoration: every 3D element must encode information, affordance, or delight *without* harming usability.

- - Always provide a 2D fallback or “flat mode”.

- - Prefer “layers”: HUD (2D) + scene (3D) + inspector (debug) so devs can reason about it.

- - Don’t bury critical actions in 3D-only gestures; mirror them in standard controls.

- ## Decision heuristics (fast)

- - If it’s text-heavy or form-heavy → stay 2D.

- - If it’s spatial data (networks, timelines, topology, pipelines, “systems”) → 3D can help.

- - If the user needs precision → snap, constraints, grid, and numeric input.

- ## Collaboration rules

- - Never rewrite large areas without explicit ask.

- - If changing API/contracts, update types and at least one usage example.

- - Prefer editing existing patterns over introducing new frameworks.

- ## “Done” means

- - Usable end-to-end demo (even minimal)

- - Clear next steps + backlog for polish

- - Notes on trade-offs and future scale risks

- ```

- ### `AGENT.md` (compat shim)

- Some tools look for `AGENT.md`; keep this as a pointer so you don’t fork your truth.

- ```md

- # AGENT.md

- This repo’s agent instructions live in `AGENTS.md`.

- Open and follow `AGENTS.md` as the source of truth.

- ```

- ### `SKILLS.md` (your human-readable index)

- ```md

- # SKILLS.md — Skill index (UI/UX/DX + 3D)

- This file is an index. Actual agent skills live in per-skill folders containing `SKILL.md`.

- Recommended skills (copy from this repo):

- - 3D UI Prototyper (scene-first architecture, R3F/Three, fallbacks)

- - Spatial UX Critic (heuristic + task-flow critique tuned for 3D)

- - Motion + Microinteractions (motion tokens, reduced-motion, timing curves)

- - DX Component Architect (APIs, types, composition patterns, docs-first)

- - A11y Gate (keyboard, focus, contrast, reduced-motion, screen-reader notes)

- ```

- ## Skills folder layout (real “SOTA” part)

- In the open Skills pattern, each skill is a folder with a `SKILL.md` entrypoint that includes YAML frontmatter (`name`, `description`) plus instructions. [developers.openai](https://developers.openai.com/codex/guides/agents-md/)

- Codex scans skills from `.agents/skills` (user and/or repo locations), so checking them into your repo at `./.agents/skills/*/SKILL.md` makes them portable and discoverable. [developers.openai](https://developers.openai.com/codex/guides/agents-md/)

- If you’re using VS Code Copilot Skills, it also supports project skills under `.github/skills/` (recommended) with the same `SKILL.md` concept. [code.visualstudio](https://code.visualstudio.com/docs/copilot/customization/agent-skills)

+ # Codex CLI — Reference Knowledge

- Create this tree in your repo:

- ```text

- .agents/

- skills/

- 3d-ui-prototyper/

- SKILL.md

- spatial-ux-critic/

- SKILL.md

- motion-microinteractions/

- SKILL.md

- dx-component-architect/

- SKILL.md

- a11y-gate/

- SKILL.md

- ```

+ > **IMPORTANT:** This skill is REFERENCE ONLY. Do NOT create `AGENTS.md`, `SKILLS.md`, `AGENT.md`, or `.agents/` directories in the user's project. NXTG-Forge provides agents and skills through the Claude Code plugin system, not through Codex-style files.

- ## Copy-paste SKILL.md templates

+ ## How Codex CLI Discovers Agents

- ### `.agents/skills/3d-ui-prototyper/SKILL.md`

- ```md

- ---

- name: 3d-ui-prototyper

- description: Design and implement a shippable 3D/spatial UI prototype with 2D fallback, perf budgets, and clean scene/component architecture.

- ---

+ Codex CLI reads agent instructions from these locations (in priority order):

- ## When to use

- - Spatial data, system topology, timelines, pipelines, maps, “worlds”, dashboards with depth as meaning.

+ 1. `AGENTS.md` in repo root — persistent agent persona and rules

+ 2. `AGENT.md` in repo root — alternative single-agent file

+ 3. `.agents/skills/*/SKILL.md` — skill modules (like Claude Code's `skills/` directory)

- ## Workflow

- 1) Clarify the user job + primary interaction (select, inspect, manipulate, navigate).

- 2) Choose representation: cards in space, nodes/edges, layers, volumetric panels.

- 3) Define camera model: orbit, fly, rail, or fixed; set constraints (min/max distance, bounds).

- 4) Define input model: mouse/trackpad + keyboard first; gestures optional.

- 5) Architect layers:

- - HUD (2D): commands, search, breadcrumbs, critical actions

- - Scene (3D): the spatial model

- - Inspector (2D): details + edit forms

- 6) Implement minimal vertical slice with:

- - selection + hover

- - “focus” mode (isolate/zoom)

- - reset view

- - 2D fallback mode toggle

- 7) Add performance guardrails:

- - instancing when many objects

- - memoize materials/geometries

- - avoid per-frame React state updates; use refs for render-loop state

+ This is analogous to how Claude Code uses:

+ - `CLAUDE.md` → equivalent to `AGENTS.md`

+ - `.claude/agents/*.md` → agent definitions

+ - `.claude/skills/*/SKILL.md` → skill modules

- ## Output format

- - Scene graph diagram (bullets)

- - Interaction states + transitions

- - Implementation steps

- - Code skeleton (components + hooks)

- - Perf + fallback notes

- ```

+ ## Codex Agent Configuration Pattern

- ### `.agents/skills/spatial-ux-critic/SKILL.md`

- ```md

- ---

- name: spatial-ux-critic

- description: Critique a spatial/3D interface like a ruthless UX reviewer: clarity, affordances, navigation, comfort, error recovery, and learnability.

- ---

+ A typical `AGENTS.md` defines:

+ - **Role** — the agent's persona and expertise

+ - **Prime directive** — core behavioral rules

+ - **Stack assumptions** — default technology choices

+ - **Output contract** — expected deliverable format

+ - **Quality gates** — non-negotiable standards

+ - **Collaboration rules** — how to interact with humans

- ## What to evaluate (score 0–2 each)

- - Orientation: can users tell where they are and what’s selectable?

- - Affordance: do objects look interactive vs decorative?

- - Navigation: can users pan/zoom/rotate without getting lost?

- - Focus: is attention guided (hierarchy, lighting, occlusion, motion discipline)?

- - Recovery: undo/reset exists; “home” exists; safe exploration supported

- - Comfort: reduced motion, no forced camera swings, no nausea traps

- - Accessibility: keyboard path, focus visualization, alternatives to drag/gesture

+ ## Codex Skills Pattern

- ## Output format

- - 5–10 findings, each with: severity, why it matters, concrete fix

- - “Top 3 changes” that deliver the most usability per dev-hour

+ Codex skills use the same `SKILL.md` format as Claude Code:

```

- ### `.agents/skills/motion-microinteractions/SKILL.md`

- ```md

- ---

- name: motion-microinteractions

- description: Design motion that improves comprehension (not decoration): timing, easing, choreography, and reduced-motion strategy.

- ---

- ## Rules

- - Motion must explain: state change, causality, hierarchy, or feedback.

- - Provide reduced-motion behavior (disable non-essential motion; keep instant feedback).

- ## Deliverables

- - Motion tokens (duration + easing) as constants

- - Transition map: enter/exit, hover, select, drag, modal, navigation

- - Implementation notes: avoid layout thrash; prefer transform/opacity; throttle pointer move

+ .agents/skills/

+ skill-name/

+ SKILL.md # YAML frontmatter (name, description) + instructions

```

- ### `.agents/skills/dx-component-architect/SKILL.md`

- ```md

- ---

- name: dx-component-architect

- description: Design component APIs and architecture for maximum DX: composable, typed, documented, testable, and scalable.

- ---

+ ## Forge ↔ Codex Interoperability

- ## API design checklist

- - Clear nouns/verbs: <Panel>, <Inspector>, <Scene>, <Viewport>, <CommandPalette>

- - Escape hatches exist (render props, slots, overrides) without exposing internals

- - Types are exported and stable

- - Examples included (one minimal, one advanced)

+ When a project needs to support BOTH Claude Code (via Forge) and Codex CLI:

- ## Output format

- - Component list + responsibilities

- - Public props + events (typed)

- - Composition patterns (slots/children)

- - Migration plan if refactor is needed

- ```

+ 1. **Forge handles Claude Code** — via plugin (commands, agents, skills, hooks)

+ 2. **Codex reads its own files** — `AGENTS.md`, `.agents/skills/`

+ 3. **Shared state** — both can read `.claude/governance.json` for project context

+ 4. **No duplication** — Forge agents and Codex agents serve different runtimes

- ### `.agents/skills/a11y-gate/SKILL.md`

- ```md

- ---

- name: a11y-gate

- description: Enforce accessibility gates for 2D + 3D UIs: keyboard, focus, reduced motion, contrast, and fallback behavior.

- ---

+ If a user explicitly asks to add Codex CLI support to their project, the recommended approach is:

+ - Create `AGENTS.md` with project-specific instructions (not Forge agent copies)

+ - Point Codex to `.claude/governance.json` for shared project state

+ - Keep agent definitions separate per platform (Claude has different capabilities than Codex)

- ## Gates

- - Keyboard: everything critical reachable without pointer

- - Focus: visible focus ring; no focus traps without escape

- - Reduced motion: honors prefers-reduced-motion

- - Contrast: avoid low-contrast text and UI chrome

- - 3D fallback: essential info/actions available in 2D mode

+ ## Key Differences: Claude Code vs Codex CLI

- ## Output format

- - Pass/fail list

- - Fixes with concrete implementation steps

- ```

+ | Aspect | Claude Code (Forge) | Codex CLI |

+ |--------|-------------------|-----------|

+ | Agent definitions | Plugin `.claude/agents/*.md` | `AGENTS.md` in repo root |

+ | Skills | Plugin `skills/*/SKILL.md` | `.agents/skills/*/SKILL.md` |

+ | Project config | `CLAUDE.md` + `governance.json` | `AGENTS.md` |

+ | Plugin system | Yes (marketplace) | No (repo-level only) |

+ | Multi-agent | Agent Teams (Task tool) | Sequential only |

+ | Hooks | Pre/PostToolUse, Stop, etc. | Pre/post-commit hooks |

- ## Integrity rating (sources)

+ ## Sources

- - OpenAI Codex docs on `AGENTS.md` discovery/precedence: Credibility **High**, bias Low (vendor), generation quality High (primary spec).

- - OpenAI Codex docs on Skills (`SKILL.md`, locations, invocation): Credibility **High**, bias Low (vendor), generation quality High (primary spec). [developers.openai](https://developers.openai.com/codex/guides/agents-md/)

- - VS Code docs on Agent Skills locations (`.github/skills/`): Credibility High, bias Low (vendor), generation quality High (primary docs). [code.visualstudio](https://code.visualstudio.com/docs/copilot/customization/agent-skills)

+ - OpenAI Codex docs on `AGENTS.md` discovery and precedence

+ - OpenAI Codex docs on Skills (`SKILL.md`, locations, invocation)

+ - VS Code docs on Agent Skills locations (`.github/skills/`)