Live
Powered by

Athlete calendar activity proposal

Objective

Create a new per-athlete calendar layer at athlete/calendar/ that holds one Markdown file per day at YYYY-MM-DD.md.

This proposal, the related skills, and any supporting processes must be athlete-agnostic. The path pattern is standardized per athlete, but the design itself must not depend on any single athlete, sport block, race calendar, or named athlete implementation.

Each daily file should contain the planned activities or events for that date in a clean, uniform, system-neutral format that can be:

  • created and revised by whatever authorized process is responsible for populating the calendar
  • consumed by downstream systems that need clean daily activity objects
  • manipulated safely by multiple agents without depending on fragile prose parsing

This calendar layer should sit between high-level planning and external system execution.

It should not replace:

  • long-range planning documents
  • rolling planning summaries
  • canonical daily logs
  • athlete-facing messages

It should become the canonical per-day plan artifact for future planned activities.

Scope boundary

This proposal is only about the calendar layer itself:

  • directory structure
  • file format
  • activity and event schema
  • templates
  • storage rules
  • revision rules for calendar files
  • the unified skill that adds, edits, deletes, and moves calendar items

This proposal is explicitly not about:

  • who decides what activities should exist
  • what planning process chooses which future items to create
  • who is responsible for approving the plan content
  • how external systems publish, sync, or schedule those items after the calendar files exist
  • athlete-facing communication behavior derived from those files

The calendar is the storage and representation layer for calendar items. Upstream planning logic and downstream publishing logic are out of scope.

Why a calendar layer is needed

The current planning stack has a gap between strategy documents and executable daily activities.

Today, the system has:

  • long-range block planning
  • rolling short-term planning
  • daily logs for what happened
  • TrainingPeaks creation tooling

What it does not yet have is a canonical daily plan object that is:

  • durable
  • per-date
  • multi-activity capable
  • neutral with respect to TrainingPeaks implementation details
  • simple for other agents and automation to revise

That missing layer makes several jobs harder than they should be:

  • storing future daily activity objects in a consistent format
  • revising one future day without rewriting broad planning prose
  • representing multiple same-day items cleanly
  • giving downstream systems one stable daily source to read

Proposed directory

Create a new directory per athlete:

athlete/calendar/

Optional supporting directory:

athlete/calendar/archives/

Important requirement:

  • the storage path is athlete-scoped, but the calendar model, workflow rules, and skill behavior must remain generic across all athletes
  • no part of this proposal should require athlete-specific assumptions, hard-coded athlete references, or athlete-specific source-file names
  • the optional archives/ directory is part of the calendar area and may be used to hold calendar files moved out of the active calendar set for future reference

Primary file contract:

  • one file per day
  • file name: YYYY-MM-DD.md
  • one file may contain zero, one, or many planned activities or events

Archive contract:

  • archived files may be moved from athlete/calendar/ into athlete/calendar/archives/
  • files in archives/ should generally be ignored by normal calendar-writing, calendar-reading, and calendar-maintenance workflows unless a task explicitly asks to inspect archived material
  • the archive is for possible future reference, not for active planning

These files are planning artifacts, not execution logs. Historical strategy should stay outside the calendar files.

Design principles

1. One daily file, many activities

The calendar should use one file per date, not one file per activity.

That keeps all same-day objects together, including cases such as:

  • bike session plus gym session
  • race plus pre-ride
  • travel plus opener
  • rest day plus physio event

2. Activities are discrete calendar objects

Each activity inside a day file should represent one object that could reasonably stand alone in an external training or coaching calendar, or even a personal calendar of an athlete.

Use a separate activity when it should exist independently, for example:

  • on-bike workout
  • gym session
  • race
  • pre-ride
  • travel day event
  • full rest day note

Do not split out tiny support items as independent activities unless they genuinely need to be managed as separate calendar objects. For example, pre-ride activation and post-ride mobility should usually remain inside the parent workout unless there is a specific reason to schedule them separately.

3. Calendar files are system-neutral

Calendar files should contain the plan content and reference metadata needed to represent, create, revise, or later correlate external activities.

They may contain durable reference fields or other data values when those fields are useful to the calendar item itself, for example:

  • a TrainingPeaks ID after the external item has been created
  • other external reference IDs if the calendar item must be correlated with another system later
  • additional notes, comments, flags, or metadata fields that help describe or track the item

They should not contain:

  • API payload details
  • MCP instructions
  • operator workflow notes
  • step-by-step process instructions
  • transient sync mechanics that describe how a tool should perform the integration

The calendar may hold durable item metadata, but it should not describe the mechanics of how another process publishes or updates the item.

4. No strategy prose inside activity files

Calendar files should not carry high-level planning rationale such as:

  • block intent
  • seasonal strategy
  • long-range progression comments
  • planning-process notes

Those belong in:

  • long-range planning documents
  • rolling plans
  • specialist notes
  • daily logs when explaining revisions

Calendar files should stay tightly focused on the activity to be executed.

5. Stable, machine-friendly structure

The format should be simple enough that:

  • humans can read it quickly
  • agents can edit it safely
  • other tools can parse it without depending on freeform prose

The best balance here is a fixed Markdown section layout with activity titles as headings, consistent bullet fields, and stable activity IDs stored as metadata when needed.

Proposed daily file structure

Recommended top-level structure:

# YYYY-MM-DD

## Controlled threshold re-entry
- Id: 2026-04-14-controlled-threshold-re-entry
- Title: Controlled threshold re-entry
- Kind: workout
- Discipline: bike
- Surface: road
- Priority: key
- Planned time: unscheduled
- Duration: 1:45-2:00
- Distance: ~45-55 km
- Intensity: Z2 warm-up, then Z4 controlled

### Objective
Controlled threshold re-entry.

### Workout plan
- 25-30 min progressive warm-up
- 3 x 8 min at controlled threshold, smooth and seated
- 4 min easy between efforts
- Finish with 30-40 min Z2
- No pushing beyond controlled threshold breathing

### Supporting work
- 10 min activation before the ride if useful: glute bridge, dead bug, calf isometrics
- 10 min mobility after the ride

### Recovery
- Light afternoon only
- Avoid stacking errands or extended time on feet

### Fueling
- 70-140 g carbohydrate before the ride depending on meal timing
- 90 g carbohydrate per hour during the session
- 30 g protein plus 80-90 g carbohydrate post-ride

### Notes
This session should feel like controlled pressure, not a test.

Proposed activity schema

Each activity should use the same core fields.

Required fields:

  • activity title, expressed as the ## section heading and not including the date
  • Title, matching the activity heading text
  • Kind

Usually required when relevant:

  • Id, format: YYYY-MM-DD-<title-tokenized>
  • Surface
  • Distance
  • Intensity
  • Location
  • Discipline
  • Priority
  • Planned time
  • Duration

Optional metadata fields when relevant:

  • TrainingPeaks ID
  • other external reference IDs
  • additional item flags, notes, or data fields needed for durable reference

ID rule:

  • the Id value should be built from the file date plus a tokenized form of the activity title
  • example: Tempo durability ride becomes 2026-04-16-tempo-durability-ride
  • use lowercase words joined by hyphens

Required content sections:

  • Objective
  • Execution section, using Workout plan for workouts and Event details for non-workout events
  • Notes

Conditionally required sections:

  • Supporting work
  • Recovery
  • Fueling
  • Constraints

Standard enum suggestions:

Kind values:

  • workout
  • strength
  • recovery
  • event
  • race
  • travel
  • rest

Discipline values:

  • bike
  • mtb
  • cx
  • strength
  • mobility
  • recovery
  • travel
  • off-bike

Priority values:

  • key
  • support
  • maintenance
  • optional
  • informational

Planned time values:

  • unscheduled
  • explicit clock time when known
  • coarse timing such as morning, afternoon, or evening

Start-time rule:

  • a planned start time is not required by default
  • whoever or whatever creates the calendar item may include a start time when one is known or useful
  • for most training activities, start time will often be left to the athlete to manage

Candidate calendar item types

The calendar should support more than standard training sessions. Useful item types that may belong in the calendar, and may later be mirrored into TrainingPeaks or another coaching system, include:

  • on-bike workouts
  • strength sessions
  • mobility or recovery sessions when they are meaningful standalone calendar objects
  • race days
  • pre-rides
  • testing sessions
  • travel days
  • transfer or arrival events before races or camps
  • full rest days
  • medical, physio, or treatment appointments when they materially affect the athlete day
  • equipment-related events, such as bike fit, mechanic appointment, or race-bike pickup, when they are operationally important
  • administrative or logistics reminders that should appear in the athlete training calendar, if the system chooses to represent them there

The proposal does not decide which of these items should exist on a given day. It only defines how such items should be represented once a process decides to store them in the calendar.

These examples are illustrative only. The calendar layer and the calendar-manager skill do not decide whether a gym session, race, travel event, rest day, physio appointment, or other item should exist as a calendar object. If an item is provided for creation, the calendar system should store it using the required format and template.

Heading structure

Use this heading hierarchy inside each daily file:

  • # YYYY-MM-DD for the date file heading
  • ## Activity title for each activity or event in that day
  • ### Objective, ### Workout plan, ### Event details, and other activity subsections

Do not add a wrapper heading such as ## Activities above the actual activity entries. Do not put the date into the activity heading text. Keep the Title field aligned with the activity heading text.

Activity variants

The format should stay consistent, but the middle content should vary by activity type.

Workout activity

Use for on-bike sessions, run sessions, gym sessions, and other training tasks.

The calendar layer does not decide when a gym session should exist as a separate activity. If a gym session is prescribed as a calendar item, it should be created as provided.

Sections:

  • header fields
  • ### Objective
  • ### Workout plan
  • ### Supporting work, when needed
  • ### Recovery, when needed
  • ### Fueling, when needed
  • ### Notes

Event activity

Use for travel, race day, pre-ride, rest day, testing appointment, physio, or other planned non-training calendar objects.

The calendar layer does not decide when these items should exist. If they are provided for creation, they should be represented using the event format.

Sections:

  • header fields
  • ### Objective
  • ### Event details
  • ### Constraints, when needed
  • ### Recovery, when needed
  • ### Fueling, when needed
  • ### Notes

Rest day activity

A rest day should still have a daily file and should usually include one explicit rest activity rather than leaving the file empty.

That makes the calendar complete and unambiguous.

Rules for splitting versus embedding

To keep the calendar usable, define one clear rule:

Create a separate activity only when it should be independently visible, editable, or publishable.

Examples:

  • On-bike session plus Lower-body strength session should usually be two activities.
  • Travel to race venue plus Pre-ride opener should usually be two activities.
  • Activation before the ride should usually stay inside the bike activity.
  • 10 min evening mobility should usually stay embedded unless explicitly scheduled as a separate calendar object.

Revision model

The calendar layer should support both:

  • creation of new daily files
  • revision of existing future daily files

Revision rules should stay structural and content-focused:

  • edit the affected daily file or files directly
  • preserve unaffected day files
  • replace stale activity details instead of appending contradictory versions
  • treat the calendar as the current planned state, not as a revision-history ledger

Archive handling rules:

  • when a calendar file should be retained for reference but removed from the active calendar set, it may be moved into athlete/calendar/archives/
  • archived files should not be treated as active daily calendar files by default
  • any process that scans the active calendar should exclude archives/ unless archived reference material is explicitly requested
  • if an archived file is moved into calendar/archives/ and a file with the same name already exists there, the moved file should be renamed with an incremented index, for example YYYY-MM-DD-1.md

If revision history is needed later, it should live outside the calendar content unless a small standardized Revision note field is adopted explicitly.

Proposed skill

calendar-manager, required

Purpose:

  • create calendar day files under athlete/calendar/YYYY-MM-DD.md
  • add activities or events to a day file
  • edit existing activities or events without breaking the format contract
  • delete activities or events when they should be removed from the active calendar
  • move activities or events when they belong on a different day
  • create, revise, and maintain the canonical template structure for calendar files

This skill should be the single calendar-layer skill for normal calendar operations. It should consolidate the responsibilities that would otherwise be split across separate creation, revision, move, delete, or template-management skills.

This skill should not decide whether a given item ought to exist. It should only apply the expected file format, naming convention, archive behavior, and item template when instructed to create or revise calendar content.

Core operations this skill should cover:

  • add an activity to an existing daily file
  • create a new daily file and add one or more activities
  • edit activity metadata or content sections
  • delete an activity from a daily file
  • move an activity from one daily file to another
  • rewrite a future daily file when the plan changes materially
  • move retired day files into calendar/archives/ when they should be preserved but ignored in active planning

Minimal implementation recommendation

The smallest useful first implementation is:

  1. create the new calendar-manager skill
  2. standardize one daily calendar template with activity variants
  3. define the add, edit, delete, and move rules for calendar items
  4. test the pattern on representative calendar entries without introducing athlete-specific rules into the contract
  5. keep the skill unified unless a real operational need appears to split it later

That gives the system a clean planning object model without overbuilding the first version.

The template should enforce these rules:

  • one # YYYY-MM-DD heading per file
  • one ## Activity title heading per activity
  • one fixed field block per activity
  • one fixed detail-section pattern per activity kind
  • activity titles should not contain the date
  • each activity should include Id: and Title: metadata lines
  • the Id: value should use the date plus tokenized title format

The active template contract applies to files in the live calendar/ directory. Files moved into calendar/archives/ should be preserved as reference artifacts and generally ignored during normal active-calendar operations.

This structure is rigid enough for automation but still comfortable for human editing.

Example multi-activity day

# 2026-04-16

## Tempo durability ride

- Id: 2026-04-16-tempo-durability-ride
- Title: Tempo durability ride
- Kind: workout
- Discipline: bike
- Surface: road
- Priority: key
- Planned time: unscheduled
- Duration: 2:00
- Distance: ~50-60 km
- Intensity: Z2 with sustained Z3 work

### Objective
Tempo durability support.

### Workout plan
- 30 min warm-up in Z2
- 2 x 20 min steady tempo
- 8 min easy between efforts
- Stay seated and rhythm-based
- Finish the remaining time in Z2

### Recovery
- Elevate legs after the ride

### Fueling
- 75 g carbohydrate per hour on the bike

### Notes
This is a key ride session.

## Lower-body strength session
- Id: 2026-04-16-lower-body-strength-session
- Title: Lower-body strength session
- Kind: strength
- Discipline: strength
- Surface: gym
- Priority: support
- Planned time: after ride
- Duration: 40-45 min

### Objective
Support force production and strength rhythm without compromising the next day.

### Workout plan
- Trap-bar deadlift 3 x 5 @ 72-77% 1RM, cap at RPE 6-7
- Goblet squat or short-ROM squat 3 x 5-6 @ RPE 6-7
- Romanian deadlift 2 x 6 @ 65-70% 1RM, cap at RPE 6
- Supported split squat 2 x 5 each side @ RPE 5-6 if ankle response remains calm

### Recovery
- If the ankle grumbles during loading, reduce split-squat volume first

### Notes
Primary strength exposure of the week.

Risks to avoid

1. Turning calendar files into mini strategy documents

If future activity files become full of block rationale and coaching philosophy, they will become hard to maintain and harder for tools to revise.

2. Embedding external-system details

If raw integration instructions, publish-state chatter, or sync notes are written directly into the calendar content, the files will become cluttered and brittle.

Durable reference metadata, such as a TrainingPeaks ID, is not the problem by itself. The real risk is storing tool-specific operational instructions instead of stable item data.

3. Over-fragmenting activities

If every warm-up, activation, and mobility item becomes its own activity, the calendar will become noisy and external calendar publishing will be poor.

4. Keeping the format too loose

If each day file is freeform prose, other agents and processes will not be able to revise it safely.

5. Treating archived files as active calendar inputs

If normal calendar readers or writers do not ignore calendar/archives/, archived files may be mistaken for active planning artifacts and create duplicate or stale downstream behavior.

Resolved decisions

  • planned start times are optional by default and should be included only when whoever creates the calendar item chooses to provide one
  • the calendar layer does not decide whether gym sessions, races, travel events, rest days, or other operational items should exist as calendar objects; it only stores them when instructed
  • Markdown is the canonical contract; no separate machine-readable mirror is required by this proposal
  • archived files should retain the same content structure when moved into calendar/archives/; if a same-name file already exists there, the moved file should be renamed with an incremented index such as YYYY-MM-DD-1.md

Recommendation

Adopt the new athlete/calendar/YYYY-MM-DD.md layer as the canonical per-day planning object model.

Implement it with:

  • one daily file per date
  • one or more neutral activities per file
  • fixed Markdown structure with title-based activity headings, explicit Id and Title fields, and stable item IDs when needed
  • no strategy prose, no implementation/process instructions, and no execution logging
  • optional durable reference metadata when needed, including external IDs such as a TrainingPeaks ID

Keep the proposal scoped to the calendar layer itself:

  • how calendar items are structured
  • how they are stored
  • how they are revised
  • how the calendar-manager skill is responsible for adding, editing, deleting, moving, and maintaining them

Do not use this proposal to define who plans the items, who approves them, or what upstream logic decides which items should exist.