@sctg/openclaw-coach 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Ronan LE MEILLAT
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,105 @@
1
+ # OpenClaw Coach
2
+
3
+ An AI endurance coach plugin for [OpenClaw](https://github.com/openclaw/openclaw),
4
+ built on top of [garmin-cli](https://github.com/sctg-development/garmin-cli)
5
+ (the `gc` CLI for Garmin Connect).
6
+
7
+ It ships:
8
+
9
+ - A `coach` skill with real coaching methodology (HRV/readiness
10
+ interpretation, training-zone recalibration, grade-adjusted pace and
11
+ cardiac-drift analysis, trail/vertical periodization) and safety framing
12
+ (see [`skills/coach/SKILL.md`](skills/coach/SKILL.md)).
13
+ - `coach_garmin_digest`, aggregating the handful of `gc` commands a routine
14
+ check-in needs (recent activities, training readiness/status, HRV, body
15
+ battery, sleep, weight trend, race predictions) into one call.
16
+ - `coach_activity_deep_dive`, a fine-grained bundle for one activity:
17
+ elevation/grade-segmented splits, HR zones, and weather — the basis for
18
+ grade-adjusted pace and cardiac-drift analysis.
19
+
20
+ It deliberately does **not** ship its own scheduler or a bundled athlete
21
+ profile. Proactive check-ins use OpenClaw's built-in
22
+ [Automations](https://docs.openclaw.ai/automation/cron-jobs) (`openclaw
23
+ automations create ...`), and the athlete's actual profile — bio, personal
24
+ records, goal race, injury/medical history, current constraints — lives in a
25
+ workspace `ATHLETE.md` file you maintain yourself, the same way OpenClaw
26
+ already handles `AGENTS.md`/`SOUL.md`/`USER.md`. That file is never part of
27
+ this repo: it's personal health data, and this plugin is public.
28
+
29
+ ## Requirements
30
+
31
+ - An OpenClaw Gateway (2026.8.2+).
32
+ - [`gc`](https://github.com/sctg-development/garmin-cli) installed and
33
+ authenticated (`gc login ...`) in the same environment the Gateway runs
34
+ in. The bundled [`garmin`](https://github.com/openclaw/openclaw/tree/main/skills/garmin)
35
+ skill already documents this.
36
+
37
+ ## Install
38
+
39
+ ```bash
40
+ openclaw plugins install npm:@sctg/openclaw-coach
41
+ ```
42
+
43
+ Or as a git submodule alongside a local OpenClaw checkout, matching how this
44
+ was originally built — see the parent deployment's plugin loading setup for
45
+ the exact wiring.
46
+
47
+ ## Publishing
48
+
49
+ `.github/workflows/publish.yml` publishes to npm when a GitHub Release is
50
+ published (or manually via workflow dispatch). It expects an `NPM_TOKEN`
51
+ repository secret with publish rights to the `@sctg` npm org:
52
+
53
+ ```bash
54
+ gh secret set NPM_TOKEN --repo sctg-development/openclaw-coach
55
+ ```
56
+
57
+ The workflow checks that `package.json`'s version matches the release tag
58
+ (`vX.Y.Z`) before building and publishing, so bump the version and tag
59
+ together.
60
+
61
+ ## Set up
62
+
63
+ 1. Confirm `gc status` succeeds in the Gateway's environment.
64
+ 2. Create `ATHLETE.md` in your OpenClaw workspace from the template in
65
+ [`skills/coach/SKILL.md`](skills/coach/SKILL.md#athletemd-template), or
66
+ just ask the coach to create it with you.
67
+ 3. Optionally, set up a proactive check-in — see
68
+ [the skill's "Proactive check-ins" section](skills/coach/SKILL.md#proactive-check-ins)
69
+ for the `openclaw automations create` recipe.
70
+ 4. Ask the coach for a status update, a plan, or anything else — it reads
71
+ `ATHLETE.md` and pulls Garmin data as needed.
72
+
73
+ ## Configuration
74
+
75
+ | Key | Type | Default | Description |
76
+ | ----------- | ------ | ------- | ------------------------------------------------ |
77
+ | `gcBinary` | string | `"gc"` | Path to the garmin-cli binary, if not on `PATH`. |
78
+
79
+ ```json5
80
+ {
81
+ plugins: {
82
+ entries: {
83
+ coach: {
84
+ config: { gcBinary: "/usr/local/bin/gc" },
85
+ },
86
+ },
87
+ },
88
+ }
89
+ ```
90
+
91
+ ## Why so little custom code?
92
+
93
+ Most of what an "AI coach" needs is already solved by OpenClaw itself: full
94
+ Garmin data access (the `garmin` skill), scheduling (Automations), and
95
+ durable per-athlete context (workspace files). This plugin's job is the one
96
+ thing those don't cover well on their own — collapsing several Garmin calls
97
+ into one coaching-shaped digest — plus the coaching methodology and safety
98
+ framing as a skill. See [`skills/coach/SKILL.md`](skills/coach/SKILL.md) for
99
+ the actual coaching logic; it lives in prose, not code, because a coach's
100
+ judgment calls (how to weigh a good VO2max trend against a still-healing
101
+ fracture, for instance) belong in reasoning, not a rigid algorithm.
102
+
103
+ ## License
104
+
105
+ MIT — see [LICENSE](LICENSE).
@@ -0,0 +1,14 @@
1
+ declare const _default: Omit<{
2
+ id: string;
3
+ name: string;
4
+ description: string;
5
+ kind?: import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition["kind"];
6
+ configSchema?: import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginConfigSchema | (() => import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginConfigSchema);
7
+ reload?: import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition["reload"];
8
+ nodeHostCommands?: import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition["nodeHostCommands"];
9
+ securityAuditCollectors?: import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition["securityAuditCollectors"];
10
+ register: NonNullable<import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition["register"]>;
11
+ }, "configSchema"> & {
12
+ configSchema: import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginConfigSchema;
13
+ };
14
+ export default _default;
package/dist/index.js ADDED
@@ -0,0 +1,171 @@
1
+ import { execFile } from "node:child_process";
2
+ import { promisify } from "node:util";
3
+ import { Type } from "typebox";
4
+ import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
5
+ const execFileAsync = promisify(execFile);
6
+ const DEFAULT_GC_BINARY = "gc";
7
+ const GC_TIMEOUT_MS = 20_000;
8
+ /**
9
+ * Runs one `gc <args...> --format json` call. Each call is independent and
10
+ * failure-isolated: a down Garmin session, a rate limit, or one unsupported
11
+ * subcommand must not blank out the rest of the digest.
12
+ */
13
+ async function fetchGarminJson(gcBinary, args) {
14
+ try {
15
+ const { stdout } = await execFileAsync(gcBinary, [...args, "--format", "json"], {
16
+ timeout: GC_TIMEOUT_MS,
17
+ maxBuffer: 8 * 1024 * 1024,
18
+ });
19
+ return { ok: true, data: JSON.parse(stdout) };
20
+ }
21
+ catch (error) {
22
+ return { ok: false, error: error instanceof Error ? error.message : String(error) };
23
+ }
24
+ }
25
+ /** Runs several failure-isolated gc fetches concurrently and splits results from errors. */
26
+ async function fetchGarminBatch(fetches) {
27
+ const resolved = await Promise.all(Object.entries(fetches).map(async ([key, pending]) => [key, await pending]));
28
+ const data = {};
29
+ const errors = {};
30
+ for (const [key, result] of resolved) {
31
+ if (result.ok) {
32
+ data[key] = result.data;
33
+ }
34
+ else {
35
+ data[key] = null;
36
+ errors[key] = result.error;
37
+ }
38
+ }
39
+ return { data, errors };
40
+ }
41
+ function isoDate(date) {
42
+ return date.toISOString().slice(0, 10);
43
+ }
44
+ const UnknownJson = Type.Unknown();
45
+ export default definePluginEntry({
46
+ id: "coach",
47
+ name: "AI Coach",
48
+ description: "Endurance coaching skill backed by Garmin Connect training-signal tools.",
49
+ register(api) {
50
+ const gcBinary = typeof api.pluginConfig?.gcBinary === "string" && api.pluginConfig.gcBinary.trim()
51
+ ? api.pluginConfig.gcBinary.trim()
52
+ : DEFAULT_GC_BINARY;
53
+ api.registerTool({
54
+ name: "coach_garmin_digest",
55
+ label: "Coach Garmin Digest",
56
+ description: "Fetches a compact Garmin Connect training-signal digest for the coach: recent " +
57
+ "activities, training readiness/status, HRV, body battery, sleep, weight trend, and " +
58
+ "race predictions. One call replaces several separate `gc` invocations. Use " +
59
+ "coach_activity_deep_dive afterwards for a specific activity's splits/HR-zones/weather. " +
60
+ "Requires the gc CLI (garmin-cli) to already be authenticated in this environment.",
61
+ parameters: Type.Object({
62
+ days: Type.Optional(Type.Integer({
63
+ minimum: 1,
64
+ maximum: 90,
65
+ default: 7,
66
+ description: "Lookback window in days for activities and weigh-ins (default 7).",
67
+ })),
68
+ }),
69
+ outputSchema: Type.Object({
70
+ rangeStart: Type.String(),
71
+ rangeEnd: Type.String(),
72
+ activities: UnknownJson,
73
+ trainingReadiness: UnknownJson,
74
+ trainingStatus: UnknownJson,
75
+ hrv: UnknownJson,
76
+ bodyBattery: UnknownJson,
77
+ sleep: UnknownJson,
78
+ weighIns: UnknownJson,
79
+ racePredictions: UnknownJson,
80
+ errors: Type.Record(Type.String(), Type.String()),
81
+ }, { additionalProperties: false }),
82
+ async execute(_id, rawParams) {
83
+ const { days = 7 } = rawParams;
84
+ const end = new Date();
85
+ const start = new Date(end.getTime() - days * 24 * 60 * 60 * 1000);
86
+ const rangeStart = isoDate(start);
87
+ const rangeEnd = isoDate(end);
88
+ const { data, errors } = await fetchGarminBatch({
89
+ activities: fetchGarminJson(gcBinary, [
90
+ "activities",
91
+ "--start",
92
+ rangeStart,
93
+ "--end",
94
+ rangeEnd,
95
+ ]),
96
+ trainingReadiness: fetchGarminJson(gcBinary, ["metrics", "training-readiness", "today"]),
97
+ trainingStatus: fetchGarminJson(gcBinary, ["metrics", "training-status", "today"]),
98
+ hrv: fetchGarminJson(gcBinary, ["metrics", "hrv", "today"]),
99
+ bodyBattery: fetchGarminJson(gcBinary, ["battery", "today"]),
100
+ sleep: fetchGarminJson(gcBinary, ["sleep", "yesterday"]),
101
+ weighIns: fetchGarminJson(gcBinary, [
102
+ "body",
103
+ "weighins",
104
+ "--start",
105
+ rangeStart,
106
+ "--end",
107
+ rangeEnd,
108
+ ]),
109
+ racePredictions: fetchGarminJson(gcBinary, ["metrics", "race-predictions"]),
110
+ });
111
+ const digest = { rangeStart, rangeEnd, ...data, errors };
112
+ const totalCalls = Object.keys(data).length;
113
+ const failedCount = Object.keys(errors).length;
114
+ const summaryText = failedCount === 0
115
+ ? `Garmin digest for ${rangeStart} to ${rangeEnd}: all ${totalCalls} signals fetched.`
116
+ : `Garmin digest for ${rangeStart} to ${rangeEnd}: ${failedCount} of ${totalCalls} signals unavailable (${Object.keys(errors).join(", ")}).`;
117
+ return {
118
+ content: [
119
+ { type: "text", text: summaryText },
120
+ { type: "text", text: JSON.stringify(digest, null, 2) },
121
+ ],
122
+ details: digest,
123
+ };
124
+ },
125
+ });
126
+ api.registerTool({
127
+ name: "coach_activity_deep_dive",
128
+ label: "Coach Activity Deep Dive",
129
+ description: "Fetches a fine-grained analysis bundle for one Garmin activity: summary, elevation- " +
130
+ "and grade-segmented splits, HR zones, and weather (temperature/conditions) at the " +
131
+ "time of the activity. Use this after coach_garmin_digest identifies an activity worth " +
132
+ "a closer look (a key long run, a race, an unusually hard or easy session).",
133
+ parameters: Type.Object({
134
+ activityId: Type.String({
135
+ description: "Garmin activity id, as returned in coach_garmin_digest's activities list.",
136
+ }),
137
+ }),
138
+ outputSchema: Type.Object({
139
+ activityId: Type.String(),
140
+ summary: UnknownJson,
141
+ typedSplits: UnknownJson,
142
+ hrZones: UnknownJson,
143
+ weather: UnknownJson,
144
+ errors: Type.Record(Type.String(), Type.String()),
145
+ }, { additionalProperties: false }),
146
+ async execute(_id, rawParams) {
147
+ const { activityId } = rawParams;
148
+ const { data, errors } = await fetchGarminBatch({
149
+ summary: fetchGarminJson(gcBinary, ["activities", "get", activityId]),
150
+ // Typed splits carry per-segment elevation/grade, the basis for grade-adjusted
151
+ // pace analysis; plain splits are a strict subset without that detail.
152
+ typedSplits: fetchGarminJson(gcBinary, ["activities", "typed-splits", activityId]),
153
+ hrZones: fetchGarminJson(gcBinary, ["activities", "hr-zones", activityId]),
154
+ weather: fetchGarminJson(gcBinary, ["activities", "weather", activityId]),
155
+ });
156
+ const digest = { activityId, ...data, errors };
157
+ const failedCount = Object.keys(errors).length;
158
+ const summaryText = failedCount === 0
159
+ ? `Activity ${activityId}: summary, splits, HR zones, and weather all fetched.`
160
+ : `Activity ${activityId}: ${failedCount} of ${Object.keys(data).length} signals unavailable (${Object.keys(errors).join(", ")}).`;
161
+ return {
162
+ content: [
163
+ { type: "text", text: summaryText },
164
+ { type: "text", text: JSON.stringify(digest, null, 2) },
165
+ ],
166
+ details: digest,
167
+ };
168
+ },
169
+ });
170
+ },
171
+ });
@@ -0,0 +1,35 @@
1
+ {
2
+ "id": "coach",
3
+ "name": "AI Coach",
4
+ "description": "Endurance coaching skill backed by Garmin Connect training-signal tools (via garmin-cli's gc CLI).",
5
+ "requiresPlugins": [],
6
+ "skills": ["skills/coach"],
7
+ "activation": {
8
+ "onStartup": true
9
+ },
10
+ "contracts": {
11
+ "tools": ["coach_garmin_digest", "coach_activity_deep_dive"]
12
+ },
13
+ "toolMetadata": {
14
+ "coach_garmin_digest": {
15
+ "optional": false,
16
+ "sideEffecting": false,
17
+ "replaySafe": true
18
+ },
19
+ "coach_activity_deep_dive": {
20
+ "optional": false,
21
+ "sideEffecting": false,
22
+ "replaySafe": true
23
+ }
24
+ },
25
+ "configSchema": {
26
+ "type": "object",
27
+ "additionalProperties": false,
28
+ "properties": {
29
+ "gcBinary": {
30
+ "type": "string",
31
+ "description": "Path to the garmin-cli `gc` binary. Defaults to \"gc\" (resolved from PATH)."
32
+ }
33
+ }
34
+ }
35
+ }
package/package.json ADDED
@@ -0,0 +1,49 @@
1
+ {
2
+ "name": "@sctg/openclaw-coach",
3
+ "version": "0.1.0",
4
+ "description": "AI endurance coach plugin for OpenClaw: aggregates Garmin Connect training signals via garmin-cli into one digest tool, backing a coaching skill.",
5
+ "type": "module",
6
+ "license": "MIT",
7
+ "author": "Ronan LE MEILLAT",
8
+ "repository": {
9
+ "type": "git",
10
+ "url": "git+https://github.com/sctg-development/openclaw-coach.git"
11
+ },
12
+ "main": "./dist/index.js",
13
+ "types": "./dist/index.d.ts",
14
+ "files": [
15
+ "dist",
16
+ "skills",
17
+ "openclaw.plugin.json",
18
+ "README.md",
19
+ "LICENSE"
20
+ ],
21
+ "scripts": {
22
+ "build": "tsc",
23
+ "prepublishOnly": "npm run build"
24
+ },
25
+ "dependencies": {
26
+ "typebox": "1.3.17"
27
+ },
28
+ "devDependencies": {
29
+ "openclaw": ">=2026.8.2",
30
+ "typescript": "^5.9.0"
31
+ },
32
+ "peerDependencies": {
33
+ "openclaw": ">=2026.8.2"
34
+ },
35
+ "openclaw": {
36
+ "extensions": ["./dist/index.js"],
37
+ "compat": {
38
+ "pluginApi": ">=2026.8.2",
39
+ "minGatewayVersion": "2026.8.2"
40
+ },
41
+ "build": {
42
+ "openclawVersion": "2026.8.2",
43
+ "pluginSdkVersion": "2026.8.2"
44
+ }
45
+ },
46
+ "publishConfig": {
47
+ "access": "public"
48
+ }
49
+ }
@@ -0,0 +1,253 @@
1
+ ---
2
+ name: coach
3
+ description: Act as an AI endurance coach using Garmin Connect training data and the athlete's own profile/constraints file.
4
+ metadata: { "clawdbot": { "emoji": "🏃", "requires": { "bins": ["gc"] } } }
5
+ ---
6
+
7
+ # AI Endurance Coach
8
+
9
+ This skill turns the agent into a data-aware endurance coach. It combines:
10
+
11
+ - **`ATHLETE.md`** — a workspace file the athlete (or the agent, on their
12
+ behalf) maintains: bio, personal records, current goal race, injury/medical
13
+ history, and any active constraints or medical clearance status. This file
14
+ is private to the athlete's own deployment; it does not ship with this
15
+ plugin. If it does not exist yet, offer to create it from the template
16
+ below before giving any coaching advice.
17
+ - **The `garmin` skill** — full read (and, for workouts, write) access to
18
+ Garmin Connect via the `gc` CLI: activities, sleep, stress, body battery,
19
+ weight, VO2max, training readiness/status, race predictions, and more.
20
+ - **`coach_garmin_digest`** (this plugin's tool) — a one-call aggregate of the
21
+ handful of `gc` signals a coaching check-in actually needs (recent
22
+ activities, training readiness/status, HRV, body battery, sleep, weight
23
+ trend, race predictions). Use it for routine check-ins.
24
+ - **`coach_activity_deep_dive`** (this plugin's tool) — a one-call bundle for
25
+ *one specific activity*: summary, elevation/grade-segmented splits, HR
26
+ zones, and weather. Use it after `coach_garmin_digest` flags an activity
27
+ worth a closer look — a key long run, a race, an unusually hard or easy
28
+ session, or anything with a confusing HR/pace pattern.
29
+ - Fall back to individual `gc` commands (see the `garmin` skill) for anything
30
+ neither tool covers — a longer weight history, device/gear data, and so on.
31
+
32
+ ## Non-negotiable safety framing
33
+
34
+ This is a coaching tool, not a medical one. Treat `ATHLETE.md`'s injury and
35
+ medical-condition entries as authoritative constraints, never as
36
+ color/background to reason around:
37
+
38
+ - Never propose load, intensity, or terrain that conflicts with a stated
39
+ active injury, a recent fracture still within its usual healing/rehab
40
+ window, or an explicit "not yet cleared for X" note — even if recent
41
+ Garmin data looks encouraging. Encouraging metrics do not override medical
42
+ status.
43
+ - When ATHLETE.md's constraints are ambiguous, out of date, or silent on
44
+ something relevant (e.g. an old entry with no clearance update, or the
45
+ question depends on something only a physio/doctor can assess), say so
46
+ explicitly and suggest checking with the relevant professional. Do not
47
+ improvise medical judgment to fill the gap.
48
+ - Prefer conservative, reversible recommendations (an easy day, a shorter
49
+ session, cross-training) over aggressive ones when signals conflict —
50
+ poor recovery metrics alongside an ambitious plan should trigger caution,
51
+ not be talked past.
52
+ - For an athlete with a metabolic condition (e.g. prediabetes/diabetes) noted
53
+ in ATHLETE.md, weight and nutrition trends are relevant context for load
54
+ and recovery discussions; this skill does not give nutrition or medical
55
+ prescriptions.
56
+
57
+ ## Methodology
58
+
59
+ These are the concrete analytical tools this skill expects you to actually
60
+ use, not just gesture at. Apply them; don't just restate the raw numbers back
61
+ at the athlete.
62
+
63
+ ### HRV and readiness
64
+
65
+ Garmin's nightly HRV Status compares the last night's average HRV against a
66
+ rolling ~3-week baseline range, categorized `Balanced` / `Unbalanced` /
67
+ `Low` / `Poor` (from `coach_garmin_digest`'s `hrv` field, or
68
+ `gc metrics hrv`). Garmin's `training-readiness` and `morning-readiness`
69
+ scores already blend HRV status with sleep, sleep history, acute training
70
+ load, and stress into one number — prefer those as the primary readiness
71
+ signal and use raw HRV to understand *why* a readiness score moved.
72
+
73
+ - One low night is noise; a multi-day downward HRV trend (or several
74
+ `Unbalanced`/`Low` days in a row) is the actionable signal. Read the
75
+ trend across the digest window, not a single day.
76
+ - HRV suppression is not always a training-load signal. Illness, alcohol,
77
+ heat, altitude, poor sleep, and — relevant here — pain or systemic stress
78
+ from a still-healing bone injury can all suppress it independent of
79
+ fitness. Don't default to "reduce training load" as the only
80
+ interpretation; consider what else changed (check `ATHLETE.md` and
81
+ recent activity/sleep context) before concluding it's training stress.
82
+ - Trend down + no other explanation -> favor an easy day, more sleep, or an
83
+ extra rest day over pushing the planned session. Trend flat-to-rising
84
+ within the athlete's normal range supports proceeding with a harder
85
+ planned session, subject to everything else in this skill.
86
+
87
+ ### Training zone recalibration
88
+
89
+ Device-configured HR/pace zones go stale — after a long layoff (a multi-year
90
+ gap, a post-injury return) they are usually calibrated to a fitness level
91
+ the athlete no longer has, in either direction. Recalibrate rather than
92
+ trusting old zones by default:
93
+
94
+ - Anchor zones on a recent lactate-threshold estimate (`gc metrics
95
+ lactate-threshold`) or Garmin's own VO2max/training-status trend, not on
96
+ personal records from years ago. A standard 5-zone percent-of-threshold-HR
97
+ model works well for trail: Z1 (<80% LTHR) recovery, Z2 (80-89%) aerobic
98
+ base — where most volume should sit — Z3 (90-94%) tempo, Z4 (95-99%)
99
+ threshold, Z5 (100%+) VO2max/anaerobic.
100
+ - After any long layoff or return from injury, assume zones need
101
+ re-anchoring from current data before trusting a plan built on them.
102
+ Say so explicitly rather than silently reusing whatever the device has
103
+ configured.
104
+ - On steep or technical trail, raw pace zones are close to meaningless —
105
+ a comfortable effort on a 20% grade climb can be far slower than a hard
106
+ effort on flat ground. Prefer HR zones or RPE for climbs, and grade-
107
+ adjusted pace (see below) when a pace comparison is genuinely useful.
108
+
109
+ ### Fine-grained activity analysis
110
+
111
+ Use `coach_activity_deep_dive` for this — it fetches the elevation/grade-
112
+ segmented splits, HR-zone time distribution, and weather for one activity.
113
+
114
+ - **Grade-adjusted effort:** read pace alongside each split's grade from
115
+ `typedSplits`. A slow pace on a steep climb and a fast pace on a
116
+ descent can represent similar physiological effort; compare effort via
117
+ HR/RPE per segment, not raw pace, on anything with meaningful elevation
118
+ change.
119
+ - **Cardiac drift:** rising HR while pace/effort holds steady over the
120
+ course of a longer activity signals accumulating fatigue, dehydration, or
121
+ heat stress — cross-check `hrZones` time-in-zone against the `typedSplits`
122
+ timeline. This is directly relevant to pacing a race with sustained
123
+ climbing like the athlete's goal event: a plan that ignores drift risks a
124
+ blow-up in the back half.
125
+ - **Weather context:** pull `weather` before judging an anomalous HR or
126
+ pace. Heat and altitude both inflate HR at a given pace/effort — a hot
127
+ day's "worse" numbers are not a fitness regression, and should not be
128
+ read as one.
129
+ - **Vertical-specific fitness:** for a hike-and-fly/trail background, track
130
+ Garmin's `hill-score` and `endurance-score` metrics over time in addition
131
+ to VO2max — they reflect climbing-specific and durability adaptations
132
+ that a flat-focused view of pace and distance misses entirely.
133
+
134
+ ### Periodization toward the goal race
135
+
136
+ Structure a plan in phases relative to the goal date in `ATHLETE.md`, not a
137
+ fixed template: base (aerobic volume, and — critically, see below — gradual
138
+ reintroduction of impact loading), build (race-specific terrain and vertical
139
+ work, ideally including sustained climbing matching the goal race's profile),
140
+ then taper. Recompute weeks-to-race whenever the goal date or current date
141
+ context makes that ambiguous; don't assume.
142
+
143
+ - **Bone-healing-aware load progression.** For an athlete with a history of
144
+ lower-limb fractures, treat impact-loading progression as conservative and
145
+ gradual by default: more running volume/intensity only as a deliberate,
146
+ small step, not a jump, and only within whatever timeline and clearance
147
+ status `ATHLETE.md` records. This is a general training-load principle,
148
+ not a medical judgment about healing time — defer entirely to
149
+ `ATHLETE.md`'s recorded clearance status for what is currently allowed,
150
+ per the safety framing above.
151
+ Note that this applies to bone-stress reintroduction broadly, not only
152
+ to fractures: any recent lower-limb injury needs the same gradual-
153
+ reintroduction treatment.
154
+ - **Climbs before technical descents.** Uphill effort loads muscles
155
+ aerobically without the high eccentric/impact forces of downhill
156
+ running; technical or steep descents carry meaningfully higher
157
+ impact/eccentric load on the same healing structures. When a plan needs
158
+ to choose what to reintroduce first after a layoff or injury, climbing
159
+ volume is generally the lower-risk starting point, descents the thing to
160
+ reintroduce later and more cautiously. Confirm against `ATHLETE.md`
161
+ before assuming this applies to the current situation.
162
+ - **Taper** shortens duration while keeping some intensity, timed off the
163
+ goal date, with the exact length depending on build volume and the
164
+ athlete's own response history — check `ATHLETE.md` for anything
165
+ previously noted about what taper length has worked for this athlete.
166
+
167
+ ## Workflow
168
+
169
+ 1. **Read `ATHLETE.md`** first. If it does not exist, offer to create it
170
+ (template below) before coaching. If it exists but looks stale (no
171
+ updates in a long time relative to how often the athlete trains), ask
172
+ whether anything has changed before relying on it.
173
+ 2. **Pull recent signals** with `coach_garmin_digest` (default 7-day window;
174
+ pass `days` for a longer look-back, e.g. before adjusting a multi-week
175
+ plan). Cross-reference against `ATHLETE.md`'s current goal and
176
+ constraints. Follow up with `coach_activity_deep_dive` on any activity
177
+ that needs a closer look — see Methodology above.
178
+ 3. **Assess, don't just report.** Note trends (training readiness/status and
179
+ HRV trajectory, sleep/body battery recovery, weight trend, activity
180
+ volume/intensity vs. plan) and flag anything that looks like overreach
181
+ given the athlete's history, not just the raw numbers.
182
+ 4. **Propose or adjust a plan** toward the athlete's stated goal, respecting
183
+ time-to-goal, current fitness signals, and — above all — the constraints
184
+ in `ATHLETE.md`. Keep the plan in prose in `ATHLETE.md` (or a separate
185
+ `PLAN.md` workspace file if the athlete prefers) so it persists and
186
+ evolves across conversations instead of being regenerated from scratch
187
+ each time. Update it explicitly when giving new guidance; do not leave
188
+ the athlete to reconcile old and new advice themselves.
189
+ 5. **Be direct.** State the assessment and the recommendation plainly. A
190
+ coach that only reflects data back without a recommendation is not doing
191
+ the job.
192
+
193
+ ## Proactive check-ins
194
+
195
+ This plugin does not implement its own scheduler — OpenClaw's built-in
196
+ Automations (cron) already does this well. Set up a recurring check-in with:
197
+
198
+ ```bash
199
+ openclaw automations create "0 7 * * *" \
200
+ --name "Coach check-in" \
201
+ --session main \
202
+ --system-event "Daily coach check-in: pull the last 24-48h of Garmin data with coach_garmin_digest, compare against ATHLETE.md's current plan and constraints, and give a short assessment. Adjust the plan if needed." \
203
+ --tz "<your timezone, e.g. Europe/Paris>"
204
+ ```
205
+
206
+ Adjust the schedule (`--cron`/`--every`), session target, and delivery
207
+ (`--announce --channel ...`) to taste — see the automations docs
208
+ (`openclaw automations --help`, or `/automation/cron-jobs` in the OpenClaw
209
+ docs) for the full set of options. A weekly deeper review (longer
210
+ `coach_garmin_digest` window, explicit plan reassessment) is a good
211
+ complement to a lighter daily check-in.
212
+
213
+ ## ATHLETE.md template
214
+
215
+ ```markdown
216
+ # Athlete Profile
217
+
218
+ ## Bio
219
+
220
+ - Age:
221
+ - Height / weight:
222
+ - Athletic background:
223
+
224
+ ## Personal records
225
+
226
+ -
227
+
228
+ ## Current goal
229
+
230
+ - Race / event:
231
+ - Date:
232
+ - Distance / elevation:
233
+
234
+ ## Injury and medical history
235
+
236
+ <!-- One entry per event: what, when, current status (recovering / cleared
237
+ / cleared with restrictions), and who cleared it if applicable. Keep
238
+ this section current -- it is the coach's primary safety constraint. -->
239
+
240
+ -
241
+
242
+ ## Current constraints
243
+
244
+ <!-- Anything actionable right now: "no technical descents until physio
245
+ clearance", "avoid running on consecutive days", "prediabetes -- watch
246
+ post-exertion glucose", etc. -->
247
+
248
+ -
249
+
250
+ ## Training availability
251
+
252
+ - Days/week, typical session length, access to terrain/elevation:
253
+ ```