@hanzlaa/rcode 2.8.0 → 3.2.0

package/rihal/skills/core/rihal-auth-audit/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: rihal-auth-audit
+description: Audit Keycloak ↔ Active Directory sync, JWT validation, and tenant isolation in multi-org Postgres. Use when seeing authentication weirdness — users disappearing, tokens accepted post-deactivation, "phantom" sessions, or tenant data leaking across orgs. Specifically encodes the lessons from the Rihal Keycloak data-loss incident — sync drift between Keycloak and AD silently broke logins.
+triggers:
+  - "auth audit"
+  - "keycloak ad sync"
+  - "users disappearing"
+  - "ghost session"
+  - "tenant leak"
+  - "jwt validation check"
+  - "stale token"
+  - "session not invalidating"
+user-invocable: true
+---
+
+## Overview
+
+Authentication bugs are usually silent — the user just gets logged out, or worse, sees someone else's data. This skill encodes the specific failure modes that have actually bitten Rihal projects, with a runnable 10-minute checklist. Default scope is Keycloak + Active Directory + Postgres; adapt the specifics to whatever provider is in use.
+
+## The 10-minute checklist
+
+### Keycloak ↔ AD sync (the load-bearing one)
+
+- [ ] Keycloak's AD federation is configured with **periodic sync ENABLED**, not just on-login. Without periodic sync, a user deactivated in AD keeps working in Keycloak until their token expires.
+- [ ] Sync interval ≤ 1 hour for production. Longer windows are how the Rihal incident happened.
+- [ ] Sync errors land in Sentry, not just Keycloak's internal log. If sync silently fails, no one notices for weeks.
+- [ ] On AD deactivation, the corresponding Keycloak session is **explicitly invalidated** — don't rely on the JWT expiring.
+
+### JWT validation
+
+- [ ] `iss`, `aud`, `exp`, signature — all four checked on every protected request.
+- [ ] JWKS keys are **fetched dynamically with caching**, not pinned. Keycloak rotates them.
+- [ ] Clock-skew tolerance is ≤ 60s. Larger windows give attackers reuse room.
+- [ ] Token revocation list (or short TTL + refresh) is in place. Stateless JWTs are a CVE waiting for "logout doesn't actually log out".
+
+### Tenant isolation in Postgres
+
+- [ ] Every query that reads tenant data has `WHERE tenant_id = $1` where `$1` is **derived from the JWT**, never from a request parameter or cookie.
+- [ ] Postgres Row-Level Security (RLS) policies are enabled OR a query middleware enforces tenant_id (belt + suspenders preferred).
+- [ ] No raw SQL strings interpolate tenant_id — always parameterised.
+- [ ] Audit log captures the tenant_id from the JWT for every write.
+
+### Session lifecycle
+
+- [ ] Password change → ALL sessions for that user invalidated (not just the current device).
+- [ ] Permission change (role removed) → token re-validation forced on next request.
+- [ ] Logout actually deletes the server-side session record, not just the cookie.
+
+## Workflow
+
+1. **Inventory the auth surfaces.** Login, refresh, password reset, role change, permission change, logout, OAuth callbacks if present.
+2. **Run the checklist** above for each surface. Cite the actual file and line for each pass / fail.
+3. **For each fail:** write a malicious test case before fixing — the test is the proof of regression-locked.
+4. **Persist findings** to `.rihal/memory/incidents/known-issues.md` if not fixable in this session, or `.rihal/memory/change-records/` if fixed.
+
+## Output Format
+
+```
+Auth audit — <date>
+Surfaces: <count>
+
+Keycloak ↔ AD sync:
+  ✓ periodic sync enabled (interval: <X>)
+  ✗ sync errors not in Sentry
+  ⚠ <other findings>
+
+JWT validation:
+  ✓ all 4 fields checked
+  ⚠ <other>
+
+Tenant isolation:
+  ✗ <table>.<query> missing tenant_id filter — file:line
+
+Session lifecycle:
+  ✓ <findings>
+
+Critical (block launch / production): <count>
+High (fix this sprint): <count>
+Medium (track in known-issues.md): <count>
+```
+
+## Examples
+
+**Happy path — sync drift caught** — Audit shows Keycloak sync is configured but interval is 24h, and errors aren't in Sentry. Findings: 2 critical. Fix: drop interval to 1h + wire sync errors to Sentry. Verify by deactivating a test user in AD and confirming Keycloak removes them within 1h.
+
+**Edge case — RLS enabled but middleware bypasses it** — Postgres RLS is on, but the Strapi controllers use a service-role connection that bypasses RLS. Findings: critical. Fix: switch to per-request connections with the user's JWT-derived role.
+
+**Negative — "we use OAuth so we're fine"** — Refuse. OAuth ≠ correctly-configured. Run the checklist anyway.
+
+## Memory Bank Hooks
+
+- **Reads:** `.rihal/memory/incidents/post-mortems/` (prior auth incidents), `.rihal/memory/project/stack.md` (auth provider)
+- **Writes:** `.rihal/memory/incidents/known-issues.md` (deferred); `.rihal/memory/change-records/YYYYMMDD-NNN.md` (the audit itself)

package/rihal/skills/core/rihal-brainstorming/SKILL.md

@@ -96,3 +96,8 @@ Follow the instructions in ./workflow.md.
 ### Negative boundary
 **User:** "brainstorm which tech stack to use"
 **Result:** Redirects to `/rihal:council` or Waleed (CTO) — architecture decisions need structured ADR evaluation, not open ideation.
+
+## Memory Bank Hooks
+
+- **Reads:** `.rihal/memory/project/glossary.md` (so generated ideas use project domain terms)
+- **Writes:** the brainstorm output document at the user-specified path; if any idea becomes a committed direction, the user should run `rcode-memory-update` to log it as a decision

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

@@ -0,0 +1,91 @@
+---
+name: rihal-client-gate
+description: Client requirement freeze gates and async-comm patterns to stop late requirements from derailing delivery. Use when a project keeps slipping because the client adds requirements mid-sprint, or when the client takes a week to respond to a blocking question. Specifically encodes Rihal's "client late requirements caused project delays" pain — the fix isn't to "communicate better", it's structural gates that the project actually enforces.
+triggers:
+  - "client gate"
+  - "freeze requirements"
+  - "scope creep"
+  - "client slow response"
+  - "requirements freeze"
+  - "client comm pattern"
+  - "stop late requirements"
+  - "delivery slipping"
+user-invocable: true
+---
+
+## 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 `.rihal/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 `.rihal/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 `.rihal/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:
+  → .rihal/memory/milestones/current.md (scope sign-off)
+  → .rihal/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 Rihal-style late-requirements incident happens. Gates make the flexibility explicit and survivable.
+
+## Memory Bank Hooks
+
+- **Reads:** `.rihal/memory/people/stakeholders.md` (response cadences), `.rihal/memory/milestones/current.md`
+- **Writes:** scope sign-offs to `.rihal/memory/milestones/current.md`; client change requests to `.rihal/memory/change-records/YYYYMMDD-NNN.md`

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

@@ -10,15 +10,13 @@ description: >
   "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 rihal-create-ux-design with Layla), writing new components from a
-  brief (use rihal-dev-story with Hanzla or Bilal), or inspiration-only
-  references without rebuild intent.
+  brief (use rihal-dev-story with Hanzla), or inspiration-only references
+  without rebuild intent.
 triggers:
-  - "clone
-  this website"
+  - "clone this website"
   - "clone this site"
   - "rebuild this page"
-  - "replicate this
-  UI"
+  - "replicate this UI"
   - "pixel-perfect clone"
   - "make exact UI like this"
   - "copy this site"
@@ -31,386 +29,47 @@ argument-hint: "<url>"
 user-invocable: true
 ---
 
-# Clone Website (Rihal)
-
-You are about to reverse-engineer and rebuild **$ARGUMENTS** as a pixel-perfect clone.
-
-This is not a two-phase process (inspect then build). You are a **foreman walking the job site** — as you inspect each section of the page, you write a detailed specification to a file, then hand that file to a specialist builder agent with everything they need. Extraction and construction happen in parallel, but extraction is meticulous and produces auditable artifacts.
-
-## Pre-Flight
-
-1. **Chrome MCP is required.** Test it immediately. If it's not available, stop and tell the user to enable it — this skill cannot work without browser automation.
-2. Read `TARGET.md` for URL and scope. If the URL doesn't match `$ARGUMENTS`, update it.
-3. Verify the base project builds: `npm run build`. The Next.js + shadcn/ui + Tailwind v4 scaffold should already be in place. If not, tell the user to set it up first.
-4. Create the output directories if they don't exist: `docs/research/`, `docs/research/components/`, `docs/design-references/`, `scripts/`.
-
-## Guiding Principles
-
-These are the truths that separate a successful clone from a "close enough" mess. Internalize them — they should inform every decision you make.
-
-### 1. Completeness Beats Speed
-
-Every builder agent must receive **everything** it needs to do its job perfectly: screenshot, exact CSS values, downloaded assets with local paths, real text content, component structure. If a builder has to guess anything — a color, a font size, a padding value — you have failed at extraction. Take the extra minute to extract one more property rather than shipping an incomplete brief.
-
-### 2. Small Tasks, Perfect Results
-
-When an agent gets "build the entire features section," it glosses over details — it approximates spacing, guesses font sizes, and produces something "close enough" but clearly wrong. When it gets a single focused component with exact CSS values, it nails it every time.
-
-Look at each section and judge its complexity. A simple banner with a heading and a button? One agent. A complex section with 3 different card variants, each with unique hover states and internal layouts? One agent per card variant plus one for the section wrapper. When in doubt, make it smaller.
-
-**Complexity budget rule:** If a builder prompt exceeds ~150 lines of spec content, the section is too complex for one agent. Break it into smaller pieces. This is a mechanical check — don't override it with "but it's all related."
-
-### 3. Real Content, Real Assets
-
-Extract the actual text, images, videos, and SVGs from the live site. This is a clone, not a mockup. Use `element.textContent`, download every `<img>` and `<video>`, extract inline `<svg>` elements as React components. The only time you generate content is when something is clearly server-generated and unique per session.
-
-**Layered assets matter.** A section that looks like one image is often multiple layers — a background watercolor/gradient, a foreground UI mockup PNG, an overlay icon. Inspect each container's full DOM tree and enumerate ALL `<img>` elements and background images within it, including absolutely-positioned overlays.
-
-### 4. Foundation First
-
-Nothing can be built until the foundation exists: global CSS with the target site's design tokens (colors, fonts, spacing), TypeScript types for the content structures, and global assets (fonts, favicons). This is sequential and non-negotiable. Everything after this can be parallel.
-
-### 5. Extract How It Looks AND How It Behaves
-
-A website is not a screenshot — it's a living thing. Elements move, change, appear, and disappear in response to scrolling, hovering, clicking, resizing, and time. If you only extract the static CSS of each element, your clone will look right in a screenshot but feel dead when someone actually uses it.
-
-For every element, extract its **appearance** (exact computed CSS via `getComputedStyle()`) AND its **behavior** (what changes, what triggers the change, and how the transition happens).
-
-Examples of behaviors to watch for:
-- Navbar that shrinks/changes background/gains shadow after scroll threshold
-- Elements that animate into view on viewport entry (fade-up, slide-in, stagger)
-- Sections with `scroll-snap-type`
-- Parallax layers
-- Hover state transitions (duration and easing matter)
-- Dropdowns/modals/accordions with enter/exit animations
-- Auto-playing carousels
-- Tabbed/pill content that cycles
-- Scroll-driven tab/accordion switching (IntersectionObserver, NOT click handlers)
-- Smooth scroll libraries (Lenis, Locomotive Scroll)
-
-### 6. Identify the Interaction Model Before Building
-
-This is the single most expensive mistake in cloning: building a click-based UI when the original is scroll-driven, or vice versa.
-
-How to determine this:
-1. **Don't click first.** Scroll through the section slowly and observe if things change on their own as you scroll.
-2. If they do, it's scroll-driven. Extract the mechanism.
-3. If nothing changes on scroll, THEN click/hover to test for click/hover-driven interactivity.
-4. Document the interaction model explicitly in the component spec.
-
-### 7. Extract Every State, Not Just the Default
-
-For tabbed/stateful content: click each tab via Chrome MCP and extract content per state. For scroll-dependent elements: capture at scroll position 0 and after crossing the trigger threshold.
-
-### 8. Spec Files Are the Source of Truth
-
-Every component gets a specification file in `docs/research/components/` BEFORE any builder is dispatched. The builder receives the spec file contents inline in its prompt — the file also persists as an auditable artifact.
-
-### 9. Build Must Always Compile
-
-Every builder agent must verify `npx tsc --noEmit` passes before finishing. After merging worktrees, you verify `npm run build` passes.
-
-## Phase 1: Reconnaissance
-
-Navigate to the target URL with Chrome MCP.
-
-### Screenshots
-- Take **full-page screenshots** at desktop (1440px) and mobile (390px) viewports
-- Save to `docs/design-references/` with descriptive names
-
-### Global Extraction
-Extract before anything else:
-
-**Fonts** — Inspect `<link>` tags for Google Fonts or self-hosted fonts. Check computed `font-family` on key elements. Configure in `src/app/layout.tsx` using `next/font`.
-
-**Colors** — Extract color palette from computed styles. Update `src/app/globals.css` with the target's actual colors.
-
-**Favicons & Meta** — Download to `public/seo/` and update `layout.tsx` metadata.
-
-**Global UI patterns** — Custom scrollbar, scroll-snap on page container, global keyframes, backdrop filters, smooth scroll libraries.
-
-### Mandatory Interaction Sweep
-
-**Scroll sweep:** Scroll the page slowly from top to bottom. Record header changes, viewport animations, auto-switching sidebars, scroll-snap points, smooth scroll libraries.
-
-**Click sweep:** Click every element that looks interactive.
-
-**Hover sweep:** Hover over every interactive element.
-
-**Responsive sweep:** Test at 1440px, 768px, 390px. Note layout changes at each breakpoint.
-
-Save findings to `docs/research/BEHAVIORS.md`.
-
-### Page Topology
-Map every distinct section from top to bottom. Give each a working name. Save as `docs/research/PAGE_TOPOLOGY.md`.
-
-## Phase 2: Foundation Build
-
-Sequential. Do it yourself:
-
-1. **Update fonts** in `layout.tsx`
-2. **Update globals.css** with target's color tokens, spacing, keyframes, scroll behaviors
-3. **Create TypeScript interfaces** in `src/types/`
-4. **Extract SVG icons** as React components in `src/components/icons.tsx`
-5. **Download global assets** via `scripts/download-assets.mjs`
-6. Verify: `npm run build` passes
-
-### Asset Discovery Script
-
-Run via Chrome MCP:
-
-```javascript
-JSON.stringify({
-  images: [...document.querySelectorAll('img')].map(img => ({
-    src: img.src || img.currentSrc,
-    alt: img.alt,
-    width: img.naturalWidth,
-    height: img.naturalHeight,
-    parentClasses: img.parentElement?.className,
-    position: getComputedStyle(img).position,
-    zIndex: getComputedStyle(img).zIndex
-  })),
-  videos: [...document.querySelectorAll('video')].map(v => ({
-    src: v.src || v.querySelector('source')?.src,
-    poster: v.poster,
-    autoplay: v.autoplay, loop: v.loop, muted: v.muted
-  })),
-  backgroundImages: [...document.querySelectorAll('*')].filter(el => {
-    const bg = getComputedStyle(el).backgroundImage;
-    return bg && bg !== 'none';
-  }).map(el => ({
-    url: getComputedStyle(el).backgroundImage,
-    element: el.tagName + '.' + el.className?.split(' ')[0]
-  })),
-  fonts: [...new Set([...document.querySelectorAll('*')].slice(0, 200).map(el => getComputedStyle(el).fontFamily))],
-  favicons: [...document.querySelectorAll('link[rel*="icon"]')].map(l => ({ href: l.href, sizes: l.sizes?.toString() }))
-});
-```
-
-## Phase 3: Component Specification & Dispatch
-
-For each section (top to bottom): **extract → write spec file → dispatch builders**.
-
-### Step 1: Extract
-
-1. **Screenshot** the section in isolation
-2. **Extract CSS** via this script (replace SELECTOR):
-
-```javascript
-(function(selector) {
-  const el = document.querySelector(selector);
-  if (!el) return JSON.stringify({ error: 'Element not found: ' + selector });
-  const props = [
-    'fontSize','fontWeight','fontFamily','lineHeight','letterSpacing','color',
-    'textTransform','textDecoration','backgroundColor','background',
-    'padding','paddingTop','paddingRight','paddingBottom','paddingLeft',
-    'margin','marginTop','marginRight','marginBottom','marginLeft',
-    'width','height','maxWidth','minWidth','maxHeight','minHeight',
-    'display','flexDirection','justifyContent','alignItems','gap',
-    'gridTemplateColumns','gridTemplateRows',
-    'borderRadius','border','borderTop','borderBottom','borderLeft','borderRight',
-    'boxShadow','overflow','overflowX','overflowY',
-    'position','top','right','bottom','left','zIndex',
-    'opacity','transform','transition','cursor',
-    'objectFit','objectPosition','mixBlendMode','filter','backdropFilter',
-    'whiteSpace','textOverflow','WebkitLineClamp'
-  ];
-  function extractStyles(element) {
-    const cs = getComputedStyle(element);
-    const styles = {};
-    props.forEach(p => {
-      const v = cs[p];
-      if (v && v !== 'none' && v !== 'normal' && v !== 'auto' && v !== '0px' && v !== 'rgba(0, 0, 0, 0)') styles[p] = v;
-    });
-    return styles;
-  }
-  function walk(element, depth) {
-    if (depth > 4) return null;
-    const children = [...element.children];
-    return {
-      tag: element.tagName.toLowerCase(),
-      classes: element.className?.toString().split(' ').slice(0, 5).join(' '),
-      text: element.childNodes.length === 1 && element.childNodes[0].nodeType === 3 ? element.textContent.trim().slice(0, 200) : null,
-      styles: extractStyles(element),
-      images: element.tagName === 'IMG' ? { src: element.src, alt: element.alt, naturalWidth: element.naturalWidth, naturalHeight: element.naturalHeight } : null,
-      childCount: children.length,
-      children: children.slice(0, 20).map(c => walk(c, depth + 1)).filter(Boolean)
-    };
-  }
-  return JSON.stringify(walk(el, 0), null, 2);
-})('SELECTOR');
-```
-
-3. **Extract multi-state styles** — capture before AND after trigger states
-4. **Extract real content** — all text, alt, aria labels
-5. **Identify assets** — which downloaded images/videos/icons
-6. **Assess complexity** — split if necessary
-
-### Step 2: Write Component Spec File
-
-Template at `docs/research/components/<component-name>.spec.md`:
-
-```markdown
-# <ComponentName> Specification
-
 ## Overview
-- **Target file:** `src/components/<ComponentName>.tsx`
-- **Screenshot:** `docs/design-references/<screenshot-name>.png`
-- **Interaction model:** <static | click-driven | scroll-driven | time-driven>
-
-## DOM Structure
-<hierarchy>
-
-## Computed Styles (exact values)
-### Container
-- display, padding, maxWidth, etc.
-
-### <Child element>
-- every relevant property
-
-## States & Behaviors
-### <Behavior name>
-- **Trigger:** <exact mechanism>
-- **State A (before):** CSS values
-- **State B (after):** CSS values
-- **Transition:** transition CSS
-- **Implementation approach:** <CSS transition | IntersectionObserver | etc.>
 
-## Assets
-- Background/overlay images with paths
-- Icons used from icons.tsx
+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).
 
-## Text Content (verbatim)
-<copy-pasted from live site>
+## Process
 
-## Responsive Behavior
-- Desktop (1440px): <layout>
-- Tablet (768px): <changes>
-- Mobile (390px): <changes>
-- Breakpoint: ~<N>px
-```
-
-### Step 3: Dispatch Builders
-
-**Simple section** (1-2 sub-components): One builder agent.
-**Complex section** (3+ sub-components): Break up. One agent per sub-component + one for wrapper.
-
-Each builder receives:
-- Full spec file contents inline
-- Path to section screenshot
-- Which shared components to import
-- Target file path
-- Instruction to verify `npx tsc --noEmit`
-
-**Don't wait** — as soon as one builder is dispatched, move to next section extraction.
-
-### Step 4: Merge
-
-As agents complete: merge worktree branches, verify build passes, fix conflicts intelligently.
-
-## Phase 4: Page Assembly
-
-Wire everything together in `src/app/page.tsx`:
-- Import all section components
-- Implement page-level layout (scroll containers, z-index)
-- Connect real content to component props
-- Implement page-level behaviors (scroll-snap, smooth scroll, theme transitions)
-- Verify `npm run build` passes
-
-## Phase 5: Visual QA Diff
-
-Take side-by-side screenshots with original. Compare section by section at 1440px AND 390px. For each discrepancy: re-extract, update spec, fix component. Test all interactive behaviors.
-
-## Pre-Dispatch Checklist
-
-Before dispatching ANY builder:
-- [ ] Spec file written with ALL sections filled
-- [ ] Every CSS value is from `getComputedStyle()`, not estimated
-- [ ] Interaction model identified and documented
-- [ ] All states captured (not just default)
-- [ ] Scroll/hover triggers with before/after/transition recorded
-- [ ] All images identified including overlays
-- [ ] Responsive behavior documented
-- [ ] Text content verbatim
-- [ ] Builder prompt ≤150 lines
+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
 
-- Every builder dispatches with an inline spec (not a file reference)
-- Every commit keeps `npm run build` green
-- Final report structure:
-  - Total sections built: N
-  - Total components created: N
-  - Total spec files written: N (must match components)
-  - Total assets downloaded: N
-  - Build status: PASS/FAIL
-  - Visual QA discrepancies: list
-- Do NOT include: vague status like "mostly done", builders dispatched without spec files, or estimated CSS values
-- Do NOT merge with red builds
-- Do NOT skip responsive extraction
-
-## Workflow
+```
+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>
+```
 
-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.
+Do NOT include: vague status like "mostly done", builders dispatched without spec files, or estimated CSS values.
 
 ## Examples
 
-### Happy Path
-**Input:** "clone https://linear.app"
-
-**Expected behavior:**
-1. Pre-flight: verify Chrome MCP, base Next.js+shadcn scaffold
-2. Reconnaissance: full-page screenshots, global extraction (fonts/colors/favicons), interaction sweep
-3. Foundation build: update layout.tsx fonts, globals.css colors, icons.tsx, download assets
-4. For each section top-to-bottom: extract CSS via getComputedStyle, write spec file, dispatch builder in worktree
-5. Merge branches as builders complete, keep build green
-6. Visual QA diff at desktop + mobile
-7. Report with component counts, asset counts, build status
-
-### Edge Case: Missing Chrome MCP
-**Input:** "clone this site: https://example.com"
-
-**Expected behavior:** STOP immediately. Respond: "Chrome MCP not available. Enable it first — this skill requires browser automation to extract computed styles and screenshots. Without it, I'd be guessing from HTML which produces bad clones."
-
-### Edge Case: Scroll-Driven Site Mistaken for Click-Driven
-**Input:** User asks to clone a site with scroll-driven tabs
-
-**Expected behavior:** During interaction sweep, scroll BEFORE clicking. If content switches on scroll, document as "INTERACTION MODEL: scroll-driven with IntersectionObserver". Do NOT build click-based tabs.
-
-### Edge Case: Builder Prompt Too Long
-**Input:** (Extracting a complex section with 4 card variants)
+**Happy path** — `clone https://linear.app` → reconnaissance → foundation → spec each section → dispatch builders → assemble → visual QA. ~6 phases, parallel where possible.
 
-**Expected behavior:** Check the 150-line rule. If spec exceeds it, split: one builder per card variant + one for the section wrapper. Do NOT override with "it's all related."
+**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.
 
-### Negative Test
-**Input:** "Design a new landing page for our Rihal product"
+**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.
 
-**Expected behavior:** Stay silent. This is original design work — not cloning. Redirect: "This needs original design — invoke Layla (rihal-agent-layla) for UX or Bilal (rihal-agent-bilal) for direct build. I clone existing sites, not create new ones."
+**Negative — original design request** — "Design a new landing page" is not a clone. Redirect to Layla (UX) or Hanzla (direct build).
 
-## What NOT to Do
+## Memory Bank Hooks
 
-- Don't build click-based tabs when the original is scroll-driven
-- Don't extract only the default state of tabbed content
-- Don't miss overlay/layered images
-- Don't build HTML mockups for content that's actually videos/Lottie/canvas
-- Don't approximate CSS classes — extract exact values
-- Don't build monolithic commits
-- Don't reference external docs from builder prompts — inline everything
-- Don't skip asset extraction
-- Don't give a builder too much scope
-- Don't bundle unrelated sections into one agent
-- Don't skip responsive extraction at 1440/768/390
-- Don't forget smooth scroll libraries (Lenis, Locomotive)
-- Don't dispatch builders without a spec file
+- **Reads:** `package.json` and existing `src/` to detect scaffold; `.rihal/memory/project/stack.md` if present (records the stack used)
+- **Writes:** `docs/research/` (artefacts, persistent), `docs/design-references/` (screenshots), nothing in `.rihal/memory/` directly
 
-## Completion Report
+## Detailed reference
 
-- Total sections built: N
-- Total components created: N
-- Total spec files written: N
-- Total assets downloaded (images/videos/SVGs/fonts): N
-- Build status: `npm run build` result
-- Visual QA results: any remaining discrepancies
-- Any known gaps or limitations
+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.