Ground the changeset in the live branch diff, not stale branch intent. Always inspect the current branch state against its base before choosing package scope or release type.

2. Identify the publishable package scope from the live branch diff.

First inspect the live branch state:

git diff --name-status origin/main...HEAD

git diff --stat origin/main...HEAD

git log --oneline --decorate --no-merges origin/main..HEAD

Use that to separate real publishable-package behavior changes from repo-local docs, skills, tooling, or cleanup.

python3 .codex/skills/changeset-pr/scripts/run_changeset_status.py --verbose

python3 .codex/skills/changeset-pr/scripts/run_changeset_status.py --output /tmp/changeset-status.json

- Prefer the helper script over direct `pnpm exec changeset status` in Codex runs because shell wrappers in non-TTY sessions can add `/dev/tty` noise or otherwise make the raw CLI output unreliable.

from __future__ import annotations

import argparse

import json

import subprocess

import sys

from pathlib import Path

def run(cmd: list[str], cwd: Path) -> str:

result = subprocess.run(

cmd,

cwd=str(cwd),

check=True,

capture_output=True,

text=True,

)

return result.stdout.strip()

def find_repo_root(start: Path) -> Path:

return Path(run(["git", "rev-parse", "--show-toplevel"], start))

def find_changeset_cli(repo_root: Path) -> Path:

candidates = [

repo_root / "node_modules" / "@changesets" / "cli" / "bin.js",

repo_root / "node_modules" / ".bin" / "changeset",

]

for candidate in candidates:

if candidate.exists():

return candidate

raise FileNotFoundError("Unable to locate Changesets CLI under node_modules")

def main() -> int:

parser = argparse.ArgumentParser(

description="Run Changesets status without shell wrappers so output is stable in non-TTY environments."

)

parser.add_argument(

"--repo-root",

default=".",

help="Repo root. Defaults to current working directory.",

)

parser.add_argument(

"--output",

help="Optional path to write Changesets JSON output.",

)

parser.add_argument(

"--verbose",

action="store_true",

help="Pass --verbose to Changesets status.",

)

parser.add_argument(

"--json",

action="store_true",

help="Emit a small JSON wrapper with command, exit code, stdout, and stderr.",

)

args = parser.parse_args()

repo_root = find_repo_root(Path(args.repo_root).resolve())

cli = find_changeset_cli(repo_root)

cmd = ["node", str(cli), "status"]

if args.verbose:

cmd.append("--verbose")

if args.output:

cmd.extend(["--output", str(Path(args.output).resolve())])

proc = subprocess.run(

cmd,

cwd=str(repo_root),

capture_output=True,

text=True,

check=False,

)

if args.json:

payload = {

"command": cmd,

"exit_code": proc.returncode,

"stdout": proc.stdout,

"stderr": proc.stderr,

}

sys.stdout.write(json.dumps(payload, indent=2) + "\n")

else:

if proc.stdout:

sys.stdout.write(proc.stdout)

if proc.stderr:

sys.stderr.write(proc.stderr)

return proc.returncode

if __name__ == "__main__":

raise SystemExit(main())

name: gh-pr-metadata

description: Update the current GitHub PR title and body for this repository so they match the repo's pull request template and conventional-commit title style. Use when a PR title is vague or misformatted, when the PR body is missing required sections or checklist items, when Codex needs to normalize PR metadata before review or merge, or when GitHub comments/checks indicate the PR title or body should be corrected.

Normalize the current branch's GitHub PR metadata to this repo's expectations. Keep the title in conventional-commit style, keep the body aligned to `.github/pull_request_template.md`, and validate before handoff.

Ground the PR metadata in the live branch state, not stale branch names or old commit subjects. Always inspect the current branch diff versus its base before rewriting the PR title/body.

Read [references/repo-pr-format.md](./references/repo-pr-format.md) when you need the exact section order, checklist items, or a title example.

1. Resolve the current branch PR.

gh pr view --json number,title,body,url,headRefName,baseRefName

2. Inspect the current branch state against the PR base branch.

At minimum, check:

git diff --name-status origin/<base>...HEAD

git diff --stat origin/<base>...HEAD

git log --oneline --decorate --no-merges origin/<base>..HEAD

Use these to answer:

- what files actually differ from the base right now

- which changes are functional versus cleanup/tooling/docs

- whether the existing PR title/body still matches the current branch after rebases, reverts, or scope narrowing

3. Validate the current title and body.

python3 .codex/skills/gh-pr-metadata/scripts/validate_pr_metadata.py

4. If the PR body needs a clean template scaffold, print one:

python3 .codex/skills/gh-pr-metadata/scripts/validate_pr_metadata.py --print-template

5. Rewrite the PR title in conventional-commit style.

Rules:

- Prefer `type(scope): summary`

- Keep the title short and direct

- Use repo-typical types such as `fix`, `feat`, `docs`, `refactor`, `chore`, `test`, `ci`, `build`, `perf`, `revert`

- Keep the scope tight to the affected package or subsystem when useful

- Do not add prefixes like `[codex]`

- Make sure the title describes the current branch diff, not the original branch intent if the branch was later narrowed or partially reverted

6. Rewrite the PR body to preserve the repo template structure:

- `## Description`

- `## Related Issue`

- `## Types of changes`

- `## Checklist`

7. Update the PR with `gh`.

Prefer writing the body to a temporary file first, then:

gh pr edit --title "<new-title>" --body-file /tmp/pr-body.md

8. Re-run validation and report whether the PR metadata is now compliant.

python3 .codex/skills/gh-pr-metadata/scripts/validate_pr_metadata.py

- Keep `Description` prose-first and specific to the branch.

- Reflect the branch as it exists now, especially after rebases, cleanups, or partial reverts.

- Summarize the real file-level themes from the live diff instead of copying commit messages mechanically.

- Put issue references in `Related Issue`; if there is no issue, say so plainly instead of deleting the section.

- In `Types of changes`, check only the boxes that actually apply.

- In `Checklist`, preserve all repo checklist items and mark only the items that are true.

- Do not remove required sections just because the PR is small.

- Keep the body concise; do not turn it into a changelog dump.

Good examples:

- `fix(node): normalize remote chunk parsing`

- `chore(manifest): drop extra compat cleanup`

- `docs(agents): prefer normalized webpack path requires`

Bad examples:

- `update pr`

- `fix stuff`

- `[codex] cleanup`

Use the helper script to detect:

- non-conventional PR titles

- missing or reordered template sections

- missing repo checklist items

The script validates either the current PR from `gh` or explicit `--title` / `--body-file` input.

interface:

display_name: 'GH PR Metadata'

short_description: 'Normalize PR title and body'

default_prompt: "Use $gh-pr-metadata to update this repo's PR title and body to match the template and conventional-commit style."

Source files:

- `.github/pull_request_template.md`

- `AGENTS.md`

Keep these sections in this order:

1. `## Description`

2. `## Related Issue`

3. `## Types of changes`

4. `## Checklist`

Types of changes:

- `- [ ] Docs change / refactoring / dependency upgrade`

- `- [ ] Bug fix (non-breaking change which fixes an issue)`

- `- [ ] New feature (non-breaking change which adds functionality)`

Checklist:

- `- [ ] I have added tests to cover my changes.`

- `- [ ] All new and existing tests passed.`

- `- [ ] I have updated the documentation.`

Prefer conventional-commit style:

Examples:

- `fix(node): normalize remote chunk parsing`

- `docs(agents): prefer normalized webpack path requires`

- `chore(manifest): drop extra compat cleanup`

Avoid:

- bracketed prefixes like `[codex]`

- vague summaries like `update pr`

- titles that do not describe the branch's actual change