Agent Skills: Jujutsu (jj)

Jujutsu (jj)

Description

Standard jj operations for day-to-day development work.

CRITICAL: Commits Are Permanent

When user says "commit": IMMEDIATELY use jj commit -m "msg"

• Committed changes are permanent and stored forever in operation log
• Uncommitted changes can be lost during rebases/restores
• Every commit is recoverable via jj op restore

Run make check periodically to catch issues early.

Configuration

• Remote: origin (github.com:mgreenly/ikigai.git)
• Primary branch: main (bookmark)

Commit Policy

Always use selective commits. Specify exactly which paths to include:

jj commit path/to/file1 path/to/dir -m "msg"

Only commit all files (jj commit -m "msg" without paths) when the user explicitly says "commit all" or "commit everything".

Never use jj restore to "clean up" files you didn't change. This destroys other agents' work. If uncommitted changes outside your scope block you, stop and ask.

NOT jj describe (only updates description without creating commit).

Prohibited Operations

This skill does NOT permit:

• Force pushing to main
• Restoring/reverting files you didn't change (destroys other agents' work)

Permitted Operations

• Commit directly to main (In this repo we're always on main and push directly to main)
• Push directly to main@origin
• Commit to feature/fix bookmarks
• Push feature/fix bookmarks to remote
• Create new bookmarks
• Create and push tags
• Fetch from remote
• Rebase commits
• Create new commits on any mutable revision

Squashing (Permission Required)

NEVER squash without explicit user permission. Only when user says "squash" or "squash commits".

Squashing workflow:

1. jj edit <revision> - Move to commit to squash
2. jj squash -m "message" - Squash into parent (MUST use -m flag in CLI)
3. Repeat for additional commits

Flag limitations:

• ✗ jj squash -r <rev> --into <dest> - INVALID (flags cannot combine)
• ✓ jj edit <rev> then jj squash -m "msg" - VALID

Recovery: jj op log then jj op restore <id> (all operations are logged)

Common Flags

| Flag | Why Use It | |------|------------| | -m "message" | Provide commit/squash message inline (required in non-interactive environments) | | -r <revision> | Specify which revision to operate on (alternative to jj edit first) | | --into <dest> | Squash into specific destination (cannot combine with -r) | | --no-graph | Show log output without tree visualization (cleaner for parsing) | | --stat | Show file change statistics in diff (lines added/removed per file) | | --bookmark <name> | Push specific bookmark to remote | | -d <dest> | Set destination for rebase operation |

Common Commands

| Task | Command | |------|---------| | Check status | jj status | | View changes | jj diff | | View log | jj log | | Commit specific files | jj commit <paths> -m "msg" | | Commit all files | jj commit -m "msg" | | Squash into parent | jj squash -m "msg" | | Edit a commit | jj edit <revision> | | Create bookmark | jj bookmark create <name> | | Update bookmark to @ | jj bookmark set <name> | | Push bookmark | jj git push --bookmark <name> | | Fetch from remote | jj git fetch | | Restore working copy | jj restore | | Create commit on revision | jj new <revision> | | Rebase | jj rebase -d <destination> | | Create tag | jj tag set <name> -r <revision> | | Push tag | git push origin <tag> | | List tags | jj tag list |

Key Concepts

• Working copy (@): Always a commit being edited (no staging area)
• Bookmarks: Equivalent to git branches (named pointers to commits)
• Immutability: ◆ = permanent, ○ = mutable, @ = mutable (lost if not committed)
• Update bookmark: Find recent bookmark in ancestry, use jj bookmark set <name>