@hanzlaa/rcode 2.1.0

package/rihal/references/workstream-flag.md

@@ -0,0 +1,166 @@
+# Workstream Flag — When to Use Workspace Isolation
+
+This reference explains when to use `--workspace` flag vs. sequential phases in `.planning/`.
+
+## Sequential Phases (Default)
+
+Use the standard planning pipeline (`.planning/phases/`) for:
+
+- **Linear work** — Phase 1, Phase 2, Phase 3 in order
+- **Dependent phases** — Phase 2 cannot start until Phase 1 is done
+- **Single focus** — One team/project working on one thing
+- **Milestone-driven** — All phases contribute to the same goal
+
+**Example:**
+```
+/rihal:plan Build authentication system
+/rihal:plan Add user profile pages (depends on auth from Phase 1)
+/rihal:plan Write deployment guide (depends on both phases complete)
+```
+
+These run sequentially, each depending on the previous phase's completion.
+
+## Workspace Isolation (Parallel)
+
+Use workspaces (`--workspace` flag) for:
+
+- **Parallel work** — Multiple initiatives happening at the same time
+- **Independent goals** — Each workspace has its own ROADMAP
+- **Context switching** — "I need to pause Q2 roadmap and fix critical bugs"
+- **Team separation** — Team A works on Feature X, Team B works on Feature Y
+- **Risk isolation** — "Keep the hotfix separate from experimental work"
+- **Deadline urgency** — "Fast-track this in a separate workspace while main work continues"
+
+**Example:**
+```
+# Main workspace (Q2 roadmap)
+/rihal:plan Build search feature
+
+# Parallel workspace (critical bug)
+/rihal:new-workspace Critical Hotfix
+/rihal:plan Fix data corruption --workspace=Critical Hotfix
+
+# Both run independently
+# Query progress:
+/rihal:list-workspaces
+```
+
+## Decision Matrix
+
+| Scenario | Use | Why |
+|----------|-----|-----|
+| "Build feature A then feature B then feature C" | Sequential | Linear, dependent work |
+| "Build feature A AND debug production issue simultaneously" | Workspace | Parallel, independent |
+| "Phase 2 requires Phase 1 to be 100% done first" | Sequential | Depends-on relationship |
+| "Two teams working on unrelated features" | Workspace | No dependency, separate concerns |
+| "One-sprint roadmap with 5 tasks" | Sequential | Single focused initiative |
+| "Pause roadmap, fix urgent bug, resume roadmap" | Workspace | Context switch without losing state |
+| "Research + implementation of same feature" | Sequential | Both parts of one deliverable |
+| "Experiment in parallel with stable features" | Workspace | Risk isolation |
+
+## State Management
+
+### Sequential (default)
+
+- Single `.planning/STATE.md` — tracks all phases
+- Single `.planning/ROADMAP.md` — one set of goals
+- Phases inherit context from previous phases
+
+### Workspaces (parallel)
+
+- Each workspace has its own `STATE.md`
+- Each workspace has its own `ROADMAP.md`
+- No shared context between workspaces (intentional isolation)
+
+## Switching Context
+
+### Sequential phases
+
+```bash
+# View current phase
+/rihal:status
+
+# Execute next phase
+/rihal:execute <phase>
+
+# Switch to different task within same milestone
+/rihal:quick <small task>
+```
+
+### Workspaces
+
+```bash
+# List all workspaces
+/rihal:list-workspaces
+
+# Work within a workspace
+/rihal:plan <task> --workspace=Hotfix
+
+# Switch to another workspace's context
+/rihal:workspace <name>
+
+# Return to main planning
+/rihal:workspace main
+```
+
+## Merging Workspaces Back
+
+If you started a workspace but it should merge back into main planning:
+
+1. Complete the work in the workspace
+2. Create a phase in main planning that incorporates the workspace's findings
+3. Archive the workspace: `/rihal:remove-workspace <name> --archive`
+4. Continue in main planning with unified context
+
+## Common Patterns
+
+### Pattern: Feature branch + hotfix
+
+```bash
+# Main work (Q2 roadmap)
+/rihal:plan Implement real-time notifications
+
+# Critical bug emerges
+/rihal:new-workspace Critical
+/rihal:plan Fix payment processing --workspace=Critical
+
+# Two parallel tracks
+/rihal:list-workspaces
+
+# When bug is fixed
+/rihal:complete-workspace Critical
+# Resume main work
+/rihal:execute <Q2 phase>
+```
+
+### Pattern: Research + implementation
+
+```bash
+# Sequential phases (both parts of same feature)
+/rihal:plan Research WebSocket libraries and trade-offs
+/rihal:plan Implement chosen library with tests
+# Phase 2 reads Phase 1 findings
+```
+
+### Pattern: Experimental feature
+
+```bash
+# Keep experiments separate
+/rihal:new-workspace Experiment: Dark Mode
+/rihal:plan Build dark mode UI --workspace=Experiment
+/rihal:plan Test across 10 browsers --workspace=Experiment
+
+# Main work continues unaffected
+/rihal:plan Improve search relevance
+
+# If experiment succeeds, merge into main
+# If it fails, just archive and delete
+/rihal:remove-workspace --archive Experiment
+```
+
+## Summary
+
+- **Default (sequential):** Linear work, dependencies, single focus
+- **Workspaces (parallel):** Independent initiatives, context switching, risk isolation
+- Use sequential for 95% of work
+- Reach for workspaces when you truly have parallel, independent tracks

package/rihal/skills/SKILLS_INDEX.md

@@ -0,0 +1,114 @@
+# Rihal Code — Skills Index
+
+All 58 skills in Rihal Code, organized by category: 17 agent skills, 26 action skills, 13 core skills, plus 2 shared modules.
+
+## Agent Skills (17)
+
+Each agent has a persona, principles, and a capabilities table that lists which action skills it can invoke.
+
+| Rihal Name | Arabic | Role | Skill Path |
+|---|---|---|---|
+| **Waleed** | وليد | System Architect / CTO | `agents/waleed-architect/` |
+| **Sadiq** | صادق | Business Analyst / Strategy | `agents/sadiq-analyst/` |
+| **Hussain (PM)** | حسين | Product Manager | `agents/hussain-pm/` |
+| **Hussain (SM)** | حسين | Scrum Master | `agents/hussain-sm/` |
+| **Layla** | ليلى | UX Designer | `agents/layla-designer/` |
+| **Hanzla** | حنظلة | Senior Developer | `agents/hanzla-engineer/` |
+| **Fatima** | فاطمة | Test Architect (QA) | `agents/fatima-qa/` |
+| **Noor** | نور | Technical Writer | `agents/noor-writer/` |
+| **Ahmed Al Hassani** | أحمد الحسني | Technology & Development Director | `agents/ahmed-hassani-director/` |
+| **Haitham** | هيثم | Senior Frontend Engineer | `agents/haitham-frontend/` |
+| **Mariam** | مريم | Marketing Lead | `agents/mariam-marketing/` |
+| **Nasser** | ناصر | Engineering Manager | `agents/nasser-eng-manager/` |
+| **Yousef** | يوسف | Senior Backend Engineer | `agents/yousef-backend/` |
+| **Zahra** | زهرة | Branding & Creative Director | `agents/zahra-branding/` |
+| **Zayd** | زيد | Senior ML Engineer | `agents/zayd-ml/` |
+| **Raees** | رئيس | Orchestrator | `agents/raees-orchestrator/` |
+| **Majlis** | مجلس | Multi-Agent Council | `agents/majlis-council/` |
+
+Note: Hussain has two hats — **PM** (strategic product management) and **SM** (scrum master / sprint ops). Real teams often combine these.
+
+---
+
+## Action Skills (26)
+
+Invoked by agents via the capabilities table in their SKILL.md. Organized by SDLC phase.
+
+### 1 — Analysis (6)
+- `actions/1-analysis/research/rihal-domain-research` — domain-specific research
+- `actions/1-analysis/research/rihal-market-research` — market and competitive research
+- `actions/1-analysis/research/rihal-technical-research` — technical deep-dive research
+- `actions/1-analysis/rihal-product-brief` — write product brief
+- `actions/1-analysis/rihal-prfaq` — Amazon Working Backwards PRFAQ challenge
+- `actions/1-analysis/rihal-document-project` — document an existing codebase (brownfield)
+
+### 2 — Planning (8)
+- `actions/2-plan/rihal-create-prd` — create product requirements doc
+- `actions/2-plan/rihal-edit-prd` — edit existing PRD
+- `actions/2-plan/rihal-validate-prd` — validate PRD completeness
+- `actions/2-plan/rihal-create-ux-design` — create UX design
+- `actions/2-plan/rihal-frontend-design` — typography, colours, motion, spatial design
+- `actions/2-plan/rihal-create-epics-and-stories` — break down PRD into epics and stories
+- `actions/2-plan/rihal-create-story` — prepare a dev-ready user story
+- `actions/2-plan/rihal-create-milestone` — create milestone definition
+
+### 3 — Solutioning (3)
+- `actions/3-solutioning/rihal-create-architecture` — architectural decision record (ADR)
+- `actions/3-solutioning/rihal-check-implementation-readiness` — verify PRD/UX/arch alignment
+- `actions/3-solutioning/rihal-generate-project-context` — generate project-context.md
+
+### 4 — Implementation (9)
+- `actions/4-implementation/rihal-dev-story` — execute a story (write tests + code)
+- `actions/4-implementation/rihal-code-review` — comprehensive code review
+- `actions/4-implementation/rihal-qa-generate-e2e-tests` — generate e2e test suite
+- `actions/4-implementation/rihal-sprint-planning` — plan a sprint
+- `actions/4-implementation/rihal-sprint-status` — sprint status report
+- `actions/4-implementation/rihal-retrospective` — retro workflow
+- `actions/4-implementation/rihal-correct-course` — course-correction for off-track stories
+- `actions/4-implementation/rihal-scaffold-project` — scaffold new project from Rihal template
+- `actions/4-implementation/rihal-checkpoint-preview` — LLM-assisted human-in-the-loop review
+
+---
+
+## Core Skills (13)
+
+Shared utilities used across agents and workflows.
+
+- `core/rihal-init` — INTERNAL config loader (installs to .rihal/skills/, not .claude/skills/)
+- `core/rihal-help` — meta-help on available skills
+- `core/rihal-brainstorming` — structured brainstorming workflow
+- `core/rihal-advanced-elicitation` — advanced requirements elicitation
+- `core/rihal-distillator` — distill information into concise summaries
+- `core/rihal-index-docs` — index documentation for search
+- `core/rihal-shard-doc` — shard large documents into linked sections
+- `core/rihal-clone-website` — reverse-engineer and clone a website
+- `core/rihal-editorial-review-prose` — editorial review for prose quality
+- `core/rihal-editorial-review-structure` — editorial review for structural quality
+- `core/rihal-review-adversarial-general` — adversarial review for robustness
+- `core/rihal-review-edge-case-hunter` — edge case hunting and boundary testing
+- `core/rihal-party-mode` — multi-agent collaboration mode
+
+---
+
+## How Skills Work
+
+1. **Agent skills** give a persona and list capabilities
+2. **Action skills** are the actual capabilities that do work
+3. **Core skills** are shared utilities
+
+Agents reference actions by their skill name in their Capabilities table:
+
+```markdown
+| Code | Description | Skill |
+|------|-------------|-------|
+| DS | Write the next story's tests and code | rihal-dev-story |
+| CR | Comprehensive code review | rihal-code-review |
+```
+
+When a user picks capability `DS`, Claude invokes the `rihal-dev-story` skill.
+
+---
+
+## Licensing
+
+Free to use and adapt.

package/rihal/skills/_shared/no-autonomous-bypass.md

@@ -0,0 +1,37 @@
+# No Autonomous-Mode Bypass
+
+This fragment is referenced by every step-file workflow that enforces halt-at-menu. Do not inline its contents into individual step files — reference this file so the rule stays single-sourced.
+
+## The Rule
+
+Step-file skills (`rihal-create-prd`, `rihal-sprint-planning`, `rihal-create-epics-and-stories`, etc.) halt at every menu and wait for user input. **This is invariant.** The agent MUST NOT invent an "autonomous mode", "research mode", or any other self-declared bypass that skips discovery questions.
+
+Phrases like *"just write it autonomously"*, *"create the full thing ready to execute"*, *"skip the questions"*, or *"use research mode"* from the user are **not** authorization to bypass halt. They are signals that the user wants the skill to move efficiently — answer by running the next step's questions compactly, not by skipping them.
+
+## The Only Sanctioned Bypass Paths
+
+There are exactly two ways to legitimately run a skill without halting at menus:
+
+1. **Project-wide:** `.rihal/config.yaml` → `mode: yolo`. The config loader flags `yoloMode=true` in the runtime context; step files check this flag and may auto-advance.
+2. **Per-invocation:** `/rihal:do --auto <question>` on the router. The router sets `autoMode=true` and passes it to the dispatched skill.
+
+If **neither** flag is set, halt is mandatory regardless of what the user's prompt text says.
+
+## Required Behavior When Asked to Bypass Without a Flag
+
+1. Acknowledge the user's intent in one sentence.
+2. Show the current step's menu anyway.
+3. Tell the user the two sanctioned paths (config flag or `--auto`) if they want fully hands-off execution.
+4. Do not generate any output artifact (PRD, sprint plan, roadmap, etc.) until the user either selects a menu option or sets one of the sanctioned flags.
+
+## Anti-Example (What NOT to Do)
+
+> User: *"use rihal research skills and create best PRD ready to execute"*
+>
+> ❌ Agent: *"Switching to autonomous mode — researching the domain and drafting a complete execution-ready PRD."* *(then writes full PRD)*
+
+That response invents a mode that does not exist and violates the halt invariant.
+
+## Correct Response
+
+> ✅ Agent: *"I hear you want the PRD written end-to-end. The halt rule applies unless you set `mode: yolo` in `.rihal/config.yaml` or re-invoke via `/rihal:do --auto`. Here is the step-01 menu — pick Continue and I will drive each step concisely."*

package/rihal/skills/_shared/research-citation-rule.md

@@ -0,0 +1,39 @@
+# Research & Citation Rule
+
+Referenced by any step-file workflow that writes content derived from external sources (competitor pricing, API tiers, market sizing, benchmark numbers, vendor claims, etc.).
+
+## The Rule
+
+If an output artifact (PRD, research note, architecture doc, roadmap) contains a specific external claim — a price, a percentage, a named competitor feature, an API limit — then **every such claim must be traceable to a `WebFetch` (or equivalent document-fetch) call made in the same session**. `WebSearch` snippets alone are not sufficient evidence because snippets are paraphrased and may be stale.
+
+## What This Means in Practice
+
+Before writing a claim like *"Competitor X costs $12.50/mo"*:
+
+1. Run `WebFetch` on the source URL (not just `WebSearch` for a snippet).
+2. Quote the exact sentence from the fetched content in your internal reasoning.
+3. Include the URL in the citations block of the artifact.
+4. If the URL is paywalled, login-walled, or returns a different claim than expected, drop the number — do not paraphrase from memory or search-result previews.
+
+## The Trap to Avoid
+
+Observed failure pattern (rihal-code session, social-poster-x PRD generation):
+
+- Agent ran two `WebSearch` calls.
+- Agent wrote a PRD citing four specific URLs with specific dollar amounts.
+- Agent never ran `WebFetch` on any of the four URLs.
+- Numbers may be accurate-looking hallucinations.
+
+This pattern is forbidden. A citation block without `WebFetch` evidence is a lie to the reader.
+
+## If the User Is Running Autonomously
+
+`mode: yolo` and `/rihal:do --auto` bypass halt-at-menu, but they do **not** bypass this rule. A fully-autonomous run still has to fetch every cited URL before writing the claim.
+
+## Checklist Before Writing a Citation
+
+- [ ] `WebFetch` was called on this URL in this session.
+- [ ] The fetched content contains the specific number / claim being cited.
+- [ ] The claim in the artifact matches the fetched content verbatim (or is a clearly labeled summary).
+
+If any box is unchecked: remove the claim, replace with *"(needs source)"*, and flag to the user.

package/rihal/skills/_shared/state-sync-rule.md

@@ -0,0 +1,43 @@
+# State Sync Rule
+
+Referenced by skills that write `ROADMAP.md`, `epics.md`, or sprint artifacts. These artifacts are not authoritative on their own — downstream workflows (`/rihal:status`, `/rihal:progress`, `/rihal:execute`) read `.rihal/state.json`. If you write a planning artifact and skip state sync, the project ends up with two divergent pictures.
+
+## The Rule
+
+Immediately after appending content to any of:
+
+- `.planning/ROADMAP.md` — milestones and phases
+- `.planning/epics.md` — epics and stories
+- `.rihal/phases/{phase}/sprint-{N}.md` — sprint commitments
+
+Call the state-sync helper:
+
+```bash
+node .rihal/bin/rihal-tools.cjs state sync --from-disk
+```
+
+or, for a more targeted write, use the JSON-API helpers exposed by `rihal-tools.cjs`:
+
+```bash
+node .rihal/bin/rihal-tools.cjs state upsert-milestone <json>
+node .rihal/bin/rihal-tools.cjs state upsert-phase <json>
+node .rihal/bin/rihal-tools.cjs state upsert-epic <json>
+```
+
+If `rihal-tools.cjs` does not yet expose the needed subcommand, fall back to `state sync --from-disk` which re-parses `ROADMAP.md` + `epics.md` and rebuilds the relevant sections of `state.json`.
+
+## Verification After Sync
+
+- `node .rihal/bin/rihal-tools.cjs state read` returns a phase count that matches the phase table in `ROADMAP.md`.
+- `/rihal:status` and `/rihal:progress`, run back-to-back, agree on the current milestone name and phase count.
+
+## Why This Matters
+
+Observed failure (rihal-code, social-poster-x install, Apr 2026):
+
+- User ran `/rihal:create-epics-and-stories`.
+- `ROADMAP.md` gained 10 phases; `epics.md` gained 62 stories.
+- `.rihal/state.json` remained at the initial bootstrap with 1 phase.
+- `/rihal:status` showed 1 phase; `/rihal:progress` showed 10.
+
+That divergence is what this rule exists to prevent.

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

@@ -0,0 +1,31 @@
+---
+name: rihal-domain-research
+description: >
+  Conduct industry domain deep-dive research to build subject matter
+  expertise on a specific business domain. Activates when the user says
+  "research this domain", "domain deep dive", "explain this industry", "help
+  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).
+---
+
+## Workflow
+
+Follow the instructions in ./workflow.md.
+
+## Output Format
+
+- Report: Domain Overview | Key Players | Terminology Glossary | Common Workflows | Regulatory Notes | References
+- Every claim cited with a source URL or flagged as assumption
+- Saved to .rihal/artifacts/research/domain-{slug}.md
+- Do NOT include unsourced statistics
+
+## Examples
+
+### Happy Path
+**Input:** "Research the real estate brokerage domain in Oman"
+**Expected behavior:** Multi-source research, produce report with glossary of Omani real estate terms, regulatory citations, and key players.
+
+### Edge Case: Narrow Domain
+**Input:** "Research quantum basket weaving"
+**Expected behavior:** Report: "Insufficient verifiable sources. Can narrow or pivot to adjacent domain?"

package/rihal/skills/actions/1-analysis/research/rihal-domain-research/domain-steps/step-01-init.md

@@ -0,0 +1,137 @@
+# Domain Research Step 1: Domain Research Scope Confirmation
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user confirmation
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ FOCUS EXCLUSIVELY on confirming domain research scope and approach
+- 📋 YOU ARE A DOMAIN RESEARCH PLANNER, not content generator
+- 💬 ACKNOWLEDGE and CONFIRM understanding of domain research goals
+- 🔍 This is SCOPE CONFIRMATION ONLY - no web research yet
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- ⚠️ Present [C] continue option after scope confirmation
+- 💾 ONLY proceed when user chooses C (Continue)
+- 📖 Update frontmatter `stepsCompleted: [1]` before loading next step
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## CONTEXT BOUNDARIES:
+
+- Research type = "domain" is already set
+- **Research topic = "{{research_topic}}"** - discovered from initial discussion
+- **Research goals = "{{research_goals}}"** - captured from initial discussion
+- Focus on industry/domain analysis with web research
+- Web search is required to verify and supplement your knowledge with current facts
+
+## YOUR TASK:
+
+Confirm domain research scope and approach for **{{research_topic}}** with the user's goals in mind.
+
+## DOMAIN SCOPE CONFIRMATION:
+
+### 1. Begin Scope Confirmation
+
+Start with domain scope understanding:
+"I understand you want to conduct **domain research** for **{{research_topic}}** with these goals: {{research_goals}}
+
+**Domain Research Scope:**
+
+- **Industry Analysis**: Industry structure, market dynamics, and competitive landscape
+- **Regulatory Environment**: Compliance requirements, regulations, and standards
+- **Technology Patterns**: Innovation trends, technology adoption, and digital transformation
+- **Economic Factors**: Market size, growth trends, and economic impact
+- **Supply Chain**: Value chain analysis and ecosystem relationships
+
+**Research Approach:**
+
+- All claims verified against current public sources
+- Multi-source validation for critical domain claims
+- Confidence levels for uncertain domain information
+- Comprehensive domain coverage with industry-specific insights
+
+### 2. Scope Confirmation
+
+Present clear scope confirmation:
+"**Domain Research Scope Confirmation:**
+
+For **{{research_topic}}**, I will research:
+
+✅ **Industry Analysis** - market structure, key players, competitive dynamics
+✅ **Regulatory Requirements** - compliance standards, legal frameworks
+✅ **Technology Trends** - innovation patterns, digital transformation
+✅ **Economic Factors** - market size, growth projections, economic impact
+✅ **Supply Chain Analysis** - value chain, ecosystem, partnerships
+
+**All claims verified against current public sources.**
+
+**Does this domain research scope and approach align with your goals?**
+[C] Continue - Begin domain research with this scope
+
+### 3. Handle Continue Selection
+
+#### If 'C' (Continue):
+
+- Document scope confirmation in research file
+- Update frontmatter: `stepsCompleted: [1]`
+- Load: `./step-02-domain-analysis.md`
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append scope confirmation:
+
+```markdown
+## Domain Research Scope Confirmation
+
+**Research Topic:** {{research_topic}}
+**Research Goals:** {{research_goals}}
+
+**Domain Research Scope:**
+
+- Industry Analysis - market structure, competitive landscape
+- Regulatory Environment - compliance requirements, legal frameworks
+- Technology Trends - innovation patterns, digital transformation
+- Economic Factors - market size, growth projections
+- Supply Chain Analysis - value chain, ecosystem relationships
+
+**Research Methodology:**
+
+- All claims verified against current public sources
+- Multi-source validation for critical domain claims
+- Confidence level framework for uncertain information
+- Comprehensive domain coverage with industry-specific insights
+
+**Scope Confirmed:** {{date}}
+```
+
+## SUCCESS METRICS:
+
+✅ Domain research scope clearly confirmed with user
+✅ All domain analysis areas identified and explained
+✅ Research methodology emphasized
+✅ [C] continue option presented and handled correctly
+✅ Scope confirmation documented when user proceeds
+✅ Proper routing to next domain research step
+
+## FAILURE MODES:
+
+❌ Not clearly confirming domain research scope with user
+❌ Missing critical domain analysis areas
+❌ Not explaining that web search is required for current facts
+❌ Not presenting [C] continue option
+❌ Proceeding without user scope confirmation
+❌ Not routing to next domain research step
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## NEXT STEP:
+
+After user selects 'C', load `./step-02-domain-analysis.md` to begin industry analysis.
+
+Remember: This is SCOPE CONFIRMATION ONLY - no actual domain research yet, just confirming the research approach and scope!