Proactive and schedule-driven; triggered by whatever new tag or release exists since the last checkpoint, whether that's one release or several.

Step 0 — Orient and resume

bash

# Read the durable ledger first — the last release tag covered, and any open
# changelog PR from a prior run.
cat .singulacomp/memory/changelog-sync-log.md 2>/dev/null || echo "(no ledger yet — first run)"

# Check for an open changelog PR before opening a new one.
gh pr list --repo {{target_repo}} --state open \
  --search 'in:title "release notes" OR label:changelog' \
  --json number,title,headRefName,statusCheckRollup,url

If a prior changelog PR is still open and unreviewed, extend that branch with the newer release instead of opening a second one.

Step 1 — Find the release range

bash

cd /workspace/repo 2>/dev/null || { git clone --filter=blob:none https://github.com/{{target_repo}}.git /workspace/repo && cd /workspace/repo; }
git fetch origin --tags

LAST_TAG=$(grep -m1 '^checkpoint:' .singulacomp/memory/changelog-sync-log.md | awk '{print \$2}')
gh release list --repo {{target_repo}} --limit 10 --json tagName,publishedAt \
  --jq 'sort_by(.publishedAt)'

If $LAST_TAG is empty, this is the first run — seed the checkpoint from the release immediately prior to the newest one (so this run covers exactly the latest release, not the entire history). List every release published after $LAST_TAG, oldest first — cover each one this run, one at a time.

Step 2 — Read the merged PRs for this release

For each release tag $NEW_TAG with predecessor $PREV_TAG:

bash

git log "$PREV_TAG".."$NEW_TAG" --merges --oneline

gh pr list --repo {{target_repo}} --state merged --base main \
  --search "merged:$PREV_TAG_DATE..$NEW_TAG_DATE" \
  --json number,title,body,labels,author,mergedAt,url

For each PR, pull the full description and diff stat, not just the title — the title alone often doesn't say what a user-facing change actually does:

bash

gh pr view <number> --repo {{target_repo}} --json title,body,labels,files

Step 3 — Drop the noise

Exclude PRs carrying any of: internal, chore, ci, dependencies, no-changelog, or whose title starts with chore(deps), ci:, or test:. These are real commits but not something a reader of the changelog cares about. Keep anything user-facing: features, fixes, performance, breaking changes, deprecations.

Step 4 — Group by area and write

Cluster the remaining PRs by the area they touch (read labels first; fall back to the changed paths). Typical groups: Features, Fixes, Performance, Breaking changes. Within each group, write one plain-language line per change — what a user can now do or what stopped being broken, not the internal mechanism. Rephrase every PR title into user-facing language; never paste a raw PR title verbatim.

Read {{changelog_path}}'s existing entries first and match its established format (heading style, date format, grouping labels, tone) rather than inventing a new one.

Step 5 — Isolated branch and PR

bash

cd /workspace/repo
BRANCH="release-notes/$NEW_TAG"
git checkout -b "$BRANCH" origin/main
# edit {{changelog_path}} — insert the new release's entry above the previous one
git add {{changelog_path}}
git commit -m "docs(changelog): release notes for $NEW_TAG"
git push origin "$BRANCH"
gh pr create --repo {{target_repo}} --base main --head "$BRANCH" \
  --title "docs(changelog): release notes for $NEW_TAG" \
  --label changelog \
  --body "Generated by the release-notes agent from PRs merged between
$PREV_TAG and $NEW_TAG. Grouped by area; internal-only PRs and dependency
bumps are dropped. A human reviews the wording and merges."

One PR per release covered. If this run covers more than one release, open them as separate PRs in shipped order rather than combining entries.

Step 6 — Update the ledger

Append a dated entry to .singulacomp/memory/changelog-sync-log.md (see <ledger-format>) with the new checkpoint tag, then advance it — even if a PR was left open for review rather than merged, the checkpoint still moves to the newest release tag this run covered.

Your people and your agents, in one place you own.

Your people and your agents, in one place you own.

Step 0 — Orient and resume

Step 1 — Find the release range

Step 2 — Read the merged PRs for this release

Step 3 — Drop the noise

Step 4 — Group by area and write

Step 5 — Isolated branch and PR

Step 6 — Update the ledger