@hanzlaa/rcode 4.1.1 → 4.3.0

package/AGENTS.md

@@ -24,7 +24,7 @@ If a user says "just keep going" or "don't stop until done", that authorization
 
 - Follow [Conventional Commits](https://www.conventionalcommits.org/) format: `type(scope): subject`
 - Types allowed: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `perf`, `revert`
-- Scopes allowed: `agents`, `skills`, `workflows`, `templates`, `dashboard`, `docs`, `config`, `github`, `commands`, `memory`, `brand`, `cli`, `ci`, `release`, `meta`, `tasks`, `migrations`, `refs`, `state`, `hooks`, `install`, `parity`, `triggers`, `dogfood`, `namespace`, `planning`, `insights`, `help`, `roadmap`, `session`, `audits`, `execute`, `executor`, `plan`, `planner`, `readme`, `sync`, `sprint`, `agent-exp`, `extensibility`, `lens-audit`, `tiers`, `build`, `council`, `doctor`, `postinstall`, `progress`, `security`, `tools`, `uninstall`, `update`, `test`, `changelog`, `scopes`, `phases`, `references`, `kanban`, `orchestrator`, `orchpanel`, `status`, `bin`, `brain`, `dogfeed`, `new-project`, `package`, `rcode-tools`, `rihal-tools`, `team`, `usp`, `v4`, `observability`, `audit`, `agent-rules`, `cursor`, `i18n`, `phase`, plus numeric phase/sprint scopes (e.g. `docs(15)`, `feat(8.3)`)
+- Scopes allowed: `agents`, `skills`, `workflows`, `templates`, `dashboard`, `docs`, `config`, `github`, `commands`, `memory`, `brand`, `cli`, `ci`, `release`, `meta`, `tasks`, `migrations`, `refs`, `state`, `hooks`, `install`, `parity`, `triggers`, `dogfood`, `namespace`, `planning`, `insights`, `help`, `roadmap`, `session`, `audits`, `execute`, `executor`, `plan`, `planner`, `readme`, `sync`, `sprint`, `agent-exp`, `extensibility`, `lens-audit`, `tiers`, `build`, `council`, `doctor`, `postinstall`, `progress`, `security`, `tools`, `uninstall`, `update`, `test`, `changelog`, `scopes`, `phases`, `references`, `kanban`, `orchestrator`, `orchpanel`, `status`, `bin`, `brain`, `dogfeed`, `new-project`, `package`, `rcode-tools`, `rihal-tools`, `team`, `usp`, `v4`, `observability`, `audit`, `agent-rules`, `cursor`, `i18n`, `phase`, `scaffold`, `campaign`, `ship`, plus numeric phase/sprint scopes (e.g. `docs(15)`, `feat(8.3)`)
 - Subject: lowercase first letter, imperative mood, no trailing period, under 72 chars
 - **NEVER add Claude/AI attribution to commit messages.** No "Generated with Claude Code", no "Co-Authored-By: Claude", no "🤖 Generated". The user does not want this.
 - **NEVER use `--no-verify`** to bypass hooks. If hooks fail, fix the underlying issue.

package/CONTRIBUTING.md

@@ -349,6 +349,9 @@ We use [Conventional Commits](https://www.conventionalcommits.org/) format. The
 - `cursor` — Cursor IDE rules under `.cursor/rules/rcode/`
 - `i18n` — internationalization, brand strings, and user-visible copy
 - `phase` — phase-lifecycle changes (variable renames, phase-loop fixes); use numeric `<phase-id>` for in-phase commits
+- `scaffold` — scaffold-project workflow changes
+- `campaign` — fix-campaign orchestration tracking files
+- `ship` — ship workflow changes
 - `<phase-id>` — numeric phase scope when committing inside a phase (e.g. `docs(15)`, `feat(8.3)`)
 - `<sprint-id>` — numeric sprint scope inside a phase (e.g. `feat(15.1)`)
 

package/README.md

@@ -117,6 +117,9 @@ pnpm dlx @hanzlaa/rcode install
 /rcode-init
 ```
 
+> **Don't have pnpm?** On Node 18+ / npm 11.x we recommend pnpm to avoid `npx` cache issues:
+> `npm install -g pnpm`
+
 `/rcode-init` detects your project state (fresh / existing / returning) and routes to the right first action. For a greenfield project it auto-routes to `/rcode-new-project`.
 
 ### The full loop

package/cli/agent.js

@@ -24,7 +24,9 @@ module.exports = function agent(args, { packageRoot }) {
   }
 
   const name = args[0];
-  const agentName = `rcode-${name}`;
+  // Strip rcode- prefix if already provided so rcode agent rcode-executor works (#882)
+  const bare = name.startsWith('rcode-') ? name.slice('rcode-'.length) : name;
+  const agentName = `rcode-${bare}`;
 
   // Validate agent file exists
   const agentFile = path.join(agentDir, `${agentName}.md`);

package/cli/index.js

@@ -34,6 +34,10 @@ const COMMANDS = {
   agent: require('./agent'),
   doctor: require('./doctor'),
   workflow: require('./workflow'),  // lifecycle bridge for non-Claude runtimes
+  // Thin lifecycle aliases — delegate to workflow show <name> (#883)
+  plan:    (args, ctx) => lifecycleAlias('plan',           args, ctx),
+  execute: (args, ctx) => lifecycleAlias('execute-sprint', args, ctx),
+  ship:    (args, ctx) => lifecycleAlias('ship',           args, ctx),
   'set-profile': require('./set-profile'),
   'set-mode': require('./set-mode'),
   config: require('./config'),
@@ -70,6 +74,9 @@ Usage:
   github-sync    Sync .rcode/ phases/epics/stories to GitHub (dry-run default)
 
 🔄 LIFECYCLE (Codex / Copilot / Grok bridge)
+  plan                         Print the plan workflow (alias for workflow show plan)
+  execute                      Print the execute-sprint workflow
+  ship                         Print the ship workflow
   workflow list                List all lifecycle workflow names
   workflow show <name>         Print a workflow's full instructions to stdout
   workflow show new-project    → project setup + ROADMAP
@@ -82,6 +89,7 @@ Usage:
   workflow show ship           → deploy / release workflow
 
   Non-Claude agents: pipe to your agent instead of using slash commands.
+  Example: rcode plan | codex run -
   Example: rcode workflow show plan | codex run -
 
 👥 TEAM
@@ -91,6 +99,7 @@ Usage:
                  rcode agent --list   to see available agents
   show-model     Show which model each agent uses in the current profile
   dashboard      Start the Diwan view-only dashboard (port 7717)
+                 Starts a view-only dashboard at http://localhost:7717. No write access.
   serve          Alias for dashboard
 
 ⚙️  META
@@ -111,6 +120,26 @@ Documentation: https://github.com/hanzlahabib/rihal-code
   `.trim());
 }
 
+/**
+ * Lifecycle aliases (plan/execute/ship): show the workflow then print actionable
+ * next-step guidance so the user knows how to actually run it.
+ */
+function lifecycleAlias(workflowName, args, ctx) {
+  require('./workflow')(['show', workflowName, ...args], ctx);
+
+  const hasAuto = args.includes('--auto') || args.includes('--run');
+
+  console.log('\n─────────────────────────────────────────────');
+  console.log(`▶ To run: paste the above into Claude Code as  /${workflowName === 'execute-sprint' ? 'rcode-execute-sprint' : `rcode-${workflowName}`}`);
+  console.log('  or pipe it directly:  rcode ' + (workflowName === 'execute-sprint' ? 'execute' : workflowName) + ' | cld --model sonnet');
+
+  if (hasAuto) {
+    console.log('\n  AUTO mode detected — in Claude Code run:  /rcode-' +
+      (workflowName === 'execute-sprint' ? 'execute-sprint' : workflowName) +
+      ' --auto  (applies yolo defaults, skips confirmation prompts)');
+  }
+}
+
 /**
  * npm 10+ suppresses postinstall script output during global installs, so users
  * who run `npm install -g @hanzlaa/rcode` see only "added 1 package" with no

package/cli/install.js

@@ -59,6 +59,11 @@ const os = require('os');
 // Ctrl+C mid-write and malicious symlink-traversal during dedup/cleanup.
 const { writeFileAtomic, safeRmSync } = require('./lib/fsutil.cjs');
 
+// HOME-aware home resolution (#889) — os.homedir() ignores a stubbed HOME on
+// Windows (it reads USERPROFILE), so HOME-isolated tests and CI leaked global
+// installs (~/.rcode, ~/.codex, ~/.gemini) into the real profile dir there.
+const { homedir } = require('./lib/homedir.cjs');
+
 // Bundled packages — devDeps inlined by esbuild, loaded from node_modules in dev.
 const pc = require('picocolors');
 const { createSpinner } = require('nanospinner');
@@ -89,7 +94,7 @@ const SOURCE_ROOT = path.join(PACKAGE_ROOT, 'rcode');
  * detectIdeSignals, plus a row to runInstallWizard's multiselect — three
  * sites instead of ten.
  */
-const SUPPORTED_IDES = Object.freeze(['claude', 'cursor', 'gemini', 'vscode', 'antigravity', 'windsurf']);
+const SUPPORTED_IDES = Object.freeze(['claude', 'cursor', 'gemini', 'vscode', 'antigravity', 'windsurf', 'codex', 'grok']);
 
 /**
  * Resolve the stable on-disk location of this package so config.yaml
@@ -197,6 +202,9 @@ function parseArgs(argv) {
     silent: false,
     // noPrompt — skip all interactive prompts (used by postinstall auto-run)
     noPrompt: false,
+    // dry-run / list-files — preview paths that would be written, then exit
+    dryRun: false,
+    listFiles: false,
   };
   const positional = [];
   for (let i = 0; i < argv.length; i++) {
@@ -231,6 +239,8 @@ function parseArgs(argv) {
     else if (arg === '--global') opts.global = true;
     else if (arg === '--silent') opts.silent = true;
     else if (arg === '--no-prompt') opts.noPrompt = true;
+    else if (arg === '--dry-run') opts.dryRun = true;
+    else if (arg === '--list-files') opts.listFiles = true;
     else if (!arg.startsWith('--')) positional.push(arg);
   }
   if (positional[0]) {
@@ -242,7 +252,7 @@ function parseArgs(argv) {
   // project directory wrote rcode artifacts to that project, not to the user's
   // home where Claude Code reads global commands from.
   if (opts.global && !opts.targetProvided) {
-    opts.target = os.homedir();
+    opts.target = homedir();
   }
   // Issue #821/#832: pnpm workspace anchor.
   // When `pnpm add -D @hanzlaa/rcode` runs inside a workspace member,
@@ -372,7 +382,7 @@ function printInstallHeader(targetVersion) {
  * Returns a set like { claude: true, cursor: false, gemini: false }.
  */
 function detectIdeSignals(target) {
-  const signals = { claude: false, cursor: false, gemini: false, vscode: false, antigravity: false, windsurf: false };
+  const signals = { claude: false, cursor: false, gemini: false, vscode: false, antigravity: false, windsurf: false, codex: false };
   // 1. Project-local install dirs (strongest signal — they already use one)
   if (fs.existsSync(path.join(target, '.claude'))) signals.claude = true;
   if (fs.existsSync(path.join(target, '.cursor'))) signals.cursor = true;
@@ -381,7 +391,7 @@ function detectIdeSignals(target) {
   if (fs.existsSync(path.join(target, '.antigravity'))) signals.antigravity = true;
   if (fs.existsSync(path.join(target, '.windsurf'))) signals.windsurf = true;
   // 2. User-level config dirs
-  const home = os.homedir();
+  const home = homedir();
   if (fs.existsSync(path.join(home, '.claude'))) signals.claude = true;
   if (fs.existsSync(path.join(home, '.cursor'))) signals.cursor = true;
   if (fs.existsSync(path.join(home, '.config', 'Cursor'))) signals.cursor = true;
@@ -396,6 +406,7 @@ function detectIdeSignals(target) {
   if (process.env.CLAUDECODE === '1' || process.env.CLAUDE_CODE_ENTRYPOINT) signals.claude = true;
   if (process.env.VSCODE_PID || /vscode/i.test(process.env.TERM_PROGRAM || '')) signals.vscode = true;
   if (/windsurf/i.test(process.env.TERM_PROGRAM || '')) signals.windsurf = true;
+  if (process.env.CODEX_ENV || /codex/i.test(process.env.TERM_PROGRAM || '')) signals.codex = true;
   return signals;
 }
 
@@ -442,6 +453,7 @@ async function resolveIde(opts) {
     options: [
       { value: 'claude',     label: 'Claude Code',  hint: signals.claude ? '(detected)' : undefined },
       { value: 'cursor',     label: 'Cursor',       hint: signals.cursor ? '(detected)' : undefined },
+      { value: 'codex',      label: 'Codex (OpenAI CLI)', hint: signals.codex ? '(detected)' : '(uses AGENTS.md + workflow bridge)' },
       { value: 'gemini',     label: 'Gemini CLI',   hint: signals.gemini ? '(detected)' : '(beta — limited)' },
       { value: 'vscode',     label: 'VS Code',      hint: signals.vscode ? '(detected)' : '(via Continue / Copilot extensions)' },
       { value: 'antigravity', label: 'Antigravity', hint: '(experimental — installs to .antigravity/)' },
@@ -522,6 +534,8 @@ Options:
   --language <lang>  set communication_language (default: English)
   --mode <guided|yolo> default mode (default: guided)
   --ide <name>       target IDE (claude, cursor, gemini; default: claude)
+  --dry-run          preview what would be written; exit without writing any files
+  --list-files       alias for --dry-run
   --help             this text
 
 Installs (IDE-specific):
@@ -601,6 +615,33 @@ function getPathsForIde(ide, target) {
         referencesDir: path.join(target, '.rcode', 'references'),
         binDir: path.join(target, '.rcode', 'bin'),
       };
+    case 'codex':
+      // OpenAI Codex CLI reads AGENTS.md from the project root (written by the
+      // claude/vscode install paths). We install agent + command files to .claude/
+      // so multi-IDE installs share files, and the rcode workflow bridge gives
+      // Codex access to lifecycle workflows via `rcode workflow show <name>` (#883).
+      // NOTE: Codex surfaces native /slash commands ONLY from ~/.codex/prompts/*.md
+      // (home, startup-loaded) — installed separately by installNativeHomeSlashCommands()
+      // under the opt-in --global flag, since .claude/commands is invisible to Codex.
+      return {
+        agentsDir: path.join(target, '.claude', 'agents'),
+        commandsDir: path.join(target, '.claude', 'commands'),
+        workflowsDir: path.join(target, '.rcode', 'workflows'),
+        referencesDir: path.join(target, '.rcode', 'references'),
+        binDir: path.join(target, '.rcode', 'bin'),
+      };
+    case 'grok':
+      // Grok Build (xAI CLI) is Claude-Code-compatible: it reads slash commands
+      // from .claude/commands/*.md (project) and ~/.claude/commands (global), same
+      // as Claude Code. So grok maps to the identical .claude/ layout — verified
+      // live: `/rcode-add-phase` surfaces in grok from these dirs.
+      return {
+        agentsDir: path.join(target, '.claude', 'agents'),
+        commandsDir: path.join(target, '.claude', 'commands'),
+        workflowsDir: path.join(target, '.rcode', 'workflows'),
+        referencesDir: path.join(target, '.rcode', 'references'),
+        binDir: path.join(target, '.rcode', 'bin'),
+      };
     default:
       throw new Error(`Unknown IDE: ${ide}. Supported: ${SUPPORTED_IDES.join(', ')}`);
   }
@@ -1058,7 +1099,7 @@ function installSkills(packageRoot, target, options = {}) {
   // prefix, Claude Code reads from BOTH global and project, showing every
   // /rcode-* twice in the slash picker. Skip the project copy for any rcode-*
   // skill that already lives in the global skills dir.
-  const globalSkillsDir = path.join(os.homedir(), '.claude', 'skills');
+  const globalSkillsDir = path.join(homedir(), '.claude', 'skills');
   const globalRcodeSkills = (options.skipGlobalDuplicates && fs.existsSync(globalSkillsDir))
     ? new Set(fs.readdirSync(globalSkillsDir).filter(n => n.startsWith('rcode-')))
     : new Set();
@@ -1282,7 +1323,7 @@ function buildInstallPlan(ide = 'claude', target = process.cwd()) {
     const rel = path.relative(path.join(SOURCE_ROOT, 'commands'), f);
     const ext = ide === 'cursor' ? '.mdc' : '.md';
     const baseName = path.basename(f, '.md');
-    const outName = (ide === 'claude' || ide === 'vscode')
+    const outName = (ide === 'claude' || ide === 'vscode' || ide === 'grok')
       ? `rcode-${baseName}${ext}`
       : baseName + ext;
     plan.push({ src: f, rel: path.join(relCommands, path.dirname(rel), outName), ide, cursor: ide === 'cursor' });
@@ -1431,8 +1472,8 @@ function generateAgentManifest(plan, target) {
   // Also scan rcode/agents/ in SOURCE_ROOT as a last-resort fallback so the
   // manifest is never empty when the package itself ships agent definitions.
   const extraScans = [
-    path.join(os.homedir(), '.claude', 'agents'),
-    path.join(os.homedir(), '.rcode', 'agents'),
+    path.join(homedir(), '.claude', 'agents'),
+    path.join(homedir(), '.rcode', 'agents'),
   ];
   // Final fallback: scan the package source itself.
   try {
@@ -1880,6 +1921,125 @@ function acquireInstallLock(target) {
   return { ok: false, pid: 0, lockPath };
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Native home-dir slash-command install.
+//
+// Some agentic CLIs surface their `/slash` command menu ONLY from a fixed
+// home directory (not from project dirs the way Claude Code / Grok do):
+//   • Codex      → ~/.codex/prompts/<name>.md          (flat prompt files)
+//   • Antigravity→ ~/.gemini/antigravity/skills/<name>/SKILL.md (skill dirs)
+// For those tools the normal project install writes files the CLI never reads,
+// so `/rcode-*` never appears. This installs the commands in each CLI's NATIVE
+// format into its NATIVE home dir, gated behind the opt-in `--global` flag.
+//
+// IDEs that read project dirs (claude, grok, cursor, vscode, windsurf) are a
+// no-op here — they already work via getPathsForIde().
+//
+// Each tool's writer lives in its own helper; the dispatcher routes by ide.
+// SOURCE_ROOT/commands/*.md is the canonical command source for all writers.
+// ─────────────────────────────────────────────────────────────────────────────
+
+// Codex + Antigravity surface NO file-based slash commands (verified live),
+// but BOTH support a prompt-submit hook (UserPromptSubmit / UserPrompt) that
+// can inject context. We install a hook ROUTER (cli/rcode-slash-router.cjs)
+// into each, plus a home-dir copy of every command body the router reads.
+// See cli/rcode-slash-router.cjs for the runtime contract.
+
+// Shared: copy every command body to ~/.rcode/slash-commands/<name>.md and the
+// router script to ~/.rcode/bin/. A fixed home-dir location lets the hook read
+// commands regardless of the user's cwd. Idempotent (plain overwrite).
+function installSlashRouterCommands(opts) {
+  const home = homedir();
+  const cmdDestDir = path.join(home, '.rcode', 'slash-commands');
+  const binDestDir = path.join(home, '.rcode', 'bin');
+  ensureDir(cmdDestDir);
+  ensureDir(binDestDir);
+
+  const srcCmdDir = path.join(SOURCE_ROOT, 'commands');
+  let copied = 0;
+  for (const file of fs.readdirSync(srcCmdDir)) {
+    if (!file.endsWith('.md')) continue;
+    fs.copyFileSync(path.join(srcCmdDir, file), path.join(cmdDestDir, file));
+    copied++;
+  }
+
+  const routerSrc = path.join(PACKAGE_ROOT, 'cli', 'rcode-slash-router.cjs');
+  const routerDest = path.join(binDestDir, 'rcode-slash-router.cjs');
+  fs.copyFileSync(routerSrc, routerDest);
+
+  if (opts && opts.global !== 'silent') {
+    console.log('  ' + ok(`Slash-router: ${copied} command bodies → ~/.rcode/slash-commands/ + router → ~/.rcode/bin/`));
+  }
+  return routerDest;
+}
+
+// The absolute command a hook entry runs. Matched by substring for idempotency
+// and for removal on uninstall — keep the basename stable.
+function slashRouterHookCommand() {
+  return `node "${path.join(homedir(), '.rcode', 'bin', 'rcode-slash-router.cjs')}"`;
+}
+
+// Merge a prompt-submit hook entry into an existing CLI hooks JSON file without
+// disturbing any pre-existing entries (e.g. herdr's). `eventKey` is the hook
+// event name that CLI uses (codex: UserPromptSubmit, antigravity: UserPrompt).
+// Idempotent: re-running detects the router by command substring and no-ops.
+function mergeSlashRouterHook(jsonPath, eventKey, command, label) {
+  let root = {};
+  if (fs.existsSync(jsonPath)) {
+    try {
+      root = JSON.parse(fs.readFileSync(jsonPath, 'utf8')) || {};
+    } catch {
+      // Unparseable file — don't clobber the user's config; bail loudly.
+      console.log('  ' + warn(`${label}: ${jsonPath} is not valid JSON — skipped slash-router wiring.`));
+      return false;
+    }
+  }
+  if (!root.hooks || typeof root.hooks !== 'object') root.hooks = {};
+  if (!Array.isArray(root.hooks[eventKey])) root.hooks[eventKey] = [];
+
+  const already = root.hooks[eventKey].some(group =>
+    Array.isArray(group?.hooks) &&
+    group.hooks.some(h => typeof h?.command === 'string' && h.command.includes('rcode-slash-router.cjs')),
+  );
+  if (already) {
+    console.log('  ' + ok(`${label}: slash-router hook already present (idempotent).`));
+    return false;
+  }
+
+  root.hooks[eventKey].push({ hooks: [{ type: 'command', command, timeout: 10 }] });
+  ensureDir(path.dirname(jsonPath));
+  fs.writeFileSync(jsonPath, JSON.stringify(root, null, 2) + '\n');
+  console.log('  ' + ok(`${label}: wired slash-router into ${eventKey} hook (existing hooks preserved).`));
+  return true;
+}
+
+// Codex: ~/.codex/hooks.json, event UserPromptSubmit.
+function installCodexSlashRouterHook(opts) {
+  installSlashRouterCommands(opts);
+  const jsonPath = path.join(homedir(), '.codex', 'hooks.json');
+  mergeSlashRouterHook(jsonPath, 'UserPromptSubmit', slashRouterHookCommand(), 'Codex');
+}
+
+// Antigravity: ~/.gemini/antigravity/settings.json, event UserPrompt.
+function installAntigravitySlashRouterHook(opts) {
+  installSlashRouterCommands(opts);
+  const jsonPath = path.join(homedir(), '.gemini', 'antigravity', 'settings.json');
+  mergeSlashRouterHook(jsonPath, 'UserPrompt', slashRouterHookCommand(), 'Antigravity');
+}
+
+function installNativeHomeSlashCommands(opts) {
+  if (!opts || !opts.global) return;
+  const ides = Array.isArray(opts.ides) ? opts.ides : [opts.ide].filter(Boolean);
+  for (const ide of ides) {
+    switch (ide) {
+      case 'codex': installCodexSlashRouterHook(opts); break;
+      case 'antigravity': installAntigravitySlashRouterHook(opts); break;
+      default:
+        break;
+    }
+  }
+}
+
 async function installInner(opts) {
   const pkgVersion = readPackageVersion();
 
@@ -1929,10 +2089,12 @@ async function installInner(opts) {
     console.error('  Currently supported:');
     console.error('    claude       — Claude Code native (recommended)');
     console.error('    cursor       — Cursor IDE');
-    console.error('    gemini       — Gemini CLI');
+    console.error('    codex        — Codex CLI');
+    console.error('    gemini       — Gemini CLI (planned — not yet implemented)');
     console.error('    vscode       — VS Code (with Claude Code / Continue / Copilot extension)');
     console.error('    windsurf     — Windsurf (Codeium)');
     console.error('    antigravity  — Antigravity (experimental)');
+    console.error('    grok         — Grok Build (xAI CLI, Claude-Code-compatible)');
     console.error('');
     console.error('  Tracked for future:');
     console.error('    jetbrains    — IntelliJ / PyCharm');
@@ -1946,6 +2108,11 @@ async function installInner(opts) {
     console.log('  ' + dim('VS Code → installing to .claude/ paths (read by Claude Code / Continue / Copilot extensions).'));
   }
 
+  // Codex installs to .claude/ and AGENTS.md; lifecycle via rcode workflow bridge.
+  if (opts.ides.includes('codex')) {
+    console.log('  ' + dim('Codex → installing to .claude/ paths + AGENTS.md. Use `rcode workflow show <name>` to feed workflows to Codex.'));
+  }
+
   // Gemini IDE support deferred
   if (opts.ides.includes('gemini')) {
     console.log(`\n⚠️  Gemini CLI install not yet implemented\n`);
@@ -1994,6 +2161,15 @@ async function installInner(opts) {
     console.log(`  Modules: ${opts.modules.join(', ')}`);
   }
 
+  // Dry run / list-files — list paths that would be written and exit without writing
+  if (opts.dryRun || opts.listFiles) {
+    console.log('DRY RUN: the following paths would be written:');
+    for (const entry of plan) {
+      console.log('  + ' + entry.rel);
+    }
+    return 0;
+  }
+
   // Force-overwrite backup — closes #381. Without this, customized
   // .claude/agents/rcode-*.md and similar package-managed files were silently
   // clobbered with no recovery path. Now every --force-overwrite run creates
@@ -2262,6 +2438,16 @@ async function installInner(opts) {
     } catch { /* non-fatal */ }
     console.log('');
     console.log(`  ${dim(`${skillsInstalled} skills installed globally`)}`);
+
+    // Native home-dir slash commands for CLIs that can't surface file-based
+    // /commands (codex, antigravity) but DO support a prompt-submit hook.
+    // This MUST run inside the --global block: the global path returns here,
+    // before the non-global call site below. Gated on opts.global inside.
+    try {
+      installNativeHomeSlashCommands(opts);
+    } catch (err) {
+      process.stderr.write(pc.yellow(`WARNING: native slash-command install skipped: ${err?.message || err}`) + '\n');
+    }
     return 0;
   }
 
@@ -2269,9 +2455,9 @@ async function installInner(opts) {
   // skip writing agents/commands to the project's .claude/ directory. Without this,
   // running `npx rcode install` in the home dir AND then in a project creates two sets
   // of identical files — Claude Code shows both as duplicate slash commands.
-  const globalClaudeCommands = path.join(os.homedir(), '.claude', 'commands');
+  const globalClaudeCommands = path.join(homedir(), '.claude', 'commands');
   const projectClaudeCommands = path.join(opts.target, '.claude', 'commands');
-  const isProjectInstall = opts.target !== os.homedir();
+  const isProjectInstall = opts.target !== homedir();
   // Run dedup even when force:true — only forceOverwrite skips it.
   if (isProjectInstall && !opts.forceOverwrite) {
     try {
@@ -2453,7 +2639,7 @@ async function installInner(opts) {
   }
 
   // ~/.rcode/agents/ global agents directory
-  const globalAgentsDir = path.join(os.homedir(), '.rcode', 'agents');
+  const globalAgentsDir = path.join(homedir(), '.rcode', 'agents');
   ensureDir(globalAgentsDir);
 
   // Issue #702: files-manifest.csv used to be written here, BEFORE
@@ -2638,9 +2824,9 @@ async function installInner(opts) {
     // the project skills folder may have only sidebar stubs while ~/.claude/
     // has the real skills — health check should see those.
     if (agentCount === 0 || commandCount === 0 || skillsInstalled < 20) {
-      const homeAgents = path.join(os.homedir(), '.claude/agents');
-      const homeCommands = path.join(os.homedir(), '.claude/commands');
-      const homeSkills = path.join(os.homedir(), '.claude/skills');
+      const homeAgents = path.join(homedir(), '.claude/agents');
+      const homeCommands = path.join(homedir(), '.claude/commands');
+      const homeSkills = path.join(homedir(), '.claude/skills');
       if (agentCount === 0 && fs.existsSync(homeAgents)) {
         // #669 — count both rcode-* and rcode-* prefixes; missing rcode-
         // branch produced "Agents: 0" alongside "Skills: 120".
@@ -2667,6 +2853,32 @@ async function installInner(opts) {
     console.error('[install] installInner: failed to count installed agents/commands:', err?.message || err);
   }
 
+  // Duplicate-namespace detection: warn when both rcode-* and rihal-* entries exist.
+  // Having both doubles the roster size with near-identical content.
+  try {
+    const skillsDir = path.join(opts.target, '.rcode', 'skills');
+    const claudeCommandsDir = path.join(opts.target, '.claude', 'commands');
+    const dirsToCheck = [skillsDir, claudeCommandsDir];
+    let hasRcode = false, hasRihal = false;
+    for (const dir of dirsToCheck) {
+      if (!fs.existsSync(dir)) continue;
+      const entries = fs.readdirSync(dir);
+      if (entries.some(e => e.startsWith('rcode-'))) hasRcode = true;
+      if (entries.some(e => e.startsWith('rihal-'))) hasRihal = true;
+    }
+    if (hasRcode && hasRihal) {
+      process.stderr.write(pc.yellow('WARNING: rcode-* and rihal-* namespaces both detected — consider removing one to reduce roster size.') + '\n');
+    }
+  } catch { /* non-fatal */ }
+
+  // Native home-dir slash commands for CLIs that ONLY surface /commands from
+  // their own home dir (not project dirs). Opt-in via --global. See the fn def.
+  try {
+    installNativeHomeSlashCommands(opts);
+  } catch (err) {
+    process.stderr.write(pc.yellow(`WARNING: native slash-command install skipped: ${err?.message || err}`) + '\n');
+  }
+
   const version = readPackageVersion();
   console.log('');
   console.log(`  ${bold('Version:')}   ${pc.cyan('@hanzlaa/rcode@' + version)}`);
@@ -2915,6 +3127,7 @@ async function runInstallWizard(opts) {
     options: [
       { value: 'claude',  label: 'Claude Code',  hint: 'recommended' },
       { value: 'cursor',  label: 'Cursor' },
+      { value: 'codex',   label: 'Codex (OpenAI CLI)', hint: 'AGENTS.md + workflow bridge' },
       { value: 'gemini',  label: 'Gemini CLI',   hint: 'coming soon' },
       { value: 'vscode',  label: 'VS Code',      hint: 'via Continue / Copilot extensions' },
       { value: 'antigravity', label: 'Antigravity', hint: 'experimental' },
@@ -3016,3 +3229,8 @@ module.exports.install = install;
 module.exports.SUPPORTED_IDES = SUPPORTED_IDES;
 module.exports.migrateVscodeCommandsLayout = migrateVscodeCommandsLayout;
 module.exports.getPathsForIde = getPathsForIde;
+// Slash-router (hook-based /rcode-* support for codex + antigravity).
+module.exports.installSlashRouterCommands = installSlashRouterCommands;
+module.exports.installCodexSlashRouterHook = installCodexSlashRouterHook;
+module.exports.installAntigravitySlashRouterHook = installAntigravitySlashRouterHook;
+module.exports.installNativeHomeSlashCommands = installNativeHomeSlashCommands;

package/cli/lib/config.cjs

@@ -18,9 +18,11 @@
  */
 
 const fs = require('fs');
-const os = require('os');
 const path = require('path');
 const { writeJsonAtomic } = require('./fsutil.cjs');
+// HOME-aware home resolution (#889) — os.homedir() ignores a stubbed HOME
+// on Windows, which broke user-level defaults isolation in tests.
+const { homedir } = require('./homedir.cjs');
 
 // ---------- Schema ----------
 
@@ -102,7 +104,7 @@ const VALID_COMMUNICATION_MODES = new Set(['guided', 'yolo']);
 // ---------- Paths ----------
 
 function userLevelPath() {
-  return path.join(os.homedir(), '.rcode', 'defaults.json');
+  return path.join(homedir(), '.rcode', 'defaults.json');
 }
 
 function projectLevelPath(cwd) {

package/cli/lib/fsutil.cjs

@@ -115,8 +115,19 @@ function safeRmSync(targetPath, projectRoot) {
     }
   }
 
-  // Real path must stay inside the project root.
-  const root = path.resolve(projectRoot);
+  // Real path must stay inside the project root. The root must be
+  // realpathed too: on macOS os.tmpdir() lives behind a symlink
+  // (/tmp → /private/tmp, /var → /private/var), so comparing a realpathed
+  // target against a merely-resolved root misreports anything under /tmp
+  // as outside-root.
+  let root;
+  try {
+    root = fs.realpathSync(projectRoot);
+  } catch {
+    // Root missing/unreadable — fall back to a lexical resolve; the
+    // containment check below then fails closed for an existing target.
+    root = path.resolve(projectRoot);
+  }
   let resolved;
   try {
     resolved = fs.realpathSync(targetPath);

package/cli/lib/homedir.cjs

@@ -0,0 +1,21 @@
+/**
+ * cli/lib/homedir.cjs — user home directory resolution (#889).
+ *
+ * process.env.HOME wins over os.homedir() so a single env var redirects
+ * every home-relative read/write on EVERY platform. os.homedir() ignores
+ * HOME on Windows (it reads USERPROFILE), which made HOME-stubbed tests
+ * silently escape to the real profile dir on Windows CI — installs leaked
+ * ~/.codex / ~/.gemini / ~/.rcode into the runner's real home and broke
+ * unrelated tests. Honoring HOME also matches git/npm behavior on Windows
+ * (git-bash sets HOME), so real users get consistent paths across shells.
+ */
+
+'use strict';
+
+const os = require('os');
+
+function homedir() {
+  return process.env.HOME || os.homedir();
+}
+
+module.exports = { homedir };

package/cli/lib/schemas.cjs

@@ -35,9 +35,14 @@ const { z } = require('zod');
  * @returns {{ frontmatter: object, body: string }}
  */
 function parseFrontmatter(text) {
-  if (typeof text !== 'string' || !text.startsWith('---\n')) {
+  if (typeof text !== 'string') {
     return { frontmatter: {}, body: text || '' };
   }
+  // CRLF tolerance (#889): Windows checkouts/user files may use \r\n.
+  text = text.replace(/\r\n/g, '\n');
+  if (!text.startsWith('---\n')) {
+    return { frontmatter: {}, body: text };
+  }
   const end = text.indexOf('\n---\n', 4);
   if (end === -1) return { frontmatter: {}, body: text };
   const block = text.slice(4, end);