agentleFS
thalissonbarbosasthalissonbarbosas/hangar/.claude/skills/release/SKILL.md

release

Skill1 starsChanged 3 months agoMITView on GitHub

Cut a Hangar release — compute the next SemVer from conventional commits since the last release, update CHANGELOG.md and the root package.json version on a release/<version> branch, and open a PR. Use when the user says 'cut a release', 'create a release', 'release X.Y.Z', 'prep the changelog', 'ship a version', or wants to roll recent commits into a tagged release. After the PR merges, run again (or follow the post-merge steps) to tag main and publish the GitHub Release.

  • Reads credentials
  • Commits and pushes

193 other projects use a version of this.

Adopted by

Most recently taken up by

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

Show its rules and text

We split this skill into the rules it gives an agent

13 rules. 0 are common, 2 are distinctive, and 11 are very specific to this project.

  • 0

    Common

    Most of the 183 edited versions we read keep these.

  • 2

    Distinctive

    This author's own choices. Worth a look.

  • 11

    Very specific

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

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

    The product is Hangar: Never reintroduce the old name "FleetView" in changelog text.

    line 32
  2. Very specific:

    Tag only a merged commit: Never push a v* tag for a release whose PR hasn't merged to main.

    line 37
  3. Very specific:

    Always run the release in a dedicated git worktree: Never do release work in the main repo checkout or inside a Hangar-managed run …

    line 40
  4. Distinctive:

    If the tree is dirty or you're not on main, stop and tell the user.

    line 65
  5. Very specific:

    If there is none, this is the first release — the range is the full history and the current package.json version is the baseline.

    line 82
  6. Very specific:

    Step 5 — Create the branch in a dedicated worktree: Do not git switch the main checkout — add a throwaway worktree for the release branch …

    line 99
  7. Very specific:

    Run every remaining Phase 1 step (screenshots, changelog, version bump, commit, push) from inside this worktree.

    line 108
  8. Very specific:

    Step 6 — Sync docs/AI_WORKFLOW.md with the implementation: Run /aiwf-sync. If it finds drift, apply the fixes before continuing — stale …

    line 113
  9. Very specific:

    Step 7 — Audit all docs for gaps and staleness: Run /docs-update. Review the findings and apply any that are clear-cut (missing features, …

    line 117
  10. Very specific:

    Step 8 — Refresh README screenshots: Run the screenshots script on alternate ports so it doesn't kill any currently-running Hangar instance:

    line 122
  11. Distinctive:

    Step 11 — Commit, push, open the PR: Use a conventional commit but a plain PR title:

    line 176
  12. Very specific:

    Run these once the Release <version> PR is merged to main.

    line 191
  13. Very specific:

    Verify package.json version equals <version> on main.

    line 200

“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

Cut a release for Hangar (thalissonbarbosas/hangar, a public, trunk-based repo).

A release here is two phases:

  1. Changelog PR — a release/<version> branch that updates CHANGELOG.md and bumps the root package.json version, opened as a PR titled Release <version>.
  2. Tag + GitHub Release — *after that PR merges to main_, tag the merge commit v<version> and publish a GitHub Release whose notes are the new changelog section.

The skill detects which phase to run: if a release/<version> PR is already open or merged for the computed version, skip ahead to tagging; otherwise start at the changelog PR.

Guardrails

  • main is trunk and must stay deployable. Branch from an up-to-date main; never commit the release directly to main. The changelog change ships as a reviewable PR like any other.
  • Versioning is SemVer, derived from conventional commits since the last v* tag:
    • a commit with ! (e.g. feat!:) or a BREAKING CHANGE: footer → major
    • any feat: → minor
    • otherwise (fix:, perf:, refactor:, …) → patch
    • 0.x caveat: while the version is 0.y.z, a breaking change bumps the minor (→ 0.(y+1).0), not the major — pre-1.0 the public API is allowed to move. State the computed version and the reason, and let the user override before writing anything.
  • The root package.json is the single source of truth for the version. Do not touch server/package.json or web/package.json — they intentionally stay at 0.1.0 and aren't part of release versioning.
  • The product is Hangar. Never reintroduce the old name "FleetView" in changelog text.
  • PR title is plain sentence case, no type prefix (repo convention): Release 0.9.0 — not chore(release): 0.9.0 and not release/0.9.0: …. The commit still uses a conventional prefix.
  • Don't bypass hooks (--no-verify). Prettier/lint-staged will reformat CHANGELOG.md on commit; let it. If a hook fails, fix the cause and commit again.
  • Tag only a merged commit. Never push a v* tag for a release whose PR hasn't merged to main.
  • Tag format is v<version> (e.g. v0.9.0). The pre-existing bundled-0.4.0 tag is legacy and not part of this scheme — ignore it for "last release" detection.
  • Always run the release in a dedicated git worktree. Never do release work in the main repo checkout or inside a Hangar-managed run worktree/live process. Create a throwaway worktree (git worktree add) for the release/<version> branch, do all changelog/version/screenshot work there, and remove it when done. This keeps the operator's main checkout and any running Hangar process untouched by the release's branch switches, commits, and screenshot server.
  • Screenshots MUST come from demo mode — never the operator's real .env. The screenshots script forces HANGAR_DEMO=1, but that alone is not enough: the Settings/Jira-connection screen historically read JIRA_BASE_URL/JIRA_EMAIL straight from .env and leaked the operator's real Jira URL and email into settings.png. After regenerating, open docs/screenshots/settings.png and confirm it shows demo.atlassian.net / demo@example.com — never a real domain or email. If it shows real data, stop and fix the demo guard before committing. Never capture screenshots against a non-demo server, and never on the default ports where the operator's live (real-data) Hangar may be running.

Steps

Phase 1 — Changelog PR

Step 1 — Preconditions. Confirm the working tree is clean and you're on main:

git status --porcelain && git rev-parse --abbrev-ref HEAD
git pull --ff-only

If the tree is dirty or you're not on main, stop and tell the user.

⚠ Never run the release inside a Hangar-managed run worktree or the current active Hangar process. Check for a HANGAR_RUN_ID env var or confirm pwd is the real repo checkout (~/dev/thalissonbarbosa/hangar), not a temp Hangar run path. If you're inside a Hangar run session, stop and instruct the user to run /release from a regular terminal.

Even from a regular terminal, all release work happens in a dedicated git worktree you create in Step 5 — not in the main checkout — so branch switches, commits, and the screenshot server never disturb the operator's main checkout or a live Hangar process.

Step 2 — Find the last release. The latest version tag:

git describe --tags --match 'v*' --abbrev=0 2>/dev/null

If there is none, this is the first release — the range is the full history and the current package.json version is the baseline.

Step 3 — Collect commits since that tag (or all commits, first release). Use first-parent so squashed PRs read as one line each:

git log <lastTag>..HEAD --first-parent --pretty='%s%n%b%x00'

Parse each commit's conventional prefix and !/BREAKING CHANGE: markers.

Step 4 — Compute the next version per the rules in Guardrails, starting from the root package.json version. Announce it to the user with the bump reason and the list of commits that drove it, e.g. "3 feats + 5 fixes since v0.8.0 → minor bump → 0.9.0. Override?" Wait for confirmation (accept an explicit override version).

Step 5 — Create the branch in a dedicated worktree. Do not git switch the main checkout — add a throwaway worktree for the release branch and cd into it for the rest of Phase 1:

git worktree add ../hangar-release-<version> -b release/<version>
cd ../hangar-release-<version>
npm run install:all   # the worktree needs its own node_modules for the screenshot server

Run every remaining Phase 1 step (screenshots, changelog, version bump, commit, push) from inside this worktree. After the PR is pushed, return to the main checkout and remove the worktree: git worktree remove ../hangar-release-<version>. Removing it before the PR merges is fine — the branch and PR live on the remote.

Step 6 — Sync docs/AI_WORKFLOW.md with the implementation. Run /aiwf-sync. If it finds drift, apply the fixes before continuing — stale AIWF docs in a release PR are confusing. If it reports "in sync", move on immediately.

Step 7 — Audit all docs for gaps and staleness. Run /docs-update. Review the findings and apply any that are clear-cut (missing features, stale config table entries, broken paths). Skip anything that needs significant new prose — that belongs in a separate docs PR, not here. If no issues are found, move on immediately.

Step 8 — Refresh README screenshots. Run the screenshots script on alternate ports so it doesn't kill any currently-running Hangar instance:

WEB_PORT=5280 PORT=3101 npm run screenshots

The script starts a demo server (HANGAR_DEMO=1), drives Playwright through the 8 key UI states, and saves PNGs to docs/screenshots/. Always use the alternate ports above — the default ports (5180/3001) may be occupied by the user's live Hangar process, and the script aggressively kills whatever is on the configured ports before starting. If screenshots fail (Playwright not installed, port conflict, etc.) print the error, skip this step, and continue — screenshots are best-effort; they do not block the release. If Playwright's Chromium browser has never been installed, the error will say so; the user can run npx playwright install chromium and re-run WEB_PORT=5280 PORT=3101 npm run screenshots manually.

⚠ Verify no real credentials leaked. Screenshots must come from demo data only, never the operator's real .env. After the script finishes, open docs/screenshots/settings.png and confirm the Jira connection shows https://demo.atlassian.net / demo@example.com — if it shows a real domain or email, the demo guard in jiraSettingsView() (server/src/config.ts) is missing or the shot was captured against a non-demo server. Stop, fix it, and re-shoot before committing. Never commit a screenshot containing a real Jira URL, email, or token.

Step 9 — Update CHANGELOG.md (create it if missing) in Keep a Changelog format. Insert a new section directly under the header, newest first. Get the date from date +%F. Group entries by category and write them as human-readable lines (rephrase terse commit subjects into clear past-tense changes; drop noise like chore: retrigger CI, merge commits, and pure formatting/test commits unless notable):

## [<version>] - <YYYY-MM-DD>

### Added

### Changed

### Fixed

### Security

Omit empty categories. If the file is new, prepend the standard preamble:

# Changelog

All notable changes to this project are documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

Step 10 — Bump the version in the root package.json to <version> (edit the "version" field only).

Step 11 — Commit, push, open the PR. Use a conventional commit but a plain PR title:

git add CHANGELOG.md package.json docs/
git commit -m "chore(release): v<version>"
git push -u origin release/<version>
gh pr create --base main --title "Release <version>" \
  --body "<summary + the new CHANGELOG section + a note that tagging happens after merge>"

Report the PR URL. Remind the user that CI (the single checks job) must pass and the PR must merge before Phase 2.

Phase 2 — Tag + GitHub Release (after the PR merges)

Run these once the Release <version> PR is merged to main.

Step 1 — Sync main and confirm the merge:

git switch main && git pull --ff-only
git log -1 --pretty='%s'   # expect the release merge / squash commit

Verify package.json version equals <version> on main.

Step 2 — Tag the merge commit and push the tag:

git tag -a v<version> -m "v<version>"
git push origin v<version>

Step 3 — Publish the GitHub Release using the changelog section as notes:

gh release create v<version> --title "v<version>" --notes "<the CHANGELOG section body>"

For a pre-1.0 (0.y.z) release, add --prerelease only if the user wants it flagged as such; otherwise a normal release is fine. Report the release URL.

Step 4 — Clean up the merged branch:

git branch -d release/<version> && git push origin --delete release/<version>

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.