polish-release-notes.yml

name: Polish Release Notes

# Uses Claude to transform raw changelog into polished release notes.
# Triggered automatically by release-prepare after publishing, or manually.
on:
  repository_dispatch:
    types: [polish-release-notes]
  workflow_dispatch:
    inputs:
      tag_name:
        description: 'Release tag to polish (e.g., v0.18.0)'
        required: true
        type: string

env:
  # repository_dispatch passes tag via client_payload, workflow_dispatch via inputs
  TAG_NAME: ${{ github.event.client_payload.tag_name || inputs.tag_name }}

permissions:
  contents: write

jobs:
  polish:
    # Only run on the main repo, not forks
    if: github.repository == 'Fission-AI/OpenSpec'
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Get current release body
        id: get-release
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh release view "${{ env.TAG_NAME }}" --json body -q '.body' > current-notes.md
          echo "Fetched release notes for ${{ env.TAG_NAME }}"

      - name: Transform release notes with Claude
        uses: anthropics/claude-code-action@v1
        id: claude
        with:
          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
          github_token: ${{ secrets.GITHUB_TOKEN }}
          claude_args: "--allowedTools Write,Read"
          prompt: |
            Transform the changelog in `current-notes.md` into release notes for OpenSpec ${{ env.TAG_NAME }}.

            ## Voice

            OpenSpec is a developer tool. Write like you're talking to a peer:
            - Direct and practical, not marketing copy
            - Focus on what changed and why it matters
            - Skip the hype, keep it real

            ## Output

            Create two files:

            ### 1. `release-title.txt`

            A short title in this format:
            ```
            ${{ env.TAG_NAME }} - [1-4 words describing the release]
            ```

            Examples:
            - `v0.18.0 - OPSX Experimental Workflow`
            - `v0.16.0 - Antigravity, iFlow Support`
            - `v0.15.0 - Gemini CLI, RooCode`

            Rules for title:
            - Lead with the most notable addition
            - 1-4 words after the dash, no fluff
            - If multiple features, comma-separate the top 2
            - For bugfix-only releases, use something like `v0.17.2 - Pre-commit Hook Fix`

            ### 2. `polished-notes.md`

            ```markdown
            ## What's New in ${{ env.TAG_NAME }}

            [One sentence: what's the theme of this release?]

            ### New

            - **Feature name** - What it does and why you'd use it

            ### Improved

            - **Area** - What got better

            ### Fixed

            - What was broken, now works
            ```

            Omit empty sections.

            ## Rules

            1. Write for developers using OpenSpec with AI coding assistants
            2. Remove commit hashes (like `eb152eb:`), PR numbers, and changesets wrappers (`### Minor Changes`)
            3. Lead with what users can do, not implementation details
            4. One to two sentences per item, max
            5. Use **bold** for feature/area names
            6. Skip internal changes (CI, refactors, tests) unless they affect users
            7. If the input is already well-formatted, just clean up structure and remove noise

            ## Example

            Before:
            ```
            ### Minor Changes
            - 8dfd824: Add OPSX experimental workflow commands and enhanced artifact system
              **New Commands:**
              - `/opsx:ff` - Fast-forward through artifact creation
            ```

            After (polished-notes.md):
            ```
            ### New

            - **Fast-forward mode** - Generate all planning artifacts at once with `/opsx:ff`. Useful when you already know what you're building.
            ```

            After (release-title.txt):
            ```
            v0.18.0 - OPSX Experimental Workflow
            ```

            Write both files. No other output.

      - name: Update release
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          TAG="${{ env.TAG_NAME }}"

          if [ -f "polished-notes.md" ] && [ -f "release-title.txt" ]; then
            TITLE=$(cat release-title.txt)
            gh release edit "$TAG" --title "$TITLE" --notes-file polished-notes.md
            echo "Updated: $TITLE"
          elif [ -f "polished-notes.md" ]; then
            gh release edit "$TAG" --notes-file polished-notes.md
            echo "Updated notes (title unchanged)"
          else
            echo "No changes generated, keeping original"
          fi