How to Build a Habit Tracker

<context>
App: Habit Tracker
Difficulty: Beginner
Estimated build time: 2–4 days
Tech stack (intermediate): Next.js + Supabase + Clerk + React Native Web for cross-platform

Data model:
  User: id, email, timezone, notification_time
  Habit: id, user_id, name, icon, color, frequency (daily/weekdays/custom), target_per_day, created_at
  HabitLog: id, habit_id, date (YYYY-MM-DD), value (1 for bool, n for quantity), created_at

FIRST RUN REQUIREMENT:
Seed 3 example habits (Drink Water, Read 20 mins, Exercise) on first login so the daily check-in screen is populated. User can edit or delete the examples at any time.

DONE WHEN — verify each before marking V1 complete:
  □ User checks a habit and the streak counter increments immediately
  □ Streak breaks correctly on a missed day; grace period allows recovery for 1-day gaps
  □ Monthly calendar shows the correct completion pattern for each habit
  □ AI weekly summary generates a coaching comment per habit on Monday
  □ App opens with 3 seeded example habits — daily check-in screen is usable immediately

Recommended build order:
  1. Define API contract + schema + seed data (always first)
  2. Habit list and daily check-in — Show a list of habits for today. Each has a checkbox. On check, write a HabitLog for today's date. If unchecked, delete today's log. Keep it simple — no streaks yet.
  3. Streak calculation — Write a function that takes an array of log dates and returns the current streak. Walk backwards from today: if yesterday has a log, increment streak. Stop at the first missing day.
  4. Streak recovery (grace period) — Add a grace_period field to habits (default: 1 day). If the user missed one day but the habit has a grace period, don't break the streak — show a "recover streak" button that logs yesterday.
  5. Progress charts — Build a 7-day heatmap row showing which days had a check-in. Add a monthly calendar view where completed days are highlighted. Use a simple CSS grid — no chart library needed for this.
  6. Habit templates — Seed 8–10 common habits (drink water, read, exercise, meditate) with icons and suggested targets. Show these as one-click templates on the add-habit screen.
  7. Daily reminder notifications — On web, use the Web Notifications API + a service worker to schedule a daily notification. On mobile (Expo), use expo-notifications with a daily trigger at the user's preferred time.
  8. AI weekly summary — Every Monday, generate a summary: fetch last week's logs, calculate hit rate per habit, send to Claude Haiku, get back a 2-sentence coaching comment per habit. Email or show in-app.
  9. End-to-end verification — walk every Done When condition above (always last)

Known pitfalls to avoid:
  - Calculating streaks in local time without knowing the user's timezone — a check-in at 11pm in New York is the next day in UTC. Always store dates as YYYY-MM-DD strings in the user's timezone, not as UTC timestamps.
  - Breaking streaks on the first missed day — this is the #1 reason users abandon habit apps. Add a 1-day grace period and a "I forgot yesterday" recovery option before you punish missed days.
  - Storing one HabitLog per check action instead of one per day — if the user checks and unchecks, you'll have multiple logs per day. Use upsert on (habit_id, date) as a unique key.
</context>

<role>
You are a Senior Full-Stack Engineer and product architect who has shipped production Habit 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. Habit list and daily check-in
   3. Streak calculation
   4. Streak recovery (grace period)
   5. Progress charts
   6. Habit templates
   7. Daily reminder notifications
   8. AI weekly summary

   DONE WHEN — one observable condition per feature:
   □ User checks a habit and the streak counter increments immediately
   □ Streak breaks correctly on a missed day; grace period allows recovery for 1-day gaps
   □ Monthly calendar shows the correct completion pattern for each habit
   □ AI weekly summary generates a coaching comment per habit on Monday
   □ App opens with 3 seeded example habits — daily check-in screen is usable immediately

   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 3 example habits (Drink Water, Read 20 mins, Exercise) on first login so the daily check-in screen is populated. User can edit or delete the examples at any time.
   ✓ 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 2–4 days
□ 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>