# 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 -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/)**