@hanzlaa/rcode 2.2.0 → 2.3.1

package/CONTRIBUTING.md

@@ -4,6 +4,144 @@ Thank you for contributing. These guidelines exist to keep the module maintainab
 
 ---
 
+## Architecture overview — what are all these files?
+
+Before you touch anything, you need a mental model of how the four building blocks fit together. Every feature in Rihal Code is assembled from the same four pieces.
+
+### The four building blocks
+
+| Layer | Where | What it is |
+|-------|-------|-----------|
+| **Command** | `rihal/commands/*.md` | The slash command entry point — what you type in Claude Code |
+| **Workflow** | `rihal/workflows/*.md` | Step-by-step orchestration instructions for multi-step tasks |
+| **Skill** | `rihal/skills/actions/*/SKILL.md` | Deep, domain-specific instructions for complex multi-stage tasks |
+| **Agent** | `rihal/agents/*.md` + `rihal/skills/agents/*/SKILL.md` | A specialized persona spawned by a workflow or skill to do focused work |
+
+### Commands — the entry point
+
+A command file is tiny. It registers a slash command in Claude Code's UI and points at the logic that handles it:
+
+```markdown
+---
+name: rihal:prfaq
+description: Working Backwards PRFAQ challenge
+allowed-tools: [Read, Write, Agent, AskUserQuestion, WebSearch]
+---
+
+@.rihal/skills/rihal-prfaq/SKILL.md
+```
+
+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`.
+
+### 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
+```
+
+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.
+
+### Skills — deep domain knowledge
+
+Skills go deeper than workflows. A skill like `rihal-prfaq` has its own folder with multi-stage reference files, sub-agent definitions, and templates:
+
+```
+rihal/skills/actions/1-analysis/rihal-prfaq/
+├── SKILL.md                   ← main entry, loaded by the command
+├── references/
+│   ├── press-release.md       ← Stage 2 instructions
+│   ├── customer-faq.md        ← Stage 3
+│   ├── internal-faq.md        ← Stage 4
+│   └── verdict.md             ← Stage 5
+├── agents/
+│   ├── artifact-analyzer.md   ← sub-agent spawned inline
+│   └── web-researcher.md
+└── assets/
+    └── prfaq-template.md
+```
+
+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
+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
+
+Agents are spawned by workflows and skills to do a specific job. They have a persona, a set of tools, and deferral rules (Hanzla defers to Waleed on architecture; Waleed defers to Sadiq on whether to build).
+
+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.
+
+### How they chain for a real request
+
+```
+User types:  /rihal:council "Should we use Redis?"
+                   │
+         commands/council.md          ← slash command entry
+                   │ @-includes
+         workflows/council.md         ← orchestration: pick agents, frame question
+                   │ spawns (parallel)
+        ┌──────────┴───────────────┐
+        ▼                          ▼
+  agents/rihal-waleed.md     agents/rihal-sadiq.md
+  (architecture answer)      (strategic kill criteria)
+        └──────────┬───────────────┘
+                   ▼
+        synthesize → output to user
+```
+
+A more complex chain involving a skill:
+
+```
+User types:  /rihal:prfaq
+                   │
+         commands/prfaq.md
+                   │ @-includes
+         skills/rihal-prfaq/SKILL.md   ← Stage 1: ignition + context gathering
+                   │ spawns (parallel)
+        ┌──────────┴────────────────────┐
+        ▼                               ▼
+  skills/.../artifact-analyzer.md   skills/.../web-researcher.md
+        └──────────┬────────────────────┘
+                   ▼
+         references/press-release.md    ← Stage 2: loaded by SKILL.md
+         references/customer-faq.md     ← Stage 3
+         references/verdict.md          ← Stage 5: output + PRD distillate
+```
+
+### Which layer do I edit?
+
+| I want to… | Edit this |
+|-----------|-----------|
+| 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 |
+| 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 |
+
+### The install chain
+
+The source tree in `rihal/` is **not what Claude reads at runtime**. On install, `cli/install.js` copies everything into `.rihal/` and `.claude/`. When a command `@-includes` `.rihal/workflows/audit.md`, it's reading the installed copy. If you edit the source but don't reinstall, Claude still sees the old version.
+
+```bash
+# After editing source files:
+node cli/install.js . --force-overwrite --yes
+```
+
+This is why the compliance check runs against the source tree but the reload window step (after install) is what actually activates your changes.
+
+---
+
 ## Who owns what — contribute to YOUR slice
 
 Rihal Code v2 is organized around **role ownership** (issue #160). Find your role, touch only that slice, open a focused PR. CODEOWNERS in `.github/CODEOWNERS` routes reviews automatically.

package/README.md

@@ -37,8 +37,8 @@ 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.**
 
-- **44 agents** with clear roles, cultural identity (Arabic names), and hard scope boundaries
-- **93 slash commands** covering research, planning, execution, verification, and recovery
+- **45 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
 - **Intent guards** on every workflow — catch wrong commands early with copy-paste redirects
@@ -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/` — 44 first-class subagents
-- `.claude/commands/rihal/` — 93 slash commands
-- `.claude/skills/` — 58 phrase-activated skills (scaffold-project, create-prd, retrospective, etc.)
+- `.claude/agents/` — 45 first-class subagents
+- `.claude/commands/rihal/` — 99 slash commands
+- `.claude/skills/` — 57 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)
 
@@ -236,6 +236,17 @@ The classifier recognizes `dubai`, `affiliate`, `bnanai`, `karobar`, `site banan
 → 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`.
+
+**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
+```
+
 ### Karpathy coding guidelines
 
 4 behavioral principles from [Andrej Karpathy's observations on LLM coding pitfalls](https://github.com/forrestchang/andrej-karpathy-skills), wired into every code-writing agent as hard constraints:
@@ -245,7 +256,7 @@ The classifier recognizes `dubai`, `affiliate`, `bnanai`, `karobar`, `site banan
 3. **Surgical changes** — touch only what's needed, match existing style
 4. **Goal-driven execution** — define verifiable success criteria
 
-Audit recent changes:
+`/rihal:karpathy-audit` 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:karpathy-audit HEAD~5..HEAD
@@ -298,7 +309,7 @@ Recent additions in this session:
 
 ---
 
-## Full command surface (69 commands)
+## Full command surface (99 commands)
 
 ### Router + lifecycle
 `init` · `do` · `help` · `status` · `stats` · `health` · `forensics` · `update`
@@ -306,14 +317,17 @@ Recent additions in this session:
 ### Discovery + research
 `new-project` · `map-codebase` · `scan` · `explore` · `document-project` · `analyze-dependencies` · `discuss-phase-power`
 
+### Discovery + validation
+`prfaq` · `brainstorm` · `market-research` · `domain-research` · `technical-research` · `product-brief`
+
 ### Planning
-`plan` · `chain` · `create-epics-and-stories` · `create-story` · `dev-story` · `sprint-planning` · `brainstorm`
+`plan` · `chain` · `create-epics-and-stories` · `create-story` · `dev-story` · `sprint-planning`
 
 ### Execution
 `execute` · `quick` · `autonomous` · `audit-fix` · `undo` · `check-implementation-readiness`
 
 ### Observability + review
-`code-review` · `code-review-fix` · `review-adversarial` · `review-edge-case-hunter` · `karpathy-audit` · `secure-phase` · `show` · `why` · `rerun` · `diff`
+`code-review` · `code-review-fix` · `review-adversarial` · `review-edge-case-hunter` · `karpathy-audit` · `checkpoint-preview` · `secure-phase` · `show` · `why` · `rerun` · `diff`
 
 ### Recovery + correction
 `pause-work` · `resume-work` · `correct-course` · `next` · `config`
@@ -402,16 +416,61 @@ Full install = all 3 modules = 201 files.
 ## Testing
 
 ```bash
-node --test test/*.cjs test/lib/*.cjs
+node --test          # full suite (95 tests, ~1s)
+node --test --test-reporter=spec   # verbose output with test names
 ```
 
-95 tests across 10 test files (8 compliance + 87 unit) verify:
-- Every command has a matching workflow file
-- Every agent has valid frontmatter + constraints
-- Module manifests match installed files
-- rihal-tools.cjs help matches implemented subcommands
-- Panel scorer routes correctly across 10+ question types
-- Classifier handles Roman Urdu + Arabic + edge cases
+**95 tests · 0 failures · pure Node stdlib (no test runner install needed)**
+
+### Test scenarios
+
+| Suite | Tests | What it verifies |
+|-------|-------|-----------------|
+| `compliance.test.cjs` | 8 | Architecture invariants — every command routes through a workflow, every agent has valid frontmatter, all module manifests resolve, `rihal-tools.cjs` subcommands match help text |
+| `classifier.test.cjs` | 10 | Question classifier handles Roman Urdu, Arabic (unicode), English, ambiguous, and multilingual inputs; routes to correct intent (greenfield / market / codebase) |
+| `panel-scorer.test.cjs` | 12 | Council panel scorer selects correct agents for market, greenfield, and codebase questions; `--agents` override bypasses scoring; `--full` returns all agents |
+| `lib/config.test.cjs` | 15 | Config loader merges hardcoded → user → project layers; validates enum values; `suggestClosest` catches typos |
+| `lib/fsutil.test.cjs` | 8 | `writeFileAtomic` creates parents, overwrites cleanly, leaves no temp files, handles custom chmod modes |
+| `lib/manifest.test.cjs` | 12 | `readPackageManifest` discovers agents/actions; `verifyClaudeInstall` detects drift; `verifyInstall` aggregates multi-editor state |
+| `lib/memory-bank.test.cjs` | 10 | Fingerprint stability, staleness detection on hash change and structure change, `never/stale/fresh` thresholds |
+| `lib/prompts.test.cjs` | 15 | `askText`, `askConfirm`, `askChoice` in piped (CI) mode; re-prompt on bad input; `PromptAbortError` on max attempts; `closeSession` idempotency |
+| `lib/no-absolute-home-paths.test.cjs` | 3 | No slash command template embeds absolute `$HOME` paths (install portability) |
+| `lib/wizard-piped.test.cjs` | 2 | Full install in piped mode against temp dir; every known slash command installs non-empty |
+
+### Post-install health check
+
+Every install runs 5 automated smoke tests before exiting:
+
+```
+  Health check:
+    ✓ rihal-tools.cjs runs — syntax ok
+    ✓ .rihal/config.yaml present — 412 bytes
+    ✓ .rihal/state.json parses — valid JSON
+    ✓ agents installed — 43
+    ✓ skills + commands installed — 56 skills + 99 commands
+```
+
+A failed check prints the debug command and returns exit code 1 so CI catches broken installs.
+
+### CI pipeline
+
+Three jobs run on every push and pull request to `main`:
+
+| Job | What it checks |
+|-----|----------------|
+| `test` | Runs `node --test` on Node 18, 20, 22, and 24 — no `npm install` needed |
+| `no-new-deps` | Blocks any addition to `dependencies{}` (runtime zero-dep invariant); audits `devDependencies` against approved build-tool list |
+| `syntax-check` | `node -c` on every file in `cli/` to catch parse errors before runtime |
+
+The release pipeline additionally runs `npm ci && npm run build:cli` to produce `dist/rcode.js` (the self-contained esbuild bundle published to npm), then runs a compliance check and attaches the artefact to the GitHub Release.
+
+### Run a single suite
+
+```bash
+node --test test/compliance.test.cjs     # architecture invariants only
+node --test test/lib/config.test.cjs     # config layer only
+node --test test/lib/manifest.test.cjs   # install verification only
+```
 
 ---