Qv SDK PR Create

SDK Pod PR Creation

Generate PR titles and descriptions for SDK pod packages, following the team's template and format rules.

When to use this skill

Applies to SDK pod packages whose paths are owned by .github/teams/sdk.json.

Use when:

• Creating a PR for any SDK pod package
• User asks to generate PR description
• User invokes /qv-sdk-pr-create

Branch / remote preference

Preferred path for internal SDK work: push the head branch to the org repo (tetherto/qvac) and open a same-repo PR. Org-branch ready PRs get baseline CI without any fork trust gate. Heavy tiers still opt in via labels (test-e2e-smoke / test-e2e-full, addon stage labels, etc.). Prefer Ready for review over Draft when you want baseline checks to run (drafts run nothing until ready).

Fallback: personal-fork → org PRs still work, but a personal fork counts as external. Privileged CI needs a merge/release-team member to approve the fork-ci environment on each workflow run for the current head SHA; each new push re-prompts. Do not ask the PR author to self-approve fork-ci.

Resolve remotes from git remote -v:

• Org remote — URL contains tetherto/qvac (often named upstream, sometimes origin)
• Fork remote — contributor fork, if present (often named origin when org is upstream)

In command examples below, ORG_REMOTE / FORK_REMOTE / BRANCH are placeholders — substitute the resolved remote and branch names. Do not run those tokens literally.

Release PR branch naming (org-branch path)

publish-sdk.yml (and sibling publish workflows) run Release Merge Guard on push to any release-* ref. The guard validates github.ref_name — the branch that was pushed — not the PR base. It requires release-<pkg>-x.y.z (three-part semver).

Consequences for release changelog / metadata PRs:

1. Base (target) must be exactly release-<pkg>-<x.y.z> (e.g. release-sdk-0.17.0). Short cuts like release-sdk-0.17 fail the guard on merge/publish. If the cut is short-named, STOP and ask a repo admin to rename it to the three-part form before relying on publish (protected-branch rename needs admin).
2. Head (working branch) must not start with release- when pushed to the org remote. Prefer chore/<pkg>-<x.y.z>-changelog (e.g. chore/sdk-0.17.0-changelog). Names like release-sdk-0.17.0-changelog trip Release Merge Guard on the helper push and can leave a failing check on that commit SHA.
3. GitHub cannot retarget a PR's head. To rename a bad head: push the same commits under the new name, open a new PR, close the old one, delete the old remote head. If the new PR still shows a stale Release Merge Guard fail on the same SHA, push an empty [skiplog] commit so checks reattach to a fresh SHA.

backmerge/release-<pkg>-<x.y.z> heads are fine — they do not match the release-* push trigger.

Release changelog PRs (metadata + notes onto release-<pkg>-x.y.z):

• Title is chore: (optional [mod] when the cut is catalog-only). Do not put [bc] on the release title; breaking lives in breaking.md.
• Body API / Models / Breaking sections are copied from changelog/<this version>/, not from an earlier hop or the generator summary. Delete a section only when that file is absent.

Workflow

1. Identify base and current branch — note whether the base is main or a release-<pkg>-<x.y.z> branch. For release PRs, apply Release PR branch naming above (base three-part; head not release-*)
2. Resolve the head remote (prefer org remote; see above). Collect commits/diff from <base>...<head-remote>/<branch> (or local HEAD if not yet pushed)
3. Infer ticket, prefix, and tags from changes (see Inference Strategy)
4. Only ask user for input when inference confidence is low
5. Generate title: TICKET prefix[tags]: subject
6. Fill template sections based on changes
7. Validate tag requirements ([bc]/[api]/[mod])
8. If the diff exposes or changes a user-facing SDK capability, apply first-class product parity (see below) before outputting the description
9. If diff touches the version of packages/sdk or its @qvac/inference range, or sdk's dep blocks, chain into the qv-sdk-inference-version skill (see "SDK @qvac/inference Version Trigger" below)
10. If the diff touches user-facing paths under packages/sdk, packages/cli, or packages/sdk-python and docs/website/content/docs is not already in the diff, apply the docs website trigger (see "Docs Website Trigger" below) before outputting the description
11. Output complete PR description
12. If base is a release branch, chain into the dual-PR flow (see "Release Target Dual-PR Flow" below)

Inference Strategy

Infer first, ask only if uncertain:

Ticket number:

• Extract from branch name pattern: QVAC-\d+, SDK-\d+
• Extract from commit messages if referenced
• ASK only if no ticket found

Prefix (feat/fix/doc/test/chore/infra):

• Extract from branch name prefix: feat/, fix/, infra/, etc.
• Use majority prefix from commit messages
• If no conventional commits, infer from diff:
  • New files/exports → feat
  • Bug-related changes → fix
  • Only .md files → doc
  • Only test files → test
• ASK only if mixed signals or unclear

Tags ([api]/[bc]/[mod]):

• [api]: new exported functions/types in public API
• [bc]: removed/changed existing public API signatures
• [mod]: changes to model constant definitions
• ASK only if change scope is ambiguous
• Release changelog PRs (base release-*, diff is notes / NOTICE / version / generated docs): title is chore: (optional [mod]). Do not copy [bc] / [api] from the notes into the title. Body API / Models / Breaking still copy changelog/<this version>/.

Testing section:

• If test files modified → "Unit tests added/updated for X"
• If no tests → ASK what manual testing was done

Format References

• PR title format: See docs/gitflow.md and the validation rules below
• PR body template: See .github/PULL_REQUEST_TEMPLATE/sdk-pod.md

Fill template sections based on the diff analysis. Delete sections that don't apply.

First-class product parity (CLI)

Trigger: the diff touches packages/sdk/server/bare/plugins/**, packages/sdk/client/api/**, a plugin *-config.ts schema, or a request/sampling schema used by serve, and the change is a user-facing inference capability (new modality, new request field, new load-time modelConfig field). Native addon-only diffs skip this.

See packages/sdk/AGENTS.md.

If triggered and packages/cli is unchanged:

1. ASK: "CLI not updated. Add CLI in this PR, mark library-only in the body, or skip?"
2. Add CLI: stop until the CLI diff is present. Library-only: one-line why in the body. Skip: reminder at the end.

Output Format

ALWAYS output the PR in this copy-ready format, even when making corrections:

## PR Title
```
TICKET prefix[tags]: subject
```

## PR Body
```markdown
## 🎯 What problem does this PR solve?
...
```

gh CLI Integration

After generating the PR description, check for gh CLI:

1. Check if gh is installed: which gh
2. Check remotes: git remote -v — identify the org remote (tetherto/qvac) and any fork remote
3. If available, ask user: "Create PR now with gh CLI?" [Yes / No / Preview first]
4. If yes, ensure changes are committed, then push the head branch to the org remote when the user has write access. Only push to a personal fork when org push is unavailable or the user explicitly chooses the fork path
5. Create the PR:

# Preferred — org-branch (same-repo) PR.
# ORG_REMOTE = remote whose URL is tetherto/qvac (often `upstream` or `origin`).
git push -u ORG_REMOTE BRANCH
gh pr create \
  --repo tetherto/qvac \
  --base main \
  --head BRANCH \
  --title "TICKET prefix: subject" \
  --body "..."

# Fallback — personal fork -> org PR (external CI path; needs merge/release fork-ci approval per run):
git push -u FORK_REMOTE BRANCH
gh pr create \
  --repo tetherto/qvac \
  --base main \
  --head FORK_OWNER:BRANCH \
  --title "TICKET prefix: subject" \
  --body "..."

# Then open in browser:
gh pr view --repo tetherto/qvac BRANCH --web

Important:

• --web alone only opens browser for manual creation, does NOT create the PR
• For fork PRs, must specify --repo, --base, and --head FORK_OWNER:BRANCH explicitly
• For org-branch PRs, --head BRANCH (no owner:) is enough when --repo tetherto/qvac
• Do not add fork trust gates on org-branch PRs; baseline CI runs without them. For fork PRs, tell the user a merge/release reviewer must approve the pending fork-ci deployment after reviewing the current head
• Commit and push before creating PR

6. If gh not available, output the copy-ready markdown format above
7. As part of the output, provide a clickable hyperlink (not plain text) to the PR on GitHub.

SDK @qvac/inference Version Trigger

Trigger: the PR diff (<base>...<head-remote>/<branch> or local HEAD) modifies the version of packages/sdk/package.json or its @qvac/inference range, or sdk's dependencies / optionalDependencies / peerDependencies.

When triggered, prompt the user to run qv-sdk-inference-version so the versions and the generated Python client are right in the same commit/PR: @qvac/sdk's version and its @qvac/inference range sharing a major.minor, and tetherto-qvac-sdk (generated SDK_VERSION / _generated/) at the SDK's version. A range on a different major.minor fails the SDK's lint on every PR.

A change to packages/inference/package.json alone is not a trigger — the engine has its own version and its own release.

Steps (after Step 8 of Workflow above)

1. Detect the trigger condition by inspecting the diff:
   • git diff <base>...<head-remote>/<branch> -- packages/sdk/package.json (or vs local HEAD) shows changes
   • Changes touch sdk's version line, its @qvac/inference range, OR sdk's dependencies / optionalDependencies / peerDependencies block
2. If triggered, ask user: "PR touches sdk's deps/version. Run qv-sdk-inference-version (version + sdk-python)?" [Yes / No (skip)]
3. If yes, read .agents/skills/qv-sdk-inference-version/SKILL.md and follow it inline.
4. Verify: bun run enforce-inference-versions in packages/sdk and packages/sdk-python generate.py --check must both pass.
5. Stage and commit the version changes onto the same branch BEFORE proceeding to Output step.