netresearch/jujutsu-workflow-skill

Fluxo de Trabalho Jujutsu

Para codificação agentiva, prefira jj (Jujutsu) em vez de git puro sempre que um repositório .jj/ estiver presente — ele é a camada de mudanças local superior. Git permanece a interface remota/PR/CI/auditoria canônica: mude com jj, verifique com Git somente leitura.

1. Detecte e bloqueie primeiro

Execute ${CLAUDE_SKILL_DIR}/scripts/detect_jj_state.sh, ou verifique manualmente:

• .jj/ presente → repositório jj: use jj, nunca use git mutante.
• .jj/ e .git/ → colocalizado: mude com jj, leia com git, nunca toque no índice/staging do git.
• apenas .git/ → repositório Git simples: não introduza jj a menos que solicitado.

Veja references/git-interop.md.

2. Regras de segurança do agente (indelegáveis)

• Sempre use --no-pager em comandos de saída; configure jj config set --user ui.paginate never.
• Sempre use -m. Nunca execute formulários editor/TUI — comandos nus como jj describe|commit|squash, jj split (interativo), jj squash -i, jj resolve, jj diffedit — eles travam agentes.
• jj captura o estado da cópia de trabalho apenas quando um comando jj é executado, não em cada gravação de arquivo.

Veja references/agent-safety.md.

3. Ciclo de edição

jj --no-pager status
# edite arquivos (capturados no próximo comando jj)
jj --no-pager diff
jj describe -m "<mensagem convencional do projeto>"
jj new -m "<próxima unidade>"     # uma mudança por unidade lógica — evita um único commit gigante

Divida uma mudança mista de forma não interativa: jj split <caminho> -m "<msg>". Veja references/command-map.md.

4. Recuperação (reversível)

jj --no-pager op log → jj undo (última operação) ou jj op restore <id>. Conflitos são cidadãos de primeira classe: jj status os sinaliza; resolva editando marcadores, depois verifique. Veja references/recovery-playbook.md.

5. Handoff via Git

jj git fetch
jj rebase -d <branch-padrão>
j j bookmark create <branch> -r @-
jj git push --bookmark <branch>      # novos bookmarks são enviados diretamente

Nunca faça push para uma branch protegida/padrão; nunca reescreva histórico público a menos que permitido. Abra o PR com gh/glab. Veja references/pr-handoff.md.

6. Agentes paralelos

Um jj workspace por agente concorrente — nunca compartilhe a cópia de trabalho. Veja references/parallel-agents.md.

7. Verifique antes de "concluído"

Execute ${CLAUDE_SKILL_DIR}/scripts/verify_handoff.sh, ou reporte jj --no-pager status, jj --no-pager log --limit 10, jj --no-pager diff --stat, git status --short --branch. Reporte comandos e saídas exatas; nunca declare "concluído/testado/pronto" sem isso; divulgue force-pushes, recuperações, conflitos.

Por que jj é melhor que git para agentes (e quando NÃO usar): references/why-jj-for-agents.md.