aicoach-framework

360° Data Athlete

⚠️ Experimental project. Not intended for unsupervised training.

This is a coding experiment with multi-agent systems, using sport training as the problem domain. It does not replace a coach or sports-medical advice. Use only with a solid training background, at your own risk. No warranty, no support, no audit.

An AI coach for endurance and strength athletes, distributed as a Claude Code plugin. A team of specialised sub-agents (planner, three workout specialists, mental coach, video analyst, post-activity analyst, data scientist, plan validator, config auditor, two clinical consultants) collaborate to plan, push, and review training — grounded in intervals.icu, Strava, Garmin and (optionally) Telegram.

Framing

This is not a multi-agent example. For pure multi-agent orchestration there are better-fitting frameworks (LangChain / LangGraph, AutoGen, CrewAI). What this project explores is something else: Claude Code as a general-purpose agent harness, applied to a domain that isn't code.

Claude Code is usually marketed for software engineering — but it already ships everything you need to drive a long-running, file-backed, sub-agent-orchestrating workflow against a real-world domain: namespaced sub-agents with isolated context, slash commands, hooks, MCP servers, plugins, persistent state in plain files, terminal + Telegram surfaces. Training planning is the test bench: it has conflicting constraints (HRV vs. schedule, injury vs. progression, weather vs. pillar rotation), persistent state across days, and an actual human (the maintainer) who pushes back when the system gets it wrong. Every rule in the framework exists because at some point that pushback exposed a gap.

If you came for the agent design, the architecture doc, agents/*.md, and framework/CLAUDE.md are the interesting parts. If you came for training: read on.

---

What it does

• Daily planning that respects HRV, CTL / ATL / TSB, sleep, weather, races on the calendar, and active injury restrictions
• Specialist delegation — each workout type has its own pane with the right context (type history, exercise progressions, validator rules)
• Pre-push validation — mechanical (scripts/validate_plan.py, rule-based) and semantic (plan-validator subagent)
• Post-activity analysis — factual lap chronicle + coaching feedback, HRV-response review
• Video form check via Gemini for strength / core / ninja and running
• Per-muscle load tracking with a 30-day fatigue overview
• Consistency audit that scans for drift across configs, agents, prompts — with the exercise-log slice auto-surfaced at every session start, so stale progression entries don't wait for /audit to be noticed
• Optional Telegram channel for use away from the terminal

---

How the daily planning works

The /training command is the central workflow — this is what actually runs when an athlete says "plan today". The flow is deliberately multi-stage so each stage has the right context and nothing else.

fetch_context  →  planner  →  specialists (per workout)
                                    ↓
                            cross-workout review
                                    ↓
                  mechanical validator + semantic plan-validator
                                    ↓
                            present to athlete
                                    ↓
                    accept  →  push to intervals.icu

1. Context (fetch_context.py)

A single Python entry point pulls everything the planner needs and normalises it into one JSON blob:

• Wellness: HRV, baseline, deviation, RHR, sleep score + hours, CTL, ATL, TSB, CTL trend, weekly load history
• Activity history (4 weeks), zone distribution, weekly polarisation
• Upcoming events / race-in-days from intervals.icu calendar
• Athlete feedback NOTEs (last 4 weeks)
• Active injury / pillar / muscle blocks from athlete_static.md + recovery rules
• HR zones from intervals.icu settings (read 1:1, never reconstructed)
• Weather forecast for the planning day
• Shoe fleet + recommendation (when Run is on the plan)
• HRV-forecast verdict for yesterday's training response (see below)

The athlete config in config/*.md is merged over the framework defaults in config.example/*.md, so each athlete sees their own zones, priorities, restrictions, and language.

2. HRV forecast — why it matters

A naive HRV-gated coach reads "HRV under baseline → block intensity". That works on rest days but fails the day after a hard session: HRV should drop after Z4 intervals, that's the autonomic system doing its job. Without context, the coach panics and downgrades the planned session — silent over-conservatism.