feat: Add release notes generator workflow#105
Open
jyejare wants to merge 4 commits intoambient-code:mainfrom
Open
feat: Add release notes generator workflow#105jyejare wants to merge 4 commits intoambient-code:mainfrom
jyejare wants to merge 4 commits intoambient-code:mainfrom
Conversation
Adds a new workflow for generating structured release notes from git commits and tags with automatic categorization. Features: - Automatic categorization (features, bugs, breaking changes, enhancements) - PR number extraction from commit messages - Component detection (API, UI/UX, Database, CLI, etc.) - Professional markdown formatting with emoji indicators - Statistics generation and analytics - /generate command for quick invocation - Conversational mode for guided generation Technical Details: - Uses utility-mcp-server Python package - Automatic tool installation on first use - Outputs to artifacts/release-notes/ - Supports clickable PR/commit links when repo URL provided - Works with conventional commit format Workflow Structure: - .ambient/ambient.json - Workflow configuration - .claude/commands/generate.md - /generate slash command - CLAUDE.md - Persistent context and behavioral guidelines - README.md - User-facing documentation with examples - DEPLOYMENT.md - Complete deployment guide - QUICKSTART.md - Fast-track deployment instructions Output Location: artifacts/release-notes/ Ready for use via Custom Workflow or as official ACP workflow. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Contributor
WalkthroughAdds a Release Notes Generator workflow that includes an Ambient agent configuration, a Changes
Sequence Diagram(s)sequenceDiagram
participant User as User
participant Assistant as ReleaseNotes Assistant
participant MCP as MCP Tool (utility-mcp-server)
participant Git as Git Repo (remote/local)
participant FS as Artifacts (artifacts/release-notes/)
User->>Assistant: request generation (/generate or convo)
Assistant->>Git: validate repo, enumerate tags/commits
alt remote access
Assistant->>Git: fetch using GITHUB_TOKEN/GITLAB_TOKEN
Git-->>Assistant: commit range + metadata
else local path
Assistant-->>Git: read local commits
end
Assistant->>MCP: call generate_release_notes(formatted_output=False)
MCP-->>Assistant: returns raw commits + ai_instructions
Assistant->>Assistant: apply ai_instructions, categorize & format markdown
Assistant->>FS: write RELEASE_NOTES_*.md and commits_*.json
Assistant-->>User: present notes, stats, and artifact locations
Estimated Code Review Effort🎯 3 (Moderate) | ⏱️ ~25 minutes 🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@workflows/release-notes-generator/.claude/commands/generate.md`:
- Around line 107-111: The current execute step changes into
artifacts/release-notes before running generate_<version>.py, but the script
itself calls Path("artifacts/release-notes").mkdir(...) which uses a relative
path and will create nested directories; fix by either updating the execution
command to run from the repo root (use python3
artifacts/release-notes/generate_<version>.py in the "Execute" section) or
modify the script generate_<version>.py to build an absolute path for the
artifacts directory (use
Path(__file__).resolve().parent.joinpath("artifacts/release-notes") or similar
and call mkdir on that Path instead of Path("artifacts/release-notes")).
- Around line 48-105: Summary: The script template uses placeholders (<VERSION>,
<PREVIOUS_VERSION>, <REPO_PATH>, <REPO_URL>) but doesn't tell users to replace
them. Fix: add a short clarifying comment above the script (or at the top of the
main() block) that explicitly lists the placeholders (<VERSION>,
<PREVIOUS_VERSION>, <REPO_PATH>, <REPO_URL>) and instructs the user to replace
them with real values (or supply them via templating/CLI/env) before running;
reference the generate_release_notes call in main() so readers know which
parameters must be populated.
In `@workflows/release-notes-generator/DEPLOYMENT.md`:
- Around line 12-25: Update the deployment snippet to remove the ambiguous
hard-coded path and make the source and destination consistent: replace the
reference to "/workspace/artifacts/release-notes-workflow" with a placeholder or
explanatory comment like "cd /path/to/your/release-notes-generator" and ensure
the subsequent copy command ("cp -r .
/path/to/workflows-repo/workflows/release-notes-generator/") clearly matches
that same source location; also add one short line explaining how users obtain
or generate the workflow files if they aren't already present so both the cd and
cp commands are unambiguous.
- Around line 151-157: The docs currently only mention Python 3.12+ under the
"Tool installation fails" troubleshooting section; add a "Prerequisites" section
near the top (before Quick Start) that explicitly lists Python 3.12+ (and
pip/internet access) or alternately update the "Verification Checklist" heading
to call out "Requires Python 3.12+" so users see the requirement earlier; update
headings referenced ("Quick Start", "Verification Checklist", and "Tool
installation fails") to ensure consistency and add a short note about verifying
python --version.
In `@workflows/release-notes-generator/install-command.sh`:
- Around line 6-14: The install script moves generate_command_temp.md to
.claude/commands/generate.md but doesn't ensure the target directory exists;
before calling mv (the block that handles generate_command_temp.md and
.claude/commands/generate.md), create the directory with a safe recursive mkdir
(e.g., mkdir -p .claude/commands) and handle any mkdir failures so the
subsequent mv succeeds and the existing echo/exit handling remains correct.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 740842b6-df9c-4882-861b-d3ccd73f4903
📒 Files selected for processing (11)
workflows/release-notes-generator/.ambient/ambient.jsonworkflows/release-notes-generator/.claude/commands/generate.mdworkflows/release-notes-generator/.gitignoreworkflows/release-notes-generator/ADD_GENERATE_COMMAND.mdworkflows/release-notes-generator/CLAUDE.mdworkflows/release-notes-generator/COMMAND_TEMPLATE.mdworkflows/release-notes-generator/COMPLETE.mdworkflows/release-notes-generator/DEPLOYMENT.mdworkflows/release-notes-generator/QUICKSTART.mdworkflows/release-notes-generator/README.mdworkflows/release-notes-generator/install-command.sh
Comment on lines
+48
to
+105
| ### 4. Create Generation Script | ||
|
|
||
| Save to `artifacts/release-notes/generate_<version>.py`: | ||
|
|
||
| ```python | ||
| #!/usr/bin/env python3 | ||
| import asyncio | ||
| import json | ||
| from pathlib import Path | ||
| from utility_mcp_server.src.tools.release_notes_tool import generate_release_notes | ||
|
|
||
| async def main(): | ||
| # Ensure output directory exists | ||
| Path("artifacts/release-notes").mkdir(parents=True, exist_ok=True) | ||
|
|
||
| # Generate release notes | ||
| result = await generate_release_notes( | ||
| version="<VERSION>", | ||
| previous_version="<PREVIOUS_VERSION>", | ||
| repo_path="<REPO_PATH>", | ||
| repo_url="<REPO_URL>", | ||
| release_date=None # Uses today's date | ||
| ) | ||
|
|
||
| if result.get("status") == "success": | ||
| # Save release notes | ||
| notes_file = "artifacts/release-notes/RELEASE_NOTES_<VERSION>.md" | ||
| with open(notes_file, "w") as f: | ||
| f.write(result["release_notes"]) | ||
| print(f"✅ Release notes saved to: {notes_file}") | ||
|
|
||
| # Save statistics | ||
| if "statistics" in result: | ||
| stats_file = "artifacts/release-notes/stats_<VERSION>.json" | ||
| with open(stats_file, "w") as f: | ||
| json.dump(result["statistics"], f, indent=2) | ||
| print(f"✅ Statistics saved to: {stats_file}") | ||
|
|
||
| # Display release notes | ||
| print("\n" + "="*80) | ||
| print(result["release_notes"]) | ||
| print("="*80 + "\n") | ||
|
|
||
| # Display statistics | ||
| if "statistics" in result: | ||
| print("📊 Statistics:") | ||
| for key, value in result["statistics"].items(): | ||
| print(f" {key}: {value}") | ||
|
|
||
| return result | ||
| else: | ||
| error_msg = result.get("error", "Unknown error") | ||
| print(f"❌ Error: {error_msg}") | ||
| return result | ||
|
|
||
| if __name__ == "__main__": | ||
| asyncio.run(main()) | ||
| ``` |
Contributor
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Clarify that placeholders must be replaced.
The script template contains placeholders like <VERSION>, <PREVIOUS_VERSION>, <REPO_PATH>, and <REPO_URL> (lines 65-68, 74, 81), but there's no explicit instruction that these must be replaced with actual values. While this may be obvious in context, adding a brief comment above the script template would improve clarity.
📝 Suggested documentation improvement
### 4. Create Generation Script
+Replace `<VERSION>`, `<PREVIOUS_VERSION>`, `<REPO_PATH>`, and `<REPO_URL>` with actual values.
+
Save to `artifacts/release-notes/generate_<version>.py`:📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| ### 4. Create Generation Script | |
| Save to `artifacts/release-notes/generate_<version>.py`: | |
| ```python | |
| #!/usr/bin/env python3 | |
| import asyncio | |
| import json | |
| from pathlib import Path | |
| from utility_mcp_server.src.tools.release_notes_tool import generate_release_notes | |
| async def main(): | |
| # Ensure output directory exists | |
| Path("artifacts/release-notes").mkdir(parents=True, exist_ok=True) | |
| # Generate release notes | |
| result = await generate_release_notes( | |
| version="<VERSION>", | |
| previous_version="<PREVIOUS_VERSION>", | |
| repo_path="<REPO_PATH>", | |
| repo_url="<REPO_URL>", | |
| release_date=None # Uses today's date | |
| ) | |
| if result.get("status") == "success": | |
| # Save release notes | |
| notes_file = "artifacts/release-notes/RELEASE_NOTES_<VERSION>.md" | |
| with open(notes_file, "w") as f: | |
| f.write(result["release_notes"]) | |
| print(f"✅ Release notes saved to: {notes_file}") | |
| # Save statistics | |
| if "statistics" in result: | |
| stats_file = "artifacts/release-notes/stats_<VERSION>.json" | |
| with open(stats_file, "w") as f: | |
| json.dump(result["statistics"], f, indent=2) | |
| print(f"✅ Statistics saved to: {stats_file}") | |
| # Display release notes | |
| print("\n" + "="*80) | |
| print(result["release_notes"]) | |
| print("="*80 + "\n") | |
| # Display statistics | |
| if "statistics" in result: | |
| print("📊 Statistics:") | |
| for key, value in result["statistics"].items(): | |
| print(f" {key}: {value}") | |
| return result | |
| else: | |
| error_msg = result.get("error", "Unknown error") | |
| print(f"❌ Error: {error_msg}") | |
| return result | |
| if __name__ == "__main__": | |
| asyncio.run(main()) | |
| ``` | |
| ### 4. Create Generation Script | |
| Replace `<VERSION>`, `<PREVIOUS_VERSION>`, `<REPO_PATH>`, and `<REPO_URL>` with actual values. | |
| Save to `artifacts/release-notes/generate_<version>.py`: | |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@workflows/release-notes-generator/.claude/commands/generate.md` around lines
48 - 105, Summary: The script template uses placeholders (<VERSION>,
<PREVIOUS_VERSION>, <REPO_PATH>, <REPO_URL>) but doesn't tell users to replace
them. Fix: add a short clarifying comment above the script (or at the top of the
main() block) that explicitly lists the placeholders (<VERSION>,
<PREVIOUS_VERSION>, <REPO_PATH>, <REPO_URL>) and instructs the user to replace
them with real values (or supply them via templating/CLI/env) before running;
reference the generate_release_notes call in main() so readers know which
parameters must be populated.
Comment on lines
+107
to
+111
| ### 5. Execute | ||
|
|
||
| ```bash | ||
| cd artifacts/release-notes && python3 generate_<version>.py | ||
| ``` |
Contributor
There was a problem hiding this comment.
Path inconsistency between script and execution.
The execution step changes directory to artifacts/release-notes/ before running the script, but the script itself (line 61) uses Path("artifacts/release-notes").mkdir(...) which is a relative path. If executed from within artifacts/release-notes/, this would create artifacts/release-notes/artifacts/release-notes/, causing the script to fail or write to the wrong location.
🔧 Proposed fix
Either execute from the repository root:
-### 5. Execute
-
-```bash
-cd artifacts/release-notes && python3 generate_<version>.py
-```
+### 5. Execute
+
+```bash
+python3 artifacts/release-notes/generate_<version>.py
+```Or update the script to use absolute paths or adjust for the current directory.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| ### 5. Execute | |
| ```bash | |
| cd artifacts/release-notes && python3 generate_<version>.py | |
| ``` | |
| ### 5. Execute | |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@workflows/release-notes-generator/.claude/commands/generate.md` around lines
107 - 111, The current execute step changes into artifacts/release-notes before
running generate_<version>.py, but the script itself calls
Path("artifacts/release-notes").mkdir(...) which uses a relative path and will
create nested directories; fix by either updating the execution command to run
from the repo root (use python3 artifacts/release-notes/generate_<version>.py in
the "Execute" section) or modify the script generate_<version>.py to build an
absolute path for the artifacts directory (use
Path(__file__).resolve().parent.joinpath("artifacts/release-notes") or similar
and call mkdir on that Path instead of Path("artifacts/release-notes")).
Comment on lines
+12
to
+25
| ```bash | ||
| cd /workspace/artifacts/release-notes-workflow | ||
|
|
||
| # Initialize git if needed | ||
| git init | ||
|
|
||
| # Or copy to your workflows repo | ||
| cp -r . /path/to/workflows-repo/workflows/release-notes-generator/ | ||
|
|
||
| cd /path/to/workflows-repo | ||
| git add workflows/release-notes-generator | ||
| git commit -m "feat: Add release notes generator workflow" | ||
| git push origin main # or your feature branch | ||
| ``` |
Contributor
There was a problem hiding this comment.
Path inconsistency in deployment instructions.
Line 13 references /workspace/artifacts/release-notes-workflow without establishing where this directory comes from or how users should get there. Then line 19 copies from the current directory (.) which contradicts the earlier path reference. This creates confusion about where the workflow files are located.
🔧 Suggested clarification
2. **Push this workflow**:
```bash
- cd /workspace/artifacts/release-notes-workflow
+ # Navigate to where you created/stored the workflow files
+ cd /path/to/your/release-notes-generator
# Initialize git if needed
git initOr provide a clearer explanation of where /workspace/artifacts/release-notes-workflow comes from in the workflow creation process.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| ```bash | |
| cd /workspace/artifacts/release-notes-workflow | |
| # Initialize git if needed | |
| git init | |
| # Or copy to your workflows repo | |
| cp -r . /path/to/workflows-repo/workflows/release-notes-generator/ | |
| cd /path/to/workflows-repo | |
| git add workflows/release-notes-generator | |
| git commit -m "feat: Add release notes generator workflow" | |
| git push origin main # or your feature branch | |
| ``` |
🧰 Tools
🪛 markdownlint-cli2 (0.22.0)
[warning] 12-12: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@workflows/release-notes-generator/DEPLOYMENT.md` around lines 12 - 25, Update
the deployment snippet to remove the ambiguous hard-coded path and make the
source and destination consistent: replace the reference to
"/workspace/artifacts/release-notes-workflow" with a placeholder or explanatory
comment like "cd /path/to/your/release-notes-generator" and ensure the
subsequent copy command ("cp -r .
/path/to/workflows-repo/workflows/release-notes-generator/") clearly matches
that same source location; also add one short line explaining how users obtain
or generate the workflow files if they aren't already present so both the cd and
cp commands are unambiguous.
Comment on lines
+151
to
+157
| ### Tool installation fails | ||
|
|
||
| **Check**: | ||
| - Python 3.12+ is available in ACP session | ||
| - pip works and has internet access | ||
| - Package name is correct: `utility-mcp-server` | ||
|
|
Contributor
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
What is the minimum Python version required for the utility-mcp-server package?
💡 Result:
The minimum Python version required by utility-mcp-server is Python 3.12 (it specifies Requires-Python: >=3.12, <3.14). [1]
🏁 Script executed:
cat -n workflows/release-notes-generator/DEPLOYMENT.mdRepository: ambient-code/workflows
Length of output: 8464
Python 3.12+ requirement should be documented earlier, not just in troubleshooting.
The Python 3.12+ version requirement appears only in the troubleshooting section (line 154), but users attempting deployment from the Quick Start or Verification Checklist will encounter it without prior notice. Add a Prerequisites section near the top of the guide listing Python 3.12+ as a requirement, or reference it explicitly in the Verification Checklist (line 106).
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@workflows/release-notes-generator/DEPLOYMENT.md` around lines 151 - 157, The
docs currently only mention Python 3.12+ under the "Tool installation fails"
troubleshooting section; add a "Prerequisites" section near the top (before
Quick Start) that explicitly lists Python 3.12+ (and pip/internet access) or
alternately update the "Verification Checklist" heading to call out "Requires
Python 3.12+" so users see the requirement earlier; update headings referenced
("Quick Start", "Verification Checklist", and "Tool installation fails") to
ensure consistency and add a short note about verifying python --version.
Comment on lines
+6
to
+14
| # Move the temp file to the correct location | ||
| if [ -f "generate_command_temp.md" ]; then | ||
| mv generate_command_temp.md .claude/commands/generate.md | ||
| echo "✅ Successfully installed /generate command at .claude/commands/generate.md" | ||
| else | ||
| echo "❌ Error: generate_command_temp.md not found" | ||
| echo "Make sure you're running this from the workflow directory" | ||
| exit 1 | ||
| fi |
Contributor
There was a problem hiding this comment.
Create target directory before moving the file.
The script attempts to move generate_command_temp.md to .claude/commands/generate.md without first ensuring the .claude/commands/ directory exists. This will cause the mv command to fail if the directory structure hasn't been created yet.
📁 Proposed fix to create directory structure
# Move the temp file to the correct location
if [ -f "generate_command_temp.md" ]; then
+ mkdir -p .claude/commands
mv generate_command_temp.md .claude/commands/generate.md
echo "✅ Successfully installed /generate command at .claude/commands/generate.md"📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| # Move the temp file to the correct location | |
| if [ -f "generate_command_temp.md" ]; then | |
| mv generate_command_temp.md .claude/commands/generate.md | |
| echo "✅ Successfully installed /generate command at .claude/commands/generate.md" | |
| else | |
| echo "❌ Error: generate_command_temp.md not found" | |
| echo "Make sure you're running this from the workflow directory" | |
| exit 1 | |
| fi | |
| # Move the temp file to the correct location | |
| if [ -f "generate_command_temp.md" ]; then | |
| mkdir -p .claude/commands | |
| mv generate_command_temp.md .claude/commands/generate.md | |
| echo "✅ Successfully installed /generate command at .claude/commands/generate.md" | |
| else | |
| echo "❌ Error: generate_command_temp.md not found" | |
| echo "Make sure you're running this from the workflow directory" | |
| exit 1 | |
| fi |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@workflows/release-notes-generator/install-command.sh` around lines 6 - 14,
The install script moves generate_command_temp.md to
.claude/commands/generate.md but doesn't ensure the target directory exists;
before calling mv (the block that handles generate_command_temp.md and
.claude/commands/generate.md), create the directory with a safe recursive mkdir
(e.g., mkdir -p .claude/commands) and handle any mkdir failures so the
subsequent mv succeeds and the existing echo/exit handling remains correct.
Updated release-notes-generator workflow to follow Option B architecture where categorization instructions come from the MCP tool response. ## What Changed ### .ambient/ambient.json - Updated systemPrompt to emphasize following ai_instructions from tool - Changed from "YOU analyze" to "Follow the tool's ai_instructions" - Added example of ai_instructions structure in tool response - Documented process: extract instructions → follow guidelines → apply strategy - Updated startupPrompt to mention embedded instructions ### CLAUDE.md - Updated Architecture section: Tool provides data + instructions - Changed "Your Job" from creating instructions to following them - Updated Process Flow: Shows extracting ai_instructions from response - Updated "Analyze and Categorize" section to reference tool instructions - Changed "Intelligent Categorization Guidelines" to "Follow the Tool's Instructions" - Added code examples showing how to extract and use instructions ### README.md - Updated "How It Works" section to mention embedded instructions - Explained two-part architecture with instructions in tool response - Updated example output to show ai_instructions field - Added benefits of embedded instructions ## Architecture ``` OLD: Instructions hardcoded in workflow files NEW: Instructions embedded in MCP tool response Workflow: 1. Calls generate_release_notes() 2. Extracts ai_instructions from response 3. Follows the tool's guidelines 4. Creates categories per tool's strategy 5. Formats per tool's output_format spec ``` ## Benefits ✅ Instructions version-controlled with tool (single source of truth) ✅ Always in sync with tool capabilities ✅ Consistent across all workflows using the tool ✅ Self-documenting - tool tells AI how to use its data Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
…ate command - Document two modes: AI-Powered (default) and Pre-Formatted (IDE usage) - Remove /generate command reference (not supported by ACP) - Add formatted_output parameter documentation - Explain when to use each mode - Update CLAUDE.md with mode comparison table - Update README.md with advanced features section This aligns with MCP tool v0.2.0 changes that added the formatted_output parameter for direct IDE usage while keeping AI-powered categorization as the default for workflows. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
CRITICAL: Workflow now properly handles GitHub/GitLab authentication
Changes:
- Check for GITHUB_TOKEN and GITLAB_TOKEN from ACP integrations first
- Ask user for token if not found (3 options: provide, skip, or local clone)
- Handle authentication errors gracefully with fallback options
- Never silently fail - always offer alternatives
Token Handling Flow:
1. Check os.getenv('GITHUB_TOKEN') or os.getenv('GITLAB_TOKEN')
2. If found: Use automatically (no user prompt needed)
3. If not found: Ask user for token, proceed without, or use local clone
4. If remote fails: Offer to provide token or clone locally
This ensures:
- ACP integrations work seamlessly
- Users without integrations get clear options
- Private repos can fallback to local cloning
- No silent failures or confusing errors
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@workflows/release-notes-generator/.ambient/ambient.json`:
- Line 4: The Token Handling Strategy currently instructs asking users to
"Provide a token" in-chat, which risks secret leakage; update the Token Handling
Strategy and all user prompt text to forbid pasting tokens into chat and require
ACP integration/env vars (GITHUB_TOKEN, GITLAB_TOKEN) or a secure secret-input
UX (or local repo path) instead, revise examples that show user chat-provided
tokens (e.g., generate_release_notes usage) to show using environment variables
or secure UI, and change decision-tree steps and error-handling prompts to offer
secure alternatives (set env var, use ACP integration, use secure secret dialog,
or clone locally) rather than asking for raw tokens in messages.
In `@workflows/release-notes-generator/CLAUDE.md`:
- Around line 91-99: Update the "If NO token found:" guidance to remove any
examples that ask users to paste raw GitHub/GitLab tokens (e.g., the inline
token prompt shown in the quoted block) and instead first check for
ACP/integrations or environment variables (GITHUB_TOKEN/GITLAB_TOKEN)
programmatically; replace the three-option prompt with secure acquisition
options (use ACP integration, instruct user to set env vars or use a
secret-prompt flow, or provide steps to authenticate via OAuth/CLI) and
explicitly state "do not paste tokens into chat" (apply the same changes to the
related section referenced around lines 135-158).
- Around line 12-37: The documentation repeats canonical policy blocks (mode
selection, token decision tree, formatted_output policy) across multiple
sections (e.g., the "Mode 1"/"Mode 2" headings and the "Your Job" block);
extract these repeated rules into a single canonical policy section or file (eg.
"Canonical Policy" or "POLICY.md") and replace the duplicated blocks in
CLAUDE.md and the other ranges (70-203, 478-529) with a short reference/link to
that canonical policy; ensure the referenced headings ("Mode 1", "Mode 2", "Your
Job", and the formatted_output policy) are updated to point to the canonical
source so runtime behavior and docs remain aligned and not duplicated.
In `@workflows/release-notes-generator/README.md`:
- Around line 11-39: The README's "Two-Part Architecture" section duplicates
workflow/mode/token rules that also live in CLAUDE.md and .ambient/ambient.json;
pick a single canonical source (e.g., .ambient/ambient.json or CLAUDE.md) to
hold the authoritative rules, remove the duplicated block in README (the
"Two-Part Architecture" section) and replace it with a short pointer to the
canonical document, and update CLAUDE.md and .ambient/ambient.json to reference
that canonical file as needed so all guidance (architecture/mode/token rules) is
maintained in one place and other docs only link to or summarize it.
- Around line 99-104: Replace the unsafe “Provide token” phrasing in the
Authentication section (the line that reads "Provide token, proceed without, or
use local clone?") with explicit instructions to use ACP integration tokens
(GITHUB_TOKEN/GITLAB_TOKEN), environment variables, or a secret manager/CI
secret injection flow; add a short, prominent warning: never paste raw tokens
into chats, issue comments, or public fields. Update the same wording at the
other occurrences mentioned (the repeated prompt-like strings) so all instances
consistently reference ACP integrations/env vars/secret management and include
the no-raw-token warning.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 34f2616c-6ac8-4655-82af-963a112c6f1f
📒 Files selected for processing (3)
workflows/release-notes-generator/.ambient/ambient.jsonworkflows/release-notes-generator/CLAUDE.mdworkflows/release-notes-generator/README.md
| { | ||
| "name": "Release Notes Generator", | ||
| "description": "Generate structured release notes from git commits and tags with AI-powered intelligent categorization guided by embedded instructions from the MCP tool", | ||
| "systemPrompt": "You are a release notes generation specialist with AI-powered intelligent categorization. You create professional, structured release notes from git commit history.\n\n## Your Role\n\nHelp users generate comprehensive release notes by:\n1. Using the MCP tool to fetch commit data AND categorization instructions\n2. **Following the tool's ai_instructions** to categorize commits intelligently\n3. **Applying the tool's guidelines** to create dynamic categories\n4. Generating markdown-formatted release notes ready for GitHub releases\n\n## Architecture (CRITICAL)\n\n**MCP Tool Provides TWO MODES**:\n\n### Mode 1: AI-Powered (formatted_output=False - DEFAULT for this workflow)\n- Raw commit data from GitHub/GitLab/local repos (hash, message, author, date, PR/MR number)\n- **Comprehensive ai_instructions field** with categorization guidance\n- Instructions include: role, task, guidelines, categorization strategy, suggested sections, output format, context understanding examples, best practices\n- **YOU analyze and categorize** commits using the tool's instructions\n\n### Mode 2: Pre-Formatted (formatted_output=True - for direct IDE usage)\n- Pre-formatted markdown with automatic categorization (10 categories with emojis)\n- Categories: Breaking Changes, Security, Features, Bug Fixes, Performance, Documentation, Refactoring, Testing, Chores, Other\n- Use this only when user explicitly requests pre-formatted output or for testing in IDEs\n- **Not recommended for this workflow** - defeats the purpose of AI-powered intelligent categorization\n\n**YOUR Responsibility (Mode 1 - Default)**:\n- **Always use formatted_output=False** (default) for AI-powered categorization\n- **Extract ai_instructions** from the tool response\n- **Follow the guidelines** provided by the tool\n- **Apply the categorization strategy** to analyze commits\n- **Use suggested sections** as guidance for categories\n- **Format according to output_format** specification\n- **Explain how you applied** the tool's instructions\n\n## How to Help Users\n\n**Gather Information**:\n- Current version tag (required)\n- Previous version tag (optional - tool auto-detects if omitted)\n- Repository URL for remote repos (GitHub/GitLab) OR repo path for local\n- GitHub/GitLab token (see Token Handling Strategy below)\n- formatted_output parameter (default: False for AI-powered mode, set True only if user requests pre-formatted output)\n\n**Output Location**: All generated files go to `artifacts/release-notes/`\n\n## Token Handling Strategy (CRITICAL)\n\nWhen user provides a **remote repository URL** (GitHub or GitLab):\n\n### Step 1: Check for ACP Integration Tokens\n```python\nimport os\ngithub_token = os.getenv('GITHUB_TOKEN') # From ACP GitHub integration\ngitlab_token = os.getenv('GITLAB_TOKEN') # From ACP GitLab integration\n```\n\n### Step 2: Decision Tree\n\n**If token found in environment:**\n- Use it automatically (no need to ask user)\n- Proceed with remote fetch\n- Example: `generate_release_notes(version='v1.0.0', repo_url='...', github_token=github_token)`\n\n**If NO token found:**\n- Ask user: \"I don't have a GitHub/GitLab token configured. Would you like to:\n 1. Provide a token (recommended for private repos and better rate limits)\n 2. Proceed without a token (works for public repos, has rate limits)\n 3. Clone the repository locally instead\"\n\n**User Response Handling:**\n- **Option 1 (Provides token)**: Use the token they provide\n- **Option 2 (No token)**: Try without token (github_token=None), may fail for private repos\n- **Option 3 (Local clone)**: Ask for local path or offer to clone the repo, then use repo_path parameter\n\n### Step 3: Handle Errors Gracefully\n\n**If remote fetch fails (401/403/404):**\n- Explain: \"Failed to access repository. This might be a private repo requiring a token.\"\n- Offer fallback: \"Would you like to provide a token or clone the repository locally?\"\n\n**If rate limit exceeded:**\n- Explain: \"GitHub API rate limit exceeded. A token would increase limits.\"\n- Offer: \"Would you like to provide a token or try again later?\"\n\n### Examples\n\n**Example 1: Token found in ACP integrations**\n```python\n# Check for token from ACP integration\ngithub_token = os.getenv('GITHUB_TOKEN')\nif github_token:\n # Use it automatically - no need to ask user\n result = await generate_release_notes(\n version='v1.0.0',\n repo_url='https://github.com/owner/repo',\n github_token=github_token\n )\n```\n\n**Example 2: No token, ask user**\n```\nYou: \"I don't have a GitHub token configured. Would you like to:\n 1. Provide a token (recommended for private repos)\n 2. Try without a token (works for public repos)\n 3. Use a local clone instead\"\n\nUser: \"Try without it\"\n\nYou: [Proceed with github_token=None]\n```\n\n**Example 3: Fallback to local**\n```\nYou: \"Failed to access the repository remotely (might be private). Would you like to clone it locally instead?\"\n\nUser: \"Yes\"\n\nYou: [Offer to clone or ask for local path, then use repo_path parameter]\n```\n\n## Process Flow\n\n1. **Gather Information**: Get version tags and repository details\n2. **Handle Authentication**: Follow Token Handling Strategy above\n3. **Call MCP Tool**: Use `generate_release_notes()` with appropriate parameters\n4. **Extract Instructions**: `instructions = result['ai_instructions']`\n5. **Read Commits**: `commits = result['data']['commits']`\n6. **Follow Instructions**: Apply guidelines, strategy, and formatting from tool\n7. **Generate Notes**: Create dynamic categories based on actual commits\n8. **Save Output**: Save to `artifacts/release-notes/RELEASE_NOTES_<version>.md`\n9. **Present Results**: Show notes and explain how you applied instructions\n\n## Using the Tool's Instructions\n\nThe tool response includes:\n```json\n{\n \"ai_instructions\": {\n \"role\": \"release_notes_categorizer\",\n \"task\": \"Analyze commits and create intelligent release notes\",\n \"guidelines\": [\n \"Create dynamic categories based on actual changes\",\n \"Group related commits intelligently\",\n \"Understand context beyond pattern matching\",\n ...\n ],\n \"categorization_strategy\": {\n \"step1\": \"Read all commits first\",\n \"step2\": \"Identify major themes\",\n \"step3\": \"Create relevant categories\",\n \"step4\": \"Group intelligently\",\n \"step5\": \"Prioritize important changes\"\n },\n \"suggested_sections\": {\n \"always_consider\": [\"Breaking Changes\", \"Security\", \"Features\", \"Bug Fixes\"],\n \"conditionally_add\": [\"Performance\", \"Documentation\", ...]\n },\n \"output_format\": {...},\n \"context_understanding\": {...},\n \"best_practices\": [...]\n }\n}\n```\n\n**How to apply:**\n1. Extract instructions from response\n2. Follow each guideline when analyzing commits\n3. Use the categorization_strategy steps\n4. Consider suggested_sections for creating categories\n5. Format output according to output_format spec\n6. Apply context_understanding examples to interpret commits\n7. Follow best_practices for presentation\n\n## Key Points\n\n- **Check for tokens from ACP integrations first** (GITHUB_TOKEN, GITLAB_TOKEN environment variables)\n- **Ask user if no token found** - don't assume, offer options\n- **Fallback to local clone** if remote access fails\n- **Instructions are in the tool response** - always extract and use them\n- **Guidelines are version-controlled with the tool** - always up to date\n- **Dynamic categorization** - create categories that fit THIS release\n- **Context understanding** - apply tool's examples to understand commits\n- **Explain your work** - tell users how you applied the instructions\n- **formatted_output parameter exists** - but don't use it for this AI workflow\n\n## Quality Guidelines\n\n- Always check for GITHUB_TOKEN or GITLAB_TOKEN environment variables first\n- Ask user for token or offer alternatives if not found\n- Handle authentication errors gracefully with fallback options\n- Always use formatted_output=False (default) for AI-powered categorization\n- Always extract and follow ai_instructions from tool response\n- Apply ALL guidelines provided by the tool\n- Use the tool's categorization strategy step-by-step\n- Consider both always_consider and conditionally_add sections\n- Format output exactly as specified in output_format\n- Explain to users how you applied the tool's instructions", |
Contributor
There was a problem hiding this comment.
Avoid collecting access tokens via chat text.
The prompt currently normalizes “provide a token” in-conversation, which risks secret exposure in chat logs/transcripts. Require ACP integration/env vars (or secure secret input UX) and explicitly tell users not to paste raw tokens into messages.
As per coding guidelines **: "Focus on major issues impacting performance, readability, maintainability and security. Avoid nitpicks and avoid verbosity."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@workflows/release-notes-generator/.ambient/ambient.json` at line 4, The Token
Handling Strategy currently instructs asking users to "Provide a token" in-chat,
which risks secret leakage; update the Token Handling Strategy and all user
prompt text to forbid pasting tokens into chat and require ACP integration/env
vars (GITHUB_TOKEN, GITLAB_TOKEN) or a secure secret-input UX (or local repo
path) instead, revise examples that show user chat-provided tokens (e.g.,
generate_release_notes usage) to show using environment variables or secure UI,
and change decision-tree steps and error-handling prompts to offer secure
alternatives (set env var, use ACP integration, use secure secret dialog, or
clone locally) rather than asking for raw tokens in messages.
Comment on lines
+12
to
+37
| #### Mode 1: AI-Powered (formatted_output=False - DEFAULT for this workflow) | ||
| - Connects to GitHub/GitLab (remote) or local git repos | ||
| - Extracts commits between version tags | ||
| - Returns: hash, message, author, date, PR/MR number | ||
| - **Includes `ai_instructions`** with comprehensive categorization guidance | ||
| - **Does NOT categorize or format** - just returns raw data + instructions | ||
| - **Best for**: AI agents that can intelligently categorize based on context | ||
|
|
||
| #### Mode 2: Pre-Formatted (formatted_output=True - for direct IDE usage) | ||
| - Same data fetching as Mode 1 | ||
| - **Automatically categorizes** commits into 10 predefined categories: | ||
| * ⚠️ Breaking Changes, 🔒 Security Updates, 🎉 New Features, 🐛 Bug Fixes | ||
| * ⚡ Performance Improvements, 📚 Documentation, 🔄 Refactoring | ||
| * 🧪 Testing, 🔧 Chores, 📦 Other Changes | ||
| - Returns pre-formatted markdown with emojis and statistics | ||
| - **Best for**: Direct IDE usage (Cursor, VS Code) where Claude doesn't follow instructions well | ||
| - **Not recommended for this workflow** - defeats the purpose of AI-powered categorization | ||
|
|
||
| ### Your Job (Follow Tool's Instructions - Mode 1) | ||
| **The tool tells you exactly how to categorize commits:** | ||
| - **Always use formatted_output=False** (default) for AI-powered categorization | ||
| - **Follow `ai_instructions`** provided in the tool response | ||
| - **Instructions include**: guidelines, categorization strategy, suggested sections, output format | ||
| - **Instructions are version-controlled** with the tool (always in sync) | ||
| - **Your expertise**: Apply the instructions intelligently to the specific commits | ||
|
|
Contributor
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Refactor repeated policy blocks to prevent instruction drift.
Mode selection + token decision tree + formatted_output policy are repeated in multiple long sections and across files. Extract canonical policy once and reference it to keep runtime behavior and docs aligned.
As per coding guidelines **: "Focus on major issues impacting performance, readability, maintainability and security. Avoid nitpicks and avoid verbosity."
Also applies to: 70-203, 478-529
🧰 Tools
🪛 markdownlint-cli2 (0.22.0)
[warning] 12-12: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 20-20: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 30-30: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@workflows/release-notes-generator/CLAUDE.md` around lines 12 - 37, The
documentation repeats canonical policy blocks (mode selection, token decision
tree, formatted_output policy) across multiple sections (e.g., the "Mode
1"/"Mode 2" headings and the "Your Job" block); extract these repeated rules
into a single canonical policy section or file (eg. "Canonical Policy" or
"POLICY.md") and replace the duplicated blocks in CLAUDE.md and the other ranges
(70-203, 478-529) with a short reference/link to that canonical policy; ensure
the referenced headings ("Mode 1", "Mode 2", "Your Job", and the
formatted_output policy) are updated to point to the canonical source so runtime
behavior and docs remain aligned and not duplicated.
Comment on lines
+91
to
+99
| **If NO token found:** | ||
| - ❌ Don't silently fail or assume | ||
| - 💬 Ask user: | ||
| ``` | ||
| "I don't have a GitHub token configured. Would you like to: | ||
| 1. Provide a token (recommended for private repos and better rate limits) | ||
| 2. Proceed without a token (works for public repos, has rate limits) | ||
| 3. Clone the repository locally instead" | ||
| ``` |
Contributor
There was a problem hiding this comment.
Do not instruct users to share raw GitHub/GitLab tokens in conversation.
This guidance includes token-sharing examples in chat (e.g., ghp_xxx...), which is a credential-leak risk. Replace with secure acquisition paths only (ACP integration/env vars/secret prompt), and state explicitly that tokens must never be pasted into chat text.
Based on learnings: "Check for GITHUB_TOKEN or GITLAB_TOKEN environment variables from ACP integrations first before asking users for authentication credentials."
Also applies to: 135-158
🧰 Tools
🪛 markdownlint-cli2 (0.22.0)
[warning] 94-94: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 94-94: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@workflows/release-notes-generator/CLAUDE.md` around lines 91 - 99, Update the
"If NO token found:" guidance to remove any examples that ask users to paste raw
GitHub/GitLab tokens (e.g., the inline token prompt shown in the quoted block)
and instead first check for ACP/integrations or environment variables
(GITHUB_TOKEN/GITLAB_TOKEN) programmatically; replace the three-option prompt
with secure acquisition options (use ACP integration, instruct user to set env
vars or use a secret-prompt flow, or provide steps to authenticate via
OAuth/CLI) and explicitly state "do not paste tokens into chat" (apply the same
changes to the related section referenced around lines 135-158).
Comment on lines
+11
to
+39
| ### Two-Part Architecture | ||
|
|
||
| The MCP tool provides **two modes** of operation: | ||
|
|
||
| **Mode 1: AI-Powered (Default - Recommended for this workflow)** | ||
| - **MCP Tool**: Fetches raw commit data + provides AI instructions | ||
| - **Claude AI**: Analyzes commits, creates dynamic categories, formats intelligently | ||
| - **Best for**: Context-aware release notes with custom categories | ||
|
|
||
| **Mode 2: Pre-Formatted (For direct IDE usage)** | ||
| - **MCP Tool**: Fetches commits + automatically categorizes into 10 predefined categories | ||
| - **Output**: Ready-to-use markdown with emojis and statistics | ||
| - **Best for**: Quick testing in Cursor/VS Code, no AI analysis needed | ||
|
|
||
| **This Workflow Uses Mode 1:** | ||
| 1. **MCP Tool (Data Fetching)** | ||
| - Fetches raw commit data from GitHub/GitLab/local repos | ||
| - Extracts: commit hash, message, author, date, PR/MR numbers | ||
| - Provides AI instructions for intelligent categorization | ||
| - **Does NOT categorize** - just returns structured data + instructions | ||
|
|
||
| 2. **Claude AI (Intelligence)** | ||
| - **Analyzes** commit messages to understand actual changes | ||
| - **Creates dynamic categories** that fit your release (not predefined templates) | ||
| - **Groups related changes** intelligently | ||
| - **Formats professional release notes** with context and clarity | ||
|
|
||
| This separation means you get **smarter categorization** than regex-based tools can provide. | ||
|
|
Contributor
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Consolidate duplicated workflow rules into a single source of truth.
Architecture/mode/token rules are duplicated across README, CLAUDE.md, and .ambient/ambient.json. This is a high drift risk for behavior-critical guidance. Keep canonical rules in one document and reference it from the others.
As per coding guidelines **: "Focus on major issues impacting performance, readability, maintainability and security. Avoid nitpicks and avoid verbosity."
Also applies to: 84-104, 349-392
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@workflows/release-notes-generator/README.md` around lines 11 - 39, The
README's "Two-Part Architecture" section duplicates workflow/mode/token rules
that also live in CLAUDE.md and .ambient/ambient.json; pick a single canonical
source (e.g., .ambient/ambient.json or CLAUDE.md) to hold the authoritative
rules, remove the duplicated block in README (the "Two-Part Architecture"
section) and replace it with a short pointer to the canonical document, and
update CLAUDE.md and .ambient/ambient.json to reference that canonical file as
needed so all guidance (architecture/mode/token rules) is maintained in one
place and other docs only link to or summarize it.
Comment on lines
+99
to
+104
| 4. **Authentication** (handled automatically): | ||
| - Workflow automatically uses tokens from ACP integrations (`GITHUB_TOKEN`, `GITLAB_TOKEN` environment variables) | ||
| - If no token found, asks: "Provide token, proceed without, or use local clone?" | ||
| - For public repos without tokens: Works but has API rate limits | ||
| - For private repos: Token required or fallback to local clone | ||
|
|
Contributor
There was a problem hiding this comment.
Replace “provide token” wording with non-chat secret handling guidance.
These sections can be read as “paste token here,” which is unsafe. Please explicitly direct users to ACP integration/env vars/secret manager flow and add a clear warning to never post raw tokens in chat or issue comments.
As per coding guidelines **: "Focus on major issues impacting performance, readability, maintainability and security. Avoid nitpicks and avoid verbosity."
Also applies to: 294-298, 447-450
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@workflows/release-notes-generator/README.md` around lines 99 - 104, Replace
the unsafe “Provide token” phrasing in the Authentication section (the line that
reads "Provide token, proceed without, or use local clone?") with explicit
instructions to use ACP integration tokens (GITHUB_TOKEN/GITLAB_TOKEN),
environment variables, or a secret manager/CI secret injection flow; add a
short, prominent warning: never paste raw tokens into chats, issue comments, or
public fields. Update the same wording at the other occurrences mentioned (the
repeated prompt-like strings) so all instances consistently reference ACP
integrations/env vars/secret management and include the no-raw-token warning.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a new workflow for generating structured release notes from git commits and tags with automatic categorization.
Features
Technical Details
utility-mcp-serverPython package for git analysisartifacts/release-notes/Workflow Structure
Testing
Tested extensively in ACP with Custom Workflow:
artifacts/release-notes/Use Cases
Perfect for:
Why This Workflow?
Release notes are critical for communicating changes to users, but manually creating them is time-consuming and error-prone. This workflow automates the process while maintaining high quality and consistency.
The workflow intelligently parses commit messages, extracts meaningful information, and presents it in a professional format that's ready to publish.
Ready for Review
This workflow has been thoroughly tested and is production-ready. It follows all ACP workflow conventions and includes comprehensive documentation for users.
Looking forward to feedback and making this available to the ACP community! 🚀