ima-claude 2.25.0 → 2.27.0

package/README.md

@@ -2,7 +2,7 @@
 
 FP patterns, architecture guidance, and team standards for AI coding agents.
 
-**Supports Claude Code, Junie CLI, Gemini CLI, and GitHub Copilot** — with an extensible adapter architecture ready for more platforms.
+**Supports Claude Code, Junie CLI, Gemini CLI, GitHub Copilot, and OpenAI Codex CLI** — with an extensible adapter architecture ready for more platforms.
 
 Built by [Independent Medical Alliance](https://imahealth.org) (formerly FLCCC)
 
@@ -38,9 +38,9 @@ claude plugin update ima-claude
 
 Or use `/plugin` inside Claude Code to manage updates interactively via the **Installed** tab.
 
-### Junie CLI / Gemini CLI / GitHub Copilot — Multi-Platform Installer
+### Junie CLI / Gemini CLI / GitHub Copilot / Codex CLI — Multi-Platform Installer
 
-For Junie, Gemini, GitHub Copilot, or any non-plugin platform, use the interactive CLI installer:
+For Junie, Gemini, GitHub Copilot, OpenAI Codex CLI, or any non-plugin platform, use the interactive CLI installer:
 
 ```bash
 npx ima-claude install
@@ -48,7 +48,7 @@ npx ima-claude install
 
 The installer auto-detects which platforms are available and walks you through installation:
 
-1. **Detects platforms** — scans for Claude Code (`~/.claude`), Junie CLI (`~/.junie`), Gemini CLI (`~/.gemini`), and GitHub Copilot (`~/.copilot`)
+1. **Detects platforms** — scans for Claude Code (`~/.claude`), Junie CLI (`~/.junie`), Gemini CLI (`~/.gemini`), GitHub Copilot (`~/.copilot`), and OpenAI Codex CLI (`~/.codex`, or `$CODEX_HOME`)
 2. **Shows preview** — lists all skills, agents, and platform-specific items to install
 3. **Allows exclusions** — skip specific skills or agents you don't need
 4. **Installs with feedback** — step-by-step progress for each item
@@ -59,20 +59,46 @@ You can also target a specific platform directly:
 npx ima-claude install --target junie       # Junie only
 npx ima-claude install --target gemini      # Gemini CLI only
 npx ima-claude install --target gh-copilot  # GitHub Copilot only
+npx ima-claude install --target codex       # OpenAI Codex CLI only
 npx ima-claude install --target claude      # Claude Code only (plugin recommended instead)
 npx ima-claude detect                       # Show detected platforms
 ```
 
+**Tip: Install into a single project instead of globally**
+
+The installer resolves its target paths via `$HOME` (`~/.claude/...`). Override `$HOME` at invocation time to write skills, agents, hooks, and `settings.json` into the current repo's `./.claude/` instead:
+
+```bash
+HOME=$(pwd) npx ima-claude install --target claude
+```
+
+Produces:
+
+```
+./.claude/skills/       # project-scoped skills
+./.claude/agents/       # project-scoped agents
+./.claude/hooks/        # Python hook scripts
+./.claude/settings.json # hook configuration (absolute paths)
+```
+
+Claude Code already reads these as project-scoped config, so the skills/hooks load only when you're working inside that repo.
+
+Caveats:
+
+- The plugin marketplace flow (`/plugin install ima-claude`) remains the recommended path for most users. Use this override only when you want per-repo skill customization without touching your home install.
+- `settings.json` records hook paths as absolute strings resolved at install time — if you rename or move the project, the hook entries break.
+- `HOME=$(pwd)` also redirects npm's cache, so the install may drop a `.npm/` folder in the project root. Add it to `.gitignore` or clean up afterward.
+
 **What's different per platform?**
 
-| | Claude Code | Junie CLI | Gemini CLI | GitHub Copilot |
-|---|---|---|---|---|
-| **Skills** | Plugin system (auto) | Copied to `~/.junie/skills/` | Copied to `~/.gemini/skills/` | Copied to `~/.copilot/skills/` |
-| **Agents** | Plugin system (auto) | Strips `permissionMode` | Strips `model` + `permissionMode`, maps tool names | Strips `model` + `permissionMode`, maps tool names, renames to `.agent.md` |
-| **Hooks** | 24 Python hook scripts | No hook system — behavioral guidelines | Translated events + tool names, translator shim | Translated events + tool names, translator shim, flattened config |
-| **Guidelines** | Plugin's `CLAUDE.md` injection | Generated `AGENTS.md` | Generated `GEMINI.md` | Generated `copilot-instructions.md` |
+| | Claude Code | Junie CLI | Gemini CLI | GitHub Copilot | Codex CLI |
+|---|---|---|---|---|---|
+| **Skills** | Plugin system (auto) | Copied to `~/.junie/skills/` | Copied to `~/.gemini/skills/` | Copied to `~/.copilot/skills/` | Copied to `~/.codex/skills/` |
+| **Agents** | Plugin system (auto) | Strips `permissionMode` | Strips `model` + `permissionMode`, maps tool names | Strips `model` + `permissionMode`, maps tool names, renames to `.agent.md` | Strips `model` + `permissionMode`, maps tool names; reference copies in `~/.codex/agents/` (Codex has no formal subagent dispatcher yet) |
+| **Hooks** | 24 Python hook scripts | No hook system — behavioral guidelines | Translated events + tool names, translator shim | Translated events + tool names, translator shim, flattened config | Translated tool names only (events match Claude Code), translator shim, matcher-grouped config |
+| **Guidelines** | Plugin's `CLAUDE.md` injection | Generated `AGENTS.md` | Generated `GEMINI.md` | Generated `copilot-instructions.md` | Generated `AGENTS.md` (Codex's native convention) |
 
-Junie doesn't support hooks, so behaviors become guidelines in `AGENTS.md`. Gemini and GitHub Copilot have hooks but use different event/tool names — a translator shim normalizes input so all existing hooks work unmodified. Copilot additionally uses a flat hook config format with `bash` field and `version: 1` wrapper.
+Junie doesn't support hooks, so behaviors become guidelines in `AGENTS.md`. Gemini and GitHub Copilot have hooks but use different event/tool names — a translator shim normalizes input so all existing hooks work unmodified. Copilot additionally uses a flat hook config format with `bash` field and `version: 1` wrapper. Codex CLI shares Claude Code's hook event names natively, so the translator only rewrites tool-name strings; MCP servers register via `[mcp_servers.<name>]` tables in `~/.codex/config.toml` (not auto-configured yet).
 
 ### Adding New Platforms
 
@@ -84,7 +110,8 @@ platforms/
 ├── claude/adapter.ts        # Claude Code adapter
 ├── junie/adapter.ts         # Junie CLI adapter
 ├── gemini/adapter.ts        # Gemini CLI adapter
-└── gh-copilot/adapter.ts    # GitHub Copilot adapter
+├── gh-copilot/adapter.ts    # GitHub Copilot adapter
+└── codex/adapter.ts         # OpenAI Codex CLI adapter
 ```
 
 See [platforms/shared/types.ts](platforms/shared/types.ts) for the interface contract.
@@ -93,10 +120,10 @@ See [platforms/shared/types.ts](platforms/shared/types.ts) for the interface con
 
 ## What's Included
 
-- **Multi-Platform Installer**: Interactive CLI with auto-detection, install preview, and per-item exclusion — supports Claude Code, Junie CLI, Gemini CLI, and GitHub Copilot
-- **49 Skills**: Foundational + FP implementation + domain expert + integration + meta-skills
+- **Multi-Platform Installer**: Interactive CLI with auto-detection, install preview, and per-item exclusion — supports Claude Code, Junie CLI, Gemini CLI, GitHub Copilot, and OpenAI Codex CLI
+- **63 Skills**: Foundational + FP implementation + domain expert + integration + meta-skills
 - **6 Named Agents**: Explorer (haiku), Implementer (sonnet), Reviewer (sonnet), Tester (sonnet), WP Developer (sonnet), Memory (sonnet) — enforced constraints
-- **23 Hooks**: Automatic behavioral enforcement (security, memory, workflow, Serena, code quality) — translated to guidelines for platforms without hook support
+- **24 Hooks**: Automatic behavioral enforcement (security, memory, workflow, Serena, code quality) — translated to guidelines for platforms without hook support
 - **Default Persona**: "The Practitioner" - 25-year veteran mindset, collaborative, plan-first
 - **3-Tier Memory**: Vestige (neural decay) + Qdrant (permanent library) + Serena (project workbench)
 - **IMA Workflow**: Brainstorm → Plan → Implement → Test → Review → Document (habit-driven, not tool-enforced)
@@ -106,7 +133,7 @@ See [platforms/shared/types.ts](platforms/shared/types.ts) for the interface con
 
 ## Prerequisites
 
-- [Claude Code](https://claude.ai/code), [Junie CLI](https://www.jetbrains.com/help/idea/junie.html), [Gemini CLI](https://github.com/google-gemini/gemini-cli), or [GitHub Copilot](https://github.com/features/copilot) installed
+- [Claude Code](https://claude.ai/code), [Junie CLI](https://www.jetbrains.com/help/idea/junie.html), [Gemini CLI](https://github.com/google-gemini/gemini-cli), [GitHub Copilot](https://github.com/features/copilot), or [OpenAI Codex CLI](https://github.com/openai/codex) installed
 
 ## MCP Servers (Highly Recommended)
 
@@ -311,6 +338,7 @@ For in-scope hard reasoning (debugging, trade-offs within plan), agents invoke `
 | `wp-ddev` | WP-CLI commands for DDEV WordPress environments |
 | `wp-local` | WP-CLI commands for Flywheel Local WP |
 | `jira-checkpoint` | Jira awareness checkpoints for team visibility |
+| `ima-git` | IMA trunk-based git workflow (main/release/tag model, hotfix flow, deploy-gate push cadence, commit atomicity) |
 | `phpunit-wp` | PHPUnit testing for WordPress plugins with FP principles |
 | `rg` | Ripgrep usage patterns |
 | `ima-forms-expert` | WordPress form components (IMA Forms) |
@@ -471,7 +499,7 @@ ima-claude follows a **Persona + Skills** architecture:
 - **Platform adapters** - Shared `PlatformAdapter` interface; each platform implements detect, preview, install, and guideline generation
 
 This makes ima-claude:
-1. **Multi-platform** - Same skills and agents across Claude Code, Junie CLI, Gemini CLI, and GitHub Copilot
+1. **Multi-platform** - Same skills and agents across Claude Code, Junie CLI, Gemini CLI, GitHub Copilot, and OpenAI Codex CLI
 2. **Fully standalone** - Complete system without dependencies
 3. **Consistent** - Same mindset across all interactions
 4. **Efficient** - Skills load on-demand based on context

package/dist/cli.js

@@ -11,7 +11,7 @@ var HOOKS_DIR = join(CLAUDE_DIR, "hooks");
 var COMMANDS_DIR = join(CLAUDE_DIR, "commands");
 var RULES_DIR = join(CLAUDE_DIR, "rules");
 var SETTINGS_FILE = join(CLAUDE_DIR, "settings.json");
-var VERSION = "2.25.0";
+var VERSION = "2.27.0";
 var colors = {
   reset: "\x1B[0m",
   bright: "\x1B[1m",
@@ -111,6 +111,7 @@ var SKILLS_TO_INSTALL = [
   "design-to-code",
   "livecanvas",
   "jira-checkpoint",
+  "ima-git",
   // Testing skills
   "unit-testing",
   "phpunit-wp",
@@ -1424,12 +1425,379 @@ function mergeCopilotHooksConfig(configPath, newConfig) {
   writeFileSync4(configPath, JSON.stringify(existing, null, 2) + "\n");
 }
 
+// platforms/codex/adapter.ts
+import { join as join6, dirname as dirname4 } from "path";
+import { homedir as homedir5 } from "os";
+import { existsSync as existsSync6, readdirSync as readdirSync6, statSync as statSync6, readFileSync as readFileSync5, writeFileSync as writeFileSync5, copyFileSync as copyFileSync5 } from "fs";
+import { fileURLToPath as fileURLToPath3 } from "url";
+var __filename3 = fileURLToPath3(import.meta.url);
+var __dirname4 = dirname4(__filename3);
+var CODEX_DIR = process.env.CODEX_HOME ?? join6(homedir5(), ".codex");
+var CODEX_SKILLS_DIR = join6(CODEX_DIR, "skills");
+var CODEX_AGENTS_DIR = join6(CODEX_DIR, "agents");
+var CODEX_HOOKS_DIR = join6(CODEX_DIR, "hooks");
+var CODEX_HOOKS_CONFIG = join6(CODEX_DIR, "hooks.json");
+var CODEX_GUIDELINES_FILE = join6(CODEX_DIR, "AGENTS.md");
+var CODEX_CONFIG_TOML = join6(CODEX_DIR, "config.toml");
+var TOOL_MAP3 = {
+  Bash: "shell",
+  Read: "read",
+  Edit: "edit",
+  Write: "write",
+  Glob: "glob",
+  Grep: "grep",
+  LS: "list",
+  WebSearch: "web_search",
+  WebFetch: "fetch",
+  ExitPlanMode: "ExitPlanMode"
+};
+var EVENT_MAP3 = {
+  PreToolUse: "PreToolUse",
+  PostToolUse: "PostToolUse",
+  UserPromptSubmit: "UserPromptSubmit",
+  SessionStart: "SessionStart"
+};
+function parseFrontmatter4(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  if (!match) return { frontmatter: {}, body: content };
+  const frontmatter = {};
+  for (const line of match[1].split("\n")) {
+    const colonIdx = line.indexOf(":");
+    if (colonIdx === -1) continue;
+    const key = line.slice(0, colonIdx).trim();
+    const value = line.slice(colonIdx + 1).trim();
+    if (key) frontmatter[key] = value;
+  }
+  return { frontmatter, body: match[2] };
+}
+function serializeFrontmatter4(frontmatter, body) {
+  const lines = Object.entries(frontmatter).map(([k, v]) => `${k}: ${v}`);
+  return `---
+${lines.join("\n")}
+---
+${body}`;
+}
+function mapToolName3(claudeName) {
+  return TOOL_MAP3[claudeName] ?? claudeName;
+}
+function transformAgentForCodex(content) {
+  const { frontmatter, body } = parseFrontmatter4(content);
+  const { permissionMode: _perm, model: _model, ...kept } = frontmatter;
+  if (kept.tools) {
+    const mapped = kept.tools.split(",").map((t) => t.trim()).map(mapToolName3).join(", ");
+    kept.tools = mapped;
+  }
+  return serializeFrontmatter4(kept, body);
+}
+function translateMatcher3(matcher) {
+  return TOOL_MAP3[matcher] ?? matcher;
+}
+function translateHookCommand3(command2) {
+  const translatorPath = join6(CODEX_HOOKS_DIR, "hooks-translator.py");
+  const match = command2.match(/python3\s+.*\/([^/\s]+\.py)(\s.*)?$/);
+  if (!match) return command2;
+  const scriptName = match[1];
+  const trailingArgs = match[2] ?? "";
+  return `python3 ${translatorPath} ${join6(CODEX_HOOKS_DIR, scriptName)}${trailingArgs}`;
+}
+function generateCodexHooksConfig() {
+  const codexHooks = {};
+  for (const [claudeEvent, hookEntries] of Object.entries(HOOKS_CONFIG.hooks)) {
+    const codexEvent = EVENT_MAP3[claudeEvent] ?? claudeEvent;
+    codexHooks[codexEvent] = hookEntries.map(
+      (entry) => {
+        const translated = {};
+        if (entry.matcher) {
+          translated.matcher = translateMatcher3(entry.matcher);
+        }
+        translated.hooks = entry.hooks.map((h) => ({
+          type: h.type,
+          command: translateHookCommand3(h.command)
+        }));
+        return translated;
+      }
+    );
+  }
+  return { hooks: codexHooks };
+}
+function generateCodexAgentsMd() {
+  return `# ima-claude: AI Coding Agent Guidelines
+
+> Generated by ima-claude v${VERSION} for OpenAI Codex CLI.
+> Source: https://github.com/Soabirw/ima-claude
+
+This file is auto-loaded by Codex at session start (\`AGENTS.md\` convention).
+Per-directory \`AGENTS.md\` files in your project tree merge on top of this one,
+with closer-to-cwd files taking precedence.
+
+## Default Persona: The Practitioner
+
+A 25-year software development veteran. FP-first, composition-minded, anti-over-engineering.
+Uses "we" not "I" \u2014 collaborative, humble, light-hearted. "Slow is smooth, smooth is fast."
+
+**Philosophy**: Simple > Complex | Evidence > Assumptions | Native > Utilities | MVP > Enterprise
+
+---
+
+## Memory Routing
+
+| Store what | Where | Why |
+|---|---|---|
+| Decisions, preferences, patterns, bugs | Vestige \`smart_ingest\` | Fades naturally if not referenced |
+| Reference material (docs, standards, PRDs) | Qdrant \`qdrant-store\` | Permanent library |
+| Session state, task progress | Serena \`write_memory\` | Project-scoped workbench |
+| Future reminders | Vestige \`intention\` | Surfaces at next session |
+
+At session start, check memory before asking questions:
+- Vestige: search for user preferences and project context
+- Vestige: check for pending reminders/intentions
+- Serena: list memories if in a Serena-activated project
+
+Auto-store: "I prefer..." \u2192 Vestige preference. "Let's go with X because..." \u2192 Vestige decision. "The reason this failed..." \u2192 Vestige bug.
+
+After completing work: store outcome in Vestige, reference material in Qdrant, session state in Serena.
+
+---
+
+## Orchestrator Protocol
+
+You are the Orchestrator. Plan and delegate. Do NOT implement directly.
+- Non-trivial work \u2192 task-planner (decompose) \u2192 task-runner (delegate)
+- Trivial = single file, < 5 lines, no judgment calls
+
+---
+
+## Available Agents
+
+Codex does not yet support a formal named-subagent dispatcher. Treat the agents
+listed below as documented delegation patterns: when the work matches, scope a
+session (or a per-directory \`AGENTS.md\` overlay) to that agent's persona.
+Reference copies of each agent's full system prompt live in \`~/.codex/agents/\`.
+
+| Agent | Use For |
+|---|---|
+| \`explorer\` | File discovery, codebase exploration |
+| \`implementer\` | Feature dev, bug fixes, refactoring |
+| \`reviewer\` | Code review, security audit, FP checks |
+| \`tester\` | Test creation, TDD, debugging test failures |
+| \`wp-developer\` | WordPress plugins, themes, WP-CLI, forms |
+| \`memory\` | Memory search, storage, consolidation |
+
+---
+
+## Code Navigation (Serena)
+
+When Serena MCP is available, **prefer Serena over read/grep for code investigation.** 40-70% token savings.
+
+| Instead of | Use |
+|---|---|
+| Read file to understand structure | Serena get_symbols_overview |
+| grep for class/function definition | Serena find_symbol |
+| grep for callers/references | Serena find_referencing_symbols |
+
+Use the read tool only when you need the actual implementation body of a known, specific symbol.
+
+---
+
+## Complex Reasoning
+
+Use sequential thinking before acting on:
+- Debugging / root cause analysis / "why is this failing"
+- Trade-off evaluation / "which approach"
+- Architectural decisions / design choices
+- Multi-step investigations where approach may change
+
+---
+
+## MCP Tool Routing
+
+| Signal | Preferred Tool |
+|---|---|
+| "latest", "2025/2026", "what's new" | Tavily search |
+| Library/framework API question | Context7 |
+| URL content extraction | Tavily extract (use advanced for complex pages) |
+
+Before web tools: check internal knowledge \u2192 Context7 \u2192 then Tavily.
+Before external lookups: check Vestige memory first.
+
+To register MCP servers in Codex, add \`[mcp_servers.<name>]\` tables to
+\`~/.codex/config.toml\`. STDIO transport is the documented default.
+
+---
+
+## Search Preference
+
+Always prefer \`rg\` (ripgrep) over grep/find. Faster, respects .gitignore, recursive by default.
+
+---
+
+## Security
+
+- Verify nonce usage and input sanitization in WordPress PHP code
+- Never concatenate user input directly into SQL \u2014 use parameterized queries
+- Check for XSS, CSRF, and OWASP top 10 vulnerabilities in written code
+
+---
+
+## Code Style
+
+- Don't create custom FP utility functions (pipe, compose, curry) \u2014 use language-native patterns or established libraries
+- In WordPress JavaScript context, use jQuery patterns when jQuery is already loaded
+- Prefer Bootstrap utility classes over custom CSS overrides
+- Run \`composer dump-autoload\` after creating new PHP files
+
+---
+
+## Documentation
+
+Follow the three-tier documentation system:
+- **Active** \u2014 Living docs, kept current (README, API docs, architecture)
+- **Archive** \u2014 Historical reference, rarely updated (decisions, post-mortems)
+- **Transient** \u2014 Ephemeral, git-ignored (session notes, scratch)
+`;
+}
+var CodexAdapter = class {
+  name = "codex";
+  displayName = "OpenAI Codex CLI";
+  configDir = CODEX_DIR;
+  detect() {
+    return existsSync6(CODEX_DIR);
+  }
+  preview(sourceDir) {
+    const skillItems = SKILLS_TO_INSTALL.map((skill) => ({
+      name: skill,
+      category: "skill",
+      destPath: join6(CODEX_SKILLS_DIR, skill),
+      exists: existsSync6(join6(CODEX_SKILLS_DIR, skill))
+    })).filter((item) => existsSync6(join6(sourceDir, "skills", item.name)));
+    const agentsDir = join6(sourceDir, "agents");
+    const agentItems = existsSync6(agentsDir) ? readdirSync6(agentsDir).filter((f) => f.endsWith(".md")).map((file) => ({
+      name: file.replace(/\.md$/, ""),
+      category: "agent",
+      destPath: join6(CODEX_AGENTS_DIR, file),
+      exists: existsSync6(join6(CODEX_AGENTS_DIR, file))
+    })) : [];
+    const hookItems = HOOKS_TO_INSTALL.map((file) => ({
+      name: file,
+      category: "hook",
+      destPath: join6(CODEX_HOOKS_DIR, file),
+      exists: existsSync6(join6(CODEX_HOOKS_DIR, file))
+    }));
+    const translatorItem = {
+      name: "hooks-translator.py",
+      category: "hook",
+      destPath: join6(CODEX_HOOKS_DIR, "hooks-translator.py"),
+      exists: existsSync6(join6(CODEX_HOOKS_DIR, "hooks-translator.py"))
+    };
+    const guidelineItem = {
+      name: "AGENTS.md",
+      category: "guideline",
+      destPath: CODEX_GUIDELINES_FILE,
+      exists: existsSync6(CODEX_GUIDELINES_FILE)
+    };
+    return {
+      platform: this.name,
+      targetDir: CODEX_DIR,
+      items: [...skillItems, ...agentItems, ...hookItems, translatorItem, guidelineItem]
+    };
+  }
+  installSkills(sourceDir, exclude) {
+    ensureDir(CODEX_SKILLS_DIR);
+    const skills = exclude?.length ? SKILLS_TO_INSTALL.filter((s) => !exclude.includes(s)) : SKILLS_TO_INSTALL;
+    for (const skill of skills) {
+      const src = join6(sourceDir, skill);
+      if (existsSync6(src) && statSync6(src).isDirectory()) {
+        copyDirRecursive(src, join6(CODEX_SKILLS_DIR, skill));
+        log.step(`skill: ${skill}`);
+      }
+    }
+  }
+  installAgents(sourceDir, exclude) {
+    ensureDir(CODEX_AGENTS_DIR);
+    const entries = readdirSync6(sourceDir).filter((f) => f.endsWith(".md")).filter((f) => !exclude?.includes(f.replace(/\.md$/, "")));
+    for (const file of entries) {
+      const content = readFileSync5(join6(sourceDir, file), "utf8");
+      const transformed = transformAgentForCodex(content);
+      writeFileSync5(join6(CODEX_AGENTS_DIR, file), transformed);
+      log.step(`agent: ${file}`);
+    }
+  }
+  installGuidelines(_pluginRoot) {
+    ensureDir(CODEX_DIR);
+    writeFileSync5(CODEX_GUIDELINES_FILE, generateCodexAgentsMd());
+    log.step(`guidelines: ${CODEX_GUIDELINES_FILE}`);
+  }
+  installHooks(sourceDir, exclude) {
+    ensureDir(CODEX_HOOKS_DIR);
+    const hooks = exclude?.length ? HOOKS_TO_INSTALL.filter((f) => !exclude.includes(f)) : HOOKS_TO_INSTALL;
+    for (const file of hooks) {
+      const src = join6(sourceDir, file);
+      if (existsSync6(src)) {
+        copyFileSync5(src, join6(CODEX_HOOKS_DIR, file));
+        log.step(`hook: ${file}`);
+      }
+    }
+    const shimSrc = join6(__dirname4, "hooks-translator.py");
+    if (!existsSync6(shimSrc)) {
+      throw new Error(`hooks-translator.py not found at ${shimSrc} \u2014 packaging error`);
+    }
+    copyFileSync5(shimSrc, join6(CODEX_HOOKS_DIR, "hooks-translator.py"));
+    log.step("hook: hooks-translator.py (shim)");
+    const hooksConfig = generateCodexHooksConfig();
+    mergeCodexHooksConfig(CODEX_HOOKS_CONFIG, hooksConfig);
+    log.step("hook: hooks.json (generated for Codex CLI)");
+  }
+  postInstall() {
+    log.info("OpenAI Codex CLI install complete. Verify:");
+    log.info(`  Skills:     ${CODEX_SKILLS_DIR}`);
+    log.info(`  Agents:     ${CODEX_AGENTS_DIR}`);
+    log.info(`  Hooks:      ${CODEX_HOOKS_DIR}`);
+    log.info(`  Hooks cfg:  ${CODEX_HOOKS_CONFIG}`);
+    log.info(`  Guidelines: ${CODEX_GUIDELINES_FILE}`);
+    log.info("");
+    log.info("MCP servers are not auto-configured. To register them, add");
+    log.info(`  [mcp_servers.<name>] command = "..." args = [...]`);
+    log.info(`tables to ${CODEX_CONFIG_TOML} (STDIO transport).`);
+    log.info("");
+    log.info("If a hook silently fails to fire, the Codex tool name may have changed \u2014");
+    log.info("update TOOL_MAP in platforms/codex/adapter.ts and reinstall.");
+  }
+};
+function mergeCodexHooksConfig(configPath, newConfig) {
+  let existing = {};
+  if (existsSync6(configPath)) {
+    try {
+      const content = readFileSync5(configPath, "utf8");
+      existing = JSON.parse(content);
+    } catch {
+      existing = {};
+    }
+  }
+  if (!existing.hooks) {
+    existing.hooks = {};
+  }
+  const existingHooks = existing.hooks;
+  const incomingHooks = newConfig.hooks;
+  for (const [event, entries] of Object.entries(incomingHooks)) {
+    if (!existingHooks[event]) {
+      existingHooks[event] = entries;
+      continue;
+    }
+    const userEntries = existingHooks[event].filter(
+      (entry) => !entry.hooks?.some((h) => h.command?.includes("hooks-translator.py"))
+    );
+    existingHooks[event] = [...userEntries, ...entries];
+  }
+  writeFileSync5(configPath, JSON.stringify(existing, null, 2) + "\n");
+}
+
 // platforms/shared/detector.ts
 var ADAPTERS = [
   new ClaudeAdapter(),
   new JunieAdapter(),
   new GeminiAdapter(),
-  new GhCopilotAdapter()
+  new GhCopilotAdapter(),
+  new CodexAdapter()
 ];
 function detectPlatforms() {
   return ADAPTERS.map((adapter) => {
@@ -1443,28 +1811,28 @@ function getAdapter(name) {
 }
 
 // platforms/shared/installer.ts
-import { join as join7 } from "path";
+import { join as join8 } from "path";
 
 // platforms/shared/types.ts
-import { join as join6, resolve, dirname as dirname4 } from "path";
-import { existsSync as existsSync6 } from "fs";
-import { fileURLToPath as fileURLToPath3 } from "url";
+import { join as join7, resolve, dirname as dirname5 } from "path";
+import { existsSync as existsSync7 } from "fs";
+import { fileURLToPath as fileURLToPath4 } from "url";
 function findPackageRoot() {
   let dir;
   try {
-    dir = dirname4(fileURLToPath3(import.meta.url));
+    dir = dirname5(fileURLToPath4(import.meta.url));
   } catch {
     dir = typeof __dirname !== "undefined" ? __dirname : resolve(".");
   }
   for (let i = 0; i < 10; i++) {
-    if (existsSync6(join6(dir, "package.json"))) return dir;
-    const parent = join6(dir, "..");
+    if (existsSync7(join7(dir, "package.json"))) return dir;
+    const parent = join7(dir, "..");
     if (parent === dir) break;
     dir = parent;
   }
   return process.cwd();
 }
-var PLUGIN_SOURCE = join6(
+var PLUGIN_SOURCE = join7(
   findPackageRoot(),
   "plugins",
   "ima-claude"
@@ -1580,9 +1948,9 @@ ${colors.bright}Hooks${colors.reset} (${hooks.length} total)`
   return filter;
 }
 async function installForPlatform(adapter, options = {}) {
-  const skillsSource = join7(PLUGIN_SOURCE, "skills");
-  const agentsSource = join7(PLUGIN_SOURCE, "agents");
-  const hooksSource = join7(PLUGIN_SOURCE, "hooks");
+  const skillsSource = join8(PLUGIN_SOURCE, "skills");
+  const agentsSource = join8(PLUGIN_SOURCE, "agents");
+  const hooksSource = join8(PLUGIN_SOURCE, "hooks");
   const preview = adapter.preview(PLUGIN_SOURCE);
   showPreview(adapter, preview.items);
   const filter = await promptExclusions(preview.items);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ima-claude",
-  "version": "2.25.0",
-  "description": "IMA's AI coding agent skills - FP patterns, architecture guidance, and team standards. Supports Claude Code, Junie CLI, Gemini CLI, and GitHub Copilot.",
+  "version": "2.27.0",
+  "description": "IMA's AI coding agent skills - FP patterns, architecture guidance, and team standards. Supports Claude Code, Junie CLI, Gemini CLI, GitHub Copilot, and OpenAI Codex CLI.",
   "type": "module",
   "scripts": {
     "build": "tsup",

package/platforms/codex/adapter.ts

@@ -0,0 +1,452 @@
+import { join, dirname } from "path";
+import { homedir } from "os";
+import { existsSync, readdirSync, statSync, readFileSync, writeFileSync, copyFileSync } from "fs";
+import { fileURLToPath } from "url";
+
+import type { PlatformAdapter, InstallItem, InstallPreview } from "../shared/types";
+import { ensureDir, copyDirRecursive, log, SKILLS_TO_INSTALL, HOOKS_TO_INSTALL, HOOKS_CONFIG, VERSION } from "../../scripts/utils";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Honour CODEX_HOME if set; otherwise default to ~/.codex
+const CODEX_DIR = process.env.CODEX_HOME ?? join(homedir(), ".codex");
+const CODEX_SKILLS_DIR = join(CODEX_DIR, "skills");
+const CODEX_AGENTS_DIR = join(CODEX_DIR, "agents");
+const CODEX_HOOKS_DIR = join(CODEX_DIR, "hooks");
+const CODEX_HOOKS_CONFIG = join(CODEX_DIR, "hooks.json");
+const CODEX_GUIDELINES_FILE = join(CODEX_DIR, "AGENTS.md");
+const CODEX_CONFIG_TOML = join(CODEX_DIR, "config.toml");
+
+// Claude Code → Codex CLI tool name mapping
+// Based on developers.openai.com/codex docs. "shell" is well-attested; the rest
+// are best-known canonical names. Update here if a Codex release renames any.
+const TOOL_MAP: Record<string, string> = {
+  Bash: "shell",
+  Read: "read",
+  Edit: "edit",
+  Write: "write",
+  Glob: "glob",
+  Grep: "grep",
+  LS: "list",
+  WebSearch: "web_search",
+  WebFetch: "fetch",
+  ExitPlanMode: "ExitPlanMode",
+};
+
+// Claude Code → Codex CLI hook event mapping
+// Codex uses Claude Code's exact event names natively, so this is identity.
+// Kept as a constant so future divergences are a single-point edit.
+const EVENT_MAP: Record<string, string> = {
+  PreToolUse: "PreToolUse",
+  PostToolUse: "PostToolUse",
+  UserPromptSubmit: "UserPromptSubmit",
+  SessionStart: "SessionStart",
+};
+
+// Simple single-line YAML parser — same shape as Junie/Gemini/Copilot adapters.
+function parseFrontmatter(content: string): { frontmatter: Record<string, string>; body: string } {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  if (!match) return { frontmatter: {}, body: content };
+
+  const frontmatter: Record<string, string> = {};
+  for (const line of match[1].split("\n")) {
+    const colonIdx = line.indexOf(":");
+    if (colonIdx === -1) continue;
+    const key = line.slice(0, colonIdx).trim();
+    const value = line.slice(colonIdx + 1).trim();
+    if (key) frontmatter[key] = value;
+  }
+
+  return { frontmatter, body: match[2] };
+}
+
+function serializeFrontmatter(frontmatter: Record<string, string>, body: string): string {
+  const lines = Object.entries(frontmatter).map(([k, v]) => `${k}: ${v}`);
+  return `---\n${lines.join("\n")}\n---\n${body}`;
+}
+
+function mapToolName(claudeName: string): string {
+  return TOOL_MAP[claudeName] ?? claudeName;
+}
+
+function transformAgentForCodex(content: string): string {
+  const { frontmatter, body } = parseFrontmatter(content);
+
+  // Drop permissionMode (Codex uses global approval_policy / sandbox_mode)
+  // Drop model (Codex uses its own model selection)
+  const { permissionMode: _perm, model: _model, ...kept } = frontmatter;
+
+  // Map tool names in the tools field if present
+  if (kept.tools) {
+    const mapped = kept.tools
+      .split(",")
+      .map((t) => t.trim())
+      .map(mapToolName)
+      .join(", ");
+    kept.tools = mapped;
+  }
+
+  return serializeFrontmatter(kept, body);
+}
+
+function translateMatcher(matcher: string): string {
+  // MCP tool matchers pass through unchanged; only map built-in Claude tool names
+  return TOOL_MAP[matcher] ?? matcher;
+}
+
+function translateHookCommand(command: string): string {
+  // Rewrite hook commands to route through the translator shim
+  // Original: python3 ~/.claude/hooks/some_hook.py
+  // Codex:    python3 ~/.codex/hooks/hooks-translator.py ~/.codex/hooks/some_hook.py
+  const translatorPath = join(CODEX_HOOKS_DIR, "hooks-translator.py");
+
+  const match = command.match(/python3\s+.*\/([^/\s]+\.py)(\s.*)?$/);
+  if (!match) return command;
+
+  const scriptName = match[1];
+  const trailingArgs = match[2] ?? "";
+  return `python3 ${translatorPath} ${join(CODEX_HOOKS_DIR, scriptName)}${trailingArgs}`;
+}
+
+function generateCodexHooksConfig(): Record<string, unknown> {
+  const codexHooks: Record<string, unknown[]> = {};
+
+  for (const [claudeEvent, hookEntries] of Object.entries(HOOKS_CONFIG.hooks)) {
+    const codexEvent = EVENT_MAP[claudeEvent] ?? claudeEvent;
+
+    codexHooks[codexEvent] = (hookEntries as Array<{ matcher?: string; hooks: Array<{ type: string; command: string }> }>).map(
+      (entry) => {
+        const translated: Record<string, unknown> = {};
+
+        if (entry.matcher) {
+          translated.matcher = translateMatcher(entry.matcher);
+        }
+
+        translated.hooks = entry.hooks.map((h) => ({
+          type: h.type,
+          command: translateHookCommand(h.command),
+        }));
+
+        return translated;
+      }
+    );
+  }
+
+  return { hooks: codexHooks };
+}
+
+function generateCodexAgentsMd(): string {
+  return `# ima-claude: AI Coding Agent Guidelines
+
+> Generated by ima-claude v${VERSION} for OpenAI Codex CLI.
+> Source: https://github.com/Soabirw/ima-claude
+
+This file is auto-loaded by Codex at session start (\`AGENTS.md\` convention).
+Per-directory \`AGENTS.md\` files in your project tree merge on top of this one,
+with closer-to-cwd files taking precedence.
+
+## Default Persona: The Practitioner
+
+A 25-year software development veteran. FP-first, composition-minded, anti-over-engineering.
+Uses "we" not "I" — collaborative, humble, light-hearted. "Slow is smooth, smooth is fast."
+
+**Philosophy**: Simple > Complex | Evidence > Assumptions | Native > Utilities | MVP > Enterprise
+
+---
+
+## Memory Routing
+
+| Store what | Where | Why |
+|---|---|---|
+| Decisions, preferences, patterns, bugs | Vestige \`smart_ingest\` | Fades naturally if not referenced |
+| Reference material (docs, standards, PRDs) | Qdrant \`qdrant-store\` | Permanent library |
+| Session state, task progress | Serena \`write_memory\` | Project-scoped workbench |
+| Future reminders | Vestige \`intention\` | Surfaces at next session |
+
+At session start, check memory before asking questions:
+- Vestige: search for user preferences and project context
+- Vestige: check for pending reminders/intentions
+- Serena: list memories if in a Serena-activated project
+
+Auto-store: "I prefer..." → Vestige preference. "Let's go with X because..." → Vestige decision. "The reason this failed..." → Vestige bug.
+
+After completing work: store outcome in Vestige, reference material in Qdrant, session state in Serena.
+
+---
+
+## Orchestrator Protocol
+
+You are the Orchestrator. Plan and delegate. Do NOT implement directly.
+- Non-trivial work → task-planner (decompose) → task-runner (delegate)
+- Trivial = single file, < 5 lines, no judgment calls
+
+---
+
+## Available Agents
+
+Codex does not yet support a formal named-subagent dispatcher. Treat the agents
+listed below as documented delegation patterns: when the work matches, scope a
+session (or a per-directory \`AGENTS.md\` overlay) to that agent's persona.
+Reference copies of each agent's full system prompt live in \`~/.codex/agents/\`.
+
+| Agent | Use For |
+|---|---|
+| \`explorer\` | File discovery, codebase exploration |
+| \`implementer\` | Feature dev, bug fixes, refactoring |
+| \`reviewer\` | Code review, security audit, FP checks |
+| \`tester\` | Test creation, TDD, debugging test failures |
+| \`wp-developer\` | WordPress plugins, themes, WP-CLI, forms |
+| \`memory\` | Memory search, storage, consolidation |
+
+---
+
+## Code Navigation (Serena)
+
+When Serena MCP is available, **prefer Serena over read/grep for code investigation.** 40-70% token savings.
+
+| Instead of | Use |
+|---|---|
+| Read file to understand structure | Serena get_symbols_overview |
+| grep for class/function definition | Serena find_symbol |
+| grep for callers/references | Serena find_referencing_symbols |
+
+Use the read tool only when you need the actual implementation body of a known, specific symbol.
+
+---
+
+## Complex Reasoning
+
+Use sequential thinking before acting on:
+- Debugging / root cause analysis / "why is this failing"
+- Trade-off evaluation / "which approach"
+- Architectural decisions / design choices
+- Multi-step investigations where approach may change
+
+---
+
+## MCP Tool Routing
+
+| Signal | Preferred Tool |
+|---|---|
+| "latest", "2025/2026", "what's new" | Tavily search |
+| Library/framework API question | Context7 |
+| URL content extraction | Tavily extract (use advanced for complex pages) |
+
+Before web tools: check internal knowledge → Context7 → then Tavily.
+Before external lookups: check Vestige memory first.
+
+To register MCP servers in Codex, add \`[mcp_servers.<name>]\` tables to
+\`~/.codex/config.toml\`. STDIO transport is the documented default.
+
+---
+
+## Search Preference
+
+Always prefer \`rg\` (ripgrep) over grep/find. Faster, respects .gitignore, recursive by default.
+
+---
+
+## Security
+
+- Verify nonce usage and input sanitization in WordPress PHP code
+- Never concatenate user input directly into SQL — use parameterized queries
+- Check for XSS, CSRF, and OWASP top 10 vulnerabilities in written code
+
+---
+
+## Code Style
+
+- Don't create custom FP utility functions (pipe, compose, curry) — use language-native patterns or established libraries
+- In WordPress JavaScript context, use jQuery patterns when jQuery is already loaded
+- Prefer Bootstrap utility classes over custom CSS overrides
+- Run \`composer dump-autoload\` after creating new PHP files
+
+---
+
+## Documentation
+
+Follow the three-tier documentation system:
+- **Active** — Living docs, kept current (README, API docs, architecture)
+- **Archive** — Historical reference, rarely updated (decisions, post-mortems)
+- **Transient** — Ephemeral, git-ignored (session notes, scratch)
+`;
+}
+
+export class CodexAdapter implements PlatformAdapter {
+  readonly name = "codex";
+  readonly displayName = "OpenAI Codex CLI";
+  readonly configDir = CODEX_DIR;
+
+  detect(): boolean {
+    return existsSync(CODEX_DIR);
+  }
+
+  preview(sourceDir: string): InstallPreview {
+    const skillItems: InstallItem[] = SKILLS_TO_INSTALL.map((skill) => ({
+      name: skill,
+      category: "skill" as const,
+      destPath: join(CODEX_SKILLS_DIR, skill),
+      exists: existsSync(join(CODEX_SKILLS_DIR, skill)),
+    })).filter((item) => existsSync(join(sourceDir, "skills", item.name)));
+
+    const agentsDir = join(sourceDir, "agents");
+    const agentItems: InstallItem[] = existsSync(agentsDir)
+      ? readdirSync(agentsDir)
+          .filter((f) => f.endsWith(".md"))
+          .map((file) => ({
+            name: file.replace(/\.md$/, ""),
+            category: "agent" as const,
+            destPath: join(CODEX_AGENTS_DIR, file),
+            exists: existsSync(join(CODEX_AGENTS_DIR, file)),
+          }))
+      : [];
+
+    const hookItems: InstallItem[] = HOOKS_TO_INSTALL.map((file) => ({
+      name: file,
+      category: "hook" as const,
+      destPath: join(CODEX_HOOKS_DIR, file),
+      exists: existsSync(join(CODEX_HOOKS_DIR, file)),
+    }));
+
+    const translatorItem: InstallItem = {
+      name: "hooks-translator.py",
+      category: "hook",
+      destPath: join(CODEX_HOOKS_DIR, "hooks-translator.py"),
+      exists: existsSync(join(CODEX_HOOKS_DIR, "hooks-translator.py")),
+    };
+
+    const guidelineItem: InstallItem = {
+      name: "AGENTS.md",
+      category: "guideline",
+      destPath: CODEX_GUIDELINES_FILE,
+      exists: existsSync(CODEX_GUIDELINES_FILE),
+    };
+
+    return {
+      platform: this.name,
+      targetDir: CODEX_DIR,
+      items: [...skillItems, ...agentItems, ...hookItems, translatorItem, guidelineItem],
+    };
+  }
+
+  installSkills(sourceDir: string, exclude?: string[]): void {
+    ensureDir(CODEX_SKILLS_DIR);
+    const skills = exclude?.length
+      ? SKILLS_TO_INSTALL.filter((s) => !exclude.includes(s))
+      : SKILLS_TO_INSTALL;
+    for (const skill of skills) {
+      const src = join(sourceDir, skill);
+      if (existsSync(src) && statSync(src).isDirectory()) {
+        copyDirRecursive(src, join(CODEX_SKILLS_DIR, skill));
+        log.step(`skill: ${skill}`);
+      }
+    }
+  }
+
+  installAgents(sourceDir: string, exclude?: string[]): void {
+    ensureDir(CODEX_AGENTS_DIR);
+    const entries = readdirSync(sourceDir)
+      .filter((f) => f.endsWith(".md"))
+      .filter((f) => !exclude?.includes(f.replace(/\.md$/, "")));
+    for (const file of entries) {
+      const content = readFileSync(join(sourceDir, file), "utf8");
+      const transformed = transformAgentForCodex(content);
+      writeFileSync(join(CODEX_AGENTS_DIR, file), transformed);
+      log.step(`agent: ${file}`);
+    }
+  }
+
+  installGuidelines(_pluginRoot: string): void {
+    ensureDir(CODEX_DIR);
+    writeFileSync(CODEX_GUIDELINES_FILE, generateCodexAgentsMd());
+    log.step(`guidelines: ${CODEX_GUIDELINES_FILE}`);
+  }
+
+  installHooks(sourceDir: string, exclude?: string[]): void {
+    ensureDir(CODEX_HOOKS_DIR);
+
+    const hooks = exclude?.length
+      ? HOOKS_TO_INSTALL.filter((f) => !exclude.includes(f))
+      : HOOKS_TO_INSTALL;
+    for (const file of hooks) {
+      const src = join(sourceDir, file);
+      if (existsSync(src)) {
+        copyFileSync(src, join(CODEX_HOOKS_DIR, file));
+        log.step(`hook: ${file}`);
+      }
+    }
+
+    const shimSrc = join(__dirname, "hooks-translator.py");
+    if (!existsSync(shimSrc)) {
+      throw new Error(`hooks-translator.py not found at ${shimSrc} — packaging error`);
+    }
+    copyFileSync(shimSrc, join(CODEX_HOOKS_DIR, "hooks-translator.py"));
+    log.step("hook: hooks-translator.py (shim)");
+
+    const hooksConfig = generateCodexHooksConfig();
+    mergeCodexHooksConfig(CODEX_HOOKS_CONFIG, hooksConfig);
+    log.step("hook: hooks.json (generated for Codex CLI)");
+  }
+
+  postInstall(): void {
+    log.info("OpenAI Codex CLI install complete. Verify:");
+    log.info(`  Skills:     ${CODEX_SKILLS_DIR}`);
+    log.info(`  Agents:     ${CODEX_AGENTS_DIR}`);
+    log.info(`  Hooks:      ${CODEX_HOOKS_DIR}`);
+    log.info(`  Hooks cfg:  ${CODEX_HOOKS_CONFIG}`);
+    log.info(`  Guidelines: ${CODEX_GUIDELINES_FILE}`);
+    log.info("");
+    log.info("MCP servers are not auto-configured. To register them, add");
+    log.info(`  [mcp_servers.<name>] command = "..." args = [...]`);
+    log.info(`tables to ${CODEX_CONFIG_TOML} (STDIO transport).`);
+    log.info("");
+    log.info("If a hook silently fails to fire, the Codex tool name may have changed —");
+    log.info("update TOOL_MAP in platforms/codex/adapter.ts and reinstall.");
+  }
+}
+
+function mergeCodexHooksConfig(
+  configPath: string,
+  newConfig: Record<string, unknown>
+): void {
+  let existing: Record<string, unknown> = {};
+
+  if (existsSync(configPath)) {
+    try {
+      const content = readFileSync(configPath, "utf8");
+      existing = JSON.parse(content);
+    } catch {
+      existing = {};
+    }
+  }
+
+  if (!existing.hooks) {
+    existing.hooks = {};
+  }
+  const existingHooks = existing.hooks as Record<string, unknown[]>;
+  const incomingHooks = (newConfig as Record<string, unknown>).hooks as Record<
+    string,
+    Array<{ matcher?: string; hooks: Array<{ command: string }> }>
+  >;
+
+  // Merge each event: strip prior ima-claude entries (identified by hooks-translator.py
+  // substring in any nested command), then append the new entries. User hooks survive.
+  for (const [event, entries] of Object.entries(incomingHooks)) {
+    if (!existingHooks[event]) {
+      existingHooks[event] = entries;
+      continue;
+    }
+
+    const userEntries = (
+      existingHooks[event] as Array<{ matcher?: string; hooks?: Array<{ command?: string }> }>
+    ).filter(
+      (entry) =>
+        !entry.hooks?.some((h) => h.command?.includes("hooks-translator.py"))
+    );
+
+    existingHooks[event] = [...userEntries, ...entries];
+  }
+
+  writeFileSync(configPath, JSON.stringify(existing, null, 2) + "\n");
+}

package/platforms/codex/hooks-translator.py

@@ -0,0 +1,67 @@
+#!/usr/bin/env python3
+"""OpenAI Codex CLI → Claude Code tool name translator shim.
+
+Sits between Codex CLI and ima-claude hook scripts, translating Codex
+tool names to their Claude Code equivalents so existing hooks (which
+read `tool_name="Bash"`, etc.) work unmodified.
+
+Codex hook events (PreToolUse, PostToolUse, UserPromptSubmit, SessionStart)
+already match Claude Code's names, so only the `tool_name` field inside
+the JSON payload needs rewriting.
+
+Usage (in hooks.json):
+  python3 ~/.codex/hooks/hooks-translator.py ~/.codex/hooks/some_hook.py
+"""
+
+import json
+import subprocess
+import sys
+
+# Codex CLI → Claude Code tool name mapping (reverse of adapter TOOL_MAP)
+CODEX_TO_CLAUDE = {
+    "shell": "Bash",
+    "read": "Read",
+    "edit": "Edit",
+    "write": "Write",
+    "glob": "Glob",
+    "grep": "Grep",
+    "list": "LS",
+    "web_search": "WebSearch",
+    "fetch": "WebFetch",
+    "ExitPlanMode": "ExitPlanMode",
+}
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: hooks-translator.py <hook-script> [args...]", file=sys.stderr)
+        sys.exit(1)
+
+    target_script = sys.argv[1]
+    extra_args = sys.argv[2:]
+
+    try:
+        raw = sys.stdin.read()
+        data = json.loads(raw) if raw.strip() else {}
+    except json.JSONDecodeError as e:
+        print(f"hooks-translator: invalid JSON from stdin: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    tool_name = data.get("tool_name", "")
+    if tool_name in CODEX_TO_CLAUDE:
+        data["tool_name"] = CODEX_TO_CLAUDE[tool_name]
+
+    translated = json.dumps(data)
+    result = subprocess.run(
+        ["python3", target_script] + extra_args,
+        input=translated,
+        stdout=None,
+        stderr=None,
+        text=True,
+    )
+
+    sys.exit(result.returncode)
+
+
+if __name__ == "__main__":
+    main()

package/platforms/shared/detector.ts

@@ -3,12 +3,14 @@ import { ClaudeAdapter } from "../claude/adapter";
 import { JunieAdapter } from "../junie/adapter";
 import { GeminiAdapter } from "../gemini/adapter";
 import { GhCopilotAdapter } from "../gh-copilot/adapter";
+import { CodexAdapter } from "../codex/adapter";
 
 const ADAPTERS: PlatformAdapter[] = [
   new ClaudeAdapter(),
   new JunieAdapter(),
   new GeminiAdapter(),
   new GhCopilotAdapter(),
+  new CodexAdapter(),
 ];
 
 export function detectPlatforms(): DetectedPlatform[] {

package/plugins/ima-claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ima-claude",
-  "version": "2.25.0",
-  "description": "IMA's Claude Code skills for functional programming, architecture, and team standards. 62 skills, 24 hooks, default persona, 3-tier memory system.",
+  "version": "2.27.0",
+  "description": "IMA's Claude Code skills for functional programming, architecture, and team standards. 63 skills, 24 hooks, default persona, 3-tier memory system.",
   "author": {
     "name": "IMA",
     "url": "https://github.com/Soabirw/ima-claude"

package/plugins/ima-claude/agents/reviewer.md

@@ -23,6 +23,33 @@ Use Serena as FIRST approach for ALL code investigation. Saves 40-70% tokens vs
 
 Use Read only for specific symbol bodies under review. Fall back to Read/Grep for non-code files.
 
+## Configured validators (REQUIRED — run first)
+
+A review is incomplete without running the project's configured gate. Validator output is primary evidence; code-reading is supplementary.
+
+Discover validators in this order:
+
+| Ecosystem | Where to look |
+|---|---|
+| PHP | `composer.json` scripts — `check`, `test`, `test:unit`, `phpcs`, `phpcs:report`, `lint` |
+| JS/TS | `package.json` scripts — `test`, `lint`, `typecheck`, `check`, `ci` |
+| Make-based | `Makefile` targets — `check`, `test`, `lint`, `ci` |
+| Python | `pyproject.toml` / `tox.ini` / `noxfile.py` |
+| Ruby | `Rakefile` — `ci`, `test`, `rubocop` |
+
+Run the project's aggregated gate if one exists (`composer check`, `npm run check`, `make check`, `rake ci`, etc.). Otherwise run lint + tests separately. If the project has none, that's a finding — not a silent pass.
+
+**Every review output MUST include a "Validators run" block:**
+
+```
+## Validators run
+- composer test:unit → exit 0 (308 tests, 0 failures)
+- composer phpcs:report → exit 1 (0 errors, 82 warnings)
+- (no JS lint configured)
+```
+
+A review with zero validator invocations is structurally incomplete. If you couldn't run a discovered validator (missing deps, auth required, etc.), say so explicitly and flag as a blocker for the review.
+
 ## PR review mode
 
 When given a Gitea/GitHub PR URL or diff:
@@ -39,7 +66,7 @@ Diff-only analysis is the failure mode. Always read surrounding context.
 
 **FP** — unnecessary mutation, side effects mixed with business logic, missing composition, custom FP utilities over native patterns
 
-**Security** — input validation at boundaries, SQL injection, XSS, exposed secrets, auth/authz
+**Security** — start with security-sniff output (WPCS security, eslint-plugin-security, bandit, etc.) if available; then input validation at boundaries, SQL injection, XSS, exposed secrets, auth/authz
 
 **Quality** — naming clarity, over-engineering, dead code, pattern consistency
 
@@ -73,3 +100,4 @@ Parent (Opus) decides whether to expand scope, re-dispatch a focused follow-up r
 - Flag style preferences that don't affect correctness
 - Suggest adding comments/docstrings/types to unchanged code
 - Report more than 10 findings — prioritize ruthlessly
+- Assert on code standards, security, or test coverage without having run the corresponding validator. "Looks clean" is not a finding; "phpcs reports 0 errors" is.

package/plugins/ima-claude/skills/ima-git/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: "ima-git"
+description: "IMA git workflow. Trunk-based development with release branches: main = dev trunk, release/* = release candidate branches, v* tags = production releases. Covers branch promotion, hotfix flow, push cadence for deploy-gate verification, commit atomicity. Use when: creating branches, opening PRs, cutting releases or tags, writing hotfixes, or asked about git workflow, branching strategy, trunk-based development, release process, or when a deploy gate fails because commits weren't pushed."
+---
+
+# IMA Git Workflow
+
+**Strategy:** Trunk-based development with release branches.
+
+## Branch model
+
+| Branch / tag | Role | Source | Deploys to |
+|---|---|---|---|
+| `main` | Dev trunk — latest integrated work | All new work lands here first | Dev environment |
+| `release/<name>` | Release candidate | Fast-forwarded from `main` when ready | Staging environment |
+| `v<version>` (tags) | Production release | Tag cut from a release branch at promotion | Production environment |
+| `hotfix/<name>` | Emergency production fix | Branched off the production tag | Merged back to `main` + new tag cut |
+
+## Core rules
+
+1. **Commits originate on `main`.** Not on release branches. Feature work, bug fixes, refactors — all start on the trunk.
+2. **Release branches only fast-forward from `main`.** Never merge sideways; never commit directly to a release branch.
+3. **Hotfixes branch off the production tag**, not main. After the fix lands, cut a new tag and merge the hotfix back into `main`.
+4. **Tags are immutable.** Rolling back to a prior production state means deploying the prior tag — not force-pushing or retagging.
+
+## Deploy-gate verification cadence
+
+Deploy tools (e.g., `trn-deploy` at `/home/eric/IMA/dev/sites/trn/deploy/`) **clone fresh from the remote** — they do not read the local filesystem. Unpushed commits are invisible to the gate.
+
+**To verify a change:** push to `main` first, then invoke the dry-run.
+
+Between commits in a multi-commit sequence:
+
+1. Commit locally
+2. `git push origin main`
+3. Run `./deploy dev --dry-run`
+4. Confirm exit 0 in `log.jsonl` before the next commit
+
+## Commit atomicity
+
+- **Security fixes: separate commits** from test-only changes and mechanical sweeps. A security change should land in a reviewable, revertable commit of its own.
+- One commit per logical change class. Don't batch "fix XSS + rename variable + reformat whitespace" into one diff.
+- Pure tests-only changes never mix with production code changes in the same commit.
+
+## Commit messages
+
+- Use a HEREDOC to pass multi-line messages: `git commit -m "$(cat <<'EOF' ... EOF)"`.
+- Single-quoted `EOF` marker (`<<'EOF'`) prevents shell expansion — required to keep `$_POST`, `$_GET`, `$variable` etc. unescaped.
+- A message with literal `\$_POST` in the body is a shell-escape artifact — amend before pushing, or treat it as a signal the HEREDOC was wrong.
+
+## Deploy tool exit codes
+
+Shared convention across IMA deploy tools:
+
+| Code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | Generic failure |
+| 2 | Validation / config error |
+| 3 | Pre-flight failure (tests, lint, clean-state check) |
+| 4 | Remote push failure (WPEngine or similar) |
+
+The authoritative record is the tool's `log.jsonl`: `tail -1 log.jsonl` shows the last run's sha, exitCode, duration. The shell's `$?` may be masked by a pipe (`| tail`), so trust the log over stdout exit.
+
+## Gitea / GitHub
+
+- IMA internal repos live on Gitea: `ssh://git@gitea.theflccc.org:2222/IMA/<repo>.git`
+- Some are mirrored to GitHub for FOSS / public presence.
+- Use `mcp-gitea` for internal repo operations, `mcp-github` or `gh-cli` for public.
+
+## When the deploy gate fails
+
+1. Check `log.jsonl` for the exit code. Don't guess from terminal output.
+2. Exit 3 = pre-flight. Look at the pipeline stage that failed — tests, lint, clean-state, composer check.
+3. Reproduce locally with the project's configured validators (`composer check`, `npm run check`, `make check`, etc.) before touching code.
+4. If a pre-flight failure is tests, invoke the source-quality triage pattern: categorize each failure as test rot, code bug, or design question **before** changing anything.
+
+## Reference
+
+- Qdrant `ima-knowledge` → article "IMA Git Workflow & Pre-flight Deploy Gate" for full detail on the gate architecture and the source-quality triage playbook.
+- Project-specific deploy specifics live in the project's Serena memory (typically named `project-workflow` or similar).

package/plugins/ima-claude/skills/scorecard/SKILL.md

@@ -26,9 +26,25 @@ Arguments are domain skills to evaluate against. If none provided, auto-detect f
 3. Identify project's primary language(s) and framework(s)
 4. Locate README (or note its absence)
 
-### Step 2: Parallel Review
+### Step 2: Run project validators (REQUIRED)
 
-Spawn parallel agents per category (`model: "sonnet"`). Each returns letter grade (A-F) + 2-3 justifying bullets. Be honest — inflated scores help nobody.
+Before any grading, discover and run the project's configured gate. Same discovery order as the `reviewer` agent:
+
+| Ecosystem | Where to look |
+|---|---|
+| PHP | `composer.json` scripts — `check`, `test`, `phpcs`, `phpcs:report` |
+| JS/TS | `package.json` scripts — `test`, `lint`, `typecheck`, `check` |
+| Make-based | `Makefile` targets — `check`, `test`, `lint`, `ci` |
+| Python | `pyproject.toml` / `tox.ini` / `noxfile.py` |
+| Ruby | `Rakefile` — `ci`, `test`, `rubocop` |
+
+Capture exit codes, error/warning counts, and test coverage % (run the coverage variant — `composer test:coverage`, `npm test -- --coverage` — when available). These are primary evidence for Code Standards, Security, and Test Coverage grades.
+
+Grades without validator backing are vibes grades. Don't ship them. No validators configured is itself a signal — floor Code Standards at C until they exist.
+
+### Step 3: Parallel Review
+
+Spawn parallel agents per category (`model: "sonnet"`). Each returns letter grade (A-F) + 2-3 justifying bullets rooted in validator output. Be honest — inflated scores help nobody.
 
 | Category | What to Evaluate | Key Signals |
 |----------|-----------------|-------------|
@@ -38,7 +54,7 @@ Spawn parallel agents per category (`model: "sonnet"`). Each returns letter grad
 | **Documentation** | README quality, inline docs, API docs | Setup instructions, usage examples, architecture notes |
 | **Maintainability** | Complexity, coupling, file organization | Small functions, clear boundaries, no circular deps |
 
-### Step 3: Compile Scores
+### Step 4: Compile Scores
 
 ```markdown
 ## Scorecard
@@ -69,7 +85,7 @@ Spawn parallel agents per category (`model: "sonnet"`). Each returns letter grad
 | D | 🔴 D | Poor — significant issues |
 | F | 🔴 F | Failing — critical problems |
 
-### Step 4: Insert into README
+### Step 5: Insert into README
 
 - Replace existing `## Scorecard` section, or insert after first heading if absent
 - Present full scorecard to user before writing