@growthub/cli 0.3.54 → 0.3.56

package/assets/worker-kits/growthub-ai-website-cloner-v1/docs/design-token-system.md

@@ -0,0 +1,135 @@
+# Design Token System
+
+**Kit:** `growthub-ai-website-cloner-v1`
+
+---
+
+## Overview
+
+The clone's design system uses Tailwind CSS v4 with oklch color tokens. All design values extracted from the target site are expressed as CSS custom properties in the `@theme` block of `globals.css`.
+
+---
+
+## Token extraction methodology
+
+The operator uses `getComputedStyle()` in the browser DevTools console to extract exact computed values from the live target site.
+
+### Color extraction
+
+```js
+// Run in browser DevTools console on the target site
+// Extract all unique colors in use
+[...document.querySelectorAll('*')].flatMap(el => {
+  const s = getComputedStyle(el);
+  return [s.color, s.backgroundColor, s.borderColor, s.outlineColor]
+    .filter(c => c && c !== 'rgba(0, 0, 0, 0)' && c !== 'transparent');
+}).filter((v, i, a) => a.indexOf(v) === i).sort();
+```
+
+### Typography extraction
+
+```js
+// Extract all typography combinations
+[...document.querySelectorAll('*')].map(el => {
+  const s = getComputedStyle(el);
+  return `${s.fontFamily} | ${s.fontSize} | ${s.fontWeight} | ${s.lineHeight}`;
+}).filter((v, i, a) => a.indexOf(v) === i).sort();
+```
+
+### Spacing extraction
+
+```js
+// Extract spacing values from a specific element
+const el = document.querySelector('.hero-section');
+const s = getComputedStyle(el);
+console.log({
+  padding: s.padding,
+  margin: s.margin,
+  gap: s.gap,
+  columnGap: s.columnGap,
+  rowGap: s.rowGap,
+});
+```
+
+---
+
+## Converting to oklch
+
+Tailwind CSS v4 uses oklch as the primary color format. Convert extracted hex/rgb values:
+
+```js
+// Paste into browser console to convert RGB to oklch approximation
+// (or use https://oklch.com/ for manual conversion)
+function rgbToOklch(r, g, b) {
+  // Simplified — use the oklch.com tool for production values
+  const L = (0.2126 * r + 0.7152 * g + 0.0722 * b) / 255;
+  return `oklch(${(L * 100).toFixed(0)}% 0 0)`;
+}
+```
+
+Use [oklch.com](https://oklch.com/) for precise conversion during token extraction.
+
+---
+
+## Tailwind CSS v4 `@theme` configuration
+
+All extracted tokens go into `src/app/globals.css`:
+
+```css
+@import "tailwindcss";
+
+@theme {
+  /* Colors */
+  --color-primary: oklch(12% 0 0);
+  --color-bg: oklch(100% 0 0);
+  --color-text: oklch(15% 0 0);
+  --color-text-secondary: oklch(45% 0 0);
+  --color-accent: oklch(50% 0.2 260);
+  --color-border: oklch(91% 0 0);
+
+  /* Typography */
+  --font-sans: "Inter", system-ui, sans-serif;
+  --font-heading: "Geist", "Inter", system-ui, sans-serif;
+
+  /* Spacing scale */
+  --spacing-xs: 0.25rem;
+  --spacing-sm: 0.5rem;
+  --spacing-md: 1rem;
+  --spacing-lg: 1.5rem;
+  --spacing-xl: 2rem;
+  --spacing-2xl: 3rem;
+
+  /* Border radius */
+  --radius-sm: 0.25rem;
+  --radius-md: 0.5rem;
+  --radius-lg: 0.75rem;
+  --radius-xl: 1rem;
+
+  /* Shadows */
+  --shadow-sm: 0 1px 2px oklch(0% 0 0 / 0.05);
+  --shadow-md: 0 4px 6px oklch(0% 0 0 / 0.1);
+  --shadow-lg: 0 10px 15px oklch(0% 0 0 / 0.1);
+}
+```
+
+---
+
+## How builders use tokens
+
+Builders use Tailwind utility classes that reference the tokens:
+
+```tsx
+// Using color tokens
+<div className="bg-[var(--color-bg)] text-[var(--color-text)]">
+
+// Using spacing tokens
+<section className="px-[var(--spacing-xl)] py-[var(--spacing-2xl)]">
+
+// Using radius tokens
+<button className="rounded-[var(--radius-md)]">
+
+// Using shadow tokens
+<div className="shadow-[var(--shadow-md)]">
+```
+
+All token references are from the extraction sheet. No builder should invent new token names.

package/assets/worker-kits/growthub-ai-website-cloner-v1/docs/multi-phase-pipeline.md

@@ -0,0 +1,129 @@
+# Multi-Phase Pipeline Architecture
+
+**Kit:** `growthub-ai-website-cloner-v1`
+
+---
+
+## Overview
+
+The clone pipeline runs in strict phase order. No phase may be skipped. Each phase produces artifacts consumed by the next.
+
+```
+Phase 0: Environment gate
+    ↓
+Phase 1: Load methodology + project context
+    ↓
+Phase 2: Load runtime docs
+    ↓
+Phase 3: Reconnaissance (screenshots, tokens, assets, interactions)
+    ↓
+Phase 4: 3-question gate (objective, exclusions, deployment target)
+    ↓
+Phase 5: Component spec writing (one spec per section)
+    ↓
+Phase 6: Builder dispatch (parallel worktrees)
+    ↓
+Phase 7: Assembly + Visual QA
+    ↓
+Phase 8: Platform handoff
+```
+
+---
+
+## Phase 0 — Environment gate
+
+**Gate criteria:**
+1. Fork exists at `~/ai-website-cloner-template` (or `AI_CLONER_FORK_PATH`)
+2. Node.js 24+ available
+3. Fork `node_modules/` installed
+4. AI agent active
+
+**If any check fails:** stop, report the specific issue, do not proceed.
+
+---
+
+## Phase 3 — Reconnaissance (most critical phase)
+
+Reconnaissance is the most time-sensitive phase. It must be thorough because all subsequent work depends on it.
+
+### Screenshot protocol
+The agent opens Chrome (or a Playwright browser) and captures:
+- Desktop screenshots at every viewport height of content (scroll the page)
+- Tablet and mobile screenshots at the same scroll depths
+- Hover state screenshots for all interactive elements
+
+### Token extraction
+The agent runs `getComputedStyle()` extraction calls in the browser console. The exact calls are defined in `skills.md`. Tokens are extracted for:
+- All colors in use (background, text, borders, accents)
+- All typography combinations (family, size, weight, line-height)
+- All spacing values (margin, padding)
+- All border-radius, box-shadow, and transition values
+
+### Asset download
+All external assets are downloaded to `public/` immediately during reconnaissance — before spec writing. This prevents broken image references during building.
+
+---
+
+## Phase 5 — Component spec writing
+
+Each spec is a complete, standalone brief for one builder. It must include:
+- Exact computed CSS values (not estimates)
+- Multi-state content for all interactive states
+- Responsive behavior at all three breakpoints
+- Exact asset paths in `public/`
+- Exact content (no placeholders)
+
+The spec is the builder's only source of truth. It must be self-contained.
+
+---
+
+## Phase 6 — Parallel builder dispatch
+
+The orchestrator creates a `git worktree` for each builder:
+
+```bash
+# Orchestrator creates worktrees
+git worktree add ../build-navigation build/navigation
+git worktree add ../build-hero-section build/hero-section
+# ... one per section
+```
+
+Each builder is dispatched as a subagent with:
+1. Their section spec (inline)
+2. The design token extraction sheet
+3. The asset manifest
+4. Clear output constraints (only write to `src/components/<section-slug>/`)
+
+Builders run in parallel — the orchestrator does not wait for one before starting the next.
+
+---
+
+## Phase 7 — Assembly and visual QA
+
+**Assembly:**
+1. All builder branches are merged into `main` (or the integration branch)
+2. The orchestrator writes `src/app/page.tsx` to import and wire all components
+3. `npm run build` is run to confirm no errors
+4. `npm run lint` and `npm run typecheck` must pass
+
+**Visual QA:**
+1. `npm run dev` is started
+2. The agent opens the clone in the browser
+3. Side-by-side comparison with original screenshots
+4. Each section is checked at all three breakpoints
+5. All hover/focus/active states are exercised interactively
+6. Findings are documented in `visual-qa-checklist.md`
+
+---
+
+## Phase 8 — Platform handoff
+
+The platform handoff document (`platform-handoff.md`) is the final deliverable. It includes:
+- What was built (summary)
+- How to run locally
+- How to build for production
+- Deployment instructions for the target platform
+- All known deviations from the original
+- Next customization steps
+
+The brand kit is updated with a deliverable line.

package/assets/worker-kits/growthub-ai-website-cloner-v1/docs/parallel-builder-dispatch.md

@@ -0,0 +1,103 @@
+# Parallel Builder Dispatch
+
+**Kit:** `growthub-ai-website-cloner-v1`
+
+---
+
+## Why parallel builders
+
+A modern website has 5–20 distinct sections. Cloning them sequentially would be slow and would block each builder on the previous one. The parallel worktree system lets all builders work simultaneously, each in an isolated branch.
+
+The orchestrator (the Growthub operator running as the main agent) dispatches all builders at once, waits for them to complete, then assembles the results.
+
+---
+
+## Worktree isolation
+
+Each builder gets a dedicated `git worktree` — a separate working directory linked to the same repository but on a different branch:
+
+```bash
+# Create worktrees (orchestrator does this before dispatch)
+git worktree add ../build-navigation build/navigation
+git worktree add ../build-hero-section build/hero-section
+git worktree add ../build-features build/features
+git worktree add ../build-footer build/footer
+```
+
+Each builder's working directory is independent. They cannot conflict with each other during development.
+
+---
+
+## Builder constraints
+
+Builders must follow these rules without exception:
+
+| Rule | Detail |
+|---|---|
+| Write only to `src/components/<section-slug>/` | No writes to shared files |
+| No writes to `src/app/` | The orchestrator owns the page |
+| No writes to `src/lib/` | Shared utilities stay unchanged |
+| No writes to `globals.css` | Tokens are in the design token file |
+| No writes to `src/types/` | Types are defined by the orchestrator |
+| No writes to `layout.tsx` | The root layout is owned by the orchestrator |
+| One component file per section | `src/components/<section-slug>/<ComponentName>.tsx` |
+
+---
+
+## Builder input package
+
+Each builder receives exactly:
+
+1. **Section spec** — the complete component spec from `specs/<section-slug>.md`
+2. **Design token sheet** — `templates/design-token-extraction.md` (full token set)
+3. **Asset manifest** — `templates/asset-manifest.md` (all `public/` asset paths)
+4. **Naming instructions** — component name, output path, export format
+
+---
+
+## Builder output format
+
+Each builder produces a TypeScript React component:
+
+```tsx
+// src/components/hero-section/HeroSection.tsx
+import Image from "next/image";
+
+export function HeroSection() {
+  return (
+    <section className="...">
+      {/* exact content from spec */}
+    </section>
+  );
+}
+```
+
+Requirements:
+- Named export (not default export)
+- TypeScript strict — no `any`
+- Tailwind CSS utility classes (no inline styles)
+- Uses `cn()` from `src/lib/utils.ts` for conditional classes
+- Asset paths from `public/` using Next.js `<Image>` or `<video>` tags
+- Uses design tokens from the Tailwind config (via CSS variables)
+
+---
+
+## Assembly
+
+After all builders complete, the orchestrator:
+
+1. Merges all `build/*` branches into `main`
+2. Resolves any conflicts (should be minimal since builders touch different files)
+3. Writes `src/app/page.tsx` importing all components in order
+4. Updates `src/app/layout.tsx` with correct metadata
+5. Updates `globals.css` with the full design token set from the extraction sheet
+
+---
+
+## Conflict resolution
+
+The most common merge conflicts:
+- `package.json` — if two builders added the same dependency. Orchestrator de-dupes.
+- `src/components/icons.tsx` — if two builders added SVG icons. Orchestrator merges all icons.
+
+These are resolved by the orchestrator with full context about what all builders were doing.

package/assets/worker-kits/growthub-ai-website-cloner-v1/examples/clone-brief-sample.md

@@ -0,0 +1,54 @@
+# Clone Brief — Sample
+
+**Project:** Acme Corp Homepage Clone  
+**Client:** Acme Corp  
+**Target URL(s):** `https://acme.example.com`  
+**Date:** 2026-04-15  
+**Operator:** `ai-website-cloner-operator`
+
+---
+
+## Objective
+
+Pixel-perfect clone of the Acme Corp homepage into a modern Next.js 16 codebase. The client needs the source code for a planned migration from their legacy Webflow site to a self-hosted Next.js deployment.
+
+---
+
+## Scope
+
+### Pages to clone
+- [x] `https://acme.example.com` — Homepage
+
+### Sections to include
+- [x] Navigation / Header (sticky, with dropdown menus)
+- [x] Hero — full-viewport with background video
+- [x] Features grid — 3-column, 6 feature cards
+- [x] Social proof — testimonials carousel
+- [x] CTA banner — centered, high-contrast
+- [x] FAQ accordion
+- [x] Footer — 4-column with newsletter signup
+
+### Sections to exclude
+- [x] Login flow — auth-gated, excluded by client request
+- [x] Blog listing — dynamic content, excluded from v1 scope
+
+---
+
+## Constraints
+
+- **Deployment target:** Vercel
+- **Custom domain:** `acme.com` (configured post-handoff)
+- **Proprietary fonts:** "Acme Sans" — not publicly available; replaced with Inter (documented deviation)
+- **Auth-gated content:** Login flow excluded from scope
+- **Terms of Service notes:** Confirmed with client — they own this site and have rights to reproduce it
+
+---
+
+## Deliverables
+
+- [x] Cloned Next.js codebase in `~/ai-website-cloner-template`
+- [x] Reconnaissance report
+- [x] Design token extraction sheet (24 colors, 8 typography combinations)
+- [x] 7 component specs
+- [x] Visual QA checklist — PASS with 1 noted deviation (font)
+- [x] Platform handoff document

package/assets/worker-kits/growthub-ai-website-cloner-v1/examples/component-spec-sample.md

@@ -0,0 +1,123 @@
+# HeroSection — Component Spec (Sample)
+
+**Project:** Acme Corp Homepage Clone  
+**Section slug:** `hero-section`  
+**Output component:** `src/components/hero-section/HeroSection.tsx`  
+**Date:** 2026-04-15
+
+---
+
+## Purpose
+
+Full-viewport hero section with a looping background video, centered headline, subheadline, and two CTA buttons. First visible content above the fold on desktop and mobile.
+
+---
+
+## Layout
+
+- **Container max-width:** 1280px
+- **Container padding (desktop):** 0 80px
+- **Container padding (mobile):** 0 24px
+- **Display:** flex, column, center-aligned
+- **Section min-height:** 100vh
+- **Background:** `#0a0a0a` / `oklch(7% 0 0)` with video overlay
+
+---
+
+## Typography
+
+| Element | Font family | Size | Line height | Weight | Color | Notes |
+|---|---|---|---|---|---|---|
+| Headline | Inter | 72px | 1.1 | 700 | `#ffffff` | Desktop only |
+| Headline | Inter | 40px | 1.15 | 700 | `#ffffff` | Mobile |
+| Subheadline | Inter | 20px | 1.5 | 400 | `rgba(255,255,255,0.7)` | Desktop |
+| Subheadline | Inter | 16px | 1.5 | 400 | `rgba(255,255,255,0.7)` | Mobile |
+| CTA primary | Inter | 16px | 1 | 600 | `#0a0a0a` | — |
+| CTA secondary | Inter | 16px | 1 | 600 | `#ffffff` | — |
+
+---
+
+## Colors
+
+- **Background:** `#0a0a0a` / `oklch(7% 0 0)` (with bg video)
+- **Text primary:** `#ffffff` / `oklch(100% 0 0)`
+- **Text secondary:** `rgba(255,255,255,0.7)` / `oklch(100% 0 0 / 0.7)`
+- **CTA primary bg:** `#ffffff` / `oklch(100% 0 0)`
+- **CTA secondary border:** `rgba(255,255,255,0.3)` / `oklch(100% 0 0 / 0.3)`
+
+---
+
+## States
+
+### Default
+Headline + subheadline centered. Two CTAs side by side. Background video loops silently at `opacity: 0.4`.
+
+### Hover — CTA primary
+- Transform: none
+- Background: `oklch(91% 0 0)` (slight dim)
+- Transition: `background 0.2s ease`
+
+### Hover — CTA secondary
+- Border-color: `oklch(100% 0 0 / 0.6)`
+- Background: `oklch(100% 0 0 / 0.08)`
+- Transition: `all 0.2s ease`
+
+### Focus (both CTAs)
+- Focus ring color: `#3b82f6` / `oklch(59% 0.2 260)`
+- Focus ring offset: 3px
+- Focus ring width: 2px
+
+---
+
+## Responsive behavior
+
+### Desktop (1440px)
+72px headline, two CTAs side by side, background video full-coverage
+
+### Tablet (768px)
+56px headline, CTAs stack vertically, video still full-coverage
+
+### Mobile (375px)
+40px headline, 16px subheadline, CTAs full-width and stacked
+
+---
+
+## Assets
+
+| File | Public path | Source URL |
+|---|---|---|
+| hero-bg.mp4 | `public/videos/hero-bg.mp4` | `https://cdn.acme.example.com/hero-bg.mp4` |
+
+---
+
+## Content
+
+**Headline:**  
+The Future of Work Starts Here
+
+**Subheadline:**  
+Automate your growth with AI. Launch faster, scale smarter, and let your team focus on what matters.
+
+**CTA primary:**  
+Start for free
+
+**CTA secondary:**  
+Watch demo
+
+---
+
+## Accessibility
+
+- **ARIA landmark:** `<section aria-label="Hero">`
+- **Heading level:** `<h1>`
+- **Video:** `<video autoPlay muted loop playsInline aria-hidden="true">` (decorative)
+- **Tab order:** CTA primary → CTA secondary
+- **Reduced motion:** video paused if `prefers-reduced-motion: reduce`
+
+---
+
+## Implementation notes
+
+The background video must use `object-fit: cover` and position `absolute` behind the content. The content must be `relative` with `z-index: 1`.
+
+Tailwind v4 class for the video overlay: use `bg-black/60` over the video to ensure text contrast.

package/assets/worker-kits/growthub-ai-website-cloner-v1/examples/platform-handoff-sample.md

@@ -0,0 +1,102 @@
+# Platform Handoff — Sample
+
+**Project:** Acme Corp Homepage Clone  
+**Client:** Acme Corp  
+**Date:** 2026-04-15  
+**Clone source:** `https://acme.example.com`  
+**Codebase location:** `~/ai-website-cloner-template`
+
+---
+
+## What was built
+
+A pixel-perfect clone of the Acme Corp homepage, rebuilt in Next.js 16 + shadcn/ui + Tailwind CSS v4. The clone includes all 7 sections of the original page (navigation, hero, features, testimonials, CTA banner, FAQ, footer) with all assets downloaded and all interactive states matched. The only deviation is the proprietary "Acme Sans" font, replaced with Inter (documented below).
+
+---
+
+## Running the clone locally
+
+```bash
+cd ~/ai-website-cloner-template
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000).
+
+---
+
+## Building for production
+
+```bash
+cd ~/ai-website-cloner-template
+npm run build
+npm run start
+```
+
+Expected build output: ~45 static pages + 1 dynamic route.
+
+---
+
+## Deploying to Vercel
+
+```bash
+npm install -g vercel
+cd ~/ai-website-cloner-template
+vercel --prod
+```
+
+The app will be live at `https://ai-website-cloner-template.vercel.app` until you configure a custom domain.
+
+---
+
+## Project structure
+
+```
+src/
+  app/
+    page.tsx                    # Main homepage
+    layout.tsx                  # Root layout with Inter font
+    globals.css                 # Full design token set (24 colors)
+  components/
+    navigation/Navigation.tsx
+    hero-section/HeroSection.tsx
+    features-grid/FeaturesGrid.tsx
+    testimonials/Testimonials.tsx
+    cta-banner/CtaBanner.tsx
+    faq/Faq.tsx
+    footer/Footer.tsx
+    icons.tsx                   # 18 extracted SVG icons
+public/
+  images/                       # 11 downloaded images
+  videos/
+    hero-bg.mp4                 # Hero background video
+  seo/
+    favicon.ico
+    og-image.png
+```
+
+---
+
+## Known deviations from original
+
+| Section | Type | Notes |
+|---|---|---|
+| All headings | Font | "Acme Sans" is a proprietary font not available via CDN. Replaced with Inter (weight 700). Visual difference is subtle — baseline spacing may differ by ~2px on some headings. |
+
+---
+
+## Customization next steps
+
+1. [ ] Replace `public/seo/og-image.png` with the client's actual OG image
+2. [ ] Update `src/app/layout.tsx` metadata: title, description, canonical URL
+3. [ ] Configure Vercel environment variables for any future dynamic features
+4. [ ] If "Acme Sans" is obtained via license, add it to `src/app/layout.tsx` and update `globals.css`
+5. [ ] Remove `public/videos/hero-bg.mp4` and replace with a client-owned video file before redistribution
+
+---
+
+## QA result
+
+See `qa/visual-qa-checklist.md` for the full QA report.
+
+**Overall result:** PASS WITH NOTED DEVIATIONS (font only)