Release Coordination Skill

---
name: release-81c90e472945
description: >
  Coordinate an AgentDash application or owned-package release across
  engineering verification, GitHub, npm when applicable, smoke testing, and
  announcement follow-up. Use when leadership asks to ship a release.
---

# Release Coordination Skill

<!-- AgentDash: release-ownership-boundary — DO NOT REMOVE OR REORDER THIS BLOCK -->
## AgentDash release ownership boundary

Classify the release before doing anything else:

- **Application/OTA:** use `.github/workflows/release.yml`, CalVer tags `vYYYY.MDD.P`, and `releases/vYYYY.MDD.P.md`. Every `scripts/release.sh` invocation must pass `--skip-npm`. This path creates application tags, GitHub Releases, and checksummed updater assets; it does not publish npm packages.
- **Owned connector:** only `packages/connect` / `agentdash-connect` is currently owned and allowlisted. Preserve semver and tags `agentdash-connect-vX.Y.Z`; put notes at `packages/connect/releases/vX.Y.Z.md`; dry-run and publish only through `.github/workflows/publish-connect.yml` using npm trusted publishing/OIDC.

Never publish inherited `@paperclipai/*` packages or unprovisioned `@agentdash/*` names, never assign application CalVer to `agentdash-connect`, and never add a long-lived npm token fallback. If later steps in this skill describe upstream Paperclip npm behavior that conflicts with this block, this block is authoritative for AgentDash.
<!-- /AgentDash: release-ownership-boundary -->

Run the full AgentDash release workflow, not an ad hoc tag or npm publish.

This skill coordinates:

- stable changelog drafting via `release-changelog`
- canary verification and publish status from `main`
- Docker smoke testing via `scripts/docker-onboard-smoke.sh`
- manual stable promotion from a chosen source ref
- GitHub Release creation
- website / announcement follow-up tasks

## Trigger

Use this skill when leadership asks for:

- "do a release"
- "ship the release"
- "promote this canary to stable"
- "cut the stable release"

## Preconditions

Before proceeding, verify all of the following:

1. `.agents/skills/release-changelog/SKILL.md` exists and is usable.
2. The immutable source checkout is clean, including untracked files.
3. There is at least one canary or candidate commit since the last stable tag.
4. The candidate SHA has passed the verification gate or is about to.
5. If manifests changed, the CI-owned `pnpm-lock.yaml` refresh is already merged on `main`.
6. For an owned-package release, npm trusted publishing is configured for the exact package and package-specific workflow. Local token auth is not an allowed fallback.
7. If running through Paperclip, you have issue context for status updates and follow-up task creation.

If any precondition fails, stop and report the blocker.

## Inputs

Collect these inputs up front:

- whether the target is a canary check or a stable promotion
- the candidate `source_ref` for stable
- whether the stable run is dry-run or live
- release issue / company context for website and announcement follow-up

## Step 0 — Release Model

Paperclip now uses a commit-driven release model:

1. every push to `main` publishes a canary automatically
2. canaries use `YYYY.MDD.P-canary.N`
3. stable releases use `YYYY.MDD.P`
4. the middle slot is `MDD`, where `M` is the UTC month and `DD` is the zero-padded UTC day
5. the stable patch slot increments when more than one stable ships on the same UTC date
6. stable releases are manually promoted from a chosen tested commit or canary source commit
7. only stable releases get `releases/vYYYY.MDD.P.md`, git tag `vYYYY.MDD.P`, and a GitHub Release

Critical consequences:

- do not use release branches as the default path
- do not derive major/minor/patch bumps
- do not create canary changelog files
- do not create canary GitHub Releases

## Step 1 — Choose the Candidate

For canary validation:

- inspect the latest successful canary run on `main`
- record the canary version and source SHA

For stable promotion:

1. choose the tested source ref
2. confirm it is the exact SHA you want to promote
3. resolve the target stable version with `./scripts/release.sh stable --skip-npm --date YYYY-MM-DD --print-version`

Useful commands:

```bash
git tag --list 'v*' --sort=-version:refname | head -1
git log --oneline --no-merges
```

## Step 2 — Draft the Stable Changelog

Stable changelog files live at:

- `releases/vYYYY.MDD.P.md`

Invoke `release-changelog` and generate or update the stable notes only.

Rules:

- review the draft with a human before publish
- preserve manual edits if the file already exists
- keep the filename stable-only
- do not create a canary changelog file

## Step 3 — Verify the Candidate SHA

Run the standard gate:

```bash
pnpm -r typecheck
pnpm test:run
pnpm build
```

If the GitHub release workflow will run the publish, it can rerun this gate. Still report local status if you checked it.

For PRs that touch release logic, the repo also runs a canary release dry-run in CI. That is a release-specific guard, not a substitute for the standard gate.

## Step 4 — Validate the Canary

The normal canary path is automatic from `main` via:

- `.github/workflows/release.yml`

Confirm:

1. verification passed
2. no npm package publication was attempted
3. git tag `canary/vYYYY.MDD.P-canary.N` exists

Useful checks:

```bash
git tag --list 'canary/v*' --sort=-version:refname | head -5
```

## Step 5 — Smoke Test the Canary

Use the checksummed application release controller in an isolated synthetic
instance. Verify its manifest before running it and keep the instance bound to
loopback. Do not substitute an inherited npm package for the AgentDash app.

Confirm:

1. the controller checksum and source/control provenance match
2. onboarding completes without crashes
3. the server boots
4. the UI loads
5. basic company creation and dashboard load work

If smoke testing fails:

- stop the stable release
- fix the issue on `main`
- wait for the next automatic canary
- rerun smoke testing

## Step 6 — Preview or Publish Stable

The normal stable path is manual `workflow_dispatch` on:

- `.github/workflows/release.yml`

Inputs:

- `source_ref`
- `stable_date`
- `dry_run`

Before live stable:

1. resolve the target stable version with `./scripts/release.sh stable --skip-npm --date YYYY-MM-DD --print-version`
2. ensure `releases/vYYYY.MDD.P.md` exists on the default-branch release-control ref
3. run the stable workflow in dry-run mode first when practical
4. then run the real stable publish

The stable workflow keeps the default-branch release controls and chosen source ref in separate checkouts. It:

- requires `source_ref` to be a full 40-character commit SHA
- re-verifies the exact source ref
- computes the next stable patch slot for the chosen UTC date
- does not publish npm packages
- creates git tag `vYYYY.MDD.P` on the exact source ref
- builds a checksummed source-install controller with a manifest that pins source and release-control SHAs
- creates or updates the GitHub Release from `releases/vYYYY.MDD.P.md` and uploads the controller assets

Local preview commands:

```bash
./scripts/release.sh stable --skip-npm --dry-run
./scripts/release.sh stable --skip-npm --date YYYY-MM-DD --print-version
```

Publish through `.github/workflows/release.yml`; do not manually publish or tag
around the canonical workflow.

## Step 7 — Finish the Other Surfaces

Create or verify follow-up work for:

- website changelog publishing
- launch post / social announcement
- release summary in Paperclip issue context

These should reference the stable release, not the canary.

## Failure Handling

If the canary is bad:

- publish another canary, do not ship stable

If stable tag creation succeeds but GitHub release creation fails, stop and
repair the GitHub workflow from the same immutable source and release-control
result. Do not retag a different commit with the same version.

If an installed application release is bad, use its generated source rollback
wrapper and verify restored health. If an owned npm package is bad, publish a
reviewed patch; do not unpublish or repoint inherited package names.

## Output

When the skill completes, provide:

- candidate SHA and tested canary version, if relevant
- stable version, if promoted
- verification status
- owned-package status, when the release includes one
- smoke-test status
- git tag / GitHub Release status
- website / announcement follow-up status
- rollback recommendation if anything is still partially complete