@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 +21 -0
- package/README.md +105 -0
- package/dist/index.d.ts +14 -0
- package/dist/index.js +171 -0
- package/openclaw.plugin.json +35 -0
- package/package.json +49 -0
- package/skills/coach/SKILL.md +253 -0
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).
|
package/dist/index.d.ts
ADDED
|
@@ -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
|
+
```
|