Qv Agent Stack Sync

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.

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.