@hanzlaa/rcode 2.1.0

package/rihal/workflows/list-plans.md

@@ -0,0 +1,146 @@
+# Workflow: rihal:list-plans
+
+<purpose>
+Display a table of all SPRINT.md plans across every phase in `.planning/phases/`. Gives a single-screen view of every plan in the project — phase, sprint ID, goal, story counts, point totals, and execution state. Use before starting new work to see what's already planned or in flight.
+</purpose>
+
+<output_format>
+Open with banner:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ RIHAL ► PLANS ACROSS ALL PHASES
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Use status symbols in the Status column: ✓ done · ◆ active · ○ todo · ⚠ blocked.
+End with totals footer and Next Up routing hint.
+</output_format>
+
+<required_reading>
+@.rihal/references/output-format.md
+</required_reading>
+
+<process>
+## Step 0 — Usage check
+
+If `$ARGUMENTS` contains `--help` or `-h`:
+
+```
+/rihal:list-plans [--phase <id>] [--status <state>] [--detail]
+
+  --phase <id>     Filter to one phase (e.g. 04 or 04-dashboard-refresh)
+  --status <state> Filter by plan state: todo | active | done | blocked
+  --detail         Include per-story breakdown under each plan
+```
+
+STOP — do not proceed.
+
+## Step 1 — Locate phases
+
+```bash
+PHASES_DIR=".planning/phases"
+```
+
+If `$PHASES_DIR` does not exist, print:
+
+```
+No plans yet. This project has no `.planning/phases/` directory.
+
+Create the first plan:
+  /rihal:plan "<task description>"
+```
+
+STOP.
+
+List every directory under `$PHASES_DIR`. For each directory, check for a `SPRINT.md` file. Directories without a `SPRINT.md` are reported separately as "Unplanned phases".
+
+## Step 2 — Parse each SPRINT.md
+
+For every `SPRINT.md` found, extract:
+
+**From YAML frontmatter:**
+- `phase` — phase ID (e.g. `05-dashboard-refresh`)
+- `sprint` — sprint ID (e.g. `05.1`)
+- `type` — plan type (e.g. `execute`)
+- `autonomous` — true/false
+
+**From body:**
+- Goal: the text after `**Goal:**` on the first heading line
+- Stories table: parse rows matching `| {id} | {title} | {points} | {status} | {ac} |`
+  - Count stories by status: `todo`, `in_progress`, `review`, `done`, `blocked`
+  - Sum points per status bucket
+
+**Derive plan state:**
+- `done` — all stories are `done`
+- `blocked` — any story is `blocked`
+- `active` — any story is `in_progress` or `review`
+- `todo` — all stories are `todo`
+
+## Step 3 — Apply filters
+
+- If `--phase <id>`: keep only plans whose phase ID matches (prefix match allowed, e.g. `04` matches `04-dashboard-refresh`)
+- If `--status <state>`: keep only plans whose derived state equals `<state>`
+
+## Step 4 — Render the table
+
+```
+| Phase                  | Sprint | Goal                                  | Stories    | Points    | State  |
+|------------------------|--------|---------------------------------------|------------|-----------|--------|
+| 04-dashboard-refresh   | 04.1   | Dashboard shows tier breakdown...     | 0/5        | 0/15      | ○ todo |
+| 05-marketing-launch    | 05.1   | Publish to npm, polish README, demo   | 0/6        | 0/13      | ○ todo |
+```
+
+Truncate `Goal` to 40 chars with ellipsis if longer. Widen the table if the terminal allows.
+
+## Step 5 — Detail view (if `--detail`)
+
+For each plan, after its table row, print its story breakdown indented:
+
+```
+  04-dashboard-refresh / 04.1 — Dashboard Refresh
+    ✓ 04.1.01  Add tier view (Starter/Advanced/Ultra)               3pt  done
+    ◆ 04.1.02  Add sprint progress visualization                    5pt  in_progress
+    ○ 04.1.03  Add velocity chart                                   3pt  todo
+    ○ 04.1.04  Show council session list                            2pt  todo
+    ○ 04.1.05  Fix GH #12 — render per-sprint state                 2pt  todo
+```
+
+## Step 6 — Footer + totals
+
+```
+Totals: {N} plans · {done_stories}/{total_stories} stories · {done_pts}/{total_pts} points
+
+  ○ todo:    {n}     ◆ active:  {n}
+  ✓ done:    {n}     ⚠ blocked: {n}
+```
+
+## Step 7 — Next Up routing
+
+Pick ONE suggestion based on the current state:
+
+- If there is an `active` plan → `Next: /rihal:sprint-status --sprint <id>` (that plan's sprint ID)
+- If no active but todos exist → `Next: /rihal:execute .planning/phases/<first-todo-phase>/SPRINT.md`
+- If a plan is `blocked` → `Next: /rihal:correct-course --phase <id>`
+- If all done → `Next: /rihal:new-milestone  (or `/rihal:sprint-planning` for the next sprint)`
+
+If unplanned phases exist, also print:
+
+```
+⚠ Phases without SPRINT.md: {list}
+  Draft a plan:  /rihal:plan --phase <id>
+```
+</process>
+
+## Success Criteria
+
+- Every `.planning/phases/*/SPRINT.md` appears exactly once in the table
+- Plan state (done/active/todo/blocked) is correctly derived from story statuses
+- `--phase` and `--status` filters return only matching rows
+- `--detail` adds per-story lines without changing the top table
+- Phases missing `SPRINT.md` are flagged, not silently skipped
+- Next Up suggestion points to a runnable command
+
+## On Error
+
+If a `SPRINT.md` has malformed frontmatter or a broken stories table, list it under "Unparseable plans" at the bottom with the parse error, and continue rendering the rest. Do not abort the whole listing because one file is bad.

package/rihal/workflows/list-workspaces.md

@@ -0,0 +1,115 @@
+# Workflow: rihal:list-workspaces
+
+<purpose>
+Display all active workspaces with summary status, creation date, and current phase. Use this to understand what parallel work is happening and switch contexts.
+</purpose>
+
+## Step 0 — Usage check
+
+If `$ARGUMENTS` contains only `--help` or `-h`:
+
+```
+/rihal:list-workspaces [--detail]
+```
+
+STOP — do not proceed.
+
+## Step 1 — Check for workspaces
+
+Verify `.rihal/workspaces.csv` exists. If not:
+
+```
+No workspaces defined yet. Create one:
+
+/rihal:new-workspace <name>
+```
+
+STOP.
+
+## Step 2 — Parse workspaces.csv
+
+Read `.rihal/workspaces.csv` and parse each row:
+
+```csv
+name,path,created,status,parent
+{name},{path},{date},{status},{parent}
+```
+
+Store in `$WORKSPACES` array.
+
+## Step 3 — Gather workspace status
+
+For each workspace, read:
+- `{path}/planning/STATE.md` → extract current phase, active work count
+- `{path}/.workspace-meta.json` → extract description
+
+## Step 4 — Display summary table
+
+Print table:
+
+```
+Active Workspaces
+
+| Name                | Created  | Status    | Current Phase | Files |
+|---------------------|----------|-----------|---------------|-------|
+| {name}              | {date}   | {status}  | {phase}       | {#}   |
+| {name}              | {date}   | {status}  | {phase}       | {#}   |
+
+Total: {count} workspaces
+```
+
+## Step 5 — Display detail (if --detail flag)
+
+For each workspace:
+
+```
+Workspace: {NAME}
+
+  Location: {path}
+  Created: {date}
+  Status: {status}
+  Current Phase: {phase}
+  
+  Recent Activity:
+    - Last updated: {date}
+    - Active tasks: {count}
+    - Phases completed: {count}
+  
+  Use: /rihal:plan <task> --workspace={name}
+```
+
+## Step 6 — Report
+
+If no workspaces:
+
+```
+No workspaces yet. Create one:
+
+/rihal:new-workspace <name>
+```
+
+Otherwise:
+
+```
+✓ {count} active workspaces
+  Use --detail for full status
+  Switch: /rihal:workspace <name>
+  Remove: /rihal:remove-workspace <name>
+```
+
+## Success Criteria
+
+- All workspaces listed with status
+- Creation date and current phase visible
+- User can see what work is happening in parallel
+- Easy switch/remove instructions provided
+
+## On Error
+
+If `.rihal/workspaces.csv` is malformed:
+
+```
+⚠ Workspaces file corrupted. Attempting to list from disk:
+```
+
+Then list directories in `.rihal/workspaces/` directly.

package/rihal/workflows/map-codebase.md

@@ -0,0 +1,449 @@
+<purpose>
+Orchestrate parallel codebase mapper agents to analyze codebase and produce structured documents in .planning/codebase/
+
+Each agent has fresh context, explores a specific focus area, and **writes documents directly**. The orchestrator only receives confirmation + line counts, then writes a summary.
+
+Output: .planning/codebase/ folder with 7 structured documents about the codebase state.
+</purpose>
+
+<required_reading>
+@.rihal/references/output-format.md
+</required_reading>
+
+<output_format>
+Open with banner:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ RIHAL ► MAPPING CODEBASE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Use TaskCreate at start:
+- TaskCreate: "Spawn 4 parallel codebase mappers"
+- TaskCreate: "Assemble and commit codebase map"
+
+Spawn indicators as each of the 4 agents completes:
+```
+◆ Spawning 4 mappers in parallel...
+  → Map tech stack and integrations
+  → Map architecture and structure
+  → Map conventions and testing
+  → Map concerns and technical debt
+
+✓ Agent "Map tech stack" completed — STACK.md (324 lines)
+✓ Agent "Map architecture" completed — ARCHITECTURE.md (412 lines)
+✓ Agent "Map conventions" completed — CONVENTIONS.md (198 lines)
+✓ Agent "Map concerns" completed — CONCERNS.md (276 lines)
+```
+
+End with closure banner + top findings summary:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ RIHAL ► CODEBASE MAPPED ✓  ({total} lines across {N} docs)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+</output_format>
+
+
+## Step 0 — Usage check
+
+If `$ARGUMENTS` is empty or contains only `--help` or `-h`:
+
+```
+/rihal:map-codebase <argument-here>
+```
+
+**Examples:**
+```
+/rihal:map-codebase example 1
+/rihal:map-codebase example 2
+```
+
+STOP — do not proceed.
+
+<available_agent_types>
+Valid Rihal subagent types (use exact names — do not fall back to 'general-purpose'):
+- rihal-codebase-mapper — Maps project structure and dependencies
+</available_agent_types>
+
+<philosophy>
+**Why dedicated mapper agents:**
+- Fresh context per domain (no token contamination)
+- Agents write documents directly (no context transfer back to orchestrator)
+- Orchestrator only summarizes what was created (minimal context usage)
+- Faster execution (agents run simultaneously)
+
+**Document quality over length:**
+Include enough detail to be useful as reference. Prioritize practical examples (especially code patterns) over arbitrary brevity.
+
+**Always include file paths:**
+Documents are reference material for the agent when planning/executing. Always include actual file paths formatted with backticks: `src/services/user.ts`.
+</philosophy>
+
+<process>
+
+<step name="init_context" priority="first">
+Load codebase mapping context:
+
+```bash
+INIT=$(node .rihal/bin/rihal-tools.cjs init map-codebase)
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+AGENT_SKILLS_MAPPER=$(node .rihal/bin/rihal-tools.cjs agent-skills rihal-codebase-mapper 2>/dev/null)
+```
+
+Extract from init JSON: `mapper_model`, `commit_docs`, `codebase_dir`, `existing_maps`, `has_maps`, `codebase_dir_exists`.
+</step>
+
+<step name="check_existing">
+Check if .planning/codebase/ already exists using `has_maps` from init context.
+
+If `codebase_dir_exists` is true:
+```bash
+ls -la .planning/codebase/
+```
+
+**If exists:**
+
+```
+.planning/codebase/ already exists with these documents:
+[List files found]
+
+What's next?
+1. Refresh - Delete existing and remap codebase
+2. Update - Keep existing, only update specific documents
+3. Skip - Use existing codebase map as-is
+```
+
+Wait for user response.
+
+If "Refresh": Delete .planning/codebase/, continue to create_structure
+If "Update": Ask which documents to update, continue to spawn_agents (filtered)
+If "Skip": Exit workflow
+
+**If doesn't exist:**
+Continue to create_structure.
+</step>
+
+<step name="create_structure">
+Create .planning/codebase/ directory:
+
+```bash
+mkdir -p .planning/codebase
+```
+
+**Expected output files:**
+- STACK.md (from tech mapper)
+- INTEGRATIONS.md (from tech mapper)
+- ARCHITECTURE.md (from arch mapper)
+- STRUCTURE.md (from arch mapper)
+- CONVENTIONS.md (from quality mapper)
+- TESTING.md (from quality mapper)
+- CONCERNS.md (from concerns mapper)
+
+Continue to spawn_agents.
+</step>
+
+<step name="detect_runtime_capabilities">
+Before spawning agents, detect whether the current runtime supports the `Task` tool for subagent delegation.
+
+**How to detect:** Check if you have access to a `Task` tool (may be capitalized as `Task` or lowercase as `task` depending on runtime). If you do NOT have a `Task`/`task` tool (or only have tools like `browser_subagent` which is for web browsing, NOT code analysis):
+
+→ **Skip `spawn_agents` and `collect_confirmations`** — go directly to `sequential_mapping` instead.
+
+**CRITICAL:** Never use `browser_subagent` or `Explore` as a substitute for `Task`. The `browser_subagent` tool is exclusively for web page interaction and will fail for codebase analysis. If `Task` is unavailable, perform the mapping sequentially in-context.
+</step>
+
+<step name="spawn_agents" condition="Task tool is available">
+Spawn 4 parallel rihal-codebase-mapper agents.
+
+Use Task tool with `subagent_type="rihal-codebase-mapper"`, `model="{mapper_model}"`, and `run_in_background=true` for parallel execution.
+
+**CRITICAL:** Use the dedicated `rihal-codebase-mapper` agent, NOT `Explore` or `browser_subagent`. The mapper agent writes documents directly.
+
+**Agent 1: Tech Focus**
+
+```
+Task(
+  subagent_type="rihal-codebase-mapper",
+  model="{mapper_model}",
+  run_in_background=true,
+  description="Map codebase tech stack",
+  prompt="Focus: tech
+
+Analyze this codebase for technology stack and external integrations.
+
+Write these documents to .planning/codebase/:
+- STACK.md - Languages, runtime, frameworks, dependencies, configuration
+- INTEGRATIONS.md - External APIs, databases, auth providers, webhooks
+
+Explore thoroughly. Write documents directly using templates. Return confirmation only.
+${AGENT_SKILLS_MAPPER}"
+)
+```
+
+**Agent 2: Architecture Focus**
+
+```
+Task(
+  subagent_type="rihal-codebase-mapper",
+  model="{mapper_model}",
+  run_in_background=true,
+  description="Map codebase architecture",
+  prompt="Focus: arch
+
+Analyze this codebase architecture and directory structure.
+
+Write these documents to .planning/codebase/:
+- ARCHITECTURE.md - Pattern, layers, data flow, abstractions, entry points
+- STRUCTURE.md - Directory layout, key locations, naming conventions
+
+Explore thoroughly. Write documents directly using templates. Return confirmation only.
+${AGENT_SKILLS_MAPPER}"
+)
+```
+
+**Agent 3: Quality Focus**
+
+```
+Task(
+  subagent_type="rihal-codebase-mapper",
+  model="{mapper_model}",
+  run_in_background=true,
+  description="Map codebase conventions",
+  prompt="Focus: quality
+
+Analyze this codebase for coding conventions and testing patterns.
+
+Write these documents to .planning/codebase/:
+- CONVENTIONS.md - Code style, naming, patterns, error handling
+- TESTING.md - Framework, structure, mocking, coverage
+
+Explore thoroughly. Write documents directly using templates. Return confirmation only.
+${AGENT_SKILLS_MAPPER}"
+)
+```
+
+**Agent 4: Concerns Focus**
+
+```
+Task(
+  subagent_type="rihal-codebase-mapper",
+  model="{mapper_model}",
+  run_in_background=true,
+  description="Map codebase concerns",
+  prompt="Focus: concerns
+
+Analyze this codebase for technical debt, known issues, and areas of concern.
+
+Write this document to .planning/codebase/:
+- CONCERNS.md - Tech debt, bugs, security, performance, fragile areas
+
+Explore thoroughly. Write document directly using template. Return confirmation only.
+${AGENT_SKILLS_MAPPER}"
+)
+```
+
+Continue to collect_confirmations.
+</step>
+
+<step name="collect_confirmations">
+Wait for all 4 agents to complete using TaskOutput tool.
+
+**For each agent task_id returned by the Agent tool calls above:**
+```
+TaskOutput tool:
+  task_id: "{task_id from Agent result}"
+  block: true
+  timeout: 300000
+```
+
+Call TaskOutput for all 4 agents in parallel (single message with 4 TaskOutput calls).
+
+Once all TaskOutput calls return, read each agent's output file to collect confirmations.
+
+**Expected confirmation format from each agent:**
+```
+## Mapping Complete
+
+**Focus:** {focus}
+**Documents written:**
+- `.planning/codebase/{DOC1}.md` ({N} lines)
+- `.planning/codebase/{DOC2}.md` ({N} lines)
+
+Ready for orchestrator summary.
+```
+
+**What you receive:** Just file paths and line counts. NOT document contents.
+
+If any agent failed, note the failure and continue with successful documents.
+
+Continue to verify_output.
+</step>
+
+<step name="sequential_mapping" condition="Task tool is NOT available (e.g. environments that do not support parallel subagents)">
+When the `Task` tool is unavailable, perform codebase mapping sequentially in the current context. This replaces `spawn_agents` and `collect_confirmations`.
+
+**IMPORTANT:** Do NOT use `browser_subagent`, `Explore`, or any browser-based tool. Use only file system tools (Read, Bash, Write, Grep, Glob, list_dir, view_file, grep_search, or equivalent tools available in your runtime).
+
+Perform all 4 mapping passes sequentially:
+
+**Pass 1: Tech Focus**
+- Explore package.json/Cargo.toml/go.mod/requirements.txt, config files, dependency trees
+- Write `.planning/codebase/STACK.md` — Languages, runtime, frameworks, dependencies, configuration
+- Write `.planning/codebase/INTEGRATIONS.md` — External APIs, databases, auth providers, webhooks
+
+**Pass 2: Architecture Focus**
+- Explore directory structure, entry points, module boundaries, data flow
+- Write `.planning/codebase/ARCHITECTURE.md` — Pattern, layers, data flow, abstractions, entry points
+- Write `.planning/codebase/STRUCTURE.md` — Directory layout, key locations, naming conventions
+
+**Pass 3: Quality Focus**
+- Explore code style, error handling patterns, test files, CI config
+- Write `.planning/codebase/CONVENTIONS.md` — Code style, naming, patterns, error handling
+- Write `.planning/codebase/TESTING.md` — Framework, structure, mocking, coverage
+
+**Pass 4: Concerns Focus**
+- Explore TODOs, known issues, fragile areas, security patterns
+- Write `.planning/codebase/CONCERNS.md` — Tech debt, bugs, security, performance, fragile areas
+
+Use the same document templates as the `rihal-codebase-mapper` agent. Include actual file paths formatted with backticks.
+
+Continue to verify_output.
+</step>
+
+<step name="verify_output">
+Verify all documents created successfully:
+
+```bash
+ls -la .planning/codebase/
+wc -l .planning/codebase/*.md
+```
+
+**Verification checklist:**
+- All 7 documents exist
+- No empty documents (each should have >20 lines)
+
+If any documents missing or empty, note which agents may have failed.
+
+Continue to scan_for_secrets.
+</step>
+
+<step name="scan_for_secrets">
+**CRITICAL SECURITY CHECK:** Scan output files for accidentally leaked secrets before committing.
+
+Run secret pattern detection:
+
+```bash
+# Check for common API key patterns in generated docs
+grep -E '(sk-[a-zA-Z0-9]{20,}|sk_live_[a-zA-Z0-9]+|sk_test_[a-zA-Z0-9]+|ghp_[a-zA-Z0-9]{36}|gho_[a-zA-Z0-9]{36}|glpat-[a-zA-Z0-9_-]+|AKIA[A-Z0-9]{16}|xox[baprs]-[a-zA-Z0-9-]+|-----BEGIN.*PRIVATE KEY|eyJ[a-zA-Z0-9_-]+\.eyJ[a-zA-Z0-9_-]+\.)' .planning/codebase/*.md 2>/dev/null && SECRETS_FOUND=true || SECRETS_FOUND=false
+```
+
+**If SECRETS_FOUND=true:**
+
+```
+⚠️  SECURITY ALERT: Potential secrets detected in codebase documents!
+
+Found patterns that look like API keys or tokens in:
+[show grep output]
+
+This would expose credentials if committed.
+
+**Action required:**
+1. Review the flagged content above
+2. If these are real secrets, they must be removed before committing
+3. Consider adding sensitive files to Claude Code "Deny" permissions
+
+Pausing before commit. Reply "safe to proceed" if the flagged content is not actually sensitive, or edit the files first.
+```
+
+Wait for user confirmation before continuing to commit_codebase_map.
+
+**If SECRETS_FOUND=false:**
+
+Continue to commit_codebase_map.
+</step>
+
+<step name="commit_codebase_map">
+Commit the codebase map:
+
+```bash
+node .rihal/bin/rihal-tools.cjs commit "docs: map existing codebase" --files .planning/codebase/*.md
+```
+
+Continue to offer_next.
+</step>
+
+<step name="offer_next">
+Present completion summary and next steps.
+
+**Get line counts:**
+```bash
+wc -l .planning/codebase/*.md
+```
+
+**Output format:**
+
+```
+Codebase mapping complete.
+
+Created .planning/codebase/:
+- STACK.md ([N] lines) - Technologies and dependencies
+- ARCHITECTURE.md ([N] lines) - System design and patterns
+- STRUCTURE.md ([N] lines) - Directory layout and organization
+- CONVENTIONS.md ([N] lines) - Code style and patterns
+- TESTING.md ([N] lines) - Test structure and practices
+- INTEGRATIONS.md ([N] lines) - External services and APIs
+- CONCERNS.md ([N] lines) - Technical debt and issues
+
+
+---
+
+## ▶ Next Up
+
+**Initialize project** — use codebase context for planning
+
+`/rihal:new-project`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- Re-run mapping: `/rihal:map-codebase`
+- Review specific file: `cat .planning/codebase/STACK.md`
+- Edit any document before proceeding
+
+---
+```
+
+End workflow.
+</step>
+
+</process>
+
+<success_criteria>
+- .planning/codebase/ directory created
+- If Task tool available: 4 parallel rihal-codebase-mapper agents spawned with run_in_background=true
+- If Task tool NOT available: 4 sequential mapping passes performed inline (never using browser_subagent)
+- All 7 codebase documents exist
+- No empty documents (each should have >20 lines)
+- Clear completion summary with line counts
+- User offered clear next steps in Rihal style
+</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
+