Add Release Notes Generator workflow with AI-powered categorization

[jyejare]

Summary

This PR adds a new Release Notes Generator workflow to the Ambient Code Platform workflows collection. The workflow uses the utility-mcp-server to fetch git commits and applies AI-powered intelligent categorization to create professional release notes.

Features

AI-Powered Intelligent Categorization

• Dynamic Categories: Creates categories based on actual changes (not predefined templates)
• Context Understanding: Analyzes commits to understand intent beyond pattern matching
• Related Commit Grouping: Groups related changes together intelligently
• Breaking Change Detection: Identifies breaking changes even without conventional commits

Multi-Platform Support

• GitHub: Fetch commits remotely via API (no clone required)
• GitLab: Fetch commits remotely via API (no clone required)
• Local Repos: Works with local git repositories

Automatic Token Handling (CRITICAL)

• ACP Integration: Automatically uses GITHUB_TOKEN and GITLAB_TOKEN from ACP integrations
• Smart Prompting: Asks user for token if not found (3 clear options)
• Graceful Fallback: Offers local cloning if remote access fails
• No Silent Failures: Always offers alternatives

Two Output Modes

Mode 1: AI-Powered (Default - Recommended)

• Tool provides raw commits + AI instructions
• Claude analyzes and categorizes intelligently
• Creates dynamic categories that fit the specific release
• Best for context-aware, professional release notes

Mode 2: Pre-Formatted (For IDE Testing)

• Tool provides pre-formatted markdown
• 10 automatic categories with emojis
• Ready-to-use output
• Best for quick testing in Cursor/VS Code

Workflow Files

.ambient/ambient.json

• Workflow configuration and system prompt
• Token Handling Strategy: Comprehensive instructions for checking ACP integrations
• Two Modes Documentation: When to use AI-powered vs pre-formatted
• Process flow with authentication step

CLAUDE.md

• Detailed instructions for the AI agent
• Section 1.5: Token Handling Strategy with 4 detailed scenarios
• Architecture explanation (two modes)
• Intelligent categorization guidelines
• Error handling examples

README.md

• User-facing documentation
• Quick start guide
• Usage examples
• Troubleshooting section
• Token handling explanation

Token Handling Strategy (Key Feature)

Step 1: Check for ACP Integration Tokens

import os
github_token = os.getenv('GITHUB_TOKEN')  # From ACP integration
gitlab_token = os.getenv('GITLAB_TOKEN')  # From ACP integration

Step 2: Decision Tree

• If token found: Use automatically (no user prompt)
• If NO token: Ask user with 3 options:
  1. Provide a token (recommended for private repos)
  2. Proceed without (works for public repos, rate limits)
  3. Clone locally instead

Step 3: Handle Errors Gracefully

• Authentication failures → Offer token or local clone
• Rate limits → Suggest providing token
• Private repos → Clear guidance on options

Changes Made

Commit 1d03fc8: Documentation Updates

• Documented formatted_output parameter (two modes)
• Removed /generate command reference (not supported by ACP)
• Added mode comparison table
• Updated all documentation files

Commit 5153ddc: Token Handling Strategy (CRITICAL)

• Added comprehensive token handling instructions
• Check for ACP integration tokens first
• User prompting with 3 clear options
• Graceful error handling with fallbacks
• 4 detailed scenario examples

Usage Example

User: "Generate release notes for v1.0.0 from https://github.com/owner/repo"

Workflow:
1. Checks os.getenv('GITHUB_TOKEN') from ACP integration
2. If found: Uses it automatically
3. If not found: Asks user for token or offers alternatives
4. Fetches commits via GitHub API
5. Analyzes commits with AI instructions
6. Creates dynamic categories
7. Generates professional release notes
8. Saves to artifacts/release-notes/

How It Works

Conversational Interface

• No special commands needed (removed misleading /generate reference)
• Natural language: "Generate release notes for v1.0.0"
• Workflow guides user through process

Token Detection

# Workflow automatically checks:
github_token = os.getenv('GITHUB_TOKEN')

if github_token:
    # Use from ACP integration - seamless!
    result = await generate_release_notes(
        version="v1.0.0",
        repo_url="https://github.com/owner/repo",
        github_token=github_token
    )
else:
    # Ask user for token or offer alternatives
    [Prompts user with 3 options]

AI Categorization

• Follows ai_instructions from tool response
• Creates categories based on actual commits
• Groups related changes intelligently
• Explains categorization choices to user

Output Example

# v1.0.0 Release Notes

**Release Date:** 2024-04-12
**Previous Version:** v0.9.0

---

## ⚠️ Breaking Changes

**Authentication System Redesign**
- Complete rewrite of authentication architecture (#156)
- JWT tokens now expire after 1 hour (#178)

## 🎉 New Features

### Real-time Collaboration
- WebSocket support for live updates (#123)
- Presence indicators (#134)

## 🐛 Bug Fixes

### Critical
- Fixed memory leak in WebSocket connections (#134)

## 📊 Release Statistics

- Total Commits: 42
- Contributors: 8
- Pull Requests: 25

Benefits

✅ Seamless ACP Integration: Uses tokens from ACP automatically
✅ Smart Token Handling: Never fails silently, always offers options
✅ No Manual Commands: Conversational interface, no /generate needed
✅ AI-Powered: Intelligent categorization, not regex patterns
✅ Multi-Platform: GitHub, GitLab, and local repos
✅ Two Modes: AI-powered (default) or pre-formatted (IDE testing)
✅ Well-Documented: Comprehensive instructions for AI agent

Testing

• ✅ Token handling scenarios documented
• ✅ Error handling with fallbacks
• ✅ Two modes documented
• ✅ All documentation files updated

Dependencies

Requires:

• utility-mcp-server>=0.2.0 (MCP tool)
• ACP GitHub/GitLab integrations (optional but recommended)

Related

• MCP Tool PR: Add remote repository support and AI-powered release notes generation utility-mcp-server#1

Notes for Reviewers

Key Changes to Review:

1. Token Handling Strategy in .ambient/ambient.json and CLAUDE.md
2. Removal of /generate command (not supported by ACP)
3. Two modes documentation (AI-powered vs pre-formatted)
4. Error handling scenarios with fallback options

Why Token Handling is Critical:

• ACP users expect seamless integration with GitHub/GitLab
• Private repos need tokens
• Public repos benefit from tokens (higher rate limits)
• Must never silently fail - always offer alternatives