# Running a Project With an Agent

Every step you run on your own machine, in order, from an empty plan to a page
that is live. Follow it in class, and follow it again on your own project.

The example repo here is your personal site, `<your-github-username>.github.io`.
For a project repo, the steps are the same and only the folder changes.

## Before you start

1. Open the repo folder in VS Code: **File > Open Folder**, then pick it. The
   folder name shows in the title bar, and every step below happens inside it.
   **No folder on your machine?** Clone it first: GitHub Desktop,
   **File > Clone repository > GitHub.com**, pick it from the list, accept the
   folder it suggests, then **Open in Visual Studio Code**.
2. Open the Chat view from the chat icon in the title bar, or with
   `Ctrl+Alt+I` (Windows) or `Cmd+Option+I` (macOS).
3. Pick **Sonnet 5 (Babson)** in the model picker at the bottom of the chat box.
   If it is not in the list, look for a session target dropdown beside it and
   set that to **Local** first. Recent VS Code versions have that dropdown and
   older ones do not. The key itself is set up in
   [Your Babson AI Key](/guides/babson-ai-key/).
4. Set the role to **Agent**, in the same row, and keep it there. Agent creates
   files and runs commands. **Ask** only talks, which is what you want while
   reading code.

## Step 1: work on a branch

Your live site keeps serving what it serves now, and today's work happens
somewhere else until you are ready.

Type this in the chat:

```
Create a new branch called redesign and switch to it.
Do not change any files. Tell me the command you ran.
```

VS Code will ask you to approve the command before it runs. **Read it, then
approve it.** The bottom left of the window now says `redesign` instead of
`main`.

## Step 2: write PROPOSAL.md yourself

No AI in this step. Create a file called `PROPOSAL.md` at the top of the repo
and write five sentences:

- Who this site is for
- The one thing a visitor should do
- The sections you need
- What content you have, and what is missing
- Two or three sites you like, and what you like about each

Sketch the main page on paper, photograph it, and save the photo in the repo as
`sketch.jpg`. The AI agent uses it when it builds. The interview below works
without it, so do it now or do it the same evening.

## Step 3: let the agent interview you

1. Start a **new chat** with the `+` button. Stay in **Agent**: the prompt
   below tells it not to touch a file until you say so.
2. Drag `PROPOSAL.md` from the Explorer into the chat box, and the sketch too
   if you have it.
3. Paste the prompt from [From a Proposal to a PRD](/guides/prd-interview/).
4. Answer one round at a time. **Change at least one recommended answer in
   every round**, or say why you accept it.

## Step 4: save PRD.md and cut it

1. Type `write it`. It creates `PRD.md`. Read the whole thing on screen.
2. Delete anything you did not decide. There is usually something.
3. Commit `PROPOSAL.md`, `PRD.md` and `sketch.jpg`. In the Source Control tab,
   write a message, then **Commit**.

## Step 5: write the rules in AGENTS.md

`AGENTS.md` sits at the top of the repo and your agent reads it on every
request, so you stop repeating yourself.

Type `/init` in the chat. It reads your repo and writes a first version. If it
offers `.github/copilot-instructions.md` instead, ask for `AGENTS.md` by name.

Read what it wrote before you keep it. It is guessing at your project from the
files that happen to be there, so check that every command and path it names is
one this repository actually has.

Then **cut it down to about five rules**. A long list gets followed less
carefully than a short one. Something close to this:

```markdown
# How this site is built

- Static site only: HTML, CSS, and a little plain JavaScript. No frameworks,
  no build step, no npm, no server.
- If a request needs a server, a database, logins or payments, stop and tell
  me, then add it to the Later list in PRD.md.
- Styles live in css/styles.css. Use only the custom properties in its :root
  block.
- Build only the pages listed in PRD.md. Ask before adding a page or a section.
- File and folder names: lowercase, hyphens, no spaces.
```

Commit it.

## Step 6: build the home page

1. Ask for one page: *"Read PRD.md and my sketch, then build the home page."*
   For a bigger job, type `/plan` first and it writes the steps without
   touching your files.
2. Read the plan. Change one thing in it.
3. Select **Start Implementation** and pick the Agent role.
4. Wait. If it stops and asks to continue, say continue.

## Step 7: read what it wrote

Each changed file shows **Keep** and **Undo**. Go through them one at a time.

- **Keep** the ones you have read.
- **Undo** anything you did not ask for, such as a page that is not in
  `PRD.md`.
- If the whole round went wrong, hover your request in the chat and select
  **Restore Checkpoint**. That puts the files back the way they were.

Then pick one line of CSS you do not recognize and ask about that line alone:
*"What does `display: flex` on `nav` do, and what breaks if I delete it?"*
Delete it, look at the page, and put it back.

What surprises people: staging a file in Source Control accepts every pending
edit at once, so review before you stage. And Restore Checkpoint puts files
back, without undoing a command the agent already ran.

## Step 8: check it

1. Right-click `index.html` in the Explorer and choose **Open in Integrated
   Browser**. The page reloads by itself when a file changes.
2. Open the browser tab's overflow menu and choose **Show Emulation Toolbar**,
   then pick a phone size. Look at the page yourself.
3. **Start a new chat** with `+`, drag in `PRD.md` and `index.html`, and ask:

```
For each item under Checks in PRD.md, open index.html and say pass or fail,
and quote the line that shows it. Do not change any files.
```

Step 3 happens in a new chat on purpose. The one that built the page remembers
adding a nav, so asked whether the nav is there it answers from that memory
instead of reading the file. A fresh chat has the file and the checklist and
nothing else. It is still the same model reading the same page, so step 2, where
you look at it, is the part nobody can do for you. Take the failures back to the
chat that built the page.

## Step 9: commit and publish the branch

1. In the Source Control tab, select the sparkle icon to generate a commit
   message, then **edit it until it is true**.
2. **Commit**, then **Publish Branch**.
3. Your live site is unchanged. The work is on GitHub, on the `redesign`
   branch.

Commits that contain agent-written code carry a `Co-authored-by:` line. Leave
it there.

## When the site is ready

Merging puts the new version on your live site in place of the old one. Look at
what changes before you do it.

Ask the agent:

```
Compare main and redesign. List every file that is on main but not on
redesign, and every file on both that changed. For each one, say in one line
what the old version has that the new one does not.
```

Ask for that list. A line-by-line comparison does not help you here: when an
agent has rebuilt a page from scratch, every line counts as removed and every
line counts as added. The list of what the old version holds is what tells you
whether you are giving anything up.

**Optional, and only if you want the old site to stay one click away.** After a
merge the old version is still in your history, but GitHub Pages can serve a
branch and nothing else, so give the old version a branch name first:

```
Create a branch called v1 from main, and push it. Do not change any files.
```

Do this once.

Then merge:

```
Merge redesign into main and push.
```

Your live site updates a minute or two later. To put the old version back, open
Settings, then Pages, and choose `v1` under Source.

## Take it back to your client

A site built for someone else gets a second conversation once the first version
is live. Book it as soon as the site is deployed, because the date depends on
your client.

Before you meet, read the Later list in your `PRD.md`: the features you have not
built yet. Your client will put them in order.

In the conversation:

1. Send the live URL and ask your client to open it on their own phone. Watch
   where they tap first and where they stop.
2. Ask what they would change. Write down their words as they say them.
3. Read those features to them and ask them to rank them: what they would use
   first, and what can wait.

If your client does not reply, write to them again a few days later. If they
still do not reply, work from the feedback your classmates wrote about your site
at the showcase.

Before you build anything from the Later list, set the role to **Ask** and have
the agent lay out the options:

```
My client wants <the feature, in their words>. List two or three ways to
build it on this site. For each one, tell me what it needs: a service or an
account, what it costs, how much code, what my client has to do, and what
can go wrong. Do not write any code yet.
```

Pick one and write down in one line why you picked it. Then build it on a branch
as in Step 1, and merge it when it works. If an approach does not work out, write
down why you stopped before you try another.

What to commit from this conversation is on the checkpoint list on Canvas.

## If something goes wrong

| What you see | What to do |
|---|---|
| The Babson model is missing from the picker | The session target is not **Local**. Change it, then reopen the picker. Still stuck? Run the interview in any browser chat, then create `PRD.md` in the repo yourself and commit it |
| The agent will not create files | The role is **Ask**. Switch it to **Agent** and ask again |
| It edited a file you did not mention | **Undo** that file, then add a rule to `AGENTS.md` naming what it may not touch |
| It wrote code you cannot read | Ask it to explain a single line. Then change one value and see what happens |
| The page looks unstyled | Open the `<link>` tag and check the path against where the CSS file actually sits |
| You are lost in a long chat | Start a new chat. One task, one chat: `PRD.md` and `AGENTS.md` carry the context, the conversation does not |