# Project Spec: [Project Name]

## Project Goals
**Type:** [internal tool / personal project / public product / MVP / learning project]

**Goal statement:**
> [1-2 sentences describing the core purpose]

---

## Product Requirements

### Who is this for?
**Target user:** [specific user description]
**User context:** [when/where/why they use this]

### What problems does it solve?
1. [Problem 1]
2. [Problem 2]
3. [Problem 3]

### What should the product do?
[Core functionality description]

**Key user flows:**
- [Flow 1]
- [Flow 2]

---

## Success and Verification
_Define the proof before implementation. These are planned checks, not claims that verification has already passed. Keep criteria specific to this project's scope; omit checks that don't apply._

### Successful Outcome
[What can the user accomplish when this work is complete? Describe the observable result.]

### Verification Criteria and Methods
_Each required outcome needs a suitable check and a clear passing result. Include important failure cases as well as the happy path. If the spec spans multiple milestones, identify which milestone each criterion belongs to._

| Criterion | How to verify | Passing result |
|-----------|---------------|----------------|
| [Required behavior or outcome] | [Test, walkthrough, measurement, or review, including relevant inputs] | [Specific observable evidence or threshold] |
| [Important failure or edge case] | [How to exercise the condition] | [Expected handling and observable result] |

### End-to-End Proof
_Describe the main user journey to exercise from start to finish. Check the actual outcome, not just whether individual components pass tests._

- **Environment:** [Local / staging / production, as appropriate to the requested scope]
- **Starting state and inputs:** [Required setup and representative data]
- **Steps:** [User actions from start to finish]
- **Expected final result:** [What must be observable when the journey completes]
- **Evidence to capture:** [Relevant test output, screenshot, persisted record, measurement, or review result]

### What Must Not Break
_Existing behavior that must still work, and how to check it. Omit for a new project when nothing exists yet._

| Existing behavior | How to verify it still works |
|-------------------|------------------------------|
| [Behavior to preserve] | [Relevant regression check] |

### Verification Constraints
_Note checks that need user review, unavailable credentials, external access, or a longer observation period. If blocked, report the specific criterion that remains unverified; a substitute check does not establish the original outcome._

- [Constraint, affected criterion, and what is needed to complete verification — or "None"]

---

## Milestones

### MVP (Milestone 1)
The absolute minimum needed to validate the idea.

- [ ] [Feature]
- [ ] [Feature]
- [ ] [Feature]

**What's left out of MVP:**
- [Deferred item]

### V2 (Milestone 2)
- [ ] [Feature]
- [ ] [Feature]

### Future Versions
- [Ideas for later]

---

## Engineering Requirements

### Tech Stack
| Component | Choice | Notes |
|-----------|--------|-------|
| Language | | |
| Framework | | |
| Styling | | |
| Database | | |
| Auth | | |
| Hosting | | |
| Other | | |

### Architecture Map
A one-page view of the system: the building blocks and how they connect. Mark any uncertain choice with **(research needed)**.

**System overview:**
> [High-level description of how pieces fit together]

**Building blocks:** (include only what this project needs)
- **Frontend:** [what the user sees and does]
- **Backend:** [API routes / business logic]
- **Database:** [what the app needs to remember]
- **Auth:** [how users sign in, if accounts are needed]
- **File storage:** [user uploads or generated files, if any]
- **External services:** [third-party APIs, AI models, payments, email]

**How the blocks connect:**
```
User → Frontend → Backend API → Database
                      ↘ [External service] ([purpose])
```

**Research needed:**
- [Uncertain choice + what to find out — e.g., "Auth: Supabase Auth vs. Clerk"]

**Open questions:**
- [Decision to make before building]

### Database Schema (initial)
> [Main entities/tables and key fields]

### API Design (if applicable)
> [Main endpoints or API approach]

### Infrastructure to Provision
- [ ] [Service/resource needed before building]

---

## Out of Scope
- [Explicit exclusion 1]
- [Explicit exclusion 2]

---

## Agent Decision Boundaries
The coding agent may make the following decisions without additional confirmation, subject to repository instructions and approval policies:
- [e.g., Database schema details]
- [e.g., API design]
- [e.g., Component structure]
- [e.g., Error handling approach]