From d2cbe2cb238deb685765942b93e67c9b1e835223 Mon Sep 17 00:00:00 2001 From: Devin Foley Date: Sun, 26 Apr 2026 22:19:07 -0700 Subject: [PATCH] Prefer pushing feature branches to a user fork in paperclip-dev skill (#4572) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies > - The `paperclip-dev` skill is the canonical reference agents read before doing development work on the Paperclip repo itself > - Today the skill assumes feature branches get pushed to `origin` (= `paperclipai/paperclip`), which clutters the upstream branch list when contributors actually have personal forks > - This is the standard open-source contribution pattern (push to fork, PR upstream) and the skill should reflect it > - This pull request adds a "Forks — Prefer Pushing to a User Fork" section that teaches agents to detect a fork remote, push there, and only fall back to `origin` when no fork is configured > - The benefit is cleaner upstream branch hygiene and behavior that matches typical contributor workflows without any code/runtime change ## What Changed - Added a new **Forks — Prefer Pushing to a User Fork** section to `skills/paperclip-dev/SKILL.md` covering: - How to detect a user fork via `git remote -v` (treat any non-`paperclipai` GitHub remote as the fork) - How to push to the fork (`git push -u HEAD`) - How to create the PR from the fork (`gh pr create --repo paperclipai/paperclip --head :`) - The no-fork fallback (push to `origin`, do not auto-create a fork — ask first) - Keeping the fork's `master` in sync - Added a reinforcing entry to the **Common Mistakes** table linking back to the new section ## Verification - Docs-only change to a single markdown skill file. Reviewer can confirm by reading the diff in `skills/paperclip-dev/SKILL.md`: - New `## Forks — Prefer Pushing to a User Fork` section sits between `## Worktrees` and `## Pull Requests` - New row appended to the `## Common Mistakes` table - No tests, no build, no runtime behavior affected. ## Risks - Low risk. Documentation-only edit. The instructions are advisory — they only change agent behavior on future runs that read the skill. ## Model Used - Provider: Anthropic (Claude) - Model ID: `claude-opus-4-7` (Claude Opus 4) - Capabilities: tool use (file read/edit, shell, git, gh CLI), extended reasoning - Context: invoked via Claude Code / Paperclip heartbeat for issue PAPA-139 ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have run tests locally and they pass (N/A — docs-only change; no test surface) - [x] I have added or updated tests where applicable (N/A) - [x] If this change affects the UI, I have included before/after screenshots (N/A — no UI change) - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge --- skills/paperclip-dev/SKILL.md | 44 +++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) 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 |