@hanzlaa/rcode 3.6.15 → 4.0.0

package/rcode/workflows/new-project-create-roadmap.md

@@ -0,0 +1,210 @@
+<purpose>
+Sub-step of new-project.md — Step 8 Create Roadmap. Spawns rcode-roadmapper agent to build ROADMAP.md from requirements and project type. Includes approval gate and commit.
+</purpose>
+
+## 8. Create Roadmap
+
+Display stage banner:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ rcode ► CREATING ROADMAP
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+◆ Spawning roadmapper...
+```
+
+Spawn rcode-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)
+- .rcode/config.yaml (Granularity and mode settings — read via `node rcode-tools.cjs config-get <key>`)
+</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="rcode-roadmapper", model="${ROADMAPPER_MODEL}", description="Create roadmap")
+```
+
+**Handle roadmapper return:**
+
+**Stub guard — verify ROADMAP.md has real content:**
+
+After the agent returns (any return signal), run:
+
+```bash
+ROADMAP_LINES=$(wc -l < .planning/ROADMAP.md 2>/dev/null || echo 0)
+ROADMAP_HAS_PHASE=$(grep -c "^## Phase\|^| [0-9]" .planning/ROADMAP.md 2>/dev/null || echo 0)
+```
+
+If `.planning/ROADMAP.md` does not exist, OR `ROADMAP_LINES < 10`, OR `ROADMAP_HAS_PHASE == 0`:
+
+```
+❌ ROADMAP.md is missing or still a stub (no phase headings detected).
+Re-spawning roadmapper...
+```
+
+Re-spawn rcode-roadmapper with the same prompt. If it fails a second time, output:
+
+```
+❌ roadmapper failed twice — ROADMAP.md was not created.
+Blockers:
+- Check that .planning/REQUIREMENTS.md exists and has content
+- Check that rcode-roadmapper agent is installed: node .rcode/bin/rcode-tools.cjs agent-info rcode-roadmapper
+
+Cannot continue without a valid ROADMAP.md. Fix the blocker and re-run /rcode-new-project.
+```
+
+STOP — do not proceed to approval gate.
+
+**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="rcode-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 rcode-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 rcode workflow docs:
+
+```markdown
+# {INSTRUCTION_FILE} — project instructions
+
+This project uses rcode for planning and execution. See `.planning/PROJECT.md` for context and `.planning/ROADMAP.md` for phases.
+
+Common commands:
+- /rcode-progress — check status and next action
+- /rcode-discuss-phase N — gather context before planning phase N
+- /rcode-plan N — create a SPRINT.md for phase N
+- /rcode-execute N — execute a SPRINT.md
+- /rcode-verify-work — conversational UAT
+- /rcode-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
+
+# Sync all roadmapper-created phases into state.json.
+# rcode-roadmapper writes ROADMAP.md as text — it never calls `phase add` — so
+# state.json is empty after this step unless we sync it. Without this, every
+# /rcode-status shows "N phases not registered" warnings immediately after init.
+node ".rcode/bin/rcode-tools.cjs" state sync --from-disk 2>/dev/null || true
+```
+
+
+## Next Up
+
+- `/rcode-discuss-phase` — discuss the first phase with the full roadmap in hand
+- `/rcode-plan` — plan the first phase of the new project

package/rcode/workflows/new-project-define-requirements.md

@@ -0,0 +1,167 @@
+<purpose>
+Sub-step of new-project.md — Step 7 Define Requirements. Gathers functional requirements through conversation and writes REQUIREMENTS.md.
+</purpose>
+
+## 7. Define Requirements
+
+Display stage banner:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ rcode ► 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"
+```
+
+
+## Next Up
+
+This is a sub-step invoked by `/rcode-new-project`. If you reached this directly:
+
+- `/rcode-new-project` — re-enter the parent flow which orchestrates research → requirements → roadmap
+- `/rcode-status` — see where you are in the current project lifecycle

package/rcode/workflows/new-project-research-decision.md

@@ -0,0 +1,254 @@
+<purpose>
+Sub-step of new-project.md — Step 6 Research Decision. Decides whether to run domain research agents, handles existing research, and synthesizes findings before requirements.
+</purpose>
+
+## 6. Research Decision
+
+**If auto mode:** Default to "Research first" without asking.
+
+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:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ rcode ► 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 rcode-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="rcode-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="rcode-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="rcode-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="rcode-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="rcode-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:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ rcode ► 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.
+
+
+## Next Up
+
+This is a sub-step invoked by `/rcode-new-project`. If you reached this directly:
+
+- `/rcode-new-project` — re-enter the parent flow which orchestrates research → requirements → roadmap
+- `/rcode-status` — see where you are in the current project lifecycle