diff --git a/skills/paperclip-dev/SKILL.md b/skills/paperclip-dev/SKILL.md index 43f1ebbc..d392d327 100644 --- a/skills/paperclip-dev/SKILL.md +++ b/skills/paperclip-dev/SKILL.md @@ -94,6 +94,49 @@ npx paperclipai worktree:merge-history --from paperclip-my-feature --to current npx paperclipai worktree:cleanup my-feature ``` +## Forks — Prefer Pushing to a User Fork + +If the user has a personal fork of `paperclipai/paperclip` configured as a git remote, push your feature branches to **that fork** instead of creating branches on the main repo. This keeps the upstream branch list clean and matches the standard open-source contribution flow. + +### Detect a fork remote + +Before pushing or creating a PR, list remotes and check for one that points at a non-`paperclipai` GitHub fork: + +```bash +git remote -v +``` + +Treat any remote whose URL points to `github.com:/paperclip` (or `github.com//paperclip.git`) as the user's fork. Common names are `fork`, ``, or `myfork`. The remote named `origin` or `upstream` that points at `paperclipai/paperclip` is the canonical upstream — do not push feature branches there if a fork exists. + +### Pushing to the fork + +```bash +# Push the current branch to the user's fork and set upstream +git push -u HEAD +``` + +Then create the PR from the fork branch: + +```bash +gh pr create --repo paperclipai/paperclip --head : ... +``` + +`gh pr create` usually figures out the head ref automatically when run from a branch tracking the fork; the explicit `--head :` form is the reliable fallback when it does not. + +### When no fork exists + +If `git remote -v` shows only `paperclipai/paperclip` remotes (no user fork), fall back to pushing branches to `origin` as before. Do NOT create a fork on the user's behalf — ask first. + +### Keeping the fork up to date + +The canonical remote that points at `paperclipai/paperclip` may be named `origin` **or** `upstream` depending on how the user set up the repo. Detect it the same way as in the "Detect a fork remote" step, then fetch and push from/with that remote so the sync works under either convention: + +```bash +UPSTREAM_REMOTE=$(git remote -v | awk '/paperclipai\/paperclip.*\(fetch\)/{print $1; exit}') +git fetch "$UPSTREAM_REMOTE" +git push "${UPSTREAM_REMOTE}/master:master" +``` + ## Pull Requests > **MANDATORY PRE-FLIGHT:** Before creating ANY pull request, you MUST read the canonical source files listed below. Do NOT run `gh pr create` until you have read these files and verified your PR body matches every required section. @@ -221,3 +264,4 @@ lsof -nP -iTCP: -sTCP:LISTEN | CLI command fails | Do NOT work around it — report the error and block (see Hard Rules above) | | Agent tries manual postgres operations | NEVER do this — all DB ops go through the CLI (see Hard Rules above) | | Dev server dies between heartbeats | Launch in a detached `tmux` session — see "Persistent Dev Servers" above | +| Pushed feature branch to `paperclipai/paperclip` when a fork exists | Push to the user's fork remote instead — see "Forks" above |