ship

Files (6)

• SKILL.md
• backfill-pr.sh · scripts/
• changelog-bump.sh · scripts/
• detect-gates.sh · scripts/
• pr.sh · scripts/lib/
• preflight.sh · scripts/

SKILL.md (first lines)

# Ship

Pre-flight checklist that validates the branch, runs quality gates, updates documentation and changelog, and opens a pull request.

**GitHub is the primary host; Azure DevOps is secondary.** The scripts detect the provider from the git remote (`github.com` vs `dev.azure.com`). If `origin` is not a GitHub remote, do not use `gh` — even when the remote is ambiguous or a script falls back to GitHub.

## Workflow overview

```
- [ ] Step 0: Defer to the repository (repo ship skill; skip gh if origin is not GitHub)
- [ ] Step 1: Verify CLI tools and host auth (GitHub or Azure DevOps)
- [ ] Step 2: Preflight (rebase, branch, existing PR, provider)
- [ ] Step 3: Quality gates (lint → typecheck → test → build)
- [ ] Step 4: Documentation (README.md, AGENTS.md)
- [ ] Step 5: Changelog bump
- [ ] Step 6: Push and open or update PR
- [ ] Step 7: Post-flight report
```

## Script path placeholder

`$SCRIPTS` is a **placeholder** for the absolute path to the `scripts/` directory next to this file — not a predefined shell or PowerShell variable. Resolve it before running any command:

- **bash/zsh**: `SCRIPTS=/abs/path/to/scripts`
- **PowerShell**: `$SCRIPTS = 'C:\abs\path\to\scripts'`

## Running helper scripts (cross-platform)

The helper scripts (`preflight.sh`, `detect-gates.sh`, `changelog-bump.sh`, `backfill-pr.sh`) are bash and require `bash`, `jq`, `node`, and `git` on PATH. PR operations also need `gh` (GitHub) and/or `az` (Azure DevOps), depending on the repo remote. If `origin` is not a GitHub remote, do not use `gh`.

- **macOS / Linux**: run directly — e.g. `bash "$SCRIPTS/preflight.sh"`.
- **Windows (PowerShell)**: use **Git Bash**, not WSL `bash.exe` (which cannot see Windows-installed tools). Discover Git Bash from the git install, then invoke each script through it:

```powershell
$gitRoot = Split-Path (Split-Path (Get-Command git).Source)   # e.g. C:\Program Files\Git
$bash = Join-Path $gitRoot 'bin\bash.exe'
& $bash "$SCRIPTS/preflight.sh"   # repeat per script + args
```

If `bin\bash.exe` does not exist under the git root, stop and tell the user to install [Git for Windows](https://git-scm.com/downloads) (bundles Git Bash).

Throughout the steps below, every `$SCRIPTS/<name>.sh` reference means run that script using the OS-appropriate invocation above.

## Step 0 — Defer to the repository

If the repository has its own ship skill at the repository root (`.agents/skills/ship/SKILL.md` or `.cursor/skills/ship/SKILL.md`), follow that skill instead and stop here.
If `origin` is not a GitHub remote, do not use `gh`.

## Step 1 — Prerequisites

Verify that all required CLI tools are installed and authenticated before proceeding.

**Always required:**

| Tool | Purpose |
| --- | --- |
| `git` | Branch ops, commits, push |
| `jq` | JSON parsing in shell scripts |
| `node` | Inline JS for changelog and gates |

**Check core tools:**

- **macOS / Linux (bash/zsh)**: `command -v git && command -v jq && command -v node`
- **Windows (PowerShell)**: `'git','jq','node' | ForEach-Object { if (-not (Get-Command $_ -ErrorAction SilentlyContinue)) { "MISSING: $_" } }`

If any core tool is missing, stop and tell the user which tool(s) need to be installed.

**Host-specific tools** — check only the provider that matches the repo (see [Provider detection](#provider-detection)). If `origin` is not a GitHub remote, do not install, auth-check, or invoke `gh`.

| Provider | Tool | Install hint |
| --- | --- | --- |
| GitHub | `gh` | macOS: `brew install gh` · [cli.github.com](https://cli.github.com) |
| Azure DevOps | `az` | macOS: `brew install azure-cli` · [aka.ms/azcli](https://aka.ms/azcli) |

**Confirm auth for the detected provider:**

- **GitHub**: `gh auth status` — if no active account, instruct the user to run `gh auth login`. Skip this when `origin` is not a GitHub remote.
- **Azure DevOps**: `az account show` (run `az login` if it errors) and `az extension show --name azure-devops` (run `az extension add --name azure-devops` if missing).

If the remote is ambiguous and both hosts are plausible, verify auth for whichever provider you will use in Step 6. Prefer GitHub when both are available **and** `origin` is a GitHub remote. If `origin` is not a GitHub remote, do not use `gh`.

## Provider detection

The preflight script sets a top-level `provider` field (`"github"` or `"azure"`) by inspecting `git remote get-url origin`:

| Remote pattern | Provider |
| --- | --- |
| `github.com`, `git@github:` | GitHub |
| `dev.azure.com`, `visualstudio.com`, `ssh.dev.azure.com` | Azure DevOps |
| Other / unknown | Do not use `gh`. Try Azure DevOps if plausible; otherwise stop — unsupported host |

Use the `provider` field (and `pr.provider` when a PR exists) in Step 6 to pick the correct create/update commands. If `origin` is not a GitHub remote, do not treat `provider` as GitHub and do not use `gh`.

The `pr` object is normalized across hosts: `provider`, `id`, `number`, `title`, `url`. For GitHub, `id` and `number` are the same PR number. For Azure DevOps, both are the pull request ID.

## Step 2 — Preflight

Run `$SCRIPTS/preflight.sh` and parse the JSON output. This fetches the default branch, rebases, checks for uncommitted changes, counts commits ahead, detects the provider, and checks for an existing PR — all in one call.

- If `uncommittedChanges` is `true`, stop and ask the user to commit or stash.
- If `onDefaultBranch` is `true`, create a new branch:
  - Analyze the committed changes to determine the type of work.
  - Pick the appropriate prefix from the table below.
  - Generate a short, descriptive slug from the changes (e.g. `feature/add-team-cadence-grid`).
  - Run `git checkout -b <prefix>/<slug>`.
- If `rebaseStatus` is `"conflicts"`, stop and report the conflicting files from `conflictFiles`. Do not attempt to resolve merge conflicts automatically.
- If `rebaseStatus` is `"clean"` or `"skipped"`, proceed.
- If `commitsAhead` is `0`, stop — there is nothing to ship.

**Branch prefixes:**

| Prefix | Use when |
| --- | --- |
| `feature/` | New functionality or capabilities |
| `fix/` | Bug fixes |
| `chore/` | Maintenance, dependency updates, config changes |
| `refactor/` | Code restructuring with no behavior change |
| `docs/` | Documentation-only changes |
| `test/` | Adding or updating tests with no production code changes |

From jcottam/agent-resources, MIT.

More from jcottam/agent-resources