x-generate-release-changelog
Changelog generator v2: hybrid format combining narrative Highlights block (derived from 'Entrega de Valor' of merged v2 epics) with Keep-a-Changelog sections (Added/Changed/Fixed/Breaking/Deprecated). Stack-aware via documentation.changelog.format config. Falls back gracefully when EPIC-0070 epics unavailable (D-R10).
- License 许可
- MIT
- 最近更新
- 2026-10-27
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- name
- x-generate-release-changelog
- model
- sonnet
- description
- Changelog generator v2: hybrid format combining narrative Highlights block (derived from 'Entrega de Valor' of merged v2 epics) with Keep-a-Changelog sections (Added/Changed/Fixed/Breaking/Deprecated). Stack-aware via documentation.changelog.format config. Falls back gracefully when EPIC-0070 epics unavailable (D-R10).
- allowed-tools
- Read, Write, Edit, Bash, Grep, Glob
- argument-hint
- [version-tag | --unreleased | --full] [--format hybrid|keep-a-changelog|conventional-only]
- user-invocable
- true
- requires-capabilities
- [ "governance.doc-as-dod" ]
02 资源文件 1
- 参考文档README.md1.6 KB
03 SKILL.md 正文
Global Output Policy
- Language: English ONLY.
- Tone: Technical, Direct, and Concise.
- Efficiency: Remove all conversational fillers and greetings to save tokens.
Skill: Changelog Generator v2
Purpose
Generates or updates CHANGELOG.md for {{PROJECT_NAME}} in hybrid format (default): a narrative ### Highlights block derived from ## Entrega de Valor sections of merged EPIC-0070 v2 epics, followed by rigorously structured Keep-a-Changelog sections populated from Conventional Commits.
Format is configurable via documentation.changelog.format in the project YAML:
hybrid(default): Highlights block + Keep-a-Changelog sectionskeep-a-changelog: Keep-a-Changelog only (no Highlights), same as v1 behaviorconventional-only: Raw Conventional Commit grouping without KaC normalization
When v2 epic content is unavailable, degrades gracefully per D-R10: empty Highlights + visible WARN + exit 0 (never blocks release).
Triggers
/x-generate-release-changelog— generate hybrid changelog for unreleased changes/x-generate-release-changelog v3.10.0— generate entry for version v3.10.0/x-generate-release-changelog --unreleased— unreleased changes since last tag/x-generate-release-changelog --full— regenerate entire changelog from all tags/x-generate-release-changelog --format keep-a-changelog— v1 format (no Highlights)/x-generate-release-changelog --format conventional-only— raw commit grouping
Parameters
| Parameter | Required | Description |
|---|---|---|
| Version tag | No | Target version (e.g., v3.10.0). Default: unreleased. |
--unreleased |
No | Only unreleased changes since last tag. |
--full |
No | Regenerate entire changelog from all tags. |
--format |
No | Output format: hybrid (default), keep-a-changelog, conventional-only. Overrides documentation.changelog.format from YAML. |
--highlights-min |
No | Minimum Highlights paragraphs. Default: 3. |
--highlights-max |
No | Maximum Highlights paragraphs before truncation. Default: 8. |
Format validation: if documentation.changelog.format or --format contains a value outside {hybrid, keep-a-changelog, conventional-only}, exit INVALID_CHANGELOG_FORMAT and list valid values on stderr.
Workflow
1. DETECT -> Determine version range from tags; load format config
2. EPICS -> Collect merged EPIC-0070 v2 epics in range (for Highlights)
3. PARSE -> Extract commits in range, parse Conventional Commits
4. HIGHLIGHTS -> Generate narrative Highlights block (hybrid mode only)
5. GROUP -> Map commit types to KaC sections
6. GENERATE -> Create or update CHANGELOG.md (incremental)
7. REPORT -> Summary of entries added
Step 1 — Detect Version Range and Load Config
# List all version tags, sorted by version
git tag --list 'v*' --sort=-v:refname
# Determine range
# If version tag given: previous_tag..version_tag
# If --unreleased: latest_tag..HEAD
# If --full: process all tags
# If no argument: latest_tag..HEAD (same as --unreleased)
Load documentation.changelog.format from project YAML:
cat iadev.yaml 2>/dev/null | grep "changelog" | grep "format"
If not found: default to hybrid. Apply --format flag override if present.
Validate format value: if not in {hybrid, keep-a-changelog, conventional-only} → exit 1 INVALID_CHANGELOG_FORMAT.
Step 2 — Collect EPIC-0070 v2 Epics in Range (hybrid mode only)
Identify epic markdown files added/modified in the git range:
git log {previous_tag}..{target} --diff-filter=AM --name-only -- 'ai/epics/epic-*/epic-*.md' 2>/dev/null
For each epic file found, read the ## Entrega de Valor section (or ## 2. Persona & Cenário de Uso + ## 3. Hipótese de Valor as fallback):
# Extract Entrega de Valor content from epic markdown
awk '/^## (2\. )?Entrega de Valor/,/^## [0-9]/' {epic_file} | head -50
Apply v2 template detection: epic uses v2 if it contains ## 1. Visão & Problema (not ## Packages — Hexagonal).
D-R10 — Fallback when no v2 epics found:
- No epic files in range, OR
- All epic files found are v1 (contain
## Packages — Hexagonal), OR ai/epics/directory absent:
WARN [x-generate-release-changelog] No EPIC-0070 v2 epics found in range {range} — Highlights will be empty.
Install/merge EPIC-0070 epics to enable narrative Highlights. (D-R10 degraded mode)
Set Highlights to empty; proceed without blocking.
Step 3 — Parse Conventional Commits
# Extract commits in range
git log {previous_tag}..{target} --format="%H|%s|%b|%an|%ai" --no-merges
Parse each commit as Conventional Commit:
<type>(<scope>): <description>
Extract: type, scope, description, breaking flag (! after type or BREAKING CHANGE: in body), body.
Skip commits that don't follow the convention (log WARN, do not abort).
Step 4 — Generate Highlights Block (hybrid mode only)
When format = hybrid and ≥ 1 v2 epic was found:
- For each v2 epic with
## Entrega de Valor, extract the section content (sanitized). - Consolidate across epics into a narrative block targeting 3–8 paragraphs:
- Each epic contributes up to 2 paragraphs (value statement + metric).
- Remaining paragraph budget filled with top
feat:entries summarized by scope.
- Minimum (3 paragraphs): if fewer than 3 paragraphs can be derived from epic content, expand with bullet-point summaries of
feat:commits until minimum is reached. - Maximum (8 paragraphs): if more than 8 paragraphs would be generated, truncate with trailing
...and emit:WARN [x-generate-release-changelog] Highlights truncated at 8 paragraphs — review manually.
Content sanitization: strip markdown link syntax ([text](url)) that references internal CI paths. Escape <, >, & characters. Never include paths matching /home/, /tmp/, /var/, /Users/ (CI runner internals). Remove environment variables ($VAR, ${VAR}).
Highlights format:
### Highlights
{paragraph_1 — value statement for epic 1}
{paragraph_2 — metric/impact for epic 1}
{paragraph_3 — value statement for epic 2 or feat: summary}
When format = keep-a-changelog or conventional-only: skip this step (no Highlights block).
Step 5 — Map to Changelog Sections
| Commit Type | Hybrid / KaC Section | Conventional-only |
|---|---|---|
feat |
Added | feat |
fix |
Fixed | fix |
refactor |
Changed | refactor |
perf |
Changed | perf |
docs |
Documentation (optional) | docs |
chore |
(skip) | chore |
build, ci, test, style |
(skip) | (skip) |
BREAKING CHANGE / feat! / fix! |
Breaking Changes (top) | breaking |
deprecate |
Deprecated | deprecate |
revert |
Removed | revert |
Section order (hybrid + keep-a-changelog): Breaking Changes > Highlights (hybrid only) > Added > Changed > Deprecated > Removed > Fixed > Security.
Step 6 — Generate CHANGELOG.md
Template: uses _TEMPLATE-CHANGELOG-ENTRY.md to render each version entry.
If CHANGELOG.md does not exist, create with header:
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
If CHANGELOG.md exists, insert new version section after header / after [Unreleased]:
## [{version}] — YYYY-MM-DD
### Highlights
{highlights_block}
### Breaking Changes
- {breaking entries}
### Added
- {feat entries}
### Changed
- {refactor/perf entries}
### Fixed
- {fix entries}
Only include sections that have entries (omit empty sections). Update [Unreleased] section (clear entries that moved to this version).
Entry format:
- {description} ([#{PR_number}]({PR_url})) — when PR linkable
- {description} ({commit_hash_short}) — when no PR
Version comparison links (bottom of CHANGELOG):
[unreleased]: https://github.com/{owner}/{repo}/compare/{latest_tag}...HEAD
[3.10.0]: https://github.com/{owner}/{repo}/compare/v3.9.0...v3.10.0
Step 7 — Report
CHANGELOG.md updated:
Version: {version or Unreleased}
Format: {hybrid | keep-a-changelog | conventional-only}
Epics v2: {count found} (Highlights: {paragraphs} paragraphs)
Entries: {count}
Sections: Breaking ({n}), Added ({n}), Changed ({n}), Fixed ({n})
Range: {from_tag}..{to_ref}
Warnings: {any D-R10 or truncation warnings}
D-R10 — Degraded Mode (EPIC-0070 Unavailable)
When v2 epic content is absent (no ai/epics/ directory, no v2 epics in range, or EPIC-0070 not installed):
- Emit visible WARN:
"EPIC-0070 not available or no v2 epics in range — Highlights manual or degraded". - Generate changelog WITHOUT Highlights block (or with empty Highlights placeholder).
- Proceed with Keep-a-Changelog sections from Conventional Commits (always available).
- Exit 0 — never block release.
D-R10 degraded output:
## [v3.10.0] — YYYY-MM-DD
<!-- WARN: Highlights not generated (EPIC-0070 v2 epics not found in range). Update manually. -->
### Added
- {feat entries}
Error Handling
| Scenario | Action |
|---|---|
| No tags found | Use all commits from initial commit |
| No Conventional Commits in range | Report "No conventional commits found in range" |
| Non-conventional commit | Skip with WARN |
| CHANGELOG.md has unexpected format | Append new section at the end with WARN |
| Version tag already in CHANGELOG | Exit 0 "Version already documented" |
format value invalid |
Exit 1 INVALID_CHANGELOG_FORMAT; list valid values on stderr |
## Entrega de Valor absent in v2 epic |
Skip epic for Highlights; use feat: summaries as filler |
| Content sanitization fails | Strip offending content; log WARN; proceed |
Performance Contract
- Total generation time: < 60s for ranges with 100+ commits and 10 merged epics.
- Epic file reading: ≤ 50 lines per epic file (only
## Entrega de Valorsection).
Integration Notes
| Skill | Relationship | Context |
|---|---|---|
x-release |
called-by | Release Step 5 changelog generation |
x-generate-docs |
called-by | When --type changelog delegated |
x-internal-write-report |
uses | Template rendering for CHANGELOG entry |
04 同仓库更多 Skills
x-parallel-eval
Detects and classifies file-collision risks between work units (tasks, stories, or epic phases) before parallel execution. Reads ## File Footprint blocks produced by x-task-plan / x-story-plan, applies the parallelism-heuristics knowledge pack (hard / regen / soft categories + hotspot overrides), and emits a collision matrix + serialization recommendation in Markdown (default) or JSON.
parallelism-heuristics
Canonical catalog of file-collision heuristics for parallel task, story, and epic execution. Defines the File Footprint block format, the three Conflict Categories (hard / regen / soft), a hotspot list of high-contention paths, and the degrade-with-warning policy. Consumed by x-task-plan, x-story-plan, x-epic-map, x-parallel-eval, and x-dev-*-implement.
x-watch-pr-ci
Polls a PR's CI checks and Copilot review status, blocking until checks complete or timeout. Returns one of 8 stable exit codes (SUCCESS=0, CI_PENDING_PROCEED=10, CI_FAILED=20, TIMEOUT=30, PR_ALREADY_MERGED=40, NO_CI_CONFIGURED=50, PR_CLOSED=60, PR_NOT_FOUND=70). Writes a versioned state-file for session resume.
x-validate-docs
Documentation freshness gate: validates 6 dimensions (readme, api-specs, grpc-proto, adr, skill-docs, system-architecture) against code changes in a PR. Stack-aware — only validates targets declared/auto-detected from ProjectConfig.documentation.targets. Returns exit non-zero on staleness; produces structured report.
x-update-system-architecture
Incrementally updates docs/architecture/system.md after an epic completes. Appends new entries to the Decision Log (§11) using x-internal-write-report --append (dedup by ## ID: marker) and surgically inserts component/integration changes into sections 1-10 via Edit. Idempotent: re-running with the same epic produces a byte-identical system.md.
x-update-architecture
Incrementally updates the service architecture document with changes from architecture plans. Adds new components, integrations, flows, and ADR references without rewriting existing content. Use after implementation to keep architecture documentation current.