feat: add Codex app support

.gitignore

@@ -16,6 +16,9 @@ Thumbs.db
 .vscode/
 .idea/
 
+# Local AI harness config generated for Codex app development
+.agents/
+
 # Environment
 .env
 .env.local

AGENTS.md

@@ -1,6 +1,6 @@
 # Impeccable
 
-The vocabulary you didn't know you needed. 1 skill, 20 commands, and curated anti-patterns for impeccable style. Works with Cursor, Claude Code, Gemini CLI, and Codex CLI.
+The vocabulary you didn't know you needed. 1 skill, 20 commands, and curated anti-patterns for impeccable style. Works with Cursor, Claude Code, Gemini CLI, Codex app, Codex CLI, and other Agent Skills consumers.
 
 ## Repository Purpose
 
@@ -12,13 +12,13 @@ We use a **feature-rich source format** that gets transformed for each provider:
 
 - **Source files** (`source/`): Full metadata with YAML frontmatter, args, descriptions
 - **Build system** (`scripts/`): Transforms source → provider-specific formats
-- **Distribution** (`dist/`): Committed output files for 4 providers
+- **Distribution** (`dist/`): Generated output files for 9 providers
 
 ### Why Option A?
 
 Cursor doesn't support frontmatter or arguments (lowest common denominator). Instead of limiting all providers, we:
 1. Author with full metadata in source files
-2. Generate full-featured versions for providers that support it (Claude Code, Gemini, Codex)
+2. Generate full-featured or provider-tuned versions for providers that support it (Claude Code, Gemini, Codex CLI, Codex app)
 3. Generate downgraded versions for Cursor (strip frontmatter, rely on appending)
 
 ## Repository Structure
@@ -185,6 +185,13 @@ Run: `bun run build`
   - Reference files in skill subdirectories
 - **Installation**: Extract ZIP into your project root, creates `.codex/` folder
 
+### 5. Codex app
+- **Skills**: Agent Skills standard → `dist/codex-app/.agents/skills/{name}/SKILL.md`
+  - Same `.agents` search path Codex app uses inside the project tree
+  - Uses Codex-oriented placeholder rendering (`AGENTS.md`, `GPT`)
+  - User-invokable skills stay available from the slash-command picker
+- **Installation**: Copy `.agents/` into your project root
+
 ## Key Design Decisions
 
 ### Why commit dist/?
@@ -225,7 +232,7 @@ End users can copy files directly without needing build tools.
 ## Important Notes
 
 - **Source is truth**: Always edit `source/`, never edit `dist/` directly
-- **Test across providers**: Changes affect 4 different outputs
+- **Test across providers**: Changes affect 9 different outputs
 - **Argument handling**: Write prompts that work with both placeholders and appending
 - **Cursor limitations**: No frontmatter/args, so design for graceful degradation
 
@@ -245,6 +252,7 @@ End users can copy files directly without needing build tools.
 - [Anthropic Skills](https://github.com/anthropics/skills)
 - [Gemini CLI Custom Commands](https://cloud.google.com/blog/topics/developers-practitioners/gemini-cli-custom-slash-commands)
 - [Gemini CLI GEMINI.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/gemini-md.md)
+- [Codex app overview](https://developers.openai.com/codex/using-codex/app/overview)
+- [Codex AGENTS.md](https://developers.openai.com/codex/configuration/agents-md)
+- [Codex skills](https://developers.openai.com/codex/configuration/skills)
 - [Codex CLI Slash Commands](https://developers.openai.com/codex/guides/slash-commands)
-- [Codex CLI Skills](https://developers.openai.com/codex/skills/)
-

DEVELOP.md

@@ -10,7 +10,7 @@ This repository uses a **feature-rich source format** that transforms into provi
 
 Different providers have different capabilities:
 - **Claude Code, OpenCode**: Full metadata — args, user-invokable, allowed-tools, license, compatibility
-- **Codex, Agents**: Args converted to `argument-hint` format
+- **Codex CLI, Codex app, Agents**: Args converted to `argument-hint` format
 - **Gemini**: Minimal frontmatter, `{{arg}}` placeholders become `{{args}}`
 - **Cursor, Kiro, Pi**: Basic frontmatter (name, description, license/compatibility)
 
@@ -73,6 +73,7 @@ source/                          → dist/
                                    claude-code/.claude/skills/{name}/SKILL.md
                                    gemini/.gemini/skills/{name}/SKILL.md
                                    codex/.codex/skills/{name}/SKILL.md
+                                   codex-app/.agents/skills/{name}/SKILL.md
                                    agents/.agents/skills/{name}/SKILL.md
                                    kiro/.kiro/skills/{name}/SKILL.md
                                    opencode/.opencode/skills/{name}/SKILL.md
@@ -108,9 +109,16 @@ All providers output skills to `dist/{provider}/.{config}/skills/{name}/SKILL.md
 - Frontmatter: name, description, argument-hint, license
 - For user-invokable skills: `{{argname}}` → `$ARGNAME` (uppercase)
 
+### Codex app
+- Output: `dist/codex-app/.agents/skills/{name}/SKILL.md`
+- Frontmatter: name, description, user-invokable, argument-hint
+- Project-local install for the Codex desktop app via `.agents/skills`
+- Uses Codex-oriented placeholders (`AGENTS.md`, `GPT`) in rendered bodies
+
 ### Agents (VS Code Copilot, Antigravity)
 - Output: `dist/agents/.agents/skills/{name}/SKILL.md`
 - Frontmatter: name, description, user-invokable, argument-hint
+- Shared `.agents` format used by VS Code Copilot and Antigravity
 - Args converted to `argument-hint` format (e.g., `<target> [FORMAT=<value>]`)
 
 ### Kiro
@@ -138,7 +146,7 @@ Add frontmatter and content following the format above.
 bun run build
 ```
 
-This generates all 8 provider formats automatically.
+This generates all 9 provider formats automatically.
 
 ### 3. Test
 
@@ -159,7 +167,7 @@ The build system uses a modular architecture under `scripts/`:
 - `build.js` — Main orchestrator
 - `lib/utils.js` — Shared utilities (frontmatter parsing, file I/O, placeholder replacement)
 - `lib/zip.js` — ZIP bundle generation
-- `lib/transformers/*.js` — One file per provider (cursor, claude-code, gemini, codex, agents, kiro, opencode, pi)
+- `lib/transformers/*.js` — One file per provider (cursor, claude-code, gemini, codex, codex-app, agents, kiro, opencode, pi)
 
 ### Key Functions
 
@@ -170,6 +178,7 @@ The build system uses a modular architecture under `scripts/`:
 - `transformClaudeCode()`: Full metadata with args and allowed-tools
 - `transformGemini()`: Minimal frontmatter, `{{arg}}` → `{{args}}`
 - `transformCodex()`: Args → argument-hint, `{{arg}}` → `$ARGNAME`
+- `transformCodexApp()`: Agent Skills output for Codex app in `.agents/skills`
 - `transformAgents()`: Args → argument-hint, user-invokable flag
 - `transformKiro()`: Basic frontmatter with license/compatibility/metadata
 - `transformOpenCode()`: Full metadata (same as Claude Code)
@@ -196,8 +205,10 @@ The build system uses a modular architecture under `scripts/`:
 - [Anthropic Skills (Claude Code)](https://github.com/anthropics/skills)
 - [Gemini CLI Custom Commands](https://cloud.google.com/blog/topics/developers-practitioners/gemini-cli-custom-slash-commands)
 - [Gemini CLI Skills](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/gemini-md.md)
+- [Codex app overview](https://developers.openai.com/codex/using-codex/app/overview)
+- [Codex AGENTS.md](https://developers.openai.com/codex/configuration/agents-md)
+- [Codex skills](https://developers.openai.com/codex/configuration/skills)
 - [Codex CLI Slash Commands](https://developers.openai.com/codex/guides/slash-commands#create-your-own-slash-commands-with-custom-prompts)
-- [Codex CLI Skills](https://developers.openai.com/codex/skills/)
 - [Pi Skills](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/skills.md)
 
 ## Repository Structure
@@ -217,6 +228,7 @@ impeccable/
 │   ├── claude-code/
 │   ├── gemini/
 │   ├── codex/
+│   ├── codex-app/
 │   ├── agents/
 │   ├── kiro/
 │   ├── opencode/
@@ -231,6 +243,7 @@ impeccable/
 │           ├── claude-code.js
 │           ├── gemini.js
 │           ├── codex.js
+│           ├── codex-app.js
 │           ├── agents.js
 │           ├── kiro.js
 │           ├── opencode.js
@@ -262,4 +275,3 @@ impeccable/
 ## Questions?
 
 Open an issue or submit a PR!
-

README.md

@@ -2,7 +2,7 @@
 
 The vocabulary you didn't know you needed. 1 skill, 20 commands, and curated anti-patterns for impeccable frontend design.
 
-> **Quick start:** Visit [impeccable.style](https://impeccable.style) to download ready-to-use bundles.
+> **Quick start:** Visit [impeccable.style](https://impeccable.style) to download ready-to-use bundles for Codex app, Codex CLI, Cursor, Claude Code, Gemini CLI, and more.
 
 ## Why Impeccable?
 
@@ -120,6 +120,13 @@ cp -r dist/gemini/.gemini your-project/
 >
 > [Learn more about Gemini CLI skills](https://geminicli.com/docs/cli/skills/)
 
+**Codex app:**
+```bash
+cp -r dist/codex-app/.agents your-project/
+```
+
+> **Note:** Codex app discovers project skills from `.agents/skills` and reads instructions from `AGENTS.md` in the repo tree.
+
 **Codex CLI:**
 ```bash
 cp -r dist/codex/.codex/* ~/.codex/
@@ -143,10 +150,13 @@ Most commands accept an optional argument to focus on a specific area:
 /polish checkout-form
 ```
 
+**Codex app:** enabled skills are project-local through `.agents/skills`. You can explicitly invoke a skill with `$frontend-design`, and user-invokable skills appear in the slash-command picker.
+
 **Note:** Codex CLI uses a different syntax: `/prompts:audit`, `/prompts:polish`, etc.
 
 ## Supported Tools
 
+- [Codex app](https://developers.openai.com/codex/using-codex/app/overview)
 - [Cursor](https://cursor.com)
 - [Claude Code](https://claude.ai/code)
 - [OpenCode](https://opencode.ai)

lib/download-providers.js

@@ -3,6 +3,7 @@ export const FILE_DOWNLOAD_PROVIDER_CONFIG_DIRS = Object.freeze({
   'claude-code': '.claude',
   gemini: '.gemini',
   codex: '.codex',
+  'codex-app': '.agents',
   agents: '.agents',
   kiro: '.kiro',
   opencode: '.opencode',

public/index.html

@@ -4,15 +4,15 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>Impeccable: The missing upgrade to Anthropic's frontend-design skill</title>
-  <meta name="description" content="1 skill, 20 commands, and curated anti-patterns for impeccable frontend design. Works with Cursor, Claude Code, Gemini CLI, and Codex CLI.">
+  <meta name="description" content="1 skill, 20 commands, and curated anti-patterns for impeccable frontend design. Works with Cursor, Claude Code, Gemini CLI, Codex app, Codex CLI, Copilot, and more.">
   <meta name="theme-color" content="#1a1a1a">
   <link rel="canonical" href="https://impeccable.style">
 
   <!-- OpenGraph -->
   <meta property="og:type" content="website">
   <meta property="og:url" content="https://impeccable.style">
   <meta property="og:title" content="Impeccable: Design skills for AI harnesses">
-  <meta property="og:description" content="1 skill, 20 commands, and curated anti-patterns for impeccable frontend design. Works with Cursor, Claude Code, Gemini CLI, and Codex CLI.">
+  <meta property="og:description" content="1 skill, 20 commands, and curated anti-patterns for impeccable frontend design. Works with Cursor, Claude Code, Gemini CLI, Codex app, Codex CLI, Copilot, and more.">
   <meta property="og:image" content="https://impeccable.style/og-image.jpg">
 
   <!-- Twitter -->
@@ -69,7 +69,7 @@ <h1 class="hero-title-combined">Impeccable</h1>
               <img src="assets/cursor-logo.png" alt="Cursor" width="24" height="24" loading="lazy">
               <img src="assets/claude-logo.png" alt="Claude Code" width="24" height="24" loading="lazy">
               <img src="assets/gemini-logo.png" alt="Gemini CLI" width="20" height="20" loading="lazy">
-              <img src="assets/openai-logo.png" alt="Codex CLI" width="20" height="20" loading="lazy">
+              <img src="assets/openai-logo.png" alt="Codex" width="20" height="20" loading="lazy">
               <img src="assets/github-logo.png" alt="VS Code Copilot" width="20" height="20" loading="lazy">
               <img src="assets/antigravity-logo.png" alt="Antigravity" width="20" height="20" loading="lazy">
               <img src="assets/kiro-logo.png" alt="Kiro" width="20" height="20" loading="lazy">
@@ -250,7 +250,7 @@ <h2 class="section-title">Install</h2>
                   </span>
                 </label>
               </div>
-              <span class="install-terminal-note">Contains all provider directories — extract to project root</span>
+              <span class="install-terminal-note">Contains all provider directories — extract to project root. <code>.agents/</code> works with Codex app, Copilot, and Antigravity.</span>
             </div>
           </div>
         </div>
@@ -273,8 +273,8 @@ <h2 class="section-title">Install</h2>
             <span>Gemini CLI</span>
           </div>
           <div class="install-provider-badge">
-            <img src="assets/openai-logo.png" alt="Codex CLI" width="20" height="20" loading="lazy">
-            <span>Codex CLI</span>
+            <img src="assets/openai-logo.png" alt="Codex" width="20" height="20" loading="lazy">
+            <span>Codex</span>
           </div>
           <div class="install-provider-badge">
             <img src="assets/github-logo.png" alt="VS Code Copilot" width="20" height="20" loading="lazy">
@@ -387,7 +387,8 @@ <h2 class="section-title">Frequently Asked Questions</h2>
           <summary class="faq-question">Where do I put the downloaded files?</summary>
           <div class="faq-answer">
             <p>The easiest way is <code>npx skills add pbakaus/impeccable</code> — it auto-detects your AI harness and places files correctly.</p>
-            <p>If you downloaded the <strong>universal ZIP</strong>, extract it to your <strong>project root</strong> (same level as your <code>package.json</code> or <code>src/</code> folder). It creates hidden folders for each supported tool: <code>.cursor/</code>, <code>.claude/</code>, <code>.gemini/</code>, <code>.codex/</code>, and <code>.agents/</code>.</p>
+            <p>If you downloaded the <strong>universal ZIP</strong>, extract it to your <strong>project root</strong> (same level as your <code>package.json</code> or <code>src/</code> folder). It creates hidden folders for each supported tool: <code>.cursor/</code>, <code>.claude/</code>, <code>.gemini/</code>, <code>.codex/</code>, <code>.agents/</code>, <code>.kiro/</code>, <code>.opencode/</code>, and <code>.pi/</code>.</p>
+            <p><code>.agents/</code> is the shared install target for Codex app, VS Code Copilot, and Antigravity. <code>.codex/</code> is the dedicated install target for Codex CLI.</p>
             <p>Project-level installation takes precedence and lets you version control your skills.</p>
           </div>
         </details>
@@ -413,6 +414,7 @@ <h2 class="section-title">Frequently Asked Questions</h2>
             <ul>
               <li><strong>Cursor:</strong> Requires Nightly channel + Agent Skills enabled in Settings → Rules</li>
               <li><strong>Gemini CLI:</strong> Requires <code>@google/gemini-cli@preview</code> + Skills enabled via <code>/settings</code></li>
+              <li><strong>Codex app:</strong> Reads <code>AGENTS.md</code> plus project-local skills from <code>.agents/skills/</code></li>
             </ul>
           </div>
         </details>
@@ -425,6 +427,7 @@ <h2 class="section-title">Frequently Asked Questions</h2>
               <li><strong>Claude Code:</strong> <a href="https://docs.anthropic.com/en/docs/claude-code" target="_blank" rel="noopener">Official Documentation</a></li>
               <li><strong>Cursor:</strong> <a href="https://docs.cursor.com" target="_blank" rel="noopener">Cursor Docs</a></li>
               <li><strong>Gemini CLI:</strong> <a href="https://geminicli.com/docs/" target="_blank" rel="noopener">Gemini CLI Docs</a></li>
+              <li><strong>Codex app:</strong> <a href="https://developers.openai.com/codex/using-codex/app/overview" target="_blank" rel="noopener">OpenAI Docs</a></li>
               <li><strong>Codex CLI:</strong> <a href="https://github.com/openai/codex" target="_blank" rel="noopener">Codex GitHub</a></li>
             </ul>
             <p>Once you're comfortable with basic prompting and code generation, come back and give Impeccable a try.</p>

scripts/build.js

@@ -8,6 +8,7 @@
  * - Claude Code: .claude/skills/
  * - Gemini: .gemini/skills/
  * - Codex: .codex/skills/
+ * - Codex app: .agents/skills/ (project-local)
  * - Agents: .agents/skills/ (VS Code Copilot + Antigravity)
  *
  * Also assembles a universal ZIP containing all providers,
@@ -23,6 +24,7 @@ import {
   transformClaudeCode,
   transformGemini,
   transformCodex,
+  transformCodexApp,
   transformAgents,
   transformKiro,
   transformOpenCode,
@@ -120,10 +122,17 @@ async function buildStaticSite() {
     return result;
   } catch (error) {
     console.error('Failed to build static site:', error.message);
-    console.error(error.stack);
+    if (error.stack) {
+      console.error(error.stack);
+    } else {
+      console.error(error);
+    }
     if (error.logs) {
       for (const log of error.logs) {
         console.error(log.message || log);
+        if (log.position) {
+          console.error(`  at ${log.position.file}:${log.position.line}:${log.position.column}`);
+        }
       }
     }
     process.exit(1);
@@ -173,7 +182,7 @@ This folder contains skills for all supported tools:
   .claude/    → Claude Code
   .gemini/    → Gemini CLI
   .codex/     → Codex CLI
-  .agents/    → VS Code Copilot, Antigravity
+  .agents/    → Codex app, VS Code Copilot, Antigravity
   .kiro/      → Kiro
   .opencode/  → OpenCode
   .pi/        → Pi
@@ -183,7 +192,7 @@ These are hidden folders (dotfiles) — press Cmd+Shift+. in Finder to see them.
 `);
 
   const label = suffix ? ' (prefixed)' : '';
-  console.log(`✓ Assembled universal${label} directory (${providerMappings.length} providers)`);
+  console.log(`✓ Assembled universal${label} directory (${providerMappings.length} config directories; .agents is shared by Codex app, Copilot, and Antigravity)`);
 }
 
 /**
@@ -345,6 +354,7 @@ async function build() {
   transformClaudeCode(skills, DIST_DIR, patterns);
   transformGemini(skills, DIST_DIR, patterns);
   transformCodex(skills, DIST_DIR, patterns);
+  transformCodexApp(skills, DIST_DIR, patterns);
   transformAgents(skills, DIST_DIR, patterns);
   transformKiro(skills, DIST_DIR, patterns);
   transformOpenCode(skills, DIST_DIR, patterns);
@@ -356,6 +366,7 @@ async function build() {
   transformClaudeCode(skills, DIST_DIR, patterns, prefixOptions);
   transformGemini(skills, DIST_DIR, patterns, prefixOptions);
   transformCodex(skills, DIST_DIR, patterns, prefixOptions);
+  transformCodexApp(skills, DIST_DIR, patterns, prefixOptions);
   transformAgents(skills, DIST_DIR, patterns, prefixOptions);
   transformKiro(skills, DIST_DIR, patterns, prefixOptions);
   transformOpenCode(skills, DIST_DIR, patterns, prefixOptions);
@@ -386,7 +397,18 @@ async function build() {
 
   copyDirSync(skillsSrc, skillsDest);
 
+  // Copy Codex app output to project's .agents directory for local development
+  const codexAppSrc = path.join(DIST_DIR, 'codex-app', '.agents');
+  const codexAppDest = path.join(ROOT_DIR, '.agents');
+  const codexAppSkillsSrc = path.join(codexAppSrc, 'skills');
+  const codexAppSkillsDest = path.join(codexAppDest, 'skills');
+
+  if (fs.existsSync(codexAppSkillsDest)) fs.rmSync(codexAppSkillsDest, { recursive: true });
+
+  copyDirSync(codexAppSkillsSrc, codexAppSkillsDest);
+
   console.log(`📋 Synced to .claude/: skills`);
+  console.log(`📋 Synced to .agents/: skills`);
 
   console.log('\n✨ Build complete!');
 }