netresearch/jujutsu-workflow-skill

Flujo de trabajo con Jujutsu

Para codificación con agentes, prefiere jj (Jujutsu) sobre git directo siempre que haya un repositorio .jj/ presente — es la capa de cambios local superior. Git sigue siendo la interfaz canónica para remotos/PR/CI/auditoría: muta con jj, verifica con Git de solo lectura.

1. Detectar y verificar primero

Ejecuta ${CLAUDE_SKILL_DIR}/scripts/detect_jj_state.sh, o verifica manualmente:

• .jj/ presente → repositorio jj: usa jj, nunca uses git de forma mutante.
• .jj/ y .git/ → colocalizado: muta con jj, lee con git, nunca toques el índice/staging de git.
• solo .git/ → repositorio Git normal: no introduzcas jj a menos que te lo pidan.

Consulta references/git-interop.md.

2. Reglas de seguridad para agentes (no negociables)

• Siempre usa --no-pager en comandos de salida; configura jj config set --user ui.paginate never.
• Siempre usa -m. Nunca ejecutes formularios de editor/TUI — jj describe, jj commit, jj squash sin banderas, jj split (interactivo), jj squash -i, jj resolve, jj diffedit — bloquean a los agentes.
• jj captura el estado del directorio de trabajo solo cuando se ejecuta un comando jj, no en cada escritura de archivo.

Consulta references/agent-safety.md.

3. Bucle de edición

jj --no-pager status
# editar archivos (se capturan en el siguiente comando jj)
jj --no-pager diff
jj describe -m "<mensaje convencional del proyecto>"
jj new -m "<siguiente unidad>"     # un cambio por unidad lógica — evita un commit grande

Divide un cambio mixto de forma no interactiva: jj split <ruta> -m "<msg>". Consulta references/command-map.md.

4. Recuperación (reversible)

jj --no-pager op log → jj undo (última operación) o jj op restore <id>. Los conflictos son de primera clase: jj status los marca; resuélvelos editando los marcadores, luego verifica. Consulta references/recovery-playbook.md.

5. Entrega a Git

jj git fetch
jj rebase -d <rama-por-defecto>
jj bookmark create <rama> -r @-
jj git push --bookmark <rama>      # los nuevos bookmarks se suben directamente

Nunca hagas push a una rama protegida o por defecto; nunca reescribas historia pública a menos que esté permitido. Abre el PR con gh/glab. Consulta references/pr-handoff.md.

6. Agentes en paralelo

Un jj workspace por agente concurrente — nunca compartas un directorio de trabajo. Consulta references/parallel-agents.md.

7. Verificar antes de "listo"

Ejecuta ${CLAUDE_SKILL_DIR}/scripts/verify_handoff.sh, o reporta jj --no-pager status, jj --no-pager log --limit 10, jj --no-pager diff --stat, git status --short --branch. Reporta los comandos exactos y su salida; nunca afirmes "listo/probado/preparado" sin ello; divulga force-pushes, recuperaciones y conflictos.

Por qué jj es mejor que git para agentes (y cuándo NO usarlo): references/why-jj-for-agents.md.