tabatago/AGENTS.md

TabataGo — Référence canonique pour agents IA

Une seule source de vérité. Ce document décrit le projet réel. Si un autre fichier (CLAUDE.md, schema.sql) contredit, ce document gagne.

---

0. ⚠️ Fichiers obsolètes — NE PAS LIRE

Fichier	Statut	Pourquoi
CLAUDE.md (racine)	❌ OBSOLÈTE	Décrit TabataFit, un concept Expo/React Native abandonné
supabase/schema.sql	❌ OBSOLÈTE	Header littéral "TabataFit" — décrit l'ancien schéma
supabase/seed.sql, supabase/setup-admin.sql	⚠️ Vérifier	Peuvent être périmés ; préférer supabase/migrations/
AGENTS.md (ancien, racine)	🔄 Remplacé par celui-ci	Mentionne PostHog 3.x comme actif (faux, voir §3)

Source de vérité du schéma : supabase/migrations/001 → 006. Jamais schema.sql.

---

1. Identité produit

Nom	TabataGo
Bundle	fr.millianlmx.tabatago
Team	2MJF39L8VY
But	App d'entraînement Tabata (intervalles 20s travail / 10s repos) sur iOS + watchOS, avec programmes par zone corporelle, HealthKit, musique, et abonnements RevenueCat
Version	1.0 (build 2) — non publiée App Store
Propriétaire	Millian LMX (CEO)
Gitea	https://gitea.1000co.fr/millianlmx/tabatago

---

2. Stack technique

Couche	Réalité vérifiée
Langage	Swift 6.0, concurrence stricte (SWIFT_STRICT_CONCURRENCY: complete)
UI	SwiftUI uniquement
iOS	26.0+
watchOS	11.0+
Build	XcodeGen — project.yml est la source, .xcodeproj est généré
SPM	Supabase 2.5.0+, RevenueCat 5.0.0+
❌ NON installé	PostHog — absent de project.yml packages. Voir §3.
Architecture	MVVM + @Observable, AppState.shared central
Backend	Supabase (PostgreSQL, Auth, Storage, Edge Functions Deno)
Local cache	SwiftData (TabataGoSchema.container)
Santé	HealthKit (fréquence cardiaque, calories, workouts)
CI/CD	Gitea Actions sur runner macOS auto-hébergé (label macos)

---

3. Architecture iOS

Cibles (tabatago-swift/project.yml)

Cible	Type	Plateforme	Bundle ID
TabataGo	application	iOS 26.0	fr.millianlmx.tabatago
TabataGoWatch	application	watchOS 11.0	fr.millianlmx.tabatago.watchkitapp
TabataGoWatchWidget	app-extension	watchOS 11.0	fr.millianlmx.tabatago.watchkitapp.widget
TabataGoTests	bundle.unit-test	iOS	.tests
TabataGoUITests	bundle.ui-testing	iOS	.uitests

Dépendances d'intégration : TabataGo embed TabataGoWatch qui embed TabataGoWatchWidget. Fichier partagé entre iOS et watch : TabataGo/Services/WatchConnectivityTypes.swift (compilé dans les deux targets via group: TabataGoWatch/Services).

Bootstrap & data flow

TabataGoApp (@main)
  └─ RootView()
       ├─ .environment(AppState.shared)       // @Observable singleton
       ├─ .modelContainer(TabataGoSchema.container)  // SwiftData
       └─ .task { await AppState.shared.bootstrap() }

AppState.bootstrap() (MainActor, idempotent, skip en preview) :

1. PurchaseService.shared.initialize() (RevenueCat)
2. AnalyticsService.shared.initialize() — ⚠️ no-op par défaut car PostHog n'est pas dans SPM : tout est gardé par #if canImport(PostHog) qui est toujours faux. La taxonomie d'events existe mais n'émet rien tant que la dépendance n'est pas ajoutée.

Navigation (PAS de NavigationStack)

MainTabView = TabView + Tab(value:) (Liquid Glass, iOS 26), 4 onglets dans cet ordre exact du code :

home → programs → activity → profile

Modals full-screen via .sheet/fullScreenCover au-dessus : PlayerView, CompletionView, PaywallView, OnboardingView.

Services (TabataGo/Services/)

Service	Rôle
SupabaseService	Client Supabase (Auth, DB, Storage)
HealthKitService	Lecture/écriture HealthKit
PurchaseService	RevenueCat IAP, état d'abonnement
MusicService	Apple Music + intégration piste YouTube
AudioService	Playback audio (coachs sonores, alerts)
AnalyticsService	Stub PostHog (voir ci-dessus)
PhoneConnectivityManager	Côté iOS — WatchConnectivity (échange avec la montre)
WatchConnectivityTypes	Protocoles/messages partagés iOS↔Watch (compilé dans les 2 targets)

Le miroir côté watch est TabataGoWatch/Services/WatchConnectivityManager.swift (cible watchOS, pas iOS).

ViewModels (@Observable)

HomeViewModel, HealthViewModel, PlayerViewModel, PurchaseViewModel, MusicPlayerViewModel.

Models (TabataGo/Models/)

WorkoutProgram, WorkoutSession, UserProfile, HealthSnapshot, MusicTrack, WorkoutActivityAttributes, MusicActivityAttributes (Live Activities), TabataGoSchema (SwiftData), PreviewData/MockPrograms (previews).

Watch (TabataGoWatch/)

TabataGoWatchApp → WatchRootView → états WatchIdleView / WatchActivityView / WatchPlayerView. Moteur : WatchPlayerEngine. Connectivité : WatchConnectivityManager (coté watch). Complications : TabataGoComplication.

---

4. Base de données

Supabase — source = supabase/migrations/ (001→006)

#	Fichier	Contenu
001	001_initial_schema.sql	trainers, workouts, collections, achievements, admin_users
002	002_download_jobs.sql	download_jobs, download_items (jobs d'import playlist YouTube)
003	003_music_genre.sql	music_genre
004	004_download_items_public_read.sql	RLS : lecture publique de download_items
005	005_workout_programs.sql	DROP programs/program_workouts → CREATE workout_programs (body_zone enum upper-body/lower-body/full-body + level Beginner/Intermediate/Advanced) et program_tabatas (3 tabatas/program, 2 exercices chacun, 8 rounds × 20s/10s) + RLS public read + admin all
006	006_seed_workout_programs.sql	18 programmes seedés (12 free : 4 par zone en 2B+1I+1A ; 6 premium) + 54 tabatas (18×3), UUIDs stables

Tables actives post-migration : trainers, workouts, collections, achievements, admin_users, download_jobs, download_items, music_genre, workout_programs, program_tabatas.

Tables supprimées (ne pas recréer) : programs, program_workouts (DROP en 005).

RLS : lecture publique sur workout_programs/program_tabatas/download_items ; écriture restreinte aux admin_users (EXISTS (SELECT 1 FROM admin_users WHERE id = auth.uid())).

SwiftData — cache local

TabataGoSchema.container (et .previewContainer pour les #Preview). Persistance offline des sessions/programmes côté app. Ne pas confondre avec Supabase.

---

5. CI/CD

Workflow : .gitea/workflows/pr-iphone-deploy.yml

Trigger : PR ouverte/synchronize/reopened sur main. Runner : label macos (auto-hébergé). Déroulé :

1. Checkout (shallow, branche head) via PR_API_TOKEN.
2. Setup PATH : echo "/opt/homebrew/bin" >> $GITHUB_PATH — requis car Rosetta ne le voit pas.
3. Clean ciblé :
   • Supprime build artifacts, TabataGo.xcodeproj, Package.resolved, DerivedData, ModuleCache.
   • GARDE le cache SPM (../build/spm-cache) — RevenueCat ≈ 1.1 GiB, re-cloner = 5+ min et échecs aléatoires du sandbox.
4. Install tools : brew install xcodegen node ios-deploy.
5. xcodegen generate → xcodebuild -resolvePackageDependencies → build (-scheme TabataGo, Debug, auto-provisioning, team 2MJF39L8VY).
6. Deploy iPhone UDID 00008120-000925CE3672201E : devicectl WiFi d'abord, fallback ios-deploy USB.
7. Post comment "Prêt à tester" sur la PR.
8. Job wait-approval : poll (30s, max 240 = 2h) les commentaires de la PR. LGTM → auto-merge. KO → blocage. Timeout → fail.

Secrets

Secret	Usage
PR_API_TOKEN	Checkout + API Gitea (comment, merge). JAMAIS GITEA_TOKEN/GITHUB_TOKEN
SUPABASE_URL, SUPABASE_ANON_KEY, REVENUECAT_API_KEY, POSTHOG_API_KEY	Injectés via Config/Secrets.xcconfig → Info.plist

⚠️ Pitfalls CI

• /opt/homebrew/bin hors PATH par défaut sous Rosetta → toujours l'ajouter.
• xcodegen 2.45.4 ne génère pas de schemes auto → scheme TabataGo défini explicitement dans project.yml (ne pas le supprimer).
• Ne jamais rm -rf le cache SPM dans le CI (c'est l'inverse des build artifacts).
• SWIFT_ENABLE_EXPLICIT_MODULES=NO au build — requis sinon segfault linker sur .pcm stale.
• -skipPackagePluginValidation -allowProvisioningUpdates.

---

6. Sous-projets

admin-web/ — Dashboard admin

Next.js 15 App Router, shadcn/ui. Gestion workouts / trainers / collections / programs. Auth Supabase → table admin_users. Stack : TypeScript, middleware.ts, tests Playwright (e2e/) + Vitest.

youtube-worker/ — Worker YouTube

Node.js (server.js, package.json, Dockerfile). Télécharge l'audio de playlists YouTube → Supabase Storage. Piloté par les Edge Functions ci-dessous.

supabase/functions/ — Edge Functions (Deno)

Function	Rôle
youtube-playlist/	Crée un download_job, liste les vidéos
youtube-process/	Orchestre le téléchargement (via youtube-worker)
youtube-status/	Statut d'un job
youtube-classify/	Classification genre musical
main/	Auth JWT (helper jose)
_shared/	auth.ts, cors.ts, supabase-client.ts, youtube-client.ts

Le pipeline musical complet : Edge Functions orchestrent → youtube-worker (Node.js) télécharge via yt-dlp + Innertube → audio dans Supabase Storage (workout-audio bucket) → classification automatique par Gemini (gemini-3.1-flash-lite-preview) → métadonnées dans download_jobs/download_items → genre dans music_genre.

---

7. Règles d'or pour les agents

1. Source de vérité = project.yml + supabase/migrations/. Tout le reste est dérivé ou obsolète.
2. SwiftUI only. Pas d'UIKit sauf nécessité absolue démontrée.
3. @Observable (macro Observation), jamais @ObservableObject/@Published.
4. Concurrency stricte. async/await partout, @MainActor sur l'UI, pas de completion handlers.
5. Pas de force-unwrap. guard let/if let, jamais !.
6. Navigation = TabView + sheet/fullScreenCover. Pas de NavigationStack.
7. Tout en français côté user-facing (Localizable.xcstrings / L10n). Codes/types restent en anglais.
8. XcodeGen. Éditer project.yml, pas .xcodeproj. Régénérer avec xcodegen generate.
9. Secrets. Jamais committer Config/Secrets.xcconfig. Template = .example.
10. Lazy d'abord. Avant d'ajouter une dépendance : stdlib Apple, puis ce qui existe déjà dans le repo, puis SPM déjà installé. PostHog n'est pas installé — ne pas l'ajouter sans justification.

---

8. Anti-patterns / pièges documentés

❌ Ne pas faire	✅ Faire
Lire CLAUDE.md ou schema.sql pour le schéma	Lire supabase/migrations/001→006
Importer PostHog comme si c'était actif	Savoir que AnalyticsService est un no-op (PostHog pas en SPM)
Utiliser NavigationStack	TabView + modals
@ObservableObject / @Published	@Observable
Force-unwrap !	guard let
Strings UI en anglais	Françaises dans L10n/Localizable.xcstrings
rm -rf le cache SPM en CI	Garder build/spm-cache
Utiliser GITEA_TOKEN en CI	PR_API_TOKEN uniquement
Supprimer le scheme explicite dans project.yml	xcodegen 2.45.4 n'en crée pas
Compter sur admin-web/ pour la app iOS	Dashboard admin séparé, communique via Supabase uniquement
Recréer programs/program_workouts	Remplacés par workout_programs/program_tabatas (migration 005)

---

9. Contexte projet & skills

• Repo Gitea : https://gitea.1000co.fr/millianlmx/tabatago (branche intégration : main).
• Équipe : "Millian Team" — équipe d'agents IA. Skills à loader selon la tâche :
  • senior-ios — SwiftUI, Xcode, iOS/watchOS
  • senior-backend — Supabase, SQL, Edge Functions
  • senior-devops — CI/CD Gitea Actions, deploy
  • po-pm — vision produit, specs, validation
• Team skill TabataGo : documente les anti-patterns ci-dessus ; aligne tous les agents sur les mêmes conventions.
• Hermes profile actif : default. Les skills vivent dans le profile sous skills/.
• Docs utiles : docs/ci-cd-setup.md, docs/app-store-submission.md, docs/maestro-e2e-testing-strategy.md, docs/ui-feature-brief.md.
• Scripts : scripts/ci-status.py, scripts/deploy-functions.sh.

Commandes usuelles

# Générer le projet Xcode
cd tabatago-swift && xcodegen generate

# Ouvrir
open tabatago-swift/TabataGo.xcodeproj

# Déployer les Edge Functions
bash scripts/deploy-functions.sh

# Statut CI
python3 scripts/ci-status.py