Skip to content

v0.4.0 — plugin for Claude Code and Codex, activity files, and a plan that keeps your decisions

Choose a tag to compare

@dithiothreitol dithiothreitol released this 21 Oct 21:35
· 110 commits to main since this release

Install: npx trainctl@0.4.0, MCP: npx -y trainctl-mcp@0.4.0, plugin for Claude Code and Codex from this repository (see docs/integrations/agents.md). New package: trainctl-sync-files. Full history in CHANGELOG.md.

Fixed — found by running every command on a fresh directory

  • review on a Sunday no longer reports the whole week's volume next to the
    number of remaining sessions ("52 km across 1 sessions"); it shows what is
    left of the week's target.
  • A directory without trainctl.yaml now points to trainctl init instead of
    trainctl plan, which would only have pointed back to init.
  • why no longer prints "About 0 minutes" for a rest day, no longer states the
    session's purpose twice, and lists each rule once with its text and
    provenance instead of in two separate sections.
  • log answers with what the plan had for that day next to what was recorded,
    says when an entry falls on a rest day, and returns structured data for MCP.
  • Messages print plan/plan.yaml on every system (Windows printed plan\plan.yaml).
  • A plan generated by another minor version of the engine is reported in
    today, week, why, review and check (informational; never fails
    --strict). A plan file with a newer schema is refused with advice to
    upgrade trainctl.
  • Rule sources link to docs/science/FOUNDATIONS.md on GitHub, pinned to the
    release tag — the file is not part of the npm package, so the relative path
    in why, desk and AGENTS.md led nowhere after installation.

Changed — trainctl plan keeps what you decided (ADR-033)

  • On an existing plan, plan regenerates only the future. Past and logged
    days, pinned days, hand edits, approved shortenings and days whose new session
    would exceed a saved time budget stay as they are. An approved volume baseline
    from adapt --apply is kept until you change athlete.recentWeeklyKm.
    Previously every regeneration silently discarded all of that — including on
    the documented path "add a race result → trainctl plan".
  • The same training cycle keeps its phase boundaries; a different goal distance,
    or a new goal after the race, starts a new cycle and keeps the earlier weeks
    as history ("week 2/12" counts the current cycle). On race day the race
    counts as done only when most of its distance is logged or synced (a day
    logged as skipped never counts), so a morning shakeout before a postponed
    race keeps the same cycle.
  • Right after adapt --apply, plan reproduces the approved days, including
    strength sessions, time-budget caps and the day of the decision. Later,
    strength follows the current phases and strength.days.
  • A plan/plan.yaml that cannot be read (a merge conflict, a missing goal) is
    never overwritten silently: plan refuses until it is fixed or --fresh is
    given, and status no longer suggests a plan that would fail.
  • trainctl diff shows exactly the regeneration plan would perform.
    plan --fresh (MCP fresh) starts over and lists what it discards.
  • Fixed: a race result recorded inside the plan's horizon did not reset the
    calibration rhythm (W-12), so a regeneration could schedule a time trial a
    week after a fresh 10 km result.

Added — a CLI you can script

  • --json on every command prints { code, data, output } — the same data the
    MCP tools return (ADR-035).
  • -C <dir> / TRAINCTL_DIR for the CLI, as the MCP server already had.
  • TRAINCTL_TODAY=YYYY-MM-DD simulates the date; every CLI and MCP output
    announces it, and past-day protection and proposal expiry follow it (ADR-034).
  • Relative dates in the CLI: today, tomorrow, yesterday, +N/-N,
    weekday names in English and Polish. MCP tools stay ISO-only.
  • trainctl log without flags in a terminal asks: pick a session from the last
    week, then status, distance, time, RPE and a note.
  • trainctl status / trainctl_status: profile validity, engine version,
    calibration, key source (never its value), .env protection, last pull,
    journal, saved proposals with their validity today, uncommitted files.
  • --commit [message] on init, plan, log, shift, reschedule --apply,
    adapt --apply and shorten --apply (MCP commit) commits exactly the files
    the command changed — never secrets, sync.json or other staged changes
    (ADR-040). init --commit includes .gitignore when it created it or when it
    had no uncommitted changes before the secret patterns were added.
  • today shows the estimated duration and the next session.
  • trainctl completion bash|zsh|fish|pwsh, examples under trainctl help <command>.
  • Usage errors (unknown command or flag, a date that is not a date) exit with 2.

Added — trainctl in Claude Code and Codex (ADR-036)

  • A plugin in plugin/, with this repository as its marketplace for both agents:
    /plugin marketplace add dithiothreitol/trainctl + /plugin install trainctl@trainctl
    in Claude Code, codex plugin marketplace add dithiothreitol/trainctl in Codex.
    It bundles the MCP server, the coach persona and four task skills
    (review, debrief, shorten, what-if), and in Claude Code two hooks: the
    coach instructions at session start in a training directory, and
    trainctl check after an edit of plan/plan.yaml.
  • Skills are generated from the same text as AGENTS.md
    (node tools/plugin/render-skills.ts); plugin.test.ts fails on drift.
  • trainctl init --agent claude|codex|all (MCP agent) writes
    .claude/settings.json or .codex/config.toml; existing files are never
    overwritten.
  • MCP: trainctl_rule explains a rule by ID with its source class and a link to
    FOUNDATIONS for this version; resources trainctl://plan, trainctl://config,
    trainctl://agents, trainctl://rules/{id}; prompts weekly-review and
    debrief. CLI: trainctl rules [id].
  • trainctl check returns its findings as data (--json, MCP, the hook).
  • tools/release/bump-version.mjs moves every pinned version together: packages,
    plugin manifests, MCP configs, the hook and the CI examples.

Added — execution without a hub, a fuller calendar, context from the watch (ADR-037)

  • New package trainctl-sync-files: reads exported FIT, TCX and GPX files
    (also .gz, as in Strava and Garmin bulk exports) as a pull-only source, with
    no dependencies. trainctl pull --from <folder> (MCP from) and
    sync.files in trainctl.yaml for review without an API key. Skipped files
    are named. The same run exported in two formats (start within 60 s, similar
    distance) counts once, keeping the richest file: FIT, then TCX, then GPX.
    init adds activities/ to .gitignore.
  • The sync port is split into ActivitySource (pull) and SyncProvider
    (pull + push).
  • push sends races as race events (RACE_A/B/C) and strength sessions as
    separate WeightTraining entries, in their own requests: if intervals.icu
    refuses either form, a race falls back to an ordinary entry, a warning says
    so, and the running sessions are pushed regardless. Cleanup of stale entries
    now covers every trainctl- entry, not only workouts. Not yet verified on a
    live intervals.icu account.
  • review quotes resting heart rate, sleep and weight from the synced wellness
    data, and RPE recorded in the hub where the journal has none — verbatim, with
    the source, never averaged or turned into a verdict. HRV and CTL/ATL are
    deliberately left out (H-1, P-4).

Added — the engine: time, life after the race, a plan without a race

  • Time budget (time.weeklyMinutes, weekdayMinutes, weekendMinutes,
    E-2): weeks over the weekly budget get a lower volume target, days over their
    limit are shortened with the same rules as shorten and carry the trade-off;
    the plan says when the budget lowers the peak below the level recommended
    for the distance, and what the peak would be without it (P-7/P-8). Races and
    time trials are never cut.
    A week keeps its macrocycle target; the volume the budget leaves is stored
    next to it (timeCappedKm), and week, adapt, diff and export show it.
    A zone recalibration from adapt changes paces: day limits shorten
    sessions that no longer fit from the current week, the weekly budget lowers
    volume from the next week on, and volume goes up again through plan.
  • Transition block after the goal race (R-8): after a half marathon or
    longer, two weeks — about half the pre-race volume, easy only, first run on
    the third day after a marathon (R-1), then back to normal with one accent;
    one week at ~70% after a shorter goal (R-10). Strength returns in the second
    week (R-9). Measured first: tools/corpus/post_race_profile.py (three long
    races in the corpus — a weak basis, stated as such). today and why say
    "after the race" instead of "outside the plan", and a new goal set during the
    block starts its cycle after it.
  • A plan without a race (goal.kind: base, until, P-11): base weeks only,
    deload every fourth week, growth to your documented peak and a plateau; no
    taper, no prediction, no race pack.
  • Strength variants and journal: two weeks of getting into it (F-18), then
    heavy sessions, one maintenance session a week in the peak (F-12, F-14);
    trainctl log --strength done|skipped [--minutes] (MCP strength) records a
    session without touching the run entry of the same day; review and today
    show it.
  • Trail results no longer calibrate road zones while a road result exists
    (Z-10); a trail-only calibration is used with a warning.
  • Rules E-2, F-18, P-11, R-8, R-9, R-10 and Z-10 in FOUNDATIONS §10, marked as
    engineering choices where no source exists. The corpus backtest is unchanged
    (volume 1.04, Δ accents 0, Δ sessions 0, tune-ups 6/6).

Docs

  • README command tables list shorten and the missing flags; tool lists no
    longer carry a count that drifts. docs.test.ts keeps both READMEs and the
    MCP README in step with bin.ts and server.ts.
  • CI examples install the published package (npx trainctl@<version>) instead
    of cloning the engine and running Node 23.
  • CLAUDE.md for coding agents working on this repository.