Release
Prepare a complete, consistent timepicker-ui release in one flow. This skill is a thin
orchestrator: the real work is done by the build-release subagent. The skill exists to
decide the version with you and to hold the approval gate the subagent can't run itself.
The version source of truth is the root package.json (timepicker-ui) — the ONLY version
field a release ever changes. app/package.json (build workspace) and docs-app/package.json
(docs site) are each a separate application's own version; a release NEVER touches their
version field. What a release does in docs-app/ is update the content that references the
library version — the changelog page, what's-new, and npm i timepicker-ui@x.y.z install
snippets — not the docs site's own app version.
The changelog is about the library, not the docs site. CHANGELOG.md and the docs-app
changelog page record changes to the published timepicker-ui package only. Changes to
docs-app/ itself (SEO, page content, demo fixes, favicons, docs-site bugs) are NEVER logged
and never bump the version — the docs site is a separate app the library does not track. The
docs-app changelog page just presents the library changelog. If a release touched only
docs-app/, there is no library release to cut — say so instead of inventing entries.
Arguments (optional)
- A version or bump type:
/release patch, /release minor, /release major, or an explicit
number /release 4.4.0. If omitted, the skill proposes a bump from the changes since the last
release and asks you to confirm.
--apply-all skips the per-area approval prompt and applies the whole audited plan (still
reports + sanity-builds at the end). Use only for an explicitly unattended run.
Workflow
Phase 1 — Decide the version (gate)
- Read the current version from root
package.json. Skim what changed since the last release
(read-only git log / git diff against the last release tag/commit, plus the working tree)
to judge magnitude. The branch name (e.g. feature/4.4.0) is a strong hint at intent.
- Propose a SemVer bump with a one-line rationale:
patch — bug fixes / internal only, no public API changeminor — new backwards-compatible options/plugins/themes/methodsmajor — breaking change to public API, option groups, getValue() shape, exports, or the
tp-ui- CSS class contract (requires migration notes)
- Use AskUserQuestion to confirm the exact new version before anything else. If the user
passed a version/bump as an argument, still confirm it. The number is a promise to consumers.
Phase 2 — Audit (read-only)
Dispatch the build-release subagent (Task tool, subagent_type: build-release) in audit mode
with the confirmed new version. Ask it to return a file-level plan, making NO edits:
- Every place that must be bumped (root
package.json; README version-pinned Socket badge +
any Features/Options/Themes/Plugins/API/Upgrading sections affected by this release).
- The historical version references it will deliberately leave untouched (prior CHANGELOG
entries, docs-app
<Section> blocks, "Removed in v4.0.0", migration guides) — listed so you
can see nothing historical gets rewritten.
- A drafted CHANGELOG.md entry (
## [x.y.z] - YYYY-MM-DD with the date the user gave, else
Unreleased; grouped Added/Changed/Fixed/…; entries per .claude/rules/writing.md, about 25
words each) derived from the actual diff/commits — not invented.
- The matching docs-app updates: a new
<Section> for app/(site)/docs/changelog/page.tsx, the
what's-new highlights, and any install/banner version strings.
Phase 3 — Present & approve (gate)
Relay the plan concisely: proposed version, the drafted changelog, the bump list, and the
"leave historical" list. Use AskUserQuestion to approve as-is, edit the changelog copy, set the
release date (or keep Unreleased), or narrow scope (e.g. skip docs-app this round). Capture the approved version + final changelog
text. Do not skip this gate unless --apply-all was passed.
Phase 4 — Apply
Dispatch build-release again in apply mode with the approved version and final changelog.
It edits root package.json, README (badge + affected sections), CHANGELOG.md, and the
docs-app changelog/what's-new/version strings — bumping only current-version references and
leaving historical ones intact. docs-app files follow docs-app's own conventions and stay CRLF.
After the docs-app timepicker-ui dependency is updated (the user runs the install), the main
agent runs node docs-app/scripts/generate-css-reference.mjs and reviews the diff of
docs-app/lib/generated/css-reference.json.
Phase 5 — Sanity build & report
- Run the full suite and a build to confirm nothing broke:
cd app && npm test && npm run build:prod,
then /verify --full. Report pass/fail with the real output — never claim green without running
it. Skip a step only when the user says so.
- Summarize: new version, every file changed (grouped: package.json / README / CHANGELOG /
docs-app), and confirmation that
exports / sideEffects / entry points / zero-dependency /
tree-shaking are intact.
- Propose the release commands for the user to run — git is theirs:
a commit message, the tag (
vX.Y.Z), and the publish step (npm publish). Do NOT run
git add/commit/tag/push or npm publish yourself.
Guardrails
- One source of truth for the version (root
package.json). NEVER touch the version field of
app/package.json or docs-app/package.json — those are separate apps, not the library. In
docs-app/ a release only edits content that references the library version (changelog /
what's-new / install snippets), never the docs site's own version.
- Never rewrite historical version references or past changelog entries.
- Keep
.claude/, library and docs-app files CRLF.
- This skill prepares a release; it does not execute git or npm publish.