sprint-release-notes

Automatically generate sprint release notes from a GitHub Project Board and publish to their respective repositories. Groups completed items by repository, g...

Security Scan

The skill generally does what it says (generate and publish release notes from a GitHub Project board) but the package metadata, runtime instructions, and included scripts disagree about where credentials come from and include an extra webhook config — these mismatches could cause accidental secret storage or unnoticed external posting.

Purpose & Capability

The skill's stated purpose (read a GitHub Project board, compile per-repo release notes, and publish GitHub Releases) is coherent with the included Python script which uses the GitHub GraphQL and REST APIs. However the registry/metadata shows no required credentials or env vars while the SKILL.md explicitly requires a GitHub PAT and the scripts expect a PAT in references/config.yaml. That mismatch (manifest claiming no credentials but runtime needing a PAT with repo/write scopes) is a material inconsistency.

Instruction Scope

SKILL.md instructs the agent to query Projects v2, read PRs, commits, README and docs via the GitHub API — all within the stated purpose. The instructions also refer to local reference files (github-queries.md and contributor-scoring.md) which are present. One note: the skill's docs/README do not mention an optional Discord webhook, but references/config.yaml contains a webhook_url entry (and could be used by code paths); that introduces an extra external endpoint not described in SKILL.md.

Install Mechanism

No install spec is provided (instruction-only), and included scripts are plain Python/bash. The Python script requires the 'requests' library, which is expected. No network download/install from arbitrary URLs or package registries is present.

Credentials

The skill needs a GitHub PAT with repository and project access to function (SKILL.md specifies scopes 'repo', 'read:org', 'project'), which is appropriate for publishing releases. But the registry entry lists no required env vars and no primary credential — a mismatch that hides the need for a high-privilege token. Additionally, references/config.yaml includes an optional Discord webhook field; storing a PAT or sending data to a webhook would permit external transmission of potentially sensitive data if the code uses that webhook path.

Persistence & Privilege

The skill is not marked always:true and does not request system-wide persistence. The included run script runs the generator in --dry-run by default. There is no evidence the skill modifies other skills or global agent configuration.

What to consider before installing

Things to consider before installing or running this skill: - It requires a GitHub Personal Access Token (PAT) with repository (write) and Projects access to create/update Releases. The registry metadata does NOT declare this; expect the skill to ask you for the PAT at runtime or to read it from the included references/config.yaml file. - The package includes a sample references/config.yaml where users might be tempted to paste their PAT. Storing long-lived tokens in plaintext files is risky; prefer using a short-lived token or entering the token interactively and avoid committing it to disk or version control. - The code and instructions are coherent with the stated purpose (reading ProjectV2, PRs, commits, README, creating Releases), but the presence of a Discord webhook entry in references/config.yaml is not documented in SKILL.md. Confirm whether the script actually sends data to that webhook before providing secrets — this could be an unexpected external sink. - Run the included script with --dry-run first (the run script defaults to dry-run) and review generate_release_notes.py fully to confirm where it posts outputs and whether it transmits anything outside GitHub. - Restrict the PAT's scope and lifetime (limit to only the repos/orgs needed, consider a repo-scoped token or a token with minimal write scope), and monitor its usage. If you cannot verify why the token is required or where outputs go (especially to the webhook), do not provide a PAT. - Ask the publisher to update the registry metadata to declare the required credential and to document webhook behavior explicitly. If you want higher assurance, request that the skill avoid storing credentials in local files and only accept tokens interactively or via well-documented environment variables.

Sprint Release Notes Generator

Generate executive-ready sprint release notes by reading a GitHub Project Board (v2), analyzing completed items, reading associated documentation, evaluating contributor performance, and publishing a polished markdown release note to a designated repo.

Required Inputs

Collect these from the user before starting:

1. GitHub Project Board URL — e.g., https://github.com/orgs/{org}/projects/{number} or https://github.com/users/{user}/projects/{number}
2. GitHub PAT Token — must have scopes: repo, read:org, project (read access to Projects v2)
3. Sprint identifier (optional) — if not provided, auto-detect the current/latest completed sprint iteration

If any of these are missing, ask the user before proceeding.

Workflow Overview

The skill executes in 7 phases. Run them sequentially:

1. Discover Sprint — Query the GitHub Project Board for the current sprint iteration
2. Categorize Items — Separate completed vs. deferred/carried-over items, and group by repository
3. Deep-Read Completed Items — For each completed item, read associated repo docs, PRs, commits
4. Evaluate Contributors — Score engineers for Lead Engineer & MVP recognition
5. Compile Per-Repo Release Notes — Generate separate markdown for each repository
6. Publish to Respective Repos — Create or update a GitHub Release per repo with the markdown as the release body
7. Post to Project Issue (Optional) — Comment on a designated issue with summary links

Phase 1: Discover Sprint

Read the reference file for the full GraphQL queries:

view /path/to/skill/references/github-queries.md

Use the GitHub GraphQL API (https://api.github.com/graphql) with the user's PAT token.

Step 1.1: Fetch the project ID from the board URL.

• Extract org/user and project number from the URL
• Query for the project node ID using organization.projectV2(number: N) or user.projectV2(number: N)

Step 1.2: Fetch iteration fields.

• Query the project's fields to find the iteration-type field (usually named "Sprint" or "Iteration")
• Identify the current iteration by checking iteration configurations — pick the iteration whose date range includes today, or the most recently completed one

Step 1.3: Fetch all items in the current sprint iteration.

• Query project items filtered by the iteration field value
• For each item, extract: title, status, linked repository, associated PRs/issues, labels, assignees

Phase 2: Categorize Items & Group by Repo

Separate items into:

• Completed: Status is "Done" or "Closed" or equivalent
• Carried Over: Items that were in the sprint but are not Done (moved to next sprint)
• Bugs Fixed: Items labeled as "bug" that are completed

Group by Repository:

• For each completed item, identify its linked repository (from the project item's field or linked PR)
• Create a map: Map<repo_name, List<completed_items>>
• Each repo will get its own GitHub Release (same sprint markdown as the release body)

Also extract metadata:

• Sprint name/number from the iteration field
• Sprint date range (start and end dates)
• Derive version as v1.{sprint_number}.0

Phase 3: Deep-Read Completed Items

For each completed item, gather context from the associated repository. This is the intelligence-gathering phase. Read the reference file for API patterns:

view /path/to/skill/references/github-queries.md

For each completed item:

3a. PR Descriptions & Commits

• Find linked pull requests via the issue timeline or cross-references
• Read PR descriptions (these often contain the best context on what changed and why)
• Read commit messages on merged PRs
• Note: PR descriptions are gold — they often explain the "why" behind changes

3b. Documentation Changes

• Check if the PR modified any files in /docs, README.md, or wiki-related paths
• If docs were changed, fetch the new content to understand feature documentation
• Use the GitHub Contents API: GET /repos/{owner}/{repo}/contents/{path}

3c. README Files

• Fetch the repo's root README.md for overall project context
• Only do this once per unique repo (cache it)

3d. Labels & Metadata

• Collect labels to categorize: feature, bug, infrastructure, security, performance, tech-debt
• Use labels to sort items into the correct release notes sections

Categorization heuristic for release notes sections:

• Labels containing "feature", "enhancement", "user-facing" → New User-Facing Features
• Labels containing "infra", "tech-debt", "performance", "security", "devops", "scalability" → Infrastructure & Tech Debt
• Labels containing "bug", "fix", "hotfix" → Stability & Bug Fixes
• If no clear label, infer from the PR title and description

Phase 4: Evaluate Contributors

Score each contributor who worked on completed items. Read the scoring reference:

view /path/to/skill/references/contributor-scoring.md

Collect per-contributor metrics:

• PRs merged count — from completed items' linked PRs
• Code complexity — approximate from lines changed (additions + deletions) across their PRs
• Review contributions — count of PR reviews given to others (use the PR reviews API)
• Bug fixes — count of completed items labeled "bug" assigned to them
• Challenge score — estimate difficulty of cards they completed based on: labels (e.g., "complex", "critical"), story points if available, or item description length as a rough proxy

Scoring formula:

Score = (PRs_merged × 2) + (lines_changed / 100) + (reviews_given × 3) + (bugs_fixed × 4) + (challenge_score × 5)

• Lead Engineer: Highest overall score (reflects breadth and depth of contribution)
• MVP: Highest score on the single hardest item OR highest bug-fix impact (the "unsung hero" who tackled the toughest problem)

If scores are very close (within 10%), note both contributors.

Phase 5: Compile Per-Repo Release Notes

For each repository group, generate a separate release notes document using the template below (this becomes the GitHub Release body).

Repository Mapping:

• Collect all unique repo names from completed items
• For each repo, filter its completed items
• Generate one markdown document per repo

Use the exact template below. Replace all [placeholders] with real data. If a section has no items, write "No changes this sprint." instead of removing the section.

# 🚀 Sprint Release Notes: [Sprint Name/Number] - [Repo Name]

**Date:** [YYYY-MM-DD] | **Version:** v1.[sprint_number].0 | **Status:** Shipped | **Repository:** [repo_name]

---

## 🎯 Summary

[2-3 sentences: What was the primary objective for this repository? What shipped?]

---

## ✨ New Features

* **[Issue Title]**: [Short description of what changed].

---

## 🛠️ Infrastructure & Tech Debt

* **[Issue Title]**: [Description of work done].

---

## 🐛 Bug Fixes

* **[Issue Title]**: [Description of fix].

---

## 📊 Items Completed

- [ ] #[issue_number] [issue_title]

---

*Generated from GitHub Project Board - Sprint [sprint_name]*

Phase 6: Publish to Respective Repos (GitHub Releases)

For each repository that had completed items, publish the sprint markdown as that repo’s Release (the Releases page / releases/latest UI), not as a file in the tree.

Step 6.1: Derive the release tag and name from the sprint (aligned with Phase 2):

• Tag name and release name: v1.[sprint_number].0 (same as the Version line in the template)

Step 6.2: Resolve whether a release for that tag already exists:

GET /repos/{owner}/{repo}/releases/tags/v1.[sprint_number].0

• If the response is 404, create a new release (Step 6.3).
• If the response includes a release id, update it (Step 6.4).

Step 6.3: Create a new release (creates the tag on the default branch if the tag does not exist yet):

POST /repos/{owner}/{repo}/releases

JSON body (minimal):

• tag_name: v1.[sprint_number].0
• target_commitish: the repo’s default branch (e.g. main)
• name: same as tag_name (or a short sprint title if the user prefers)
• body: the full markdown from Phase 5
• draft: false
• prerelease: false

Step 6.4: Update an existing release’s notes and title flags:

PATCH /repos/{owner}/{repo}/releases/{release_id}

Example (curl; use the user’s PAT and API version header as appropriate):

curl -L -X PATCH \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  https://api.github.com/repos/OWNER/REPO/releases/RELEASE_ID \
  -d '{
    "name": "v1.2.3",
    "body": "Updated release notes",
    "draft": false,
    "prerelease": false
  }'

Step 6.5: Track each repo’s html_url from the create/update response for Phase 7 and the user summary.

Notes:

• The PAT needs permission to create releases and push tags (typically repo on private repos).
• Prefer Authorization: Bearer with Accept: application/vnd.github+json for REST calls; include X-GitHub-Api-Version when using calendar-dated API versions.
• If a repo must not auto-create tags, create the tag (or draft release) out of band and only PATCH the body.

Phase 7: Post Summary to Project Issue (Optional)

If the user specifies a designated issue to post the summary:

Step 7.1: Collect all published release URLs (html_url from each create/update response).

Step 7.2: Use GitHub Issues API to add a comment:

POST /repos/{owner}/{repo}/issues/{issue_number}/comments

Comment template:

## 🚀 Sprint [sprint_number] Release Notes Published

Release notes have been published to each repository’s Releases:

| Repository | Release |
|------------|---------|
| [repo_1] | [release_link_1] |
| [repo_2] | [release_link_2] |
| ... | ... |

---
*Generated automatically from GitHub Project Board*

Step 7.3: Confirm success and provide the user with all published links.

Error Handling

• Rate limiting: If GitHub API returns 403 with rate limit headers, wait and retry. Inform the user.
• Missing permissions: If 404 on project queries, the PAT likely lacks project scope. Tell the user which scopes are needed.
• Empty sprint: If no items found in the current iteration, inform the user and ask if they want to check a different sprint.
• No linked PRs: Some items may not have linked PRs. Use the item title/description as the best available context.
• No linked repo: If an item has no repository link, use a default repo or ask the user for clarification.
• Large sprints: If >50 items, batch API calls and summarize in groups to stay within context limits.
• Release publish failures: If creating or updating a release fails (permissions, tag policy, etc.), continue with other repos and report failures at the end.

Important Notes

• Always use the GitHub GraphQL API for project board queries (REST API doesn't support Projects v2 well)
• Use the REST API for repo contents (read), PR details, and Releases (create/update) for publishing
• Cache repo READMEs — don't fetch the same README twice
• The PAT token is sensitive — never log it, echo it, or include it in output files
• All API calls go through https://api.github.com — ensure network access is available