npm - @hanzlaa/rcode - Versions diffs - 3.6.15 → 4.0.0 - Mend

@hanzlaa/rcode 3.6.15 → 4.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1484) hide show

package/rihal/agents/rules/roadmapper/detailed-guide.md DELETED Viewed

@@ -1,620 +0,0 @@
-## Requirements Drive Structure
-**Derive phases from requirements. Don't impose structure.**
-Bad: "Every project needs Setup → Core → Features → Polish"
-Good: "These 12 requirements cluster into 4 natural delivery boundaries"
-Let the work determine the phases, not a template.
-## Goal-Backward at Phase Level
-**Forward planning asks:** "What should we build in this phase?"
-**Goal-backward asks:** "What must be TRUE for users when this phase completes?"
-Forward produces task lists. Goal-backward produces success criteria that tasks must satisfy.
-## Coverage is Non-Negotiable
-Every v1 requirement must map to exactly one phase. No orphans. No duplicates.
-If a requirement doesn't fit any phase → create a phase or defer to v2.
-If a requirement fits multiple phases → assign to ONE (usually the first that could deliver it).
-</philosophy>
-<goal_backward_phases>
-## Deriving Phase Success Criteria
-For each phase, ask: "What must be TRUE for users when this phase completes?"
-**Step 1: State the Phase Goal**
-Take the phase goal from your phase identification. This is the outcome, not work.
-- Good: "Users can securely access their accounts" (outcome)
-- Bad: "Build authentication" (task)
-**Step 2: Derive Observable Truths (2-5 per phase)**
-List what users can observe/do when the phase completes.
-For "Users can securely access their accounts":
-- User can create account with email/password
-- User can log in and stay logged in across browser sessions
-- User can log out from any page
-- User can reset forgotten password
-**Test:** Each truth should be verifiable by a human using the application.
-**Step 3: Cross-Check Against Requirements**
-For each success criterion:
-- Does at least one requirement support this?
-- If not → gap found
-For each requirement mapped to this phase:
-- Does it contribute to at least one success criterion?
-- If not → question if it belongs here
-**Step 4: Resolve Gaps**
-Success criterion with no supporting requirement:
-- Add requirement to REQUIREMENTS.md, OR
-- Mark criterion as out of scope for this phase
-Requirement that supports no criterion:
-- Question if it belongs in this phase
-- Maybe it's v2 scope
-- Maybe it belongs in different phase
-## Example Gap Resolution
-```
-Phase 2: Authentication
-Goal: Users can securely access their accounts
-Success Criteria:
-1. User can create account with email/password ← AUTH-01 ✓
-2. User can log in across sessions ← AUTH-02 ✓
-3. User can log out from any page ← AUTH-03 ✓
-4. User can reset forgotten password ← ??? GAP
-Requirements: AUTH-01, AUTH-02, AUTH-03
-Gap: Criterion 4 (password reset) has no requirement.
-Options:
-1. Add AUTH-04: "User can reset password via email link"
-2. Remove criterion 4 (defer password reset to v2)
-```
-</goal_backward_phases>
-<phase_identification>
-## Deriving Phases from Requirements
-**Step 1: Group by Category**
-Requirements already have categories (AUTH, CONTENT, SOCIAL, etc.).
-Start by examining these natural groupings.
-**Step 2: Identify Dependencies**
-Which categories depend on others?
-- SOCIAL needs CONTENT (can't share what doesn't exist)
-- CONTENT needs AUTH (can't own content without users)
-- Everything needs SETUP (foundation)
-**Step 3: Create Delivery Boundaries**
-Each phase delivers a coherent, verifiable capability.
-Good boundaries:
-- Complete a requirement category
-- Enable a user workflow end-to-end
-- Unblock the next phase
-Bad boundaries:
-- Arbitrary technical layers (all models, then all APIs)
-- Partial features (half of auth)
-- Artificial splits to hit a number
-**Step 4: Assign Requirements**
-Map every v1 requirement to exactly one phase.
-Track coverage as you go.
-## Phase Numbering
-**Integer phases (1, 2, 3):** Planned milestone work.
-**Decimal phases (2.1, 2.2):** Urgent insertions after planning.
-- Created via `/rihal-insert-phase`
-- Execute between integers: 1 → 1.1 → 1.2 → 2
-**Starting number:**
-- New milestone: Start at 1
-- Continuing milestone: Check existing phases, start at last + 1
-## Granularity Calibration
-Read granularity from config.json. Granularity controls compression tolerance.
-| Granularity | Typical Phases | What It Means |
-|-------------|----------------|---------------|
-| Coarse | 3-5 | Combine aggressively, critical path only |
-| Standard | 5-8 | Balanced grouping |
-| Fine | 8-12 | Let natural boundaries stand |
-**Key:** Derive phases from work, then apply granularity as compression guidance. Don't pad small projects or compress complex ones.
-## Good Phase Patterns
-**Foundation → Features → Enhancement**
-```
-Phase 1: Setup (project scaffolding, CI/CD)
-Phase 2: Auth (user accounts)
-Phase 3: Core Content (main features)
-Phase 4: Social (sharing, following)
-Phase 5: Polish (performance, edge cases)
-```
-**Vertical Slices (Independent Features)**
-```
-Phase 1: Setup
-Phase 2: User Profiles (complete feature)
-Phase 3: Content Creation (complete feature)
-Phase 4: Discovery (complete feature)
-```
-**Anti-Pattern: Horizontal Layers**
-```
-Phase 1: All database models ← Too coupled
-Phase 2: All API endpoints ← Can't verify independently
-Phase 3: All UI components ← Nothing works until end
-```
-</phase_identification>
-<coverage_validation>
-## 100% Requirement Coverage
-After phase identification, verify every v1 requirement is mapped.
-**Build coverage map:**
-```
-AUTH-01 → Phase 2
-AUTH-02 → Phase 2
-AUTH-03 → Phase 2
-PROF-01 → Phase 3
-PROF-02 → Phase 3
-CONT-01 → Phase 4
-CONT-02 → Phase 4
-...
-Mapped: 12/12 ✓
-```
-**If orphaned requirements found:**
-```
-⚠️ Orphaned requirements (no phase):
-- NOTF-01: User receives in-app notifications
-- NOTF-02: User receives email for followers
-Options:
-1. Create Phase 6: Notifications
-2. Add to existing Phase 5
-3. Defer to v2 (update REQUIREMENTS.md)
-```
-**Do not proceed until coverage = 100%.**
-## Traceability Update
-After roadmap creation, REQUIREMENTS.md gets updated with phase mappings:
-```markdown
-## Traceability
-| Requirement | Phase | Status |
-|-------------|-------|--------|
-| AUTH-01 | Phase 2 | Pending |
-| AUTH-02 | Phase 2 | Pending |
-| PROF-01 | Phase 3 | Pending |
-...
-```
-</coverage_validation>
-<output_formats>
-## ROADMAP.md Structure
-**CRITICAL: ROADMAP.md requires TWO phase representations. Both are mandatory.**
-### 1. Summary Checklist (under `## Phases`)
-```markdown
-- [ ] **Phase 1: Name** - One-line description
-- [ ] **Phase 2: Name** - One-line description
-- [ ] **Phase 3: Name** - One-line description
-```
-### 2. Detail Sections (under `## Phase Details`)
-```markdown
-### Phase 1: Name
-**Goal**: What this phase delivers
-**Depends on**: Nothing (first phase)
-**Requirements**: REQ-01, REQ-02
-**Success Criteria** (what must be TRUE):
-  1. Observable behavior from user perspective
-  2. Observable behavior from user perspective
-**Plans**: TBD
-### Phase 2: Name
-**Goal**: What this phase delivers
-**Depends on**: Phase 1
-...
-```
-**The `### Phase X:` headers are parsed by downstream tools.** If you only write the summary checklist, phase lookups will fail.
-### UI Phase Detection
-After writing phase details, scan each phase's goal, name, requirements, and success criteria for UI/frontend keywords. If a phase matches, add a `**UI hint**: yes` annotation to that phase's detail section (after `**Plans**`).
-**Detection keywords** (case-insensitive):
-```
-UI, interface, frontend, component, layout, page, screen, view, form,
-dashboard, widget, CSS, styling, responsive, navigation, menu, modal,
-sidebar, header, footer, theme, design system, Tailwind, React, Vue,
-Svelte, Next.js, Nuxt
-```
-**Example annotated phase:**
-```markdown
-### Phase 3: Dashboard & Analytics
-**Goal**: Users can view activity metrics and manage settings
-**Depends on**: Phase 2
-**Requirements**: DASH-01, DASH-02
-**Success Criteria** (what must be TRUE):
-  1. User can view a dashboard with key metrics
-  2. User can filter analytics by date range
-**Plans**: TBD
-**UI hint**: yes
-```
-This annotation is consumed by downstream workflows (`new-project`, `progress`) to suggest `/rihal-ui-phase` at the right time. Phases without UI indicators omit the annotation entirely.
-### 3. Progress Table
-```markdown
-| Phase | Plans Complete | Status | Completed |
-|-------|----------------|--------|-----------|
-| 1. Name | 0/3 | Not started | - |
-| 2. Name | 0/2 | Not started | - |
-```
-Reference full template: `.rihal/templates/roadmap.md`
-## STATE.md Structure
-Use template from `.rihal/templates/state.md`.
-Key sections:
-- Project Reference (core value, current focus)
-- Current Position (phase, plan, status, progress bar)
-- Performance Metrics
-- Accumulated Context (decisions, todos, blockers)
-- Session Continuity
-## Draft Presentation Format
-When presenting to user for approval:
-```markdown
-## ROADMAP DRAFT
-**Phases:** [N]
-**Granularity:** [from config]
-**Coverage:** [X]/[Y] requirements mapped
-### Phase Structure
-| Phase | Goal | Requirements | Success Criteria |
-|-------|------|--------------|------------------|
-| 1 - Setup | [goal] | SETUP-01, SETUP-02 | 3 criteria |
-| 2 - Auth | [goal] | AUTH-01, AUTH-02, AUTH-03 | 4 criteria |
-| 3 - Content | [goal] | CONT-01, CONT-02 | 3 criteria |
-### Success Criteria Preview
-**Phase 1: Setup**
-1. [criterion]
-2. [criterion]
-**Phase 2: Auth**
-1. [criterion]
-2. [criterion]
-3. [criterion]
-[... abbreviated for longer roadmaps ...]
-### Coverage
-✓ All [X] v1 requirements mapped
-✓ No orphaned requirements
-### Awaiting
-Approve roadmap or provide feedback for revision.
-```
-</output_formats>
-<execution_flow>
-## Step 1: Receive Context
-Orchestrator provides:
-- PROJECT.md content (core value, constraints)
-- REQUIREMENTS.md content (v1 requirements with REQ-IDs)
-- research/SUMMARY.md content (if exists - phase suggestions)
-- config.json (granularity setting)
-Parse and confirm understanding before proceeding.
-## Step 2: Extract Requirements
-Parse REQUIREMENTS.md:
-- Count total v1 requirements
-- Extract categories (AUTH, CONTENT, etc.)
-- Build requirement list with IDs
-```
-Categories: 4
-- Authentication: 3 requirements (AUTH-01, AUTH-02, AUTH-03)
-- Profiles: 2 requirements (PROF-01, PROF-02)
-- Content: 4 requirements (CONT-01, CONT-02, CONT-03, CONT-04)
-- Social: 2 requirements (SOC-01, SOC-02)
-Total v1: 11 requirements
-```
-## Step 3: Load Research Context (if exists)
-If research/SUMMARY.md provided:
-- Extract suggested phase structure from "Implications for Roadmap"
-- Note research flags (which phases need deeper research)
-- Use as input, not mandate
-Research informs phase identification but requirements drive coverage.
-## Step 4: Identify Phases
-Apply phase identification methodology:
-1. Group requirements by natural delivery boundaries
-2. Identify dependencies between groups
-3. Create phases that complete coherent capabilities
-4. Check granularity setting for compression guidance
-## Step 5: Derive Success Criteria
-For each phase, apply goal-backward:
-1. State phase goal (outcome, not task)
-2. Derive 2-5 observable truths (user perspective)
-3. Cross-check against requirements
-4. Flag any gaps
-## Step 6: Validate Coverage
-Verify 100% requirement mapping:
-- Every v1 requirement → exactly one phase
-- No orphans, no duplicates
-If gaps found, include in draft for user decision.
-## Step 7: Write Files Immediately
-**ALWAYS use the Write tool to create files** — never use `Bash(cat << 'EOF')` or heredoc commands for file creation.
-Write files first, then return. This ensures artifacts persist even if context is lost.
-1. **Write ROADMAP.md** using output format
-2. **Write STATE.md** using output format
-3. **Update REQUIREMENTS.md traceability section**
-Files on disk = context preserved. User can review actual files.
-## Step 8: Return Summary
-Return `## ROADMAP CREATED` with summary of what was written.
-## Step 9: Handle Revision (if needed)
-If orchestrator provides revision feedback:
-- Parse specific concerns
-- Update files in place (Edit, not rewrite from scratch)
-- Re-validate coverage
-- Return `## ROADMAP REVISED` with changes made
-</execution_flow>
-<structured_returns>
-## Roadmap Created
-When files are written and returning to orchestrator:
-```markdown
-## ROADMAP CREATED
-**Files written:**
-- .rihal/ROADMAP.md
-- .rihal/STATE.md
-**Updated:**
-- .rihal/REQUIREMENTS.md (traceability section)
-### Summary
-**Phases:** {N}
-**Granularity:** {from config}
-**Coverage:** {X}/{X} requirements mapped ✓
-| Phase | Goal | Requirements |
-|-------|------|--------------|
-| 1 - {name} | {goal} | {req-ids} |
-| 2 - {name} | {goal} | {req-ids} |
-### Success Criteria Preview
-**Phase 1: {name}**
-1. {criterion}
-2. {criterion}
-**Phase 2: {name}**
-1. {criterion}
-2. {criterion}
-### Files Ready for Review
-User can review actual files:
-- `cat .rihal/ROADMAP.md`
-- `cat .rihal/STATE.md`
-{If gaps found during creation:}
-### Coverage Notes
-⚠️ Issues found during creation:
-- {gap description}
-- Resolution applied: {what was done}
-```
-## Roadmap Revised
-After incorporating user feedback and updating files:
-```markdown
-## ROADMAP REVISED
-**Changes made:**
-- {change 1}
-- {change 2}
-**Files updated:**
-- .rihal/ROADMAP.md
-- .rihal/STATE.md (if needed)
-- .rihal/REQUIREMENTS.md (if traceability changed)
-### Updated Summary
-| Phase | Goal | Requirements |
-|-------|------|--------------|
-| 1 - {name} | {goal} | {count} |
-| 2 - {name} | {goal} | {count} |
-**Coverage:** {X}/{X} requirements mapped ✓
-### Ready for Planning
-Next: `/rihal-plan 1`
-```
-## Roadmap Blocked
-When unable to proceed:
-```markdown
-## ROADMAP BLOCKED
-**Blocked by:** {issue}
-### Details
-{What's preventing progress}
-### Options
-1. {Resolution option 1}
-2. {Resolution option 2}
-### Awaiting
-{What input is needed to continue}
-```
-</structured_returns>
-<anti_patterns>
-## What Not to Do
-**Don't impose arbitrary structure:**
-- Bad: "All projects need 5-7 phases"
-- Good: Derive phases from requirements
-**Don't use horizontal layers:**
-- Bad: Phase 1: Models, Phase 2: APIs, Phase 3: UI
-- Good: Phase 1: Complete Auth feature, Phase 2: Complete Content feature
-**Don't skip coverage validation:**
-- Bad: "Looks like we covered everything"
-- Good: Explicit mapping of every requirement to exactly one phase
-**Don't write vague success criteria:**
-- Bad: "Authentication works"
-- Good: "User can log in with email/password and stay logged in across sessions"
-**Don't add project management artifacts:**
-- Bad: Time estimates, Gantt charts, resource allocation, risk matrices
-- Good: Phases, goals, requirements, success criteria
-**Don't duplicate requirements across phases:**
-- Bad: AUTH-01 in Phase 2 AND Phase 3
-- Good: AUTH-01 in Phase 2 only
-</anti_patterns>
-<success_criteria>
-Roadmap is complete when:
-- [ ] PROJECT.md core value understood
-- [ ] All v1 requirements extracted with IDs
-- [ ] Research context loaded (if exists)
-- [ ] Phases derived from requirements (not imposed)
-- [ ] Granularity calibration applied
-- [ ] Dependencies between phases identified
-- [ ] Success criteria derived for each phase (2-5 observable behaviors)
-- [ ] Success criteria cross-checked against requirements (gaps resolved)
-- [ ] 100% requirement coverage validated (no orphans)
-- [ ] ROADMAP.md structure complete
-- [ ] STATE.md structure complete
-- [ ] REQUIREMENTS.md traceability update prepared
-- [ ] Draft presented for user approval
-- [ ] User feedback incorporated (if any)
-- [ ] Files written (after approval)
-- [ ] Structured return provided to orchestrator
-Quality indicators:
-- **Coherent phases:** Each delivers one complete, verifiable capability
-- **Clear success criteria:** Observable from user perspective, not implementation details
-- **Full coverage:** Every requirement mapped, no orphans
-- **Natural structure:** Phases feel inevitable, not arbitrary
-- **Honest gaps:** Coverage issues surfaced, not hidden
-</success_criteria>
-## Constraints
-- preserve phase structure from existing ROADMAP.md
-- validate phase dependencies before suggesting order
-- document risk and complexity estimates clearly
-- follow ROADMAP.md schema exactly
-- never remove phases without explicit confirmation