@hanzlaa/rcode 3.2.1 → 3.3.1

package/CONTRIBUTING.md

@@ -30,7 +30,7 @@ A command file is tiny. It registers a slash command in Claude Code's UI and poi
 
 ```markdown
 ---
-name: rihal:prfaq
+name: rihal-prfaq
 description: Working Backwards PRFAQ challenge
 allowed-tools: [Read, Write, Agent, AskUserQuestion, WebSearch]
 ---
@@ -40,14 +40,14 @@ allowed-tools: [Read, Write, Agent, AskUserQuestion, WebSearch]
 
 That `@-include` line tells Claude to load the target file's contents as context. Without a command file, a skill is unreachable via `/` — it can only be triggered by describing the task in natural language.
 
-**Rule:** Every capability intended to be user-typed as `/rihal:something` needs a matching `rihal/commands/something.md`.
+**Rule:** Every capability intended to be user-typed as `/rihal-something` needs a matching `rihal/commands/something.md`.
 
 ### Workflows — orchestration logic
 
 Workflows are prose instructions — markdown files Claude reads as a script to follow. They handle control flow: read state, ask a question, dispatch to a sub-workflow, report results. Most slash commands point to a workflow:
 
 ```
-/rihal:audit  →  commands/audit.md  →  @workflows/audit.md
+/rihal-audit  →  commands/audit.md  →  @workflows/audit.md
 ```
 
 Workflows are the right tool when the task is a sequence of steps that Claude drives (check state → ask user → run something → report). They should not contain deep domain knowledge — that belongs in skills.
@@ -74,7 +74,7 @@ rihal/skills/actions/1-analysis/rihal-prfaq/
 Skills are the right tool when the task has multiple stages, needs sub-agent parallelism, or carries domain-specific coaching logic (e.g., how to run a PRFAQ gauntlet, how to do a Karpathy code review).
 
 Skills have **two activation paths**:
-1. **Via command** — `/rihal:prfaq` loads the SKILL.md directly
+1. **Via command** — `/rihal-prfaq` loads the SKILL.md directly
 2. **Phrase-activated** — when a user describes the task, Claude picks up the skill from its `description` field in the YAML frontmatter
 
 ### Agents — focused specialists
@@ -85,12 +85,12 @@ There are two kinds:
 
 **Sub-agents** live inside skill folders (`rihal/skills/agents/*/SKILL.md`). They're invoked by their parent skill, not by the user directly. Example: the PRFAQ skill spawns `artifact-analyzer` and `web-researcher` in parallel during Stage 1.
 
-**Council agents** live in `rihal/agents/*.md`. They're the named characters (Waleed, Hanzla, Fatima, Sadiq…) that `/rihal:council` assembles into a panel. These are installed to `.claude/agents/` and can be spawned from any workflow.
+**Council agents** live in `rihal/agents/*.md`. They're the named characters (Waleed, Hanzla, Fatima, Sadiq…) that `/rihal-council` assembles into a panel. These are installed to `.claude/agents/` and can be spawned from any workflow.
 
 ### How they chain for a real request
 
 ```
-User types:  /rihal:council "Should we use Redis?"
+User types:  /rihal-council "Should we use Redis?"
                    │
          commands/council.md          ← slash command entry
                    │ @-includes
@@ -108,7 +108,7 @@ User types:  /rihal:council "Should we use Redis?"
 A more complex chain involving a skill:
 
 ```
-User types:  /rihal:prfaq
+User types:  /rihal-prfaq
                    │
          commands/prfaq.md
                    │ @-includes
@@ -128,10 +128,10 @@ User types:  /rihal:prfaq
 
 | I want to… | Edit this |
 |-----------|-----------|
-| Add a new `/rihal:something` slash command | Create `rihal/commands/something.md` pointing to a workflow or skill |
+| Add a new `/rihal-something` slash command | Create `rihal/commands/something.md` pointing to a workflow or skill |
 | Change the steps in an existing command | Edit the workflow it points to |
 | Improve how a persona thinks (Hanzla, Waleed, etc.) | Edit `rihal/skills/agents/<name>/SKILL.md` or `rihal/agents/<name>.md` |
-| Add a new agent to `/rihal:council` | Edit `rihal/agents/team.yaml` + add agent file |
+| Add a new agent to `/rihal-council` | Edit `rihal/agents/team.yaml` + add agent file |
 | Improve a complex multi-stage task (PRFAQ, code review, etc.) | Edit the skill's stage reference files |
 | Add a new skill triggered by natural language | Create `rihal/skills/actions/<category>/<name>/SKILL.md` — no command file needed if slash is not required |
 | Fix a broken `@-include` reference | Check that the target file exists at `.rihal/<path>` after install |

package/README.md

@@ -44,7 +44,7 @@ Rihal Code packages a lot. To keep things approachable, everything is organized
 
 **Brand new?** Do the [Golden Path](docs/TIERS.md#-starter--the-golden-path): scaffold → PRD → stories → sprint → dev → review → status. Seven skills, one project, end-to-end.
 
-> **v2.0 — Rihal Brain.** v1 was a generic AI-engineering methodology. v2 keeps all of that and adds the Rihal context layer on top: standards, guides, and institutional knowledge pulled fresh from Rihal's own repos on install and on `/rihal:update`. See [`CHANGELOG.md`](CHANGELOG.md) and the [v2.0 milestone](https://github.com/hanzlahabib/rihal-code/milestone/4).
+> **v2.0 — Rihal Brain.** v1 was a generic AI-engineering methodology. v2 keeps all of that and adds the Rihal context layer on top: standards, guides, and institutional knowledge pulled fresh from Rihal's own repos on install and on `/rihal-update`. See [`CHANGELOG.md`](CHANGELOG.md) and the [v2.0 milestone](https://github.com/hanzlahabib/rihal-code/milestone/4).
 
 ---
 
@@ -56,7 +56,7 @@ Most AI tools give you one assistant pretending to be everything. **Rihal Code g
 - **95 slash commands** covering research, planning, execution, verification, and recovery
 - **80 skills** including Memory Bank primitives, 11 engineering-rigor skills (TDD, harden, perf, debug, trim, etc.), and 8 real-pain skills (auth-audit, mvp-graduate, deploy-unify, etc.)
 - **Persistent project memory** at `.rihal/memory/` — checked into git, visible in the Diwan dashboard, lossless distillates for fast LLM hydration
-- **3 execution modes**: parallel debate (`/rihal:council`), sequential pipelines (`/rihal:chain`), and quick-sync (`/rihal:discuss`)
+- **3 execution modes**: parallel debate (`/rihal-council`), sequential pipelines (`/rihal-chain`), and quick-sync (`/rihal-discuss`)
 - **File-based state** in `.rihal/` that every workflow reads and updates
 - **Intent guards** on every workflow — catch wrong commands early with copy-paste redirects
 - **Karpathy-inspired coding guidelines** wired into every code-writing agent
@@ -90,14 +90,14 @@ One unified installer. Pure file shipping, no runtime dependencies. Installs int
 - `rihal/brain/` — Rihal standards pulled from upstream (PR / commit / architecture docs)
 - `.planning/` — where your artifacts land (council sessions, plans, chains, summaries)
 
-Restart Claude Code (or your IDE), type `/`, and every `rihal:*` command appears.
+Restart Claude Code (or your IDE), type `/`, and every `rihal-*` command appears.
 
-Update anytime with `npx @hanzlaa/rcode update` (or `/rihal:update` inside a Claude session).
+Update anytime with `npx @hanzlaa/rcode update` (or `/rihal-update` inside a Claude session).
 
 ### Then begin the rihla
 
 ```
-/rihal:init
+/rihal-init
 ```
 
 Detects your project state (fresh / existing-with-no-rihal / returning), asks a few configuration questions, and routes you to the right first action.
@@ -123,14 +123,14 @@ npx @hanzlaa/rcode install --ide gemini
 ## 90-second tour
 
 ```
-/rihal:do                                    → interactive router
-/rihal:council should I rewrite auth?        → 5 agents debate in parallel, 2 rounds
-/rihal:discuss waleed what stack for saas?   → single expert, fast
-/rihal:chain research-plan dubai affiliate   → Mariam → Hussain-PM → Planner pipeline
-/rihal:plan --research build a rental app    → researcher grounds, plan-checker verifies
-/rihal:execute .planning/plans/01/PLAN.md    → atomic commits + post-gates
-/rihal:status                                → phases, decisions, blockers, sessions
-/rihal:code-review HEAD~5..HEAD --karpathy   → audit changes vs 4 coding principles
+/rihal-do                                    → interactive router
+/rihal-council should I rewrite auth?        → 5 agents debate in parallel, 2 rounds
+/rihal-discuss waleed what stack for saas?   → single expert, fast
+/rihal-chain research-plan dubai affiliate   → Mariam → Hussain-PM → Planner pipeline
+/rihal-plan --research build a rental app    → researcher grounds, plan-checker verifies
+/rihal-execute .planning/plans/01/PLAN.md    → atomic commits + post-gates
+/rihal-status                                → phases, decisions, blockers, sessions
+/rihal-code-review HEAD~5..HEAD --karpathy   → audit changes vs 4 coding principles
 ```
 
 ---
@@ -160,7 +160,7 @@ npx @hanzlaa/rcode install --ide gemini
   phases/01-name/PLAN.md       — plans organized by phase number (01, 02, 02.1, etc.)
   council-sessions/            — debate artifacts
   chains/                       — pipeline outputs (RESEARCH.md → SCOPE.md → PLAN.md)
-  notes/                        — quick notes from /rihal:note
+  notes/                        — quick notes from /rihal-note
   HANDOFF.json                  — pause-work checkpoint
   .continue-here.md            — human-readable handoff summary
 ```
@@ -193,38 +193,38 @@ npx @hanzlaa/rcode install --ide gemini
 
 ## Three modes, three mental models
 
-### 🏛️ `/rihal:council` — Parallel debate
+### 🏛️ `/rihal-council` — Parallel debate
 
 3-5 agents answer simultaneously in Round 1, then Round 2 lets each agent challenge the others' Round 1 responses. Result: one session artifact with all voices + orchestrator note flagging the sharpest disagreement.
 
 **Best for:** strategic decisions where you want disagreement, not consensus.
 
 ```
-/rihal:council should we migrate from monolith to microservices?
+/rihal-council should we migrate from monolith to microservices?
 ```
 
-### 🔗 `/rihal:chain` — Sequential pipeline
+### 🔗 `/rihal-chain` — Sequential pipeline
 
 Each agent runs after the previous one finishes, reading that agent's artifact as input. Result: a typed artifact per stage (RESEARCH.md → SCOPE.md → PLAN.md) in `.planning/chains/`.
 
 **Best for:** when you know roughly what you want and each specialist needs to do their part in order.
 
 ```
-/rihal:chain research-plan dubai affiliate site for mobile accessories
-/rihal:chain feasibility migrate postgres to neon serverless
-/rihal:chain gtm-to-build saas bookkeeping in oman
+/rihal-chain research-plan dubai affiliate site for mobile accessories
+/rihal-chain feasibility migrate postgres to neon serverless
+/rihal-chain gtm-to-build saas bookkeeping in oman
 ```
 
-Presets: `research-plan` · `feasibility` · `gtm-to-build` · `full-discovery`. Or custom: `/rihal:chain mariam,waleed,fatima "your topic"`.
+Presets: `research-plan` · `feasibility` · `gtm-to-build` · `full-discovery`. Or custom: `/rihal-chain mariam,waleed,fatima "your topic"`.
 
-### 💬 `/rihal:discuss` — Single agent, quick-sync
+### 💬 `/rihal-discuss` — Single agent, quick-sync
 
 One agent, one round, conversational tone, no mandatory artifact. Feels like texting one colleague.
 
 ```
-/rihal:discuss waleed can we use postgres jsonb for this?
-/rihal:discuss fatima is this release ready?
-/rihal:discuss what's the kill criterion for this project?
+/rihal-discuss waleed can we use postgres jsonb for this?
+/rihal-discuss fatima is this release ready?
+/rihal-discuss what's the kill criterion for this project?
 ```
 
 If no agent named, the panel scorer picks the top match.
@@ -238,10 +238,10 @@ If no agent named, the panel scorer picks the top match.
 Run the wrong command and you get a single-line copy-paste redirect — not a useless output.
 
 ```
-/rihal:plan should we use postgres or mongo?
+/rihal-plan should we use postgres or mongo?
 ⚠ That's a decision question, not a planning input.
 Copy-paste this to ask the council instead:
-/rihal:council should we use postgres or mongo?
+/rihal-council should we use postgres or mongo?
 ```
 
 Every workflow has a Step 0.5 intent detector.
@@ -251,19 +251,19 @@ Every workflow has a Step 0.5 intent detector.
 The classifier recognizes `dubai`, `affiliate`, `bnanai`, `karobar`, `site banana`, `دبئی`, `مارکیٹ`, `کاروبار` and many more. Mariam leads for GCC/MENA market questions.
 
 ```
-/rihal:council yar affiliate site bnanai hai dubai ma for quick bucks
+/rihal-council yar affiliate site bnanai hai dubai ma for quick bucks
 → panel: [mariam, hussain-pm, sadiq]
 ```
 
 ### PRFAQ — validate before you build
 
-Amazon's "Working Backwards" method: write the finished-product press release *before* writing a line of code. If you can't write a compelling press release, the product isn't ready. `/rihal:prfaq` runs a 5-stage coaching gauntlet — Ignition → Press Release → Customer FAQ → Internal FAQ → Verdict — and outputs a battle-hardened concept document plus a PRD distillate ready for `/rihal:create-prd`.
+Amazon's "Working Backwards" method: write the finished-product press release *before* writing a line of code. If you can't write a compelling press release, the product isn't ready. `/rihal-prfaq` runs a 5-stage coaching gauntlet — Ignition → Press Release → Customer FAQ → Internal FAQ → Verdict — and outputs a battle-hardened concept document plus a PRD distillate ready for `/rihal-create-prd`.
 
 **When to use it:** Any time a PM or engineer wants to validate whether an idea is worth building before committing sprint capacity. The skill challenges vague thinking, enforces customer-first framing, and gives a build/refine/kill verdict.
 
 ```
-/rihal:prfaq                                         → interactive gauntlet
-/rihal:prfaq --headless --customer "..." --problem "..." --solution "..."   → autonomous first draft
+/rihal-prfaq                                         → interactive gauntlet
+/rihal-prfaq --headless --customer "..." --problem "..." --solution "..."   → autonomous first draft
 ```
 
 ### Karpathy coding guidelines
@@ -275,23 +275,23 @@ Amazon's "Working Backwards" method: write the finished-product press release *b
 3. **Surgical changes** — touch only what's needed, match existing style
 4. **Goal-driven execution** — define verifiable success criteria
 
-`/rihal:code-review --karpathy` runs these 4 principles as a post-hoc audit against any diff or phase. Use it after implementation to catch bloated, over-engineered, or scope-creeping changes before they land in a PR.
+`/rihal-code-review --karpathy` runs these 4 principles as a post-hoc audit against any diff or phase. Use it after implementation to catch bloated, over-engineered, or scope-creeping changes before they land in a PR.
 
 ```
-/rihal:code-review HEAD~5..HEAD --karpathy
-/rihal:code-review 03 --files=src/auth/ --karpathy
+/rihal-code-review HEAD~5..HEAD --karpathy
+/rihal-code-review 03 --files=src/auth/ --karpathy
 ```
 
 ### Plan verification + post-execute gates
 
-`/rihal:plan` runs `rihal-plan-checker` after the planner writes PLAN.md. On failure, loops back to planner with feedback (max 2 retries).
+`/rihal-plan` runs `rihal-plan-checker` after the planner writes PLAN.md. On failure, loops back to planner with feedback (max 2 retries).
 
-`/rihal:execute` runs `rihal-integration-checker` (cross-phase E2E) and `rihal-nyquist-auditor` (test coverage) after completion. Both append to SUMMARY.md.
+`/rihal-execute` runs `rihal-integration-checker` (cross-phase E2E) and `rihal-nyquist-auditor` (test coverage) after completion. Both append to SUMMARY.md.
 
 ### Model profiles
 
 ```bash
-/rihal:settings       # interactive config
+/rihal-settings       # interactive config
 ```
 
 - **quality** — opus/sonnet-4.6 for reasoning agents
@@ -302,8 +302,8 @@ Amazon's "Working Backwards" method: write the finished-product press release *b
 ### Session handoff
 
 ```
-/rihal:pause-work    → writes .rihal/HANDOFF.json + .continue-here.md
-/rihal:resume-work   → reads HANDOFF, surfaces blocking constraints
+/rihal-pause-work    → writes .rihal/HANDOFF.json + .continue-here.md
+/rihal-resume-work   → reads HANDOFF, surfaces blocking constraints
 ```
 
 ---
@@ -315,16 +315,16 @@ Recent additions in this session:
 - **69 slash commands** across 3 modes and 3 modules (up from 64)
 - **Numeric ID system** — milestones (M1, M2), phases (01, 02, 02.1), plans (01.01, 02.03), tasks (01.01.01) with decimal insertion for urgent inserts
 - **Intent guards** (`Step 0.5`) — every workflow detects mismatched intent and redirects instead of failing
-- **Plan-checker loop** — `/rihal:plan` now verifies file existence and symbol definitions; loops back to planner on validation failure
-- **Post-execute gates** — `/rihal:execute` runs integration-checker (E2E) and nyquist-auditor (coverage) as hard gates
+- **Plan-checker loop** — `/rihal-plan` now verifies file existence and symbol definitions; loops back to planner on validation failure
+- **Post-execute gates** — `/rihal-execute` runs integration-checker (E2E) and nyquist-auditor (coverage) as hard gates
 - **Multilingual classifier** — Roman Urdu, Arabic, English with cultural signal routing (Mariam leads GCC/MENA)
 - **Karpathy guidelines enforcement** — 4 coding principles baked into every code-writing agent
 - **Global agents** — customize agents in `~/.rihal/agents/` without forking the repo
 - **Multi-IDE installer** — support for Claude Code, Cursor, Gemini CLI
 - **Hooks system** — opt-in pre-edit, pre-workflow, post-commit enforcement
-- **Session pause/resume** — `/rihal:pause-work` + `/rihal:resume-work` with HANDOFF.json
-- **Workspace isolation** — `/rihal:new-workspace` for parallel tracks
-- **Decimal phase insertion** — `/rihal:insert-phase` for urgent mid-cycle work
+- **Session pause/resume** — `/rihal-pause-work` + `/rihal-resume-work` with HANDOFF.json
+- **Workspace isolation** — `/rihal-new-workspace` for parallel tracks
+- **Decimal phase insertion** — `/rihal-insert-phase` for urgent mid-cycle work
 
 ---
 
@@ -370,7 +370,7 @@ Recent additions in this session:
 
 ## Configuration
 
-`.rihal/config.yaml` — edit directly or run `/rihal:settings`:
+`.rihal/config.yaml` — edit directly or run `/rihal-settings`:
 
 ```yaml
 user_name: "Hanzla"
@@ -402,7 +402,7 @@ View formatted:
 ```bash
 node .rihal/bin/rihal-tools.cjs state read
 # or
-/rihal:status
+/rihal-status
 ```
 
 ---
@@ -410,7 +410,7 @@ node .rihal/bin/rihal-tools.cjs state read
 ## Hooks (opt-in)
 
 ```bash
-/rihal:enable-hooks
+/rihal-enable-hooks
 ```
 
 Installs 3 opt-in hooks into `.claude/settings.json`:
@@ -424,9 +424,9 @@ Installs 3 opt-in hooks into `.claude/settings.json`:
 
 | Module | Contents |
 |--------|----------|
-| **core** | 5 council agents, `/rihal:council`, `/rihal:discuss`, `/rihal:status`, `/rihal:do`, `/rihal:help`, state management |
-| **execution** | Executor, planner, verifier + checker agents, `/rihal:execute`, `/rihal:plan`, `/rihal:quick`, `/rihal:debug`, `/rihal:audit-fix`, `/rihal:undo` |
-| **discovery** | Codebase-mapper, project-researcher, roadmapper, `/rihal:new-project`, `/rihal:map-codebase`, `/rihal:scan`, `/rihal:explore`, `/rihal:code-review`, `/rihal:docs-update` |
+| **core** | 5 council agents, `/rihal-council`, `/rihal-discuss`, `/rihal-status`, `/rihal-do`, `/rihal-help`, state management |
+| **execution** | Executor, planner, verifier + checker agents, `/rihal-execute`, `/rihal-plan`, `/rihal-quick`, `/rihal-debug`, `/rihal-audit-fix`, `/rihal-undo` |
+| **discovery** | Codebase-mapper, project-researcher, roadmapper, `/rihal-new-project`, `/rihal-map-codebase`, `/rihal-scan`, `/rihal-explore`, `/rihal-code-review`, `/rihal-docs-update` |
 
 Full install = all 3 modules = 201 files.
 

package/cli/context.js

@@ -13,7 +13,7 @@
  *                                         prints a warning when stale
  *
  * The refresh does NOT rewrite active.md or project-brief.md — that's
- * /rihal:init's job (the scan requires an LLM). --refresh just stores the
+ * /rihal-init's job (the scan requires an LLM). --refresh just stores the
  * current fingerprint so the next check sees things as fresh.
  */
 
@@ -117,7 +117,7 @@ function printReport(cwd) {
   console.log();
 
   if (report.status !== 'fresh') {
-    console.log(`   ➡ Refresh with: /rihal:init (in your editor)`);
+    console.log(`   ➡ Refresh with: /rihal-init (in your editor)`);
     console.log();
   }
 }
@@ -125,7 +125,7 @@ function printReport(cwd) {
 /**
  * --refresh: recompute and save the fingerprint to .rihal/state.json.
  * Only use this when you know the memory bank was actually refreshed
- * (e.g. by /rihal:init running end-to-end). Does NOT rewrite context files.
+ * (e.g. by /rihal-init running end-to-end). Does NOT rewrite context files.
  */
 function doRefresh(cwd) {
   ensureRihalDir(cwd);
@@ -161,7 +161,7 @@ if command -v rcode >/dev/null 2>&1; then
   output=$(rcode context --check 2>&1)
   if [ $? -ne 0 ]; then
     echo ""
-    echo "⚠ Rihal memory bank is stale — run /rihal:init in your editor to refresh."
+    echo "⚠ Rihal memory bank is stale — run /rihal-init in your editor to refresh."
     echo "   $(echo "$output" | grep '•' | head -1 | sed 's/^ *//')"
   fi
 fi

package/cli/doctor.js

@@ -190,7 +190,7 @@ function runPreflight(cwd, packageRoot) {
       checks.push({
         label: 'Memory bank',
         status: 'warn',
-        message: 'never initialized (run /rihal:init to populate)',
+        message: 'never initialized (run /rihal-init to populate)',
       });
     } else {
       checks.push({

package/cli/generate-command-skills.cjs

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+/**
+ * Install-time generator: skill stubs that mirror slash commands.
+ *
+ * WHY: VS Code's Claude Code extension lists `.claude/skills/` in its
+ * sidebar, but slash commands at `.claude/commands/rihal/` are only
+ * reachable via the `/` autocomplete. Users coming from GSD (which ships
+ * a skill per command) expect to see lifecycle commands like `rihal-do`
+ * in the sidebar.
+ *
+ * This script creates ONE skill stub per slash command at install time,
+ * unless a real skill with the same name already exists at the source.
+ * The stubs live at the install destination only (`.claude/skills/`) —
+ * they are NEVER committed to the rcode source tree. That keeps the
+ * source codebase free of duplication while letting the sidebar feel
+ * full.
+ *
+ * Each generated stub is marked with `generated: true` and
+ * `generated-by: rcode-install` in frontmatter so it can be detected
+ * and refreshed on subsequent installs without confusing real skills.
+ *
+ * Run: node scripts/generate-command-skills.cjs <package-root> <target-skills-dir>
+ *      (called from cli/install.js)
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Curated list of commands that get skill stubs. Not every command
+ * deserves a sidebar entry — only the user-facing entry points and
+ * lifecycle verbs. Internal sub-commands stay slash-only.
+ */
+const SIDEBAR_COMMANDS = new Set([
+  'do', 'status', 'progress', 'next', 'plan', 'execute',
+  'council', 'discuss', 'ship', 'audit', 'autonomous',
+  'session-report', 'forensics', 'health', 'debug',
+  'verify-phase', 'verify-work', 'review', 'code-review',
+  'new-project', 'new-milestone', 'milestone-summary',
+  'note', 'add-todo', 'check-todos', 'pause-work', 'resume-work',
+]);
+
+function parseFrontmatter(text) {
+  if (!text.startsWith('---\n')) return {};
+  const end = text.indexOf('\n---\n', 4);
+  if (end === -1) return {};
+  const block = text.slice(4, end);
+  const fm = {};
+  for (const raw of block.split('\n')) {
+    const m = raw.match(/^([a-zA-Z_-]+):\s*(.+)$/);
+    if (m) fm[m[1].trim()] = m[2].trim().replace(/^["']|["']$/g, '');
+  }
+  return fm;
+}
+
+function discoverRealSkills(packageRoot) {
+  const out = new Set();
+  const buckets = ['core', 'agents'];
+  for (const bucket of buckets) {
+    const dir = path.join(packageRoot, 'rihal', 'skills', bucket);
+    if (!fs.existsSync(dir)) continue;
+    for (const entry of fs.readdirSync(dir)) {
+      if (entry.startsWith('rihal-')) out.add(entry);
+    }
+  }
+  // actions are nested by phase
+  const actionsDir = path.join(packageRoot, 'rihal', 'skills', 'actions');
+  if (fs.existsSync(actionsDir)) {
+    for (const phase of fs.readdirSync(actionsDir)) {
+      const phaseDir = path.join(actionsDir, phase);
+      if (!fs.statSync(phaseDir).isDirectory()) continue;
+      for (const entry of fs.readdirSync(phaseDir)) {
+        if (entry.startsWith('rihal-')) out.add(entry);
+      }
+    }
+  }
+  return out;
+}
+
+function generateStub(cmdName, commandFm, version) {
+  const desc = commandFm.description || `Slash command shortcut for /rihal-${cmdName}.`;
+  const triggers = [
+    `rihal ${cmdName}`,
+    `rihal-${cmdName}`,
+    `/rihal-${cmdName}`,
+  ];
+
+  return `---
+name: rihal-${cmdName}
+description: >
+  ${desc.replace(/\n/g, ' ')}
+  Sidebar entry — invokes the same workflow as /rihal-${cmdName}.
+triggers:
+${triggers.map((t) => `  - "${t}"`).join('\n')}
+user-invocable: true
+generated: true
+generated-by: rcode-install-v${version}
+source: rihal/commands/${cmdName}.md
+---
+
+<!--
+AUTO-GENERATED at install time by scripts/generate-command-skills.cjs.
+Do NOT edit this file directly — your changes will be overwritten on the next
+install or update. To customise, create a sibling \`.local.md\` file (which
+is preserved across installs) or modify the source command at
+rihal/commands/${cmdName}.md.
+
+This stub exists so the slash command /rihal-${cmdName} appears in VS Code's
+Claude Code sidebar (which lists skills only, not slash commands). The
+behaviour is identical to /rihal-${cmdName} — both invoke the workflow at
+.rihal/workflows/${cmdName}.md.
+-->
+
+## Overview
+
+Sidebar entry for the \`/rihal-${cmdName}\` slash command. Phrase-activated alternative invocation route.
+
+## Workflow
+
+Read and execute \`@.rihal/workflows/${cmdName}.md\` end-to-end. The behaviour is the same as invoking \`/rihal-${cmdName}\` directly.
+
+## Output Format
+
+Identical to \`/rihal-${cmdName}\`. See the workflow file for the canonical output spec.
+
+## Examples
+
+**Happy path** — say "rihal ${cmdName}" or "/rihal-${cmdName}" → workflow runs identically either way.
+
+**Negative — looking for the canonical command file** — see \`rihal/commands/${cmdName}.md\` (the source of truth) and \`rihal/workflows/${cmdName}.md\` (the orchestration logic).
+
+## Memory Bank Hooks
+
+- **Reads:** whatever \`.rihal/workflows/${cmdName}.md\` reads
+- **Writes:** whatever the workflow writes
+- This stub itself is read-only — it just dispatches to the workflow.
+`;
+}
+
+function main(packageRoot, targetSkillsDir, version) {
+  if (!fs.existsSync(targetSkillsDir)) {
+    fs.mkdirSync(targetSkillsDir, { recursive: true });
+  }
+
+  const realSkills = discoverRealSkills(packageRoot);
+  const commandsDir = path.join(packageRoot, 'rihal', 'commands');
+  if (!fs.existsSync(commandsDir)) {
+    console.warn(`[generate-command-skills] commands dir not found: ${commandsDir}`);
+    return { generated: 0, skipped: 0 };
+  }
+
+  let generated = 0;
+  let skipped = 0;
+
+  for (const file of fs.readdirSync(commandsDir)) {
+    if (!file.endsWith('.md')) continue;
+    if (file.startsWith('_')) continue; // internal aliases / metadata
+    const cmdName = file.replace(/\.md$/, '');
+    if (!SIDEBAR_COMMANDS.has(cmdName)) { skipped++; continue; }
+
+    const skillName = `rihal-${cmdName}`;
+    if (realSkills.has(skillName)) {
+      // A real skill with this name exists in the source tree — don't shadow it
+      skipped++;
+      continue;
+    }
+
+    const cmdPath = path.join(commandsDir, file);
+    const cmdText = fs.readFileSync(cmdPath, 'utf8');
+    const cmdFm = parseFrontmatter(cmdText);
+
+    const stubDir = path.join(targetSkillsDir, skillName);
+    const stubFile = path.join(stubDir, 'SKILL.md');
+
+    // Idempotency: only overwrite if the file is missing OR is a previously
+    // generated stub (has the marker). Never clobber a user's hand-edited file.
+    if (fs.existsSync(stubFile)) {
+      const existing = fs.readFileSync(stubFile, 'utf8');
+      if (!/^generated:\s*true/m.test(existing)) {
+        skipped++;
+        continue;
+      }
+    }
+
+    fs.mkdirSync(stubDir, { recursive: true });
+    fs.writeFileSync(stubFile, generateStub(cmdName, cmdFm, version), 'utf8');
+    generated++;
+  }
+
+  return { generated, skipped };
+}
+
+if (require.main === module) {
+  const [packageRoot, targetSkillsDir, version = '0.0.0'] = process.argv.slice(2);
+  if (!packageRoot || !targetSkillsDir) {
+    console.error('Usage: generate-command-skills.cjs <package-root> <target-skills-dir> [version]');
+    process.exit(2);
+  }
+  const { generated, skipped } = main(packageRoot, targetSkillsDir, version);
+  console.log(`✓ ${generated} sidebar skill stub${generated === 1 ? '' : 's'} generated, ${skipped} skipped (already real skills or out of curated set)`);
+}
+
+module.exports = { main, SIDEBAR_COMMANDS };