The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
docs(skills): add release coordination workflow
Dottafd73d6fcab52
diff --git a/skills/release/SKILL.md b/skills/release/SKILL.mdnew file mode 100644index 0000000000..7fe3d97c6a--- /dev/null+++ b/skills/release/SKILL.md@@ -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.