---
name: manage-atlas-pull-requests
description: Read private Atlas repository and pull-request metadata, create a draft pull request after a tested branch is pushed, or update the title/body of an existing draft through Hermes' least-authority Forgejo client. Use for PR handoff in scm.bstein.dev/atlas repositories. Never use it to 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 an Atlas repository API path to the read operation:

```sh
/opt/coordinator/gitea_api.py read /api/v1/repos/atlas/REPO/pulls/NUMBER
```

Reads outside `scm.bstein.dev/atlas` are rejected. 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. Write the PR description to a workspace
file so multiline Markdown is not shell-quoted, then validate without reading a
credential or using the network:

```sh
/opt/coordinator/gitea_api.py --dry-run create-draft REPO \
  --base main --head hermes/TASK --title "Focused change" \
  --body-file /tmp/pr-body.md
```

Run the same command without `--dry-run` only when the branch is review-ready.
The client always creates a draft in the same repository. Report its URL and
exact head commit to Brad. Leave it unmerged for human review.

## Update an existing draft

Use only a title, a body file, or both:

```sh
/opt/coordinator/gitea_api.py update-draft REPO NUMBER \
  --body-file /tmp/pr-body.md
```

The client first reads the PR from Forgejo and refuses the update unless it is
still a draft. It never changes head/base, review state, or merge state.

## Stop at the authority boundary

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.