L07 · Build & preview · 5 min
Branches, pull requests and merging
In one sentence
A branch is a safe draft copy of your project where your agent builds a new task without touching the live main version, and a pull request lets you review the changes and test a private Preview before merging them live.
Think of it like this
Think of editing a restaurant's printed menu while guests are dining. You don't cross out dishes on the menus at the tables (`main`); you print a draft copy (`branch`), let the owner taste the new dish (`pull request` + `Preview`), and only swap the menus (`merge`) once approved.
How it works
In your Definitionrepo (repository)Your project folder plus its full history. Git records each checkpoint so you can go back to any version.Open in the glossary →, the DefinitionmainThe main branch. Whatever is in `main` is what your live site shows.Open in the glossary → branch is the official line of history: whatever is in main is what DefinitionVercelThe service that turns your code on GitHub into a live site, with a Preview for every change.Open in the glossary → shows on your live DefinitionProductionThe live version of your app, the one everyone sees. It comes from `main`.Open in the glossary → website. Because real visitors see main, your agent never builds half-finished work directly on it.
Instead, at the start of each task in your DefinitionplanThe spec split into small tasks, each finished and checkable on its own, in `tasks/plan.md`.Open in the glossary →, your agent creates a DefinitionbranchA safe copy of your project where changes are drafted. `main` is the live one.Open in the glossary → named feature/<short-name> (for example, feature/contact-form). On that branch, it can make commits, experiment, and fix mistakes without affecting the live site.
When the task works locally, the agent pushes the branch to GitHub and opens a Definitionpull requestA proposal to merge a branch, shown on GitHub with its changes and checks, so you can review it first.Open in the glossary → (gh pr create). A pull request is a proposal page on GitHub that shows every changed line, runs automated quality checks (lint, type check, and DefinitiontestA small program that checks your app does what it should, so a fix can't silently break later.Open in the glossary → suite), and asks Vercel to build a private DefinitionPreviewA private test link Vercel makes for each change, so you can try it before it goes live.Open in the glossary → link.
You click the Preview link, try the feature yourself, and decide. Only when you say “publish” or “merge” does your agent run gh pr merge --squash --delete-branch to DefinitionmergeBringing the changes from one branch into another, usually into `main` once approved.Open in the glossary → the finished work into main, clean up the temporary branch, and update Production.
What it looks like in your project
You will never have to create branches or pull requests by hand. Your agent creates the feature/... branch when starting a task from tasks/todo.md, opens the pull request when the task is ready, and shares the Vercel Preview link in the chat so you can click and test it.
Copy for your agent
Show me which branch we are currently on, whether there is an open pull request, and explain what needs to pass before we merge into main.
Quick check · 1 question