@hanzlaa/rcode 2.3.1 → 2.3.3

package/CLAUDE.md

@@ -92,6 +92,21 @@ If a user says "just keep going" or "don't stop until done", that authorization
 
 ---
 
+## 🚨 No Theoretical Suggestions — Codebase First
+
+**Every suggestion, plan, or change MUST be grounded in what actually exists in the codebase.**
+
+- **NEVER suggest adding, fixing, or implementing something that doesn't exist yet** unless the user explicitly asked you to build it from scratch
+- **ALWAYS read the actual files** before proposing a change — never assume a function, field, or file exists based on documentation or naming conventions
+- **NEVER say "this probably does X"** — verify with `grep`, `find`, or `Read` first
+- **NEVER produce an investigation/plan based on theoretical structure** — if you can't find it in the code, say "this doesn't exist yet" and stop
+- **When a workflow or agent references something** (file path, function name, config key) — confirm it exists before including it in a plan
+- If a file is missing that should exist: report it as a gap, do NOT write a plan that assumes it will work
+
+**The test:** Could every line of your plan be traced back to a specific file and line number in the repo? If not, it's theoretical — don't ship it.
+
+---
+
 ## Communication Rules
 
 - Report progress honestly — do not claim work is done if it isn't

package/README.md

@@ -37,7 +37,7 @@ Rihal Code packages a lot. To keep things approachable, everything is organized
 
 Most AI tools give you one assistant pretending to be everything. **Rihal Code gives you Rihal's team — and Rihal's brain — inside every project.**
 
-- **45 agents** with clear roles, cultural identity (Arabic names), and hard scope boundaries
+- **43 agents** with clear roles, cultural identity (Arabic names), and hard scope boundaries
 - **99 slash commands** covering research, planning, execution, verification, and recovery
 - **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
@@ -65,9 +65,9 @@ npx @hanzlaa/rcode install
 One unified installer. Pure file shipping, no runtime dependencies. Installs into:
 
 - `.rihal/` — config, workflows, references, bin (Rihal infrastructure)
-- `.claude/agents/` — 45 first-class subagents
+- `.claude/agents/` — 43 first-class subagents
 - `.claude/commands/rihal/` — 99 slash commands
-- `.claude/skills/` — 57 phrase-activated skills (scaffold-project, create-prd, prfaq, retrospective, etc.)
+- `.claude/skills/` — 56 phrase-activated skills (scaffold-project, create-prd, prfaq, retrospective, etc.)
 - `rihal/brain/` — Rihal standards pulled from upstream (PR / commit / architecture docs)
 - `.planning/` — where your artifacts land (council sessions, plans, chains, summaries)
 

package/cli/postinstall.js

@@ -11,8 +11,8 @@ console.log(`
 🕌 Rihal Code installed.
 
 First-time setup:
-  npx @hanzlahabib/rihal-code install     # set up agents + slash commands
-  npx @hanzlahabib/rihal-code tiers       # see the tier map
+  npx @hanzlaa/rcode install     # set up agents + slash commands
+  npx @hanzlaa/rcode tiers       # see the tier map
 
 🌱 The Golden Path (say these phrases in your AI IDE):
   1. "scaffold a new project"     → rihal-scaffold-project
@@ -24,8 +24,8 @@ First-time setup:
   7. "sprint status"              → rihal-sprint-status
 
 More:
-  npx @hanzlahabib/rihal-code help        # all commands (grouped)
-  npx @hanzlahabib/rihal-code dashboard   # view-only Diwan on :7717
+  npx @hanzlaa/rcode help        # all commands (grouped)
+  npx @hanzlaa/rcode dashboard   # view-only Diwan on :7717
 
 Docs: https://github.com/hanzlahabib/rihal-code
 Tiers: docs/TIERS.md   ·   Standards: docs/STANDARDS.md

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@hanzlaa/rcode",
-  "version": "2.3.1",
-  "description": "Rihal Code (rcode) — installable context-brain for Rihalians. 44 agents, 93 slash commands, 58 skills, pullable Rihal standards. Unified install for Claude Code, Cursor, and Gemini.",
+  "version": "2.3.3",
+  "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": {
     "rcode": "dist/rcode.js",
+    "rihal": "dist/rcode.js",
     "rihal-code": "dist/rcode.js"
   },
   "scripts": {

package/rihal/agents/rihal-executor.md

@@ -9,6 +9,7 @@ color: yellow
 @.rihal/references/karpathy-guidelines-full.md
 @.rihal/references/output-realism.md
 @.rihal/references/no-unauthorized-git-ops.md
+@.rihal/brain/best-practices/no-theoretical-suggestions.md
 
 <role>
 Rihal sprint executor. Execute SPRINT.md files atomically, commit each story, handle deviations, pause at checkpoints, produce SUMMARY.md.

package/rihal/agents/rihal-phase-researcher.md

@@ -8,6 +8,7 @@ color: cyan
 
 @.rihal/references/response-style.md
 @.rihal/references/karpathy-guidelines.md
+@.rihal/brain/best-practices/no-theoretical-suggestions.md
 
 <role>
 You are a Rihal phase researcher. You answer "What do I need to know to PLAN this phase well?" and produce a single RESEARCH.md that the planner consumes.

package/rihal/agents/rihal-planner.md

@@ -8,6 +8,7 @@ color: green
 @.rihal/references/response-style.md
 @.rihal/references/karpathy-guidelines-full.md
 @.rihal/references/output-realism.md
+@.rihal/brain/best-practices/no-theoretical-suggestions.md
 
 <role>
 Rihal sprint planner. Create executable SPRINT.md files with story breakdown, dependency analysis, and goal-backward verification.
@@ -129,7 +130,7 @@ Output: [Artifacts created]
 </objective>
 
 <execution_context>
-@.rihal/workflows/execute-plan.md
+@.rihal/workflows/execute.md
 @.rihal/templates/summary.md
 </execution_context>
 

package/rihal/brain/best-practices/no-theoretical-suggestions.md

@@ -0,0 +1,56 @@
+# No Theoretical Suggestions Rule
+
+Referenced by all agents that propose plans, file changes, or implementation steps.
+
+## The Rule
+
+**Every suggestion, plan, or implementation step must be grounded in what actually exists in the codebase.** Never propose a change based on assumed structure, naming conventions, documentation, or what "probably" exists.
+
+## What This Means in Practice
+
+Before including any file path, function name, config key, or field in a plan:
+
+1. Confirm it exists — use `Read`, `grep`, `find`, or `glob`.
+2. If it doesn't exist, say so explicitly: "this doesn't exist yet."
+3. Only then decide whether to create it (if the user asked) or report the gap (if they didn't).
+
+## The Test
+
+Could every line of your plan be traced to a specific file and line number in the repo right now? If not, the plan contains theoretical content — do not ship it.
+
+## Failure Pattern to Avoid
+
+- Agent reads an investigation doc or workflow description.
+- Agent produces a plan based on what the doc *says* should exist.
+- Agent never verifies the described files/fields/functions actually exist.
+- Plan references symbols that are missing, misnamed, or not yet implemented.
+- Execution fails or produces wrong results.
+
+This pattern is forbidden. Investigation documents describe intent, not ground truth. Code is ground truth.
+
+## Correct Behavior
+
+```
+# WRONG — theoretical
+"Fix the force_web_search toggle in backend/config.py"
+(without checking if force_web_search actually exists in that file)
+
+# RIGHT — grounded
+grep -r "force_web_search" backend/
+→ no results
+→ "force_web_search doesn't exist in the codebase yet. The investigation doc was theoretical. Here's what actually exists: ..."
+```
+
+## When You Can't Find Something
+
+- Do NOT assume it's in a different file or under a different name.
+- Do NOT write a plan that assumes you'll find it later.
+- STOP and report: "I searched for X and found nothing. Either it doesn't exist yet or the investigation was theoretical."
+
+## Applies To
+
+- `rihal-planner` — every task in SPRINT.md must reference real files
+- `rihal-executor` — read the target file before writing any change
+- `rihal-phase-researcher` — cite actual code paths, not presumed ones
+- `rihal-sprint-checker` — flag plans that reference non-existent symbols
+- All council agents — proposals must name real constraints, not theoretical ones

package/rihal/commands/add-phase.md

@@ -1,7 +1,7 @@
 ---
 name: rihal:add-phase
-description: Execute add-phase workflow
-argument-hint: ""
+description: "Add a new integer phase to the end of the current milestone. Auto-calculates the next phase number, creates the phase directory, and updates ROADMAP.md. Use when scope expands mid-milestone."
+argument-hint: "<phase-name>"
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
 ---
 

package/rihal/commands/cleanup.md

@@ -1,7 +1,7 @@
 ---
 name: rihal:cleanup
-description: Execute cleanup workflow
-argument-hint: ""
+description: "Archive completed milestone phase directories into .planning/milestones/. Run after /rihal:complete-milestone to keep .planning/ tidy. Shows a dry-run summary before moving anything."
+argument-hint: "[--dry-run]"
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion, Agent
 ---
 

package/rihal/commands/pr-branch.md

@@ -1,7 +1,7 @@
 ---
 name: rihal:pr-branch
-description: Execute pr-branch workflow
-argument-hint: ""
+description: "Create a clean PR branch that strips all Rihal planning artifacts (.planning/, SPRINT.md, SUMMARY.md, STATE.md). Reviewers see only code changes. Use before /rihal:ship when you want a clean git history in the PR."
+argument-hint: "[<base-branch>]"
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
 ---
 

package/rihal/commands/remove-phase.md

@@ -1,7 +1,7 @@
 ---
 name: rihal:remove-phase
-description: Execute remove-phase workflow
-argument-hint: ""
+description: "Remove an unstarted future phase from ROADMAP.md, delete its directory, and renumber all subsequent phases to maintain a clean sequence. Cannot remove a phase already in progress or completed."
+argument-hint: "<phase-number>"
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
 ---
 

package/rihal/commands/research-phase.md

@@ -1,7 +1,7 @@
 ---
 name: rihal:research-phase
-description: Execute research-phase workflow
-argument-hint: ""
+description: "Research how to implement a phase before planning. Spawns rihal-phase-researcher with phase context. Standalone tool — /rihal:plan already runs this automatically. Use only when you want research without immediately creating a plan."
+argument-hint: "<phase-number>"
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
 ---
 

package/rihal/commands/ship.md

@@ -1,12 +1,24 @@
 ---
 name: rihal:ship
-description: Execute ship workflow
-argument-hint: ""
+description: "After a phase is verified, create a PR: push branch, auto-generate PR body from planning artifacts (ROADMAP, VERIFICATION, SUMMARY), and optionally request review. Closes the plan→execute→verify→ship loop."
+argument-hint: "[<phase>] [--draft]"
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
 ---
 
 <objective>
-Execute ship workflow
+Ship a completed, verified phase by pushing its feature branch and opening a
+pull request with an auto-generated body drawn from planning artifacts.
+
+**When to use:**
+- You have finished `/rihal:execute <phase>` and `/rihal:verify-phase <phase>` passed
+- You want to open a PR from your feature branch into main/develop
+- You want the PR body auto-filled with phase goal, changes, requirements addressed, and verification status
+
+**When NOT to use:**
+- Publishing a package to npm → use `npm publish` directly
+- Tagging a release → use `git tag` + `git push --tags`
+- You are inside the rihal-code framework repo itself (no phases exist here)
+- Your project uses `git.branching_strategy: none` and you commit directly to main
 </objective>
 
 <execution_context>

package/rihal/commands/validate-phase.md

@@ -1,7 +1,7 @@
 ---
 name: rihal:validate-phase
 description: Audit Nyquist validation gaps for a completed phase. Generate missing tests. Update VALIDATION.md.
-argument-hint: ""
+argument-hint: "<phase-number>"
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion, Agent
 ---
 

package/rihal/commands/verify-phase.md

@@ -1,7 +1,7 @@
 ---
 name: rihal:verify-phase
-description: Verify phase goal achievement through goal-backward analysis. Check that the codebase delivers what the phase promised, 
-argument-hint: ""
+description: "Goal-backward audit — does the codebase actually deliver what the phase promised? Produces VERIFICATION.md with pass/fail. Required before /rihal:ship. Run after /rihal:execute completes."
+argument-hint: "<phase-number>"
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion, Agent
 ---
 

package/rihal/skills/actions/1-analysis/research/rihal-domain-research/SKILL.md

@@ -7,8 +7,19 @@ description: >
   me understand X industry", or "domain research for". Do NOT use for market
   analysis (use rihal-market-research) or technical feasibility (use
   rihal-technical-research).
+triggers:
+  - "research this domain"
+  - "domain deep dive"
+  - "explain this industry"
+  - "help
+  me understand X industry"
+  - "domain research for"
 ---
 
+## Overview
+
+Conduct industry domain deep-dive research to build subject matter expertise on a specific business domain.
+
 ## Workflow
 
 Follow the instructions in ./workflow.md.

package/rihal/skills/actions/1-analysis/research/rihal-market-research/SKILL.md

@@ -6,8 +6,19 @@ description: >
   "competitive analysis", "market analysis for", "size the market",
   "competitor scan", or "analyze the market for X". Do NOT use for domain
   deep-dives (use rihal-domain-research) or technical feasibility.
+triggers:
+  - "market research"
+  - "competitive analysis"
+  - "market analysis for"
+  - "size the market"
+  - "competitor scan"
+  - "analyze the market for X"
 ---
 
+## Overview
+
+Analyze market size, competitive landscape, customer needs, and trends for a product or industry.
+
 ## Workflow
 
 Follow the instructions in ./workflow.md.

package/rihal/skills/actions/1-analysis/research/rihal-technical-research/SKILL.md

@@ -7,8 +7,21 @@ description: >
   options", "how would we build X", "what stack for", or "technical
   feasibility for". Do NOT use for final architecture decisions (use
   rihal-create-architecture) or market analysis.
+triggers:
+  - "technical research"
+  - "feasibility study"
+  - "research implementation
+  options"
+  - "how would we build X"
+  - "what stack for"
+  - "technical
+  feasibility for"
 ---
 
+## Overview
+
+Research technical feasibility, architecture options, and implementation approaches for a proposed product or feature.
+
 ## Workflow
 
 Follow the instructions in ./workflow.md.

package/rihal/skills/actions/1-analysis/rihal-document-project/SKILL.md

@@ -6,8 +6,19 @@ description: >
   "document this project", "analyze this codebase", "generate docs for
   existing code", "brownfield analysis", or "create LLM-friendly docs". Do
   NOT use for writing net-new docs (use write-document prompt).
+triggers:
+  - "document this project"
+  - "analyze this codebase"
+  - "generate docs for
+  existing code"
+  - "brownfield analysis"
+  - "create LLM-friendly docs"
 ---
 
+## Overview
+
+Analyze an existing codebase and produce documentation for both human and LLM consumption (brownfield analysis).
+
 ## Workflow
 
 Follow the instructions in ./workflow.md.

package/rihal/skills/actions/1-analysis/rihal-prfaq/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: rihal-prfaq
 description: Working Backwards PRFAQ challenge to forge product concepts. Use when the user requests to 'create a PRFAQ', 'work backwards', or 'run the PRFAQ challenge'.
+triggers:
+  - "prfaq"
 ---
 
 ## Do NOT use this skill for

package/rihal/skills/actions/1-analysis/rihal-product-brief/SKILL.md

@@ -6,6 +6,13 @@ description: >
   brief", "draft a brief for", "product briefing", or "create the brief". Do
   NOT use for full PRD (use rihal-create-prd) or market analysis alone (use
   rihal-market-research).
+triggers:
+  - "create a product brief"
+  - "write a product
+  brief"
+  - "draft a brief for"
+  - "product briefing"
+  - "create the brief"
 ---
 
 ## Workflow

package/rihal/skills/actions/2-plan/rihal-create-epics-and-stories/SKILL.md

@@ -6,8 +6,20 @@ description: >
   the epic list", "epic and story breakdown", "decompose the PRD", or
   "create the backlog". Do NOT use to prepare a single story for dev (use
   rihal-create-story).
+triggers:
+  - "create epics"
+  - "break this into stories"
+  - "generate
+  the epic list"
+  - "epic and story breakdown"
+  - "decompose the PRD"
+  - "create the backlog"
 ---
 
+## Overview
+
+Break a PRD into epics and user stories that drive development.
+
 ## Workflow
 
 Follow the instructions in ./workflow.md.

package/rihal/skills/actions/2-plan/rihal-create-milestone/SKILL.md

@@ -8,8 +8,20 @@ description: >
   lifecycle (use rihal-new-milestone / rihal-complete-milestone), for
   decomposing one milestone into epics (use rihal-create-epics-and-stories),
   or for single-phase planning (use rihal-plan-phase).
+triggers:
+  - "create milestones"
+  - "plan milestones"
+  - "create roadmap"
+  - "what milestones do I need"
+  - "break this project into
+  milestones"
+  - "roadmap for this product"
 ---
 
+## Overview
+
+Design the milestone roadmap (M1..Mn) for a project from an approved PRD.
+
 Follow the instructions in ./workflow.md.
 
 ## Output Format
@@ -22,6 +34,12 @@ Follow the instructions in ./workflow.md.
 - Do NOT include: unquantified success language ("grow the user base"), open-ended milestones without dates, or more than 6 active milestones in one roadmap (split into v1/v2 if needed)
 - If a milestone goal cannot be expressed as a single verifiable sentence, split it into two milestones
 
+## Workflow
+
+1. Read the user request and extract key parameters.
+2. Execute the skill logic as described in the Overview.
+3. Return output in the format specified below.
+
 ## Examples
 
 ### Happy Path

package/rihal/skills/actions/2-plan/rihal-create-prd/SKILL.md

@@ -7,8 +7,21 @@ description: >
   "draft requirements for", "new product spec", or "start a PRD". Do NOT use
   for updating an existing PRD (use rihal-edit-prd), or validating an
   existing PRD (use rihal-validate-prd).
+triggers:
+  - "create a PRD"
+  - "write product
+  requirements document"
+  - "lets make a PRD"
+  - "I want to create a new PRD"
+  - "draft requirements for"
+  - "new product spec"
+  - "start a PRD"
 ---
 
+## Overview
+
+Create a new Product Requirements Document from scratch through guided facilitation.
+
 ## Workflow
 
 Follow the instructions in ./workflow.md.

package/rihal/skills/actions/2-plan/rihal-create-story/SKILL.md

@@ -6,8 +6,20 @@ description: >
   story {id}", "write the story for", "get next story ready for dev", or
   "assemble story context". Do NOT use to execute a story (use
   rihal-dev-story).
+triggers:
+  - "create the next story"
+  - "prepare a story"
+  - "create
+  story {id}"
+  - "write the story for"
+  - "get next story ready for dev"
+  - "assemble story context"
 ---
 
+## Overview
+
+Prepare a dev-ready user story with full implementation context.
+
 ## Workflow
 
 Follow the instructions in ./workflow.md.

package/rihal/skills/actions/2-plan/rihal-create-ux-design/SKILL.md

@@ -6,8 +6,20 @@ description: >
   when the user says "create UX design", "design the user flow", "wireframe
   this", "UX plan", "design this screen", or "create the design for". Do NOT
   use for UI code (use rihal-dev-story) or visual code review.
+triggers:
+  - "create UX design"
+  - "design the user flow"
+  - "wireframe
+  this"
+  - "UX plan"
+  - "design this screen"
+  - "create the design for"
 ---
 
+## Overview
+
+Guide through realizing a UX design that informs architecture and implementation — user flows, wireframes, design system updates.
+
 ## Workflow
 
 Follow the instructions in ./workflow.md.

package/rihal/skills/actions/2-plan/rihal-edit-prd/SKILL.md

@@ -6,8 +6,19 @@ description: >
   PRD", "edit the PRD", "add a section to the PRD", "revise requirements",
   or "change the scope in the PRD". Do NOT use to create a new PRD (use
   rihal-create-prd) or to validate quality (use rihal-validate-prd).
+triggers:
+  - "update the
+  PRD"
+  - "edit the PRD"
+  - "add a section to the PRD"
+  - "revise requirements"
+  - "change the scope in the PRD"
 ---
 
+## Overview
+
+Update an existing Product Requirements Document with new sections, revisions, or clarifications.
+
 ## Workflow
 
 Follow the instructions in ./workflow.md.

package/rihal/skills/actions/2-plan/rihal-frontend-design/SKILL.md

@@ -14,6 +14,19 @@ description: >
   and rihal-agent-zahra (branding expert) for brand alignment. Do
   NOT use for: cloning existing sites (use rihal-clone-website
   instead), pure backend work, or documentation.
+triggers:
+  - "AI slop"
+  - "design this UI"
+  - "build a beautiful frontend"
+  - "distinctive design"
+  - "creative UI"
+  - "unforgettable interface"
+  - "award-winning design"
+  - "not generic"
+  - "bold aesthetic"
+  - "brutalist"
+  - "editorial"
+  - "maximalist"
 license: Adapted from Anthropic's frontend-design skill
 ---
 

package/rihal/skills/actions/2-plan/rihal-validate-prd/SKILL.md

@@ -5,8 +5,20 @@ description: >
   and internal consistency. Activates when the user says "validate the PRD",
   "review the PRD", "check the PRD", "is the PRD ready", "PRD quality
   check", or "audit the PRD". Do NOT use to create or edit a PRD.
+triggers:
+  - "validate the PRD"
+  - "review the PRD"
+  - "check the PRD"
+  - "is the PRD ready"
+  - "PRD quality
+  check"
+  - "audit the PRD"
 ---
 
+## Overview
+
+Validate an existing PRD for comprehensiveness, leanness, organization, and internal consistency.
+
 ## Workflow
 
 Follow the instructions in ./workflow.md.

package/rihal/skills/actions/3-solutioning/rihal-check-implementation-readiness/SKILL.md

@@ -6,8 +6,20 @@ description: >
   "check implementation readiness", "is this ready for dev", "verify
   alignment", "readiness check", "IR check", or "can we start building". Do
   NOT use during active implementation (use rihal-correct-course instead).
+triggers:
+  - "check implementation readiness"
+  - "is this ready for dev"
+  - "verify
+  alignment"
+  - "readiness check"
+  - "IR check"
+  - "can we start building"
 ---
 
+## Overview
+
+Verify that PRD, UX designs, architecture decisions, and epics/stories are all aligned and ready for implementation.
+
 ## Workflow
 
 Follow the instructions in ./workflow.md.

package/rihal/skills/actions/3-solutioning/rihal-create-architecture/SKILL.md

@@ -7,8 +7,22 @@ description: >
   architecture record", "lock this technical decision", or "record the
   decision to use X". Do NOT use for implementation code (use
   rihal-dev-story) or sprint planning (use rihal-sprint-planning).
+triggers:
+  - "write an ADR"
+  - "create
+  architecture decision"
+  - "document this architectural choice"
+  - "write an
+  architecture record"
+  - "lock this technical decision"
+  - "record the
+  decision to use X"
 ---
 
+## Overview
+
+Write an Architecture Decision Record (ADR) to lock a significant technical decision.
+
 ## Workflow
 
 Follow the instructions in ./workflow.md.

package/rihal/skills/actions/3-solutioning/rihal-generate-project-context/SKILL.md

@@ -7,8 +7,20 @@ description: >
   file", "document project conventions", "setup AI context", or "create
   project-context.md". Do NOT use for full project documentation (use
   rihal-document-project).
+triggers:
+  - "generate project context"
+  - "create context
+  file"
+  - "document project conventions"
+  - "setup AI context"
+  - "create
+  project-context.md"
 ---
 
+## Overview
+
+Generate a project-context.md file that summarizes project standards, conventions, tech stack, and key patterns for AI agents to reference.
+
 ## Workflow
 
 Follow the instructions in ./workflow.md.