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/coordinator/gitea_api.py for Forgejo API access. It reads its token from the pod-lifetime Vault projection; never read that file, copy the token, put it in an argument or environment variable, or replace this client with curl.

Read repository or PR state

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

/opt/coordinator/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. Validate without reading a credential or using the network:

/opt/coordinator/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.