@hanzlaa/rcode 3.4.4 → 3.4.5

package/rihal/workflows/new-project.md

@@ -807,570 +807,16 @@ Use AskUserQuestion:
 
 Use models resolved in Step 1: `RESEARCHER_MODEL`, `SYNTHESIZER_MODEL`, `ROADMAPPER_MODEL`.
 
-## 6. Research Decision
 
-**If auto mode:** Default to "Research first" without asking.
+@rihal/workflows/new-project-research-decision.md
 
-Use AskUserQuestion:
-
-- header: "Research"
-- question: "Research the domain ecosystem before defining requirements?"
-- options:
-  - "Research first (Recommended)" — Discover standard stacks, expected features, architecture patterns
-  - "Skip research" — I know this domain well, go straight to requirements
-
-**If "Research first":**
-
-Display stage banner:
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- RIHAL ► RESEARCHING
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Researching [domain] ecosystem...
-```
-
-Create research directory:
-
-```bash
-mkdir -p .planning/research
-```
-
-**Determine milestone context:**
-
-- If no "Validated" requirements in PROJECT.md → Greenfield (building from scratch)
-- If "Validated" requirements exist → Subsequent milestone (adding to existing app)
-
-Display spawning indicator:
-
-```
-◆ Spawning 4 researchers in parallel...
-  → Stack research
-  → Features research
-  → Architecture research
-  → Pitfalls research
-```
-
-Spawn 4 parallel rihal-project-researcher agents:
-
-```
-Task(prompt="<research_type>
-Project Research — Stack dimension for [domain].
-</research_type>
-
-<milestone_context>
-[greenfield OR subsequent]
-
-Greenfield: Research the standard stack for building [domain] from scratch.
-Subsequent: Research what's needed to add [target features] to an existing [domain] app.
-</milestone_context>
-
-<question>
-What's the standard 2026 stack for [domain]?
-</question>
-
-<files_to_read>
-- .planning/PROJECT.md (Project context and goals)
-</files_to_read>
-
-${AGENT_RESEARCHER}
-
-<downstream_consumer>
-Your STACK.md feeds into roadmap creation. Be prescriptive:
-- Specific libraries with versions
-- Clear rationale for each choice
-- What NOT to use and why
-</downstream_consumer>
-
-<quality_gate>
-- [ ] Versions are current (verify with Context7/official docs, not training data)
-- [ ] Rationale explains WHY, not just WHAT
-- [ ] Confidence levels assigned to each recommendation
-</quality_gate>
-
-<output>
-Write to: .planning/research/STACK.md
-</output>
-", subagent_type="rihal-project-researcher", model="${RESEARCHER_MODEL}", description="Stack research")
-
-Task(prompt="<research_type>
-Project Research — Features dimension for [domain].
-</research_type>
-
-<milestone_context>
-[greenfield OR subsequent]
-
-Greenfield: What features do [domain] products have? What's table stakes vs differentiating?
-Subsequent: How do [target features] typically work? What's expected behavior?
-</milestone_context>
-
-<files_to_read>
-- .planning/PROJECT.md
-</files_to_read>
-
-${AGENT_RESEARCHER}
-
-<downstream_consumer>
-Your FEATURES.md feeds into requirements definition. Categorize clearly:
-- Table stakes (must have or users leave)
-- Differentiators (competitive advantage)
-- Anti-features (things to deliberately NOT build)
-</downstream_consumer>
-
-<quality_gate>
-- [ ] Categories are clear (table stakes vs differentiators vs anti-features)
-- [ ] Complexity noted for each feature
-- [ ] Dependencies between features identified
-</quality_gate>
-
-<output>
-Write to: .planning/research/FEATURES.md
-</output>
-", subagent_type="rihal-project-researcher", model="${RESEARCHER_MODEL}", description="Features research")
-
-Task(prompt="<research_type>
-Project Research — Architecture dimension for [domain].
-</research_type>
-
-<milestone_context>
-[greenfield OR subsequent]
-
-Greenfield: How are [domain] systems typically structured? What are major components?
-Subsequent: How do [target features] integrate with existing [domain] architecture?
-</milestone_context>
-
-<files_to_read>
-- .planning/PROJECT.md
-</files_to_read>
-
-${AGENT_RESEARCHER}
-
-<downstream_consumer>
-Your ARCHITECTURE.md informs phase structure in roadmap. Include:
-- Component boundaries (what talks to what)
-- Data flow (how information moves)
-- Suggested build order (dependencies between components)
-</downstream_consumer>
-
-<quality_gate>
-- [ ] Components clearly defined with boundaries
-- [ ] Data flow direction explicit
-- [ ] Build order implications noted
-</quality_gate>
-
-<output>
-Write to: .planning/research/ARCHITECTURE.md
-</output>
-", subagent_type="rihal-project-researcher", model="${RESEARCHER_MODEL}", description="Architecture research")
-
-Task(prompt="<research_type>
-Project Research — Pitfalls dimension for [domain].
-</research_type>
-
-<milestone_context>
-[greenfield OR subsequent]
-
-Greenfield: What do [domain] projects commonly get wrong? Critical mistakes?
-Subsequent: What are common mistakes when adding [target features] to [domain]?
-</milestone_context>
-
-<files_to_read>
-- .planning/PROJECT.md
-</files_to_read>
-
-${AGENT_RESEARCHER}
-
-<downstream_consumer>
-Your PITFALLS.md prevents mistakes in roadmap/planning. For each pitfall:
-- Warning signs (how to detect early)
-- Prevention strategy (how to avoid)
-- Which phase should address it
-</downstream_consumer>
-
-<quality_gate>
-- [ ] Pitfalls are specific to this domain (not generic advice)
-- [ ] Prevention strategies are actionable
-- [ ] Phase mapping included where relevant
-</quality_gate>
-
-<output>
-Write to: .planning/research/PITFALLS.md
-</output>
-", subagent_type="rihal-project-researcher", model="${RESEARCHER_MODEL}", description="Pitfalls research")
-```
-
-After all 4 agents complete, spawn synthesizer to create SUMMARY.md:
-
-```
-Task(prompt="
-<task>
-Synthesize research outputs into SUMMARY.md.
-</task>
-
-<files_to_read>
-- .planning/research/STACK.md
-- .planning/research/FEATURES.md
-- .planning/research/ARCHITECTURE.md
-- .planning/research/PITFALLS.md
-</files_to_read>
-
-${AGENT_SYNTHESIZER}
-
-<output>
-Write to: .planning/research/SUMMARY.md
-Synthesize into: recommended stack, table stakes vs differentiators, architecture outline, top pitfalls to avoid.
-</output>
-", subagent_type="rihal-research-synthesizer", model="${SYNTHESIZER_MODEL}", description="Synthesize research")
-```
-
-**Commit research (guarded):**
-
-```bash
-git add .planning/research/ 2>/dev/null \
-  && git commit -m "docs: add project research" 2>/dev/null \
-  || echo "ℹ .planning/ gitignored — research written, not committed"
-```
-
-Display research complete banner and key findings:
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- RIHAL ► RESEARCH COMPLETE ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-## Key Findings
-
-**Stack:** [from SUMMARY.md]
-**Table Stakes:** [from SUMMARY.md]
-**Watch Out For:** [from SUMMARY.md]
-
-Files: `.planning/research/`
-```
-
-**If "Skip research":** Continue to Step 7.
-
-## 7. Define Requirements
-
-Display stage banner:
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- RIHAL ► DEFINING REQUIREMENTS
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-**Load context:**
-
-Read PROJECT.md and extract:
-
-- Core value (the ONE thing that must work)
-- Stated constraints (budget, timeline, tech limitations)
-- Any explicit scope boundaries
-
-**If research exists:** Read research/FEATURES.md and extract feature categories.
-
-**If auto mode:**
-
-- Auto-include all table stakes features
-- Include features explicitly mentioned in provided document
-- Auto-defer differentiators not mentioned in document
-- Skip per-category AskUserQuestion loops
-- Skip "Any additions?" question
-- Skip requirements approval gate
-- Generate REQUIREMENTS.md and commit directly
 
-**Present features by category (interactive mode only):**
 
-```
-Here are the features for [domain]:
-
-## Authentication
-**Table stakes:**
-- Sign up with email/password
-- Email verification
-- Password reset
-- Session management
-
-**Differentiators:**
-- Magic link login
-- OAuth (Google, GitHub)
-- 2FA
-
-**Research notes:** [any relevant notes]
-
----
-
-## [Next Category]
-...
-```
-
-**If no research:** Gather requirements through conversation.
-
-Ask: "What are the main things users need to be able to do?"
-
-For each capability mentioned:
-
-- Ask clarifying questions to make it specific
-- Probe for related capabilities
-- Group into categories
-
-**Scope each category:**
-
-For each category, use AskUserQuestion:
-
-- header: "[Category]" (max 12 chars)
-- question: "Which [category] features are in v1?"
-- multiSelect: true
-- options:
-  - "[Feature 1]" — [brief description]
-  - "[Feature 2]" — [brief description]
-  - "[Feature 3]" — [brief description]
-  - "None for v1" — Defer entire category
-
-Track responses:
-
-- Selected features → v1 requirements
-- Unselected table stakes → v2
-- Unselected differentiators → out of scope
-
-**Identify gaps:**
-
-Use AskUserQuestion:
-
-- header: "Additions"
-- question: "Any requirements research missed?"
-- options:
-  - "No, research covered it" — Proceed
-  - "Yes, let me add some" — Capture additions
-
-**Validate core value:**
-
-Cross-check requirements against Core Value from PROJECT.md. If gaps detected, surface them.
-
-**Generate REQUIREMENTS.md:**
-
-Create `.planning/REQUIREMENTS.md` with:
-
-- v1 Requirements grouped by category (checkboxes, REQ-IDs)
-- v2 Requirements (deferred)
-- Out of Scope (explicit exclusions with reasoning)
-- Traceability section (empty, filled by roadmap)
-
-**REQ-ID format:** `[CATEGORY]-[NUMBER]` (AUTH-01, CONTENT-02)
-
-**Requirement quality criteria:**
-
-Good requirements are:
-
-- **Specific and testable:** "User can reset password via email link"
-- **User-centric:** "User can X"
-- **Atomic:** One capability per requirement
-- **Independent:** Minimal dependencies on other requirements
-
-Reject vague requirements. Push for specificity:
-
-- "Handle authentication" → "User can log in with email/password and stay logged in across sessions"
-- "Support sharing" → "User can share post via link that opens in recipient's browser"
-
-**Present full requirements list (interactive mode only):**
-
-Show every requirement for user confirmation:
-
-```
-## v1 Requirements
-
-### Authentication
-- [ ] **AUTH-01**: User can create account with email/password
-- [ ] **AUTH-02**: User can log in and stay logged in across sessions
-- [ ] **AUTH-03**: User can log out from any page
-
-### Content
-- [ ] **CONT-01**: User can create posts with text
-- [ ] **CONT-02**: User can edit their own posts
-
-[... full list ...]
-
----
-
-Does this capture what you're building? (yes / adjust)
-```
-
-If "adjust": Return to scoping.
-
-**Commit requirements (guarded):**
-
-```bash
-git add .planning/REQUIREMENTS.md 2>/dev/null \
-  && git commit -m "docs: define v1 requirements" 2>/dev/null \
-  || echo "ℹ .planning/ gitignored — requirements written, not committed"
-```
+@rihal/workflows/new-project-define-requirements.md
 
-## 8. Create Roadmap
 
-Display stage banner:
 
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- RIHAL ► CREATING ROADMAP
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-◆ Spawning roadmapper...
-```
-
-Spawn rihal-roadmapper agent:
-
-```
-Task(prompt="
-<planning_context>
-
-<files_to_read>
-- .planning/PROJECT.md (Project context)
-- .planning/REQUIREMENTS.md (v1 Requirements)
-- .planning/research/SUMMARY.md (Research findings - if exists)
-- .planning/config.json (Granularity and mode settings)
-</files_to_read>
-
-${AGENT_ROADMAPPER}
-
-</planning_context>
-
-<instructions>
-Create roadmap:
-1. Derive phases from requirements (don't impose structure)
-2. Map every v1 requirement to exactly one phase
-3. Derive 2-5 success criteria per phase (observable user behaviors)
-4. Validate 100% coverage
-5. Write files immediately (ROADMAP.md, STATE.md, update REQUIREMENTS.md traceability)
-6. Return ROADMAP CREATED with summary
-
-Write files first, then return. This ensures artifacts persist even if context is lost.
-</instructions>
-", subagent_type="rihal-roadmapper", model="${ROADMAPPER_MODEL}", description="Create roadmap")
-```
-
-**Handle roadmapper return:**
-
-**If `## ROADMAP BLOCKED`:**
-
-- Present blocker information
-- Work with user to resolve
-- Re-spawn when resolved
-
-**If `## ROADMAP CREATED`:**
-
-Read the created ROADMAP.md and present it nicely inline:
-
-```
----
-
-## Proposed Roadmap
-
-**[N] phases** | **[X] requirements mapped** | All v1 requirements covered ✓
-
-| # | Phase | Goal | Requirements | Success Criteria |
-|---|-------|------|--------------|------------------|
-| 1 | [Name] | [Goal] | [REQ-IDs] | [count] |
-| 2 | [Name] | [Goal] | [REQ-IDs] | [count] |
-| 3 | [Name] | [Goal] | [REQ-IDs] | [count] |
-
-### Phase Details
-
-**Phase 1: [Name]**
-Goal: [goal]
-Requirements: [REQ-IDs]
-Success criteria:
-1. [criterion]
-2. [criterion]
-3. [criterion]
-
-[... continue for all phases ...]
-
----
-```
-
-**If auto mode:** Skip approval gate — auto-approve and commit directly.
-
-**CRITICAL: Ask for approval before committing (interactive mode only):**
-
-Use AskUserQuestion:
-
-- header: "Roadmap"
-- question: "Does this roadmap structure work for you?"
-- options:
-  - "Approve" — Commit and continue
-  - "Adjust phases" — Tell me what to change
-  - "Review full file" — Show raw ROADMAP.md
-
-**If "Approve":** Continue to commit.
-
-**If "Adjust phases":**
-
-- Get user's adjustment notes
-- Re-spawn roadmapper with revision context:
-
-  ```
-  Task(prompt="
-  <revision>
-  User feedback on roadmap:
-  [user's notes]
-
-  <files_to_read>
-  - .planning/ROADMAP.md (Current roadmap to revise)
-  </files_to_read>
-
-  ${AGENT_ROADMAPPER}
-
-  Update the roadmap based on feedback. Edit files in place.
-  Return ROADMAP REVISED with changes made.
-  </revision>
-  ", subagent_type="rihal-roadmapper", model="${ROADMAPPER_MODEL}", description="Revise roadmap")
-  ```
-
-- Present revised roadmap
-- Loop until user approves
-
-**If "Review full file":** Display raw `cat .planning/ROADMAP.md`, then re-ask.
-
-**Generate or refresh project instruction file before final commit:**
-
-The rihal-tools CLI does not expose a `generate-claude-md` subcommand. Instead, if `$INSTRUCTION_FILE` does not already exist, write a minimal instruction file pointing at the rihal workflow docs:
-
-```markdown
-# {INSTRUCTION_FILE} — project instructions
-
-This project uses Rihal for planning and execution. See `.planning/PROJECT.md` for context and `.planning/ROADMAP.md` for phases.
-
-Common commands:
-- /rihal-progress — check status and next action
-- /rihal-discuss-phase N — gather context before planning phase N
-- /rihal-plan N — create a SPRINT.md for phase N
-- /rihal-execute N — execute a SPRINT.md
-- /rihal-verify-work — conversational UAT
-- /rihal-complete-milestone — archive milestone and reset
-
-Rules:
-- Never run `git push` without explicit user authorization.
-- No Claude/AI attribution in commits.
-- Prefer editing existing files over creating new ones.
-```
-
-If it already exists, leave it alone (respect user-customized content).
-
-**Commit roadmap (guarded):**
-
-```bash
-git add \
-  .planning/ROADMAP.md \
-  .planning/STATE.md \
-  .planning/REQUIREMENTS.md \
-  "$INSTRUCTION_FILE" 2>/dev/null \
-&& git commit -m "docs: create roadmap ([N] phases)" 2>/dev/null \
-|| echo "ℹ .planning/ gitignored — roadmap written, not committed (instruction file committed separately)"
-
-# Fallback: also try committing just the instruction file if .planning was ignored
-git add "$INSTRUCTION_FILE" 2>/dev/null && git commit -m "docs: add project instruction file" 2>/dev/null || true
-```
+@rihal/workflows/new-project-create-roadmap.md
 
 ## 9. Done
 

package/rihal/workflows/note.md

@@ -100,7 +100,7 @@ EOF
 
 Print:
 ```
-✅ Note saved: {target_dir}/{filename}
+✓ Note saved: {target_dir}/{filename}
 
 ---
 date: 2026-04-12

package/rihal/workflows/phase.md

@@ -0,0 +1,54 @@
+<purpose>
+Unified phase CRUD command. Routes to add (default — append integer phase to current milestone), insert (decimal phase under a parent — useful for urgent work mid-flight), or remove (delete an unstarted future phase + renumber). Replaces the muscle-memory pattern of remembering which of /rihal-add-phase, /rihal-insert-phase, /rihal-remove-phase to invoke.
+</purpose>
+
+## Step 0 — Usage check
+
+If `$ARGUMENTS` is empty AND no flag is set:
+
+```
+/rihal-phase <name>                          # append next integer phase (default)
+/rihal-phase --insert <parent> <name>        # insert decimal under <parent> (e.g. 14.1)
+/rihal-phase --remove <id>                   # remove unstarted future phase + renumber
+```
+
+STOP — do not proceed.
+
+## Step 1 — Parse mode flags
+
+Inspect `$ARGUMENTS`:
+
+- `--insert <parent>` → insert mode (delegates to insert-phase workflow with the parent + name)
+- `--remove <id>` → remove mode (delegates to remove-phase workflow)
+- (none) → add mode (default, delegates to add-phase workflow)
+
+Strip the mode flag and pass remaining args to the underlying workflow.
+
+## Step 2 — Dispatch to underlying workflow
+
+Each mode is implemented by an existing workflow:
+
+- **add (default):** read and execute `@.rihal/workflows/add-phase.md`. Output identical to `/rihal-add-phase`.
+- **insert (`--insert <parent>`):** read and execute `@.rihal/workflows/insert-phase.md`. Output identical to `/rihal-insert-phase`.
+- **remove (`--remove <id>`):** read and execute `@.rihal/workflows/remove-phase.md`. Output identical to `/rihal-remove-phase`.
+
+The underlying workflows are unchanged — `/rihal-phase` is a thin router. Behaviour, output format, and disk side-effects are byte-identical to invoking the underlying command directly.
+
+## Step 3 — Footer
+
+After the underlying workflow's output, append:
+
+```
+(rihal-phase: routed to {add|insert|remove} mode)
+```
+
+## Migration note
+
+The three absorbed commands continue to work as first-class aliases. `/rihal-phase` exists as the unified entry. Future minor versions may consolidate further; until then, both invocation paths are supported.
+
+## Acceptance
+
+- [ ] `/rihal-phase "fix authentication"` produces the same artefacts as `/rihal-add-phase "fix authentication"`
+- [ ] `/rihal-phase --insert 14 "hotfix wave"` produces the same artefacts as `/rihal-insert-phase 14 "hotfix wave"`
+- [ ] `/rihal-phase --remove 99` produces the same artefacts as `/rihal-remove-phase 99`
+- [ ] Unknown flag combinations produce a clear error

package/rihal/workflows/plan-milestone-gaps.md

@@ -170,7 +170,7 @@ node ".rihal/bin/rihal-tools.cjs" commit "docs(roadmap): add gap closure phases
 ---
 
 **Also available:**
-- `/rihal-execute-phase {N}` — if plans already exist
+- `/rihal-execute {N}` — if plans already exist
 - `cat .planning/ROADMAP.md` — see updated roadmap
 
 ---