create-pr

Create PR

Publish the current change as a verified, accurately described pull request that is ready for review. The request authorizes the repository's declared gates, relevant commits, PR metadata updates, one ordinary draft pull request or the confirmed native stack layers owned by the change, required review and behavior testing, in-scope fixes, and transitions to ready for review. This includes the project's existing PR preview path when required to test the change. Merge and integration delivery belong to /deliver, which a direct request continues into under the delivery settings; the request does not add unrelated changes.

A failed check, review or CI run routes to repair, not a stop. Stop only when there is nothing to publish, a material unresolved choice or new authority is needed, or an external blocker remains after safe alternatives are exhausted. A material choice that publication depends on stops before any push or draft PR. Keep the PR draft while any required evidence or CI is missing, pending or failing.

Conditional references

• When the branch belongs to a native GitHub stack or builds on an unmerged PR (step 1), read ../git-workflow/references/github-stacks.md. The request then authorizes submission and metadata reconciliation for the confirmed stack layers owned by the current change, not unrelated branches.
• When the change has visible or demonstrable behavior, or local screenshots or videos belong in the PR, read references/walkthroughs.md. It owns media capture, upload and gap reporting. Never commit evidence media to the repository. Missing media capabilities alone do not block publication or readiness; required behavior evidence and project gates still apply.

Preview-only draft

When required behavior can only be tested on a PR preview, open or update the draft needed to obtain it under this publication request after the available checks pass. Publish a native stack's necessary drafts through the same permitted stack path. Test that exact revision and resume the loop before readiness. Recording a walkthrough does not replace behavior testing.

Workflow

1. Inspect the working tree, staged diff, recent commits, remote default branch, stack topology when applicable, and any existing remote head. Preserve unrelated local work.

   PRs target the remote default branch. The exception is a long-lived base branch that the user names or that project instructions such as AGENTS.md or CONTRIBUTING.md document, such as a release branch for a backport: the named base. A branch that is only an open PR's feature head is never a named base. Outside a named base and the stack reference's native stack operations, never set a PR base to a non-default branch by hand.

   Before choosing a base, check whether the change builds on an unmerged PR. List open PRs with gh pr list --state open --limit 1000 --json number,headRefName,headRefOid,isCrossRepository,baseRefName. A listing with as many rows as the limit may be truncated: re-list with a higher limit until it returns fewer rows, or stop and report. Fetch the heads in one git fetch REMOTE pull/A/head pull/B/head ... from the remote of the repository that list queried. Skip this branch's own PR, any PR whose head contains this branch's head, and any same-repository PR whose head branch is the named base. The change builds on PR N when N is from this repository and its head branch is the intended base, or when git rev-list HEAD ^BASE ^DEFAULT and git rev-list HEAD-OID ^BASE ^DEFAULT share a commit. DEFAULT is the fetched remote default, BASE the fetched named base or DEFAULT, and HEAD-OID N's headRefOid. Stop and report a match from a fork (isCrossRepository), which cannot be a base here. With a named base, also stop and report a match based on any other branch, so a backport never stacks on the default trunk. Publish any other match as a native stack under the stack reference's "When to start a stack".

2. Stop if there are no relevant changes or commits ahead of the remote base. Continue without an empty commit when the work is already committed.

3. If currently on the base branch, create a focused branch named from the issue or change.

4. Establish the PR claim and publication requirements before publishing anything. Read the explicit request, linked issue or confirmed mini-spec, applicable project instructions, product docs, ADRs or durable decisions, the nearest DEFINITION_OF_READY.md, and the completion evidence supplied by the implementation workflow. If no source states the claim, reconstruct the narrowest claim supported by the commits and diff and label it as inferred.

5. Apply /code-review fix-all and /test-against-spec fix to the current requirements and change. Reuse only results whose content, command, environment and coverage still match; run missing or stale review and real-interface checks. If the claim was inferred from the diff, establish explicit expected behavior before specification testing. Resolve a material ambiguity without inventing requirements from the implementation.

6. Repair every verified in-scope requirement, fidelity, test and compatibility gap, regardless of severity, through /implement's development loop; use the same documented checks directly if a companion skill is unavailable. After edits, obtain renewed review and specification results for the affected scope before publication or readiness. Targeted finding revalidation can reuse unchanged review coverage; fixing a finding does not itself renew the review result. Run the missing or invalidated project gate after fixes converge.

7. Commit uncommitted relevant work under git-workflow: stage only relevant files, excluding secrets and unrelated local work, and use a concise Conventional Commit subject. Never amend and never skip hooks. Preserve already-published history and add a new commit for any correction. Run the publication guard at each commit, push and PR write.

8. Title each pull request with a Conventional Commit subject covering the whole change; git-workflow's squash merge makes that title the base-branch commit subject. Follow ../agent-writing/references/pr-descriptions.md for the body's section order and character limits, preserving explicit project-template requirements. Keep every PR template heading verbatim and in order, and under a heading with nothing to say write a one-line None or the reason; this is not boilerplate to omit. Leave the author's verification out of the body's sections; the final handoff reports it, and review results go only in the review note at the end of the body. Before writing it, search open and closed issues and recent sibling sessions or adjacent branches when available for related findings and duplicates. Put each closing keyword on its own line as Closes #N after the change summary, and only on the layer that completes that issue. Run template-check on the draft with --kind pr --body FILE and fix every heading problem it reports before publishing.

9. After the publication checks pass, or under the preview-only draft rule above, push an ordinary branch normally and set its upstream when needed, then open one draft PR against the remote default or the named base. For a verified native stack, follow the stack reference: a new top layer above frozen approved PRs uses protected push, separate PR creation and native append; a new stack on a frozen lower PR uses protected gh stack link; broader authorized submissions use gh stack submit. Require current evidence for every published layer. Only guarded official stack operations may rebase or push with force-with-lease. Preserve bottom-to-top topology and keep each layer draft.

10. Run the PR-specific phase. Compare the actual PR diff, body, links, metadata, committed tests and documentation, supplied completion evidence, and facts that exist only after publication. Run template-check on the live body with --pr N; a reported heading problem is a metadata-only gap. Correct metadata-only gaps without a commit.

11. If the PR-specific phase or CI exposes an in-scope repository, behavior, fidelity, test, documentation or compatibility gap, repair it through the development loop. Revalidate affected requirements, then use /update-pr for the same PR and verify its new head. Continue until all verified requirement gaps are resolved.

12. Invoke delivery-wait's wait checks-terminal operation, under its running rules, with the repository, PR number, exact head, --all-workflows, absolute deadline and --json. --all-workflows waits for every GitHub Actions run and job on the head, including jobs that later stages add. Add one --check per commit status or other app's check that applies, such as a deployment preview. Do not build the --check list from the checks visible when the wait starts; that set is often partial. For a dispatched run whose checks do not appear on the PR, also run wait workflow-terminal --run-id <id> --head <sha>. Passively await meaningful transitions; do not substitute repeated model turns for a passive wait, and report an unavailable host capability. Inspect failed logs and return established in-scope causes to step 11. If expected PR checks have no run, inspect mergeability and resolve an established conflict through /update-pr before considering a retrigger. An unavailable external dependency remains pending or blocked, never a passed check. Call CI green only after the wait reports it satisfied for the current head, and then say so in plain words. Call a local check passing from its actual result on the tested content. Treat a failure as flaky or transient only after its failing log shows it is intermittent. Blaming something other than the change, or leaving the failure out of repair, needs its own evidence; a flaky failure the change introduced is in scope.

13. Once the PR is missing nothing required by the publication and PR-specific phases and all applicable CI is observed green for its exact head, mark it ready for review. Return every affected URL and linked issue, native stack order when applicable, final states, metadata changes, supplied completion evidence, what the publication guard rewrote, and observed readiness and CI evidence. Include incomplete walkthrough requirements and actionable remedies, even when the PR is ready. Started directly, continue under the delivery settings; with entry-points: deliver, the ready PR goes on to /address-feedback.