--- name: playbook-project-setup type: playbook description: "The prescribed sequence for standing up a new project of any kind, not only a website: a short intake interview that establishes the configuration (website or not, public or private, framework, CMS, hosting, domain and staging, which services and environment variables), then the setup itself in order — repository and branch protection, CI, deployment project and environments, environment variables and secrets, and the content and analytics services the configuration calls for. Read and follow this whenever a new project is being stood up, so the shape is the same each time and nothing is improvised. Composes convention-github, convention-vercel, convention-secrets, convention-sanity, convention-mux and convention-analytics rather than restating them, and names which steps a session can drive itself and which need the Owner's own hands." license: CC BY-NC-SA 4.0 --- # Project setup The prescribed response when the Owner says a new project needs standing up. It composes the platform conventions rather than restating them: every rule about how a repository, a deployment, a secret or a content service is configured stays in its own `convention-*`, and this playbook holds only the order, the intake that decides which steps apply, and the split between what a session drives and what the Owner must do himself. ## Trigger The Owner says a project needs setting up, or a delivery ticket arrives for a repository that does not exist yet. Not every setup is a website: an app, a bot or a tool reaches this playbook on the same words and skips the steps its configuration does not call for. ## Step 1 — Intake interview, before anything is created Establish the configuration first, in one short exchange, because half the later steps are conditional on it: whether the project is a website or not; public or private; the framework; whether it needs a CMS, video, or analytics; where it deploys; whether it needs a domain and a staging environment; and which services and environment variables follow from those answers. Record the answers on the setup ticket before the first write. An intake skipped is paid for later as a repository with the wrong visibility or a deployment wired to the wrong branch, both of which cost an Owner action to undo. ## Step 2 — Repository and branch protection Create the repository at the visibility the intake fixed, then apply the ruleset and required checks as `convention-github` holds them. Two points the retired website checklist got wrong and this playbook does not repeat: the merge label is whatever `convention-github` currently names, never a label carried over from an older sequence; and required checks are enforceable on the current plan, so they are configured rather than noted as unavailable. ## Step 3 — CI, proved red before it is trusted green Add the pipeline the framework needs, then prove it can fail before accepting that it passes: a green pipeline that cannot go red is not a gate. `convention-github` holds the prove-it-red step and this playbook only sequences it — after the repository exists and before the first deployment is wired. Give the workflow its concurrency group and its per-leg timeout at this point rather than later (`convention-github`, *Billed minutes are part of standing up or changing a workflow*): both are cheaper to write once than to retrofit. ## Step 4 — Deployment project and environments Create the deployment project, connect it to the repository, and set the production branch and preview behaviour per `convention-vercel`. Where the Vercel connector is attached to the surface in hand, a session creates the project, its build configuration, its environment variables and its domain itself. Two things stay the Owner's: granting the deployment platform's GitHub app access to the new repository, which is a settings change needing his own yes per action; and confirming the production URL once the project is live. ## Step 5 — Environment variables and secrets Take the variable names and shape from `convention-secrets`. The split is absolute and is not a preference: client-safe `NEXT_PUBLIC_*` values a session may set itself; every secret value — an API key, a token, a signing secret — is entered by the Owner, never typed, pasted or relayed by a session, and never read back to confirm it. ## Step 6 — The services the intake named Only now, and only where step 1 called for them: content per `convention-sanity`, video per `convention-mux`, measurement per `convention-analytics`. Each is configured to its own convention; this playbook adds nothing to them but the position in the order. ## Step 7 — Close out Record what was created against the configuration from step 1, name every step the Owner performed, and state which steps the intake made inapplicable rather than leaving them silently unticked. A setup whose skipped steps are unexplained reads identically to an unfinished one. ## Guardrails - Never type, paste or relay a secret value. The Owner enters every one. - Never create a repository or a deployment before the intake has fixed the configuration. - Never restate a rule that a `convention-*` owns; cite it and move on. Where this playbook and a convention disagree, the convention governs and the disagreement is a friction note. - Never treat a step as inapplicable without saying which intake answer made it so. - Check the surface in hand for each connector the sequence needs rather than assuming it, and record which steps were driven by a connector and which by the Owner. - `playbook.website-build` refers to this playbook for the setup sequence and carries no copy of it. Where that document and this artefact diverge, this artefact governs and the document is corrected (Owner ruling, 2026-09-30 — APP-1889). ## Tone Calm, precise, sentence case, British spelling, no exclamation marks, outcome before adjective.