@hanzlaa/rcode 2.1.0

package/rihal/workflows/plant-seed.md

@@ -0,0 +1,169 @@
+<purpose>
+Capture a forward-looking idea as a structured seed file with trigger conditions.
+Seeds auto-surface during /rihal:new-milestone when trigger conditions match the
+new milestone's scope.
+
+Seeds beat deferred items because they:
+- Preserve WHY the idea matters (not just WHAT)
+- Define WHEN to surface (trigger conditions, not manual scanning)
+- Track breadcrumbs (code references, related decisions)
+- Auto-present at the right time via new-milestone scan
+</purpose>
+
+<process>
+
+<step name="parse_idea">
+Parse `$ARGUMENTS` for the idea summary.
+
+If empty, ask:
+```
+What's the idea? (one sentence)
+```
+
+Store as `$IDEA`.
+</step>
+
+<step name="create_seed_dir">
+```bash
+mkdir -p .planning/seeds
+```
+</step>
+
+<step name="gather_context">
+Ask focused questions to build a complete seed:
+
+```
+AskUserQuestion(
+  header: "Trigger",
+  question: "When should this idea surface? (e.g., 'when we add user accounts', 'next major version', 'when performance becomes a priority')",
+  options: []  // freeform
+)
+```
+
+Store as `$TRIGGER`.
+
+```
+AskUserQuestion(
+  header: "Why",
+  question: "Why does this matter? What problem does it solve or what opportunity does it create?",
+  options: []
+)
+```
+
+Store as `$WHY`.
+
+```
+AskUserQuestion(
+  header: "Scope",
+  question: "How big is this? (rough estimate)",
+  options: [
+    { label: "Small", description: "A few hours — could be a quick task" },
+    { label: "Medium", description: "A phase or two — needs planning" },
+    { label: "Large", description: "A full milestone — significant effort" }
+  ]
+)
+```
+
+Store as `$SCOPE`.
+</step>
+
+<step name="collect_breadcrumbs">
+Search the codebase for relevant references:
+
+```bash
+# Find files related to the idea keywords
+grep -rl "$KEYWORD" --include="*.ts" --include="*.js" --include="*.md" . 2>/dev/null | head -10
+```
+
+Also check:
+- Current STATE.md for related decisions
+- ROADMAP.md for related phases
+- todos/ for related captured ideas
+
+Store relevant file paths as `$BREADCRUMBS`.
+</step>
+
+<step name="generate_seed_id">
+```bash
+# Find next seed number
+EXISTING=$( (ls .planning/seeds/SEED-*.md 2>/dev/null || true) | wc -l )
+NEXT=$((EXISTING + 1))
+PADDED=$(printf "%03d" $NEXT)
+```
+
+Generate slug from idea summary.
+</step>
+
+<step name="write_seed">
+Write `.planning/seeds/SEED-{PADDED}-{slug}.md`:
+
+```markdown
+---
+id: SEED-{PADDED}
+status: dormant
+planted: {ISO date}
+planted_during: {current milestone/phase from STATE.md}
+trigger_when: {$TRIGGER}
+scope: {$SCOPE}
+---
+
+# SEED-{PADDED}: {$IDEA}
+
+## Why This Matters
+
+{$WHY}
+
+## When to Surface
+
+**Trigger:** {$TRIGGER}
+
+This seed should be presented during `/rihal:new-milestone` when the milestone
+scope matches any of these conditions:
+- {trigger condition 1}
+- {trigger condition 2}
+
+## Scope Estimate
+
+**{$SCOPE}** — {elaboration based on scope choice}
+
+## Breadcrumbs
+
+Related code and decisions found in the current codebase:
+
+{list of $BREADCRUMBS with file paths}
+
+## Notes
+
+{any additional context from the current session}
+```
+</step>
+
+<step name="commit_seed">
+```bash
+node ".rihal/bin/rihal-tools.cjs" commit "docs: plant seed — {$IDEA}" --files .planning/seeds/SEED-{PADDED}-{slug}.md
+```
+</step>
+
+<step name="confirm">
+```
+✅ Seed planted: SEED-{PADDED}
+
+"{$IDEA}"
+Trigger: {$TRIGGER}
+Scope: {$SCOPE}
+File: .planning/seeds/SEED-{PADDED}-{slug}.md
+
+This seed will surface automatically when you run /rihal:new-milestone
+and the milestone scope matches the trigger condition.
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Seed file created in .planning/seeds/
+- [ ] Frontmatter includes status, trigger, scope
+- [ ] Breadcrumbs collected from codebase
+- [ ] Committed to git
+- [ ] User shown confirmation with trigger info
+</success_criteria>

package/rihal/workflows/pr-branch.md

@@ -0,0 +1,129 @@
+<purpose>
+Create a clean branch for pull requests by filtering out .planning/ commits.
+The PR branch contains only code changes — reviewers don't see Rihal artifacts
+(SPRINT.md, SUMMARY.md, STATE.md, CONTEXT.md, etc.).
+
+Uses git cherry-pick with path filtering to rebuild a clean history.
+</purpose>
+
+<process>
+
+<step name="detect_state">
+Parse `$ARGUMENTS` for target branch (default: `main`).
+
+```bash
+CURRENT_BRANCH=$(git branch --show-current)
+TARGET=${1:-main}
+```
+
+Check preconditions:
+- Must be on a feature branch (not main/master)
+- Must have commits ahead of target
+
+```bash
+AHEAD=$(git rev-list --count "$TARGET".."$CURRENT_BRANCH" 2>/dev/null)
+if [ "$AHEAD" = "0" ]; then
+  echo "No commits ahead of $TARGET — nothing to filter."
+  exit 0
+fi
+```
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ Rihal ► PR BRANCH
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Branch: {CURRENT_BRANCH}
+Target: {TARGET}
+Commits: {AHEAD} ahead
+```
+</step>
+
+<step name="analyze_commits">
+Classify commits:
+
+```bash
+# Get all commits ahead of target
+git log --oneline "$TARGET".."$CURRENT_BRANCH" --no-merges
+```
+
+For each commit, check if it ONLY touches .planning/ files:
+
+```bash
+# For each commit hash
+FILES=$(git diff-tree --no-commit-id --name-only -r $HASH)
+ALL_PLANNING=$(echo "$FILES" | grep -v "^\.planning/" | wc -l)
+```
+
+Classify:
+- **Code commits**: Touch at least one non-.planning/ file → INCLUDE
+- **Planning-only commits**: Touch only .planning/ files → EXCLUDE
+- **Mixed commits**: Touch both → INCLUDE (planning changes come along)
+
+Display analysis:
+```
+Commits to include: {N} (code changes)
+Commits to exclude: {N} (planning-only)
+Mixed commits: {N} (code + planning — included)
+```
+</step>
+
+<step name="create_pr_branch">
+```bash
+PR_BRANCH="${CURRENT_BRANCH}-pr"
+
+# Create PR branch from target
+git checkout -b "$PR_BRANCH" "$TARGET"
+```
+
+Cherry-pick only code commits (in order):
+
+```bash
+for HASH in $CODE_COMMITS; do
+  git cherry-pick "$HASH" --no-commit
+  # Remove any .planning/ files that came along in mixed commits
+  git rm -r --cached .planning/ 2>/dev/null || true
+  git commit -C "$HASH"
+done
+```
+
+Return to original branch:
+```bash
+git checkout "$CURRENT_BRANCH"
+```
+</step>
+
+<step name="verify">
+```bash
+# Verify no .planning/ files in PR branch
+PLANNING_FILES=$(git diff --name-only "$TARGET".."$PR_BRANCH" | grep "^\.planning/" | wc -l)
+TOTAL_FILES=$(git diff --name-only "$TARGET".."$PR_BRANCH" | wc -l)
+PR_COMMITS=$(git rev-list --count "$TARGET".."$PR_BRANCH")
+```
+
+Display results:
+```
+✅ PR branch created: {PR_BRANCH}
+
+Original: {AHEAD} commits, {ORIGINAL_FILES} files
+PR branch: {PR_COMMITS} commits, {TOTAL_FILES} files
+Planning files: {PLANNING_FILES} (should be 0)
+
+Next steps:
+  git push origin {PR_BRANCH}
+  gh pr create --base {TARGET} --head {PR_BRANCH}
+
+Or use /rihal:ship to create the PR automatically.
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] PR branch created from target
+- [ ] Planning-only commits excluded
+- [ ] No .planning/ files in PR branch diff
+- [ ] Commit messages preserved from original
+- [ ] User shown next steps
+</success_criteria>

package/rihal/workflows/profile-user.md

@@ -0,0 +1,162 @@
+# Workflow: rihal:profile-user
+
+<purpose>
+Classify developer on 4 dimensions: communication style, autonomy preference, domain depth, and iteration speed. Spawn a profiler subagent to ask questions and produce a USER-PROFILE.md artifact with YAML frontmatter + structured classification.
+</purpose>
+
+
+## Step 0 — Usage check
+
+If `$ARGUMENTS` is empty or contains only `--help` or `-h`:
+
+```
+/rihal:profile-user <argument-here>
+```
+
+**Examples:**
+```
+/rihal:profile-user example 1
+/rihal:profile-user example 2
+```
+
+STOP — do not proceed.
+
+<available_agent_types>
+- `rihal-profiler` — user classification agent (spawned once per session)
+</available_agent_types>
+
+## Step 0 — Initialize
+
+```bash
+INIT=$(node .rihal/bin/rihal-tools.cjs init profile-user "$ARGUMENTS")
+```
+
+Parse:
+- `flags.json` — if set, parse as pre-filled profile JSON (skip questions)
+- `profile_path` — `.rihal/USER-PROFILE.md` (output location)
+
+**If no arguments and `--json` not provided:** Use AskUserQuestion to collect 4 profile dimensions interactively.
+
+## Step 1 — Collect Profile Data (if not `--json`)
+
+Use AskUserQuestion with 4 separate calls (one per dimension):
+
+**Q1: Communication Style**
+```
+header: "Communication"
+question: "How do you prefer to receive technical guidance?"
+multiSelect: false
+options:
+  - "Direct & dense (structured data, minimal prose)"
+  - "Balanced (explanation + examples)"
+  - "Narrative & conversational"
+  - "Persona-driven (character voice OK)"
+```
+
+**Q2: Autonomy Preference**
+```
+header: "Autonomy"
+question: "How should the agent handle decisions?"
+multiSelect: false
+options:
+  - "Autonomous (just do it, report after)"
+  - "Checkpoint-based (ask before each decision)"
+  - "Guided (suggestions + approval loops)"
+  - "Hands-off (full human control)"
+```
+
+**Q3: Domain Depth**
+```
+header: "Domain Depth"
+question: "How deep should technical explanations go?"
+multiSelect: false
+options:
+  - "Beginner (conceptual, no jargon)"
+  - "Intermediate (standard patterns, some internals)"
+  - "Advanced (architectural depth, trade-offs)"
+  - "Expert (research papers, edge cases)"
+```
+
+**Q4: Iteration Speed**
+```
+header: "Speed"
+question: "Preferred pace for feedback loops?"
+multiSelect: false
+options:
+  - "Fast (minimal detail, quick feedback)"
+  - "Balanced (normal pace)"
+  - "Thorough (deep analysis, slower)"
+  - "Adaptive (match the moment)"
+```
+
+Collect answers into `profile` object:
+```json
+{
+  "communication": "Direct & dense",
+  "autonomy": "Checkpoint-based",
+  "domain_depth": "Intermediate",
+  "iteration_speed": "Balanced"
+}
+```
+
+## Step 2 — Generate Profile
+
+**If `--json` provided:** Parse `flags.json` into `profile` object (skip questions).
+
+**Otherwise:** Use answers from Step 1.
+
+Spawn `rihal-profiler` subagent:
+
+```
+Task tool call:
+  subagent_type: "rihal-profiler"
+  description: "Generate user profile classification"
+  prompt: |
+    Generate a USER-PROFILE.md with the following profile data:
+    
+    Communication: {profile.communication}
+    Autonomy: {profile.autonomy}
+    Domain Depth: {profile.domain_depth}
+    Iteration Speed: {profile.iteration_speed}
+    
+    Output format:
+    1. YAML frontmatter with all 4 dimensions + metadata
+    2. One paragraph per dimension explaining implications
+    3. Recommended settings (e.g., verbosity, checkpoint frequency)
+    
+    Write to: {profile_path}
+```
+
+## Step 3 — Persist Profile
+
+Store `profile` object in state:
+
+```bash
+node .rihal/bin/rihal-tools.cjs state set-user-profile --json '{json-string}'
+```
+
+Print:
+```
+✅ Profile saved: {profile_path}
+
+Dimensions:
+  • Communication: {communication}
+  • Autonomy: {autonomy}
+  • Domain Depth: {domain_depth}
+  • Iteration Speed: {iteration_speed}
+
+This profile will personalize future /rihal:council and /rihal:execute responses.
+```
+
+## Success Criteria
+
+- USER-PROFILE.md created with YAML frontmatter
+- All 4 dimensions documented
+- Profile persisted to state.json
+- Message confirms location and dimensions
+
+## On Error
+
+- If AskUserQuestion fails: retry or skip to default profile
+- If subagent fails: manually create USER-PROFILE.md with frontmatter
+- If state write fails: print warning but continue (profile still written to disk)

package/rihal/workflows/progress.md

@@ -0,0 +1,184 @@
+<purpose>
+Render project progress: what was accomplished, where you are, what's pending, what's next. All data comes from a single `rihal-tools progress init` call. This workflow is a pure renderer — no direct markdown parsing, no state.json grep, no phase-directory walk.
+
+**SSOT:** `.rihal/state.json`, surfaced through `rihal-tools progress init`. `/rihal:progress` and `/rihal:status` call the same CLI and cannot disagree (issue #131 closed).
+
+For a sprint-board view, use `/rihal:sprint-status`. For a concise dashboard, use `/rihal:status`. This workflow gives the full narrative view with recent-work excerpts and an intent-tree Next Up menu.
+</purpose>
+
+<required_reading>
+@.rihal/references/output-format.md
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<output_format>
+Banner from output-format.md:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ RIHAL ► PROGRESS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Use ✓ complete / ◆ in_progress / ○ planned / 🅿 parking-lot throughout.
+End with a Next Up block rendered from the CLI's `routes[]` array.
+</output_format>
+
+<process>
+
+<step name="init_context">
+
+## 1. Init context
+
+Fetch the full progress snapshot in a single call:
+
+```bash
+SNAPSHOT=$(node .rihal/bin/rihal-tools.cjs progress init)
+```
+
+Parse as JSON.
+
+If `SNAPSHOT.project` is null AND `SNAPSHOT.phases[]` is empty:
+
+```
+No planning structure found.
+
+Run /rihal:new-project to start a new project.
+```
+
+Exit.
+
+Read `DISCUSS_MODE` from config (separate cheap call):
+
+```bash
+DISCUSS_MODE=$(node .rihal/bin/rihal-tools.cjs config 2>/dev/null | grep -oE '"discuss_mode"\s*:\s*"[^"]*"' | cut -d'"' -f4 || echo "discuss")
+```
+
+</step>
+
+<step name="recent_work">
+
+## 2. Recent work excerpts
+
+For the last 2-3 phase directories with SUMMARY.md, pull the one-liner field surgically:
+
+```bash
+# find the 3 most recent SUMMARY.md files
+(find .planning/phases -name "SUMMARY.md" -o -name "*-SUMMARY.md" 2>/dev/null) | xargs -r ls -t 2>/dev/null | head -3 | while read f; do
+  node .rihal/bin/rihal-tools.cjs summary-extract "$f" --fields one_liner,status
+done
+```
+
+Each call returns `{ ok: true, one_liner: "...", status: "..." }`. Collect into an in-memory list for rendering. This avoids loading full SUMMARY.md bodies — context-expensive and unnecessary.
+
+</step>
+
+<step name="insights">
+
+## 3. Insights — surface what the CLI noticed
+
+`SNAPSHOT.insights[]` contains drift warnings, between-milestone detection, phase-dir undercount. Render above the progress bar so the user sees divergences immediately:
+
+```
+⚠ {insight.message}     (severity: warn)
+ℹ {insight.message}     (severity: info)
+```
+
+Each insight that mentions a fix command should have it surfaced exactly as-is — e.g. "Run: node .rihal/bin/rihal-tools.cjs state sync --from-disk".
+
+</step>
+
+<step name="report">
+
+## 4. Render the progress view
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ RIHAL ► PROGRESS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+# {SNAPSHOT.project}
+
+{insights block — printed FIRST if present}
+
+**Progress:** {SNAPSHOT.bar}
+**Milestone:** {SNAPSHOT.milestone or "—"}
+**Discuss mode:** {DISCUSS_MODE}
+
+## Recent Work
+- [Phase {N}]: {one_liner extracted in step 2}
+- [Phase {N}]: {one_liner}
+
+## Current Position
+Phase [{SNAPSHOT.current_phase}] of [{SNAPSHOT.phase_count}]
+Plan progress: {completed_count}/{phase_count}
+
+## Key Decisions
+- {SNAPSHOT.decisions[].summary} — [{phase}.{plan}], {date}
+
+## Blockers
+- ⚠ {SNAPSHOT.blockers[].description} — [{phase}.{plan}]
+
+## Pending Todos
+- {todo count} pending — /rihal:check-todos to review
+(Skip if count = 0)
+
+## Active Debug Sessions
+- {count} active — /rihal:debug to continue
+(Skip if count = 0)
+```
+
+Omit any section whose underlying array is empty — don't print "Key Decisions" with zero entries.
+
+</step>
+
+<step name="next_up">
+
+## 5. Next Up — intent tree
+
+Render `SNAPSHOT.routes[]` as a grouped menu. Group by `letter` field (A / B / C). Multiple routes per letter print indented under that letter's heading:
+
+```
+▶ Next Up
+
+  [A] Execute unfinished work
+      → /rihal:execute-phase 999.5
+      → /rihal:execute-phase 66
+
+  [B] Plan researched-but-unplanned phases
+      → /rihal:plan-phase 68
+
+  [C] Close out current milestone
+      → /rihal:audit-milestone
+      → /rihal:complete-milestone
+```
+
+The CLI derives routes from current disk state (researched-not-planned phases, phases with pending plans, all-complete detection for milestone closure). Do NOT second-guess by walking disk yourself.
+
+If `SNAPSHOT.routes[]` is empty or only has fallback entries, print:
+
+```
+▶ Nothing obvious on deck.
+
+  [A] /rihal:progress          — refresh
+  [B] /rihal:council            — start a conversation on what next
+  [C] /rihal:new-milestone     — if the current cycle is done
+```
+
+</step>
+
+</process>
+
+## Success Criteria
+
+- [ ] `progress init` called once — not repeatedly per section
+- [ ] No direct parsing of ROADMAP.md, epics.md, or SUMMARY.md in the workflow body
+- [ ] Recent work uses `summary-extract --fields one_liner` (surgical read)
+- [ ] Insights section rendered when non-empty
+- [ ] Next Up is a grouped route tree, not a single suggestion
+
+## On Error
+
+- **CLI missing:** "Rihal Code install missing or stale. Run: npx @hanzlahabib/rihal-code install"
+- **CLI returns `ok: false`:** surface the CLI's error verbatim. Do not attempt to compensate — the CLI's failures are the source of truth on what's wrong.
+- **Network-dependent insights:** there should be none. Insights are computed from local state + disk only.