Skip to content

netresearch/jujutsu-workflow

v1.0.0(MIT AND CC-BY-SA-4.0)

Agent-safe version control with Jujutsu (jj): jj as the local change layer, Git as the canonical remote/PR/CI/audit interface

GitHub

Jujutsu Workflow

What this skill solves

Coding agents are unreliable Git operators: they fold unrelated edits into one commit, lose work to git reset / checkout / stash / bad rebases, leave unclear branch state, and claim "done" without showing version-control status. This skill teaches agents to use Jujutsu (jj) — a Git-compatible VCS (docs) — as the local change-management layer while keeping Git as the canonical collaboration, CI, PR, and audit interface.

  • Safer, reversible edits via the jj operation log and undo instead of destructive Git recovery.
  • Cleaner patches — small, reviewable changes with unrelated edits split before handoff.
  • A Git-visible PR handoff that humans and CI can inspect with ordinary Git tools.

Why jj beats pure Git for agentic coding (proven)

For speculative, iterative, multi-step agent work, jj is superior to pure Git — and this skill does not just assert it, it proves it with a runnable eval suite (tests/superiority_evals.sh, also run in CI) demonstrating four concrete wins:

  • Reversible discards — jj op restore recovers abandoned work; git's discarded uncommitted edits are unrecoverable.
  • Conflicts don't block — a conflicting jj rebase completes and records the conflict (and jj undo reverses it); git rebase halts mid-operation.
  • Non-interactive history surgery — jj split <path> -m carves a commit in two without an editor; git needs interactive rebase -i.
  • Whole-repo time travel — jj op restore rewinds many operations (commits + bookmarks) in one command; git has no single-command equivalent.

This skill claims the advantage here, proves it in the evals, and enforces it in SKILL.md (jj-first whenever a .jj/ repo is present). The mechanism-grounded decision guide — when jj helps, when it doesn't — is in why-jj-for-agents.md.

Use when

  • A coding agent works in a repository where jj is installed or allowed.
  • You use jj / Jujutsu, patch stacks, or speculative iterative edits.
  • You need to recover agent edits with jj op log / jj undo / jj op restore.
  • You split agent-generated changes, hand off a PR from jj, or update a PR after review comments.
  • You want to replace fragile git reset / checkout / stash / rebase recovery with reversible jj operations.

Expected outputs

  • A local change described or committed with jj, with unrelated edits split.
  • A Git-visible branch/bookmark pushed for PR creation, never targeting a protected branch.
  • A final verification block reporting both jj and Git state plus any tests or lints that were run.

Context requirements

  • A Git-backed repository (colocated jj/Git preferred), with jj installed locally.
  • Project governance is respected: branch protection, CODEOWNERS, commit conventions, signed commits, CI gates.
  • External access: none beyond the Git remote (GitHub/GitLab) the project already uses.

Example prompts

"Use jj to make this change and prepare a clean PR branch without touching main."
"I made a mess with jj — undo my last operation and show me how to recover."
"Split these mixed edits into separate jj commits before we open the PR."

Related skills

Installation

Marketplace (recommended)

Add the Netresearch marketplace once, then browse and install skills:

/plugin marketplace add netresearch/claude-code-marketplace
/plugin install jujutsu-workflow@netresearch-claude-code-marketplace

Without a marketplace

Since Claude Code 2.1.157 a plugin directory under your personal skills directory loads on its own:

mkdir -p ~/.claude/skills
git clone https://github.com/netresearch/jujutsu-workflow-skill.git \
  ~/.claude/skills/jujutsu-workflow

It loads as jujutsu-workflow@skills-dir on the next session. Update with git -C ~/.claude/skills/jujutsu-workflow pull and start a new session; remove it by deleting the directory. This route has no claude plugin update.

npx (skills.sh)

Install with any Agent Skills-compatible agent:

npx skills add https://github.com/netresearch/jujutsu-workflow-skill --skill jujutsu-workflow

Download release

Download the latest release and extract to your agent's skills directory.

Git clone

git clone https://github.com/netresearch/jujutsu-workflow-skill.git

Composer (PHP projects)

composer require netresearch/jujutsu-workflow-skill

Requires netresearch/composer-agent-skill-plugin.

npm (Node projects)

npm install --save-dev \
  @netresearch/agent-skill-coordinator \
  github:netresearch/jujutsu-workflow-skill

Requires @netresearch/agent-skill-coordinator, which discovers the skill in node_modules and registers it in AGENTS.md via a postinstall hook.

Contributing

Contributions welcome. Open PRs for feature improvements, bug fixes, and documentation updates. The product specification lives in docs/PRD.md.

Governance and policies

This repository follows the Netresearch organisation policies:

  • Governance: ownership, roles, how decisions are made and disputes resolved, and continuity.
  • Roadmap: planned and explicitly excluded work for the coming year.
  • Handling of dependency and code analysis findings: thresholds, deadlines and the exception process for dependency (SCA) and static analysis (SAST) findings.
  • Secret management: how CI and release credentials are stored, accessed and rotated.
  • Access roster: who holds administrative access to this repository and the organisation.

The security assurance case for this skill (threat model, trust boundaries, countermeasures and limits) is in docs/SECURITY-ASSURANCE.md.

Checks that run on pull requests in this repository:

  • Every pull request: Skill Validation (lint.yml: skill structure, markdownlint, yamllint, actionlint, JSON syntax, ShellCheck, checkpoint schema), Eval Validation (eval-validate.yml) and Evals (evals.yml: tests/smoke_test.sh and tests/superiority_evals.sh against the pinned jj version).
  • Pull requests to main: security.yml with Betterleaks (secret scanning), zizmor (workflow static analysis), dependency review, Composer Audit and Opengrep SAST (both behind a preflight event-gate job); Harness Verification (harness-verify.yml) and Template Drift (check-template-drift.yml). The organisation's security policy sets when dependency review and Opengrep fail: see dependencies and static analysis (SAST).
  • Also on every pull request: PR Quality Gates (pr-quality.yml, auto-approval of collaborator pull requests), Labeler (labeler.yml), the DCO sign-off check, SonarCloud Code Analysis and the CodeRabbit review status (GitHub Apps) and, for dependency-update pull requests, auto-merge (auto-merge-deps.yml). CodeQL for actions runs through GitHub's default setup.

License

Split licensing:

  • Code (scripts, workflows, configs): MIT
  • Content (skill definitions, documentation, references): CC-BY-SA-4.0

Developed and maintained by Netresearch DTT GmbH.

Made with ❤️ for Open Source by Netresearch