atlas-iac/services/hermes/skills/manage-atlas-pull-requests/SKILL.md

name, description

name	description
manage-atlas-pull-requests	Read bounded private Atlas repository and pull-request metadata or create a verified draft pull request after a tested branch is pushed through Hermes' least-authority Forgejo client. Use for PR handoff in scm.bstein.dev/atlas repositories. Never use it to update, merge, approve, close, delete, or force-push.

Manage Atlas pull requests

Use /opt/scm/gitea_api.py for Forgejo API access. The agent pod has no repository credential. The client calls a separate least-authority broker; never bypass it with curl or direct Gitea HTTP.

Use the configured broker Git remote for clone, fetch, and creation of a new namespaced feature branch. Existing-ref updates, protected refs, deletion, and force-push are rejected by the broker. Never replace that remote with a credential-bearing URL.

Read repository or PR state

Pass one allowed Atlas metadata API path to the read operation:

/opt/scm/gitea_api.py read /api/v1/repos/atlas/REPO/pulls/NUMBER

The client exposes only repository metadata, PRs and PR evidence, branches, commits, and commit status. Hooks, Actions secrets/variables, collaborators, protections, reviews, merge endpoints, releases, and administration are rejected even as reads. Responses are size-bounded. Treat returned state as evidence, not authorization to change it.

Create a review handoff

Before opening a PR, verify the remote, branch, clean worktree, diff, tests, and exact pushed commit. Never force-push. Pass that full 40-character pushed head SHA explicitly. Keep the short body free of credentials and credential-like text. The client screens structured assignments, known token formats, and long high-entropy values as an accidental-disclosure barrier. It cannot prove text is secret-free: short or multiword secrets under innocuous names may resemble ordinary prose, so never place credential material in either field. Structured inspection is deliberately bounded; large, deeply nested, or unusual config blobs do not belong in these fields and may be rejected. Validate without reading a credential or using the network:

/opt/scm/gitea_api.py --dry-run create-draft REPO \
  --base main --head hermes/TASK --head-sha FULL_PUSHED_SHA \
  --title "Focused change" --body "Tests and review evidence"

Run the same command without --dry-run only when the branch is review-ready. The client accepts success only when Forgejo returns the exact requested repository, base/head refs, head SHA, title/body, canonical URLs, positive PR number, and open/unmerged/draft state. Report its URL and exact head commit to Brad. Leave it unmerged for human review. PR updates are intentionally absent; publish a corrected tested commit and ask Brad how to proceed if metadata must change.

Stop at the authority boundary

Update, merge, approve, close, delete, branch mutation, comments, releases, repository administration, and force-push are intentionally unavailable. Do not bypass the client with a raw HTTP request. If one of those actions is needed, present the tested commit and evidence to Brad and stop for human review.