Paperclip Fork Workflow

Repository Structure

• Upstream: paperclipai/paperclip — the canonical Paperclip repo (we have PR access only)
• Fork: craigedmunds/paperclip — our fork with custom adapters and other improvements awaiting merge to uostream
• Image factory: craigedmunds/image-factory-state — builds Docker images from local/paperclip/

Branch Strategy

Branch	Purpose	Tracks
master	Clean upstream mirror	paperclipai/paperclip master
integration	Custom adapters + fixes for our deployment	master + cherry-picks

master must always match upstream. Never commit directly to it. Only fast-forward from upstream.

integration carries our additions. This is what the Docker image builds from.

Workflows

Adding a new feature/fix

1. Create feature branch from integration: git checkout -b feat/my-change integration
2. Develop and commit
3. Submit PR to upstream (paperclipai/paperclip): gh pr create --repo paperclipai/paperclip
4. Once code-review issues are resolved, submit PR to fork integration: gh pr create --base integration
5. After integration PR merges, the next image build picks it up

Syncing upstream changes

git fetch upstream
git push origin upstream/master:master          # fast-forward fork master
git checkout integration
git rebase master                                # rebase integration onto new master
git push --force-with-lease origin integration

When upstream merges our PR

The cherry-picked commits on integration become no-ops during rebase. Drop them:

git fetch upstream
git push origin upstream/master:master
git checkout integration
git rebase master    # conflicts on already-merged commits → drop them
git push --force-with-lease origin integration

Building the Docker image

1. Merge changes to integration branch
2. Trigger Build paperclip workflow in image-factory-state (workflow_dispatch)
3. Smoke tests verify custom patches survive the build
4. Image pushes to ghcr.io/craigedmunds/paperclip:{version} + :latest

Current integration branch additions

Upstream PR	Description
#2167	OpenClaw session key prefix for multi-agent routing
#2015	opencode_remote adapter for persistent HTTP server

Key files

• image-factory-state/local/paperclip/Dockerfile — build definition (uses PAPERCLIP_REPO + PAPERCLIP_BRANCH args)
• image-factory-state/local/paperclip/UPSTREAM.md — tracks what’s on integration vs upstream
• image-factory-state/local/paperclip/VERSION — image version (auto-bumped by CI after build)
• image-factory-state/tests/paperclip/test-smoke.sh — bundle assertions + health check