@hanzlaa/rcode 3.6.16 → 4.1.0

package/rcode/skills/core/rcode-review-adversarial-general/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: rcode-review-adversarial-general
+description: "Perform a Cynical Review and produce a findings report."
+triggers:
+  - "review adversarial general"
+---
+@.rcode/references/karpathy-guidelines.md
+
+
+# Adversarial Review (General)
+
+**Goal:** Cynically review content and produce findings.
+
+**Your Role:** You are a cynical, jaded reviewer with zero patience for sloppy work. The content was submitted by a clueless weasel and you expect to find problems. Be skeptical of everything. Look for what's missing, not just what's wrong. Use a precise, professional tone — no profanity or personal attacks.
+
+**Inputs:**
+- **content** — Content to review: diff, spec, story, doc, or any artifact
+- **also_consider** (optional) — Areas to keep in mind during review alongside normal adversarial analysis
+
+
+## Overview
+
+Review adversarial general skill for rcode.
+
+## EXECUTION
+
+### Step 1: Receive Content
+
+- Load the content to review from provided input or context
+- If content to review is empty, ask for clarification and abort
+- Identify content type (diff, branch, uncommitted changes, document, etc.)
+
+### Step 2: Adversarial Analysis
+
+Review with extreme skepticism — assume problems exist. Find at least ten issues to fix or improve in the provided content.
+
+### Step 3: Present Findings
+
+Output findings as a Markdown list (descriptions only).
+
+
+## Output Format
+
+Markdown bullet list of findings, each describing a specific problem, gap, or risk.
+
+## Workflow
+
+1. Read the user request and extract key parameters.
+2. Execute the skill logic as described in the Overview.
+3. Return output in the format specified below.
+
+## Examples
+
+### Happy path
+**User:** "critically review this PRD"
+**Result:** 12 findings covering missing error handling, vague acceptance criteria, unaddressed security, scope creep risks
+
+### Edge case
+**User:** "review" + empty content
+**Result:** "No content provided — please share the artifact to review"
+
+### Negative boundary
+**User:** "review this code for edge cases"
+**Result:** Not adversarial → route to `rcode-review-edge-case-hunter`
+
+## HALT CONDITIONS
+
+- HALT if zero findings — this is suspicious, re-analyze or ask for guidance
+- HALT if content is empty or unreadable
+
+## Memory Bank Hooks
+
+- **Reads:** the content under review (diff, spec, story, doc)
+- **Writes:** nothing — produces findings only. Findings can be persisted by the caller via `rcode-memory-update` if they shape downstream work.

package/rcode/skills/core/rcode-review-edge-case-hunter/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: rcode-review-edge-case-hunter
+description: "Walk every branching path and boundary condition in content, report only unhandled edge cases."
+triggers:
+  # English
+  - "find edge cases"
+  - "edge case hunt"
+  - "edge cases in this"
+  - "review edge case hunter"
+  - "corner cases"
+  - "boundary conditions"
+  - "what could break"
+  # Roman Urdu / Hindi
+  - "edge cases dhoondo"
+  - "edge cases nikalo"
+  # Arabic native
+  - "حالات استثنائية"
+  - "حالات حدية"
+  - "ابحث عن الحالات الاستثنائية"
+  - "افحص الحالات الحدية"
+  - "ما قد يفشل"
+---
+@.rcode/references/karpathy-guidelines.md
+
+
+# Edge Case Hunter Review
+
+**Goal:** You are a pure path tracer. Never comment on whether code is good or bad; only list missing handling.
+When a diff is provided, scan only the diff hunks and list boundaries that are directly reachable from the changed lines and lack an explicit guard in the diff.
+When no diff is provided (full file or function), treat the entire provided content as the scope.
+Ignore the rest of the codebase unless the provided content explicitly references external functions.
+
+**Inputs:**
+- **content** — Content to review: diff, full file, or function
+- **also_consider** (optional) — Areas to keep in mind during review alongside normal edge-case analysis
+
+**MANDATORY: Execute steps in the Execution section IN EXACT ORDER. DO NOT skip steps or change the sequence. When a halt condition triggers, follow its specific instruction exactly. Each action within a step is a REQUIRED action to complete that step.**
+
+**Your method is exhaustive path enumeration — mechanically walk every branch, not hunt by intuition. Report ONLY paths and conditions that lack handling — discard handled ones silently. Do NOT editorialize or add filler — findings only.**
+
+
+## Overview
+
+Review edge case hunter skill for rcode.
+
+## EXECUTION
+
+### Step 1: Receive Content
+
+- Load the content to review strictly from provided input
+- If content is empty, or cannot be decoded as text, return `[{"location":"N/A","trigger_condition":"Input empty or undecodable","guard_snippet":"Provide valid content to review","potential_consequence":"Review skipped — no analysis performed"}]` and stop
+- Identify content type (diff, full file, or function) to determine scope rules
+
+### Step 2: Exhaustive Path Analysis
+
+**Walk every branching path and boundary condition within scope — report only unhandled ones.**
+
+- If `also_consider` input was provided, incorporate those areas into the analysis
+- Walk all branching paths: control flow (conditionals, loops, error handlers, early returns) and domain boundaries (where values, states, or conditions transition). Derive the relevant edge classes from the content itself — don't rely on a fixed checklist. Examples: missing else/default, unguarded inputs, off-by-one loops, arithmetic overflow, implicit type coercion, race conditions, timeout gaps
+- For each path: determine whether the content handles it
+- Collect only the unhandled paths as findings — discard handled ones silently
+
+### Step 3: Validate Completeness
+
+- Revisit every edge class from Step 2 — e.g., missing else/default, null/empty inputs, off-by-one loops, arithmetic overflow, implicit type coercion, race conditions, timeout gaps
+- Add any newly found unhandled paths to findings; discard confirmed-handled ones
+
+### Step 4: Present Findings
+
+Output findings as a JSON array following the Output Format specification exactly.
+
+
+## OUTPUT FORMAT
+
+Return ONLY a valid JSON array of objects. Each object must contain exactly these four fields and nothing else:
+
+```json
+[{
+  "location": "file:start-end (or file:line when single line, or file:hunk when exact line unavailable)",
+  "trigger_condition": "one-line description (max 15 words)",
+  "guard_snippet": "minimal code sketch that closes the gap (single-line escaped string, no raw newlines or unescaped quotes)",
+  "potential_consequence": "what could actually go wrong (max 15 words)"
+}]
+```
+
+No extra text, no explanations, no markdown wrapping. An empty array `[]` is valid when no unhandled paths are found.
+
+
+## HALT CONDITIONS
+
+- If content is empty or cannot be decoded as text, return `[{"location":"N/A","trigger_condition":"Input empty or undecodable","guard_snippet":"Provide valid content to review","potential_consequence":"Review skipped — no analysis performed"}]` and stop
+
+## Workflow
+
+1. Read the user request and extract key parameters.
+2. Execute the skill logic as described in the Overview.
+3. Return output in the format specified below.
+
+## Output Format
+
+- Structured Markdown response
+- Headers for each section
+- Concise, actionable content
+
+## Examples
+
+### Happy path
+**User:** "find edge cases in this auth middleware"
+**Result:** JSON array with 8 findings — missing null check on token, no timeout on DB lookup, off-by-one in retry loop, etc.
+
+### Edge case
+**User:** pastes a diff with no branching logic
+**Result:** `[]` — empty array, no unhandled paths found
+
+### Negative boundary
+**User:** "critically review this spec"
+**Result:** Not edge-case hunting → route to `rcode-review-adversarial-general`
+
+## Memory Bank Hooks
+
+- **Reads:** the content under review (diff, full file, or function)
+- **Writes:** nothing — produces an unhandled-edges report only

package/rcode/skills/core/rcode-shard-doc/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: rcode-shard-doc
+description: "Splits large markdown documents into smaller, organized files based on level 2 (default) sections."
+triggers:
+  - "shard doc"
+---
+@.rcode/references/karpathy-guidelines.md
+
+
+# Shard Document
+
+**Goal:** Split large markdown documents into smaller, organized files based on level 2 sections using `npx @kayvan/markdown-tree-parser`.
+
+## Overview
+
+Shard doc skill for rcode.
+
+## CRITICAL RULES
+
+- MANDATORY: Execute ALL steps in the EXECUTION section IN EXACT ORDER
+- DO NOT skip steps or change the sequence
+- HALT immediately when halt-conditions are met
+- Each action within a step is a REQUIRED action to complete that step
+
+## EXECUTION
+
+### Step 1: Get Source Document
+
+- Ask user for the source document path if not provided already
+- Verify file exists and is accessible
+- Verify file is markdown format (.md extension)
+- If file not found or not markdown: HALT with error message
+
+### Step 2: Get Destination Folder
+
+- Determine default destination: same location as source file, folder named after source file without .md extension
+  - Example: `/path/to/architecture.md` --> `/path/to/architecture/`
+- Ask user for the destination folder path (`[y]` to confirm use of default: `[suggested-path]`, else enter a new path)
+- If user accepts default: use the suggested destination path
+- If user provides custom path: use the custom destination path
+- Verify destination folder exists or can be created
+- Check write permissions for destination
+- If permission denied: HALT with error message
+
+### Step 3: Execute Sharding
+
+- Inform user that sharding is beginning
+- Execute command: `npx @kayvan/markdown-tree-parser explode [source-document] [destination-folder]`
+- Capture command output and any errors
+- If command fails: HALT and display error to user
+
+### Step 4: Verify Output
+
+- Check that destination folder contains sharded files
+- Verify index.md was created in destination folder
+- Count the number of files created
+- If no files created: HALT with error message
+
+### Step 5: Report Completion
+
+- Display completion report to user including:
+  - Source document path and name
+  - Destination folder path
+  - Number of section files created
+  - Confirmation that index.md was created
+  - Any tool output or warnings
+- Inform user that sharding completed successfully
+
+### Step 6: Handle Original Document
+
+> **Critical:** Keeping both the original and sharded versions defeats the purpose of sharding and can cause confusion.
+
+Present user with options for the original document:
+
+> What would you like to do with the original document `[source-document-name]`?
+>
+> Options:
+> - `[d]` Delete - Remove the original (recommended - shards can always be recombined)
+> - `[m]` Move to archive - Move original to a backup/archive location
+> - `[k]` Keep - Leave original in place (NOT recommended - defeats sharding purpose)
+> - `[x]` Cancel - Keep original and exit without changing anything
+>
+> Your choice (d/m/k/x):
+
+#### If user selects `x` (cancel)
+
+- Do not delete or move the original document
+- Inform user: "Cancelled. Original document kept at: [source-document-path]. No changes made."
+- End the skill
+
+#### If user selects `d` (delete)
+
+- **Before deleting, confirm with the user:**
+  > About to delete 1 file: `[source-document-path]`. This cannot be undone. Continue?
+  > - `[y]` Yes — delete the original
+  > - `[n]` No — keep the original and exit
+- If user selects `n`: inform user "Cancelled. Original document kept at: [source-document-path]." and end the skill.
+- If user selects `y`: proceed with deletion.
+- Delete the original source document file
+- Confirm deletion to user: "Original document deleted: [source-document-path]"
+- Note: The document can be reconstructed from shards by concatenating all section files in order
+
+#### If user selects `m` (move)
+
+- Determine default archive location: same directory as source, in an `archive` subfolder
+  - Example: `/path/to/architecture.md` --> `/path/to/archive/architecture.md`
+- Ask: Archive location (`[y]` to use default: `[default-archive-path]`, or provide custom path)
+- If user accepts default: use default archive path
+- If user provides custom path: use custom archive path
+- Create archive directory if it does not exist
+- Move original document to archive location
+- Confirm move to user: "Original document moved to: [archive-path]"
+
+#### If user selects `k` (keep)
+
+- Display warning to user:
+  - Keeping both original and sharded versions is NOT recommended
+  - The discover_inputs protocol may load the wrong version
+  - Updates to one will not reflect in the other
+  - Duplicate content taking up space
+  - Consider deleting or archiving the original document
+- Confirm user choice: "Original document kept at: [source-document-path]"
+
+## Workflow
+
+1. Read the user request and extract key parameters.
+2. Execute the skill logic as described in the Overview.
+3. Return output in the format specified below.
+
+## Output Format
+
+- Structured Markdown response
+- Headers for each section
+- Concise, actionable content
+
+## Examples
+
+### Happy path
+**User:** "shard document ./docs/architecture.md"
+**Result:** Splits into `architecture/` folder with section files + index.md → asks what to do with original
+
+### Edge case
+**User:** "shard document" + non-markdown file
+**Result:** HALT — file must be .md format
+
+### Negative boundary
+**User:** "split this into smaller components"
+**Result:** If referring to code, not a doc sharding task. If referring to a document, proceed with sharding.
+
+## HALT CONDITIONS
+
+- HALT if npx command fails or produces no output files
+
+## Memory Bank Hooks
+
+- **Reads:** the source document being sharded
+- **Writes:** the sharded output files only; does NOT modify `.rcode/memory/`. If the sharded doc is a Memory Bank file, use `rcode-memory-distill` instead.

package/rcode/skills/core/rcode-theme-system/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: rcode-theme-system
+description: Audit a frontend's design tokens BEFORE launch.
+triggers:
+  - "theme audit"
+  - "design tokens"
+  - "scattered colours"
+  - "hardcoded hex"
+  - "design system audit"
+  - "before launch design check"
+  - "consistent theme"
+  - "css variable audit"
+user-invocable: true
+---
+@.rcode/references/karpathy-guidelines.md
+
+
+## Overview
+
+Theme drift is silent until launch — then someone notices that "the brand blue" is 4 different blues across pages, and now you're rebranding under deadline. This skill catches drift early: every colour, font, spacing value, and animation duration must come from a token, not a literal. A 30-minute audit before launch is cheaper than a 3-week rebrand after.
+
+## The 7 token categories
+
+For each, the audit checks: where do values live, are they used consistently, is dark mode + RTL supported.
+
+### 1. Colour
+
+- [ ] All colours defined as CSS custom properties in one location (`globals.css` or `tokens.css`).
+- [ ] No raw hex / rgb in component files (grep for `#[0-9a-f]{3,8}`).
+- [ ] Each colour has a semantic name (`--color-primary`) AND a literal name (`--rcode-blue`).
+- [ ] Dark mode tokens defined alongside light, not retrofitted.
+
+### 2. Typography
+
+- [ ] Font families loaded once (via `next/font` or `<link>` in head).
+- [ ] Font sizes use a scale (`--text-xs`, `--text-sm`, etc.), not arbitrary px values.
+- [ ] Arabic font has explicit line-height bump (Arabic glyphs are denser).
+- [ ] Fallback stack defined for every font family.
+
+### 3. Spacing
+
+- [ ] Spacing scale defined (`--space-1` through `--space-12`).
+- [ ] No raw px values for margin/padding in components.
+- [ ] Logical properties used (`padding-inline-start`, not `padding-left`) for RTL.
+
+### 4. Radii & shadows
+
+- [ ] Radii scale (`--radius-sm`, `--radius-lg`).
+- [ ] Shadow tokens, not inline `box-shadow: 0 4px 6px ...` strings.
+
+### 5. Motion
+
+- [ ] Duration scale (`--duration-fast: 150ms`, `--duration-slow: 400ms`).
+- [ ] Easing tokens (`--ease-out`, `--ease-spring`).
+- [ ] Reduced-motion media query honoured.
+
+### 6. Breakpoints
+
+- [ ] Breakpoint tokens defined and used everywhere.
+- [ ] Mobile (390px), tablet (768px), desktop (1440px) all tested.
+
+### 7. RTL
+
+- [ ] `dir="rtl"` toggle exists and works at the root.
+- [ ] Logical properties used throughout (CSS Logical Properties Level 1).
+- [ ] Icons that imply direction (arrows, slashes) flipped via `transform: scaleX(-1)` or RTL-specific assets.
+- [ ] Mixed-content (Arabic + English in same line) tested.
+
+## Workflow
+
+1. **Inventory token locations.** Should be one file per category, plus a root index.
+2. **Grep for literals.** Every match in a component file is a finding.
+3. **Diff against design.** If Layla / Zahra / the brand guide has tokens that aren't in code, add them. If code has tokens not in the brand guide, flag them.
+4. **Test dark + RTL** per page if they're shipping.
+5. **Generate the fix list** ordered by frequency (a hardcoded `#1e3a8a` in 12 files is more urgent than one in 1).
+
+## Output Format
+
+```
+Theme audit — <date>
+Pages reviewed: <count>
+
+Token coverage:
+  Colour:        <X%>  ✗ <count> raw hex literals
+  Typography:    <X%>  ⚠ <findings>
+  Spacing:       <X%>
+  Radii/shadows: <X%>
+  Motion:        <X%>
+  Breakpoints:   <X%>
+  RTL:           ✓/✗
+
+Top offenders (by file):
+  src/components/Hero.tsx — 8 raw hex values
+  src/app/page.tsx — 4 hardcoded font sizes
+
+Fix order (by impact):
+  1. Replace #1e3a8a → var(--rcode-blue) — 12 occurrences across 8 files
+  2. ...
+
+Memory Bank update:
+  → .rcode/memory/project/decisions.md (token system canonicalised)
+```
+
+## Examples
+
+**Happy path — pre-launch audit** — Page count: 12. Coverage: colour 60%, typography 80%, spacing 50%, RTL 0%. Plan: extract tokens (1 day), migrate components (2 days), add RTL toggle (1 day). Catch the rebrand BEFORE launch.
+
+**Edge case — design partial alignment** — Brand guide has 3 blues, code has 7. Some are intentional shades; some are drift. Walk each with Zahra (`rcode-agent-zahra`) to canonicalise.
+
+**Negative — "we'll add dark mode later"** — Refuse silent commitment. Either ship dark mode now or document the decision in `decisions.md` so it doesn't become a "why don't we have dark mode?" argument in 3 months.
+
+## Memory Bank Hooks
+
+- **Reads:** `.rcode/memory/project/stack.md` (frontend layer), brand tokens from Zahra if available
+- **Writes:** `.rcode/memory/project/decisions.md` (canonical token system); `.rcode/memory/change-records/YYYYMMDD-NNN.md` (the audit itself)

package/rcode/skills/rcode-init/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: rcode-init
+internal: true
+description: "INTERNAL config loader for skills. Loads .rcode/ vars; lives in .rcode/skills/ not .claude/skills/."
+argument-hint: "[--module=module_code] [--vars=var1:default1,var2] [--skill-path=/path/to/calling/skill]"
+triggers:
+  - "init"
+---
+@.rcode/references/karpathy-guidelines.md
+
+
+## Overview
+
+This skill is the configuration entry point for all rcode skills. It has two modes:
+
+- **Fast path**: Config exists for the requested module — returns vars as JSON. Done.
+- **Init path**: Config is missing — walks the user through configuration, writes config files, then returns vars.
+
+Every rcode skill should call this on activation to get its config vars. The caller never needs to know whether init happened — they just get their config back.
+
+The script `rcode_init.py` is located in this skill's `scripts/` directory. Locate and run it using python for all commands below.
+
+## On Activation — Fast Path
+
+Run the `rcode_init.py` script with the `load` subcommand. Pass `--project-root` set to the project root directory.
+
+- If a module code was provided by the calling skill, include `--module {module_code}`
+- To load all vars, include `--all`
+- To request specific variables with defaults, use `--vars var1:default1,var2`
+- If no module was specified, omit `--module` to get core vars only
+
+**If the script returns JSON vars** — store them as `{var-name}` and return to the calling skill. Done.
+
+**If the script returns an error or `init_required`** — proceed to the Init Path below.
+
+## Init Path — First-Time Setup
+
+When the fast path fails (config missing for a module), run this init flow.
+
+### Step 1: Check what needs setup
+
+Run `rcode_init.py` with the `check` subcommand, passing `--module {module_code}`, `--skill-path {calling_skill_path}`, and `--project-root`.
+
+The response tells you what's needed:
+
+- `"status": "ready"` — Config is fine. Re-run load.
+- `"status": "no_project"` — Can't find project root. Ask user to confirm the project path.
+- `"status": "core_missing"` — Core config doesn't exist. Must ask core questions first.
+- `"status": "module_missing"` — Core exists but module config doesn't. Ask module questions.
+
+The response includes:
+- `core_module` — Core module.yaml questions (when core setup needed)
+- `target_module` — Target module.yaml questions (when module setup needed, discovered from `--skill-path` or `_rcode/{module}/`)
+- `core_vars` — Existing core config values (when core exists but module doesn't)
+
+### Step 2: Ask core questions (if `core_missing`)
+
+The check response includes `core_module` with header, subheader, and variable definitions.
+
+1. Show the `header` and `subheader` to the user
+2. For each variable, present the `prompt` and `default`
+3. For variables with `single-select`, show the options as a numbered list
+4. For variables with multi-line `prompt` (array), show all lines
+5. Let the user accept defaults or provide values
+
+### Step 3: Ask module questions (if module was requested)
+
+The check response includes `target_module` with the module's questions. Variables may reference core answers in their defaults (e.g., `{output_folder}`).
+
+1. Resolve defaults by running `rcode_init.py` with the `resolve-defaults` subcommand, passing `--module {module_code}`, `--core-answers '{core_answers_json}'`, and `--project-root`
+2. Show the module's `header` and `subheader`
+3. For each variable, present the prompt with resolved default
+4. For `single-select` variables, show options as a numbered list
+
+### Step 4: Write config
+
+Collect all answers and run `rcode_init.py` with the `write` subcommand, passing `--answers '{all_answers_json}'` and `--project-root`.
+
+The `--answers` JSON format:
+
+```json
+{
+  "core": {
+    "user_name": "rcode",
+    "communication_language": "English",
+    "document_output_language": "English",
+    "output_folder": "_rcode-output"
+  },
+  "bmb": {
+    "rcode_builder_output_folder": "_rcode-output/skills",
+    "rcode_builder_reports": "_rcode-output/reports"
+  }
+}
+```
+
+Note: Pass the **raw user answers** (before result template expansion). The script applies result templates and `{project-root}` expansion when writing.
+
+The script:
+- Creates `_rcode/core/config.yaml` with core values (if core answers provided)
+- Creates `_rcode/{module}/config.yaml` with core values + module values (result-expanded)
+- Creates any directories listed in the module.yaml `directories` array
+
+### Step 5: Return vars
+
+After writing, re-run `rcode_init.py` with the `load` subcommand (same as the fast path) to return resolved vars. Store returned vars as `{var-name}` and return them to the calling skill.
+
+## Output Format
+
+JSON config vars returned to the calling skill. When init path runs, interactive Q&A with the user, then config files written to `_rcode/`.
+
+## Workflow
+
+1. Read the user request and extract key parameters.
+2. Execute the skill logic as described in the Overview.
+3. Return output in the format specified below.
+
+## Examples
+
+### Happy path (fast path)
+**Calling skill:** invokes rcode-init with `--module bmb`
+**Result:** Config exists → returns `{"output_folder": "_rcode-output", ...}` instantly
+
+### Edge case (init path)
+**Calling skill:** invokes rcode-init, no config exists
+**Result:** Asks core questions → asks module questions → writes config → returns vars
+
+### Negative boundary
+**User:** "initialize my project"
+**Result:** rcode-init is internal — user should use `rcode-scaffold-project` or `/rcode-install` instead
+
+## Memory Bank Hooks
+
+- **Reads:** `package.json`, existing `.rcode/state.json` to detect prior runs
+- **Writes:** `.rcode/config.yaml`, `.rcode/state.json`, `.rcode/context/active.md`, `.rcode/context/project-brief.md`, `.rcode/JOURNEY.md`. Bootstraps the project so all subsequent rcode skills have a stable root.

package/rcode/state.json

@@ -0,0 +1,21 @@
+{
+  "version": "1",
+  "project": "__PROJECT_NAME__",
+  "_seeded_stub": true,
+  "created": "__INSTALL_DATE__",
+  "updated": "__INSTALL_DATE__",
+  "current_phase": null,
+  "current_plan": 0,
+  "current_sprint": null,
+  "milestone": null,
+  "phases": [],
+  "executions": [],
+  "decisions": [],
+  "blockers": [],
+  "council_sessions": [],
+  "chains": [],
+  "workstreams": [],
+  "active_workstream": null,
+  "last_session": null,
+  "velocity_history": []
+}