@hanzlaa/rcode 3.6.16 → 4.0.0

package/rcode/workflows/stats.md

@@ -0,0 +1,147 @@
+# Workflow: rcode-stats
+
+<purpose>
+Read .rcode/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`:
+
+```
+/rcode-stats <argument-here>
+```
+
+**Examples:**
+```
+/rcode-stats example 1
+/rcode-stats example 2
+```
+
+STOP — do not proceed.
+
+## Step 1 — Load state
+
+Read `.rcode/state.json`:
+
+```bash
+cat .rcode/state.json 2>/dev/null || echo '{}'
+```
+
+Parse as JSON. If parse fails or file doesn't exist, print:
+```
+ℹ️ No rcode state found in this project yet.
+Run /rcode-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' -- .rcode rcode/ | wc -l
+git log --oneline --pretty=format:'%s' -- .rcode rcode/ | head -5
+```
+
+Extract:
+- **rcode_commits**: count of commits on .rcode or rcode paths
+- **recent_commits**: last 5 commit messages
+
+If `.git/` does not exist, set `rcode_commits` = 0 and omit recent_commits from output.
+
+## Step 5 — Format and print output
+
+Print a human-readable stats block:
+
+```
+📊 rcode-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 (rcode-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
+
+- [ ] `.rcode/state.json` read successfully (empty object used gracefully when file is missing)
+- [ ] Phase count, plan count, council session count, decision count, and blocker count extracted and displayed
+- [ ] Timeline start date (from `state.created`) and elapsed time shown
+- [ ] Git stats displayed: total rcode commits count and last 5 commit messages
+- [ ] All stats presented in a single formatted output block — no fields silently omitted (zero values shown as `0`)
+
+## 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
+
+
+## Next Up
+
+- `/rcode-status` — get full project dashboard with phase and plan details
+- `/rcode-do` — continue working informed by the stats

package/rcode/workflows/status.md

@@ -0,0 +1,164 @@
+# Workflow: rcode-status
+
+<purpose>
+Render a human-readable project status dashboard. All data comes from a single `rcode-tools progress init` call — this workflow does NOT parse ROADMAP.md, walk SUMMARY.md files, or grep state.json itself. Rendering only. See `rcode-tools.cjs` `cmdProgress` for the source-of-truth logic (issue #159 M2.5).
+
+**SSOT:** `.rcode/state.json`. `/rcode-status` and `/rcode-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>
+@.rcode/references/auto-init-guard.md
+@.rcode/references/output-format.md
+</required_reading>
+
+<process>
+
+## Step 1 — Fetch the snapshot
+
+```bash
+SNAPSHOT=$(node .rcode/bin/rcode-tools.cjs progress init)
+VERBOSE=$(node .rcode/bin/rcode-tools.cjs config-get output.verbose 2>/dev/null || echo "false")
+```
+
+Parse as JSON. If `SNAPSHOT.ok` is not true, print a one-line error and stop.
+
+**Slim mode** (default when `VERBOSE != "true"`): Output Steps 2–3 only (banner + phases list). Skip decisions, blockers detail, and route menu — just print the top route as a single "Next: `/rcode-X`" line. Append `(run /rcode-status --verbose for full detail)`.
+
+**Verbose mode** (`VERBOSE == "true"` or `$ARGUMENTS` contains `--verbose`): Full Steps 2–6 output.
+
+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
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ rcode ► STATUS — {SNAPSHOT.project}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+╭─ rcode Status — {SNAPSHOT.project} ─────────────────────╮
+│ Milestone:  {SNAPSHOT.milestone or "—"}                 │
+│ Phase:      {SNAPSHOT.current_phase or "none started"}  │
+│ Progress:   {SNAPSHOT.bar}                              │
+│ Weighted:   {SNAPSHOT.weighted_bar}                     │
+│ Updated:    {relative_time(SNAPSHOT.updated)}           │
+╰─────────────────────────────────────────────────────────╯
+```
+
+If `SNAPSHOT.weighted_progress > 0` but `SNAPSHOT.completed_count === 0`, display
+the weighted bar as the primary progress indicator to avoid a misleading `0/N (0%)`.
+
+### Milestone health (issue #718)
+
+After the main dashboard, call `rcode-tools milestone-health` and surface
+a gauge when the milestone is full:
+
+```bash
+HEALTH=$(node ".rcode/bin/rcode-tools.cjs" milestone-health 2>/dev/null)
+```
+
+Parse `recommendation`, `open_phases`, `phase_count`. Display ONLY when
+`recommendation` is not `healthy`:
+
+```
+⚠ Milestone health: {open_phases} open / {phase_count} total — {recommendation}
+   → /rcode-complete-milestone to close, or /rcode-new-milestone to fork
+```
+
+**State-drift exception:** If `recommendation === "healthy"` AND `phase_count === 0` AND
+`SNAPSHOT.insights[]` is non-empty (drift insights present), the "healthy" reading is a
+false negative caused by state.json being out of sync with disk. In this case print:
+
+```
+⚠ Milestone health: unreadable — state.json not synced with disk.
+   Fix: node .rcode/bin/rcode-tools.cjs state sync --from-disk
+```
+
+When truly healthy (phase_count > 0, no drift insights), print nothing — keeps status terse for normal projects.
+
+## Step 3 — Phases section
+
+For each entry in `SNAPSHOT.phases[]`:
+
+**Null guard:** If `phase.disk` is `null` or missing (state-disk drift — state.json not yet synced), treat the phase as `○` (planned) and append a note `(disk state unavailable — run: node .rcode/bin/rcode-tools.cjs state sync --from-disk)`. Do NOT attempt to access fields on a null `phase.disk`.
+
+- `▶` if `phase.number === SNAPSHOT.current_phase`
+- `✓` if `phase.disk.summary_count > 0` AND `phase.disk.summary_count >= phase.disk.plan_count` AND `phase.disk.has_verification` (complete + verified; if VERIFICATION.md absent, use `◎` and label "complete-unverified")
+- `◎` if `phase.disk.summary_count > 0` AND `phase.disk.summary_count >= phase.disk.plan_count` AND NOT `phase.disk.has_verification` (work done, awaiting verification)
+- `◆` if `phase.disk.plan_count > phase.disk.summary_count` (executing — has plans, not all summarized)
+- `◇` if `phase.disk.has_context && !phase.disk.plan_count` (discussing — CONTEXT.md exists but no plan yet)
+- `◈` if `phase.disk.has_research && !phase.disk.plan_count` (researched — RESEARCH.md but no plan)
+- `○` otherwise (planned — no artifacts on disk)
+
+**Edge case — summary without sprint:** If `summary_count > 0` AND `plan_count === 0`, treat as `◎ complete-unverified` (sprint was archived or the phase used an older single-file workflow; summary is evidence of completed work).
+
+```
+Phases:
+  ▶ [04] Component compaction — executing (1/3 plans)
+  ✓ [03] Auth hardening — complete
+  ◇ [05] Billing rewrite — discussing
+  ◈ [06] API optimization — researched
+  ○ [07] Final cleanup — 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 ⚠, the blocker description, and its age. Compute age from `blocker.date` to now: if > 7 days, append `(⚡ {N} days old)` in amber; if > 30 days, append `(🔥 {N} days — stale)`. If no `date` field, render `(age unknown)`.
+
+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. Each route is **one line** — the command is the thing you copy and run:
+
+```
+Next Up:
+
+  [A] /rcode-execute 4
+  [B] /rcode-plan 5
+  [C] /rcode-audit-milestone 28 --fix-drift
+  [C] /rcode-complete-milestone
+```
+
+Format: `  [{letter}] {command}` — no label, no arrow, no indented second line. The command already contains the relevant arguments (phase number, count, flags). Group routes by letter; multiple routes sharing a letter appear on consecutive lines. 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:** "rcode install missing. Run: npx @hanzlaa/rcode 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 .rcode/bin/rcode-tools.cjs state read"
+
+## Next Up
+
+- `/rcode-next` — auto-advance to the next logical step based on current state
+- `/rcode-do` — take action on what the status dashboard surfaced

package/rcode/workflows/ui-phase.md

@@ -0,0 +1,159 @@
+# Workflow: rcode-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`:
+
+```
+/rcode-ui-phase <argument-here>
+```
+
+**Examples:**
+```
+/rcode-ui-phase example 1
+/rcode-ui-phase example 2
+```
+
+STOP — do not proceed.
+
+<available_agent_types>
+- `rcode-ux-designer` — UI specification generator
+</available_agent_types>
+
+## Step 0 — Initialize
+
+```bash
+INIT=$(node .rcode/bin/rcode-tools.cjs init ui-phase "$ARGUMENTS" 2>/dev/null)
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+If `INIT` is empty or `INIT.ok` is false, print error and exit:
+```
+Error: rcode-tools init failed. Verify .rcode/ is installed and state.json is valid.
+```
+
+Parse:
+- `flags.existing_ui` — path to existing design system or Figma export
+- `flags.design_system` — path to design tokens file
+- `ui_spec_path` — `.rcode/UI-SPEC.md` (output location)
+
+## Step 1 — Detect Existing UI Assets
+
+If `flags.existing_ui` or `flags.design_system` provided:
+```bash
+EXISTING=$(node .rcode/bin/rcode-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 `rcode-ux-designer` subagent:
+
+```
+Task tool call:
+  subagent_type: "rcode-ux-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 .rcode/bin/rcode-tools.cjs state set --ui-spec-path ".rcode/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 .rcode/bin/rcode-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:
+
+/rcode-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 /rcode-ui-phase first"
+  - "Skip for now, continue planning"
+```
+
+If "Yes, run /rcode-ui-phase first":
+```
+Run /rcode-ui-phase, then return to /rcode-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)
+
+## Next Up
+
+- `/rcode-plan` — plan the UI implementation phase against the spec
+- `/rcode-execute` — implement UI once the spec is approved

package/rcode/workflows/ui-review.md

@@ -0,0 +1,145 @@
+# Workflow: rcode-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`:
+
+```
+/rcode-ui-review <argument-here>
+```
+
+**Examples:**
+```
+/rcode-ui-review example 1
+/rcode-ui-review example 2
+```
+
+STOP — do not proceed.
+
+<available_agent_types>
+- `rcode-ui-auditor` — UI compliance auditor
+</available_agent_types>
+
+## Step 0 — Initialize
+
+```bash
+INIT=$(node .rcode/bin/rcode-tools.cjs init ui-review "$ARGUMENTS" 2>/dev/null)
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+If `INIT` is empty or `INIT.ok` is false, print error and exit:
+```
+Error: rcode-tools init failed. Verify .rcode/ is installed and state.json is valid.
+```
+
+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 ".rcode/UI-SPEC.md"
+```
+
+**If missing:**
+```
+⚠ UI-SPEC.md not found. Run /rcode-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 `rcode-ui-auditor` subagent:
+
+```
+Task tool call:
+  subagent_type: "rcode-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.
+       **Hex literal scan (issue #660):** run `rg -n '#[0-9A-Fa-f]{3,6}\b' <css/tailwind paths>` —
+       any hex outside the `:root { ... }` token block in globals.css (or equivalent token
+       definition file) is a regression flag. If a token is missing for the stated semantic
+       role, the fix is to ADD the token, never to inline the hex. Cite the exact file:line.
+    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:
+- `.rcode/UI-REVIEW-{phase-name}.md` (if phase specified)
+- `.rcode/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
+
+## Next Up
+
+- `/rcode-plan` — plan UI fix phases for pillar failures
+- `/rcode-correct-course` — correct UI deviations from the design spec