pull-request

Pull Request

Pushes the current branch and creates a GitHub Pull Request via gh pr create, auto-filling any detected PR template from commit context and linked Issues.

Modes

Check first: does docs/agents/pull-requests.md exist?

• No → Init: run the interview (see INTERVIEW.md), write config, then proceed to pre-flight.
• Yes → Proceed: load config, run pre-flight.

Pre-flight checks

Run all four in parallel:

• git remote get-url origin — remote URL (fails if no remote)
• git log --oneline -1 — confirms at least one commit exists
• git status --short — uncommitted changes
• git status -sb — remote tracking state and branch name

Then, in order — abort early if any check fails:

1. No remote — if git remote get-url origin fails: abort. "No remote named origin is configured. Add one with git remote add origin <url> then re-run."

2. No commits — if git log returns empty: abort. "No commits found. Make at least one commit before opening a Pull Request."

3. Uncommitted changes — if dirty and the user has not already indicated what to do: ask. Suggest /commit if available, otherwise suggest committing manually. Do not proceed until the working tree is clean.

4. Current branch — if on the configured target branch and allow-direct-push is false: abort with guidance. Example: "You're on main. Create a feature branch first (/create-branch)."

5. Remote tracking state:

   • Branch not yet pushed → push in step 1 of the workflow.
   • Branch already pushed, no PR open → skip to PR creation.
   • Branch already pushed, PR already open → report the existing PR URL and stop.

Workflow

1. Push branch (if not yet pushed) — run git push -u origin <branch>. Never force-push.

2. Load PR template — read the template value from config:

   • none: check for newly added templates (.github/PULL_REQUEST_TEMPLATE.md, .github/PULL_REQUEST_TEMPLATE/*.md; org-level via gh api repos/<org>/.github/contents/.github/PULL_REQUEST_TEMPLATE.md). If found, ask the user whether to use one and update config. Otherwise skip to step 4b.
   • Repo-level (Level: repo): read the file at the stored Path from the working tree. If the file is missing, warn ("PR template at <path> not found — proceed without template, or fix config first?") and act on the user's choice.
   • Org-level (Level: org): fetch with gh api repos/<Repo>/contents/<Path> — decode the content field from base64. If the response is not 200, warn ("PR template fetch failed — gh api repos/<Repo>/contents/<Path> returned <status>. Proceed without template, or fix config first?") and act on the user's choice.

3. Build PR title — infer from commit subjects:

   • Single commit → use its subject line directly.
   • Multiple commits → derive a one-line summary that captures the shared intent.

4. Build PR body:

   Treat commit messages and the diff as source material for understanding what changed — not as text to copy into the PR body. Synthesize a description of the changes in your own words.

   • Template found (4a): synthesize content for each section of the template from the commit messages and diff context. Shape the language to fit the intent of each section — a "Summary" section gets a prose overview, a "Test plan" section gets a checklist of what to verify, and so on. Extract the Issue Number from the branch name (<type>/<issue>-<slug>). If the template contains a section for issue references (e.g. "Closes", "Fixes", "Related issues"), inject Closes #<n> there. Do not append it outside the template.
   • No template (4b): synthesize a short prose description of the changes. Append Closes #<n> on its own line at the end if an Issue Number is present in the branch name.

5. Validate and fix body — run validate.sh:

   • If exit 0: body is valid, continue.
   • If exit 1: read the VIOLATION: lines from stderr. Apply fixes using your own judgment, then re-run the script on the corrected body. Repeat until exit 0.

   Never present a body that has not passed validation.

6. Present and confirm — show the proposed title, body, target branch, and draft status. Allow the user to edit any field. Do not call gh pr create until the user confirms.

7. Create PR — run:

   gh pr create \
     --title "<title>" \
     --body "<body>" \
     --base <target-branch> \
     [--draft]
   

   Report the PR URL when done.

Key rules

• Never force-push.
• Never call gh pr create without explicit user confirmation of title and body. A prior approval from another skill in the same chain does not carry over.
• gh CLI is the only interface for GitHub operations. Do not use the REST API directly.
• If gh is not authenticated, pause and guide the user through gh auth login before continuing.
• allow-direct-push applies only to the configured target branch. Any other branch may be pushed freely.
• Write all generated PR body prose as unwrapped lines — do not insert hard line breaks within paragraphs or list items. Commit message bodies are hard-wrapped at 72 chars for git log; reflow them (collapse single newlines into spaces, preserve double newlines as paragraph breaks) before including them in the PR body.