projecta-rrr 1.22.4 → 1.23.1

package/AGENTS.md

@@ -0,0 +1,87 @@
+<!-- auto-generated by scripts/gen-agents-md.js — do NOT hand-edit; regenerate with: node scripts/gen-agents-md.js -->
+
+# RRR — AI Workflow for Codex
+
+RRR is a structured planning and execution workflow that reduces cognitive load while maintaining quality across brownfield projects. Codex invokes RRR capabilities via `$rrr-*` trigger phrases, each corresponding to a specific workflow skill.
+
+## Invocation
+
+Use `$rrr-{skill-name}` syntax to invoke a skill. Examples:
+
+- `$rrr-plan-phase` — create a detailed execution plan for a phase
+- `$rrr-execute-phase` — run all plans in a phase with wave-based parallelization
+- `$rrr-next` — see the recommended next action
+- `$rrr-help` — show full skill catalogue
+
+Trigger phrases are case-sensitive: use `$rrr-plan-phase` not `$rrr-PlanPhase`.
+
+## Core Workflow
+
+The RRR loop follows five steps:
+
+1. **Discuss** — Align on goals, scope, and approach
+2. **Plan** — Generate structured PLAN.md files with tasks and verification
+3. **Execute** — Run plans atomically, one task per commit
+4. **Verify** — Confirm output matches success criteria
+5. **Complete** — Archive milestone, update STATE.md, tag release
+
+## Available Skills
+
+| Trigger | Description |
+| ------- | ----------- |
+| `$rrr-add-phase` | Add phase to end of current milestone in roadmap |
+| `$rrr-add-todo` | Capture idea or task as todo from current conversation context |
+| `$rrr-audit-milestone` | Audit milestone completion against original intent before archiving |
+| `$rrr-bootstrap-nextjs` | Scaffold a Next.js App Router MVP with TypeScript, Tailwind, shadcn/ui, Vitest, and Playwright |
+| `$rrr-brownfield-audit` | Audit brownfield repos for scattered planning docs before RRR initialization |
+| `$rrr-check-browser-uat` | Verify browser UAT setup and report tool selection |
+| `$rrr-check-todos` | List pending todos and select one to work on |
+| `$rrr-check-upstream` | Run check-upstream workflow |
+| `$rrr-check-version` | Check version consistency across package.json, CHANGELOG, and planning docs |
+| `$rrr-complete-milestone` | Archive completed milestone and prepare for next version |
+| `$rrr-create-roadmap` | Create roadmap with phases for the project |
+| `$rrr-debug` | Systematic debugging with persistent state across context resets |
+| `$rrr-define-requirements` | Define what "done" looks like with checkable requirements |
+| `$rrr-discuss-milestone` | Gather context for next milestone through adaptive questioning |
+| `$rrr-discuss-phase` | Gather phase context through adaptive questioning before planning |
+| `$rrr-doctor` | Diagnose and fix duplicate RRR installs - non-destructive with rollback |
+| `$rrr-execute-phase` | Execute all plans in a phase with wave-based parallelization |
+| `$rrr-execute-plan` | Execute a PLAN.md file |
+| `$rrr-fix-visual-failure` | Analyze visual proof failures and suggest fixes |
+| `$rrr-help` | Show available RRR commands and usage guide |
+| `$rrr-insert-phase` | Insert urgent work as decimal phase (e.g., 72.1) between existing phases |
+| `$rrr-install-skill` | Install a skill from GitHub or marketplace |
+| `$rrr-list-phase-assumptions` | Surface Claude's assumptions about a phase approach before planning |
+| `$rrr-list-skills` | List all available skills (vendored and community) |
+| `$rrr-map-codebase` | Analyze codebase with parallel mapper agents to produce .planning/codebase/ documents |
+| `$rrr-migrate-phases` | Assign orphan phases to milestones (for v1.11 migration) |
+| `$rrr-mvp` | One-command router - detects project state, estimates complexity, and tells you exactly what to run next |
+| `$rrr-new-milestone` | Start a new milestone cycle — update PROJECT.md and route to requirements |
+| `$rrr-new-project` | Initialize a new project with deep context gathering and PROJECT.md |
+| `$rrr-next` | Determine and execute the next action based on project state |
+| `$rrr-optimize-cpu` | Optimize CPU, RAM, and disk - clean caches and kill zombies - clean caches, kill zombies, free RAM/CPU |
+| `$rrr-overnight` | Jarvis (overnight automation) guidance - preflight checks and safe run instructions |
+| `$rrr-pause-work` | Create context handoff when pausing work mid-phase |
+| `$rrr-plan-milestone-gaps` | Create phases to close all gaps identified by milestone audit |
+| `$rrr-plan-phase` | Create detailed execution plan for a phase (PLAN.md) with verification loop |
+| `$rrr-progress` | Check project progress, show context, and route to next action (execute or plan) |
+| `$rrr-remove-phase` | Remove a future phase from roadmap and renumber subsequent phases |
+| `$rrr-research-phase` | Research how to implement a phase (standalone - usually use /rrr:plan-phase instead) |
+| `$rrr-research-project` | Research domain ecosystem before creating roadmap |
+| `$rrr-resume-work` | Resume work from previous session with full context restoration |
+| `$rrr-savings` | Show token-savings report (session + lifetime) with tier distribution and Opus-rate dashboard |
+| `$rrr-search-skills` | Search for skills on skillsmp.com marketplace |
+| `$rrr-ship` | Create PR from verified work with planning context, or generate SHIP-READY.md |
+| `$rrr-think` | Apply structured thinking models for architecture decisions, risk assessment, scope cuts, and root cause analysis |
+| `$rrr-update` | Update RRR to latest version with idempotent install + duplicate prevention |
+| `$rrr-verify-work` | Validate built features through audit (default) or interactive UAT |
+| `$rrr-whats-new` | See what's new in RRR since your installed version |
+
+## Key Conventions
+
+- Always check `.planning/STATE.md` for current project position before invoking a workflow skill
+- Use `$rrr-next` to see recommended next action
+- Use `$rrr-help` for full skill catalogue
+- Trigger phrases are case-sensitive: `$rrr-plan-phase` not `$rrr-PlanPhase`
+
+<!-- generated: 2026-04-20T21:10:01.139Z | source: commands/rrr/*.md | count: 47 skills -->

package/CHANGELOG.md

@@ -4,6 +4,29 @@ 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.1] - 2026-04-20
+
+### Fixed
+- **Codex agent TOML generation** — removed `tier` and `fallback_model` fields from generated `.toml` files; Codex CLI rejects these unknown fields and silently ignores the entire agent definition. Generated files now contain only `name`, `description`, and `model`.
+
+## [1.23.0] - 2026-04-20
+
+**v1.23 Multi-Provider Compatibility — RRR workflow now works on OpenAI Codex with zero extra setup.**
+
+### Added
+- **Codex skill transformation** (`rrr/lib/codex-skill-transform.js`) — `convertRRRCommandToCodexSkill()` strips Claude-specific frontmatter, rewrites `~/.claude/` → `~/.codex/` and `/rrr:` → `$rrr-`; all 47 RRR commands available as `$rrr-*` Codex skills
+- **Codex agent configs** (`rrr/lib/codex-agent-gen.js`) — generates `.toml` files for all 13 agents with provider-agnostic tier labels (FAST/STANDARD/ADAPTIVE); no Anthropic model names in Codex configs
+- **Auto-detection + auto-install** — `bin/install.js` detects Codex CLI in PATH and installs skills/agents automatically; brownfield-safe (`.claude/` never touched)
+- **`/rrr:update` Codex support** — existing users get Codex skills and fresh AGENTS.md without a re-install
+- **Hosted MCP for Codex** (`bin/hosted-setup.js`) — registers `rrr-search-hosted` in `.codex/config.toml`; same bearer token, no second prompt; idempotent via remove-then-append
+- **`AGENTS.md` auto-generation** (`scripts/gen-agents-md.js`) — 47-row trigger table + workflow conventions for Codex; ships in npm package
+- **AGENTS.md sync gate** — `prepublish:check` section 16 fails if AGENTS.md drifts from skill files (hard block, not warning)
+
+### Changed
+- Installer idempotent for Codex: re-running `npx projecta-rrr` or `/rrr:update` does not duplicate skill files
+
+---
+
 ## [1.22.4] - 2026-04-19
 
 **Patch: semantic search wired into 5 agents; rrr-explore tool names fixed.**

package/bin/hosted-setup.js

@@ -23,12 +23,14 @@
 
 const fs = require('fs');
 const path = require('path');
+const os = require('os');
 const readline = require('readline');
 const { execSync, spawnSync } = require('child_process');
 
 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');
 
 // ──────────────────────────────── UI ──────────────────────────────────────
 
@@ -115,12 +117,39 @@ function mcpAlreadyRegistered (name) {
   } catch { return false; }
 }
 
+// ──────────────────────── Codex MCP helpers ───────────────────────────────
+
+function codexAlreadyRegistered () {
+  try {
+    const content = fs.readFileSync(CODEX_CONFIG_PATH, 'utf8');
+    return content.includes('[mcp_servers.' + MCP_NAME + ']');
+  } catch { return false; }
+}
+
+function registerCodexMcp (bearer) {
+  // Read existing config or start empty
+  let content = '';
+  try { content = fs.readFileSync(CODEX_CONFIG_PATH, 'utf8'); } catch { /* file may not exist */ }
+
+  // Remove existing registration if present (idempotent re-register)
+  const sectionRegex = /\[mcp_servers\.rrr-search-hosted\][\s\S]*?(?=\[|\s*$)/;
+  content = content.replace(sectionRegex, '').trimEnd();
+
+  // Append new registration
+  const section = `\n\n[mcp_servers.${MCP_NAME}]\nurl = "${HOSTED_URL}"\nheaders = { Authorization = "Bearer ${bearer}" }\n`;
+  content = content + section;
+
+  // Ensure ~/.codex directory exists
+  fs.mkdirSync(path.dirname(CODEX_CONFIG_PATH), { recursive: true });
+  fs.writeFileSync(CODEX_CONFIG_PATH, content, 'utf8');
+}
+
 // ──────────────────────────────── flow ────────────────────────────────────
 
 async function main () {
   const args = parseArgs(process.argv.slice(2));
   const cwd = process.cwd();
-  const TOTAL_STEPS = 6;
+  const TOTAL_STEPS = 7;
 
   banner(` rrr-search-hosted setup — ${path.basename(cwd)}`);
 
@@ -248,8 +277,33 @@ async function main () {
     } catch { warn('Health check skipped'); }
   }
 
-  // ---------- Step 6: GitHub App + first index ----------
-  step(6, TOTAL_STEPS, 'GitHub App + first index');
+  // ---------- Step 6: Register MCP in Codex (if Codex present) ----------
+  step(6, TOTAL_STEPS, 'Register MCP in Codex (optional)');
+
+  // Detect codex CLI
+  const hasCodex = (() => { try { execSync('command -v codex', { stdio: 'pipe' }); return true; } catch { return false; } })();
+
+  if (!bearer) {
+    warn('Skipping (no bearer).');
+  } else if (!hasCodex) {
+    info('Codex CLI not found — skipping ~/.codex/config.toml registration.');
+    info('If you install Codex later, re-run: projecta-rrr hosted-setup --bearer <your-token>');
+  } else {
+    if (codexAlreadyRegistered()) {
+      info('Removing existing Codex registration to re-register with current bearer');
+    }
+    try {
+      registerCodexMcp(bearer);
+      ok(`Registered ${MCP_NAME} in ~/.codex/config.toml`);
+      info('Same bearer token works for both Claude Code and Codex (MCP-02)');
+    } 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');
+    }
+  }
+
+  // ---------- Step 7: GitHub App + first index ----------
+  step(7, TOTAL_STEPS, 'GitHub App + first index');
   console.log();
   console.log(c.bold('  Install GitHub App (required for ingest):'));
   console.log(c.cyan(`    ${GH_APP_INSTALL_URL}`));

package/bin/install.js

@@ -74,6 +74,22 @@ function checkBashAvailability() {
   }
 }
 
+/**
+ * Detect if OpenAI Codex CLI is available in PATH
+ * Returns { available: boolean, version?: string }
+ */
+function detectCodexCLI() {
+  try {
+    const version = execSync('codex --version', { encoding: 'utf8', timeout: 5000 })
+      .split('\n')[0]
+      .trim();
+    return { available: true, version };
+  } catch (e) {
+    // codex not in PATH — not an error, just not installed
+    return { available: false };
+  }
+}
+
 /**
  * Print Windows bash remediation message
  */
@@ -2163,6 +2179,60 @@ function install(isGlobal) {
     }
   }
 
+  // Install Codex skills if Codex CLI is in PATH (INST-01, INST-03, INST-04, SKILL-02)
+  // Brownfield-safe: ~/.claude/ is never modified by this block
+  // Idempotent: installCodexSkills() overwrites existing files
+  const codexStatus = detectCodexCLI();
+  if (codexStatus.available) {
+    try {
+      const { installCodexSkills } = require('../rrr/lib/codex-skill-transform');
+      const codexSkillsDir = path.join(os.homedir(), '.codex', 'skills');
+      const rrrCommandsDir = path.join(src, 'commands', 'rrr');
+      const result = installCodexSkills({
+        sourceDir: rrrCommandsDir,
+        targetDir: codexSkillsDir,
+        dryRun: hasDryRun,
+        verbose: false
+      });
+      if (result.errors.length === 0) {
+        console.log(`  ${green}✓${reset} Installed ${result.written.length} Codex skills to ~/.codex/skills/`);
+      } else {
+        console.log(`  ${yellow}⚠${reset} Installed ${result.written.length} Codex skills (${result.errors.length} errors)`);
+        result.errors.slice(0, 3).forEach(e => {
+          console.log(`    - ${e.file}: ${e.error}`);
+        });
+      }
+    } catch (e) {
+      // Silent fail — Codex skill install is optional, must not break main Claude install
+      console.log(`  ${dim}Codex skills skipped: ${e.message}${reset}`);
+    }
+
+    // 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 rrrAgentsDir = path.join(src, 'agents');
+      const agentResult = installCodexAgents({
+        sourceDir: rrrAgentsDir,
+        targetDir: codexAgentsDir,
+        dryRun: hasDryRun,
+        verbose: false
+      });
+      if (agentResult.errors.length === 0) {
+        console.log(`  ${green}✓${reset} Installed ${agentResult.written.length} Codex agent configs to ~/.codex/agents/`);
+      } else {
+        console.log(`  ${yellow}⚠${reset} Installed ${agentResult.written.length} agent configs (${agentResult.errors.length} errors)`);
+        agentResult.errors.slice(0, 3).forEach(e => {
+          console.log(`    - ${e.file}: ${e.error}`);
+        });
+      }
+    } catch (e) {
+      // Silent fail — agent install is optional, must not break main Claude install
+      console.log(`  ${dim}Codex agents skipped: ${e.message}${reset}`);
+    }
+  }
+  // (no else — silently skip when codex is not in PATH)
+
   return { settingsPath, settings, statuslineCommand, notifyCommand, claudeDir, localDirName, isGlobal, bashAvailable: bashStatus.available };
 }
 

package/commands/rrr/update.md

@@ -155,6 +155,50 @@ If the version shown is older than what just installed, print a warning:
 Show error and STOP. Do not proceed.
 </step>
 
+<step name="refresh_codex_skills">
+**Codex skill refresh (automatic)**
+
+The `npx projecta-rrr@latest --global` step above automatically detects Codex CLI in PATH and re-installs transformed RRR skills to `~/.codex/skills/`. No manual action needed.
+
+If Codex CLI is installed, you will see:
+```
+  ✓ Installed N Codex skills to ~/.codex/skills/
+```
+
+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
+```
+Should show 47 (or current command count) skill files.
+</step>
+
+<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.
+
+```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)"
+```
+
+**If AGENTS.md was updated:**
+```
+  ✓ AGENTS.md refreshed (N skills)
+```
+
+**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.
+
+**To verify:**
+```bash
+grep -c '\$rrr-' AGENTS.md 2>/dev/null && echo "skills listed" || echo "AGENTS.md not present"
+```
+</step>
+
 <step name="verify_installation_integrity">
 Run the smoke test to verify installation succeeded:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projecta-rrr",
-  "version": "1.22.4",
+  "version": "1.23.1",
   "description": "A meta-prompting, context engineering and spec-driven development system for Claude Code by Projecta.ai",
   "bin": {
     "projecta-rrr": "bin/install.js",
@@ -36,6 +36,7 @@
   },
   "files": [
     "bin",
+    "AGENTS.md",
     "commands",
     "docs",
     "agents",

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

@@ -0,0 +1,191 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Provider-agnostic tier mapping for RRR agents.
+ *
+ * Maps Claude model labels (from agents/*.md frontmatter) to Codex-compatible
+ * tier labels and OpenAI model names. No Anthropic model names appear in output.
+ *
+ * AGENT-02, AGENT-03 tier definitions:
+ *   haiku   → FAST      (gpt-4o-mini)
+ *   sonnet  → STANDARD  (gpt-4o)
+ *   inherit → ADAPTIVE  (gpt-4o with o1 fallback for complex reasoning)
+ */
+const TIER_MAP = {
+  haiku: { tier: 'FAST', model: 'gpt-4o-mini' },
+  sonnet: { tier: 'STANDARD', model: 'gpt-4o' },
+  inherit: { tier: 'ADAPTIVE', model: 'gpt-4o', fallback_model: 'o1' },
+};
+
+/**
+ * Parse the YAML frontmatter from a markdown string.
+ *
+ * Supports files that start with a `---` block.
+ *
+ * Returns { frontmatterLines: string[], body: string } where:
+ *   - frontmatterLines: raw key-value lines from the YAML block (no delimiters)
+ *   - body: everything after the closing `---` delimiter (may start with \n)
+ *
+ * If there is no frontmatter, frontmatterLines is [] and body is the full content.
+ */
+function parseFrontmatter(source) {
+  // Must begin with ---\n
+  if (!source.startsWith('---\n') && !source.startsWith('---\r\n')) {
+    return { frontmatterLines: [], body: source };
+  }
+
+  // Find the closing --- delimiter (must be on its own line)
+  const afterOpen = source.slice(4); // skip the opening "---\n"
+  const closingMatch = afterOpen.match(/^---[ \t]*(\r?\n|$)/m);
+  if (!closingMatch) {
+    // No closing delimiter — treat entire file as body
+    return { frontmatterLines: [], body: source };
+  }
+
+  const closingIndex = closingMatch.index;
+  const frontmatterText = afterOpen.slice(0, closingIndex);
+  const body = afterOpen.slice(closingIndex + closingMatch[0].length);
+
+  // Split into lines for individual field processing
+  const frontmatterLines = frontmatterText.split('\n');
+  // Remove trailing empty line if present
+  if (frontmatterLines[frontmatterLines.length - 1] === '') {
+    frontmatterLines.pop();
+  }
+
+  return { frontmatterLines, body };
+}
+
+/**
+ * Extract a specific field value from frontmatter lines.
+ * Only looks at simple scalar values on the same line as the key.
+ * Returns null if the key is not found.
+ */
+function extractField(lines, key) {
+  for (const line of lines) {
+    const match = line.match(new RegExp(`^${key}\\s*:\\s*(.+)$`));
+    if (match) {
+      // Strip surrounding quotes if present
+      return match[1].replace(/^["']|["']$/g, '').trim();
+    }
+  }
+  return null;
+}
+
+/**
+ * Convert a single RRR agent markdown file (Claude Code format) into
+ * a Codex-compatible TOML agent config string.
+ *
+ * @param {string} sourceMarkdown  - Raw content of an agents/rrr-*.md file
+ * @param {string} filename        - Filename (e.g. "rrr-executor.md")
+ * @returns {string} Generated TOML string for ~/.codex/agents/<basename>.toml
+ */
+function generateCodexAgentToml(sourceMarkdown, filename) {
+  const { frontmatterLines } = parseFrontmatter(sourceMarkdown);
+
+  // Extract fields from frontmatter
+  const nameField = extractField(frontmatterLines, 'name');
+  const descriptionField = extractField(frontmatterLines, 'description');
+  const modelField = extractField(frontmatterLines, 'model');
+
+  // Derive agent name: use name: field if present, else strip .md from filename
+  const agentName = nameField || path.basename(filename, '.md');
+
+  // Look up tier mapping; default to STANDARD (sonnet) if model not found
+  const tierEntry = TIER_MAP[modelField] || TIER_MAP.sonnet;
+
+  // Build TOML lines — only fields Codex CLI accepts
+  const lines = [
+    '# Generated by projecta-rrr — do not edit manually',
+    `# Source: agents/${filename}`,
+    '',
+    `name = "${agentName}"`,
+    `description = "${descriptionField || agentName}"`,
+    `model = "${tierEntry.model}"`,
+  ];
+
+  return lines.join('\n') + '\n';
+}
+
+/**
+ * Install all RRR agent TOML config files to a target directory.
+ *
+ * Reads all .md files from sourceDir (agents/), generates a .toml config
+ * for each via generateCodexAgentToml(), and writes to targetDir as
+ * <basename>.toml (e.g. rrr-executor.md → rrr-executor.toml).
+ *
+ * @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 {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}> }}
+ */
+function installCodexAgents(options) {
+  const {
+    sourceDir,
+    targetDir,
+    dryRun = false,
+    verbose = false,
+  } = options;
+
+  const written = [];
+  const skipped = [];
+  const errors = [];
+
+  // Ensure target directory exists (no-op if already exists)
+  if (!dryRun) {
+    fs.mkdirSync(targetDir, { recursive: true });
+  }
+
+  // Read all files in sourceDir
+  let entries;
+  try {
+    entries = fs.readdirSync(sourceDir);
+  } catch (err) {
+    errors.push({ file: sourceDir, error: `Cannot read sourceDir: ${err.message}` });
+    return { written, skipped, errors };
+  }
+
+  for (const entry of entries) {
+    // Only process .md files
+    if (!entry.endsWith('.md')) {
+      skipped.push(entry);
+      continue;
+    }
+
+    const sourcePath = path.join(sourceDir, entry);
+    // Output filename: <basename>.toml (source files are already rrr-*.md)
+    const basename = path.basename(entry, '.md');
+    const outputFilename = `${basename}.toml`;
+    const targetPath = path.join(targetDir, outputFilename);
+
+    try {
+      const source = fs.readFileSync(sourcePath, 'utf8');
+      const toml = generateCodexAgentToml(source, entry);
+
+      if (!dryRun) {
+        fs.writeFileSync(targetPath, toml, 'utf8');
+      }
+
+      if (verbose) {
+        console.log(`  ${dryRun ? '[dry-run] would write' : 'wrote'}: ${outputFilename}`);
+      }
+
+      written.push(outputFilename);
+    } catch (err) {
+      errors.push({ file: entry, error: err.message });
+    }
+  }
+
+  return { written, skipped, errors };
+}
+
+module.exports = {
+  generateCodexAgentToml,
+  installCodexAgents,
+  TIER_MAP,
+};

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

@@ -0,0 +1,286 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Fields in YAML frontmatter that are Claude Code-specific and must be stripped
+ * when generating a Codex-compatible skill.
+ */
+const CLAUDE_ONLY_FIELDS = new Set([
+  'model',
+  'allowed_tools',
+  'allowed-tools',
+  'agent',
+  'argument-hint',
+]);
+
+/**
+ * Parse the YAML frontmatter from a markdown string.
+ *
+ * Supports files that start with a `---` block.
+ *
+ * Returns { frontmatterLines: string[], body: string } where:
+ *   - frontmatterLines: raw key-value lines from the YAML block (no delimiters)
+ *   - body: everything after the closing `---` delimiter (may start with \n)
+ *
+ * If there is no frontmatter, frontmatterLines is [] and body is the full content.
+ */
+function parseFrontmatter(source) {
+  // Must begin with ---\n
+  if (!source.startsWith('---\n') && !source.startsWith('---\r\n')) {
+    return { frontmatterLines: [], body: source };
+  }
+
+  // Find the closing --- delimiter (must be on its own line)
+  const afterOpen = source.slice(4); // skip the opening "---\n"
+  const closingMatch = afterOpen.match(/^---[ \t]*(\r?\n|$)/m);
+  if (!closingMatch) {
+    // No closing delimiter — treat entire file as body
+    return { frontmatterLines: [], body: source };
+  }
+
+  const closingIndex = closingMatch.index;
+  const frontmatterText = afterOpen.slice(0, closingIndex);
+  const body = afterOpen.slice(closingIndex + closingMatch[0].length);
+
+  // Split into lines for individual field processing
+  const frontmatterLines = frontmatterText.split('\n');
+  // Remove trailing empty line if present
+  if (frontmatterLines[frontmatterLines.length - 1] === '') {
+    frontmatterLines.pop();
+  }
+
+  return { frontmatterLines, body };
+}
+
+/**
+ * Strip Claude-specific fields from parsed frontmatter lines.
+ *
+ * Handles multi-line values (indented continuation lines) for fields like:
+ *   allowed-tools:
+ *     - Read
+ *     - Write
+ *
+ * Returns filtered lines (no delimiters).
+ */
+function stripClaudeFields(lines) {
+  const result = [];
+  let skipping = false;
+
+  for (const line of lines) {
+    // Detect a top-level YAML key (no leading spaces/tabs before the key)
+    const keyMatch = line.match(/^([a-zA-Z_-][a-zA-Z0-9_-]*)\s*:/);
+    if (keyMatch) {
+      const key = keyMatch[1];
+      if (CLAUDE_ONLY_FIELDS.has(key)) {
+        skipping = true;
+        continue;
+      } else {
+        skipping = false;
+      }
+    } else if (skipping) {
+      // Check if this is a continuation/value line (indented or starts with -)
+      // If the line is non-empty and starts with whitespace or is a list item,
+      // it belongs to the field being skipped.
+      if (/^[ \t]/.test(line) || line === '') {
+        continue;
+      }
+      // Otherwise it's a new top-level key that wasn't caught above — stop skipping
+      skipping = false;
+    }
+
+    if (!skipping) {
+      result.push(line);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Derive the skill name from a filename.
+ *
+ * e.g. "plan-phase.md" → "rrr-plan-phase"
+ *      "execute-phase.md" → "rrr-execute-phase"
+ */
+function deriveSkillName(filename) {
+  const basename = path.basename(filename, '.md');
+  return `rrr-${basename}`;
+}
+
+/**
+ * Extract a specific field value from frontmatter lines.
+ * Only looks at simple scalar values on the same line as the key.
+ * Returns null if the key is not found.
+ */
+function extractField(lines, key) {
+  for (const line of lines) {
+    const match = line.match(new RegExp(`^${key}\\s*:\\s*(.+)$`));
+    if (match) {
+      // Strip surrounding quotes if present
+      return match[1].replace(/^["']|["']$/g, '').trim();
+    }
+  }
+  return null;
+}
+
+/**
+ * Serialize filtered frontmatter lines back to a YAML block with delimiters.
+ *
+ * Ensures the output frontmatter always contains at minimum:
+ *   name: <derived>
+ *   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}`);
+  }
+
+  // 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}`);
+  }
+
+  return `---\n${outputLines.join('\n')}\n---\n`;
+}
+
+/**
+ * Apply path reference and trigger text conversions to the skill body.
+ *
+ * Conversions:
+ *   1. `~/.claude/`  → `~/.codex/`
+ *   2. `.claude/` when preceded by non-word/non-slash → `.codex/`
+ *   3. `/rrr:`       → `$rrr-`
+ */
+function transformBody(body) {
+  // 1. ~/.claude/ → ~/.codex/
+  let result = body.replace(/~\/\.claude\//g, '~/.codex/');
+
+  // 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/');
+
+  // 3. /rrr: → $rrr-
+  result = result.replace(/\/rrr:/g, '$rrr-');
+
+  return result;
+}
+
+/**
+ * Convert a single RRR command markdown file (Claude Code format) into
+ * a Codex-compatible skill markdown string.
+ *
+ * @param {string} sourceMarkdown  - Raw content of a commands/rrr/*.md file
+ * @param {string} filename        - Filename (e.g. "plan-phase.md")
+ * @returns {string} Transformed skill markdown
+ */
+function convertRRRCommandToCodexSkill(sourceMarkdown, filename) {
+  const { frontmatterLines, body } = parseFrontmatter(sourceMarkdown);
+
+  const skillName = deriveSkillName(filename);
+
+  // Extract description before stripping fields (it should survive, but grab it now)
+  const sourceDescription = extractField(frontmatterLines, 'description');
+
+  // Strip Claude-specific fields
+  const filteredLines = stripClaudeFields(frontmatterLines);
+
+  // Serialize with required fields guaranteed
+  const newFrontmatter = serializeFrontmatter(filteredLines, skillName, sourceDescription);
+
+  // Transform body (path refs + trigger text)
+  const newBody = transformBody(body);
+
+  return `${newFrontmatter}${newBody}`;
+}
+
+/**
+ * Install all RRR command skills as Codex-compatible skill files to a target directory.
+ *
+ * @param {object} options
+ * @param {string}  options.sourceDir - Absolute path to commands/rrr/
+ * @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}> }}
+ */
+function installCodexSkills(options) {
+  const {
+    sourceDir,
+    targetDir,
+    dryRun = false,
+    verbose = false,
+  } = options;
+
+  const written = [];
+  const skipped = [];
+  const errors = [];
+
+  // Ensure target directory exists (no-op if already exists)
+  if (!dryRun) {
+    fs.mkdirSync(targetDir, { recursive: true });
+  }
+
+  // Read all files in sourceDir
+  let entries;
+  try {
+    entries = fs.readdirSync(sourceDir);
+  } catch (err) {
+    errors.push({ file: sourceDir, error: `Cannot read sourceDir: ${err.message}` });
+    return { written, skipped, errors };
+  }
+
+  for (const entry of entries) {
+    // Only process .md files
+    if (!entry.endsWith('.md')) {
+      skipped.push(entry);
+      continue;
+    }
+
+    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);
+
+    try {
+      const source = fs.readFileSync(sourcePath, 'utf8');
+      const transformed = convertRRRCommandToCodexSkill(source, entry);
+
+      if (!dryRun) {
+        fs.writeFileSync(targetPath, transformed, 'utf8');
+      }
+
+      if (verbose) {
+        console.log(`  ${dryRun ? '[dry-run] would write' : 'wrote'}: ${outputFilename}`);
+      }
+
+      written.push(outputFilename);
+    } catch (err) {
+      errors.push({ file: entry, error: err.message });
+    }
+  }
+
+  return { written, skipped, errors };
+}
+
+module.exports = {
+  convertRRRCommandToCodexSkill,
+  installCodexSkills,
+};

package/scripts/gen-agents-md.js

@@ -0,0 +1,146 @@
+'use strict';
+
+/**
+ * gen-agents-md.js — Generate AGENTS.md for RRR project root.
+ *
+ * Reads every commands/rrr/*.md filename, derives the $rrr-{stem} trigger
+ * phrase, and writes a fresh AGENTS.md to the project root.
+ *
+ * Usage:
+ *   node scripts/gen-agents-md.js
+ *
+ * DO NOT hand-edit AGENTS.md — regenerate with:
+ *   node scripts/gen-agents-md.js
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Build the full AGENTS.md content string from a commandsDir.
+ *
+ * @param {string} commandsDir - Absolute path to commands/rrr/ directory
+ * @returns {{ content: string, skillCount: number }} Generated content and skill count
+ */
+function buildContent(commandsDir) {
+  // Read all .md files, sort alphabetically
+  const allFiles = fs.readdirSync(commandsDir);
+  const mdFiles = allFiles.filter(f => f.endsWith('.md')).sort();
+
+  const skills = mdFiles.map(filename => {
+    const stem = path.basename(filename, '.md');
+    const filePath = path.join(commandsDir, filename);
+
+    let description = `Run ${stem} workflow`;
+    try {
+      const content = fs.readFileSync(filePath, 'utf8');
+      const descMatch = content.match(/^description:\s*(.+)$/m);
+      if (descMatch) {
+        description = descMatch[1].trim();
+        // Strip surrounding quotes if present
+        description = description.replace(/^["']|["']$/g, '').trim();
+      }
+    } catch (err) {
+      // Use default description on read error
+    }
+
+    return { stem, trigger: `$rrr-${stem}`, description };
+  });
+
+  const skillCount = skills.length;
+
+  // Build trigger table rows
+  const tableRows = skills
+    .map(s => `| \`${s.trigger}\` | ${s.description} |`)
+    .join('\n');
+
+  const timestamp = new Date().toISOString();
+
+  const content = [
+    `<!-- auto-generated by scripts/gen-agents-md.js — do NOT hand-edit; regenerate with: node scripts/gen-agents-md.js -->`,
+    ``,
+    `# RRR — AI Workflow for Codex`,
+    ``,
+    `RRR is a structured planning and execution workflow that reduces cognitive load while maintaining quality across brownfield projects. Codex invokes RRR capabilities via \`$rrr-*\` trigger phrases, each corresponding to a specific workflow skill.`,
+    ``,
+    `## Invocation`,
+    ``,
+    `Use \`$rrr-{skill-name}\` syntax to invoke a skill. Examples:`,
+    ``,
+    `- \`$rrr-plan-phase\` — create a detailed execution plan for a phase`,
+    `- \`$rrr-execute-phase\` — run all plans in a phase with wave-based parallelization`,
+    `- \`$rrr-next\` — see the recommended next action`,
+    `- \`$rrr-help\` — show full skill catalogue`,
+    ``,
+    `Trigger phrases are case-sensitive: use \`$rrr-plan-phase\` not \`$rrr-PlanPhase\`.`,
+    ``,
+    `## Core Workflow`,
+    ``,
+    `The RRR loop follows five steps:`,
+    ``,
+    `1. **Discuss** — Align on goals, scope, and approach`,
+    `2. **Plan** — Generate structured PLAN.md files with tasks and verification`,
+    `3. **Execute** — Run plans atomically, one task per commit`,
+    `4. **Verify** — Confirm output matches success criteria`,
+    `5. **Complete** — Archive milestone, update STATE.md, tag release`,
+    ``,
+    `## Available Skills`,
+    ``,
+    `| Trigger | Description |`,
+    `| ------- | ----------- |`,
+    tableRows,
+    ``,
+    `## Key Conventions`,
+    ``,
+    `- Always check \`.planning/STATE.md\` for current project position before invoking a workflow skill`,
+    `- Use \`$rrr-next\` to see recommended next action`,
+    `- Use \`$rrr-help\` for full skill catalogue`,
+    `- Trigger phrases are case-sensitive: \`$rrr-plan-phase\` not \`$rrr-PlanPhase\``,
+    ``,
+    `<!-- generated: ${timestamp} | source: commands/rrr/*.md | count: ${skillCount} skills -->`,
+  ].join('\n');
+
+  return { content, skillCount };
+}
+
+/**
+ * Generate AGENTS.md and write it to outputPath.
+ *
+ * @param {object} options
+ * @param {string} options.commandsDir - Absolute path to commands/rrr/ directory
+ * @param {string} options.outputPath  - Absolute path to output AGENTS.md
+ * @returns {{ written: string, skillCount: number }}
+ */
+function generateAgentsMd({ commandsDir, outputPath }) {
+  const { content, skillCount } = buildContent(commandsDir);
+  fs.writeFileSync(outputPath, content, 'utf8');
+  return { written: content, skillCount };
+}
+
+/**
+ * Return expected AGENTS.md content WITHOUT writing to disk.
+ * Used by prepublish-check.js to verify the committed file is in sync.
+ *
+ * Note: The timestamp in the footer will differ between calls. For sync
+ * checking, compare everything except the generated: timestamp line.
+ *
+ * @param {object} options
+ * @param {string} options.commandsDir - Absolute path to commands/rrr/ directory
+ * @returns {string} Expected content string
+ */
+function getExpectedContent({ commandsDir }) {
+  const { content } = buildContent(commandsDir);
+  return content;
+}
+
+module.exports = { generateAgentsMd, getExpectedContent };
+
+// CLI entry point
+if (require.main === module) {
+  const root = path.join(__dirname, '..');
+  generateAgentsMd({
+    commandsDir: path.join(root, 'commands', 'rrr'),
+    outputPath: path.join(root, 'AGENTS.md'),
+  });
+  console.log('AGENTS.md generated at project root');
+}

package/scripts/prepublish-check.js

@@ -346,6 +346,33 @@ try {
   check('Install smoke v1.20 parity', false, `Could not run: ${e.message}`);
 }
 
+// 16. AGENTS.md sync check (SYNC-02, Phase 89)
+console.log(`\n${cyan}16. AGENTS.md Sync${reset}`);
+try {
+  const genAgentsMd = require('./gen-agents-md.js');
+  const root = path.join(__dirname, '..');
+  const commandsDir = path.join(root, 'commands', 'rrr');
+  const agentsMdPath = path.join(root, 'AGENTS.md');
+
+  if (!fs.existsSync(agentsMdPath)) {
+    check('AGENTS.md exists', false, 'Run: node scripts/gen-agents-md.js');
+  } else {
+    const onDisk = fs.readFileSync(agentsMdPath, 'utf8');
+    const expected = genAgentsMd.getExpectedContent({ commandsDir });
+
+    // Compare by normalizing the timestamp footer line (it changes on every run)
+    // Strip the <!-- generated: ... --> line before comparing
+    const normalize = s => s.replace(/<!--\s*generated:.*?-->/g, '').trim();
+    const diskNorm = normalize(onDisk);
+    const expectedNorm = normalize(expected);
+
+    check('AGENTS.md in sync with commands/rrr/*.md', diskNorm === expectedNorm,
+      'AGENTS.md is out of sync. Run: node scripts/gen-agents-md.js');
+  }
+} catch (e) {
+  check('AGENTS.md sync check', false, `Could not run: ${e.message}`);
+}
+
 // Summary
 console.log(`\n${cyan}━━━ Summary ━━━${reset}\n`);
 if (hasErrors) {