playbooks

home / skills / trevors / dot-claude / jj-workflow

jj-workflow skill

/skills/jj-workflow

This skill helps you manage jj workflows non-interactively, enforce descriptions, and streamline commits and recovery for clean, traceable version control.

npx playbooks add skill trevors/dot-claude --skill jj-workflow

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
3.7 KB
---
name: jj-workflow
description: Jujutsu (jj) version control, load skill when hook output shows vcs=jj-colocated or vcs=jj in the system-reminder.
---

# jj Workflow

## CRITICAL: Avoid Interactive Mode

**Always use `-m` flag** to prevent jj from opening an editor:

```bash
# WRONG - opens editor, blocks AI
jj new
jj describe
jj squash

# CORRECT - non-interactive
jj new -m "message"
jj describe -m "message"
jj squash -m "message"
```

**Never use these interactive commands:**

- `jj split` - inherently interactive, no non-interactive mode

## Mental Model

**No staging area.** Your working directory is always a commit. Every save is tracked.

- `@` = your current change (the working copy)
- `@-` = parent of current change
- Changes are mutable until pushed

## When to Use What

| Situation                   | Do This                                                   |
| --------------------------- | --------------------------------------------------------- |
| Starting new work           | `jj new -m "what I'm trying"`                             |
| Forgot to start with jj new | `jj describe -m "what I'm doing"` (do this immediately)   |
| Work is done, move on       | `jj new -m "next task"`                                   |
| Annotate what you did       | `jj describe -m "feat: auth"`                             |
| Broke something             | `jj op log` → `jj op restore <id>`                        |
| Undo one file               | `jj restore --from @- <path>`                             |
| Combine messy commits       | `jj squash -m "combined message"`                         |
| Try something risky         | `jj new -m "experiment"`, then `jj abandon @` if it fails |

## AI Coding Pattern

**Always have a description.** The working copy should never stay "(no description set)".

```bash
# BEFORE starting work - declare intent
jj new -m "feat: add user logout button"
# Now implement... jj tracks everything automatically

# FORGOT to start with jj new? Describe immediately
jj describe -m "feat: what I'm working on"
```

**Why this matters:**

- `jj log` shows meaningful history while working
- Easier to understand what each change does
- Simpler to curate/squash later
- Teammates can follow progress

```bash
# Checkpoint before risky changes
jj describe -m "checkpoint: auth works"
jj new -m "trying OAuth integration"

# If it breaks
jj op log              # Find good state
jj op restore <id>     # Go back

# When done, curate history
jj squash -m "feat: OAuth support"
```

## Push to GitHub

**Pushed commits are immutable.** You can't squash into or modify them. The safe pattern:

```bash
# 1. Abandon empty checkpoint commits cluttering history
jj log -r '::@'                      # Find checkpoints
jj abandon <change-ids>              # Remove empty ones

# 2. Describe your work (don't try to squash into immutable parent)
jj describe -m "feat: what you did"

# 3. Move bookmark to your commit and push
jj bookmark set master -r @
jj git push
```

**For feature branches (new):**

```bash
jj bookmark create feature-x -r @
jj git push --bookmark feature-x
# If refused, configure auto-tracking once:
jj config set --user 'remotes.origin.auto-track-bookmarks' 'glob:*'
# Then retry: jj git push --bookmark feature-x
```

**For feature branches (updating):**

```bash
jj bookmark set feature-x -r @
jj git push
```

Teammates see clean git. They don't know you used jj.

## Recovery

The oplog records every operation. Nothing is lost.

```bash
jj op log                      # See all operations
jj undo                        # Undo last operation
jj op restore <id>             # Jump to any past state
```

## Bail Out

```bash
rm -rf .jj    # Delete jj, keep git unchanged
```

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

FAQ

What if I accidentally run an interactive command?

If you open an editor or run an inherently interactive command (like jj split), abort and use non-interactive alternatives. Use jj op log and jj op restore to recover a prior state if changes were disrupted.

Can I rewrite commits I already pushed?

No. Pushed commits are immutable. Curate history before pushing by squashing and abandoning local changes. Use bookmarks to push only the desired change state.