Contribution Guide

The Open Activity Library is community-driven. There are several ways to contribute, from simple feedback votes to full exercise submissions.

Ways to Contribute

Chat with AI

Easiest

Ask the AI chat to create an exercise. It will draft a complete exercise with all metadata and route it through the review engine automatically.

1.Open the dashboard and use the AI chat
2.Describe the exercise you want to add
3.AI creates a draft with muscles, equipment, instructions, etc.
4.Review the draft and approve it
5.The exercise enters the library through the review pipeline

Suggest Edits

Easy

Found an issue with an existing exercise? Use the "Suggest Edit" button in the activity viewer to propose changes.

1.Open any exercise in the Activity Viewer
2.Click the lightbulb icon to open the suggestion modal
3.Select the fields you want to change
4.Provide your corrections and reasoning
5.The AI reviews your suggestion and applies if valid

YAML Edit & Paste

Intermediate

For power users. View the raw YAML of any exercise, copy it, edit in your preferred editor, and paste it back. The system computes the diff and routes changes through review.

1.Open any exercise in the Activity Viewer
2.Click the code icon to open the YAML viewer
3.Click "Copy" to copy the YAML to your clipboard
4.Edit the YAML in any text editor (VS Code, Vim, etc.)
5.Click "Edit & Suggest" and paste your modified YAML
6.Click "Submit Changes" — the system diffs and reviews

Validate Exercises

Easiest

No writing needed. When you encounter exercises with "pending validation" status, you'll see a subtle card asking if the data looks accurate. A quick thumbs up or down helps the library.

1.Browse exercises normally in the app
2.Look for amber feedback cards on pending exercises
3.Click thumbs up if the exercise data looks accurate
4.Click thumbs down if something seems wrong
5.Your feedback contributes to the confidence score

YAML Format Example

When using the YAML editor, exercises follow this format. Not all fields are required.

name: Nordic Hamstring Curl
description: >-
  Eccentric hamstring exercise. Kneel on a pad, lock ankles,
  lower your body forward under control using hamstring tension.
experienceLevelRecommended: intermediate
primaryMuscles:
  - hamstrings
secondaryMuscles:
  - glutes
  - core
equipment:
  - nordic curl bench
tags:
  - eccentric
  - injury prevention
  - posterior chain
modality: resistance
metValue: 4.5
unilateral: false
trackableMetrics:
  - key: reps
    label: Reps
    unit: count
    isPrimary: true
    category: movement
defaults:
  sets: 3
  reps: 6
instructions:
  - Kneel on a pad with ankles secured
  - Cross arms over chest or extend forward
  - Slowly lower torso toward the ground using hamstring control
  - Catch yourself with hands at the bottom
  - Push off hands and use hamstrings to return to start
safetyNotes: >-
  Start with partial range of motion. This exercise places high
  eccentric load on hamstrings — build up volume gradually.

Field Reference

Field	Req	Description
name	yes	Exercise name. Unique within the library.
description	yes	Clear description of the exercise movement.
primaryMuscles	yes	Array of primary muscle groups targeted.
secondaryMuscles	no	Array of secondary/stabilizer muscles.
equipment	yes	Array of required equipment. Use "bodyweight" if none.
tags	no	Categorization tags (compound, isolation, plyometric, etc.).
experienceLevelRecommended	no	beginner, intermediate, or advanced.
modality	no	resistance, cardio, flexibility, etc.
metValue	no	Metabolic equivalent. Used for calorie estimation.
unilateral	no	true if exercise is performed one side at a time.
trackableMetrics	yes	Array of metrics users can log (reps, weight, duration, etc.).
defaults	yes	Default values for sets, reps, weight, rest, etc.
instructions	no	Step-by-step instructions array.
safetyNotes	no	Safety warnings and precautions.
muscleActivationMap	no	Muscle → activation level mapping (0-100).

Submission Guidelines

✓

Be specific — "Targets the long head of the triceps" is better than "works arms"

✓

Use standard names — Check existing library entries for naming conventions

✓

Include safety notes — Especially for advanced or high-risk exercises

✓

Cite sources — Research papers, certified trainer resources, or anatomy references increase confidence

✗

Don't submit duplicates — Search the library first. The AI checks too, but save everyone time

✗

Don't guess anatomy — If you're unsure about muscle groups, leave them out. The AI will fill in or flag

Attribution

All contributions are tracked in the exercise's provenance record. Your user ID is added to the contributors list with the type of contribution (created, edited, reviewed) and timestamp. This data is visible on each exercise and exported to the public git repository.