QVAC Agent Stack Sync

Orchestrate the published dependency cascade:

@qvac/inference
  -> @qvac/sdk
    -> @qvac/cli
      -> @qvac/ai-sdk-provider
        -> @qvac/opencode-plugin
        -> @qvac/openclaw-plugin

Goal: know which packages need a release, prepare draft release + backmerge PRs when asked, never auto-publish. SDK releases run qv-sdk-inference-version for the @qvac/inference range and sdk-python.

Modes

Invoke: /qv-agent-stack-sync or /qv-agent-stack-sync --plan.

Release train

When --plan lists two or more packages of a release train, release them with qv-release-train instead of --prepare-cascade and --promote: one branch, one release PR, one publish run, and no wait for each layer to reach npm.

References

• .github/teams/sdk.json — current SDK pod scope
• Current package manifests — agent-stack dependency order
• .agents/skills/qv-sdk-changelog/SKILL.md
• .agents/skills/qv-sdk-pr-create/SKILL.md
• .agents/skills/qv-sdk-backmerge/SKILL.md
• .agents/skills/qv-sdk-inference-version/SKILL.md (sdk releases only)
• docs/architecture/AGENT-INTEGRATIONS.md
• packages/cli/test/AGENT_STACK_E2E.md
• Planner: .agents/skills/_lib/sdk/agent-stack-plan.mjs
• Path map: scripts/sdk/package-paths.cjs
• Cascade details: references/prepare-cascade.md

Version policy (pre-major 0.x)

Recommend with rationale — never silent-bump. Confirm before --prepare-cascade.

• 0.x carets do not cross minors (^0.8.0 ≠ 0.9.0); tildes never do.
• Minor — outstanding [bc], [api], or feat: commits.
• Patch — dep-range alignment, or other non-breaking outstanding commits (e.g. fix:).
• Shared major.minor — @qvac/sdk sits on @qvac/inference's major and minor, so an engine minor makes the SDK a minor too, whatever its own commits say. Patches move independently.

Blockers the plan must surface

• AI SDK major mismatch — e.g. provider on ai@7 while OpenCode still depends on ai@6 / provider ^0.2.x. Hold that plugin release until code + deps align.
• Missing git tags vs npm latest — stop and ask; do not guess changelog base.
• Lower layer not on npm yet — drafts may declare future ranges; --promote / publish wait on npm view.

Workflow

0. Shared preflight

1. Prefer a clean worktree / dedicated worktree for cascade prep.
2. git fetch org remote (upstream / tetherto/qvac) tags + main.
3. Identify org remote vs fork remote (same policy as qv-sdk-pr-create).

1. --plan (mandatory first step)

node .agents/skills/_lib/sdk/agent-stack-plan.mjs
node .agents/skills/_lib/sdk/agent-stack-plan.mjs --json

Show the markdown table to the user. For each package report:

• local version, npm latest, last tag
• needs_release / blocked
• suggested next version + rationale
• dep ranges vs target lower version
• outstanding non-noise commits since tag

Do not create branches or PRs in this mode.

2. --prepare-cascade

Requires explicit user confirmation of the plan (versions + which packages).

Then for each needs_release package in dependency order, follow references/prepare-cascade.md:

1. Create org release-<slug>-<version> from main if missing.
2. Prep version bump + dep ranges, then qv-sdk-changelog --package=<slug> (follow that skill; do not call the generator as a shortcut) + NOTICE.
3. Open draft release PR → release-<slug>-<version>.
4. Open draft backmerge PR → main ([skiplog], cherry-pick -x) in the same session.
5. Skip packages marked blocked; report them clearly.
6. Do not merge. Do not trigger publish (Dima / human).

@qvac/inference is the first hop: it releases from release-inference-<version> through publish-inference.yml, and the SDK release PR points at the engine version already on npm. SDK releases chain qv-sdk-inference-version + docs Step 8 from qv-sdk-changelog.

3. --promote <slug>

1. Confirm lower dependencies are on npm (npm view).
2. Fresh-install verification (below).
3. Re-run NOTICE for this package so JS can resolve. If install still fails, restore the JS block from HEAD.
4. Mark the draft release PR ready for review (and keep backmerge draft until release merges, or ready it alongside — prefer ready both when release is ready to merge).
5. Remind: human merges; human triggers publish; then promote the next upper package.

The release-<slug>-* line is the cut. Do not cherry-pick later main onto it. Backmerge keeps main in sync with the cut.

File updates (when preparing releases)

Inference

• packages/inference/package.json — version only; the SDK's range moves in the SDK's own release
• changelog via qv-sdk-changelog --package=inference
• NOTICE via qv-notice-generate inference

SDK

• packages/sdk/package.json — version + dependencies["@qvac/inference"] via qv-sdk-inference-version, against the engine version already on npm
• changelog via qv-sdk-changelog --package=sdk (engine commits are scanned in), then docs Step 8
• sdk-python regenerated; tetherto-qvac-sdk publishes at the SDK's version

CLI

• packages/cli/package.json — version + dependencies["@qvac/sdk"]
• changelog via qv-sdk-changelog --package=cli
• NOTICE via qv-notice-generate cli
• README committed SDK range if documented

AI SDK Provider

• packages/ai-sdk-provider/package.json — version + extend peerDependencies["@qvac/cli"]
• changelog + NOTICE via SDK pod tools

OpenCode / OpenClaw plugins

• plugins/opencode/package.json or plugins/openclaw/package.json (+ openclaw.plugin.json version when present)
• bump @qvac/cli and @qvac/ai-sdk-provider deps to the planned minors
• OpenCode may also need ai / @ai-sdk/openai-compatible majors to match the provider — if not aligned, plan marks blocked
• changelog: qv-sdk-changelog --package=opencode-plugin or --package=openclaw-plugin (path map resolves plugins/*)
• NOTICE + README compatibility lines

Verification

Per package (from package dir)

• CLI: lint, build, test:unit, test:e2e, node scripts/check-publish-ready.cjs
• Provider: lint, build, test:unit (optional QVAC_INTEGRATION_TEST=1 npm run test:integration)
• OpenCode / OpenClaw: lint, build, test:unit (optional integration where available)

Fresh install (after lower npm publish)

tmp=$(mktemp -d)
cd "$tmp"
npm init -y
npm install --no-fund --no-audit @qvac/opencode-plugin@latest
npm ls @qvac/opencode-plugin @qvac/ai-sdk-provider @qvac/cli @qvac/sdk

Repeat with @qvac/openclaw-plugin@latest when promoting OpenClaw.

Completion report

Always end with:

• plan table (or link to --json output)
• packages released / drafted / blocked / skipped
• confirmed versions and dep ranges before → after
• draft release + backmerge PR URLs
• tests run
• reminder that publish is human-gated

Quality checklist

• --plan run before any mutation
• User confirmed versions for --prepare-cascade
• OpenClaw included in the cascade
• @qvac/inference released ahead of an SDK release that moves major.minor
• Draft release and draft backmerge opened together per package
• Release head is chore/<slug>-<version>-changelog, not release-*
• qv-sdk-changelog completed for each hop (published-version audit included)
• Blocked plugins (e.g. AI SDK mismatch) not force-released
• No publish / workflow_dispatch for npm
• Org-branch heads preferred (tetherto/qvac)