Luigit
repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by admin

pi/agent/skillz/jj-workflow/SKILL.md

Raw
Rendered preview

name: jj-workflow path: .jj description: "Use before implementation in a Jujutsu repository and for local change organization, commits, revision/bookmark reviews, pull/sync/rebase, bookmark integration, or authorized pushes."

Jujutsu workflow

Read every section the request touches; each section defines its own authority. Routing grants no authority; local organization never authorizes publication or rewriting shared history. In colocated repositories, follow the user/project's VCS choice; ask if ambiguous before mutating.

Model

  • @ is a commit, not uncommitted Git state; most jj commands snapshot edits and automatically track eligible new files.
  • Change IDs survive rewrites; commit IDs pin exact content and metadata.
  • No active/current bookmark exists; bookmarks follow rewrites, not new child commits.
  • Revsets are not Git revision syntax: @- selects parents; files(...) selects revisions touching paths.
  • Conflicts are recorded state, not a suspended operation; no Git-style --continue.
  • Check installed jj help <command> before unfamiliar flags or revsets.
  • Ordinary jj git push can rewrite remote history; command spelling is not the safety boundary, forward-only checks are.

Shared rules

  • Preserve pre-existing and unrelated work; ask before rewriting it or published/shared changes.
  • Inspect affected descendants and bookmarks before rewriting; indirect rewrites have the same boundary.
  • Mutable does not mean unpublished; never bypass immutability protections.
  • Resolve remotes from the target's tracked remote or the sole configured remote; ask when ambiguous.
  • Prefer an explicit target; otherwise inspect trunk() and remote bookmarks; confirm a real target, not a fallback root().
  • Run repository-required gates plus requested or obvious fast checks; stop on conflicts or failed required checks.

Local changes

Authorized implementation includes routine new, describe, and scoped split/squash of unpublished changes created for the task, unless VCS mutations were restricted. Do not move integration bookmarks or push under local-work authority. Coordinate workspace ownership before parallel mutation; separate changes do not isolate concurrent filesystem edits.

Before work:

  1. Prevent secret/generated-file tracking before snapshotting commands, not merely before finalization.
  2. Inspect jj status, the relevant graph, and complete existing diffs; identify task scope, starting revision, and unrelated work.
  3. Reuse a suitable empty @; otherwise create a change at the intended parent before distinct work. Leave unrelated @ intact: create the task change at an independent base without describing or reorganizing it. A child separates diffs but still depends on its parent; ask when a safe base or workspace transition is unclear. Describe task intent early with -m.

During work and handoff:

  • Create boundaries for distinct purposes, useful checkpoints, and experiments, not every edit.
  • Review the whole task stack, not only @; an empty @ above completed changes is normal.
  • Keep coherent changes separate; squash fixups into their owning change; split mixed concerns when selection is unambiguous.
  • Resolve task-local conflicts when the intended result is clear; ask rather than guess or discard; inspect the whole stack for conflicts before claiming completion.
  • After cleanup, inspect per-change diffs, descriptions, and affected bookmarks; verify intended final content is preserved.
  • Checkpoints never imply passing verification; report failed and unrun checks.
  • Finalize descriptions to match content; jj commit -m is describe plus new; avoid redundant empty changes.
  • Report change IDs, commit IDs, subjects, checks, and remaining workspace state; do not push.

Noninteractive commands:

  • Never open an editor or interactive selector.
  • Pass -m to new, describe, commit, and squash (resulting description).
  • jj split: select content noninteractively and pass -m; -m alone does not suppress the diff editor; describe the remainder explicitly.
  • If a command would still prompt, stop and report.

Descriptions: short concrete subject per repository conventions; preserve work-item IDs; body explains rationale, not a tool diary; preserve rationale when combining; never label unfinished work complete; no AI attribution or trailers.

Review

No source edits, history rewrites, bookmark movement, pushes, or published feedback. Fetch explicitly requested remote revisions; tests may use an isolated workspace.

  1. Resolve base and head; ask when ambiguous.
  2. Record caller workspace state and resolved change IDs; pin commit IDs after any fetch.
  3. Inspect the exact base-to-head diff and relevant source, callers, tests, docs, and config.
  4. Run requested checks at the pinned head in an isolated workspace.
  5. Report pinned revisions, comparison, workspace location, checks, and limitations.

Sync

Resolve the stack and target independently of bookmarks; local sync needs no bookmark. For publication, resolve the exact local bookmark, reviewed publication tip (may differ from @), and remote.

  1. Record starting revisions, stack, target, remote, and any publication bookmark.
  2. Fetch; inspect the resulting graph and bookmark conflicts.
  3. Inspect every revision and descendant the rebase would rewrite; ask before rewriting unrelated or published changes.
  4. Rebase the scoped stack onto the fetched target; on conflicts, stop and report affected changes and choices.
  5. Run checks.
  6. Without publication authorization, stop after local sync.
  7. Before publication, verify the fetched remote tip and existing local bookmark tip are ancestors of the publication tip.
  8. Move only the authorized bookmark to that tip; push only that bookmark. On rejection, fetch and inspect before deciding whether the operation remains safe.
  9. Report change/commit IDs, target, bookmark/remote, checks, and publication result or blocker.

Advance an integration bookmark

Advance and publish a target bookmark to a reviewed source revision without a merge commit.

  1. Resolve the source revision independently of bookmarks; do not assume @.
  2. Resolve the explicit target bookmark and remote; confirm its identity rather than inferring a name from a revision.
  3. Require explicit authorization to advance and publish; fetch its remote.
  4. Verify the fetched and local target are ancestors of the source; otherwise require sync; never permit a backwards move. If both already point to the source, nothing moves.
  5. Inspect the published range for conflicts; run checks.
  6. Move only the target bookmark; push only it. On rejection, fetch and repeat ancestry and local-history checks before any retry.
  7. Report source IDs, bookmark/remote, old/new target commits, checks, and push result. Never abandon changes or delete bookmarks automatically.

Sources: tutorial, working copy, bookmarks, GitHub workflows, operation log.

---
name: jj-workflow
path: .jj
description: "Use before implementation in a Jujutsu repository and for local change organization, commits, revision/bookmark reviews, pull/sync/rebase, bookmark integration, or authorized pushes."
---

# Jujutsu workflow

Read every section the request touches; each section defines its own authority.
Routing grants no authority; local organization never authorizes publication or rewriting shared history.
In colocated repositories, follow the user/project's VCS choice; ask if ambiguous before mutating.

## Model

- `@` is a commit, not uncommitted Git state; most jj commands snapshot edits and automatically track eligible new files.
- Change IDs survive rewrites; commit IDs pin exact content and metadata.
- No active/current bookmark exists; bookmarks follow rewrites, not new child commits.
- Revsets are not Git revision syntax: `@-` selects parents; `files(...)` selects revisions touching paths.
- Conflicts are recorded state, not a suspended operation; no Git-style `--continue`.
- Check installed `jj help <command>` before unfamiliar flags or revsets.
- Ordinary `jj git push` can rewrite remote history; command spelling is not the safety boundary, forward-only checks are.

## Shared rules

- Preserve pre-existing and unrelated work; ask before rewriting it or published/shared changes.
- Inspect affected descendants and bookmarks before rewriting; indirect rewrites have the same boundary.
- Mutable does not mean unpublished; never bypass immutability protections.
- Resolve remotes from the target's tracked remote or the sole configured remote; ask when ambiguous.
- Prefer an explicit target; otherwise inspect `trunk()` and remote bookmarks; confirm a real target, not a fallback `root()`.
- Run repository-required gates plus requested or obvious fast checks; stop on conflicts or failed required checks.

## Local changes

Authorized implementation includes routine `new`, `describe`, and scoped split/squash of unpublished changes created for the task, unless VCS mutations were restricted.
Do not move integration bookmarks or push under local-work authority.
Coordinate workspace ownership before parallel mutation; separate changes do not isolate concurrent filesystem edits.

Before work:

1. Prevent secret/generated-file tracking before snapshotting commands, not merely before finalization.
2. Inspect `jj status`, the relevant graph, and complete existing diffs; identify task scope, starting revision, and unrelated work.
3. Reuse a suitable empty `@`; otherwise create a change at the intended parent before distinct work.
   Leave unrelated `@` intact: create the task change at an independent base without describing or reorganizing it.
   A child separates diffs but still depends on its parent; ask when a safe base or workspace transition is unclear.
   Describe task intent early with `-m`.

During work and handoff:

- Create boundaries for distinct purposes, useful checkpoints, and experiments, not every edit.
- Review the whole task stack, not only `@`; an empty `@` above completed changes is normal.
- Keep coherent changes separate; squash fixups into their owning change; split mixed concerns when selection is unambiguous.
- Resolve task-local conflicts when the intended result is clear; ask rather than guess or discard; inspect the whole stack for conflicts before claiming completion.
- After cleanup, inspect per-change diffs, descriptions, and affected bookmarks; verify intended final content is preserved.
- Checkpoints never imply passing verification; report failed and unrun checks.
- Finalize descriptions to match content; `jj commit -m` is describe plus new; avoid redundant empty changes.
- Report change IDs, commit IDs, subjects, checks, and remaining workspace state; do not push.

Noninteractive commands:

- Never open an editor or interactive selector.
- Pass `-m` to `new`, `describe`, `commit`, and `squash` (resulting description).
- `jj split`: select content noninteractively and pass `-m`; `-m` alone does not suppress the diff editor; describe the remainder explicitly.
- If a command would still prompt, stop and report.

Descriptions: short concrete subject per repository conventions; preserve work-item IDs; body explains rationale, not a tool diary; preserve rationale when combining; never label unfinished work complete; no AI attribution or trailers.

## Review

No source edits, history rewrites, bookmark movement, pushes, or published feedback.
Fetch explicitly requested remote revisions; tests may use an isolated workspace.

1. Resolve base and head; ask when ambiguous.
2. Record caller workspace state and resolved change IDs; pin commit IDs after any fetch.
3. Inspect the exact base-to-head diff and relevant source, callers, tests, docs, and config.
4. Run requested checks at the pinned head in an isolated workspace.
5. Report pinned revisions, comparison, workspace location, checks, and limitations.

## Sync

Resolve the stack and target independently of bookmarks; local sync needs no bookmark.
For publication, resolve the exact local bookmark, reviewed publication tip (may differ from `@`), and remote.

1. Record starting revisions, stack, target, remote, and any publication bookmark.
2. Fetch; inspect the resulting graph and bookmark conflicts.
3. Inspect every revision and descendant the rebase would rewrite; ask before rewriting unrelated or published changes.
4. Rebase the scoped stack onto the fetched target; on conflicts, stop and report affected changes and choices.
5. Run checks.
6. Without publication authorization, stop after local sync.
7. Before publication, verify the fetched remote tip and existing local bookmark tip are ancestors of the publication tip.
8. Move only the authorized bookmark to that tip; push only that bookmark.
   On rejection, fetch and inspect before deciding whether the operation remains safe.
9. Report change/commit IDs, target, bookmark/remote, checks, and publication result or blocker.

## Advance an integration bookmark

Advance and publish a target bookmark to a reviewed source revision without a merge commit.

1. Resolve the source revision independently of bookmarks; do not assume `@`.
2. Resolve the explicit target bookmark and remote; confirm its identity rather than inferring a name from a revision.
3. Require explicit authorization to advance and publish; fetch its remote.
4. Verify the fetched and local target are ancestors of the source; otherwise require sync; never permit a backwards move.
   If both already point to the source, nothing moves.
5. Inspect the published range for conflicts; run checks.
6. Move only the target bookmark; push only it.
   On rejection, fetch and repeat ancestry and local-history checks before any retry.
7. Report source IDs, bookmark/remote, old/new target commits, checks, and push result.
   Never abandon changes or delete bookmarks automatically.

Sources: [tutorial](https://docs.jj-vcs.dev/latest/tutorial/), [working copy](https://docs.jj-vcs.dev/latest/working-copy/), [bookmarks](https://docs.jj-vcs.dev/latest/bookmarks/), [GitHub workflows](https://docs.jj-vcs.dev/latest/github/), [operation log](https://docs.jj-vcs.dev/latest/operation-log/).