[DOCS] Add a skill for bumping the client pins and their specs

[chandrasekharan-zipstack]

What

Adds .claude/skills/bump-client-pins/SKILL.md — the ordered sequence for bumping unstract-client / llmwhisperer-client and cutting a CLI release.

A client bump here is three coupled edits, not one:

1. the exact pin in pyproject.toml, then uv lock + uv sync (CI installs from the lockfile)
2. the vendored spec re-copied byte-for-byte from the commit the pinned client was generated from — reachable via that client's release tag → its tools/gen_sdk.sh SPEC_SOURCE
3. the upstream commit and sha256 in src/unstract_cli/specs/provenance.json

tests/test_specs.py and tests/test_contract.py enforce the coupling, so today it is discoverable only by tripping them and working backwards. The skill also covers the part that is easy to get wrong: tests/derived_flags.json is refreshed deliberately after reading what moved — a flag missing from it is a flag the CLI has stopped offering — and the release shape (publish before tag, none for the version already committed, pre_release for the rc flow).

Why

Nothing notifies this repo when either client releases, and the pipeline is undocumented in-repo. It points at the existing tests and src/unstract_cli/specs/README.md rather than restating them, and carries no version numbers, dates or codenames.

Notes

• Docs only — no code, no CI changes.
• Based on feat/cli-scaffold rather than main, since main is still the empty initial commit and this skill describes machinery that lives on the scaffold branch.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CSm32dsxD56PkKENgav3Mn

[greptile-apps]

Greptile Summary

Adds an in-repository skill documenting the complete client-pin bump and CLI release process.

• Couples exact dependency pins with lockfile updates, vendored specifications, and provenance.
• Documents contract testing and deliberate derived-flag snapshot refreshes.
• Clarifies that every provenance field must be checked against the client generator.
• Clarifies that RC promotion must reuse the same version_bump.

Confidence Score: 5/5

The documentation-only PR appears safe to merge, with both previous findings fully addressed and no new actionable issues identified.

The updated instructions now require maintainers to verify all four provenance fields and explicitly require RC promotion to reuse the same version bump. Both previous threads are resolved, and the latest edits introduce no remaining correctness or repository-rule violations.

Important Files Changed

Filename	Overview
.claude/skills/bump-client-pins/SKILL.md	Documents the coupled dependency, specification, provenance, validation, and release workflow; the latest changes fully address both previous review findings.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Choose released client versions] --> B[Update exact pins]
  B --> C[Run uv lock and uv sync]
  C --> D[Trace client tag to gen_sdk SPEC_SOURCE]
  D --> E[Copy vendored specs byte-for-byte]
  E --> F[Update all provenance fields and sha256]
  F --> G[Run tests]
  G --> H{Derived flags changed?}
  H -- Yes --> I[Review changes and deliberately refresh snapshot]
  H -- No --> J[Run lint]
  I --> J
  J --> K[Choose version bump]
  K --> L[Dispatch release workflow]
  L --> M{Pre-release?}
  M -- Yes --> N[Publish RC]
  N --> O[Promote using the same version_bump]
  M -- No --> P[Publish stable release]

Loading

_{Reviews (2): Last reviewed commit: "docs: check all four provenance fields, ..." | Re-trigger Greptile}