tetherto SDK Lockstep Client Sync
Keep the SDK pod aligned with the @qvac/inference version anchor so a
release-* cut ships the same version on npm (@qvac/inference, @qvac/sdk)
and PyPI (tetherto-qvac-sdk).
@qvac/inference is the sole version anchor. sdk and sdk-python follow it
and publish at the same version. The engine drives the number; the SDK is a
transport over it.
When to use this skill
Applies to the inference-anchored SDK pod (not the agent-stack cascade: cli / ai-sdk-provider / plugins).
Use when:
- User runs
/qv-sdk-lockstep-syncdirectly. - Auto-invoked by
/qv-sdk-changelogwhen--package=sdk. - Auto-invoked by
/qv-sdk-pr-createwhen the PR diff touches the version ofpackages/inferenceorpackages/sdk. - Manually, anytime
@qvac/inference'sversionchanges and you want the pod in lockstep before opening a PR.
Packages
| Package | npm / PyPI | Role |
|---|---|---|
| inference | @qvac/inference |
Version anchor — the source of truth |
| sdk | @qvac/sdk |
Follows inference's version |
| sdk-python | tetherto-qvac-sdk |
Follows via generated client (SDK_VERSION stamped from sdk) |
sdk-python doesn't get its own changelog — its history lives in
packages/sdk/CHANGELOG.md. Commits under packages/inference are scanned
into that changelog as well.
What it does NOT do
- Does not open release PRs or publish (see
publish-sdk.yml+ gitflow). - Does not sync agent-stack packages (
/qv-agent-stack-sync). - Does not auto-commit.
- Does not run in CI. CI enforces the aligned version at release
(
publish-sdk.ymlverify step); this skill is the fix.
Workflow
Step 1: Stamp the inference anchor into sdk
From the monorepo root:
node .agents/skills/qv-sdk-lockstep-sync/scripts/sync-sdk-pod.mjs
Flags on the script: --dry-run, --check (exit 1 on drift). It sets
packages/sdk version to @qvac/inference's version.
Step 2: Sync packages/sdk-python generated client
Requires a venv with gen extras (create once if missing):
cd packages/sdk-python
python3 -m venv .venv
.venv/bin/pip install -U pip
.venv/bin/pip install -e ".[gen]"
.venv/bin/python3 scripts/generate.py
.venv/bin/python3 scripts/generate.py --check
SDK_VERSION is stamped from packages/sdk/package.json (which Step 1 already
set to the inference anchor). Commit any updates under
packages/sdk-python/src/tetherto/qvac_sdk/_generated/.
Step 3: Review and commit
git status should show (as applicable):
packages/sdk/package.jsonpackages/sdk-python/src/tetherto/qvac_sdk/_generated/**
Commit alongside the originating inference change. When invoked from
/qv-sdk-changelog, this is part of the release commit; when invoked from
/qv-sdk-pr-create, part of the PR's last commit.
When this skill is invoked from another skill
From /qv-sdk-changelog
/qv-sdk-changelog --package=sdk calls this skill after NOTICE generation for
sdk. Skip for any other --package value.
From /qv-sdk-pr-create
If the PR diff touches the version of packages/inference or
packages/sdk, the parent skill prompts to run this skill first. Opt out
with --no-sync on the parent skill.
Quality Checklist
-
sync-sdk-pod.mjsreports OK or an apply summary -
packages/sdkversion matches@qvac/inference -
packages/sdk-pythongenerate.py --checkpasses - Staged changes are only lockstep pod artifacts (+ originating inference edit)
- No CI auto-commits of this skill
References
- Python generator:
packages/sdk-python/scripts/generate.py - Notice generator:
.agents/skills/qv-notice-generate/SKILL.md - Publish:
.github/workflows/publish-sdk.yml - Changelog / PR skills:
qv-sdk-changelog,qv-sdk-pr-create