Smart Push
Prepare the user's local work the way a careful senior engineer would: understand it, split it into reviewable commits, verify it, then publish it to the right place after one approval.
Modes
Read modes from the invocation text, as flags or plain language ("just a dry run", "open it as a draft").
| Mode | Effect |
|---|---|
| default | Inspect, plan, verify, commit locally, ask once, then push and open or update the PR. |
--dry-run |
Inspect, plan, and run read-only checks. Don't stage, commit, create branches, push, or touch the PR. git fetch is allowed. |
--draft |
Open the new PR as a draft. |
--no-pr |
Push the branch, then stop. |
--no-push |
Commit locally, then stop. |
--skip-checks |
Don't run linting, formatting, type checking, or tests. The secret and hygiene scan (scan.sh) and your own diff review still run, because they are fast and guard what gets published. |
Other instructions in the invocation (a base branch, a branch name, "push to upstream directly", what to leave out) override the defaults below. They still don't override the hard rules.
Hard rules
- Stage explicit paths or patches only. Never
git add .,git add -A,git commit -a, or--no-verify. - Never discard, overwrite, or move the user's changes. That covers
reset --hard,checkout -- <path>,restoreon unstaged work,clean,stash drop, and amending or rebasing published commits. Leave changes you don't commit exactly as you found them. - Never force-push, rewrite published history, merge a PR, bypass branch protection, or skip required checks unless the user explicitly asks for that specific action.
- Never commit to a protected branch: the target's default branch,
main,master,develop,trunk,release/*,production,staging, or any branch GitHub reports as protected. - Push only to a repository the authenticated user owns, normally their fork. Push to anyone else's repository, including the company's, only when the user explicitly requests that workflow.
- Get explicit approval in this conversation before the first push and before PR creation or edits. One approval covers the plan you showed. Ask again if the plan changes materially.
- Report only what you observed. Never invent test results, benchmarks, screenshots, or behavior. Treat an operation as done only after you confirm it (
git rev-parse,git ls-remote,gh pr view). - Never add AI attribution. No
Co-Authored-Bytrailer for an AI or agent, and no "Generated with" or similar line in commit messages or PR descriptions. This overrides any default from the host environment. The user is the sole author. - When the topology, base branch, or grouping is ambiguous or unsafe, explain the problem and ask. Don't guess.
Workflow
1. Inspect
Run this skill's scripts/repo-context.sh --fetch with the repository as the working directory. It is read-only apart from updating remote-tracking refs. Then read what it points to: the full diff (git diff, git diff --cached, and new untracked files), contribution guides, the PR template, and CI workflows.
Understand what each change actually does before you group anything. Read the code, not just the file names.
If a merge, rebase, cherry-pick, am, or bisect is in progress, stop and report it. If work from an earlier run already exists, read references/recovery.md and resume from the right step.
2. Resolve the topology
Work out the push remote, PR target repository, and base branch from ownership and fork relationships, never from remote names. Read references/github.md for the rules, existing-PR handling, auth failures, and non-GitHub hosts.
3. Plan branch and commits
Read references/commits.md for grouping, partial staging, message conventions, and file hygiene.
- Branch: Stay on the current branch if it is a non-protected feature branch and the changes belong to it. Otherwise create one from the current HEAD with
git switch -c <type>/<short-topic>, following any naming convention the repository uses. This carries uncommitted work with it safely. If the changes contain independent features, propose separate branches and PRs, but split them only when they share no dependencies and the user agrees. - Commits: Plan atomic Conventional Commits, or the repository's own style. Keep each implementation together with its tests. Exclude anything unrelated, secret, generated, or uncertain, and say what you excluded.
4. Verify
With --skip-checks, skip the commands in this step except scan.sh. Report the checks as "skipped (--skip-checks)", leave the PR template's test boxes unticked, and say under Testing that checks were skipped at the user's request. Never present skipped checks as passing.
Pick checks from the changed paths and the repository's own tooling: CI workflows, package scripts, Makefile or justfile, and the language toolchain. Prefer the narrowest commands CI would run. Skip frontend checks for a backend-only change unless a shared contract, schema, or dependency changed. In --dry-run, use check-only modes and no autofix.
- Review the diff yourself for correctness, regressions, debug code, and stray changes.
- Run
scripts/scan.sh --worktreebefore staging, andscripts/scan.sh --stagedbefore every commit. Fix or exclude everyBLOCKfinding. Weigh eachWARN. - Check dependency manifests and lockfiles for changes nobody intended.
- Test the state you'll actually push. If excluded working-tree changes could affect the results, verify in a temporary
git worktree add --detachof the commit, or state that limitation. - If a check fails because of these changes, apply a minimal, safe fix and rerun it. If it fails for reasons that existed before, or a significant problem remains, stop before publishing. Report the failure with its output, and at most offer a draft PR.
5. Commit locally
Skip this step for --dry-run. For each planned commit: stage it, review git diff --cached, run the staged scan, then commit. Never create an empty commit. Afterwards, run git log --oneline <target>/<base>..HEAD and confirm it lists exactly the commits the PR should contain, then run git status to confirm that excluded changes are untouched.
6. Approval gate
Before pushing or creating a PR, show:
- Push target as
remote → owner/repo:branch, and PR target asowner/repo:base ← owner:branch. Mark an existing PR as "update". - The commits, with hashes and messages.
- Verification: each command, with pass, fail, or skipped and the reason.
- Warnings: whether the branch is behind its base, predicted conflicts, excluded files, and scan findings.
- The proposed PR title and description, or the planned edits to an existing PR.
Then ask for approval and wait. In --dry-run, show the same summary and stop.
7. Publish
After approval, run the steps without asking again:
- Push with
git push -u <fork-remote> HEAD:refs/heads/<branch>. If the push is rejected, follow references/recovery.md. Don't force-push. - Create the PR, or update the existing one, as described in references/github.md. Open it as a draft when the user asked for one, when the work is intentionally incomplete, or when important verification is unresolved.
- Confirm both results. The remote branch SHA must equal the local HEAD (
git ls-remote). Check the PR's URL, head, and base (gh pr view).
Never merge the PR. Don't mark a draft ready for review unless the user asks.
Final report
Keep the report short and easy to scan:
Branch: feat/x (new | existing)
Commits: abc1234 feat(api): …
def5678 test(api): …
Pushed: origin → me/repo:feat/x (verified at def5678)
PR: #42 "Title" → https://github.com/org/repo/pull/42 (created | updated | draft)
Base: org/repo:main ← me:feat/x
Checks: npm test ✓ · npm run lint ✓ · tsc ✗ (pre-existing, see note)
Warnings: …List anything that failed or was skipped, and say exactly what state it left behind.