Tag Release

Core Question

Is the repository in a verified release-ready state for the requested Git tag action, and what confirmation is required before local or remote tag mutation?

When To Use

Use this skill when the user asks to:

• inspect release tag readiness,
• choose or validate a tag name,
• create a local annotated or signed Git tag,
• verify an existing tag,
• push a Git tag after explicit confirmation.

When Not To Use

Do not use this skill for version-file edits, changelog edits, release-note drafting, package publication, hosted release publication, or tag recovery.

Route to:

• version-bump for version decisions or local version file edits.
• changelog-maintenance for changelog file changes.
• release-notes for release-note text.
• undo-recover for deleting, replacing, retagging, or recovering tags.
• a future publish-release skill or manual workflow for package or hosted release publication.

Required Evidence

Before tag mutation, inspect or establish:

• git status --short --branch,
• current branch and target commit SHA,
• version files and expected tag name,
• changelog or release notes when relevant,
• existing local and remote tags,
• latest tag and release range,
• project tag policy for annotated, lightweight, or signed tags,
• CI/build/test status when available,
• remote configuration when push is requested.

Operating Contract

You MAY:

• inspect release readiness and tag state,
• propose a tag name from evidenced version policy,
• create a local annotated or signed tag when explicitly requested and verified,
• push a tag only after exact remote/shared confirmation,
• verify tag object, annotation, target SHA, and remote ref.

You MUST:

• inspect clean/dirty state before tag creation,
• verify version/tag consistency,
• check whether tag already exists,
• prefer annotated tags unless project policy says otherwise,
• gate remote tag push as R4,
• route tag deletion, replacement, retagging, and recovery to undo-recover.

You MUST NOT:

• infer a tag name without version or user evidence,
• tag a dirty tree without explicit risk acceptance,
• overwrite, delete, or move tags in this skill,
• publish package artifacts or hosted releases,
• push tags without exact confirmation,
• perform remote/shared mutation without verification.

State / Risk Table

Workflow

1. Identify requested tag action: inspect, plan, create local tag, or push tag.
2. Inspect status, current commit, version files, existing tags, release notes/changelog, and remote config.
3. Classify state and risk.
4. Verify tag name, target SHA, and release readiness evidence.
5. Ask for exact confirmation when local tag creation is consequential or any remote mutation is requested.
6. Create or push only the requested tag.
7. Verify local tag object and remote ref when applicable.
8. Report evidence, action, verification, and residual risk.

Decision Rules

• Prefer annotated tags unless project policy requires lightweight tags.
• Signed tags require evidence that signing is configured or a limitation note.
• Do not assume SemVer or tag prefix without project/user evidence.
• Do not tag if version files, changelog, or release notes conflict with the requested tag unless user explicitly accepts risk.
• Tag deletion, replacement, retagging, and recovery are owned by undo-recover.
• Hosted release or package publication is out of scope.
• This skill owns normal Git tag creation and push only; tag recovery/destructive tag mutation routes to undo-recover.

Workflow Guardrails

Tag Delete / Retag / Replace

Trigger:

• The requested tag already exists, or the user asks to delete, move, replace, retag, or force-update a tag.

Default: <!-- guardrail:tag-mutation.route-destructive-to-recovery -->

• Stop normal release tagging and route destructive tag recovery to undo-recover.

Must:

• Inspect local and remote tag refs before routing.
• Report the current tag target SHA and intended requested target when known.

Must not: <!-- guardrail:tag-mutation.no-create-as-retag -->

• Treat normal tag creation as permission to move or delete an existing tag.
• Run git tag -d, git tag -f, git push origin :refs/tags/, or git push --force origin tag from this skill.

Requires explicit confirmation:

• Exact tag name, current target, intended replacement or deletion, remote scope, and recovery plan in the routed undo-recover workflow.

Verification:

• Verify this skill did not mutate the existing tag.
• In the routed workflow, verify local and remote tag refs after mutation.

Tool Rules

Allowed:

• inspect status, tags, version files, changelog/release notes, remotes, and target SHA,
• create a local annotated or signed tag after explicit request and preflight,
• push a specific tag after exact confirmation.

Requires explicit confirmation:

• local tag creation when release consequence is material,
• any remote tag push,
• dirty-tree tag creation.

Forbidden in this skill:

• tag deletion,
• tag replacement,
• retagging,
• force-updating tags,
• package publication,
• hosted release publication.

Verification

Minimum verification:

• R0/R1: readiness evidence summarized.
• R2/R3: local tag exists, points to intended SHA, and has expected annotation/signature state.
• R4: remote tag exists and points to intended SHA after push.

For remote push confirmation, require:

• tag name,
• remote name,
• target commit SHA,
• whether the tag exists remotely,
• intended push operation.

Output Contract

Final response should include:

## State

- Branch, target SHA, version, tag, dirty/clean state.

## Action

- Preflight, local tag, or push action.

## Risk / Confirmation

- Risk classification and confirmation status.

## Verification

- Local tag and remote ref evidence.

## Remaining Risk

- CI, release notes, publication, or human review still needed.

Stop / Confirmation Rules

Stop when the repository state is dirty, conflicted, diverged, missing required evidence, or ambiguous in a way that could overwrite user work, invalidate the requested scope, or require a gated action.

Requires exact confirmation for:

• local release tag creation when consequence is material,
• remote tag push,
• dirty-tree tag creation.

Route tag deletion, replacement, retagging, or recovery to undo-recover, where R5 rescue/rollback planning is required.

Lazy-load References

Load:

• references/tag-policy.md for annotated, lightweight, signed, or naming policy.
• references/commands.md when command choice is needed.
• references/release-preflight.md for release-readiness checks.
• references/failure-modes.md for existing tags, mismatches, or dirty state.
• references/verification.md for local/remote tag verification.