@hanzlaa/rcode 2.1.0

package/rihal/workflows/explore.md

@@ -0,0 +1,171 @@
+<purpose>
+Socratic ideation workflow. Guides the developer through exploring an idea via probing questions,
+offers mid-conversation research when useful, then routes crystallized outputs to Rihal artifacts.
+</purpose>
+
+
+## Step 0 — Usage check
+
+If `$ARGUMENTS` is empty or contains only `--help` or `-h`:
+
+```
+/rihal:explore <argument-here>
+```
+
+**Examples:**
+```
+/rihal:explore example 1
+/rihal:explore example 2
+```
+
+STOP — do not proceed.
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+
+@.rihal/references/questioning.md
+@.rihal/references/domain-probes.md
+</required_reading>
+
+<available_agent_types>
+Valid Rihal subagent types (use exact names — do not fall back to 'general-purpose'):
+- rihal-phase-researcher — Researches specific questions and returns concise findings
+</available_agent_types>
+
+<process>
+
+## Step 1: Open the conversation
+
+If a topic was provided, acknowledge it and begin exploring:
+```
+## Explore: {topic}
+
+Let's think through this together. I'll ask questions to help clarify the idea
+before we commit to any artifacts.
+```
+
+If no topic, ask:
+```
+## Explore
+
+What's on your mind? This could be a feature idea, an architectural question,
+a problem you're trying to solve, or something you're not sure about yet.
+```
+
+## Step 2: Socratic conversation (2-5 exchanges)
+
+Guide the conversation using principles from `questioning.md` and `domain-probes.md`:
+
+- Ask **one question at a time** (never a list of questions)
+- Questions should probe: constraints, tradeoffs, users, scope, dependencies, risks
+- Use domain-specific probes contextually when the topic touches a known domain
+- Listen for signals: "or" / "versus" / "tradeoff" indicate competing priorities worth exploring
+- Reflect back what you hear to confirm understanding before moving forward
+
+**Conversation should feel natural, not formulaic.** Avoid rigid sequences. Follow the developer's energy — if they're excited about one aspect, go deeper there.
+
+## Step 3: Mid-conversation research offer (after 2-3 exchanges)
+
+If the conversation surfaces factual questions, technology comparisons, or unknowns that research could resolve, offer:
+
+```
+This touches on [specific question]. Want me to do a quick research pass before we continue?
+This would take ~30 seconds and might surface useful context.
+
+[Yes, research this] / [No, let's keep exploring]
+```
+
+If yes, spawn a research agent:
+```
+Task(
+  prompt="Quick research: {specific_question}. Return 3-5 key findings, no more than 200 words.",
+  subagent_type="rihal-phase-researcher"
+)
+```
+
+Share findings and continue the conversation.
+
+If the topic doesn't warrant research, skip this step entirely. **Don't force it.**
+
+## Step 4: Crystallize outputs (after 3-6 exchanges)
+
+When the conversation reaches natural conclusions or the developer signals readiness, propose outputs. Analyze the conversation to identify what was discussed and suggest **up to 4 outputs** from:
+
+| Type | Destination | When to suggest |
+|------|-------------|-----------------|
+| Note | `.planning/notes/{slug}.md` | Observations, context, decisions worth remembering |
+| Todo | `.planning/todos/pending/{slug}.md` | Concrete actionable tasks identified |
+| Seed | `.planning/seeds/{slug}.md` | Forward-looking ideas with trigger conditions |
+| Research question | `.planning/research/questions.md` (append) | Open questions that need deeper investigation |
+| Requirement | `REQUIREMENTS.md` (append) | Clear requirements that emerged from discussion |
+| New phase | `ROADMAP.md` (append) | Scope large enough to warrant its own phase |
+
+Present suggestions:
+```
+Based on our conversation, I'd suggest capturing:
+
+1. **Note:** "Authentication strategy decisions" — your reasoning about JWT vs sessions
+2. **Todo:** "Evaluate Passport.js vs custom middleware" — the comparison you want to do
+3. **Seed:** "OAuth2 provider support" — trigger: when user management phase starts
+
+Create these? You can select specific ones or modify them.
+
+[Create all] / [Let me pick] / [Skip — just exploring]
+```
+
+**Never write artifacts without explicit user selection.**
+
+## Step 5: Write selected outputs
+
+For each selected output, write the file:
+
+- **Notes:** Create `.planning/notes/{slug}.md` with frontmatter (title, date, context)
+- **Todos:** Create `.planning/todos/pending/{slug}.md` with frontmatter (title, date, priority)
+- **Seeds:** Create `.planning/seeds/{slug}.md` with frontmatter (title, trigger_condition, planted_date)
+- **Research questions:** Append to `.planning/research/questions.md`
+- **Requirements:** Append to `.planning/REQUIREMENTS.md` with next available REQ ID
+- **Phases:** Use existing `/rihal:add-phase` command via SlashCommand
+
+Commit if `commit_docs` is enabled:
+```bash
+node "$PROJECT_ROOT/.rihal/bin/rihal-tools.cjs" commit "docs: capture exploration — {topic_slug}" --files {file_list}
+```
+
+## Step 6: Close
+
+```
+## Exploration Complete
+
+**Topic:** {topic}
+**Outputs:** {count} artifact(s) created
+{list of created files}
+
+Continue exploring with `/rihal:explore` or start working with `/rihal:next`.
+```
+
+</process>
+
+<success_criteria>
+- [ ] Socratic conversation follows questioning.md principles
+- [ ] Questions asked one at a time, not in batches
+- [ ] Research offered contextually (not forced)
+- [ ] Up to 4 outputs proposed from conversation
+- [ ] User explicitly selects which outputs to create
+- [ ] Files written to correct destinations
+- [ ] Commit respects commit_docs config
+</success_criteria>
+
+## 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/export-to-github.md

@@ -0,0 +1,174 @@
+# Workflow: rihal:export-to-github
+
+<purpose>
+Push Rihal state to GitHub as issues, milestones, and (optionally) a Project v2 board. Thin slash-command wrapper around the existing `rihal-code github-sync` CLI, plus a `--decisions` mode that publishes the project's recent decision log as a single tracking issue.
+
+Use this to externalize a phase into GitHub for stakeholders who live in issues, to seed a milestone before starting work, or to publish decisions for team visibility.
+</purpose>
+
+<output_format>
+Open with banner:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ RIHAL ► EXPORT TO GITHUB
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Always default to dry-run. Show a preview, then require `--execute` on a follow-up run to mutate GitHub.
+</output_format>
+
+<required_reading>
+@.rihal/references/output-format.md
+@.rihal/references/command-redirect-format.md
+</required_reading>
+
+<process>
+## Step 0 — Usage check
+
+If `$ARGUMENTS` is empty or contains `--help` / `-h`:
+
+```
+/rihal:export-to-github [target] [flags]
+
+Targets (mutually exclusive):
+  (none)                    Sync all phases → milestones, epics/stories → issues
+  --phase <id>              One phase
+  --sprint <id>             One sprint's stories
+  --epic <id>               One epic + its child stories
+  --story <id>              One story only
+  --decisions [--since ISO] Publish recent decisions as a single tracking issue
+
+Flags (passed through to rihal-code github-sync):
+  --repo owner/name         Target repo (default: auto-detect from gh)
+  --with-labels             Create Rihal label taxonomy
+  --project                 Also create a GitHub Project v2 board
+  --no-update / --no-close / --no-update-body / --no-update-labels
+  --execute                 Actually mutate (default is dry-run)
+  --yes                     Skip confirmation (requires --force-yolo in yolo mode)
+```
+
+STOP — do not proceed.
+
+## Step 1 — Preflight
+
+```bash
+# gh CLI must be installed and authenticated
+command -v gh >/dev/null 2>&1 || { echo "gh CLI not installed. Install: https://cli.github.com/"; exit 0; }
+gh auth status >/dev/null 2>&1 || { echo "gh not authenticated. Run: gh auth login"; exit 0; }
+```
+
+## Step 2 — Branch on target
+
+### Standard targets (phase/sprint/epic/story/default)
+
+Delegate to the CLI:
+
+```bash
+node "$(command -v rihal-code || echo ./cli/index.js)" github-sync $ARGUMENTS
+```
+
+If `rihal-code` is not on PATH, fall back to `node ./cli/index.js github-sync $ARGUMENTS`. The CLI handles:
+
+- Auto-detecting the repo via `gh repo view`
+- Idempotent sync of phases → milestones, stories → issues
+- Dry-run by default (mutations require `--execute`)
+- Guided/yolo confirmation gates per `AGENTS.md`
+
+Pass through all arguments unchanged. Print the CLI output verbatim — do not re-wrap it.
+
+### Decisions target
+
+When `$ARGUMENTS` starts with `--decisions`, follow this branch instead:
+
+```bash
+SINCE=""
+if echo "$ARGUMENTS" | grep -q -- "--since"; then
+  SINCE=$(echo "$ARGUMENTS" | grep -oE -- "--since [^ ]+" | awk '{print $2}')
+fi
+
+# Pull this project's decisions from the cross-project log
+RESULT=$(node .rihal/bin/rihal-tools.cjs state decisions-global --limit 100 ${SINCE:+--since "$SINCE"} --project "$(node .rihal/bin/rihal-tools.cjs state read | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{try{process.stdout.write(JSON.parse(s).project||"")}catch{}}')" 2>/dev/null)
+```
+
+Render the decisions as a markdown table in the issue body:
+
+```markdown
+# Decision Log — {project_name}
+
+_Generated by `/rihal:export-to-github --decisions` on {ISO date}. Source: `~/.rihal/decisions.jsonl` (this project only)._
+
+| Date | Phase | Plan | Decision |
+|------|-------|------|----------|
+| {YYYY-MM-DD} | {phase} | {plan} | {summary} |
+| ... |
+```
+
+**Dry-run (default):**
+
+Print the rendered markdown to stdout with a header "The following issue would be created:" and STOP. Do not call `gh`.
+
+**With `--execute`:**
+
+```bash
+REPO_FLAG=""
+if echo "$ARGUMENTS" | grep -q -- "--repo"; then
+  REPO_FLAG=$(echo "$ARGUMENTS" | grep -oE -- "--repo [^ ]+")
+fi
+
+TITLE="Decision log — ${PROJECT_NAME} (${ISO_DATE})"
+
+# Confirmation gate — mandatory before mutating GitHub
+echo "About to create issue: ${TITLE} in repo $(gh repo view --json nameWithOwner -q .nameWithOwner)"
+read -p "Proceed? [y/N] " CONFIRM
+[ "$CONFIRM" = "y" ] || { echo "Aborted."; exit 0; }
+
+gh issue create $REPO_FLAG \
+  --title "$TITLE" \
+  --label "rihal,decisions" \
+  --body-file /tmp/rihal-decisions-export.md
+```
+
+On success, echo the issue URL returned by `gh issue create`.
+
+## Step 3 — Report
+
+For standard targets: rely on the CLI's own summary.
+
+For `--decisions`:
+
+```
+✓ Created issue: {url}
+  Contents: {N} decisions{since_suffix}
+```
+
+Where `since_suffix` is `, since {ISO}` if `--since` was passed.
+
+## Step 4 — Record in state
+
+After a successful mutation (either CLI or --decisions), append a decision for traceability:
+
+```bash
+node .rihal/bin/rihal-tools.cjs state add-decision \
+  "Exported ${TARGET_DESCRIPTION} to GitHub: ${ISSUE_OR_SUMMARY_URL}" \
+  2>/dev/null || true
+```
+
+This also mirrors to `~/.rihal/decisions.jsonl` so `/rihal:decisions` surfaces the export.
+</process>
+
+## Success Criteria
+
+- Dry-run is the default for every target — mutations require `--execute`
+- `gh` preflight aborts cleanly if the CLI is missing or unauthenticated
+- Standard targets fully delegate to `rihal-code github-sync` (no duplicated logic)
+- `--decisions` target reads from `~/.rihal/decisions.jsonl` filtered to this project
+- Confirmation gate is shown before `gh issue create` — yolo mode does NOT bypass this for GitHub mutations
+- Successful export is recorded via `state add-decision` for audit trail
+
+## On Error
+
+- `gh auth status` fails → tell the user to run `gh auth login`, exit
+- `gh repo view` fails (no remote) → tell the user to pass `--repo owner/name`, exit
+- `rihal-code` missing from PATH → fall back to `node ./cli/index.js`; if that also fails, instruct the user to `pnpm install` from the repo root
+- Empty decision log under `--decisions` → print "No decisions to export{since_suffix}. Run /rihal:council or complete a sprint to create some." and exit cleanly

package/rihal/workflows/forensics.md

@@ -0,0 +1,201 @@
+# Workflow: rihal:forensics
+
+<purpose>
+Analyze execution history in state.json and filesystem to detect incomplete work. Show timeline of what happened, where it broke, and suggest resume command.
+</purpose>
+
+
+## Step 0 — Usage check
+
+If `$ARGUMENTS` is empty or contains only `--help` or `-h`:
+
+```
+/rihal:forensics <argument-here>
+```
+
+**Examples:**
+```
+/rihal:forensics example 1
+/rihal:forensics 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 invalid or missing, print:
+```
+ℹ️ No rihal state found. Nothing to diagnose.
+```
+Exit.
+
+Extract:
+- **executions**: array of execution records (each has: id, phase, timestamp, status, error)
+- **current_phase**: string or null (name of current phase)
+- **last_session**: timestamp of most recent activity
+
+## Step 2 — Find failed executions
+
+From `$STATE.executions`, filter for ones where:
+- `status !== "complete"` OR
+- `error` field is present and non-empty OR
+- `status === "failed"`
+
+Store as `$FAILED_EXECS`.
+
+## Step 3 — Check for incomplete plans
+
+Scan `.planning/` directory for:
+
+```bash
+find .planning/ -name "SPRINT.md" -type f
+```
+
+For each SPRINT.md found, check if a corresponding SUMMARY.md exists:
+
+```bash
+ls -1 .planning/*/SUMMARY.md 2>/dev/null || true
+```
+
+If SPRINT.md exists but no SUMMARY.md, that's an incomplete execution.
+
+Store as `$INCOMPLETE_PLANS` (list of plan IDs).
+
+## Step 4 — Check for checkpoint artifacts
+
+Search for checkpoint markers in recent planning artifacts:
+
+```bash
+grep -r "---CHECKPOINT REACHED---" .planning/ 2>/dev/null | head -10 || echo ""
+```
+
+If found, these indicate partial progress within a phase. Extract:
+- File containing checkpoint
+- Line number
+- Context around checkpoint
+
+Store as `$CHECKPOINTS`.
+
+## Step 5 — Scan recent git history for rihal commits
+
+If `.git/` exists, extract rihal-related commits:
+
+```bash
+git log --oneline -20 --pretty=format:'%h %s' -- .rihal rihal/ .planning/ 2>/dev/null || echo ""
+```
+
+Parse to identify:
+- Last commit on .rihal (install/config changes)
+- Last commit on rihal/ (workflow/agent changes)
+- Last commit on .planning/ (execution artifacts)
+
+Store as `$RECENT_COMMITS`.
+
+## Step 6 — Assemble timeline
+
+Build a chronological timeline from:
+1. `current_phase` (if set, this is where work stopped)
+2. Most recent execution from `$FAILED_EXECS` (when and why it failed)
+3. Last item in `$INCOMPLETE_PLANS` (phase with PLAN but no SUMMARY)
+4. Most recent checkpoint from `$CHECKPOINTS` (partial progress)
+5. Last commit from `$RECENT_COMMITS`
+
+Format as:
+
+```
+Timeline of Execution
+
+T-5h: Started phase "Feature X" (/rihal:plan feature-x)
+T-3h: Phase created, plan saved to .planning/feature-x/SPRINT.md
+T-2h: Execution began — checkpoint at step 3/8
+T-0h: ❌ FAIL — Execution error: "Dependency not installed"
+      Stuck at: .planning/feature-x/ (no SUMMARY.md yet)
+      Last git: commit abc1234 "draft plan"
+```
+
+## Step 7 — Suggest recovery
+
+Based on what was found:
+
+**If incomplete phase with checkpoint:**
+```
+💡 Suggested recovery:
+
+You were working on phase "phase-name" and reached checkpoint 3.
+
+To resume:
+  /rihal:resume-work
+```
+
+**If failed execution with error:**
+```
+💡 Suggested recovery:
+
+Phase "phase-name" failed during execution:
+  Error: [error message from state.json]
+
+To retry:
+  1. Fix the issue noted above
+  2. Run: /rihal:next
+```
+
+**If incomplete plan (PLAN exists, no SUMMARY):**
+```
+💡 Suggested recovery:
+
+Phase "phase-name" was planned but never executed.
+
+To continue:
+  /rihal:execute phase-name
+```
+
+**If no incomplete work found:**
+```
+✅ No incomplete executions detected. All phases complete or active.
+```
+
+## Step 8 — Print full diagnostic report
+
+If user needs more detail, print:
+
+```
+📋 Full Forensic Report
+
+Current Phase: {phase_name or "none"}
+Last Session: {last_session timestamp}
+
+Failed Executions: {count}
+  [List each with ID, phase, error, timestamp]
+
+Incomplete Plans: {count}
+  [List each with plan ID, created timestamp]
+
+Checkpoints Reached: {count}
+  [List each with location and progress]
+
+Recent Rihal Commits: {count}
+  [List with hash, message, timestamp]
+
+Recommendation: {recovery suggestion}
+```
+
+## 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
+