Autoship

Autoship

Drive an npm release end to end: changeset, fix loop, push, CI watch, Version Packages PR merge, publish watch, npm verification.

• IS: the full release pipeline for an existing changesets-based npm package, from writing the changeset file to confirming the new version on the registry.
• IS NOT: opening a feature PR (use pr-creator), monitoring a feature PR for reviews, conflicts, or CI (use pr-babysitter), or scaffolding a new package (use scaffold-cli, which hands off to autoship for the first release).

The Release Loop

One workflow, two successive runs. Misreading this as two different workflows is the root cause of most autoship mistakes.

1. You push a commit containing a pending .changeset/*.md file to the default branch. 2. The release workflow runs. changesets/action sees pending changesets, runs changeset version inside CI, and opens or updates a PR titled "Version Packages" on branch changeset-release/main containing the package.json bump and CHANGELOG.md updates. 3. You merge that PR once every check is green. 4. The same workflow runs again. With no pending changesets left, the action executes its publish: script (changeset publish), which pushes tags and publishes to npm.

The local job ends at "push the changeset file". CI owns versioning and publishing; anything versioned locally breaks the loop (see Gotchas).

Reference Files

Intent Map

Safety Tiers

Invoking autoship is standing consent for the full release flow. Do not pause mid-flow for re-confirmation; gate risky steps with objective preconditions instead.

• Green (execute directly): gh run list, gh run view, gh pr list, gh pr checks, npm view, reading CI status, listing changesets, reading package.json scripts, git log, git status.
• Yellow (announce, then execute): writing changeset files, running lint/typecheck/test/format fixers, git add/commit/push, starting Monitor background watches, and gh pr merge of the Version Packages PR once its identity is confirmed and all checks are green.
• Red (explicit confirmation required): force-pushing, history rewrites, and any destructive git operation.

Workflow

Copy this checklist to track progress:

Autoship progress:
- [ ] Step 1: Create changeset (default patch)
- [ ] Step 2: Fix lint, types, tests, format
- [ ] Step 3: Commit + push changeset (do NOT run `changeset version`)
- [ ] Step 4: Monitor CI and find/merge the Version Packages PR
- [ ] Step 5: Watch the publish run, verify on npm

Step 1: Create changeset (default patch)

• Load references/changeset-and-commit.md.
• Check for existing pending changesets: ls .changeset/*.md 2>/dev/null | grep -v README.md. If any exist, ask the user whether to add another or skip.
• Default to patch. Only use minor or major on explicit user instruction.
• Write the changeset file directly (non-interactive agent mode); infer the summary from git log --oneline -10.

Step 2: Fix lint, types, tests, format

• Load references/changeset-and-commit.md (skip the changeset sections when running the "Fix compiler only" intent).
• Discover commands from package.json scripts (build, typecheck, tsc, type-check, lint, test, format); also check for Makefile, Cargo.toml, pyproject.toml, go.mod in non-npm repos.
• Run gates in order: lint, typecheck, test, format.
• Scope auto-fixers (lint --fix, format) to changed files where the tool supports it. After any fixer runs, check git status: broad fix scripts routinely reformat files outside your change (MDX is a frequent casualty). Revert unrelated churn with git restore <path> before continuing.
• On gate failure, parse output for file, line, code, and message. Fix syntax errors first, then type errors, then lint errors. Fix one root cause at a time when errors cascade.
• Retry each gate up to 5 fix iterations, reporting the remaining error count each pass. If a gate still fails after 5, stop and report (see Failure Recovery).

Step 3: Commit + push changeset

• Stage the changeset file and in-scope fixes only: git add <paths>, never git add -A. Sweep git status --porcelain for stray generated artifacts (e.g. a root schema.gql left by a pre-commit hook) and unrelated fixer churn before committing.
• Commit (chore: add <type> changeset for <package>) and push.
• Do NOT run npx changeset version locally. The pushed commit must still contain the pending .changeset/*.md file so CI's "Changeset Status" check passes and the Version Packages PR opens.

Step 4: Monitor CI and find/merge the Version Packages PR

• Load references/ci-polling.md and references/version-pr-and-publish.md.
• Start a Monitor watch scoped to the pushed commit SHA that emits a line on each state change and a TERMINAL: line when every workflow run completes. Do not stop on an idle first poll; runs take time to queue.
• On failure, classify via logs (gh run view <id> --log-failed): flaky/infra failures get gh run rerun <id> --failed up to 3 times; real failures get a fix, commit, push, and a fresh Monitor.
• Once green, find the open PR titled "Version Packages" on branch changeset-release/main. If absent, start a second Monitor that polls for it, capped at 10 minutes (the bot needs time).
• Verify ALL merge preconditions:
• PR title is exactly "Version Packages" OR head branch is changeset-release/main. Never merge any other PR.
• Every check reports bucket: pass via gh pr checks <number> --json name,bucket.
• gh pr view <number> --json mergeable reports MERGEABLE (not CONFLICTING or UNKNOWN; on UNKNOWN, wait briefly and re-query).
• Announce in one line ("Merging Version Packages PR #N: <package>@<version>"), then gh pr merge <number> --squash --delete-branch. No confirmation pause; invoking autoship is the consent.
• If any precondition fails, stop and report. Do not merge.

Step 5: Watch the publish run, verify on npm

• Load references/version-pr-and-publish.md and references/ci-polling.md.
• Merging the Version Packages PR triggers the SAME workflow again; with no pending changesets it publishes (see The Release Loop).
• Identify the workflow file in .github/workflows/ (commonly release.yml, npm-publish.yml, or publish.yml) and start a Monitor watch on its latest run on the default branch.
• On failure: report with logs and stop. Never auto-retry a publish failure; causes are real (npm auth, registry, OIDC/provenance, tag conflict).
• On success: verify with npm view <package> version against the merged package.json, stop all remaining Monitors, and report the published version. The npm view output is the completion evidence; do not report success without it.

Failure Recovery

Gotchas

• Never run `npx changeset version` locally. It consumes the .changeset/*.md file, so the pushed commit has no pending changeset, the "Changeset Status" check fails, and no Version Packages PR opens. Recovery means reverting the bump, not rerunning CI.
• Never run npm publish directly. It bypasses changesets, skips the changelog and git tags, and leaves the Version Packages PR describing a version that already shipped.
• Do not hand-edit CHANGELOG.md or the package.json version field. CI generates both inside the Version Packages PR; local edits create conflicts that make the bot PR unmergeable.
• gh pr list --json headBranch and gh pr checks --json conclusion are invalid fields and error out. Use headRefName and bucket respectively.
• Do not stop CI monitoring because the first poll shows no runs; workflows take time to queue. Stop only on a TERMINAL: line from the Monitor script.
• Keep Monitor sleep at 30 seconds or longer. Tighter polling burns GitHub API rate limit (gh api rate_limit) and can throttle the rest of the flow.
• Letting a broad format/fix script ride into the release commit ships unrelated reformatting. Scope fixers to changed files and git restore everything else first.
• git add -A silently commits pre-commit-hook artifacts (e.g. a root schema.gql). Stage explicit paths only.
• Selecting major without explicit user instruction signals breaking changes to every consumer of the package. Default to patch.

Related Skills

• scaffold-cli: scaffolds a new TypeScript package and hands off to autoship for its first release.
• pr-creator: opens feature PRs. Autoship only ever merges the bot-opened Version Packages PR.
• pr-babysitter: watches feature PRs (reviews, conflicts, CI). Autoship watches release CI only.

Changeset Creation and Commit

Table of Contents

• Detecting Existing Changesets
• Creating a Changeset
• Quality Gates
• What Happens Next (CI Handles Versioning)
• Commit and Push

Detecting Existing Changesets

Check for pending changesets before creating a new one:

ls .changeset/*.md 2>/dev/null | grep -v README.md

If changesets already exist, ask the user whether to create an additional one or skip.

Creating a Changeset

Prefer non-interactive changeset creation for agent mode:

# Interactive (TTY required)
npm run changeset

# Non-interactive: write the changeset file directly
cat > .changeset/<short-id>.md << 'EOF'
---
"<package-name>": patch
---

<description of changes>
EOF

Generate the short id with: node -e "console.log(Math.random().toString(36).slice(2,10))".

Bump Type Selection

Default to patch unless the user specifies otherwise.

Changeset Summary

Infer the summary from recent commits:

git log --oneline -10

Write a concise 1-2 sentence description focusing on user-facing changes.

Quality Gates

Run the project's quality checks in this order before committing. Discover available scripts first:

cat package.json | jq '.scripts | keys[]' -r

Gate Order

1. Lint: npm run lint or the project's lint script

• Auto-fix: npm run lint -- --fix or npx eslint --fix <changed-paths>

2. Type-check: npm run typecheck or npx tsc --noEmit

• Fix type errors manually; there is no safe auto-fixer

3. Tests: npm test or npm run test

• Fix failing tests; do not skip or delete them to get green

4. Format: npm run format or npx prettier --write <changed-paths>

• Scope to changed files; project-wide formatting reformats files outside the change

After any auto-fixer runs, check git status and revert files it touched outside your change (git restore <path>) before continuing.

Retry Logic

• Retry each gate up to 5 fix iterations; report the remaining error count each pass.
• If a gate still fails after 5 iterations, stop and report to the user.
• Re-run all gates from the beginning after any code change to catch regressions one fix introduces in an earlier gate.

What Happens Next (CI Handles Versioning)

After the changeset file is committed and pushed, CI's changesets/action workflow detects the pending changeset on the default branch and opens (or updates) a "Version Packages" PR on branch changeset-release/main. That PR contains the package.json version bump and CHANGELOG.md updates generated by running changeset version inside CI.

Do not run `npx changeset version` locally. It consumes the changeset file, so the commit pushed to main has no pending changeset, CI's "Changeset Status" check fails, and no Version Packages PR is opened.

The local job ends at "commit + push the changeset file".

Commit and Push

Use chore: add <type> changeset for <package> as the commit message convention.

Stage explicit paths only (git add <paths>, never git add -A): pre-commit hooks can emit stray artifacts (e.g. a root schema.gql) that broad staging silently commits into the release.

CI Watching with the Monitor Tool

Table of Contents

• Why Monitor, not /loop
• Watching CI on the Current Branch
• Waiting for the Version Packages PR to Appear
• Watching the Publish Workflow
• Failure Diagnosis
• Stopping a Monitor
• Rate Limit Awareness
• The Changeset Status PR Check

Why Monitor, not /loop

Monitor runs a small script in the background and feeds each output line back to the agent as it arrives. The agent reacts mid-conversation: no scheduled re-prompt, no fixed interval cadence, no extra context per poll. For CI watching this is strictly better than /loop:

• The watch script controls the cadence (one sleep line) instead of CronCreate firing a whole prompt.
• The agent only sees output when state actually changes, not on every tick.
• Stopping is one cancellation, not "remember to delete the cron".

Use Monitor for every CI / PR / workflow wait in autoship.

Watching CI on the Current Branch

After git push, start a Monitor that waits for every workflow run on the pushed commit to reach completed, then classifies the overall result. Scope by commit SHA, not branch, so older pushes do not bleed in and so the Monitor does not exit early when one of several parallel workflows finishes first.

SHA=$(git rev-parse HEAD)
LAST=""
while true; do
  CUR=$(gh run list --commit "$SHA" --limit 20 \
    --json status,conclusion,workflowName,databaseId \
    --jq 'map("\(.databaseId)|\(.workflowName)|\(.status)|\(.conclusion // "")") | .[]')
  if [ "$CUR" != "$LAST" ]; then echo "---"; echo "$CUR"; LAST="$CUR"; fi
  # No runs registered yet: keep waiting
  [ -z "$CUR" ] && { sleep 30; continue; }
  # Any run still in flight: keep waiting
  echo "$CUR" | grep -qv '|completed|' && { sleep 30; continue; }
  # All runs completed: classify
  if echo "$CUR" | grep -qv '|success$'; then
    echo "TERMINAL: failure"
  else
    echo "TERMINAL: success"
  fi
  exit 0
done

The agent keeps the Monitor running; each state change surfaces a new block. Stop on the first TERMINAL: line. Any non-success conclusion (failure, cancelled, timed_out, action_required, neutral, skipped, stale) is reported as a failure so the agent can inspect logs rather than spin.

Waiting for the Version Packages PR to Appear

changesets/action may take several minutes to open the PR after the changeset commit lands on the default branch. Watch for it:

DEADLINE=$(( $(date +%s) + 600 ))   # 10-minute cap
while [ "$(date +%s)" -lt "$DEADLINE" ]; do
  PR=$(gh pr list --state open --search "Version Packages in:title" \
    --json number,headRefName \
    --jq '.[] | select(.headRefName == "changeset-release/main") | .number' | head -n1)
  if [ -n "$PR" ]; then
    echo "FOUND: $PR"
    exit 0
  fi
  sleep 30
done
echo "TIMEOUT"
exit 1

Stop the Monitor on FOUND: or TIMEOUT.

Watching the Publish Workflow

After merging the Version Packages PR, the same release workflow runs again (this time invoking changeset publish). Identify the workflow file in .github/workflows/, then:

WF="release.yml"   # adjust to the actual file name
LAST=""
while true; do
  CUR=$(gh run list --workflow "$WF" --branch main --limit 1 \
    --json status,conclusion,databaseId \
    --jq '.[0] | "\(.databaseId)|\(.status)|\(.conclusion // "")"')
  if [ "$CUR" != "$LAST" ]; then echo "$CUR"; LAST="$CUR"; fi
  case "$CUR" in
    *"|completed|success") echo "TERMINAL: success"; exit 0 ;;
    *"|completed|"*)       echo "TERMINAL: failure"; exit 0 ;;
  esac
  sleep 30
done

Pipe (|) is used as the field delimiter instead of tab so the case patterns can anchor on the end of the string and avoid the trailing-delimiter trap. Any conclusion other than success is treated as a failure so non-standard terminal states (neutral, skipped, action_required, etc.) are surfaced rather than silently looped.

Do not auto-retry on publish failure; these are real (auth, OIDC, tag conflict).

Failure Diagnosis

When a Monitor reports a failed run:

1. Read the failed logs: gh run view <id> --log-failed. 2. Classify the failure:

Retry flaky/infrastructure failures up to 3 times. After 3 retries, escalate to the user. Never auto-retry the publish workflow.

Stopping a Monitor

A Monitor stops when its script exits (the examples above exit on TERMINAL: / FOUND: / TIMEOUT lines). To cancel an in-flight Monitor before it exits, ask the agent to stop it. Always stop monitors before reporting autoship complete.

Rate Limit Awareness

gh calls count against your GitHub API rate limit. Keep sleep at 30s or higher in Monitor scripts. Check remaining quota if you suspect throttling:

gh api rate_limit --jq '.resources.core.remaining'

The Changeset Status PR Check

Changesets repos typically run npx changeset status --since origin/<baseBranch> on every PR (often as a step in the main CI job). This check verifies that a PR modifying publishable code includes a pending .changeset/*.md file.

Common failure modes:

• "no changeset found": the PR touches code but adds no changeset. Fix: run Step 1 of autoship to add one.
• "changeset consumed": a local npx changeset version was run; the changeset file is gone and the package.json version has already been bumped. Fix: revert the version bump and CHANGELOG.md edit, re-add the changeset file, force-push. Do NOT retry CI; the state is broken at the commit level.

This check is what you read first when a release PR fails CI.

Version Packages PR and npm Publish

Companion reference: the reusable Monitor snippets for this file live in references/ci-polling.md (sections "Waiting for the Version Packages PR to Appear" and "Watching the Publish Workflow"). SKILL.md Steps 4 and 5 load both files together, so they should already be in context.

Table of Contents

• The `changesets/action` Workflow
• Finding the Version Packages PR
• Verifying CI Before Merge
• Merging the Version Packages PR
• Watching the Publish Run
• Cleanup

The changesets/action Workflow

A single workflow (commonly release.yml or npm-publish.yml) handles both versioning and publishing. It runs on pushes to the default branch and uses changesets/action@v1 with a publish: input pointing at an npm script that calls changeset publish (typically npm run release).

The action has two modes, chosen automatically by state on main:

1. Pending changesets present → it runs changeset version internally, then opens or updates a PR titled "Version Packages" on branch changeset-release/main containing the version bump and CHANGELOG.md updates. No publish yet. 2. No pending changesets (Version Packages PR just merged) → it runs the publish: script, which calls changeset publish to push tags and publish to npm.

So the SAME workflow run that opens the Version Packages PR does not publish; a second run of the SAME workflow, triggered by merging that PR, publishes. When monitoring, you are watching two successive runs of one workflow, not two different workflows.

Reference best-practice release.yml shape (OIDC trusted publishing):

permissions:
  contents: write
  pull-requests: write
  id-token: write
steps:
  - uses: actions/checkout@v4
    with: { fetch-depth: 0 }
  - uses: actions/setup-node@v4
    with: { node-version: 22, registry-url: https://registry.npmjs.org, cache: npm }
  - run: npm ci
  - uses: changesets/action@v1
    with:
      publish: npm run release
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      NPM_CONFIG_PROVENANCE: "true"

The release script is typically changeset publish (optionally preceded by a build). The changeset:version npm script, if present, is invoked by the action, never locally.

.changeset/config.json should have "commit": false so the action controls commits via the PR.

Finding the Version Packages PR

With gh CLI

# Search by title (the JSON field is headRefName; headBranch is not a valid field)
gh pr list --search "Version Packages" --state open --json number,title,headRefName,statusCheckRollup

# Search by branch pattern
gh pr list --head changeset-release/main --state open --json number,title,statusCheckRollup

If the PR Does Not Exist Yet

The changesets bot may take a few minutes. Use the Monitor tool to watch for the PR (see the "Waiting for the Version Packages PR to Appear" snippet in references/ci-polling.md). Cap the watch at 10 minutes. If the watch times out, check:

• Are there pending changesets on the default branch?
• Is the changesets GitHub Action configured in .github/workflows/?
• Did the action run? Check with gh run list --workflow <changeset-workflow-name>

Verifying CI Before Merge

Before merging the Version Packages PR, verify all CI checks pass:

gh pr checks <pr-number> --json name,state,bucket

Every check must report bucket: pass. (gh pr checks has no conclusion field; requesting it errors with "Unknown JSON field". A bucket of pending, fail, skipping, or cancel blocks the merge.)

If checks are still running, use the Monitor tool (see references/ci-polling.md) to wait for them to complete.

Merging the Version Packages PR

YELLOW-tier within autoship: invoking the skill is standing consent for the merge. Do not prompt for re-confirmation. Gate the merge with these objective preconditions instead.

Preconditions (all must hold):

• PR title is exactly "Version Packages" OR head branch is changeset-release/main. Never merge a PR that does not match.
• Every check on the PR reports bucket: pass (verify with gh pr checks <pr-number> --json name,bucket).
• PR is mergeable: gh pr view <pr-number> --json mergeable reports MERGEABLE (not CONFLICTING or UNKNOWN). If UNKNOWN, wait briefly and re-query.

Announce in one short line, then execute:

Merging Version Packages PR #<n>: <package>@<version>

gh pr merge <pr-number> --squash --delete-branch

Prefer --squash for clean history. Use --merge if the project convention requires merge commits.

If any precondition fails, stop and report to the user. Do not attempt to fix mergeability or override failing checks.

Watching the Publish Run

After merging the Version Packages PR, the push to the default branch triggers the SAME release workflow again. This second run detects there are no pending changesets and executes the publish: script (changeset publish).

Detecting the Workflow Run

Find the workflow file by inspecting .github/workflows/; common names are release.yml, npm-publish.yml, publish.yml. Then:

# Replace release.yml with the actual file name
gh run list --workflow release.yml --branch main --limit 3 --json status,conclusion,databaseId,createdAt

# Or list all recent runs and identify by name
gh run list --branch main --limit 5 --json workflowName,status,conclusion,databaseId

Watching for Completion

Start a Monitor watch on the release workflow's latest run on main. See the "Watching the Publish Workflow" snippet in references/ci-polling.md for a ready-to-use script. The Monitor exits on the first TERMINAL: line.

Terminal conditions:

• Success: workflow completes with conclusion: success. Report and stop.
• Failure: workflow completes with any other conclusion. Report with logs and stop.
• Do NOT auto-retry publish failures. These typically indicate real issues (npm auth, registry, OIDC/provenance, tag conflict).

Verifying the Published Version

After the publish workflow succeeds:

npm view <package-name> version

Compare with the version in package.json to confirm the publish was successful.

Cleanup

• The --delete-branch flag on merge handles branch cleanup
• Stop any Monitor watches that are still running
• Report the final published version to the user