Site forge

Site Forge

<objective> Turn a one-line brief into a finished, deployed, award-quality website. The output is a self-contained site with no build step on a CDN stack — a single `index.html` for a one-pager, or a multi-page set that shares one byte-identical shell (head, nav, footer, scripts) — optionally paired with a Remotion promo video. The rule that makes this worth running: **every site is designed fresh for its brief** — a plumber's one-pager and a SaaS launch must look nothing alike (different palette, fonts, layout, sections, motion). The references here are a **capability library you draw from**, never a checklist you fill in. Start from a clean, fast, responsive floor and add only what the brief earns; the references are a starting point, not a ceiling — exceed them when the brief calls for it. </objective>

<execution_context> Phase 0 resolves the mode:

• auto (fast): Do as much as possible yourself. After the one plan/approval gate (Phase 3), run to completion without asking. Use only media you can make yourself for free (jina; MCP/Higgsfield if present). If a step blocks, needs interaction, or fails — skip it, keep going, list it under "Skipped / upgrade later" at the end. Bias to shipping.
• full (best quality): Interactive. Ask whenever a choice meaningfully changes the result, and use the best free media even when it needs the user (Google/Gemini for images, Veo 3.1 Fast in Flow for video — hand them exact prompts, they generate, drop the files). A blocked step → ask them to step in.

Both modes:

• 🟢 Auto: explore the environment, design, write code, extract frames, run ffmpeg, local-preview, and deploy after approval.
• 🟡 One mandatory gate: the Phase 3 plan (what runs, installs, spends credits, needs the user) must be approved before building — in both modes.
• 🔴 Never: invent fake credentials/keys; publish claims the user flagged as unverified without a disclaimer; enter the user's secrets into forms. </execution_context>

<process> <phase name="0_mode_and_brief"> ## Phase 0 — Mode + brief First token of the invocation (`auto`/`full`) sets the mode; the rest is the brief. If no mode is given, ask once. Capture: who it's for, the goal, any assets/links/voice. Thin brief → in `full` ask 1–2 sharpening questions; in `auto` infer sensibly and record assumptions in the plan. </phase> <phase name="1_explore"> ## Phase 1 — Explore (this is what makes it portable) Detect what's actually on this machine before planning, quickly and in parallel: - **Skills:** `frontend-design`, `jina-image-search`, `remotion`, `higgsfield-generate`, `here-now` (`ls ~/.claude/skills` + plugin list). - **MCP:** context7, higgsfield, any image/video servers. - **CLI/runtime:** `node`, `npx`, `python3`, `ffmpeg`, `edge-tts`, `netlify`, and the **OS + version** (`sw_vers` — version matters; macOS < 15 needs the Remotion workaround in `references/remotion-video.md`). Record what's present. Prefer live skills/tools when found; fall back to this skill's baked-in references when not. Install nothing yet — install *just before* the step that needs it (Phase 5/6), Netlify only at deploy. </phase> <phase name="2_design"> ## Phase 2 — Design direction (frontend-design first, always) **Invoke `frontend-design` before any markup** (installed → use it; else read `references/frontend-design.md` — the **full skill, bundled verbatim**, so you get its complete guidance even offline). Then use `references/aesthetics.md` as the theme/type/layout-derivation helper. This is the anti-slop gate and the biggest quality lever. Commit to a bold, brief-specific direction: - One clear aesthetic, executed precisely; a distinctive font pairing (never Inter/Roboto/Arial); a cohesive palette as CSS variables. - The *structure* — which sections, what hierarchy, the one memorable moment — derived from the brief. **Do not reuse the last site's shape.** - Which capabilities fit, and which to leave out (see the Reference map). A simple brief may use none of the heavy effects; a flagship may use several. Write a 3–5 line design brief to carry into the plan. </phase> <phase name="3_plan_and_approve"> ## Phase 3 — Plan + approve (the one gate, both modes) Present a tight plan: design direction, sections, capabilities you'll use, what you'll **install/run**, what **spends credits** (AI media), and (in `full`) what **needs the user**. In `auto`, also list likely skips. Approval here is the only mandatory stop in `auto`. </phase> <phase name="4_media"> ## Phase 4 — Media (per mode) See `references/ai-media.md` and `references/images.md`. - `auto`: jina for images (and try for embeddable/scrub video); MCP/Higgsfield if present and free; extract scroll-scrub frames from any clip with ffmpeg. No good video available → ship image-only (Ken-Burns) and flag the upgrade. - `full`: best free media — Gemini images, Veo 3.1 Fast in Flow video (hand the user exact prompts) — plus everything `auto` can do. Always: right dimensions, `object-fit`, lazy-load, the `img{height:auto}` rule, and the before/after same-base edit trick when the brief wants it. </phase> <phase name="5_build"> ## Phase 5 — Build the site Write the site as self-contained HTML — one `index.html`, or a multi-page set (see below) — with CDN libs via SRI'd `<script>` tags (nothing to install). Compose from the capability references chosen in Phase 2, reading each only when you use it (see the Reference map). Stagger heavy effects (one per viewport), lazy-init below the fold, keep the console clean, and match implementation complexity to the aesthetic — restraint for minimal briefs, elaboration for maximal ones. A useful, well-built skeleton lives at `assets/templates/index-skeleton.html` — treat it as a *starting point to reshape*, not a template to fill.

Single-page vs multi-page. A one-pager ships as a single index.html. A brief with distinct audiences or real depth (a business site with patient / physician / pricing / about sections, a marketing site with a Science page) earns a multi-page set instead — separate *.html pages sharing one chrome. With no build step the shared blocks are hand-copied, so drift is a real bug: keep the <head> (incl. the no-FOUC theme snippet), nav, footer, and <script> tags byte-identical across every page, and verify by hashing them before deploy — a page that quietly diverges (different fonts, a missing toggle, a dead link) is the classic failure. Give each page its own self-referential canonical/og:url + <title>/description, emit a sitemap.xml + robots.txt, and noindex any private/app mockup pages. If the page count or shared-block size makes hand-copying fragile, a tiny include step (Node concat, or Eleventy/Astro) is a fair trade — but only when the brief earns it; default to no-build. </phase>

<phase name="6_video"> ## Phase 6 — Promo video (optional) If the brief wants a video, build it with Remotion — full pipeline (VO → karaoke captions → audio mix → **sequence render → ffmpeg stitch**, incl. the macOS < 15 workaround) in `references/remotion-video.md`, using `scripts/build-captions.py`, `scripts/mix-audio.sh`, `scripts/render-video.sh`. Install Remotion/edge-tts/ffmpeg just before this step. In `auto`, a render failure → skip + flag; in `full`, ask the user to help. </phase> <phase name="7_qa_and_deploy"> ## Phase 7 — QA + deploy Run `references/quality-checklist.md` (CSS collisions, JS TDZ, `img` stretch, form detection, lazy-load timing, mobile pass, console-clean, reduced-motion). Local-preview, fix, then deploy free with `scripts/deploy-netlify.sh` (`references/deploy.md`) — Netlify is the only thing installed at the end; enable Forms (`ignore_html_forms`) + the notification hook if there's a form. **Then set up Cloudflare Web Analytics by default** (the user usually wants it): ask for a beacon token for the deployed hostname, inject the snippet before `</body>` with NO SRI (Cloudflare rotates it — the documented exception), and redeploy. In `auto`, surface it as a "needs the user" item with the exact hostname. Details in `references/deploy.md`. Report the live URL, what was used, and (in `auto`) the Skipped / upgrade-later list. </phase> </process>

Reference map (read on demand — do NOT preload all of these)

Need	File
GSAP+Lenis wiring, reduced-motion, CDN/SRI	references/stack-and-wiring.md
Scroll scrub (frames), before/after, progress bar + back-to-top ring, reveals, perf rules	references/scroll-effects.md
Canvas pseudo-3D (no bundler, default) + Three.js (capability-gated)	references/interactive-3d.md
Carousel, video player, counters, Netlify Forms	references/components.md
frontend-design — full skill, verbatim (offline fallback)	references/frontend-design.md
Theme system, fonts, deriving a unique look	references/aesthetics.md
AI image/video gen (auto vs full), free-vs-paid	references/ai-media.md
Image handling, height:auto fix, ffmpeg crop/scale	references/images.md
Remotion VO→captions→mix→render→stitch, macOS fix	references/remotion-video.md
Bug checklist before shipping	references/quality-checklist.md
Netlify deploy, Forms API, rename	references/deploy.md

This is a toolkit, not a sequence. Use what the brief earns; ignore the rest.

<error_handling>

• Missing skill/tool → auto falls back to the baked-in reference and notes it; full offers to install or asks.
• Install fails / needs interaction → auto skips + surfaces; full asks.
• macOS < 15 Remotion render abort → sequence-render + ffmpeg-stitch path (references/remotion-video.md), never the direct mp4 mux.
• AI media unavailable / out of credits → auto ships image-only + flags upgrade; full routes to Gemini/Flow.
• Netlify form not detected → set ignore_html_forms:false via API + redeploy (references/deploy.md). </error_handling>

<success_criteria>

• Design is unique to the brief — not a reuse of a prior site's look.
• frontend-design applied (invoked, or its principles via aesthetics.md).
• Self-contained site (one index.html, or a multi-page set sharing byte-identical chrome); console-clean; mobile passes.
• Only brief-earned capabilities included (no gratuitous effects).
• Plan approved before build (both modes).
• Deployed; live URL reported; auto lists any skips/upgrades. </success_criteria>