projecta-rrr 1.23.3 → 1.23.5

package/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to RRR will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [1.23.5] - 2026-04-30
+
+### Fixed
+- **Codex command discovery** — RRR now installs Codex skills in the discoverable `~/.codex/skills/rrr-*/SKILL.md` layout, removes legacy flat skill files, and quotes generated YAML metadata so every `$rrr-*` command loads cleanly.
+- **Codex runtime provisioning** — installer now refreshes `~/.codex/rrr` with the support scripts used by RRR commands and skips copied `node_modules` directories so updates do not break on symlinked dependencies.
+- **Codex agent registration** — RRR agent TOML files are registered in `~/.codex/config.toml` under managed `[agents.rrr-*]` blocks while preserving user-managed config.
+
+### Changed
+- **Seamless repo updates for Codex developers** — running `$rrr-update` or `npx projecta-rrr@latest --global` from an RRR repo now refreshes repo-local `AGENTS.md` automatically when Codex is installed.
+- **Codex command adapter** — transformed skills now document `$rrr-*` invocation, `{{RRR_ARGS}}` handling, default-mode question fallback, slash-command conversion, and RRR subagent mapping for Codex.
+
+## [1.23.4] - 2026-04-20
+
+### Fixed
+- **Codex hosted MCP launcher** — installer now writes a Codex-specific bearer env file and registers `bearer_token_env_var` in `~/.codex/config.toml` so the hosted RRR setup works with the new `scripts/codex-rrr.sh` launcher.
+- **Codex launch helper** — added `npm run codex:rrr` and docs for starting Codex with the hosted bearer loaded from `~/.config/projecta-rrr/rrr-hosted.env`.
+
 ## [1.23.3] - 2026-04-20
 
 ### Fixed

package/bin/hosted-setup.js

@@ -31,6 +31,8 @@ const HOSTED_URL = 'https://rrr-search-hosted.fly.dev/mcp';
 const GH_APP_INSTALL_URL = 'https://github.com/apps/rrr-search/installations/new';
 const MCP_NAME = 'rrr-search-hosted';
 const CODEX_CONFIG_PATH = path.join(os.homedir(), '.codex', 'config.toml');
+const CODEX_BEARER_ENV_VAR = 'RRR_HOSTED_BEARER';
+const CODEX_ENV_FILE = path.join(os.homedir(), '.config', 'projecta-rrr', 'rrr-hosted.env');
 
 // ──────────────────────────────── UI ──────────────────────────────────────
 
@@ -136,7 +138,7 @@ function registerCodexMcp (bearer) {
   content = content.replace(sectionRegex, '').trimEnd();
 
   // Append new registration
-  const section = `\n\n[mcp_servers.${MCP_NAME}]\nurl = "${HOSTED_URL}"\nheaders = { Authorization = "Bearer ${bearer}" }\n`;
+  const section = `\n\n[mcp_servers.${MCP_NAME}]\nurl = "${HOSTED_URL}"\nbearer_token_env_var = "${CODEX_BEARER_ENV_VAR}"\n`;
   content = content + section;
 
   // Ensure ~/.codex directory exists
@@ -144,6 +146,15 @@ function registerCodexMcp (bearer) {
   fs.writeFileSync(CODEX_CONFIG_PATH, content, 'utf8');
 }
 
+function writeCodexBearerEnv (bearer) {
+  fs.mkdirSync(path.dirname(CODEX_ENV_FILE), { recursive: true });
+  fs.writeFileSync(
+    CODEX_ENV_FILE,
+    `export ${CODEX_BEARER_ENV_VAR}=${JSON.stringify(bearer)}\n`,
+    'utf8'
+  );
+}
+
 // ──────────────────────────────── flow ────────────────────────────────────
 
 async function main () {
@@ -177,7 +188,7 @@ async function main () {
   step(2, TOTAL_STEPS, 'Team bearer token');
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
 
-  let bearer = args.bearer || process.env.RRR_HOSTED_MCP_TOKEN || null;
+  let bearer = args.bearer || process.env.RRR_HOSTED_BEARER || process.env.RRR_HOSTED_MCP_TOKEN || null;
   if (!bearer && !args.yes) {
     info('You need a bearer token of the form: rrr_<prefix>_<32chars>');
     info('New team? Ask your rrr-search admin to run:');
@@ -192,6 +203,9 @@ async function main () {
       err('Bearer format invalid. Expected rrr_<prefix>_<32chars>.');
       process.exit(1);
     }
+    if (!args.bearer && process.env.RRR_HOSTED_MCP_TOKEN && !process.env.RRR_HOSTED_BEARER) {
+      warn('RRR_HOSTED_MCP_TOKEN is deprecated for this launcher; prefer RRR_HOSTED_BEARER.');
+    }
     ok(`Bearer captured (team prefix: ${bearer.split('_')[1]})`);
   } else {
     warn('No bearer — skipping MCP registration. You can run this wizard again after getting one.');
@@ -294,8 +308,11 @@ async function main () {
     }
     try {
       registerCodexMcp(bearer);
+      writeCodexBearerEnv(bearer);
       ok(`Registered ${MCP_NAME} in ~/.codex/config.toml`);
-      info('Same bearer token works for both Claude Code and Codex (MCP-02)');
+      info(`Codex will read the bearer from ${CODEX_BEARER_ENV_VAR}`);
+      info(`Codex launcher env file written to ${CODEX_ENV_FILE}`);
+      info(`Run scripts/codex-rrr.sh to launch Codex with RRR ready`);
     } catch (e) {
       warn(`Could not write ~/.codex/config.toml: ${e.message}`);
       info('You can manually add the MCP server entry — see docs/hosted-search-setup.md');

package/bin/install.js

@@ -900,6 +900,10 @@ function copyWithPathReplacement(srcDir, destDir, pathPrefix) {
   const entries = fs.readdirSync(srcDir, { withFileTypes: true });
 
   for (const entry of entries) {
+    if (entry.name === 'node_modules') {
+      continue;
+    }
+
     const srcPath = path.join(srcDir, entry.name);
     const destPath = path.join(destDir, entry.name);
 
@@ -916,6 +920,181 @@ function copyWithPathReplacement(srcDir, destDir, pathPrefix) {
   }
 }
 
+function getCodexHome() {
+  return expandTilde(process.env.CODEX_HOME) || path.join(os.homedir(), '.codex');
+}
+
+function getCodexPathPrefix(codexHome) {
+  const defaultCodexHome = path.join(os.homedir(), '.codex');
+  const normalizedHome = path.resolve(codexHome);
+  const normalizedDefault = path.resolve(defaultCodexHome);
+  if (normalizedHome === normalizedDefault) {
+    return '~/.codex/';
+  }
+  return `${codexHome.replace(/\\/g, '/')}/`;
+}
+
+function getCodexEnvPathPrefix(codexHome) {
+  const defaultCodexHome = path.join(os.homedir(), '.codex');
+  const normalizedHome = path.resolve(codexHome);
+  const normalizedDefault = path.resolve(defaultCodexHome);
+  if (normalizedHome === normalizedDefault) {
+    return '$HOME/.codex/';
+  }
+  return `${codexHome.replace(/\\/g, '/')}/`;
+}
+
+function copyFileIfExists(srcFile, destFile, installed) {
+  if (!fs.existsSync(srcFile)) return;
+  fs.mkdirSync(path.dirname(destFile), { recursive: true });
+  fs.copyFileSync(srcFile, destFile);
+  installed.push(destFile);
+}
+
+function copyDirIfExists(srcDir, destDir, pathPrefix, installed) {
+  if (!fs.existsSync(srcDir)) return;
+  copyWithPathReplacement(srcDir, destDir, pathPrefix);
+  installed.push(destDir);
+}
+
+function installCodexRuntimeAssets({ src, codexHome, dryRun = false }) {
+  const installed = [];
+  const skipped = [];
+  const codexPathPrefix = getCodexPathPrefix(codexHome);
+
+  if (dryRun) {
+    return { installed, skipped: ['dry-run'] };
+  }
+
+  const rrrSrc = path.join(src, 'rrr');
+  const rrrDest = path.join(codexHome, 'rrr');
+  copyDirIfExists(rrrSrc, rrrDest, codexPathPrefix, installed);
+
+  const scriptsDestDir = path.join(codexHome, 'rrr', 'scripts');
+  copyFileIfExists(
+    path.join(src, 'scripts', 'refresh-scope-cache.js'),
+    path.join(scriptsDestDir, 'refresh-scope-cache.js'),
+    installed
+  );
+  copyFileIfExists(
+    path.join(src, 'scripts', 'doctor-rrr.js'),
+    path.join(scriptsDestDir, 'doctor-rrr.js'),
+    installed
+  );
+  copyFileIfExists(
+    path.join(src, 'scripts', 'cleanup-phases.js'),
+    path.join(scriptsDestDir, 'cleanup-phases.js'),
+    installed
+  );
+  copyFileIfExists(
+    path.join(src, 'scripts', 'test-install-smoke.js'),
+    path.join(scriptsDestDir, 'test-install-smoke.js'),
+    installed
+  );
+  copyFileIfExists(
+    path.join(src, 'scripts', 'handoff-preflight.js'),
+    path.join(scriptsDestDir, 'handoff-preflight.js'),
+    installed
+  );
+  copyDirIfExists(
+    path.join(src, 'scripts', 'rrr-memory'),
+    path.join(scriptsDestDir, 'rrr-memory'),
+    codexPathPrefix,
+    installed
+  );
+  copyFileIfExists(
+    path.join(src, 'scripts', 'build-project-context.js'),
+    path.join(scriptsDestDir, 'build-project-context.js'),
+    installed
+  );
+  copyFileIfExists(
+    path.join(src, 'scripts', 'bootstrap-external-skills.js'),
+    path.join(scriptsDestDir, 'bootstrap-external-skills.js'),
+    installed
+  );
+  copyFileIfExists(
+    path.join(src, 'scripts', 'gen-agents-md.js'),
+    path.join(scriptsDestDir, 'gen-agents-md.js'),
+    installed
+  );
+  copyFileIfExists(
+    path.join(src, 'scripts', 'jarvis.sh'),
+    path.join(scriptsDestDir, 'jarvis.sh'),
+    installed
+  );
+  copyFileIfExists(
+    path.join(src, 'scripts', 'verify-milestone.js'),
+    path.join(scriptsDestDir, 'verify-milestone.js'),
+    installed
+  );
+  copyFileIfExists(
+    path.join(src, 'rrr', 'lib', 'inline-status.js'),
+    path.join(codexHome, 'rrr', 'lib', 'inline-status.js'),
+    installed
+  );
+  copyFileIfExists(
+    path.join(src, 'CHANGELOG.md'),
+    path.join(codexHome, 'rrr', 'CHANGELOG.md'),
+    installed
+  );
+
+  fs.mkdirSync(path.join(codexHome, 'rrr'), { recursive: true });
+  fs.writeFileSync(path.join(codexHome, 'rrr', 'VERSION'), pkg.version);
+  installed.push(path.join(codexHome, 'rrr', 'VERSION'));
+
+  if (fs.existsSync(path.join(rrrDest, 'package.json'))) {
+    try {
+      execSync('npm install --omit=dev --silent 2>/dev/null || npm install --omit=dev', {
+        cwd: rrrDest,
+        stdio: 'pipe',
+        timeout: 120000
+      });
+      installed.push(path.join(rrrDest, 'node_modules'));
+    } catch (e) {
+      skipped.push(`runtime deps failed: ${e.message}`);
+    }
+  }
+
+  const mcpServerDir = path.join(rrrDest, 'mcp-server');
+  if (fs.existsSync(path.join(mcpServerDir, 'package.json'))) {
+    try {
+      execSync('npm install --omit=dev --silent 2>/dev/null || npm install --omit=dev', {
+        cwd: mcpServerDir,
+        stdio: 'pipe',
+        timeout: 60000
+      });
+      installed.push(path.join(mcpServerDir, 'node_modules'));
+    } catch (e) {
+      skipped.push(`MCP deps failed: ${e.message}`);
+    }
+  }
+
+  return { installed, skipped };
+}
+
+function refreshProjectAgentsMdForCodex({ src, projectDir, dryRun = false }) {
+  const planningStatePath = path.join(projectDir, '.planning', 'STATE.md');
+  if (!fs.existsSync(planningStatePath)) {
+    return { refreshed: false, reason: 'no-planning-state' };
+  }
+
+  const generatorPath = path.join(src, 'scripts', 'gen-agents-md.js');
+  const commandsDir = path.join(src, 'commands', 'rrr');
+  const outputPath = path.join(projectDir, 'AGENTS.md');
+
+  if (!fs.existsSync(generatorPath) || !fs.existsSync(commandsDir)) {
+    return { refreshed: false, reason: 'generator-missing' };
+  }
+
+  if (dryRun) {
+    return { refreshed: false, reason: 'dry-run' };
+  }
+
+  const { generateAgentsMd } = require(generatorPath);
+  const result = generateAgentsMd({ commandsDir, outputPath });
+  return { refreshed: true, outputPath, skillCount: result.skillCount };
+}
+
 /**
  * Install scripts to target project (for Pushpa Mode and MCP setup)
  */
@@ -1563,6 +1742,22 @@ function install(isGlobal) {
     console.log(`  ${green}✓${reset} Installed rrr/scripts/build-project-context.js`);
   }
 
+  const additionalRuntimeScripts = [
+    'bootstrap-external-skills.js',
+    'gen-agents-md.js',
+    'jarvis.sh',
+    'verify-milestone.js',
+  ];
+  for (const scriptName of additionalRuntimeScripts) {
+    const scriptSrc = path.join(src, 'scripts', scriptName);
+    if (fs.existsSync(scriptSrc)) {
+      const scriptsDestDir = path.join(claudeDir, 'rrr', 'scripts');
+      fs.mkdirSync(scriptsDestDir, { recursive: true });
+      fs.copyFileSync(scriptSrc, path.join(scriptsDestDir, scriptName));
+      console.log(`  ${green}✓${reset} Installed rrr/scripts/${scriptName}`);
+    }
+  }
+
   // Copy inline-status.js for post-execution status display
   const inlineStatusSrc = path.join(src, 'rrr', 'lib', 'inline-status.js');
   if (fs.existsSync(inlineStatusSrc)) {
@@ -2184,18 +2379,42 @@ function install(isGlobal) {
   // Idempotent: installCodexSkills() overwrites existing files
   const codexStatus = detectCodexCLI();
   if (codexStatus.available) {
+    const codexHome = getCodexHome();
+    const codexHomeLabel = codexHome.replace(os.homedir(), '~');
+
+    try {
+      const runtimeResult = installCodexRuntimeAssets({
+        src,
+        codexHome,
+        dryRun: hasDryRun
+      });
+      const dryRunText = hasDryRun ? ' (dry-run)' : '';
+      console.log(`  ${green}✓${reset} Installed Codex runtime assets to ${codexHomeLabel}/rrr/${dryRunText}`);
+      if (runtimeResult.skipped.length > 0 && !hasDryRun) {
+        console.log(`  ${yellow}⚠${reset} Codex runtime skipped: ${runtimeResult.skipped.join(', ')}`);
+      }
+    } catch (e) {
+      // Silent fail — Codex runtime install is optional, must not break main Claude install
+      console.log(`  ${dim}Codex runtime assets skipped: ${e.message}${reset}`);
+    }
+
     try {
       const { installCodexSkills } = require('../rrr/lib/codex-skill-transform');
-      const codexSkillsDir = path.join(os.homedir(), '.codex', 'skills');
+      const codexSkillsDir = path.join(codexHome, 'skills');
       const rrrCommandsDir = path.join(src, 'commands', 'rrr');
       const result = installCodexSkills({
         sourceDir: rrrCommandsDir,
         targetDir: codexSkillsDir,
         dryRun: hasDryRun,
-        verbose: false
+        verbose: false,
+        codexPathPrefix: getCodexPathPrefix(codexHome),
+        codexEnvPathPrefix: getCodexEnvPathPrefix(codexHome)
       });
       if (result.errors.length === 0) {
-        console.log(`  ${green}✓${reset} Installed ${result.written.length} Codex skills to ~/.codex/skills/`);
+        const removedText = result.removed && result.removed.length > 0
+          ? `, removed ${result.removed.length} legacy flat files`
+          : '';
+        console.log(`  ${green}✓${reset} Installed ${result.written.length} Codex skills to ${codexHomeLabel}/skills/<skill>/SKILL.md${removedText}`);
       } else {
         console.log(`  ${yellow}⚠${reset} Installed ${result.written.length} Codex skills (${result.errors.length} errors)`);
         result.errors.slice(0, 3).forEach(e => {
@@ -2210,18 +2429,21 @@ function install(isGlobal) {
     // Install Codex agent .toml configs (AGENT-01, AGENT-02, AGENT-03)
     try {
       const { installCodexAgents } = require('../rrr/lib/codex-agent-gen');
-      const codexAgentsDir = path.join(os.homedir(), '.codex', 'agents');
+      const codexAgentsDir = path.join(codexHome, 'agents');
+      const codexConfigPath = path.join(codexHome, 'config.toml');
       const rrrAgentsDir = path.join(src, 'agents');
       const agentResult = installCodexAgents({
         sourceDir: rrrAgentsDir,
         targetDir: codexAgentsDir,
+        configPath: codexConfigPath,
         dryRun: hasDryRun,
         verbose: false
       });
       if (agentResult.errors.length === 0) {
         const removedCount = agentResult.removed.length;
         const removedText = removedCount > 0 ? `, pruned ${removedCount} stale configs` : '';
-        console.log(`  ${green}✓${reset} Installed ${agentResult.written.length} Codex agent configs to ~/.codex/agents/${removedText}`);
+        const registeredText = agentResult.registered > 0 ? `, registered ${agentResult.registered} in config.toml` : '';
+        console.log(`  ${green}✓${reset} Installed ${agentResult.written.length} Codex agent configs to ${codexHomeLabel}/agents/${removedText}${registeredText}`);
       } else {
         console.log(`  ${yellow}⚠${reset} Installed ${agentResult.written.length} agent configs (${agentResult.errors.length} errors)`);
         agentResult.errors.slice(0, 3).forEach(e => {
@@ -2232,6 +2454,21 @@ function install(isGlobal) {
       // Silent fail — agent install is optional, must not break main Claude install
       console.log(`  ${dim}Codex agents skipped: ${e.message}${reset}`);
     }
+
+    try {
+      const agentsMdResult = refreshProjectAgentsMdForCodex({
+        src,
+        projectDir: process.cwd(),
+        dryRun: hasDryRun
+      });
+      if (agentsMdResult.refreshed) {
+        const agentsPathLabel = agentsMdResult.outputPath.replace(process.cwd(), '.');
+        console.log(`  ${green}✓${reset} Refreshed ${agentsPathLabel} for Codex (${agentsMdResult.skillCount} skills)`);
+      }
+    } catch (e) {
+      // Silent fail — AGENTS.md is helpful for Codex, but should not block install/update
+      console.log(`  ${dim}Codex AGENTS.md refresh skipped: ${e.message}${reset}`);
+    }
   }
   // (no else — silently skip when codex is not in PATH)
 

package/commands/rrr/update.md

@@ -162,14 +162,14 @@ The `npx projecta-rrr@latest --global` step above automatically detects Codex CL
 
 If Codex CLI is installed, you will see:
 ```
-  ✓ Installed N Codex skills to ~/.codex/skills/
+  ✓ Installed N Codex skills to ~/.codex/skills/<skill>/SKILL.md
 ```
 
 If Codex CLI is not installed, this step is silently skipped.
 
 **To verify Codex skills were refreshed:**
 ```bash
-ls ~/.codex/skills/rrr-*.md 2>/dev/null | wc -l
+find ~/.codex/skills -path '*/rrr-*/SKILL.md' 2>/dev/null | wc -l
 ```
 Should show 47 (or current command count) skill files.
 </step>
@@ -177,13 +177,12 @@ Should show 47 (or current command count) skill files.
 <step name="refresh_agents_md">
 **AGENTS.md refresh (automatic)**
 
-After updating, regenerate `AGENTS.md` in the current project root so Codex has
-the latest trigger phrase catalogue. This uses the generator script shipped with
-the updated RRR package.
+The `npx projecta-rrr@latest --global` step above automatically regenerates
+`AGENTS.md` in the current project root when:
+- Codex CLI is installed and on PATH
+- the current repo has `.planning/STATE.md`
 
-```bash
-node "$HOME/.claude/rrr/scripts/gen-agents-md.js" 2>/dev/null || echo "AGENTS.md refresh skipped (run: node ~/.claude/rrr/scripts/gen-agents-md.js manually)"
-```
+No manual action is needed for normal repo updates.
 
 **If AGENTS.md was updated:**
 ```
@@ -193,6 +192,11 @@ node "$HOME/.claude/rrr/scripts/gen-agents-md.js" 2>/dev/null || echo "AGENTS.md
 **If not in an RRR project or script not found:**
 Silently skip — AGENTS.md is only relevant when Codex is being used in the project.
 
+**Manual fallback if needed:**
+```bash
+node "$HOME/.claude/rrr/scripts/gen-agents-md.js" 2>/dev/null || node "$HOME/.codex/rrr/scripts/gen-agents-md.js"
+```
+
 **To verify:**
 ```bash
 grep -c '\$rrr-' AGENTS.md 2>/dev/null && echo "skills listed" || echo "AGENTS.md not present"

package/docs/hosted-search-setup.md

@@ -43,6 +43,12 @@ npx projecta-rrr@1.21.0 --enable-hosted
 #    The installer registered `rrr-search-hosted` pointed at https://rrr-search-hosted.fly.dev/mcp.
 ```
 
+For Codex, use `scripts/codex-rrr.sh` to launch the CLI with the hosted bearer loaded from
+`~/.config/projecta-rrr/rrr-hosted.env`. Codex accepts the same `$rrr-*` trigger text, but it
+does not provide Claude-style live autocomplete for those triggers while you type.
+From this repo, `npm run codex:rrr -- <args>` is the shortest way to start Codex with the RRR
+environment loaded.
+
 **What happens under the hood:**
 
 1. The installer writes `rrr-search-hosted` into `~/.claude/mcp.registry.json` with `disabled:false`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projecta-rrr",
-  "version": "1.23.3",
+  "version": "1.23.5",
   "description": "A meta-prompting, context engineering and spec-driven development system for Claude Code by Projecta.ai",
   "bin": {
     "projecta-rrr": "bin/install.js",
@@ -16,6 +16,7 @@
     "test": "node --test tests/*.test.js && jest",
     "test:node": "node --test tests/*.test.js",
     "test:jest": "jest",
+    "codex:rrr": "bash scripts/codex-rrr.sh",
     "test:browser": "vitest --browser",
     "test:ui": "vitest --ui",
     "mcp:setup": "bash scripts/mcp-setup.sh",

package/rrr/lib/codex-agent-gen.js

@@ -21,6 +21,12 @@ const TIER_MAP = {
 };
 
 const LEGACY_TOP_LEVEL_FIELDS = ['tier', 'fallback_model'];
+const CODEX_AGENTS_BEGIN_MARKER = '# BEGIN projecta-rrr managed Codex agents';
+const CODEX_AGENTS_END_MARKER = '# END projecta-rrr managed Codex agents';
+const CODEX_MCP_TOOL_REWRITES = [
+  [/mcp__rrr-search-hosted__/g, 'mcp__rrr_search_hosted__'],
+  [/mcp__rrr-search__/g, 'mcp__rrr_search__'],
+];
 
 /**
  * Parse the YAML frontmatter from a markdown string.
@@ -92,6 +98,72 @@ function assertNoLegacyTopLevelFields(toml, filename) {
   }
 }
 
+/**
+ * Codex normalizes MCP server names in tool namespaces by replacing hyphens
+ * with underscores. Claude-facing RRR agent sources use the raw MCP names, so
+ * generated Codex agent prompts must rewrite those tool identifiers.
+ */
+function normalizeCodexMcpToolNames(text) {
+  let result = text || '';
+  for (const [pattern, replacement] of CODEX_MCP_TOOL_REWRITES) {
+    result = result.replace(pattern, replacement);
+  }
+  return result;
+}
+
+function tomlString(value) {
+  return String(value || '')
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/\r?\n/g, ' ');
+}
+
+function generateCodexAgentsConfigBlock(agentConfigs) {
+  const lines = [
+    CODEX_AGENTS_BEGIN_MARKER,
+    '# Generated by projecta-rrr — do not edit manually',
+  ];
+
+  for (const agent of agentConfigs) {
+    lines.push(
+      '',
+      `[agents.${agent.name}]`,
+      `description = "${tomlString(agent.description || agent.name)}"`,
+      `config_file = "${tomlString(agent.configFile)}"`
+    );
+  }
+
+  lines.push('', CODEX_AGENTS_END_MARKER);
+  return lines.join('\n') + '\n';
+}
+
+function stripManagedCodexAgentsConfig(content) {
+  if (!content) return '';
+
+  let result = content;
+  const markerPattern = new RegExp(
+    `\\n?${CODEX_AGENTS_BEGIN_MARKER.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[\\s\\S]*?${CODEX_AGENTS_END_MARKER.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\n?`,
+    'g'
+  );
+  result = result.replace(markerPattern, '\n');
+
+  // Self-heal older managed blocks that did not have markers.
+  result = result.replace(/\n?\[agents\.rrr-[^\]\r\n]+\][\s\S]*?(?=\n\[[^\]]+\]|\s*$)/g, '\n');
+
+  return result.replace(/\n{3,}/g, '\n\n').trim();
+}
+
+function mergeCodexAgentsConfig(configPath, agentConfigs) {
+  const block = generateCodexAgentsConfigBlock(agentConfigs);
+  const existing = fs.existsSync(configPath)
+    ? fs.readFileSync(configPath, 'utf8')
+    : '';
+  const stripped = stripManagedCodexAgentsConfig(existing);
+  const next = stripped ? `${stripped}\n\n${block}` : block;
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  fs.writeFileSync(configPath, next, 'utf8');
+}
+
 /**
  * Convert a single RRR agent markdown file (Claude Code format) into
  * a Codex-compatible TOML agent config string.
@@ -117,7 +189,7 @@ function generateCodexAgentToml(sourceMarkdown, filename) {
   // developer_instructions: body of the markdown file (the system prompt).
   // Truncated to 3000 chars; uses TOML literal multi-line strings (''') which
   // need zero escaping — safe as long as the body contains no ''' sequence.
-  const instructions = body.trim().slice(0, 3000);
+  const instructions = normalizeCodexMcpToolNames(body.trim()).slice(0, 3000);
 
   // Build TOML — only fields Codex CLI accepts
   const lines = [
@@ -125,7 +197,7 @@ function generateCodexAgentToml(sourceMarkdown, filename) {
     `# Source: agents/${filename}`,
     '',
     `name = "${agentName}"`,
-    `description = "${descriptionField || agentName}"`,
+    `description = "${normalizeCodexMcpToolNames(descriptionField || agentName)}"`,
     `model = "${tierEntry.model}"`,
     `developer_instructions = '''`,
     instructions,
@@ -147,14 +219,16 @@ function generateCodexAgentToml(sourceMarkdown, filename) {
  * @param {object} options
  * @param {string}  options.sourceDir - Absolute path to agents/ directory
  * @param {string}  options.targetDir - Absolute path to target directory (e.g. ~/.codex/agents/)
+ * @param {string}  [options.configPath] - Optional ~/.codex/config.toml path for agent registration
  * @param {boolean} [options.dryRun=false] - If true, compute paths but skip writing
  * @param {boolean} [options.verbose=false] - If true, log each file written
- * @returns {{ written: string[], skipped: string[], removed: string[], errors: Array<{file: string, error: string}> }}
+ * @returns {{ written: string[], skipped: string[], removed: string[], registered: number, errors: Array<{file: string, error: string}> }}
  */
 function installCodexAgents(options) {
   const {
     sourceDir,
     targetDir,
+    configPath = null,
     dryRun = false,
     verbose = false,
   } = options;
@@ -162,6 +236,7 @@ function installCodexAgents(options) {
   const written = [];
   const skipped = [];
   const removed = [];
+  const agentConfigs = [];
   const errors = [];
 
   // Ensure target directory exists (no-op if already exists)
@@ -175,7 +250,7 @@ function installCodexAgents(options) {
     entries = fs.readdirSync(sourceDir);
   } catch (err) {
     errors.push({ file: sourceDir, error: `Cannot read sourceDir: ${err.message}` });
-    return { written, skipped, errors };
+    return { written, skipped, removed, registered: 0, errors };
   }
 
   for (const entry of entries) {
@@ -193,6 +268,9 @@ function installCodexAgents(options) {
 
     try {
       const source = fs.readFileSync(sourcePath, 'utf8');
+      const { frontmatterLines } = parseFrontmatter(source);
+      const agentName = extractField(frontmatterLines, 'name') || basename;
+      const description = normalizeCodexMcpToolNames(extractField(frontmatterLines, 'description') || agentName);
       const toml = generateCodexAgentToml(source, entry);
 
       if (!dryRun) {
@@ -204,6 +282,11 @@ function installCodexAgents(options) {
       }
 
       written.push(outputFilename);
+      agentConfigs.push({
+        name: agentName,
+        description,
+        configFile: targetPath,
+      });
     } catch (err) {
       errors.push({ file: entry, error: err.message });
     }
@@ -228,11 +311,25 @@ function installCodexAgents(options) {
     }
   }
 
-  return { written, skipped, removed, errors };
+  if (configPath && !dryRun && errors.length === 0) {
+    try {
+      mergeCodexAgentsConfig(configPath, agentConfigs);
+    } catch (err) {
+      errors.push({ file: configPath, error: `Cannot merge Codex config: ${err.message}` });
+    }
+  }
+
+  return { written, skipped, removed, registered: configPath && !dryRun && errors.length === 0 ? agentConfigs.length : 0, errors };
 }
 
 module.exports = {
+  CODEX_AGENTS_BEGIN_MARKER,
+  CODEX_AGENTS_END_MARKER,
   generateCodexAgentToml,
+  generateCodexAgentsConfigBlock,
   installCodexAgents,
+  mergeCodexAgentsConfig,
+  normalizeCodexMcpToolNames,
+  stripManagedCodexAgentsConfig,
   TIER_MAP,
 };

package/rrr/lib/codex-skill-transform.js

@@ -15,6 +15,61 @@ const CLAUDE_ONLY_FIELDS = new Set([
   'argument-hint',
 ]);
 
+const CODEX_MCP_TOOL_REWRITES = [
+  [/mcp__rrr-search-hosted__/g, 'mcp__rrr_search_hosted__'],
+  [/mcp__rrr-search__/g, 'mcp__rrr_search__'],
+];
+
+function normalizeCodexMcpToolNames(text) {
+  let result = text || '';
+  for (const [pattern, replacement] of CODEX_MCP_TOOL_REWRITES) {
+    result = result.replace(pattern, replacement);
+  }
+  return result;
+}
+
+function convertSlashCommandsToCodexSkillMentions(content) {
+  let converted = content.replace(/\/rrr:([a-z0-9-]+)/gi, (_, commandName) => {
+    return `$rrr-${String(commandName).toLowerCase()}`;
+  });
+
+  // Convert hyphen-style command references while avoiding file paths.
+  converted = converted.replace(/(?<![a-zA-Z0-9./])\/rrr-([a-z0-9-]+)/gi, (_, commandName) => {
+    return `$rrr-${String(commandName).toLowerCase()}`;
+  });
+
+  return converted;
+}
+
+function getCodexSkillAdapterHeader(skillName) {
+  const invocation = `$${skillName}`;
+  return `<codex_skill_adapter>
+## A. Skill Invocation
+- This skill is invoked by mentioning \`${invocation}\`.
+- Treat all user text after \`${invocation}\` as \`{{RRR_ARGS}}\`.
+- If no arguments are present, treat \`{{RRR_ARGS}}\` as empty.
+
+## B. AskUserQuestion -> request_user_input Mapping
+RRR workflows use \`AskUserQuestion\` in Claude Code command sources. Translate it to Codex \`request_user_input\` when that tool is available:
+
+- \`header\` -> \`header\`
+- \`question\` -> \`question\`
+- Options formatted as \`"Label" - description\` -> \`{ label: "Label", description: "description" }\`
+- Generate \`id\` from the header: lowercase, replace spaces with underscores
+- Batched questions become one \`request_user_input\` call with multiple entries in \`questions[]\`
+- In Default mode, \`request_user_input\` is unavailable. Do not call it; present a concise numbered list instead and use a reasonable default when the workflow can proceed safely
+
+## C. Task() -> spawn_agent Mapping
+RRR workflows use \`Task(...)\` to delegate to RRR subagents. Translate to Codex collaboration tools when policy allows spawning:
+
+- \`Task(subagent_type="X", prompt="Y")\` -> \`spawn_agent(agent_type="X", message="Y")\`
+- Omit inline model parameters; Codex agent configuration owns model selection
+- Default \`fork_context\` to false unless the workflow explicitly needs shared context
+- For parallel fan-out, spawn agents, collect IDs, wait for completion, then close completed agents
+- If spawning is not allowed in the current mode, complete the work inline in the current agent
+</codex_skill_adapter>`;
+}
+
 /**
  * Parse the YAML frontmatter from a markdown string.
  *
@@ -125,6 +180,14 @@ function extractField(lines, key) {
   return null;
 }
 
+function quoteYamlScalar(value) {
+  return `"${String(value || '')
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/\r?\n/g, ' ')
+    .trim()}"`;
+}
+
 /**
  * Serialize filtered frontmatter lines back to a YAML block with delimiters.
  *
@@ -133,28 +196,13 @@ function extractField(lines, key) {
  *   description: <from source or generated>
  */
 function serializeFrontmatter(filteredLines, skillName, sourceDescription) {
-  // Build final set of lines, ensuring required fields are present
-  const hasName = filteredLines.some(l => /^name\s*:/.test(l));
-  const hasDescription = filteredLines.some(l => /^description\s*:/.test(l));
-
-  const outputLines = [...filteredLines];
-
-  // Replace or insert 'name' field (always override with derived skill name)
-  if (hasName) {
-    const idx = outputLines.findIndex(l => /^name\s*:/.test(l));
-    outputLines[idx] = `name: ${skillName}`;
-  } else {
-    // Insert name as first field
-    outputLines.unshift(`name: ${skillName}`);
-  }
+  const description = sourceDescription || `RRR: ${skillName}`;
+  const outputLines = filteredLines.filter(l => {
+    return !/^name\s*:/.test(l) && !/^description\s*:/.test(l);
+  });
 
-  // Insert description if missing
-  if (!hasDescription) {
-    const description = sourceDescription || `RRR: ${skillName}`;
-    // Insert after name
-    const nameIdx = outputLines.findIndex(l => /^name\s*:/.test(l));
-    outputLines.splice(nameIdx + 1, 0, `description: ${description}`);
-  }
+  outputLines.unshift(`description: ${quoteYamlScalar(description)}`);
+  outputLines.unshift(`name: ${quoteYamlScalar(skillName)}`);
 
   return `---\n${outputLines.join('\n')}\n---\n`;
 }
@@ -165,21 +213,33 @@ function serializeFrontmatter(filteredLines, skillName, sourceDescription) {
  * Conversions:
  *   1. `~/.claude/`  → `~/.codex/`
  *   2. `.claude/` when preceded by non-word/non-slash → `.codex/`
- *   3. `/rrr:`       → `$rrr-`
+ *   3. `$ARGUMENTS`  → `{{RRR_ARGS}}`
+ *   4. `/clear`      → removed
+ *   5. `/rrr:*`      → `$rrr-*`
  */
-function transformBody(body) {
-  // 1. ~/.claude/ → ~/.codex/
-  let result = body.replace(/~\/\.claude\//g, '~/.codex/');
+function transformBody(body, options = {}) {
+  const codexPathPrefix = options.codexPathPrefix || '~/.codex/';
+  const codexEnvPathPrefix = options.codexEnvPathPrefix || '$HOME/.codex/';
+  let result = convertSlashCommandsToCodexSkillMentions(body);
+
+  result = result.replace(/\$ARGUMENTS\b/g, '{{RRR_ARGS}}');
+
+  // Remove /clear references. Codex has no equivalent command.
+  result = result.replace(/`\/clear`\s*,?\s*then:?\s*\n?/gi, '');
+  result = result.replace(/\/clear\s*,?\s*then:?\s*\n?/gi, '');
+  result = result.replace(/^\s*`?\/clear`?\s*$/gm, '');
+
+  // 1. ~/.claude/ and $HOME/.claude/ -> Codex home.
+  result = result.replace(/~\/\.claude\//g, codexPathPrefix);
+  result = result.replace(/\$HOME\/\.claude\//g, codexEnvPathPrefix);
 
   // 2. .claude/ when NOT preceded by a word character or slash
   //    Use a regex that matches the context prefix so we can reconstruct it.
   //    Matches: start-of-string, whitespace, or punctuation that isn't a word char or slash.
   result = result.replace(/(^|[^a-zA-Z0-9/_])\.claude\//gm, '$1.codex/');
+  result = result.replace(/\.claudeignore\b/g, '.codexignore');
 
-  // 3. /rrr: → $rrr-
-  result = result.replace(/\/rrr:/g, '$rrr-');
-
-  return result;
+  return normalizeCodexMcpToolNames(result);
 }
 
 /**
@@ -190,7 +250,7 @@ function transformBody(body) {
  * @param {string} filename        - Filename (e.g. "plan-phase.md")
  * @returns {string} Transformed skill markdown
  */
-function convertRRRCommandToCodexSkill(sourceMarkdown, filename) {
+function convertRRRCommandToCodexSkill(sourceMarkdown, filename, options = {}) {
   const { frontmatterLines, body } = parseFrontmatter(sourceMarkdown);
 
   const skillName = deriveSkillName(filename);
@@ -205,9 +265,9 @@ function convertRRRCommandToCodexSkill(sourceMarkdown, filename) {
   const newFrontmatter = serializeFrontmatter(filteredLines, skillName, sourceDescription);
 
   // Transform body (path refs + trigger text)
-  const newBody = transformBody(body);
+  const newBody = transformBody(body, options);
 
-  return `${newFrontmatter}${newBody}`;
+  return `${newFrontmatter}\n${getCodexSkillAdapterHeader(skillName)}\n\n${newBody.trimStart()}`;
 }
 
 /**
@@ -218,7 +278,7 @@ function convertRRRCommandToCodexSkill(sourceMarkdown, filename) {
  * @param {string}  options.targetDir - Absolute path to target directory (e.g. ~/.codex/skills/)
  * @param {boolean} [options.dryRun=false] - If true, compute paths but skip writing
  * @param {boolean} [options.verbose=false] - If true, log each file written
- * @returns {{ written: string[], skipped: string[], errors: Array<{file: string, error: string}> }}
+ * @returns {{ written: string[], skipped: string[], removed: string[], errors: Array<{file: string, error: string}> }}
  */
 function installCodexSkills(options) {
   const {
@@ -226,10 +286,13 @@ function installCodexSkills(options) {
     targetDir,
     dryRun = false,
     verbose = false,
+    codexPathPrefix = '~/.codex/',
+    codexEnvPathPrefix = '$HOME/.codex/',
   } = options;
 
   const written = [];
   const skipped = [];
+  const removed = [];
   const errors = [];
 
   // Ensure target directory exists (no-op if already exists)
@@ -243,7 +306,7 @@ function installCodexSkills(options) {
     entries = fs.readdirSync(sourceDir);
   } catch (err) {
     errors.push({ file: sourceDir, error: `Cannot read sourceDir: ${err.message}` });
-    return { written, skipped, errors };
+    return { written, skipped, removed, errors };
   }
 
   for (const entry of entries) {
@@ -254,17 +317,27 @@ function installCodexSkills(options) {
     }
 
     const sourcePath = path.join(sourceDir, entry);
-    // Output filename: rrr-{basename}.md (e.g. plan-phase.md → rrr-plan-phase.md)
     const basename = path.basename(entry, '.md');
-    const outputFilename = `rrr-${basename}.md`;
-    const targetPath = path.join(targetDir, outputFilename);
+    const skillName = `rrr-${basename}`;
+    const skillDir = path.join(targetDir, skillName);
+    const outputFilename = path.join(skillName, 'SKILL.md');
+    const targetPath = path.join(skillDir, 'SKILL.md');
+    const legacyFlatPath = path.join(targetDir, `${skillName}.md`);
 
     try {
       const source = fs.readFileSync(sourcePath, 'utf8');
-      const transformed = convertRRRCommandToCodexSkill(source, entry);
+      const transformed = convertRRRCommandToCodexSkill(source, entry, {
+        codexPathPrefix,
+        codexEnvPathPrefix,
+      });
 
       if (!dryRun) {
+        fs.mkdirSync(skillDir, { recursive: true });
         fs.writeFileSync(targetPath, transformed, 'utf8');
+        if (fs.existsSync(legacyFlatPath)) {
+          fs.unlinkSync(legacyFlatPath);
+          removed.push(`${skillName}.md`);
+        }
       }
 
       if (verbose) {
@@ -277,10 +350,12 @@ function installCodexSkills(options) {
     }
   }
 
-  return { written, skipped, errors };
+  return { written, skipped, removed, errors };
 }
 
 module.exports = {
   convertRRRCommandToCodexSkill,
+  getCodexSkillAdapterHeader,
   installCodexSkills,
+  normalizeCodexMcpToolNames,
 };

package/scripts/codex-rrr.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+ENV_FILE="${RRR_HOSTED_ENV_FILE:-$HOME/.config/projecta-rrr/rrr-hosted.env}"
+
+if [[ -f "$ENV_FILE" ]]; then
+  # shellcheck disable=SC1090
+  source "$ENV_FILE"
+fi
+
+if [[ -z "${RRR_HOSTED_BEARER:-}" ]]; then
+  cat >&2 <<'EOF'
+RRR_HOSTED_BEARER is unset.
+Set it in ~/.config/projecta-rrr/rrr-hosted.env or export it before launching Codex.
+EOF
+  exit 1
+fi
+
+exec codex "$@"