Site Forge

Site Forge

• 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.
• 🟡 TWO mandatory gates in both modes: (1) the Phase 3 plan before building, and (2) the deploy itself — ask immediately before every deploy, every time. Approval for one deploy is never approval for the next. Default is local preview.
• 🔴 Never: invent fake credentials/keys; publish claims the user flagged as unverified without a disclaimer; enter the user's secrets into forms.

0. Pick the PROFILE before anything else. Read references/design-profiles.md and state it in one line: "Profile: creative-portfolio. Bending display-size ceiling, serif ban, scrim floor, conversion furniture. Craft floor unchanged." The default is local-service; creative-portfolio covers photographers, designers and artists; personal-agency is Adam's own. The profile decides which of Adam's aesthetic rules are in force — the craft floor never bends, so 16px body, 4.5:1 contrast, 44px taps, reduced-motion, schema, the sixteen social tags and the security headers apply no matter what the brief or a reference site does. Getting this wrong produces a trades site wearing a portfolio's photographs.

1. Read references/page-composition.md first (it is the difference between a page that feels designed and one that feels empty), then 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).

2. Invoke design-taste-frontend. State its one-line design read ("Reading this as: for , with a language…") and set the three dials. Use taste-skill's own defaults and presets. The one carve-out: its perpetual-motion unlock at MOTION_INTENSITY > 5 stays off — no pulse, shimmer, float, typewriter, or infinite loops. Skip its React/Tailwind stack section on static builds.

3. Impeccable is already running: its hook fires on every write. Its commands are the Phase 7 gate.

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.

Impeccable's hook fires on every write. Resolve its findings as they appear, not in a pile at the end — each one either gets fixed or explicitly classified as a false positive with a stated reason. Never inline-suppress a rule to skip fixing it; suppression needs Adam's confirmation. After ~6 edits it goes quiet to avoid noise, which is why the Phase 7 audit is a separate hard gate.

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.

Then three mechanical gates, all of which have caught real shipped defects:

python3 <skill>/scripts/audit-seo.py        # SEO, local SEO, security. exit 1 on HIGH
python3 <skill>/scripts/check-crops.py      # object-fit:cover discarding the subject
python3 <skill>/scripts/colour-system.py    # one treatment per photograph, site-wide

And click every interactive element in a real browser, asserting a state change. An FAQ, a filter bar and a map panel have all shipped with complete markup, complete CSS and no handler at all: nothing looks broken in the source. Use document.elementFromPoint at the control's own centre, not .click(), which skips hit-testing and passes on a control that is completely buried.

If anything feels janky, TRACE it, do not sample it. performance_start_trace then scroll then performance_analyze_insight("ForcedReflow") names the offending function by file and line. Frame-rate sampling has plus or minus ten points of variance and will send you after the wrong thing. See scroll-performance.md.

Design-stack gate — hard, before deploy, no exceptions:

1. /impeccable critique (UX review) then /impeccable audit (a11y, perf, responsive).
2. Every finding fixed, or classified a false positive with a stated reason. Never inline-suppress. Suppression needs Adam's confirmation.
3. Run taste-skill's own pre-flight checklist (its Section 14).
4. Grep the CSS for infinite animations and tinted box-shadow, and neutralize both. This catches the one taste-skill setting we deliberately override.

Default is LOCAL. Preview with python3 -m http.server 8080 in the build dir and iterate there. Do not deploy unless the user asks in that moment — a live URL is only warranted for a paying client or a scheduled demo, and every deploy costs Netlify credits (38 deploys to one site exhausted a monthly allowance and forced a paid upgrade). Batch every outstanding fix into ONE deploy per review round.

Mobile QA is deferred to the first real deploy — it cannot be done locally and the automation browser cannot emulate a true mobile viewport. Plan for a dedicated mobile pass at demo time rather than pretending it was verified earlier.

NEVER deploy the project root. .netlifyignore is NOT honoured by netlify deploy --dir, and deploying a root once published a client's HOME ADDRESS and a tracker PASSWORD across the fleet. Build an explicit publish directory and verify the live surface, every time:

python3 scripts/make-dist.py .        # publishes only web files, withholds .py/.md/package.json
netlify deploy --prod --dir dist
scripts/verify-published.sh <host> [owner-street-name]   # must print "clean"; non-zero exit = leak

When the user does approve, deploy 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.

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

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

CMS / "can I edit it myself?" — read references/cms-options.md before answering. Short version: default is NO CMS; content changes are included in the monthly, and that is a feature, not a gap (a trade changes their site ~twice a year and will forget the login). If one is genuinely warranted, the only category that fits hand-written static HTML is a git-based CMS (Sveltia or Decap), never WordPress — we sell against WordPress explicitly. A CMS is a paid tier feature, never a default.

Twilio / missed-call text-back / A2P 10DLC — read references/twilio-a2p-10dlc.md before quoting or building it. Three things that decide everything: (1) the reseller rule — brand registrations carry the CLIENT's email and address, not ours; using ours caps the business at 10 clients, silently; (2) campaign vetting takes WEEKS, not days — start the day they sign; (3) a live website + a business email on a real domain are REQUIRED FIELDS, and our gmail-using prospects have neither, which makes the website a prerequisite for texting rather than a nice-to-have. That is the strongest sales argument in the ladder.