chore: add cut-release-tag agent skill

[ericksoa]

Summary

Adds a /cut-release-tag agent skill that walks through creating annotated semver tags on main. The skill:

• Fetches the latest semver tag and computes patch/minor/major bump options
• Prompts for which bump (patch default)
• Shows the changelog since the last tag
• Creates an annotated tag + moves the latest floating tag
• Pushes both

Tested live — used it to cut v0.0.3 just now.

Summary by CodeRabbit

• Documentation
  • Added release tagging workflow documentation with step-by-step instructions for semantic version management, including tag creation, changelog reference points, and verification checks.

[coderabbitai]

📝 Walkthrough

Walkthrough

A new skill document was added at .agents/skills/cut-release-tag/SKILL.md that defines a complete release tagging workflow. The process covers fetching remote tags, determining version bumps via semantic versioning, confirming the new tag with commit details, creating and pushing annotated tags, and verifying the remote state.

Changes

Cohort / File(s)	Summary
Release Tagging Skill .agents/skills/cut-release-tag/SKILL.md	New documentation defining an end-to-end release tagging workflow, including version bump selection, tag creation, push operations, and verification steps with explicit constraints around confirmation requirements and tag management.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Poem

🐰 A hop, a tag, a version new,
Semver bumps in every hue,
From latest floating high above,
To annotated tags with love,
Release workflows, crisp and true! 🏷️

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'chore: add cut-release-tag agent skill' clearly and directly summarizes the main change: adding a new agent skill for cutting release tags.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch chore/add-cut-release-tag-skill

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (2)

.agents/skills/cut-release-tag/SKILL.md (2)

78-83: Strengthen remote verification to be deterministic

Line 79 only confirms names exist; it does not robustly prove both tags resolve to the same target commit.

Suggested verification commands

-```bash
-git ls-remote --tags origin | grep -E '(<new-version>|latest)'
-```
-
-Confirm both tags point to the same commit on the remote.
+```bash
+new_sha=$(git ls-remote --tags origin "refs/tags/<new-version>^{}" | awk '{print $1}')
+latest_sha=$(git ls-remote --tags origin "refs/tags/latest^{}" | awk '{print $1}')
+test -n "$new_sha" && test "$new_sha" = "$latest_sha"
+```
+
+Confirm command success, then report the shared SHA to the user.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.agents/skills/cut-release-tag/SKILL.md around lines 78 - 83, Replace the
current non-deterministic grep check with an explicit SHA comparison: use git
ls-remote to fetch the dereferenced tag SHAs for "refs/tags/<new-version>^{}"
and "refs/tags/latest^{}" (assign to new_sha and latest_sha), ensure both
variables are non-empty and compare them (test "$new_sha" = "$latest_sha"), and
on success print the shared SHA; update the SKILL.md section that references the
grep command accordingly so the remote tag verification is deterministic and
reports the common commit SHA.

---

19-27: Handle “no existing semver tag” explicitly

Line 23 assumes at least one prior vX.Y.Z tag. If none exists, parsing in Line 26 becomes undefined and the flow breaks.

Suggested doc addition

 Fetch all tags and find the latest semver tag:
@@
 git tag --sort=-v:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -1

Parse the major, minor, and patch components from this tag.
+If no semver tag exists, treat this as the first release and prompt for an explicit initial version (for example v0.1.0), then continue.

</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against the current code and only fix it if needed.

In @.agents/skills/cut-release-tag/SKILL.md around lines 19 - 27, The doc
currently assumes a prior semver tag when running the git commands and parsing
major/minor/patch; update the SKILL.md instructions to explicitly handle the
case where the git tag pipeline (git fetch origin --tags && git tag
--sort=-v:refname | grep -E '^v[0-9]+.[0-9]+.[0-9]+$' | head -1) returns empty
by adding a step that treats this as the first release and prompts for (or
documents choosing) an explicit initial version (e.g., v0.1.0) before attempting
to parse components; include guidance to validate the chosen initial tag format
and then proceed with the existing parse/assembly steps that extract major,
minor, and patch.

</details>

</blockquote></details>

</blockquote></details>

<details>
<summary>🤖 Prompt for all review comments with AI agents</summary>

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.agents/skills/cut-release-tag/SKILL.md:

• Around line 84-90: Update the "Important Notes" section to remove or clarify
  the blanket "Do NOT update package.json version" instruction: explicitly state
  that the repo’s pre-push hook validates the tagged vX.Y.Z against the
  package.json in the tagged commit, so authors must update package.json to
  match the tag before creating/pushing an annotated tag on origin/main (or
  document the required workflow to update package.json and commit that change
  first); also call out that failing to do this will block pushes and reference
  the "Important Notes" bullets "Do NOT update package.json version",
  "origin/main", and "latest" so readers know the exception and ordering (update
  package.json → commit → tag → push).

---

Nitpick comments:
In @.agents/skills/cut-release-tag/SKILL.md:

• Around line 78-83: Replace the current non-deterministic grep check with an
  explicit SHA comparison: use git ls-remote to fetch the dereferenced tag SHAs
  for "refs/tags/^{}" and "refs/tags/latest^{}" (assign to new_sha
  and latest_sha), ensure both variables are non-empty and compare them (test
  "$new_sha" = "$latest_sha"), and on success print the shared SHA; update the
  SKILL.md section that references the grep command accordingly so the remote tag
  verification is deterministic and reports the common commit SHA.
• Around line 19-27: The doc currently assumes a prior semver tag when running
  the git commands and parsing major/minor/patch; update the SKILL.md instructions
  to explicitly handle the case where the git tag pipeline (git fetch origin
  --tags && git tag --sort=-v:refname | grep -E '^v[0-9]+.[0-9]+.[0-9]+$' | head
  -1) returns empty by adding a step that treats this as the first release and
  prompts for (or documents choosing) an explicit initial version (e.g., v0.1.0)
  before attempting to parse components; include guidance to validate the chosen
  initial tag format and then proceed with the existing parse/assembly steps that
  extract major, minor, and patch.

</details>

<details>
<summary>🪄 Autofix (Beta)</summary>

Fix all unresolved CodeRabbit comments on this PR:

- [ ] <!-- {"checkboxId": "4b0d0e0a-96d7-4f10-b296-3a18ea78f0b9"} --> Push a commit to this branch (recommended)
- [ ] <!-- {"checkboxId": "ff5b1114-7d8c-49e6-8ac1-43f82af23a33"} --> Create a new PR with the fixes

</details>

---

<details>
<summary>ℹ️ Review info</summary>

<details>
<summary>⚙️ Run configuration</summary>

**Configuration used**: Path: .coderabbit.yaml

**Review profile**: CHILL

**Plan**: Pro

**Run ID**: `007e707e-b747-494d-9407-bb4598c5c11e`

</details>

<details>
<summary>📥 Commits</summary>

Reviewing files that changed from the base of the PR and between b999c0e1c0a1e28533d6e04afb7bf08122b6da15 and f96bd324d7447a823992e85060a486782edd0541.

</details>

<details>
<summary>📒 Files selected for processing (1)</summary>

* `.agents/skills/cut-release-tag/SKILL.md`

</details>

</details>

<!-- This is an auto-generated comment by CodeRabbit for review status -->