npm - @hanzlaa/rcode - Versions diffs - 3.6.16 → 4.1.0 - Mend

@hanzlaa/rcode 3.6.16 → 4.1.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 (1493) hide show

package/rihal/workflows/scaffold-milestone.md DELETED Viewed

@@ -1,60 +0,0 @@
-<purpose>
-Bulk-create all phase directories for a milestone from a pipe-separated name list or from ROADMAP.md planned phases. Closes #731.
-</purpose>
-<process>
-## 1. Parse arguments
-If `--names` is provided in `$ARGUMENTS`:
-```bash
-node ".rihal/bin/rihal-tools.cjs" phase scaffold-milestone --names "${NAMES_ARG}" ${START_ARG:+--start $START_ARG}
-```
-Print the result JSON and exit.
-## 2. Auto-detect from ROADMAP.md (when no --names)
-Read `.planning/ROADMAP.md`. Extract all phase entries that:
-- Have a `**Status:** Planned` line
-- Do NOT have a corresponding directory under `.planning/phases/`
-Collect their names in order. Build a pipe-separated list and pass to scaffold-milestone:
-```bash
-PLANNED_NAMES="Phase A|Phase B|Phase C"
-node ".rihal/bin/rihal-tools.cjs" phase scaffold-milestone --names "${PLANNED_NAMES}"
-```
-## 3. Report
-Print a summary:
-```
-✓ Scaffolded {N} phase directories:
-  {number}-{slug}/
-  {number}-{slug}/
-  ...
-Next step: /rihal-plan {first_number}
-```
-</process>
-## Output Format
-One line per created phase directory. Final "Next step" routing.
-## Examples
-**With names:** `/rihal-scaffold-milestone --names "Auth System|Dashboard|API Layer"` → creates 3 phase dirs.
-**Auto-detect:** `/rihal-scaffold-milestone` → reads ROADMAP.md, creates dirs for all Planned phases without existing directories.
-## Success Criteria
-- [ ] Phase directories created under `.planning/phases/`
-- [ ] Summary printed with one line per created directory
-- [ ] Next-step routing printed

package/rihal/workflows/scaffold-project.md DELETED Viewed

@@ -1,31 +0,0 @@
-# Workflow: rihal-scaffold-project
-<purpose>
-Scaffold a new project from the official Rihal template repo. Delegates to the rihal-scaffold-project skill.
-</purpose>
-## Execution
-Locate and follow the installed skill:
-```bash
-find .rihal/skills/actions -path "*rihal-scaffold-project/workflow.md" 2>/dev/null | head -1
-```
-Read and follow the workflow at that path. If the path is empty:
-```
-Skill not installed — run: npx @hanzlaa/rcode install
-```
-## On Completion
-/rihal-init — configure Rihal for the scaffolded project
-/rihal-new-project {name} — design the project with full facilitation
-/rihal-create-prd — write the product requirements document
-## ▶ Next Up
-- /rihal-create-prd
-- /rihal-new-milestone
-- /rihal-do

package/rihal/workflows/scaffold-skill.md DELETED Viewed

@@ -1,137 +0,0 @@
-# Workflow: rihal-scaffold-skill
-<purpose>
-Create a new compliant SKILL.md file for a Rihal role in one command. Eliminates the friction of finding a folder, reading an existing skill, copying it, renaming, and chasing the 5-component compliance check.
-Output: a SKILL.md that already passes `test/compliance.test.cjs` and is ready to be filled in.
-</purpose>
-## Step 0 — Parse Arguments
-Expected forms:
-```
-/rihal-scaffold-skill --role <role> --name <skill-name>
-/rihal-scaffold-skill --role pm --name sharper-prd-discovery
-/rihal-scaffold-skill --help
-```
-Required: `--role` (one of: `pm`, `qa`, `architect`, `frontend`, `backend`, `marketing`, `designer`, `writer`, `engineer`, `ml`, `branding`, `eng-manager`, `analyst`, `director`, `scout`).
-Required: `--name` — kebab-case identifier. Validate it matches `^[a-z][a-z0-9-]+$`.
-Optional: `--dry-run` — print the file content to stdout instead of writing.
-If `$ARGUMENTS` is `--help` or empty, print usage and STOP.
-## Step 1 — Resolve target path
-Map `--role` to a directory under `rihal/skills/actions/`. Group by role family:
-| Role flag | Target directory |
-|-----------|------------------|
-| `pm` | `rihal/skills/actions/1-discovery/rihal-<name>/` |
-| `architect` | `rihal/skills/actions/2-planning/rihal-<name>/` |
-| `engineer`, `frontend`, `backend`, `ml` | `rihal/skills/actions/4-implementation/rihal-<name>/` |
-| `qa` | `rihal/skills/actions/5-verification/rihal-<name>/` |
-| `designer`, `branding` | `rihal/skills/actions/3-design/rihal-<name>/` |
-| `marketing`, `writer`, `eng-manager`, `analyst`, `director`, `scout` | `rihal/skills/actions/6-other/rihal-<name>/` |
-If the directory already exists, abort with: `Skill rihal-<name> already exists at <path>. Pick a different --name or delete the existing directory first.`
-## Step 2 — Write the template
-Write `rihal/skills/actions/<group>/rihal-<name>/SKILL.md` with this content (substitute `<NAME>`, `<ROLE>`, `<DESCRIPTION_FILLER>`):
-```yaml
----
-name: rihal-<NAME>
-description: >
-  <One-line summary of what this skill does. Activates when the user says
-  "<trigger phrase>", "<another phrase>". Do NOT use for: <negative
-  boundaries>.>
-triggers:
-  - "<trigger phrase 1>"
-  - "<trigger phrase 2>"
-  - "<trigger phrase 3>"
-  - "<trigger phrase 4>"
-  - "<trigger phrase 5>"
----
-# <NAME> — <ROLE>
-## Overview
-<2-3 sentences explaining what the skill does and when it's invoked. What
-real-world problem does it solve? What does the user get back when they
-invoke it?>
-## Workflow
-<Step-by-step instructions the model follows. Use numbered steps. Each step
-should be specific enough that two different models converge to similar
-output. Reference rihal-tools subcommands where state changes are needed.>
-1. <First step>
-2. <Second step>
-3. <Third step>
-## Output Format
-<Exact shape of the output. If markdown, include the headers. If JSON, the
-schema. The compliance check expects this section verbatim — keep the
-heading text as "## Output Format".>
-## Examples
-### Happy path
-<Input → output example showing the skill at its best>
-### Edge case
-<Input → output for a tricky variant (missing data, ambiguous request, etc.)>
-### Negative
-<Input that should NOT trigger this skill — show the redirect>
-```
-## Step 3 — Verify compliance
-Run the 5-component check on the new file:
-```bash
-F="rihal/skills/actions/<group>/rihal-<name>/SKILL.md"
-fails=""
-grep -q "^triggers:" "$F" || fails="$fails triggers-frontmatter"
-grep -q "^## Overview"      "$F" || fails="$fails overview"
-grep -q "^## Workflow"      "$F" || fails="$fails workflow"
-grep -q "^## Output Format" "$F" || fails="$fails output-format"
-grep -q "^## Examples"      "$F" || fails="$fails examples"
-if [ -n "$fails" ]; then
-  echo "✖ Scaffolded skill missing components:$fails"
-  echo "  This is a bug in the scaffolder template — file an issue."
-  exit 1
-fi
-```
-## Step 4 — Confirm and Next Up
-Print:
-```
-✓ Skill scaffolded: rihal-<NAME>
-  Location: rihal/skills/actions/<group>/rihal-<NAME>/SKILL.md
-  All 5 required components are present (triggers, Overview, Workflow,
-  Output Format, Examples). The placeholders need real content before
-  the skill becomes useful.
-▶ Next Up
-  $EDITOR rihal/skills/actions/<group>/rihal-<NAME>/SKILL.md
-                                                  # fill in placeholders
-  npx @hanzlaa/rcode install --force              # install to .claude/skills/
-  node --test test/compliance.test.cjs            # verify compliance
-```

package/rihal/workflows/scan.md DELETED Viewed

@@ -1,382 +0,0 @@
-<purpose>
-Lightweight codebase assessment. Spawns a single rihal-codebase-mapper agent for one focus area,
-producing targeted documents in `.planning/codebase/`.
-</purpose>
-<required_reading>
-Read all files referenced by the invoking prompt's execution_context before starting.
-</required_reading>
-<available_agent_types>
-Valid Rihal subagent types (use exact names — do not fall back to 'general-purpose'):
-- rihal-codebase-mapper — Maps project structure and dependencies
-</available_agent_types>
-## Step 0 — Usage check
-If `$ARGUMENTS` is empty or contains only `--help` or `-h`:
-- Print the usage block below
-- STOP — do not proceed
-**Usage:**
-```
-/rihal-scan [--focus tech|arch|quality|concerns|tech+arch] [--refresh] [--reset]
-```
-**Examples:**
-```
-/rihal-scan --focus tech
-/rihal-scan --focus arch
-/rihal-scan --focus tech+arch
-/rihal-scan --refresh                 # auto-update stale docs, brief diff, log to CHANGELOG.md
-/rihal-scan --reset --focus tech+arch # silent overwrite (CI / autonomous)
-```
-**Refresh flag — memory-bank pattern.** When `--refresh` is passed AND existing docs are present, the orchestrator:
-1. Captures a *pre-state snapshot* (top-level dirs, manifests, dep counts, file counts, git HEAD).
-2. Reads the oldest existing target doc's mtime — anchor for "changes since last scan".
-3. Runs git log + dir diff + manifest diff against that anchor.
-4. Spawns Dalil with the diff context, instructs him to overwrite docs AND prepend a "Changes since last scan" section to each.
-5. Appends a structured entry to `.planning/codebase/CHANGELOG.md` with the brief.
-This is the canonical way to keep the memory bank fresh without losing the audit trail of what changed and why.
-<process>
-## Focus-to-Document Mapping
-| Focus | Documents Produced |
-|-------|-------------------|
-| `tech` | STACK.md, INTEGRATIONS.md |
-| `arch` | ARCHITECTURE.md, STRUCTURE.md |
-| `quality` | CONVENTIONS.md, TESTING.md |
-| `concerns` | CONCERNS.md |
-| `tech+arch` | STACK.md, INTEGRATIONS.md, ARCHITECTURE.md, STRUCTURE.md |
-## Step 1: Parse arguments and resolve focus
-Parse the user's input for `--focus <area>`. Default to `tech+arch` if not specified.
-Validate that the focus is one of: `tech`, `arch`, `quality`, `concerns`, `tech+arch`.
-Also parse:
-- `--refresh` → auto-update mode (briefs the user on what changed, then overwrites)
-- `--reset` → silent overwrite (no prompt, no brief — for CI / autonomous chains)
-If invalid focus:
-```
-Unknown focus area: "{input}". Valid options: tech, arch, quality, concerns, tech+arch
-```
-Exit.
-## Step 2: Check for existing documents
-```bash
-INIT=$(node "$PROJECT_ROOT/.rihal/bin/rihal-tools.cjs" init scan 2>/dev/null || echo "{}")
-if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
-```
-Extract `response_language` from INIT JSON. If set, include `Respond in {response_language}.` in all spawned subagent prompts.
-Look up which documents would be produced for the selected focus (from the mapping table above).
-For each target document, check if it already exists in `.planning/codebase/`:
-```bash
-ls -la .planning/codebase/{DOCUMENT}.md 2>/dev/null
-```
-**Three modes:**
-### 2a — Refresh mode (`--refresh` flag)
-Skip the [y/N] prompt. Instead, run the diff analysis in Step 2c and proceed to dispatch with refresh context.
-### 2b — Reset mode (`--reset` flag)
-Silent overwrite. No prompt, no brief, no CHANGELOG entry. Use only for CI or chained autonomous workflows.
-### 2c — Default mode (no flag)
-If any target doc exists, show their mod dates AND age in days, AND a one-line activity hint, then ask:
-```bash
-# For each existing doc, compute relative age:
-for DOC in {document_list}; do
-  if [ -f ".planning/codebase/$DOC" ]; then
-    MTIME=$(stat -c %Y ".planning/codebase/$DOC" 2>/dev/null || stat -f %m ".planning/codebase/$DOC" 2>/dev/null)
-    NOW=$(date +%s)
-    AGE_DAYS=$(( (NOW - MTIME) / 86400 ))
-    COMMITS_SINCE=$(git log --oneline --since="@$MTIME" 2>/dev/null | wc -l | tr -d ' ')
-    echo "  - $DOC ({date}, ${AGE_DAYS}d ago, ${COMMITS_SINCE} commits since)"
-  fi
-done
-```
-```
-Existing documents found:
-  - STACK.md         (2026-03-22, 35d ago, 14 commits since)
-  - INTEGRATIONS.md  (2026-03-22, 35d ago, 14 commits since)
-These docs are stale. Three options:
-  [Y]   Refresh — analyze what changed, briefly explain, then overwrite + log to CHANGELOG.md
-  [o]   Overwrite blind — skip the diff brief, just rebuild
-  [n]   Keep as-is, exit
-```
-Map the answer:
-- `Y` / `y` / empty → set internal mode to **refresh**, continue to Step 2d
-- `o` → set mode to **reset**, continue to Step 4
-- `n` / `no` → exit
-## Step 2d — Pre-state capture (refresh mode only)
-Before dispatching Dalil, capture a structured snapshot for diff comparison. Fire each command and save the output verbatim — it goes into the dispatch prompt and the CHANGELOG entry.
-```bash
-# Anchor mtime — oldest existing target doc
-ANCHOR_TS=$(for DOC in {document_list}; do
-  [ -f ".planning/codebase/$DOC" ] && stat -c %Y ".planning/codebase/$DOC" 2>/dev/null || stat -f %m ".planning/codebase/$DOC" 2>/dev/null
-done | sort -n | head -1)
-ANCHOR_DATE=$(date -d "@$ANCHOR_TS" -u +%Y-%m-%d 2>/dev/null || date -r "$ANCHOR_TS" -u +%Y-%m-%d 2>/dev/null)
-# Commits since anchor
-echo "=== COMMITS SINCE $ANCHOR_DATE ==="
-git log --oneline --since="@$ANCHOR_TS" 2>/dev/null | head -50
-# Top-level dir set
-echo "=== TOP-LEVEL DIRS ==="
-find . -maxdepth 1 -type d -not -name '.git' -not -name 'node_modules' -not -name '.next' -not -name 'dist' -not -name '.venv' -not -name '__pycache__' | sort
-# Manifest hashes (changed if deps shifted)
-echo "=== MANIFEST HASHES ==="
-for M in package.json pnpm-lock.yaml pyproject.toml requirements.txt Cargo.toml go.mod; do
-  [ -f "$M" ] && echo "$M  $(sha256sum "$M" 2>/dev/null | awk '{print $1}' || shasum -a 256 "$M" | awk '{print $1}')"
-done
-# Source file count by language
-echo "=== SOURCE FILE COUNTS ==="
-for EXT in py ts tsx js jsx go rs rb; do
-  COUNT=$(find . -name "*.$EXT" -not -path '*/node_modules/*' -not -path '*/.venv/*' -not -path '*/dist/*' 2>/dev/null | wc -l | tr -d ' ')
-  [ "$COUNT" -gt 0 ] && echo "*.$EXT  $COUNT"
-done
-```
-Store this entire output as `$PRE_STATE` for the dispatch prompt.
-## Step 3: Create output directory
-```bash
-mkdir -p .planning/codebase
-```
-## Step 4: Announce dispatch (persona-driven)
-Use the canonical dispatch-banner spec at `.rihal/references/dispatch-banner.md`. Read it now if you have not already — it defines the persona-driven first-person hand-off pattern.
-For this workflow, the dispatched agent is `rihal-codebase-mapper` → persona **Dalil (دليل) — Codebase Scout** 🧭.
-Print the DISPATCH banner per the spec. Filled-in template for this workflow:
-```
-╭─────────────────────────────────────────────────────────╮
-│  🧭  Dalil (دليل) — Codebase Scout                       │
-╰─────────────────────────────────────────────────────────╯
-السلام عليكم — I'm Dalil, your codebase scout.
-I'll map this repo for you with focus: {focus}{ — topic: "{topic}" if topic else ""}.
-Before I start I'll discover every source root (not just `src/`),
-detect the language mix from manifests, and — if you gave me a
-topic phrase — sweep for it across all roots before narrowing.
-Scope:
-  • Focus: {focus}
-  • Topic phrase: {topic-keyword or "none — broad scan"}
-  • Read-only: I never edit code.
-Output:
-  → .planning/codebase/{document_list}
-Working now — I'll come back with a Scan Scope declaration
-so you see exactly what I covered (and what I skipped).
-```
-Always first-person. Always include the deliverable path. If a topic phrase isn't provided, drop the topic-related lines rather than printing "none".
-## Step 5: Spawn mapper agent
-Spawn a single `rihal-codebase-mapper` agent. Pass the persona instructions in the prompt so the agent's own response opens in-character.
-**Base prompt (always sent):**
-```
-Task(
-  prompt="You are spawned as **Dalil (دليل) — Codebase Scout**. Open your response with a one-line in-character continuity beat (e.g. 'Dalil here — starting the scan.') and sign your closing summary with your persona name. Use first-person.
-  Scan this codebase with focus: {focus}.
-  Topic phrase (literal search target, may be empty): {topic-keyword}
-  Write results to .planning/codebase/. Produce only: {document_list}.
-  REQUIRED — every document must open with a 'Scan Scope' section per `.rihal/agents-rules/codebase-mapper/detailed-guide.md` that declares:
-  - Source roots discovered (top-level non-vendored directories)
-  - Source roots searched (grep/glob targets)
-  - Source roots NOT searched and why
-  - Languages detected (from package manifests)
-  - If a topic phrase was provided: a literal `grep -rl '<phrase>' <discovered-roots>` run across ALL source roots, with the file count and an excerpt of matches
-  This scope section is non-negotiable — the orchestrator will reject documents missing it.",
-  subagent_type="rihal-codebase-mapper",
-  model="{model}",
-  model="{resolved_model}"
-)
-```
-**Refresh-mode addendum (append to the prompt above when mode === "refresh"):**
-```
-  REFRESH MODE — this is NOT a first scan. Existing docs are present and stale.
-  Anchor date (last scan): {ANCHOR_DATE}
-  Pre-state snapshot (verbatim from orchestrator):
-  {PRE_STATE}
-  Additional requirements for refresh runs:
-  1. After the Scan Scope section in EACH document, insert a section titled
-     '## Changes since last scan ({ANCHOR_DATE} → today)' that lists, in bullets:
-     - new files / removed files relevant to this doc's focus
-     - new dependencies / removed dependencies (for STACK.md / INTEGRATIONS.md)
-     - new modules / removed modules (for ARCHITECTURE.md / STRUCTURE.md)
-     - new TODO/FIXME or eliminated ones (for CONCERNS.md)
-     - 3-7 most-important commit subjects from the pre-state COMMITS list
-       that materially shaped the current state
-  2. The body of each document must reflect CURRENT state — not a diff. The
-     'Changes since last scan' section is the ONLY place where pre-state and
-     diff narrative belongs.
-  3. Include a final line in your return summary:
-     'Brief: {one-paragraph plain-English summary of the most important changes
-     since last scan, suitable for posting to CHANGELOG.md}'
-     The orchestrator extracts this verbatim.
-```
-When refresh mode is active, also include `topic_keyword` (if any) and the resolved focus in the prompt as before.
-## Step 6: Announce return (persona-driven)
-When the agent returns, print the RETURNED banner per `.rihal/references/dispatch-banner.md`. Filled-in template:
-```
-╭─────────────────────────────────────────────────────────╮
-│  ✓  Dalil — back from scout                              │
-╰─────────────────────────────────────────────────────────╯
-Done — here's what I covered for you.
-Covered:
-  • Searched: {roots actually iterated}
-  • Languages: {detected language mix}
-  • Topic sweep: {file count + sample paths, or "n/a"}
-Skipped / blind spots:
-  • {explicit list — never leave empty without justification}
-Wrote:
-  → .planning/codebase/{doc} ({N} lines)
-{Optional: 1-2 follow-up questions Dalil surfaces in his own voice,
- e.g. "I noticed X — want me to dig deeper?"}
-I'm still here if you want to follow up on what I found,
-until the next dispatch. — Dalil
-```
-If the document is missing its Scan Scope section, do NOT print the success banner. Instead print:
-```
-⚠  Dalil returned without a Scan Scope declaration.
-    Treating this run as incomplete — re-spawn with stricter instructions?
-```
-## Follow-up framing
-Until the next `Task()` dispatch, answer follow-up questions about the scan AS Dalil — first-person, sign with `— Dalil`. If the user asks something outside Dalil's scope (e.g. strategy, planning, code editing), hand off explicitly per the dispatch-banner spec and print a fresh DISPATCH banner for the new persona.
-## Step 6.5: Append to CHANGELOG.md (refresh mode only)
-When mode === "refresh", extract Dalil's `Brief:` line from his RETURNED summary and append a structured entry to `.planning/codebase/CHANGELOG.md`. Create the file if missing. Use the Read tool first if updating, then Edit/Write — never blind-overwrite a file with prior entries.
-**Entry format:**
-```markdown
-## {today's ISO date} — refresh
-**Anchor:** {ANCHOR_DATE} ({age in days} days ago)
-**Focus:** {focus}
-**Commits since anchor:** {count}
-**Docs touched:** {comma-separated list}
-{Dalil's Brief: line, verbatim, formatted as a paragraph}
-**Top-level signals:**
-- Source roots: {comma-separated list of dirs from PRE_STATE}
-- Languages: {detected mix}
-- Manifest changes: {hash diff summary, e.g. "package.json: changed", "pyproject.toml: unchanged"}
----
-```
-Insert at the TOP of the file body (newest-first), under any pre-existing `# Changelog — Codebase Memory Bank` H1. If the file doesn't exist, write it with this header:
-```markdown
-# Changelog — Codebase Memory Bank
-This file tracks structural changes between scans. Each entry is auto-written by `/rihal-scan --refresh`. Newest entries first.
----
-{first entry here}
-```
-This file is **read by future `/rihal-scan --refresh` runs** as additional anchor context — the memory bank is self-improving across scans.
-## Step 7: Final cue (orchestrator-level, after RETURNED banner)
-The RETURNED banner above is Dalil's voice. After it, the orchestrator may add ONE neutral cue line if the user might want a deeper scan:
-```
-Tip: `/rihal-map-codebase` runs a 4-area parallel scan if you want broader coverage.
-```
-Skip this cue if the user already asked for a focused scan — don't push an upsell.
-</process>
-<success_criteria>
-- [ ] Focus area correctly parsed (default: tech+arch)
-- [ ] Existing documents detected with modification dates shown
-- [ ] User prompted before overwriting
-- [ ] Single mapper agent spawned with correct focus
-- [ ] Output documents written to .planning/codebase/
-</success_criteria>
-## Success Criteria
-- [ ] Task completed as requested
-- [ ] Output saved or reported
-- [ ] State updated if necessary
-- [ ] No errors encountered
-## 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
-/rihal-council {your question} — strategic question about what was found
-/rihal-plan {N} — plan fixes for discovered issues
-/rihal-explore — go deeper with socratic analysis
-/rihal-next — get suggested next action