@hanzlaa/rcode 3.6.16 → 4.0.0

package/rihal/workflows/discuss-phase-discuss-areas.md

@@ -1,271 +0,0 @@
-<purpose>
-Sub-step of discuss-phase.md — discuss_areas step. Walks through each selected grey area with the user, collects decisions, and records them for CONTEXT.md.
-</purpose>
-
-<step name="discuss_areas">
-Discuss each selected area with the user. Flow depends on advisor mode.
-
-**If ADVISOR_MODE is true:**
-
-Table-first discussion flow — present research-backed comparison tables, then capture user picks.
-
-**For each selected area:**
-
-1. **Present the synthesized comparison table + rationale paragraph** (from advisor_research step)
-
-2. **Use AskUserQuestion:**
-   - header: "{area_name}"
-   - question: "Which approach for {area_name}?"
-   - options: Extract from the table's Option column (AskUserQuestion adds "Other" automatically)
-
-3. **Record the user's selection:**
-   - If user picks from table options → record as locked decision for that area
-   - If user picks "Other" → receive their input, reflect it back for confirmation, record
-
-   **Thinking partner (conditional):**
-   If `features.thinking_partner` is enabled in config, check the user's answer for tradeoff signals
-   (see `references/thinking-partner.md` for signal list). If tradeoff detected:
-
-   ```
-   I notice competing priorities here — {option_A} optimizes for {goal_A} while {option_B} optimizes for {goal_B}.
-
-   Want me to think through the tradeoffs before we lock this in?
-   [Yes, analyze] / [No, decision made]
-   ```
-
-   If yes: provide 3-5 bullet analysis (what each optimizes/sacrifices, alignment with PROJECT.md goals, recommendation). Then return to normal flow.
-   If no or thinking_partner disabled: continue to next area.
-
-4. **After recording pick, Claude decides whether follow-up questions are needed:**
-   - If the pick has ambiguity that would affect downstream planning → ask 1-2 targeted follow-up questions using AskUserQuestion
-   - If the pick is clear and self-contained → move to next area
-   - Do NOT ask the standard 4 questions — the table already provided the context
-
-5. **After all areas processed:**
-   - header: "Done"
-   - question: "That covers [list areas]. Ready to create context?"
-   - options: "Create context" / "Revisit an area"
-
-**Scope creep handling (advisor mode):**
-If user mentions something outside the phase domain:
-```
-"[Feature] sounds like a new capability — that belongs in its own phase.
-I'll note it as a deferred idea.
-
-Back to [current area]: [return to current question]"
-```
-
-Track deferred ideas internally.
-
----
-
-**If ADVISOR_MODE is false:**
-
-For each selected area, conduct a focused discussion loop.
-
-**Research-before-questions mode:** Check if `workflow.research_before_questions` is enabled in config (from init context or `.planning/config.json`). When enabled, before presenting questions for each area:
-1. Do a brief web search for best practices related to the area topic
-2. Summarize the top findings in 2-3 bullet points
-3. Present the research alongside the question so the user can make a more informed decision
-
-Example with research enabled:
-```
-Let's talk about [Authentication Strategy].
-
-📊 Best practices research:
-• OAuth 2.0 + PKCE is the current standard for SPAs (replaces implicit flow)
-• Session tokens with httpOnly cookies preferred over localStorage for XSS protection
-• Consider passkey/WebAuthn support — adoption is accelerating in 2025-2026
-
-With that context: How should users authenticate?
-```
-
-When disabled (default), skip the research and present questions directly as before.
-
-**Text mode support:** Parse optional `--text` from `$ARGUMENTS`.
-- Accept `--text` flag OR read `workflow.text_mode` from config (from init context)
-- When active, replace ALL `AskUserQuestion` calls with plain-text numbered lists
-- User types a number to select, or types free text for "Other"
-- This is required for Claude Code remote sessions (`/rc` mode) where TUI menus
-  don't work through the Claude App
-
-**Batch mode support:** Parse optional `--batch` from `$ARGUMENTS`.
-- Accept `--batch`, `--batch=N`, or `--batch N`
-
-**Analyze mode support:** Parse optional `--analyze` from `$ARGUMENTS`.
-When `--analyze` is active, before presenting each question (or question group in batch mode), provide a brief **trade-off analysis** for the decision:
-- 2-3 options with pros/cons based on codebase context and common patterns
-- A recommended approach with reasoning
-- Known pitfalls or constraints from prior phases
-
-Example with `--analyze`:
-```
-**Trade-off analysis: Authentication strategy**
-
-| Approach | Pros | Cons |
-|----------|------|------|
-| Session cookies | Simple, httpOnly prevents XSS | Requires CSRF protection, sticky sessions |
-| JWT (stateless) | Scalable, no server state | Token size, revocation complexity |
-| OAuth 2.0 + PKCE | Industry standard for SPAs | More setup, redirect flow UX |
-
-💡 Recommended: OAuth 2.0 + PKCE — your app has social login in requirements (REQ-04) and this aligns with the existing NextAuth setup in `src/lib/auth.ts`.
-
-How should users authenticate?
-```
-
-This gives the user context to make informed decisions without extra prompting. When `--analyze` is absent, present questions directly as before.
-- Accept `--batch`, `--batch=N`, or `--batch N`
-- Default to 4 questions per batch when no number is provided
-- Clamp explicit sizes to 2-5 so a batch stays answerable
-- If `--batch` is absent, keep the existing one-question-at-a-time flow
-
-**Philosophy:** stay adaptive, but let the user choose the pacing.
-- Default mode: 4 single-question turns, then check whether to continue
-- `--batch` mode: 1 grouped turn with 2-5 numbered questions, then check whether to continue
-
-Each answer (or answer set, in batch mode) should reveal the next question or next batch.
-
-**Auto mode (`--auto`):** For each area, Claude selects the recommended option (first option, or the one explicitly marked "recommended") for every question without using AskUserQuestion. Log each auto-selected choice:
-```
-[auto] [Area] — Q: "[question text]" → Selected: "[chosen option]" (recommended default)
-```
-After all areas are auto-resolved, skip the "Explore more gray areas" prompt and proceed directly to write_context.
-
-**CRITICAL — Auto-mode pass cap:**
-In `--auto` mode, the discuss step MUST complete in a **single pass**. After writing CONTEXT.md once, you are DONE — proceed immediately to write_context and then auto_advance. Do NOT re-read your own CONTEXT.md to find "gaps", "undefined types", or "missing decisions" and run additional passes. This creates a self-feeding loop where each pass generates references that the next pass treats as gaps, consuming unbounded time and resources.
-
-Check the pass cap from config:
-```bash
-MAX_PASSES=$(node ".rihal/bin/rihal-tools.cjs" config-get workflow.max_discuss_passes 2>/dev/null || echo "3")
-```
-
-If you have already written and committed CONTEXT.md, the discuss step is complete. Move on.
-
-**Interactive mode (no `--auto`):**
-
-**For each area:**
-
-1. **Announce the area:**
-   ```
-   Let's talk about [Area].
-   ```
-
-2. **Ask questions using the selected pacing:**
-
-   **Default (no `--batch`): Ask 4 questions using AskUserQuestion**
-   - header: "[Area]" (max 12 chars — abbreviate if needed)
-   - question: Specific decision for this area
-   - options: 2-3 concrete choices (AskUserQuestion adds "Other" automatically), with the recommended choice highlighted and brief explanation why
-   - **Annotate options with code context** when relevant:
-     ```
-     "How should posts be displayed?"
-     - Cards (reuses existing Card component — consistent with Messages)
-     - List (simpler, would be a new pattern)
-     - Timeline (needs new Timeline component — none exists yet)
-     ```
-   - Include "You decide" as an option when reasonable — captures Claude discretion
-   - **Context7 for library choices:** When a gray area involves library selection (e.g., "magic links" → query next-auth docs) or API approach decisions, use `mcp__context7__*` tools to fetch current documentation and inform the options. Don't use Context7 for every question — only when library-specific knowledge improves the options.
-
-   **Batch mode (`--batch`): Ask 2-5 numbered questions in one plain-text turn**
-   - Group closely related questions for the current area into a single message
-   - Keep each question concrete and answerable in one reply
-   - When options are helpful, include short inline choices per question rather than a separate AskUserQuestion for every item
-   - After the user replies, reflect back the captured decisions, note any unanswered items, and ask only the minimum follow-up needed before moving on
-   - Preserve adaptiveness between batches: use the full set of answers to decide the next batch or whether the area is sufficiently clear
-
-3. **After the current set of questions, check:**
-   - header: "[Area]" (max 12 chars)
-   - question: "More questions about [area], or move to next? (Remaining: [list other unvisited areas])"
-   - options: "More questions" / "Next area"
-
-   When building the question text, list the remaining unvisited areas so the user knows what's ahead. For example: "More questions about Layout, or move to next? (Remaining: Loading behavior, Content ordering)"
-
-   If "More questions" → ask another 4 single questions, or another 2-5 question batch when `--batch` is active, then check again
-   If "Next area" → proceed to next selected area
-   If "Other" (free text) → interpret intent: continuation phrases ("chat more", "keep going", "yes", "more") map to "More questions"; advancement phrases ("done", "move on", "next", "skip") map to "Next area". If ambiguous, ask: "Continue with more questions about [area], or move to the next area?"
-
-4. **After all initially-selected areas complete:**
-   - Summarize what was captured from the discussion so far
-   - Increment internal PASS_COUNT (starts at 1 for the initial area set)
-   - If PASS_COUNT >= MAX_PASSES: display "Max discussion passes ({MAX_PASSES}) reached — proceeding to write context." and go directly to write_context WITHOUT prompting.
-   - Otherwise, AskUserQuestion:
-     - header: "Done"
-     - question: "We've discussed [list areas]. Which gray areas remain unclear? ({MAX_PASSES - PASS_COUNT} pass(es) remaining)"
-     - options: "Explore more gray areas" / "I'm ready for context"
-   - If "Explore more gray areas":
-     - Identify 2-4 additional gray areas based on what was learned
-     - Return to present_gray_areas logic with these new areas
-     - Increment PASS_COUNT; if PASS_COUNT >= MAX_PASSES, skip the end-of-set prompt and go directly to write_context after this round
-     - Loop: discuss new areas, then prompt again (if passes remain)
-   - If "I'm ready for context": Proceed to write_context
-
-**Canonical ref accumulation during discussion:**
-When the user references a doc, spec, or ADR during any answer — e.g., "read adr-014", "check the MCP spec", "per browse-spec.md" — immediately:
-1. Read the referenced doc (or confirm it exists)
-2. Add it to the canonical refs accumulator with full relative path
-3. Use what you learned from the doc to inform subsequent questions
-
-These user-referenced docs are often MORE important than ROADMAP.md refs because they represent docs the user specifically wants downstream agents to follow. Never drop them.
-
-**Question design:**
-- Options should be concrete, not abstract ("Cards" not "Option A")
-- Each answer should inform the next question or next batch
-- If user picks "Other" to provide freeform input (e.g., "let me describe it", "something else", or an open-ended reply), ask your follow-up as plain text — NOT another AskUserQuestion. Wait for them to type at the normal prompt, then reflect their input back and confirm before resuming AskUserQuestion or the next numbered batch.
-
-**Scope creep handling:**
-If user mentions something outside the phase domain:
-```
-"[Feature] sounds like a new capability — that belongs in its own phase.
-I'll note it as a deferred idea.
-
-Back to [current area]: [return to current question]"
-```
-
-Track deferred ideas internally.
-
-**Incremental checkpoint — save after each area completes:**
-
-After each area is resolved (user says "Next area" or area auto-resolves in `--auto` mode), immediately write a checkpoint file with all decisions captured so far. This prevents data loss if the session is interrupted mid-discussion.
-
-**Checkpoint file:** `${phase_dir}/${padded_phase}-DISCUSS-CHECKPOINT.json`
-
-Write after each area:
-```json
-{
-  "phase": "{PHASE_NUMBER}",
-  "phase_name": "{phase_name}",
-  "timestamp": "{ISO timestamp}",
-  "areas_completed": ["Area 1", "Area 2"],
-  "areas_remaining": ["Area 3", "Area 4"],
-  "decisions": {
-    "Area 1": [
-      {"question": "...", "answer": "...", "options_presented": ["..."]},
-      {"question": "...", "answer": "...", "options_presented": ["..."]}
-    ],
-    "Area 2": [
-      {"question": "...", "answer": "...", "options_presented": ["..."]}
-    ]
-  },
-  "deferred_ideas": ["..."],
-  "canonical_refs": ["..."]
-}
-```
-
-This is a structured checkpoint, not the final CONTEXT.md — the `write_context` step still produces the canonical output. But if the session dies, the next `/rihal-discuss-phase` invocation can detect this checkpoint and offer to resume from it instead of starting from scratch.
-
-**On session resume:** In the `check_existing` step, also check for `*-DISCUSS-CHECKPOINT.json`. If found and no CONTEXT.md exists:
-- Display: "Found interrupted discussion checkpoint ({N} areas completed). Resume from checkpoint?"
-- Options: "Resume" / "Start fresh"
-- On "Resume": Load the checkpoint, skip completed areas, continue from where it left off
-- On "Start fresh": Delete the checkpoint, proceed as normal
-
-**After write_context completes successfully:** Delete the checkpoint file — the canonical CONTEXT.md now has all decisions.
-
-**Track discussion log data internally:**
-For each question asked, accumulate:
-- Area name
-- All options presented (label + description)
-- Which option the user selected (or their free-text response)
-- Any follow-up notes or clarifications the user provided
-This data is used to generate DISCUSSION-LOG.md in the `write_context` step.
-</step>

package/rihal/workflows/discuss-phase-power.md

@@ -1,325 +0,0 @@
-# Workflow: rihal-discuss-phase-power
-
-<purpose>
-Power user mode for discuss-phase. Generates ALL questions upfront into a JSON state file and an HTML companion UI, then waits for the user to answer at their own pace. When the user signals readiness, processes all answers in one pass and generates CONTEXT.md.
-
-**When to use:** Large phases with many gray areas, or when users prefer to answer questions offline / asynchronously rather than interactively in the chat session.
-</purpose>
-
-
-## Step 0 — Usage check
-
-If `$ARGUMENTS` is empty or contains only `--help` or `-h`:
-
-```
-/rihal-discuss-phase --power <argument-here>
-```
-
-**Examples:**
-```
-/rihal-discuss-phase --power example 1
-/rihal-discuss-phase --power example 2
-```
-
-STOP — do not proceed.
-
-<trigger>
-This workflow executes when `--power` flag is present in ARGUMENTS to `/rihal-discuss-phase`.
-
-The caller (discuss-phase.md) has already:
-- Validated the phase exists
-- Provided init context: `phase_dir`, `padded_phase`, `phase_number`, `phase_name`, `phase_slug`
-
-Begin at **Step 1** immediately.
-</trigger>
-
-<step name="analyze">
-Run the same gray area identification as standard discuss-phase mode.
-
-1. Load prior context (PROJECT.md, REQUIREMENTS.md, STATE.md, prior CONTEXT.md files)
-2. Scout codebase for reusable assets and patterns relevant to this phase
-3. Read the phase goal from ROADMAP.md
-4. Identify ALL gray areas — specific implementation decisions the user should weigh in on
-5. For each gray area, generate 2–4 concrete options with tradeoff descriptions
-
-Group questions by topic into sections (e.g., "Visual Style", "Data Model", "Interactions", "Error Handling"). Each section should have 2–6 questions.
-
-Do NOT ask the user anything at this stage. Capture everything internally, then proceed to generate.
-</step>
-
-<step name="generate_json">
-Write all questions to:
-
-```
-{phase_dir}/{padded_phase}-QUESTIONS.json
-```
-
-**JSON structure:**
-
-```json
-{
-  "phase": "{padded_phase}-{phase_slug}",
-  "generated_at": "ISO-8601 timestamp",
-  "stats": {
-    "total": 0,
-    "answered": 0,
-    "chat_more": 0,
-    "remaining": 0
-  },
-  "sections": [
-    {
-      "id": "section-slug",
-      "title": "Section Title",
-      "questions": [
-        {
-          "id": "Q-01",
-          "title": "Short question title",
-          "context": "Codebase info, prior decisions, or constraints relevant to this question",
-          "options": [
-            {
-              "id": "a",
-              "label": "Option label",
-              "description": "Tradeoff or elaboration for this option"
-            },
-            {
-              "id": "b",
-              "label": "Another option",
-              "description": "Tradeoff or elaboration"
-            },
-            {
-              "id": "c",
-              "label": "Custom",
-              "description": ""
-            }
-          ],
-          "answer": null,
-          "chat_more": "",
-          "status": "unanswered"
-        }
-      ]
-    }
-  ]
-}
-```
-
-**Field rules:**
-- `stats.total`: count of all questions across all sections
-- `stats.answered`: count where `answer` is not null and not empty string
-- `stats.chat_more`: count where `chat_more` has content
-- `stats.remaining`: `total - answered`
-- `question.id`: sequential across all sections — Q-01, Q-02, Q-03, ...
-- `question.context`: concrete codebase or prior-decision annotation (not generic)
-- `question.answer`: null until user sets it; once answered, the selected option id or free-text
-- `question.status`: "unanswered" | "answered" | "chat-more" (has chat_more but no answer yet)
-</step>
-
-<step name="generate_html">
-Write a self-contained HTML companion file to:
-
-```
-{phase_dir}/{padded_phase}-QUESTIONS.html
-```
-
-The file must be a single self-contained HTML file with inline CSS and JavaScript. No external dependencies.
-
-**Layout:**
-
-```
-┌─────────────────────────────────────────────────────────┐
-│  Phase {N}: {phase_name} — Discussion Questions      │
-│  ┌──────────────────────────────────────────────────┐   │
-│  │  12 total  |  3 answered  |  9 remaining     │   │
-│  └──────────────────────────────────────────────────┘   │
-├─────────────────────────────────────────────────────────┤
-│  ▼ Visual Style (3 questions)                        │
-│   ┌──────────┐ ┌──────────┐ ┌──────────┐            │
-│   │ Q-01     │ │ Q-02     │ │ Q-03     │            │
-│   │ Layout   │ │ Density  │ │ Colors   │            │
-│   │ ...      │ │ ...      │ │ ...      │            │
-│   └──────────┘ └──────────┘ └──────────┘            │
-│  ▼ Data Model (2 questions)                          │
-│   ...                                                │
-└─────────────────────────────────────────────────────────┘
-```
-
-**Stats bar:**
-- Total questions, answered count, remaining count
-- A simple CSS progress bar (green fill = answered / total)
-
-**Section headers:**
-- Collapsible via click — show/hide questions in the section
-- Show answered count for the section (e.g., "2/4 answered")
-
-**Question cards (3-column grid):**
-Each card contains:
-- Question ID badge (e.g., "Q-01") and title
-- Context annotation (gray italic text)
-- Option list: radio buttons with bold label + description text
-- Chat more textarea (orange border when content present)
-- Card highlighted green when answered
-
-**JavaScript behavior:**
-- On radio button select: mark question as answered in page state; update stats bar
-- On textarea input: update chat_more content in page state; show orange border if content present
-- "Save answers" button at top and bottom: serializes page state back to the JSON file path
-
-**Save mechanism:**
-The Save button writes the updated JSON back using the File System Access API if available, otherwise generates a downloadable JSON file the user can save over the original. Include clear instructions in the UI:
-
-```
-After answering, click "Save answers" — or download the JSON and replace the original file.
-Then return to Claude and say "refresh" to process your answers.
-```
-
-**Answered question styling:**
-- Card border: `2px solid #22c55e` (green)
-- Card background: `#f0fdf4` (light green tint)
-
-**Unanswered question styling:**
-- Card border: `1px solid #e2e8f0` (gray)
-- Card background: `white`
-
-**Chat more textarea:**
-- Placeholder: "Add context, nuance, or clarification for this question..."
-- Normal border: `1px solid #e2e8f0`
-- Active (has content) border: `2px solid #f97316` (orange)
-</step>
-
-<step name="notify_user">
-After writing both files, print this message to the user:
-
-```
-Questions ready for Phase {N}: {phase_name}
-
-  HTML (open in browser/IDE):   {phase_dir}/{padded_phase}-QUESTIONS.html
-  JSON (state file):            {phase_dir}/{padded_phase}-QUESTIONS.json
-
-  {total} questions across {section_count} topics.
-
-Open the HTML file, answer the questions at your own pace, then save.
-
-When ready, tell me:
-  "refresh"   — process your answers and update the file
-  "finalize"  — generate CONTEXT.md from all answered questions
-  "explain Q-05"   — elaborate on a specific question
-  "exit power mode" — return to standard one-by-one discussion (answers carry over)
-```
-</step>
-
-<step name="wait_loop">
-Enter wait mode. Claude listens for user commands and handles each:
-
----
-
-**"refresh"** (or "process answers", "update", "re-read"):
-
-1. Read `{phase_dir}/{padded_phase}-QUESTIONS.json`
-2. Recalculate stats: count answered, chat_more, remaining
-3. Write updated stats back to the JSON
-4. Re-generate the HTML file with the updated state (answered cards highlighted green, progress bar updated)
-5. Report to user:
-
-```
-Refreshed. Updated state:
-  Answered:  {answered} / {total}
-  Remaining: {remaining}
-  Chat-more: {chat_more}
-
-  {phase_dir}/{padded_phase}-QUESTIONS.html updated.
-
-Answer more questions, then say "refresh" again, or say "finalize" when done.
-```
-
----
-
-**"finalize"** (or "done", "generate context", "write context"):
-
-Proceed to the **finalize** step.
-
----
-
-**"explain Q-{N}"** (or "more info on Q-{N}", "elaborate Q-{N}"):
-
-1. Find the question by ID in the JSON
-2. Provide a detailed explanation: why this decision matters, how it affects the downstream plan, what additional context from the codebase is relevant
-3. Return to wait mode
-
----
-
-**"exit power mode"** (or "switch to interactive"):
-
-1. Read all currently answered questions from JSON
-2. Load answers into the internal accumulator as if they were answered interactively
-3. Continue with standard `discuss_areas` step from discuss-phase.md for any unanswered questions
-4. Generate CONTEXT.md as normal
-
----
-
-**Any other message:**
-Respond helpfully, then remind the user of available commands:
-```
-(Power mode active — say "refresh", "finalize", "explain Q-N", or "exit power mode")
-```
-</step>
-
-<step name="finalize">
-Process all answered questions from the JSON file and generate CONTEXT.md.
-
-1. Read `{phase_dir}/{padded_phase}-QUESTIONS.json`
-2. Filter to questions where `answer` is not null/empty
-3. Group decisions by section
-4. For each answered question, format as a decision entry:
-   - Decision: the selected option label (or custom text if free-form answer)
-   - Rationale: the option description, plus `chat_more` content if present
-   - Status: "Decided" if fully answered, "Needs clarification" if only chat_more with no option selected
-
-5. Write CONTEXT.md using the standard context template format:
-   - `<decisions>` section with all answered questions grouped by section
-   - `<deferred_ideas>` section for unanswered questions (carry forward for future discussion)
-   - `<specifics>` section for any chat_more content that adds nuance
-   - `<code_context>` section with reusable assets found during analysis
-   - `<canonical_refs>` section (MANDATORY — paths to relevant specs/docs)
-
-6. If fewer than 50% of questions were answered, warn the user:
-```
-Warning: Only {answered}/{total} questions answered ({pct}%).
-CONTEXT.md generated with available decisions. Unanswered questions listed as deferred.
-Consider running /rihal-discuss-phase {N} again to refine before planning.
-```
-
-7. Print completion message:
-```
-CONTEXT.md written: {phase_dir}/{padded_phase}-CONTEXT.md
-
-  Decisions captured: {answered}
-  Deferred:          {remaining}
-
-Next step: /rihal-plan {N}
-```
-</step>
-
-<success_criteria>
-- Questions generated into well-structured JSON covering all identified gray areas
-- HTML companion file is self-contained and usable without a server
-- Stats bar accurately reflects answered/remaining counts after each refresh
-- Answered questions highlighted green in HTML
-- CONTEXT.md generated in the same format as standard discuss-phase output
-- Unanswered questions preserved as deferred items (not silently dropped)
-- `canonical_refs` section always present in CONTEXT.md (MANDATORY)
-- User knows how to refresh, finalize, explain, or exit power mode
-</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
-