Release Workflow for ai-todo

Quick Reference

Prepare:

./release/release.sh --prepare [--beta] [--set-version X.Y.Z] --summary release/AI_RELEASE_SUMMARY.md

Dry Run:

./release/release.sh --prepare --dry-run

(preview without committing)

Execute:
```
./release/release.sh --execute
```
Abort:
```
./release/release.sh --abort [version]
```
(cleanup failed release)
Linear Tracking: Release workflow integrated with Linear issues (auto-updates status)
Detailed docs: release/RELEASE_PROCESS.md

Prepare a Release

When user asks to "prepare release" or "prepare beta release":

Check Linear for release issue:
- Search Linear for release-related issues:
```
user-linear.list_issues
```
  with filters for release keywords
- If no issue found: ⚠️ Warn "No Linear release issue found. Do you want to proceed anyway?"
- If one issue found: Show issue details and confirm
- If multiple issues found: Present list and ask user to select one
- Once confirmed: Mark issue as "In Progress" using
```
user-linear.update_issue
```
- Store issue ID for later updates
Pre-flight checks: Verify repository is ready for release:
- Check branch:
```
git branch --show-current
```
  (must be
```
main
```
  )
- Check sync:
```
git fetch origin && git status
```
  (must be in sync with origin/main)
- Check clean:
```
git status --porcelain
```
  (must be empty - no uncommitted changes)
- If any check fails: ⚠️ Warn user with specific issue and ask "Do you want to proceed anyway?"
- If user declines: Stop and let them fix the issue first.
Wait for CI:
```
./scripts/wait-for-ci.sh
```
Generate summary: Create 2-4 paragraphs highlighting user-facing changes. Save to
```
release/AI_RELEASE_SUMMARY.md
```
.
- For beta-to-beta releases: Analyze commits since the last beta tag.
- For stable releases (graduating from beta): Analyze ALL commits since the last stable release (not the last beta). This ensures the summary covers the entire beta cycle.
- See "Generating Release Summary" section below for detailed guidance.

Commit and push summary: The release script requires a clean repository.

```
git add release/AI_RELEASE_SUMMARY.md
```

git commit -m "release: Add AI-generated summary for v[version]"

```
git push
```

Run prepare:

./release/release.sh --prepare [--beta] --summary release/AI_RELEASE_SUMMARY.md

Show preview to user: Display the proposed release notes with clickable link.
- Show
```
release/RELEASE_NOTES.md
```
  summary/preview (first ~20 lines)
- Provide clickable markdown link:
```
[release/RELEASE_NOTES.md](release/RELEASE_NOTES.md)
```
  (not inline code)

Update Linear issue:

Read
```
release/RELEASE_NOTES.md
```
content
Post content to Linear issue as comment using
```
user-linear.create_comment
```

Include clickable link: Add link to full notes at top of comment:

📋 Full Release Notes: [release/RELEASE_NOTES.md](https://github.com/fxstein/ai-todo/blob/main/release/RELEASE_NOTES.md)

Mark issue as "In Review" using
```
user-linear.update_issue
```

STOP. Wait for user approval before proceeding.

Generating Release Summary

Role: You are a Technical Release Manager for a professional Open Source project.

Task: Draft a release summary based on commit messages for end-users (not developers).

Commit Range:

For beta-to-beta releases: Analyze commits since the last beta tag (e.g.,
```
v4.0.0b2..HEAD
```
)
For stable releases (graduating from beta): Analyze ALL commits since the last stable release (e.g.,
```
v3.0.2..HEAD
```
)

Constraints & Formatting:

Format: Write exactly 2-4 paragraphs of narrative text. Do not use bulleted lists or markdown headers (e.g., no
```
#
```
or
```
##
```
).
Content: Focus only on the most significant features, user-facing changes, and critical fixes. Filter out minor chores, typo fixes, or internal refactors unless they directly impact end users.
Documentation: If commits added new documentation files (
```
.md
```
,
```
.pdf
```
), mention them with direct GitHub links:
- Get repo URL:
```
git remote get-url origin
```
  (convert SSH to HTTPS if needed)
- Format:
```
[filename](https://github.com/user/repo/blob/main/path/to/file.md)
```
Tone: Professional, concise, and encouraging. Write for users who want to understand what's new and why they should upgrade.
Output: Save to
```
release/AI_RELEASE_SUMMARY.md
```

Example Structure:

This release focuses on [theme/primary improvement]. [Key feature 1] provides [user benefit]. [Key feature 2] enhances [capability].

[Second major area of improvement]. [Specific change] now allows users to [benefit]. [Another change] improves [aspect] by [improvement].

Additional improvements include [grouped minor features]. Several bug fixes improve robustness including [specific fixes that matter to users].

Generate Commits:

bash

# For beta-to-beta:
git log v4.0.0b2..HEAD --pretty=format:"%h %s" --no-merges

# For stable (graduating from beta):
git log v3.0.2..HEAD --pretty=format:"%h %s" --no-merges

Execute a Release

When user asks to "execute release":

Run execute:
```
./release/release.sh --execute
```
Monitor CI: Watch GitHub Actions until successful deployment:
- Poll
```
gh run list
```
  for latest workflow run
- Wait for "completed" status with "success" conclusion
- If CI fails, report error and STOP (see Error Handling section)
Update Linear issue:
- Read
```
release/RELEASE_SUMMARY.md
```
  content
- Post release summary to Linear issue using
```
user-linear.create_comment
```
- Include PyPI link:
```
https://pypi.org/project/ai-todo/[version]/
```
- Include GitHub release link from workflow output
- Mark issue as "Done" using
```
user-linear.update_issue
```

Abort a Release

When user asks to "abort release":

Run abort:
```
./release/release.sh --abort [version]
```
Update Linear issue (if exists):
- Post abort summary to Linear issue using
```
user-linear.create_comment
```
- Include: reason for abort, version that was aborted, current state
- Mark issue as "Todo" using
```
user-linear.update_issue
```
  (reset for retry)

Error Handling

If ANY error occurs:

STOP IMMEDIATELY.
Report the error.
If Linear issue exists: Post error details to issue
WAIT FOR USER. Do not attempt auto-recovery.

Forbidden Actions

❌ Never auto-execute after prepare.
❌ Never bypass CI/CD failures.
❌ NEVER use
--no-verify
on git commits.

Additional Resources

Detailed Process: release/RELEASE_PROCESS.md
Version Strategy: Beta vs Stable release guidelines in RELEASE_PROCESS.md
Migration Handling: See RELEASE_PROCESS.md for adding migrations to releases
Release Scripts: All scripts are in
```
release/
```
directory

release-workflow

NPX Install

Tags

SKILL.md Content