@hanzlaa/rcode 4.1.0 → 4.1.2

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

@@ -33,6 +33,11 @@ const COMMANDS = {
   team: require('./team'),
   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'),
@@ -68,6 +73,25 @@ Usage:
   context        Memory bank freshness (--check | --refresh | --install-hook)
   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
+  workflow show create-prd     → write / update the PRD
+  workflow show discuss-phase  → gather phase context
+  workflow show plan           → create a SPRINT plan
+  workflow show execute-sprint → execute a SPRINT
+  workflow show verify-phase   → verify phase completion
+  workflow show retrospective  → retrospective + velocity
+  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
   team           List the team roster
   digest         Print compact digests for all agents
@@ -75,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
@@ -95,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

@@ -89,7 +89,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']);
 
 /**
  * Resolve the stable on-disk location of this package so config.yaml
@@ -197,6 +197,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 +234,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]) {
@@ -372,7 +377,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;
@@ -396,6 +401,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 +448,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 +529,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 +610,18 @@ 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).
+      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(', ')}`);
   }
@@ -847,6 +868,7 @@ function ensureRcodeGitignore(target, options = {}) {
     '.rcode/brain/best-practices/',
     '',
     '# Runtime noise',
+    'node_modules/',
     '.rcode/state.json.lock',
     '.planning/debug/',
     '.planning/_backup/',
@@ -1928,7 +1950,8 @@ 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)');
@@ -1945,6 +1968,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`);
@@ -1993,6 +2021,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
@@ -2666,6 +2703,24 @@ 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 */ }
+
   const version = readPackageVersion();
   console.log('');
   console.log(`  ${bold('Version:')}   ${pc.cyan('@hanzlaa/rcode@' + version)}`);
@@ -2914,6 +2969,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' },

package/cli/workflow.js

@@ -0,0 +1,99 @@
+/**
+ * rcode workflow [list|show <name>] — lifecycle bridge for non-Claude runtimes.
+ *
+ * Codex, Copilot, Grok, and other non-Claude agents cannot invoke slash
+ * commands directly. This command exposes rcode's lifecycle workflows as
+ * readable markdown so any agent can follow the same process:
+ *
+ *   rcode workflow list               → list available workflow names
+ *   rcode workflow show <name>        → print workflow markdown to stdout
+ *   rcode workflow show plan          → print the plan workflow
+ *
+ * An agent consuming `rcode workflow show <name>` should treat the output
+ * as its operative instructions for that lifecycle step (the same content
+ * Claude Code loads when a slash command fires).
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Canonical lifecycle order shown in help output
+const LIFECYCLE_ORDER = [
+  'new-project',
+  'create-prd',
+  'discuss-phase',
+  'plan',
+  'execute-sprint',
+  'verify-phase',
+  'retrospective',
+  'ship',
+];
+
+module.exports = function workflow(args, { packageRoot }) {
+  const workflowsDir = path.join(packageRoot, 'rcode', 'workflows');
+
+  const subcommand = args[0];
+
+  if (!subcommand || subcommand === 'list' || subcommand === '--list') {
+    return listWorkflows(workflowsDir);
+  }
+
+  if (subcommand === 'show' || subcommand === 'get' || subcommand === 'run') {
+    const name = args[1];
+    if (!name) {
+      console.error('Usage: rcode workflow show <name>');
+      console.error('       rcode workflow list');
+      process.exit(1);
+    }
+    return showWorkflow(workflowsDir, name);
+  }
+
+  // Treat bare `rcode workflow <name>` as show
+  return showWorkflow(workflowsDir, subcommand);
+};
+
+function listWorkflows(workflowsDir) {
+  const all = fs.readdirSync(workflowsDir)
+    .filter(f => f.endsWith('.md'))
+    .map(f => f.replace(/\.md$/, ''))
+    .sort();
+
+  // Show lifecycle commands first, then remaining alphabetically
+  const lifecycle = LIFECYCLE_ORDER.filter(n => all.includes(n));
+  const rest = all.filter(n => !LIFECYCLE_ORDER.includes(n));
+
+  console.log('🕌 rcode lifecycle workflows\n');
+  console.log('Core lifecycle (in order):');
+  lifecycle.forEach(n => console.log(`  rcode workflow show ${n}`));
+  if (rest.length) {
+    console.log('\nOther workflows:');
+    rest.forEach(n => console.log(`  rcode workflow show ${n}`));
+  }
+  console.log('\nUsage: rcode workflow show <name>  — print the full workflow instructions');
+}
+
+function showWorkflow(workflowsDir, name) {
+  // Normalise: strip rcode- prefix so both `plan` and `rcode-plan` resolve (#883)
+  const bare = name.startsWith('rcode-') ? name.slice('rcode-'.length) : name;
+  const candidates = [
+    path.join(workflowsDir, `${bare}.md`),
+    path.join(workflowsDir, `${name}.md`),
+  ];
+
+  for (const p of candidates) {
+    if (fs.existsSync(p)) {
+      process.stdout.write(fs.readFileSync(p, 'utf8'));
+      return;
+    }
+  }
+
+  // Not found — list available and exit non-zero
+  const available = fs.readdirSync(workflowsDir)
+    .filter(f => f.endsWith('.md'))
+    .map(f => f.replace(/\.md$/, ''))
+    .sort()
+    .join(', ');
+  console.error(`Error: workflow '${name}' not found.`);
+  console.error(`Available: ${available}`);
+  process.exit(1);
+}