<!-- SPDX-License-Identifier: CC-BY-SA-4.0 -->
<!-- SPDX-FileCopyrightText: Netresearch DTT GmbH -->
# 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`)](https://github.com/jj-vcs/jj)** — a Git-compatible VCS ([docs](https://docs.jj-vcs.dev/latest/)) — 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](tests/superiority_evals.sh), and **enforces** it in [`SKILL.md`](skills/jujutsu-workflow/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](skills/jujutsu-workflow/references/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](https://docs.jj-vcs.dev/latest/install-and-setup/) 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
- [`git-workflow-skill`](https://github.com/netresearch/git-workflow-skill) — the canonical Git/PR/merge workflow this skill defers to for the remote contract.
- [`github-project-skill`](https://github.com/netresearch/github-project-skill) — branch protection, rulesets, and PR merge gates.
## Installation
### Marketplace (recommended)
Add the [Netresearch marketplace](https://github.com/netresearch/claude-code-marketplace) once, then browse and install skills:
```bash
/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:
```bash
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](https://skills.sh))
Install with any [Agent Skills](https://agentskills.io)-compatible agent:
```bash
npx skills add https://github.com/netresearch/jujutsu-workflow-skill --skill jujutsu-workflow
```
### Download release
Download the [latest release](https://github.com/netresearch/jujutsu-workflow-skill/releases/latest) and extract to your agent's skills directory.
### Git clone
```bash
git clone https://github.com/netresearch/jujutsu-workflow-skill.git
```
### Composer (PHP projects)
```bash
composer require netresearch/jujutsu-workflow-skill
```
Requires [netresearch/composer-agent-skill-plugin](https://github.com/netresearch/composer-agent-skill-plugin).
### npm (Node projects)
```bash
npm install --save-dev \
@netresearch/agent-skill-coordinator \
github:netresearch/jujutsu-workflow-skill
```
Requires [@netresearch/agent-skill-coordinator](https://github.com/netresearch/node-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`](docs/PRD.md).
## Governance and policies
This repository follows the Netresearch organisation policies:
- [Governance](https://github.com/netresearch/.github/blob/main/GOVERNANCE.md): ownership, roles, how decisions are made and disputes resolved, and continuity.
- [Roadmap](https://github.com/netresearch/.github/blob/main/ROADMAP.md): planned and explicitly excluded work for the coming year.
- [Handling of dependency and code analysis findings](https://github.com/netresearch/.github/blob/main/SECURITY.md#handling-of-dependency-and-code-analysis-findings): thresholds, deadlines and the exception process for dependency (SCA) and static analysis (SAST) findings.
- [Secret management](https://github.com/netresearch/.github/blob/main/SECURITY.md#secret-management): how CI and release credentials are stored, accessed and rotated.
- [Access roster](https://github.com/netresearch/.github/blob/main/docs/access-roster.md): 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](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`, `tests/superiority_evals.sh` and `tests/verify_jj_version.sh` against the floor jj version and the newest jj release; also weekly).
- 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](https://github.com/netresearch/.github/blob/main/SECURITY.md#dependencies-software-composition-analysis) and [static analysis (SAST)](https://github.com/netresearch/.github/blob/main/SECURITY.md#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 as the `codeql` job of `security.yml`.
## License
Split licensing:
- **Code** (scripts, workflows, configs): [MIT](LICENSE-MIT)
- **Content** (skill definitions, documentation, references): [CC-BY-SA-4.0](LICENSE-CC-BY-SA-4.0)
---
Developed and maintained by [Netresearch DTT GmbH](https://www.netresearch.de/).
**Made with ❤️ for Open Source by [Netresearch](https://www.netresearch.de/)**