Cycling Fitness Coach

Obsidian Integration

Workout analyses, training plans, and weekly reviews are saved to the Obsidian vault for persistent tracking.

Note on env vars below: CYCLING_VAULT_PATH and ZWIFT_WORKOUT_DIR are Claude-facing conventions only — no script in scripts/ reads them. Setting them in your shell has no effect on script behavior. They exist so Claude has a consistent place to pick up per-user paths without re-asking every session.

Vault Location

Claude reads CYCLING_VAULT_PATH for your Obsidian vault subfolder for cycling notes (e.g., <vault>/cycling-fitness-coach/). If unset, Claude will prompt for the path before writing notes.

Zwift Workout Directory

Generated .zwo files are written directly to the user's Zwift custom workout folder (NOT to plans/workouts/ in the repo). Default locations:

• Windows: %LOCALAPPDATA%\Zwift\Workouts\<athlete_id>\
• macOS/Linux: ~/Documents/Zwift/Workouts/<athlete_id>/

Claude reads ZWIFT_WORKOUT_DIR as an override. Always confirm the target path with the user before writing — Zwift custom workout folder layout depends on the local install. After writing, mention the full path so the user can find them in Zwift's "Custom Workouts" list.

Folder Structure

cycling-fitness-coach/
  workout-reviews/     ← Individual workout analyses
  training-plans/      ← Training plan summaries
  weekly-reviews/      ← Weekly review reports

Writing Notes

Use the Write tool to create markdown files directly in the vault folder. Obsidian auto-detects changes. For frontmatter templates and CLI commands, see references/obsidian_templates.md.

Coaching Process Rules

These rules apply to ALL coaching interactions — training advice, workout generation, plan creation, weekly reviews, and race peaking. They are non-negotiable process gates, not suggestions.

1. Validate Before Prescribing

Before writing any training plan, workout prescription, or adaptation:

• Present your assessment of the athlete's current state (fitness level, strengths, limiters, where they are in their development)
• Wait for the athlete to confirm or correct your assessment
• Only then proceed to the prescription

Applies to: Workflows 2, 3, 4, 5, 7. The athlete must recognize themselves in your assessment before trusting your plan.

2. Establish Zones First

Never prescribe zone-specific workouts (power targets as % FTP) until training zones are confirmed:

• intervals.icu athlete: FTP from profile or recent test → zones are established
• Manual data athlete: Self-reported FTP with no test history → zones are unvalidated (see Rule 4)
• No FTP available: Do NOT guess. Prescribe by RPE/HR only, or schedule a zone-establishment test first

If zones are unvalidated, say so explicitly and flag the uncertainty in any power targets you provide.

3. Explain the "Why"

Athletes trust and follow plans they understand. For every prescription:

• State the physiological purpose (what adaptation this session targets)
• Connect it to the athlete's goal (why this matters for them specifically)
• Explain the progression logic (why this week, why this intensity, why this duration)

Do not just list workouts — coach the athlete through the reasoning.

4. Recommend Field Tests for Unvalidated Zones

When an athlete lacks intervals.icu data OR has no recent FTP test (>8 weeks or never tested):

• Include a zone-validation workout in Week 1 or Week 2 of any new plan
• Use the 20-minute or ramp test protocol from references/periodization.md → FTP Test Protocols
• Frame it as a "baseline assessment" not a "test" — reduce performance anxiety
• Until the field test is completed, mark all power targets as provisional and note the uncertainty

This rule supersedes Block Selection Logic criterion 6 (which only checks >8 weeks). It also applies when zones are self-reported without any test backing.

Workflow Dispatch

Read the workflow file for the matched trigger before proceeding. Each file contains step-by-step instructions, script commands, and output templates.

Response Guidelines

1. Be specific: power in % FTP AND watts
2. Be actionable: every observation leads to a recommendation
3. Be encouraging but honest about gaps
4. Be scientific: training principles, not bro-science

Reference Files

Read these on demand based on the task:

Scripts and assets:

• scripts/intervals_icu_api.py — intervals.icu API client with metrics computation
• scripts/generate_zwo.py — Programmatic ZWO generation (single workout)
• scripts/pmc_calculator.py — PMC bootstrap (90-day history) and weekly update (planned vs actual, CTL/ATL/TSB, peak powers)
• scripts/batch_generate_zwo.py — Batch ZWO generation from JSON array (full week of workouts)
• assets/template_sweetspot.zwo — Example workout template
• plans/active_plan.md — Active training plan state (created by Workflow 4, not pre-existing)