Git Release Workflow

Purpose

Executes the git operations for a release: running pre-release hooks, staging modified files, creating a commit with proper formatting and attribution, creating an annotated git tag with configurable patterns, and running post-release hooks. Works with any project type.

Input Context

Requires:

• Project Configuration: Output from

  detect-project-type

  skill
• Version: New version string (e.g., "1.2.0")
• Commit Message: Pre-formatted commit message (from changelog-update skill)
• Files to Stage: List of modified files to include in commit

Workflow

1. Load Configuration

Use configuration from

detect-project-type

:

• tag_pattern

  - Pattern for git tag (e.g., "v{version}", "{package}-v{version}")

• tag_message

  - Message template for annotated tag

• commit_message_template

  - Template for commit message

• pre_release_hook

  - Script to run before git operations (optional)

• post_release_hook

  - Script to run after successful push (optional)

2. Run Pre-Release Hook

If

preReleaseHook

is configured, execute it before any git operations:

if [ -n "$pre_release_hook" ]; then
  echo "Running pre-release hook: $pre_release_hook"

  if [ -x "$pre_release_hook" ]; then
    # Run hook and capture output
    if ! hook_output=$($pre_release_hook 2>&1); then
      # Hook failed - abort release
      echo "✗ Pre-release hook failed:"
      echo "$hook_output"
      exit 1
    else
      echo "✓ Pre-release hook succeeded"
      echo "$hook_output"
    fi
  else
    echo "⚠️  Pre-release hook not executable: $pre_release_hook"
    exit 1
  fi
fi

Common pre-release hook use cases:

• Run tests:

  npm test

  ,

  cargo test

  ,

  go test ./...

• Build project:

  npm run build

  ,

  cargo build --release

• Run linters:

  npm run lint

  ,

  cargo clippy

• Generate documentation:

  npm run docs

• Validate package:

  npm pack --dry-run

  ,

  twine check dist/*

3. Stage Modified Files

Stage all files that were modified during the release process:

git add {file1} {file2} {file3} ...

Files typically include:

• Version configuration files (plugin.json, marketplace.json, variants.json)
• Changelog files (CHANGELOG.md)
• Documentation files (README.md)

Verify staging succeeded:

git status --short

2. Create Commit

Create commit with the provided message, ensuring proper formatting and attribution:

git commit -m "$(cat <<'EOF'
{commit-message}

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
EOF
)"

Commit message format:

Release {scope} v{version}

{changelog-body}

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Important: Use heredoc (

<<'EOF'

) to preserve formatting and handle multi-line messages correctly.

Capture commit hash:

git rev-parse HEAD

5. Create Annotated Git Tag

Create an annotated tag (not lightweight) using configurable pattern from configuration:

Build tag name from pattern:

# Get pattern from config (e.g., "v{version}", "{package}-v{version}")
tag_pattern="v{version}"  # from config

# Replace placeholders
tag_name="${tag_pattern//\{version\}/$new_version}"

# For monorepo/plugins, also replace {package}
if [[ "$tag_pattern" == *"{package}"* ]]; then
  tag_name="${tag_name//\{package\}/$package_name}"
fi

# Examples:
# Pattern: "v{version}" → Tag: "v1.2.0"
# Pattern: "release-{version}" → Tag: "release-1.2.0"
# Pattern: "{package}-v{version}" → Tag: "my-lib-v1.2.0"

Build tag message from template:

# Get template from config (default: "Release v{version}")
tag_message_template="Release v{version}"  # from config

# Replace placeholders
tag_message="${tag_message_template//\{version\}/$new_version}"
tag_message="${tag_message//\{package\}/$package_name}"

# Example: "Release v1.2.0"

Create tag:

git tag -a "$tag_name" -m "$tag_message"

Verify tag created:

if git tag -l "$tag_name" | grep -q "$tag_name"; then
  echo "✓ Created tag: $tag_name"
else
  echo "✗ Failed to create tag: $tag_name"
  exit 1
fi

4. Prepare Push Information

Do NOT automatically push. Instead, prepare information for the command to display:

# Get remote URL
git remote get-url origin

# Get current branch
git branch --show-current

# Show what will be pushed
git log origin/{branch}..HEAD --oneline

Return push command for user to execute:

git push origin {branch} --follow-tags

Or if using

--force-with-lease

after rebase:

git push origin {branch} --follow-tags --force-with-lease

6. Run Post-Release Hook (After Push)

Note: This section is executed by the

/release

command AFTER successful push, not within this skill.

If

postReleaseHook

is configured, execute it after git push succeeds:

if [ -n "$post_release_hook" ]; then
  echo "Running post-release hook: $post_release_hook"

  if [ -x "$post_release_hook" ]; then
    # Run hook and capture output
    if ! hook_output=$($post_release_hook 2>&1); then
      # Hook failed - warn but don't abort (release already pushed)
      echo "⚠️  Post-release hook failed:"
      echo "$hook_output"
      # Continue anyway - release is already public
    else
      echo "✓ Post-release hook succeeded"
      echo "$hook_output"
    fi
  else
    echo "⚠️  Post-release hook not executable: $post_release_hook"
  fi
fi

Common post-release hook use cases:

• Publish package:

  npm publish

  ,

  cargo publish

  ,

  twine upload dist/*

• Deploy to CDN/hosting:

  netlify deploy

  ,

  vercel --prod

• Send notifications:

  ./scripts/notify-slack.sh

  ,

  ./scripts/post-to-discord.sh

• Update documentation site:

  ./scripts/deploy-docs.sh

• Trigger CI/CD:

  curl -X POST $CI_WEBHOOK_URL

• Create GitHub release:

  gh release create $TAG_NAME

7. Generate Summary

Collect information for post-release summary:

• Commit hash (short: first 7 characters)
• Tag name
• Files committed (count)
• Current branch
• Remote URL (if configured)

Output Format

Return:

{
  "commit_hash": "a1b2c3d",
  "commit_hash_full": "a1b2c3d4e5f6g7h8i9j0",
  "tag_name": "daily-carry-v1.2.0",
  "files_committed": [
    "plugins/daily-carry/.claude-plugin/plugin.json",
    "plugins/daily-carry/CHANGELOG.md",
    ".claude-plugin/marketplace.json"
  ],
  "files_count": 3,
  "branch": "master",
  "remote_url": "https://github.com/jayteealao/agent-skills.git",
  "push_command": "git push origin master --follow-tags",
  "success": true
}

Examples

Example 1: Plugin Release

Input:

• Scope:

  plugin:daily-carry

• Version:

  1.2.0

• Commit message:

  Release plugin:daily-carry v1.2.0
  
  Added:
  - New deployment command
  
  Fixed:
  - Git push error handling
  
  Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
  

• Files:

  ["plugins/daily-carry/.claude-plugin/plugin.json", "plugins/daily-carry/CHANGELOG.md", ".claude-plugin/marketplace.json"]

Operations:

# Stage files
git add plugins/daily-carry/.claude-plugin/plugin.json
git add plugins/daily-carry/CHANGELOG.md
git add .claude-plugin/marketplace.json

# Create commit
git commit -m "$(cat <<'EOF'
Release plugin:daily-carry v1.2.0

Added:
- New deployment command

Fixed:
- Git push error handling

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
EOF
)"

# Create tag
git tag -a "daily-carry-v1.2.0" -m "Release plugin:daily-carry v1.2.0"

Output:

{
  "commit_hash": "f7e8d9c",
  "commit_hash_full": "f7e8d9c6b5a4e3d2c1b0a9f8e7d6c5b4",
  "tag_name": "daily-carry-v1.2.0",
  "files_committed": [
    "plugins/daily-carry/.claude-plugin/plugin.json",
    "plugins/daily-carry/CHANGELOG.md",
    ".claude-plugin/marketplace.json"
  ],
  "files_count": 3,
  "branch": "master",
  "remote_url": "https://github.com/jayteealao/agent-skills.git",
  "push_command": "git push origin master --follow-tags",
  "success": true
}

Example 2: Marketplace Release

Input:

• Scope:

  marketplace

• Version:

  1.1.0

• Files:

  [".claude-plugin/marketplace.json", "CHANGELOG.md", "README.md"]

Tag created:

marketplace-v1.1.0

Output:

{
  "commit_hash": "b4c5d6e",
  "tag_name": "marketplace-v1.1.0",
  "files_count": 3,
  "branch": "master",
  "push_command": "git push origin master --follow-tags",
  "success": true
}

Example 3: Variants Release

Input:

• Scope:

  variants

• Version:

  2.0.0

• Files:

  ["variants/variants.json", "variants/CHANGELOG.md"]

Tag created:

variants-v2.0.0

Error Handling

Git Add Failure

Error: File doesn't exist or permission denied

Response:

{
  "success": false,
  "error": "Failed to stage files",
  "details": "git add failed: {error-message}",
  "suggestion": "Verify files exist and are writable"
}

Git Commit Failure

Error: Nothing to commit, commit hook failed, etc.

Response:

{
  "success": false,
  "error": "Failed to create commit",
  "details": "{git-error-message}",
  "suggestion": "Check git status and pre-commit hooks"
}

Rollback: If commit fails, unstage files:

git reset HEAD

Git Tag Failure

Error: Tag already exists, invalid tag name, etc.

Response:

{
  "success": false,
  "error": "Failed to create tag",
  "details": "{git-error-message}",
  "commit_hash": "f7e8d9c",
  "suggestion": "Tag may already exist. Use 'git tag -d {tag}' to delete or choose different version"
}

Rollback: Offer to undo commit:

git reset --soft HEAD~1

No Remote Configured

Warning: (non-blocking)

Response:

{
  "success": true,
  "commit_hash": "f7e8d9c",
  "tag_name": "daily-carry-v1.2.0",
  "remote_url": null,
  "push_command": null,
  "warning": "No git remote configured - cannot push"
}

Integration Notes

This skill is invoked by the

/release

command in Phase 6. The command will:

1. Execute git operations via this skill
2. Display commit hash and tag name
3. Prompt user to push with provided command
4. If user confirms, execute push:

   git push origin {branch} --follow-tags
   

5. Proceed to Phase 7 for verification

Git Best Practices

• Always use annotated tags (

  -a

  flag) for releases (contains metadata)
• Use heredoc for multi-line commit messages to preserve formatting
• Include Co-Authored-By for attribution when Claude assists
• Use

  --follow-tags

  when pushing to include annotated tags
• Never force push unless explicitly requested and using

  --force-with-lease

• Verify operations after each git command (check status, verify tag exists)

Linear History Maintenance

To maintain linear git history:

• Commit directly to master/main (no merge commits)
• If on feature branch, rebase onto master first
• Use fast-forward merges only
• Avoid

  git merge --no-ff