@hanzlaa/rcode 3.6.16 → 4.1.0

package/rcode/skills/core/rcode-client-gate/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: rcode-client-gate
+description: Client requirement freeze gates and async-comm patterns to stop late requirements from derailing.
+triggers:
+  - "client gate"
+  - "freeze requirements"
+  - "scope creep"
+  - "client slow response"
+  - "requirements freeze"
+  - "client comm pattern"
+  - "stop late requirements"
+  - "delivery slipping"
+user-invocable: true
+---
+@.rcode/references/karpathy-guidelines.md
+
+
+## Overview
+
+Late client requirements aren't the client's fault — they're the project's structural failure to define when input is welcome and when it's not. This skill installs three gates: a **scope freeze** at sprint start, a **decision deadline** for blocking questions, and a **change-control** path for everything that arrives after the freeze. Without these, every client comment becomes a potential mid-sprint pivot.
+
+## The 3 gates
+
+### Gate 1 — Scope freeze at sprint start
+
+- Sprint scope is locked at sprint kickoff, in writing, with the client signing off.
+- "Locked" means: no new stories enter the sprint without going through Gate 3 (change control).
+- The scope doc lives in `.rcode/memory/milestones/current.md` (not just a Slack message).
+- Sign-off is explicit — a thumbs-up emoji doesn't count. Email or document sign-off.
+
+### Gate 2 — Decision deadline for blocking questions
+
+- Every blocking question to the client carries a deadline: e.g. "we need an answer by Wed EOD or we ship the default option".
+- Deadlines are enforced — when missed, the team picks the documented default and moves on.
+- Defaults are documented BEFORE asking — "if you don't reply, we'll do X".
+- Stakeholder response cadences from `.rcode/memory/people/stakeholders.md` inform the deadline (don't give a 24h deadline to a stakeholder with a documented 1-week cadence).
+
+### Gate 3 — Change control after the freeze
+
+- Anything new that arrives after the sprint kickoff goes into a queue, not the current sprint.
+- Each change-request gets evaluated weekly:
+  - **Critical** (broken core flow, security): emergency mid-sprint slot — but explicit, with a story shipped late.
+  - **High** (next sprint priority): goes to top of next sprint's backlog.
+  - **Medium / nice-to-have**: parked, reviewed at next milestone.
+- Client sees the queue; transparency prevents "where did my request go?" friction.
+
+## Workflow
+
+1. **At project kickoff:** install the 3 gates. Walk the client through them — explain that this is how delivery dates stay credible.
+2. **At each sprint kickoff:** run Gate 1. Write down the scope. Get sign-off.
+3. **Throughout the sprint:** any blocking question gets Gate 2 (deadline + default). Any new requirement gets Gate 3 (queue).
+4. **At sprint close:** review the change queue with the client. Triage.
+5. **Persist all gate events** to `.rcode/memory/people/stakeholders.md` and the change-records folder. The pattern of "client always responds Friday afternoon" becomes a planning input.
+
+## Output Format
+
+For each sprint:
+
+```
+Sprint kickoff — <date>
+Scope (signed off by <client>):
+  - Story 1
+  - Story 2
+  ...
+
+Active blocking questions:
+  Q1 (asked <date>, deadline <date>): <question>
+  Default if no answer: <documented default>
+
+Change queue (post-freeze):
+  Critical:   <count>
+  High:       <count>
+  Medium:     <count>
+
+Memory Bank update:
+  → .rcode/memory/milestones/current.md (scope sign-off)
+  → .rcode/memory/people/stakeholders.md (cadence observations)
+```
+
+## Examples
+
+**Happy path — government client** — Client has documented 1-week response cadence. Gate 2 deadline becomes 5 days, with a default ("we'll go with option B unless you reply"). Project ships on time despite slow comms.
+
+**Happy path — scope freeze enforced** — Day 4 of sprint, client adds 3 requirements. Gate 3 queues all 3. Client sees them in the next-sprint backlog. No mid-sprint pivot.
+
+**Edge case — "but this requirement is critical"** — Run the Gate 3 critical-or-not test: does this break a core flow? Is it a security issue? If yes, emergency mid-sprint slot with explicit story shipped late. If no, it's a next-sprint priority. Don't let "critical" be a synonym for "I'd really like this".
+
+**Negative — "we'll just be more flexible"** — Refuse. Flexibility without gates is how every rcode-style late-requirements incident happens. Gates make the flexibility explicit and survivable.
+
+## Memory Bank Hooks
+
+- **Reads:** `.rcode/memory/people/stakeholders.md` (response cadences), `.rcode/memory/milestones/current.md`
+- **Writes:** scope sign-offs to `.rcode/memory/milestones/current.md`; client change requests to `.rcode/memory/change-records/YYYYMMDD-NNN.md`

package/rcode/skills/core/rcode-clone-website/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: rcode-clone-website
+description: >
+  Reverse-engineer and clone any website pixel-perfectly — extracts assets,
+  exact CSS via getComputedStyle, content section-by-section, and dispatches
+  parallel builder agents in worktrees. Activates when the user says "clone
+  this website", "clone this site", "rebuild this page", "replicate this
+  UI", "pixel-perfect clone", "make exact UI like this", "copy this site",
+  "reverse engineer this site", "build me a clone of", "aisi website banao",
+  "yeh site clone karo", or "exact same UI chahiye like [URL]". Provide the
+  target URL as input. Do NOT use for: creating original designs from scratch
+  (use rcode-create-ux-design with Layla), writing new components from a
+  brief (use rcode-dev-story with Hanzla), or inspiration-only references
+  without rebuild intent.
+triggers:
+  # English
+  - "clone this website"
+  - "clone this site"
+  - "rebuild this page"
+  - "replicate this UI"
+  - "pixel-perfect clone"
+  - "make exact UI like this"
+  - "copy this site"
+  - "reverse engineer this site"
+  - "build me a clone of"
+  # Roman Urdu / Hindi
+  - "aisi website banao"
+  - "yeh site clone karo"
+  - "exact same UI chahiye like [URL]"
+  - "yeh website ki copy banao"
+  - "site ko clone karo"
+  # Arabic native
+  - "استنسخ هذا الموقع"
+  - "أعد بناء هذه الصفحة"
+  - "موقع مطابق تمامًا"
+  - "انسخ هذا الموقع"
+  - "هندسة عكسية للموقع"
+argument-hint: "<url>"
+user-invocable: true
+---
+@.rcode/references/karpathy-guidelines.md
+
+
+## Overview
+
+Reverse-engineer a target URL into a working Next.js + shadcn/ui + Tailwind clone. The skill is **foreman-style**: extract a section, write a spec file, dispatch a builder agent in a worktree, move on to the next section. Extraction is meticulous (computed CSS, real assets, both static and behavioral) — building runs in parallel. Detailed principles, scripts, and templates live in [`references.md`](references.md).
+
+## Workflow
+
+1. **Pre-flight** — Chrome MCP available, Next.js + shadcn scaffold builds clean, output dirs exist.
+2. **Phase 1 — Reconnaissance** — full-page screenshots (desktop + mobile), global extraction (fonts, colors, favicons), mandatory interaction sweep (scroll, click, hover, responsive), page topology map.
+3. **Phase 2 — Foundation build** — fonts, `globals.css`, TypeScript types, SVG icons, downloaded assets. Sequential, must compile.
+4. **Phase 3 — Component spec & dispatch** — for each section: extract DOM + computed CSS + states + content + assets → write `docs/research/components/<name>.spec.md` → dispatch builder agent with full spec inline. Don't wait between sections.
+5. **Phase 4 — Page assembly** — wire components in `src/app/page.tsx`, implement page-level behaviours (scroll-snap, smooth scroll, theme transitions). Build must pass.
+6. **Phase 5 — Visual QA diff** — side-by-side screenshots vs original at 1440px and 390px. Re-extract on discrepancies.
+
+## Output Format
+
+```
+Total sections built:        N
+Total components created:    N
+Total spec files written:    N   (must match component count)
+Total assets downloaded:     N   (images / videos / SVGs / fonts)
+Build status:                PASS | FAIL
+Visual QA discrepancies:     <list of remaining diffs>
+```
+
+Do NOT include: vague status like "mostly done", builders dispatched without spec files, or estimated CSS values.
+
+## Examples
+
+**Happy path** — `clone https://linear.app` → reconnaissance → foundation → spec each section → dispatch builders → assemble → visual QA. ~6 phases, parallel where possible.
+
+**Edge case — missing Chrome MCP** — STOP immediately and tell the user to enable it. Without browser automation we'd be guessing from HTML, which produces bad clones.
+
+**Edge case — scroll-driven site** — during interaction sweep, scroll BEFORE clicking. If content switches on scroll, document as "INTERACTION MODEL: scroll-driven (IntersectionObserver)" and do NOT build click-based tabs. This is the #1 expensive mistake.
+
+**Negative — original design request** — "Design a new landing page" is not a clone. Redirect to Layla (UX) or Hanzla (direct build).
+
+## Memory Bank Hooks
+
+- **Reads:** `package.json` and existing `src/` to detect scaffold; `.rcode/memory/project/stack.md` if present (records the stack used)
+- **Writes:** `docs/research/` (artefacts, persistent), `docs/design-references/` (screenshots), nothing in `.rcode/memory/` directly
+
+## Detailed reference
+
+See [`references.md`](references.md) for: the 9 guiding principles, the asset discovery script, the CSS extraction script, the component spec template, the pre-dispatch checklist, and the "what NOT to do" list.

package/rcode/skills/core/rcode-deploy-unify/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: rcode-deploy-unify
+description: Detect and unify multiple deployment paths in a single project.
+triggers:
+  - "deploy unify"
+  - "multiple deploy paths"
+  - "which deploy is production"
+  - "deploy chaos"
+  - "consolidate deployments"
+  - "kubernetes vs compose"
+  - "single deploy path"
+  - "deployment audit"
+user-invocable: true
+---
+@.rcode/references/karpathy-guidelines.md
+
+
+## Overview
+
+Multiple deploy paths is a shipping-risk multiplier. Every path is one more thing that can drift from the others, deploy stale code, or "I thought you ran it" through ops. The rcode Siraaj incident was a textbook case — Docker Compose for some services, Helm for others, manual `ssh && pull` for the rest, and no one knew which combination was production.
+
+## Workflow
+
+1. **Inventory every deploy path.** Look in:
+   - `docker-compose.yml`, `docker-compose.*.yml`
+   - `helm/`, `charts/`, `k8s/`
+   - `Makefile`, `scripts/deploy*`
+   - `.github/workflows/deploy*.yml`, `.gitlab-ci.yml`, `Jenkinsfile`
+   - Vercel / Netlify project links
+   - Anything in `infra/` or `deployment/`
+2. **Classify each:** dev / staging / production. If you can't classify it, that's the bug.
+3. **Identify drift.** For each pair (dev↔staging, staging↔prod):
+   - Different env vars?
+   - Different image tags?
+   - Different replica counts?
+   - Different healthchecks?
+   - Different secret-management?
+4. **Pick ONE canonical path per environment.** Helm + values per env is the rcode default. Compose is dev-only. No "and also a Jenkinsfile that does it differently".
+5. **Deprecate the others** with a clear timeline. Don't delete on day one — leave them as `*.deprecated` and observe for 2 weeks before removal.
+6. **Document the canonical path** in `.rcode/memory/project/decisions.md` and a top-level `DEPLOYMENT.md`.
+
+## Common drift patterns to look for
+
+| Symptom | Root cause | Fix |
+|---|---|---|
+| "Works in staging, breaks in prod" | Different env vars between paths | Single source of truth (Helm values + sealed-secrets) |
+| Image tags lag behind git SHA | Manual `docker push` mid-week | Tag-based deploys via CI only |
+| Healthchecks pass in compose, fail in K8s | Compose uses HTTP, K8s uses TCP | Align probe definitions |
+| "Deploy" doesn't restart all services | Some compose, some bare metal | One orchestrator |
+| Secrets diverge | `.env` files copied manually | External Secrets Operator or sealed-secrets only |
+
+## Output Format
+
+```
+Deploy paths discovered: <count>
+  - <path 1> — <classification>
+  - <path 2> — <classification>
+  ...
+
+Drift findings:
+  ✗ <pair> — <specific drift>
+  ✗ <pair> — <specific drift>
+
+Canonical path proposal:
+  dev:        <one path>
+  staging:    <one path>
+  production: <one path>
+
+Deprecation plan:
+  Week 1: mark <X> as deprecated, route docs to canonical
+  Week 2: remove <X> if no fallback usage observed
+
+Memory Bank update:
+  → .rcode/memory/project/decisions.md (canonical path decision)
+  → DEPLOYMENT.md (the runbook)
+```
+
+## Examples
+
+**Happy path — Siraaj-style mess** — 4 deploy paths found: docker-compose (dev), Helm (staging), manual script (prod-mostly), Jenkinsfile (sometimes prod). Drift: 6 envs differ between staging and prod. Canonical: Helm with `values.staging.yaml` and `values.production.yaml`. Compose stays dev-only. Manual + Jenkinsfile deprecated, removed 2 weeks later.
+
+**Edge case — legitimate dual path** — Mobile app uses TestFlight + Play Console; web uses Vercel. These are different surfaces, not deploy-path drift. Document why each surface uses what it does; don't try to unify across surfaces.
+
+**Negative — "let's just delete the old paths"** — Refuse without observation period. Some "deprecated" paths are actually the only thing that works for a specific service. Mark, observe, then delete.
+
+## Memory Bank Hooks
+
+- **Reads:** `.rcode/memory/incidents/post-mortems/` (prior deploy incidents)
+- **Writes:** `.rcode/memory/project/decisions.md` (canonical path decision); `.rcode/memory/change-records/YYYYMMDD-NNN.md` (the unification itself as a change record)

package/rcode/skills/core/rcode-distillator/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: rcode-distillator
+description: Lossless LLM-optimized compression of source documents.
+argument-hint: "<source-paths> [--validate <distillate-path>] [--token-budget <N>] [--consumer <name>]"
+triggers:
+  - "distillator"
+  - "distill documents"
+  - "create a distillate"
+  - "compress these docs"
+user-invocable: true
+---
+@.rcode/references/karpathy-guidelines.md
+
+
+## Overview
+
+Compresses source documents into a dense, lossless distillate optimised for LLM context loading. Output is one (or several semantically split) markdown files containing every fact, decision, named entity, and relationship from the sources — but no prose connectives, decoration, or repetition. A downstream LLM can use the distillate as sole context with no information loss.
+
+## Workflow
+
+1. **Validate inputs.** Required: `source_documents`. Optional: `downstream_consumer` (judges signal vs noise; if omitted, preserve everything), `token_budget` (triggers split when exceeded), `output_path` (default: adjacent to primary source with `-distillate.md` suffix), `--validate` flag (round-trip reconstruction test).
+2. **Stage 1 — Analyze.** Run `scripts/analyze_sources.py` on the source paths. Use its routing recommendation (`single` / `fan-out`) and grouping output. Do not read sources yourself.
+3. **Stage 2 — Compress.** Spawn `agents/distillate-compressor.md` subagent(s):
+   - **Single mode** (≤3 files, ≤15K tokens): one compressor.
+   - **Fan-out mode**: one compressor per group, then a merge compressor consuming the intermediate distillates (not originals).
+   - **Graceful degradation:** if subagent spawning is unavailable, perform the work directly using the same instructions.
+4. **Stage 3 — Verify & output.** Completeness check (every returned heading and named entity appears in the distillate; up to 2 targeted fix passes). Format check (bullets only, no prose, no repetition, `##` themes). Save with frontmatter (`type: rcode-distillate`, `sources`, `created`, `token_estimate`, `parts`). Split distillates when >5K tokens or `token_budget` exceeded — see [`references.md`](references.md) for the split format.
+5. **Stage 4 — Round-trip validate (only with `--validate`).** Spawn `agents/round-trip-reconstructor.md` with the distillate path only (no source access). Semantic-diff the reconstruction against the originals. Produce `<name>-validation-report.md` with status, gaps, and hallucinations. Up to 2 fix passes if gaps found. Adds significant token cost — only for high-stakes use.
+
+## Output Format
+
+Structured JSON on every run:
+
+```json
+{
+  "status": "complete",
+  "distillate": "path/to/file-distillate.md",
+  "section_distillates": ["path1", "path2"] or null,
+  "source_total_tokens": 15000,
+  "distillate_total_tokens": 4688,
+  "compression_ratio": "3.2:1",
+  "source_documents": ["path1", "path2"],
+  "completeness_check": "pass" | "pass_with_additions"
+}
+```
+
+Token counts come from `scripts/analyze_sources.py`. Compression ratio is `source / distillate`.
+
+## Examples
+
+**Happy path** — `distill ./docs/architecture.md ./docs/decisions.md` → single-mode → saves `architecture-distillate.md` → reports `3.2:1`.
+
+**Edge case — large folder** — `distill ./docs/ --validate` → fan-out mode (multiple compressors) → merge pass → round-trip validation produces a validation report.
+
+**Negative — summarisation request** — "summarize this meeting" — distillation is lossless compression, not summarisation. Clarify the difference or route to a writing skill.
+
+## Memory Bank Hooks
+
+- **Reads:** the source documents passed in
+- **Writes:** the distillate file (or folder) at the specified or default path
+- **Note:** for Memory Bank-specific distillates, use `rcode-memory-distill` instead — it knows the Memory Bank source set.
+
+## Detailed reference
+
+See [`references.md`](references.md) for: the split distillate folder format, the validation report template, frontmatter schema, and `--validate` flag semantics.

package/rcode/skills/core/rcode-distillator/references.md

@@ -0,0 +1,118 @@
+# Distillator — Detailed Reference
+
+Detailed formats and templates for [`SKILL.md`](SKILL.md).
+
+---
+
+## Frontmatter schema
+
+Every distillate file (single or split-index) has:
+
+```yaml
+---
+type: rcode-distillate
+sources:
+  - "{relative path to source 1}"
+  - "{relative path to source 2}"
+downstream_consumer: "{consumer or 'general'}"
+created: "{ISO date}"
+token_estimate: {approximate token count}
+parts: 1   # or N for split distillates
+---
+```
+
+Source paths are relative to the distillate's location.
+
+---
+
+## Single distillate format
+
+When `total_tokens ≤ 5000` and `token_budget` is not exceeded:
+
+- One file: `{base-name}-distillate.md`
+- Frontmatter as above with `parts: 1`
+- Body: `##` themes containing self-contained bullets — no prose paragraphs, no decorative formatting, no repetition
+
+---
+
+## Split distillate format
+
+When `total_tokens > 5000` OR `token_budget` requires splitting:
+
+```
+{base-name}-distillate/
+├── _index.md           # orientation, cross-cutting items, section manifest
+├── 01-{topic-slug}.md  # self-contained section
+├── 02-{topic-slug}.md
+└── 03-{topic-slug}.md
+```
+
+`_index.md` contains:
+- Frontmatter (sources relative to the folder; `parts: N`)
+- 3-5 bullet orientation: what was distilled, from what
+- Section manifest: each section's filename + 1-line description
+- Cross-cutting items that span multiple sections
+
+Each section file:
+- Self-contained — loadable independently
+- 1-line context header: `This section covers {topic}. Part N of M.`
+- Same bullet-only format
+
+---
+
+## Round-trip validation report template
+
+Saved adjacent to the distillate as `{base-name}-validation-report.md`:
+
+```markdown
+---
+type: distillate-validation
+distillate: "{distillate path}"
+sources: ["{source paths}"]
+created: "{ISO date}"
+---
+
+## Validation Summary
+- Status: PASS | PASS_WITH_WARNINGS | FAIL
+- Information preserved: {percentage estimate}
+- Gaps found: {count}
+- Hallucinations detected: {count}
+
+## Gaps (information in originals but missing from reconstruction)
+- {gap description} — Source: {which original}, Section: {where}
+
+## Hallucinations (information in reconstruction not traceable to originals)
+- {hallucination description} — appears to fill gap in: {section}
+
+## Possible Gap Markers (flagged by reconstructor)
+- {marker description}
+```
+
+---
+
+## Validation semantics
+
+- **PASS** — every fact, decision, constraint, and relationship survives the round trip.
+- **PASS_WITH_WARNINGS** — minor gaps that the reconstructor itself flagged ("possible gap markers").
+- **FAIL** — material gaps or hallucinations. Trigger up to 2 targeted fix passes on the distillate.
+
+If gaps remain after fix passes: surface them honestly in the report. Do not pad the distillate with regenerated content — that introduces hallucination.
+
+---
+
+## When to use `--validate`
+
+- Distillates feeding architecture / system-design workflows
+- Distillates of regulatory or compliance documents
+- Distillates produced for an external consumer (client deliverable)
+- Anywhere information loss is unacceptable
+
+Skip `--validate` for routine distillates (Memory Bank refresh, internal context loading) — it adds significant token cost.
+
+---
+
+## Cleanup behaviour
+
+- Intermediate distillates (fan-out mode) live only in memory; they are not saved.
+- Reconstruction files (`--validate` mode) are temporary; delete them after the validation report is written.
+- The validation report itself persists alongside the distillate.