@softspark/ai-toolkit 2.0.2 → 2.1.1

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',
 };
 
@@ -199,11 +203,12 @@ function showHelp() {
   console.log('\nOptions for install / update:');
   console.log('  --only <list>   Apply only listed components (e.g. agents,hooks,cursor,windsurf,gemini)');
   console.log('  --skip <list>   Skip listed components');
-  console.log('  --local         Also set up project-local configs (CLAUDE.md, settings, constitution, copilot, cline, roo, aider, git hooks)');
+  console.log('  --local         Also set up project-local configs (CLAUDE.md, settings, constitution, language rules, git hooks)');
   console.log('  --profile <p>   Install profile: minimal (agents+skills), standard (default), strict (all+git hooks)');
+  console.log('  --persona <p>   Persona preset: backend-lead, frontend-lead, devops-eng, junior-dev');
   console.log('  --modules <list>  Install specific modules (e.g. core,agents,rules-typescript)');
   console.log('  --lang <list>   Explicitly select language rules (e.g. typescript, go,python)');
-  console.log('  --editors <list> Install editor configs: cursor,windsurf,cline,roo,aider,augment,copilot,antigravity (or "all")');
+  console.log('  --editors <list> Install editor configs: cursor,windsurf,cline,roo,aider,augment,copilot,antigravity,codex (or "all")');
   console.log('                  Default with --local: auto-detect from existing project files');
   console.log('  --auto-detect   Detect project languages and install matching rule modules');
   console.log('  --list, --dry-run  Dry-run: show what would be applied');
@@ -230,20 +235,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 +382,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);
@@ -394,7 +404,9 @@ function handleConfig(args) {
  * @param {string[]} _args - Unused, kept for signature consistency
  */
 function handleGenerateAll(_args) {
-  for (const gen of Object.values(GENERATORS)) {
+  for (const [name, gen] of Object.entries(GENERATORS)) {
+    // Skip agents-md — codex-md generates a superset to the same AGENTS.md
+    if (name === 'agents-md') continue;
     writeGeneratorOutput(gen);
   }
   // Directory-based generators (multi-file output)
@@ -404,11 +416,21 @@ 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);
   console.log('Generated: CONVENTIONS.md');
   generateLlmsTxt();
+  // Re-inject registered custom rules into .claude/CLAUDE.md (idempotent markers)
+  const rulesDir = path.join(process.env.HOME, '.softspark', 'ai-toolkit', 'rules');
+  if (fs.existsSync(rulesDir)) {
+    const ruleFiles = fs.readdirSync(rulesDir).filter(f => f.endsWith('.md')).sort();
+    for (const rf of ruleFiles) {
+      run(scriptPath('inject_rule_cli.py'), [path.join(rulesDir, rf), CWD]);
+    }
+  }
 }
 
 /**
@@ -501,6 +523,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
 ```
 
 ---

package/kb/reference/architecture-overview.md

@@ -3,10 +3,10 @@ title: "AI Toolkit - Architecture Overview"
 category: reference
 service: ai-toolkit
 tags: [architecture, overview, design, structure]
-version: "1.4.2"
+version: "1.4.4"
 created: "2026-03-23"
-last_updated: "2026-04-09"
-description: "Architecture of ai-toolkit: directory layout, global install model, skill tiers, and integration with projects."
+last_updated: "2026-04-13"
+description: "Architecture of ai-toolkit: directory layout, global install model, editor-aware MCP install, Codex translation layer, skill tiers, and integration with projects."
 ---
 
 # AI Toolkit Architecture
@@ -105,11 +105,13 @@ Machine (global)                              Project (local)
 **`ai-toolkit update`** — re-apply after `npm install -g @softspark/ai-toolkit@latest` or after `add-rule` / `remove-rule`. Same as `install` but semantically correct for update flows.
 
 **`ai-toolkit install --local`** — run per project. Always installs Claude Code configs (CLAUDE.md, settings.local.json, constitution.md, language rules). Editor configs are opt-in via `--editors`:
-- `--editors all` — install all 8 editors (Cursor, Windsurf, Cline, Roo, Aider, Augment, Copilot, Antigravity)
+- `--editors all` — install all 9 editors (Cursor, Windsurf, Cline, Roo, Aider, Augment, Copilot, Antigravity, Codex)
 - `--editors cursor,aider` — install only selected editors
 - (no flag) — auto-detect from existing project files; `update --local` picks up whatever editors already have configs
 
-Each editor gets directory-based format (`.cursor/rules/*.mdc`, `.windsurf/rules/*.md`, `.clinerules/*.md`, `.roo/rules/*.md`, `.augment/rules/ai-toolkit-*.md`, `.agent/rules/*.md`, `CONVENTIONS.md`). Hooks are global-only — not merged into project settings.
+Each editor gets directory-based format (`.cursor/rules/*.mdc`, `.windsurf/rules/*.md`, `.clinerules/*.md`, `.roo/rules/*.md`, `.augment/rules/ai-toolkit-*.md`, `.agent/rules/*.md`, `CONVENTIONS.md`). Codex local install additionally generates `AGENTS.md`, `.agents/rules/*.md`, `.agents/skills/*`, and `.codex/hooks.json`. Hooks are global-only — not merged into project settings except for editor-native local hook files such as Codex `.codex/hooks.json`. Experimental plugin packs can also layer a global Codex target in `HOME` (`~/AGENTS.md`, `~/.agents/`, `~/.codex/hooks.json`) when installed with `ai-toolkit plugin install --editor codex`.
+
+If a project already has `.mcp.json`, local install mirrors its `mcpServers` entries into `.claude/settings.local.json` plus any selected editors with project-scoped native MCP files (`.cursor/mcp.json`, `.github/mcp.json`).
 
 ## CLI Commands
 
@@ -122,6 +124,8 @@ Each editor gets directory-based format (`.cursor/rules/*.mdc`, `.windsurf/rules
 | `uninstall` | `~/.claude/` | Strips toolkit components (preserves user content) |
 | `add-rule <file>` | `~/.softspark/ai-toolkit/rules/` | Register rule — auto-applied on every `update` |
 | `remove-rule <name>` | `~/.softspark/ai-toolkit/rules/` + `~/.claude/CLAUDE.md` | Unregister rule and remove its block |
+| `mcp add <name...>` | `./.mcp.json` | Merge canonical MCP template(s) into project config |
+| `mcp install --editor <name...>` | native editor config | Render MCP template(s) into editor-native config files |
 | `validate` | toolkit | Integrity check |
 | `doctor` | toolkit | Install health, hooks, benchmark freshness, and artifact drift diagnostics |
 | `benchmark-ecosystem` | toolkit | Benchmark snapshot for official Claude Code and external ecosystem repos |
@@ -140,6 +144,9 @@ Each editor gets directory-based format (`.cursor/rules/*.mdc`, `.windsurf/rules
 | `conventions-md` | `./` | Generates `CONVENTIONS.md` (Aider auto-loaded) |
 | `augment-dir-rules` | `./` | Generates `.augment/rules/ai-toolkit-*.md` |
 | `antigravity-rules` | `./` | Generates `.agent/rules/` + `.agent/workflows/` |
+| `codex-md` | `./` | Generates Codex-facing `AGENTS.md` |
+| `codex-rules` | `./` | Generates `.agents/rules/*.md` |
+| `codex-hooks` | `./` | Generates `.codex/hooks.json` |
 | `agents-md` | toolkit | Regenerates `AGENTS.md` |
 | `llms-txt` | `./` | Generates `llms.txt` |
 | `generate-all` | `./` | Generates all platform configs at once |
@@ -191,6 +198,38 @@ Skills that spawn real parallel agents use:
 
 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` must be set for Agent Teams (tmux-based) support.
 
+### Codex Translation Layer
+
+Codex does not expose Claude's `Agent`, `Team*`, and `Task*` primitives with the
+same runtime semantics. To keep the skill catalog aligned, local Codex install
+uses a translation layer:
+
+- native Codex-compatible skills are linked directly
+- Claude-only orchestration skills are emitted as generated wrappers
+- wrapper guidance maps delegation to `spawn_agent`, `send_input`, `wait_agent`, `close_agent`, and `update_plan`
+
+Codex therefore receives the full skill catalog, but not the full Claude hook
+surface or tmux-backed Agent Teams lifecycle. Plugin packs reuse the same
+translation and hook-compatibility model when targeting the global Codex layer.
+
+See `kb/reference/codex-cli-compatibility.md` for the detailed mapping.
+
+## MCP Rendering Layer
+
+`.mcp.json` is the canonical project-level template format. ai-toolkit can render that configuration into editor-native MCP files through `scripts/mcp_editors.py`.
+
+Current native adapters:
+- Claude Code: `.claude/settings.local.json` and `~/.claude/settings.json`
+- Cursor: `.cursor/mcp.json` and `~/.cursor/mcp.json`
+- GitHub Copilot: `.github/mcp.json` and `~/.copilot/mcp-config.json`
+- Gemini CLI: `.gemini/settings.json` and `~/.gemini/settings.json`
+- Windsurf: `~/.codeium/windsurf/mcp_config.json`
+- Cline: `~/.cline/data/settings/cline_mcp_settings.json`
+- Augment: `~/.augment/settings.json`
+- Codex CLI: `~/.codex/config.toml`
+
+See `kb/reference/mcp-editor-compatibility.md` for the support matrix and scope rules.
+
 ## Quality Guardrails
 
 ### Anti-Rationalization Tables

package/kb/reference/claude-ecosystem-expansion-foundations.md

@@ -5,8 +5,8 @@ service: ai-toolkit
 tags: [benchmark, claude-code, ecosystem, hooks, plugins, architecture]
 version: "1.0.0"
 created: "2026-03-27"
-last_updated: "2026-04-01"
-description: "Reference summary of the ecosystem signals and implementation foundations adopted in ai-toolkit."
+last_updated: "2026-04-13"
+description: "Reference summary of the ecosystem signals and implementation foundations adopted in ai-toolkit, including runtime-aware plugin packaging."
 ---
 
 # Claude Ecosystem Expansion Foundations
@@ -19,13 +19,13 @@ This document captures the architectural foundations adopted in `ai-toolkit` aft
 2. official Claude Code patterns,
 3. selected external benchmark repositories.
 
-The outcome is a toolkit that is now positioned as a more modular, Claude-native, benchmark-backed system with stronger lifecycle automation and extension tooling.
+The outcome is a toolkit that is now positioned as a more modular, Claude-first, benchmark-backed system with stronger lifecycle automation and extension tooling.
 
 ## Implemented Foundations
 
 ### 1. Plugin-oriented structure
 
-`ai-toolkit` now treats plugin packaging as a first-class capability.
+`ai-toolkit` now treats plugin packaging as a first-class capability, with runtime-aware install surfaces for Claude and optional global Codex layering.
 
 Implemented artifacts:
 - `app/.claude-plugin/plugin.json`