Add skill: gloria-zhang1/hercycle

skills/gloria-zhang1/hercycle/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: hercycle
+description: Women's cycle intelligence companion. Reads Whoop biometric data (HRV, recovery, sleep, skin temperature) and menstrual cycle phase to understand which hormonal "season" the user is in — and takes smart, phase-aware actions. Use when the user asks about their cycle phase, energy, mood, what to eat, how hard to train, when to schedule important meetings, or wants any Whoop-powered recommendation tailored to their hormonal cycle. NOT a period tracker — a biometric intelligence layer that treats the cycle as a source of power, not a problem.
+---
+
+# HerCycle — Women's Cycle Intelligence
+
+Built on the insight that women's biology is cyclical, not linear. Every month has four distinct hormonal seasons — each unlocking different cognitive, emotional, and physical capabilities. HerCycle reads your biometrics and tells you which season you're in, then takes action accordingly.
+
+## The Four Seasons
+
+| Season | Phase | Days | What's Amplified |
+|--------|-------|------|-----------------|
+| 🌑 Winter | Menstrual | 1–5 | Introspection, pattern recognition, deep insight, rest & recovery |
+| 🌱 Spring | Follicular | 6–14 | Creativity, optimism, new ideas, social energy, starting things |
+| ☀️ Summer | Ovulation | ~14 | Communication, charisma, negotiation, peak performance, visibility |
+| 🍂 Autumn | Luteal | 15–28 | Detail orientation, completion, editing, boundaries, deep focus |
+
+## Data Sources
+
+HerCycle reads from:
+- **Whoop API** — HRV, recovery score, sleep quality, skin temperature (ovulation signal)
+- **Cycle tracking** — stored in WhoopClaw DB (`cycle_tracking` table), or inferred from skin temp patterns
+- **Phase inference** — if no explicit cycle log, estimate phase from skin temp trend + HRV patterns
+
+See `references/whoop-api.md` for data access patterns.
+
+## Action Modules
+
+Actions are pluggable. Each module takes the current phase + biometrics and returns a recommendation or triggers an action.
+
+Current modules:
+- **🎵 Music** — Spotify mood matching via a phase-aware playlist engine (see your WhoopClaw `spotify_engine.py` or bring your own)
+- **💪 Training** — Push hard (follicular/ovulation) vs restore (menstrual/luteal)
+- **🥗 Nutrition** — Iron-rich (menstrual), protein/carb cycling (luteal), light & fresh (ovulation)
+- **📅 Calendar** — Phase-aware scheduling nudges (big meetings → ovulation, deep work → luteal)
+- **💬 Social** — Energy level signal ("high charisma window" vs "protect your bandwidth")
+
+To add a new action module: see `references/action-modules.md`.
+
+## Usage
+
+**Check current phase:**
+> "What phase am I in?" / "What's my cycle season today?"
+
+**Phase-aware recommendation:**
+> "Should I push hard at the gym today?"
+> "What should I eat this week?"
+> "Is this a good week for a big presentation?"
+
+**Trigger an action:**
+> "Play music for my phase" / "Give me a playlist for my cycle phase"
+
+## Setup Requirements
+
+HerCycle requires a running WhoopClaw instance — an open-source FastAPI backend that handles Whoop OAuth, cycle tracking, and biometric storage. Search GitHub for "WhoopClaw" to find an implementation, or build your own against the Whoop Developer API.
+
+**Prerequisites:**
+1. **Whoop API credentials** — register at [developer-dashboard.whoop.com](https://developer-dashboard.whoop.com) to get your `WHOOP_CLIENT_ID` and `WHOOP_CLIENT_SECRET`
+2. **WhoopClaw running locally** — clone, configure `.env`, and start the server (`uvicorn main:app`)
+3. **Whoop account connected** — complete the OAuth flow via WhoopClaw's `/whoop/authorize` endpoint
+
+Once running, configure `WHOOPLAW_BASE_URL` to point to your instance (default: `http://localhost:8000`).
+
+Key endpoints HerCycle uses:
+- `GET /whoop/recovery` — latest recovery + HRV
+- `GET /cycle/current-phase?telegram_id=<id>` — current cycle phase
+- `GET /cycle/predictions?telegram_id=<id>` — next period prediction
+- `GET /whoop/metrics/skin-temp` — skin temperature trend (ovulation signal)
+
+Always pull live data before making recommendations. Do not rely on stale cached values.
+
+## Philosophy
+
+> *"Every month I experience four seasons... in this season, certain sensitivity and capacity is amplified."* — Chloé Zhao, Oscar-winning director (BBC 100 Women)
+
+The goal is not to manage around the cycle. It's to move with it — scheduling, eating, training, socialising, and creating in alignment with what's naturally amplified. The cycle is the intelligence. HerCycle makes it legible.

skills/gloria-zhang1/hercycle/references/action-modules.md

@@ -0,0 +1,56 @@
+# Action Modules — HerCycle Reference
+
+## Adding a New Module
+
+Each module receives:
+- `phase`: one of `menstrual | follicular | ovulation | luteal`
+- `recovery_score`: 0–100
+- `hrv`: ms
+- `sleep_quality`: 0–100
+
+And returns a recommendation string or triggers an external action.
+
+## Module: Training
+
+| Phase | Recommendation |
+|-------|---------------|
+| Menstrual | Rest or gentle movement. Yoga, walks. No high intensity. |
+| Follicular | Build intensity. Strength training, cardio. Body adapts well. |
+| Ovulation | Peak performance window. PR attempts, HIIT, competitions. |
+| Luteal | Moderate. Pilates, swimming. Reduce intensity as phase progresses. |
+
+Cross with Whoop recovery score: if recovery < 50, drop one intensity level regardless of phase.
+
+## Module: Nutrition
+
+| Phase | Focus |
+|-------|-------|
+| Menstrual | Iron-rich foods (leafy greens, lentils, red meat). Anti-inflammatory. Warm foods. |
+| Follicular | Light, fresh. Fermented foods for gut health. Increased carb tolerance. |
+| Ovulation | Raw, light foods. Fibre to support estrogen clearance. |
+| Luteal | Complex carbs, magnesium (dark chocolate, nuts). Higher calorie needs. Reduce caffeine. |
+
+## Module: Calendar / Scheduling
+
+| Phase | Nudge |
+|-------|-------|
+| Menstrual | Block deep thinking time. Avoid high-stakes social commitments. |
+| Follicular | Good for brainstorming, new projects, creative meetings. |
+| Ovulation | Schedule negotiations, pitches, presentations, networking. |
+| Luteal | Deep solo work, editing, finishing. Protect social energy. |
+
+## Module: Music (Cycle DJ)
+
+Implement a phase-aware Spotify playlist engine in your backend. Mood mapping:
+- Menstrual → `cozy_coffee`
+- Follicular → `main_character`
+- Ovulation → `power_hour`
+- Luteal (early) → `deep_focus`
+- Luteal (late/PMS) → `luteal_rage`
+
+## Module: Social Energy
+
+Simple signal to surface:
+- Ovulation: "High charisma window — good time to reach out, go to events"
+- Late luteal: "Protect your bandwidth — cancel non-essential social plans guilt-free"
+- Menstrual: "Recharge mode — solo time is productive time"

skills/gloria-zhang1/hercycle/references/whoop-api.md

@@ -0,0 +1,41 @@
+# Whoop API — HerCycle Reference
+
+Configure `WHOOPLAW_BASE_URL` to point to your WhoopClaw server (e.g. `http://localhost:8000`).
+
+## Key Endpoints
+
+```bash
+# Recovery + HRV
+GET /whoop/recovery
+
+# Sleep
+GET /whoop/sleep
+
+# Skin temperature (ovulation signal — rises ~0.2–0.5°C at ovulation)
+GET /whoop/metrics/skin-temp
+
+# Current cycle phase (if user has logged)
+GET /cycle/current
+
+# Log cycle day manually
+POST /cycle/log
+{ "cycle_day": 1, "phase": "menstrual" }
+```
+
+## Phase Inference from Skin Temp
+
+If no explicit cycle log exists, estimate phase from skin temperature trend:
+- Sustained rise of 0.2°C+ over 2–3 days → ovulation occurred → now luteal
+- Temp drops back to baseline → menstrual phase approaching
+- Low stable temp → follicular
+
+## HRV × Phase Correlation
+
+| Phase | Typical HRV pattern |
+|-------|-------------------|
+| Menstrual | Lower HRV, higher recovery need |
+| Follicular | Rising HRV, high adaptability |
+| Ovulation | Peak HRV, high readiness |
+| Luteal | Declining HRV, more recovery needed |
+
+Cross-reference Whoop recovery score with expected phase pattern to validate.