---
name: site-forge
description: >-
  Build a distinctive, production-grade website (single-page or multi-page) — and an optional
  Remotion promo video — for any business, product, or person, then deploy it
  free. Use whenever the user wants to build, design, mock up, prototype, or
  pitch a website, landing page, demo/spec site, or portfolio — for a local
  business, a product launch, cold-outreach demos, or themselves — even if they
  never say "site-forge". Adapts a unique aesthetic and structure to each brief
  (never a template). Two modes: auto (fast, autonomous, free agent-made media)
  and full (interactive, best quality, Gemini + Veo media).
argument-hint: "[auto|full] <what to build, for whom, any assets/links>"
---

# 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>