@softspark/ai-toolkit 2.0.1 → 2.1.0

package/CHANGELOG.md

@@ -7,6 +7,43 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v2.1.0 — Codex CLI Support & Native Editor MCP Install (2026-04-13)
+
+### Added
+- **Codex CLI as 10th editor** — full support via `--editors codex`: `AGENTS.md`, `.agents/rules/*.md`, `.agents/skills/*`, `.codex/hooks.json`
+- **Codex skill translation layer** — Claude-only orchestration skills (orchestrate, workflow, swarm, teams, subagent-development) are automatically translated to Codex-native `spawn_agent`/`update_plan` wrappers; native skills are symlinked directly
+- **Native editor MCP install** — `ai-toolkit mcp install --editor <name> --scope project|global` renders canonical `.mcp.json` templates into 8 editor-native config formats (Claude, Cursor, Copilot, Gemini, Windsurf, Cline, Augment, Codex)
+- **MCP auto-sync on local install** — `install --local` mirrors `.mcp.json` into `.claude/settings.local.json` plus selected project editors (Cursor, Copilot)
+- **`mcp editors` subcommand** — lists all supported native MCP adapters with scope/path info
+- **Cross-editor verification SOP** — mandatory check against official docs before adding any component
+- **Runtime-aware plugin installs** — `ai-toolkit plugin install|update|remove|status --editor claude|codex|all` now targets Claude and a global Codex plugin layer consistently
+- **Global Codex plugin layer** — plugin packs can bootstrap `~/AGENTS.md`, `~/.agents/`, and `~/.codex/hooks.json` without changing the default project-local Codex core install model
+- **Plugin lifecycle tests** — coverage for install/update/remove behavior across Claude and Codex runtimes, including shared asset retention
+- **Safe Codex and Cline rule regeneration** — `generate_codex_rules.py` and `generate_cline_rules.py` now support `--skip-cleanup` to refresh standard generated rules without deleting custom overlays
+
+### New Files
+- `scripts/mcp_editors.py` — 8 native MCP config adapters
+- `scripts/codex_skill_adapter.py` — skill translation layer for Codex
+- `scripts/generate_codex.py` — AGENTS.md generator with Codex orchestration guidance
+- `scripts/generate_codex_hooks.py` — `.codex/hooks.json` generator
+- `scripts/generate_codex_rules.py` — `.agents/rules/*.md` generator
+- `kb/reference/codex-cli-compatibility.md` — Codex mapping reference
+- `kb/reference/mcp-editor-compatibility.md` — native MCP support matrix
+- `tests/test_plugin.bats` — runtime-aware plugin install/remove coverage
+
+### Changed
+- **Release workflow** — `generate:all` now refreshes tracked Codex rules and uses the directory-based Cline generator that matches the current repository layout
+- **Documentation** — README, KB references, maintenance SOPs, and generated artifacts now consistently describe the Claude + global Codex plugin model
+
+---
+
+## v2.0.2 — Clean Legacy Directory Removal (2026-04-12)
+
+### Fixed
+- **Migration cleanup** — `~/.ai-toolkit/` is now fully removed after migration instead of leaving an empty directory with a `.migrated` marker
+
+---
+
 ## v2.0.1 — Migration Hook Path Fix (2026-04-12)
 
 ### Fixed

package/README.md

@@ -1,12 +1,12 @@
 # ai-toolkit
 
-> Professional-grade AI coding toolkit with multi-platform support. Machine-enforced safety, 92 skills, 44 agents, expanded lifecycle hooks, persona presets, experimental opt-in plugin packs, and benchmark tooling — works with Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo Code, Aider, Augment, and Google Antigravity, ready in 60 seconds.
+> Professional-grade AI coding toolkit with multi-platform support. Machine-enforced safety, 92 skills, 44 agents, expanded lifecycle hooks, persona presets, experimental opt-in plugin packs, and benchmark tooling — works with Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo Code, Aider, Augment, Google Antigravity, and Codex CLI, ready in 60 seconds.
 
 [![CI](https://github.com/softspark/ai-toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/softspark/ai-toolkit/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Skills](https://img.shields.io/badge/skills-92-brightgreen)](app/skills/)
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
-[![Tests](https://img.shields.io/badge/tests-575%20passing-success)](tests/)
+[![Tests](https://img.shields.io/badge/tests-598%20passing-success)](tests/)
 
 ---
 
@@ -36,7 +36,7 @@ After global install, run `--local` in each project. By default, only Claude Cod
 ```bash
 cd your-project/
 ai-toolkit install --local                     # Claude Code only
-ai-toolkit install --local --editors all       # + all editors (Cursor, Windsurf, Cline, Roo, Aider, Augment, Copilot, Antigravity)
+ai-toolkit install --local --editors all       # + all editors (Cursor, Windsurf, Cline, Roo, Aider, Augment, Copilot, Antigravity, Codex)
 ai-toolkit install --local --editors cursor,aider  # + specific editors
 ai-toolkit update --local                      # auto-detects editors from existing project files
 ```
@@ -45,13 +45,19 @@ ai-toolkit update --local                      # auto-detects editors from exist
 
 ```bash
 ai-toolkit plugin list             # show available packs
-ai-toolkit plugin install --all    # install all packs
-ai-toolkit plugin update --all     # re-apply after toolkit updates
-ai-toolkit plugin status           # show what's installed
+ai-toolkit plugin install --editor all --all   # install all packs for Claude + Codex
+ai-toolkit plugin install --editor codex memory-pack   # Codex global target
+ai-toolkit plugin update --editor all --all    # re-apply after toolkit updates
+ai-toolkit plugin status --editor all          # show what's installed per runtime
 ai-toolkit plugin clean memory-pack --days 30  # prune old data
 ```
 
-After each `ai-toolkit update`, also run `ai-toolkit plugin update --all` to keep plugin hooks and scripts in sync.
+`plugin` is editor-aware:
+- `--editor claude` targets global Claude install in `~/.claude/`
+- `--editor codex` targets global Codex assets in `HOME` (`~/AGENTS.md`, `~/.agents/`, `~/.codex/hooks.json`)
+- `--editor all` applies both
+
+After each `ai-toolkit update`, also run `ai-toolkit plugin update --editor all --all` to keep plugin hooks and scripts in sync.
 
 ### Install Profiles
 
@@ -139,9 +145,9 @@ Compiles the full toolkit (20K+ tokens) into a minimal system prompt that fits S
 | Aider | `.aider.conf.yml` + `CONVENTIONS.md` | `ai-toolkit install --local` | project |
 | Augment | `.augment/rules/ai-toolkit-*.md` | `ai-toolkit install --local` | project |
 | Google Antigravity | `.agent/rules/*.md` + `.agent/workflows/*.md` | `ai-toolkit install --local` | project |
-| Codex / OpenCode | `AGENTS.md` | `ai-toolkit agents-md` | project |
+| Codex CLI | `AGENTS.md` + `.agents/rules/*.md` + `.agents/skills/*` + `.codex/hooks.json` | `ai-toolkit install --local` for project files, `ai-toolkit plugin install --editor codex` for global plugin layer | project + optional global plugin layer |
 
-> **Note:** Claude Code is always installed (primary platform with full feature support). Other editors are installed on demand with `--editors <list>` or auto-detected from existing project files. All platforms receive the same agent/skill catalog, guidelines, rules, language-specific rules, and registered custom rules. For editors lacking native bash lifecycle hooks, `--local` installs a Git hooks fallback (`.git/hooks/pre-commit`) to enforce quality gates pre-commit.
+> **Note:** Claude Code is always installed (primary platform with full feature support). Other editors are installed on demand with `--editors <list>` or auto-detected from existing project files. All platforms receive the same agent/skill catalog, guidelines, rules, language-specific rules, and registered custom rules. Codex CLI core install remains project-local and receives all 92 skills via `.agents/skills/`: native Codex-compatible skills are symlinked directly, while Claude-native orchestration skills are translated into Codex subagent workflows during install. Experimental plugin packs can additionally target a global Codex surface in `HOME` (`~/AGENTS.md`, `~/.agents/`, `~/.codex/hooks.json`). For editors lacking native bash lifecycle hooks, `--local` installs a Git hooks fallback (`.git/hooks/pre-commit`) to enforce quality gates pre-commit.
 
 ---
 
@@ -524,10 +530,27 @@ Agents follow a research-before-action protocol enforced via rules:
 ai-toolkit mcp add github slack           # add GitHub + Slack MCP servers
 ai-toolkit mcp list                       # browse all 25 templates
 ai-toolkit mcp show postgres              # inspect config before adding
+ai-toolkit mcp install --editor cursor --scope project github --target .
+ai-toolkit mcp install --editor codex context7
 ```
 
 Templates include: GitHub, PostgreSQL, Slack, Sentry, Context7, Brave Search, Supabase, Cloudflare, Vercel, and 16 more. Each is a validated JSON config fragment merged into `.mcp.json`.
 
+Native editor MCP install is available where the client exposes a stable config format:
+
+| Editor | Scope | Native MCP Config |
+|--------|-------|-------------------|
+| Claude Code | project + global | `.claude/settings.local.json`, `~/.claude/settings.json` |
+| Cursor | project + global | `.cursor/mcp.json`, `~/.cursor/mcp.json` |
+| GitHub Copilot | project + global | `.github/mcp.json`, `~/.copilot/mcp-config.json` |
+| Gemini CLI | project + global | `.gemini/settings.json`, `~/.gemini/settings.json` |
+| Windsurf | global | `~/.codeium/windsurf/mcp_config.json` |
+| Cline | global | `~/.cline/data/settings/cline_mcp_settings.json` |
+| Augment | global | `~/.augment/settings.json` |
+| Codex CLI | global | `~/.codex/config.toml` |
+
+`install --local` now auto-syncs project `.mcp.json` into Claude project settings plus selected project editors that support repository/workspace MCP configs (`cursor`, `copilot`). Global-only clients are configured explicitly with `ai-toolkit mcp install --editor ...`.
+
 ---
 
 ## Language Rules
@@ -552,6 +575,7 @@ When `--editors` is used alongside detected or explicit languages, language rule
 | Roo Code | `.roo/rules/ai-toolkit-lang-<lang>.md` | always loaded |
 | Augment | `.augment/rules/ai-toolkit-lang-<lang>.md` | `agent_requested` with globs |
 | Antigravity | `.agent/rules/ai-toolkit-lang-<lang>.md` | always loaded |
+| Codex CLI | `.agents/rules/ai-toolkit-lang-<lang>.md` | always loaded |
 
 Registered rules (`ai-toolkit add-rule`) are also propagated to directory-based editor configs as `ai-toolkit-custom-<name>` files.
 
@@ -667,7 +691,7 @@ ai-toolkit update                # global update + parallel update ALL projects
 | Effort-based model budgeting | **Yes** | No | No | No |
 | Test suite | Yes (bats) | Yes (997 tests) | No | Yes |
 | npm/npx install | Yes | Yes | Yes | Yes |
-| Cross-tool support | **Cursor, Windsurf, Copilot, Gemini, Cline, Roo, Aider, Augment, Antigravity** | 5+ tools | Smithery | Limited |
+| Cross-tool support | **Cursor, Windsurf, Copilot, Gemini, Cline, Roo, Aider, Augment, Antigravity, Codex** | 5+ tools | Smithery | Limited |
 | Selective install | Yes | Yes | Yes (72 plugins) | No |
 | Session persistence | Yes | Yes | No | No |
 | Architecture notes | **Yes** | No | No | No |
@@ -708,7 +732,7 @@ Pre-configured team presets via `/teams`:
 | Aider | `.aider.conf.yml` | project |
 | Augment | `.augment/rules/ai-toolkit-*.md` | project |
 | Google Antigravity | `.agent/rules/` + `.agent/workflows/` | project |
-| Codex / OpenCode | `AGENTS.md` | project |
+| Codex CLI | `AGENTS.md` + `.agents/rules/` + `.agents/skills/` + `.codex/hooks.json` | project + optional global plugin layer in `HOME` |
 
 ```bash
 # First-time install (Claude + Cursor + Windsurf + Gemini)
@@ -720,7 +744,7 @@ ai-toolkit update
 # Init project (Claude Code configs only: CLAUDE.md, settings, constitution, language rules)
 ai-toolkit install --local
 
-# Init with all editors (Cursor, Windsurf, Cline, Roo, Aider, Augment, Copilot, Antigravity)
+# Init with all editors (Cursor, Windsurf, Cline, Roo, Aider, Augment, Copilot, Antigravity, Codex)
 ai-toolkit install --local --editors all
 
 # Update project — auto-detects editors from existing config files
@@ -807,9 +831,11 @@ Usage: ai-toolkit <command> [options]
 | `inject-hook <file.json>` | Inject external hooks into settings.json (idempotent, `_source` tagged) |
 | `remove-hook <name>` | Remove injected hooks by source name |
 | `mcp list` | List available MCP server templates (25 templates) |
+| `mcp editors` | List editors with native MCP config adapters and scopes |
 | `mcp add <name> [names...]` | Add MCP server template(s) to `.mcp.json` |
+| `mcp install --editor <name[,..]> [names...]` | Install templates into native editor MCP config |
 | `mcp show <name>` | Show MCP template config details |
-| `mcp remove <name>` | Remove MCP server from `.mcp.json` |
+| `mcp remove <name>` | Remove MCP server from `.mcp.json` or editor MCP config |
 | `config validate [path]` | Validate `.softspark-toolkit.json` schema + extends + enforcement |
 | `config diff [path]` | Show project vs base config differences |
 | `config init [flags]` | Create `.softspark-toolkit.json` (`--extends`, `--profile`, `--no-extends`) |
@@ -823,13 +849,13 @@ Usage: ai-toolkit <command> [options]
 | `doctor --fix` | Auto-repair broken symlinks, missing hooks, stale artifacts |
 | `eject [dir]` | Export standalone config (no symlinks, no toolkit dependency) |
 | `plugin list` | Show available plugin packs with install status |
-| `plugin install <name>` | Install a plugin pack (hooks, scripts, verify agents/skills) |
-| `plugin install --all` | Install all 11 plugin packs |
-| `plugin update <name>` | Update a plugin pack (remove + reinstall, preserves data) |
-| `plugin update --all` | Update all installed plugin packs |
+| `plugin install <name> [--editor claude|codex|all]` | Install a plugin pack for selected runtime(s) |
+| `plugin install --all [--editor claude|codex|all]` | Install all 11 plugin packs for selected runtime(s) |
+| `plugin update <name> [--editor claude|codex|all]` | Update a plugin pack (remove + reinstall, preserves data) |
+| `plugin update --all [--editor claude|codex|all]` | Update all installed plugin packs for selected runtime(s) |
 | `plugin clean <name> [--days N]` | Prune old plugin data (default: 90 days) |
-| `plugin remove <name>` | Remove a plugin pack |
-| `plugin status` | Show installed plugins with data stats (DB size, observation count) |
+| `plugin remove <name> [--editor claude|codex|all]` | Remove a plugin pack from selected runtime(s) |
+| `plugin status [--editor claude|codex|all]` | Show installed plugins with runtime-specific details |
 | `stats` | Show skill usage statistics (`--reset` to clear, `--json` for raw output) |
 | `benchmark --my-config` | Compare your installed config vs toolkit defaults vs ecosystem |
 | `benchmark-ecosystem` | Generate a benchmark snapshot for official Claude Code and external ecosystem repos |
@@ -852,6 +878,9 @@ Usage: ai-toolkit <command> [options]
 | `cline-dir-rules` | Generate `.cline/rules/*.md` for Cline |
 | `roo-dir-rules` | Generate `.roo/rules/*.md` for Roo Code |
 | `antigravity-rules` | Generate `.agent/rules/` and `.agent/workflows/` for Google Antigravity |
+| `codex-md` | Generate `AGENTS.md` with marker injection for Codex CLI |
+| `codex-rules` | Generate `.agents/rules/*.md` for Codex CLI |
+| `codex-hooks` | Generate `.codex/hooks.json` for Codex CLI (9 hooks in 4 events) |
 | `agents-md` | Regenerate `AGENTS.md` from agent definitions |
 | `llms-txt` | Generate `llms.txt` and `llms-full.txt` |
 | `generate-all` | Generate all platform configs at once |
@@ -865,7 +894,7 @@ ai-toolkit install --skip hooks          # skip listed components
 ai-toolkit install --profile minimal     # profile preset: minimal | standard | strict
 ai-toolkit install --persona backend-lead # persona preset: backend-lead | frontend-lead | devops-eng | junior-dev
 ai-toolkit install --local               # Claude Code only (CLAUDE.md, settings, constitution, language rules)
-ai-toolkit install --local --editors all # Claude Code + all editors (Cursor, Windsurf, Cline, Roo, Aider, Augment, Copilot, Antigravity)
+ai-toolkit install --local --editors all # Claude Code + all editors (Cursor, Windsurf, Cline, Roo, Aider, Augment, Copilot, Antigravity, Codex)
 ai-toolkit install --local --editors cursor,aider  # Claude Code + specific editors
 ai-toolkit update --local                # re-apply; auto-detects editors from existing project files
 ai-toolkit install --list                # dry-run: show what would be applied

package/app/ARCHITECTURE.md

@@ -307,7 +307,7 @@ Lead Session (You)
 ### Language Rules (70 files, 13 languages)
 `app/rules/` contains per-language coding rules. Supported languages: TypeScript, Python, Go, Rust, Java, Kotlin, Swift, Dart, C#, PHP, C++, Ruby, and common (shared). Auto-detected from project files via `--auto-detect` or selected with `--modules rules-<lang>`.
 
-Language rules are propagated to **all configured editors** — not just Claude. `dir_rules_shared.build_language_rules()` reads `app/rules/<lang>/*.md`, strips frontmatter, and returns combined content per language. Each directory-based generator (Cursor, Windsurf, Cline, Roo, Augment, Antigravity) emits `ai-toolkit-lang-<lang>` files in its native format. Registered custom rules (`~/.softspark/ai-toolkit/rules/`) are similarly propagated as `ai-toolkit-custom-<name>` files via `build_registered_rules()`.
+Language rules are propagated to **all configured editors** — not just Claude. `dir_rules_shared.build_language_rules()` reads `app/rules/<lang>/*.md`, strips frontmatter, and returns combined content per language. Each directory-based generator (Cursor, Windsurf, Cline, Roo, Augment, Antigravity, Codex) emits `ai-toolkit-lang-<lang>` files in its native format. Registered custom rules (`~/.softspark/ai-toolkit/rules/`) are similarly propagated as `ai-toolkit-custom-<name>` files via `build_registered_rules()`.
 
 ### Extension API (`inject-hook`)
 The `inject_section_cli.py` script provides a stable marker-based injection API. Any tool can add sections to `CLAUDE.md`, `constitution.md`, or `ARCHITECTURE.md` without overwriting user content, using `<!-- TOOLKIT:START:<id> -->` / `<!-- TOOLKIT:END:<id> -->` markers.

package/app/plugins/README.md

@@ -5,10 +5,15 @@ Experimental opt-in plugin packs that group existing ai-toolkit assets by domain
 These packs are **not** installed automatically by `ai-toolkit install` and are **not** part of the default install.
 They serve three purposes:
 
-1. formalize a plugin-pack contract compatible with Claude Code plugin manifests,
+1. formalize a plugin-pack contract for runtime-aware plugin installation,
 2. provide curated bundles by domain,
 3. give `plugin-creator` a concrete scaffold to follow.
 
+Plugin packs can target:
+- Claude global runtime via `ai-toolkit plugin install --editor claude <name>`
+- Codex global plugin layer via `ai-toolkit plugin install --editor codex <name>`
+- both runtimes via `ai-toolkit plugin install --editor all <name>`
+
 Current packs:
 - `security-pack`
 - `research-pack`
@@ -16,4 +21,3 @@ Current packs:
 - `enterprise-pack`
 
 See `kb/reference/plugin-pack-conventions.md` for pack rules, validation, and adoption guidance.
-

package/app/skills/plugin-creator/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: plugin-creator
-description: "Creates experimental opt-in Claude Code plugin packs with manifests, conventions, and optional module scaffolding"
+description: "Creates experimental opt-in plugin packs with manifests, conventions, and optional module scaffolding for Claude and Codex runtimes"
 effort: high
 disable-model-invocation: true
 argument-hint: "[plugin pack name or domain]"
@@ -11,7 +11,7 @@ allowed-tools: Read, Write, Edit, Bash, Grep, Glob
 
 $ARGUMENTS
 
-Create a new experimental opt-in Claude Code plugin pack following ai-toolkit conventions.
+Create a new experimental opt-in plugin pack following ai-toolkit conventions.
 
 ## Workflow
 
@@ -64,7 +64,7 @@ app/plugins/<plugin-name>/
 - Prefer referencing existing toolkit assets before duplicating them
 - Pack manifests must be valid JSON with `name`, `description`, `version`, `domain`, `type`, `status`, and `includes`
 - Optional hooks must be executable and documented in the pack README
-- If the pack introduces policy or hook behavior, document install/opt-in semantics clearly, including that the pack is not part of the default install
+- If the pack introduces policy or hook behavior, document install/opt-in semantics clearly, including supported runtimes (`claude`, `codex`, or `all`) and that the pack is not part of the default install
 - Experimental packs should remain opt-in and must not silently alter default global install behavior
 
 ## Validation Checklist
@@ -75,4 +75,3 @@ app/plugins/<plugin-name>/
 - [ ] Optional hooks are executable and use `#!/bin/bash`
 - [ ] `scripts/validate.py` passes
 - [ ] Public docs mention the pack only after the manifest and README exist
-

package/bin/ai-toolkit.js

@@ -29,6 +29,7 @@ const GENERATORS = {
   'aider-conf':           { script: 'generate_aider_conf.py',    dest: '.aider.conf.yml' },
   'augment-rules':        { script: 'generate_augment.py',       dest: path.join('.augment', 'rules', 'ai-toolkit.md'), mkdir: '.augment/rules' },
   'agents-md':            { script: 'generate_agents_md.py',     dest: 'AGENTS.md' },
+  'codex-md':             { script: 'generate_codex.py',         dest: 'AGENTS.md' },
 };
 
 // ---------------------------------------------------------------------------
@@ -74,7 +75,7 @@ const COMMANDS = {
   evaluate: 'Run skill evaluation suite',
   stats: 'Show skill usage statistics (--reset to clear, --json for raw output)',
   create: 'Scaffold new skill from template (e.g. create skill my-lint --template=linter)',
-  mcp: 'Manage MCP server templates (list, show, add, remove)',
+  mcp: 'Manage MCP templates and install native editor MCP configs',
   config: 'Manage config inheritance (validate, diff, init, create-base, check)',
   projects: 'List and manage registered projects (--prune, remove <path>)',
   plugin: 'Manage plugin packs (install, remove, update, clean, list, status)',
@@ -94,10 +95,13 @@ const COMMANDS = {
   'augment-rules': 'Generate .augment/rules/ai-toolkit.md for Augment (legacy)',
   'augment-dir-rules': 'Generate .augment/rules/ai-toolkit-*.md for Augment (recommended)',
   'antigravity-rules': 'Generate .agent/rules/ and .agent/workflows/ for Google Antigravity',
+  'codex-md': 'Generate AGENTS.md for OpenAI Codex CLI',
+  'codex-rules': 'Generate .agents/rules/ for OpenAI Codex CLI',
+  'codex-hooks': 'Generate .codex/hooks.json for OpenAI Codex CLI',
   'agents-md': 'Regenerate AGENTS.md from agent definitions',
   'compile-slm': 'Compile toolkit into a minimal SLM system prompt (--budget, --model-size, --dry-run)',
   'llms-txt': 'Generate llms.txt and llms-full.txt',
-  'generate-all': 'Generate all platform configs at once (agents, cursor, windsurf, copilot, gemini, cline, roo, aider, augment, antigravity, llms)',
+  'generate-all': 'Generate all platform configs at once (agents, cursor, windsurf, copilot, gemini, cline, roo, aider, augment, antigravity, codex, llms)',
   help: 'Show this help message',
 };
 
@@ -230,20 +234,25 @@ function showHelp() {
   console.log('  <rule-file>     Path to .md rule file to register globally');
   console.log('  [rule-name]     Override rule name (default: filename without .md)');
   console.log('\nOptions for plugin:');
-  console.log('  install <name>  Install a plugin pack (copies hooks, links skills/agents)');
-  console.log('  install --all   Install all available plugin packs');
+  console.log('  install <name>  Install a plugin pack (--editor claude|codex|all)');
+  console.log('  install --all   Install all available plugin packs for selected editor(s)');
   console.log('  update <name>   Update a plugin pack (remove + reinstall)');
-  console.log('  update --all    Update all installed plugin packs');
+  console.log('  update --all    Update all installed plugin packs for selected editor(s)');
   console.log('  clean <name>    Prune old data (e.g. memory-pack --days 30)');
   console.log('  remove <name>   Remove a plugin pack');
   console.log('  remove --all    Remove all installed plugins');
   console.log('  list            Show available plugin packs with install status');
   console.log('  status          Show currently installed plugins with data stats');
+  console.log('  --editor <list> Runtime target: claude, codex, or all (default: claude)');
   console.log('\nOptions for mcp:');
   console.log('  list                          List available MCP templates');
+  console.log('  editors                       List editors with native MCP config adapters');
   console.log('  show <name>                   Show template details');
   console.log('  add <name> [names..] [--target <path>]  Add servers to .mcp.json');
-  console.log('  remove <name>                 Remove a server from .mcp.json');
+  console.log('  install --editor <name[,..]> [--scope project|global] [--target <path>] [names..]');
+  console.log('                                Install templates into native editor MCP config');
+  console.log('  remove <name> [--editor <name[,..]>] [--scope project|global] [--target <path>]');
+  console.log('                                Remove from .mcp.json or native editor configs');
   console.log('\nOptions for doctor:');
   console.log('  --fix           Auto-repair detected issues');
   console.log('\nOptions for eject:');
@@ -372,7 +381,7 @@ function handleRemoveHook(args) {
  */
 function handleMcp(args) {
   if (args.length === 0) {
-    console.error('Usage: ai-toolkit mcp <list|show|add|remove> [args..]');
+    console.error('Usage: ai-toolkit mcp <list|editors|show|add|install|remove> [args..]');
     process.exit(1);
   }
   run(scriptPath('mcp_manager.py'), args);
@@ -404,6 +413,8 @@ function handleGenerateAll(_args) {
   run(scriptPath('generate_cline_rules.py'), [CWD]);
   run(scriptPath('generate_roo_rules.py'), [CWD]);
   run(scriptPath('generate_augment_rules.py'), [CWD]);
+  run(scriptPath('generate_codex_rules.py'), [CWD]);
+  run(scriptPath('generate_codex_hooks.py'), [CWD]);
   // Single-file generators
   const conventionsOut = runGenerator('generate_conventions.py');
   fs.writeFileSync(path.join(CWD, 'CONVENTIONS.md'), conventionsOut);
@@ -501,6 +512,8 @@ const SPECIAL_HANDLERS = {
   'roo-dir-rules': (_args) => run(scriptPath('generate_roo_rules.py'), [CWD]),
   'conventions-md': (_args) => { const out = runGenerator('generate_conventions.py'); fs.writeFileSync(path.join(CWD, 'CONVENTIONS.md'), out); console.log('Generated: CONVENTIONS.md'); },
   'augment-dir-rules': (_args) => run(scriptPath('generate_augment_rules.py'), [CWD]),
+  'codex-rules': (_args) => run(scriptPath('generate_codex_rules.py'), [CWD]),
+  'codex-hooks': (_args) => run(scriptPath('generate_codex_hooks.py'), [CWD]),
   'generate-all': handleGenerateAll,
 };
 

package/kb/procedures/maintenance-sop.md

@@ -3,9 +3,9 @@ title: "SOP: Claude Toolkit Maintenance"
 category: procedures
 service: ai-toolkit
 tags: [sop, maintenance, agents, skills, install]
-version: "1.4.2"
+version: "1.4.4"
 created: "2026-03-23"
-last_updated: "2026-04-10"
+last_updated: "2026-04-13"
 description: "Standard operating procedures for installing, maintaining, and evolving the ai-toolkit."
 ---
 
@@ -34,7 +34,7 @@ ai-toolkit install --local --editors all                  # all supported editor
 ai-toolkit install --local --editors cursor,aider         # specific editors only
 ```
 
-Supported editors: `cursor`, `windsurf`, `cline`, `roo`, `aider`, `augment`, `copilot`, `antigravity`.
+Supported editors: `cursor`, `windsurf`, `cline`, `roo`, `aider`, `augment`, `copilot`, `antigravity`, `codex`.
 
 To restrict which language rules are injected, use `--lang`:
 
@@ -194,22 +194,22 @@ Use `PreToolUse` for blocking validations, `PostToolUse` for non-blocking feedba
 ## Managing Plugins
 
 ```bash
-ai-toolkit plugin list               # show available packs
-ai-toolkit plugin install <name>     # install a single pack
-ai-toolkit plugin install --all      # install all 11 packs
-ai-toolkit plugin update <name>      # update a pack (preserves data)
-ai-toolkit plugin update --all       # update all installed packs
-ai-toolkit plugin clean <name>       # prune data older than 90 days
+ai-toolkit plugin list                             # show available packs
+ai-toolkit plugin install --editor claude <name>  # install for Claude global target
+ai-toolkit plugin install --editor codex <name>   # install for Codex global target
+ai-toolkit plugin install --editor all --all      # install all 11 packs for both runtimes
+ai-toolkit plugin update --editor all --all       # re-apply all installed packs after toolkit updates
+ai-toolkit plugin clean <name>                    # prune data older than 90 days
 ai-toolkit plugin clean <name> --days 30  # custom retention
-ai-toolkit plugin remove <name>      # remove a pack
-ai-toolkit plugin status             # show installed packs with data stats
+ai-toolkit plugin remove --editor codex <name>    # remove from one runtime only
+ai-toolkit plugin status --editor all             # show installed packs with runtime details
 ```
 
-Install copies hooks/scripts, verifies agents+skills are linked, merges hooks into `settings.json`, and runs init scripts. Update removes and reinstalls from current source (data preserved). Clean prunes old plugin data. Remove reverses install but leaves data intact. Core agents/skills are never removed.
+Install copies hooks/scripts, verifies agents+skills are linked, merges hooks into the selected runtime config, and runs init scripts. For Codex, the selected runtime is the global `HOME` layer (`~/AGENTS.md`, `~/.agents/`, `~/.codex/hooks.json`). Update removes and reinstalls from current source while preserving plugin data. Clean prunes old plugin data. Remove reverses install for the selected runtime but leaves plugin data intact. Core agents/skills are never removed.
 
 Memory-pack auto-prunes observations older than 90 days on every session end (configurable via `MEMORY_RETENTION_DAYS`).
 
-State tracked in `~/.softspark/ai-toolkit/plugins.json`.
+State is tracked per runtime in `~/.softspark/ai-toolkit/plugins.json`. After every `ai-toolkit update`, also run `ai-toolkit plugin update --editor all --all` if plugin packs are installed.
 
 ## Adding a KB Document
 
@@ -229,6 +229,51 @@ Follow the `documentation-standards` knowledge skill (`app/skills/documentation-
 2. `chmod +x` the script
 3. Reference: `` python3 ${CLAUDE_SKILL_DIR}/scripts/script.py . ``
 
+## Cross-Editor Verification (Mandatory)
+
+**Every addition — skill, hook, MCP template, agent, rule — MUST be verified against all supported editors before merge.**
+
+This toolkit targets 10 platforms. Each has its own config format, file path conventions, and runtime capabilities. A feature that works in Claude Code may silently break in Cursor, Codex, or Copilot if the editor's official spec diverges.
+
+### Verification checklist
+
+When adding or modifying any toolkit component:
+
+1. **Check official docs** — before implementing, fetch the editor's current documentation (web search or Context7) to confirm the config format, file path, and feature support haven't changed
+2. **Validate output format** — ensure the generated file matches what the editor expects (JSON schema, TOML structure, MDC frontmatter, directory naming)
+3. **Test scope rules** — verify project-local vs global behavior matches the editor's own scope model
+4. **Confirm feature parity** — if the feature relies on runtime primitives (hooks, MCP, agent delegation), check whether the target editor supports them; document gaps in `kb/reference/` if not
+
+### Editor documentation sources
+
+| Editor | Where to verify |
+|--------|----------------|
+| Claude Code | `docs.anthropic.com/claude-code` |
+| Cursor | `docs.cursor.com` |
+| Windsurf | `docs.codeium.com/windsurf` |
+| GitHub Copilot | `docs.github.com/copilot` |
+| Gemini CLI | `github.com/google-gemini/gemini-cli` |
+| Cline | `github.com/cline/cline` |
+| Roo Code | `github.com/RooVetGit/Roo-Code` |
+| Aider | `aider.chat` |
+| Augment | `docs.augmentcode.com` |
+| Codex CLI | `github.com/openai/codex` |
+| Google Antigravity | `developers.google.com/project-idx` |
+
+### When to do this
+
+- Adding a new skill → verify it renders correctly for Codex `.agents/skills/` and all directory-based editors
+- Adding a new hook → verify event name is valid in Claude and check `.codex/hooks.json` compatibility
+- Adding a new MCP template → verify it installs correctly for all 8 native adapters (`mcp_editors.py`)
+- Modifying generator output → check that every editor-specific generator still produces valid output
+- Adding a new editor → verify ALL existing features render correctly for the new target
+
+### Anti-pattern
+
+Do NOT assume an editor's format based on memory or past behavior. Editors ship breaking changes to their config surfaces. Always verify against current official docs before implementation.
+
+---
+
 ## Quality Checks
 
 ```bash
@@ -254,14 +299,17 @@ ai-toolkit benchmark-ecosystem --offline   # benchmark snapshot
 Changes propagate instantly to all machines via symlinks. After any change:
 
 ```bash
-npm run generate:all          # FIRST: regenerate AGENTS.md, llms.txt, all platform configs
+npm run generate:all          # FIRST: regenerate AGENTS.md, Codex rules, llms.txt, and platform configs
 scripts/validate.py           # then validate — must pass before commit
 npm test                      # then test — must pass before commit
 ```
 
 Run `generate:all` before validate and test so that generated artifacts are current when
-the metadata contract tests run. Committing without regenerating first causes artifact
-drift and fails CI.
+the metadata contract tests run. Directory-based rule generators now use ownership-aware
+cleanup: repo regeneration manages only standard generated files, while `install/update`
+manages standard, language, and custom overlays together. That keeps regeneration safe
+without leaving stale standard artifacts behind. Committing without regenerating first
+causes artifact drift and fails CI.
 
 ## Release Checklist
 

package/kb/procedures/release-preparation-sop.md

@@ -5,7 +5,7 @@ service: ai-toolkit
 tags: [sop, release, version, publish, changelog, semver]
 version: "1.5.0"
 created: "2026-04-10"
-last_updated: "2026-04-10"
+last_updated: "2026-04-13"
 description: "Step-by-step checklist for preparing a new ai-toolkit release — version sync, changelog, artifact regeneration, validation, and tagging. Run BEFORE every git tag."
 ---
 
@@ -38,6 +38,7 @@ python3 scripts/sync_version.py X.Y.Z          # if script exists, else manual
 # 3. Write CHANGELOG.md entry
 # 4. Regenerate artifacts
 python3 scripts/generate_agents_md.py > AGENTS.md
+python3 scripts/generate_codex_rules.py .
 python3 scripts/generate_llms_txt.py > llms.txt
 python3 scripts/generate_llms_txt.py --full > llms-full.txt
 
@@ -161,6 +162,7 @@ Add entry at the top of `CHANGELOG.md` (after the header, before previous releas
 
 ```bash
 python3 scripts/generate_agents_md.py > AGENTS.md
+python3 scripts/generate_codex_rules.py .
 python3 scripts/generate_llms_txt.py > llms.txt
 python3 scripts/generate_llms_txt.py --full > llms-full.txt
 ```
@@ -268,7 +270,7 @@ git push origin --delete vX.Y.Z
 | 5 | `package-lock.json` | `npm install --package-lock-only` | Matches target |
 | 6 | Count sync | Check `package.json` description, README | `validate.py` passes |
 | 7 | CHANGELOG.md | Add release entry | Entry exists for vX.Y.Z |
-| 8 | Regenerate artifacts | `generate_agents_md.py`, `generate_llms_txt.py` | No unexpected diff |
+| 8 | Regenerate artifacts | `generate_agents_md.py`, `generate_codex_rules.py`, `generate_llms_txt.py` | No unexpected diff |
 | 9 | Validate | `validate.py --strict` | 0 errors, 0 warnings |
 | 10 | Security audit | `audit_skills.py --ci` | 0 HIGH |
 | 11 | Tests | `npm test` | All pass |

package/kb/procedures/release-verification-sop.md

@@ -5,7 +5,7 @@ service: ai-toolkit
 tags: [sop, verification, release, smoke-test, install, update, qa]
 version: "1.1.0"
 created: "2026-04-08"
-last_updated: "2026-04-08"
+last_updated: "2026-04-13"
 description: "End-to-end smoke test after installing or updating @softspark/ai-toolkit — verifies CLI, install, doctor, validation, tests, and eject from user perspective."
 ---
 
@@ -31,21 +31,22 @@ Verifies all critical paths from the user's perspective.
 
 ## Quick Checklist (TL;DR)
 
-9 commands — if all pass, the release is ready:
+10 commands — if all pass, the release is ready:
 
 ```bash
 # Pre-commit (Phase 0)
-python3 scripts/generate_agents_md.py > AGENTS.md   # 1. Regenerate artifacts
-python3 scripts/generate_llms_txt.py > llms.txt      # 2. Regenerate llms.txt
-python3 scripts/validate.py --strict                 # 3. Validation passed?
-npm test                                             # 4. All tests passed?
+python3 scripts/generate_agents_md.py > AGENTS.md           # 1. Regenerate AGENTS.md
+python3 scripts/generate_codex_rules.py .                   # 2. Refresh standard Codex rules
+python3 scripts/generate_llms_txt.py > llms.txt             # 3. Regenerate llms.txt
+python3 scripts/validate.py --strict                        # 4. Validation passed?
+npm test                                                    # 5. All tests passed?
 
 # Post-install verification (Phases 1-7)
-ai-toolkit --version                                 # 5. Version OK?
-ai-toolkit status                                    # 6. Status OK?
-ai-toolkit doctor                                    # 7. Health check passed?
-ai-toolkit install --dry-run                         # 8. Global install OK?
-python3 scripts/audit_skills.py --ci                 # 9. Security audit clean?
+ai-toolkit --version                                        # 6. Version OK?
+ai-toolkit status                                           # 7. Status OK?
+ai-toolkit doctor                                           # 8. Health check passed?
+ai-toolkit install --dry-run                                # 9. Global install OK?
+python3 scripts/audit_skills.py --ci                        # 10. Security audit clean?
 ```
 
 ---
@@ -58,6 +59,7 @@ counts but does NOT auto-regenerate — you must do it locally.
 ```bash
 # 1. Regenerate generated artifacts
 python3 scripts/generate_agents_md.py > AGENTS.md
+python3 scripts/generate_codex_rules.py .
 python3 scripts/generate_llms_txt.py > llms.txt
 python3 scripts/generate_llms_txt.py --full > llms-full.txt
 
@@ -71,7 +73,7 @@ python3 scripts/audit_skills.py --ci
 npm test
 
 # 5. Stage and commit
-git add AGENTS.md llms.txt llms-full.txt
+git add AGENTS.md .agents/rules/ai-toolkit-*.md llms.txt llms-full.txt
 git add -p  # stage your other changes
 git commit -m "feat: your change description"
 ```
@@ -82,7 +84,7 @@ by the developer as part of their PR.
 
 **One-liner (copy-paste):**
 ```bash
-python3 scripts/generate_agents_md.py > AGENTS.md && python3 scripts/generate_llms_txt.py > llms.txt && python3 scripts/generate_llms_txt.py --full > llms-full.txt && python3 scripts/validate.py --strict && python3 scripts/audit_skills.py --ci && npm test
+python3 scripts/generate_agents_md.py > AGENTS.md && python3 scripts/generate_codex_rules.py . && python3 scripts/generate_llms_txt.py > llms.txt && python3 scripts/generate_llms_txt.py --full > llms-full.txt && python3 scripts/validate.py --strict && python3 scripts/audit_skills.py --ci && npm test
 ```
 
 ---