---
name: release
description: >
  Coordinate a full Paperclip release across engineering, website publishing,
  and social announcement. Use when CTO/CEO requests "do a release" or
  "release vX.Y.Z". Runs pre-flight checks, generates changelog via
  release-changelog, executes npm release, creates cross-project follow-up
  tasks, and posts a release wrap-up.
---

# Release Coordination Skill

Run the full Paperclip release process as an organizational workflow, not just
an npm publish.

This skill coordinates:
- App release execution (`scripts/release.sh`)
- User-facing changelog generation (`release-changelog` skill)
- Website publishing task creation
- CMO announcement task creation
- Final release summary with links

---

## Trigger

Use this skill when leadership asks for:
- "do a release"
- "release {patch|minor|major}"
- "release vX.Y.Z"

---

## Preconditions

Before proceeding, verify all of the following:

1. `skills/release-changelog/SKILL.md` exists and is usable.
2. The `release-changelog` dependency work is complete/reviewed before running this flow.
3. App repo working tree is clean.
4. There are commits since the last release tag.
5. You have release permissions (`npm whoami` succeeds for real publish).
6. If running via Paperclip, you have issue context for posting status updates.

If any precondition fails, stop and report the blocker.

---

## Inputs

Collect these inputs up front:

- Release request source issue (if in Paperclip)
- Requested bump (`patch|minor|major`) or explicit version (`vX.Y.Z`)
- Whether this run is dry-run or live publish
- Company/project context for follow-up issue creation

---

## Step 1 - Pre-flight and Version Decision

Run pre-flight in the App repo root:

```bash
LAST_TAG=$(git tag --sort=-version:refname | head -1)
git diff --quiet && git diff --cached --quiet
git log "${LAST_TAG}..HEAD" --oneline --no-merges | head -50
```

Then detect minimum required bump:

```bash
# migrations
git diff --name-only "${LAST_TAG}..HEAD" -- packages/db/src/migrations/

# schema deltas
git diff "${LAST_TAG}..HEAD" -- packages/db/src/schema/

# breaking commit conventions
git log "${LAST_TAG}..HEAD" --format="%s" | rg -n 'BREAKING CHANGE|BREAKING:|^[a-z]+!:' || true
```

Bump policy:
- Destructive migration/API removal/major changeset/breaking commit -> `major`
- Additive migrations or clear new features -> at least `minor`
- Fixes-only -> `patch`

If requested bump is lower than required minimum, escalate bump and explain why.

---

## Step 2 - Generate Changelog Draft

Invoke the `release-changelog` skill and produce:
- `releases/v{version}.md`
- Sections ordered as: Breaking Changes (if any), Highlights, Improvements, Fixes, Upgrade Guide (if any)

Required behavior:
- Present the draft for human review.
- Flag ambiguous categorization items.
- Flag bump mismatches before publish.
- Do not publish until reviewer confirms.

---

## Step 3 - Run App Release

After changelog approval, execute:

```bash
# dry run
./scripts/release.sh {patch|minor|major} --dry-run

# live release
./scripts/release.sh {patch|minor|major}
```

Then capture final release metadata:

```bash
NEW_TAG=$(git tag --sort=-version:refname | head -1)   # e.g. v0.4.0
NEW_VERSION=${NEW_TAG#v}
NPM_URL="https://www.npmjs.com/package/@paperclipai/cli/v/${NEW_VERSION}"
```

If publish fails, stop immediately, keep issue in progress/blocked, and include
failure logs in the update.

---

## Step 4 - Create Cross-Project Follow-up Tasks

Create at least two tasks in Paperclip:

1. Website task: publish changelog for `v{version}`
2. CMO task: draft announcement tweet for `v{version}`

When creating tasks:
- Set `parentId` to the release issue id.
- Carry over `goalId` from the parent issue when present.
- Include `billingCode` for cross-team work when required by company policy.
- Mark website task `high` priority if release has breaking changes.

Suggested payloads:

```json
POST /api/companies/{companyId}/issues
{
  "projectId": "{websiteProjectId}",
  "parentId": "{releaseIssueId}",
  "goalId": "{goalId-or-null}",
  "billingCode": "{billingCode-or-null}",
  "title": "Publish release notes for v{version}",
  "priority": "medium",
  "status": "todo",
  "description": "Publish /changelog entry for v{version}. Include full markdown from releases/v{version}.md and prominent upgrade guide if breaking changes exist."
}
```

```json
POST /api/companies/{companyId}/issues
{
  "projectId": "{workspaceProjectId}",
  "parentId": "{releaseIssueId}",
  "goalId": "{goalId-or-null}",
  "billingCode": "{billingCode-or-null}",
  "title": "Draft release announcement tweet for v{version}",
  "priority": "medium",
  "status": "todo",
  "description": "Draft launch tweet with top 1-2 highlights, version number, and changelog URL. If breaking changes exist, include an explicit upgrade-guide callout."
}
```

---

## Step 5 - Wrap Up the Release Issue

Post a concise markdown update linking:
- Release issue
- Changelog file (`releases/v{version}.md`)
- npm package URL
- Website task
- CMO task
- Final changelog URL (once website publishes)
- Tweet URL (once published)

Completion rules:
- Keep issue `in_progress` until website + social tasks are done.
- Mark `done` only when all required artifacts are published and linked.
- If waiting on another team, keep open with clear owner and next action.

---

## Paperclip API Notes (When Running in Agent Context)

Use:
- `GET /api/companies/{companyId}/projects` to resolve website/workspace project IDs.
- `POST /api/companies/{companyId}/issues` to create follow-up tasks.
- `PATCH /api/issues/{issueId}` with comments for release progress.

For issue-modifying calls, include:
- `Authorization: Bearer $PAPERCLIP_API_KEY`
- `X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID`

---

## Failure Handling

If blocked, update the release issue explicitly with:
- what failed
- exact blocker
- who must act next
- whether any release artifacts were partially published

Never silently fail mid-release.