@hanzlaa/rcode 2.1.0

package/rihal/skills/core/rihal-shard-doc/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: rihal-shard-doc
+description: 'Splits large markdown documents into smaller, organized files based on level 2 (default) sections. Use if the user says perform shard document'
+---
+
+# Shard Document
+
+**Goal:** Split large markdown documents into smaller, organized files based on level 2 sections using `npx @kayvan/markdown-tree-parser`.
+
+## CRITICAL RULES
+
+- MANDATORY: Execute ALL steps in the EXECUTION section IN EXACT ORDER
+- DO NOT skip steps or change the sequence
+- HALT immediately when halt-conditions are met
+- Each action within a step is a REQUIRED action to complete that step
+
+## EXECUTION
+
+### Step 1: Get Source Document
+
+- Ask user for the source document path if not provided already
+- Verify file exists and is accessible
+- Verify file is markdown format (.md extension)
+- If file not found or not markdown: HALT with error message
+
+### Step 2: Get Destination Folder
+
+- Determine default destination: same location as source file, folder named after source file without .md extension
+  - Example: `/path/to/architecture.md` --> `/path/to/architecture/`
+- Ask user for the destination folder path (`[y]` to confirm use of default: `[suggested-path]`, else enter a new path)
+- If user accepts default: use the suggested destination path
+- If user provides custom path: use the custom destination path
+- Verify destination folder exists or can be created
+- Check write permissions for destination
+- If permission denied: HALT with error message
+
+### Step 3: Execute Sharding
+
+- Inform user that sharding is beginning
+- Execute command: `npx @kayvan/markdown-tree-parser explode [source-document] [destination-folder]`
+- Capture command output and any errors
+- If command fails: HALT and display error to user
+
+### Step 4: Verify Output
+
+- Check that destination folder contains sharded files
+- Verify index.md was created in destination folder
+- Count the number of files created
+- If no files created: HALT with error message
+
+### Step 5: Report Completion
+
+- Display completion report to user including:
+  - Source document path and name
+  - Destination folder path
+  - Number of section files created
+  - Confirmation that index.md was created
+  - Any tool output or warnings
+- Inform user that sharding completed successfully
+
+### Step 6: Handle Original Document
+
+> **Critical:** Keeping both the original and sharded versions defeats the purpose of sharding and can cause confusion.
+
+Present user with options for the original document:
+
+> What would you like to do with the original document `[source-document-name]`?
+>
+> Options:
+> - `[d]` Delete - Remove the original (recommended - shards can always be recombined)
+> - `[m]` Move to archive - Move original to a backup/archive location
+> - `[k]` Keep - Leave original in place (NOT recommended - defeats sharding purpose)
+>
+> Your choice (d/m/k):
+
+#### If user selects `d` (delete)
+
+- Delete the original source document file
+- Confirm deletion to user: "Original document deleted: [source-document-path]"
+- Note: The document can be reconstructed from shards by concatenating all section files in order
+
+#### If user selects `m` (move)
+
+- Determine default archive location: same directory as source, in an `archive` subfolder
+  - Example: `/path/to/architecture.md` --> `/path/to/archive/architecture.md`
+- Ask: Archive location (`[y]` to use default: `[default-archive-path]`, or provide custom path)
+- If user accepts default: use default archive path
+- If user provides custom path: use custom archive path
+- Create archive directory if it does not exist
+- Move original document to archive location
+- Confirm move to user: "Original document moved to: [archive-path]"
+
+#### If user selects `k` (keep)
+
+- Display warning to user:
+  - Keeping both original and sharded versions is NOT recommended
+  - The discover_inputs protocol may load the wrong version
+  - Updates to one will not reflect in the other
+  - Duplicate content taking up space
+  - Consider deleting or archiving the original document
+- Confirm user choice: "Original document kept at: [source-document-path]"
+
+## Examples
+
+### Happy path
+**User:** "shard document ./docs/architecture.md"
+**Result:** Splits into `architecture/` folder with section files + index.md → asks what to do with original
+
+### Edge case
+**User:** "shard document" + non-markdown file
+**Result:** HALT — file must be .md format
+
+### Negative boundary
+**User:** "split this into smaller components"
+**Result:** If referring to code, not a doc sharding task. If referring to a document, proceed with sharding.
+
+## HALT CONDITIONS
+
+- HALT if npx command fails or produces no output files

package/rihal/skills/core/rihal-shard-doc/rihal-shard-doc/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: rihal-shard-doc
+description: 'Splits large markdown documents into smaller, organized files based on level 2 (default) sections. Use if the user says perform shard document'
+---
+
+# Shard Document
+
+**Goal:** Split large markdown documents into smaller, organized files based on level 2 sections using `npx @kayvan/markdown-tree-parser`.
+
+## CRITICAL RULES
+
+- MANDATORY: Execute ALL steps in the EXECUTION section IN EXACT ORDER
+- DO NOT skip steps or change the sequence
+- HALT immediately when halt-conditions are met
+- Each action within a step is a REQUIRED action to complete that step
+
+## EXECUTION
+
+### Step 1: Get Source Document
+
+- Ask user for the source document path if not provided already
+- Verify file exists and is accessible
+- Verify file is markdown format (.md extension)
+- If file not found or not markdown: HALT with error message
+
+### Step 2: Get Destination Folder
+
+- Determine default destination: same location as source file, folder named after source file without .md extension
+  - Example: `/path/to/architecture.md` --> `/path/to/architecture/`
+- Ask user for the destination folder path (`[y]` to confirm use of default: `[suggested-path]`, else enter a new path)
+- If user accepts default: use the suggested destination path
+- If user provides custom path: use the custom destination path
+- Verify destination folder exists or can be created
+- Check write permissions for destination
+- If permission denied: HALT with error message
+
+### Step 3: Execute Sharding
+
+- Inform user that sharding is beginning
+- Execute command: `npx @kayvan/markdown-tree-parser explode [source-document] [destination-folder]`
+- Capture command output and any errors
+- If command fails: HALT and display error to user
+
+### Step 4: Verify Output
+
+- Check that destination folder contains sharded files
+- Verify index.md was created in destination folder
+- Count the number of files created
+- If no files created: HALT with error message
+
+### Step 5: Report Completion
+
+- Display completion report to user including:
+  - Source document path and name
+  - Destination folder path
+  - Number of section files created
+  - Confirmation that index.md was created
+  - Any tool output or warnings
+- Inform user that sharding completed successfully
+
+### Step 6: Handle Original Document
+
+> **Critical:** Keeping both the original and sharded versions defeats the purpose of sharding and can cause confusion.
+
+Present user with options for the original document:
+
+> What would you like to do with the original document `[source-document-name]`?
+>
+> Options:
+> - `[d]` Delete - Remove the original (recommended - shards can always be recombined)
+> - `[m]` Move to archive - Move original to a backup/archive location
+> - `[k]` Keep - Leave original in place (NOT recommended - defeats sharding purpose)
+>
+> Your choice (d/m/k):
+
+#### If user selects `d` (delete)
+
+- Delete the original source document file
+- Confirm deletion to user: "Original document deleted: [source-document-path]"
+- Note: The document can be reconstructed from shards by concatenating all section files in order
+
+#### If user selects `m` (move)
+
+- Determine default archive location: same directory as source, in an `archive` subfolder
+  - Example: `/path/to/architecture.md` --> `/path/to/archive/architecture.md`
+- Ask: Archive location (`[y]` to use default: `[default-archive-path]`, or provide custom path)
+- If user accepts default: use default archive path
+- If user provides custom path: use custom archive path
+- Create archive directory if it does not exist
+- Move original document to archive location
+- Confirm move to user: "Original document moved to: [archive-path]"
+
+#### If user selects `k` (keep)
+
+- Display warning to user:
+  - Keeping both original and sharded versions is NOT recommended
+  - The discover_inputs protocol may load the wrong version
+  - Updates to one will not reflect in the other
+  - Duplicate content taking up space
+  - Consider deleting or archiving the original document
+- Confirm user choice: "Original document kept at: [source-document-path]"
+
+## HALT CONDITIONS
+
+- HALT if npx command fails or produces no output files
+
+## Output Format
+
+- Original doc preserved as index (TOC linking to shards)
+- Shards at `{doc_stem}/{shard-slug}.md` under the parent's dir
+- Each shard stays under 500 lines
+- Cross-shard references via relative markdown links
+
+## Examples
+
+### Happy Path
+**Input:** "Shard this 1500-line PRD into sections"
+**Expected:** PRD.md becomes index; sections split into PRD/{section-slug}.md files. Links preserved.
+
+### Negative Test
+**Input:** Shard a document under 500 lines
+**Expected:** Refuse — too small to benefit from sharding. Suggest alternative.

package/rihal/team.yaml

@@ -0,0 +1,343 @@
+# Rihal v2 Agent Roster
+# Structured definition of all installed agents: roles, authority levels, domain keywords for council dispatch
+# Updated: 2026-04-23
+
+agents:
+  - id: rihal-sadiq
+    name: Sadiq (صادق)
+    file_path: rihal/agents/rihal-sadiq.md
+    role: Director of Strategy
+    authority_level: strategic
+    domain_keywords:
+      - strategy
+      - priority
+      - kill-criterion
+      - opportunity-cost
+      - should-we-build
+      - timing
+      - market-opportunity
+    description: Pushes for measurable outcomes and kill criteria. Answers "should we build this", "why now", "what NOT to do" questions.
+
+  - id: rihal-waleed
+    name: Waleed (وليد)
+    file_path: rihal/agents/rihal-waleed.md
+    role: Chief Technology Officer
+    authority_level: technical
+    domain_keywords:
+      - architecture
+      - stack
+      - feasibility
+      - security
+      - scale
+      - performance
+      - tech-debt
+      - database
+      - infrastructure
+    description: Answers architecture, stack selection, technical feasibility, security, and scale questions.
+
+  - id: rihal-fatima
+    name: Fatima (فاطمة)
+    file_path: rihal/agents/rihal-fatima.md
+    role: QA Lead
+    authority_level: quality
+    domain_keywords:
+      - quality
+      - testing
+      - test-strategy
+      - coverage
+      - release-readiness
+      - regression
+      - bugs
+      - qa-gates
+    description: Answers quality gates, test strategy, coverage, release readiness, and "is this production-ready" questions.
+
+  - id: rihal-mariam
+    name: Mariam (مريم)
+    file_path: rihal/agents/rihal-mariam.md
+    role: Marketing & Growth Lead
+    authority_level: growth
+    domain_keywords:
+      - market-research
+      - discovery
+      - user-research
+      - gtm
+      - positioning
+      - messaging
+      - growth-strategy
+    description: Market research, user discovery, GTM strategy, positioning, and growth metrics.
+
+  - id: rihal-hussain-pm
+    name: Hussain (حسين)
+    file_path: rihal/agents/rihal-hussain-pm.md
+    role: Product Manager
+    authority_level: product
+    domain_keywords:
+      - scope
+      - requirements
+      - prd
+      - user-stories
+      - acceptance-criteria
+      - backlog
+    description: Scope, requirements, PRD writing, user stories, and backlog curation.
+
+  - id: rihal-tech-writer
+    name: Tech Writer
+    file_path: rihal/agents/rihal-tech-writer.md
+    role: Technical Documentation Specialist
+    authority_level: operational
+    domain_keywords:
+      - documentation
+      - readme
+      - api-docs
+      - changelog
+      - migration-guide
+      - inline-comments
+    description: Generates and updates README, API docs, changelogs, migration guides, and inline code comments.
+
+  - id: rihal-yousef
+    name: Yousef (يوسف)
+    file_path: rihal/agents/rihal-yousef.md
+    role: Senior Backend Engineer
+    authority_level: technical
+    domain_keywords:
+      - backend
+      - api
+      - database
+      - performance
+      - latency
+      - queues
+      - webhooks
+      - integrations
+      - p50
+      - p95
+    description: Backend implementation, API design, database queries, performance tuning, and latency diagnosis.
+
+  - id: rihal-haitham
+    name: Haitham (هيثم)
+    file_path: rihal/agents/rihal-haitham.md
+    role: Senior Frontend Engineer
+    authority_level: technical
+    domain_keywords:
+      - frontend
+      - react
+      - nextjs
+      - components
+      - rtl
+      - arabic-layout
+      - accessibility
+      - a11y
+      - bundle-size
+    description: React/Next.js, component design, RTL/Arabic layouts, accessibility, and frontend performance.
+
+  - id: rihal-zayd
+    name: Zayd (زيد)
+    file_path: rihal/agents/rihal-zayd.md
+    role: Senior ML Engineer
+    authority_level: technical
+    domain_keywords:
+      - ml
+      - machine-learning
+      - ocr
+      - llm
+      - rag
+      - retrieval
+      - embeddings
+      - vector-search
+      - nlp
+      - arabic-nlp
+    description: ML model selection, training, LLM integration, RAG/retrieval, vector search, and Arabic NLP.
+
+  - id: rihal-layla
+    name: Layla (ليلى)
+    file_path: rihal/agents/rihal-layla.md
+    role: UX Designer
+    authority_level: design
+    domain_keywords:
+      - ux
+      - user-experience
+      - interaction-design
+      - user-flow
+      - wireframe
+      - design-system
+      - accessibility
+      - usability
+    description: User experience design, interaction flows, design systems, accessibility audits, and usability reviews.
+
+  - id: rihal-zahra
+    name: Zahra (زهرة)
+    file_path: rihal/agents/rihal-zahra.md
+    role: Branding & Creative Director
+    authority_level: design
+    domain_keywords:
+      - brand
+      - brand-identity
+      - typography
+      - arabic-typography
+      - color-system
+      - design-tokens
+      - visual-language
+      - brand-audit
+    description: Brand identity, visual language, typography systems (Latin + Arabic), color systems, and design tokens.
+
+  - id: rihal-nasser
+    name: Nasser (ناصر)
+    file_path: rihal/agents/rihal-nasser.md
+    role: Software Engineering Manager
+    authority_level: management
+    domain_keywords:
+      - 1on1
+      - hiring
+      - onboarding
+      - growth-plan
+      - performance-review
+      - team-health
+      - burnout
+      - squad-composition
+    description: People operations, 1:1s, hiring, onboarding, growth plans, team health, and burnout detection.
+
+  - id: rihal-khalid
+    name: Khalid (خالد)
+    file_path: rihal/agents/rihal-khalid.md
+    role: DevOps & Infrastructure Engineer
+    authority_level: operational
+    domain_keywords:
+      - devops
+      - ci-cd
+      - deployment
+      - containers
+      - docker
+      - kubernetes
+      - monitoring
+      - infrastructure
+      - release-engineering
+    description: Deployment pipelines, CI/CD, container orchestration, cloud infrastructure, monitoring, and release engineering.
+
+  - id: rihal-noor
+    name: Noor (نور)
+    file_path: rihal/agents/rihal-noor.md
+    role: Technical Writer & Presentation Lead
+    authority_level: operational
+    domain_keywords:
+      - documentation
+      - readme
+      - api-docs
+      - mermaid
+      - diagrams
+      - pitch-deck
+      - changelog
+      - blog-post
+    description: Documentation, README files, API docs, architecture diagrams, changelogs, pitch decks, and blog posts.
+
+  - id: rihal-ahmed
+    name: Ahmed Al Hassani (أحمد الحسني)
+    file_path: rihal/agents/rihal-ahmed.md
+    role: Technology & Development Director
+    authority_level: strategic
+    domain_keywords:
+      - delivery-plan
+      - engineering-standards
+      - raci
+      - cross-team
+      - dora-metrics
+      - tech-debt-backlog
+      - delivery-timeline
+    description: Bridges CTO vision to executable delivery. Engineering standards, DORA metrics, cross-team coordination.
+
+  - id: rihal-hanzla
+    name: Hanzla (حنظلة)
+    file_path: rihal/agents/rihal-hanzla.md
+    role: Senior Full-Stack Engineer
+    authority_level: technical
+    domain_keywords:
+      - implementation
+      - story-execution
+      - code
+      - bug-fix
+      - refactoring
+      - testing
+    description: Story execution, code implementation, bug fixes, refactoring, and hands-on development.
+
+  - id: rihal-omar
+    name: Omar (عمر)
+    file_path: rihal/agents/rihal-omar.md
+    role: Software Engineer
+    authority_level: operational
+    domain_keywords:
+      - implementation
+      - code
+      - pairing
+      - tasks
+      - migrations
+    description: Generalist engineer for implementation tasks spanning frontend and backend. Pairs with Hanzla on complex stories.
+
+utility_agents:
+  - id: rihal-planner
+    name: Rihal Planner
+    role: Phase Planning
+    authority_level: operational
+    domain_keywords:
+      - planning
+      - phase-plan
+      - task-breakdown
+    description: Creates detailed implementation plans from scope and context.
+
+  - id: rihal-executor
+    name: Rihal Executor
+    role: Implementation
+    authority_level: operational
+    domain_keywords:
+      - implementation
+      - execution
+      - code-changes
+    description: Executes planned work, commits changes, creates summaries.
+
+  - id: rihal-verifier
+    name: Rihal Verifier
+    role: Quality Verification
+    authority_level: quality
+    domain_keywords:
+      - verification
+      - testing
+      - validation
+    description: Verifies phase completion and checks quality gates.
+
+# Council panel routing rules
+# These rules determine which agents are spawned for different question types.
+# Panel scorer (council-panel.cjs) picks from these based on keyword signals.
+routing:
+  market:
+    - rihal-mariam      # leads
+    - rihal-hussain-pm  # scopes
+    - rihal-sadiq       # kill criteria
+  codebase:
+    - rihal-waleed      # architecture lead
+    - rihal-yousef      # backend implementation
+    - rihal-fatima      # quality gates
+  performance:
+    - rihal-yousef      # backend perf diagnosis owns p50/p95/throughput
+    - rihal-waleed      # architecture-level perf decisions (caching, sharding)
+    - rihal-fatima      # benchmarking + regression guards
+  ml:
+    - rihal-zayd        # ML/OCR/retrieval lead
+    - rihal-yousef      # integration points (queues, APIs)
+    - rihal-fatima      # eval + perf testing
+  frontend:
+    - rihal-haitham     # React/Next.js/RTL implementation
+    - rihal-layla       # UX + interaction design
+    - rihal-fatima      # accessibility + visual regression
+  team:
+    - rihal-sadiq       # leads
+    - rihal-nasser      # people/ops
+  release:
+    - rihal-fatima      # leads
+    - rihal-waleed      # architecture
+    - rihal-khalid      # infra/deploy (if installed)
+  design:
+    - rihal-layla       # UX design lead
+    - rihal-zahra       # branding + visual identity
+    - rihal-waleed      # technical feasibility
+  greenfield:
+    - rihal-mariam      # market
+    - rihal-hussain-pm  # scope
+    - rihal-waleed      # feasibility
+    - rihal-sadiq       # strategic fit

package/rihal/templates/UI-SPEC.md

@@ -0,0 +1,127 @@
+# UI-SPEC.md — Design Contract
+
+**Project:** {project_name}  
+**Generated:** {date}  
+**Status:** draft
+
+---
+
+## 1. Color Tokens
+
+Define semantic color variables with hex values and WCAG AA contrast ratios.
+
+| Token Name | Hex | WCAG AA (on white) | Usage |
+|---|---|---|---|
+| `color-primary` | #0066CC | ✓ Pass | Primary actions, links |
+| `color-success` | #00A651 | ✓ Pass | Success states, confirmations |
+| `color-warning` | #F59E0B | ✓ Pass | Warnings, attention |
+| `color-error` | #DC2626 | ✓ Pass | Errors, destructive actions |
+| `color-neutral-900` | #111827 | ✓ Pass | Text, headings |
+| `color-neutral-500` | #6B7280 | ✓ Pass | Secondary text |
+| `color-neutral-100` | #F3F4F6 | ✓ Pass | Backgrounds, borders |
+
+---
+
+## 2. Typography
+
+| Scale | Font Family | Size | Weight | Line Height | Usage |
+|---|---|---|---|---|---|
+| H1 | {font_family} | 32px | Bold (700) | 1.2 | Page titles |
+| H2 | {font_family} | 28px | Bold (700) | 1.2 | Section titles |
+| H3 | {font_family} | 24px | Semi-bold (600) | 1.3 | Subsections |
+| Body | {font_family} | 16px | Regular (400) | 1.5 | Body text |
+| Small | {font_family} | 14px | Regular (400) | 1.4 | Secondary text |
+| Caption | {font_family} | 12px | Regular (400) | 1.4 | Labels, hints |
+
+---
+
+## 3. Component Inventory
+
+### Buttons
+
+| Component | Variants | States | Notes |
+|---|---|---|---|
+| Button | Primary, Secondary, Tertiary | Default, Hover, Active, Disabled, Loading | Icon-left, icon-right |
+| IconButton | — | Default, Hover, Active, Disabled | 24px, 32px, 40px sizes |
+
+### Forms
+
+| Component | Properties | Accessibility |
+|---|---|---|
+| Input | Text, Email, Password, Number | Label required, error text, aria-describedby |
+| Textarea | — | Label required, char counter |
+| Select | Single, Multiple | Label required, screen reader support |
+| Checkbox | — | Label adjacent, aria-label if icon-only |
+| Radio | — | Grouped with fieldset, aria-label if icon-only |
+
+### Layout
+
+| Component | Usage | Notes |
+|---|---|---|
+| Container | Max-width wrapper | 1200px max-width, responsive padding |
+| Grid | 12-column layout | Mobile: 4 cols, Tablet: 8 cols, Desktop: 12 cols |
+| Stack | Flex container | Vertical or horizontal spacing (4px, 8px, 16px, 24px) |
+
+---
+
+## 4. Interaction States
+
+All interactive elements must support:
+
+- **Default** — Normal state, no interaction
+- **Hover** — Cursor over element (desktop)
+- **Focus** — Keyboard focus, visible focus ring (2px outline, color-primary)
+- **Active** — Pressed or selected state
+- **Disabled** — Non-interactive, opacity 50%, cursor not-allowed
+- **Loading** — Spinner or progress indicator, disabled state
+
+---
+
+## 5. Accessibility (WCAG 2.1 AA)
+
+**Color Contrast:**
+- All text must meet WCAG AA minimum: 4.5:1 for normal text, 3:1 for large text
+- Do not rely on color alone to convey information
+
+**Keyboard Navigation:**
+- All interactive elements must be focusable via Tab key
+- Focus order must be logical (top-to-bottom, left-to-right)
+- Escape key closes modals and dropdowns
+
+**Screen Readers:**
+- Buttons must have `aria-label` if icon-only
+- Form inputs must have associated `<label>` or `aria-label`
+- Links must have descriptive text (not "Click here")
+- Modal dialogs must use `role="dialog"` and `aria-labelledby`
+
+**Semantic HTML:**
+- Use `<button>` for buttons, `<a>` for links
+- Use `<input type="...">` for form fields with proper types
+- Use heading hierarchy: `<h1>` → `<h2>` → `<h3>` (never skip levels)
+
+---
+
+## 6. Responsive Breakpoints
+
+| Device | Width | Columns | Font Scale | Note |
+|---|---|---|---|---|
+| Mobile | 320px–639px | 4 | 14px base | Stack all, single column |
+| Tablet | 640px–1023px | 8 | 16px base | 2-column layouts |
+| Desktop | 1024px+ | 12 | 16px base | 3-column layouts, full UI |
+
+**Touch Targets:** Minimum 44×44px on mobile, 32×32px on desktop.
+
+---
+
+## 7. Implementation Notes
+
+- **Framework:** {framework} (React, Vue, etc.)
+- **CSS Approach:** {css_approach} (Tailwind, CSS Modules, Styled Components, etc.)
+- **Icon Library:** {icon_library}
+- **Package Management:** {package_manager} (npm, pnpm, yarn)
+- **Design Tool:** {design_tool} (Figma, etc.)
+
+---
+
+**Approval Status:** Pending  
+**Last Updated:** {date}