---
name: smart-push
description: Turn local Git changes into clean atomic commits, verify them, push the branch to the user's fork, and open or update a GitHub pull request. Explicit invocation only; supports --dry-run, --draft, --no-pr, --no-push, and --skip-checks.
disable-model-invocation: true
title: smart-push
canonical_url: https://skilld.dev/gh/akdevsaha-dev/factory-skills/smart-push
last_updated: 2026-11-18T12:30:23.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [agents/openai.yaml](https://skilld.dev/api/skills-raw/akdevsaha-dev/factory-skills/smart-push/agents/openai.yaml), [references/commits.md](https://skilld.dev/api/skills-raw/akdevsaha-dev/factory-skills/smart-push/references/commits.md), [references/github.md](https://skilld.dev/api/skills-raw/akdevsaha-dev/factory-skills/smart-push/references/github.md), [references/recovery.md](https://skilld.dev/api/skills-raw/akdevsaha-dev/factory-skills/smart-push/references/recovery.md), [scripts/repo-context.sh](https://skilld.dev/api/skills-raw/akdevsaha-dev/factory-skills/smart-push/scripts/repo-context.sh), [scripts/scan.sh](https://skilld.dev/api/skills-raw/akdevsaha-dev/factory-skills/smart-push/scripts/scan.sh).
>
> If the user asked to install this Skill, run `npx skilld install akdevsaha-dev/factory-skills/smart-push`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/smart-push`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/akdevsaha-dev/factory-skills/smart-push) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/smart-push`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/smart-push --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/smart-push --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# 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>`, `restore` on 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-By` trailer 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](https://skilld.dev/api/skills-raw/akdevsaha-dev/factory-skills/smart-push/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](https://skilld.dev/api/skills-raw/akdevsaha-dev/factory-skills/smart-push/references/github.md) for the rules, existing-PR handling, auth failures, and non-GitHub hosts.

### 3. Plan branch and commits

Read [references/commits.md](https://skilld.dev/api/skills-raw/akdevsaha-dev/factory-skills/smart-push/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 --worktree` before staging, and `scripts/scan.sh --staged` before every commit. Fix or exclude every `BLOCK` finding. Weigh each `WARN`.
- 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 --detach` of 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 as `owner/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:

1. Push with `git push -u <fork-remote> HEAD:refs/heads/<branch>`. If the push is rejected, follow [references/recovery.md](https://skilld.dev/api/skills-raw/akdevsaha-dev/factory-skills/smart-push/references/recovery.md). Don't force-push.
2. Create the PR, or update the existing one, as described in [references/github.md](https://skilld.dev/api/skills-raw/akdevsaha-dev/factory-skills/smart-push/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.
3. 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.
