@hanzlaa/rcode 3.6.16 → 4.1.0

package/rcode/workflows/init.md

@@ -0,0 +1,356 @@
+# Workflow: rcode-init
+
+<purpose>
+Begin the rihla. This is the entry point for configuring rcode in a project. Runs automatically on first use of any rcode command (via auto-init-guard in do.md), or explicitly via /rcode-init for a full setup with codebase scan.
+
+No manual "rcode install" needed per project — just use any /rcode-* command and this triggers automatically when config is missing.
+</purpose>
+
+## Step 0 — Usage check
+
+If `$ARGUMENTS` contains only `--help` or `-h`:
+
+```
+Usage: /rcode-init [--reset] [--skip-scan]
+
+  --reset        overwrite existing .rcode/config.yaml and JOURNEY.md
+  --skip-scan    skip the codebase scan step
+
+Examples:
+  /rcode-init                  # first-time setup for this project
+  /rcode-init --reset          # reconfigure from scratch
+  /rcode-init --skip-scan      # config only, no codebase read
+```
+
+STOP here if just help was requested.
+
+## Step 1 — Greet and detect state
+
+Print:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  السلام عليكم — rcode init
+  Configuring your rihla (journey)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Run detection in parallel:
+
+```bash
+# rcode presence
+test -f .rcode/config.yaml && echo "rcode-configured: yes" || echo "rcode-configured: no"
+test -f .rcode/state.json && echo "state-present: yes" || echo "state-present: no"
+test -f .rcode/JOURNEY.md && echo "rihla-present: yes" || echo "rihla-present: no"
+
+# Project presence
+# Use git rev-parse instead of test -d .git — in git worktrees .git is a FILE not a dir
+git rev-parse --is-inside-work-tree >/dev/null 2>&1 && echo "git: yes" || echo "git: no"
+ls package.json pyproject.toml Cargo.toml go.mod 2>/dev/null | head -3
+find . -maxdepth 2 -type d \( -name src -o -name app -o -name lib \) 2>/dev/null | head -3
+
+# Git history depth (if present)
+git log --oneline 2>/dev/null | wc -l
+```
+
+Classify project into one of four states:
+
+| State | Signal | Suggested next step |
+|-------|--------|---------------------|
+| `fresh` | No code, no git, no rcode | `/rcode-new-project` — let's design it |
+| `existing-new-rcode` | Has code + git, no rcode | `/rcode-scan` or `/rcode-council` — understand before changing |
+| `returning` | rcode already configured | `/rcode-resume-work` or `/rcode-next` |
+| `reset` | User passed `--reset` flag | Proceed with full reconfigure |
+
+Print one-line state summary:
+
+```
+📁 State: {state}  |  Code: {detected or none}  |  Git: {commits or none}  |  Journey: {present or new}
+```
+
+If `state === "returning"` and `--reset` not passed:
+
+- If `rihla-present: yes` — print the standard returning message and STOP:
+
+  ```
+  ✓ rcode is already configured here.
+
+  What next?
+    /rcode-resume-work    — pick up where you left off
+    /rcode-status         — see the dashboard
+    /rcode-next           — suggested next action
+
+  Or run with --reset to reconfigure.
+  ```
+
+- If `rihla-present: no` — JOURNEY.md is missing from a partial prior init. Do NOT stop. Print a recovery notice and continue to Steps 4 and 4b to write the missing baseline:
+
+  ```
+  ✓ rcode is already configured here.
+
+  JOURNEY.md baseline is missing — completing the scan step now...
+  ```
+
+  Skip Steps 2 and 3 (config already exists). Jump directly to Step 4.
+
+## Step 2 — Ask the questions
+
+Use AskUserQuestion (one batched question with multiple fields if the tool supports; otherwise sequential).
+
+**Pre-fill from existing `.rcode/config.yaml` if present, otherwise from defaults.**
+
+Questions:
+
+1. **Your name** (what rcode calls you in state artifacts)
+   - Default: `$USER` environment variable
+2. **Communication language** (how agents talk to you)
+   - Options: English, Urdu, Arabic, Roman Urdu, Mixed
+   - Default: English
+3. **Mode** (how rcode proceeds at decision gates)
+   - Options: `guided` (confirm at each gate), `yolo` (proceed autonomously)
+   - Default: guided
+4. **Model profile** (agent cost vs quality tradeoff)
+   - Options: `quality` (opus for reasoning), `balanced` (sonnet), `budget` (haiku), `inherit` (use parent model)
+   - Default: balanced
+5. **Branching strategy** (how code commits land)
+   - Options: `none` (current branch), `feature-branch` (one per phase), `worktree-isolation` (parallel-safe)
+   - Default: none
+
+## Step 3 — Write config + state seed
+
+Write `.rcode/config.yaml` via `rcode-tools.cjs config-set` (not direct file write):
+
+```bash
+node .rcode/bin/rcode-tools.cjs config-set user_name "{name}"
+node .rcode/bin/rcode-tools.cjs config-set project_name "$(basename $(pwd))"
+node .rcode/bin/rcode-tools.cjs config-set communication_language "{lang}"
+node .rcode/bin/rcode-tools.cjs config-set mode "{mode}"
+node .rcode/bin/rcode-tools.cjs config-set model_profile "{profile}"
+node .rcode/bin/rcode-tools.cjs config-set git.branching_strategy "{strategy}"
+```
+
+Initialize state.json if missing:
+
+```bash
+test -f .rcode/state.json || node .rcode/bin/rcode-tools.cjs state init --project "$(basename $(pwd))"
+```
+
+## Step 4 — Scan existing context (skip if `--skip-scan`)
+
+If the project has code (from Step 1 detection), produce `.rcode/JOURNEY.md`. This is the journey baseline — a lightweight snapshot, not a full audit. Use `/rcode-map-codebase` or `/rcode-scan` later for deep analysis.
+
+**Memory-bank refresh on `--reset`.** When `--reset` is passed AND `.planning/codebase/` already contains docs from a previous scan, also chain to `/rcode-scan --refresh --focus tech+arch` immediately after writing JOURNEY.md. The refresh path:
+
+- Captures pre-state (commits since last doc mtime, manifest hashes, top-level dirs).
+- Briefs the user on what changed since the last scan.
+- Overwrites the docs and appends an entry to `.planning/codebase/CHANGELOG.md`.
+
+Skip the chain if `--skip-scan` is set, no existing docs are present (nothing stale to refresh), or the user passes `--no-refresh`.
+
+This makes init+reset a true memory-bank refresh — JOURNEY baseline updated, codebase docs reconciled with current code, CHANGELOG entry written.
+
+Gather (parallel reads, all bounded):
+
+```bash
+test -f README.md && head -80 README.md
+test -f package.json && head -60 package.json
+test -f pyproject.toml && head -40 pyproject.toml
+test -f Cargo.toml && head -30 Cargo.toml
+test -f go.mod && head -20 go.mod
+test -f .env.example && head -30 .env.example
+git log --oneline -15 2>/dev/null
+git remote -v 2>/dev/null | head -2
+find . -maxdepth 3 -type d ! -path "./node_modules*" ! -path "./.git*" ! -path "./.rcode*" ! -path "./.claude*" ! -path "./.planning*" 2>/dev/null | head -20
+```
+
+Write `.rcode/JOURNEY.md` following this template (don't over-interpret — just record what's seen).
+
+**Naming note (do NOT remove from the template):** the file is `JOURNEY.md`, not `RIHAL.md`. This is intentional — same Arabic root, different word. **rcode (رحّال)** = the traveler/tool. **Rihla (رحلة)** = the journey/voyage. The product is *rcode* (the tool you use); the per-project artifact is *Rihla* (your project's journey). The HTML comment in the template below preserves this reminder for anyone who later wonders if it's a typo.
+
+```markdown
+<!-- JOURNEY — your project's path. Renamed from RIHLA (رحلة, "the journey") in v4.1 for plain-English clarity. -->
+# JOURNEY — Project journey baseline
+
+**Written by:** /rcode-init
+**Date:** {ISO date}
+**Project:** {project_name}
+**Detected state:** {fresh | existing-new-rcode | returning}
+
+## At a glance
+
+- **Primary language:** {detected from files: JS/TS/Python/Go/Rust/etc or "none yet"}
+- **Framework signals:** {Next.js / Django / Express / etc, if obvious from package.json}
+- **Git history:** {N commits, first: YYYY-MM-DD, last: YYYY-MM-DD} or "not a git repo"
+- **Top-level dirs:** {list of ~8 most relevant}
+
+## What's here
+
+{80-line README excerpt, or "no README" if absent}
+
+## Dependencies (from package manifest)
+
+{top 15 dependencies with one-line context — NOT all of them}
+
+## Recent work (last 10 commits)
+
+{git log oneline, or "no commits yet"}
+
+## Not scanned
+
+This file is a journey baseline — intentionally shallow. For deep analysis run:
+- `/rcode-map-codebase` — structured codebase documents per focus area
+- `/rcode-scan` — rapid codebase assessment
+- `/rcode-explore` — socratic ideation against the codebase
+```
+
+If no code detected, write a minimal JOURNEY.md with just the header and a "fresh project — no code yet" note.
+
+## Step 4b — Populate context files
+
+After writing JOURNEY.md, populate the two context files that every rcode skill reads at runtime. These files are the project's "memory bank" — without them, agents work blind.
+
+**`.rcode/context/active.md`** — Current task context and working state. Write it using the JOURNEY.md scan data from Step 4:
+
+```markdown
+# Active Context
+
+**Last updated:** {ISO date}
+**Updated by:** /rcode-init
+
+## Current State
+
+- **Project:** {project_name}
+- **Primary stack:** {detected language + framework}
+- **Branch:** {git branch or "n/a"}
+- **Recent focus:** {summary from last 5 commit messages, or "fresh project"}
+
+## Active Work
+
+{If returning with --reset: summarize what was in progress from git log}
+{If existing-new-rcode: "rcode just configured — no active work tracked yet."}
+{If fresh: "New project — no code yet."}
+
+## Key Decisions
+
+- rcode configured with mode: {mode from Step 2}
+- Branching strategy: {strategy from Step 2}
+- Model profile: {profile from Step 2}
+
+## Open Questions
+
+_None yet. Use `/rcode-explore` or `/rcode-council` to surface questions._
+```
+
+**`.rcode/context/project-brief.md`** — High-level project description. Write it using the JOURNEY.md scan data:
+
+```markdown
+# Project Brief
+
+**Project:** {project_name}
+**Created:** {ISO date}
+
+## Overview
+
+{If code exists: 3-5 sentence summary derived from README + package manifest — what the project does, who it's for, and the primary tech stack}
+{If fresh: "Project not yet started. Run `/rcode-new-project` to design it."}
+
+## Technical Stack
+
+- **Language:** {detected primary language}
+- **Framework:** {detected framework or "none detected"}
+- **Package manager:** {npm/pnpm/pip/cargo/etc or "none detected"}
+
+## Project Goals
+
+_To be refined. Run `/rcode-create-prd` for full requirements discovery._
+```
+
+Ensure the directory exists before writing:
+
+```bash
+mkdir -p .rcode/context
+```
+
+**Important:** If `--reset` is passed and the files already have user-written content beyond the template stub, preserve a backup before overwriting:
+
+```bash
+if [ -s .rcode/context/active.md ] && ! grep -q "Run \`/rcode" .rcode/context/active.md; then
+  cp .rcode/context/active.md .rcode/context/active.md.bak
+fi
+```
+
+After writing both files, refresh the memory bank fingerprint so staleness checks see the project as fresh:
+
+```bash
+node .rcode/bin/rcode-tools.cjs context refresh >/dev/null 2>&1 || true
+```
+
+## Step 5 — Suggest the next step
+
+Print a contextual recommendation, **one line of copy-paste per suggestion** (per `.rcode/references/command-redirect-format.md`):
+
+**If `fresh`:**
+```
+✓ rcode configured. Your journey begins.
+
+Ready to design a new project? Try:
+
+/rcode-new-project {your-project-name}
+
+Or think through an idea first:
+
+/rcode-explore what should I build?
+```
+
+**If `existing-new-rcode`:**
+```
+✓ rcode configured. JOURNEY.md written as your baseline.
+
+Recommended first move — understand before changing:
+
+/rcode-scan
+
+Or strategic question about the codebase:
+
+/rcode-council {your question}
+```
+
+**If `returning` with `--reset`:**
+```
+✓ rcode reconfigured. Prior state preserved in state.json.
+
+Pick up where you left off:
+
+/rcode-resume-work
+```
+
+## Step 6 — Update state
+
+```bash
+node .rcode/bin/rcode-tools.cjs state record-session 2>/dev/null || true
+```
+
+Silent if state tools fail.
+
+## Success Criteria
+
+- [ ] `.rcode/config.yaml` written with user's answers
+- [ ] `.rcode/state.json` exists (created or preserved)
+- [ ] `.rcode/JOURNEY.md` written (unless `--skip-scan` or no code)
+- [ ] `.rcode/context/active.md` populated with project state (not the placeholder stub)
+- [ ] `.rcode/context/project-brief.md` populated with project overview (not the placeholder stub)
+- [ ] State detected correctly (fresh / existing-new-rcode / returning)
+- [ ] Contextual next-step suggestion printed as single-line copy-paste
+
+## On Error
+
+- **AskUserQuestion unavailable:** fall back to reading defaults from env / existing config and skip the interactive step.
+- **config.yaml write fails:** print permission error and stop.
+- **git not installed:** skip git detection, still proceed.
+- **rcode-tools.cjs not found:** this command requires the installer to have run — point user to `npx @hanzlaa/rcode install`.
+- **Existing JOURNEY.md without `--reset`:** do NOT overwrite; note it in Step 4 output.
+
+## Next Up
+
+- `/rcode-new-project` — start a brand-new project after initialization
+- `/rcode-status` — check state of an existing project after re-init

package/rcode/workflows/insert-phase.md

@@ -0,0 +1,122 @@
+# Workflow: rcode-insert-phase
+
+<purpose>
+Insert a decimal phase for urgent work discovered mid-milestone between existing integer phases. Uses decimal numbering (2.1, 2.2, etc.) to preserve the logical sequence of planned phases while accommodating urgent insertions without renumbering subsequent phases. Maintains phase array in `.rcode/state.json` in sort order.
+</purpose>
+
+## Step 0 — Usage check
+
+If `$ARGUMENTS` is empty or contains only `--help` or `-h`:
+- Print the usage block below
+- STOP — do not proceed to Step 0.5
+
+**Usage:**
+```
+/rcode-insert-phase <N.M> <name>
+```
+
+**Examples:**
+```
+/rcode-insert-phase 2.1 urgent-fix
+/rcode-insert-phase 3.2 critical-security-patch
+/rcode-insert-phase 1.1 blocking-issue
+```
+
+Only after the user provides arguments, proceed to Step 0.5.
+
+## Step 0.5 — Validate N.M format
+
+Parse the first argument as `N.M` (integer.decimal format).
+
+Validate using regex: `^\d+\.\d+$`
+
+If validation fails:
+```
+ERROR: Phase number must be in N.M format (e.g., 2.1, 3.2)
+Usage: /rcode-insert-phase <N.M> <name>
+```
+
+Exit.
+
+Extract `N` (integer part) and `M` (decimal part) for later use.
+
+## Step 1 — Call rcode-tools
+
+Invoke the state subcommand to insert the phase:
+
+```bash
+RESULT=$(node .rcode/bin/rcode-tools.cjs state insert-phase --number <N.M> --name <name>)
+```
+
+Parse the JSON response for:
+- `ok` — success flag
+- `phase_number` — the inserted phase number (should match N.M)
+- `name` — phase name
+- `slug` — lowercase-hyphenated slug generated from name
+- `directory` — absolute path to created directory (`.planning/phases/<N.M>-<slug>/`)
+
+If `ok` is false, print error message and exit.
+
+## Step 2 — Create phase directory
+
+Ensure the phase directory exists:
+
+```bash
+mkdir -p "<directory_from_result>"
+```
+
+If directory creation fails, print error and exit.
+
+## Step 3 — Print confirmation
+
+Present completion summary:
+
+```
+✓ Phase {phase_number} inserted: {name}
+  Directory: .planning/phases/{phase_number}-{slug}/
+  Status: Ready for planning
+
+Next steps:
+  /rcode-discuss-phase {phase_number}   — gather context
+  /rcode-plan {phase_number}            — create detailed plan
+
+Or continue with current work and return to this phase later.
+```
+
+## Anti-patterns
+
+- Don't insert before Phase 1 (decimal 0.1 makes no sense)
+- Don't renumber existing phases
+- Don't create plans yet (that's `/rcode-plan`)
+- Don't commit changes (user decides when to commit)
+- Don't duplicate phase numbers (state insert-phase prevents this)
+
+## Success criteria
+
+Phase insertion is complete when:
+
+- [ ] `rcode-tools.cjs state insert-phase` executed successfully
+- [ ] Phase directory created at `.planning/phases/<N.M>-<slug>/`
+- [ ] Phase array in state.json updated with new entry in sort order
+- [ ] User informed of next steps
+
+## Success Criteria
+
+- [ ] `rcode-tools.cjs state insert-phase` exits 0 and returns a valid JSON result (with `slug` and `directory` fields)
+- [ ] Phase directory created at `.planning/phases/<N.M>-<slug>/`
+- [ ] New phase entry inserted into `.rcode/state.json` phases array in numeric sort order
+- [ ] No existing integer phase numbers displaced or renumbered
+- [ ] User shown next-step commands (`/rcode-plan <N.M>`) and the created directory path
+
+## 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
+
+
+## Next Up
+
+- `/rcode-discuss-phase` — discuss the inserted phase before planning
+- `/rcode-plan` — plan the inserted phase immediately

package/rcode/workflows/install.md

@@ -0,0 +1,82 @@
+# Workflow: rcode-install
+
+<purpose>
+Install a rcode module into the current project. Modules are capability bundles (agents + workflows + commands + references). This workflow validates the module exists, checks dependencies, runs the installer, and updates the manifest.
+</purpose>
+
+## Step 0 — Validate module name
+
+```bash
+MODULES=$(node .rcode/bin/rcode-tools.cjs module list)
+```
+
+Parse JSON. If the requested module is not in the available list, print:
+```
+Unknown module: {name}
+Available modules: core, execution
+```
+And stop.
+
+## Step 1 — Check if already installed
+
+```bash
+INSTALLED=$(node .rcode/bin/rcode-tools.cjs module installed)
+```
+
+If the requested module is already in the installed list:
+```
+Module '{name}' is already installed.
+```
+And stop.
+
+## Step 2 — Check dependencies
+
+```bash
+CHECK=$(node .rcode/bin/rcode-tools.cjs module check-requires {name})
+```
+
+If `ok` is false:
+```
+Module '{name}' requires '{missing_module}' to be installed first.
+Run: /rcode-install {missing_module}
+```
+And stop.
+
+## Step 3 — Run installer
+
+The installer needs to be called with the `--module` flag. Detect the rcode package location:
+
+```bash
+npx @hanzlaa/rcode install --module {name} --force --yes
+```
+
+## Step 4 — Print summary
+
+```
+✓ Module installed: {name}
+   {description from module manifest}
+
+New commands available:
+  /rcode-{command} — {description}
+```
+
+## Success Criteria
+
+- [ ] Module name is validated against available modules
+- [ ] Module is not already installed
+- [ ] Dependencies are checked and satisfied
+- [ ] Installer runs without errors
+- [ ] User sees confirmation with new commands available
+
+## On Error
+
+- **Unknown module:** list available modules.
+- **Already installed:** inform user, no-op.
+- **Missing dependencies:** list missing modules, tell user to install them first.
+- **Installer not found:** tell user to install rcode package.
+- **Installation fails:** report the specific error and suggest manual installation steps
+
+## Next Up
+
+- `/rcode-health` — verify the installed module is working
+- `/rcode-do` — use newly available commands from the installed module