submit-pr

---
name: submit-pr
description: >-
  Create and submit a pull request from the current branch — sync with main,
  format/lint/test, commit all changes, push, monitor the Check workflow, and
  surface the Composer PR deploy URL when the PR has one. Use when the user asks to open, submit, or
  raise a PR, including stacking a PR on another open PR (`gh stack`). To land
  an existing PR, use the `land` skill instead.
---

# Submit PR

Take the current branch and open a green pull request. You **never** create a new
branch or worktree — you submit from the branch and worktree the session already
runs in. To land (merge) an existing PR, use the `land` skill.

## Steps

1. **Sync with base.** Merge the branch's base into it and resolve any
   conflicts: `origin/main` for a standalone or bottom-of-stack branch; for a
   branch stacked on another open PR, merge that parent PR's head branch
   instead — merging `main` into a stacked child duplicates the parent's
   commits into its PR.
2. **Format.** Run `pnpm format` (oxfmt — CI checks `oxfmt --check`).
3. **Lint.** `moon run :lint -- --fix` must succeed.
4. **Test.** `moon run :test` must pass.
5. **Changeset.** If the change is consumer-relevant, write one `.changeset/*.md`
   now, from the whole diff against the base: a summary of what the PR changes
   for a consumer, not a log of the commits. If a file already exists, rewrite
   its body rather than appending. See
   [`agents/instructions/changesets.md`](../../../agents/instructions/changesets.md)
   for when one is needed, which package to name, and bump levels.
6. **Account for every file.** `git status`; commit ALL modified/untracked
   files, including the changeset and edits the user made in the shared
   worktree. Never leave changes behind silently — commit them or confirm
   exclusion with the user.
7. **Push**, then verify `git status` shows a clean working tree. If anything
   remains, commit it or confirm before proceeding.
8. **Open the PR as a draft** with `gh pr create --draft`. A draft runs only `check` and
   the node tests, so iterate on the draft freely; a PR opened ready from a `claude/` or `dm/`
   branch is converted to a draft anyway (`draft-on-open.yml`). Add the `preview` label only when the
   user asks for a preview deploy: each push to a labeled PR builds one. Title uses `scope: description`. Write the
   description with the `pr-description` skill: pick every template that
   applies (summary and safety always), and link any Linear issue as
   `closes DX-123` or `part of DX-123`. Apply the Safety labels it specifies
   (`risk: …` always, plus any `breaking:`/`api:`/`tests:`/`revert:`/`perf:`).
   If this work builds on another open PR (or the user asked for a stack), see
   **Stacked PRs** below instead of `gh pr create`.
9. **Mark it ready.** Run `moon run :lint :build :test-types` locally, then `gh pr ready`, which
   starts the full Check: a draft runs `check` and the node tests, a ready PR every suite.
   Every push after this runs Check, so batch fixes into one push rather than pushing each one, and merge
   `main` in only to resolve a conflict. To keep iterating, convert it back to a
   draft first (`gh pr ready --undo`).
10. **Monitor CI every 5 minutes:**
    `gh run list --branch <branch> --limit 3 --workflow "Check"` and
    `pnpm -w gh-action --verify --watch`. Diagnose and, where possible, fix ALL
    CI errors — even ones unrelated to this branch. Never merge around a red
    Check; fix the root cause with `gh run view <id> --log-failed`.
11. **Address and RESPOND to every PR review comment.**

## Stacked PRs

GitHub has native stacked PRs (public preview since 2026-07, via the `gh-stack`
CLI extension) — it postdates model training, so follow this section rather than
prior knowledge. One command covers this skill's case (the branch already
exists):

```bash
gh extension install github/gh-stack   # once per machine
gh stack link <base-pr-number> <current-branch>
```

Arguments run bottom-to-top; each may be a PR number, PR URL, or branch name.
`link` pushes the branch, creates its PR if missing, chains the base branches,
and registers the stack with GitHub — stack map in the PR UI, CI as if
targeting `main`, one-click whole-stack merge. Linking is what makes it a
stack; a PR merely based on another PR's branch is not one. A PR that `link`
creates gets an auto-generated title and body — follow up with
`gh pr edit <pr> --title --body` so it meets step 8's standards (scope-prefixed
title, `pr-description` templates, Linear link), and `gh pr ready --undo <pr>`
to make it a draft until step 9. Docs:
<https://docs.github.com/en/pull-requests/how-tos/stacked-pull-requests>.

## Composer PR deploy URL — surface when labeled

For a PR labeled `preview`, the `pr-deploy.yml` workflow posts a sticky `composer-preview` comment with
a `*.workers.dev` preview-alias URL (a `wrangler versions upload --preview-alias`
against composer-app's `dev` env). Fetch it and include it verbatim next to the
PR link in chat summaries AND the final message:

```
gh pr view <pr> --json comments
# or: gh api repos/dxos/dxos/issues/<pr>/comments
```

If the preview comment is not posted yet (deploy still running), say "preview
pending" next to the PR link and re-check on the next status update.

## Rules

- **Do NOT delete any branch or worktree that has uncommitted changes.**
- Do not create a new branch or PR — submit from what exists.
- Work only in the assigned worktree (see `AGENTS.md` Non-negotiables).