home-jj-agent-spawn

name	home-jj-agent-spawn
description	Spawn a parallel coding-agent session in its own jj workspace. Uses `jj_agent` if the nwiizo/jujutsu.fish plugin is installed, otherwise falls back to raw `jj workspace add`. Use when starting a second (or Nth) agent on a different task without disturbing the current working copy. Teach the user the workspace/base-revision model and show the exact jj commands executed. Invoke manually; creates a workspace directory on disk.
disable-model-invocation	true

jj Agent Spawn

Create a new jj workspace (the equivalent of git worktree add) and open it ready for an agent to start work.

The value of this workflow is isolation plus reversibility: each agent gets its own @, while all operations still land in the shared jj operation log.

Mental model to teach

Explain these points briefly when invoking the workflow:

• A jj workspace is a separate working directory with its own working-copy commit (@). It is similar to git worktree, but it does not require creating or checking out a branch.
• Revisions and the operation log belong to the repository, not to one workspace. Isolation prevents file-level working-copy interference; it does not make repository operations private.
• The -r argument chooses the new workspace's starting revision. Use trunk() for an independent task and @ only when the new work must include the current in-flight change.
• A workspace name such as fix-auth can be addressed as fix-auth@ in revsets. Use that form when comparing or integrating work from another workspace.

When to use

• User wants to run two or more agents on different tasks in parallel.
• User wants to try an alternative approach without contaminating the main working copy.
• User wants the agent's output isolated in its own @ for later review.

Prerequisites

• .jj/ exists in the repo root.
• $TMUX is set if --tmux mode is desired.
• $EDITOR is set (or an explicit editor is provided).

Rules

• Pick the base revision deliberately. Use trunk() for an independent task; use @ only when the spawned agent should build on the current change.
• Do not spawn from a messy current @ by accident. If the current workspace contains unrelated edits, finish them with the commit cycle, split them, or choose trunk() as the base.
• Each workspace has an independent @, but the operation log is shared across the repo. A rebase, squash, abandon, or undo in one workspace is visible from the others.
• In colocated repositories, use jj for mutating operations inside spawned workspaces. Read-only Git inspection is fine; git commit, git rebase, and branch-moving Git tools make jj workspace state harder to reason about.
• Before push/PR closeout, verify whether the finished change is @ or @-. If the agent ran the commit cycle and opened a fresh child, the preserved change is usually @-.
• Forgetting a workspace and deleting a directory are not the same as undoing its changes. Use jj op log, jj undo, or jj op restore when you need to reverse repository state.

Steps

1. Pick a workspace name. Short, descriptive, kebab-case:

   • Good: fix-auth, review-pr-42, try-approach-b.
   • Bad: agent1, tmp, wip.

2. Pick the base revision:

   • Use trunk() for a clean, independent task.
   • Use @ only if the new agent should build on the current workspace's change.
   • Use a specific change ID when the task should branch from a known in-flight change.

3. Spawn. Prefer the plugin wrapper if available:

   # Preferred: with nwiizo/jujutsu.fish installed
   jj_agent <name> -r 'trunk()'
   jj_agent <name> --tmux           # opens a new tmux window
   jj_agent <name> -e 'claude'      # override editor
   
   # Fallback: plain jj
   jj workspace add --name <name> -r 'trunk()' ../<name>
   cd ../<name>
   $EDITOR .
   

4. Confirm the workspace registered:

   jj workspace list          # or `jj_agent_list` if the plugin is installed
   jj st
   

   The new workspace should appear with an empty @.

Lifecycle follow-ups

Plugin-available shortcuts (otherwise run the underlying jj commands):

• Compare two agents' output: jj_agent_diff <A> <B> (or jj diff --from <A>@ --to <B>@).
• Close out a workspace: inspect jj st and jj log -r '@-::@', push the intended change (@ or @- depending on whether a commit cycle was run), then jj_agent_done <name> --push-pr --forget or summarize + push + jj workspace forget <name>.
• Cleanup of empty abandoned workspaces: jj_agent_prune --dry-run then jj_agent_prune.

User-facing handoff

After spawning, report:

• The exact wrapper or raw jj commands executed. Do not replace them with a generic summary.
• The workspace name, filesystem path, and chosen base revision.
• What @ points to in the new workspace and whether it is empty.
• The next useful inspection commands: jj workspace list, jj st, and jj log -r '@-::@'.

If a wrapper such as jj_agent was used, also show the equivalent raw command when it materially helps the user learn the underlying jj operation:

jj workspace add --name <name> -r '<base>' ../<name>

Notes for the invoking agent

• The spawned session is an independent jj workspace. Operations there record into the shared op log, so the main agent can see what the spawned agent did via jj op log from any workspace.
• Do not invoke this skill programmatically just to create a workspace — the skill exists so the user explicitly chooses the name, base, and mode.
• If multiple agents touch related code, compare their resulting changes before pushing. Isolation prevents working-copy contamination; it does not resolve semantic conflicts for you.