CommunityProductivity & Collaborationgithub.com

rampwise-planner

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.

What is rampwise-planner?

rampwise-planner is a Claude Code agent skill that 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.

Works with✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Azahir21/rampwise/tree/HEAD/skills/rampwise-planner

Installed? Explore more Productivity & Collaboration skills: steipete/gemini, steipete/gh-issues, steipete/skill-creator · View all 6 →

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

Paths. <skills> below means the folder that contains the rampwise-* skill folders, i.e. the parent of this skill's own folder (in Claude Code the plugin's skills/ 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).

Garmin Planner

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.

Always first

  1. 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.
  2. Never invent a date or a timeline for a goal: no verified source gives a rate of improvement for this athlete. Targets are checked, not promised.

The goals and how they are tested

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 typeMeasured byScript
Aerobic base: hold a pace with HR under the easy ceiling for longerHOLD 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 cadencerun_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 heartbeatride_check.py, cycling_power.py
Longer events (a marathon, an ultra ride)later; need the base, the shorter goals and a long-run/ride buildstored 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.

Workflow

  1. State: run 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).
  2. Build: 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.
  3. Explain in phone-friendly form: phase (base or pace intro), why a reset week if one is used, this week's sessions, one thing to watch. Quote numbers only from the script.
  4. Calendar (main session only, not a subagent): 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]).
  5. Weekly re-sync: every week (or when the athlete says they were ill, injured, travelled or tired) rebuild from the new data, replace the window, and record the decision with athlete.py note.

Heart-rate targets: zone first, custom second, ask before assuming

Rules (set by the athlete 2026-11-16; they apply to every user):

  1. Ask first. If 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.
  2. Zone first. For each step the builder checks whether ONE zone of that sport's set covers the band (both ends within 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.
  3. No answer? Use the trend. 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).
  4. Warm-up and cool-down have no HR alert (open target; the cap is in the step note), so ranges never overlap the main step. Hard efforts (tempo, intervals, climbs) use 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.
  5. Zone targets resolve on the watch, using the zone set currently on the watch for that sport (running, cycling and the default set are separate and can use different methods). So 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.

Garmin workouts and the session menu

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).

Plan rules (what the builder does; full table in references/evidence-map.md)

  • Base first: most cardio is easy (HR ceiling from athlete.json, talk test); quality is a small share of the week.
  • Quality by default: from the second week on, one run quality session per build week (rotation of tempo, strides, 3 km time trial, interval run) and one short-interval ride per build week, unless this athlete's data locks them (see the session menu). High-intensity time stays <= 20 % of the week.
  • Volume: start from the average of the last three full weeks; reset week x0.70 when readiness is RED/AMBER, there was no rest day for 14 days, last week jumped > 20 %, or an injury is active; then at most +10 % per build week; every 4th week x0.75.
  • Long run/ride: at most +10 % over the longest in the last 30 days, chained week to week (run rule from Frandsen 2025; applied to rides as an extrapolation).
  • Strength equipment comes from 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).
  • Strength is generated (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.
  • Strength placement: on 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.
  • Schedule comes from 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.
  • Daily override: each calendar item says "if readiness is RED, swap for rest or a 20-30 min easy spin". The head coach applies it each morning.

Bikes and rides (athlete.json equipment.bikes, bike_log, the ride goal)

  • A ride speed goal (for example a speed over a distance on a flat route) is a goal with 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.
  • Which bike a ride used: Garmin's server does not say. 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).
  • The power model (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.

The one planner: a race, or no target at all (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.

Event plans: a race plan with or without Garmin data (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"}'.

  • Events (17): 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.
  • Shape: base, build, peak, taper (2 weeks for most events, 1 for short ones); a lighter week every 4th week; weekly volume +10 % at most; long sessions capped (+10 % over the last long one, and an event cap); about 70-80 % easy; strength twice a week via the strength generator (it asks for equipment first). Triathlon and duathlon get brick runs; swims are written by time and effort.
  • Honest limits: if the weeks left cannot reach the usual peak hours at +10 % a week, the plan says so and peaks lower; if the longest recent sessions are short for the hours reported, it says so. Effort is RPE and, for rides, a share of FTP; no heart-rate numbers are assumed.
  • View and export: 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.
  • Rule labels are in 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).
  • The plan never promises a finish time. With Garmin data, plan.py --from-garmin starts from the athlete's real training; build_plan.py --legacy keeps the old rolling planner for one more release.

Honesty rules

  • Practice rules (volume steps, reset/deload factors, exercise lists, interval formats, the 125 steps/min walking cut-off, the flat-route cut-off of 8 m/km) are labelled practice. The 10 % weekly rule is not shown to prevent injury (Buist 2008); it is a conservative convention.
  • Speed numbers from rides depend on wind, stops and traffic; use them as context. The power model uses assumed CdA, mass and rolling resistance; the model form is validated (Martin 1998), the numbers are not measurements of the athlete.
  • If a signal is missing (no readiness, no gate check), build the plan with the safer assumption (readiness RED, gate open) and say so.
  • A coach is not a doctor: pain that changes gait or worsens, chest pain, fainting -> stop and see a clinician.

Files

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).

Papers

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.

Related Skills