Skip to content

Commit 40369c8

Browse files
ericksoaericksoa
authored
feat(skills): add release notes maintainer workflow (#4490)
## Summary - Add `nemoclaw-maintainer-release-notes`, a maintainer skill for drafting and posting NemoClaw release notes from live tag/compare data. - Capture the release-note workflow used for v0.0.54: three-paragraph narrative, categorized shipped-change bullets, local HTML preview before posting, external-only GitHub username thanks, replay attribution, and no affiliation text. - Update the skills guide so the new maintainer skill is discoverable and fix the guide counts to match the current skill directories. ## Validation - `npx markdownlint-cli2 .agents/skills/nemoclaw-maintainer-release-notes/SKILL.md .agents/skills/nemoclaw-skills-guide/SKILL.md` - `git diff --check` Signed-off-by: Aaron Erickson <aerickson@nvidia.com> <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **New Features** * Added a user-invocable maintainer skill to draft and publish NemoClaw release notes with strict house style, categorized shipped changes, contributor credit rules, preview/draft-by-default behavior, and safeguards against premature posting. * **Documentation** * Updated maintainer skills guide and skill catalog to reflect an expanded maintainer skill set and revised role skill counts. <!-- review_stack_entry_start --> [![Review Change Stack](https://storage.googleapis.com/coderabbit_public_assets/review-stack-in-coderabbit-ui.svg)](https://app.coderabbit.ai/change-stack/NVIDIA/NemoClaw/pull/4490?utm_source=github_walkthrough&utm_medium=github&utm_campaign=change_stack) <!-- review_stack_entry_end --> <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Signed-off-by: Aaron Erickson <aerickson@nvidia.com>
1 parent b0e6c0f commit 40369c8

2 files changed

Lines changed: 265 additions & 6 deletions

File tree

  • .agents/skills

‎.agents/skills/nemoclaw-maintainer-release-notes/SKILL.md‎

Lines changed: 254 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,254 @@
1+
---
2+
name: nemoclaw-maintainer-release-notes
3+
description: Draft and publish NemoClaw release notes from live GitHub tag and compare data. Produces the repo's narrative release-note style with three lead paragraphs, categorized shipped changes, why-it-matters bullets, and external-only contributor thanks. Use after cutting a release tag or when asked to write/post a release announcement. Trigger keywords - release note, release notes, announcement, discussion post, changelog, v0.0.x is out, Carl Sagan.
4+
user_invocable: true
5+
---
6+
7+
<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
8+
<!-- SPDX-License-Identifier: Apache-2.0 -->
9+
10+
# NemoClaw Maintainer Release Notes
11+
12+
Draft and publish NemoClaw release notes from live release data. The house style is:
13+
14+
- three narrative lead paragraphs,
15+
- a categorized list of shipped changes,
16+
- one "what changed and why it matters / why we did it" bullet for every included shipped change,
17+
- external-only contributor thanks,
18+
- visible `#NNNN` GitHub links.
19+
20+
Default to a local draft and HTML preview first. Do not create or update a GitHub Discussion until the user explicitly approves posting.
21+
22+
## Prerequisites
23+
24+
- You must be in the NemoClaw git repository.
25+
- `gh` must be authenticated for `NVIDIA/NemoClaw`.
26+
- The release tag should already exist. If the user is still cutting the tag, use `nemoclaw-maintainer-cut-release-tag` first.
27+
- Use live GitHub and remote tag state, not memory or a stale local branch.
28+
29+
## Step 1: Verify the Release Range
30+
31+
Identify the current release tag and previous release tag. If the user gives only the current version, derive the previous semver tag from remote tags.
32+
33+
```bash
34+
git ls-remote https://github.com/NVIDIA/NemoClaw.git \
35+
refs/heads/main \
36+
refs/tags/<previous-version> 'refs/tags/<previous-version>^{}' \
37+
refs/tags/<current-version> 'refs/tags/<current-version>^{}' \
38+
refs/tags/latest 'refs/tags/latest^{}'
39+
```
40+
41+
Confirm:
42+
43+
- `<current-version>^{}` peels to the intended release commit.
44+
- `latest` points to the same peeled commit unless the user explicitly says otherwise.
45+
- The compare range is `<previous-version>...<current-version>`.
46+
47+
## Step 2: Collect the Shipped Surface
48+
49+
Use the compare API as the first source of truth:
50+
51+
```bash
52+
gh api repos/NVIDIA/NemoClaw/compare/<previous-version>...<current-version> \
53+
--jq '{status,ahead_by,total_commits,commits:[.commits[] | {sha:.sha, headline:(.commit.message|split("\n")[0]), author:.commit.author.name}], files:[.files[] | {filename,status,changes}]}'
54+
```
55+
56+
For each PR number in commit headlines, collect live PR metadata:
57+
58+
```bash
59+
gh pr view <number> --repo NVIDIA/NemoClaw \
60+
--json number,title,author,headRepositoryOwner,url,mergeCommit,labels,body,mergedAt
61+
```
62+
63+
Also inspect any shipped commit that does not have a PR number in the headline. Include it only if it is a real shipped change worth announcing.
64+
65+
## Step 3: Decide What to Include
66+
67+
Include the shipped product, docs, release-surface, and CI confidence changes that a reader should know about.
68+
69+
For each included item, write:
70+
71+
- what changed,
72+
- why it matters or why we did it,
73+
- a visible PR link like `[#4474](https://github.com/NVIDIA/NemoClaw/pull/4474)`.
74+
75+
Be careful with sensitive internal cleanup:
76+
77+
- Do not count testing reverts or guardrail reversions as release value unless the user explicitly asks for a full raw changelog.
78+
- If a revert-like commit must be mentioned, use neutral language and do not frame it as someone else's mistake.
79+
- Avoid public wording that could embarrass a teammate.
80+
81+
## Step 4: Categorize the Changes
82+
83+
Use categories that match the release surface. Prefer 4-6 sections. Common categories:
84+
85+
- OpenClaw, Sandbox, and Network Stability
86+
- Windows, WSL, and Onboarding Recovery
87+
- Messaging and OpenClaw Runtime Activation
88+
- Hermes and Inference
89+
- Skills, Docs, and Release Surface
90+
- CI and Release Confidence
91+
92+
Every included shipped change should appear in exactly one category unless the user asks for a shorter note.
93+
94+
## Step 5: Handle Contributor Credit
95+
96+
By default, thank external contributors only. Do not thank NVIDIA/internal contributors by GitHub ID unless the user explicitly asks.
97+
98+
Determine external contributors from live GitHub state:
99+
100+
```bash
101+
for login in <github-logins>; do
102+
code=$(gh api -i orgs/NVIDIA/members/$login 2>/dev/null \
103+
| sed -n '1s/.* \([0-9][0-9][0-9]\).*/\1/p' || true)
104+
printf '%s %s\n' "$login" "${code:-unknown}"
105+
done
106+
```
107+
108+
Interpretation:
109+
110+
- `204` means the account is a visible member of `NVIDIA`.
111+
- `404` means the account is not a visible member and should be treated as external for release-note thanks.
112+
113+
Replay PRs need special care:
114+
115+
- If a maintainer replayed an external PR, inspect the replay PR body and the original PR.
116+
- Credit the original external GitHub username in the issue-level bullet for the shipped replay.
117+
- Also thank that username in the final thanks section.
118+
- Do not mention affiliations, organizations, domains, or companies unless the user explicitly asks. Use the GitHub username only.
119+
120+
Example:
121+
122+
```markdown
123+
- [#4474](https://github.com/NVIDIA/NemoClaw/pull/4474) replays and narrows the Hermes Provider host-smoke fix originally contributed by @shannonsands in [#4385](https://github.com/NVIDIA/NemoClaw/pull/4385). ...
124+
125+
## Thank you
126+
127+
Thank you to external contributor @shannonsands for the original Hermes Provider smoke-check contribution in [#4385](https://github.com/NVIDIA/NemoClaw/pull/4385), which was replayed and narrowed into [#4474](https://github.com/NVIDIA/NemoClaw/pull/4474) for this release.
128+
```
129+
130+
## Step 6: Draft the Narrative
131+
132+
Write the top section as exactly three paragraphs unless the user asks otherwise.
133+
134+
If the user requests a theme, let it shape the paragraphs. If the user asks for the voice of Carl Sagan, keep it subtle: cosmic scale, humility, clarity, and wonder, but no parody, no quotes, and no overdone imitation.
135+
136+
Suggested structure:
137+
138+
1. Stability theme and infrastructure/security boundary changes.
139+
2. User-facing workflow stability: messaging, Hermes, inference, onboarding.
140+
3. Maintenance stability: skills, docs, checks, and release confidence.
141+
142+
Keep the prose warm and polished, but concrete. Tie the narrative to actual PRs in the release range.
143+
144+
## Step 7: Write Local Drafts First
145+
146+
Create a Markdown draft and an HTML preview. By default, place these outside the checkout root so the repo stays clean, for example:
147+
148+
```bash
149+
../nemoclaw-<current-version>-release-note-draft.md
150+
../nemoclaw-<current-version>-release-note-draft.html
151+
```
152+
153+
The Markdown body is the source that will be posted to GitHub Discussions. The HTML file is just a browser preview for review.
154+
155+
After writing the files, open the HTML preview with the platform's default file opener:
156+
157+
```text
158+
macOS:
159+
open ../nemoclaw-<current-version>-release-note-draft.html
160+
161+
Linux:
162+
xdg-open ../nemoclaw-<current-version>-release-note-draft.html
163+
164+
Windows (PowerShell):
165+
Start-Process ../nemoclaw-<current-version>-release-note-draft.html
166+
```
167+
168+
Stop here unless the user approves posting.
169+
170+
## Step 8: Publish to GitHub Discussions After Approval
171+
172+
When the user says to post the release note, publish the reviewed Markdown body as a Discussion in `Announcements`.
173+
174+
Resolve repository and category IDs live:
175+
176+
```bash
177+
gh api graphql -f owner=NVIDIA -f name=NemoClaw -f query='
178+
query($owner:String!,$name:String!){
179+
repository(owner:$owner,name:$name){
180+
id
181+
discussionCategories(first:20){ nodes{ id name slug } }
182+
}
183+
}'
184+
```
185+
186+
Check for an existing discussion for the same version before creating a new one:
187+
188+
```bash
189+
gh api graphql -f owner=NVIDIA -f name=NemoClaw -f query='
190+
query($owner:String!,$name:String!){
191+
repository(owner:$owner,name:$name){
192+
discussions(first:20, orderBy:{field:CREATED_AT,direction:DESC}){
193+
nodes{ number title url createdAt category{ name } }
194+
}
195+
}
196+
}' --jq '.data.repository.discussions.nodes | map(select(.title|test("<current-version>"; "i")))'
197+
```
198+
199+
Create the discussion:
200+
201+
```bash
202+
gh api graphql \
203+
-f repositoryId='<repo-id>' \
204+
-f categoryId='<announcements-category-id>' \
205+
-f title='NemoClaw <current-version> is out' \
206+
-F body=@../nemoclaw-<current-version>-release-note-draft.md \
207+
-f query='mutation($repositoryId:ID!,$categoryId:ID!,$title:String!,$body:String!){
208+
createDiscussion(input:{repositoryId:$repositoryId,categoryId:$categoryId,title:$title,body:$body}){
209+
discussion{ number title url category{ name } body }
210+
}
211+
}'
212+
```
213+
214+
Verify the live result:
215+
216+
```bash
217+
gh api graphql -F number=<discussion-number> -f owner=NVIDIA -f name=NemoClaw -f query='
218+
query($owner:String!,$name:String!,$number:Int!){
219+
repository(owner:$owner,name:$name){
220+
discussion(number:$number){ number title url category{ name } body createdAt }
221+
}
222+
}'
223+
```
224+
225+
Confirm:
226+
227+
- category is `Announcements`,
228+
- title is `NemoClaw <current-version> is out`,
229+
- body starts with the reviewed draft,
230+
- external thanks are present if expected,
231+
- no affiliation text appears unless the user requested it.
232+
233+
## Output
234+
235+
For a draft-only run, return:
236+
237+
- Markdown draft path,
238+
- HTML preview path,
239+
- a short note about the compare range and any excluded revert/test-cleanup items.
240+
241+
For a posted run, return:
242+
243+
- Discussion URL,
244+
- discussion number,
245+
- verification summary.
246+
247+
## Hard Rules
248+
249+
- Never publish a Discussion before the user approves the local draft.
250+
- Never draft from memory alone; use live `gh api compare` and PR metadata.
251+
- Never mention contributor affiliation unless the user explicitly asks.
252+
- Never thank internal contributors by default; keep thanks external-only.
253+
- Never include testing reverts as release-value bullets unless explicitly asked for a raw changelog.
254+
- Never create duplicate release Discussions.

‎.agents/skills/nemoclaw-skills-guide/SKILL.md‎

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -17,15 +17,15 @@ Load the specific skill you need after identifying it here.
1717
Skills are grouped into three buckets by audience.
1818
The prefix in each skill name indicates who it is for.
1919

20-
### `nemoclaw-user-*` (9 skills)
20+
### `nemoclaw-user-*` (10 skills)
2121

2222
For end users operating a NemoClaw sandbox.
2323
Covers installation, inference configuration, network policy management, monitoring, remote deployment, security configuration, workspace management, and reference material.
2424

25-
### `nemoclaw-maintainer-*` (8 skills)
25+
### `nemoclaw-maintainer-*` (12 skills)
2626

2727
For project maintainers.
28-
Covers the daily maintainer cadence (morning standup, daytime loop, evening handoff), cutting releases, finding PRs to review, normalizing issue and PR title tags, performing security code reviews, and verifying whether stale bug reports still reproduce on the latest release.
28+
Covers the daily maintainer cadence (morning standup, daytime loop, evening handoff), cutting releases, drafting release notes, finding PRs to review, comparing PRs, cross-issue sweeps, triage, normalizing issue and PR title tags, performing security code reviews, and verifying whether stale bug reports still reproduce on the latest release.
2929

3030
### `nemoclaw-contributor-*` (2 skills)
3131

@@ -48,17 +48,22 @@ Covers creating pull requests that follow the project template and drafting docu
4848
| `nemoclaw-user-configure-security` | Review the risk framework for every configurable security control, understand credential storage, and assess posture trade-offs. |
4949
| `nemoclaw-user-manage-sandboxes` | Manage day-two sandbox operations, including status, logs, diagnostics, rebuilds, upgrades, messaging channels, workspace files, backup, and restore. |
5050
| `nemoclaw-user-reference` | CLI command reference, plugin and blueprint architecture, baseline network policies, and troubleshooting guide. |
51+
| `nemoclaw-user-agent-skills` | Describes the agent skills shipped with NemoClaw and how to access them by cloning the repository. |
5152
<!-- user-skills-table:end -->
5253

5354
### Maintainer Skills
5455

5556
| Skill | Summary |
5657
|-------|---------|
5758
| `nemoclaw-maintainer-morning` | Morning standup: triage the backlog, determine the day's target version, label selected items, surface stragglers, and output the daily plan. |
59+
| `nemoclaw-maintainer-triage` | Suggest and optionally apply labels for issues and PRs using the live NemoClaw triage instructions. |
60+
| `nemoclaw-maintainer-cross-issue-sweep` | Scan open issues for adjacent fixes or contradiction risks when reviewing a PR. |
5861
| `nemoclaw-maintainer-day` | Daytime loop: pick the highest-value version-targeted item and execute the right workflow (merge gate, salvage, security sweep, test gaps, hotspot cooling, or sequencing). Designed for `/loop`. |
5962
| `nemoclaw-maintainer-evening` | End-of-day handoff: check version progress, bump stragglers to the next patch, generate a QA handoff summary, and cut the release tag. |
6063
| `nemoclaw-maintainer-cut-release-tag` | Cut an annotated semver tag on main, move the `latest` floating tag, and push both to origin. |
64+
| `nemoclaw-maintainer-release-notes` | Draft and publish release notes from live tag/compare data, with the three-paragraph narrative, categorized change list, and external-only contributor thanks. |
6165
| `nemoclaw-maintainer-find-review-pr` | Find open PRs labeled security + priority-high, link each to its issue, detect duplicates, and present a review summary. |
66+
| `nemoclaw-maintainer-pr-comparator` | Compare competing PRs for the same issue and recommend which one to merge. |
6267
| `nemoclaw-maintainer-normalize-title-tags` | Preview and remove bracketed `NemoClaw` title tags from issues and PRs case-insensitively, even when the tag appears later in the title. |
6368
| `nemoclaw-maintainer-security-code-review` | Perform a 9-category security review of a PR or issue, producing per-category PASS/WARNING/FAIL verdicts. |
6469
| `nemoclaw-maintainer-verify-stale` | Verify whether old bug reports still reproduce on latest. Reuses or provisions a Brev box (CPU or GPU), runs the extracted reproducer, scores confidence, and posts an evidence-backed comment with `fixed-on-latest` or `verify-inconclusive`. Tag-only — never auto-closes. |
@@ -82,8 +87,8 @@ Skills are cumulative. Each role includes the skills from the roles above it:
8287

8388
| Role | Skills included | Count | Start with |
8489
|------|----------------|-------|------------|
85-
| User | `nemoclaw-user-*` | 9 | `nemoclaw-user-get-started` |
86-
| Contributor | `nemoclaw-user-*` + `nemoclaw-contributor-*` | 11 | `nemoclaw-user-overview` |
87-
| Maintainer | All skills | 19 | `nemoclaw-maintainer-morning` |
90+
| User | `nemoclaw-user-*` | 10 | `nemoclaw-user-get-started` |
91+
| Contributor | `nemoclaw-user-*` + `nemoclaw-contributor-*` | 12 | `nemoclaw-user-overview` |
92+
| Maintainer | All skills | 24 | `nemoclaw-maintainer-morning` |
8893

8994
After identifying the role, present the applicable skills from the Skill Catalog above and recommend the starting skill.

0 commit comments

Comments
 (0)