# AGENTS.md — AI Coding Agent Instructions > **For:** Claude Code, OpenAI Codex, Cursor, GitHub Copilot, Windsurf Cascade, and any AI coding agent. > **Repo:** `learning_ai_clock` — ChronoMind AI-powered contextual clock & timer. > **See also:** [`docs/PRD.md`](docs/PRD.md) for full product spec, [`docs/roadmap.md`](docs/roadmap.md) for implementation plan. --- ## 1. Project Identity | Key | Value | |-----|-------| | **Product** | ChronoMind | | **Product ID** | `chronomind` | | **Bundle ID (iOS)** | `com.saravana.chronomind` | | **Bundle ID (Android)** | `com.chronomind.app` | | **Domain** | chronomind.app (TBD) | | **Repo** | `learning_ai_clock` | | **Ecosystem** | ByteLyst (shares platform-service with LysnrAI, MindLyst, NomGap) | ## 2. Repo Layout ``` learning_ai_clock/ ├── web/ # Next.js 16 PWA (App Router) │ ├── src/ │ │ ├── app/ # Pages: dashboard, focus, history, routines, settings, landing, privacy, terms │ │ ├── components/ # React components (12 files) │ │ │ ├── Dashboard.tsx # Main timeline + timer list │ │ │ ├── CreateTimerModal.tsx # Timer creation with NL input │ │ │ ├── AlarmOverlay.tsx # Full-screen critical alarm │ │ │ ├── PomodoroView.tsx # Pomodoro session UI │ │ │ ├── CountdownRing.tsx # Visual countdown ring │ │ │ ├── RoutineEditor.tsx # Create/edit routines │ │ │ ├── RoutineRunner.tsx # Execute routines step-by-step │ │ │ ├── StatsView.tsx # Charts + analytics │ │ │ ├── StreakCard.tsx # Streak display │ │ │ ├── TimerCard.tsx # Individual timer card │ │ │ ├── FocusView.tsx # Focus mode UI │ │ │ └── Toast.tsx # In-app toast notifications │ │ └── lib/ # Pure engine modules (16 files + 16 test files) │ │ ├── timer-engine.ts # Timer state machine (424 lines) │ │ ├── cascade.ts # Pre-warning cascade system │ │ ├── urgency.ts # 5 urgency levels │ │ ├── routines.ts # Routine engine │ │ ├── linked-timers.ts # Timer chaining │ │ ├── nl-parser.ts # Natural language parsing │ │ ├── recurrence.ts # Recurring timer rules │ │ ├── categories.ts # Timer categories/tags │ │ ├── context-messages.ts # Contextual pre-warning messages │ │ ├── prep-time.ts # Prep time intelligence │ │ ├── adaptive-snooze.ts # Snooze pattern learning │ │ ├── calendar-import.ts # .ics import │ │ ├── stats.ts # Statistics + streaks │ │ ├── sounds.ts # Web Audio API alarm tones │ │ ├── notifications.ts # Web Push + Service Worker │ │ ├── platform-sync.ts # Sync client for platform-service │ │ ├── store.ts # Zustand + localStorage │ │ ├── routine-store.ts # Routine Zustand store │ │ ├── format.ts # Time formatting │ │ ├── time-blindness.ts # Familiar time references │ │ ├── export.ts # JSON/CSV export + import │ │ ├── analytics.ts # Analytics stub │ │ ├── use-sync.ts # React sync hook │ │ ├── use-tick.ts # rAF tick hook │ │ ├── use-theme.ts # Theme hook │ │ ├── use-keyboard-shortcuts.ts │ │ └── schemas.ts # Zod schemas │ ├── e2e/ # Playwright E2E tests │ │ └── core-flows.spec.ts # 10 test suites │ ├── public/ # Static assets + manifest │ ├── next.config.ts # Serwist PWA config │ ├── package.json # Next.js 16, React 19, Zustand, Vitest │ └── vitest.config.ts │ ├── ios/ # Native SwiftUI (iOS + watchOS + macOS) │ ├── ChronoMind/ # iOS app │ │ ├── App/ # Entry point + ContentView │ │ ├── Shared/ # Cross-platform Swift code │ │ │ ├── TimerEngine/ # Cascade, Format, TimerEngine, TimeBlindness, Urgency │ │ │ ├── Store/ # TimerStore (UserDefaults-based) │ │ │ ├── Notifications/ # UNUserNotificationCenter scheduling │ │ │ ├── Haptics/ # UIImpactFeedbackGenerator │ │ │ ├── Calendar/ # EventKit sync │ │ │ ├── Cloud/ # CloudKitSyncManager + PlatformSyncManager │ │ │ ├── Location/ # CoreLocation + MapKit travel time │ │ │ ├── Sleep/ # HealthKit sleep integration │ │ │ ├── Wellness/ # Mood check-in │ │ │ ├── Gamification/ # Streaks, badges, focus score │ │ │ ├── Growth/ # Referral manager │ │ │ ├── Sharing/ # Shareable timer links │ │ │ ├── Data/ # Data export manager │ │ │ ├── Reschedule/ # AI reschedule engine │ │ │ ├── Diagnostics/ # Crash reporter │ │ │ ├── Accessibility/ # VoiceOver + Dynamic Type helpers │ │ │ ├── AppGroup/ # SharedTimerData (iPhone <-> Watch <-> Widget) │ │ │ └── Theme/ # ChronoMindTheme │ │ ├── Views/ # SwiftUI screens + components │ │ │ ├── Components/ # AlarmOverlay, TimerCard, CountdownRing, etc. │ │ │ ├── CreateTimer/ # CreateTimerView, QuickTimerSheet │ │ │ ├── Focus/ # PomodoroView │ │ │ └── Gamification/ # BadgeGrid, ConfettiView, Streak, WeeklySummary, FocusScore │ │ ├── LiveActivity/ # Dynamic Island + Lock Screen │ │ └── SiriShortcuts/ # App Intents │ ├── ChronoMindWatch/ # watchOS app (4 files) │ ├── ChronoMindMac/ # macOS menu bar app (4 files) │ ├── ChronoMindWidgets/ # WidgetKit (5 files) │ ├── ChronoMindTests/ # XCTest (8 test files, 129 tests) │ ├── ChronoMind.xcodeproj/ │ └── project.yml # XcodeGen project spec │ ├── android/ # Jetpack Compose + Kotlin │ ├── app/src/main/java/com/chronomind/app/ │ │ ├── engine/ # Models.kt + TimerEngine.kt (Kotlin port) │ │ ├── data/ # Room: TimerDatabase, TimerDao, TimerEntity, TimerMapper │ │ ├── di/ # Hilt AppModule │ │ ├── ui/ │ │ │ ├── screens/ # Timeline, Focus, History, Settings (4 screens) │ │ │ ├── navigation/ # NavHost │ │ │ └── theme/ # Material 3 theme │ │ ├── notifications/ # AlarmManager, BroadcastReceiver, NotificationManager │ │ ├── service/ # ForegroundService, QuickSettingsTile │ │ ├── sync/ # PlatformApiClient, SyncRepository │ │ ├── calendar/ # CalendarSyncManager (Google Calendar via CalendarContract) │ │ ├── viewmodel/ # TimerViewModel │ │ └── widget/ # Glance widgets (3 sizes) │ ├── app/src/test/ # JUnit5 tests (30 tests) │ └── wear/ # Wear OS app (1 file, minimal) │ ├── docs/ │ ├── PRD.md # Full product requirements │ ├── roadmap.md # 5-phase implementation roadmap │ ├── roadmap-v2-review.md # Roadmap audit trail │ ├── INDUSTRY_RESEARCH.md # Competitive analysis │ └── raw_idea.md # Original concept │ └── .github/workflows/ # GitHub Actions CI ``` ## 3. Tech Stack | Layer | Technology | |-------|-----------| | **Web** | Next.js 16 (App Router), React 19, TailwindCSS v4, Zustand 5, Serwist (PWA), date-fns, Recharts, Zod, Vitest, Playwright | | **iOS** | SwiftUI (iOS 17+), WidgetKit, ActivityKit, EventKit, CoreLocation, MapKit, HealthKit, App Intents | | **watchOS** | SwiftUI (watchOS 10+), WidgetKit complications | | **macOS** | SwiftUI (macOS 14+), AppKit (menu bar) | | **Android** | Jetpack Compose, Material 3, Kotlin, Room, Hilt, Glance widgets, AlarmManager | | **Wear OS** | Compose for Wear OS | | **Backend** | Platform-service (Fastify 5, port 4003) in sibling repo `learning_ai_common_plat` | | **Database** | Azure Cosmos DB via `@bytelyst/cosmos` (`productId: "chronomind"`) | | **Tests** | Vitest (web, 373 tests), XCTest (iOS, 129 tests), JUnit5 (Android, 30 tests) | ## 4. Coding Conventions ### MUST follow - Every Cosmos document MUST include a `productId: "chronomind"` field - Web engine logic lives in `web/src/lib/` — pure TS, no React imports (testable without DOM) - Components in `web/src/components/` — React UI only - iOS shared logic in `ios/ChronoMind/Shared/` — consumed by iOS, Watch, Mac, Widgets - Android engine in `android/app/.../engine/` — pure Kotlin, no Android framework deps - Theme tokens use `--cm-*` CSS custom properties (web) or `ChronoMindTheme` (native) - Commit messages: `type(scope): description` — types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore` ### MUST NOT do - Never use `console.log` in production code - Never hardcode colors — use theme tokens - Never hardcode API URLs — use env vars or config - Never modify tests to make them pass — fix the actual code - Never delete existing comments or documentation unless explicitly asked - Never add emojis to code unless explicitly asked ## 5. Key Design Decisions ### Pre-Warning Cascade (Core Feature) - 6 presets: Aggressive, Standard, Light, Minimal, None, Custom - Each timer has cascade intervals (e.g., [120, 60, 30, 15, 5] minutes) - Cascade fires notifications at each interval before target time ### Urgency Levels - **Critical** — persistent sound, full-screen overlay, no auto-dismiss - **Important** — prominent notification, medium sound - **Standard** — normal notification - **Gentle** — subtle notification, soft sound - **Passive** — badge only, no sound ### Timer Types - **Alarm** — fires at specific time - **Countdown** — fires after duration - **Pomodoro** — work/break cycles - **Event** — days until future date with milestone warnings ## 6. Build & Test Commands ```bash # ── Web ──────────────────────────────────────────── cd web && npm run dev # Dev server (port 3000) cd web && npm run build # Production build (uses --webpack flag) cd web && npm test # Vitest (373 tests) cd web && npm run typecheck # tsc --noEmit cd web && npm run test:e2e # Playwright E2E # ── iOS (requires Xcode) ────────────────────────── # Open ios/ChronoMind.xcodeproj in Xcode # Cmd+B to build, Cmd+U to test (129 XCTests) # ── Android (requires Android SDK) ──────────────── cd android && ./gradlew :app:compileDebugKotlin cd android && ./gradlew :app:test # 30 JUnit5 tests # ── Full Verification ───────────────────────────── cd web && npm test && npm run typecheck && npm run build # ── Docker / CI Builds ─────────────────────────── # Pack @bytelyst/* tarballs so builds don't need the sibling repo cd ../learning_ai_common_plat && pnpm build ./scripts/docker-prep.sh # pack + rewrite web/package.json docker build web/ # self-contained build ./scripts/docker-prep.sh --restore # undo ``` ## 7. Backend Integration ChronoMind uses the shared **platform-service** (port 4003) from `learning_ai_common_plat`. Four ChronoMind-specific modules exist: | Module | Container | Endpoints | Tests | |--------|-----------|-----------|-------| | `timers` | `timers` (pk: `/userId`) | 7 (CRUD + delta sync + batch) | 42 | | `routines` | `routines` (pk: `/userId`) | 7 (CRUD + delta sync + batch) | 32 | | `households` | `households` (pk: `/id`) | 9 (CRUD + invite/join/leave) | 26 | | `shared-timers` | `shared_timers` (pk: `/householdId`) | 6 (CRUD + per-user ack) | 30 | All documents include `productId: "chronomind"`. ### Sync Protocol - `syncVersion` monotonic integer — optimistic concurrency, 409 on stale writes - Delta sync: `GET /timers/sync?since=` returns only changed timers - Batch upsert: `POST /timers/batch` for offline queue flush ### Sync Clients (written, not yet wired into app flow) - Web: `web/src/lib/platform-sync.ts` + `use-sync.ts` - iOS: `ios/ChronoMind/Shared/Cloud/PlatformSyncManager.swift` - Android: `android/.../sync/PlatformApiClient.kt` + `SyncRepository.kt` ## 8. Color Palette | Token | Hex | Use | |-------|-----|-----| | `--cm-bg-canvas` | `#0A0B0F` | Page background | | `--cm-bg-elevated` | `#12131A` | Elevated surfaces | | `--cm-surface-card` | `#1A1B26` | Cards | | `--cm-text-primary` | `#E8ECF4` | Main text | | `--cm-text-secondary` | `#8B92A8` | Descriptions | | `--cm-text-tertiary` | `#565C72` | Timestamps | | `--cm-accent` | `#5B8DEE` | Primary accent | | Critical urgency | `#FF4757` | Red | | Important urgency | `#FF9F43` | Orange | | Standard urgency | `#FECA57` | Yellow | | Gentle urgency | `#2ED573` | Green | | Passive urgency | `#8B92A8` | Gray | ## 9. Known Gaps (as of Feb 2026) ### iOS — Missing Swift Ports - `Recurrence.swift` — no recurring timer engine on iOS - `NLParser.swift` — no natural language parser on iOS - `ContextMessages.swift` — no contextual pre-warning messages on iOS - Routine models + UI (`RoutineListView`, `RoutineRunnerView`) not built - Still using UserDefaults — SwiftData migration pending ### Android - `RoutineScreen.kt` not built - Wear OS is minimal (1 file) ### Cross-Platform - Sync clients exist but not wired into app flow - No account creation (Apple/Google Sign-In) - No iCloud/CloudKit sync wired ### Infrastructure - No domain registered - No Vercel deployment - No TestFlight / App Store / Play Store submissions ## 10. Common Pitfalls 1. **Next.js 16 + Turbopack** — Must pass `--webpack` flag to `next build` and `next dev` (Serwist not yet compatible with Turbopack) 2. **Web engine purity** — `web/src/lib/` files must NOT import from React or Next.js 3. **iOS targets** — 4 targets share `Shared/` folder: ChronoMind (iOS), ChronoMindWatch, ChronoMindMac, ChronoMindWidgets 4. **Android Hilt** — All new `@Singleton` classes must be provided in `AppModule.kt` 5. **Sync version** — All timer mutations must increment `syncVersion` for conflict detection