Communitygithub.com

Client Site Builder

Runs a full client-website pipeline: brief and design intake, sitemap and copy, build, checks, review, SEO, and launch prep, with two approval gates and a capped fix loop.

What is Client Site Builder?

Starts or rebuilds a client site from intake through launch prep, and stops for approval instead of drifting into an endless restyle.

Works with✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/cgfeletar/website-builder/tree/HEAD/core/.claude/skills/build-site

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

Build a client site

The main session runs this pipeline and delegates to subagents. (Subagents can't start other subagents, which is why this is a skill, not an orchestrator agent.)

[0 Intake gate]  brief + DESIGN.md + references
      ↓
[1 Plan]  sitemap, page sections, copy  →  plan.md, src/data/*
      ↓
[USER GATE 1]  approve plan and copy
      ↓
[2 Build]  pages and visual system
      ↓
[3 SEO]     seo agent            →  seo-report.md
      ↓
[4 Verify]  npm run verify (hard gate)
      ↓
[5 Review]  site-reviewer agent  →  review-report.md
      ↓
[6 Fix loop]  P0/P1 → fix → verify → re-review (max 2 rounds)
      ↓
[USER GATE 2]  approve the site
      ↓
[7 Launch prep]  launch checklist + handoff doc
      ↓
[8 Lessons]  append to docs/lessons.md

Artifacts

Everything goes in .claude/pipeline/:

pipeline-state.md   stage, fix round, last updated
plan.md             sitemap, sections per page, main action per page
review-report.md    from site-reviewer
seo-report.md       from seo
screenshots/        from npm run verify

Read pipeline-state.md at the start of every stage and resume from where it says. Update it at the end of every stage. This lets a build span several sessions.

Stage 0: Intake gate

Check each item. If any is missing, stop and help the user fill it before anything else.

ItemReady when
.agents/product-marketing.mdBusiness facts section complete, main action named, audience and voice filled. Use the product-marketing skill to draft it from what the user gives you.
src/data/business.jsonName, phone, address, hours, maps link match the brief. Copy them from the brief.
DESIGN.mdEvery section filled. If the user only has references, draft it from references/ and ask them to confirm.
references/At least two screenshots or URLs with a line on what to take from each.
Client assetsLogo and photos, or an explicit note that stand-ins are OK for now.
EditingWill the client edit the site themselves? (Affects stage 7.)

Then fill src/styles/tokens.css from DESIGN.md.

Stage 1: Plan

  1. Write plan.md: the pages (most clients need Home, a page per main offer or a Menu/Services page, About, Contact), the one main action per page, and the sections on each page in order. Use the brief and site-essentials.
  2. Write the copy with the copywriting skill, then run copy-editing on it. Start from the brief's customer language and the client's own words, and use some of those phrases nearly verbatim. Follow house rule 9 in CLAUDE.md (no generic AI phrasing). Put it in src/data/ (home.json, services, FAQs), not in components.
  3. Mark anything you don't know as [NEED: ...]. Never fill a gap with an invented fact.

User gate 1

Stop. Show the user: the sitemap, each page's sections and main action, the full copy, and every [NEED: ...] item. Wait for approval or changes. Copy is cheaper to change now than after the build.

Stage 2: Build

Build with the design-taste-frontend skill (Taste Skill), inside this Astro project. Before starting, tell it:

  • The kind is place (people come to it) or service (people are hired), never a tech kind.
  • DESIGN.md and references/ set the palette, type and feel. Its own dealt palette and fonts are overridden.
  • Business facts come from src/data/business.json. Its stand-in contact rules don't apply.
  • Motion follows the house rules in CLAUDE.md.

Build page by page, home first. After home, run npm run verify, look at the three screenshots and fix what you see before building the next page. Taste Skill's finish gate runs on its own when it stops; treat its findings as input, but CLAUDE.md wins on conflicts.

Stage 3: SEO

The seo agent edits head tags, JSON-LD and robots, so it runs before verify and review. That way the review judges the finished site.

seo: "Audit and implement SEO for this site, including the local business step. Brief: .agents/product-marketing.md. Write your report to .claude/pipeline/seo-report.md."

Stage 4: Verify (hard gate)

npm run verify

All check-site FAILs and screenshot problems (sideways scroll, console errors) must be fixed before review. [NEED: ...] failures are allowed only for facts the user has already been asked for; list them. Rewrite any copy check-site flags as generic, unless the client actually uses that word.

Stage 5: Review

The reviewer is read-only and returns its report as its final message. Save that message verbatim to .claude/pipeline/review-report.md.

site-reviewer: "Review the built site. Plan: .claude/pipeline/plan.md. Brief: .agents/product-marketing.md. Design: DESIGN.md. Screenshots: .claude/pipeline/screenshots/. SEO changes already made: .claude/pipeline/seo-report.md. Return the full report as your final message."

Stage 6: Fix loop

site-reviewer verdictAction
ReadyGo to gate 2
Needs follow-up, P2s onlyGo to gate 2, list the P2s
Needs follow-up (P1s) or Blocked (P0s)Round < 2: fix them, rerun stage 4 (verify), rerun site-reviewer on the changed pages and save its report. Round = 2: stop and show the user.

Use the bug-fixer agent for anything that is broken rather than just off-brief. Increment the round in pipeline-state.md each time.

User gate 2

Stop. Show the user: home screenshots at 390 and 1440, the verdict, remaining P2s, SEO decisions needed, remaining [NEED: ...] items, and stand-in photos to replace. Wait for approval.

Stage 7: Launch prep

  1. Run npm run check:launch and fix every FAIL. Then fill docs/launch-checklist.md, marking each item done, not applicable, or waiting on someone (say who).
  2. Fill docs/handoff.md for the client.
  3. If the client will edit the site, follow docs/client-editing.md.
  4. After the site is live on its real domain, remind the user to run claude-seo on it: /seo local <url> and /seo audit <url>.

Stage 8: Lessons

Scan the reports and the fix rounds for anything that went wrong twice or cost real time. Append a dated line per lesson to docs/lessons.md. Tell the user which lessons are worth copying back into site-starter so every future site gets them.

Related Skills