| name | commit-push |
| description | Commit and push changes, then create or reuse a PR with optional merge |
Commit staged/unstaged changes, push to the remote, and open or reuse a PR.
Pre-commit check
If tests are missing or the commit hook blocks due to missing tests:
- Never write tests directly in this conversation.
- Invoke the
/write-tests skill first, then resume commit-push.
If documentation is missing or the commit hook blocks due to missing documentation updates:
- Invoke the
/update-docs skill first, then resume commit-push.
Phase 1 (issue-close-stage) pre-flight
Run: "$AGENTS_CONFIG_DIR/bin/detect-non-github.sh" "Phase 1 pre-flight" || NON_GITHUB=1
When NON_GITHUB=1 (non-GitHub remote): skip the entire pre-flight block below (including check-phase1-complete.sh), then proceed with commit/push as normal — do NOT abort the skill.
When the command exits 0 (GitHub remote, or unknown/fail-open): run the pre-flight as normal.
Skip message on non-GitHub remote (emitted by the script to stdout): [GITHUB_ISSUES disabled: non-GitHub remote detected, skipping Phase 1 pre-flight]
For each issue N in the session's closes_issues list (parsed from
${WORKFLOW_PLANS_DIR:-$HOME/.workflow-plans}/<session-id>-intent.md —
the ## Issues section; canonical parser: hooks/lib/parse-closes-issues.js — do not reimplement),
run from the worktree root:
bash "$AGENTS_CONFIG_DIR/bin/github-issues/check-phase1-complete.sh" <N>
Non-zero → abort /commit-push and surface stderr (it names the missing
condition: sentinel, history entry, or both). Resolve by invoking
/issue-close-stage <N> from the linked worktree, then re-run /commit-push.
Skip this pre-flight when:
closes_issues is empty, or the session intent file is missing.- Running from the main worktree (main-worktree commit-push is only valid when
ENFORCE_WORKTREE=off, where the 2-phase split does not apply).
Procedure
Read rules/github-issues.md before CP-1 — on-demand-only, never auto-injected.
Read rules/coding.md before CP-2 — on-demand-only, never auto-injected; its Public GitHub Rules govern the commit message and PR body.
CP-1. Stage changes with git add — explicitly add each file you intend to commit.
Then run bash "$AGENTS_CONFIG_DIR/bin/check-unstaged-tracked.sh" from the worktree root.
rc=1 → list of unstaged tracked files is printed; either git add them, git stash push -u -- <file>, or pass --wip to skip this gate (git -c workflow.wip=1 commit).
rc=2/3 → surface stderr and abort. Skip this verification when WORKFLOW_OFF or WORKTREE_OFF session marker is active (parity with workflow-gate.js bypass); also set wip_mode: true in the step CP-2 worker JSON to propagate the bypass to the worker's Gate 3 staging-verification step.
CP-2. Dispatch commit/push/PR to the commit-push worker per skills/_shared/worker-dispatch.md.
Sibling pre-check (non-blocking): bash "$AGENTS_CONFIG_DIR/bin/check-sibling-uncommitted.sh" "$(git rev-parse --show-toplevel)/WORKTREE_NOTES.md" — warns when a sibling worktree in ## SiblingWorktrees has uncommitted/unpushed work.
Payload keys: commit_message, branch, closes_issues, pr_body_template, wip_mode, enforce_worktree, agents_config_dir, artifact_dir (= PLANS_DIR), worktree_path (= git rev-parse --show-toplevel), session_id.
Pass closes_issues as the hooks/lib/parse-closes-issues.js records verbatim ({number, repo?} objects) — never flatten them to bare numbers.
Resolve PLANS_DIR and ENFORCE_WORKTREE before dispatching.
Staging verification (Step CP-2) is skipped only when wip_mode: true — i.e. --wip, or a WORKFLOW_OFF / WORKTREE_OFF session marker (parity with the workflow-gate.js bypass).
On branch_mismatch: the branch payload key is not the branch checked out at worktree_path — nothing was committed. Re-derive branch from git rev-parse --abbrev-ref HEAD in that worktree and re-run; never re-dispatch with the same value.
On staging_incomplete or staging_check_failed: surface summary + artifact_path and stop.
On gate_blocked: workflow-gate refused the commit or the push (or could not be trusted — a gate crash fails closed). Surface the summary verbatim, complete the named workflow step, and re-run /commit-push. Never retry by another route.
On push_failed or conflict: surface summary + artifact_path to user and stop.
On pushed (no PR — ENFORCE_WORKTREE=off or non-GitHub remote): report the branch and skip step CP-2b.
On pr_created or pr_reused: extract PR URL from summary for steps CP-2b and CP-3.
On bootstrap_pending (issue #772 — remote has no default branch): surface guidance text "Remote has no default branch yet (new repo). Run to push the first commit as and set the default branch — this is the bootstrap path, not a normal push." Skip step CP-3 (no merge confirmation; nothing was pushed). Do NOT emit — Step WE-4b owns that sentinel. Stop.
settings.json model and effort fields are auto-updated by the system — exclude them from the commit if they appear in the diff.
CP-2a. Append PR number to session title: node "$AGENTS_CONFIG_DIR/bin/cc-session-title" add-pr "$(pwd)" "<PR_NUMBER>" where <PR_NUMBER> is extracted from pr_url by taking the last path segment (format: https://github.com/<owner>/<repo>/pull/<N> → <N>). Skip when outcome is bootstrap_pending, branch_mismatch, gate_blocked, staging_incomplete, staging_check_failed, push_failed, or conflict. Fail-open.
CP-2b. Open the PR URL: run node "$AGENTS_CONFIG_DIR/bin/open-pr-url.js" "<pr_url>" when the status is pr_created only — pr_reused did not create anything, so it must not re-open a tab (parity with the retired pr-created-open.js, which fired on gh pr create alone).
The PR URL MUST also appear in this turn's final response text — the dispatcher path has no tool-permission dialog to display it.
Fail-open: a non-zero exit or missing browser never blocks the flow.
CP-3. Merge prompt:
Check ENFORCE_WORKTREE:
bash -c 'cd "$AGENTS_CONFIG_DIR" && bash "$AGENTS_CONFIG_DIR/bin/confirm-off" ENFORCE_WORKTREE on'
(a) stdout ON or ERROR (ENFORCE_WORKTREE=on):
- Output
PR #<N> is open: [<url>](<url>).
- Run
/worktree-end.
(b) stdout OFF (ENFORCE_WORKTREE=off): Output PR #<N> is open: [<url>](<url>),
then AskUserQuestion: "PR # — merge, wait, or abort?"
- merge:
gh pr merge --squash --delete-branch, then git fetch --prune origin.
- wait / abort: display URL and stop.
If AskUserQuestion is unavailable, default to wait.
WIP mode (--wip)
When invoked with --wip (for fixup / intermediate commits between substantive work):
- Issue the commit as
git -c workflow.wip=1 commit -m "...". The -c workflow.wip=1
pair MUST appear before the commit subcommand verb — git ignores -c placed
after the subcommand, and workflow-gate.js only recognizes the pre-subcommand form.
- The gate skips ONLY
user_verification for that commit. All other gates
(run_tests, review_security, docs) still fire.
- Also skip the
review-code-codex invocation by convention in --wip mode (this is a
skill-level convention; the gate does not track it).
- Do NOT set
workflow.wip in git config globally — the signal must be scoped to the
single commit invocation to avoid leakage across commits.
- Works with
--amend: git -c workflow.wip=1 commit --amend ....
--wip mode also skips Gate 3 (Step CP-1 unstaged-tracked verification + the commit-push worker's staging-verification step) and Gate 1 (workflow-gate.js unstaged-tracked check), since workflow.wip=1 signals intentional partial staging.
See docs/architecture/claude-code/workflow.md for the signal contract.
Rules
- Follow all existing commit and push rules.
- If push fails, report the error — do not force-push.
- Merge is always user-confirmed — never auto-merge without
AskUserQuestion.
Exception: /worktree-end when AUTO_MERGE_PR=on (worktree mode only).
In worktree mode this skill defers entirely to /worktree-end (Step 7a).
- Note:
git branch -D (force-delete) and --no-verify are prohibited.
bootstrap_pending is terminal for /commit-push — defer the actual push to /worktree-end Step WE-4b. No PR is created and no user-verified sentinel is emitted in /commit-push for this status.- On fallback or step degradation (push retry, PR reuse, merge deferral): run
node "$AGENTS_CONFIG_DIR/bin/supervisor-report" --categories workflow --severity warning --detail "<describe fallback>" --reporter commit-push (session-id auto-resolves).
- Report observations via /supervisor-report (trigger conditions: rules/supervisor-reporting.md).
