Capstone (weeks 6–8)

Build, secure and ship a full-stack web app of your choice. An AI agent does much of the typing. You do the directing, the checking and the explaining.

Item	Details
Weeks	6–8. The pitch is due 72 hours before week 6 Studio A
Solo or pair	Either. Pairs take on a bigger scope and are examined individually (details)
Starter	projects/capstone-starter/ · how to start from a starter · feature patterns
Repo	Its own repo on your personal GitHub account, named after what it does, for example study-buddy. Create it before week 6 Studio A
Hosting	Vercel, plus Supabase if your app stores data that more than one person shares. Current tools and fallbacks: Tool Handout
Due	Pitch, Milestone 1 (end of week 6), Milestone 2 (end of week 7) and Final (end of week 8): see Milestones
Graded as	Capstone rubric (30% of the course). Milestones 1 and 2 are your week 6 and week 7 homework. Also walkthrough 2, walkthrough 3 and your final reflection
Step-by-step labs	Week 6 · Week 7 · Week 8

What you'll build

A web app at a production URL (the main, permanent web address of your deployed app) that solves a real (small) problem for a real (possibly imaginary) user, built from your own spec with an AI agent: an AI that edits files and runs commands in your repo while you supervise. It follows the Safe Loop the whole way: describe, plan, one small step, test, read the diff, commit. Two habits make the loop safer: check first (write the test before you ask for the code, in a separate prompt) and teach back (before you commit AI-written code, write 2–3 sentences in PROMPTS.md saying what changed and why).

The capstone is graded mostly on how well you specified, tested, secured and documented your app, and whether you can explain it. A working demo is required, but it isn't enough on its own. That's deliberate: AI makes it easy to build a demo that works once, and much harder to build something that handles the edge cases (Utah CS 3960).

Stuck for an idea? See Capstone Ideas.

Milestones

Every capstone deadline and deliverable is defined here, once. Week READMEs and homework pages copy these rows word for word. Unless Canvas (the course's learning management system) says otherwise, each is due before the next week's Studio A (default 11:59 pm the night before).

Milestone	Due	Deliverables	Graded as
Pitch	72 hours before week 6 Studio A. Your instructor replies Go, Shrink or Rethink before Studio A	• The pitch, on Canvas (🟡 AI limited: the AI may critique it, not write it) • Before Studio A: your capstone repo created from the starter on your personal account, opened in a Codespace, with npm test passing	Part of your week 5 score (AI micro-app rubric, pitch row)
Milestone 1: walking skeleton (end of week 6)	Before week 7 Studio A	• SPEC.md complete, with a Goldfish test logged in PROMPTS.md and the revision it led to • AGENTS.md edited for this project, with a Scope section, and trial notes in PROMPTS.md (two small tasks, whether the agent followed the file, one change you made to it) • At least two features merged through pull requests, each with an automated test written before the code • Deployed: a working production URL on Vercel, plus a screenshot of it, on Canvas • PROMPTS.md with an entry for each agent session and a teach-back before each agent commit	Week 6 homework (weekly rubric)
Milestone 2: feature complete (end of week 7)	Before week 8 Studio A	• Your second feature type working, for example Supabase with row-level security, its grants and policies saved in supabase/policies.sql • SECURITY_CHECKLIST.md with evidence for every ticked item • Peer review given: your written review of a classmate's capstone, on Canvas • Response to the review you received: what you changed (link the commits or pull request) and what you decided not to change, and why, on Canvas • Handoff test: a classmate tried one small change using only your README and AGENTS.md; you fixed what confused them and noted it in PROMPTS.md	Week 7 homework (weekly rubric); the peer review in Reflections and peer reviews
Final (end of week 8)	Posted on Canvas: a few days after the Project Fair, and before the University's grade deadline	• Everything in What done means • A GitHub release v1.0 on your final commit • On Canvas: the production URL and a screenshot of it working, the repo URL and the link to the v1.0 release • A 2–3 minute demo video, linked from the README or submitted on Canvas • Your final reflection on Canvas (🔴 AI off), with your revised personal AI-use rules	Capstone rubric; the final reflection in Reflections and peer reviews

The milestones exist so you get feedback while there's still time to act on it. Milestones 1 and 2 are checked for completion; the capstone rubric judges the finished app.

Along the way (graded elsewhere): oral walkthrough 2 in week 6 and walkthrough 3 in week 8; your weekly reflections and exit tickets; the 🔴 AI-off maintenance task on your own capstone in week 7 Studio B; the Project Fair in week 8 Studio B.

Handoff test access: your classmate opens your public repo in their own Codespace and tries the change there. They can't push to your repo, and they don't need to. If your repo is private, add them as a collaborator for the week, then remove them.

Deploy on day one, even if the app is just the starter. Deployment problems are much easier to fix early; students in other courses reported that deployment took more time than coding (CMU 15-113 Student Wisdom report). Submit the production URL, not a preview link: Vercel deletes old preview deployments (Tool Handout).

The pitch

Due 72 hours before week 6 Studio A, on Canvas (Canvas shows the exact time). It takes about 30 minutes, and it saves you from spending three weeks on an idea that can't be finished. 🟡 AI limited: you write it; an AI may critique it ("What's the riskiest part? What's missing from my out-of-scope list?").

Copy this template, fill it in and submit it on Canvas:

# Capstone pitch: [working title]

**Name(s):** [your name, and your partner's if you're a pair] · **Solo or pair:** [solo / pair]

## Problem and user
One paragraph (4–6 sentences): who has what problem, why it matters to them,
and how your app will help.

## Sketch
A photo of a paper sketch of the main screen, or a text sketch.

## Feature types (at least two; pairs at least three)
- [ ] (a) Server-side API call with a hidden key: what for?
- [ ] (b) Database with access rules and/or sign-in: what data, and who may see or change it?
- [ ] (c) Data visualization: what chart, of what data?
- [ ] (d) External public API: which one, does it need a key, and what for?

Which starter feature patterns will you use? [db.js and policies.sql / chart.js / weather.js / the AI route]

## Out of scope
At least three things you will NOT build.

## Biggest risk
The one thing most likely to go wrong, and your plan B.

Your instructor replies before week 6 Studio A with one of:

• Go: build it as pitched.
• Shrink: go, with a smaller scope (your instructor suggests what to cut). Most pitches need some shrinking. See how to shrink an idea.
• Rethink: let's talk before you start.

Pairs who want two feature types plus a scope increase (instead of three feature types) ask for it in the pitch; the reply says whether it's approved. If you use a grace token on the pitch, the reply may come at the start of week 6 Studio A.

Requirements

Feature types: include at least two

Your app must include at least two of these four (pairs: see below). Each one has a tested pattern in the starter that you can copy and adapt; the starter README explains each one.

	Feature type	What it means	Example	Pattern in the starter
(a)	Server-side API call with a hidden key	A route in api/ calls a service that needs a key. The key lives in environment variables, never in public/	An LLM feature: summarize, classify, suggest, quiz	api/ask.js with lib/llm.js (the same route as week 5)
(b)	Database with access rules and/or sign-in	Data saved in a database, protected by row-level security (RLS: database rules that decide who can read or change each row), and/or user accounts (authentication: proving who you are)	Each user sees only their own entries; anyone can add to a guestbook, but only the owner can delete	public/config.js (copied from public/config.example.js), public/lib/db.js and supabase/policies.sql (week 7 Studio A worked example)
(c)	Data visualization	A chart or diagram drawn from your app's own data	A bar chart of study minutes per week	public/lib/chart.js: an SVG bar chart with no dependencies, and a tested function that prepares the data (week 6 feature clinic)
(d)	External public API	Your app fetches live data from someone else's public service	Weather, books, public holidays, open city data	api/weather.js: a server route that calls a public API with no key, tested with a fake (mocked) response (week 5 mini-lesson, week 6 feature clinic)

One piece of work counts once. If a weather service needs a key and you call it through your server, count it as (a) or (d), not both. Check a public API's terms and whether it needs a key before you pitch it.

Charts and other libraries: the starter's chart.js draws with plain SVG and adds nothing to install. If you want a library instead, check it like any new package (safety contract, rule 6) and ask your instructor first.

IMPORTANT

Not every key is a secret. Your Supabase project URL and publishable key go in public/config.js, where every visitor can read them. That's by design, and it's safe only with row-level security switched on for every table, with policies that say who may do what. Secret keys (an LLM key, a Supabase secret key) live only in server environment variables: .env in your Codespace and the project settings on Vercel, never in public/. Use publishable and secret keys; the older anon and service_role keys are being retired (Tool Handout).

WARNING

Grants and row-level security go together. New Supabase tables need an explicit grant before the API can see them (Tool Handout). If you hit "permission denied", don't fix it with a bare grant to anon (an agent's favorite shortcut): that makes the table public. Add the grant, switch on RLS and write the policies in the same change, and keep all three in supabase/policies.sql.

Deliverables

All of these, in one repo (the starter already contains adapted templates for the documents), except the items marked Canvas:

Deliverable	What it must contain
Production URL	The deployed app. It works in a private window, on a phone and a laptop. Submit it on Canvas with a screenshot of it working
Repo	All code and documents, with a history of small commits, including commits before and after agent tasks. Commits made with AI help end with an Assisted-by: [tool] line. Features merged through pull requests
README.md	From the template: production URL, screenshot, demo video link, how to use it, how it works, where authorization is enforced, where each key lives, status against the spec, an honest Known issues section, the tools you used and any fallback you switched to, credits. Pairs: a Contributions table
SPEC.md	Your spec (🟡 AI limited: you write it; the AI may critique it), with testable WHEN … THE APP SHALL … criteria, including edge cases, and at least one criterion for each feature type you chose. Revised after a Goldfish test: paste only SPEC.md into a fresh chat, and if it can't understand what to build without asking you, improve the spec
AGENTS.md	Instructions for your agent, edited for this project (not the unchanged template), with a Scope section that says which folders and tasks the agent may touch. Template. Remember that AGENTS.md is advice, not enforcement: the agent can ignore it
PROMPTS.md	Your key prompts and agent sessions; a teach-back before each agent commit; your Goldfish test and AGENTS.md trial notes; what the agent got wrong and how you caught it; and the ownership statement under "What I wrote or decided myself" (specific code, decisions and changes). Template
TESTS.md	At least 3 automated tests that pass with npm test, written before the code they check, and at least 3 manual edge-case tests with dated results. Template
SECURITY_CHECKLIST.md	Every applicable item ticked, each with one line of evidence. Template
supabase/policies.sql	If you chose (b): the grants, enable row level security and policies for every table
Demo video	2–3 minutes (what to show)
Final reflection	🔴 AI off, on Canvas (prompts)

Automated tests are code that checks your code (tests/*.test.js, run by npm test). Keep testable logic in public/lib/ (or lib/ for server-only code), as in the starter, so tests can import it. Tests must not need the internet or a real key. Manual tests are steps a person follows in the browser.

npm test
npm run check:secrets
npm audit

npm run check:secrets scans your files and your git history for keys. npm audit checks your dependencies for known problems.

Demo video

Two to three minutes, recorded in week 8 Studio A, which lists free built-in screen recorders. Tell it as a story:

About	Show
15 seconds	Problem: who it's for and what it solves
60–90 seconds	Demo: the main task, live, including your feature types and one edge case handled well (empty input, an error)
20 seconds	How: one line on how it's built, and where the data and secrets live
20 seconds	What broke and what you learned: one honest moment

• Upload it as an unlisted video and link it in the README, or submit it on Canvas only and write "Demo video: submitted on Canvas" in the README. A link in a public README can be found by anyone.
• Speak over it or add captions. Automatic captions are fine if you fix the mistakes.
• If recording or speaking is a barrier, a written script with screenshots is accepted instead (accommodations).
• Use made-up data only. Never show .env, your hosting or database dashboards, API keys or real people's information.
• Pairs: both partners speak (or both write part of the script).

Final reflection

🔴 AI off. Write it yourself, 400–600 words, and submit it on Canvas, not in your repo. Use the reflection template as a starting shape. This one has a specific job: compare how much you felt you understood while building with what you could actually explain afterward. Anchor it in concrete moments (a prompt, a commit, an error, a walkthrough question, an agent claim you checked):

1. A time you felt you understood something but couldn't explain it later (in a walkthrough, or while fixing a bug).
2. A time it went the other way: you doubted yourself, but could explain it fine.
3. One habit from the Safe Loop that changed how you work.
4. Your revised personal AI-use rules. Paste the rules you wrote in week 1, then your revised version from week 8 Studio B, and explain one rule you changed and why.
5. What you'd tell a friend starting this course.

Before you write, look back at your answers to the pre-course self-assessment on Canvas, and take the post-course one in week 8 Studio B. The full instructions are in the week 8 homework.

Working solo or in a pair

Solo is the default. Pairs are welcome, with these rules:

• Bigger scope. Pairs include at least three of the four feature types, or two plus a scope increase your instructor approves at the pitch.

• Both partners build. Each partner commits their own work under their own GitHub account. Work on branches, and merge through pull requests reviewed by the other partner.

• Contributions table in the README, using GitHub usernames, not real names:

  ## Contributions
  
  | Area | Mainly built by | Key pull requests |
  |---|---|---|
  | Sign-in and RLS policies | @[username-1] | #4, #7 |
  | LLM summary route | @[username-2] | #5 |
  | Chart | Both (pair-programmed) | #9 |
  
  We both reviewed every pull request.

• Signed contribution statement on Canvas. Each partner submits the same short statement, agreeing who built what. It stays on Canvas, not in the repo. Without it, the capstone's Process row is at most Developing.

• Individual parts. Each partner does their own oral walkthroughs, final reflection, peer review, exit tickets and self-assessment. In walkthroughs you can be asked about any part of the app, but detailed questions focus on the parts your contribution statement says you built.

• Same score for shared work. Both partners normally get the same capstone score. If the history and the contribution statement show a big imbalance, your instructor will talk with both of you and may adjust individual scores.

• Grace tokens: a pair can use one on the capstone only if both partners have one left, and it costs each partner one.

• If a pair splits up, tell your instructor early. Each partner keeps a copy of the repo and reduces the scope.

Tip: pair-program for the hard parts, taking turns as "driver" (typing) and "navigator" (reading and checking), and swap every 20–30 minutes.

What done means

Your capstone is done when all of these are true:

• ☐ The production URL works in a private window, on a phone and a laptop, and you've submitted it on Canvas with a screenshot.
• ☐ Every MUST acceptance criterion passes, or the README's status table honestly says which don't and why.
• ☐ npm test passes with at least 3 automated tests, written before the code they check, and no test was deleted or switched off to make that happen.
• ☐ TESTS.md has at least 3 manual edge-case tests with dated results.
• ☐ SECURITY_CHECKLIST.md is complete, with evidence on every ticked item; npm run check:secrets finds nothing in your files or history; you've read the npm audit output.
• ☐ If you have a database: RLS is on for every table, and the grants and policies are in supabase/policies.sql.
• ☐ You can say in one sentence where authorization is enforced (authorization: the rules for what each user is allowed to do), and the README says it too.
• ☐ SPEC.md and AGENTS.md (with its Scope section) describe the app you actually built.
• ☐ PROMPTS.md is honest and up to date, with teach-backs on agent commits and your ownership statement.
• ☐ The README is complete, including Known issues, and links the 2–3 minute demo video (or says it's on Canvas).
• ☐ The polish checklist is done.
• ☐ Your final commit has a GitHub release tagged v1.0. (On your repo page: Releases → Create a new release, type v1.0 as the tag, add a one-line summary, Publish. Menus move; if you can't find it, ask your assistant how to create a GitHub release.)
• ☐ Your final reflection, with your revised personal AI-use rules, is submitted on Canvas.
• ☐ You can explain any part of it with the AI off.

Naming a real limitation in Known issues never costs points. An honest list is worth more than a README that claims everything works.

Rules and safety

• The three project rules: no real payments, no real personal data about other people, nothing you'd miss if an agent deleted it.
• Test accounts only. If your app has sign-in, create test users with made-up details. At the Project Fair, ask classmates to use fake data too.
• Contain the agent. Work in a Codespace, keep approvals on (never an autopilot or "skip permissions" mode), commit before and after every agent task, and never give the agent a production key or a real password. The safety contract has the full rules, including rule 9: agents don't publish, and untrusted content never shares a session with your secrets.
• AGENTS.md is advice, not a lock. What actually limits an agent is the Codespace, the approval prompts, narrowly scoped tokens, spending caps and, for your data, row-level security.
• Keep secret keys on the server (as in the AI micro-app). Only the publishable key goes in the browser, and only with row-level security on for every table (see Not every key is a secret).
• Personal account. Keep the repo on your personal GitHub account. Vercel's free plan can't deploy private repos owned by an organization (Tool Handout).
• Free services can pause or run out. Free databases may pause when idle, and AI credits may run out mid-week. Check Tool Handout, and open your app a day before the Fair to make sure it wakes up.

AI use on the capstone

Label	On the capstone
🟢 AI on	Agent-built features, plans, tests, explanations, reviewing your diffs, a comparison AI code review (after you've written yours)
🟡 AI limited	SPEC.md and the pitch: the AI may critique them, not write them
🔴 AI off	Your written peer review; your teach-back notes and the "What I wrote or decided myself" section of PROMPTS.md; a pair's contribution statement; weekly and final reflections; your personal AI-use rules; exit tickets; the week 7 maintenance task; oral walkthroughs 2 and 3

The complete list of 🔴 AI off and 🟡 AI limited work is in section 8 of the syllabus.

How it's graded

The capstone rubric scores the spec (including your Goldfish test), tests (including check first), the security checklist, deployment (production URL, screenshot, v1.0), feature types, process (teach-backs, ownership statement, AGENTS.md with Scope and trial notes, pull requests), README and video (including Known issues), and code you can explain. A working demo is required but not sufficient: without a working production URL the capstone is capped at half marks, and a working demo alone earns only a small part of the points.

Submit

Follow How to submit. For the final: on Canvas, the repo URL, the production URL with a screenshot of it working, the link to your v1.0 release, and your demo video link (or the video itself). The final reflection is its own Canvas assignment.

If you get stuck

• The agent keeps breaking things: stop after two failed attempts (the two-strikes rule), go back to your last good commit, and give it a smaller task with a clearer "Done when".
• Your feature is too big: move it to "Out of scope" in SPEC.md, and tell your instructor. A smaller finished app beats a bigger broken one.
• Out of credits: I ran out of free credits.
• Database problems ("permission denied", empty results, policies): Supabase troubleshooting, then redo the RLS lab steps on your own table.
• Deploy problems: Deploying to Vercel.
• More help: troubleshooting, office hours, and the course tutor (hint-only mode).