Skill: sigmalifting-dev/sigmalifting-cli (version 0.1.0)

--- name: sigmalifting-cli description: Use when the user wants to create, translate, import, validate, inspect, or update powerlifting training programs or workout logs for SigmaLifting using sigmalifting-cli, especially from spreadsheets, manuals, public programs, app exports, program-import bundles, or process-import bundles. --- # 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](references/program-modeling.md). - For Candito-specific lessons extracted from an exported app bundle, read [references/candito-translation.md](references/candito-translation.md). - For process execution and workout logging rules, read [references/process-logging.md](references/process-logging.md).

path: README.md
content: # Sigma CLI Skill

This skill teaches agents how to use the SigmaLifting CLI.

Install the CLI:

```bash
npm install -g https://github.com/sigmalifting/cli.git
```

Required executable:

```bash
sigmalifting-cli doctor --compact
sigmalifting-cli help --compact
sigmalifting-cli schema list --compact
```

The CLI is the executable schema and validation source of truth. The skill is the modeling guide.


path: references/candito-translation.md
content: # Candito Translation

This reference captures modeling rules extracted from a real app-exported Candito sample that validated and normalized cleanly through the standalone CLI.

## First Principle

When a user gives you an exported Candito bundle, validate and normalize that file first.

Do not start from the public spreadsheet and assume the structure.

The exported app bundle is authoritative for how SigmaLifting chose to model the program.

## Structural Lessons

The sample is not one block.

It is six blocks, each with `duration: 1`:

1. Muscular Conditioning
2. Hypertrophy
3. Linear Progression
4. Heavy Acclimation& Po
5. Maximal Strength
6. Deload or Max Test

The key lesson is not the exact phase names. It is the modeling choice:

- each structurally distinct week became its own block
- the block count matches the real phase boundaries
- the process `blockly_one_rm` array length also matches block count

For this family of Candito translations, unique-week structure is strong evidence for `duration: 1` blocks.

Observed phase footprint in the sample:

- Muscular Conditioning: 6 scheduled days, 16 exercises
- Hypertrophy: 5 scheduled days, 16 exercises
- Linear Progression: 4 scheduled days, 12 exercises
- Heavy Acclimation& Po: 4 scheduled days, 12 exercises
- Maximal Strength: 3 scheduled days, 7 exercises
- Deload or Max Test: 1 scheduled day, 1 exercise

## What Actually Changes Across Blocks

The sample changes:

- number of training days used in the week
- which days are blank in the 7-slot schedule
- which exercises appear in the week
- which exercises are anchored
- how many set groups each exercise has
- whether a lift is fixed percentage work, source-dependent backoff work, a multi-step percentage ladder, an accessory stack, or a special-rule set

That is why compressing these weeks into one block is wrong even if the schema can technically hold all the numbers.

## Candito Modeling Rules

### 1. Use one-week blocks when the week skeleton changes

If the day layout or exercise structure changes materially from week to week, keep those weeks as separate blocks with `duration: 1`.

### 2. Trust schedule shape, not day labels

The exported sample uses day names like `Untitled` and copied suffixes.

Do not infer semantics from those names.

Use these as the real signals:

- block name
- `weekly_schedule`
- day occupancy
- exercise membership per day

### 3. Use anchors conservatively and explicitly

Observed anchor patterns in the sample:

- competition squat: `squat` with ratio `1`
- competition bench: `bench` with ratio `1`
- competition deadlift: `deadlift` with ratio `1`
- deadlift variations: `deadlift` with ratio `0.9`
- accessories: anchor disabled

Do not invent anchors for accessories.

### 4. Use `rpe` as the variable parameter for percentage-driven rep-range work

In the sample, many main-lift set groups look like:

- `variable_parameter: "rpe"`
- fixed `weekly_weight_percentage`
- `weekly_rpe: [-1]`

That means the set is modeled as a percentage-based prescribed set where the realized RPE is the variable outcome.

This is important for Candito-style rep-range and max-rep work.

### 5. Use `weight` as the variable parameter for accessories and manual-rule work

In the sample, accessories and special-rule work usually look like:

- `variable_parameter: "weight"`
- `weekly_weight_percentage: [-1]`
- fixed reps and set counts

That is the right choice when the work is load-progressed manually rather than percentage-prescribed from the anchor.

### 6. Keep special rules in notes unless they are truly machine-derived

The sample preserves important instructions in `weekly_notes`, including:

- extra volume squat rules
- back-off squat decision rules
- rep-range reminders like `4-6 reps`, `3-6 reps`, `1-2 reps`, `1-4 reps`
- deadlift-variation special handling

Do not convert these into fake automation unless the app actually has a precise mechanic for them.

For Candito, notes are often the correct representation.

### 7. Prefer explicit set groups over over-abstract backoff logic

The sample mostly encodes Candito work as explicit set groups rather than using automatic backoff or fatigue-drop configs.

That is a useful default when the spreadsheet logic is human-rule-heavy.

Do not call every lower-load follow-up set a Sigma backoff. If the weight is independently prescribed, such as a fixed percentage from 1RM, model it as an explicit set group. Use `backoff_config` only when the later set group's weight depends on a previous set group's actual or calculated weight.

## Process-Side Lessons

The exported sample is a `process-import`, not just a `program-import`.

Important consistency checks:

- the sample has 64 exercises and 64 exercise recordings
- `exercise_recordings.length` matches `exercises.length`
- each recording belongs to one exported exercise id
- each recording `weekly.length` matches its block `duration`
- `blockly_one_rm.length` matches `program.blocks.length`

When synthesizing similar process bundles, keep those alignments exact.

## Practical Heuristic

For Candito-style translations:

1. validate the exported bundle with the CLI
2. normalize it to inspect the canonical shape
3. identify the phase boundaries from structure, not just chronology
4. keep unique weeks as separate blocks
5. use anchors and variable parameters the way the exported sample does
6. store human decision rules in notes unless the app has real automation for them

If your translated bundle feels smaller only because you compressed unlike weeks together, it is probably wrong.


path: references/program-modeling.md
content: # Program Modeling

## Block Definition

In SigmaLifting, a block is not merely "some consecutive weeks."

A block is the longest consecutive span of weeks where each exercise keeps the same structural role and only the weekly values change.

This is similar to combining like terms:

- if the structure is the same, keep it in one block and vary the weekly arrays
- if the structure changes, it is not the same term anymore and should become a new block

## Structural Sameness

Treat weeks as structurally the same only if all of the following stay stable:

- day count and day identity
- exercise identity per day
- set-group count per exercise
- set-group ordering
- variable parameter selection
- dependency graph between set groups
- meaning of the exercise within the phase

Numeric drift alone does not require a new block.

Examples of numeric drift that can stay inside one block:

- 5 reps becomes 3 reps
- 72.5% becomes 80%
- 4 sets becomes 5 sets
- notes change week to week

Examples of structural drift that should usually create a new block:

- fixed percentage work becomes source-dependent backoff work
- an accessory disappears and a competition lift variation replaces it
- a day changes from bench volume day to bench intensity day with a different lift stack
- a lift changes from a single set-group structure to multiple semantically distinct set groups

## Backoff Semantics

Do not use generic lifting slang as the schema model.

In SigmaLifting, a set group is a backoff only when `backoff_config.enabled` is true and `depends_on_set_group_id` points to an earlier set group.

Use `backoff_config` when the later set group's weight should be derived from a previous source set group, such as:

- a percentage of the source group's actual weight
- a target-RPE calculation from the source set's actual weight, reps, and RPE

Do not model fixed lower-percentage work as backoff. If the program says `1x3 @85%` followed by `2x5 @75%`, and both weights are prescribed directly from 1RM, that is two explicit percentage set groups, not a source-dependent backoff.

For real backoff work, the source set group should normally make weight the workout-recorded variable. If the source weight is already fully prescribed by percentage, there is usually no reason to make later work depend on it; model the later work explicitly instead.

The dependent backoff group itself should not use `variable_parameter: "weight"` when the app is expected to calculate its weight. Record a different variable, usually RPE or reps, while the backoff config supplies the weight.

## Variable Parameter Semantics

Each set group chooses one parameter to record at workout time:

- `weight`: prescribe reps and RPE
- `reps`: prescribe weight and RPE
- `rpe`: prescribe weight and reps

The selected variable parameter is not another prescribed progression column. It is the slot the lifter fills in during execution.

Backoff and fatigue-drop behavior depends on runtime performance and is represented in the app as RPE-variable work. Use `variable_parameter: "rpe"` for dependent backoff or fatigue-drop set groups. Do not enable mixed-weight prescription when `variable_parameter` is `weight`, because mixed weight is itself a weight prescription.

## Anti-Pattern

Bad modeling pattern:

- start from program duration
- create one block with that duration
- force every week into that block using zeros and notes

This produces a bundle that may validate, but it hides the real phase structure and makes the program harder to edit, inspect, and reason about.

## Better Heuristic

When translating a manual or spreadsheet:

1. write down each week's day and exercise skeleton
2. compare adjacent weeks for structural equivalence
3. split the program whenever structural equivalence breaks
4. only then fill in weekly arrays for the block

If a generated bundle feels "technically representable" but not "true to the phase structure," the block model is probably too compressed.


path: references/process-logging.md
content: # Process Logging

Use this reference when an agent is updating a running `process-import` bundle from user workout data.

## Program Versus Process

The program is the prescription. Do not edit it during ordinary workout logging.

Program `weekly_notes` are part of the prescription. Use them only for program facts the schema cannot express directly, such as:

- rep ranges like `4-6 reps`
- branch rules like optional max attempts
- special prescription logic that cannot fit in fixed reps, weight, or RPE fields

Do not use program `weekly_notes` for generic coaching cues by default.

The process is the user's execution diary. Actual performed sets and per-exercise day notes belong in the process.

## Normal Logging

If a user reports a set that corresponds to a prescribed set slot, write it to that slot with `process update-set`.

Use:

- `weight` for actual load used
- `reps` for actual reps completed
- `rpe` for actual reported RPE
- `completed: true` when the set was performed

Do not change the source program just because the user's actual set differs from the prescription.

## Off-Plan Work

If the user tries to do something materially outside the prescription, the agent should first resist and explain the mismatch.

Examples:

- prescribed triples but the user wants an extra heavy single
- prescribed 3 sets but the user wants a fourth or fifth set
- prescribed percentage work but the user wants a much heavier load
- fatigue or pain makes the attempted work unsafe or clearly inconsistent with the plan

If the user insists, or reports that the off-plan work already happened, preserve the record without corrupting the prescription:

- If the set still corresponds to a prescribed set slot, log it into that prescribed slot as the actual performed set.
- If the work is extra or too far from any prescribed slot, do not create fake prescribed sets just to hold it.
- Put the off-plan detail in the process exercise note for that week using `process update-note`.

The note should be factual and concise:

```text
Off-plan: user performed an extra 405x1 @9.5 single after the prescribed squat work.
```

Do not write this into program `weekly_notes`.

## Finding State

For an installed CLI workflow, prefer these commands:

1. `sigmalifting-cli process list --compact`
2. `sigmalifting-cli process show --process-id <id> --compact`
3. `sigmalifting-cli render process-overview --file <stored-json> --raw`
4. `sigmalifting-cli render exercise-detail --file <stored-json> --exercise-id <id> --raw`
5. `sigmalifting-cli process get-recording --process-id <id> --exercise-id <id> --compact`

Use `SIGMALIFTING_HOME` or `--store-root` to make sure you are reading and writing the intended store.

## Answering "What Is Next?"

To answer what the user should do next:

1. inspect the process recordings for completed sets
2. inspect the program exercise set groups for prescribed set count, reps, RPE, and percentage
3. compute percentage-based loads from the process one-rep-max profile and weight rounding config
4. check `backoff_config.enabled` before describing a set as backoff or deriving it from another set
5. account for program notes only when they encode prescription facts
6. recommend the next uncompleted prescribed set

Do not infer Sigma backoff semantics from ordinary gym wording. A later set at a lower fixed percentage is not a backoff unless `backoff_config.enabled` is true and it depends on an earlier set group.

If the CLI cannot compute the next set directly, do the calculation explicitly and state the assumption.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)