Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
de6f057
fix(cli): naprawy 0.3.1 — review, why, log, komunikaty i dokumentacja…
dithiothreitol Oct 21, 2026
38bba4c
feat(cli): chroniona regeneracja planu i CLI, które da się skryptować
dithiothreitol Oct 21, 2026
146a9cf
feat(plugin): trainctl jako plugin Claude Code i Codex, zasoby i prom…
dithiothreitol Oct 21, 2026
80a6957
feat(sync): wykonanie z plików FIT/TCX/GPX, starty i siła w kalendarz…
dithiothreitol Oct 21, 2026
d4f5488
feat(engine): budżet czasu, blok po starcie, plan bez startu, wariant…
dithiothreitol Oct 21, 2026
eac6e4a
fix(i18n): faza po starcie nazywa się „transition”/„okres przejściowy…
dithiothreitol Oct 21, 2026
55ec364
fix: poprawki po code review gałęzi dev/plan-v0.4
dithiothreitol Oct 21, 2026
41d5d9d
fix: druga runda po code review — budżet czasu, odczyt planu, dzień s…
dithiothreitol Oct 21, 2026
84d01fa
fix: trzecia runda po code review — propozycja vs regeneracja, dzień …
dithiothreitol Oct 21, 2026
84252aa
fix: czwarta runda po code review — monotoniczny budżet, siła za faza…
dithiothreitol Oct 21, 2026
cfba968
fix: piąta runda po code review — budżet od rozpisanej objętości, kot…
dithiothreitol Oct 21, 2026
800f9e8
fix: szósta runda po code review — granica budżetu zamiast znacznika,…
dithiothreitol Oct 21, 2026
ba5680d
fix: siódma runda po code review — spójny model budżetu przy propozyc…
dithiothreitol Oct 21, 2026
87977cf
fix: ósma runda po code review — dwie granice budżetu, stan „budżet t…
dithiothreitol Oct 21, 2026
0b58d92
fix: dziewiąta runda po code review — objętość bez budżetu w tygodniu…
dithiothreitol Oct 21, 2026
389d566
fix: dziesiąta runda po code review — ostrzeżenia budżetu na planie k…
dithiothreitol Oct 21, 2026
475e34a
chore(release): wydanie 0.4.0
dithiothreitol Oct 21, 2026
ddb4da0
fix(plugin): marketplace Codex z polityką uwierzytelniania, którą Cod…
dithiothreitol Oct 21, 2026
de99eee
fix(plugin): skrypty hooków z LF także po checkoucie na Windows
dithiothreitol Oct 21, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions .agents/plugins/marketplace.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
{
"name": "trainctl",
"interface": { "displayName": "trainctl" },
"plugins": [
{
"name": "trainctl",
"source": { "source": "local", "path": "./plugin" },
"policy": { "installation": "AVAILABLE", "authentication": "ON_USE" },
"category": "Productivity"
}
]
}
15 changes: 15 additions & 0 deletions .claude-plugin/marketplace.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
{
"name": "trainctl",
"owner": { "name": "Dariusz Tyszka" },
"description": "trainctl: a running coach in your terminal and in your agent — training plan as code, MCP tools, coach skills",
"plugins": [
{
"name": "trainctl",
"source": "./plugin",
"description": "Running coach as your agent's tool: training plan as code, MCP tools, coach skills and a lint after plan edits",
"version": "0.4.0",
"category": "productivity",
"keywords": ["running", "training-plan", "coach", "mcp"]
}
]
}
3 changes: 3 additions & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
@@ -1 +1,4 @@
* text=auto
# Skrypty z shebangiem (hooki pluginu): vitest zdejmuje `#!` tylko przed LF —
# z CRLF po checkoucie na Windows import kończy się SyntaxError.
*.mjs text eol=lf
10 changes: 8 additions & 2 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,10 @@ jobs:
# repository, so the seven backtest cases skip here by design.
- run: pnpm test

# The plugin's skills are generated from the AGENTS.md text; a stale copy
# would give the agent a different coach than `trainctl init` writes.
- run: node tools/plugin/render-skills.ts --check

# What the repository cannot see about itself: the published packages run from
# node_modules, where Node refuses to strip TypeScript types. 0.1.0 shipped
# broken because every other check runs from the source tree.
Expand All @@ -64,7 +68,7 @@ jobs:
run: |
set -euo pipefail
mkdir -p /tmp/tgz
for p in core export sync-intervalsicu cli mcp; do
for p in core export sync-intervalsicu sync-files cli mcp; do
(cd "packages/$p" && pnpm pack --pack-destination /tmp/tgz)
done
ls -1 /tmp/tgz
Expand All @@ -75,12 +79,14 @@ jobs:
cd /tmp/tgz
npm init -y > /dev/null
npm install ./trainctl-core-*.tgz ./trainctl-export-*.tgz \
./trainctl-sync-intervalsicu-*.tgz ./trainctl-mcp-*.tgz \
./trainctl-sync-intervalsicu-*.tgz ./trainctl-sync-files-*.tgz ./trainctl-mcp-*.tgz \
./trainctl-[0-9]*.tgz
./node_modules/.bin/trainctl --version
./node_modules/.bin/trainctl init --template
./node_modules/.bin/trainctl plan --date 2026-08-08 | grep -q 'weeks of plan'
./node_modules/.bin/trainctl check
./node_modules/.bin/trainctl status --json | grep -q '"code": 0'
node --input-type=module -e "import('trainctl-sync-files').then((m) => { if (typeof m.FileActivitySource !== 'function') process.exit(1) })"
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"ci","version":"0"}}}' \
| TRAINCTL_DIR=/tmp/tgz timeout 30 ./node_modules/.bin/trainctl-mcp \
| grep -q '"serverInfo"'
160 changes: 160 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,166 @@ change between minor versions — a regenerated plan can differ.

## [Unreleased]

## [0.4.0] — 2026-10-21

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

## [0.3.0] — 2026-09-06

### Added — everyday coaching workflows
Expand Down
30 changes: 30 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
# trainctl — notes for coding agents

Read [CONTRIBUTING.md](CONTRIBUTING.md) first; decisions live in the ADR table
of [SPEC.md](SPEC.md) §10–§11, rule IDs in
[docs/science/FOUNDATIONS.md](docs/science/FOUNDATIONS.md) §10. The current
work plan is [docs/PLAN-v0.4.md](docs/PLAN-v0.4.md).

Gate before every commit: `pnpm check` (typecheck of all packages + vitest).

Rules that break things when ignored:

1. **Native type stripping (Node ≥ 22.18).** Relative imports end in `.ts`;
no parameter properties, enums or namespaces. The repo has no build step;
`pnpm build` only emits `dist/` for publishing (ADR-026).
2. **Handlers return blocks, not colours.** Command handlers in
`packages/cli/src/commands.ts` return semantic blocks (`ui/blocks.ts`) and
`data`; only `bin.ts` renders ANSI. MCP must never receive `\x1b[`.
3. **Both languages, always.** User-facing text goes to the catalogues
(`packages/cli/src/i18n/cli-en.ts` is the type source, `cli-pl.ts` follows;
domain text in `packages/core/src/i18n/`). `cli-i18n.test.ts` and
`no-leaks.test.ts` enforce it.
4. **Every engine constant cites a FOUNDATIONS rule ID** or is commented as an
engineering choice. The engine proposes, it never silently rewrites a plan
(ADR-011, ADR-029).
5. **Secrets and personal data never enter the repo**: no API keys, no corpus
files, no real activity files or `init --from-intervals` output in fixtures.
Remote deletes only touch entries prefixed `trainctl-` (ADR-016).

Comments and commit messages are written in Polish (Conventional Commits);
README and package descriptions in English, with `README.pl.md` kept in step.
11 changes: 11 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,12 +35,23 @@ visible rather than silent.
| `trainctl-mcp` | the MCP server — 17 tools over those same handlers |
| `trainctl-export` | `.fit`, `.ics`, printable HTML, race-day pack |
| `trainctl-sync-intervalsicu` | the intervals.icu adapter |
| `trainctl-sync-files` | exported activity files (FIT, TCX, GPX) as a pull-only source |

The dependency arrow points one way: `core` knows nothing about the CLI, and the
MCP server imports only from `trainctl`. A command handler that formats its own
output with colours is a bug — handlers return semantic blocks
(`packages/cli/src/ui/blocks.ts`) and the CLI renderer adds the colour.

## The agent plugin

`plugin/` packages the MCP server for Claude Code and Codex (see
[docs/integrations/agents.md](docs/integrations/agents.md)). Its skills are
generated: after changing the `AGENTS.md` text in the CLI catalogues or
`packages/cli/src/plugin-skills.ts`, run `node tools/plugin/render-skills.ts`.
Versions are pinned in several places (packages, plugin manifests, MCP configs,
the check hook, CI examples); `node tools/release/bump-version.mjs <x.y.z>` moves
them together, and the tests fail when one is left behind.

## What a change needs

**Engine rules need a source.** Every rule carries an ID from
Expand Down
Loading
Loading