How to Build a Fitness Tracker

<context>
App: Fitness Tracker
Difficulty: Intermediate
Estimated build time: 1–2 weeks
Tech stack (intermediate): Next.js + Supabase + Recharts — multi-device sync with progress visualisation

Data model:
  User: id, email, height, weight, fitness_goal (lose_weight/build_muscle/maintain), created_at
  Workout: id, user_id, name, notes, started_at, ended_at, total_volume
  WorkoutSet: id, workout_id, exercise_id, set_number, reps, weight_kg, duration_seconds (for cardio)
  Exercise: id, name, muscle_group, type (strength/cardio/flexibility), equipment
  PersonalRecord: user_id, exercise_id, reps, weight_kg, achieved_at

FIRST RUN REQUIREMENT:
Seed 50 common exercises indexed by muscle group. Also seed 5 past workouts for the demo user so progress charts show a trend line, not a single dot.

DONE WHEN — verify each before marking V1 complete:
  □ User logs a workout (3 exercises × 3 sets) and sees total volume calculated correctly
  □ A new personal record triggers a celebration on the workout completion screen
  □ Per-exercise strength progress chart shows a correct trend line across 5+ workouts
  □ AI generates a 4-week progressive overload plan based on current PRs within 10 seconds
  □ App opens with a pre-seeded exercise library of 50+ exercises — no blank library

Recommended build order:
  1. Define API contract + schema + seed data (always first)
  2. Exercise library — Seed a table of 50–100 common exercises with name, muscle group, and type. Add a search to find exercises by name or muscle group. This is the foundation everything else builds on.
  3. Workout logger — Build the active workout screen: search and add exercises, add sets per exercise (reps + weight), mark sets complete. Use a flat list — exercise name as a header, sets as rows beneath it.
  4. Rest timer — After logging a set, auto-start a configurable rest timer (default 90 seconds for strength, 60 for cardio). Show a countdown with a sound alert at zero. Let the user skip or extend.
  5. Workout history — On workout end, save the workout with all sets. Build a history screen: list of past workouts with date, name, and total volume (sum of weight × reps across all sets). Tap to see the full detail.
  6. Personal records — After each workout, check if any set is a new PR for that exercise (highest weight for that rep count). If yes, store it and show a "New PR! 🎉" celebration on the workout end screen.
  7. Progress charts — Build per-exercise strength progress: a line chart of max weight over time. Build volume chart: total weekly volume over 12 weeks. These are the charts users open most.
  8. AI workout plan — Send the user's goal, current PRs, and training frequency to Claude. Ask it to generate a 4-week progressive overload plan as structured JSON. Save it and let users follow it session by session.
  9. End-to-end verification — walk every Done When condition above (always last)

Known pitfalls to avoid:
  - Storing weight in imperial and metric separately — pick one storage format (kg) and convert for display. A user who switches their preference shouldn't see their old data in the wrong unit.
  - Not handling incomplete workouts — users often start a workout and close the app. Store workout state in localStorage or a "draft" status in the DB so they can resume.
  - Calculating volume with bodyweight exercises — for exercises like pull-ups, weight = 0. Exclude them from volume calculations or add an "assisted/bodyweight" flag and calculate differently.
</context>

<role>
You are a Senior Full-Stack Engineer and product architect who has shipped production Fitness Trackers before. You know exactly where developers get stuck and how to structure the project to avoid rewrites.
</role>

<task id="step-1-clarify">
Before writing any code or spec, ask me 3–5 clarifying questions that will meaningfully change the architecture. Focus on: scale expectations, auth requirements, platform (web / mobile / both), must-have vs nice-to-have features for the MVP, and any hard constraints (budget, deadline, existing infrastructure).

<example>
BAD: "What tech stack do you want to use?" — too broad, doesn't change architecture decisions.
GOOD: "Do you need real-time sync across devices, or is single-device with periodic refresh acceptable? This decides whether we use WebSockets or simple REST polling and significantly affects infrastructure complexity."
</example>

⚠️ Do NOT start planning or writing code until I answer. Present the questions, then stop and wait.
</task>

<task id="step-2-architect">
After I answer your questions, produce the following in order:

1. TECHNICAL SPECIFICATION
   - System architecture using → to show data and event flow
   - Core data model (refer to data model in <context>)
   - API contract — list ALL routes with request/response shapes BEFORE any implementation
     WHY: agreeing on contracts first prevents rewrites when frontend and backend shapes diverge
   - External APIs and integration points

2. MVP PLAN in three phases:

   SETUP   ✦ Step 1 (always): API contract + schema migration + seed data
     Done when: schema is migrated, seed script runs, app starts with demo data, zero manual setup.

   CORE FEATURES — build in this exact order:
   2. Exercise library
   3. Workout logger
   4. Rest timer
   5. Workout history
   6. Personal records
   7. Progress charts
   8. AI workout plan

   DONE WHEN — one observable condition per feature:
   □ User logs a workout (3 exercises × 3 sets) and sees total volume calculated correctly
   □ A new personal record triggers a celebration on the workout completion screen
   □ Per-exercise strength progress chart shows a correct trend line across 5+ workouts
   □ AI generates a 4-week progressive overload plan based on current PRs within 10 seconds
   □ App opens with a pre-seeded exercise library of 50+ exercises — no blank library

   STRETCH GOALS — post-launch additions that are explicitly out of V1 scope.

3. BLOCKER ANALYSIS
   Flag: API rate limits, auth complexity, scope risks, cold-start problems, top 2–3 failure modes.

   FIRST RUN REQUIREMENT: Seed 50 common exercises indexed by muscle group. Also seed 5 past workouts for the demo user so progress charts show a trend line, not a single dot.
   ✓ Done when: app launches with seed data and the full user journey works without any manual setup.

<self_check>
Before presenting your output, verify:
□ Every answer I gave to clarifying questions is reflected in the spec
□ Step 1 is ALWAYS: API contract + schema + seed — never UI first
□ Done When criteria are observable user behaviors, not internal states
□ The plan is realistic for one person to ship within 1–2 weeks
□ All known pitfalls from <context> are addressed in the spec
</self_check>
</task>

<task id="step-2.5-agents-md">
Generate an AGENTS.md file at the project root. This file is read automatically by Claude Code, Cursor, Windsurf, and all major AI coding tools at the start of every session.

Include:
- Project overview (2–3 sentences)
- Tech stack with exact version numbers
- Folder structure with one-line descriptions per directory
- Key architectural decisions and the WHY behind each
- Coding conventions: camelCase components, kebab-case files, max 200 lines per file, one concern per file
- Available commands: dev, build, test, lint, db:migrate, db:seed
- MVP scope boundaries — features explicitly out of V1

Note in the file: "Cursor users: symlink .cursorrules → AGENTS.md. Claude Code users: symlink CLAUDE.md → AGENTS.md."
</task>

<task id="step-3-implement">
Implement the full project in the exact order from step 2. For each step:
- Write complete code (no placeholders or TODOs)
- Confirm the step works before moving to the next

<constraints>
- Step 1 is ALWAYS: define all API routes + TypeScript request/response interfaces + run schema migration
  WHY: agreeing on contracts before writing a single component prevents shape mismatches that require rewrites
- Final step is ALWAYS: start the app and walk every Done When condition from <context> end-to-end
  WHY: a spec that passes unit tests but breaks the core user journey is not done
- Max 200 lines per file. WHY: every file must fit in one AI context window for complete reasoning
- One concern per file. WHY: mixing auth logic into API routes makes it impossible to reuse — extract to lib/auth.ts
- TypeScript strict mode, no `any` types. WHY: catches data shape mismatches at compile time, not in production
- All database queries in server components or API routes only. WHY: keeps credentials server-side
- All environment variables documented in .env.example. WHY: next developer sets up in under 5 minutes
</constraints>
</task>