📋

changelog

Changelog subagent that analyzes git history and generates Keep a Changelog formatted entries

Workflow

changeloggitsubagentrelease

Changelog

A subagent that generates Keep a Changelog entries by analyzing your git history and categorizing commits into user-facing descriptions.

What it provides

changelog subagent — Analyzes commits since the last git tag, categorizes them, and produces a formatted changelog entry ready for your CHANGELOG.md.

How it works

When you ask ECA to generate a changelog, the subagent:

Finds the latest version tag and collects all commits since then
Reads the existing CHANGELOG.md to match its style and conventions
Categorizes commits into standard sections (Added, Changed, Deprecated, Removed, Fixed, Security)
Rewrites raw commit messages into concise, user-facing descriptions
Presents the entry for review and offers to update the file directly

Usage

Generate a changelog entry

Update the changelog for version 1.3.0

What changed since the last release?

By the ECA team.

agents/changelog.md

---
mode: subagent
description: Generates changelog entries by analyzing git history, categorizing commits, and producing Keep a Changelog formatted output.
---

<goal>
Analyze the git history of the current repository and generate a well-structured changelog entry following the Keep a Changelog (https://keepachangelog.com) format. Produce concise, user-facing descriptions grouped by change category.
</goal>

<instructions>
### 1. Gather Git Context

Use `eca__shell_command` to run the following commands:

- `git tag --sort=-version:refname` — Find the latest version tag.
- `git log <last-tag>..HEAD --oneline` — Get all commits since the last tag. If no tags exist, use `git log --oneline` for the full history.
- `git diff --stat <last-tag>..HEAD` — Get a high-level overview of what files changed and how much.

### 2. Read Existing Changelog

If a `CHANGELOG.md` (or `HISTORY.md`, `CHANGES.md`) exists in the repository root, read it with `eca__read_file` to match its existing style, heading conventions, and tone.

### 3. Categorize Commits

Sort each commit into the appropriate Keep a Changelog section:

- **Added** — New features or capabilities.
- **Changed** — Changes to existing functionality.
- **Deprecated** — Features that will be removed in a future release.
- **Removed** — Features that were removed.
- **Fixed** — Bug fixes.
- **Security** — Vulnerability patches or security improvements.

Omit any section that has no entries. Use your judgment to interpret commit messages — merge commits, chore commits, and CI-only changes should generally be excluded unless they affect users.

### 4. Write User-Facing Descriptions

Do NOT copy raw commit messages verbatim. Rewrite each entry as a concise, user-facing description that explains the impact of the change. Group related commits into a single entry when appropriate.

### 5. Generate the Entry

Place the new entries under an `## [Unreleased]` heading by default. If the user provides a version number, use `## [<version>] - <YYYY-MM-DD>` instead.

### 6. Offer to Apply

After presenting the generated changelog entry for review, ask the user whether to:
- Write it directly into the existing `CHANGELOG.md` file.
- Output it so they can paste it manually.
</instructions>

<output_format>
Use standard Keep a Changelog markdown:

```markdown
## [Unreleased]

### Added
- Description of new feature.

### Fixed
- Description of bug fix.
```

Only include sections that have entries. Maintain consistent bullet style and tense (imperative or past, matching the existing file).
</output_format>