MoveSpec

MoveSpec is a YAML-first movement definition format. You author a MoveSpec to describe the movements you want to detect, then version and release it for use in detection sessions.

Lifecycle

Create a MoveSpec

Create the top-level MoveSpec resource in a project. This also creates a mutable draft.

Update the draft YAML

Replace the full draft YAML when you make authoring changes. See the YAML reference for the schema.

Validate the draft

Run validation before versioning so you can inspect blocking errors and non-blocking warnings.

Create an immutable version

Snapshot the draft into an immutable version when it is ready for runtime use.

Release the version

Release the immutable version you want future sessions to resolve by default.

Runtime resolution

Detection sessions can resolve a MoveSpec in two ways:

movespec_version_id — Use a specific immutable version for deterministic replay or staged rollout control.
movespec_id — Resolve the current released version automatically. Your sessions follow the latest release.

Example

from kynasmith import KynasmithClient
from kynasmith.models import MoveSpecCreate, MoveSpecDraftUpdate

client = KynasmithClient(api_key="ks_key_123:secret_123")

movespec = client.movespecs.create(
    MoveSpecCreate(name="Squat counter")
)
client.movespecs.update_draft(
    movespec.movespec_id,
    MoveSpecDraftUpdate(yaml_source="""
name: squat
version: "1.0"
detection:
  type: repetition
  movement:
    name: squat
    phases:
      - name: standing
        criteria:
          - joint: knee
            angle_min: 160
            angle_max: 180
      - name: bottom
        criteria:
          - joint: knee
            angle_min: 60
            angle_max: 100
    sequence:
      - standing
      - bottom
      - standing
"""),
)
validation = client.movespecs.validate_draft(movespec.movespec_id)
version = client.movespecs.create_version(movespec.movespec_id)
client.movespecs.release_version(
    movespec.movespec_id,
    version.movespec_version_id,
)

Visibility and catalogue

Visibility applies to the top-level MoveSpec resource:

private keeps the MoveSpec inside the owning project boundary.
public makes the MoveSpec visible through the public catalogue.

Changing visibility does not skip the normal lifecycle. You still validate, version, and release.

Forking

Treat a public catalogue MoveSpec as a starting point, not as a shared mutable dependency:

Fork when you want to adapt a public MoveSpec to your own project.
Release your own immutable version after changing the YAML.
Keep production integrations pinned to your released version.

This keeps runtime behavior under your control even when the source catalogue entry evolves.

Public surface

The public developer API covers:

MoveSpec creation and metadata updates (name, description, visibility)
Draft reads and full draft replacement
Draft validation results
Immutable version listing and creation
Explicit release of an immutable version
Forking a MoveSpec into your own project

Validation output

Validation results include:

errors — Block version creation and release readiness. Must be resolved.
warnings — Flag risky but non-blocking YAML patterns.

See the YAML reference for the complete schema and MoveSpec validation troubleshooting for common issues.

​MoveSpec

​Lifecycle

​Runtime resolution

​Example

​Visibility and catalogue

​Forking

​Public surface

​Validation output