@hanzlaa/rcode 2.1.0

package/rihal/workflows/dashboard.md

@@ -0,0 +1,102 @@
+# Workflow: rihal:dashboard
+
+<purpose>
+Start the Diwan view-only dashboard — a local web UI that visualizes .rihal/state.json, .planning/ artifacts, phases, decisions, and council sessions. The dashboard is read-only (no write endpoints) and runs dep-free on Node stdlib.
+</purpose>
+
+## Step 0 — Usage check
+
+If `$ARGUMENTS` contains `--help` or `-h`:
+
+```
+/rihal:dashboard [--port <N>] [--no-open]
+```
+
+**Examples:**
+```
+/rihal:dashboard                  # start on port 7717, open browser
+/rihal:dashboard --port 8080      # use a different port
+/rihal:dashboard --no-open        # don't auto-open the browser
+```
+
+STOP — do not proceed.
+
+## Step 1 — Resolve dashboard script
+
+Check for the dashboard server in priority order:
+
+1. `./server/dashboard.js` (when inside the rihal-code source repo)
+2. `./.rihal/lib/server/dashboard.js` (installed package copy)
+3. `$(npm root -g)/@hanzlahabib/rihal-code/server/dashboard.js` (global install)
+
+Store the resolved path as `$DASHBOARD`.
+
+If none found, print:
+```
+❌ Dashboard script not found.
+Run `npx rihal-code install` to install the package, or check you're inside a project with .rihal/.
+```
+Exit.
+
+## Step 2 — Parse arguments
+
+- `--port <N>` → set `PORT=$N` (default 7717)
+- `--no-open` → skip opening the browser (default: open)
+
+## Step 3 — Start the dashboard
+
+Run in the background:
+
+```bash
+PORT=$PORT node "$DASHBOARD" &
+```
+
+Wait 1 second for the server to bind.
+
+Verify it's listening:
+```bash
+curl -s -o /dev/null -w "%{http_code}" "http://localhost:$PORT/"
+```
+
+If not 200/301/302, print the error and exit.
+
+## Step 4 — Announce
+
+Print:
+```
+🏛️ Diwan dashboard running at http://localhost:$PORT
+    (view-only — browse phases, decisions, council sessions)
+    Ctrl+C in the terminal to stop.
+```
+
+If `--no-open` not passed, open the default browser:
+```bash
+# Linux
+xdg-open "http://localhost:$PORT" 2>/dev/null &
+# macOS
+open "http://localhost:$PORT" 2>/dev/null &
+```
+
+## Step 5 — Tail
+
+The server runs until the user kills it. The slash command returns after announcing; the user inspects in the browser.
+
+## Output
+
+- Server running on specified port (default 7717)
+- Browser opened to dashboard (unless --no-open)
+- Confirmation message with URL
+
+## Examples
+
+### Happy Path
+**Input:** `/rihal:dashboard`
+**Expected:** Server starts on 7717, browser opens, confirmation printed.
+
+### Edge Case: Port in use
+**Input:** `/rihal:dashboard` (when 7717 is taken)
+**Expected:** Server reports EADDRINUSE. Suggest `--port` flag with alternative.
+
+### Negative Test
+**Input:** `/rihal:dashboard --write something`
+**Expected:** Dashboard is view-only. Reject unknown write-related flags.

package/rihal/workflows/debug.md

@@ -0,0 +1,256 @@
+<purpose>
+Orchestrate parallel debug agents to investigate issues and find root causes.
+
+After identifying issues, spawn one debug agent per issue. Each agent investigates autonomously with symptoms pre-filled. Collect root causes, then hand off to plan with actual diagnoses.
+
+Orchestrator stays lean: parse issues, spawn agents, collect results, synthesize findings.
+</purpose>
+
+
+## Step 0 — Usage check
+
+If `$ARGUMENTS` is empty or contains only `--help` or `-h`:
+
+```
+/rihal:debug <argument-here>
+```
+
+**Examples:**
+```
+/rihal:debug example 1
+/rihal:debug example 2
+```
+
+STOP — do not proceed.
+
+<available_agent_types>
+Valid Rihal subagent types (use exact names — do not fall back to 'general-purpose'):
+- rihal-debugger — Diagnoses and fixes issues
+</available_agent_types>
+
+<paths>
+DEBUG_DIR=.rihal/debug
+
+Debug files use the `.rihal/debug/` path (hidden directory with leading dot).
+</paths>
+
+<core_principle>
+**Diagnose before planning fixes.**
+
+Issue identification tells us WHAT is broken (symptoms). Debug agents find WHY (root cause). Future planning then creates targeted fixes based on actual causes, not guesses.
+
+Without diagnosis: "Feature doesn't work" → guess at fix → maybe wrong
+With diagnosis: "Feature doesn't work" → "missing error handler" → precise fix
+</core_principle>
+
+## Step 0.5 — Detect non-bug questions (redirect)
+
+If input contains "should we", "what is the best way to", "how do I implement" — these are not bugs, they are how-to or strategy questions.
+
+```
+⚠ /rihal:debug investigates broken behavior, not how-to questions.
+
+For implementation guidance: /rihal:discuss waleed $ARGUMENTS
+For a strategic decision: /rihal:council $ARGUMENTS
+```
+
+Only proceed past this step if the input describes broken or unexpected behavior (e.g., "error X occurs", "feature Y doesn't work", "API returns wrong data").
+
+<process>
+
+<step name="parse_issues">
+**Extract issues from context:**
+
+From the conversation or provided input, identify:
+- What is broken or not working (truth/expected behavior)
+- Severity: blocker, major, minor
+- Reproduction steps or context
+- Any error messages or symptoms
+
+Build issue list:
+```
+issues = [
+  {truth: "Feature X doesn't work", severity: "major", context: "..."},
+  {truth: "API returns wrong data", severity: "blocker", context: "..."},
+  ...
+]
+```
+</step>
+
+<step name="report_plan">
+**Report diagnosis plan to user:**
+
+```
+## Diagnosing {N} Issues
+
+Spawning parallel debug agents to investigate root causes:
+
+| Issue (Truth) | Severity |
+|---------------|----------|
+| Feature X doesn't work | major |
+| API returns wrong data | blocker |
+
+Each agent will:
+1. Create DEBUG-{slug}.md with symptoms pre-filled
+2. Investigate autonomously (read code, form hypotheses, test)
+3. Return root cause
+
+This runs in parallel - all issues investigated simultaneously.
+```
+</step>
+
+<step name="spawn_agents">
+**Load agent skills:**
+
+```bash
+AGENT_SKILLS_DEBUGGER=$(node .rihal/bin/rihal-tools.cjs agent-skills rihal-debugger 2>/dev/null)
+```
+
+**Spawn debug agents in parallel:**
+
+For each issue, fill the debug-subagent-prompt template and spawn:
+
+```
+Task(
+  prompt=filled_debug_subagent_prompt + "\n\n<files_to_read>\n- .rihal/STATE.md\n</files_to_read>\n${AGENT_SKILLS_DEBUGGER}",
+  subagent_type="rihal-debugger",
+  description="Debug: {truth_short}"
+)
+```
+
+**Never pass `isolation="worktree"` without explicit user consent.** Worktree isolation creates a git worktree, which is a write operation the user may not want. If you believe isolation is genuinely needed (e.g., the debug agent may edit files), ask first via AskUserQuestion:
+
+```
+Spawn the debug agent with git worktree isolation?
+  - Safer: agent edits stay isolated until you merge
+  - Trade-off: creates a new worktree in .worktrees/ that needs cleanup
+  [yes / no — default no]
+```
+
+**All agents spawn in single message** (parallel execution).
+
+Template placeholders:
+- `{truth}`: The expected behavior that failed
+- `{expected}`: What should happen
+- `{actual}`: What actually happens
+- `{errors}`: Any error messages (or "None reported")
+- `{context}`: Reproduction context
+- `{goal}`: `find_root_cause_only`
+- `{slug}`: Generated from truth
+</step>
+
+<step name="collect_results">
+**Collect root causes from agents:**
+
+Each agent returns with:
+```
+## ROOT CAUSE FOUND
+
+**Debug Session:** ${DEBUG_DIR}/{slug}.md
+
+**Root Cause:** {specific cause with evidence}
+
+**Evidence Summary:**
+- {key finding 1}
+- {key finding 2}
+- {key finding 3}
+
+**Files Involved:**
+- {file1}: {what's wrong}
+- {file2}: {related issue}
+
+**Suggested Fix Direction:** {brief hint for planning}
+```
+
+Parse each return to extract:
+- root_cause: The diagnosed cause
+- files: Files involved
+- debug_path: Path to debug session file
+- suggested_fix: Hint for fix planning
+
+If agent returns `## INVESTIGATION INCONCLUSIVE`:
+- root_cause: "Investigation inconclusive - manual review needed"
+- Note which issue needs manual attention
+- Include remaining possibilities from agent return
+
+**Record verification metadata in DEBUG files (NEW):**
+After collecting results, each debug artifact file should have frontmatter added:
+```yaml
+---
+verified_against_commit: <current git HEAD SHA>
+verified_at: <ISO 8601 timestamp>
+---
+```
+
+This records the exact codebase state where the diagnosis was made, so downstream tools (planner, sprint-checker) can detect stale findings when branch changes.
+
+</step>
+
+<step name="report_results">
+**Report diagnosis results:**
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ RIHAL ► DIAGNOSIS COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+| Issue (Truth) | Root Cause | Files |
+|---------------|------------|-------|
+| Feature X doesn't work | Missing error handler | handler.ts |
+| API wrong data | Query missing filter | api.ts |
+
+Debug sessions: ${DEBUG_DIR}/
+
+Next: Use diagnosed root causes to plan fixes.
+```
+
+Provide quick command to review findings and plan next steps.
+</step>
+
+</process>
+
+<context_efficiency>
+Agents start with symptoms pre-filled from issue context (no symptom gathering).
+Agents only diagnose—planning handles fixes (no fix application).
+</context_efficiency>
+
+<failure_handling>
+**Agent fails to find root cause:**
+- Mark issue as "needs manual review"
+- Continue with other issues
+- Report incomplete diagnosis
+
+**Agent times out:**
+- Check DEBUG-{slug}.md for partial progress
+- Can resume investigation
+
+**All agents fail:**
+- Something systemic (permissions, git, etc.)
+- Report for manual investigation
+- Fall back to manual debugging
+</failure_handling>
+
+<success_criteria>
+- [ ] Issues parsed from context
+- [ ] Debug agents spawned in parallel
+- [ ] Root causes collected from all agents
+- [ ] Debug sessions saved to ${DEBUG_DIR}/
+- [ ] User has clear diagnosis to proceed with fixes
+</success_criteria>
+</process>
+
+## 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/decisions.md

@@ -0,0 +1,107 @@
+# Workflow: rihal:decisions
+
+<purpose>
+Surface recent decisions across every Rihal project on this machine. Decisions are mirrored to `~/.rihal/decisions.jsonl` whenever a project runs `state add-decision`. Use this to see what was decided elsewhere, find precedent for a similar call you are about to make, or answer "what did I commit to last week?".
+</purpose>
+
+<output_format>
+Open with banner:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ RIHAL ► DECISIONS (cross-project)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Newest decisions first. One row per decision with project, date, phase, and summary. Truncate long summaries to 80 chars.
+</output_format>
+
+<required_reading>
+@.rihal/references/output-format.md
+</required_reading>
+
+<process>
+## Step 0 — Usage check
+
+If `$ARGUMENTS` contains `--help` or `-h`:
+
+```
+/rihal:decisions [--limit N] [--project <name>] [--since <ISO-date>] [--this-project]
+
+  --limit N         Max rows to show (default 20, max 500)
+  --project <name>  Filter to one project name (as recorded in state.project)
+  --since <ISO>     Only decisions after the given ISO timestamp (e.g. 2026-01-01)
+  --this-project    Shortcut: filter to the current project (uses state.project)
+```
+
+STOP — do not proceed.
+
+## Step 1 — Resolve filters
+
+Parse args. If `--this-project` is set:
+
+```bash
+CURRENT_PROJECT=$(node .rihal/bin/rihal-tools.cjs state read 2>/dev/null | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>{try{process.stdout.write(JSON.parse(s).project||'')}catch{}}")
+```
+
+If non-empty, pass `--project "$CURRENT_PROJECT"` to the next step. If empty, print a warning and fall through to the unfiltered query.
+
+## Step 2 — Query the global log
+
+```bash
+QUERY_ARGS=()
+[ -n "$LIMIT" ]    && QUERY_ARGS+=(--limit "$LIMIT")
+[ -n "$PROJECT" ]  && QUERY_ARGS+=(--project "$PROJECT")
+[ -n "$SINCE" ]    && QUERY_ARGS+=(--since "$SINCE")
+RESULT=$(node .rihal/bin/rihal-tools.cjs state decisions-global "${QUERY_ARGS[@]}")
+```
+
+The result is JSON: `{decisions: [...], total: N}`. If `decisions` is empty:
+
+```
+No decisions logged yet.
+
+Decisions are mirrored to ~/.rihal/decisions.jsonl whenever /rihal:execute or /rihal:council records one. Run a council or complete a sprint to populate this log.
+```
+
+STOP.
+
+## Step 3 — Render the table
+
+For each decision, show:
+
+```
+| Date        | Project          | Phase | Decision                                                                     |
+|-------------|------------------|-------|------------------------------------------------------------------------------|
+| 2026-04-18  | rihal-code       | 04    | Ship list-plans as a table rather than a tree view                           |
+| 2026-04-17  | siraaj-platform  | 07    | Migrate queue workers to Fluid Compute for cold-start savings                |
+```
+
+Format date as `YYYY-MM-DD` (strip time) to keep the table readable. Keep project column to 16 chars; phase to 5. Truncate the Decision column with `…` if longer than 80 chars.
+
+## Step 4 — Footer
+
+```
+Showing {rendered}/{total} decisions{ filter suffix }.
+  ~/.rihal/decisions.jsonl  ({size} records)
+```
+
+Where filter suffix is, for example: ` · project=rihal-code · since=2026-01-01`.
+
+## Step 5 — Next Up routing
+
+- If `--this-project` was used and results look thin (fewer than 3) → `Next: /rihal:council "<open question>"  (then decisions flow back here)`
+- Otherwise → `Next: /rihal:decisions --project <name>  for deeper history on one project`
+</process>
+
+## Success Criteria
+
+- Empty `~/.rihal/decisions.jsonl` produces a clear empty-state message, not an error
+- `--project` and `--since` filters pass through to `state decisions-global`
+- Malformed JSONL lines are skipped (handled by rihal-tools reader), not displayed as garbage
+- Newest decision appears first
+- Table remains readable with long project names / summaries (truncation applied)
+
+## On Error
+
+If `~/.rihal/decisions.jsonl` cannot be read (permissions, missing home dir), print the underlying error and suggest `chmod`/`ls -la ~/.rihal/` for diagnosis. Do not crash other workflows — this command is read-only.