@hanzlaa/rcode 2.7.0 → 2.7.2

package/cli/install.js

@@ -1025,12 +1025,18 @@ function sweepStaleInstalledFiles(target, newPlan) {
   const newRelsSet = new Set(newPlan.map(e => e.rel.split(path.sep).join('/')));
   // Safety — never sweep these, even if they somehow landed in the manifest.
   const neverSweep = /^(\.rihal\/config\.yaml|\.rihal\/state\.json|\.rihal\/state\.json\.lock|\.planning\/|\.rihal\/brain\/sources\.yaml)/;
+  // #382 — local overrides: files matching <name>.local.md are user-managed.
+  // The installer never touches them: not in copy, not in sweep, not even on
+  // --force-overwrite. This gives users a stable path to customize agent
+  // voice / examples / project-specific rules without losing them on update.
+  const isLocalOverride = (rel) => /\.local\.(md|mdc|json|yaml|yml|toml|js|ts)$/.test(rel);
 
   let removed = 0;
   const emptyCandidateDirs = new Set();
   for (const rel of oldRels) {
     if (newRelsSet.has(rel)) continue;
     if (neverSweep.test(rel)) continue;
+    if (isLocalOverride(rel)) continue; // #382 — never sweep user-owned overrides
     const full = path.join(target, rel);
     try {
       if (fs.existsSync(full)) {
@@ -1603,6 +1609,10 @@ async function install(opts) {
   console.log(dim('    npx @hanzlaa/rcode@latest install   # pull the latest rcode + brain'));
   console.log(dim(`    /rihal:update v${version}              # pin rcode to a specific version`));
   console.log('');
+  console.log(dim('  Customize without losing changes on update:'));
+  console.log(dim('    Create <name>.local.md siblings (e.g. .claude/agents/rihal-waleed.local.md)'));
+  console.log(dim('    *.local.md files are NEVER touched by install / --force-overwrite / uninstall.'));
+  console.log('');
   console.log('  ' + warn('If your IDE is already open, reload the window to refresh skills/commands.'));
   console.log(dim('    Claude Code / VS Code / Cursor:  Cmd+Shift+P → Reload Window'));
   console.log('');

package/cli/uninstall.js

@@ -57,14 +57,26 @@ function parseArgs(args) {
   return opts;
 }
 
+/**
+ * #382 — Local overrides: files matching <name>.local.md (or .local.mdc /
+ * .local.json / etc.) are user-managed. The uninstaller never removes them
+ * — they survive both regular uninstall AND --purge. Users can customize
+ * an agent voice / skill / command by creating a .local.md sibling, knowing
+ * it'll persist across updates and uninstalls.
+ */
+function isLocalOverride(name) {
+  return /\.local\.(md|mdc|json|yaml|yml|toml|js|ts)$/.test(name);
+}
+
 /**
  * Walk a directory and remove all files/subdirs whose name matches a predicate.
- * Returns the number of entries removed.
+ * Returns the number of entries removed. Always skips local overrides (#382).
  */
 function removeMatching(dir, predicate) {
   if (!fs.existsSync(dir)) return 0;
   let count = 0;
   for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (isLocalOverride(entry.name)) continue; // #382 — never remove user overrides
     if (!predicate(entry.name)) continue;
     const full = path.join(dir, entry.name);
     fs.rmSync(full, { recursive: true, force: true });

package/dist/rcode.js

@@ -16530,11 +16530,13 @@ Say "plan a sprint" or run \`/rihal:sprint-planning\` to break Phase 01 into sto
       }
       const newRelsSet = new Set(newPlan.map((e) => e.rel.split(path2.sep).join("/")));
       const neverSweep = /^(\.rihal\/config\.yaml|\.rihal\/state\.json|\.rihal\/state\.json\.lock|\.planning\/|\.rihal\/brain\/sources\.yaml)/;
+      const isLocalOverride = (rel) => /\.local\.(md|mdc|json|yaml|yml|toml|js|ts)$/.test(rel);
       let removed = 0;
       const emptyCandidateDirs = /* @__PURE__ */ new Set();
       for (const rel of oldRels) {
         if (newRelsSet.has(rel)) continue;
         if (neverSweep.test(rel)) continue;
+        if (isLocalOverride(rel)) continue;
         const full = path2.join(target, rel);
         try {
           if (fs2.existsSync(full)) {
@@ -17005,6 +17007,10 @@ Say "plan a sprint" or run \`/rihal:sprint-planning\` to break Phase 01 into sto
       console.log(dim("    npx @hanzlaa/rcode@latest install   # pull the latest rcode + brain"));
       console.log(dim(`    /rihal:update v${version}              # pin rcode to a specific version`));
       console.log("");
+      console.log(dim("  Customize without losing changes on update:"));
+      console.log(dim("    Create <name>.local.md siblings (e.g. .claude/agents/rihal-waleed.local.md)"));
+      console.log(dim("    *.local.md files are NEVER touched by install / --force-overwrite / uninstall."));
+      console.log("");
       console.log("  " + warn("If your IDE is already open, reload the window to refresh skills/commands."));
       console.log(dim("    Claude Code / VS Code / Cursor:  Cmd+Shift+P \u2192 Reload Window"));
       console.log("");
@@ -17953,10 +17959,14 @@ var require_uninstall = __commonJS({
       }
       return opts;
     }
+    function isLocalOverride(name) {
+      return /\.local\.(md|mdc|json|yaml|yml|toml|js|ts)$/.test(name);
+    }
     function removeMatching(dir, predicate) {
       if (!fs2.existsSync(dir)) return 0;
       let count = 0;
       for (const entry of fs2.readdirSync(dir, { withFileTypes: true })) {
+        if (isLocalOverride(entry.name)) continue;
         if (!predicate(entry.name)) continue;
         const full = path2.join(dir, entry.name);
         fs2.rmSync(full, { recursive: true, force: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzlaa/rcode",
-  "version": "2.7.0",
+  "version": "2.7.2",
   "description": "Rihal Code (rcode) — installable context-brain for Rihalians. 43 agents, 99 slash commands, 56 skills, pullable Rihal standards. Unified install for Claude Code, Cursor, and Gemini.",
   "main": "cli/index.js",
   "bin": {

package/rihal/workflows/do.md

@@ -28,6 +28,56 @@ fi
 ```
 </step>
 
+<step name="persona_shortcut" priority="first-match">
+**Recognize `@persona CODE` shortcuts as the deterministic API surface.**
+
+Every Rihal persona file has a Capabilities table listing 2-3-letter codes (Waleed: ADR/RV/TS/FZ/KS · Hussain-PM: CP/VP/EP/CE/CS/IR/CC · Mariam: MR/ICP/GTM/POS/LP · Fatima: TS/RG/EC/RR/RP/FT · Hanzla: DS/IS/BF/RF/KA/CR · Sadiq: KC/OC/PT/MT/KS · Dalil: SC/MC/RF/TS · Khattat / Munaffidh / Bahith / Muhaqqiq similarly).
+
+Match if `$QUESTION` starts with `@<persona> <CODE>` or `@<persona>:<CODE>` — case-insensitive on persona, codes uppercase. Examples:
+
+- `@hussain CP` → dispatch to Hussain-PM with capability `CP` (Create PRD via interview)
+- `@waleed ADR` → dispatch to Waleed with capability `ADR` (write an ADR)
+- `@fatima RG` → dispatch to Fatima with capability `RG` (release-gate review)
+- `@dalil SC --topic "Sentry"` → dispatch to Dalil with capability `SC` (lightweight scan, topic phrase passed)
+
+**Persona-name aliases** (lowercased, common nicknames):
+| Alias | Resolves to | Agent file |
+|---|---|---|
+| `sadiq`, `strategy`, `director` | Sadiq | rihal-sadiq |
+| `waleed`, `cto`, `architect` | Waleed | rihal-waleed |
+| `hussain`, `hussain-pm`, `pm` | Hussain | rihal-hussain-pm |
+| `mariam`, `marketing` | Mariam | rihal-mariam |
+| `fatima`, `qa` | Fatima | rihal-fatima |
+| `hanzla`, `dev`, `engineer` | Hanzla | rihal-hanzla |
+| `dalil`, `scout`, `mapper` | Dalil | rihal-codebase-mapper |
+| `khattat`, `planner` | Khattat | rihal-planner |
+| `munaffidh`, `executor` | Munaffidh | rihal-executor |
+
+**Behavior:**
+
+1. Parse the persona alias and CODE.
+2. Read the persona's agent file at `.claude/agents/{agent-id}.md` (or `.claude/agents/{agent-id}.local.md` if it exists — local overrides take precedence).
+3. Look up the CODE in the Capabilities table. If found, the table row's "Skill / workflow" column tells you which sub-command to invoke; pass the rest of `$QUESTION` (after the shortcut) as arguments.
+4. If the CODE is not in that persona's Capabilities table, print:
+   ```
+   Persona '{persona}' has no capability '{CODE}'. Available codes:
+   {list from the persona's Capabilities table}
+   ```
+   And stop. Do not fall back to fuzzy intent matching — the user used the deterministic API, honour it.
+5. Dispatch directly via the routing banner. Skip greenfield_guard / external_data_guard / explicit_intent_check / route — the user already chose the persona AND the action. The persona itself can still refuse internally if its preconditions aren't met.
+
+**This is the deterministic API surface.** Power users (and other agents in council follow-ups) can invoke specific capabilities without re-reading triggers or risking fuzzy match. It's the cheapest way to get repeatable behaviour out of the persona system.
+
+**Edge cases:**
+
+- `@waleed` (no code) → dispatch to Waleed with no capability hint; persona uses its default workflow.
+- `@nobody CP` (unknown persona) → fail loud: list known personas, exit.
+- `CP @hussain` (code first) → reorder; do not match. The `@persona CODE` order is canonical.
+- `@hussain CP fix the auth bug` → dispatch with `CP` and pass `fix the auth bug` as argument context.
+
+If this step does NOT fire (no `@` prefix), continue to validate.
+</step>
+
 <step name="validate">
 **Check for input.**