@hanzlaa/rcode 4.0.0 → 4.1.1

package/AGENTS.md

@@ -48,7 +48,7 @@ If a user says "just keep going" or "don't stop until done", that authorization
 
 ## Naming & Branding (per `BRAND.md`)
 
-- **Skill names** in frontmatter: `rcode-<verb>-<noun>` for legacy skills; new branded skills use `rcode-<verb>-<noun>` ONLY in slash command surface (`/rcode:<name>`); folder names stay `rcode-*` because `cli/install.js` hardcodes that prefix.
+- **Skill names** in frontmatter: `rcode-<verb>-<noun>` for legacy skills; new branded skills use `rcode-<verb>-<noun>` ONLY in slash command surface (`/rcode-<name>`); folder names stay `rcode-*` because `cli/install.js` hardcodes that prefix.
 - **Persona IDs** in `team.yaml` stay `rcode-<name>` (dashboard scanner reads them by id; renaming breaks rendering).
 - **Persona display names** keep Arabic alongside Latin: `Sadiq (صادق)`, `Dalil (دليل)`, etc.
 - **Concept primitives** (Memory Bank, Distillate, Majlis, Diwan) are named tooling — capitalised, used consistently in user-facing copy.

package/README.md

@@ -13,7 +13,7 @@ pnpm dlx @hanzlaa/rcode install
 [![CI](https://github.com/hanzlahabib/rihal-code/actions/workflows/test.yml/badge.svg)](https://github.com/hanzlahabib/rihal-code/actions/workflows/test.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-Status: `@hanzlaa/rcode` v4.0.0 on npm. 339 automated tests across 58 files, 45 agents, 116 commands, 86 skills. Actively dogfooded on real projects every week.
+Status: `@hanzlaa/rcode` v4.0.0 on npm. 457 automated tests across 63 files, 45 agents, 116 commands, 87 skills. Actively dogfooded on real projects every week.
 
 ---
 
@@ -42,7 +42,7 @@ Three layers, specialised for software delivery:
 | Layer | What lives here | Example |
 |-------|-----------------|---------|
 | **Memory** | `.rcode/memory/` — git-tracked markdown, lossless distillates | "We chose Postgres over Mongo because of JSON-B + RLS — see ADR-007" |
-| **Skills** | `rcode/skills/` — 85 phrase-activated playbooks | `rcode-sprint-checker` validates file/symbol refs before execute |
+| **Skills** | `rcode/skills/` — 87 phrase-activated playbooks | `rcode-sprint-checker` validates file/symbol refs before execute |
 | **Workflows** | `rcode/workflows/` — orchestrated multi-step paths | `/rcode-plan` runs research → planner → checker → confirm |
 
 Single agent navigates the structure. No LangChain, no AutoGen, no orchestrator process. Just folders the model can read.

package/cli/doctor.js

@@ -52,13 +52,30 @@ function findAgentFiles(dir) {
     .map((e) => path.join(dir, e.name));
 }
 
+// Negative-boundary signal — an explicit statement of what a skill does NOT do.
+// Mirrors the same constant in cli/lib/schemas.cjs so both checks stay in sync.
+const NEGATIVE_BOUNDARY_RE = /not for|do not|does not|don't|never\b|audit-only|negative/i;
+
 function checkCompliance(filePath) {
   const content = fs.readFileSync(filePath, 'utf8');
+  const { frontmatter, body } = parseFrontmatter(content);
   const missing = [];
   if (!/^name:/m.test(content)) missing.push('name');
   if (!/^description:/m.test(content)) missing.push('description');
+  if (!/^## Overview/m.test(content)) missing.push('Overview section');
   if (!/^## Output Format/m.test(content)) missing.push('Output Format');
   if (!/^## Examples/m.test(content)) missing.push('Examples');
+
+  // Negative-boundary clause (component 1 of the 5-component standard).
+  // Parse the frontmatter description so folded-block YAML is normalized
+  // before the regex runs — "Do\n  NOT" becomes "Do NOT" after normalization.
+  const desc = typeof frontmatter.description === 'string' ? frontmatter.description : '';
+  const hasBoundary =
+    NEGATIVE_BOUNDARY_RE.test(desc) ||
+    /##[^\n]*\bnot\b/i.test(body) ||
+    /\bdo not (use|include)\b/i.test(body);
+  if (!hasBoundary) missing.push('negative-boundary clause');
+
   return missing;
 }
 

package/cli/github-sync.js

@@ -481,8 +481,9 @@ async function main(args) {
       console.error(`   Check the filter value or run without filters to see available ids.`);
       process.exit(1);
     }
-    console.error(`❌ No phases found in .rcode/phases/.`);
-    process.exit(1);
+    console.log(`ℹ  No phases found in .rcode/phases/ — nothing to sync.`);
+    console.log(`   Run 'rcode init' or create a phase to get started.`);
+    process.exit(0);
   }
 
   console.log(`   ✓ Phases found: ${phases.length}`);

package/cli/index.js

@@ -33,6 +33,7 @@ const COMMANDS = {
   team: require('./team'),
   agent: require('./agent'),
   doctor: require('./doctor'),
+  workflow: require('./workflow'),  // lifecycle bridge for non-Claude runtimes
   'set-profile': require('./set-profile'),
   'set-mode': require('./set-mode'),
   config: require('./config'),
@@ -68,6 +69,21 @@ 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)
+  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 workflow show plan | codex run -
+
 👥 TEAM
   team           List the team roster
   digest         Print compact digests for all agents

package/cli/install.js

@@ -847,6 +847,7 @@ function ensureRcodeGitignore(target, options = {}) {
     '.rcode/brain/best-practices/',
     '',
     '# Runtime noise',
+    'node_modules/',
     '.rcode/state.json.lock',
     '.planning/debug/',
     '.planning/_backup/',

package/cli/lib/manifest.cjs

@@ -47,12 +47,25 @@ function readPackageManifest(packageRoot) {
   // Mirror installSkills() walkForSkills: recurse into action bucket dirs
   // (1-analysis, 2-plan, etc.) until a dir with SKILL.md is found, then add
   // the dir name as installed. Bucket dirs themselves are never installed.
+  // Issue #873: skills with `internal: true` in frontmatter are installed to
+  // .rcode/skills/ (not .claude/skills/), so omit them from manifest.actions
+  // to avoid false drift reports.
+  function isInternalSkill(skillDir) {
+    try {
+      const text = fs.readFileSync(path.join(skillDir, 'SKILL.md'), 'utf8');
+      return /^internal:\s*true\s*$/m.test(text);
+    } catch {
+      return false;
+    }
+  }
+
   function walkActions(dir) {
     if (!fs.existsSync(dir)) return;
     for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
       if (!entry.isDirectory()) continue;
       const full = path.join(dir, entry.name);
       if (fs.existsSync(path.join(full, 'SKILL.md'))) {
+        if (isInternalSkill(full)) continue; // internal → .rcode/skills/, not .claude/skills/
         // Use the name as it lands in .claude/skills/ (installSkills prefixes
         // non-rcode- dirs with 'rcode-', but all current skills already have it)
         const installedName = entry.name.startsWith('rcode-')

package/cli/set-mode.js

@@ -51,6 +51,16 @@ module.exports = function setMode(args) {
 
   const requested = args[0];
 
+  if (requested === '--help' || requested === '-h') {
+    console.log(`Usage: rcode set-mode [<mode>]`);
+    console.log();
+    console.log(`  rcode set-mode               show current mode + explanation`);
+    console.log(`  rcode set-mode <mode>        switch to mode <mode>`);
+    console.log();
+    console.log(`Available modes: ${[...VALID_COMMUNICATION_MODES].join(', ')}`);
+    process.exit(0);
+  }
+
   if (!requested) {
     // Show current + available modes
     const config = loadConfig(cwd);

package/cli/set-profile.js

@@ -37,6 +37,16 @@ module.exports = function setProfile(args) {
   const requested = args[0];
   const available = listProfiles();
 
+  if (requested === '--help' || requested === '-h') {
+    console.log(`Usage: rcode set-profile [<name>]`);
+    console.log();
+    console.log(`  rcode set-profile             show current profile + available options`);
+    console.log(`  rcode set-profile <name>      switch to profile <name>`);
+    console.log();
+    console.log(`Available profiles: ${available.join(', ')}`);
+    process.exit(0);
+  }
+
   if (!requested) {
     // Show current profile + available options
     const current = getProjectProfile(cwd);

package/cli/uninstall.js

@@ -87,6 +87,47 @@ function stripRcodeGitignoreBlock(text) {
     .replace(/\n{3,}/g, '\n\n');
 }
 
+/**
+ * Strip the rcode-managed block from .git/hooks/pre-commit.
+ * Removes the file entirely when only the shebang + rcode block remain.
+ * Returns 'removed' | 'stripped' | 'unchanged' | 'skipped'.
+ */
+function cleanRcodePreCommitHook(cwd) {
+  const hookPath = path.join(cwd, '.git', 'hooks', 'pre-commit');
+  if (!fs.existsSync(hookPath)) return 'skipped';
+
+  const BEGIN = '# ===== rcode-managed pre-commit block =====';
+  const END   = '# ===== end rcode pre-commit block =====';
+
+  let content;
+  try { content = fs.readFileSync(hookPath, 'utf8'); } catch { return 'skipped'; }
+
+  if (!content.includes(BEGIN)) return 'unchanged';
+
+  const startIdx = content.indexOf(BEGIN);
+  const endIdx = content.indexOf(END, startIdx);
+  if (endIdx < 0) return 'unchanged'; // malformed — leave it
+
+  // Trim the newline that precedes BEGIN and the newline that follows END
+  let lo = startIdx;
+  if (lo > 0 && content[lo - 1] === '\n') lo--;
+  let hi = endIdx + END.length;
+  if (hi < content.length && content[hi] === '\n') hi++;
+
+  const stripped = content.slice(0, lo) + content.slice(hi);
+
+  // If only a shebang (or blank) remains, remove the whole file
+  const remnant = stripped.trim();
+  if (remnant === '' || remnant === '#!/bin/sh' || remnant === '#!/bin/bash') {
+    try { fs.unlinkSync(hookPath); return 'removed'; } catch { return 'skipped'; }
+  }
+
+  try {
+    writeFileAtomic(hookPath, stripped, { mode: 0o755 });
+    return 'stripped';
+  } catch { return 'skipped'; }
+}
+
 /**
  * Walk a directory and remove all files/subdirs whose name matches a predicate.
  * Returns the number of entries removed. Always skips local overrides (#382).
@@ -148,7 +189,7 @@ function cleanupEmptyDirs(cwd, relPaths) {
  */
 function buildPlan(cwd, editors) {
   const plan = {
-    claude: { skills: [], commands: [], agents: [] },
+    claude: { skills: [], commands: [], agents: [], agentsRulesDir: false },
     cursor: [],
     windsurf: [],
     antigravity: [],
@@ -194,6 +235,10 @@ function buildPlan(cwd, editors) {
         .readdirSync(agentsDir)
         .filter((name) => name.startsWith('rcode-') && name.endsWith('.md'));
     }
+    // Installer copies rcode/agents/rules/ tree → .claude/agents/rules/ (#876)
+    if (fs.existsSync(path.join(cwd, '.claude/agents/rules'))) {
+      plan.claude.agentsRulesDir = true;
+    }
   }
 
   if (editors.includes('cursor')) {
@@ -201,7 +246,8 @@ function buildPlan(cwd, editors) {
     if (fs.existsSync(cursorDir)) {
       plan.cursor = fs
         .readdirSync(cursorDir)
-        .filter((name) => name.startsWith('rcode-') || name === 'rcode.mdc' || name === 'rcode-method.mdc');
+        // 'rcode' matches the .cursor/rules/rcode/ subdir installed by the cursor IDE path (#876)
+        .filter((name) => name.startsWith('rcode-') || name === 'rcode.mdc' || name === 'rcode-method.mdc' || name === 'rcode');
     }
   }
 
@@ -331,6 +377,9 @@ function planToPathList(plan, cwd, options = {}) {
   for (const name of plan.claude.agents) {
     paths.push(path.join('.claude/agents', name));
   }
+  if (plan.claude.agentsRulesDir) {
+    paths.push('.claude/agents/rules');
+  }
   for (const name of plan.cursor) {
     paths.push(path.join('.cursor/rules', name));
   }
@@ -650,6 +699,17 @@ async function runUninstall(args) {
     removed += nAgents;
     if (nAgents > 0) console.log(`   ✓ removed ${nAgents} Claude agents`);
 
+    // .claude/agents/rules/ — installed by the agent-rules sub-tree (#876)
+    if (plan.claude.agentsRulesDir) {
+      const rulesDir = path.join(cwd, '.claude/agents/rules');
+      const r = safeRmSync(rulesDir, path.resolve(cwd));
+      if (r.ok && r.reason !== 'missing') {
+        console.log(`   ✓ removed .claude/agents/rules/ (agent reference rules)`);
+      } else if (r.reason === 'outside-root') {
+        console.log(`   ⚠ refused to remove .claude/agents/rules/ — symlink resolves outside project root`);
+      }
+    }
+
     // Clean up now-empty .claude/commands and .claude/agents dirs
     try {
       if (fs.existsSync(path.join(cwd, '.claude/commands')) && fs.readdirSync(path.join(cwd, '.claude/commands')).length === 0) {
@@ -664,7 +724,7 @@ async function runUninstall(args) {
   if (editors.includes('cursor')) {
     const cursorDir = path.join(cwd, '.cursor/rules');
     const n = removeMatching(cursorDir, (name) =>
-      name.startsWith('rcode-') || name === 'rcode.mdc' || name === 'rcode-method.mdc',
+      name.startsWith('rcode-') || name === 'rcode.mdc' || name === 'rcode-method.mdc' || name === 'rcode',
     );
     removed += n;
     if (n > 0) console.log(`   ✓ removed ${n} Cursor rules`);
@@ -719,6 +779,29 @@ async function runUninstall(args) {
     }
   }
 
+  // Strip the rcode block from .gitignore — always, not just on --purge (#876)
+  const gitignorePath = path.join(cwd, '.gitignore');
+  if (fs.existsSync(gitignorePath)) {
+    try {
+      const before = fs.readFileSync(gitignorePath, 'utf8');
+      const after = stripRcodeGitignoreBlock(before);
+      if (after !== before) {
+        fs.writeFileSync(gitignorePath, after);
+        console.log(`   ✓ stripped rcode block from .gitignore`);
+      }
+    } catch (err) {
+      console.log(`   ⚠ could not strip .gitignore block: ${err.message}`);
+    }
+  }
+
+  // Remove .git/hooks/pre-commit rcode block (or the whole file if rcode-only) (#876)
+  const hookResult = cleanRcodePreCommitHook(cwd);
+  if (hookResult === 'removed') {
+    console.log(`   ✓ removed .git/hooks/pre-commit (was rcode-only)`);
+  } else if (hookResult === 'stripped') {
+    console.log(`   ✓ stripped rcode block from .git/hooks/pre-commit`);
+  }
+
   // Cleanup empty editor directories left behind after removing rcode-*
   // entries. Only removes dirs that are COMPLETELY empty — never touches
   // user content. Order matters: innermost first so each parent gets a
@@ -784,7 +867,7 @@ async function runUninstall(args) {
     }
   }
 
-  // --purge: also wipe .planning/ artifacts and the rcode .gitignore block.
+  // --purge: also wipe .planning/ artifacts (user project data beyond .rcode/).
   // Without this, "uninstall + reinstall" carries forward stale phases /
   // sprints / SUMMARY files even after .rcode/ is gone.
   if (opts.purge) {
@@ -799,36 +882,6 @@ async function runUninstall(args) {
         console.log(`   ⚠ could not remove .planning/: ${r.reason}`);
       }
     }
-
-    // Strip the rcode-managed block from .gitignore. The installer writes
-    // a fenced block; we remove it cleanly without touching user lines.
-    //
-    // Issue #684: previous regex `/\n?# rcode[\s\S]*?(?=\n\n|\n$|$)/g` was a
-    // footgun — it matched ANY user line starting with "# rcode" (e.g.
-    // "# rcode notes", "# rcode is great") and greedily consumed everything
-    // up to the next blank line, silently nuking user content.
-    //
-    // Three shapes have ever shipped:
-    //   1. Current (install.js:653-654): "# ===== rcode-managed gitignore block ... =====" ... "# ===== end rcode-managed gitignore block ====="
-    //   2. Old fenced markers: "# >>> rcode >>>" ... "# <<< rcode <<<"
-    //   3. Hypothetical legacy single-line "# rcode" — never actually
-    //      committed by any installer version we can find. Removed.
-    //
-    // Both kept patterns require BOTH sentinel markers to be present —
-    // user content with "# rcode" prefix is now safe.
-    const gitignorePath = path.join(cwd, '.gitignore');
-    if (fs.existsSync(gitignorePath)) {
-      try {
-        const before = fs.readFileSync(gitignorePath, 'utf8');
-        const stripped = stripRcodeGitignoreBlock(before);
-        if (stripped !== before) {
-          fs.writeFileSync(gitignorePath, stripped);
-          console.log(`   ✓ stripped rcode block from .gitignore (--purge)`);
-        }
-      } catch (err) {
-        console.log(`   ⚠ could not strip .gitignore block: ${err.message}`);
-      }
-    }
   }
 
   console.log(`\n✅ Uninstall complete. Removed ${removed} files.`);
@@ -836,12 +889,20 @@ async function runUninstall(args) {
     console.log(`   Backup: ${backup.path} (restore with: tar -xzf ${backup.path})`);
   }
 
-  // Hint about the purge flag if the user kept state — closes the user's
-  // most common confusion: "I uninstalled but /rcode-init still says configured."
-  if (plan.stateDir && fs.existsSync(path.join(cwd, '.rcode'))) {
+  // Notice about what was intentionally preserved (#876 — never delete user data silently)
+  const rcodeStillExists = plan.stateDir && fs.existsSync(path.join(cwd, '.rcode'));
+  const planningStillExists = !opts.purge && fs.existsSync(path.join(cwd, '.planning'));
+  if (rcodeStillExists || planningStillExists) {
     console.log();
-    console.log(`ℹ  .rcode/ state was preserved. /rcode-init will detect this on reinstall.`);
-    console.log(`   For a fully clean slate next time, use: rcode uninstall --purge`);
+    console.log(`ℹ  Preserved (your project data — not removed by default):`);
+    if (rcodeStillExists) {
+      console.log(`      .rcode/     phases, decisions, progress, config`);
+      console.log(`                  /rcode-init will detect this on reinstall`);
+    }
+    if (planningStillExists) {
+      console.log(`      .planning/  planning scaffolds (ROADMAP, STATE, PROJECT)`);
+    }
+    console.log(`   To remove these on next uninstall: rcode uninstall --purge`);
   }
 
   // IDE cache reload hint — Claude Code caches the slash-command list in memory.

package/cli/workflow.js

@@ -0,0 +1,97 @@
+/**
+ * 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) {
+  const candidates = [
+    path.join(workflowsDir, `${name}.md`),
+    path.join(workflowsDir, `rcode-${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);
+}