Exercise Library Agent Deployment Guide

Instructions for deploying agents to build exercise pages at scale

Overview

This guide ensures consistent, high-quality exercise pages when using agents to build the exercise library. Follow these instructions exactly to avoid MDX parsing errors and maintain template compliance.

Template Structure (12 Sections)

Every exercise page MUST have these 12 sections in this exact order:

YAML Frontmatter (metadata)
MDX Imports
Title + Tagline
⚡ Quick Reference (collapsible, open)
🎯 Setup (collapsible, open)
🔄 Execution (collapsible, open) - with Tabs
💪 Muscles Worked (collapsible, open)
⚠️ Common Mistakes (collapsible, open)
🔀 Variations (collapsible, open) - with Tabs
📊 Programming (collapsible, closed)
🔄 Alternatives & Progressions (collapsible, closed)
🛡️ Safety & Contraindications (collapsible, closed)
🦴 Joints Involved (collapsible, closed)
❓ Common Questions (collapsible, closed)
📚 Sources (collapsible, closed)
:::info For Mo (coaching guidance)
Last updated footer

YAML Frontmatter Requirements

---
title: "Exercise Name"
sidebar_label: "Exercise Name"
description: "One-line description"

# === CATEGORIZATION ===
patterns:
  - pattern-name  # push, pull, hinge, squat, lunge, carry, core

primary_muscles:
  - muscle-1
  - muscle-2

secondary_muscles:
  - muscle-1

stabilizers:
  - muscle-1

# === EQUIPMENT & SETUP ===
equipment:
  - equipment-type  # barbell, dumbbell, kettlebell, bodyweight, machine, cable

equipment_details: "Specific equipment description"

body_position:
  - position  # standing, seated, prone, supine, hanging, bent-over

grip:
  - grip-type  # overhand, underhand, neutral, mixed

grip_width:
  - width  # narrow, shoulder-width, wide, n/a

stance:
  - stance-type  # hip-width, shoulder-width, wide, staggered, n/a

# === MOVEMENT CHARACTERISTICS ===
force_type: push|pull|isometric

plane:
  - sagittal|frontal|transverse

chain: anterior|posterior

kinetic_chain: open|closed

movement_type: compound|isolation

bilateral: true|false

# === CLASSIFICATION ===
exercise_type:
  - strength
  - hypertrophy
  - power
  - endurance
  - stability

difficulty: beginner|intermediate|advanced|elite

priority: essential|common|specialized|niche

# === PROGRAMMING ===
typical_rep_ranges:
  strength: "X-X"
  hypertrophy: "X-X"
  endurance: "X-X+"

typical_sets: "X-X"
rest_period: "Xs-Xs"

# === RELATIONSHIPS ===
joints:
  - joint-name

variations:
  - variation-1
  - variation-2

alternatives:
  - alternative-1

progressions:
  - harder-exercise

regressions:
  - easier-exercise

# === SAFETY ===
injury_considerations:
  - consideration-1

contraindications:
  - condition-1
---

MDX Component Rules

CRITICAL: Avoid These Errors

Error	Wrong	Correct
Wrong tag name	`<invoke value="...">`	`<TabItem value="...">`
Unclosed TabItem	`<TabItem>...</Tabs>`	`<TabItem>...</TabItem></Tabs>`
Missing import	(no import statement)	`import Tabs from '@theme/Tabs';`
Wrong closing	`</Tab>`	`</Tabs>`

Required Imports

Always include at the top after frontmatter:

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Tabs Component Structure

<Tabs>
<TabItem value="unique-id" label="Label Text" default>

Content here...

</TabItem>
<TabItem value="another-id" label="Another Label">

More content...

</TabItem>
</Tabs>

Rules:

First TabItem should have default attribute
Each TabItem needs unique value
Blank line after opening tag
Blank line before closing tag
NEVER use <invoke> - always <TabItem>

Collapsible Sections

<details open>
<summary>

## Section Title

</summary>

Content here...

</details>

Rules:

Use open for sections that should be expanded by default
Omit open for collapsed sections
Blank lines around summary content

Mermaid Diagrams

```mermaid
flowchart LR
    A[Step 1] --> B[Step 2]
    B --> C[Step 3]

**Rules:**
- Use `flowchart LR` for horizontal flow
- Use `flowchart TB` for vertical flow
- Keep node text short (no special characters)
- Avoid quotes in node labels

### Admonitions

```jsx
:::tip[Title]
Content here
:::

:::caution[Title]
Warning content
:::

:::danger[Title]
Critical warning
:::

:::info[Title]
Informational content
:::

Muscle Activation Bars

Use this exact format for muscle activation percentages:

| Muscle | Action | Activation |
|--------|--------|------------|
| [**Muscle Name**](/apply/anatomy/muscles/muscle-slug) | Action description | `█████████░` 90% |

Bar scale:

90-100%: █████████░ or ██████████
80-89%: ████████░░
70-79%: ███████░░░
60-69%: ██████░░░░
50-59%: █████░░░░░
40-49%: ████░░░░░░
30-39%: ███░░░░░░░
20-29%: ██░░░░░░░░
10-19%: █░░░░░░░░░

"For Mo" Section Template

:::info[For Mo]

**When to recommend this exercise:**
- Bullet point 1
- Bullet point 2

**Who should NOT do this exercise:**
- Condition → Alternative suggestion

**Key coaching cues to emphasize:**
1. "Cue 1"
2. "Cue 2"
3. "Cue 3"

**Common issues to watch for in user feedback:**
- "User complaint" → Solution

**Programming guidance:**
- Pair with: Exercise types
- Avoid same day as: Conflicting exercises
- Typical frequency: Xx per week

**Progression signals:**
- Ready to progress when: Criteria
- Regress if: Warning signs

:::

Agent Prompt Template

When deploying an agent to build exercises, use this prompt structure:

Build exercise pages for the [CATEGORY] category.

EXERCISES TO BUILD:
1. exercise-name-1
2. exercise-name-2
[list all exercises]

TEMPLATE FILE:
Use /Users/stumati/Developer/mo/mo-docs/docs/apply/training/exercise-library/back-squat.md as the template.

REQUIREMENTS:
1. Follow the exact template structure (12 sections)
2. Use proper MDX syntax - NEVER use <invoke>, always use <TabItem>
3. Include all YAML frontmatter fields
4. Use proper muscle activation bar format
5. Include comprehensive "For Mo" section
6. Cross-link to related exercises where appropriate

OUTPUT:
Create each file at: /Users/stumati/Developer/mo/mo-docs/docs/apply/training/exercise-library/[exercise-name].md

VALIDATION:
After creating files, verify:
- Equal count of <TabItem> and </TabItem> tags
- Equal count of <Tabs> and </Tabs> tags
- Equal count of <details> and </details> tags
- No <invoke> tags anywhere

Post-Build Validation Script

Run this after each agent batch:

cd /Users/stumati/Developer/mo/mo-docs/docs/apply/training/exercise-library

echo "=== MDX Validation ==="

# Check for invoke tags (ERROR)
if grep -l "<invoke" *.md 2>/dev/null; then
  echo "❌ ERROR: Found <invoke> tags - must be <TabItem>"
else
  echo "✅ No <invoke> tags found"
fi

# Check TabItem balance
echo ""
echo "Checking TabItem balance..."
for file in *.md; do
  if [[ ! "$file" =~ "_" ]]; then
    open=$(grep -c "<TabItem" "$file" 2>/dev/null || echo 0)
    close=$(grep -c "</TabItem>" "$file" 2>/dev/null || echo 0)
    if [ "$open" != "$close" ]; then
      echo "❌ MISMATCH: $file (open: $open, close: $close)"
    fi
  fi
done
echo "✅ TabItem check complete"

# Check Tabs balance
echo ""
echo "Checking Tabs balance..."
for file in *.md; do
  if [[ ! "$file" =~ "_" ]]; then
    open=$(grep -c "<Tabs>" "$file" 2>/dev/null || echo 0)
    close=$(grep -c "</Tabs>" "$file" 2>/dev/null || echo 0)
    if [ "$open" != "$close" ]; then
      echo "❌ MISMATCH: $file (open: $open, close: $close)"
    fi
  fi
done
echo "✅ Tabs check complete"

# Check details balance
echo ""
echo "Checking details balance..."
for file in *.md; do
  if [[ ! "$file" =~ "_" ]]; then
    open=$(grep -c "<details" "$file" 2>/dev/null || echo 0)
    close=$(grep -c "</details>" "$file" 2>/dev/null || echo 0)
    if [ "$open" != "$close" ]; then
      echo "❌ MISMATCH: $file (open: $open, close: $close)"
    fi
  fi
done
echo "✅ Details check complete"

echo ""
echo "=== Validation Complete ==="

Common Pitfalls to Avoid

1. Tag Typos

❌ <invoke> → ✅ <TabItem>
❌ <Tab> → ✅ <Tabs>
❌ </Tab> → ✅ </Tabs>

2. Missing Closing Tags

Always match:

<Tabs> ... </Tabs>
<TabItem> ... </TabItem>
<details> ... </details>
<summary> ... </summary>

3. Angle Brackets in Content

Escape angle brackets in markdown content:

❌ <90 degrees
✅ <90 degrees or less than 90 degrees

4. Special Characters in Mermaid

Avoid in Mermaid node labels:

Quotes: " or '
Parentheses in certain contexts
Special symbols

5. Missing Blank Lines

MDX requires blank lines:

After <TabItem> opening
Before </TabItem> closing
After <summary> content
Before </details>

File Naming Convention

Use lowercase
Use hyphens for spaces
No special characters
Match the exercise name

Examples:

bench-press.md ✅
Bench Press.md ❌
bench_press.md ❌
dumbbell-shoulder-press.md ✅
db-shoulder-press.md ❌ (use full words)

Checklist Before Committing

Example Agent Deployment

Task: Build 7 Pull exercises

Agent Prompt:
"Build these 7 Pull exercise pages following the template at back-squat.md:
1. pull-up
2. chin-up
3. lat-pulldown
4. barbell-row
5. dumbbell-row
6. seated-cable-row
7. face-pull

Each file must have all 12 sections, proper MDX syntax, and comprehensive coaching guidance. CRITICAL: Use <TabItem> not <invoke>."

After Agent Completes:
1. Run validation script
2. Fix any issues
3. Commit and push

Parallel Agent Deployment Strategy

Key insight: Small batches + many parallel agents = high throughput without context overflow

The Problem

When agents try to build too many exercises in a single batch:

Context window fills up
Files become incomplete
Quality degrades
Agents fail mid-task

The Solution: Micro-Batching with Parallelism

Parameter	Value	Rationale
Model	`sonnet`	Better domain expertise, richer coaching cues
Batch size	4 exercises per agent	Proven safe, no context overflow
Parallel agents	25 simultaneous	100 exercises/wave throughput
Grouping	By movement pattern	Keeps context focused, ensures consistency

Why Sonnet (Not Haiku)

Aspect	Sonnet	Haiku
Domain expertise	Uses insider terminology (Spoto press, board press)	More generic descriptions
Coaching cues	Memorable metaphors ("shoulder blades in back pockets")	Functional but simpler
Technical nuance	Richer variations, more specific fixes	Accurate but less detailed
Sources	More specific research citations	Adequate but fewer
Recommendation	✅ Use for all exercises	❌ Avoid for content work

Deployment Pattern

Wave = 15 agents × 4 exercises each = 60 exercises

Agent 1: Push (barbell variations)    → 4 exercises
Agent 2: Push (dumbbell variations)   → 4 exercises
Agent 3: Push (cable variations)      → 4 exercises
Agent 4: Pull (rows)                  → 4 exercises
Agent 5: Pull (pulldowns)             → 4 exercises
Agent 6: Pull (rear delt)             → 4 exercises
Agent 7: Hinge (deadlift variations)  → 4 exercises
Agent 8: Hinge (RDL variations)       → 4 exercises
Agent 9: Squat (barbell)              → 4 exercises
Agent 10: Squat (variations)          → 4 exercises
Agent 11: Lunge (forward/reverse)     → 4 exercises
Agent 12: Lunge (split squat)         → 4 exercises
Agent 13: Core (anti-extension)       → 4 exercises
Agent 14: Core (anti-rotation)        → 4 exercises
Agent 15: Isolation (shoulders)       → 4 exercises

Agent Prompt Template (Micro-Batch)

Build these 4 [PATTERN] exercise pages:

1. exercise-name-1
2. exercise-name-2
3. exercise-name-3
4. exercise-name-4

TEMPLATE: Use back-squat.md as reference

REQUIREMENTS:
- All 13 sections (Quick Reference through For Mo)
- Proper MDX syntax (TabItem, not invoke)
- Complete YAML frontmatter
- Rich coaching cues with memorable metaphors
- Specific troubleshooting for common issues

QUALITY STANDARDS:
- Use domain-specific terminology where appropriate
- Include evocative coaching cues (not generic)
- Cite specific sources when possible
- Write as if for professional trainers

OUTPUT: Create files at /path/to/exercise-library/[name].md

Validation After Each Wave

# Quick section completeness check
for file in *.md; do
  count=0
  for section in "Quick Reference" "Setup" "Execution" "Muscles Worked" \
    "Common Mistakes" "Variations" "Programming" "Alternatives" \
    "Safety" "Joints" "Common Questions" "Sources" "For Mo"; do
    grep -q "$section" "$file" && ((count++))
  done
  if [ "$count" -lt 13 ]; then
    echo "INCOMPLETE: $file ($count/13)"
  fi
done

Workflow Summary

Key Rules

Never use haiku for exercise content
Max 4 exercises per agent to avoid context overflow
Group by pattern for focused, consistent output
Validate before commit - check all 13 sections
Sonnet model for all content generation
Monitor agents - check status every 7-10 minutes or have agents report completion

Agent Monitoring

Two approaches for tracking agent completion:

Option A: Polling (check every 7-10 min)

# Check agent status periodically
Use TaskOutput tool with block=false to check status without waiting

Option B: Completion reporting

# Add to agent prompt:
"When complete, report: DONE - Created [X] files: [list filenames]"

Wait for ALL agents to complete before running validation and committing.

Expected Results

Metric	Target
Exercises per wave	100 (25 agents × 4)
Completion rate	100%
Quality (sections)	13/13
Time per wave	~10-15 minutes

Template Consistency Protocol

Lesson learned: 100 files/wave works, but agents drift on header formatting. Always validate and fix.

The Problem

When deploying 25 parallel agents, each may interpret the template slightly differently:

Some use emoji headers: ## 🎯 Setup
Some use plain headers: ## Setup
Some use alternate names: ## How To Perform vs ## Setup
Some miss emoji in Sources: ## Sources vs ## 📚 Sources

The Solution: 3-Step Protocol

Step 1: Strict Template in Agent Prompt

Include these EXACT headers in every agent prompt:

EXACT SECTION HEADERS (copy these exactly):

## ⚡ Quick Reference
## 🎯 Setup
## 🔄 Execution
## 💪 Muscles Worked
## ⚠️ Common Mistakes
## 🔀 Variations
## 📊 Programming
## 🔄 Alternatives & Progressions
## 🛡️ Safety & Contraindications
## 🦴 Joints Involved
## ❓ Common Questions
## 📚 Sources

Optional extra sections (if relevant):
## 🎁 Benefits
## 🔗 Related Exercises

CRITICAL: Include the emoji in EVERY header. Do NOT use plain text headers.

Step 2: Post-Generation Validation Script

Run this after each wave completes:

#!/bin/bash
DIR="/Users/stumati/Developer/mo/mo-docs/docs/apply/training/exercise-library"
REPO="/Users/stumati/Developer/mo/mo-docs"

echo "=== CONSISTENCY VALIDATION ==="

# Check 1: Plain headers without emojis
echo "1. Checking for plain headers..."
issues=0
for file in "$DIR"/*.md; do
  fname=$(basename "$file")
  if git -C "$REPO" ls-files --error-unmatch "docs/apply/training/exercise-library/$fname" >/dev/null 2>&1; then
    continue  # Skip committed files
  fi

  if grep -qE "^## (Quick Reference|Setup|Execution|Muscles Worked|Common Mistakes|Variations|Programming|Alternatives & Progressions|Safety & Contraindications|Joints Involved|Common Questions|Sources|Benefits|Related Exercises)$" "$file"; then
    echo "  PLAIN HEADERS: $fname"
    issues=$((issues + 1))
  fi
done
echo "  Files with plain headers: $issues"

# Check 2: For Mo section
echo ""
echo "2. Checking For Mo sections..."
missing=0
for file in "$DIR"/*.md; do
  fname=$(basename "$file")
  if git -C "$REPO" ls-files --error-unmatch "docs/apply/training/exercise-library/$fname" >/dev/null 2>&1; then
    continue
  fi
  if ! grep -q "For Mo" "$file"; then
    echo "  MISSING For Mo: $fname"
    missing=$((missing + 1))
  fi
done
echo "  Files missing For Mo: $missing"

# Check 3: Proper file endings
echo ""
echo "3. Checking file endings..."
bad=0
for file in "$DIR"/*.md; do
  fname=$(basename "$file")
  if git -C "$REPO" ls-files --error-unmatch "docs/apply/training/exercise-library/$fname" >/dev/null 2>&1; then
    continue
  fi
  lastline=$(tail -1 "$file" | tr -d '\n')
  if [[ ! "$lastline" =~ "Last updated" ]] && [[ "$lastline" != "" ]]; then
    echo "  BAD ENDING: $fname"
    bad=$((bad + 1))
  fi
done
echo "  Files with bad endings: $bad"

echo ""
if [[ $issues -eq 0 ]] && [[ $missing -eq 0 ]] && [[ $bad -eq 0 ]]; then
  echo "✅ ALL CHECKS PASSED"
else
  echo "❌ ISSUES FOUND - Run fix script"
fi

Step 3: Quick Fix Script (~5 minutes)

If validation finds issues, run this sed script:

#!/bin/bash
DIR="/Users/stumati/Developer/mo/mo-docs/docs/apply/training/exercise-library"
REPO="/Users/stumati/Developer/mo/mo-docs"

echo "=== FIXING HEADER INCONSISTENCIES ==="

for file in "$DIR"/*.md; do
  fname=$(basename "$file")

  # Skip committed files
  if git -C "$REPO" ls-files --error-unmatch "docs/apply/training/exercise-library/$fname" >/dev/null 2>&1; then
    continue
  fi

  # Add emojis to plain headers
  sed -i '' 's/^## Quick Reference$/## ⚡ Quick Reference/' "$file"
  sed -i '' 's/^## Setup$/## 🎯 Setup/' "$file"
  sed -i '' 's/^## Execution$/## 🔄 Execution/' "$file"
  sed -i '' 's/^## Muscles Worked$/## 💪 Muscles Worked/' "$file"
  sed -i '' 's/^## Common Mistakes$/## ⚠️ Common Mistakes/' "$file"
  sed -i '' 's/^## Variations$/## 🔀 Variations/' "$file"
  sed -i '' 's/^## Programming$/## 📊 Programming/' "$file"
  sed -i '' 's/^## Alternatives & Progressions$/## 🔄 Alternatives \& Progressions/' "$file"
  sed -i '' 's/^## Safety & Contraindications$/## 🛡️ Safety \& Contraindications/' "$file"
  sed -i '' 's/^## Joints Involved$/## 🦴 Joints Involved/' "$file"
  sed -i '' 's/^## Common Questions$/## ❓ Common Questions/' "$file"
  sed -i '' 's/^## Sources$/## 📚 Sources/' "$file"
  sed -i '' 's/^## Benefits$/## 🎁 Benefits/' "$file"
  sed -i '' 's/^## Related Exercises$/## 🔗 Related Exercises/' "$file"

  # Fix alternate section names
  sed -i '' 's/^## 🎯 How To Perform$/## 🎯 Setup \& Execution/' "$file"
  sed -i '' 's/^## 🔀 Variations & Modifications$/## 🔀 Variations/' "$file"
  sed -i '' 's/^## 📊 Programming Recommendations$/## 📊 Programming/' "$file"
  sed -i '' 's/^## 🛡️ Safety Considerations$/## 🛡️ Safety \& Contraindications/' "$file"
  sed -i '' 's/^## 🔄 Related Exercises$/## 🔗 Related Exercises/' "$file"
  sed -i '' 's/^## ❓ FAQ$/## ❓ Common Questions/' "$file"
done

echo "✅ Headers fixed - re-run validation to confirm"

Summary

Step	When	Time
1. Strict template	Before deploying agents	0 min (in prompt)
2. Validation script	After agents complete	1 min
3. Fix script	If issues found	5 min

Total overhead: ~6 minutes per 100-file wave

This ensures:

✅ 100 files/wave throughput maintained
✅ Consistent emoji headers across all files
✅ Quick automated fixes for any drift
✅ No manual editing required

Last updated: December 2024

Overview​

Template Structure (12 Sections)​

YAML Frontmatter Requirements​

MDX Component Rules​

CRITICAL: Avoid These Errors​

Required Imports​

Tabs Component Structure​

Collapsible Sections​

Mermaid Diagrams​

Muscle Activation Bars​

"For Mo" Section Template​

Agent Prompt Template​

Post-Build Validation Script​

Common Pitfalls to Avoid​

1. Tag Typos​

2. Missing Closing Tags​

3. Angle Brackets in Content​

4. Special Characters in Mermaid​

5. Missing Blank Lines​

File Naming Convention​

Checklist Before Committing​

Example Agent Deployment​

Parallel Agent Deployment Strategy​

The Problem​

The Solution: Micro-Batching with Parallelism​

Why Sonnet (Not Haiku)​

Deployment Pattern​

Agent Prompt Template (Micro-Batch)​

Validation After Each Wave​

Workflow Summary​

Key Rules​

Agent Monitoring​

Expected Results​

Template Consistency Protocol​

The Problem​

The Solution: 3-Step Protocol​

Step 1: Strict Template in Agent Prompt​

Step 2: Post-Generation Validation Script​

Step 3: Quick Fix Script (~5 minutes)​

Summary​

Overview

Template Structure (12 Sections)

YAML Frontmatter Requirements

MDX Component Rules

CRITICAL: Avoid These Errors

Required Imports

Tabs Component Structure

Collapsible Sections

Mermaid Diagrams

Muscle Activation Bars

"For Mo" Section Template

Agent Prompt Template

Post-Build Validation Script

Common Pitfalls to Avoid

1. Tag Typos

2. Missing Closing Tags

3. Angle Brackets in Content

4. Special Characters in Mermaid

5. Missing Blank Lines

File Naming Convention

Checklist Before Committing

Example Agent Deployment

Parallel Agent Deployment Strategy

The Problem

The Solution: Micro-Batching with Parallelism

Why Sonnet (Not Haiku)

Deployment Pattern

Agent Prompt Template (Micro-Batch)

Validation After Each Wave

Workflow Summary

Key Rules

Agent Monitoring

Expected Results

Template Consistency Protocol

The Problem

The Solution: 3-Step Protocol

Step 1: Strict Template in Agent Prompt

Step 2: Post-Generation Validation Script

Step 3: Quick Fix Script (~5 minutes)

Summary