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