--- gh_classroom: assignment_id: "978082" invitation_url: https://classroom.github.com/a/FJ_XRq-e --- # Final Project Checkpoint 1 In this checkpoint, you will plan, scaffold, and build a tiny working slice of your project. ## Setup If you have not already done so, accept the final project assignment: [button:: Accept the Final Project Assignment](https://classroom.github.com/a/FJ_XRq-e) Once you accept the assignment: 1. Open the repository in Cursor (recommended) or VS Code 2. Review the files in your project (see the [Transition Lab](../labs/01-transition/01-transition.lab.md) for a walkthrough) 3. Review your project.spec.md file and fill out any missing information or extra details. --- ## Choose a primary category Pick the category that matches what you want to build. This can evolve as your project progresses, but starting with a primary category will help you get started. Each guide has setup instructions, project ideas, tutorials, and agent prompts to help you get started. | Category | What you will build | Guide | | --------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------- | | **Web App** | A website or web application with pages, forms, and data — runs in a browser | [Flask Setup Guide](../resources/flask-setup.guide.md) | | **Data Science** | Analyze a dataset and create visualizations that tell a story | [Data Science Setup Guide](../resources/data-science-setup.guide.md) | | **Game / Simulation** | An interactive game or visual simulation with graphics and input | [Pygame Setup Guide](../resources/pygame-setup.guide.md) | Not sure which to pick? Think about what excites you. Do you want to make something people can use in a browser? Go with Flask. Do you love finding patterns in data? Try data science. Do you want to build something you can play? Pygame is for you. You could also do some combination of the above (e.g. a web game built with Flask or a data visualization built with Pygame). Any category can incorporate AI (using the OpenAI or Anthropic APIs) if that interests you. --- ## Write Your Spec Your `project.spec.md` file is the most important document in your project. It is your plan — and it is also the main way your coding agent understands what you are building. We'll need to make sure it reflects your project goals and gives enough detail to get started. **Spec-driven development** means you write the plan first, then use that plan to guide everything else. Here is the workflow: 1. **Fill out your spec.** Open `project.spec.md` and answer each section. Focus on the MVP (Minimum Viable Product), this is the smallest version of your project that works. 2. **Share it with your agent.** When you ask your agent for help, point it to your spec first. The agent will give you much better help when it understands your full plan. Pro Tip: You can `@` mention your spec in the chat window e.g. `Read my @project.spec.md file...`. 3. **Scaffold from the spec.** Use your agent to create the initial project structure, install dependencies, and build a minimal starting point you can run. 4. **Build one tiny slice right away.** Do not stop at "Hello World." Build the smallest possible feature that proves your project's core loop works. 5. **Iterate.** Build one feature at a time. Update your spec as your plan evolves. ### Project Guide Here is what a strong answer looks like for each section of `project.spec.md`. **Project Name**: Give it a real name, not "Final Project." A short name makes it easier to talk about and looks better on your GitHub profile. Examples: "CampusBoard," "StatSmash," "SnakePit." **Category**: Pick one to start with: Web Development (Flask), Data Science, or Game/Simulation. Check the setup guide for your category (linked above) for project ideas if you are still deciding. **Description**: Be specific about what your project does and who would use it. Vague descriptions lead to vague projects. | Vague | Specific | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | "A quiz app" | "A web app that loads trivia questions from a JSON file and quizzes the user, tracking their score across 10 rounds" | | "A data project about sports" | "A Python script that analyzes NBA player stats from a Kaggle CSV and creates charts comparing shooting percentages across positions" | | "A game" | "A Snake game built with Pygame where the snake grows when it eats food and the game ends when it hits a wall" | **Features (MVP)**: This is the most important section. Your MVP features are the 3-5 things your project absolutely must do to work. If your list is longer than 5 items, your scope is too big — move some to stretch goals. Ask yourself: _what is the one core thing my project does?_ A quiz app quizzes you. A data visualizer shows charts. A game lets you play. Your MVP is that core thing, working end to end. **Features (stretch)**: These are real goals, just not first priorities. Do not start these until your MVP works. Having a polished MVP with no stretch goals is better than a broken project with half-finished features. **Tech Stack**: List the specific libraries you will use. Your setup guide recommends the standard ones for each category. If you are not sure, just list what the guide suggests and update later. **Inspiration / References**: Link to anything that inspired your idea: similar apps, tutorials you followed, datasets you found. This helps your instructor understand your vision and helps your agent give you better suggestions. ### Agent Prompts for Spec Writing Use these with your coding agent to refine your idea: **Get help brainstorming:** ```text Read my project.spec.md. I am thinking about building [your rough idea]. Help me refine this into a clear plan. Ask me questions about what I want the project to do, who it is for, and what the simplest working version looks like. Then help me fill out the spec sections. ``` **Review your spec:** ```text Read my project.spec.md and give me honest feedback. Is the MVP scope realistic for 3 weeks? Are the features specific enough to start building? What is missing or unclear? Suggest improvements but keep things beginner-friendly. ``` --- ## Scaffold Your Project Once your spec is filled out, use your agent to set up the initial project. This is where spec-driven development pays off... your agent reads your plan and creates exactly the structure you need. ```text Read my project.spec.md and the setup guide for my category. Set up my project: initialize uv, install the dependencies listed in my tech stack, create the basic file structure, and build a minimal starting point I can run. Explain each file you create so I understand how they connect. ``` After running this, you should be able to run your project and see something, even if it is just a "Hello World" page, an empty chart, or a window with a colored background. That is your starting point. From here, you build one feature at a time. ## Build Your First Working Slice Checkpoint 1 should include one tiny, working slice of your actual project. Keep it small enough that you can explain every line and make changes yourself. If you don't understand something the agent created, ask the agent to explain it to you. If you don't like the way the agent did something, ask the agent to do it differently and be specific about what you want it to do. Examples: - **Web App**: one route or form that accepts input and shows a result - **Data Science**: one dataset loaded with one chart, table, or summary printed - **Game / Simulation**: one controllable loop with visible state changes Use your agent to help with setup and explanation, but stay in the driver's seat for the core logic of this first slice. ```text Read my `project.spec.md`. Help me build the smallest possible first feature for this project. Keep the core logic simple and explain each step so I can understand and modify it myself. ``` If your agent writes part of the core logic for you, rewrite or annotate it in your own words before keeping it. --- ## What is Due for Checkpoint 1 By **Thursday, April 16th**, you should have: - [ ] A completed `project.spec.md` with your project plan - [ ] Your project initialized with `uv` and dependencies installed - [ ] A basic scaffolding that runs (even if it does not do much yet) - [ ] A tiny working feature that demonstrates your project's core loop - [ ] Your first entry in `project.journal.md`, including what code you wrote yourself and what your agent helped with - [ ] Everything committed and pushed to GitHub ### Check Your Work with Your Agent Before you submit, have your agent review your checkpoint. Paste this prompt into your coding agent from within your project: ```text I am building a [web app / data science project / game] for my final project. Review my Checkpoint 1 work using this guide: https://csc-121.path.app/unit-3/resources/checkpoint-1-review.agent.llm.md ``` Replace the bracket text with your actual project type. The agent will check your spec, scaffolding, first working slice, and journal and tell you what is done and what still needs work. --- ## Commit and Push Your Work Commit and push your work to GitHub to save your progress. You can have your agent do this for you if you like: ```text Commit and push my work to GitHub. ``` [checkpoint-1-review]: ../resources/checkpoint-1-review.agent.md