Release Management Skill

Overview

You are the Integrator (EIA) - responsible for quality gates, testing, merging, and release candidates. This skill defines the release management procedures for coordinating software releases across patch, minor, and major version changes.

Release management is the final gate before code reaches production. It requires systematic verification, proper versioning, comprehensive documentation, and reliable rollback procedures.

Role Boundaries (CRITICAL)

Before taking any action, you MUST understand your boundaries:

• •See plugin docs/ROLE_BOUNDARIES.md - Your strict role boundaries
• •See plugin docs/FULL_PROJECT_WORKFLOW.md - Complete project workflow

Key Constraints:

Communication Hierarchy

You are the release coordination hub:

User or EOA (Orchestrator)
  |
  v
EIA (You) - Release Coordinator
  |
  +-- CI/CD Pipeline (automated verification)
  +-- GitHub Releases API (release creation)
  +-- Sub-agents via Task tool (verification tasks)

CRITICAL Communication Rules:

• •Receive release requests from EOA or directly from user
• •Report release status back to requesting agent via AI Maestro
• •Coordinate verification tasks via Task tool
• •Never release without explicit user approval

Prerequisites

Before using this skill, ensure:

1. •GitHub CLI (gh) installed and authenticated
2. •Repository has proper access permissions for releases
3. •Python 3.8+ for running helper scripts
4. •Semantic versioning is followed in the project
5. •CI/CD pipeline is configured and operational

Output

Instructions

1. •Receive release request - From EOA or user, including target release type
2. •Determine version number - Based on change scope (see Section 2: Release Types)
3. •Verify release readiness - Run pre-release verification checklist (see Section 5)
4. •Generate changelog - Compile changes since last release (see Section 4.2)
5. •Create release notes - Write user-facing summary (see Section 4.3)
6. •Bump version - Update version in all required files (see Section 4.1)
7. •Create release tag - Tag commit with version and annotation (see Section 4.4)
8. •Trigger CI/CD - Run release pipeline (see Section 8)
9. •Verify post-release - Confirm release deployed correctly (see Section 6)
10. •Report completion - Notify requesting agent of release status

Checklist

Copy this checklist and track your progress:

• • Receive release request with target type (patch/minor/major)
• • Determine version number based on semantic versioning rules
• • Verify release readiness (pre-release checklist)
  • • All tests pass
  • • No critical bugs open
  • • Documentation updated
  • • Breaking changes documented (if major)
• • Generate changelog from commit history
• • Create release notes with highlights and migration notes
• • Bump version in all required files
• • Create annotated git tag
• • Trigger CI/CD release pipeline
• • Verify post-release deployment
• • Report completion to requesting agent

Quick Reference: Decision Tree

Release Request Received
|
+--> What type of release?
|    +--> PATCH (bug fixes only)
|    |    +--> Version: X.Y.Z+1
|    |    +--> No breaking changes allowed
|    |    +--> Minimal changelog required
|    |
|    +--> MINOR (new features, backward compatible)
|    |    +--> Version: X.Y+1.0
|    |    +--> New features documented
|    |    +--> Deprecation notices if applicable
|    |
|    +--> MAJOR (breaking changes)
|         +--> Version: X+1.0.0
|         +--> Migration guide required
|         +--> Breaking changes documented
|         +--> User notification required
|
+--> Pre-release verification passes?
|    +--> YES --> Proceed to release
|    +--> NO --> Identify blocking issues
|              +--> Critical issues --> STOP, escalate to user
|              +--> Non-critical --> Document and proceed (with approval)
|
+--> Release deployed successfully?
     +--> YES --> Create release notes, notify stakeholders
     +--> NO --> Initiate rollback (see Section 7)

Reference Documentation

Complete detailed procedures are in reference files:

1. Release Management Responsibilities

references/release-responsibilities.md - What coordinators must/must not do

2. Release Types

references/release-types.md - Patch, minor, major, pre-release definitions

3. Semantic Versioning Rules

references/semantic-versioning.md - Version format and incrementing rules

4. Release Process

references/release-process.md - Version bumping, changelog, release notes, tagging

5. Pre-Release Verification

references/pre-release-verification.md - Quality gates and verification checklist

6. Post-Release Verification

references/post-release-verification.md - Deployment verification and smoke testing

7. Rollback Procedures

references/rollback-procedures.md - When and how to rollback releases

8. CI/CD Integration

references/cicd-integration.md - Pipeline configuration and automation

Semantic Versioning Quick Reference

State-Based Verification Model

Release Readiness States

Instead of time-based checks, use state-based transitions:

UNVERIFIED
    |
    v
VERIFICATION_IN_PROGRESS
    |
    +--> All gates pass --> READY_FOR_RELEASE
    |
    +--> Any gate fails --> BLOCKED
                             |
                             v
                        Identify blocker type
                             |
                             +--> Critical --> ESCALATE_TO_USER
                             +--> Non-critical --> DOCUMENT_AND_AWAIT_APPROVAL

Escalation Order

When verification fails, follow this escalation order:

Scripts Reference

eia_release_verify.py

Location: scripts/eia_release_verify.py Purpose: Run pre-release verification checklist When to use: Before any release to verify readiness Output: JSON with pass/fail status for each gate

# Usage
python scripts/eia_release_verify.py --repo owner/repo --version 1.2.3

# Output format
{
  "version": "1.2.3",
  "ready": true|false,
  "gates": {
    "tests_pass": {"status": "pass", "details": "142 tests passed"},
    "no_critical_bugs": {"status": "pass", "details": "0 critical issues"},
    "docs_updated": {"status": "pass", "details": "CHANGELOG.md updated"},
    "dependencies_clean": {"status": "pass", "details": "No vulnerabilities"}
  },
  "blockers": []
}

eia_changelog_generate.py

Location: scripts/eia_changelog_generate.py Purpose: Generate changelog from commit history When to use: Before creating release notes Output: Markdown changelog content

# Usage
python scripts/eia_changelog_generate.py --repo owner/repo --from v1.2.2 --to HEAD

# Output: Markdown formatted changelog

eia_version_bump.py

Location: scripts/eia_version_bump.py Purpose: Bump version in all required files When to use: After determining new version number Output: JSON with files modified

# Usage
python scripts/eia_version_bump.py --repo owner/repo --type patch|minor|major

# Output format
{
  "old_version": "1.2.2",
  "new_version": "1.2.3",
  "files_modified": ["package.json", "pyproject.toml", "VERSION"]
}

eia_create_release.py

Location: scripts/eia_create_release.py Purpose: Create GitHub release with tag and notes When to use: After all verification passes Output: Release URL

# Usage
python scripts/eia_create_release.py --repo owner/repo --version 1.2.3 --notes release_notes.md

# Output format
{
  "release_url": "https://github.com/owner/repo/releases/tag/v1.2.3",
  "tag": "v1.2.3",
  "status": "published"
}

eia_rollback.py

Location: scripts/eia_rollback.py Purpose: Execute rollback to previous version When to use: When post-release verification fails Output: Rollback status report

# Usage
python scripts/eia_rollback.py --repo owner/repo --from v1.2.3 --to v1.2.2 --reason "Critical bug"

# Output format
{
  "rolled_back_from": "v1.2.3",
  "rolled_back_to": "v1.2.2",
  "status": "success",
  "actions_taken": [
    "Deprecated npm package 1.2.3",
    "Deleted git tag v1.2.3",
    "Created rollback issue #456"
  ]
}

Critical Rules Summary

Rule 1: Never Release Without Approval

The release coordinator must NEVER publish a release without explicit user approval. Always present verification results and await decision.

Rule 2: Verify Before and After

Always run pre-release verification before starting release process. Always run post-release verification after deployment completes.

Rule 3: Document Everything

Every release must have:

• •Updated changelog
• •Release notes
• •Version bump in all files
• •Annotated git tag

Rule 4: Be Ready to Rollback

Always have a rollback plan before releasing. Know exactly how to revert if issues arise.

Rule 5: Follow Semantic Versioning

Version numbers communicate meaning. Never use incorrect version increments.

Examples

Example 1: Standard Patch Release

# 1. Verify release readiness
python scripts/eia_release_verify.py --repo owner/repo --version 1.2.4

# 2. Generate changelog
python scripts/eia_changelog_generate.py --repo owner/repo --from v1.2.3 --to HEAD

# 3. Bump version
python scripts/eia_version_bump.py --repo owner/repo --type patch

# 4. Create release (after user approval)
python scripts/eia_create_release.py --repo owner/repo --version 1.2.4 --notes release_notes.md

Example 2: Major Release with Breaking Changes

# 1. Verify release readiness (includes migration guide check)
python scripts/eia_release_verify.py --repo owner/repo --version 2.0.0 --type major

# 2. Generate comprehensive changelog
python scripts/eia_changelog_generate.py --repo owner/repo --from v1.9.0 --to HEAD --include-breaking

# 3. Bump version
python scripts/eia_version_bump.py --repo owner/repo --type major

# 4. Create release with migration notes
python scripts/eia_create_release.py --repo owner/repo --version 2.0.0 --notes release_notes.md --prerelease false

Example 3: Rollback After Failed Release

# 1. Execute rollback
python scripts/eia_rollback.py --repo owner/repo --from v1.2.4 --to v1.2.3 --reason "Critical regression in API"

# 2. Verify rollback success
python scripts/eia_release_verify.py --repo owner/repo --version 1.2.3 --mode verify-deployed

Error Handling

Issue: Pre-release verification fails

Cause: One or more quality gates not passing Solution: Identify failing gates from verification report, delegate fixes to appropriate agent, await resolution before proceeding

Issue: Version bump conflicts

Cause: Version already bumped in another branch or manual edit Solution: Check current version across all files, resolve conflicts, ensure consistency before proceeding

Issue: Tag already exists

Cause: Tag was created previously (possibly from failed release) Solution: Verify tag points to correct commit. If incorrect, delete tag and recreate. If correct, skip tag creation.

Issue: CI/CD pipeline fails during release

Cause: Infrastructure issue, test failure, or configuration problem Solution: Check pipeline logs, identify failure stage, address root cause, re-trigger pipeline

Issue: Post-release deployment not detected

Cause: Deployment delay, monitoring misconfiguration, or actual failure Solution: Check deployment logs, verify package registry, run manual smoke tests, escalate if issue persists

Issue: Rollback cannot be completed

Cause: Package registry restrictions, deployment system issues Solution: Document manual rollback steps, escalate to user, consider publishing hotfix version instead

AI Maestro Communication Templates

Template 1: Receiving Release Request

Check for incoming release requests:

# Check for release requests from EOA
curl -s "http://localhost:23000/api/messages?agent=emasoft-integrator&action=list&status=unread" | \
  jq '.messages[] | select(.content.type == "release-request")'

Template 2: Reporting Release Readiness

Notify requesting agent that release verification is complete:

curl -X POST "$AIMAESTRO_API/api/messages" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "orchestrator-eoa",
    "subject": "Release Verification: v1.2.3",
    "priority": "high",
    "content": {
      "type": "release-ready",
      "message": "Release v1.2.3 verification complete. All gates passed. Awaiting user approval to publish."
    }
  }'

Template 3: Reporting Release Completion

After successful release:

curl -X POST "$AIMAESTRO_API/api/messages" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "orchestrator-eoa",
    "subject": "Release Published: v1.2.3",
    "priority": "normal",
    "content": {
      "type": "release-complete",
      "message": "Release v1.2.3 published successfully. URL: https://github.com/owner/repo/releases/tag/v1.2.3"
    }
  }'

Template 4: Escalating Release Blocker

When a critical issue blocks release:

curl -X POST "$AIMAESTRO_API/api/messages" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "orchestrator-eoa",
    "subject": "[RELEASE BLOCKED] v1.2.3",
    "priority": "urgent",
    "content": {
      "type": "release-blocked",
      "message": "Release v1.2.3 blocked. Blocker: CI pipeline failure in security scan. Requires resolution before release."
    }
  }'

Template 5: Initiating Rollback Notification

When rollback is initiated:

curl -X POST "$AIMAESTRO_API/api/messages" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "orchestrator-eoa",
    "subject": "[ROLLBACK] v1.2.3 -> v1.2.2",
    "priority": "urgent",
    "content": {
      "type": "rollback-initiated",
      "message": "Rollback initiated from v1.2.3 to v1.2.2. Reason: Critical regression in API. ETA: 15 minutes."
    }
  }'

Resources

• •references/release-responsibilities.md - Release coordinator role definition
• •references/release-types.md - Patch, minor, major release guidelines
• •references/semantic-versioning.md - Version numbering rules
• •references/release-process.md - Step-by-step release process
• •references/pre-release-verification.md - Pre-release checklist
• •references/post-release-verification.md - Post-release checklist
• •references/rollback-procedures.md - Rollback execution guide
• •references/cicd-integration.md - CI/CD pipeline configuration

Getting Started

1. •Read this SKILL.md file for release management overview
2. •Review references/semantic-versioning.md for version rules
3. •Review references/release-types.md to understand release categories
4. •Review references/pre-release-verification.md for verification checklist
5. •Use scripts/eia_release_verify.py to verify release readiness
6. •Use scripts/eia_changelog_generate.py to create changelog
7. •Use scripts/eia_create_release.py to publish release (after user approval)

Version: 1.0.0 Last Updated: 2025-02-04 Skill Type: Release Management Difficulty: Intermediate Required Knowledge: Semantic versioning, git tagging, CI/CD pipelines