From afa4b4df5a1a487c5856c6028e5559659fd6495d Mon Sep 17 00:00:00 2001
From: Amolith <amolith@secluded.site>
Date: Sun, 1 Mar 2026 12:19:20 -0700
Subject: [PATCH] feat(pr.pico.sh): best-effort jj support

---
 README.md                                     |  9 +--
 .../collaborating-through-pr-pico-sh/SKILL.md |  1 +
 .../references/jujutsu.md                     | 63 +++++++++++++++++++
 3 files changed, 69 insertions(+), 4 deletions(-)
 create mode 100644 skills/collaborating-through-pr-pico-sh/references/jujutsu.md

diff --git a/README.md b/README.md
index a8c8cb239d4f6f4717864cd4e5a1e64709bd3c0c..3e541a3093296bdbd75d1c98417e82e7ed7c594c 100644
--- a/README.md
+++ b/README.md
@@ -259,12 +259,13 @@ Token breakdown:
 Token breakdown:
   Name:           30 tokens
   Description:   120 tokens
-  Body:         1260 tokens (42 lines)
+  Body:         1377 tokens (43 lines)
   References:
     contributing.md                            435 tokens
+    jujutsu.md                                1409 tokens
     reviewing.md                              1080 tokens
   ───────────────────────────────────────────────
-  Total:        2925 tokens
+  Total:        4451 tokens
 
 === creating-tasks-through-lunatask ===
 
@@ -455,8 +456,8 @@ SUMMARY
 
 Skills: 22
 Metadata: 3217 tokens
-Combined bodies: 58858 tokens
-Overall: 185706 tokens
+Combined bodies: 58975 tokens
+Overall: 187232 tokens
 Validation errors: 0
 
 Largest skills (by total tokens):
diff --git a/skills/collaborating-through-pr-pico-sh/SKILL.md b/skills/collaborating-through-pr-pico-sh/SKILL.md
index 23a71edd8e73bd66e54b40c27d311df9d6719102..09e809ffc427841b14e0beac252c01000c6b25d0 100644
--- a/skills/collaborating-through-pr-pico-sh/SKILL.md
+++ b/skills/collaborating-through-pr-pico-sh/SKILL.md
@@ -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
diff --git a/skills/collaborating-through-pr-pico-sh/references/jujutsu.md b/skills/collaborating-through-pr-pico-sh/references/jujutsu.md
new file mode 100644
index 0000000000000000000000000000000000000000..2f46188d85cb8a07821d3f2f58272c555592c5e6
--- /dev/null
+++ b/skills/collaborating-through-pr-pico-sh/references/jujutsu.md
@@ -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
+```