# From Brief to Working Site: The Vibe Coding Workflow > Source: https://agilitycms.com/docs/developers/vibe-coding-workflow This is the workflow behind the proof-of-concept builds described in [Vibe Coding with Agility](/docs/developers/vibe-coding-with-agility). It takes you from whatever brief you have (a discovery call outline, an RFP, a scoring spreadsheet, a call transcript) to a deployed Agility site that editors can preview and edit in Web Studio, plus the script you need to show it. It assumes you've connected the Agility CMS MCP server and the Agility Knowledgebase MCP server to your AI coding tool. If you haven't, follow [Building an Agility Site with AI Coding Tools](/docs/developers/building-sites-with-ai-coding-tools) first. ![The vibe coding workflow in ten steps and three phases. Plan: turn the brief into a feature map, then pick a starting point. Build: model content through the MCP server, seed real content and record provenance, build components and pages, apply the brand. Show: wire preview, Web Studio and the publish webhook, deploy and dry-run, write a timed demo script, write handoff notes. AGENTS.md is updated with every ID throughout.](https://cdn.aglty.io/agility-cms-docs/images/developer/vibe-coding-workflow.svg) > [!NOTE] > The times below are typical of the builds this workflow comes from. They are a guide for planning, not a promise. Expect your first build to take longer. ## 1. Turn the brief into a feature map **Typical time:** 1 to 2 hours. Before any code, have the AI tool turn the brief into a plan document with one row per ask. Each row says how important the ask is, the mechanism that delivers it (a content model, a component, a shared block, a personalization rule, or "talk track only, not built") and the URL where it can be seen once it's built. Anything the brief says isn't needed goes in a "deliberately left out" list. Cap the build at four to six headline features. Every extra feature costs build time, and more importantly demo time. ```text Read the brief in docs/brief/ and write docs/plan.md. Make a table with one row per requirement: requirement, priority, mechanism (content model, component, shared block, personalization, or "talk track only, not built"), and the URL where it will be visible. List anything the brief marks as not needed under "Deliberately left out". Recommend at most six headline features. Don't write any code yet. ``` Review this plan yourself. It's the cheapest place in the whole workflow to cut scope. ## 2. Pick a starting point **Typical time:** minutes. Don't start from a blank folder. Copy the closest thing you've already built and keep its plumbing: the data layer with cache tags, routing, preview, the revalidation webhook, the component registry, typed environment variables and the `AGENTS.md`. If you don't have a previous build yet, start from the [Agility Next.js Starter](https://github.com/agility/agilitycms-nextjs-starter), which gives you all of that on Next.js 16 with the App Router. Then remove what belongs to the previous project: its components, its sample content assumptions, its brand. Leftovers from a previous build are easy to miss, so ask for a cleanup pass explicitly. ```text This repo was copied from a previous Agility build. Keep the data layer, routing, preview, the revalidate webhook, the component registry and the env module. List every component, page model assumption, brand asset and piece of copy that belongs to the previous project, and remove them. Update AGENTS.md so it no longer describes the old project. ``` ## 3. Model the content through the MCP server **Typical time:** 1 to 3 hours. Some setup is still done by a person in the Agility app: creating the instance, API keys and the sitemap. Once those exist, the AI tool can create content models, containers and component models through the MCP server. Create the page model and its content zones through the MCP server (with `save_page_model`), or in the Agility app. Two rules keep this step clean: - **Map every component model field 1:1 to a React prop.** The component then has no translation layer to get wrong. - **Record every ID as you go.** Each model, container, component model and seed content item goes into the instance ledger in `AGENTS.md` the moment it's created. See [Writing an AGENTS.md for Agility Projects](/docs/developers/agents-md-for-agility#keep-an-instance-ledger). ```text Using docs/plan.md, design the content models and component models for the headline features. Before creating anything, list the existing models (get_content_models, get_component_models) and reuse any that fit. Show me the proposed models and fields first. After I approve, create them through the Agility MCP server, read each one back to confirm the real field names, and add every model, container and component model ID to the ledger in AGENTS.md. ``` Read [MCP and Agility Gotchas](/docs/developers/vibe-coding-gotchas) before this step. Several of the gotchas there, such as normalized reference names and saves that blank omitted fields, show up here first. ## 4. Seed real content, and record where it came from **Typical time:** 1 to 3 hours. A site filled with the project's own content is far more convincing than one filled with placeholder text, and it tests your content model against reality. Have the AI tool import the public content you have permission to use, upload the matching media, and save it all as content items. Keep a provenance file. For every piece of content, record whether it came from the source (and when it was collected), was written new, or is invented sample data. That file keeps the demo honest and tells the next person what has to be replaced. ```text Import the public pages listed in docs/sources.md into the models we created. Upload images to the media library and use the returned URLs. Save items with null release and pull dates. Don't publish anything. Write docs/content-provenance.md listing each item, its source URL, the date collected, and whether it is copied, rewritten or invented. Add the seed content IDs to the AGENTS.md ledger. ``` For large or structured imports, script the transformation instead of pasting content into the conversation. [Migrating Content into Agility with an AI Agent](/docs/developers/migrating-content-with-an-ai-agent) covers that in depth. ## 5. Build the components and pages **Typical time:** a few hours. Build one async server component per component model and register it, following the starter's pattern: the component receives its content ID, fetches its own fields through the project's data layer (so the request gets a cache tag), and fetches any linked list separately by reference name. Every rendered field carries its Web Studio attribute from the start, because retrofitting them later is slow. ```text For each component model in the AGENTS.md ledger, build a server component in components/agility-components/ following the existing component pattern, and register it. Use the data layer for every read. Add data-agility-component on the root, data-agility-field on every rendered field and data-agility-nested-listitem on each list item. Then create the pages in docs/plan.md on the Main page model and add the components to them. Run npm run build and fix any errors. ``` ## 6. Brand it **Typical time:** under an hour. Apply the brand's colors, fonts, logo and favicon as CSS custom properties, and make every component read its colors from those variables. For a demo, this is the single biggest lever for making a site feel custom for the effort it takes. ```text Apply the brand from docs/brand/: define the colors and fonts as CSS custom properties in the global stylesheet, swap in the logo and favicon, and replace any hard-coded colors in components with the variables. Check text contrast against WCAG AA and list anything that fails. ``` ## 7. Wire preview, Web Studio and the publish webhook **Typical time:** about an hour, plus fixes. This is what makes the site an Agility site rather than a static mockup: - **Preview** uses draft mode and the preview API key, so editors see saved changes before publishing. See [Setting Up Preview](/docs/developers/setting-up-preview) and [Preview URL Lifecycle](/docs/nextjs/preview-url-lifecycle). - **Web Studio** relies on the `data-agility-*` attributes from step 5. Expect a round of fixes: a wrong attribute opens the wrong editor or lets an edit overwrite the wrong text. [Agility Decorate](/docs/developers/agility-decorate) can add and check the attributes for you. - **The publish webhook** calls your revalidate route so a publish shows up on the live site in seconds, without a rebuild. See [Webhooks](/docs/developers/webhooks). Keep the webhook's signature check in place even for a demo. If you do switch it off to get unblocked, write that down in `AGENTS.md` as something to restore. See [Verifying Signed Webhooks](/docs/developers/verifying-signed-webhooks). ## 8. Deploy and dry-run **Typical time:** about an hour. Deploy to your host, set the environment variables, register the webhook and the preview deployment in Agility, then rehearse the whole demo: - Use a fresh incognito window, so no draft-mode cookie hides a problem. - Check the site against the **published** fetch key. In development the starter uses the preview key, so "it works locally" can hide content that was never published. - Publish a change and watch it arrive. If it takes about a minute instead of seconds, the cache tag your data layer sets and the tag your webhook revalidates don't match. ## 9. Write the demo script **Typical time:** half a day or more. A demo needs a script as much as a site. Split it into timed acts, each with one point to make, the URLs to open, and what to click. Add pre-flight checks, how to reset content between runs, and a fallback for each act if something fails live. ```text Write docs/demo-script.md as a run of show for a 30-minute demo. Split it into timed acts, one per headline feature in docs/plan.md. For each act give the point it makes, the exact URLs, the clicks and the edits to make in Agility or Web Studio, and a fallback if it fails. Add a pre-flight checklist and steps to reset the demo content. ``` A strong finale is to edit live content with a prompt through the MCP server and show the change arrive on the site. ## 10. Write the handoff notes **Typical time:** after the demo. Whoever picks the project up next (a colleague, a partner, the customer's developers, or you in three months) needs to know what's real. Write a short handoff document covering: - The instance ledger: every model, container, component model and content ID. - What is simulated: mocked sign-in, mocked membership lookups, sample data, external systems that were faked. - What was deliberately left out, from the feature map. - The gotchas you hit, so they go into the next build's `AGENTS.md`. - What has to change before production. Start from [From Proof of Concept to Production](/docs/developers/vibe-coding-to-production). ## Related - [Vibe Coding Playbooks by Use Case](/docs/developers/vibe-coding-playbooks): content model ideas and starter prompts for common use cases. - [Writing an AGENTS.md for Agility Projects](/docs/developers/agents-md-for-agility) - [MCP and Agility Gotchas to Know Before You Build](/docs/developers/vibe-coding-gotchas)