leonvanzyl/agentic-coding-starter-kit/ship-it

Ship It

Push your work to GitHub and open a pull request — handling prerequisites, branch creation, pushing, and PR generation automatically.

This skill complements checkpoint. Use checkpoint to commit locally (with quality gates), then ship-it to get the code to GitHub for review.

Instructions

Step 0: Prerequisites

Verify tooling before doing anything else.

1. GitHub CLI installed?

``bash gh --version `` If the command fails (not found):

• Detect the platform and attempt to install:
• Windows: winget install --id GitHub.cli
• macOS: brew install gh
• Linux (Debian/Ubuntu): follow the official apt instructions
• If auto-install fails, tell the user what to install and stop.

1. GitHub CLI authenticated?

``bash gh auth status ` If not authenticated, tell the user: ` GitHub CLI is not logged in. Please run this in the prompt: ! gh auth login Then re-run /ship-it. `` Stop here — do not proceed until auth is confirmed.

1. Git remote exists?

``bash git remote -v ` If no remote named origin exists, stop and tell the user: ` No git remote found. Add one with: git remote add origin https://github.com/{user}/{repo}.git ``

Step 1: Detect the Environment

Run these commands to understand the current state:

1. git branch --show-current — get the current branch name
2. Detect the default branch:

``bash gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name' ``

1. git status --porcelain — check for uncommitted changes

If there are uncommitted changes, stop and tell the user:

You have uncommitted changes. Run /checkpoint first to commit them, then /ship-it to push.

Store the default branch name for use throughout the remaining steps.

Step 2: Check for Unpushed Commits

Determine if there are commits that haven't been pushed yet.

If on a feature branch with a remote tracking branch:

git log @{upstream}..HEAD --oneline

If on a feature branch with no remote tracking branch, or on the default branch:

git log origin/{default_branch}..HEAD --oneline

If there are no unpushed commits, stop and tell the user:

Nothing to ship — all commits are already pushed.

Save the list of unpushed commit messages for use in later steps.

Step 3: Handle Branching

If already on a feature branch (not the default branch):

• Stay on it. No branching needed.
• Skip to Step 4.

If on the default branch:

• Generate a branch name from the unpushed commit messages:
• Read the commit subjects
• Derive a kebab-case branch name with a conventional prefix: feat/, fix/, refactor/, chore/, docs/ based on the commit content
• Keep it short (3-5 words max after the prefix), e.g., feat/add-user-auth, fix/login-redirect-loop
• Strip special characters, lowercase everything
• Create and switch to the new branch:

``bash git checkout -b {branch_name} ``

• Tell the user: Created branch {branch_name}

Step 4: Push to Origin

git push -u origin {branch_name}

If the branch already has a remote tracking branch, a regular git push is fine.

Step 5: Check for Existing PR

Before creating a new PR, check if one already exists for this branch:

gh pr view --json number,url,title,state 2>/dev/null

If a PR already exists and is open:

• Do NOT create a new one
• Skip to Step 7 and report the existing PR with a note that new commits were pushed.

If no PR exists (or it is closed/merged), proceed to Step 6.

Step 6: Create the Pull Request

Generate the PR title and body from the unpushed commits:

• Title: concise summary under 70 chars. If single commit, use its subject. If multiple, synthesize a short summary. Imperative mood.
• Body: TL;DR of the changes in 2-4 bullet points max.

gh pr create --base {default_branch} --head {branch_name} --title "{title}" --body "$(cat <<'EOF'
## Summary
{2-4 bullet points}
 
---
🤖 Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"

Step 7: Report

Display the result clearly:

Shipped to GitHub:
  Branch: {branch_name}
  PR: #{number} — {title}
  URL: {url}

Important

• Do NOT run lint, type-check, or build — that is checkpoint's job
• Do NOT commit anything — only push existing commits and create a PR
• If the user has uncommitted changes, tell them to run /checkpoint first
• Keep the PR body short — a TL;DR, not an essay
• Always check for an existing open PR before creating a new one to avoid duplicates
• Detect the default branch dynamically — do not hardcode main or master
• When creating a branch from the default branch, use conventional prefixes (feat/, fix/, etc.) with kebab-case names
• Never run destructive git operations (no --force, no reset --hard)
• If gh is not installed or authenticated, help the user get set up before proceeding