jj workspaces skill

2026-04-13 17:50:04 +01:00
parent 966e40e71b
commit b42a9ecffa
4 changed files with 397 additions and 6 deletions
@@ -0,0 +1,99 @@
+---
+name: jj-issue-workspaces
+description: Create one Jujutsu workspace per issue, base them on an updated mainline bookmark like master, optionally create feature bookmarks, and open a zellij tab running pi in each workspace. Use when the user wants to fan out work across multiple issues, especially from a screenshot, Linear board, or issue list.
+---
+
+# JJ Issue Workspaces
+
+This skill sets up a parallel issue workflow with `jj workspaces`.
+
+Use it when the user wants any of the following:
+- one workspace per issue
+- multiple issues opened side by side
+- a zellij tab for each issue
+- `pi` opened in each issue workspace with a task-specific prompt
+- issue fan-out from a screenshot, Linear board, or manually listed issues
+
+## Workflow
+
+1. Confirm the target repo and verify it is a `jj` repo.
+2. If the user gave a screenshot path, use the `read` tool on the screenshot first and extract the issue keys and titles.
+3. Decide the base bookmark/revision, usually `master` or `main`.
+4. Run the helper script to:
+   - fetch the base bookmark from `origin`
+   - create sibling workspaces like `../Phoenix-spa-748`
+   - create bookmarks like `feature/spa-748`
+   - optionally open one zellij tab per workspace and launch `pi`
+5. Tell the user which workspaces and tabs were created.
+
+## Helper script
+
+Use the helper script in this skill:
+
+```bash
+./scripts/jj-workspace-fanout.sh --help
+```
+
+Run it from anywhere. Pass absolute paths when convenient.
+
+## Common usage
+
+### Create workspaces and bookmarks only
+
+```bash
+./scripts/jj-workspace-fanout.sh \
+  --repo /path/to/repo \
+  --base master \
+  --issue "SPA-748=Wrap text in credits line items" \
+  --issue "SPA-428=Implement \"Downgrade\" Mimir modal (maximalist)" \
+  --issue "SPA-754=Resize seat count picker"
+```
+
+### Create workspaces, bookmarks, zellij tabs, and launch pi
+
+```bash
+./scripts/jj-workspace-fanout.sh \
+  --repo /path/to/repo \
+  --base master \
+  --session attio \
+  --open-pi \
+  --issue "SPA-748=Wrap text in credits line items" \
+  --issue "SPA-428=Implement \"Downgrade\" Mimir modal (maximalist)" \
+  --issue "SPA-754=Resize seat count picker"
+```
+
+### Recreate existing workspaces from scratch
+
+```bash
+./scripts/jj-workspace-fanout.sh \
+  --repo /path/to/repo \
+  --base master \
+  --session attio \
+  --open-pi \
+  --reset-existing \
+  --issue "SPA-748=Wrap text in credits line items"
+```
+
+## Defaults and conventions
+
+- Workspace names use the lowercased issue key, for example `spa-748`
+- Workspace directories are created beside the repo, for example `../Phoenix-spa-748`
+- Bookmark names default to `feature/<issue-key-lowercase>`
+- Base revision defaults to `master`
+- Remote defaults to `origin`
+- If `--open-pi` is used, the script launches `pi` in each workspace with a task-specific prompt
+
+## Recommended agent behavior
+
+When using this skill:
+- Prefer `jj` over `git`
+- Check `jj workspace list` before changing anything
+- If the user says to update `master` or `main` first, let the script fetch that base revision before creating workspaces
+- If the user wants an existing set recreated, use `--reset-existing`
+- If zellij tabs already exist and the user wants a clean retry, close those tabs first or recreate the session
+
+## Notes
+
+- The script does not delete existing workspaces unless `--reset-existing` is provided.
+- `--open-pi` requires a zellij session name, either via `--session <name>` or `ZELLIJ_SESSION_NAME`.
+- If the repo uses `main` instead of `master`, pass `--base main`.