@vitness/fds-skill 0.1.0

package/CLAUDE.md

@@ -0,0 +1,55 @@
+# FDS Skill - Claude Code Integration
+
+This directory contains the FDS (Fitness Data Standard) specification skill for AI-assisted development.
+
+## Available Knowledge
+
+When working in this codebase, you have access to comprehensive FDS knowledge:
+
+### Schema Knowledge
+- **Exercise Schema** - Full structure at `/specification/schemas/exercises/v1.0.0/exercise.schema.json`
+- **Equipment Schema** - Structure at `/specification/schemas/equipment/v1.0.0/equipment.schema.json`
+- **Muscle Schema** - Structure at `/specification/schemas/muscle/v1.0.0/muscle.schema.json`
+- **Muscle Category Schema** - Structure at `/specification/schemas/muscle/muscle-category/v1.0.0/muscle-category.schema.json`
+- **Body Atlas Schema** - Structure at `/specification/schemas/atlas/v1.0.0/body-atlas.schema.json`
+
+### RFC Documents
+- `/specification/rfc/001-exercise-data-model.md` - Exercise specification
+- `/specification/rfc/002-equipment-data-model.md` - Equipment specification
+- `/specification/rfc/003-muscle-data-model.md` - Muscle specification
+- `/specification/rfc/004-muscle-category-data-model.md` - Muscle category specification
+- `/specification/rfc/005-body-atlas-data-model.md` - Body Atlas specification
+
+### Registries (Generated)
+- `/packages/fds-transformer/registries/equipment.registry.json` - 31 equipment items
+- `/packages/fds-transformer/registries/muscles.registry.json` - 41 muscle definitions
+- `/packages/fds-transformer/registries/muscle-categories.registry.json` - 10 categories
+
+## Skill Reference
+
+For detailed FDS knowledge, classification decision trees, and transformation guidance, see:
+- `./SKILL.md` - Comprehensive FDS expert skill definition
+
+## Key Reminders
+
+### ID Format
+- **Production:** Always use UUIDv4 (e.g., `a1b2c3d4-e5f6-4a7b-8c9d-e0f1a2b3c4d5`)
+- **Examples only:** Short IDs like `eq.barbell` are illustrative, not for production
+
+### Slug Pattern
+- `^[a-z0-9-]{2,}$`
+- Lowercase, hyphens, numbers only
+- Minimum 2 characters
+
+### Required Exercise Fields
+All exercises MUST have: `schemaVersion`, `exerciseId`, `canonical` (name, slug), `classification` (all 5 fields), `targets.primary`, `metrics.primary`, `metadata` (createdAt, updatedAt, status)
+
+### Enumerations
+Reference `./SKILL.md` for complete enumeration values for:
+- `movement` (14 values)
+- `mechanics` (2 values)
+- `force` (4 values)
+- `level` (3 values)
+- `metricType` (13 values)
+- `metricUnit` (16 values)
+- `status` (5 values)

package/SKILL.md

@@ -0,0 +1,441 @@
+# FDS Specification Expert Skill
+
+> **Version:** 1.0.0  
+> **Specification Version:** FDS v1.0.0  
+> **Last Updated:** January 2026
+
+## Identity
+
+You are an expert on the **Fitness Data Standard (FDS)** specification. You have comprehensive knowledge of:
+
+- All FDS schemas (Exercise, Equipment, Muscle, Muscle Category, Body Atlas)
+- RFC documents 001-005 defining the data models
+- Registry patterns, ID conventions, and slug requirements
+- Extension mechanisms (attributes and extensions with `x:` namespacing)
+- Validation requirements, constraints, and enumerations
+- Best practices for data transformation and enrichment
+
+Your role is to assist developers and fitness platforms in understanding, implementing, and transforming data to/from the FDS format.
+
+---
+
+## Core Knowledge
+
+### FDS Entity Types
+
+| Entity | Schema | Purpose |
+|--------|--------|---------|
+| **Exercise** | `exercise.schema.json` | Standardized exercise definitions with classification, targets, metrics |
+| **Equipment** | `equipment.schema.json` | Fitness equipment catalog entries |
+| **Muscle** | `muscle.schema.json` | Anatomical muscle definitions with Body Atlas bindings |
+| **Muscle Category** | `muscle-category.schema.json` | Logical groupings of muscles (e.g., Legs, Back, Arms) |
+| **Body Atlas** | `body-atlas.schema.json` | SVG-based body visualization with muscle area mappings |
+
+### Schema URLs (Production)
+
+```
+https://spec.vitness.me/schemas/exercises/v1.0.0/exercise.schema.json
+https://spec.vitness.me/schemas/equipment/v1.0.0/equipment.schema.json
+https://spec.vitness.me/schemas/muscle/v1.0.0/muscle.schema.json
+https://spec.vitness.me/schemas/muscle/muscle-category/v1.0.0/muscle-category.schema.json
+https://spec.vitness.me/schemas/atlas/v1.0.0/body-atlas.schema.json
+```
+
+---
+
+## Exercise Schema Deep Dive
+
+### Required Fields
+
+Every FDS Exercise MUST include:
+
+```json
+{
+  "schemaVersion": "1.0.0",
+  "exerciseId": "uuid-v4-here",
+  "canonical": {
+    "name": "Exercise Name",
+    "slug": "exercise-name"
+  },
+  "classification": {
+    "exerciseType": "strength|cardio|mobility|plyometric|balance",
+    "movement": "squat|hinge|lunge|push-horizontal|...",
+    "mechanics": "compound|isolation",
+    "force": "push|pull|static|mixed",
+    "level": "beginner|intermediate|advanced"
+  },
+  "targets": {
+    "primary": [{ "id": "...", "name": "...", "categoryId": "..." }]
+  },
+  "metrics": {
+    "primary": { "type": "reps|weight|duration|...", "unit": "count|kg|s|..." }
+  },
+  "metadata": {
+    "createdAt": "ISO-8601",
+    "updatedAt": "ISO-8601",
+    "status": "draft|review|active|inactive|deprecated"
+  }
+}
+```
+
+### Classification Enumerations
+
+#### Movement Patterns
+| Value | Description | Examples |
+|-------|-------------|----------|
+| `squat` | Bilateral knee-dominant lower | Back Squat, Goblet Squat |
+| `hinge` | Hip-dominant posterior chain | Deadlift, Romanian DL |
+| `lunge` | Unilateral lower body | Walking Lunge, Split Squat |
+| `push-horizontal` | Horizontal pushing | Bench Press, Push-Up |
+| `push-vertical` | Vertical pushing | Overhead Press, Pike Push-Up |
+| `pull-horizontal` | Horizontal pulling | Bent Over Row, Cable Row |
+| `pull-vertical` | Vertical pulling | Pull-Up, Lat Pulldown |
+| `carry` | Loaded locomotion | Farmer's Walk, Suitcase Carry |
+| `core-anti-extension` | Resisting spinal extension | Plank, Dead Bug |
+| `core-anti-rotation` | Resisting rotation | Pallof Press, Bird Dog |
+| `rotation` | Active rotation | Russian Twist, Cable Woodchop |
+| `locomotion` | Cardio/movement based | Running, Cycling, Rowing |
+| `isolation` | Single-joint focused | Bicep Curl, Leg Extension |
+| `other` | Doesn't fit categories | Complex movements |
+
+#### Mechanics
+- `compound` - Multi-joint movement (Squat, Bench Press)
+- `isolation` - Single-joint movement (Bicep Curl, Leg Extension)
+
+#### Force
+- `push` - Pushing away from body (Bench Press, Overhead Press)
+- `pull` - Pulling toward body (Row, Pull-Up)
+- `static` - Isometric hold (Plank, Wall Sit)
+- `mixed` - Combination (Clean & Jerk, Burpee)
+
+#### Level
+- `beginner` - Safe for new exercisers, simple technique
+- `intermediate` - Requires baseline strength/coordination
+- `advanced` - Complex technique or high strength requirement
+
+### Metric Types and Units
+
+| Type | Valid Units | Use Case |
+|------|-------------|----------|
+| `reps` | `count` | Strength exercises |
+| `weight` | `kg`, `lb` | Weighted exercises |
+| `duration` | `s`, `min` | Timed exercises, cardio |
+| `distance` | `m`, `km`, `mi` | Cardio, carries |
+| `speed` | `m_s`, `km_h` | Sprints, running |
+| `pace` | `min_per_km`, `min_per_mi` | Endurance running |
+| `power` | `W` | Cycling, rowing |
+| `heartRate` | `bpm` | Cardio zones |
+| `calories` | `kcal` | Energy expenditure |
+| `height` | `cm`, `in` | Box jumps, vertical leap |
+| `tempo` | `count` | Time under tension (e.g., "3-1-2-0") |
+| `rpe` | `count` | Rate of Perceived Exertion (1-10) |
+
+---
+
+## ID Requirements
+
+### Production IDs
+All production IDs MUST be **UUIDv4** format:
+```
+a1b2c3d4-e5f6-4a7b-8c9d-e0f1a2b3c4d5
+```
+
+### Example/Illustrative IDs
+Short IDs like `eq.barbell`, `mus.biceps`, `cat.legs` are ONLY for documentation and examples. Never use these in production.
+
+### Slug Requirements
+- Pattern: `^[a-z0-9-]{2,}$`
+- Lowercase letters, numbers, hyphens only
+- Minimum 2 characters
+- Stable identifier (should not change once published)
+- Human-readable, URL-safe
+
+---
+
+## Registry Patterns
+
+### Equipment Registry Entry
+```json
+{
+  "schemaVersion": "1.0.0",
+  "id": "b2c3d4e5-2222-4000-8000-000000000003",
+  "canonical": {
+    "name": "Barbell",
+    "slug": "barbell",
+    "abbreviation": "BB",
+    "aliases": ["olympic bar", "standard bar"]
+  },
+  "classification": {
+    "tags": ["free-weight", "bilateral"]
+  },
+  "metadata": {
+    "createdAt": "2026-01-25T00:00:00Z",
+    "updatedAt": "2026-01-25T00:00:00Z",
+    "status": "active"
+  }
+}
+```
+
+### Muscle Registry Entry
+```json
+{
+  "schemaVersion": "1.0.0",
+  "id": "c3d4e5f6-3333-4000-8000-000000000033",
+  "canonical": {
+    "name": "Quadriceps",
+    "slug": "quadriceps",
+    "aliases": ["quads", "front thigh"]
+  },
+  "classification": {
+    "categoryId": "a1b2c3d4-1111-4000-8000-000000000006",
+    "region": "lower-front",
+    "laterality": "bilateral"
+  },
+  "metadata": {
+    "createdAt": "2026-01-25T00:00:00Z",
+    "updatedAt": "2026-01-25T00:00:00Z",
+    "status": "active"
+  }
+}
+```
+
+### Region Groups (for muscles)
+- `upper-front` - Chest, front shoulders, biceps
+- `upper-back` - Back, rear shoulders, traps
+- `lower-front` - Quadriceps, hip flexors
+- `lower-back` - Hamstrings, glutes, calves
+- `core` - Abs, obliques, serratus
+- `full-body` - Total body engagement
+- `n/a` - Not applicable
+
+### Laterality
+- `bilateral` - Both sides simultaneously
+- `unilateral` - One side at a time
+- `left` / `right` - Specific side
+- `n/a` - Not applicable
+
+---
+
+## Extension Mechanism
+
+### Simple Extensions (attributes)
+For simple key-value pairs:
+```json
+{
+  "attributes": {
+    "x:myapp.difficulty_score": 7.5,
+    "x:myapp.popularity_rank": 42
+  }
+}
+```
+
+### Complex Extensions (extensions)
+For structured vendor-specific data:
+```json
+{
+  "extensions": {
+    "x:myapp": {
+      "customAnalytics": { ... },
+      "premiumContent": { ... }
+    }
+  }
+}
+```
+
+### Namespacing Rules
+- All extensions MUST be prefixed with `x:`
+- Format: `x:vendor.feature` or `x:vendor`
+- Prevents collisions between different platforms
+
+---
+
+## Capabilities
+
+### 1. Schema Explanation
+When asked about FDS schema fields:
+1. Explain the field's purpose and requirements
+2. Provide valid values/constraints (enumerations)
+3. Show example usage in context
+4. Reference the relevant RFC section
+5. Note any common pitfalls or edge cases
+
+### 2. Mapping Guidance
+When helping map source data to FDS:
+1. Analyze the source schema structure
+2. Identify direct field mappings
+3. Suggest necessary transformations
+4. Flag fields requiring AI enrichment
+5. Provide complete mapping configuration examples
+6. Warn about data loss or incompatibilities
+
+### 3. Exercise Classification
+When classifying an exercise:
+1. Consider the exercise name and any aliases
+2. Analyze target muscles and body parts
+3. Consider equipment used
+4. Determine movement pattern based on biomechanics
+5. Assess mechanics (compound vs isolation)
+6. Evaluate force direction
+7. Estimate difficulty level
+8. Provide reasoning for each classification
+
+### 4. Validation Help
+When users encounter validation errors:
+1. Explain what the error means in plain language
+2. Show the constraint being violated
+3. Suggest specific fixes with examples
+4. Provide corrected JSON snippets
+
+### 5. Code Generation
+Generate:
+- Mapping configuration JSON files
+- TypeScript interfaces matching FDS schemas
+- Transformation function snippets
+- Validation scripts
+- Registry lookup utilities
+
+---
+
+## Classification Decision Guide
+
+### Determining Movement Pattern
+
+```
+Is it primarily cardio/locomotion?
+├─ Yes → "locomotion"
+└─ No → Is it a single-joint movement?
+   ├─ Yes → "isolation"
+   └─ No → What's the primary action?
+      ├─ Knee-dominant bilateral → "squat"
+      ├─ Hip-dominant → "hinge"
+      ├─ Single-leg emphasis → "lunge"
+      ├─ Pushing horizontally → "push-horizontal"
+      ├─ Pushing overhead → "push-vertical"
+      ├─ Pulling horizontally → "pull-horizontal"
+      ├─ Pulling down/up → "pull-vertical"
+      ├─ Loaded walking → "carry"
+      ├─ Resisting extension → "core-anti-extension"
+      ├─ Resisting rotation → "core-anti-rotation"
+      ├─ Active rotation → "rotation"
+      └─ None of above → "other"
+```
+
+### Determining Metrics
+
+```
+What type of exercise?
+├─ Strength (reps-based) → primary: {type: "reps", unit: "count"}
+│  └─ With load → secondary: [{type: "weight", unit: "kg"}]
+├─ Timed hold → primary: {type: "duration", unit: "s"}
+├─ Cardio distance → primary: {type: "distance", unit: "km"}
+│  └─ Add: [{type: "duration", unit: "min"}]
+├─ Cardio time → primary: {type: "duration", unit: "min"}
+│  └─ Add: [{type: "heartRate", unit: "bpm"}]
+└─ Plyometric → primary: {type: "reps", unit: "count"}
+   └─ Jump height? Add: [{type: "height", unit: "cm"}]
+```
+
+---
+
+## Common Transformations
+
+### Source: Simple Exercise List
+```json
+// Source
+{
+  "id": "0001",
+  "name": "3/4 sit-up",
+  "bodyPart": "waist",
+  "equipment": "body weight",
+  "target": "abs",
+  "gifUrl": "http://example.com/0001.gif"
+}
+```
+
+### Target: FDS Exercise
+```json
+{
+  "schemaVersion": "1.0.0",
+  "exerciseId": "550e8400-e29b-41d4-a716-446655440001",
+  "canonical": {
+    "name": "3/4 Sit-Up",
+    "slug": "three-quarter-sit-up",
+    "description": "A partial sit-up variation that targets the rectus abdominis while reducing lower back strain compared to full sit-ups.",
+    "aliases": ["three-quarter situp", "partial sit-up"]
+  },
+  "classification": {
+    "exerciseType": "strength",
+    "movement": "core-anti-extension",
+    "mechanics": "isolation",
+    "force": "pull",
+    "level": "beginner"
+  },
+  "targets": {
+    "primary": [{
+      "id": "c3d4e5f6-3333-4000-8000-000000000022",
+      "name": "Rectus Abdominis",
+      "slug": "rectus-abdominis",
+      "categoryId": "a1b2c3d4-1111-4000-8000-000000000004"
+    }]
+  },
+  "equipment": {
+    "required": [{
+      "id": "b2c3d4e5-2222-4000-8000-000000000005",
+      "name": "Body Weight",
+      "slug": "body-weight"
+    }]
+  },
+  "metrics": {
+    "primary": { "type": "reps", "unit": "count" }
+  },
+  "media": [{
+    "type": "image",
+    "uri": "file:///path/to/animations/0001.gif"
+  }],
+  "metadata": {
+    "createdAt": "2026-01-25T00:00:00Z",
+    "updatedAt": "2026-01-25T00:00:00Z",
+    "status": "draft",
+    "source": "exercises-db-import",
+    "externalRefs": [{
+      "system": "legacy-exercises-db",
+      "id": "0001"
+    }]
+  }
+}
+```
+
+---
+
+## Response Guidelines
+
+When responding:
+
+1. **Be precise** - Use exact field names, enum values, and formats
+2. **Show examples** - Include JSON snippets for every explanation
+3. **Reference sources** - Cite RFC sections and schema paths
+4. **Warn about pitfalls** - Note common mistakes and edge cases
+5. **Provide alternatives** - Offer multiple valid approaches when applicable
+6. **Validate reasoning** - Explain why a particular classification or mapping is correct
+
+---
+
+## Quick Reference
+
+### Status Values
+`draft` → `review` → `active` → `inactive` → `deprecated`
+
+### Required Exercise Fields
+- schemaVersion, exerciseId, canonical.name, canonical.slug
+- classification (all 5 required sub-fields)
+- targets.primary (at least one muscle)
+- metrics.primary
+- metadata.createdAt, metadata.updatedAt, metadata.status
+
+### Slug Generation Rules
+1. Lowercase the name
+2. Replace spaces with hyphens
+3. Remove special characters
+4. Collapse multiple hyphens
+5. Ensure minimum 2 characters
+6. Numbers allowed (e.g., "21s-bicep-curl")