ags-changelog

name	ags-changelog
description	Auto-generates a changelog from git commits, sprint data, and design documents. Produces both internal and player-facing versions.
argument-hint	[version|sprint-number]
user-invocable	true
allowed-tools	Read, Glob, Grep, Bash, Write, AskUserQuestion
context	!git log --oneline -30 2>/dev/null !git tag --list --sort=-v:refname 2>/dev/null | head -5
model	haiku

Language: Talk to user in language from .ags/project/user-interaction.md. Fall back to English if file missing. Files on disk always English per .ags/rules/user-interaction.md.

Phase 0: Prerequisites

Artifact	Created by	If missing
Git repository with ≥1 commit	git init + dev work	STOP. "No git history. Changelog needs commits."
.ags/project/epics/index.md	/ags-create-epics	WARN: changelog grouped by commits only, not epics.

If STOP triggers, exit verdict BLOCKED.

---

Phase 1: Parse Arguments

Read argument for target version or sprint number. Version → git tag. Sprint number → date range.

Verify repo initialized: run git rev-parse --is-inside-work-tree. Not a git repo → inform user and abort.

---

Phase 2: Gather Change Data

Read the git log since the last tag or release:

git log --oneline [last-tag]..HEAD

If no tags exist, read the full log or a reasonable recent range (last 100 commits).

Read sprint reports from .ags/project/epics/ for the relevant period to understand planned work and context behind changes.

Read completed design documents from design/gdd/ for any new features implemented during this period.

---

Phase 3: Categorize Changes

Categorize every change into one of these categories:

• New Features: Entirely new gameplay systems, modes, or content
• Improvements: Enhancements to existing features, UX improvements, performance gains
• Bug Fixes: Corrections to broken behavior
• Balance Changes: Tuning of gameplay values, difficulty, economy
• Known Issues: Issues the team is aware of but have not yet resolved
• Miscellaneous: Changes that do not fit the above categories, or commits whose messages are too vague to classify confidently

For each commit, check whether the message contains a task ID or story reference (e.g. [STORY-123], TR-, #NNN, or similar). Count commits that lack any task reference and include this count in the Phase 4 Metrics section as: Commits without task reference: [N].

---

Phase 4: Generate Internal Changelog

# Internal Changelog: [Version]
Date: [Date]
Sprint(s): [Sprint numbers covered]
Commits: [Count] ([first-hash]..[last-hash])

## New Features
- [Feature Name] -- [Technical description, affected systems]
  - Commits: [hash1], [hash2]
  - Owner: [who implemented it]
  - Design doc: [link if applicable]

## Improvements
- [Improvement] -- [What changed technically and why]
  - Commits: [hashes]
  - Owner: [who]

## Bug Fixes
- [BUG-ID] [Description of bug and root cause]
  - Fix: [What was changed]
  - Commits: [hashes]
  - Owner: [who]

## Balance Changes
- [What was tuned] -- [Old value -> New value] -- [Design intent]
  - Owner: [who]

## Technical Debt / Refactoring
- [What was cleaned up and why]
  - Commits: [hashes]

## Miscellaneous
- [Change that didn't fit other categories, or vague commit message]
  - Commits: [hashes]

## Known Issues
- [Issue description] -- [Severity] -- [ETA for fix if known]

## Metrics
- Total commits: [N]
- Files changed: [N]
- Lines added: [N]
- Lines removed: [N]
- Commits without task reference: [N]

---

Phase 5: Generate Player-Facing Changelog

# What is New in [Version]

## New Features
- **[Feature Name]**: [Player-friendly description of what they can now do
  and why it is exciting. Focus on the experience, not the implementation.]

## Improvements
- **[What improved]**: [How this makes the game better for the player.
  Be specific but avoid jargon.]

## Bug Fixes
- Fixed an issue where [describe what the player experienced, not what was
  wrong in the code]
- Fixed [player-visible symptom]

## Balance Changes
- [What changed in player-understandable terms and the design intent.
  Example: "Healing potions now restore 50 HP (up from 30) -- we felt
  players needed more recovery options in late-game encounters."]

## Known Issues
- We are aware of [issue description in player terms] and are working on a
  fix. [Workaround if one exists.]

---
Thank you for playing! Your feedback helps us make the game better.
Report issues at [link].

---

Phase 6: Output

Output both changelogs to the user. The internal changelog is the primary working document. The player-facing changelog is ready for community posting after review.

---

Phase 7: Offer File Write

After presenting the changelogs, ask the user:

"May I write this changelog to docs/CHANGELOG.md? [A] Yes, append this entry (recommended if the file already exists) [B] Yes, overwrite the file entirely [C] No — I'll copy it manually"

• Check whether docs/CHANGELOG.md exists before asking. If it does, default the recommendation to [A] append.
• If the user selects [A]: append the new internal changelog entry to the top of the existing file (newest entries first).
• If the user selects [B]: overwrite the file with the new changelog.
• If the user selects [C]: stop here without writing.

After a successful write: Verdict: CHANGELOG WRITTEN — changelog saved to docs/CHANGELOG.md. If the user declines: Verdict: COMPLETE — changelog generated.

---

Phase 7: Next Steps

• Use /ags-patch-notes [version] to generate a styled, saved version for public release.
• Use /ags-release-checklist before publishing the changelog externally.

Guidelines

• Never expose code refs, file paths, or developer names in player-facing changelog
• Group related changes; don't list individual commits
• Unclear commit message → check files and sprint data for context
• Balance changes: always include design reasoning, not just numbers
• Known issues: be honest — players appreciate transparency
• Messy git history (merges, reverts, fixups): clean the narrative, don't list every commit literally

---

Combined Review Loop (parallel external Codex)

Per .ags/rules/review-workflow.md. Authoring + internal review runs in parallel with external Codex inside one loop. Each iteration:

1. Resolve severity floor: iter 1-2 → keep all severities; iter 3-4 → critical/high; iter 5+ → critical only.
2. Persist current draft to .ags/project/reviews/.tmp/changelog-[version]-iter[N]-draft.md.
3. Spawn in one message, in parallel:
   • All internal reviewer Tasks (producer + narrative-director for tone).
   • /ags-external-review custom [draft-path] --embedded-parallel --iteration [N] --min-severity [floor] — Codex unavailable returns skipped: codex-unavailable; aggregator logs skip in decisions-log and continues with internal pool only.
4. Aggregator (producer) merges findings from internal + Codex, drops nitpicks + below-floor.
5. Loop exit: filtered set empty → proceed to write approval. Non-empty → surface aggregated kept findings, user revises draft, N++, repeat.

No iteration cap. No user-confirm gate before external — it runs every iteration automatically.