@hanzlaa/rcode 3.4.33 → 3.6.0

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`, `changelog`, `scopes`, `phases`, `references`, 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`, `kanban`, `orchestrator`, 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.
@@ -77,12 +77,12 @@ If a user says "just keep going" or "don't stop until done", that authorization
 
 ## Testing Rules
 
-- Run the compliance check after modifying any skill:
+- Run schema validation after modifying any skill or agent — it enforces the
+  5-component skill standard (frontmatter, trigger phrases, negative boundary)
+  in place of the old grep-based check:
   ```bash
-  for f in rihal/skills/agents/*/SKILL.md rihal/skills/actions/*/SKILL.md; do
-    grep -q "^## Output Format" "$f" || echo "MISSING: $f"
-    grep -q "^## Examples" "$f" || echo "MISSING: $f"
-  done
+  node cli/doctor.js                       # full preflight + compliance
+  node --test test/artifact-schema.test.cjs   # schema validators only
   ```
 - Run grep checks before committing renames or refactors:
   ```bash

package/CONTRIBUTING.md

@@ -329,6 +329,8 @@ We use [Conventional Commits](https://www.conventionalcommits.org/) format. The
 - `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)
+- `kanban` — `/rihal-kanban` orchestration board workflow and surfaces
+- `orchestrator` — orchestrator panel, SSE streaming, session persistence
 - `<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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hanzla Habib
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,7 +2,7 @@
 
 <div dir="rtl">طريقة رحال</div>
 
-> **The AI team that never forgets.** Persistent memory, 45 specialist agents, 95 commands — install once, and your AI IDE gets a project brain that survives every session reset.
+> **The AI team that never forgets.** Persistent memory, 45 specialist agents, 109 commands — install once, and your AI IDE gets a project brain that survives every session reset.
 
 ```bash
 npx @hanzlaa/rcode install    # one command, zero dependencies
@@ -11,99 +11,63 @@ npx @hanzlaa/rcode install    # one command, zero dependencies
 [![npm version](https://img.shields.io/npm/v/@hanzlaa/rcode)](https://www.npmjs.com/package/@hanzlaa/rcode)
 [![downloads](https://img.shields.io/npm/dw/@hanzlaa/rcode)](https://www.npmjs.com/package/@hanzlaa/rcode)
 
-**Quick look:** `npx @hanzlaa/rcode install` → `/rihal-council` → `/rihal-plan 1` → `/rihal-execute 1` — that's the full loop in three commands.
+Status: actively developed — published on npm as `@hanzlaa/rcode` v3.5.x, with an automated test suite covered by `node --test`.
 
 ---
 
-## Who is rcode for
+## See it work
 
-You'll feel rcode pay off if you've lived any of these:
-
-- **AI agents lose context mid-project.** Three sessions in, the assistant has forgotten the architectural decision you made on day one.
-- **Onboarding a teammate** means a 30-minute archaeology dig through Slack, Notion, and review comments to explain "why we did it this way".
-- **Late client requirements** keep shifting the goal posts, and there's no record of what was decided when.
-- **MVPs that work but can't be revamped** without rewriting from scratch — the original context is lost.
-
-rcode addresses these with a checked-in **Memory Bank** (`.rihal/memory/`), distinctive engineering personas, and a phased workflow that survives session resets. **For everything in one place, read [`DOCS.md`](DOCS.md).** See [`MEMORY_BANK.md`](MEMORY_BANK.md) for the spec, and [`BRAND.md`](BRAND.md) for naming and voice conventions.
+The full loop runs in three commands — `/rihal-council` → `/rihal-plan` → `/rihal-execute`. The Diwan dashboard (`npm run dashboard`) renders project state, decisions, and the Memory Bank in one view.
 
 ---
 
 ## Why this exists
 
-Every project carries unwritten context — how the team reviews PRs, what "done" means, how milestones sequence, how PRDs travel from Product into Engineering. That context sits in people's heads, Slack, Notion, and senior engineers' review comments. AI assistants pick it up never, because every new chat session starts knowing nothing about how this project actually works.
+Every project carries unwritten context — how the team reviews PRs, what "done" means, how milestones sequence. That context sits in people's heads, Slack, and senior engineers' review comments. AI assistants pick it up never, because every new chat session starts knowing nothing about how this project actually works.
 
-**rcode fixes that.** One install, and the AI knows. Every session. Every repo. Every contributor.
-
----
-
-## 🚦 Start Here
-
-Rihal Code packages a lot. To keep things approachable, everything is organized into **four tiers**:
+You'll feel rcode pay off if you've lived any of these:
 
-| Tier | Who it's for | Start with |
-|------|--------------|-----------|
-| 🌱 **[Starter](docs/TIERS.md#-starter--the-golden-path)** | First-time Rihalian | 7 skills — the Golden Path |
-| 🌿 **[Advanced](docs/TIERS.md#-advanced--real-sprint-team)** | Teams running sprints | PRD variants, architecture, UX, QA |
-| 🌳 **[Ultra Advanced](docs/TIERS.md#-ultra-advanced--power-user-workflows)** | Power users | Multi-agent council, dashboard, clone-website |
-| 📐 **[Standards](docs/STANDARDS.md)** | Contributors | Skill spec, commit rules, PR checklist |
+- **AI agents lose context mid-project.** Three sessions in, the assistant has forgotten the architectural decision you made on day one.
+- **Onboarding a teammate** means a 30-minute archaeology dig through Slack, Notion, and review comments.
+- **Late client requirements** keep shifting the goal posts, with no record of what was decided when.
+- **MVPs that work but can't be revamped** without rewriting from scratch — the original context is lost.
 
-**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.
+rcode fixes that with a checked-in **Memory Bank** (`.rihal/memory/`), distinctive engineering personas, and a phased workflow that survives session resets. One install, and the AI knows. Every session. Every repo. Every contributor.
 
-> **v3 — Rihal Brain.** v1 was a generic AI-engineering methodology. v2 added the Rihal context layer. v3 ships it as a single npm package with a Memory Bank, live dashboard, and 134 automated tests. See [`CHANGELOG.md`](CHANGELOG.md).
+It's not a chatbot. It's a methodology.
 
 ---
 
-## What is this
-
-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
-- **96 slash commands** covering research, planning, execution, verification, and recovery
-- **105 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.)
-- **102 workflows** — the execution backbone behind every slash command
-- **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`)
-- **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
-- **Numeric ID system** (M1 milestones, NN phases, NN.M plans, NN.M.T tasks, with decimal insertion for urgent work)
-- **Plan verification loop** that validates file/symbol references before execution
-- **Post-execute gates** (integration-checker, nyquist-auditor) verify completeness
-- **Global agents** at `~/.rihal/agents/` — customize without forking
-
-See [`MIGRATIONS.md`](MIGRATIONS.md) if you're upgrading from a pre-Memory-Bank install.
+## Quickstart
 
-It's not a chatbot. It's a methodology.
-
----
+### Install — two steps, one minute
 
-## Install — one command
+rcode ships in two parts. Run them both up front so nothing surfaces as an afterthought later:
 
-In any project directory (existing codebase OR empty folder):
+**Step 1 — project files (required).** In any project directory (existing codebase OR empty folder):
 
 ```bash
 npx @hanzlaa/rcode install
 ```
 
-[Live on npm](https://www.npmjs.com/package/@hanzlaa/rcode) as `@hanzlaa/rcode`. See [`docs/install.md`](docs/install.md) for flavors (module subsets, IDE options, version pinning, yolo mode).
+**Step 2 — `rcode` on your PATH (optional).** For the `rcode` CLI command (e.g. `rcode version`, `rcode update`), install globally once:
 
-One unified installer. Pure file shipping, no runtime dependencies. Installs into:
+```bash
+npm install -g @hanzlaa/rcode
+```
+
+[Live on npm](https://www.npmjs.com/package/@hanzlaa/rcode) as `@hanzlaa/rcode`. Pure file shipping, no runtime dependencies. Step 1 installs into:
 
 - `.rihal/` — config, workflows, references, bin (Rihal infrastructure)
 - `.claude/agents/` — 45 first-class subagents
-- `.claude/commands/rihal/` — 95 slash commands
-- `.claude/skills/` — 105 phrase-activated skills (scaffold-project, create-prd, prfaq, memory-init, retrospective, etc.)
-- `rihal/brain/` — Rihal standards pulled from upstream (PR / commit / architecture docs)
-- `.planning/` — where your artifacts land (council sessions, plans, chains, summaries)
+- `.claude/commands/rihal/` — 109 slash commands
+- `.claude/skills/` — 85 phrase-activated skills
+- `rihal/brain/` — Rihal standards pulled from upstream
+- `.planning/` — where your artifacts land
 
-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`.
 
-Update anytime with `npx @hanzlaa/rcode update` (or `/rihal-update` inside a Claude session).
-
-> **Want `rcode` on your PATH?** `npx @hanzlaa/rcode install` sets up the project files but doesn't put `rcode` in your shell. For the `rcode` CLI command (e.g. `rcode version`, `rcode update`), install globally once:
-> ```bash
-> npm install -g @hanzlaa/rcode
-> ```
+See [`docs/install.md`](docs/install.md) for flavors (module subsets, IDE options, version pinning, yolo mode).
 
 ### Then begin the rihla
 
@@ -111,138 +75,41 @@ Update anytime with `npx @hanzlaa/rcode update` (or `/rihal-update` inside a Cla
 /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.
-
-### Install a specific module
-
-```bash
-npx @hanzlaa/rcode install --module core         # council + quick-sync only
-npx @hanzlaa/rcode install --module execution --force
-npx @hanzlaa/rcode install --module discovery --force
-```
-
-### Multi-IDE support
-
-```bash
-npx @hanzlaa/rcode install --ide claude    # default
-npx @hanzlaa/rcode install --ide cursor
-npx @hanzlaa/rcode install --ide gemini
-```
-
----
+`/rihal-init` is the single first command — there is no other entry point to choose. It detects your project state (fresh / existing-with-no-rihal / returning), asks a few configuration questions, and routes you to the right first action. For a greenfield project it routes into `/rihal-new-project` automatically — you never call that directly, it's a sub-path of `/rihal-init`.
 
-## 90-second tour
+### The full loop
 
 ```
-/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
-```
-
----
-
-## Filesystem layout
-
-**System-owned directories (do not edit):**
-
 ```
-.rihal/                        — Rihal infrastructure + state
-  config.yaml                  — preferences (model, language, mode, branching)
-  state.json                   — project phases, decisions, sessions, workstreams
-  RIHLA.md                      — project journey baseline
-  HANDOFF.json                  — pause-work context for resuming
-  bin/
-    rihal-tools.cjs            — CLI helper (state read/write, panel scoring, etc.)
-    lib/council-panel.cjs      — deterministic panel scorer
-  workflows/                   — 102 slash command workflows
-  references/                  — shared contracts (council-protocol, gates, karpathy-guidelines, etc.)
-  agents-rules/                — lazy-loaded agent rule files (planner, executor, debugger)
-```
-
-**Your artifacts (created automatically):**
-
-```
-.planning/                     — your work outputs
-  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
-  HANDOFF.json                  — pause-work checkpoint
-  .continue-here.md            — human-readable handoff summary
-```
-
----
-
-## The team
-
-**5 council agents** with cultural identity, each with hard scope boundaries and response-style contracts:
-
-| Agent | Role | Spawns for |
-|-------|------|-----------|
-| 🧭 **Sadiq (صادق)** | Director of Strategy | Priorities, kill criteria, market timing, "should we build this" |
-| 🏗️ **Waleed (وليد)** | CTO | Architecture, stack, feasibility, security, scale, tech debt |
-| 🛡️ **Fatima (فاطمة)** | QA Lead | Test strategy, release readiness, regression risk, coverage |
-| 📣 **Mariam (مريم)** | Marketing & Growth | Market research, GTM, positioning, GCC/MENA markets |
-| 📋 **Hussain-PM (حسين)** | Product Manager | Scope, roadmap, features, user stories, PRDs, sprint planning |
 
-**30+ specialist agents** for execution, discovery, and verification:
-
-- **Execution**: rihal-executor, rihal-planner, rihal-verifier, rihal-plan-checker, rihal-debugger
-- **Discovery**: rihal-codebase-mapper, rihal-project-researcher, rihal-roadmapper, rihal-phase-researcher, rihal-advisor-researcher, rihal-assumptions-analyzer, rihal-research-synthesizer
-- **Verification**: rihal-integration-checker, rihal-nyquist-auditor
-- **Quality**: rihal-noor, rihal-ux-designer, rihal-code-reviewer, rihal-code-fixer, rihal-edge-case-hunter, rihal-deviation-analyzer
-- **And more**: rihal-docs-auditor, rihal-doc-verifier, rihal-doc-writer, rihal-repo-metrics, rihal-security-auditor, etc.
-
-**Customize globally:** Define reusable agents in `~/.rihal/agents/rihal-<name>.md`. They appear in every project alongside project-local agents, without forking the repo.
+**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.
 
 ---
 
-## Three modes, three mental models
-
-### 🏛️ `/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-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
-```
-
-Presets: `research-plan` · `feasibility` · `gtm-to-build` · `full-discovery`. Or custom: `/rihal-chain mariam,waleed,fatima "your topic"`.
+## What makes Rihal different
 
-### 💬 `/rihal-discuss` — Single agent, quick-sync
+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.**
 
-One agent, one round, conversational tone, no mandatory artifact. Feels like texting one colleague.
+How it stacks up against the tools you already know:
 
-```
-/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?
-```
+| Dimension | Cursor / Windsurf | CrewAI / AutoGen | **Rihal Code** |
+|-----------|-------------------|------------------|----------------|
+| Per-project memory | Per-user, not git-tracked | Requires a vector DB | Git-tracked markdown in `.rihal/memory/` |
+| Specialist agents | 1 generalist with IDE context | Define your own in code | 45 shipped at install time |
+| Workflow gates | None | Build your own | Structural — refuses to run without upstream |
+| Infrastructure | Cloud API + local IDE | Python server + dependencies | Zero — pure files |
+| IDE lock-in | Cursor only | Framework-specific | Claude, Cursor, Gemini, Codex |
+| Install | IDE extension | `pip install` + config + code | `npx install` — one command |
 
-If no agent named, the panel scorer picks the top match.
+Full breakdown: [`docs/USP.md`](docs/USP.md).
 
----
+### Persistent project memory
 
-## What makes Rihal different
+A checked-in **Memory Bank** at `.rihal/memory/` — visible in the Diwan dashboard, with lossless distillates for fast LLM hydration. A typical session loads ~5K tokens of Memory Bank and is fully oriented to the project's history, decisions, and known issues. See [`MEMORY_BANK.md`](MEMORY_BANK.md) for the spec.
 
 ### Intent guards catch wrong commands
 
@@ -251,236 +118,44 @@ Run the wrong command and you get a single-line copy-paste redirect — not a us
 ```
 /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?
 ```
 
 Every workflow has a Step 0.5 intent detector.
 
-### Multilingual — Roman Urdu + Arabic + English
-
-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
-→ panel: [mariam, hussain-pm, sadiq]
-```
+### Markdown-first agent design
 
-### PRFAQ — validate before you build
+Most agent frameworks wrap their logic in Python classes, JSON schemas, and orchestration layers. rcode doesn't. Every agent is a markdown file — the model follows structured prose, no wrapper needed.
 
-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`.
+The design rule: **markdown owns the logic, scripts own the boundaries.** Heavy playbook content lives in `rihal/references/` and gets `@-include`d at spawn time, so agent files stay thin (≤100 lines) without losing context.
 
-**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.
+### Three execution modes
 
-```
-/rihal-prfaq                                         → interactive gauntlet
-/rihal-prfaq --headless --customer "..." --problem "..." --solution "..."   → autonomous first draft
-```
+- **`/rihal-council`** — parallel debate: 3-5 agents answer simultaneously, then challenge each other in Round 2. For strategic decisions where you want disagreement, not consensus.
+- **`/rihal-chain`** — sequential pipeline: each agent reads the previous one's artifact (RESEARCH.md → SCOPE.md → PLAN.md).
+- **`/rihal-discuss`** — single agent, quick-sync: one expert, conversational, no mandatory artifact.
 
 ### 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:
+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: think before coding, simplicity first, surgical changes, goal-driven execution. `/rihal-code-review --karpathy` runs them as a post-hoc audit against any diff.
 
-1. **Think before coding** — surface assumptions, don't hide confusion
-2. **Simplicity first** — minimum code, no speculative abstractions
-3. **Surgical changes** — touch only what's needed, match existing style
-4. **Goal-driven execution** — define verifiable success criteria
+### Verification built in
 
-`/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
-```
-
-### 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-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
-```
-
-- **quality** — opus/sonnet-4.6 for reasoning agents
-- **balanced** — sonnet-4.6 across the board (default)
-- **budget** — haiku-4.5 everywhere
-- **inherit** — use parent session's model
-
-### Session handoff
-
-```
-/rihal-pause-work    → writes .rihal/HANDOFF.json + .continue-here.md
-/rihal-resume-work   → reads HANDOFF, surfaces blocking constraints
-```
-
----
-
-## Full command surface (95 commands)
-
-### Router + lifecycle
-`init` · `do` · `help` · `status` · `stats` · `health` · `forensics` · `update`
-
-### Discovery + research
-`new-project` · `map-codebase` · `scan` · `explore` · `document-project` · `analyze-dependencies`
-
-### 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`
-
-### Execution
-`execute` · `quick` · `autonomous` · `audit-fix` · `undo`
-
-### Observability + review
-`code-review` · `code-review-fix` · `checkpoint-preview` · `secure-phase` · `show` · `why` · `rerun` · `diff`
-
-### Recovery + correction
-`pause-work` · `resume-work` · `correct-course` · `next` · `config`
-
-### Multi-agent modes
-`council` · `chain` · `discuss`
-
-### Configuration + setup
-`settings` · `install` · `enable-hooks` · `profile-user`
-
-### Lifecycle + phases
-`insert-phase` · `new-milestone` · `audit-milestone` · `complete-milestone` · `milestone-summary` · `new-workspace` · `list-workspaces` · `remove-workspace` · `workstream`
-
-### Docs + notes + reporting
-`docs-update` · `note` · `report` · `session-report` · `add-todo` · `import` · `inbox`
-
-### UI design
-`ui-phase` · `ui-review`
-
----
-
-## Configuration
-
-`.rihal/config.yaml` — edit directly or run `/rihal-settings`:
-
-```yaml
-user_name: "Hanzla"
-project_name: "your-project"
-communication_language: "English"   # or Urdu, Arabic, etc.
-mode: "guided"                       # or yolo
-model_profile: "balanced"            # quality | balanced | budget | inherit
-workflow:
-  research_by_default: false
-  plan_checker: true
-  post_execute_gates: true
-  ui_safety_gate: true
-git:
-  branching_strategy: "none"         # none | feature-branch | worktree-isolation
-```
+`/rihal-plan` runs `rihal-plan-checker` to validate file/symbol references before execution. `/rihal-execute` runs `rihal-integration-checker` (cross-phase E2E) and `rihal-nyquist-auditor` (test coverage) after completion.
 
 ---
 
-## State tracking
-
-`.rihal/state.json` tracks everything:
+## Learn more
 
-- `current_phase`, `current_plan`
-- `phases[]`, `executions[]`, `decisions[]`, `blockers[]`
-- `council_sessions[]`, `chains[]`
-- `workstreams[]`, `active_workstream`, `last_session`
-
-View formatted:
-```bash
-node .rihal/bin/rihal-tools.cjs state read
-# or
-/rihal-status
-```
-
----
-
-## Hooks (opt-in)
-
-```bash
-/rihal-enable-hooks
-```
-
-Installs 3 opt-in hooks into `.claude/settings.json`:
-1. **pre-edit** — enforces read-before-edit
-2. **pre-workflow** — soft intent warnings on mismatched commands
-3. **post-commit** — validates commit format, blocks AI attribution
-
----
-
-## Modules
-
-| 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` |
-
-Full install = all 3 modules = 700+ files.
-
----
-
-## Testing
-
-```bash
-node --test          # full suite (134 tests, ~2s)
-node --test --test-reporter=spec   # verbose output with test names
-```
-
-**134 tests · 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 — 45
-    ✓ skills + commands installed — 105 skills + 95 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
-```
+| Document | What's in it |
+|----------|--------------|
+| [`DOCS.md`](DOCS.md) | Complete documentation — install, concepts, all commands, Memory Bank, dashboard, testing & CI, architecture |
+| [`docs/getting-started.md`](docs/getting-started.md) | Step-by-step first project |
+| [`docs/TIERS.md`](docs/TIERS.md) | Starter / Advanced / Power-user paths |
+| [`MEMORY_BANK.md`](MEMORY_BANK.md) | Memory Bank specification |
+| [`BRAND.md`](BRAND.md) | Naming, voice, and persona glossary |
+| [`MIGRATIONS.md`](MIGRATIONS.md) | Upgrade path from a pre-Memory-Bank install |
+| [`CHANGELOG.md`](CHANGELOG.md) | Release history |
 
 ---
 
@@ -499,16 +174,4 @@ node --test test/lib/manifest.test.cjs   # install verification only
 
 ## License
 
-UNLICENSED — proprietary. All rights reserved.
-
----
-
-## Auto-heal cadence
-
-rihal-code ships continuous auto-heal tools — `/rihal-feature-drift`, `/rihal-memory-audit`, `/rihal-health` — plus a CI dogfood gate that runs them against this repo on every push. See [docs/AUTO-HEAL-CADENCE.md](docs/AUTO-HEAL-CADENCE.md) for recommended schedules, `/loop` examples, crontab entries, and the safety rules around `--fix` modes.
-
----
-
-## Roadmap
-
-See [GitHub Issues](https://github.com/hanzlahabib/rihal-code/issues) for tracked work. Current focus: marketing launch, MCP server, dashboard enhancements.
+Released under the [MIT License](LICENSE).