pull-request:create

Context

• Remote URL: !git remote get-url origin
• Review bot: !bun ${CLAUDE_PLUGIN_ROOT}/scripts/detect-bot.ts
• PR Template: !bun ${CLAUDE_PLUGIN_ROOT}/scripts/pr-template.ts

!bun ${CLAUDE_PLUGIN_ROOT}/scripts/git-context.ts

!bun ${CLAUDE_PLUGIN_ROOT}/scripts/contributing.ts

Title

• Check the log in the context above to determine the repo's commit style:
  • subject (default): ${subject}: ${summary} (e.g., api: add timeout to request)
  • conventional: ${type}: ${summary} (e.g., fix: add timeout to request)
• Name the primary change. If the title needs a serial comma, it's naming several changes. Name the shared theme or the largest change, and put the rest in the body.
• Keep under 50 characters. Cut scope rather than truncating words.
• Use imperative mood, lowercase except proper nouns

Body

Lead with intent: why the change exists, the decisions a reviewer can't reconstruct from the diff, and how you know it works. Don't restate what the diff, the git log, or the status checks show. Review the session for content that never reached the code (rejected alternatives, scope changes, test observations) and state each as a self-contained decision, never as a delta against a plan the reviewer hasn't seen.

• Open with a bare verb ("Adds", "Fixes", "Removes") when the change is self-evident, or with the problem when it needs justifying. Don't restate the title.
• Default to prose. Write a small PR as one paragraph with no headings. Add ## sections only when the body is long enough to need them. Base length on substance, not diff size.
• Reference the motivating issue at the end of the opening (Closes #N, Fixes #N, or bare #N if not closing). Never touch the issue itself: no comments, labels, milestones, or assignees.
• Wrap code identifiers in backticks, but leave bare anything the platform auto-links: commit SHAs and issue/MR refs (#N, !N, owner/repo#N). Backticked refs don't auto-link.
• Write one line per paragraph and one line per list item. The body soft-wraps when it renders. Hard-wrapping at a column only narrows it.

Load the writing skill for the full set of tropes to avoid.

When the context above shows a detected PR template, follow its structure instead of the default body format and load references/template.md for mapping content into its sections.

Reviewers

Corporate and internal repos only. On OSS (a public repo you don't own), skip this step and leave triage to the maintainer. Suggest reviewers for the user to choose from. Never assign them yourself. Load references/reviewers.md for the visibility gate, the ranking script (${CLAUDE_PLUGIN_ROOT}/scripts/suggest-reviewers.ts), and username resolution.

Arguments

Parse $ARGUMENTS for these flags. With none, create a PR/MR that is ready for review and, on a repo you own, set to auto-merge.

• --draft: open the PR/MR as a draft. Default: ready for review.
• --no-auto: skip auto-merge. Default: auto-merge on a repo you own, off on a third-party repo and off under --draft. See references/merge.md.
• --base <ref>: parent branch to target. A branch whose parent is another topic branch is a stack layer. Only this flag or the user identifies one. The upstream ref tracks the branch's own remote copy, so it can't identify the parent. Default: the repo's default branch.
• --label <name>: apply a label, repeatable. Confirm each label exists first, per references/labels.md. Default: none.
• --no-review: don't request the hosted review. Default: on a repo that gates its hosted bot on a label, request it when the diff clears the metered-review gate and no local pass ran. See references/labels.md.

Workflow

1. Branch validation: If the context above shows you're on a default branch (main/master), stop and ask the user to switch to a feature branch first.
2. Stage changes if not already staged: git add .
3. Commit if there are no commits yet on the branch, using the same format as the PR title.
4. Local bot review, gated: the Review bot line above reports repo config, CLI presence, and any cooldown. On a config hit with no cooldown, apply the gate in follow-up's SKILL.md to decide whether the diff needs a metered review. If it does, run pull-request:follow-up --local before pushing. With no config, decide from the hosted signals in follow-up's local.md. Skip when a local bot pass already ran on this branch this session (/ship runs one), the gate says skip, the provider is paused, detection finds nothing, or the user declines.
5. Push the branch to remote: git push -u origin HEAD
6. Resolve the label set against the repo before creating: any --label values, plus the review label when the local bot review step's gate said the diff warrants a metered review and that pass didn't already spend the credit. See references/labels.md.
7. Draft the body. Past a single paragraph, read references/sections.md first: audience tiers, session content, density and heading rules, evidence, optional sections, slop to cut.
8. Create the PR/MR, appending --draft when set, --base <parent> when the branch is a stack layer, and --label <name> for each label that resolved:
   • GitHub: gh pr create --title "..." --body-file tmp/pr-body-<branch>.md
   • GitLab: glab mr create --title "..." --description-file tmp/pr-body-<branch>.md
   • A screenshot or recording the body references by local path goes up with the command. GitHub: --attach ./shot.png per file on gh pr create, which rewrites the reference to the uploaded asset. Load github:attach first. GitLab: upload each file per the uploads section of gitlab:api and paste the returned markdown into the body before creating.
   • Put the branch name in the body filename so concurrent agents don't collide. Writing the file with a quoted heredoc (cat > tmp/pr-body-<branch>.md <<'EOF') in the same call as the create command works: the validation hook reads the heredoc directly.
9. Chain a GitHub stack layer into its stack once the PR exists. Load github:stack for the gh stack link forms, the detection query that picks between them, and what an exit code 9 means.
10. Enable auto-merge after the PR/MR exists, unless --no-auto or --draft is set. On a repo you own (the Remote URL above names the owner), run gh pr merge --auto. On a third-party repo, leave the merge to the maintainer. GitLab, stacked PRs, and a repo that rejects --auto take the paths in references/merge.md.
11. Suggest reviewers on corporate repos (see Reviewers). Skip this step for OSS.