SigmaLifting CLI

Use this skill when working with SigmaLifting CLI bundles, especially when turning a spreadsheet, manual, or public program into a program-import bundle.

Core Boundaries

• Treat the CLI as a standalone JSON tool.
• Use the installed sigmalifting-cli executable as the contract and validation engine.
• Do not rely on Realm, Expo file APIs, or app services for CLI behavior.
• Stored program changes may cascade into linked process bundles in the CLI JSON store; file-only bundle edits cannot update unrelated files unless the command output is saved to the store.
• Prefer contract-valid JSON bundles over app-coupled shortcuts.
• Treat this skill folder as the modeling guide, not as the executable schema.

Agent Mutation Policy

SigmaLifting JSON is the CLI's internal storage and import/export contract. It is not an agent editing surface.

Agents must not directly create or mutate program/process bundle JSON with file edits, apply_patch, ad hoc scripts, jq, editor operations, or manual rewrites of files in the CLI store. Reading JSON for diagnosis is allowed; writing JSON directly is not.

All bundle creation and mutation must go through CLI commands:

• create initial bundles with template, program create, process create-from-program, or xlsx import
• change programs with program add-block, program update-block, program add-day, program update-schedule, program add-exercise, program update-exercise, custom-lift commands, and the exercise-progression intent commands such as program set-anchor, program add-set-group, program set-week-value, and program toggle-backoff
• change processes with process update-* commands and narrow intent commands such as process set-one-rm
• write command results with --out or let the local store persist command output
• import externally supplied JSON only through validate; use normalize only when the user explicitly wants CLI cleanup/repair

validate is a strict import/acceptance gate for existing JSON. If it fails with repair warnings, use normalize to produce the cleaned bundle before inspecting or importing it.

If the CLI does not expose a command for a needed mutation, stop and report the CLI command gap or add the command first. Do not bypass the CLI by patching raw JSON.

CLI Discovery

When the installed CLI and this skill are available, inspect the tool before modeling:

1. run sigmalifting-cli doctor --compact
2. read this SKILL.md and any task-relevant files in references/
3. run sigmalifting-cli help --compact
4. run sigmalifting-cli schema list --compact
5. run sigmalifting-cli template program-import --compact or template process-import --compact

Program and process bundle results persist as local JSON by default. Use sigmalifting-cli store path to locate the store, and use SIGMALIFTING_HOME or --store-root when you need an explicit test or project-local store.

Schema Contract

Do not treat this skill file as the schema.

This skill explains modeling judgment: block boundaries, weekly structure, set-group semantics, and common translation mistakes. The installed CLI is the schema source of truth.

Schema mentions in this skill are routing instructions, not schema documentation. They tell the agent which CLI commands to call before building CLI payloads or accepting imported JSON.

Before building CLI command payloads or importing existing JSON, get the executable contract from the CLI:

1. sigmalifting-cli schema list --compact
2. sigmalifting-cli schema show <kind> --compact
3. sigmalifting-cli template <kind> --compact
4. sigmalifting-cli validate <kind> --file <path|"-"> --compact

Use the template to learn field shape, defaults, sentinel values, and nesting. Use schema show to check constraints. Use this skill to decide what the program should mean structurally.

If the skill and CLI appear to disagree, trust the CLI schema and report the skill as stale.

Do not invent fields that are not present in the CLI schema or template.

Authoritative Sample Workflow

If the user provides an exported SigmaLifting JSON file, treat that export as the first source of truth.

Before generating or translating anything similar:

1. identify the bundle kind the file actually matches
2. run the standalone CLI against the file exactly as provided
3. validate it first
4. if validation reports repair warnings, normalize it and validate the normalized output
5. only then extract modeling rules from it
6. make any changes through CLI mutation commands, never by patching the JSON file

If an app-exported file cannot be consumed by the standalone CLI, treat that as a CLI problem to investigate before declaring the modeling wrong.

Do not skip this step and jump straight to reconstructing the program from memory, public spreadsheets, or a simplified interpretation.

Block Semantics

Do not define a block by contiguous time alone.

A block is a maximal consecutive run of weeks that share the same structural skeleton.

The structural skeleton means:

• same training day layout
• same exercise identities on each day
• same set-group count and ordering per exercise
• same variable-parameter style per set group
• same dependency shape such as backoff or fatigue-drop relationships

What may vary inside a block:

• weekly set counts
• weekly reps
• weekly RPE values
• weekly percentages
• weekly notes

What should usually force a new block:

• a day appears, disappears, or changes role materially
• an exercise is added, removed, or replaced
• a set group appears or disappears
• a set group changes semantic role rather than just numeric values
• dependency structure changes
• the week only fits by abusing placeholder zero-sets across many exercises
• the phase intent clearly changes even if the schema could be compressed

Do not collapse an entire multi-week program into one block just because weekly arrays can encode it.

That is a schema-valid compression, but it is a modeling error under SigmaLifting semantics.

Variable Parameter Semantics

Every set group has exactly one workout-recorded variable parameter: weight, reps, or rpe.

The other two training numbers are prescribed by the program:

• variable_parameter: "weight" means reps and RPE are prescribed, and weight is recorded during the workout.
• variable_parameter: "reps" means weight and RPE are prescribed, and reps are recorded during the workout.
• variable_parameter: "rpe" means weight and reps are prescribed, and RPE is recorded during the workout.

Do not model a set group by prescribing all three numbers. Do not leave two numbers open unless the CLI has a command and schema support for that explicit behavior.

Backoff and fatigue-drop configs are RPE-variable tools in the app model. They are only valid on set groups with variable_parameter: "rpe". If weight is the variable parameter, do not enable backoff_config, fatigue_drop_config, or mixed-weight prescription.

Workflow

When modeling a program:

1. Inspect each week for structural sameness, not just duration.
2. Group only consecutive weeks that share the same skeleton.
3. Create one block per structural group.
4. Use weekly arrays only for parameter variation inside that block.
5. Preserve special-case instructions in notes if they are not truly machine-derived.
6. If unsure, prefer more blocks over fewer blocks.

Warning Signs

Stop and re-evaluate the block split if you notice:

• many 0 set placeholders just to make weeks fit
• weeks that feel like distinct phases but are still in one block
• day layouts drifting across weeks
• exercise schemes changing identity from week to week

References

• For detailed modeling guidance, read references/program-modeling.md.
• For Candito-specific lessons extracted from an exported app bundle, read references/candito-translation.md.
• For process execution and workout logging rules, read references/process-logging.md.