@softspark/ai-toolkit 2.0.2 → 2.1.0

package/llms.txt

@@ -27,6 +27,7 @@
 - [CI Integration](kb/reference/ci-integration.md)
 - [Claude Ecosystem Benchmark Snapshot](kb/reference/claude-ecosystem-benchmark-snapshot.md)
 - [Claude Ecosystem Expansion Foundations](kb/reference/claude-ecosystem-expansion-foundations.md)
+- [AI Toolkit - Codex CLI Compatibility](kb/reference/codex-cli-compatibility.md)
 - [Plan: Competitive Features — ai-toolkit](kb/reference/competitive-features-implementation.md)
 - [Distribution Model](kb/reference/distribution-model.md)
 - [Enterprise Config Inheritance Guide](kb/reference/enterprise-config-guide.md)
@@ -38,6 +39,7 @@
 - [Language Plugin Packs](kb/reference/language-packs.md)
 - [Language Rules System](kb/reference/language-rules.md)
 - [Manifest-Driven Install System](kb/reference/manifest-install.md)
+- [MCP Editor Compatibility](kb/reference/mcp-editor-compatibility.md)
 - [MCP Server Templates](kb/reference/mcp-templates.md)
 - [Merge-Friendly Install Model](kb/reference/merge-friendly-install-model.md)
 - [Plugin Pack Conventions](kb/reference/plugin-pack-conventions.md)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@softspark/ai-toolkit",
-  "version": "2.0.2",
-  "description": "Professional-grade AI coding toolkit: 92 skills, 44 agents, multi-platform support (Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo Code, Aider, Augment, Google Antigravity), machine-enforced safety constitution, persona presets, skill security auditor, expanded lifecycle hooks, 11 plugin packs, and benchmark tooling.",
+  "version": "2.1.0",
+  "description": "Professional-grade AI coding toolkit: 92 skills, 44 agents, multi-platform support (Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo Code, Aider, Augment, Google Antigravity, Codex CLI), machine-enforced safety constitution, persona presets, skill security auditor, expanded lifecycle hooks, 11 plugin packs, and benchmark tooling.",
   "keywords": [
     "claude",
     "claude-code",
@@ -52,10 +52,11 @@
     "generate:windsurf": "python3 scripts/generate_windsurf.py > .windsurfrules",
     "generate:copilot": "python3 scripts/generate_copilot.py > .github/copilot-instructions.md",
     "generate:gemini": "python3 scripts/generate_gemini.py > GEMINI.md",
-    "generate:cline": "python3 scripts/generate_cline.py > .clinerules",
+    "generate:cline": "python3 scripts/generate_cline_rules.py .",
     "generate:roo": "python3 scripts/generate_roo_modes.py > .roomodes",
     "generate:aider": "python3 scripts/generate_aider_conf.py > .aider.conf.yml",
-    "generate:all": "npm run generate:agents && npm run generate:cursor && npm run generate:windsurf && npm run generate:copilot && npm run generate:gemini && npm run generate:cline && npm run generate:roo && npm run generate:aider && npm run generate:llms"
+    "generate:codex-rules": "python3 scripts/generate_codex_rules.py .",
+    "generate:all": "npm run generate:agents && npm run generate:codex-rules && npm run generate:cursor && npm run generate:windsurf && npm run generate:copilot && npm run generate:gemini && npm run generate:cline && npm run generate:roo && npm run generate:aider && npm run generate:llms"
   },
   "files": [
     "bin/",

package/scripts/codex_skill_adapter.py

@@ -0,0 +1,295 @@
+"""Adapt ai-toolkit skills for Codex CLI.
+
+Compatible skills are symlinked as-is. Skills that rely on Claude-only
+delegation primitives are rendered into Codex-specific wrappers that keep the
+same references/assets but rewrite the main SKILL.md guidance to use native
+Codex subagents and plan tracking.
+"""
+from __future__ import annotations
+
+import re
+import shutil
+import sys
+from pathlib import Path
+
+try:
+    from frontmatter import frontmatter_field
+except ModuleNotFoundError:
+    sys.path.insert(0, str(Path(__file__).resolve().parent))
+    from frontmatter import frontmatter_field
+
+
+CLAUDE_ONLY_TOOLS = frozenset({
+    "Agent", "TeamCreate", "TeamDelete", "SendMessage",
+    "TaskCreate", "TaskList", "TaskUpdate", "TaskGet", "TaskOutput", "TaskStop",
+    "Skill", "EnterPlanMode", "ExitPlanMode",
+})
+
+CODEX_DELEGATION_TOOLS = (
+    "spawn_agent", "send_input", "wait_agent", "close_agent", "update_plan",
+)
+
+ADAPTED_MARKER = ".ai-toolkit-codex-adapted"
+
+_FRONTMATTER_RE = re.compile(r"\A---\n(?P<frontmatter>.*?)\n---\n?(?P<body>.*)\Z", re.S)
+_SINGLE_AGENT_CALL_RE = re.compile(
+    r'Agent\(subagent_type="([^"]+)",\s*prompt="([^"]+)"[^)]*\)'
+)
+_MULTILINE_AGENT_CALL_RE = re.compile(
+    r'Agent\(\s*\n'
+    r'\s*subagent_type="([^"]+)"\s*,\s*\n'
+    r'\s*description="([^"]+)"\s*,\s*\n'
+    r'\s*prompt="([^"]+)"\s*\n'
+    r'\)',
+    re.S,
+)
+
+_CODEX_NOTE = """
+## Codex Translation Layer
+
+This generated Codex variant preserves the original workflow while translating
+Claude-only delegation primitives into Codex-native ones:
+
+- Use `spawn_agent(..., fork_context=True, ...)` instead of Claude `Agent(...)`.
+- Pick `explorer` for read-only discovery, `worker` for edits, `default` for
+  synthesis, planning, and mixed execution.
+- Use `send_input` to redirect or clarify an active subagent.
+- Use `wait_agent` only when the next critical-path step is blocked on a
+  delegated result.
+- Use `close_agent` after integrating finished subagents.
+- Track progress with `update_plan` or a local checklist instead of Claude
+  task/team APIs.
+- Treat a "team" as a coordinated set of spawned subagents with explicit file
+  ownership. No extra Codex feature flag is required.
+"""
+
+
+def skill_tools(skill_file: Path) -> list[str]:
+    """Return ordered allowed-tools entries from a skill frontmatter block."""
+    tools_str = frontmatter_field(skill_file, "allowed-tools") or ""
+    return [tool.strip() for tool in tools_str.split(",") if tool.strip()]
+
+
+def is_codex_adapted_skill(skill_file: Path) -> bool:
+    """Return True if a skill needs Claude→Codex delegation adaptation."""
+    return bool(set(skill_tools(skill_file)) & CLAUDE_ONLY_TOOLS)
+
+
+def codex_skill_description(skill_file: Path) -> str:
+    """Return the skill description shown in Codex-facing generators."""
+    description = frontmatter_field(skill_file, "description")
+    if not description:
+        return ""
+    if is_codex_adapted_skill(skill_file):
+        return f"{description} Codex-adapted: uses native subagents and plan tracking."
+    return description
+
+
+def build_codex_skill_text(skill_file: Path) -> str:
+    """Render the Codex-facing SKILL.md contents for a source skill."""
+    text = skill_file.read_text(encoding="utf-8")
+    match = _FRONTMATTER_RE.match(text)
+    if not match:
+        return text
+
+    frontmatter = _parse_frontmatter(match.group("frontmatter"))
+    body = match.group("body")
+    adapted = is_codex_adapted_skill(skill_file)
+
+    if adapted:
+        frontmatter = _adapt_frontmatter(frontmatter)
+        body = _adapt_body(skill_file.parent.name, body)
+
+    rendered_frontmatter = _render_frontmatter(frontmatter)
+    return f"---\n{rendered_frontmatter}\n---\n{body.rstrip()}\n"
+
+
+def sync_codex_skill(skill_dir: Path, skills_dst: Path) -> str:
+    """Install one skill into `.agents/skills/` and return its mode."""
+    skill_file = skill_dir / "SKILL.md"
+    target = skills_dst / skill_dir.name
+    adapted = is_codex_adapted_skill(skill_file)
+    marker = target / ADAPTED_MARKER
+
+    if adapted:
+        if target.is_symlink():
+            target.unlink()
+        elif target.is_dir() and not marker.is_file():
+            return "skipped"
+        elif target.is_dir():
+            shutil.rmtree(target)
+        elif target.exists():
+            return "skipped"
+
+        target.mkdir(parents=True, exist_ok=True)
+        marker.write_text("generated by ai-toolkit for Codex\n", encoding="utf-8")
+
+        for child in sorted(skill_dir.iterdir()):
+            dest = target / child.name
+            if child.name == "SKILL.md":
+                continue
+            if dest.is_symlink() or dest.is_file():
+                dest.unlink()
+            elif dest.is_dir():
+                shutil.rmtree(dest)
+            dest.symlink_to(child)
+
+        (target / "SKILL.md").write_text(build_codex_skill_text(skill_file), encoding="utf-8")
+        return "adapted"
+
+    if target.is_symlink():
+        if target.resolve() == skill_dir.resolve():
+            return "linked"
+        target.unlink()
+    elif target.is_dir():
+        if marker.is_file():
+            shutil.rmtree(target)
+        else:
+            return "skipped"
+    elif target.exists():
+        return "skipped"
+
+    target.symlink_to(skill_dir)
+    return "linked"
+
+
+def cleanup_codex_skills(skills_dst: Path, skills_src: Path) -> None:
+    """Remove broken symlinks and stale generated Codex skill wrappers."""
+    for item in skills_dst.iterdir():
+        src = skills_src / item.name
+        if item.is_symlink() and not item.exists():
+            item.unlink()
+            continue
+        if item.is_dir() and (item / ADAPTED_MARKER).is_file() and not src.is_dir():
+            shutil.rmtree(item)
+
+
+def _parse_frontmatter(frontmatter_text: str) -> list[tuple[str, str]]:
+    entries: list[tuple[str, str]] = []
+    for line in frontmatter_text.splitlines():
+        if ":" not in line:
+            continue
+        key, value = line.split(":", 1)
+        entries.append((key.strip(), value.strip()))
+    return entries
+
+
+def _render_frontmatter(entries: list[tuple[str, str]]) -> str:
+    return "\n".join(f"{key}: {value}" for key, value in entries)
+
+
+def _adapt_frontmatter(entries: list[tuple[str, str]]) -> list[tuple[str, str]]:
+    adapted: list[tuple[str, str]] = []
+    for key, value in entries:
+        if key in {"context", "agent", "model"}:
+            continue
+        if key == "description":
+            stripped = _strip_quotes(value)
+            value = f'"{stripped} Codex-adapted: uses native subagents and plan tracking."'
+        elif key == "allowed-tools":
+            value = ", ".join(_adapt_allowed_tools(value))
+        adapted.append((key, value))
+    return adapted
+
+
+def _adapt_allowed_tools(value: str) -> list[str]:
+    tools = []
+    for tool in [item.strip() for item in value.split(",") if item.strip()]:
+        if tool in CLAUDE_ONLY_TOOLS:
+            continue
+        if tool not in tools:
+            tools.append(tool)
+    for tool in CODEX_DELEGATION_TOOLS:
+        if tool not in tools:
+            tools.append(tool)
+    return tools
+
+
+def _adapt_body(skill_name: str, body: str) -> str:
+    body = body.replace(
+        "## MANDATORY: You MUST use the Agent tool",
+        "## MANDATORY: Use Codex subagents for delegation",
+    )
+    body = body.replace("`Agent` tool", "Codex subagent tools")
+    body = body.replace("the `Agent` tool", "Codex subagent tools")
+    body = body.replace("Agent tool", "Codex subagent tools")
+    body = body.replace("Agent Teams", "parallel Codex subagents")
+    body = body.replace(
+        "Requires: `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`",
+        "Requires: native Codex subagent support (`spawn_agent`, `send_input`, `wait_agent`, `close_agent`)",
+    )
+    body = body.replace(
+        "Check `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` is set; warn if not",
+        "Confirm the user explicitly wants delegated/subagent execution before launching workers",
+    )
+    body = body.replace(
+        "export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1",
+        "# No extra environment variable is required in Codex",
+    )
+    body = body.replace("TaskCreate", "update_plan")
+    body = body.replace("TaskList", "update_plan")
+    body = body.replace("TaskUpdate", "update_plan")
+    body = body.replace("TaskGet", "wait_agent")
+    body = body.replace("TaskOutput", "wait_agent")
+    body = body.replace("TaskStop", "close_agent")
+    body = body.replace("SendMessage", "send_input")
+    body = body.replace("TeamCreate", "spawn_agent")
+    body = body.replace("TeamDelete", "close_agent")
+
+    body = _MULTILINE_AGENT_CALL_RE.sub(_replace_multiline_agent_call, body)
+    body = _SINGLE_AGENT_CALL_RE.sub(_replace_single_agent_call, body)
+
+    if "$ARGUMENTS" in body:
+        body = body.replace("$ARGUMENTS", f"$ARGUMENTS\n{_CODEX_NOTE.rstrip()}", 1)
+
+    if skill_name == "teams":
+        body = body.replace(
+            "Launches a pre-configured Agent Teams composition for your task.",
+            "Launches a pre-configured Codex subagent composition for your task.",
+        )
+    return body
+
+
+def _replace_single_agent_call(match: re.Match[str]) -> str:
+    role = match.group(1)
+    prompt = match.group(2)
+    agent_type = _codex_agent_type(role, prompt)
+    escaped_prompt = prompt.replace('"', "'")
+    return (
+        f'spawn_agent(agent_type="{agent_type}", fork_context=True, '
+        f'message="Act as {role}. {escaped_prompt}")'
+    )
+
+
+def _replace_multiline_agent_call(match: re.Match[str]) -> str:
+    role = match.group(1)
+    prompt = match.group(3).replace('"', "'")
+    return (
+        "spawn_agent(\n"
+        f'  agent_type="{_codex_agent_type(role, prompt)}",\n'
+        "  fork_context=True,\n"
+        f'  message="Act as {role}. {prompt}"\n'
+        ")"
+    )
+
+
+def _codex_agent_type(role: str, prompt: str) -> str:
+    role_l = role.lower()
+    prompt_l = prompt.lower()
+    if role_l == "explorer-agent":
+        return "explorer"
+    if any(token in prompt_l for token in ("read-only", "review", "audit", "trace", "map ", "analyze")):
+        return "default"
+    if any(token in prompt_l for token in (
+        "own files:", "implement", "write ", "apply", "build ", "update ",
+        "create ", "execute ", "fix", "document", "deploy",
+    )):
+        return "worker"
+    return "default"
+
+
+def _strip_quotes(value: str) -> str:
+    value = value.strip()
+    if len(value) >= 2 and value[0] == value[-1] and value[0] in {'"', "'"}:
+        return value[1:-1]
+    return value

package/scripts/dir_rules_shared.py

@@ -20,6 +20,11 @@ from emission import (
 )
 
 PREFIX = "ai-toolkit-"
+LANG_PREFIX = f"{PREFIX}lang-"
+CUSTOM_PREFIX = f"{PREFIX}custom-"
+STANDARD_SCOPE = "standard"
+LANG_SCOPE = "lang"
+CUSTOM_SCOPE = "custom"
 
 
 # ---------------------------------------------------------------------------
@@ -415,25 +420,59 @@ STANDARD_WORKFLOWS: dict[str, callable] = {
 # Shared file generation helpers
 # ---------------------------------------------------------------------------
 
-def cleanup_stale(directory: Path, current_files: set[str]) -> None:
-    """Remove ai-toolkit-* files that are no longer in the registry."""
+def rule_scope(filename: str) -> str | None:
+    """Classify a generated rule file by ownership scope."""
+    if filename.startswith(LANG_PREFIX):
+        return LANG_SCOPE
+    if filename.startswith(CUSTOM_PREFIX):
+        return CUSTOM_SCOPE
+    if filename.startswith(PREFIX):
+        return STANDARD_SCOPE
+    return None
+
+
+def cleanup_stale(
+    directory: Path,
+    current_files: set[str],
+    *,
+    managed_scopes: tuple[str, ...] = (STANDARD_SCOPE, LANG_SCOPE, CUSTOM_SCOPE),
+    extra_managed_names: set[str] | None = None,
+) -> None:
+    """Remove managed files that are no longer in the active registry."""
     if not directory.is_dir():
         return
+    scope_set = set(managed_scopes)
+    extra_names = extra_managed_names or set()
     for f in directory.iterdir():
-        if f.name.startswith(PREFIX) and f.name not in current_files:
+        if f.name in current_files:
+            continue
+        if f.name in extra_names:
+            f.unlink()
+            print(f"  Removed stale: {f.relative_to(directory.parent.parent)}")
+            continue
+        if rule_scope(f.name) in scope_set:
             f.unlink()
             print(f"  Removed stale: {f.relative_to(directory.parent.parent)}")
 
 
 def write_rules(target_dir: Path, rules: dict[str, callable],
-                subdir: str = "rules", label: str = "") -> None:
+                subdir: str = "rules", label: str = "",
+                cleanup: bool = True,
+                managed_scopes: tuple[str, ...] = (STANDARD_SCOPE, LANG_SCOPE, CUSTOM_SCOPE),
+                extra_managed_names: set[str] | None = None) -> None:
     """Write rule files to target_dir/<subdir>/.
 
     Only writes ai-toolkit-* files. User files are never touched.
     """
     out_dir = target_dir / subdir
     out_dir.mkdir(parents=True, exist_ok=True)
-    cleanup_stale(out_dir, set(rules.keys()))
+    if cleanup:
+        cleanup_stale(
+            out_dir,
+            set(rules.keys()),
+            managed_scopes=managed_scopes,
+            extra_managed_names=extra_managed_names,
+        )
 
     for filename, content_fn in rules.items():
         (out_dir / filename).write_text(content_fn(), encoding="utf-8")
@@ -511,7 +550,7 @@ def build_language_rules(
 
         if parts:
             combined = "\n\n".join(parts) + "\n"
-            filename = f"{PREFIX}lang-{lang}.md"
+            filename = f"{LANG_PREFIX}{lang}.md"
             # Capture value via default arg to avoid late-binding closure
             result[filename] = (lambda c: lambda: c)(combined)
 
@@ -531,7 +570,7 @@ def build_registered_rules(
     result: dict[str, callable] = {}
     for rule_file in sorted(rules_dir.glob("*.md")):
         content = rule_file.read_text(encoding="utf-8")
-        filename = f"{PREFIX}custom-{rule_file.stem}.md"
+        filename = f"{CUSTOM_PREFIX}{rule_file.stem}.md"
         result[filename] = (lambda c: lambda: c)(content)
 
     return result

package/scripts/generate_cline_rules.py

@@ -16,6 +16,7 @@ from pathlib import Path
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 from dir_rules_shared import (
     STANDARD_RULES,
+    STANDARD_SCOPE,
     build_language_rules,
     build_registered_rules,
     write_rules,
@@ -24,7 +25,9 @@ from dir_rules_shared import (
 
 def generate(target_dir: Path, *,
              language_modules: list[str] | None = None,
-             rules_dir: Path | None = None) -> None:
+             rules_dir: Path | None = None,
+             cleanup: bool = True,
+             managed_scopes: tuple[str, ...] = (STANDARD_SCOPE,)) -> None:
     """Write .clinerules/*.md files to target_dir."""
     # Migrate: if .clinerules exists as a single file, remove it
     # so the directory can be created (Cline 3.7+ uses directory format)
@@ -34,7 +37,13 @@ def generate(target_dir: Path, *,
     rules = dict(STANDARD_RULES)
     rules.update(build_language_rules(language_modules))
     rules.update(build_registered_rules(rules_dir))
-    write_rules(target_dir, rules, ".clinerules")
+    write_rules(
+        target_dir,
+        rules,
+        ".clinerules",
+        cleanup=cleanup,
+        managed_scopes=managed_scopes,
+    )
 
 
 def main() -> None:

package/scripts/generate_codex.py

@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+"""Generate AGENTS.md content for OpenAI Codex CLI.
+
+Adapts Claude-oriented skills to Codex-native delegation guidance so the full
+skill catalog can be surfaced in Codex installs.
+
+Usage: ./scripts/generate_codex.py > AGENTS.md
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from codex_skill_adapter import codex_skill_description
+from emission import (
+    agents_dir,
+    skills_dir,
+    generate_quality_standards,
+    generate_workflow_guidelines,
+    print_toolkit_end,
+    print_toolkit_start,
+)
+from frontmatter import frontmatter_field
+
+
+def _emit_agents() -> str:
+    """Emit agents as bullets."""
+    lines: list[str] = []
+    for agent_file in sorted(agents_dir.glob("*.md")):
+        name = frontmatter_field(agent_file, "name")
+        description = frontmatter_field(agent_file, "description")
+        if not name or not description:
+            continue
+        lines.append(f"- **{name}**: {description}")
+    return "\n".join(lines)
+
+
+def _emit_skills() -> str:
+    """Emit skills as bullets, adapting Claude-native descriptions for Codex."""
+    lines: list[str] = []
+    for skill_dir in sorted(skills_dir.iterdir()):
+        if skill_dir.name.startswith("_"):
+            continue
+        skill_file = skill_dir / "SKILL.md"
+        if not skill_file.is_file():
+            continue
+        name = frontmatter_field(skill_file, "name")
+        description = codex_skill_description(skill_file)
+        if not name or not description:
+            continue
+        lines.append(f"- **{name}**: {description}")
+    return "\n".join(lines)
+
+
+def main() -> None:
+    print_toolkit_start()
+
+    print("# AI Toolkit — Codex CLI Configuration")
+    print()
+    print(
+        "Shared AI development toolkit with specialized agents,"
+        " Codex-compatible skills, quality hooks, and a safety constitution."
+    )
+
+    # Agents (all agents are informational — safe to list)
+    print()
+    print("## Available Agents")
+    print()
+    print("Specialized agent personas — apply their expertise for relevant tasks:")
+    print()
+    print(_emit_agents())
+
+    # Skills
+    print()
+    print("## Available Skills")
+    print()
+    print("Skills are invocable commands or auto-loaded knowledge sources:")
+    print()
+    print(_emit_skills())
+
+    # Guidelines
+    print()
+    print(generate_quality_standards())
+    print()
+    print(generate_workflow_guidelines())
+
+    print_toolkit_end()
+
+
+if __name__ == "__main__":
+    main()

package/scripts/generate_codex_hooks.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+"""Generate .codex/hooks.json for OpenAI Codex CLI.
+
+Maps compatible ai-toolkit hooks to Codex lifecycle events.
+Hook scripts are shared with Claude Code (stored in ~/.softspark/ai-toolkit/hooks/).
+
+Codex supports 5 events: SessionStart, PreToolUse, PostToolUse,
+UserPromptSubmit, Stop. PreToolUse/PostToolUse only support Bash matcher.
+
+Usage:
+  python3 scripts/generate_codex_hooks.py [target-dir]
+
+Writes .codex/hooks.json to target-dir.
+"""
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+
+HOOKS_PREFIX = '"$HOME/.softspark/ai-toolkit/hooks/'
+
+# Hooks compatible with Codex, grouped by event.
+# Format: (matcher, script_name)
+CODEX_HOOKS: dict[str, list[tuple[str, str]]] = {
+    "SessionStart": [
+        ("startup|resume", "session-start.sh"),
+        ("startup|resume", "mcp-health.sh"),
+        ("startup|resume", "session-context.sh"),
+    ],
+    "PreToolUse": [
+        ("Bash", "guard-destructive.sh"),
+        ("Bash", "commit-quality.sh"),
+    ],
+    "UserPromptSubmit": [
+        ("", "user-prompt-submit.sh"),
+        ("", "track-usage.sh"),
+    ],
+    "Stop": [
+        ("", "quality-check.sh"),
+        ("", "save-session.sh"),
+    ],
+}
+
+
+def build_hooks_json() -> dict:
+    """Build the hooks.json structure for Codex."""
+    hooks: dict[str, list] = {}
+    for event, entries in CODEX_HOOKS.items():
+        hooks[event] = []
+        for matcher, script in entries:
+            entry: dict = {"hooks": [{"type": "command", "command": f"{HOOKS_PREFIX}{script}\""}]}
+            if matcher:
+                entry["matcher"] = matcher
+            hooks[event].append(entry)
+    return {"hooks": hooks}
+
+
+def generate(target_dir: Path) -> None:
+    """Write .codex/hooks.json to target_dir."""
+    codex_dir = target_dir / ".codex"
+    codex_dir.mkdir(parents=True, exist_ok=True)
+    hooks_path = codex_dir / "hooks.json"
+    data = build_hooks_json()
+    with open(hooks_path, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=4, ensure_ascii=False)
+        f.write("\n")
+
+
+def main() -> None:
+    target = Path(sys.argv[1]) if len(sys.argv) > 1 else Path.cwd()
+    generate(target)
+    print(f"Generated: .codex/hooks.json ({sum(len(v) for v in CODEX_HOOKS.values())} hooks)")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/generate_codex_rules.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+"""Generate Codex CLI .agents/rules/ files.
+
+Codex discovers rules in .agents/rules/ at the project root.
+This generator follows the same pattern as generate_antigravity.py.
+
+Usage:
+  python3 scripts/generate_codex_rules.py [target-dir]
+
+Writes files directly to target-dir/.agents/rules/.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from dir_rules_shared import (
+    STANDARD_RULES,
+    STANDARD_SCOPE,
+    build_language_rules,
+    build_registered_rules,
+    write_rules,
+)
+
+
+def generate(target_dir: Path, *,
+             language_modules: list[str] | None = None,
+             rules_dir: Path | None = None,
+             cleanup: bool = True,
+             managed_scopes: tuple[str, ...] = (STANDARD_SCOPE,)) -> None:
+    """Write .agents/rules/ files to target_dir."""
+    rules = dict(STANDARD_RULES)
+    rules.update(build_language_rules(language_modules))
+    rules.update(build_registered_rules(rules_dir))
+    write_rules(
+        target_dir,
+        rules,
+        ".agents/rules",
+        cleanup=cleanup,
+        managed_scopes=managed_scopes,
+    )
+
+
+def main() -> None:
+    target = Path(sys.argv[1]) if len(sys.argv) > 1 else Path.cwd()
+    generate(target)
+
+
+if __name__ == "__main__":
+    main()