@hanzlaa/rcode 2.1.0

package/rihal/workflows/why.md

@@ -0,0 +1,130 @@
+<purpose>
+Explain the reasoning behind a Rihal decision: why this panel was selected, why this question was classified, why this deviation was logged, or cite a prior decision from state.json.
+</purpose>
+
+## Step 0: Usage Check
+
+Verify non-empty argument: `/rihal:why <topic-or-question>`
+
+Examples:
+- `/rihal:why should I use waleed for this question`
+- `/rihal:why did it classify as codebase`
+- `/rihal:why did we deviate from the plan`
+- `/rihal:why choose this tech stack`
+
+If empty: `Usage: /rihal:why <topic-or-question>`
+
+## Step 1: Detect What User Is Asking About
+
+Parse the question to determine category:
+
+1. **Panel selection**: If contains "panel", "waleed", "hussain", "fatima", "sadiq" → Branch to Step 2a
+2. **Classification**: If contains "classify", "type", "question type", "category" → Branch to Step 2b
+3. **Deviation**: If contains "deviation", "deviate", "didn't follow" → Branch to Step 2c
+4. **General decision**: Default → Branch to Step 2d
+
+## Step 2a: Panel Selection Reasoning
+
+Run: `node .rihal/bin/rihal-tools.cjs select-panel "$ARGUMENTS" --explain`
+
+Output shows:
+```json
+{
+  "panel": ["waleed", "hussain"],
+  "scores": { "waleed": 85, "hussain": 78, "fatima": 62 },
+  "question": "user question here"
+}
+```
+
+Format output as:
+
+```
+📋 Panel Selection for: {question}
+
+Selected: {panel agents joined with commas}
+
+Scoring breakdown:
+{table of all agents with scores, sorted descending}
+
+Why this panel:
+- {top agent}: {reason from scoring logic}
+- {next agent}: {reason}
+
+Alternative considered: {2nd place agent} scored {score} but lower fit for this question type
+```
+
+## Step 2b: Question Classification
+
+Run: `node .rihal/bin/rihal-tools.cjs classify-question "$ARGUMENTS"`
+
+Output shows classification type and signals matched.
+
+Format output as:
+
+```
+🏗️ Question Classification: {question}
+
+**Type:** {codebase|discovery|market|greenfield|team|release|design}
+
+**Signals matched:**
+{list the matched phrases from the question}
+
+**What this means:**
+- Codebase: existing code analysis — scan codebase, use engineer panel
+- Discovery: choosing what to build — requires research/market context
+- Market: external context — may need research agents
+- Greenfield: starting from scratch — consider deep requirements phase
+- Team: people/process questions — involve PM, leadership agents
+- Release: production/shipping — involve ops, security agents
+- Design: UX/visual — involve design agents
+
+**Recommendation:** {brief next step based on classification}
+```
+
+## Step 2c: Deviation Reasoning
+
+Read `.rihal/state.json` and extract `executions[].deviations[]`:
+
+For each deviation in the most recent execution:
+
+```
+🛡️ Deviation: {deviation.title}
+
+Reason: {deviation.reason}
+Impact: {deviation.impact}
+Timestamp: {when it occurred}
+Context: {brief context from plan_id that was executed}
+```
+
+If no deviations found: `No deviations logged in current state.`
+
+## Step 2d: General Decision Lookup
+
+Read `.rihal/state.json` and search `decisions[]` for entry matching the topic.
+
+If found:
+
+```
+📋 Decision: {decision.title}
+
+**Made:** {timestamp}
+**Category:** {category}
+**Reasoning:** {decision.reasoning}
+**Alternatives considered:** {decision.alternatives}
+**Next decision point:** {decision.next_checkpoint}
+```
+
+If not found: `No recorded decision matches "{ARGUMENTS}". Use /rihal:progress to see recent context.`
+
+## Success Criteria
+
+- [ ] Category detected correctly
+- [ ] Relevant data fetched from state.json or rihal-tools
+- [ ] Output explains the "why" with data and reasoning
+- [ ] Format is scannable (tables, bullets, clear sections)
+
+## On Error
+
+- rihal-tools error → Show error message
+- state.json missing → `State not initialized. Run /rihal:new-project first.`
+- No match found → Suggest `/rihal:progress` for context

package/rihal/workflows/workstream.md

@@ -0,0 +1,197 @@
+# Workflow: rihal:workstream
+
+<purpose>
+Manage parallel workstreams (milestone tracks) in Rihal. A workstream is an independent execution path with its own phases and tasks. Multiple workstreams can run in parallel, sharing decisions, blockers, and council sessions. This workflow handles creation, switching, listing, and completion of workstreams stored in state.json.
+</purpose>
+
+<required_reading>
+@.rihal/references/workstream-flag.md
+</required_reading>
+
+## Step 0 — Usage check
+
+If `$ARGUMENTS` is empty or contains only `--help` or `-h`:
+- Print the usage block below
+- STOP — do not proceed to Step 1
+
+**Usage:**
+```
+/rihal:workstream create --name <name>
+/rihal:workstream switch --name <name>
+/rihal:workstream list
+/rihal:workstream status
+/rihal:workstream complete --name <name>
+```
+
+**Examples:**
+```
+/rihal:workstream create --name "Frontend Redesign"
+/rihal:workstream switch --name "Frontend Redesign"
+/rihal:workstream list
+/rihal:workstream status
+/rihal:workstream complete --name "Backend Migration"
+```
+
+Only after the user provides arguments, proceed to Step 1.
+
+## Step 1 — Parse arguments
+
+Extract from `$ARGUMENTS`:
+- `subcommand` — one of: `create`, `switch`, `list`, `status`, `complete`
+- `--name` flag value (for `create`, `switch`, `complete`)
+
+Call the state helper:
+```bash
+RESULT=$(node .rihal/bin/rihal-tools.cjs state workstream-validate "$subcommand" --name "${NAME}" 2>&1)
+```
+
+If validation fails, print error and STOP.
+
+## Step 2 — Execute subcommand
+
+### Subcommand: create
+
+**Check:** name is not empty, does not already exist in state.json workstreams.
+
+**Execute:**
+```bash
+node .rihal/bin/rihal-tools.cjs state workstream-create --name "$NAME"
+```
+
+**Output:**
+```
+✅ Workstream created: {name}
+   ID: {id}
+   Active: false
+   Phases: 0
+```
+
+Set it as active unless user specifies `--no-activate` (not currently supported — leave for future).
+
+### Subcommand: switch
+
+**Check:** name exists in workstreams.
+
+**Execute:**
+```bash
+node .rihal/bin/rihal-tools.cjs state workstream-switch --name "$NAME"
+```
+
+**Output:**
+```
+✅ Switched to workstream: {name}
+   Previous: {old_name}
+   Phases in this workstream: {count}
+```
+
+### Subcommand: list
+
+**Execute:**
+```bash
+node .rihal/bin/rihal-tools.cjs state workstream-list
+```
+
+**Output (formatted table):**
+```
+Name                     Active  Completed  Phases  Created
+─────────────────────────────────────────────────────────────
+Frontend Redesign        ✓       ✗          3       2026-04-12
+Backend Migration        ✗       ✓          2       2026-04-10
+API Refactor             ✗       ✗          1       2026-04-09
+```
+
+### Subcommand: status
+
+**Execute:**
+```bash
+node .rihal/bin/rihal-tools.cjs state workstream-status
+```
+
+**Output:**
+```
+📌 Current Workstream
+
+Name: {name}
+Active: {yes|no}
+Completed: {yes|no}
+Phases: {count}
+Created: {date}
+
+Recent phases:
+  - {phase_name} ({date})
+  - {phase_name} ({date})
+```
+
+### Subcommand: complete
+
+**Check:** name exists and is not already completed.
+
+**Execute:**
+```bash
+node .rihal/bin/rihal-tools.cjs state workstream-complete --name "$NAME"
+```
+
+**Output:**
+```
+✅ Marked workstream complete: {name}
+   Completed at: {ISO date}
+   All phases: {count}
+   Commits in this workstream: {count}
+```
+
+## Step 3 — Update state validation
+
+After any state mutation (create/switch/complete), validate:
+- workstreams array exists
+- active_workstream field is set
+- no duplicate names
+- all workstreams have: name, created (ISO), active (bool), completed (bool), phases (array)
+
+## Data Structure
+
+All workstreams are stored in state.json:
+
+```json
+{
+  "workstreams": [
+    {
+      "name": "Frontend Redesign",
+      "id": "ws-abc123",
+      "created": "2026-04-12T10:30:00Z",
+      "active": true,
+      "completed": false,
+      "phases": []
+    }
+  ],
+  "active_workstream": "Frontend Redesign"
+}
+```
+
+- `name` — human readable workstream name (unique)
+- `id` — short UUID or hash (for future linking)
+- `created` — ISO timestamp when created
+- `active` — boolean, only one workstream is active at a time
+- `completed` — boolean, marks workstream as done
+- `phases` — array of phase objects that belong to this workstream
+
+**Shared state** (NOT scoped to workstream):
+- `decisions` — all decisions apply to all workstreams
+- `blockers` — all blockers apply to all workstreams
+- `council_sessions` — sessions record which workstream they apply to (if any)
+
+**Future:** phases will record which workstream they belong to via `workstream_id` field.
+
+## 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
+