Repository navigation
Releases
Releases · tomasstankovic/running-coach
v0.17.1
- Every run goes to TrainingPeaks structured, not as text. The rule that easy and long runs
get a structure too sat at the end of a long step inweek.md, and only the quality sessions
were written with one: "Ľahko 7 km + 6× rovinky" reached the calendar as a description, with
no target on the watch and strides that the analysis couldn't see. Nowtp_structure.py
takes a whole week ("sessions", each with date, title, description and steps), returns
onetp_create_workoutpayload per run, and refuses a run without steps.workouts.mdshows
an easy run and an "easy + strides" run as specs, the check-in rebuilds the structure when it
changes a session, and the 0.17.1 check inwhats-new.mdoffers to add structures to the
runs already planned. Reported by the author, whose easy runs had none.
v0.17.0
- A session can mix kilometres and time.
tp_structure.pyused to write every step in the
workout's one unit, so for a km runner a 75 s jog between 1 km reps became "300 m" on the
watch, and for a time runner the 1 km reps became "4:12". Now each step goes to
TrainingPeaks in the unit it is written in (km/mas distance,seconds/minutesas
time); the spec'sunitonly sets the workout's primary axis.workouts.mdsays how to pick
the unit per step: flat reps by distance, hill and trail reps by time, recoveries usually by
time (or 200 m on a track), warm-up and cool-down in the runner's unit. Strides are now steps
of the structure (a 15' warm-up is 12' easy + 3 × 20 s / 40 s jog, classwarmUpso the
analysis doesn't read them as reps). Suggested from the author's own sessions,
which had the strides only in the text and the jogs turned into metres.
v0.16.3
- The week is planned on the runner's days, not on last week's. A runner agreed their days
at the start of the conversation, and the coach planned the week on the days of the previous
week instead, which had been shaped by a family event. Week planning now starts with
week.md§0: days the runner named in the conversation win, then the profile's weekly
template; the coach asks every week whether the template holds, and a one-off week doesn't
change the template.check_week.pytakes"days"and FAILs a run on any other day (Slovak
day names work too); without"days"it warns that the days were never confirmed. New eval
week-days-not-copied: template Tue/Thu/Sat/Sun, last week run on Mon/Wed/Fri/Sat. And
week-days-from-conversation, the reported case in two turns: the runner names their days
in the first message, the profile has no template, and the plan is asked for in the second
(2 of 2 runs passed all graders).
v0.16.2
- Readiness sees more than last night.
readiness.pyflags sleep debt (3 of the last 4
nights under 6 h) even when last night and HRV look fine, and takes--stress 1-5, the
runner's rating of load outside running (travel, work, heat, family; 4–5 is a flag). The
check-in passes what the runner says about travel or a heavy week into the script. Suggested
on Reddit: a green HRV after four bad nights and a long flight should not clear a tempo
session. New evalen-checkin-travel-sleep-debtis that case.
v0.16.1
- Evals in English too. English copies of the eight Slovak cases behind the README tables
(en-*, generated bytests/make_en_evals.pyfrom the Slovak case, so the runner, data and
graders stay the same), and language tags on every case:en,sk, andreadmefor the
table cases in both languages. - Block review runs the block report. "How did the block go?" now has its own paragraph in
Review mode (SKILL.md"End of a block"): runblock_report.pyfirst, don't add up the weeks
by hand, and name the key sessions as counts (on target, missed, under target) with the reason
for the misses. The evals found the coach counting by hand in 3 of 4 runs and, in English,
leaving out the counts; after the fix the script ran in 3 of 4 and the counts were in all 4
(block review 75 → 88 % in English). - README: with and without the plugin, in both languages, run on 5 November 2026 with 2 runs
per case and arm: plain Claude 67 % (English) and 66 % (Slovak), with the plugin 93 % and 95 %.
v0.16.0
- Training on a fixed time budget (
methodology.md§11, from a research pass over 58 studies):
plan from the hours a runner can really give (onboarding asks for them), with an allocation by
budget (≤ 3, 3–5, 5–7, 7+ h); where an extra hour goes (easy running for a half or marathon,
about 4 min off a marathon per +10 km a week; quality and strength for 5k/10k); threshold or
sub-threshold as the default quality and long intervals over sprints; busy weeks keep 2 runs
with intensity, never easy-only; cheaper volume (commutes, doubles, cross-training) and what is
not proven for amateurs (Norwegian singles, profile-based emphasis). 11 new sources (S54–S64),
each DOI checked in Crossref. - README: "The research behind it": the key studies by topic with their size, and the link to
all 63 sources. - Evals: a 3-hour week for a 10 km goal, and a busy month before a marathon (tag
v016), plus six
in English (tagen): a first chat, a weekly review, a taper in miles, a return from a bone
stress injury, a trail race from a flat city, and a sub-4 marathon on 4 hours a week. - Evals for faster runners (tag
performance): sub-3 and sub-2:45 marathons, sub-1:30 and
sub-1:20 halves, each checked for an honest prediction, gradual volume, race-specific work and
the race plan. - Trail and mountain races (
methodology.md§9): long runs by time toward the race's
duration, vertical in a flat city (incline treadmill, stairs, car parks, weekend hills),
power hiking, downhill practice with eccentric strength, and fuel and water for the race's real
duration, rehearsed in race kit. - After an update (
whats-new.md): the coach notices a new version at the start of a
conversation (Coach versionin the profile), says what is new for that runner, checks their
plan and forecast against the new rules and proposes changes (made only after a yes), and
publishes the new page template to the same link (the data stays). A scheduled review does
the same and asks in its report. - Faster runners (
methodology.md§5): volume from the runner's best block with deloads said
in the plan, easy doubles past ~6 runs, two quality sessions (double threshold only as labelled
practice), the specific phase by distance, the limiter named from two results of different
length, and smaller gains per block. The goal table now has half sub-1:20 and marathon sub-2:45. - The first answer to a time goal (
onboarding.md§5): the numbers and a fallback goal, the
limiter, the block shape with its deload rhythm, the key sessions per phase, a halfway check
point, a tune-up 2–4 weeks out, the taper, and race pacing and fuelling, then only the questions
that change the plan. - "Today" card at the top of the plan page: today's session with pace, HR cap and distance,
this morning's readiness and what it means for that session (the morning brief now writes one
sentence ofadvicewith its readiness row), active pain or illness, and tomorrow. - Plan page in the order a runner reads it: "Where we are" first (the phase, week x of y, what
the phase is for and what to focus on, its goal from the plan and what comes next; a coach's
note per phase inphase_notes), then readiness next to this week (with next week's key
sessions), then each race's forecast with its road under it, and only then key sessions, load
and form, blocks, zones and history. The four number tiles are gone: their content is in the
phase panel, and the race chips count the weeks. - A road to each race. Every A and B race has its own ~5 milestones (4-6) from the 12 weeks
before it, tagged with the race: for a marathon the marathon-pace long runs, the longest run and
one with race fuelling; for a half the threshold check and race-pace sessions. Races are the end
of a road, no longer milestones.season_plan.py roadssets them on an existing plan, keeping
every result;check-roadmapwarns when a road has fewer than 4 or more than 6. - Key sessions on the plan page: "Next" is only this week and the next, with the next
milestone after them; "Done" the sessions run, newest first; "Whole plan" everything. Below,
each race's road on a time line (✓ / ◐ / ✕ / –, the next one marked, the race and its forecast
at the end). The prediction card shows one line ("milestones 0 of 5 · next …") instead of a list. - Projection "if the plan happens" no longer undersells the plan. Two fixes, found on a real
season where the projection came out slower than the runner's own best at the same load:- Without
weekly_tssthe plan's TSS was rescaled by CTL x 7, which lags behind the load in a
build and made the plan ~10 % lighter (race-day CTL 42 instead of 47). The plan's own
estimate is now used, and the skill always passesweekly_tss. - The time-vs-CTL slope is fitted twice, with today's level and from the earlier races alone. A
runner who is already faster at a lower CTL than last season made the single fit flat (0.09 %
per CTL point), as if more training bought little; the middle now uses the mean of the two. - The marathon card's "today" mark shows today's form, not the forecast at the plan's volume.
- Without
- A faded marathon and race checks.
analyze_session.pyprints a marathon's pace to km 30 and
after it. In the forecast history that marathon getssteady_pace: the projection's slow end
assumes the fade comes back, the fast end that it doesn't, and the middle starts at half of it
(it used to assume the full fade, which at ~60 km a week is typical, but trainable). The race's
milestones, read from the plan with the review'sactual.check, move the middle: every one held
toward the fast end, every one faded back. - Plan page predictions read at a glance: one headline time with its label above it ("on race
day, if the plan happens") and one range; today's form and the goal are marks on a time line
instead of a second range, and the goal's distance from the best case is in seconds or minutes
("25 s faster than the best case: a stretch"), not a percentage against "the projection". - Race plan: weather typed in by the runner (instead of fetched) is shown as "given" with the
heat line; it used to read "no weather data" although the heat was counted. - README: a picture of three real answers at the top (morning brief, race plan, session
analysis; fictional runner), a one-minute install, and a table of what the plugin adds over
plain Claude, from the evals.
v0.15.1
- Race plan fuelling adds up: the gels start after 20-30 min and stop before the finish, so
they alone fell short of the hourly rate (2 gels = ~31 g/h on a plan of 45 g/h). The plan now
gives the total and the rest from the sports drink (carbs_total_g,drink_carbs_g). - Shorter morning brief: one line each for the verdict, today, pain or illness and what
moves, with an example. - Race plan output: no "wind None km/h", the heat line is labelled; block report: Slovak counts
read naturally. - Evals for the 0.15.0 features: race plan on a hilly course in the heat, rising calf pain in
the diary, an amber morning brief, a block overview, durability on a long run, fuelling
practice (fictional data, tagv015). - SKILL.md review (skill-creator guidelines): the description also triggers on pain and
niggles ("bolí ma lýtko"), the morning brief, block reviews and gut training; the modes table
points to the block report, durability and fuelling practice; a scripts table says what each
script gives and which reference explains it (instead of a list of commands under Zones); the
review reads the pain diary. - Fewer tokens per answer: planning a week (role, draft, load check, plan format, saving to
TrainingPeaks or.ics) moved fromSKILL.mdtoreferences/week.md, read only when a week is
planned. Check-ins, the morning brief, race plans, analysis and zones load ~1,300 fewer tokens. - README: who it's for (and not for), features grouped by what they do, a season with the
coach step by step (incl. scheduled brief and review), privacy and safety (the one network
call is the weather), and an FAQ.
v0.15.0
This release also contains 0.10.0 to 0.14.0, which were not released on their own.
- Race plan (
race_plan.py,weather.py): the forecast range moved for the weather (Open-Meteo:
the real forecast up to 16 days out, the typical weather of that date in the last 10 years
before), the goal checked against it with a safe B, splits by the course's GPX profile (Daniels'
hill rule, downhill capped at ~12 % faster from Strava's GAP data), even or negative, and the
fuelling plan: carbs per hour by duration capped at what the gut tolerated in training, gel times
matched to aid stations, drinking, carb loading, breakfast and caffeine in grams for the runner. - Durability:
analyze_session.pyreports, for runs of 90+ min, the efficiency lost in the last
quarter vs. early (durabilityin the page rows, charted under aerobic fitness). - Pain and illness diary in TrainingPeaks (
health_log.py): each report a calendar note with a
machine-readable line; read back into check-ins, reviews and the page with the rules (pain
monitoring up to 3/10, reduce at 4-5, stop at 6+ or a changed stride; illness by the IOC triage). - Morning brief to the phone: the scheduled check-in adds the diary and the weather and sends
one line with PushNotification. - Fuelling practice: a gut-training ladder (30 -> 90 g/h) on long runs, recorded as TP workout
comments, feeding the race plan. - Block reports (
block_report.py): volume, key-session verdicts, milestones, efficiency and
durability, threshold, forecast, readiness, health and takeaways; a blocks section on the page. - Sources S51 (Strava GAP), S53 (pain-monitoring model).
0.14.0
- The runner's own zones are the default, whatever the method (TrainingPeaks and the watch:
80/20, Friel, 5-zone, ...).zones.py showreads any TP method and gives each band its use
from where it sits relative to the threshold; a heart-rate set with another method than the
pace set gets its own table. The profile records it (Zones: own set (TP = Garmin) ...). - Other methods to compare (
--method): 80/20 from thresholds, % max HR, heart-rate reserve
(Karvonen), Daniels VDOT paces (E/M/T/I/R from a race, Daniels-Gilbert equations). Friel is read
from TP or the watch rather than computed (his published percentages differ between versions). - Personal aerobic threshold (
zones.py lt1): flat steady runs of 45+ min under 5 % decoupling
were at or below it; the highest proven HR becomes the easy cap instead of the population 83 % of
LTHR (with a drift test to confirm big changes). - The watch: its own threshold detection counts as evidence in
zones.py suggest; after a
change the runner is told which values to set on the watch (this skill can't write to Garmin). methodology.md"Zone methods"; sources S46–S50 (Daniels, Karvonen, 80/20, Friel, drift test).- Fix: the 7-zone X/Y model is 80/20 Endurance (Fitzgerald), not Friel's.
0.13.0
- Training zones ("Tréningové zóny"):
zones.py showputs pace, % of threshold, heart rate,
power and what each zone is for in one table, from TrainingPeaks' own bands (the run set when
there is one) or from thresholds. The plan page has a training zones panel with the current
table, power, the easy-run HR cap and how the threshold moved over the season (zones
collection). - Keeping them current: checked in the first review of every month and after new evidence (a
flat race, a 30-min test, threshold sessions clearly faster or slower than the zones, a new max
HR, resting HR, power efforts).zones.py suggestproposes old -> new with what it means for
the paces; it never averages sources more than 3 % apart, ignores changes under 1.5 % and hilly
or hot races, and asks for a retest after 12 weeks without evidence. - Writing to TrainingPeaks after the runner's yes: threshold pace, LTHR / max / resting HR,
rFTP (tp_update_speed_zones,tp_update_hr_zones,tp_update_ftp), re-read to confirm, then
the key sessions re-target and the page updates. Creating a missing run power set is offered,
never done unasked. The scheduled weekly review includes the monthly check. - Eval
zones-after-race.
0.12.0
- The coach designs the key sessions; the script computes and checks. Tested blind on three
fictional runners who needed adapting (Achilles history before a marathon, no flat ground for a
half, a 57-year-old 10k runner with a treadmill winter): the roadmap the coach adapted from the
script's draft beat the script-led one on all three (68 : 54 points), and the losers' misses all
traced back to the draft's defaults. Paces were right in both (0 errors in 344 sessions). season_plan.py roadmapnow writes a default draft;season.md§2b has the coach adapt it
(injuries, terrain, what worked, recovery, weather, order of sessions) with a reason per change.season_plan.py check-roadmap: pace vs. its %, two hard days in a row, quality 1–2 days after a
race or test (3 after a half or longer), long run longer than the week's, big marathon-pace runs
in consecutive weeks or the week before a B race, the continuous marathon-pace run 2–4 weeks out
and never the week after a race, milestone count.retargetwithout a new threshold just fills the targets of the coach's new or edited sessions.- Reviews: after a session under target or missed,
actualsonly proposes holding back
(PROPOSE); the coach decides with the context,--hold-backapplies it. - Draft fixes: no quality 2–3 days after races and tests, big marathon-pace long runs never in
consecutive weeks or before a B race, half-marathon pace never drops from build to specific
(3× 3 → 2× 5 → 3× 4 → 2× 6 km, then 2× 6 → 3× 5 → 10 km continuous), dress rehearsal a real
race-pace session in a full week 2–3 weeks out. - Evals:
roadmap-achilles-marathon,roadmap-hilly-half,roadmap-masters-10k.
0.11.0
- Key-session roadmap (
season_plan.py roadmap,key_sessions.py): every week of the season
gets its key sessions from progression ladders by phase and goal distance (more reps, then
longer reps, then faster), placed on the runner's quality and long-run days, with targets as
% of threshold speed and paces frompaces.py. Race-pace targets use the goal pace, at most
3 % faster than the threshold supports. 6–10 milestones: threshold check, longest run, B races,
marathon-pace long runs and a continuous 18–23 km at marathon pace 2–4 weeks before a
marathon, a dress rehearsal for shorter goals, the A race. - Results against the map:
actuals --sessionsmatchesanalyze_session.py --jsonrows to the
key sessions and judges them (on target, better, under, missed). After under or missed, the
rest of that ladder moves back a step, logged.retargetrecomputes future paces after a new
threshold or goal and logs what moved.replankeeps the roadmap. - Plan page: a key sessions section (next + milestones, milestones only, all), by phase, with
target pace, HR cap, result and verdict, and an "adjusted" mark that leads to the change log. workouts.md"Progressions",season.md§2b, Week mode starts from the week's key sessions.
Proposed in a coaching session on real data.
0.10.0
- "If the plan happens":
forecast.pyadds a race-day projection next to the forecast from
today's form. The plan's weekly TSS is run through the CTL formula to race day and the
runner's own results against their CTL give how much faster they get per CTL point (held to
0.05–0.4 %, no extrapolation beyond 15 % above the highest CTL they raced at). The marathon
goes through their own marathon/half ratio. The plan's TSS estimate is rescaled to the
runner's own TSS per km (weekly_tss, or today's CTL). Needsctlandhistory[].ctl;
without them nothing changes. Proposed and first built in a coaching session on real data. - Plan page, this week: always Monday to Sunday, rest days shown as rest, strength
sessions tagged, the week's total and how many sessions are done. - Plan page, readiness: today's verdict with what to do and why (HRV, resting HR, sleep),
where the 7-day HRV sits in the runner's band, last night's HRV, and the trend only from
5 days on.readiness.py --trendrows carryreasonscodes andhrv_state. - Fix: the page used the UTC date for "today", so after midnight in Europe it marked the wrong
day.
v0.9.1
- Choose your setup. The first conversation explains where the coach keeps things in the
runner's setup (TrainingPeaks notes, a working folder, or files in a Claude Project), what that
setup gives and misses, and the better option; the choice goes into the profile'sSetup:
line. - Folder sessions save files themselves. In Claude Code or Cowork the profile (without TP),
plan.jsonandseason-plan.mdgo intorunning-coach/in the folder and are read at the
start of every chat, instead of being handed over for download. - README: a "Choose your setup" comparison with what each setup gives and misses.
v0.9.0
- Race predictions (
forecast.py): current form over 5 km, 10 km, half and marathon, and a
race-day forecast for every race in the season. Recent races count most (by age and distance),
workout best efforts only as "at least this fast", threshold as a second view (a > 3 % gap is
flagged as a stale threshold or misleading races), and the marathon comes from the volume
models instead of Riegel. Race day: today's level is the slow end; the plan's volume and the
runner's own earlier results at similar volume set the fast end; course and heat adjust it. The
goal is judged as realistic, a stretch or out of reach. No generic "+x % per block". - Plan page: a predictions section with each race's forecast, its trend over the weeks against
the goal, and a current-form table (predictionscollection). - Weekly review re-runs the forecast; onboarding and race plans start from it. A Predict mode in
the skill. - README: the Slovak section is gone.
Install: in Claude, Customize → Plugins → Add marketplace → tomasstankovic/running-coach. Or upload running-coach.zip as a skill.