agentleFS
naomiaronaomiaro/waveform-playlist/.claude/skills/release/SKILL.md

release

Skill1.7k starsChanged yesterdayMITView on GitHub

Use when versioning or publishing packages, running pnpm release:version, changeset version or publish, any npm or pnpm publish, checking a published packument, writing a chore(release) commit or creating a GitHub release - and when npm answers EOTP, E404 or E403 during a publish.

  • Commits and pushes

193 other projects use a version of this.

Trending

Quiet this year.thin dataabout the whole repository

Dec 2025: 0 mentionsJan 2026: 0 mentionsFeb 2026: 0 mentionsMar 2026: 0 mentionsApr 2026: 0 mentionsMay 2026: 0 mentionsJun 2026: 0 mentionsJul 2026: 0 mentionsAug 2026: 0 mentionsSep 2026: 0 mentionsOct 2026: 0 mentionsNov 2026: 0 mentions
Dec 2025Jun 2026Nov 2026
Mentions a month of the naomiaro/waveform-playlist repository that our weekly crawl found: only 11 in all, so this is a hint, not a trend. There is no adoption data for this file yet.

Most recently taken up by

Who's talking about naomiaro/waveform-playlist

The biggest 5 of 11 mentions linking to the repository that our crawl found. Each line is their own headline.

See all 11

Talked about on GitHub, Stack Overflow and Hacker News (11 times).

On GitHub · 8

3 more on GitHub

On Stack Overflow · 2

On Hacker News · 1

Used with

Projects with it also use create-agent-adapter, changelog-style and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • MicrosoftSkill

    create-agent-adapter

    Technical guide for creating a new Paperclip agent adapter. Use when building a new adapter package, adding support for a new AI coding tool (e.g. a new CLI agent, API-based agent, or custom process), or when modifying the adapter system. Covers the required interfaces, module structure, registration points, and conventions derived from the existing claude-local and codex-local adapters.

    Also in 5 projects that use this

  • GrinvSkill

    changelog-style

    Turn a commit range into CHANGELOG.md entries following common-changelog style. Use when finishing a PR or cutting a release, to write/fix the [Unreleased] section's entries — moving [Unreleased] under a new dated version heading is a separate, automated step (see the release skill / scripts/sync-version.ts), not this skill's job.

    Also in 4 projects that use this

  • GrinvSkill

    docs-consistency-check

    Check README/manifest.json/server.json/CHANGELOG.md/AGENTS.md and docs/*.md for drift against the actual registered tools and source. Use after adding, renaming, or removing a tool, or as part of a live-audit pass.

    Also in 4 projects that use this

  • Microsoft AzureSkill

    component-release

    Prepares a verifiable Agent Landing Zone UI release. Use for release branches, VERSION, changelog entries, tags, release notes, and compatibility evidence; never publish without explicit human approval.

    Also in 4 projects that use this

  • Microsoft AzureSkill

    documentation-consistency

    Keeps AI Landing Zone contributor, user, and operator documentation aligned with shipped Bicep behavior. Use for parameters, defaults, outputs, topology, deployment flow, operations, or releases.

    Also in 8 projects that use this

  • rivet-devSkill

    launch-graphics

    Generate agentOS marketing/launch graphics (launch & social heroes, code-snippet cards) from the committed generators in docs-internal/graphics. Use when asked to make, update, or render an agentOS launch image, social image, "agentOS Apps" graphic, or technical code-snippet image.

    Also in 3 projects that use this

  • +3 more from Grinv

The file

We split this skill into the rules it gives an agent

4 rules. 0 are common, 0 are distinctive, and 4 are very specific to this project.

  • 0

    Common

    Most of the 183 edited versions we read keep these.

  • 0

    Distinctive

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    No release is started unless the maintainer asks for one.

    line 8
  2. Very specific:

    Build before publishing: No package defines prepublish hooks — always run pnpm --filter <pkg> build before pnpm publish, or the tarball …

    line 43
  3. Very specific:

    Prerelease Tag: Use @next for prerelease versions when preparing future major releases.

    line 45
  4. Very specific:

    GitHub Release Notes: use gh release create --notes-file <path> (or gh release edit --notes-file <path>), NOT --notes "$(cat <<'EOF')".

    line 51

“Common” is measured: kept by at least 6 in 10 of the 183 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Releasing

No release is started unless the maintainer asks for one. Every PR that changes packages/*/src adds a changeset; that rule is in root CLAUDE.md.

Versioning and publishing

Stable Releases: Publish without tag to update @latest.

pnpm release:version   # changeset version — computes all bumps incl. the dependent cascade
pnpm release:publish   # pnpm build && changeset publish --no-git-tag

Version Bumping — Changesets owns the math (since 2026-07-05): every PR that changes packages/*/src adds a changeset (pnpm changeset; pick patch for @dawcore/* — zerover, never minor/major). Each package follows its own semver independently. At release time pnpm changeset version computes all bumps INCLUDING the exact-pin dependent cascade (validated against the 2026-07-05 manual closure: identical 13-package result; onlyUpdatePeerDependentsWhenOutOfRange keeps floating peer floors like dawcore's >=0.0.13 untouched; private packages excluded via privatePackages). Review the version diff, then pnpm release:publish (= pnpm build && changeset publish --no-git-tag: builds everything first — no prepublish hooks exist — then publishes topologically, skipping versions already on the registry; safe to re-run after a partial failure). Don't name a script version — pnpm version resolves to pnpm's built-in, not the script. The old pnpm version:bump (scripts/bump-version.js) is REMOVED — it synced ALL packages to one version, incompatible with independent versioning. changelog: false — the hand-written descriptive-tag GitHub release remains the record. Then the chore(release) commit + GitHub release as below. changeset version CONSUMES the .changeset/*.md files — reverting packages/*/package.json after a dry-run does NOT restore them; re-create the changeset (or revert .changeset/ too) before re-running. Validation pattern for config changes: write a throwaway changeset bumping one package, run pnpm release:version, diff the computed closure against expectation, then revert everything including .changeset/.

Independent Versioning: @dawcore/components and @dawcore/transport have their own version schemes (0.x.x), separate from the main @waveform-playlist/* packages.

First-time scoped packages: New scoped packages (@waveform-playlist/*, @dawcore/*) need --access public on first npm publish:

pnpm publish --filter @waveform-playlist/NEW-PACKAGE --no-git-checks --access public

Verifying fresh publishes: npm view caches 404s — a just-published new package can look missing for minutes. Verify with curl -s https://registry.npmjs.org/@scope%2fname instead.

Pre-publish workspace-dep sweep: for every workspace:*/workspace:^ dep of the packages being published, verify local version == registry latest (curl -s https://registry.npmjs.org/...) — a feature PR that bumps a package version without publishing it (e.g. media-element-playout 12.3.0 in #473) makes dependents' exact pins unresolvable at install time.

Hand-written peer floors are not raised by changesets: check them at every release. onlyUpdatePeerDependentsWhenOutOfRange leaves a floating floor (">=7.0.0") alone, so it goes stale without anyone noticing: on 2026-11-14 the engine's peer range on core was >=7.0.0 while it imported createSourceLoader, createValueSource, isLoadingClip and assertTrackKind, which exist only in the unreleased core 13 (four pending majors). When reviewing the output of pnpm release:version, grep each peerDependencies floor in packages/*/package.json and compare it with what the package imports at runtime from that peer; the engine's floor on core must be >=13.0.0 at the next release, and @dawcore/components' floor on core (>=12.7.0) has not been checked. Do it at the release, not earlier: a floor above the workspace's current version puts the workspace out of range until the bump (not tried).

Republish cascade is MANDATORY — never publish a package without its dependents (the outbound direction of the sweep above; AUTOMATED by changeset version since 2026-07-05 — this note is the why, and the fallback procedure if changesets is bypassed): regular workspace:* deps publish as EXACT pins in the tarball; workspace:^ peers publish as carets (verified from packuments). Publishing pkg X without republishing every published package that lists X in dependencies leaves those dependents pinning the OLD X — consumers silently install duplicate/stale copies. This happened: the core@12.5.0/ui-components@13.1.1 release skipped the cascade, so browser@15.2.0 shipped core 12.4.0 + ui-components 13.1.0 pins until the next sweep (2026-07-05) cured it. Procedure: compute the transitive exact-pin dependent closure of every bumped package (grep "<pkg-name>" across packages/*/package.json dependencies), patch-bump + republish ALL of it in topological order, then curl the new packuments and check the dependencies pins are the fresh versions. Caret peers force a republish only when the bump escapes the range (any major; ANY bump for zerover ^0.0.x peers like @dawcore/*).

workspace:* in devDependencies does NOT trigger the republish cascade — devDeps are build-time only (never published pins), so changesets correctly excludes such packages (e.g. transport/worklets in the 2026-07-12 annotation-suite release). When auditing a computed closure, check WHICH section a workspace ref lives in before suspecting a missed bump.

Security-key-only 2FA (since 2026-10-28): changeset publish cannot publish from this session. The account has no authenticator app, only a hardware key, so there is no OTP to type and npm has no TTY here — every package fails EOTP ("Open this URL in your browser to authenticate") before anything uploads, and changeset publish itself pre-prompts for a typed code. Procedure that works: pnpm release:version → review the closure → pnpm build → hand the user a dependency-ordered chain of pnpm --filter <pkg> publish --no-git-checks && … (toposort dependencies across packages/*/package.json) to paste into a REAL terminal, not the ! prompt (npm's auth-type=web opens the browser for one key tap per package) → verify from here: ~/.npm/_logs http fetch PUT 202 + verbose exit 0 per package is the immediate proof, packuments lag 3–8 minutes (poll with Cache-Control: no-cache) → chore(release) commit → GitHub release. ! npm login fixes an expired token (npm whoami E401) but does not bypass 2FA for publishing. The --otp flow below applies only if an authenticator app is added as a second 2FA method.

npm auth failures during changeset publish are disguised: an EXPIRED token surfaces as E404 Not Found - PUT … ("could not be found or you do not have permission") on every package, not as a 401 — check npm whoami first (it returns the real E401). With 2FA-for-writes enabled on the account, changeset publish spawns npm publish with no TTY, so npm can't open its OTP prompt and fails with E403 … Two-factor authentication or granular access token with bypass 2fa enabled is required — even when the user runs it themselves. Fix: pnpm exec changeset publish --no-git-tag --otp=<6-digit code> (one code covers all packages in the run), or a granular token with 2FA bypass in ~/.npmrc. Publish PUTs return 202 and packuments lag the CDN by 1–3 minutes — poll curl with Cache-Control: no-cache before concluding a publish failed (the npm debug log's http fetch PUT 202 + verbose exit 0 lines are the immediate proof).

Build before publishing: No package defines prepublish hooks — always run pnpm --filter <pkg> build before pnpm publish, or the tarball ships a stale dist/.

Prerelease Tag: Use @next for prerelease versions when preparing future major releases.

The commit, the tag and the GitHub release

  • A full release is THREE artifacts — easy to do partially: (1) npm publish (pnpm --filter <pkg> publish --no-git-checks), (2) the chore(release): pkg@x.y.z commit on main, (3) the descriptive-tag GitHub release (gh release create). "Bump and publish" naturally stops after (1)+(2) — the GitHub release is a separate step, easy to forget. Preview the tarball first with pnpm --filter <pkg> publish --no-git-checks --dry-run (shows files/version/tag/access before the irreversible publish); verify the publish landed with curl -s https://registry.npmjs.org/@scope%2fname (npm view caches 404s).
  • Release tags are descriptive, not pkg@version — feature-named (e.g. optional-playout-engines, recording-latency-config). gh release create <descriptive-tag> --target main --notes-file <path> creates the tag + release; the release commit is chore(release): pkg@x.y.z, … on main. Bumping workspace package versions does NOT change pnpm-lock.yaml.
  • GitHub Release Notes: use gh release create --notes-file <path> (or gh release edit --notes-file <path>), NOT --notes "$(cat <<'EOF')". Shell escapes in HEREDOCs mangle inline backticks and quotes inside code spans, leaving visible \" and \` in the rendered release body.
  • npm version <v> --no-git-tag-version may normalize unicode escapes in package.json (e.g. \u2014 becomes a literal —) — an extra diff line beyond version; harmless, commit it.
  • @dawcore/components has no published dependents — only website (workspace:*, unpublished) depends on it, so bumping it is a SINGLE-package release, not a workspace-pin republish cascade. Verify republish scope with grep -rl '"@dawcore/components"' packages/*/package.json before assuming the cascade.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.