@hanzlaa/rcode 2.1.0

package/rihal/workflows/stats.md

@@ -0,0 +1,141 @@
+# Workflow: rihal:stats
+
+<purpose>
+Read .rihal/state.json and display project statistics: phases, plans, council sessions, decisions, blockers, timeline, and git stats.
+</purpose>
+
+
+## Step 0 — Usage check
+
+If `$ARGUMENTS` is empty or contains only `--help` or `-h`:
+
+```
+/rihal:stats <argument-here>
+```
+
+**Examples:**
+```
+/rihal:stats example 1
+/rihal:stats example 2
+```
+
+STOP — do not proceed.
+
+## Step 1 — Load state
+
+Read `.rihal/state.json`:
+
+```bash
+cat .rihal/state.json 2>/dev/null || echo '{}'
+```
+
+Parse as JSON. If parse fails or file doesn't exist, print:
+```
+ℹ️ No rihal state found in this project yet.
+Run /rihal:help to get started.
+```
+Exit.
+
+Store the parsed state as `$STATE`.
+
+## Step 2 — Compute statistics
+
+From `$STATE`, extract:
+
+- **phases**: `$STATE.phases.length` (total)
+- **active_phases**: count of phases with status = "active"
+- **plans_completed**: `$STATE.current_plan` (number completed in current phase)
+- **council_sessions**: `$STATE.council_sessions.length`
+- **chains_run**: `$STATE.executions.length` (all execution records)
+- **decisions**: `$STATE.decisions.length` (total)
+- **blockers_open**: count of blockers with status = "open"
+- **blockers_resolved**: count of blockers with status = "resolved"
+- **last_3_decisions**: extract summaries from the last 3 items in `$STATE.decisions` array (summary field or description field)
+- **timeline_start**: `$STATE.created` (ISO timestamp of first session)
+- **timeline_end**: `$STATE.last_session` (ISO timestamp of most recent activity)
+
+## Step 3 — Compute timeline duration
+
+Calculate human-readable duration from timeline_start to timeline_end:
+- If more than 30 days: show "N months"
+- If 1-30 days: show "N days"
+- If less than 1 day: show "hours"
+- If null/missing: show "never started"
+
+## Step 4 — Compute git stats (if .git exists)
+
+If `.git/` directory exists, run:
+
+```bash
+git log --oneline --pretty=format:'%s' -- .rihal rihal/ | wc -l
+git log --oneline --pretty=format:'%s' -- .rihal rihal/ | head -5
+```
+
+Extract:
+- **rihal_commits**: count of commits on .rihal or rihal paths
+- **recent_commits**: last 5 commit messages
+
+If `.git/` does not exist, set `rihal_commits` = 0 and omit recent_commits from output.
+
+## Step 5 — Format and print output
+
+Print a human-readable stats block:
+
+```
+📊 rihal:stats — Project Timeline
+
+Project: $PROJECT_NAME
+Created: $TIMELINE_START
+Updated: $TIMELINE_END
+Duration: $DURATION
+
+Phases
+  Total: N
+  Active: N
+  Example: [01] Initial Setup, [02] API Development, [02.1] Urgent Fix
+
+Plans
+  Completed: N
+  Example: [01.01] Schema setup, [01.02] Seed data
+
+Council
+  Sessions: N
+  Decisions: N (last 3: "...", "...", "...")
+
+Chains
+  Executions: N
+
+Blockers
+  Open: N
+  Resolved: N
+
+Git Activity (rihal-related)
+  Commits: N
+  Recent:
+    - [01.02] message-1
+    - [02.01] message-2
+    - [02.1] message-3
+```
+
+**ID Format Notes:**
+- Phases display as `[NN]` (e.g., `[01]`, `[02]`)
+- Decimal phases display as `[NN.M]` (e.g., `[02.1]`)
+- Plans display as `[NN.MM]` (e.g., `[01.02]`)
+- Include IDs in examples and recent commit references where available
+
+If any counts are 0, still show them (e.g., "Phases: 0").
+
+## Success Criteria
+
+- [ ] Task completed as requested
+- [ ] Output saved or reported
+- [ ] State updated if necessary
+- [ ] No errors encountered
+
+## On Error
+
+If arguments are invalid, missing files, or subagent fails:
+- Validate inputs match expected format
+- Check that required files exist
+- Retry with clearer arguments or report the specific error to the user
+

package/rihal/workflows/status.md

@@ -0,0 +1,116 @@
+# Workflow: rihal:status
+
+<purpose>
+Render a human-readable project status dashboard. All data comes from a single `rihal-tools progress init` call — this workflow does NOT parse ROADMAP.md, walk SUMMARY.md files, or grep state.json itself. Rendering only. See `rihal-tools.cjs` `cmdProgress` for the source-of-truth logic (issue #159 M2.5).
+
+**SSOT:** `.rihal/state.json`. `/rihal:status` and `/rihal:progress` both call the same CLI so they cannot disagree. If the CLI reports a drift insight, surface it — do not silently compensate.
+</purpose>
+
+<required_reading>
+@.rihal/references/output-format.md
+</required_reading>
+
+<process>
+
+## Step 1 — Fetch the snapshot
+
+```bash
+SNAPSHOT=$(node .rihal/bin/rihal-tools.cjs progress init)
+```
+
+Parse as JSON. If `SNAPSHOT.ok` is not true, print a one-line error and stop.
+
+If `SNAPSHOT.project` is empty and `SNAPSHOT.phases` is empty, print:
+
+```
+No state found. Run a council session or execute a plan to initialize state.
+```
+
+Then stop.
+
+## Step 2 — Print banner + dashboard
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ RIHAL ► STATUS — {SNAPSHOT.project}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+╭─ Rihal Status — {SNAPSHOT.project} ─────────────────────╮
+│ Milestone:  {SNAPSHOT.milestone or "—"}                 │
+│ Phase:      {SNAPSHOT.current_phase or "none started"}  │
+│ Progress:   {SNAPSHOT.bar}                              │
+│ Updated:    {relative_time(SNAPSHOT.updated)}           │
+╰─────────────────────────────────────────────────────────╯
+```
+
+## Step 3 — Phases section
+
+For each entry in `SNAPSHOT.phases[]`:
+
+- `▶` if `phase.number === SNAPSHOT.current_phase`
+- `✓` if `phase.disk.summary_count > 0` AND matches `phase.disk.plan_count` (complete)
+- `◆` if `phase.disk.plan_count > phase.disk.summary_count` (in progress)
+- `○` otherwise (planned)
+
+```
+Phases:
+  ▶ [04] Component compaction — in progress (1/3 plans)
+  ✓ [03] Auth hardening — complete
+  ○ [05] Billing rewrite — planned
+```
+
+If a phase number starts with `999.`, render with a `🅿` marker and the label `(parking lot)`.
+
+## Step 4 — Insights (NEW — issue #159)
+
+If `SNAPSHOT.insights[]` is non-empty, print above the Next Up section:
+
+```
+Insights:
+  ⚠ {insight.message}       (for severity: warn)
+  ℹ {insight.message}       (for severity: info)
+```
+
+Do NOT hide insights. They exist because the CLI noticed something the workflow would otherwise gloss over.
+
+## Step 5 — Recent decisions + blockers
+
+- If `SNAPSHOT.decisions.length > 0`, print the last 3 (most recent first).
+- If `SNAPSHOT.blockers.length > 0`, render each with ⚠ and the blocker description.
+
+Omit a section entirely when its array is empty.
+
+## Step 6 — Next Up (intent-tree)
+
+Render `SNAPSHOT.routes[]` as a Route A/B/C menu:
+
+```
+Next Up:
+
+  [A] {route where letter === "A"}
+      → {route.command}
+
+  [B] {route where letter === "B"}
+      → {route.command}
+
+  [C] {route where letter === "C"}
+      → {route.command}
+```
+
+Group routes by letter. If multiple routes share a letter, list them indented. If there are no routes, print the fallback suggestion from the CLI output.
+
+</process>
+
+## Success Criteria
+
+- [ ] State read via `progress init` — no direct ROADMAP.md or SUMMARY.md parsing
+- [ ] Drift insights surfaced if present
+- [ ] Banner + dashboard printed
+- [ ] Phases section shows symbols based on CLI-computed disk state
+- [ ] Next Up is a route tree, not a single suggestion
+
+## On Error
+
+- **CLI not found:** "Rihal Code install missing. Run: npx @hanzlahabib/rihal-code install"
+- **state.json invalid JSON:** report the CLI's exact error string — the CLI already has a clean error shape.
+- **Unexpected shape:** fall back to the banner + "State present but unreadable. Try: node .rihal/bin/rihal-tools.cjs state read"

package/rihal/workflows/ui-phase.md

@@ -0,0 +1,148 @@
+# Workflow: rihal:ui-phase
+
+<purpose>
+Produce UI-SPEC.md with formalized design contract: color tokens, typography system, component inventory, interaction states, accessibility requirements. Detects frontend keywords (React, Next.js, Vue, Tailwind, CSS, UI) and suggests this workflow early if UI-SPEC.md is absent.
+</purpose>
+
+
+## Step 0 — Usage check
+
+If `$ARGUMENTS` is empty or contains only `--help` or `-h`:
+
+```
+/rihal:ui-phase <argument-here>
+```
+
+**Examples:**
+```
+/rihal:ui-phase example 1
+/rihal:ui-phase example 2
+```
+
+STOP — do not proceed.
+
+<available_agent_types>
+- `rihal-ui-designer` — UI specification generator
+</available_agent_types>
+
+## Step 0 — Initialize
+
+```bash
+INIT=$(node .rihal/bin/rihal-tools.cjs init ui-phase "$ARGUMENTS")
+```
+
+Parse:
+- `flags.existing_ui` — path to existing design system or Figma export
+- `flags.design_system` — path to design tokens file
+- `ui_spec_path` — `.rihal/UI-SPEC.md` (output location)
+
+## Step 1 — Detect Existing UI Assets
+
+If `flags.existing_ui` or `flags.design_system` provided:
+```bash
+EXISTING=$(node .rihal/bin/rihal-tools.cjs find-files --type=design-tokens)
+```
+
+Load existing design system, extract:
+- Color palette (hex, variable names)
+- Typography scales (font family, sizes, weights, line heights)
+- Component list (buttons, forms, layouts, modals, etc.)
+- Interaction patterns (hover, focus, active, disabled states)
+
+## Step 2 — Spawn UI Designer
+
+Spawn `rihal-ui-designer` subagent:
+
+```
+Task tool call:
+  subagent_type: "rihal-ui-designer"
+  description: "Generate UI-SPEC.md"
+  prompt: |
+    Generate a UI-SPEC.md file with the following structure:
+    
+    1. **Color Tokens** — semantic variable names, hex values, accessibility contrast ratios
+    2. **Typography** — font family, scales (12px, 14px, 16px, 18px, 20px, 24px, etc.), weights, line heights
+    3. **Component Inventory** — list of UI components with property variants (size, color, state, disabled)
+    4. **Interaction States** — hover, focus, active, disabled, loading for interactive elements
+    5. **Accessibility** — WCAG 2.1 AA compliance checklist, color contrast requirements, keyboard navigation rules
+    6. **Responsive Breakpoints** — mobile, tablet, desktop breakpoints and stacking rules
+    
+    {existing_design_system_data_if_provided}
+    
+    Write to: {ui_spec_path}
+```
+
+## Step 3 — Store Reference in State
+
+Update state with UI-SPEC.md location:
+```bash
+node .rihal/bin/rihal-tools.cjs state set --ui-spec-path ".rihal/UI-SPEC.md"
+```
+
+Print:
+```
+✅ UI-SPEC.md generated: {ui_spec_path}
+
+Contains:
+  • Color Tokens
+  • Typography System
+  • Component Inventory
+  • Interaction States
+  • Accessibility Checklist
+  • Responsive Breakpoints
+
+This spec will guide component development and design consistency.
+```
+
+## Step 4 — Modify plan.md Detection (referenced in plan workflow)
+
+In plan.md workflow, add Step 0.6 — **Detect frontend keywords and suggest UI safety gate**
+
+```bash
+FRONTEND_KEYWORDS=$(node .rihal/bin/rihal-tools.cjs classify-tech --keywords "react,next.js,vue,tailwind,css,ui,component,design,frontend" "$ARGUMENTS")
+```
+
+**If `FRONTEND_KEYWORDS.has_frontend == true` AND UI-SPEC.md missing:**
+
+Check `config.yaml` for `workflow.ui_safety_gate`:
+```yaml
+workflow:
+  ui_safety_gate: true  # default true
+```
+
+If enabled, print:
+```
+⚠ Frontend project detected. Before planning, create a design contract:
+
+/rihal:ui-phase
+
+This ensures consistent UI patterns, accessibility, and design tokens across all components.
+```
+
+Offer via AskUserQuestion:
+```
+header: "UI Safety Gate"
+question: "Should we define UI-SPEC.md before planning component development?"
+options:
+  - "Yes, run /rihal:ui-phase first"
+  - "Skip for now, continue planning"
+```
+
+If "Yes, run /rihal:ui-phase first":
+```
+Run /rihal:ui-phase, then return to /rihal:plan
+```
+
+## Success Criteria
+
+- UI-SPEC.md created with all 6 sections
+- Color tokens documented with contrast ratios
+- Component inventory complete with variants
+- Accessibility checklist included
+- State updated with UI-SPEC.md path
+
+## On Error
+
+- If subagent fails: provide template UI-SPEC.md
+- If frontend detection fails: skip suggestion
+- If config.yaml missing ui_safety_gate: default to true (suggest)

package/rihal/workflows/ui-review.md

@@ -0,0 +1,130 @@
+# Workflow: rihal:ui-review
+
+<purpose>
+Retroactively audit completed UI work against the UI-SPEC.md contract. Validates across 6 pillars: color consistency, typography compliance, component inventory coverage, accessibility requirements, responsive behavior, and design coherence. Produces audit report with pass/fail per pillar.
+</purpose>
+
+
+## Step 0 — Usage check
+
+If `$ARGUMENTS` is empty or contains only `--help` or `-h`:
+
+```
+/rihal:ui-review <argument-here>
+```
+
+**Examples:**
+```
+/rihal:ui-review example 1
+/rihal:ui-review example 2
+```
+
+STOP — do not proceed.
+
+<available_agent_types>
+- `rihal-ui-auditor` — UI compliance auditor
+</available_agent_types>
+
+## Step 0 — Initialize
+
+```bash
+INIT=$(node .rihal/bin/rihal-tools.cjs init ui-review "$ARGUMENTS")
+```
+
+Parse:
+- `flags.phase` — audit specific phase (optional, default: all completed phases)
+- `flags.detailed` — include detailed findings per component
+- `spec_path` — load UI-SPEC.md if exists
+- `phase_name` — phase to audit
+
+## Step 1 — Validate UI-SPEC.md Exists
+
+```bash
+test -f ".rihal/UI-SPEC.md"
+```
+
+**If missing:**
+```
+⚠ UI-SPEC.md not found. Run /rihal:ui-phase first to create design contract.
+```
+
+Exit.
+
+## Step 2 — Load UI-SPEC.md and Codebase
+
+Read UI-SPEC.md for:
+- Expected color tokens and contrast ratios
+- Typography scales (sizes, weights, line heights)
+- Component inventory with variants
+- Accessibility requirements
+- Responsive breakpoints
+
+Scan phase/codebase for:
+- Component files (*.tsx, *.jsx, *.vue)
+- CSS/styling files (*.css, *.module.css, tailwind.config.js, etc.)
+- Accessibility attributes (aria-label, role, aria-describedby, etc.)
+- Media queries and responsive rules
+
+## Step 3 — Spawn UI Auditor
+
+Spawn `rihal-ui-auditor` subagent:
+
+```
+Task tool call:
+  subagent_type: "rihal-ui-auditor"
+  description: "Audit UI against UI-SPEC.md"
+  prompt: |
+    Audit the completed UI implementation against UI-SPEC.md contract.
+    
+    **UI-SPEC.md Reference:**
+    {contents_of_ui_spec_md}
+    
+    **Codebase to Audit:**
+    {component_files_list}
+    {styling_rules}
+    {accessibility_attributes}
+    
+    **Audit 6 pillars (pass/fail + findings):**
+    
+    1. Color Consistency — All text/backgrounds match color tokens, contrast ratios >= WCAG AA
+    2. Typography Compliance — Font sizes, weights, line heights match typography scales
+    3. Component Inventory — All specified components present, all variants implemented
+    4. Accessibility — aria-labels, roles, keyboard navigation, focus rings per WCAG 2.1 AA
+    5. Responsive Behavior — Breakpoints match, layouts stack correctly, touch targets >= 44px mobile
+    6. Design Coherence — Visual consistency, spacing system, interaction patterns uniform
+    
+    {detailed_findings_if_flag_set}
+    
+    Output format: UI-REVIEW.md with per-pillar assessment + remediation tasks
+```
+
+## Step 4 — Generate Audit Report
+
+Store audit report at:
+- `.rihal/UI-REVIEW-{phase-name}.md` (if phase specified)
+- `.rihal/UI-REVIEW.md` (if all phases)
+
+Print:
+```
+📋 UI Audit Complete
+
+Pillars:
+  {pillar_name}: {PASS|FAIL} {summary}
+
+Detailed findings: {audit_report_path}
+
+{failed_pillar_remediation_recommendations}
+```
+
+## Success Criteria
+
+- UI-SPEC.md loaded and parsed
+- All 6 pillars audited
+- Audit report generated with pass/fail per pillar
+- Remediation tasks filed (if issues found)
+
+## On Error
+
+- If UI-SPEC.md invalid: print error and suggest recreating
+- If codebase has no components: report as INCOMPLETE
+- If audit agent fails: provide template audit report structure