`workout.md` — the routine format

A routine is plain markdown. It reads fine on screen, prints on a gym clipboard, and parses cleanly back into tensr. Four properties on purpose: machine readable, human readable, printable, and useful by itself.

Minimal example

---
title: Upper Hypertrophy — Push
---

# Day A

## Barbell Bench Press: 4x6-8 rest:150

## Incline Dumbbell Press: 3x8-12 rest:90

## Cable Crossover: 3x12-15 rest:60

Grammar

Piece	Shape	Notes
Frontmatter	`--- … ---`	YAML. `title` is optional (untitled routines get Finder-style numbering).
Day	`# Day A` / `# Mon` / `# Push`	One `#` heading per training day. Omit entirely for a single-workout routine. Labels like `Mon` or `Push` carry across to every surface.
Movement	`## Name: SETSxREPS`	An `h2` per movement. The name resolves against the open movement catalog (or stays a custom name).
Prescription	`4x8` · `3x8-12`	`SETS x REPS`. Reps may be a single number or a range. Never invent a prescription the source doesn't state.
Rest	`rest:90`	Optional, seconds, after the prescription.
Notes / cues	plain text under a movement	Free prose (e.g. `per leg`, form cues) is preserved as movement notes.

Supersets & multi-day

Superset notation (e.g. 4a/4b pairs) is preserved from the source. A multi-day split is just multiple # day sections in one file; a single workout omits the day headings and lists movements directly.

Provenance (catalog entries)

Routines curated into the open catalog carry mandatory attribution in frontmatter — source_author and source_url — so a program's origin travels with the file:

---
version: 0.1
title: Cable A/B Split (curated)
source_author: Jane Coach
source_url: https://example.com/cable-program
---

For agents

When a model proposes a program, it should emit exactly this format so the user can import it directly, and prefer catalog movement names it can confirm exist. A forthcoming workoutmd CLI validates a file against this spec with agent-legible error messages (which line, which rule, how to fix). Until then, the grammar above is the contract.