The file your agent reads before it touches the theme.
An agent pointed at a HubSpot theme sees the code layer and assumes that's the whole site. It isn't — the content is edited live in the app, the account is the source of truth, and some don'ts are load-bearing. This prompt generates the conventions file that makes those seams explicit — once — so every future session starts oriented instead of guessing.
Copy it, run it in your theme repo
Paste it into an agent session opened in your CMS project. It reads what the repo can prove, interviews you for what it can't — who edits live, what's fragile, what “verified” means here — and drafts the file with every fact labeled by where it came from.
I want a conventions file for this HubSpot CMS project — the file you (and any
future agent) read at the start of every session so nobody re-derives the
project or guesses wrong. This platform has traps a normal web project
doesn't, so the file must capture the seams, not just the commands. Work
read-only: explore and draft the file, but change nothing else.
PHASE 0 — Read the project, then interview me. First map what the repo can
tell you: the project config and platform version, where the theme lives, the
templates and which modules they mount, each module's fields, and how local
dev and deploy appear to work here. Then ask me ONLY what the repo cannot
answer (at most six questions), and WAIT for my answers:
- Who edits this site live in the HubSpot app, and which pages or modules
do they touch most?
- Is my local copy current with the account, or does it drift?
- Which assets feel load-bearing or fragile — the ones nobody wants to
touch?
- Is any page's visibility driven by CRM lists or memberships rather than
the code?
- What does "verified" mean here — how do we check a change actually
landed without breaking a live page?
- Anything an agent must never do in this project without asking first?
PHASE 1 — Draft the conventions file. Write it for an agent reading cold,
with these sections:
- THE SHAPE — platform version, where things live, how templates, modules,
and fields relate, and how to run local dev and deploy here.
- CODE VS. CONTENT — which layer is code we deploy and which is content
edited live in the app; name the modules whose fields already hold live
content, per my answers.
- THE SOURCE OF TRUTH — the account, not this repo: what that means for
pulling before editing, and how current local actually is.
- LOAD-BEARING DON'TS — the specific don'ts for this project, each with a
one-line why. Include at least: don't rename or retype a module field
that live content fills without a migration plan; don't deploy without
checking who edited the affected assets in the app; don't assume a
page's access is in the code.
- VERIFY — the exact steps that prove a change worked here, per my answer.
For every entry, mark it FROM THE REPO (you read it) or FROM THE OWNER (I
told you) so the next reader knows which facts to re-verify and where.
PHASE 2 — Flag the gaps. End with a short list of what the file still can't
answer — the things neither the repo nor I could confirm — as questions to
resolve in the account, not as assumptions written down as fact.
Show me the draft before saving anything. Start with Phase 0 now.It writes down what the repo can't show
It records the seams
A HubSpot theme is code you deploy AND a surface marketers edit live, at once. The file names which is which — module by module — so an agent treats a "small" code change as the live-content change it actually is.
The don'ts carry the danger
The platform's traps — the field rename that orphans live content, the deploy that overwrites a marketer's newer edit — become written project rules with a one-line why, instead of lessons each session re-learns the hard way.
Every fact shows its source
Each entry is marked "from the repo" or "from the owner" — so the next agent (or the next you) knows which claims were read from files and which came from an interview and should be re-verified as the account drifts.
A launchpad, with its sources shown
The shape of the generated file — the project's real layout from the repo, the seams and don'ts from your interview answers, and the honest “still unknown” list at the bottom instead of assumptions written down as fact.
# Conventions — acme-theme (HubSpot CMS-React) THE SHAPE [from the repo] 2025.2 project; theme under src/; templates in templates/*.hubl.html mount modules from components/modules/* (Component / meta / fields) CODE VS. CONTENT Hero, PricingTable fields hold LIVE content [from the owner] → a field rename there = a live-content migration, not a refactor THE SOURCE OF TRUTH The account, not this repo. Marketing edits Tue/Thu. [from the owner] Local drifts — check freshness before any deploy. LOAD-BEARING DON'TS ✗ Never rename/retype a content-bearing field without a plan ✗ Never deploy without checking who edited these pages this week ✗ Never assume page access is in the code (some pages CRM-gated) STILL UNKNOWN — resolve in the account, don't assume ? Which lists gate the /members pages ? Whether the newsletter module is used outside the homepage
What “the project shape” means on CMS-React
The prompt's Phase 0 works because a modern HubSpot project has a well-defined code layer the agent can read. Here's what it finds there — and why the fields are the seam that matters most.
A project declares its platform in hsproject.json (e.g. platformVersion: "2025.2", srcDir); the theme lives under that src dir with theme.json, fields.json, HubL templates, and components/.
A CMS-React module exports Component, meta, and fields — where fields is a JSX tree built from @hubspot/cms-components/fields (or a plain fields object). Those field definitions render the editor UI a marketer fills in — which is exactly why the conventions file treats a field rename as a live-content migration, not a refactor.
Reflects HubSpot as of June 2026 · verify against the linked docs
The file is the artifact. The seams are the skill.
Knowing why each don't is load-bearing — why the account outranks your repo, why a deploy is a publish, why one shared module can fan a typo site-wide — is what the HubSpot CMS module teaches. The conventions file is its compounding artifact: every lesson sharpens what you write down.
Prefer it as a reusable tool? This prompt is the public twin of the kit's /remember skill. The full kit ships with the course.