Smart Fitness App: Phased Implementation Plan & Verification Roadmap
ArtifactThis is the artifact used in Episode 4: The No-Code App Implementation Plan. You can use this roadmap to orchestrate milestone-driven development with dual-layer verification and Git branch/tag gates.
Sign in to access this artifact
Sign in with your Google Developer Profile to view and copy the full artifact used in the Build It! series.
Developer Profile Required
You are not eligible for a developer profile. Notify your workspace administrator to enable this feature.
Create a Developer Profile
Create a free Google Developer Profile to unlock all Build It! prompts and artifacts.
Join Builder Central to Unlock
Claim your free Builder member badge in one click to unlock all Build It! prompts and artifacts.
Status: Approved & Ready for Execution
Target Audience: Autonomous AI Developer Agent & Human Project Lead
Companion Documents: Data Architecture Spec, Client Architecture Spec, AI Trainer Agent Spec
Executive Summary & Execution Strategy
This implementation plan orchestrates the complete build of the Smart Fitness application from foundational schemas to production readiness.
The Execution Paradigm: Milestone-Driven with Dual-Layer Verification
To balance high agent velocity against architectural precision, this plan follows a Phase-Gated Milestone Framework:
- Autonomous Execution within Milestones: The implementing agent works continuously through the steps of each milestone, writing code, executing builds, fixing compiler errors, and self-healing issues without human micromanagement.
- Layer 1 Verification — Autonomous Agent Pre-Gate Barrier: Before requesting human sign-off, the agent must run compiler checks, execute backend test scripts, and launch Google Antigravity Autonomous Browser Verification (using Chrome DevTools) to simulate real mobile user interactions, execute the plain-English test cases, inspect DOM state, and capture screenshots.
- Layer 2 Verification — Human Gatekeeper Checkpoint: Once the agent's automated checks pass, the human gatekeeper reviews a concrete 2-minute checklist to verify UX feel, business alignment, and data integrity before granting permission to advance to the next milestone.
The Version Control & Git Tagging Protocol
To ensure disaster recovery, transparent code review diffs, and zero compounding errors across milestones, the implementing agent must strictly observe the following Git protocol:
- Branching Strategy:
main: Protected branch. Only human-approved milestone releases are merged here.- Milestone Feature Branches: Dedicated branch per milestone (
feat/m1-scaffolding-typesthroughfeat/m6-pwa-production).
- Pre-Gate Commit Ceremony:
git add -A git commit -m "feat(mX): complete milestone X tasks and pre-gate verifications" - Human Gatekeeper Diff Review:
git diff main..HEAD # or across gates: git diff gate-[N-1]-approved..HEAD - Gate Approval & Milestone Tagging:
git checkout main git merge --no-ff feat/mX-... -m "merge: approve milestone X" git tag -a gate-X-approved -m "Milestone X: Verified and approved by Gatekeeper" - Rollback & Disaster Recovery:
git checkout main git branch -D feat/mX-... git checkout -b feat/mX-... gate-[N-1]-approved
Primary Architecture Dependency Graph
M1 [Milestone 1: Foundations, Types & Database Seed] ──> G1 {Gate 1 Sign-Off}
├──> M2 [Milestone 2: Server APIs & Gemini Coach Engine] ──> G2 {Gate 2 Sign-Off}
└──> M3 [Milestone 3: Client State & Gym-Floor Tracker] ──> G3 {Gate 3 Sign-Off}
├──> M4 [Milestone 4: Coach Chat & Staged Proposal Interface] ──> G4 {Gate 4 Sign-Off}
└──> M5 [Milestone 5: Schedule, Analytics & Profile Settings] ──> G5 {Gate 5 Sign-Off}
└──> M6 [Milestone 6: PWA Offline Sync & E2E Validation] ──> G6 {Gate 6: Final Production Acceptance}Milestone 1: Project Scaffolding, Core Types & Database Layer
Objective: Establish the repository foundation, strict TypeScript domain contracts, Firebase SDK connections, and seed the static exercise encyclopedia.
- Task 1.0: Git Branch Initialization — Create and switch to
feat/m1-scaffolding-types. - Task 1.1: Project Scaffolding & Toolchain Setup — Initialize Next.js 19 (App Router) with TypeScript strict mode, Tailwind CSS v4, Tailwind Variants, Lucide React, Zustand, TanStack Query, Firebase SDKs, Google generative AI SDK, Recharts, and PWA baseline.
- Task 1.2: Canonical TypeScript Domain Type Definitions — Create
src/types/module (exercise.ts,plan.ts,session.ts,profile.ts,chat.ts,pr.ts) strictly matching the Data Architecture Spec. - Task 1.3: Firebase Client & Admin SDK Setup — Implement
src/lib/firebase/client.tsandsrc/lib/firebase/admin.ts. - Task 1.4: Exercise Encyclopedia Seeding Script — Create
scripts/seed-exercises.tsto seed/exerciseswith canonical slugs and metadata. - Task 1.5: Firestore Rules & Indexes — Deploy
firestore.rulesandfirestore.indexes.json.
Layer 1 & Layer 2 Verification (Gate 1): Run npx tsc --noEmit, npm run lint, and npx ts-node scripts/seed-exercises.ts; inspect git diff main..HEAD and verify seeded Firestore documents before tagging gate-1-approved.
Milestone 2: Backend API Route Handlers & AI Engine Pipeline
Objective: Implement the server route handlers for workout logging and the Gemini AI coaching pipeline with context caching, memory mutation handling, and staged proposals.
- Task 2.0: Git Branch Initialization — Create and switch to
feat/m2-backend-apisfrommain. - Task 2.1: Authentication Middleware Helper — Implement
src/lib/auth/server-auth.tsverifying Firebase ID tokens. - Task 2.2: Workout Logging Endpoint (
POST /api/workouts/log) — Compute session volume, apply Brzycki 1RM formula, upsert PRs, persist immutable log, and mark scheduled day ascompleted. - Task 2.3: Gemini Context Caching & Dynamic Prompt Assembly — Set up
cachedContents.createwith Primary System Instructions and dynamic runtime context assembly. - Task 2.4: Unified Chat Endpoint (
POST /api/coach/chat) — Enforce structured JSON schema output, dual-write toweekly_chats, and enforce Staged Mutation Isolation. - Task 2.5: Autonomous Memory Mutation Processor — Apply
memory_mutations(CREATE,UPDATE,DELETE) to/users/{userId}/profile/main. - Task 2.6: Read-Only Analytical Query Tools — Implement
get_historical_exercise_logs,get_volume_trends, andget_pr_records.
Layer 1 & Layer 2 Verification (Gate 2): Run npx ts-node scripts/test-api-routes.ts, verify staged mutation isolation, check cached latency (<2.5s), and tag gate-2-approved.
Milestone 3: Client State Infrastructure & Core Gym-Floor Tracker
Objective: Build the application shell, persistent bottom dock, local Zustand and TanStack Query state architecture, and the high-stakes /workout/active gym-floor execution view.
- Task 3.0: Git Branch Initialization — Create and switch to
feat/m3-client-state-trackerfrommain. - Task 3.1: Application Shell & Persistent Navigation — Implement
<AppContainer />and<BottomNavigationBar />with 5 tactile 48dp tap targets and dynamic center button. - Task 3.2: Client State Management & Step-Graph Flattener — Implement
useActiveSessionStore(Zustand +localStorage) and the Step-Graph Flattener algorithm. - Task 3.3: Reusable Workout Block Component Catalog — Implement
<WorkoutHeader />,<WorkoutExerciseSummary />,<WorkoutBlock />,<ExerciseCard />,<EmptyDayPlaceholder />, and<ModifyWithCoachCard />. - Task 3.4: Daily Workout Preview Views — Implement
DailyWorkoutViewfor/todayand/workouts/:day. - Task 3.5: Active Workout Execution Screen (
/workout/active) — Implement stopwatch header,<CurrentSetTargetCard />(<16ms optimistic UI),<ActiveRestTimerDock />,<ExerciseSetsTable />,<SwapExerciseModal />, and<FinishConfirmationModal />. - Task 3.6: Exercise Detail Encyclopedia View (
/exercises/:exerciseId) — Implement auto-looping muted<ExerciseVideoPlayer />, target muscles, steps, and form tips.
Layer 1 & Layer 2 Verification (Gate 3): Execute Suites 1, 2, 5, and 6 in Chrome DevTools mobile viewport (390x844), verify localStorage reload recovery, and tag gate-3-approved.
Milestone 4: AI Coach Conversational Hub & Staged Proposal Interface
Objective: Implement the conversational coaching interface (/coach) with speech-to-text dictation, prompt chip recommendations, context banner attachments, and interactive staged proposal cards.
- Task 4.0: Git Branch Initialization — Create and switch to
feat/m4-coach-chatfrommain. - Task 4.1: Chat State & Real-Time Sync — Implement
useCoachChatStorewith FirestoreonSnapshotsubscription. - Task 4.2: Coach Chat View Layout & Message Stream — Implement
<CoachHeader />,<ChatMessageList />,<ChatBubble />, and Coach Thinking Spinner. - Task 4.3: Context Attachment & Prompt Chips — Implement
<ContextBanner />,<ContextualPromptsBar />,<ChatInputBar />, and<SpeechToTextButton />. - Task 4.4: Staged Proposal Card Implementation — Implement
<StagedProposalCard />forUPDATE_DAYandUPDATE_WEEKdiffs. - Task 4.5: Human-in-the-Loop Proposal Commitment — Commit
proposal.datato Firestoreweekly_plansonly when[Accept Plan]is tapped.
Layer 1 & Layer 2 Verification (Gate 4): Execute Suite 4 in Chrome DevTools, verify staged mutation isolation and [Accept Plan] commit, and tag gate-4-approved.
Milestone 5: Schedule Overhaul, Progress Analytics & Profile Settings
Objective: Complete the remaining application views: Week Schedule (/week), Progress & Analytics (/progress), and Profile/Settings (/settings) with 3-tier memory management.
- Task 5.0: Git Branch Initialization — Create and switch to
feat/m5-schedule-progress-settingsfrommain. - Task 5.1: Week Schedule View (
/week) — Implement<WeekHeader />,<WeeklyStatsSummary />,<DayScheduleCard variant="normal" />, and<ModifyWeekWithCoachCard />. - Task 5.2: Progress & Analytics View (
/progress) — Implement<PRShowcaseBanner />, Recharts<VolumeProgressChartCard />(4W | 3M | 1Y),<AllTimeStatsGrid />, and<WorkoutHistorySection />. - Task 5.3: Profile, Settings & AI Memory View (
/settings) — Implement<UserProfileCard />,<EquipmentSelectorCard />,<PreferencesGroup />, and<MemoryTierViewerCard />with[🗑]deletion.
Layer 1 & Layer 2 Verification (Gate 5): Execute Suites 3, 7, and 8 in Chrome DevTools, verify chart toggles and memory deletion, and tag gate-5-approved.
Milestone 6: Production Hardening, PWA Offline Buffer & Full Matrix Sign-Off
Objective: Harden the application for real gym environments: configure offline PWA asset caching, implement offline workout log sync, and execute the complete 42-test plain-English verification matrix.
- Task 6.0: Git Branch Initialization — Create and switch to
feat/m6-pwa-productionfrommain. - Task 6.1: PWA Service Worker & Asset Caching — Finalize Serwist / next-pwa service worker and standalone PWA manifest.
- Task 6.2: Basement Gym Offline Sync Buffer — Implement offline queue in IndexedDB/localStorage for
POST /api/workouts/logwith automatic reconnection flush. - Task 6.3: Error Boundaries & Fallback Views — Verify 404 fallback, invalid day fallback, and invalid exercise fallback.
- Task 6.4: Full Matrix Execution & Performance Audit — Execute all 42 plain-English test cases across Suites 1–8 and run Lighthouse audit (Performance >90, LCP <2.5s, touch targets ≥48dp).
Layer 1 & Layer 2 Verification (Gate 6): Run npm run build, simulate offline network mode in Chrome DevTools, verify full 42/42 test suite pass, and tag v1.0.0.
Summary of Verification Gates for Human Gatekeeper
| Gate | Focus Area | Git Branch & Release Tag | Key Agent Deliverable | Expected Human Verification Time |
|---|---|---|---|---|
| Gate 1 | Types, DB Schema & Seed | feat/m1-scaffolding-typesTag: gate-1-approved |
src/types/, seed script executed, clean compile |
~2 minutes (inspect diff & seeded DB) |
| Gate 2 | Backend APIs & Gemini Pipeline | feat/m2-backend-apisTag: gate-2-approved |
/api/workouts/log, /api/coach/chat, integration tests |
~3 minutes (run API test script & check schema) |
| Gate 3 | Client State & Active Tracker | feat/m3-client-state-trackerTag: gate-3-approved |
Shell, /today, /workout/active, browser test passed |
~3 minutes (tap workout controls & test stopwatch) |
| Gate 4 | Coach Chat & Staged Proposals | feat/m4-coach-chatTag: gate-4-approved |
/coach, <StagedProposalCard />, proposal commit |
~3 minutes (chat with coach, test [Accept Plan]) |
| Gate 5 | Schedule, Analytics & Settings | feat/m5-schedule-progress-settingsTag: gate-5-approved |
/week, /progress, /settings, memory manager |
~3 minutes (review charts & delete a test memory) |
| Gate 6 | PWA Offline Sync & Full Release | feat/m6-pwa-productionTag: v1.0.0 |
Production build, PWA cache, 42/42 tests passed | ~5 minutes (review final report & mobile sanity check) |