Worktree CLI: `--go` vira o padrão (escape `--stay`) e `kill` volta ao main

Status: rascunho Atualizado em: 2026-08-10 Issue: #569 Priority: P2 Model: composer-2.5 model-local: deepseek-v4-flash-high Impeccable: A — N/A (CLI de dev; sem superfície de usuário de produto) Canvas UI: N/A — sem UI Appetite: ~0,5 dia eng; um outcome verificável (o terminal sempre termina no lugar certo)

Intenção

Hoje pnpm worktree next / plan só aplicam o cd com --go explícito — mas quase toda invocação quer ir para o worktree; o raro é ficar. O usuário lança worktree next --go e worktree plan --go todo dia, e o caso incomum (automação, olhar sem entrar, rodar de dentro do opencode) é o que deveria pedir o flag. Além disso, worktree kill destrói o worktree em que o shell está e deixa o terminal órfão num diretório que não existe mais — o output até imprime "Volte ao main: cd …", mas ninguém aplica esse cd, então o prompt do shell fica num cwd morto até o usuário sair manualmente.

Persona e fluxo

Persona / contexto: Francisco no terminal (bash), fluxo diário de abrir/fechar worktrees; e o agente opencode rodando o comando /worktree.
Job principal: um comando worktree que termina me deixando no lugar certo — dentro do worktree quando crio, no repo principal quando destruo.
Fluxo desejado: pnpm worktree next (sem flags) cria/reusa e provisiona o worktree e aplica cd <dir> no shell; pnpm worktree plan idem; pnpm worktree kill destrói, remove os bancos e aplica cd <main> (~/Code/teqo); quem não quer entrar usa --stay.
Anti-goals de produto: não criar um sistema de flags complexo (um escape só); não mudar a lógica determinística de branch/slot/provisionamento; não alterar o que kill destrói.

Objetivo e aceite

pnpm worktree next e pnpm worktree plan sem flags aplicam o cd no shell do terminal (hoje exigem --go).
--stay suprime o cd (e a futura abertura de opencode — ver OPS26): o script imprime o caminho sem aplicar.
--go explícito continua aceito como no-op — não quebra hábito, script de automação ou a doc existente.
pnpm worktree kill termina com o shell no main repo; o cwd nunca fica num diretório destruído.
O comportamento vale nas duas superfícies que aplicam o cd: função worktree() do .agents/shell/worktree.sh (terminal) e comando /worktree do opencode (.opencode/commands/worktree.md).
O comando /worktree no TUI do opencode continua criando/reutilizando o worktree (roda o script completo, com provisionamento) — o cd é consequência, não a função dele. Com default-go, /worktree next cria + provisiona + aplica o cd na sessão; /worktree plan idem; /worktree kill destrói + aplica cd <main>.
AGENTS.md (seção "Per-worktree environments") reflete a nova semântica default-go/--stay.

Dados (intenção)

Vou apresentar dados? Não — sem superfície de dados; é ergonomia de CLI de dev.

Direção no codebase (hipótese)

Áreas prováveis: scripts/worktree.mjs (cmdNext/cmdPlan imprimem cd <dir> por default; flag --stay no parseArgs; cmdKill imprime cd <mainRoot> no mesmo formato máquina que next/plan já usam); .agents/shell/worktree.sh (aplica o cd por default, suprime com --stay, aplica também no kill); .opencode/commands/worktree.md (texto de uso das três formas).
Precedente a olhar: o formato cd <dir> já é o contrato entre o script e a função shell (sed parse na última linha); o kill já resolve mainRoot como entries[0]?.path.
Risco de acoplamento: o opencode command (/worktree) e a função shell dividem a mesma saída do script — qualquer mudança de formato quebra os dois; manter UMA linha cd … no fim, sempre.

Dependências

Nenhuma. (Base de semântica para OPS26 e OPS27.)

Fora de escopo

Abertura do opencode ao "go" — item próprio (OPS26).
O subcomando worktree new — item próprio (OPS27).
Mudanças no provisionamento (porta/bancos/env) — pré-existente, não é o alvo.

Rabbit holes de produto

"Vários escapes": --no-go, --here, --cd… um só, com nome claro.
"O script deve detectar terminal vs opencode": não — o script imprime o cd; quem aplica (shell function vs opencode command) decide o que fazer com ele. Manter o contrato de saída simples.

Questões em aberto (produto)

Nome do escape? Opções: A) --stay | B) --no-go | C) --here. Recomendação: A — curto, lê como o oposto de "go" e não parece flag de modo. (confirmado no gate — --stay)
kill deve suportar --stay (não voltar ao main)? Opções: A) não — kill sempre volta ao main | B) sim, por simetria. Recomendação: A — ficar num cwd destruído é exatamente o bug que estamos corrigindo; quem roda kill por automação não depende do cwd do terminal pai.

Referências

GitHub Issue #569
scripts/worktree.mjs:444-481 — cmdKill já imprime "Volte ao main: cd ${mainRoot}"; nada aplica
scripts/worktree.mjs:329 e 400 — if (go) console.log(\cd ${dir}`)emnext/plan`
.agents/shell/worktree.sh:36-39 — cd só quando --go presente
.opencode/commands/worktree.md — instrui o agente a aplicar o cd quando --go
AGENTS.md seção "Per-worktree environments" — documenta worktree next [--go] etc.

5.3 KiB Raw Blame History

Worktree CLI: --go vira o padrão (escape --stay) e kill volta ao main