/vertical-fitness

name: vertical-fitness
description: Domain-knowledge pack for fitness & wellness (boutique studios, gyms, coaches, on-demand brands) — the membership vocabulary, non-obvious billing/booking rules, and retention realities a builder must know so fitness products aren't speced naive. Covers the four products this niche ships (class-booking, coaching, churn-prevention, on-demand-video), how they wedge against Mindbody / PushPress / Zen Planner / Wodify / WellnessLiving, and the must-model entities (membership with freeze, recurring class template, waitlist, no-show policy, access tier). Applied by architect/pm during spec authoring so the schema and flows reflect how a studio actually bills and books, not a generic CRUD app.
when_to_use: |
  Apply when architect/pm specs a fitness/wellness product:
  - architect writes ARCH-*.md for a class-booking / coaching / churn-prevention / on-demand-video product in the fitness niche
  - pm decomposes any of those four products into tasks and needs the domain rules to not under-scope (billing + waitlist are where naive specs fail)
  - design-advisor wireframes a member-facing booking flow or a studio-owner dashboard
  Do NOT apply for non-membership verticals (the entity model here assumes recurring billing, class capacity, and attendance-driven retention).
effort: low
allowed-tools: Read, Write, Grep, Glob
paths:
  - "docs/architecture/**"
  - "docs/plans/**"
  - "docs/design/**"

Fitness & wellness — spec it like a studio bills and books

Boutique studios, gyms, coaches, on-demand brands. Members on recurring plans, classes with finite capacity, retention won or lost on attendance. A builder who models this as "events + tickets" ships something no studio owner will run their business on — because the hard parts are *billing* and *waitlists*, not the calendar. This skill is the domain briefing so the spec is right before code starts.

1. Domain vocabulary (know these or look naive)

• **Class pack vs unlimited membership vs drop-in** — three distinct

products. A **pack** is N prepaid classes that decrement (10-class pack); an **unlimited membership** is a recurring plan (often monthly auto-renew) with no per-class deduction; a **drop-in** is a single paid visit. The schema must hold all three, not collapse them into "credits".

• **Recurring billing / auto-renew** — memberships rebill on a cycle

(monthly is the norm) until cancelled. This is the revenue engine and the hardest thing to get right (see §2).

• **Waitlist** — a full class has an ordered queue; when a spot opens

(someone late-cancels), the system **auto-promotes** the next person and notifies them. Core, not optional.

• **Late-cancel / no-show fee** — cancelling inside the policy window

(e.g. <12h) or not showing forfeits the class (pack decrements) or charges a fee. The policy *is* the booking discipline.

• **Class capacity** — every class has a hard cap (bikes, mats, reformers).

Booking beyond cap goes to the waitlist, never overbooks.

• **Recurring class schedule** — classes are templates ("Mon/Wed/Fri 6am

Spin") that generate dated instances, with per-instance overrides (holiday cancel, sub instructor). Not a list of one-off events.

• **Check-in** — marking a member present at class; drives attendance

history, which drives churn signals and pack decrement.

• **Freeze / hold** — a member pauses a membership (travel, injury) without

cancelling; billing suspends, the plan resumes later. Expected feature.

• **MRR / churn rate / LTV** — monthly recurring revenue, the % of members

who cancel per month, and lifetime value. The owner's scoreboard.

• **Punch card** — a physical-metaphor pack (10 punches); same model as a

class pack with a remaining balance.

• **Family / household account** — one billing account, multiple members

(parent + kids, couples); shared or separate balances.

• **Mindbody discovery marketplace** — Mindbody's consumer app where users

*find and book* studios. Listing there is a customer-acquisition channel, not just software — see §2 and §5.

2. Non-obvious domain rules (what makes this vertical specific)

• **Billing is the hard part, not booking.** Packs that decrement,

memberships that auto-renew, **freezes/holds** that suspend billing, **proration** on mid-cycle plan changes, and failed-payment retry/dunning are where naive specs collapse. Design the membership/pack/freeze model first; the calendar is the easy half.

• **No-show / late-cancel fees + waitlist promotion are core booking

logic.** A cancel inside the window triggers a fee *and* frees a spot that must **auto-promote** the next waitlisted member with a notification. The two rules are coupled — model them together.

• **Recurring class schedules generate per-instance bookings.** Members

book a *specific dated instance* ("this Friday's 6am"), but the schedule is a recurring template with exceptions. Booking, capacity, and waitlist all attach to the instance, not the template.

• **Class capacity + waitlist auto-promote is the heart of booking.** Cap is

hard; overflow queues; promotion is automatic and time-sensitive (a spot freed 2h before class should offer to the waitlist immediately).

• **Mindbody's moat is the consumer discovery app — displacing it is a real

trade-off.** Replacing Mindbody as the studio's software is easy software-wise, but a studio that delists loses Mindbody's marketplace as a lead source. **Surface this trade-off in the spec** (see §5) — don't silently assume displacement is free.

3. What a naive build gets wrong

• ❌ **Membership without freeze/hold + proration.** Modeling a plan as a

flat recurring charge with no pause and no mid-cycle math. Members travel and get injured; owners offer holds. No freeze = cancellations instead of pauses = churn the product *caused*.

• ❌ **No waitlist auto-promotion.** A waitlist that's just a list nobody

acts on. The value is the *automatic* promote-and-noti