> HOW TO USE THIS FILE > > This is the brain of your project. Every coding agent — Grok, Codex, Claude, Cursor — should read THIS file. > Fill in the sections. If a line is in [brackets] or says "Example:" — delete it and write your own. > > Do not put secret passwords, API keys, or live credentials anywhere in this file. > Write the NAME of an environment variable and what it is for. Never the secret value. # [PROJECT NAME] Example — delete this line: "FitTrack — Personal Workout Logger" --- ## Vision [2–5 sentences. What are you building? Who is it for? What problem does it solve? What does success look like?] Vague vision = generic app. Specific vision = useful plan. **Strong:** "A simple web page where gym-goers log sets in under 60 seconds and see last week's numbers. No social feed. No diet tracking." --- ## Target users [A real person, not "everyone."] **Weak:** "People who want to budget." **Strong:** "People in their 20s who tried budgeting apps, quit because they felt watched, and just want to see last month's spending." --- ## Tech stack [List exactly what you are using. Blank here means the agent will guess.] A **framework** (React, Next.js) is extra machinery. For a first site, you usually do not need it. Recommended first stack: - HTML5, CSS3, vanilla JavaScript — no frameworks - Firebase Hosting — free place to put a static site on the internet - No npm unless you explicitly add it below When in doubt: start vanilla. --- ## Architecture [How the pieces fit. For a first site this can be one sentence.] Example: "Static pages. All styles in index.css. All behavior in index.js. No backend in Phase 1." --- ## Folder structure [Paste the layout you want, or leave this for the agent to propose — then you approve it.] Example for a first static site: ``` /your-project-name/ ├── PROJECT.md ← this file, always in the root ├── adapters/ ← tiny pointers for specific AIs (optional) ├── index.html ├── index.css ├── index.js ├── /pages/ └── /assets/ ``` --- ## Coding conventions [Rules the agent must follow when writing code.] Keep these unless you have a reason not to: - Mobile-first — it must work on a phone before you call a step done - No new features that are not in Core features - Do not add a framework unless it is listed in Tech stack - Keep CSS in index.css and JavaScript in index.js unless the stack says otherwise --- ## Core features [Only what the first version MUST do. These become the build steps.] Start small. Phase 2 exists for a reason. --- ## Out of scope [What this app will NOT do. This keeps the agent from "helpfully" adding a social network.] --- ## Database [None / Firestore / something else. If none, write "None in Phase 1."] --- ## Security rules [Anything safety-related the agent must respect. Examples: no public write access, login required for X.] --- ## Environment variables Document **names and purposes only. Never secret values.** An environment variable is a named setting your app can read, like a label on a locked drawer. The name is public. The key inside the drawer is not. **Correct:** | Name | Purpose | |---|---| | STRIPE_SECRET_KEY | Stripe server authentication credential | | FIREBASE_API_KEY | Firebase web app identifier (public client key — still not a secret to paste into chat if you can avoid it) | **Wrong — never do this:** ``` STRIPE_SECRET_KEY=sk_live_actual_secret_here ``` If an agent asks you to paste a live secret into this file or into the chat, refuse. --- ## Commands [How to run, test, and deploy this project. Write the actual commands for your computer.] Example for a static site: "Open index.html in a browser. No build step." If you are on Windows, say so. Commands differ. --- ## Testing [How you will know a step worked. "It looks fine" is not a test.] Examples: - Open the page — it is not a white screen - Submit the form — a thank-you message appears - Browser console (F12 → Console) — no red errors - Phone width — no sideways scrolling --- ## Deployment [How this gets a public URL. If you do not know yet, write "Not decided — propose options, do not deploy."] --- ## Current priorities [What should happen next, in order. The agent works the top item unless you say otherwise.] 1. [First thing] 2. [Second thing] --- ## Known issues [Bugs and weirdness that already exist. Empty is fine on day one.] --- ## Things the AI must never do without explicit approval AI can propose. AI can implement inside the current step. You control anything consequential. **Do not do any of the following unless I typed a clear yes for that specific action:** - Production deployment (putting the live site/app on the public internet) - Database migrations - Destructive database operations (drop, wipe, bulk delete) - Deleting files or data - Changing authentication or security rules - Changing billing or payment logic - Modifying production environment configuration - Handling, printing, committing, or exposing secrets - Force pushing or other destructive Git operations (`reset --hard` on shared history, rewriting published commits) If you are unsure whether something is on this list: stop and ask. --- ## Notes for the agent Keep these unless I change them: - Build one step at a time. Do not start the next step without my confirmation. - After each step tell me: what was built, which files changed, how to test it. - Do not modify finished steps unless that specific step has a bug. - If a command might destroy data, show me the command and wait. - I am a beginner unless I say otherwise. Explain terms in plain English. Add your own notes below: - [Example: "Windows PC — all terminal commands should be for PowerShell"] - [Example: "Dark background, light text"]