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.
| Item | Ready when |
|---|---|
.agents/product-marketing.md | Business 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.json | Name, phone, address, hours, maps link match the brief. Copy them from the brief. |
DESIGN.md | Every 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 assets | Logo and photos, or an explicit note that stand-ins are OK for now. |
| Editing | Will the client edit the site themselves? (Affects stage 7.) |
Then fill src/styles/tokens.css from DESIGN.md.
Stage 1: Plan
- 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 andsite-essentials. - Write the copy with the
copywritingskill, then runcopy-editingon 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 insrc/data/(home.json, services, FAQs), not in components. - 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) orservice(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 verdict | Action |
|---|---|
| Ready | Go to gate 2 |
| Needs follow-up, P2s only | Go 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
- Run
npm run check:launchand fix every FAIL. Then filldocs/launch-checklist.md, marking each item done, not applicable, or waiting on someone (say who). - Fill
docs/handoff.mdfor the client. - If the client will edit the site, follow
docs/client-editing.md. - 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.