/spec-commit-push-pr

name: spec-commit-push-pr
description: Internal landing helper for public workflows that already hold explicit commit and landing authorization; commits scoped changes, pushes, and creates or updates a PR with a value-first description.
user-invocable: false
argument-hint: "[PR ref] [mode:pipeline] [archive:on|off]"

Git Commit, Push, and PR

Go from working changes to an open pull request, rewrite an existing PR description, or generate a description without touching git state.

Invocation And Authorization Boundary

This is an internal-only helper. A public workflow may delegate the full commit/push/PR path only after the current user or a visible upstream handoff has established both `commit_authorization: authorized` and `landing_authorization: authorized`. `workflow invocation does not authorize commit, push, or PR creation`; `mode:pipeline`, tool permission, a feature branch, a green test suite, or an existing PR are execution facts, not authority. Missing commit authority stops before staging/commit with `commit_authorization_missing`; missing landing authority stops before push or PR mutation with `landing_authorization_missing`.

Description-only generation remains non-mutating, but applying a description with `gh pr edit` is a landing mutation and still requires explicit landing authority. This helper never broadens the caller's run-owned file scope or absorbs unrelated dirty paths.

**Asking the user:** When this skill says "ask the user", use the platform's blocking question tool: `AskUserQuestion` in Claude Code (call `ToolSearch` with `select:AskUserQuestion` first if its schema isn't loaded) or `request_user_input` in Codex. Fall back to presenting the question in chat only when no blocking tool exists in the harness or the call errors (e.g., Codex edit modes) — not because a schema load is required. Never silently skip the question.

Mode detection

Three flavors of intent. Pick one and follow the matching path; otherwise default to the full workflow.

• **Description-only generation.** If the user asked for *just* a PR description with no commit or push intent (e.g., "write a PR description", "draft a PR description for this branch", "describe this PR", or pasted a PR URL/number alone), skip Steps 4-5 AND Step 1's decision tree (its stop gates are full-workflow only and would terminate common cases like "feature branch, all pushed, open PR -> stop"). Use the data from the Context section above instead. Then go to Step 6 to compose. If the user pasted a PR URL/number, pass it to Step 6 as the PR ref so Pre-A resolves the right commit range (otherwise Pre-A defaults to current-branch mode). Print the result back to the user; apply via `gh pr edit`/`gh pr create` only if the user asks.
• **Description update on existing PR.** If the user is asking to update, refresh, or rewrite an existing PR description (with no mention of committing or pushing), follow the Description Update workflow below. The user may also provide a focus (e.g., "update the PR description and add the benchmarking results"). Note any focus for DU-3.
• **Full workflow.** Otherwise, follow the Full workflow below.

**`mode:pipeline` modifier:** Set by orchestrated callers such as `spec-lfg`. Run the resolved mode non-interactively and suppress every blocking ask. The existing-PR rewrite question defaults to **not rewriting**; in description-update mode the preview ask is skipped and the rewrite applies directly because the update invocation is already the apply intent. Any other suppressed ask takes its conservative documented default: keep the current branch when possible, and stop/report instead of guessing when a base, PR, or branch state cannot be resolved. After an authorized full-workflow landing, return a structured `watch_handoff` containing the PR number/URL, head SHA, base ref/SHA when available, and the caller's existing authorization source and scope. This handoff lets the pipeline owner enter its bounded review/CI/head/base-currency watch; it grants no new authority. Ordinary standalone and description-only runs do not start or recommend a watch by default.

The landing disclosure for `mode:pipeline` includes bounded PR-feedback fixes and only a repo-policy-approved, non-rewriting branch-currency update. This helper never authorizes or performs merge, rebase, force-push, or history rewrite as part of that handoff. If the repository policy is absent or currency requires rewriting history, return `branch-currency-update-required` to the caller.

Context

**On platforms other than Claude Code**, skip to the "Context fallback" section below and run the command there to gather context.

**In Claude Code**, the six labeled sections below contain pre-populated data. Use them directly -- do not re-run these commands.

**Git status:** !`git status`

**Working tree diff:** !`git diff HEAD`

**Current branch:** !`git branch --show-current`

**Recent commits:** !`git log --oneline -10`

**Remote default branch:** !`git rev-parse --abbrev-ref origin/HEAD`

**Existing PR check:** !`gh pr view --json url,title,state`

Context fallback

**In Claude Code, skip this section — the data above is already available.**

Run these commands separately to gather context without interleaving unrelated output:

git status
git diff HEAD
git branch --show-current
git log --oneline -10
git rev-parse --abbrev-ref origin/HEAD 2>/dev/null || echo 'DEFAULT_BRANCH_UNRESOLVED'
gh pr view --json url,title,state 2>/dev/null || echo 'NO_OPEN_PR'

---

Description Update workflow

DU-1: Confirm intent

Ask the user: "Update the PR description for this branch?" If declined, stop.

DU-2: Find the PR

Use the current branch and existing PR check from context. If the current branch is empty (detached HEAD), report no branch and stop. If the PR check returned `state: OPEN`, note the PR `url` and proceed to DU-3. Otherwise, report no open PR and stop.

DU-3: Write and apply the updated desc