jj-workflow_skill

Overview

This skill integrates Jujutsu (jj) version control guidance into the agent workflow when system hooks indicate vcs=jj or vcs=jj-colocated. It provides non-interactive command patterns, recovery techniques, and push workflows designed to keep working copies descriptive and safe. The guidance emphasizes non-interactive usage and practical steps for everyday tasks, branching, and recovery.

How this skill works

The skill inspects hook output for vcs=jj or vcs=jj-colocated and activates jj-specific recommendations and command patterns. It enforces using the -m flag to avoid interactive editors, explains the mental model (working copy = a commit), and supplies concrete commands for starting work, checkpoints, squashing, pushing, and recovery. It also provides safe push workflows so Git history remains clean.

When to use it

• Starting a new task in a jj-tracked repo
• You forgot to mark work with jj new at start of work
• You need to create a checkpoint before risky changes
• You need to squash or curate local history before pushing
• Recovering or undoing mistakes using the oplog

Best practices

• Always use -m with jj commands that accept messages (never run jj new/describe/squash without -m).
• Keep the working copy described — never leave it as “(no description set)”.
• Treat the working directory as a mutable commit; use jj new/describe to mark intent and checkpoints.
• Before pushing, abandon empty checkpoint changes and describe final work; pushed commits are immutable.
• Use oplog commands (jj op log, jj op restore, jj undo) to recover past states safely.

Example use cases

• Start work: jj new -m "feat: add user logout button" then implement changes.
• Forgot to start: jj describe -m "feat: continue login fixes" immediately to record intent.
• Checkpoint and experiment: jj describe -m "checkpoint: auth works"; jj new -m "try OAuth"; if it fails, jj abandon @.
• Curate before push: jj log -r '::@' to find checkpoints, jj abandon <ids>, jj squash -m "feat: OAuth support", jj bookmark set master -r @, jj git push.
• Create and push feature branch: jj bookmark create feature-x -r @; jj git push --bookmark feature-x (configure auto-track if needed).