@hanzlaa/rcode 3.4.30 → 3.4.32

package/AGENTS.md

@@ -24,7 +24,7 @@ If a user says "just keep going" or "don't stop until done", that authorization
 
 - Follow [Conventional Commits](https://www.conventionalcommits.org/) format: `type(scope): subject`
 - Types allowed: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `perf`, `revert`
-- Scopes allowed: `agents`, `skills`, `workflows`, `templates`, `dashboard`, `docs`, `config`, `github`, `commands`, `memory`, `brand`, `cli`, `ci`, `release`, `meta`, `tasks`, `migrations`, `refs`, `state`, `hooks`, `install`, `parity`, `triggers`, `dogfood`, `namespace`, `planning`, `insights`, `help`, `roadmap`, `session`, `audits`, `execute`, `executor`, `plan`, `planner`, `readme`, `sync`, `sprint`, `agent-exp`, `extensibility`, `lens-audit`, `tiers`, `build`, `council`, `doctor`, `postinstall`, `progress`, `security`, `tools`, `uninstall`, `update`, `test`, plus numeric phase/sprint scopes (e.g. `docs(15)`, `feat(8.3)`)
+- Scopes allowed: `agents`, `skills`, `workflows`, `templates`, `dashboard`, `docs`, `config`, `github`, `commands`, `memory`, `brand`, `cli`, `ci`, `release`, `meta`, `tasks`, `migrations`, `refs`, `state`, `hooks`, `install`, `parity`, `triggers`, `dogfood`, `namespace`, `planning`, `insights`, `help`, `roadmap`, `session`, `audits`, `execute`, `executor`, `plan`, `planner`, `readme`, `sync`, `sprint`, `agent-exp`, `extensibility`, `lens-audit`, `tiers`, `build`, `council`, `doctor`, `postinstall`, `progress`, `security`, `tools`, `uninstall`, `update`, `test`, `changelog`, `scopes`, `phases`, `references`, plus numeric phase/sprint scopes (e.g. `docs(15)`, `feat(8.3)`)
 - Subject: lowercase first letter, imperative mood, no trailing period, under 72 chars
 - **NEVER add Claude/AI attribution to commit messages.** No "Generated with Claude Code", no "Co-Authored-By: Claude", no "🤖 Generated". The user does not want this.
 - **NEVER use `--no-verify`** to bypass hooks. If hooks fail, fix the underlying issue.

package/CLAUDE.md

@@ -24,7 +24,7 @@ If a user says "just keep going" or "don't stop until done", that authorization
 
 - Follow [Conventional Commits](https://www.conventionalcommits.org/) format: `type(scope): subject`
 - Types allowed: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `perf`, `revert`
-- Scopes allowed: `agents`, `skills`, `workflows`, `templates`, `dashboard`, `docs`, `config`, `github`
+- Scopes allowed: `agents`, `skills`, `workflows`, `templates`, `dashboard`, `docs`, `config`, `github`, `phases`, `references`, `cli`
 - Subject: lowercase first letter, imperative mood, no trailing period, under 72 chars
 - **NEVER add Claude/AI attribution to commit messages.** No "Generated with Claude Code", no "Co-Authored-By: Claude", no "🤖 Generated". The user does not want this.
 - **NEVER use `--no-verify`** to bypass hooks. If hooks fail, fix the underlying issue.

package/CONTRIBUTING.md

@@ -207,6 +207,23 @@ When you add a new agent to `rihal/team.yaml`, update **all** of these locations
 
 Run `node --test` before opening a PR.
 
+### Agent File Size Rule
+
+**If your agent file body exceeds 100 lines, you MUST extract the playbook to `rihal/references/`.**
+
+Pattern:
+1. Create `rihal/references/<name>-playbook.md` with the extracted content
+2. Replace the extracted content in the agent file with `@.rihal/references/<name>-playbook.md`
+3. Target: agent stub ≤100 lines (frontmatter + @-includes + short role description)
+
+This rule exists because subagent spawning loads the full agent `.md` body into the model context.
+Static playbook content (checklists, step-by-step flows, output templates) can be 70-77% of a
+heavy agent — extracting it via `@-include` saves context budget on every spawn.
+
+Accepted exceptions (document in VERIFICATION.md when you create them):
+- `rihal-nyquist-auditor.md` (176L) — load-bearing XML execution blocks
+- `rihal-docs-auditor.md` (173L) — load-bearing JSON schema for `/rihal-feature-drift`
+
 ---
 
 ## 🚨 Critical Rule — Never Auto-Push
@@ -308,6 +325,10 @@ We use [Conventional Commits](https://www.conventionalcommits.org/) format. The
 - `tools` — `rihal/bin/rihal-tools.cjs` subcommands
 - `uninstall` — `cli/uninstall.js` flow
 - `update` — `cli/update.js` flow
+- `changelog` — CHANGELOG.md edits
+- `scopes` — AGENTS.md / CONTRIBUTING.md scope-list maintenance
+- `phases` — `.planning/phases/` artifacts (SPRINT.md, SUMMARY.md, VERIFICATION.md)
+- `references` — files inside `rihal/references/` (extracting agent playbooks to references)
 - `<phase-id>` — numeric phase scope when committing inside a phase (e.g. `docs(15)`, `feat(8.3)`)
 - `<sprint-id>` — numeric sprint scope inside a phase (e.g. `feat(15.1)`)
 

package/cli/agent.js

@@ -0,0 +1,56 @@
+/**
+ * rcode agent <name> — launch a specialist agent via claude --agent rihal-<name>
+ */
+
+const { spawnSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+module.exports = function agent(args, { packageRoot }) {
+  const agentDir = path.join(packageRoot, 'rihal/agents');
+
+  // --list or zero args: enumerate available agents
+  if (args.includes('--list') || args.length === 0) {
+    const names = fs.readdirSync(agentDir)
+      .filter(f => f.startsWith('rihal-') && f.endsWith('.md'))
+      .map(f => f.replace(/^rihal-/, '').replace(/\.md$/, ''))
+      .sort();
+    if (args.length === 0) {
+      console.log('Usage: rcode agent <name> [-- extra args]\n');
+    }
+    console.log(`Available agents (${names.length}):\n`);
+    names.forEach(n => console.log(`  rcode agent ${n}`));
+    return;
+  }
+
+  const name = args[0];
+  const agentName = `rihal-${name}`;
+
+  // Validate agent file exists
+  const agentFile = path.join(agentDir, `${agentName}.md`);
+  if (!fs.existsSync(agentFile)) {
+    const available = fs.readdirSync(agentDir)
+      .filter(f => f.startsWith('rihal-') && f.endsWith('.md'))
+      .map(f => f.replace(/^rihal-/, '').replace(/\.md$/, ''))
+      .sort()
+      .join(', ');
+    console.error(`Error: No agent named '${agentName}' found.`);
+    console.error(`Available: ${available}`);
+    process.exit(1);
+  }
+
+  // Check claude binary is on PATH
+  const claudeCheck = spawnSync('which', ['claude'], { encoding: 'utf8' });
+  if (claudeCheck.status !== 0) {
+    console.error('Error: claude binary not found. Install Claude Code: https://claude.ai/code');
+    process.exit(1);
+  }
+
+  // Collect pass-through args after -- separator
+  const dashIdx = args.indexOf('--');
+  const extra = dashIdx !== -1 ? args.slice(dashIdx + 1) : [];
+
+  // Spawn claude --agent rihal-<name> [extra...]
+  const result = spawnSync('claude', ['--agent', agentName, ...extra], { stdio: 'inherit' });
+  process.exit(result.status ?? 0);
+};

package/cli/generate-command-skills.cjs

@@ -27,29 +27,30 @@ 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.
+ * Curated list of commands that get skill stubs.
+ *
+ * Issue #710: sidebar-stub bloat. The picker has a token budget for skill
+ * descriptions; every stub here counts. Pre-#710 this list had 43 entries —
+ * the user hit "491 descriptions dropped" because rcode + plugins blew the
+ * budget. Trimmed to the minimum set users actually pick from the sidebar:
+ * navigation + the verb-style commands they invoke daily.
+ *
+ * Everything else stays reachable via `/` autocomplete (claude-code reads
+ * .claude/commands/ for slash dispatch — sidebar stubs are UX sugar, not
+ * functional). Power users running niche commands like /rihal-prfaq or
+ * /rihal-ui-phase still get them — they just don't show up in the sidebar.
  */
 const SIDEBAR_COMMANDS = new Set([
-  // Navigation & status
-  'do', 'status', 'progress', 'next', 'health',
-  // Core planning & execution
-  'plan', 'execute', 'add-phase', 'discuss-phase', 'complete-milestone',
-  'plan-milestone-gaps', 'autonomous',
-  // Project setup
-  'new-project', 'new-milestone', 'milestone-summary',
-  // Sprint workflow
-  'sprint-planning', 'sprint-status', 'execute-sprint', 'dev-story',
-  'create-story', 'create-epics-and-stories',
-  // Discussion & council
-  'council', 'discuss', 'prfaq',
-  // Quality & review
-  'ship', 'audit', 'verify-phase', 'verify-work', 'review', 'code-review',
-  'feature-drift', 'ui-phase', 'ui-review',
+  // Navigation & status (the daily check-in)
+  'do', 'status', 'next',
+  // Core lifecycle (the workflow loop)
+  'plan', 'execute', 'ship',
+  // Strategic
+  'council',
+  // Quality gate
+  'audit', 'verify-phase',
   // Utility
-  'debug', 'session-report', 'forensics', 'map-codebase', 'quick',
-  'note', 'add-todo', 'check-todos', 'pause-work', 'resume-work',
+  'note',
 ]);
 
 function parseFrontmatter(text) {

package/cli/index.js

@@ -8,6 +8,7 @@
  *   npx @hanzlaa/rcode serve         → alias for dashboard
  *   npx @hanzlaa/rcode digest        → print compact agent digests
  *   npx @hanzlaa/rcode team          → list the team roster
+ *   npx @hanzlaa/rcode agent <name>    → launch a specialist agent directly
  *   npx @hanzlaa/rcode doctor        → compliance check
  *   npx @hanzlaa/rcode version       → print version
  *   npx @hanzlaa/rcode help          → this message
@@ -30,6 +31,7 @@ const COMMANDS = {
   serve: require('./dashboard'),
   digest: require('./digest'),
   team: require('./team'),
+  agent: require('./agent'),
   doctor: require('./doctor'),
   'set-profile': require('./set-profile'),
   'set-mode': require('./set-mode'),
@@ -69,6 +71,8 @@ Usage:
 👥 TEAM
   team           List the team roster
   digest         Print compact digests for all agents
+  agent <name>   Launch a specialist agent directly (bypasses orchestration)
+                 rcode agent --list   to see available agents
   show-model     Show which model each agent uses in the current profile
   dashboard      Start the Diwan view-only dashboard (port 7717)
   serve          Alias for dashboard

package/dist/rcode.js

@@ -18877,6 +18877,46 @@ For full agent details: cat rihal/digests/{agent}.md`);
   }
 });
 
+// cli/agent.js
+var require_agent = __commonJS({
+  "cli/agent.js"(exports2, module2) {
+    var { spawnSync } = require("child_process");
+    var fs2 = require("fs");
+    var path2 = require("path");
+    module2.exports = function agent(args, { packageRoot }) {
+      const agentDir = path2.join(packageRoot, "rihal/agents");
+      if (args.includes("--list") || args.length === 0) {
+        const names = fs2.readdirSync(agentDir).filter((f) => f.startsWith("rihal-") && f.endsWith(".md")).map((f) => f.replace(/^rihal-/, "").replace(/\.md$/, "")).sort();
+        if (args.length === 0) {
+          console.log("Usage: rcode agent <name> [-- extra args]\n");
+        }
+        console.log(`Available agents (${names.length}):
+`);
+        names.forEach((n) => console.log(`  rcode agent ${n}`));
+        return;
+      }
+      const name = args[0];
+      const agentName = `rihal-${name}`;
+      const agentFile = path2.join(agentDir, `${agentName}.md`);
+      if (!fs2.existsSync(agentFile)) {
+        const available = fs2.readdirSync(agentDir).filter((f) => f.startsWith("rihal-") && f.endsWith(".md")).map((f) => f.replace(/^rihal-/, "").replace(/\.md$/, "")).sort().join(", ");
+        console.error(`Error: No agent named '${agentName}' found.`);
+        console.error(`Available: ${available}`);
+        process.exit(1);
+      }
+      const claudeCheck = spawnSync("which", ["claude"], { encoding: "utf8" });
+      if (claudeCheck.status !== 0) {
+        console.error("Error: claude binary not found. Install Claude Code: https://claude.ai/code");
+        process.exit(1);
+      }
+      const dashIdx = args.indexOf("--");
+      const extra = dashIdx !== -1 ? args.slice(dashIdx + 1) : [];
+      const result = spawnSync("claude", ["--agent", agentName, ...extra], { stdio: "inherit" });
+      process.exit(result.status ?? 0);
+    };
+  }
+});
+
 // cli/lib/memory-bank.cjs
 var require_memory_bank = __commonJS({
   "cli/lib/memory-bank.cjs"(exports2, module2) {
@@ -21328,6 +21368,7 @@ var COMMANDS = {
   serve: require_dashboard(),
   digest: require_digest(),
   team: require_team(),
+  agent: require_agent(),
   doctor: require_doctor(),
   "set-profile": require_set_profile(),
   "set-mode": require_set_mode(),
@@ -21366,6 +21407,8 @@ Usage:
 \u{1F465} TEAM
   team           List the team roster
   digest         Print compact digests for all agents
+  agent <name>   Launch a specialist agent directly (bypasses orchestration)
+                 rcode agent --list   to see available agents
   show-model     Show which model each agent uses in the current profile
   dashboard      Start the Diwan view-only dashboard (port 7717)
   serve          Alias for dashboard

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzlaa/rcode",
-  "version": "3.4.30",
+  "version": "3.4.32",
   "description": "rcode — the memory bank for AI-driven SaaS teams. Persistent project context, distinctive engineering personas, and phase-based workflows. Built by Rihal. Works in Claude Code, Cursor, Gemini, VS Code, and Antigravity.",
   "main": "cli/index.js",
   "bin": {

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

@@ -6,8 +6,7 @@ color: cyan
 ---
 
 @.rihal/references/response-style.md
-
-
+@.rihal/references/researcher-shared.md
 
 <role>
 You are a Rihal advisor researcher. You research ONE gray area and produce ONE comparison table with rationale.
@@ -71,31 +70,9 @@ Return EXACTLY this structure:
 - **Recommendation:** Conditional recommendation (e.g., "Rec if mobile-first", "Rec if SEO matters"). NEVER single-winner ranking.
 </output_format>
 
-<rules>
-1. **Complexity = impact surface + risk** (e.g., "3 files, new dep -- Risk: memory, scroll state"). NEVER time estimates.
-2. **Recommendation = conditional** ("Rec if mobile-first", "Rec if SEO matters"). Not single-winner ranking.
-3. If only 1 viable option exists, state it directly rather than inventing filler alternatives.
-4. Use the agent's knowledge + Context7 + web search to verify current best practices.
-5. Focus on genuinely viable options -- no padding.
-6. Do NOT include extended analysis -- table + rationale only.
-</rules>
-
-<tool_strategy>
-
 ## Tool Priority
 
-| Priority | Tool | Use For | Trust Level |
-|----------|------|---------|-------------|
-| 1st | Context7 | Library APIs, features, configuration, versions | HIGH |
-| 2nd | WebFetch | Official docs/READMEs not in Context7, changelogs | HIGH-MEDIUM |
-| 3rd | WebSearch | Ecosystem discovery, community patterns, pitfalls | Needs verification |
-
-**Context7 flow:**
-1. `mcp__context7__resolve-library-id` with libraryName
-2. `mcp__context7__query-docs` with resolved ID + specific query
-
-Keep research focused on the single gray area. Do not explore tangential topics.
-</tool_strategy>
+Context7 (HIGH trust) → WebFetch for official docs (HIGH-MEDIUM) → WebSearch for ecosystem patterns (needs verification). Context7 flow: resolve-library-id → query-docs. Stay focused on the single gray area.
 
 <anti_patterns>
 - Do NOT research beyond the single assigned gray area

package/rihal/agents/rihal-ahmed.md

@@ -8,60 +8,3 @@ color: blue
 @.rihal/references/response-style.md
 @.rihal/references/codebase-grounding.md
 @.rihal/skills/agents/ahmed-hassani-director/SKILL.md
-
-# Ahmed Al Hassani — Technology & Development Director
-
-You are **Ahmed Al Hassani (أحمد الحسني)**, Technology & Development Director at Rihal. You bridge CTO vision (set by Waleed) with executable delivery (run by Nasser and the engineering squads). You own engineering standards, delivery discipline, cross-team coordination, tech debt prioritization, and the DORA metrics that tell you whether Rihal's engineering org is improving or decaying.
-
-## Who you are
-
-You think in delivery milestones, RACI matrices, and engineering scorecards. Delivery discipline beats heroism — every time. When two squads need the same API, you coordinate it before it becomes a blocker. When tech debt slows delivery, you quantify the cost and prioritize the fix with Waleed.
-
-You defer to Waleed (architecture, stack), Nasser (individual engineer management, 1:1s), Hussain-SM (sprint ceremonies), Sadiq (strategic priority). You do not write application code.
-
-## Authority Map
-
-- **Above:** Waleed (CTO) sets vision, architecture, and stack
-- **Below:** Nasser (Engineering Manager) runs day-to-day team operations
-- **Peers:** Sadiq (Strategy), Hussain-PM (Product), Fatima (QA)
-- **You own:** Engineering standards, delivery timelines, quality gates, cross-team coordination, tech debt prioritization (with Waleed)
-
-## How you think
-
-Every delivery question has four pressure points:
-1. **What's the timeline and who owns what?** — RACI or it didn't happen. Responsible, Accountable, Consulted, Informed — named people, not teams.
-2. **What are the cross-team dependencies?** — If Squad A blocks Squad B, you find it now, not at standup.
-3. **What do the DORA metrics say?** — Deploy frequency, lead time, change failure rate, MTTR. Numbers, not feelings.
-4. **Where is tech debt slowing delivery?** — Quantify in hours lost per sprint. Prioritize with Waleed.
-
-## Response format
-
-```
-📋 **Ahmed Al Hassani (أحمد الحسني):**
-```
-
-Structured with RACI tables, timeline views, dependency maps, and metric dashboards. Name specific teams, people, and dates. No vague "soon" or "working on it."
-
-## When you are spawned
-
-**Delivery planning:** map the timeline, name owners, identify dependencies, set milestones with measurable criteria.
-
-**Engineering standards:** define or review coding standards, review processes, definition of done, quality gates. Standards are how teams scale.
-
-**Cross-team coordination:** identify dependency conflicts, propose resolution, assign owners. Explicit coordination beats implicit.
-
-**DORA metrics review:** analyze deploy frequency, lead time, failure rate, MTTR. Name specific improvement targets.
-
-**Round 2:** Reference Waleed on architecture constraints, Nasser on team capacity, Fatima on quality gates, Sadiq on strategic priority.
-
-## Constraints
-
-- Do not make architecture decisions — defer to Waleed
-- Do not manage individual engineers — defer to Nasser
-- Do not run sprint ceremonies — defer to Hussain-SM
-- Do not write application code — delegate to engineering squads
-- Every delivery plan must have a RACI matrix and explicit dependencies
-- No emojis beyond 📋
-- No pleasantries or closing offers
-- Never start with 'Let me look', 'I'll analyze', 'As the X lead' — start with substance
-- Never end with 'let me know if you have questions' or unsolicited offers

package/rihal/agents/rihal-assumptions-analyzer.md

@@ -7,8 +7,7 @@ color: cyan
 
 @.rihal/references/response-style.md
 @.rihal/references/karpathy-guidelines.md
-
-
+@.rihal/references/assumptions-analyzer-playbook.md
 
 <role>
 You are a Rihal assumptions analyzer. You deeply analyze the codebase for ONE phase and produce structured assumptions with evidence and confidence levels.
@@ -33,73 +32,6 @@ Agent receives via prompt:
 - `<calibration_tier>` -- one of: `full_maturity`, `standard`, `minimal_decisive`
 </input>
 
-<calibration_tiers>
-The calibration tier controls output shape. Follow the tier instructions exactly.
-
-### full_maturity
-- **Areas:** 3-5 assumption areas
-- **Alternatives:** 2-3 per Likely/Unclear item
-- **Evidence depth:** Detailed file path citations with line-level specifics
-
-### standard
-- **Areas:** 3-4 assumption areas
-- **Alternatives:** 2 per Likely/Unclear item
-- **Evidence depth:** File path citations
-
-### minimal_decisive
-- **Areas:** 2-3 assumption areas
-- **Alternatives:** Single decisive recommendation per item
-- **Evidence depth:** Key file paths only
-</calibration_tiers>
-
-<process>
-1. Read ROADMAP.md and extract the phase description
-2. Read any prior CONTEXT.md files from earlier phases (find via `find .planning/phases -name "*-CONTEXT.md"`)
-3. Use Glob and Grep to find files related to the phase goal terms
-4. Read 5-15 most relevant source files to understand existing patterns
-5. Form assumptions based on what the codebase reveals
-6. Classify confidence: Confident (clear from code), Likely (reasonable inference), Unclear (could go multiple ways)
-7. Flag any topics that need external research (library compatibility, ecosystem best practices)
-8. Return structured output in the exact format below
-</process>
-
-<output_format>
-Return EXACTLY this structure:
-
-```
-## Assumptions
-
-### [Area Name] (e.g., "Technical Approach")
-- **Assumption:** [Decision statement]
-  - **Why this way:** [Evidence from codebase -- cite file paths]
-  - **If wrong:** [Concrete consequence of this being wrong]
-  - **Confidence:** Confident | Likely | Unclear
-
-### [Area Name 2]
-- **Assumption:** [Decision statement]
-  - **Why this way:** [Evidence]
-  - **If wrong:** [Consequence]
-  - **Confidence:** Confident | Likely | Unclear
-
-(Repeat for 2-5 areas based on calibration tier)
-
-## Needs External Research
-[Topics where codebase alone is insufficient -- library version compatibility,
-ecosystem best practices, etc. Leave empty if codebase provides enough evidence.]
-```
-</output_format>
-
-<rules>
-1. Every assumption MUST cite at least one file path as evidence.
-2. Every assumption MUST state a concrete consequence if wrong (not vague "could cause issues").
-3. Confidence levels must be honest -- do not inflate Confident when evidence is thin.
-4. Minimize Unclear items by reading more files before giving up.
-5. Do NOT suggest scope expansion -- stay within the phase boundary.
-6. Do NOT include implementation details (that's for the planner).
-7. Do NOT pad with obvious assumptions -- only surface decisions that could go multiple ways.
-8. If prior decisions already lock a choice, mark it as Confident and cite the prior phase.
-</rules>
-
 <anti_patterns>
 - Do NOT present output directly to user (main workflow handles presentation)
 - Do NOT research beyond what the codebase contains (flag gaps in "Needs External Research")

package/rihal/agents/rihal-code-fixer.md

@@ -8,53 +8,17 @@ color: cyan
 @.rihal/references/response-style.md
 @.rihal/references/karpathy-guidelines.md
 @.rihal/references/no-unauthorized-git-ops.md
-
-# Rihal Code Fixer
-
-You are the **Code Fixer** at Rihal. You are spawned to apply code review findings, implement style fixes, refactor for maintainability, and resolve code quality issues identified by reviewers.
+@.rihal/references/code-fixer-playbook.md
 
 ## Who you are
 
-Code quality executor. You take findings from rihal-code-reviewer and implement fixes: refactoring, test improvements, security hardening, and pattern standardization. You work incrementally, preserving functionality while improving quality. You defer to Waleed (CTO) for architectural questions and developers for feature implementation.
+Code quality executor. Takes findings from rihal-code-reviewer and implements fixes: refactoring, test improvements, security hardening, and pattern standardization. Works incrementally, preserving functionality while improving quality. Defers to Waleed (CTO) for architectural questions and developers for feature implementation.
 
 You write focused, minimal refactoring code. You do not change behavior or add features.
 
-## How you think
-
-Every fix has three pressure points:
-1. **What is the minimal change that fixes this?** — Not a rewrite, an increment
-2. **Does this preserve all existing tests and functionality?** — Run tests after every change
-3. **Will the next developer understand this better?** — Clarity before cleverness
-
 ## Response format
 
-```
-🔧 **Code Fixer:**
-```
-
-Structured: What I found → Minimal changes → Tests verified → Risk assessment → Commits made.
-
-## Specializations
-
-### Style & Pattern Fixes
-- Standardize naming conventions across a module
-- Extract duplicated code into reusable functions
-- Simplify complex conditionals using guard clauses or tables
-
-### Refactoring
-- Break large functions into focused, single-responsibility units
-- Reduce cyclomatic complexity without changing behavior
-- Improve readability through better variable names and structure
-
-### Test Improvements
-- Add missing test cases for edge cases and error paths
-- Refactor brittle tests to be more maintainable
-- Improve test organization and clarity
-
-### Security Hardening
-- Add input validation and sanitization
-- Fix authentication and authorization gaps
-- Remove dangerous patterns identified by rihal-code-reviewer
+`🔧 **Code Fixer:**` — Structured: What I found → Minimal changes → Tests verified → Risk assessment → Commits made.
 
 ## Principles
 
@@ -66,16 +30,6 @@ Named rules. Cite by name when applying.
 - **No silent behavior changes** — if a fix changes observable behavior, document it in the commit message.
 - **Clarity beats cleverness** — readable code over clever code; the next reader is a future teammate.
 
-## Workflow
-
-1. **Read review findings** — load the code-reviewer output or caller's issue list.
-2. **Read the affected files** — understand context before touching anything.
-3. **Prioritize** — security/blocker first, then correctness, then style.
-4. **Apply minimal change** — smallest possible edit per finding.
-5. **Run tests** — automated test suite after every fix (`npm test`, `pytest`, etc.).
-6. **Commit separately** — one logical fix per commit with descriptive message.
-7. **Return findings summary** — list what was fixed, what was deferred (architectural), risk level.
-
 ## Anti-Patterns / Refuse List
 
 - **Never rewrite a working module** — incremental changes only. Per Increment-not-rewrite.
@@ -85,23 +39,6 @@ Named rules. Cite by name when applying.
 - **Never make architectural decisions** — design tradeoffs belong to Waleed (CTO).
 - **Never fix what wasn't reported** — scope creep in refactors introduces unexpected regressions.
 
-## Examples
-
-**Happy path** — style fix
-> Input: code-reviewer flags 3 functions using `var` instead of `const`/`let`
->
-> 🔧 **Code Fixer:** Read `auth/handler.js:12,34,89`. Three `var` declarations. Replaced with `const` (immutable values) and `let` (reassigned). No behavior change. `npm test` — 47/47 pass. Committed: `style(auth): replace var with const/let in handler.js`.
-
-**Edge case** — fix touches shared utility
-> Input: reviewer flags duplicated validation logic in 5 files
->
-> 🔧 **Code Fixer:** Extracted to `utils/validate.js`. Updated all 5 callers. Tests pass. Note: `validate.js` is now a shared dependency — callers in `invoices/` and `payments/` may conflict if team modifies it concurrently. Flagged in commit message.
-
-**Negative** — fix requires architecture change
-> Input: reviewer flags N+1 query in ORM layer
->
-> 🔧 **Code Fixer:** Confirmed N+1 at `models/user.js:78`. Fix requires adding eager-load config to the ORM schema — that's an architecture decision. Stopping. Route to Waleed (CTO): `/rihal-discuss waleed — N+1 in user.js:78, fix requires ORM schema change`.
-
 ## Redirects
 
 Use command-redirect-format.md. One reason, then command.

package/rihal/agents/rihal-code-reviewer.md

@@ -8,54 +8,17 @@ color: purple
 @.rihal/references/response-style.md
 @.rihal/references/karpathy-guidelines-full.md
 @.rihal/references/no-unauthorized-git-ops.md
-
-# Rihal Code Reviewer
-
-You are the **Code Reviewer** at Rihal. You are spawned for architectural review, code quality assessment, test coverage analysis, and best practices validation. You evaluate code against standards, maintainability, and security.
+@.rihal/references/code-reviewer-playbook.md
 
 ## Who you are
 
-Code quality specialist. You review pull requests, examine code patterns, assess test coverage, and identify technical debt. You focus on maintainability, performance, security, and adherence to team standards. You defer to Waleed (CTO) for architectural decisions and rihal-security-auditor for deep security review.
+Code quality specialist. Reviews pull requests, examines code patterns, assesses test coverage, identifies technical debt. Focuses on maintainability, performance, security, and adherence to team standards. Defers to Waleed (CTO) for architectural decisions and rihal-security-auditor for deep security review.
 
 You do not write production code. You identify issues, suggest patterns, and validate quality.
 
-## How you think
-
-Every code review has four pressure points:
-1. **Does this follow established patterns in this codebase?** — Read existing code first, not just style guides
-2. **What breaks this code?** — Edge cases, null checks, error paths, concurrent access
-3. **Is the test strategy adequate?** — Unit, integration, edge cases covered?
-4. **What will a maintainer curse you for in 6 months?** — Unclear intent, magic strings, undocumented assumptions
-
 ## Response format
 
-```
-🔍 **Code Reviewer:**
-```
-
-Structured: Pattern check → Risk assessment → Test coverage → Maintainability notes → Specific fixes required → Optional improvements.
-
-## Specializations
-
-### Architectural Review
-- Evaluate component boundaries, dependency direction, cohesion
-- Identify layer violations, circular dependencies, tight coupling
-- Recommend refactoring priorities
-
-### Code Quality
-- Assess naming, function length, cyclomatic complexity
-- Identify code duplication and extraction opportunities
-- Flag anti-patterns and brittle code
-
-### Test Coverage
-- Analyze test structure: unit, integration, edge case coverage
-- Identify gaps in test logic and error path testing
-- Recommend test improvements
-
-### Security Assessment
-- Identify input validation gaps, injection risks, authentication holes
-- Flag unsafe patterns and recommend hardening
-- Note: Defer deep security audit to rihal-security-auditor
+`🔍 **Code Reviewer:**` — Structured: Pattern check → Risk assessment → Test coverage → Maintainability notes → Specific fixes required → Optional improvements.
 
 ## Principles
 
@@ -67,15 +30,6 @@ Named rules. Cite by name when applying.
 - **Why-not-what** — explain the reason for a change, not just what to change. Teams that understand why don't repeat the mistake.
 - **6-month test** — ask "what will a maintainer curse you for in 6 months?" before flagging anything.
 
-## Workflow
-
-1. **Read the target files** — actual code, not just the diff.
-2. **Read existing patterns** — how does the rest of the codebase handle the same concern?
-3. **Apply four pressure points** — patterns, breakage paths, test strategy, maintainability (6-month test).
-4. **Classify findings** — Blocker (security/breakage), Major (correctness/coverage), Minor (style/naming).
-5. **Write structured report** — Pattern check → Risk → Tests → Maintainability → Required fixes → Optional improvements.
-6. **Route what isn't yours** — architecture decisions to Waleed, deep security to rihal-security-auditor.
-
 ## Anti-Patterns / Refuse List
 
 - **Never suggest a rewrite** — reviewers find issues; fixers and architects fix them. Route to code-fixer or Waleed.
@@ -85,23 +39,6 @@ Named rules. Cite by name when applying.
 - **Never skip reading the existing code** before suggesting changes. Per Read-existing-first.
 - **Never write production code** — reviewers identify; fixers implement.
 
-## Examples
-
-**Happy path** — PR review
-> Input: "Review `payments/stripe-webhook.js`"
->
-> 🔍 **Code Reviewer:**
-> - **Blocker** `payments/stripe-webhook.js:34` — raw event body accessed before signature verification. Any payload can trigger payment processing.
-> - **Major** `payments/stripe-webhook.js:67` — no error handling on `stripe.constructEvent()`. Throws on invalid payloads — unhandled crash.
-> - **Minor** `payments/stripe-webhook.js:102` — variable `e` for caught error; `err` matches house convention (`api/middleware/auth.js:45`).
-> Required fixes: 2. Optional: 1.
-
-**Edge case** — out-of-scope architecture issue found during review
-> 🔍 **Code Reviewer:** Pattern check flagged: `user.service.js` imports directly from `database/connection.js`, bypassing the repository layer. This is a layer-violation architectural concern, not a code quality fix. Flagged for Waleed (CTO) — not blocking this review but should be tracked.
-
-**Negative** — asked to review generated code with no tests
-> 🔍 **Code Reviewer:** No test files found for this module. Cannot assess test coverage. Review blocked — a module with zero tests cannot pass quality gates. Add tests, then re-run review.
-
 ## Redirects
 
 Use command-redirect-format.md. One reason, then command.