Start a project the right way.

I want to build a software project and need a research-backed technical spec that I can hand to an AI coding agent (Claude Code or Codex) to build from. Research thoroughly before writing.

MY IDEA
[DESCRIBE YOUR IDEA IN A FEW SENTENCES]

WHO IT'S FOR
[TARGET USERS]

MY CONSTRAINTS
- Experience: [YOUR EXPERIENCE, e.g. comfortable with Python, new to web apps]
- Deadline: [DEADLINE]
- Monthly budget for hosting and APIs: [BUDGET]
- Must use or avoid: [REQUIRED OR BANNED TECH, or none]

RESEARCH
1. Existing solutions: what already exists, what it does well, and where it falls short. What would make mine worth building?
2. Stack: compare 2 or 3 realistic options for my constraints. Prefer mature, well-documented, widely used tools. Only recommend libraries and services you can confirm exist and are actively maintained, and link their official docs.
3. Pitfalls: the most common ways projects like this fail, whether technical, security, cost, or scope.
4. Security and privacy: what data this app handles, which risks matter most for it (use the OWASP Top 10:2025 as a reference), and any privacy or legal considerations, such as student data or payments.

Then write the spec in Markdown, using EXACTLY this structure:

# Spec: [PROJECT NAME]
## 1. Overview
What it is, who it's for, and the problem it solves, in 3 to 5 sentences.
## 2. MVP scope
Must-have features for v1, plus an explicit "Not in v1" list.
## 3. User flows
Step by step, for each core flow.
## 4. Tech stack
Each choice with a one-line reason and its exact package or service name.
## 5. Architecture
The main components, how data flows between them, and what runs in the browser (untrusted) versus on the server (trusted).
## 6. Data model
Every table with its fields, types, and relationships. Mark sensitive fields.
## 7. Access rules
A table of role x data x read / create / update / delete, including signed-out visitors. The default is no access.
## 8. Environment variables
Each variable, what it is for, and whether it is public or secret.
## 9. Security requirements
Concrete, testable rules for this app: authentication, input validation, secrets, rate limits, and anything specific to its data.
## 10. Milestones
5 to 10 small milestones in build order. Each ends in something runnable, with acceptance criteria. Authentication and access rules come early, not at the end.
## 11. Open questions
Decisions I still need to make.

Label anything you are unsure about as an assumption, and cite sources for stack and security claims.

Before I build from this spec, pressure-test it. Act as a skeptical senior engineer who has to build this and will be blamed if it ships late or insecure.

1. Gaps: what is missing that would force the builder to guess? Look for unclear flows, missing fields, undefined error cases, and unstated limits.
2. Contradictions: anything that conflicts with something else in the spec.
3. Scope: is v1 too big for my deadline and experience? Recommend what to cut.
4. Security: holes in the access rules. Can any role reach data it shouldn't? Could any secret end up in the browser? Does anything cost money without a limit?
5. Risky choices: any library or service that is overkill, poorly maintained, or likely to exceed my budget.

Ask me your questions as one numbered list, most important first, then wait for my answers. Don't rewrite the spec yet.

When I say "finalize," output the complete updated spec in the same structure (the whole document, not just the changes) so I can save it as SPEC.md.

You are building [PROJECT NAME]. The full spec is in SPEC.md at the root of this repository. It is the source of truth. Read all of it before doing anything, and re-read the relevant sections before each milestone.

HOW TO WORK
1. Start by summarizing the spec back to me in 5 to 10 bullets and listing any questions or ambiguities. Wait for my answers before writing code.
2. Build one milestone at a time, in the order given in SPEC.md. Before each one, tell me which files you will create or change and your approach. Keep each change small enough for me to review.
3. After each milestone, run lint, typecheck, and tests and fix any failures. Tell me exactly how to test it myself, then check the milestone off in SPEC.md with a one-line note. Wait for my OK before starting the next one.
4. If the spec is wrong or missing something, stop and tell me. Don't silently invent requirements. When we change a decision, update SPEC.md so it stays accurate.
5. Use the stack and versions in the spec. Don't add a framework, library, or service that isn't in it without asking. Before installing any package, confirm the exact name is real and actively maintained. AI tools sometimes invent package names, and attackers publish malware under those names.
6. Write complete code, with no "TODO" or "rest of code here" placeholders. Only use APIs and options you are confident exist in these versions. If unsure, check the docs or ask.

FIRST MILESTONE: FOUNDATION (before any features)
- Create the project with the framework's official starter, with strict type checking, linting, and formatting.
- Add a .gitignore that excludes every .env file except .env.example, before any secret exists.
- Add a .env.example listing every variable from the spec with fake values, and validate required config at startup.
- Set up a test runner with one passing test, and a README with setup and run instructions.
- Create a CLAUDE.md or AGENTS.md containing the project commands, conventions, and the security rules below, so every future session follows them.

SECURITY RULES (never break these, even to get something working)
- No secrets in code, logs, git, or anything sent to the browser. Server-only keys stay on the server.
- Validate every input on the server: forms, URL parameters, uploads, webhooks, and AI model output.
- Every request that reads or changes data checks on the server that the user is signed in AND allowed to access that specific record. Follow the access rules in SPEC.md exactly, and deny by default.
- If the database supports row-level security, enable it on every table with policies that match the spec.
- Use parameterized queries only. Never build SQL, shell commands, or HTML from user input.
- Rate-limit sign-in and anything that costs money, such as email, AI calls, and uploads.
- Fail closed: on an error, deny access, show a generic message, and log the details on the server.
- Never disable a security check, type check, or test to make something pass. If one is blocking you, explain why and ask me.

Begin by reading SPEC.md and giving me your summary and questions.

Do a security audit of this repository before it goes live. You did not write this code. Review it like an outside application security engineer who assumes there are bugs. The intended behavior is described in SPEC.md, so check the code against it.

First, explore the whole codebase: routes and API handlers, server actions, the database schema and security policies, auth setup, environment variable usage, file uploads, webhooks, AI integrations, configuration, and dependencies.

CHECK
1. Access control: can a signed-out visitor reach private data? Can user A read, edit, or delete user B's data by changing an ID? Can a normal user make themselves an admin? Compare every route against the access rules in SPEC.md.
2. Database rules: is row-level security (or its equivalent) enabled on every table with correct policies? Is an admin or service-role key used anywhere the user's own permissions should apply?
3. Secrets: are any keys hardcoded, logged, committed to git history, or reachable from the browser bundle? Are .env files ignored?
4. Input and injection: server-side validation on every input; SQL, command, and XSS injection; unsafe HTML rendering; fetching URLs supplied by users.
5. Authentication: sessions verified on the server, sensible expiry, logout that works, and password reset through the provider's own flow.
6. Abuse and cost: rate limits on sign-in, sign-up, forms, and anything paid, plus spending limits on AI and other usage-billed APIs.
7. AI features, if any: prompt injection paths, model output rendered or executed unsafely, and AI tools with more power than the user has.
8. Configuration: security headers, cookie flags, CORS, and no debug mode, stack traces, or verbose errors in production.
9. Dependencies: run the package manager's audit. Flag high and critical vulnerabilities, and any unmaintained or suspicious packages.
10. Error handling: anything that fails open, or empty catch blocks that hide failures.

REPORT
For each finding:
- Severity: Critical, High, Medium, or Low, based on how exploitable it really is in this app
- Location: file and line
- The problem, in plain language
- How an attacker would exploit it, step by step
- The fix

Only report what you can point to in the code. List anything you can't confirm under "Needs verification," and skip style nitpicks.

End with:
- A go or no-go for launch, listing any blocking issues
- Settings to check outside the code: hosting environment variables, the database dashboard, the auth provider, and spending alerts

Don't change any code yet. After I review the report, I'll tell you which fixes to make. Then fix them one at a time and re-test each one.