Skip to content

New site checklist#

These are the steps in the order that worked. The effort figures come from the first site and are a planning guide, not a quote. Install the plugin first: its scripts cover most of the process, and the parts each site writes for itself are listed on the Tools page.

Before anything else#

  • Install the bb-hubspot plugin in Claude Code (/plugin install bb-hubspot --marketplace thomasjefferson/bb-hubspot), then ask Claude to set up the site: the hubspot-site-setup skill takes it from there.

Access is the long pole, so ask for it on day one and do the rest of week one while you wait.

  • A personal access key on the live portal, for crawls, fetches and File Manager reads.
  • A developer test portal created under the agency's developer account (Enterprise content tier). This is where every upload and page build goes.
  • A HubSpot service key on the live portal with the Content and Files scopes (plus Forms if pages carry forms). Draft pages on live need it, because a personal access key on production only gets read access to the Pages API.

Week one#

  • New repo. Write .gitignore before the first commit: CLI config, .env, crawl cache, backups/. Copy the templates: see the Repo template. Under an hour.
  • Authenticate the dev portal as the CLI default and the live portal by name. Confirm both with hs account list. Fill in hubspot-site.json (Site config) and put the accounts table at the top of CLAUDE.md. Under an hour.
  • Fetch the theme, commit it untouched, tag it prod-baseline. Check that the templates are chassis templates, look for hard-coded HubDB ids, and note any asset folders the theme loads from outside itself. Theme baseline. Half a day.
  • Once the client says go: upload the theme (and any external font folders) to dev, recreate the nav menus from the live trees, and build a smoke-test page through the Pages API. Half a day.
  • Run the crawler, tune its page-type classifier, and take one full-page screenshot per type. Crawl and audit. Half a day.
  • Write DESIGN-RULES.md from the crawl: archetypes, global rules, rhythm recipes, Style-tab cheat sheet, anti-patterns. Design rules. One day.
  • Generate the module catalog. Write annotations for every module that has live usage. Catalog and previews. Half a day.
  • Build the preview site, writing shims for forms, video, menus and blog data as they come up. One to two days.

Week two#

  • Export a copy doc from every live page. Build the generator until every one of them drafts at full QA coverage. Add a numbered rule for every fix a review round asks for. Copy doc to dev page. Two to three days.
  • Publish one page end to end on dev. This is where the Pages API surprises show up. Half a day.
  • Rebuild the first module on the shape of the reference module and preview it locally. One day.

After that#

  • Write the Style tab convention and its linter once two rebuilt modules exist. Rebuild the high-usage modules as prefixed parallel modules, each with a showcase page on dev. Module conventions. One to two weeks.
  • Set up the visual-regression snapshot and compare before the first module upload to live. Going to live.
  • Add a draft-only live mode to the publisher, run by the service key.
  • Keep the dated log in CLAUDE.md current: every upload, every publish, every page id.