autoship

What this skill does

# Autoship

Automate npm releases with a changeset -> fix -> push -> monitor -> merge -> publish workflow.

## Reference Files

| File | Read when |
|------|-----------|
| `references/changeset-and-commit.md` | Creating a changeset, fixing quality issues, or committing and pushing |
| `references/ci-polling.md` | Watching CI with the Monitor tool, diagnosing failures, or handling retries |
| `references/version-pr-and-publish.md` | Searching for the Version Packages PR, merging it, or watching the release workflow |

## Intent Map

| Intent | Steps | Notes |
|--------|-------|-------|
| Full autoship (ship / release / publish) | 1 through 5 | Default entry point. Runs end-to-end through publish without intermediate prompts |
| Create changeset only | Step 1 | Stage a release without pushing |
| Fix quality and push | Steps 1-2 | Changeset + fixes + commit, no CI watch |
| Watch CI only | Steps 3-5 | When changes are already pushed |
| Merge version PR only | Steps 4-5 | When CI already passed. Auto-merges once preconditions are met |
| Fix compiler only | Step 2 | When build is broken, no changeset needed |

## 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:` `npm run changeset` / 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 opened by `changesets/action` once its identity is confirmed and all checks are green.
- `RED -- explicit confirmation required:` force-pushing, history rewrites, and any destructive git operations.

## Workflow

Copy this checklist to track progress:

```text
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 release workflow to completion
```

### 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 changesets exist, ask the user whether to create an additional one or skip.
- Default to `patch` bump type. Only use `minor` or `major` when the user explicitly requests it.
- Write the changeset file directly for non-interactive agent mode.
- Infer the changeset summary from recent commits with `git log --oneline -10`.

### Step 2: Fix lint, types, tests, format

- Load `references/changeset-and-commit.md` (skip when running Fix compiler only intent).
- Auto-discover build/typecheck command: check `package.json` scripts for `build`, `typecheck`, `tsc`, `type-check`; also check for `Makefile`, `Cargo.toml`, `pyproject.toml`, `go.mod`.
- Discover available scripts from `package.json`.
- Run quality 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 `format`/`fix` scripts routinely reformat or corrupt files outside your change (MDX is a frequent casualty). Revert anything unrelated (`git restore <path>`) before continuing; never let a fixer's unrelated churn ride along in the release commit.
- If any gate fails, parse error output to extract file, line, error code, and message. Prioritize: syntax errors first, then type errors, then lint errors.
- Fix one error at a time when errors cascade (one root cause produces many symptoms).
- Retry each gate up to 5 iterations after applying fixes. Report remaining error count each iteration.
- If a gate still fails after retries, stop and report to the user.

### Step 3: Commit + push changeset

- Stage the changeset file and the in-scope auto-fixes only — prefer `git add <paths>` over `git add -A`. Before committing, run `git status --porcelain` and strip stray generated artifacts (e.g. a root `schema.gql` left by a pre-commit hook) and any unrelated files a fixer touched. Commit and push.
- Do NOT run `npx changeset version` locally. CI's `changesets/action` runs it inside the Version Packages PR.
- The pushed commit must contain the pending `.changeset/*.md` file so CI's "Changeset Status" check passes.

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

- Load `references/ci-polling.md` and `references/version-pr-and-publish.md`.
- After pushing, start a `Monitor` watch that emits a line each time the latest workflow run on the current branch reaches a terminal state (`completed`). The agent reacts to each emitted line; no `/loop` re-prompt needed.
- Do not stop prematurely. A single idle snapshot does not mean CI is done — keep the monitor running until at least one workflow run reports `completed`.
- On failure: read logs, classify as flaky or real. Retry flaky failures up to 3 times with `gh run rerun <id> --failed`. For real failures: fix, commit, push, restart the monitor.
- Once CI is green, search for an open PR titled "Version Packages" or on branch `changeset-release/main`. If not found immediately, start a second `Monitor` watch that polls for the PR for up to 10 minutes (the changesets bot needs time).
- Before merging, verify ALL of the following preconditions:
  - PR title is exactly "Version Packages" OR head branch is `changeset-release/main` (do not merge any other PR).
  - Every check on the PR shows `state: completed` and `conclusion: success`.
  - PR is mergeable (`mergeable: MERGEABLE`, not `CONFLICTING` or `UNKNOWN`).
- Announce in one short line ("Merging Version Packages PR #N — <package>@<version>"), then merge with `gh pr merge <number> --squash --delete-branch`. Do not pause for confirmation; invoking autoship is the consent.
- If any precondition fails, stop and report — do not merge.

### Step 5: Watch the publish run to completion

- Load `references/version-pr-and-publish.md` and `references/ci-polling.md`.
- Merging the Version Packages PR triggers the SAME release workflow again. Because no pending changesets remain, `changesets/action` now executes the `publish:` script (`changeset publish`).
- Identify the workflow file (commonly `release.yml`, `npm-publish.yml`, or `publish.yml`) in `.github/workflows/`.
- Start a `Monitor` watch on that workflow's latest run on `main`, emitting a line when it reaches a terminal state.
- Terminal conditions: workflow succeeds (report published version) or fails (report with logs).
- Do NOT auto-retry publish failures. These typically need human investigation (npm auth, registry, OIDC/provenance, tag conflict).
- On success, verify with `npm view <package> version` and stop any remaining `Monitor` watches.

## Anti-patterns

- Running `npm publish` directly instead of using the changesets workflow.
- Merging the Version Packages PR before its CI checks pass.
- Stopping CI monitoring after the first poll shows no runs (workflows take time to queue).
- Creating a changeset with `major` bump without explicit user instruction.
- Force-pushing to the default branch.
- Auto-retrying publish failures (these are typically real auth, registry, OIDC/provenance, or tag-conflict issues).
- Polling tighter than ~30s, which wastes GitHub API rate limit. Monitor scripts should `sleep 30` or longer between `gh` calls.
- **Never run `npx changeset version` locally.** CI's `changesets/action` runs it inside the Version Packages PR. Running it locally consumes the changeset file, the pushed commit has no pending changeset, CI's "Changeset Status" check fails, and no Version Packages PR is opened.
- Hand-editing `CHANGELOG.md` or `package.json` `version` as part of au