dotfiles/pi/files/agent/skills/jj-issue-workspaces/SKILL.md

name, description

name	description
jj-issue-workspaces	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:

./scripts/jj-workspace-fanout.sh --help

Run it from anywhere. Pass absolute paths when convenient.

Common usage

Create workspaces and bookmarks only

./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

./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

./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.