lets-build-a-site

Let's Build a Site

Operating contract

Own intake, architecture integration, implementation, rendered QA, and delivery. Delegate only decisions that need a specialist. Invoke specialists one at a time; verify their artifacts before preserving their decisions.

Inspect available files before asking questions. Never invent identity, claims, prices, testimonials, certifications, metrics, contacts, rights, or promises. Treat publishing, DNS, purchases, analytics activation, real form submission, and other external writes as separate actions requiring explicit authority.

Keep the core workflow tool-agnostic so it runs in Codex and Claude Code. Use host-specific tools only as interchangeable ways to inspect, edit, render, and verify.

Load references progressively

• At every start: read references/intake-and-classification.md before questioning the user or editing the project.
• When the request includes assets, documents, copy, media, or missing content: read references/assets-and-content-gaps.md. Run scripts/inventory_assets.py when manual metadata collection would be repetitive.
• When architecture is not already accepted or a sitemap must be created: read references/architecture-single-vs-multi.md.
• Before invoking a specialist, accepting its return, or reopening an upstream decision: read references/specialist-routing.md.
• Before editing code and again before final QA: read references/implementation-and-quality-gates.md.
• Before creating .site-work, sending a specialist handoff, or writing the final response: read references/handoffs-and-site-work.md.

Do not load all references by default.

Workflow

1. Resolve scope. Identify the project or asset directory, editable boundary, requested outcome, constraints, and whether the deliverable is a prototype, production-ready site, or change to existing code. Inspect repository state and current implementation without mutating it.
2. Inventory before opening. List asset and document metadata, then inspect only shortlisted files and relevant document sections. Record provenance, rights, conflicts, and unsupported material without copying binaries into working notes.
3. Classify independently. State the site goal, single-page or multi-page architecture, and deliverable as three separate decisions with evidence and confidence. Treat labels such as “showcase site” as goals, not architecture choices.
4. Gate missing information. Classify gaps as blocking, important, or optional. Require a real identity or subject, site purpose, intended audience or primary task, and deliverable before implementation; placeholders cannot replace this minimum brief. Ask at most three short questions per round, only after inspection and only when the answers materially change correctness. Proceed with explicit placeholders for other non-blocking gaps; stop at unresolved blocking gaps. Build a speculative generic concept only when the user explicitly requests one.
5. Create compact truth sources. Maintain the relevant .site-work artifacts. Keep facts, observations, inferences, assumptions, unknowns, placeholders, and user decisions distinct.
6. Plan the site. Define content roles, routes or sections, shared templates, navigation, CTA destinations, and completion criteria. Record durable decisions and their reopen conditions.
7. Route adaptively. Use only specialists whose trigger is present. Give each one a single owned question and a handoff of at most 400 words. Record every specialist as used or skipped with a concrete reason.
8. Implement completely. Preserve an existing stack and design system unless blocked. For a new project, choose the simplest stack that satisfies the deliverable. Build the agreed pages, states, responsive behavior, assets, interactions, and safe integration boundaries. Trace every visible factual claim, process, place, material, response expectation, and promise to approved content; do not infer facts from filenames, email domains, or visual tone. Render user-controlled values as text, never executable markup.
9. Render and correct. Exercise the real site at representative project widths and states. Route findings back to their owner, apply the smallest causal fix, and rerun the affected check before expanding regression coverage.
10. Pass the quality gate. Verify the build and rendered result, update qa-report.md, and distinguish pass, fail, not verified, and not applicable. Mark pass only when the report names the executed or observed evidence. Do not claim production readiness when a critical rendered check is unavailable.
11. Deliver. Report the site path, run and verification commands, architecture, coverage, specialist routing, approvals needed, placeholders, disconnected integrations, and concrete residual risks.