agentleFS
solo-istsolo-ist/prose/.claude/skills/release/SKILL.md

release

Skill8 starsChanged 5 months agoMITView on GitHub

Create a new Prose release with automated testing, GitHub release, and local verification.

  • Deletes or force-pushes
  • Commits and pushes

193 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use create-agent-adapter, changelog-style and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • MicrosoftSkill

    create-agent-adapter

    Technical guide for creating a new Paperclip agent adapter. Use when building a new adapter package, adding support for a new AI coding tool (e.g. a new CLI agent, API-based agent, or custom process), or when modifying the adapter system. Covers the required interfaces, module structure, registration points, and conventions derived from the existing claude-local and codex-local adapters.

    Also in 5 projects that use this

  • GrinvSkill

    changelog-style

    Turn a commit range into CHANGELOG.md entries following common-changelog style. Use when finishing a PR or cutting a release, to write/fix the [Unreleased] section's entries — moving [Unreleased] under a new dated version heading is a separate, automated step (see the release skill / scripts/sync-version.ts), not this skill's job.

    Also in 4 projects that use this

  • GrinvSkill

    docs-consistency-check

    Check README/manifest.json/server.json/CHANGELOG.md/AGENTS.md and docs/*.md for drift against the actual registered tools and source. Use after adding, renaming, or removing a tool, or as part of a live-audit pass.

    Also in 4 projects that use this

  • Microsoft AzureSkill

    component-release

    Prepares a verifiable Agent Landing Zone UI release. Use for release branches, VERSION, changelog entries, tags, release notes, and compatibility evidence; never publish without explicit human approval.

    Also in 4 projects that use this

  • Microsoft AzureSkill

    documentation-consistency

    Keeps AI Landing Zone contributor, user, and operator documentation aligned with shipped Bicep behavior. Use for parameters, defaults, outputs, topology, deployment flow, operations, or releases.

    Also in 8 projects that use this

  • rivet-devSkill

    launch-graphics

    Generate agentOS marketing/launch graphics (launch & social heroes, code-snippet cards) from the committed generators in docs-internal/graphics. Use when asked to make, update, or render an agentOS launch image, social image, "agentOS Apps" graphic, or technical code-snippet image.

    Also in 3 projects that use this

  • +3 more from Grinv

The file

Show its rules and text

We split this skill into the rules it gives an agent

15 rules. 0 are common, 6 are distinctive, and 9 are very specific to this project.

  • 0

    Common

    Most of the 183 edited versions we read keep these.

  • 6

    Distinctive

    This author's own choices. Worth a look.

  • 9

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Write it once, there, and commit it before tagging — the tag is what publishes it.

    line 178
  2. Distinctive:

    If CI is not available or you want to publish manually:

    line 223
  3. Very specific:

    Use git -C <path> rather than cd && git — compound chains get flagged for manual approval and block unattended agents.

    line 267
  4. Distinctive:

    Not just the newest one. Find where the copy actually left off:

    line 271
  5. Very specific:

    Check all of these in prose/index.html.

    line 282
  6. Distinctive:

    Never invent a feature. Every claim traces back to a release note.

    line 301
  7. Very specific:

    Do NOT use npm run dev — the smoke test must exercise the signed bundle.

    line 366
  8. Distinctive:

    If any path fails, fix before tagging.

    line 402
  9. Distinctive:

    Run through this before any release:

    line 473
  10. Very specific:

    "Invalid signature": Check that Apple Distribution cert is in keychain and not expired

    line 516
  11. Very specific:

    "Missing provisioning profile": Verify build/Prose_Distribution.provisionprofile exists and bundle ID matches ist.solo.prose

    line 517
  12. Very specific:

    "Cannot find valid 3rd Party Mac Developer Installer": Use team ID (8PT2Y7QQ2F) as identity in mas: block, not cert name

    line 520
  13. Very specific:

    afterPack error "Unsupported platform: mas": Ensure build/afterPack.cjs handles the mas case

    line 521
  14. Very specific:

    Notarization hanging locally: Don't set notarize: true in config.

    line 524
  15. Very specific:

    Missing secrets: Verify CSC_LINK, CSC_KEY_PASSWORD, APPLE_ID, APPLE_APP_SPECIFIC_PASSWORD, APPLE_TEAM_ID, SENTRY_AUTH_TOKEN are set in repo …

    line 527

“Common” is measured: kept by at least 6 in 10 of the 183 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Release Manager

Manages the full release workflow for Prose across two distribution channels:

  • Mac App Store — signed .pkg uploaded via Transporter → TestFlight → App Store
  • GitHub Releases — signed .dmg + .zip published to GitHub for direct download + auto-update

Usage

/release [command]

Commands

CommandDescription
/releaseShow current version, build number, and release status
/release masBuild and prepare MAS .pkg for Transporter upload
/release githubBuild DMG and create GitHub Release
/release copyUpdate the solo.ist/prose marketing copy after a release
/release bump-buildIncrement buildVersion and rebuild MAS .pkg
/release bump-version <version>Bump marketing version (e.g., 1.1.0)
/release smokeBuild the DMG and walk 7 critical paths (~5 min) — fast pre-release sanity check
/release statusCheck TestFlight processing, GitHub Release, and CI status
/release checklistRun the full pre-release verification checklist

Architecture

Version Numbers

Two version numbers, managed independently:

  • Marketing version (CFBundleShortVersionString): Set in package.json "version". Example: 1.0.0. This is what users see. Must match the App Store Connect record.
  • Build number (CFBundleVersion): Set in electron-builder.yml "buildVersion". Example: "2". Incremented for each upload to App Store Connect. GitHub Releases don't care about this.

Signing Identities

BuildIdentityProfile
DMG (direct download)Developer ID ApplicationNone (notarized via CI)
MAS (App Store)Apple Distribution (via team ID 8PT2Y7QQ2F)build/Prose_Distribution.provisionprofile
MAS .pkg installer3rd Party Mac Developer InstallerN/A

Bundle ID

ist.solo.prose — used across all builds. Must match provisioning profiles and App Store Connect.

Key Files

FilePurpose
package.jsonMarketing version ("version")
electron-builder.ymlBuild number (buildVersion), signing config, targets
build/entitlements.mac.plistDMG entitlements (includes network.server for MCP)
build/entitlements.mas.plistMAS entitlements (sandbox, no network.server)
build/entitlements.mas.inherit.plistChild process entitlements for MAS
build/Prose_Distribution.provisionprofileMAS distribution profile
build/afterPack.cjsElectron fuse flipping
.github/workflows/release.ymlCI: builds signed DMG on v* tag push

Workflow: MAS Release (/release mas)

1. Pre-flight

git branch --show-current          # Must be on release branch or main
git status --porcelain             # Must be clean
node -p "require('./package.json').version"   # Current marketing version
grep buildVersion electron-builder.yml        # Current build number

2. Build

# Clean previous builds
rm -rf dist/mas-arm64

# Build with MAS_BUILD flag (gates HTTP MCP server, auto-updater)
npm run build:mas

3. Verify

# Check .pkg exists
ls -la dist/mas-arm64/*.pkg

# Verify version strings
plutil -p dist/mas-arm64/Prose.app/Contents/Info.plist | grep -E "CFBundleVersion|CFBundleShortVersion"

# Verify code signature
codesign --verify --deep --strict dist/mas-arm64/Prose.app

# Verify entitlements
codesign -d --entitlements - dist/mas-arm64/Prose.app 2>&1 | head -20

Entitlements must include: app-sandbox, allow-jit, network.client, files.user-selected.read-write, bookmarks.app-scope

Entitlements must NOT include: network.server, get-task-allow

4. Upload to App Store Connect

xcrun altool --upload-app \
  --type macos \
  --file dist/mas-arm64/Prose-1.0.0-arm64.pkg \
  --apiKey 73DLM4525G \
  --apiIssuer f46c81a3-3264-4e9d-9b2f-93de6a302175

The API key .p8 file lives at ~/.appstoreconnect/private_keys/AuthKey_73DLM4525G.p8.

5. Report

## MAS Build Uploaded

- **Version:** <version> (build <N>)
- **Package:** dist/mas-arm64/Prose-<version>-arm64.pkg
- **Signed:** Apple Distribution + 3rd Party Mac Developer Installer
- **Delivery UUID:** <from upload output>

### Next steps
1. Wait for processing in App Store Connect (~10 min)
2. Test via **TestFlight** on your Mac
3. **HUMAN ONLY:** When satisfied, submit for App Store review manually in App Store Connect

⚠️ **NEVER submit for App Store review programmatically.** This is always a human decision. The automated workflow stops at TestFlight upload.

Workflow: GitHub Release (/release github)

1. Pre-flight

git branch --show-current          # Should be main (after PR merge)
git status --porcelain             # Must be clean

2. Build

rm -rf dist/mac-arm64
npm run build:mac

3. Verify

# Check outputs
ls -la dist/Prose-*-arm64.dmg dist/Prose-*-arm64-mac.zip

# Verify signature
codesign --verify --deep --strict dist/mac-arm64/Prose.app

# Verify entitlements include network.server (MCP)
codesign -d --entitlements - dist/mac-arm64/Prose.app 2>&1 | grep network.server

4. Write the Release Notes

The notes live at resources/release-notes/<version>.md — one file per version, and the single source of truth (#1058). That same file is bundled into the app (via extraResources) and shown in the post-update modal, and becomes the GitHub Release body: release.yml reads it by tag and appends the install/requirements boilerplate. Write it once, there, and commit it before tagging — the tag is what publishes it.

There is no separate RELEASE_NOTES.md; it was removed in 1.9.0 after sitting stale at v1.2.0 for six releases, which is the exact drift this one-file rule prevents.

VERSION=$(node -p "require('./package.json').version")

# Commits since last release, to write the notes from
git log $(git tag --list 'v*' --sort=-v:refname | head -1)..HEAD --oneline --no-merges

# Confirm the file the release will actually read
test -f "resources/release-notes/${VERSION}.md" || echo "MISSING — write this first"

Template — user-facing changes only. Do not include Installation or Requirements sections: release.yml appends those to the GitHub Release, and in the in-app modal they would be noise.

# Prose v<version>

<One sentence description.>

## <Grouping — e.g. Tables, Fixes, Removed>

- <Feature or fix, in user-facing terms>

The modal renders a deliberately small markdown subset — ##/### headings, bullets, paragraphs, and inline bold/italic/code/links. Anything else shows as literal text, so keep to those (see components/releaseNotes/renderNotes.tsx).

5. Tag and Publish

VERSION=$(node -p "require('./package.json').version")

# Create tag
git tag "v${VERSION}"
git push origin "v${VERSION}"

The tag push triggers release.yml which builds, signs, notarizes, and publishes the DMG + ZIP to GitHub Releases automatically.

If CI is not available or you want to publish manually:

gh release create "v${VERSION}" \
  --title "Prose v${VERSION}" \
  --notes-file "resources/release-notes/${VERSION}.md" \
  "dist/Prose-${VERSION}-arm64.dmg" \
  "dist/Prose-${VERSION}-arm64-mac.zip"

6. Update the marketing copy

The release is not finished when the tag is published. Run /release copy (next section) to bring solo.ist/prose up to the version you just shipped — nothing in CI does this, and the page has drifted five releases behind before.


Workflow: Post-release Marketing Copy (/release copy)

Run this after a GitHub release publishes (and again when a MAS version clears review, if the App Store link or availability changed). The marketing site is a separate repo and nothing in CI touches it — if this step is skipped, solo.ist/prose silently falls behind. It sat pinned at v1.6.2 through five releases because this section didn't exist.

Where the copy lives

RepoPathWhat it is
solo-ist/solo-ist (~/Code/solo.ist)prose/index.htmlThe solo.ist/prose page — hand-authored HTML, no build step
solo-ist/solo-istCOPY.mdCanonical copy mirror for solo.ist and its project pages
solo-ist/prosedocs/app-store-copy.mdApp Store listing copy — canonical here, not in the site repo

Vercel deploys solo-ist/solo-ist on push to main. prose/index.html has no build step — it ships exactly as authored, so a typo is live the moment the PR merges.

1. Pre-flight

git -C ~/Code/solo.ist fetch origin
git -C ~/Code/solo.ist status --porcelain
gh release list --repo solo-ist/prose --limit 10

Working tree must be clean. Branch off freshly-fetched main:

git -C ~/Code/solo.ist checkout -b prose-v<version>-copy origin/main

Use git -C <path> rather than cd && git — compound chains get flagged for manual approval and block unattended agents.

2. Read every release since the last copy update

Not just the newest one. Find where the copy actually left off:

git -C ~/Code/solo.ist log -1 --format=%cI -- prose/index.html    # last time the page moved
gh release view <tag> --repo solo-ist/prose --json body -q .body  # for each tag since

Point releases are where the good material hides — a .5 can carry far more user-facing change than the .0 before it.

3. Walk the version-sensitive surfaces

Check all of these in prose/index.html. Each has gone stale at least once:

#SurfaceCheck against
1Nav version chip (.nav-ver)Latest published release tag
2"What's new" section labelThe current release era
3"What's new" cells (.news-tag / .news-title / .news-desc)Everything shipped since the last copy update
4"What's next" preview celldocs/roadmap.md — reconcile, don't guess
5MCP tool list (.mcp-tools)mcpToolNames in src/shared/tools/registry.ts
6Feature cards (.feat-desc)A release may have widened a feature's scope
7Hero sub-paragraphIts twin in COPY.md — update both or neither
8Download / App Store linksMAS link is live only once that version clears review

4. Write it as marketing, not as a changelog

  • Lead with what the reader can now do, not what was implemented.
  • One idea per cell. If a cell needs a semicolon, it's two cells.
  • Tag each cell with the version that actually introduced the feature (v1.6.5 — Comments), not the version being shipped — readers returning after a gap need to place it.
  • Fold dependency bumps and internal refactors out entirely. If a release is the security story, give it one plainly-stated cell.
  • Never invent a feature. Every claim traces back to a release note.

5. Verify locally

python3 -m http.server 8899 --directory ~/Code/solo.ist

Open http://localhost:8899/prose/. Pick an unused port — other agents may hold the common ones. Confirm the nav chip, the "What's new" grid at both desktop and narrow widths, and that no cell overflows its box.

6. Open the PR

git -C ~/Code/solo.ist add prose/index.html COPY.md
git -C ~/Code/solo.ist commit -m "feat(prose): refresh marketing copy for v<version>"
git -C ~/Code/solo.ist push -u origin prose-v<version>-copy
gh pr create --repo solo-ist/solo-ist --title "Prose v<version> marketing copy" --body "<summary>"

⚠️ Never auto-merge and never push straight to main. Marketing voice is a human call — the PR stops for review even when every fact in it is right.

7. Report

## Marketing Copy — v<version>

- **PR:** <url>
- **Updated:** <surfaces changed>
- **Checked, no change needed:** <surfaces>
- **Left stale, with reason:** <surfaces, or "none">

Workflow: Quick Smoke Test (/release smoke)

Fast (~5 min) verification before tagging a GitHub release. Exercises the signed/notarized artifact users will actually receive — not dev mode. Use this for routine releases. Escalate to /release checklist if the release touches:

  • Main-process IPC handlers or new IPC channels
  • Entitlements (build/entitlements.*.plist)
  • Sandbox / contextIsolation / nodeIntegration settings
  • First build after an Electron major upgrade

1. Build (skip if fresh)

rm -rf dist/mac-arm64
npm run build:mac

2. Verify artifact

VERSION=$(node -p "require('./package.json').version")
ls -la "dist/Prose-${VERSION}-arm64.dmg" "dist/Prose-${VERSION}-arm64-mac.zip"
codesign --verify --deep --strict dist/mac-arm64/Prose.app
codesign -d --entitlements - dist/mac-arm64/Prose.app 2>&1 | grep network.server   # expect a match (MCP)

3. Launch the built app

open dist/mac-arm64/Prose.app

Do NOT use npm run dev — the smoke test must exercise the signed bundle.

4. Walk the 7 critical paths

#PathPass criteria
1App launchesWindow renders, no crash dialog, no console error storm
2Editor round-tripNew file → type a paragraph → Cmd+S → close → reopen, content intact
3Settings dialogOpens cleanly, no outline/focus artifacts, closes cleanly
4API key testSettings → LLM → "Test API Key" returns success with current key
5Chat streamingSend a message in chat panel, response streams in fully
6Skill downloadHelp → Download Prose Skill (or Settings → Integrations) downloads the .zip
7prose:// schemeTrigger a prose:// URL (Claude artifact → Open in Prose) and confirm the app handles it

5. Clean up

rm -f electron-screenshot-*.jpeg

6. Report

## Smoke Test Results — v<version>

- [x] App launches
- [x] Editor round-trip
- [x] Settings dialog
- [x] API key test
- [x] Chat streaming
- [x] Skill download
- [x] prose:// scheme

Ready to tag.

If any path fails, fix before tagging. Do not ship on red smoke.


Workflow: Bump Build Number (/release bump-build)

Used when you need to re-upload to App Store Connect (Transporter rejects duplicate version + build combos).

1. Read current

grep buildVersion electron-builder.yml

2. Increment

Edit electron-builder.yml: increment buildVersion (e.g., "2" → "3").

3. Rebuild and verify

rm -rf dist/mas-arm64
npm run build:mas
plutil -p dist/mas-arm64/Prose.app/Contents/Info.plist | grep CFBundleVersion

4. Commit

git add electron-builder.yml
git commit -m "chore(build): bump build number to <N>"
git push origin <branch>

5. Upload

xcrun altool --upload-app \
  --type macos \
  --file dist/mas-arm64/Prose-1.0.0-arm64.pkg \
  --apiKey 73DLM4525G \
  --apiIssuer f46c81a3-3264-4e9d-9b2f-93de6a302175

Report the delivery UUID and wait for App Store Connect processing.


Workflow: Bump Marketing Version (/release bump-version <version>)

1. Update package.json

npm version <version> --no-git-tag-version

2. Leave buildVersion alone

Do not reset buildVersion. This project uses a global monotonic build counter across marketing versions (e.g., 1.0.0 ended at build 20; first 1.0.1 MAS upload will be build 21). App Store Connect treats version+build as unique either way, and continuous numbering matches the established pattern.

3. Commit

git add package.json package-lock.json
git commit -m "chore: bump version to <version>"

Workflow: Pre-release Checklist (/release checklist)

Run through this before any release:

## Pre-release Checklist

### Build
- [ ] `npm run build` succeeds with no errors
- [ ] `npm run build:mac` produces signed DMG
- [ ] `npm run build:mas` produces signed .pkg
- [ ] `codesign --verify --deep --strict` passes on both builds

### App Verification (DMG build)
- [ ] App launches from dist/mac-arm64/Prose.app
- [ ] Editor: create file, type, save, reopen
- [ ] Settings dialog opens and closes without outline
- [ ] API key test passes (Settings > LLM > Test)
- [ ] Chat works with valid API key
- [ ] Feature flags: Google Docs and reMarkable hidden
- [ ] File explorer: no Google/reMarkable tabs
- [ ] Body does not scroll off screen

### MAS-specific
- [ ] HTTP MCP server disabled (check console for log message)
- [ ] MCP install returns error in MAS build
- [ ] Auto-updater disabled in MAS build

### Security
- [ ] No plaintext secrets in ~/.prose/settings.json
- [ ] DMG entitlements: allow-jit (not allow-unsigned-executable-memory)
- [ ] MAS entitlements: app-sandbox, no network.server
- [ ] Fuses flipped (RunAsNode, NodeOptions, CliInspect all false)

### CI
- [ ] E2E tests pass on PR
- [ ] Code review clean (no blocking issues)

Troubleshooting

Transporter rejects upload

  • "Duplicate version": Bump buildVersion in electron-builder.yml and rebuild
  • "Invalid signature": Check that Apple Distribution cert is in keychain and not expired
  • "Missing provisioning profile": Verify build/Prose_Distribution.provisionprofile exists and bundle ID matches ist.solo.prose

MAS build fails at signing

  • "Cannot find valid 3rd Party Mac Developer Installer": Use team ID (8PT2Y7QQ2F) as identity in mas: block, not cert name
  • afterPack error "Unsupported platform: mas": Ensure build/afterPack.cjs handles the mas case

DMG build hangs

  • Notarization hanging locally: Don't set notarize: true in config. Notarization happens in CI via env vars (APPLE_ID, APPLE_APP_SPECIFIC_PASSWORD). Local builds skip it.

GitHub Release workflow fails

  • Missing secrets: Verify CSC_LINK, CSC_KEY_PASSWORD, APPLE_ID, APPLE_APP_SPECIFIC_PASSWORD, APPLE_TEAM_ID, SENTRY_AUTH_TOKEN are set in repo secrets
  • Signing fails in CI: CSC_LINK must be the base64-encoded .p12 containing the Developer ID Application cert

TestFlight build won't install

  • "App can't be opened": Distribution-signed MAS builds cannot run locally. Only TestFlight or App Store installs work.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.