Build cms

Build CMS

Overview

Retrofit a Webflow-like CMS onto an existing app. The app already has a front end (usually vibe-coded, content hardcoded in components); this skill adds a database-backed content layer, a secure admin UI for editors, and production-grade SEO — then rewires the front end so every content field comes from the CMS.

Core principle: the front end is the spec. You do not invent a content model — you extract it from the existing pages, confirm it with the user, and map every field. A CMS that covers 80% of the site's content is a failed CMS: editors will still need a developer.

Operating Contract — Fire and Forget

This skill runs as a single command (/build-cms) that finishes the job. User input happens at exactly two checkpoints:

1. Interview (Phase 2) — one batched round of questions.
2. Architecture pick (Phase 3) — user chooses from 2–3 proposed options.

After the architecture pick, run Phases 4–9 to completion without asking anything else. Decisions that come up mid-build are made autonomously using the defaults in the reference files and recorded in the final report's "Decisions made" section. The only exceptions that justify stopping: a missing credential/secret you cannot generate, or an action that would destroy existing user data.

Track the phases with your task list so progress is visible, and end with the Final Report (format below) — never with "let me know if you want me to continue."

Branch safety: Phases 1–3 are read-only. Before the first code change (Phase 4), create a cms/build branch and commit at every phase boundary — a failed run must be one checkout away from undone. Never build on the default branch, and never touch files unrelated to the CMS retrofit.

Resumable state: A long build must survive interruption, context loss, or a new session. CMS-BUILD-STATE.md at the repo root is the run's durable memory:

• Create it the moment checkpoint 1 is answered (start from templates/CMS-BUILD-STATE.template.md); update it at checkpoint 2, at every phase-boundary commit, and whenever an autonomous decision is made.
• Sections: Phase (current phase + what's in progress), Branch, Snapshot (location), Interview answers (one line per question), Architecture (the confirmed pick), Decisions made autonomously (one line each — this feeds the Final Report directly), Remaining (unfinished items in the current phase).
• On every invocation, look for this file before anything else. If it exists: the checkpoints are already answered — do not re-interview; verify the branch and FIELD-MAP.md match its claims, announce "resuming from Phase N", and continue. If it contradicts reality (branch missing, files absent), say so and reconcile from what actually exists before proceeding.
• It lives in the phase commits on the build branch. In the final Phase 9 commit, delete it (and the snapshot) — FIELD-MAP.md stays as the durable contract, and a finished build is what extend mode detects on a future run.

The Iron Rules

1. Interview before you build. Complete Phases 1–3 before writing any schema or admin code. Do not scaffold "a reasonable CMS" and adjust later — the answers change the architecture (auth, database, rendering, publishing).
2. No unmapped fields, no empty fields. Produce FIELD-MAP.md before building. Every user-visible string, image, link, and list on every page appears in it, and every field is seeded with the site's current content when wired — the retrofit must not change what visitors see. The build is done only when every row is wired.
3. SEO is built, not stubbed. Editable meta/OG per page, auto-regenerating sitemap, structured data, canonicals, and slug-change redirects ship with the CMS — see references/seo.md.
4. Security is built in, not reviewed in. Every applicable control in references/security.md ships with the build, and Phase 9 actively probes for the failures it lists. An admin panel is an attack surface on a production site.

Workflow

Phase 1 — Discovery (read, don't ask yet)

First check for CMS-BUILD-STATE.md — if present, resume that run instead of starting over (see Resumable state above). Otherwise analyze the codebase: framework, rendering mode (SSG/SSR/SPA), database (or none), hosting, existing auth, media handling, and a full inventory of routes and hardcoded content. → references/discovery.md

Phase 2 — Interview (checkpoint 1)

Ask the question set in references/discovery.md, pre-filled with discovery findings. Covers editors, scope, database, publishing workflow, media, auth, localization, new content types, SEO baseline. One focused round.

Phase 3 — Architecture proposal (checkpoint 2, last user input)

Based on the detected stack, present 2–3 concrete options for where the CMS lives and how it's accessed (embedded /admin, separate admin app, embedded headless CMS; path vs subdomain; extra access layers), each with trade-offs and one marked recommended. → references/architecture.md

Phase 4 — Content model + field map

Design collections, singletons, the shared SEO field group, and global site settings from the front-end inventory. Write FIELD-MAP.md mapping every front-end field to its CMS field — start from templates/FIELD-MAP.template.md. → references/content-modeling.md

Phase 5 — Build the CMS

Check references/stacks/ first — if a playbook matches the detected stack (nextjs-supabase.md, astro.md, sveltekit.md, vite-spa.md), follow its file map, auth wiring, publishing pipeline, and gotchas for Phases 5–7; the generic references still govern what to build. Then: schema/migrations, validated content API, and the Webflow-like admin UI (sidebar of pages + collections, editor with Content/SEO tabs, SERP preview, media library, draft → publish). Security controls (authz on every endpoint, input validation, upload hardening, CSRF, headers) are written with this code, not after it. → references/admin-ui.md, references/security.md

Phase 6 — Wire the front end

Before touching the first page, snapshot the site: run the app and save each route's rendered HTML (curl each route into .cms-snapshot/, committed on the build branch so a resumed session still has it) — this is the Phase 9 parity baseline. Then, page by page: seed first, wire second — insert the page's current hardcoded values into the CMS, then replace the hardcoded code with CMS reads, updating FIELD-MAP.md status as you go. Seeding lives in a committed seed script/migration, not ad-hoc inserts, so fresh environments get the content too. Preserve (or introduce) server rendering — CMS content fetched client-side is invisible to crawlers.

Phase 7 — SEO layer

Implement the full checklist in references/seo.md: meta/OG editing, sitemap, robots, JSON-LD, canonicals, redirect manager with automatic slug-change redirects, alt-text enforcement.

Phase 8 — Hardening + quality gates

Work through the references/security.md checklist item by item, then run the quality gates — all must pass:

• Typecheck and lint clean; production build succeeds.
• Targeted tests for the critical paths: auth guard on mutations, publish flow (draft invisible → published visible), slug-change → 301.
• Admin round-trip by hand: log in → edit → preview draft → publish → change appears on the live page; browser console free of errors.

Phase 9 — Verify + report

• Every FIELD-MAP.md row is wired; grep confirms no leftover hardcoded copy.
• Content parity: diff each route's rendered output against the Phase 6 snapshot — visible content must be identical. The only acceptable deltas are intended additions (new meta/OG tags, JSON-LD); any changed or missing copy is a seeding bug, not a note for the report.
• Run scripts/verify.sh against the running site — it automates the crawler checks (raw-HTML content/meta/JSON-LD, sitemap, robots, soft-404), admin lockdown, unauthenticated-mutation and slug-redirect probes, and the client-bundle secret grep. Exit code = failure count; paste its output into the report.
• Manual security probes it can't do (from references/security.md): disguised-file upload rejected, XSS payload in rich text rendered inert, draft URL blocked without a preview token.
• Final commit: delete CMS-BUILD-STATE.md and .cms-snapshot/ — FIELD-MAP.md remains as the durable contract.
• Deliver the Final Report (the "Decisions made" section comes straight from the state file's log).

Final Report (required structure)

End the run with exactly these sections:

1. What was built — architecture chosen, collections/singletons created, pages wired.
2. Access — admin URL, how to log in, where credentials live (never print a password that should be secret; say where it was stored).
3. Decisions made autonomously — every default applied after checkpoint 2, one line each.
4. Field map — total fields, all wired (or the explicit exclusion list from the interview).
5. Verification results — quality gates, crawler checks, and security probes, with pass/fail evidence.
6. Limitations & next steps — anything deferred, with a recommendation.

Quick Reference

Situation	Do
App is a client-only SPA (Vite/CRA)	Raise in the interview — SEO needs prerendering/SSR; the architecture proposal must include a rendering plan
App has no database	Interview decides: SQLite for simple hosts, Postgres/Supabase for serverless
App already has a database	CMS tables live alongside it, prefixed cms_ — never restructure app tables
User wants only some pages editable	Fine — those pages' fields must be 100% mapped; note exclusions in FIELD-MAP.md
Existing auth in the app	Reuse it with an editor/admin role; don't build a second login
A previous /build-cms run detected (FIELD-MAP.md, cms_ tables)	Extend mode: diff the field map against the current front end and add only what's missing — never drop or rebuild existing cms_ tables
A third-party CMS detected (Sanity, Contentful, WordPress, Payload, Strapi…)	Don't build a competing CMS — surface it at the interview: extend it, migrate off it, or scope this build to the unmanaged parts. User decides
User can't decide at checkpoint 2	Take the recommended option, say so, proceed
Mid-build uncertainty (naming, library choice, field grouping)	Decide using reference defaults, log it in the report — do not ask

Red Flags — Stop

• Writing schema or admin code before checkpoint 2 is answered
• A third round of questions to the user
• Re-asking interview questions that CMS-BUILD-STATE.md already answers
• A phase commit without a matching state-file update
• A page whose content you never inventoried
• "I'll map the remaining fields after the build works"
• SEO fields that exist in the schema but render nowhere
• CMS content that only appears after client-side JavaScript runs
• A mutation endpoint whose only protection is a client-side route guard
• A second CMS being scaffolded next to one that already exists
• A wired page rendering different copy than the pre-build snapshot
• CMS code being written on the default branch
• Ending the run without the Final Report

Common Mistakes

Mistake	Fix
Modeling by content type you imagined, not pages that exist	Extract the model from the route/component inventory
One giant pages table with JSON blobs	Typed fields per collection/singleton — editors need real inputs, not JSON
Slug edits silently 404 old URLs	Auto-create a 301 redirect on every slug change
Admin UI lists raw DB rows	Webflow-like: human labels, grouped fields, SERP preview, publish state
Rich text stored as raw HTML, rendered unsanitized	Store structured rich text, or sanitize server-side with a strict allowlist
Security added as a final review pass	Controls are written with each endpoint/upload/form as it's built (Iron Rule 4)
Fields wired but the database left empty	Seed first, wire second — the site must render its current content from the CMS immediately
Service-role/DB credentials reachable from the client bundle	Server-only env access; verify by grepping the built client output