> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kynasmith.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# MoveSpec YAML reference

> Complete reference for the MoveSpec YAML schema with annotated examples.

# MoveSpec YAML reference

MoveSpec definitions are authored in YAML. This page documents the schema structure with well-commented examples covering all available features.

## Minimal example

The simplest valid MoveSpec defines a single movement with two phases:

```yaml theme={null}
# Every MoveSpec starts with a name and version.
name: squat
version: "1.0"

# The detection block defines what movements to detect.
detection:
  type: repetition          # Count repeated movement cycles.
  movement:
    name: squat
    phases:
      - name: standing      # Starting position.
        criteria:
          - joint: knee
            angle_min: 160
            angle_max: 180
      - name: bottom        # Bottom of the squat.
        criteria:
          - joint: knee
            angle_min: 60
            angle_max: 100
    sequence:               # The phase order that defines one repetition.
      - standing
      - bottom
      - standing
```

## Full-featured example

This example demonstrates all supported schema features:

```yaml theme={null}
# Top-level metadata
name: workout-combo
version: "1.0"
description: "Detect a squat-to-lunge combination with feedback cues."

# Detection configuration
detection:
  type: repetition
  movement:
    name: squat-lunge-combo

    # Phases define the discrete positions in the movement.
    phases:
      - name: standing
        description: "Upright standing position"
        criteria:
          - joint: knee
            angle_min: 160
            angle_max: 180
          - joint: hip
            angle_min: 160
            angle_max: 180

      - name: squat-bottom
        description: "Bottom of squat — knees at roughly 90 degrees"
        criteria:
          - joint: knee
            angle_min: 70
            angle_max: 110
          - joint: hip
            angle_min: 70
            angle_max: 110

      - name: lunge-bottom
        description: "Bottom of lunge — front knee bent, back leg extended"
        criteria:
          - joint: knee
            side: front
            angle_min: 70
            angle_max: 100
          - joint: knee
            side: back
            angle_min: 150
            angle_max: 180

    # Sequence defines the phase ordering for one complete repetition.
    sequence:
      - standing
      - squat-bottom
      - standing
      - lunge-bottom
      - standing

    # Feedback cues emitted during detection.
    feedback:
      - trigger: squat-bottom
        cue: "Good depth — hold briefly"
      - trigger: lunge-bottom
        cue: "Keep your back knee extended"

    # Timing constraints (optional).
    timing:
      min_phase_duration_ms: 200   # Ignore phases shorter than 200ms (likely noise).
      max_phase_duration_ms: 5000  # Fail phases longer than 5 seconds.

    # Confidence thresholds (optional).
    thresholds:
      min_landmark_confidence: 0.5  # Ignore frames below this landmark confidence.
```

## Schema reference

### Top-level fields

| Field         | Type   | Required | Description                                   |
| ------------- | ------ | -------- | --------------------------------------------- |
| `name`        | string | Yes      | Human-readable name for the MoveSpec.         |
| `version`     | string | Yes      | Schema version string (e.g., `"1.0"`).        |
| `description` | string | No       | Optional description of the MoveSpec purpose. |
| `detection`   | object | Yes      | The detection configuration block.            |

### `detection` object

| Field      | Type   | Required | Description                                                                     |
| ---------- | ------ | -------- | ------------------------------------------------------------------------------- |
| `type`     | string | Yes      | Detection mode. Currently `"repetition"` for counting repeated movement cycles. |
| `movement` | object | Yes      | The movement definition.                                                        |

### `movement` object

| Field        | Type   | Required | Description                                                |
| ------------ | ------ | -------- | ---------------------------------------------------------- |
| `name`       | string | Yes      | Identifier for the movement being detected.                |
| `phases`     | array  | Yes      | List of phase definitions that make up the movement.       |
| `sequence`   | array  | Yes      | Ordered list of phase names defining one repetition cycle. |
| `feedback`   | array  | No       | Optional feedback cues to emit during detection.           |
| `timing`     | object | No       | Optional timing constraints for phase transitions.         |
| `thresholds` | object | No       | Optional confidence thresholds for frame filtering.        |

### `phase` object

| Field         | Type   | Required | Description                                         |
| ------------- | ------ | -------- | --------------------------------------------------- |
| `name`        | string | Yes      | Unique name for this phase within the movement.     |
| `description` | string | No       | Human-readable description of the phase.            |
| `criteria`    | array  | Yes      | List of joint-angle criteria that define the phase. |

### `criteria` object

| Field       | Type   | Required | Description                                                                               |
| ----------- | ------ | -------- | ----------------------------------------------------------------------------------------- |
| `joint`     | string | Yes      | The joint to evaluate (e.g., `"knee"`, `"hip"`, `"elbow"`, `"shoulder"`).                 |
| `angle_min` | number | Yes      | Minimum joint angle in degrees (0-180).                                                   |
| `angle_max` | number | Yes      | Maximum joint angle in degrees (0-180).                                                   |
| `side`      | string | No       | Which side to evaluate: `"front"`, `"back"`, `"left"`, `"right"`. Defaults to both sides. |

### `feedback` object

| Field     | Type   | Required | Description                                 |
| --------- | ------ | -------- | ------------------------------------------- |
| `trigger` | string | Yes      | Phase name that triggers this feedback cue. |
| `cue`     | string | Yes      | The feedback message to emit.               |

### `timing` object

| Field                   | Type   | Required | Description                                                                            |
| ----------------------- | ------ | -------- | -------------------------------------------------------------------------------------- |
| `min_phase_duration_ms` | number | No       | Minimum phase duration in milliseconds. Phases shorter than this are ignored.          |
| `max_phase_duration_ms` | number | No       | Maximum phase duration in milliseconds. Phases exceeding this trigger an interruption. |

### `thresholds` object

| Field                     | Type   | Required | Description                                                                        |
| ------------------------- | ------ | -------- | ---------------------------------------------------------------------------------- |
| `min_landmark_confidence` | number | No       | Minimum landmark confidence (0.0 to 1.0). Frames below this threshold are skipped. |

## Validation

Always validate your MoveSpec draft before creating a version:

* **Errors** block version creation and must be resolved.
* **Warnings** flag risky but non-blocking YAML patterns.

Use `validateDraft()` (SDKs) or `POST /api/movespecs/{id}/validate` (API) to check your YAML before versioning.

See [MoveSpec validation troubleshooting](/troubleshooting/movespec-validation) if validation fails.