@hanzlaa/rcode 3.6.16 → 4.1.0

package/rcode/workflows/add-tests.md

@@ -0,0 +1,362 @@
+<purpose>
+Generate unit and E2E tests for a completed phase based on its SUMMARY.md, CONTEXT.md, and implementation. Classifies each changed file into TDD (unit), E2E (browser), or Skip categories, presents a test plan for user approval, then generates tests following RED-GREEN conventions.
+
+Users currently hand-craft `/rcode-quick` prompts for test generation after each phase. This workflow standardizes the process with proper classification, quality gates, and gap reporting.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+@.rcode/references/karpathy-guidelines.md
+</required_reading>
+
+<process>
+
+<step name="parse_arguments">
+Parse `$ARGUMENTS` for:
+- Phase number (integer, decimal, or letter-suffix) → store as `$PHASE_ARG`
+- Remaining text after phase number → store as `$EXTRA_INSTRUCTIONS` (optional)
+
+Example: `/rcode-add-tests 12 focus on edge cases` → `$PHASE_ARG=12`, `$EXTRA_INSTRUCTIONS="focus on edge cases"`
+
+If no phase argument provided:
+
+```
+ERROR: Phase number required
+Usage: /rcode-add-tests <phase> [additional instructions]
+Example: /rcode-add-tests 12
+Example: /rcode-add-tests 12 focus on edge cases in the pricing module
+```
+
+Exit.
+</step>
+
+<step name="init_context">
+Load phase operation context:
+
+```bash
+INIT=$(node ".rcode/bin/rcode-tools.cjs" init phase-op "${PHASE_ARG}" 2>/dev/null)
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+If `INIT` is empty or `INIT.ok` is false, print error and exit:
+```
+Error: rcode-tools init failed. Verify .rcode/ is installed and state.json is valid.
+```
+
+Extract from init JSON: `phase_dir`, `phase_number`, `phase_name`.
+
+Verify the phase directory exists. If not:
+```
+ERROR: Phase directory not found for phase ${PHASE_ARG}
+Ensure the phase exists in .planning/phases/
+```
+Exit.
+
+Read the phase artifacts (in order of priority):
+1. `${phase_dir}/*-SUMMARY.md` — what was implemented, files changed
+2. `${phase_dir}/CONTEXT.md` — acceptance criteria, decisions
+3. `${phase_dir}/*-VERIFICATION.md` — user-verified scenarios (if UAT was done)
+
+If no SUMMARY.md exists:
+```
+ERROR: No SUMMARY.md found for phase ${PHASE_ARG}
+This command works on completed phases. Run /rcode-execute first.
+```
+Exit.
+
+Present banner:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ rcode ► ADD TESTS — Phase ${phase_number}: ${phase_name}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+</step>
+
+<step name="analyze_implementation">
+Extract the list of files modified by the phase from SUMMARY.md ("Files Changed" or equivalent section).
+
+For each file, classify into one of three categories:
+
+| Category | Criteria | Test Type |
+|----------|----------|-----------|
+| **TDD** | Pure functions where `expect(fn(input)).toBe(output)` is writable | Unit tests |
+| **E2E** | UI behavior verifiable by browser automation | Playwright/E2E tests |
+| **Skip** | Not meaningfully testable or already covered | None |
+
+**TDD classification — apply when:**
+- Business logic: calculations, pricing, tax rules, validation
+- Data transformations: mapping, filtering, aggregation, formatting
+- Parsers: CSV, JSON, XML, custom format parsing
+- Validators: input validation, schema validation, business rules
+- State machines: status transitions, workflow steps
+- Utilities: string manipulation, date handling, number formatting
+
+**E2E classification — apply when:**
+- Keyboard shortcuts: key bindings, modifier keys, chord sequences
+- Navigation: page transitions, routing, breadcrumbs, back/forward
+- Form interactions: submit, validation errors, field focus, autocomplete
+- Selection: row selection, multi-select, shift-click ranges
+- Drag and drop: reordering, moving between containers
+- Modal dialogs: open, close, confirm, cancel
+- Data grids: sorting, filtering, inline editing, column resize
+
+**Skip classification — apply when:**
+- UI layout/styling: CSS classes, visual appearance, responsive breakpoints
+- Configuration: config files, environment variables, feature flags
+- Glue code: dependency injection setup, middleware registration, routing tables
+- Migrations: database migrations, schema changes
+- Simple CRUD: basic create/read/update/delete with no business logic
+- Type definitions: records, DTOs, interfaces with no logic
+
+Read each file to verify classification. Don't classify based on filename alone.
+</step>
+
+<step name="present_classification">
+Present the classification to the user for confirmation before proceeding:
+
+```
+AskUserQuestion(
+  header: "Test Classification",
+  question: |
+    ## Files classified for testing
+
+    ### TDD (Unit Tests) — {N} files
+    {list of files with brief reason}
+
+    ### E2E (Browser Tests) — {M} files
+    {list of files with brief reason}
+
+    ### Skip — {K} files
+    {list of files with brief reason}
+
+    {if $EXTRA_INSTRUCTIONS: "Additional instructions: ${EXTRA_INSTRUCTIONS}"}
+
+    How would you like to proceed?
+  options:
+    - "Approve and generate test plan"
+    - "Adjust classification (I'll specify changes)"
+    - "Cancel"
+)
+```
+
+If user selects "Adjust classification": apply their changes and re-present.
+If user selects "Cancel": exit gracefully.
+</step>
+
+<step name="discover_test_structure">
+Before generating the test plan, discover the project's existing test structure:
+
+```bash
+# Find existing test directories
+find . -type d -name "*test*" -o -name "*spec*" -o -name "*__tests__*" 2>/dev/null | head -20
+# Find existing test files for convention matching
+find . -type f \( -name "*.test.*" -o -name "*.spec.*" -o -name "*Tests.fs" -o -name "*Test.fs" \) 2>/dev/null | head -20
+# Check for test runners
+ls package.json *.sln 2>/dev/null || true
+```
+
+Identify:
+- Test directory structure (where unit tests live, where E2E tests live)
+- Naming conventions (`.test.ts`, `.spec.ts`, `*Tests.fs`, etc.)
+- Test runner commands (how to execute unit tests, how to execute E2E tests)
+- Test framework (xUnit, NUnit, Jest, Playwright, etc.)
+
+If test structure is ambiguous, ask the user:
+```
+AskUserQuestion(
+  header: "Test Structure",
+  question: "I found multiple test locations. Where should I create tests?",
+  options: [list discovered locations, "Cancel — exit without changes"]
+)
+```
+</step>
+
+<step name="generate_test_plan">
+For each approved file, create a detailed test plan.
+
+**For TDD files**, plan tests following RED-GREEN-REFACTOR:
+1. Identify testable functions/methods in the file
+2. For each function: list input scenarios, expected outputs, edge cases
+3. Note: since code already exists, tests may pass immediately — that's OK, but verify they test the RIGHT behavior
+
+**For E2E files**, plan tests following RED-GREEN gates:
+1. Identify user scenarios from CONTEXT.md/VERIFICATION.md
+2. For each scenario: describe the user action, expected outcome, assertions
+3. Note: RED gate means confirming the test would fail if the feature were broken
+
+Present the complete test plan:
+
+```
+AskUserQuestion(
+  header: "Test Plan",
+  question: |
+    ## Test Generation Plan
+
+    ### Unit Tests ({N} tests across {M} files)
+    {for each file: test file path, list of test cases}
+
+    ### E2E Tests ({P} tests across {Q} files)
+    {for each file: test file path, list of test scenarios}
+
+    ### Test Commands
+    - Unit: {discovered test command}
+    - E2E: {discovered e2e command}
+
+    Ready to generate?
+  options:
+    - "Generate all"
+    - "Cherry-pick (I'll specify which)"
+    - "Adjust plan"
+)
+```
+
+If "Cherry-pick": ask user which tests to include.
+If "Adjust plan": apply changes and re-present.
+</step>
+
+<step name="execute_tdd_generation">
+For each approved TDD test:
+
+1. **Create test file** following discovered project conventions (directory, naming, imports)
+
+2. **Write test** with clear arrange/act/assert structure:
+   ```
+   // Arrange — set up inputs and expected outputs
+   // Act — call the function under test
+   // Assert — verify the output matches expectations
+   ```
+
+3. **Run the test**:
+   ```bash
+   {discovered test command}
+   ```
+
+4. **Evaluate result:**
+   - **Test passes**: Good — the implementation satisfies the test. Verify the test checks meaningful behavior (not just that it compiles).
+   - **Test fails with assertion error**: This may be a genuine bug discovered by the test. Flag it:
+     ```
+     ⚠️ Potential bug found: {test name}
+     Expected: {expected}
+     Actual: {actual}
+     File: {implementation file}
+     ```
+     Do NOT fix the implementation — this is a test-generation command, not a fix command. Record the finding.
+   - **Test fails with error (import, syntax, etc.)**: This is a test error. Fix the test and re-run.
+</step>
+
+<step name="execute_e2e_generation">
+For each approved E2E test:
+
+1. **Check for existing tests** covering the same scenario:
+   ```bash
+   grep -r "{scenario keyword}" {e2e test directory} 2>/dev/null || true
+   ```
+   If found, extend rather than duplicate.
+
+2. **Create test file** targeting the user scenario from CONTEXT.md/VERIFICATION.md
+
+3. **Run the E2E test**:
+   ```bash
+   {discovered e2e command}
+   ```
+
+4. **Evaluate result:**
+   - **GREEN (passes)**: Record success
+   - **RED (fails)**: Determine if it's a test issue or a genuine application bug. Flag bugs:
+     ```
+     ⚠️ E2E failure: {test name}
+     Scenario: {description}
+     Error: {error message}
+     ```
+   - **Cannot run**: Report blocker. Do NOT mark as complete.
+     ```
+     🛑 E2E blocker: {reason tests cannot run}
+     ```
+
+**No-skip rule:** If E2E tests cannot execute (missing dependencies, environment issues), report the blocker and mark the test as incomplete. Never mark success without actually running the test.
+</step>
+
+<step name="summary_and_commit">
+Create a test coverage report and present to user:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ rcode ► TEST GENERATION COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+## Results
+
+| Category | Generated | Passing | Failing | Blocked |
+|----------|-----------|---------|---------|---------|
+| Unit     | {N}       | {n1}    | {n2}    | {n3}    |
+| E2E      | {M}       | {m1}    | {m2}    | {m3}    |
+
+## Files Created/Modified
+{list of test files with paths}
+
+## Coverage Gaps
+{areas that couldn't be tested and why}
+
+## Bugs Discovered
+{any assertion failures that indicate implementation bugs}
+```
+
+Record test generation in project state:
+```bash
+node ".rcode/bin/rcode-tools.cjs" state-snapshot
+```
+
+If there are passing tests to commit:
+
+```bash
+git add {test files}
+git commit -m "test(phase-${phase_number}): add unit and E2E tests from add-tests command"
+```
+
+Present next steps:
+
+```
+---
+
+## ▶ Next Up
+
+{if bugs discovered:}
+**Fix discovered bugs:** `/rcode-quick fix the {N} test failures discovered in phase ${phase_number}`
+
+{if blocked tests:}
+**Resolve test blockers:** {description of what's needed}
+
+{otherwise:}
+**All tests passing!** Phase ${phase_number} is fully tested.
+
+---
+
+**Also available:**
+- `/rcode-add-tests {next_phase}` — test another phase
+- `/rcode-verify-work {phase_number}` — run UAT verification
+
+---
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Phase artifacts loaded (SUMMARY.md, CONTEXT.md, optionally VERIFICATION.md)
+- [ ] All changed files classified into TDD/E2E/Skip categories
+- [ ] Classification presented to user and approved
+- [ ] Project test structure discovered (directories, conventions, runners)
+- [ ] Test plan presented to user and approved
+- [ ] TDD tests generated with arrange/act/assert structure
+- [ ] E2E tests generated targeting user scenarios
+- [ ] All tests executed — no untested tests marked as passing
+- [ ] Bugs discovered by tests flagged (not fixed)
+- [ ] Test files committed with proper message
+- [ ] Coverage gaps documented
+- [ ] Next steps presented to user
+</success_criteria>
+
+## Next Up
+
+- `/rcode-verify-work` — run UAT to confirm tests pass in context
+- `/rcode-code-review` — review test quality before committing

package/rcode/workflows/add-todo.md

@@ -0,0 +1,193 @@
+<purpose>
+Capture an idea, task, or issue that surfaces during a rcode session as a structured note for later work. Enables "thought → capture → continue" flow without losing context.
+</purpose>
+
+
+## Step 0 — Usage check
+
+If `$ARGUMENTS` is empty or contains only `--help` or `-h`:
+
+```
+/rcode-add-todo <argument-here>
+```
+
+**Examples:**
+```
+/rcode-add-todo example 1
+/rcode-add-todo example 2
+```
+
+STOP — do not proceed.
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="init_context">
+Load todo context:
+
+```bash
+[ -d .rcode/todos ] || mkdir -p .rcode/todos/pending .rcode/todos/done
+```
+
+Ensure directories exist for organized todo capture.
+</step>
+
+<step name="extract_content">
+**With arguments:** Use as the title/focus.
+- `/rcode-add-todo Add auth token refresh` → title = "Add auth token refresh"
+
+**Without arguments:** Analyze recent conversation to extract:
+- The specific problem, idea, or task discussed
+- Relevant file paths mentioned
+- Technical details (error messages, line numbers, constraints)
+
+Formulate:
+- `title`: 3-10 word descriptive title (action verb preferred)
+- `problem`: What's wrong or why this is needed
+- `solution`: Approach hints or "TBD" if just an idea
+- `files`: Relevant paths with line numbers from conversation
+</step>
+
+<step name="infer_area">
+Infer area from file paths:
+
+| Path pattern | Area |
+|--------------|------|
+| `src/api/*`, `api/*` | `api` |
+| `src/components/*`, `src/ui/*` | `ui` |
+| `src/auth/*`, `auth/*` | `auth` |
+| `src/db/*`, `database/*` | `database` |
+| `tests/*`, `__tests__/*` | `testing` |
+| `docs/*` | `docs` |
+| `.rcode/*` | `planning` |
+| `scripts/*`, `bin/*` | `tooling` |
+| No files or unclear | `general` |
+
+Use existing area if similar match exists.
+</step>
+
+<step name="check_duplicates">
+```bash
+# Search for key words from title in existing todos
+grep -l -i "[key words from title]" .rcode/todos/pending/*.md 2>/dev/null || true
+```
+
+If potential duplicate found:
+1. Read the existing todo
+2. Compare scope
+
+If overlapping, ask user:
+- "Similar todo exists: [title]. What would you like to do?"
+- Options:
+  - "Skip" — keep existing todo
+  - "Replace" — update existing with new context
+  - "Add anyway" — create as separate todo
+</step>
+
+<step name="create_file">
+Generate slug for the title and write to `.rcode/todos/pending/{date}-{slug}.md`:
+
+```bash
+slug=$(echo "$title" | tr ' ' '-' | tr '[:upper:]' '[:lower:]')
+date=$(date +%Y-%m-%d)
+```
+
+Write file with:
+
+```markdown
+---
+created: [ISO timestamp]
+title: [title]
+area: [area]
+files:
+  - [file:lines]
+---
+
+## Problem
+
+[problem description - enough context for future agent to understand weeks later]
+
+## Solution
+
+[approach hints or "TBD"]
+```
+</step>
+
+<step name="update_state">
+If `.rcode/STATE.md` exists:
+
+1. Count pending todos in .rcode/todos/pending/
+2. Update "## Pending Todos" section (if exists)
+</step>
+
+<step name="git_commit">
+Commit the todo and any updated state:
+
+```bash
+git add .rcode/todos/pending/ .rcode/STATE.md 2>/dev/null || true
+git commit -m "docs: capture todo - $title" 2>/dev/null || true
+```
+
+Confirm: "Committed: docs: capture todo - [title]"
+</step>
+
+<step name="confirm">
+```
+Todo saved: .rcode/todos/pending/[filename]
+
+  [title]
+  Area: [area]
+  Files: [count] referenced
+
+---
+
+Would you like to:
+
+1. Continue with current work
+2. Add another todo
+3. View all todos (/rcode-add-todo --list)
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Directory structure exists
+- [ ] Todo file created with valid frontmatter
+- [ ] Problem section has enough context for future agent
+- [ ] No duplicates (checked and resolved)
+- [ ] Area consistent with existing todos
+- [ ] STATE.md updated if exists
+- [ ] Todo committed to git
+</success_criteria>
+</process>
+
+## Success Criteria
+
+- [ ] Todo file created at `.rcode/todos/pending/{date}-{slug}.md` with valid YAML frontmatter (created, title, area, files)
+- [ ] Problem section contains enough context for a future agent to act without re-investigation
+- [ ] Duplicate check performed against existing pending todos; conflict resolved before file creation
+- [ ] `.rcode/STATE.md` updated with pending todo count (if the file exists)
+- [ ] Todo committed to git with a `docs: capture todo - {title}` message
+
+## 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
+
+
+## On Completion
+
+/rcode-check-todos — review all open todos
+/rcode-next — get suggested next action
+/rcode-progress — see overall roadmap status
+
+## Next Up
+
+- `/rcode-check-todos` — view all captured todos
+- `/rcode-do` — continue with your current work

package/rcode/workflows/analyze-dependencies.md

@@ -0,0 +1,149 @@
+# Workflow: rcode-analyze-dependencies
+
+<purpose>
+Analyze ROADMAP.md phases for dependency relationships before execution. Detect file overlap between phases, semantic API/data-flow dependencies, and suggest `Depends on` entries to prevent merge conflicts during parallel execution.
+</purpose>
+
+
+## Step 0 — Usage check
+
+If `$ARGUMENTS` is empty or contains only `--help` or `-h`:
+
+```
+/rcode-analyze-dependencies <argument-here>
+```
+
+**Examples:**
+```
+/rcode-analyze-dependencies example 1
+/rcode-analyze-dependencies example 2
+```
+
+STOP — do not proceed.
+
+## Step 0 — Load ROADMAP.md
+
+**Action:** Read `.planning/ROADMAP.md` and extract all phases.
+
+```bash
+test -f .planning/ROADMAP.md || echo "No ROADMAP.md found — run /rcode-new-project first."
+```
+
+For each phase, capture:
+- Phase number and name
+- Scope/Goal description
+- Files listed in `Files` or `files_modified` fields (if present)
+- Existing `Depends on` field value
+
+If file missing: exit with instructions to create project.
+
+## Step 1 — Infer likely file modifications
+
+**Action:** For each phase without explicit `files_modified`, analyze scope/goal and infer file domains.
+
+Use heuristics to classify phases:
+- **Database/schema phases** → migration files, schema definitions, model files
+- **API/backend phases** → route files, controller files, service files, handler files
+- **Frontend/UI phases** → component files, page files, style files
+- **Auth phases** → middleware files, auth route files, session/token files
+- **Config/infra phases** → config files, environment files, CI/CD files
+- **Test phases** → test files, spec files, fixture files
+- **Shared utility phases** → lib/utils files, shared type definitions
+
+Group phases by inferred file domain (database, API, frontend, auth, config, shared).
+
+## Step 2 — Detect dependency relationships
+
+**Action:** For each pair of phases (A, B), check for three types of dependencies.
+
+### File Overlap Detection
+If phases A and B both modify files in same domain or same specific file, one must run before the other. The foundational phase runs first.
+
+### Semantic Dependency Detection
+Read each phase's scope/goal for patterns:
+- Phase B mentions consuming/using something Phase A creates/implements
+- Phase B references "API", "schema", "model", "endpoint", "interface" that Phase A builds
+- Phase B says "after X complete", "once X built", "using the X from Phase N"
+- Phase B extends code that Phase A establishes
+
+### Data Flow Detection
+- Phase A creates data structures/schemas → Phase B consumes/transforms them
+- Phase A seeds/migrates database → Phase B reads from it
+- Phase A exposes API contract → Phase B implements client for it
+
+## Step 3 — Build dependency table
+
+**Action:** Output dependency suggestions for each phase.
+
+For each phase, print:
+
+```
+Phase N: <name>
+  Scope: <brief scope>
+  Likely touches: <inferred file domains>
+
+  Suggested dependencies:
+  → Depends on: <Phase M> — reason: <overlap/semantic/data-flow explanation>
+
+  Current "Depends on": <existing value or "(none)">
+```
+
+For phase pairs with no detected dependency: "No dependency detected between Phase X and Phase Y."
+
+## Step 4 — Summarize suggested changes
+
+**Action:** Show consolidated diff of proposed ROADMAP.md `Depends on` changes.
+
+```
+Suggested ROADMAP.md updates:
+  Phase 3: add "Depends on: 1, 2"   (file overlap: database schema)
+  Phase 5: add "Depends on: 3"      (semantic: uses auth API from Phase 3)
+  Phase 4: no change needed         (independent scope)
+```
+
+## Step 5 — Confirm and apply changes
+
+**Action:** Ask user for confirmation and apply changes if approved.
+
+```
+Apply these Depends on suggestions to ROADMAP.md? (yes / no / edit)
+```
+
+Handle responses:
+- **yes** — Write all suggested entries to ROADMAP.md. Confirm each write.
+- **no** — Print suggestions as text only. User updates manually.
+- **edit** — Present each suggestion individually with yes/no/skip per suggestion.
+
+When writing:
+- Locate phase entry and add or update `Depends on:` field
+- Preserve all other phase content unchanged
+- Do not reorder phases
+
+After applying: "ROADMAP.md updated. Run `/rcode-execute-milestone` to execute phases in the correct order."
+
+## Success Criteria
+
+- [ ] All phases analyzed for dependencies
+- [ ] File overlap detected correctly
+- [ ] Semantic dependencies identified
+- [ ] Data flow dependencies recognized
+- [ ] Suggestions clear and justified
+- [ ] User approval obtained before changes
+- [ ] ROADMAP.md updated atomically
+
+## On Error
+
+- **ROADMAP.md missing:** Print error and suggest creating project first
+- **Phase parsing fails:** Print which phase and why parsing failed
+- **File write fails:** Print error and suggest manual update
+
+## ▶ Next Up
+
+- **Circular deps found:** Fix dependency cycle, then re-run analysis
+- /rcode-execute {phase}
+- /rcode-progress
+
+## Next Up
+
+- `/rcode-plan-milestone` — plan phases in the correct dependency order
+- `/rcode-execute-milestone` — execute phases with dependency-aware wave ordering