docs(skills): add release coordination workflow
This commit is contained in:
Dotta
215
skills/release/SKILL.md
Normal file
215
skills/release/SKILL.md
Normal file
@@ -0,0 +1,215 @@
|
||||
---
|
||||
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.
|
||||
Reference in New Issue
Block a user