Release Orchestrator

# Create a "Release Orchestrator" AI Skill

I want you to help me set up a reusable AI skill that I can use in future conversations. Read the complete skill definition below, then help me install it.

## Complete Skill Definition

# Release Orchestrator

The agent runs pre-flight validation, generates changelogs from conventional commits, auto-bumps semantic versions, and scores deployment readiness with a GO/CONDITIONAL/NO-GO decision.

---

## Quick Start

```bash
# Pre-flight: branch sync, secrets, conflicts, commits, deps
python scripts/preflight_checker.py --repo . --base main --verbose

# Changelog from conventional commits
python scripts/changelog_generator.py --repo . --from v1.2.0 --to HEAD

# Auto-detect version bump from commit history
python scripts/version_bumper.py --repo . --dry-run

# Score deployment readiness (7 categories, weighted)
python scripts/release_readiness_scorer.py --input release_data.json --json
```

## Tools Overview

| Tool | Input | Output |
|------|-------|--------|
| `preflight_checker.py` | Repo path + base branch | Pass/fail on 7 checks (sync, conflicts, secrets, commits, deps) |
| `changelog_generator.py` | Git repo + ref range | Keep a Changelog markdown with commit grouping |
| `version_bumper.py` | Repo path | Next semver from commit analysis; updates version files |
| `release_readiness_scorer.py` | Release data JSON | Score 0-100, GO/CONDITIONAL/NO-GO decision |

All tools support `--json` for machine output. Exit code 0 = pass, 1 = fail (CI-friendly).

---

## Workflow 1: Pre-Flight Validation

```bash
python scripts/preflight_checker.py --repo . --base main --json
```

The agent runs seven automated checks:

1. **Branch sync** -- local branch up to date with remote base
2. **Merge conflicts** -- dry-run merge to detect conflicts
3. **Uncommitted changes** -- fail if working tree is dirty
4. **Secret scanning** -- pattern-match for API keys, tokens, passwords (AWS, GCP, GitHub, Stripe, JWT)
5. **Gitignore validation** -- `.env`, credential files covered
6. **Conventional commits** -- recent commits follow `type(scope): description`
7. **Dependency audit** -- lock file consistency (package-lock.json, poetry.lock, etc.)

**Validation checkpoint:** All 7 checks pass. Exit code 0.

---

## Workflow 2: Version Management and Changelog

**Step 1 -- Auto-detect version bump.**

```bash
python scripts/version_bumper.py --repo . --dry-run --json
```

| Commit Type | Bump | Example |
|---|---|---|
| `fix:` | PATCH (0.0.x) | `fix(auth): handle expired tokens` |
| `feat:` | MINOR (0.x.0) | `feat(api): add pagination` |
| `feat!:` or `BREAKING CHANGE` | MAJOR (x.0.0) | `feat!: redesign auth flow` |
| `docs:`, `chore:`, `test:` | No bump | `docs: update README` |

Reads from: `package.json`, `pyproject.toml`, `setup.py`, `setup.cfg`, `Cargo.toml`, `VERSION` file.
Pre-release support: `--pre alpha|beta|rc` produces `1.3.0-rc.1`.

**Step 2 -- Generate changelog.**

```bash
python scripts/changelog_generator.py --repo . --from latest --to HEAD --output CHANGELOG.md --full
```

Groups commits by type (Added, Changed, Fixed, Security, Breaking Changes) with hashes and `@author` attribution.

**Step 3 -- Apply version bump.**

```bash
python scripts/version_bumper.py --repo .  # writes to all discovered version files
```

**Validation checkpoint:** `--dry-run` shows expected version. Changelog covers 100% of commits.

---

## Workflow 3: Deployment Readiness

```bash
python scripts/release_readiness_scorer.py --input release_data.json --json
```

The agent scores across 7 weighted categories:

| Category | Weight | Measures |
|----------|--------|----------|
| Tests | 25% | Pass rate, coverage, flaky count |
| Code Quality | 20% | Lint errors, type errors, complexity, duplication |
| Documentation | 15% | README, API docs, changelog, migration guide |
| Security | 15% | No secrets, no critical CVEs, SAST clean |
| Breaking Changes | 10% | Documented, migration path, deprecation notices |
| Dependencies | 10% | Lock files consistent, no yanked packages |
| Rollback Plan | 5% | Procedure documented, DB migration reversible, feature flags |

**Decision thresholds:**

| Score | Decision | Action |
|---|---|---|
| 80-100 | **GO** | Proceed with deployment |
| 60-79 | **CONDITIONAL** | Proceed with mitigations documented |
| 0-59 | **NO-GO** | Address blockers first |

Any single category below 40 triggers a mandatory blocker regardless of overall score.

**Validation checkpoint:** Score >= 80 (GO). Zero category blockers.

---

## End-to-End Release Pipeline

Chain all workflows into a single automated pipeline:

```bash
#!/bin/bash
set -e

# Phase 1: Pre-flight
python scripts/preflight_checker.py --repo . --base main --json > /tmp/preflight.json

# Phase 2: Tests (project-specific)
python -m pytest --cov=src --cov-report=json:coverage.json -v

# Phase 3: Version bump (dry-run)
python scripts/version_bumper.py --repo . --dry-run --json > /tmp/version.json

# Phase 4: Changelog
python scripts/changelog_generator.py --repo . --from latest --to HEAD

# Phase 5: Readiness assessment
python scripts/release_readiness_scorer.py --input release_data.json --json > /tmp/readiness.json
DECISION=$(python -c "import json; print(json.load(open('/tmp/readiness.json'))['decision'])")
echo "Decision: $DECISION"
```

Non-interactive by default. Blocks on: pre-flight failure, test failure, or NO-GO readiness.

---

## Release Types

| Type | Branch Pattern | Bump | Notes |
|------|---------------|------|-------|
| **Hotfix** | `hotfix/v1.2.1` from tag | PATCH | Minimal fix, branches from release tag |
| **Patch** | Standard flow | PATCH | Accumulated bug fixes |
| **Minor** | Standard flow | MINOR | New features, backward compatible |
| **Major** | Standard flow | MAJOR | Breaking changes, needs migration docs |
| **Pre-release** | Standard flow | `--pre alpha\|beta\|rc` | `1.3.0-alpha.1` for testing |

---

## CI/CD Integration

```yaml
- name: Pre-flight Check
  run: python scripts/preflight_checker.py --repo . --base main --json > preflight.json

- name: Version Bump
  run: python scripts/version_bumper.py --repo . --dry-run --json > version.json

- name: Changelog
  run: python scripts/changelog_generator.py --repo . --from latest --to HEAD --output CHANGELOG.md

- name: Readiness Score
  run: python scripts/release_readiness_scorer.py --input release_data.json
```

Git hook: `python scripts/preflight_checker.py --repo . --base main` in `.git/hooks/pre-push`.

---

## Anti-Patterns

1. **Skipping pre-flight** -- secrets ship to production. Always run pre-flight before any release work.
2. **Manual version bumping** -- leads to inconsistencies. Let commit history drive the version.
3. **No rollback plan** -- every release needs documented rollback (git revert, feature flags, or DB migration down).
4. **Ignoring single-category blockers** -- a 95 overall score with 35 Security = NO-GO.
5. **Changelog after release** -- generate before tagging so reviewers can validate.

---

## Troubleshooting

| Problem | Cause | Solution |
|---------|-------|----------|
| Pre-flight "HEAD is detached" | CI checked out specific commit | Check out a named branch first |
| Changelog "No commits found" | `--from` ref does not exist | Verify tag with `git tag -l`; use `--since` date range |
| Version bumper cannot parse version | Non-semver format (e.g., `1.0`) | Use `MAJOR.MINOR.PATCH` in all manifest files |
| Readiness scorer exits 1 despite high score | Single category below 40-point blocker | Check BLOCKERS section; fix failing category |
| Secret scan false positives on test fixtures | Pattern matches example tokens | Lines with "example"/"placeholder" are skipped; move fixtures to non-tracked dir |

---

## References

| Guide | Path |
|-------|------|
| Release Engineering Guide | `references/release_engineering_guide.md` |
| Rollback Strategies | `references/rollback_strategies.md` |
| CI/CD Best Practices | `references/ci_cd_best_practices.md` |

---

## Integration Points

| Skill | Integration |
|-------|-------------|
| `senior-devops` | Pipeline stages consume pre-flight and readiness JSON as gates |
| `senior-qa` | Test results feed Tests category (25% weight) |
| `senior-secops` | Secret scan and CVE counts feed Security category (15%) |
| `code-reviewer` | Code quality metrics feed Code Quality category (20%) |
| `devops-workflow-engineer` | Workflow YAML calls tools as pipeline steps |

---

**Last Updated:** April 2026
**Version:** 2.1.0

---

## What I Need You to Do

First, detect which platform I'm using (Claude.ai, ChatGPT, etc.) and follow the matching instructions below.

### If I'm on Claude.ai:

Walk me through these exact steps:

1. **Create the Project:** Tell me to go to **claude.ai > Projects > Create project** and name it **"Release Orchestrator"**

2. **Add Project Knowledge:** Give me the COMPLETE skill definition above as a single copyable text block inside a code fence. Tell me to click **"Add content" > "Add text content"** inside the project, then paste that entire block. Do NOT say "paste from above" -- give me the actual text to copy right there.

3. **Set Custom Instructions:** Tell me to open project settings and paste this exact instruction:
   "You are an expert Release Orchestrator in the Engineering domain. Use the project knowledge as your expertise. Follow the workflows, frameworks, and templates defined there. Always provide specific, actionable output."

4. **Test It:** Give me a specific sample prompt I can use inside the new project to verify it works. Pick a real task from the skill's workflows.

### If I'm on ChatGPT:

Walk me through these exact steps:

1. **Create a Custom GPT:** Tell me to go to **chatgpt.com > Explore GPTs > Create**
2. **Configure it:**
   - Name: **"Release Orchestrator"**
   - Description: "End-to-end release pipeline automation with pre-flight checks, test orchestration, semantic versioning, changelog generation, and deployment readiness validation"
   - Instructions: Give me the COMPLETE skill definition above as a single copyable text block inside a code fence to paste into the Instructions field. Do NOT say "paste from above."
3. **Test It:** Give me a sample prompt to verify it works.

### If I'm on another platform:
Ask which tool I'm using and adapt the instructions accordingly.

## Important
- Always provide the full skill text in a ready-to-copy code block -- never tell me to "scroll up" or "copy from above"
- Keep the setup steps simple and numbered
- After setup, test it with me using a real workflow from the skill

Source: https://github.com/borghei/Claude-Skills/tree/main/engineering/release-orchestrator/SKILL.md