One training planner for every goal: a race (17 events: running, triathlon, duathlon, cycling, open-water swim) or NO target (build endurance and aerobic base for any mix of run, ride and swim), from the athlete's own Garmin data (--from-garmin) or answers, with persistent goals (athlete.json). Use to build or adjust a multi-week plan, check the run gate (a tracked goal, optional lock), set pace targets after a time trial, view a plan, or export it (.ics, .csv, Zwift, MRC, Garmin .fit workouts when heart-rate data are known). Starts from aerobic base; quality sessions are on by default and locked per athlete only when their own data says so (active injury, a RED reset week, their settings). Respects recovery, load and injuries. Every rule is labelled research or practice in references/evidence-map.md.
81%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Low
Low-risk findings worth noting
Paths.
<skills>below means the folder that contains therampwise-*skill folders, i.e. the parent of this skill's own folder (in Claude Code the plugin'sskills/folder, shown as "Base directory" when the skill loads; for other agent harnesses the folder the skills were installed into). Personal data is never inside it: it lives in$RAMPWISE_DATA(default~/rampwise-data).
Turns the athlete's goals into a rolling plan and keeps the Google Calendar in step with it. The plan is a draft that adapts: it is rebuilt weekly from fresh Garmin data, readiness, the run gate, the load check and injuries.
python -X utf8 "<skills>/rampwise/scripts/athlete.py" show (goals, gate, injuries, schedule, HR ceilings). Obey every active injury restriction. If injury_history_known is false, ask once about injuries and niggles before planning heavier work, then record the answer with athlete.py injury-add ... or injury-none.Goals are whatever the user records in athlete.json (athlete.py goal-add); the planner never assumes one. Typical goal types and the scripts that measure them:
| Goal type | Measured by | Script |
|---|---|---|
| Aerobic base: hold a pace with HR under the easy ceiling for longer | HOLD minutes, speed at the easy HR, drift (continuous running only) | rampwise-aerobic-base/scripts/hold_check.py |
An optional run gate the user sets (for example a whole session of a given length run with no walking; it locks sessions only if preferences.quality.requires_gate is true) | walking found from FIT cadence | run_gate.py [--record] |
| A race or pace target (a distance and a time) | a short time trial -> paces.py predict / zones (rampwise) | paces.py |
| A ride speed goal (a target speed over a target distance on a flat route) | flat rides' moving speed, best by distance band, speed per heartbeat | ride_check.py, cycling_power.py |
| Longer events (a marathon, an ultra ride) | later; need the base, the shorter goals and a long-run/ride build | stored in athlete.json, no date |
Use the user's own words for sessions (for example "easy run", never a label the user dislikes) and ask if you are unsure.
rampwise-recovery readiness (readiness_check.py --brief) and load_check.py (or take the head coach's handoff blocks). Run run_gate.py --record (about a minute; it downloads recent run files).python -X utf8 "<skills>/rampwise-planner/scripts/build_plan.py" --start YYYY-MM-DD --weeks 4 --readiness green|amber|red --out "<skills>/rampwise-planner/plans/plan-YYYY-MM-DD.json". It reads history from Garmin, applies the rules below, and prints the weeks. Gate state is read from athlete.json; override with --gate passed|open.calendar_events.py PLAN.json --json prepares event payloads for the next 14 days. Before writing: list events in the window with the connector (list_events, fullText = rampwise-plan), delete old coach events (delete_event, notificationLevel NONE), look for clashes with the athlete's own events and tell them, then create_event for each, on the primary calendar, no attendees. Report how many were created and how to remove them (search [GC]).athlete.py note.Rules (set by the athlete 2026-11-16; they apply to every user):
athlete.json has no hr.easy_band (and no legacy hr.run_easy_max), build_plan.py stops with exit code 2 and prints the questions. Ask the user: do they want to share their watch zones (max HR, LTHR, resting HR, which method: %max, %HRR or %LTHR; a screenshot of the zones page works) and what they call "easy". Record it with athlete.py set hr.easy_band '{"run":[lo,hi],"bike":[lo,hi]}' and athlete.py set hr.zone_sets '{"run":{"method":"..","floors":[z1..z5],"top":MAX},"bike":{..}}'. Never assume zones.hr.target_mode.tolerance_bpm, default 3). If yes the step uses the watch's own zone ("HR Zone 2 (126-147 bpm on your watch)"); if not it uses a custom bpm range. Every session text says which: "Zone targets (...) use your watch's ... zones" or "Custom bpm (...): your ... zones do not cover this band." hr.target_mode.prefer = "custom" turns zones off.build_plan.py --hr-from-trend estimates an easy band from the user's own last 60 days (median average HR of steady sessions >= 30 min as the ceiling, 20 bpm below as the floor; needs 5 sessions per sport). Custom bpm only, never zones, printed as an ESTIMATE, not saved to athlete.json; ask the user to confirm later (practice, no paper).hr.hard_band, preferences.quality.tempo.hr_low/hr_high and preferences.climb.hr_band when the user has them; without a band the step is open and says "a few words at a time".
5b. Where the LTHR / max HR came from matters. Ask whether the LTHR is a watch estimate (auto-detect or guided test, which per Garmin's manual and the Heiber 2024 study needs a chest strap), a lab or lactate test, or a typed guess, and store it in hr.inputs.lthr_source / max_source. A watch LTHR is an estimate: in one study (Lu 2025, Forerunner 265, n = 23) it was off by about 11 bpm on average, and only 65 % of tests gave a value; another (Heiber 2024, Fenix 7, n = 26) was close on average (-1.7 %) but with a narrower spread than the field test. Label zones built on it as estimated, never as validated, and do not use a typed or default max HR that the athlete has never reached (fixed %max anchors with an estimated max were less accurate in 165 recreational runners, Eur J Appl Physiol 2025). No lab is needed to plan: the talk test and the athlete's own easy band are the practical checks. See references/evidence-map.md and references/library.md rows 20-24.hr.zone_sets must match the watch; if the user changes the method or inputs, re-record it and rebuild. Never put one user's zones, bands or sizes in the scripts.Every run and ride is built as a structured Garmin workout (scripts/workout.py): warm-up, steady / interval / tempo, rest or recovery, cool-down, repeat blocks, each step with a duration (time, distance or lap button) and a target (a watch heart-rate zone when one covers the band, otherwise a custom bpm range, pace, speed, cadence, or none). export_workouts.py PLAN.json writes one .fit file per cardio session (folder: athlete.json -> workouts.output_dir, default ~/garmin-workouts) and every file is decoded again as a check. Not tried on a real watch: Garmin does not state name limits or loading rules; the usual route is USB -> GARMIN/NewFiles (reports are mixed), so say that. Strength sessions are text only.
Session menu (every size and heart-rate band is a setting in athlete.json, with common defaults when the user has none): easy run (warm-up + steady zone-2 block + cool-down, sizes from preferences.easy_run), long run, short run; an optional MAF-style test (a fixed heart rate and equal laps on the same course, settings in tests.maf; it replaces a deload-week long run; not gated); tempo run (warm-up + a steady block at a hard-but-controlled effort + cool-down); interval run (short hard repeats with rests); strides; a 3 km time trial; climb ride (a total-ascent target reached by repeating a short climb, preferences.climb; the advice on which bike comes from preferences.climb.bike_hint). Quality sessions are ON by default for everyone (tempo, strides, 3 km time trial, interval run, ride intervals): the Run A slot of each build week rotates through them (order: preferences.quality.rotation) and they replace an easy session, so they add no volume. They are locked per athlete, from that athlete's own data: (1) an injury with status active in athlete.json locks them and freezes volume (status monitoring only adds the restriction text, resolved does nothing); (2) the reset week (RED readiness, 14 days without rest, a load jump) has no quality; (3) preferences.quality.locked = types the athlete turned off; (4) preferences.quality.requires_gate = true adds the athlete's own no-walking rule as a lock; (5) preferences.quality.unlocked = types allowed despite a lock (the athlete's own call). Previews of every type are always written to workouts/after-gate. Today's readiness never blocks future weeks: every session says "RED morning: swap for rest". If a quality session hurts, set it with athlete.py set preferences.quality.locked '["tempo"]' for that athlete only. Every calendar event carries WHY IT MATTERS (with an evidence label), the watch steps, CHECK AFTER and SAFETY (scripts/why.py).
references/evidence-map.md)athlete.json, talk test); quality is a small share of the week.athlete.json equipment.tags; nothing else is assumed. Banned exercises (constraints.no_exercises) are never prescribed (build_plan.py refuses to output them). With light loads, lower-body work uses single-leg versions, slow lowering, pauses and band tension (practice; may give a smaller effect than the heavy-strength trials).rampwise-strength/scripts/strength_plan.py, called by build_plan.py): goal profile (preferences.strength.goal) + equipment tags + constraints + the user's own Garmin set history. Sizes: short 3 moves (default), mid 4, full all; max_minutes trims sets first; sessions per week and weekdays follow the profile (preferences.strength.days). Starting weights the history cannot give are printed as ASK THE ATHLETE (strength): ask, do not guess. See the rampwise-strength skill for the 11 goal profiles and their evidence.preferences.strength.days, at least 3 h after cardio, no heavy lower-body work within 18 h before a key session (practice), lighter in a reset week or when readiness is not GREEN.preferences (days per week, rest day, long-run and long-ride days, cardio and strength slots). Defaults: 6 days a week, morning cardio, evening strength, long sessions not back to back.equipment.bikes, bike_log, the ride goal)target_speed_kmh, target_distance_km, flat_max_m_per_km (flat = at most that many metres of climbing per km; a practice cut-off), long_ride_km and optional baseline. ride_check.py reads it.athlete.json bike_log decides: {"default_bike": "road", "other_bikes": {"mtb": [activity ids]}}; a ride counts as the default bike unless its id is listed under another bike. ride_check.py --bike NAME|all and hold_check.py --sport bike --bike NAME|all use the same log.gearing.py converts cadence and gear to speed (wheel size assumed unless given); on a fixed gear you cannot coast, so do not plan recovery or descents on it (practice; no paper read).cycling_power.py) uses assumed CdA, mass and rolling resistance: the model form is validated (Martin 1998), the numbers are not measurements of the user.plan.py)plan.py is the only planner (event_plan.py and build_plan.py are old names that forward to it; build_plan.py --legacy keeps the old rolling planner for one more release). Goal: a race (--event) or no target (--goal base: build endurance and aerobic base for the sports chosen with --sports run,bike,swim, 12 weeks by default). Length: a no-target plan is 12 weeks unless the athlete says otherwise: --weeks N (2 to 52), or save it once with athlete.py set preferences.plan_weeks N (a short rolling block of 4 weeks that is re-planned each month suits many people; 12 or more suits a longer base). A race plan always runs to race day. Calendar: calendar_events.py PLAN.json --weeks N writes N weeks ahead; save calendar.window_weeks (or calendar.window_days, default 14) as the standing setting. Ask the athlete how far ahead they want in their calendar; longer windows go stale when readiness or injury changes the plan, so re-sync when the plan changes. Inputs: --from-garmin reads hours a week, longest sessions, sports done and training days from the athlete's real Garmin history; otherwise ask (level, hours now, most hours available, days a week). Safety built in: an active injury locks quality sessions; --readiness red|amber makes week 1 lighter; volume rises at most 10 % a week; a standardised aerobic test sits in each lighter week of a base plan. Heart-rate workouts and .fit: when the athlete's heart-rate data are known (zone first, custom bpm second, from athlete.json) every run and ride carries a heart-rate workout and export_plan.py --format fit writes Garmin .fit files for the watch; without heart-rate data nothing is assumed and no .fit is written (ask the athlete for max HR or LTHR or their watch zones). Swims and strength have no .fit export. Check each file on the watch.
plan.py --event)For "plan my marathon / Olympic triathlon / gran fondo / 5 km swim" use scripts/plan.py --event .... It needs no Garmin account: ask the athlete for the event, its date, their level (beginner, intermediate, advanced), the hours they train now, the most hours they can train, and training days per week (5, 6 or 7); also their longest recent run, ride and swim in minutes, equipment for strength, injuries and pain today. If something is missing the script stops and lists it. Record the answers with athlete.py set manual_baseline '{...}' and athlete.py set event '{"type":"olympic-tri","date":"YYYY-MM-DD"}'.
5k 10k half marathon ultra-50k (running), sprint-tri olympic-tri 70.3 ironman (triathlon), duathlon-sprint duathlon-standard, gran-fondo century ultra-ride (cycling), swim-1500 swim-5k swim-10k (open-water swimming). plan.py --list-events lists them with the usual plan length.plan_viewer.py PLAN.json makes one interactive HTML page; export_plan.py PLAN.json --format all writes a calendar file (.ics), a spreadsheet (.csv) and Zwift (.zwo) and ERG/MRC ride workouts (power as a share of FTP, scaled by the app). Garmin .fit workout files for runs and rides (when the athlete's heart-rate data are known) come from export_plan.py PLAN.json --format fit. Swim and run sessions are in .ics and .csv only.references/evidence-map.md, section "Event plans". Research: taper (Bosquet 2007), mostly-easy distribution in Ironman triathletes (Munoz 2014, Neal 2011), swim as the smallest part of race time (Figueiredo 2016), overuse injury burden in iron-distance triathletes (Andersen 2013). Brick runs: research for the extra cost of running after cycling (Walsh 2019, full text read), gap for any training benefit; they stay short, are cut to 10 minutes with a history of exercise-related leg pain (ask) and dropped while an injury is active. Practice or gap: peak hours per event, session mix, swim/bike/run shares, and everything for cycling, swimming and duathlon events (no study read). Read depth per paper: docs/EVIDENCE-DEPTH.md (most are abstract only because they are paywalled).plan.py --from-garmin starts from the athlete's real training; build_plan.py --legacy keeps the old rolling planner for one more release.scripts/: build_plan.py, run_gate.py, ride_check.py, cycling_power.py, gearing.py (speed from cadence and gear, or the cadence a speed needs; wheel size assumed unless given), calendar_events.py. plans/ holds saved plans (local only). references/: evidence-map.md, library.md, papers/ (open-access full texts).
The studies behind this skill are in references/papers/ (INDEX.md lists the read depth). Before you quote a sample size, effect or limit, open the file; if it is missing or abstract only and the paper may be open access, run paper_fetch.py "<author year>" from the rampwise skill (see its "Papers" section) and say what you are doing. Paywalled papers stay abstract only: say so and claim no more.
Azahir21/rampwise
d757ece
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.