@@ -48,3 +48,4 @@ You will often be _either_ reviewing or sending patches, and the user will have
- For sending patches, opening a PR, contributing upstream, or similar requests when the project uses pr.pico.sh, see [contributing.md](references/contributing.md)
- For reviewing patches/PRs, accepting a contributor's PR, or similar, see [reviewing.md](references/reviewing.md)
+- If the project uses **jj (Jujutsu)** instead of git, read [jujutsu.md](references/jujutsu.md) first — colocation is required and must be verified before generating or applying patches
@@ -0,0 +1,63 @@
+jj has no native support for the patch workflows (`format-patch` / `am`) that pr.pico.sh relies on. Its flow only works reliably in **colocated** jj repos (where `.git/` exists alongside `.jj/` at the workspace root).
+
+## Ensure colocation
+
+Run these checks from the jj workspace root (`jj root`) before doing anything else.
+
+```console
+# Check whether you're in the root.
+pwd && jj root
+
+# If not, prefix commands with
+cd $(jj root) && ...
+
+jj git colocation status
+
+# If the repo is not colocated, enable it
+jj git colocation enable
+```
+
+**STOP** if `jj git colocation enable` fails or is unavailable (jj < 0.28). The `git format-patch` / `git am` workflow will not work reliably without colocation. Ask the user how they would like to proceed.
+
+## Contributing
+
+Once colocated, the workflow mirrors the git-based contributing flow. Use jj for all VCS work except generating and applying patches.
+
+```console
+# Make changes with jj as usual (describe, new, split, squash, etc.)
+# When ready, ensure jj's state is exported to git (automatic in colocated repos)
+
+# Create a new patch request
+git format-patch origin/main --stdout | ssh pr.pico.sh pr create {repo}
+
+# Apply reviewer feedback
+ssh pr.pico.sh pr print {id} | git am -3
+
+# Submit a revision to an existing PR
+git format-patch origin/main --stdout | ssh pr.pico.sh pr add {id}
+
+# Submit a revision with a comment
+git format-patch origin/main --stdout | ssh pr.pico.sh pr add --comment "addressed feedback" {id}
+```
+
+After running `git am -3`, jj will automatically detect the new commits on its _next_ snapshot (meaning a subsequent `jj` command is required). You can run `jj log` to confirm they appear.
+
+## Reviewing
+
+```console
+# Apply patches from a PR (and update the jj snapshot)
+ssh pr.pico.sh pr print {id} | git am -3 && jj log
+
+# Submit a review (comments/changes as commits)
+git format-patch origin/main --stdout | ssh pr.pico.sh pr add --review {id}
+
+# Accept a PR
+ssh pr.pico.sh pr accept {id}
+
+# Submit final patchset and accept in one step
+git format-patch origin/main --stdout | ssh pr.pico.sh pr add --accept {id}
+
+# Prep and push to upstream
+jj rebase -d main # or the appropriate trunk bookmark
+jj git push
+```