name: jj Workflow description: This skill should be used when the user is working in a jj-enabled repository (has .jj directory), asks to "commit changes", "push code", "check status", "create a PR", "view history", or performs any version control operation. Teaches Claude to prefer jj over git in jj repositories while maintaining git compatibility knowledge. version: 0.1.0

jj (Jujutsu) Workflow

Overview

jj (Jujutsu) is a Git-compatible version control system with a different mental model. When working in repositories with a .jj directory, prefer jj commands over git equivalents. Repositories without .jj should continue using git normally.

Detection

Before any version control operation, check for jj:

# Check if current repo uses jj
test -d .jj && echo "jj repo" || echo "git repo"

Only use jj commands when .jj directory exists. Otherwise, use standard git.

Core Workflow

The jj Mental Model

• Working copy is always a commit - Changes are automatically tracked
• No staging area - All changes go directly into the current change
• Changes vs commits - jj uses "change" (mutable) vs "commit" (immutable snapshot)
• @ - Refers to the current working copy change

Preferred Workflow: describe + new

When the user wants to commit changes, use this workflow:

# 1. Describe the current change (like writing a commit message)
jj describe -m "Your commit message here"

# 2. Create a new empty change on top (moves @ forward)
jj new

Do NOT use jj commit - The describe + new workflow is preferred because:

• Separates message writing from change creation
• Allows iterative message refinement
• Matches the jj philosophy of mutable changes

Common Commands

Pushing and Pull Requests

To push changes for a PR:

# Push current change, creating a bookmark (branch) automatically
jj git push -c @ --allow-new

This command:

• Creates a bookmark pointing to the current change (@)
• Pushes to the remote
• --allow-new permits creating new remote branches

Do NOT manually create bookmarks unless specifically needed. Let jj git push -c @ handle it.

Fetching and Syncing

# Fetch from remote
jj git fetch

# Rebase onto latest main
jj rebase -d main

Complex Operations

For complex operations like interactive rebasing, splitting changes, or conflict resolution, consult the official jj documentation via Context7:

https://context7.com/jj-vcs/jj/llms.txt

Use the mcp__plugin_compound-engineering_context7__query-docs tool with library ID /jj-vcs/jj for specific questions.

User Configuration

If CLAUDE.md contains a jj configuration section, it includes the user's custom aliases and revset aliases. Respect these customizations when suggesting commands.

Quick Reference

Starting Work

jj status          # See what's changed
jj log             # See recent history
jj new             # Start fresh change if needed

Making Changes

# Edit files normally, jj tracks automatically
jj status          # Review changes
jj diff            # See detailed diff
jj describe -m "Add feature X"  # Describe the change
jj new             # Create new change, ready for next task

Sharing Work

jj git fetch                    # Get latest from remote
jj rebase -d main              # Rebase onto main if needed
jj git push -c @ --allow-new   # Push for PR

Viewing History

jj log                    # Condensed graph view
jj log -r @               # Show current change details
jj show                   # Show current change diff
jj show <change-id>       # Show specific change

Key Differences from Git

1. No staging - All file changes are part of current change
2. Automatic tracking - New files tracked automatically
3. Mutable history - Changes can be edited until pushed
4. Change IDs - Use change IDs (letters) or commit IDs (hex)
5. Bookmarks vs branches - jj uses "bookmarks" (lightweight pointers)
6. Operation log - jj op log shows all operations for undo

Error Handling

If a jj command fails:

1. Check jj status for conflicts or issues
2. Use jj op log to see recent operations
3. Use jj op undo to undo last operation if needed
4. Consult Context7 docs for specific error messages