← Library
release-notes

Release notes

Most teams have twenty crusty shell and Python scripts nobody wants to port, and every agent framework asks them to port them. heddle does not: a tool is a program that reads JSON on stdin and prints JSON on stdout, so the distance between a script you already run by hand and a tool an agent can call is about fifteen lines. This entry is that claim, made concrete. scripts/ holds three plainly pre-agent programs — flags in, text out, non-zero on failure, written for a person — and they are not touched, not imported and not rewritten; they still work by hand. tools/ holds one shim per script: read the JSON, spend it as flags, run the thing, print one JSON object. When a script fails, its own exit code and its own stderr come back verbatim, because a friendlier error invented by the shim is the one thing the person debugging cannot use. The agent on top reads what the scripts print and writes notes grouped the way a reader would group them, with a rule it is held to: every line must trace to a commit it was shown, and a subject it cannot interpret goes in an "unclear" list by hash rather than being guessed at. Swap the three scripts for your own twenty and the shape does not change.

releasegitscriptswrappingci

Run it

terminal
npx @heddle-run/cli run release-notes

One command, pasted into a terminal. The bare name is this entry's published address, and fetching it fetches the agent — flow, tools and sample data travel inside the bundle, along with a default input. heddle asks for anything still missing, like your model key, before it starts. Nothing is installed.

The flow

spec.yaml
# release-notes — the agent your team's existing scripts already were.
#
# start ──> write (Agent, three tools) ──> end
#
# The three tools in tools/ do no work. Each is a shim: read JSON from stdin,
# spend it as command-line flags, run the script your release engineer has been
# running by hand since 2023, print one JSON object. The scripts in scripts/ are
# untouched, unimported and still work by hand.
component_type: Flow
agentspec_version: 26.2.0
id: flow_release_notes
name: release-notes
description: >
Writes the release notes for a range of commits by running the team's own
scripts — git log, ticket extraction, contributors — and reading their output.
metadata: {}
inputs: []
outputs: []
start_node:
$component_ref: n_start
nodes:
- $component_ref: n_start
- $component_ref: n_write
- $component_ref: n_end
control_flow_connections:
- component_type: ControlFlowEdge
id: e_start_write
name: start_to_write
metadata: {}
from_node: { $component_ref: n_start }
from_branch: null
to_node: { $component_ref: n_write }
- component_type: ControlFlowEdge
id: e_write_end
name: write_to_end
metadata: {}
from_node: { $component_ref: n_write }
from_branch: null
to_node: { $component_ref: n_end }
data_flow_connections:
- component_type: DataFlowEdge
id: e_since
name: since_to_write
metadata: {}
source_node: { $component_ref: n_start }
source_output: since
destination_node: { $component_ref: n_write }
destination_input: since
- component_type: DataFlowEdge
id: e_until
name: until_to_write
metadata: {}
source_node: { $component_ref: n_start }
source_output: until
destination_node: { $component_ref: n_write }
destination_input: until
- component_type: DataFlowEdge
id: e_repo
name: repo_to_write
metadata: {}
source_node: { $component_ref: n_start }
source_output: repo
destination_node: { $component_ref: n_write }
destination_input: repo
- component_type: DataFlowEdge
id: e_audience
name: audience_to_write
metadata: {}
source_node: { $component_ref: n_start }
source_output: audience
destination_node: { $component_ref: n_write }
destination_input: audience
- component_type: DataFlowEdge
id: e_result
name: result_to_end
metadata: {}
source_node: { $component_ref: n_write }
source_output: result
destination_node: { $component_ref: n_end }
destination_input: result
$referenced_components:
n_start:
component_type: StartNode
id: n_start
name: start
metadata: {}
inputs: []
outputs:
- { title: since, type: string }
- { title: until, type: string }
- { title: repo, type: string }
- { title: audience, type: string }
branches: [next]
n_write:
component_type: AgentNode
id: n_write
name: write
metadata: {}
inputs:
- { title: since, type: string }
- { title: until, type: string }
- { title: repo, type: string }
- { title: audience, type: string }
outputs:
- { title: result, type: string }
branches: [next]
agent:
component_type: Agent
id: a_release
name: release-notes-agent
description: Writes release notes from the output of the team's own scripts
metadata: {}
inputs:
- { title: since, type: string }
- { title: until, type: string }
- { title: repo, type: string }
- { title: audience, type: string }
outputs:
- { title: result, type: string }
system_prompt: |
You write the release notes for a range of commits. Your tools are this
team's own scripts — the same ones a person runs by hand — so what you
see is what they see.
1. changes_since for the range. That is the raw material and the only
record of what actually shipped.
2. issue_ids for the tickets referenced, and contributors for who did
the work. A commit subject with no ticket is still a change; do not
drop it because it is untracked.
3. Group the commits by what a reader would call them, not by the order
they landed. A reader wants "faster imports" and "fixed the timezone
bug", not seventeen bullets in commit order.
Write for: {{audience}}. If that is customers, say what changed for
them and leave out refactors entirely. If it is the team, keep the
refactors and name the risky ones.
Rules that matter more than style:
- Every line you write must trace to a commit you were shown. A release
note nobody can check against the log is worse than a short one.
- A commit subject you cannot interpret goes in an "unclear" list at the
end, named by its short hash. Do not guess what it did.
- No preamble and no sign-off. Markdown, one `##` heading per group.
Range: {{since}}..{{until}} in {{repo}}
llm_config:
component_type: OpenAiConfig
id: llm_openai
name: gpt
metadata: {}
model_id: gpt-4o-mini
api_key: $OPENAI_API_KEY
tools:
- component_type: ServerTool
id: t_changes
name: changes_since
description: >
Commits in a range, one per line as `hash<TAB>author<TAB>subject`.
Wraps the team's changes_since.sh; a bad ref comes back as git's own
error, unaltered.
metadata: {}
inputs:
- { title: since, type: string }
- { title: until, type: string, default: HEAD }
- { title: repo, type: string, default: "." }
outputs:
- { title: commits, type: string }
- { title: count, type: integer }
- component_type: ServerTool
id: t_tickets
name: issue_ids
description: >
Ticket references in the range, with how many commits mention each.
Wraps changes_since.sh piped into issue_ids.py. A range with no
tickets is not an error.
metadata: {}
inputs:
- { title: since, type: string }
- { title: until, type: string, default: HEAD }
- { title: repo, type: string, default: "." }
- { title: prefix, type: string, default: ENG }
outputs:
- { title: tickets, type: string }
- { title: count, type: integer }
- component_type: ServerTool
id: t_people
name: contributors
description: >
Who committed in the range, most commits first. Wraps the team's
contributors.sh.
metadata: {}
inputs:
- { title: since, type: string }
- { title: until, type: string, default: HEAD }
- { title: repo, type: string, default: "." }
outputs:
- { title: people, type: string }
- { title: count, type: integer }
n_end:
component_type: EndNode
id: n_end
name: end
metadata: {}
inputs:
- { title: result, type: string }
outputs: []
branches: []
branch_name: null

Facts

Model
gpt-4o-mini
Tools
changes_since, contributors, issue_ids
Mounts
scripts:scripts:ro
Requires
OPENAI_API_KEYpython3bashgit

The entry

  • README.md
  • bundle.json
  • probe-args.json
  • scripts/changes_since.sh
  • scripts/contributors.sh
  • scripts/issue_ids.py
  • spec.yaml
  • tools/changes_since.sh
  • tools/contributors.sh
  • tools/issue_ids.sh

The spec, the tools and the mounted files travel in the archive; the README and bundle.json stay here. Neither carries the API key — a spec names it as an environment variable and it resolves where the bundle runs.

Source

library/release-notes on GitHub →

Its README covers pointing this at your own data, and what it will not do.