← All craftbooks

Release Notes

Ship and releaseevalv1.0.5released 2026-09-05workflow: build-loop

Steps

Entry step: gather. Each step names the specialist role it wants; the full working prompt is expandable.

1. Gather the change inventorydeveloperentry

   collect and de-noise every shipped change since the last tag

   Show working prompt

   1. Determine the version range: the last released tag (or last release date) up to HEAD/the release candidate. 2. Collect the raw inventory — merged PRs, commit subjects, and linked issue IDs (use git log, gh pr list --state merged, or the changelog source available to you). 3. Filter OUT noise that should never reach users: merge commits, dependency-bump-only commits, CI/build-config tweaks, lint/format-only commits, and anything not yet actually released. 4. Classify each remaining change into exactly one bucket: Features, Improvements, Bug Fixes, Breaking Changes. 5. Flag every Breaking Change and anything requiring a user action (config change, migration, new env var) — these get top billing later. 6. Good looks like: a deduplicated, categorized list where each item has a PR/issue reference and a one-line plain description, and every category is either populated or explicitly marked 'none'. Write an acceptance-criteria checklist (e.g. 'every shipped user-facing change appears exactly once', 'breaking changes are flagged with the required user action', 'no merge/dependency/CI-only noise', 'each item cites a PR or issue') plus the version range and the classified inventory to the notes file via write_task_note AND to {{workPath}}/gather.md.
   
   The deliverable `{{workPath}}/gather.md` lands in the project's artifacts drawer — write it with `write_artifact` and read it back with `read_artifact`; the shipped workspace stays untouched.

2. Write the notescopywriter

   turn the inventory into benefit-led, user-facing notes

   Show working prompt

   1. Open {{workPath}}/gather.md and write the release notes for HUMANS, not for the commit log — lead each item with the user-visible benefit, not the implementation. 2. Order the document: a one-paragraph highlights summary, then Breaking Changes / Upgrade Notes (with the exact action the user must take), then Features, Improvements, Bug Fixes. 3. Keep each line tight and parallel in voice; use the imperative or present tense consistently ('Adds…', 'Fixes…'). 4. Preserve the PR/issue references as links or trailing (#123) so readers can dig in. 5. Open with the version number and release date as an H1/H2. 6. Good looks like: a reader who has never seen the codebase understands what changed and what they must do, breaking changes are impossible to miss, and every inventory item from gather.md is represented. Write the notes to release-notes.md.
   
   Before working, open the artifact input `{{workPath}}/gather.md` with `read_artifact`; do not look for it in the workspace.

3. Review for completeness and tonereviewer

   verify coverage, accuracy, and that nothing internal leaked

   Show working prompt

   1. Cross-check release-notes.md against {{workPath}}/gather.md: every classified item must appear, and nothing must appear that was filtered as noise or is unreleased. 2. Verify Breaking Changes are at the top with a concrete user action, not buried. 3. Check the voice is consistent and benefit-led, version + date are present, and references resolve. 4. Confirm no internal-only details (private ticket chatter, internal service names, secrets, profanity) leaked into a public document. 5. Write a PASS/FAIL against each acceptance criterion from gather.md, listing any specific gap. 6. If anything fails, the fix happens back in the write phase. Write your findings to {{workPath}}/review.md.
   
   Before working, open the artifact input `{{workPath}}/gather.md` with `read_artifact`; do not look for it in the workspace.
   
   The deliverable `{{workPath}}/review.md` lands in the project's artifacts drawer — write it with `write_artifact` and read it back with `read_artifact`; the shipped workspace stays untouched.

4. Evaluatereviewer

   Grade the deliverable against every acceptance criterion. All pass → finish; any fail → loop back and fix the gap.

   Show working prompt

   Review `{{workPath}}/review.md` against the original scope: every claim cites a real path, the severities and priorities are defensible, and nothing important in scope was skipped. Open the underlying files for at least the top findings; do not grade from the report's own summary. If a finding cannot be verified, say so explicitly.
   
   Write your review to the artifact `{{workPath}}/review.md` with one `write_artifact` call: what you checked, what held, what did not (as a findings table with columns `| Severity | File | Line | Problem | Fix |` when anything needs fixing), ending with exactly `Verdict: PASS` or `Verdict: REVISE`. The gate enforces the verdict: a well-formed REVISE is routed back to the `review` step automatically with your findings. On PASS, `advance_task_step` to `finish`.

5. Finishdeveloper

   All acceptance criteria met. Stamp a short summary and report DONE.

   Show working prompt

   Every acceptance criterion passed. Write a one-paragraph DONE summary to task notes via `write_task_note`: what was built, the deliverable path(s), and a one-line confirmation that each criterion is met. Then report DONE.

Triggers

Phrases that suggest this craftbook to a crew.

• write release notes
• release notes for v2
• what changed this release
• draft release announcement
• notes for the new version
• cut a changelog
• update CHANGELOG.md
• roll unreleased into a version
• stamp the changelog for v1.4
• keep a changelog release
• write a changelog
• generate release notes
• whats new writeup
• changelog from commits
• version notes

Source

View this craftbook on GitHub · MIT license