chrislacey89/execute

O que execute faz?

Execute uma unidade de trabalho completa: planeje, construa, verifique os resultados reais e faça o commit.

Posição de Invocação

Esta é uma habilidade primária do pipeline usada depois que /prd-to-issues produziu uma fatia concreta, ou quando o usuário já tem uma tarefa de implementação claramente escopada.

Use /execute quando o trabalho estiver pronto para construir, verificar e commitar.

Use HITL /execute quando a fatia ainda precisar de julgamento ativo do usuário, supervisão ou decisões de aceitação durante a implementação. Use AFK /execute apenas quando a próxima fatia já estiver durável no GitHub, desbloqueada e legível a partir de sua issue, mapa de fronteira e qualquer artefato de pesquisa vinculado (arquivo de archive ou issue de spike) ou contexto docs/solutions/.

Legível para um leitor que não possui nada disso — que é o que uma iteração AFK é. A verificação de completude de contexto da seção 4 de /prd-to-issues é a barreira por trás dessa condição: ela exige que toda fatia AFK carregue um bloco ### Context, ou declarações vazias explícitas, antes da issue ser arquivada. Uma fatia marcada como AFK sem tal bloco nunca foi verificada contra essa condição, apenas assumida como atendida. Trate isso como um motivo para executar a fatia como HITL, ou para enviá-la de volta para /prd-to-issues, em vez de uma formalidade a ser ignorada.

Veja a Etapa 0: Pré-requisitos abaixo para as portas obrigatórias de detecção automática de Ralph e marcadores TDD.

Não use para substituir /shape, /research, ou /write-a-prd quando o problema ou a forma ainda não estiver resolvida. Não use como substituto para /pre-merge quando a implementação estiver completa e pronta para revisão.

Fluxo de Trabalho

0. Pré-requisitos

Portão de isolamento de branch. Antes de qualquer trabalho de implementação, garanta que você está trabalhando em um branch limpo criado para esta tarefa específica — não um branch de feature antigo de trabalho anterior.

Isolamento já fornecido — fique parado (verifique isso primeiro, antes das regras numeradas). Alguns ambientes fornecem ao sessão uma árvore de trabalho + branch dedicada e isolada antes de /execute executar — workspaces do Conductor, GitHub Codespaces, devcontainers e hosts similares provisionam "um workspace = um branch, auto-forkado da base" com scripts de configuração já executados. Quando esse é o caso, o pipeline não é dono do provisionamento: criar uma worktree aqui aninharia uma dentro da do host, e o branch do host (nomeado para o workspace, não para a tarefa) não está "obsoleto". Leia o sinal do ambiente e ceda a worktree para quem já a possui (Norman — leia o significante do mundo em vez de carregar uma suposição na cabeça de que o pipeline sempre provisiona; Meadows — um ator por estoque, então o pipeline adere em vez de adicionar um gerenciador competidor).

Resolva o modo de provisionamento de .claude/settings.json worktree.provisioning — "host" | "pipeline" | "auto", padrão "auto" quando a chave estiver ausente (espelhando o precedente research.storage):

• host — o isolamento é de propriedade do host. Fique parado incondicionalmente.
• pipeline — o pipeline provisiona. Pule esta parada e execute a porta numerada abaixo.
• auto (padrão) — fique parado se qualquer sinal disparar:
  • uma variável de ambiente do host descreve esta árvore — o bloco abaixo imprime host_owned=yes. Este é o discriminador primário mais barato: o único mecanismo de detecção do pipeline é Bash, e essas variáveis são visíveis no shell do agente. A presença sozinha não é suficiente: CONDUCTOR_WORKSPACE_PATH é herdada por qualquer shell iniciado sob o Conductor e pode nomear um workspace de um repositório diferente, então conta apenas quando contém o toplevel atual. (Não detecte através de um diretório .conductor no cwd — o Conductor o mantém sob $CONDUCTOR_ROOT_PATH, não no workspace.)
  • a árvore de trabalho atual não é a árvore de trabalho primária do repositório — git rev-parse --show-toplevel difere do primeiro caminho em git worktree list --porcelain.

# host-signal: uma variável de ambiente do host descreve ESTA árvore, não apenas este shell?
host_owned=no
top=$(cd "$(git rev-parse --show-toplevel)" && pwd -P)
if [ -n "${CONDUCTOR_WORKSPACE_PATH:-}" ]; then
  ws=$(cd "$CONDUCTOR_WORKSPACE_PATH" 2>/dev/null && pwd -P) || ws=
  if [ -n "$ws" ]; then
    case "$top/" in "$ws"/*) host_owned=yes ;; esac
  fi
fi
if [ -n "${CODESPACES:-}" ] || [ -n "${REMOTE_CONTAINERS:-}" ]; then host_owned=yes; fi
echo "host_owned=$host_owned"

CODESPACES e REMOTE_CONTAINERS não carregam caminho para comparar e são lidos por presença; eles são escopados ao container, então um shell que os vê está dentro do container cujos repositórios eles descrevem. O mesmo bloco aparece em /closeout, /lfg, e /init-pipeline, byte-idêntico, fixado por scripts/test-host-signal-containment.sh no repositório do próprio pack.

Ao ficar parado: pule a criação de worktree e EnterWorktree, e trabalhe no lugar no branch atual. As regras numeradas abaixo já estão satisfeitas — em particular a regra 3 não se aplica (um branch provisionado pelo host não é base nem nomeado para a tarefa, mas não está obsoleto; não aninhe uma worktree e não pare). O host já semeou configurações ignoradas pelo git e dependências, então a maior parte da "Lista de verificação de configuração da worktree" é apenas informacional — verifique .env.local/dependências se um comando falhar, mas não reprovisione. Sua exceção de git hooks ainda se aplica. Hosts provisionam arquivos rastreados mais dependências; git hooks vivem em .git/hooks, que é por-worktree e não rastreado, então um workspace provisionado pelo host caracteristicamente não tem nenhum. Verifique esse item mesmo ao ficar parado. Continue para o portão de forma da issue.

Esta parada é deliberadamente assimétrica com a verificação de desmontagem de /closeout. O fluxo de entrada só precisa responder "já estou isolado?" — detecção genérica (toplevel ≠ primário) e a dica de variável de ambiente cada uma resolve isso. A pergunta de saída — "quem é dono da desmontagem?" — é mais estrita e não pode confiar apenas na heurística genérica, porque uma worktree feita pelo pipeline também satisfaz toplevel ≠ primário; /closeout depende da configuração explícita ou apenas da variável de ambiente do host.

1. Verifique o branch atual: git branch --show-current
2. Se o branch atual for o branch base (por exemplo, main, prod, master), crie um novo branch de feature para esta tarefa.
3. Se o branch atual for um branch de feature diferente (não o branch base e não um branch nomeado para esta tarefa), você está em um branch obsoleto de trabalho anterior. Não faça commit de novo trabalho aqui. Exceção: se o branch atual for um branch de fatia irmã nomeado na declaração Consumes from #N desta tarefa, você está intencionalmente prestes a bifurcar dele para uma fatia de PR empilhado — prossiga. Exceção (provisionado pelo host): se a verificação de parada acima disparou, este branch é o branch de workspace isolado do host — não está obsoleto; trabalhe no lugar.

Para criar um branch isolado, use uma destas abordagens (em ordem de preferência):

• Worktrunk (se wt estiver disponível): wt switch --create <branch-name> — cria uma nova worktree + branch a partir da base apropriada e muda para ela, fornecendo isolamento completo do sistema de arquivos. Use a habilidade /worktrunk para orientação.
• Git simples: git checkout <base> && git checkout -b <branch-name> — cria um novo branch a partir da base apropriada no diretório de trabalho atual.

A base apropriada é o branch base do próprio repositório por padrão — o que bash "$SC" base-ref --name imprimir, com SC definido como references/sidecar.sh desta habilidade. Não assuma main. Para uma fatia com uma dependência Consumes from #N não mesclada que produz símbolos que esta fatia importa, bifurque do branch dessa fatia irmã para que o PR empilhado possa mirar no PR da irmã (Hammant Trunk-Based Development Ch. 13: múltiplos PRs por história; o PR da irmã ainda deve mesclar ao branch base do repositório dentro de 2 dias).

Derive o nome do branch da tarefa: por exemplo, issue-5-landing-page, landing-page, ou o slug da issue. Não reutilize nomes de branch de trabalho anterior.

Entre na worktree como uma sessão (quando você criou uma worktree). Criar a worktree não é o mesmo que a sessão executar dentro dela — wt switch --create redefine o cwd do shell de volta para a raiz do projeto após cada comando, então sem um passo adicional a sessão permanece ancorada no checkout original e o cwd reportado mente sobre onde o trabalho está acontecendo. Depois de criar a worktree, entre nela com a ferramenta EnterWorktree para que o diretório de trabalho da sessão seja genuinamente a worktree:

• Chame EnterWorktree { path: <absolute-worktree-path> }. O caminho já deve aparecer em git worktree list para este repositório (aparecerá, porque você acabou de criá-lo). Isso muda persistentemente a sessão para a worktree.
• Mantenha a etapa de criação exatamente como acima — wt switch --create / git worktree add executa os hooks pre-start do worktrunk que semeiam .env.local e dependências. EnterWorktree apenas muda o cwd; não executa esses hooks. Crie primeiro (para semear env/deps), depois entre.
• Isso coloca o conhecimento no mundo, não na cabeça: o cwd diz a verdade sobre onde edições e commits caem (um operador assistindo pode ver), e não há prefixo cd por comando para esquecer — eliminando a classe de deslize onde um comando não prefixado escreve na árvore errada.
• A opção Git simples (git checkout -b, sem worktree) cria o branch no checkout atual — não há worktree para entrar, então pule EnterWorktree e trabalhe no lugar.

Fallback AFK / headless. Se EnterWorktree não estiver disponível (execuções headless, AFK Ralph, cron), recorra à disciplina de prefixo de cwd: o cwd do shell redefine para a raiz do projeto após cada comando Bash, então prefixe toda chamada Bash nesta sessão com cd <absolute-worktree-path> &&. Use isso apenas quando a ferramenta harness for genuinamente indisponível — é a solução alternativa antiga, mantida para ambientes sem o mecanismo nativo.

A desmontagem desta worktree é de propriedade de /closeout na cauda do pipeline — após o PR mesclar, /closeout reancora o shell ao checkout base, remove a worktree e poda o branch mesclado. /execute é o lado de entrada do ciclo de vida da worktree; /closeout é a saída. A limpeza da Etapa 6 abaixo remove apenas os marcadores .tdd-* — deliberadamente não remove a worktree.

Depois de criar a worktree, configure-a. Uma nova worktree herda arquivos rastreados, mas não os ignorados pelo git (.env.local, dependências por-worktree, caches de build). Dois caminhos:

Preferido — configure uma vez através de hooks do worktrunk (.config/wt.toml no projeto):

[pre-start]
copy = "wt step copy-ignored"
install = "pnpm install"

Os hooks pre-start são bloqueantes — a worktree não é reportada como pronta até que terminem. Use pre-start (não post-start) para ambos, porque post-start é executado em segundo plano e comandos subsequentes que precisam de .env.local ou node_modules competirão com o hook. Veja /worktrunk para a receita completa. Uma vez por projeto.

Fallback — configuração manual para git worktree add simples (sem worktrunk):

• cp <source-repo>/.env.local <worktree>/.env.local (e qualquer outra configuração ignorada pelo git que o projeto use).
• Execute o comando de instalação do projeto (pnpm install, npm ci, pip install -r requirements.txt, etc.) a partir da worktree.

Lista de verificação de configuração da worktree (FAÇA-CONFIRME — execute cada etapa, depois verifique antes de prosseguir). Aplica-se independentemente de como a worktree foi criada:

• Configurações ignoradas pelo git copiadas — .env.local (e qualquer outro .env.*, *.local, ou configuração ignorada específica do projeto) existe na worktree
• Dependências instaladas — comando de instalação (pnpm install, npm ci, etc.) executou sem erro na worktree
• Sessão está dentro da worktree — pwd reporta o caminho da worktree porque você entrou via EnterWorktree { path } (não a raiz do projeto). No fallback AFK/headless apenas, este item significa que o prefixo cd <absolute-worktree-path> && está sendo aplicado a cada chamada Bash
• Escopo de $CLAUDE_PROJECT_DIR correto — se o projeto referencia esta variável de ambiente em scripts, verifique se ela resolve para o caminho da worktree, não para o repositório primário
• Hooks git locais instalados e seu gerenciador está no PATH — ls "$(git rev-parse --git-dir)/hooks/" | grep -v '\.sample$' lista algo, e o gerenciador que o repositório declara (lefthook, husky, pre-commit, …) resolve. Hooks vivem em .git/hooks, que é por-worktree e não rastreado, então uma worktree nova não herda nenhum deles — e a falha é silenciosa na pior direção: cada commit é bem-sucedido, e cada garantia que o repositório documenta no momento do commit simplesmente não executou. Se o gerenciador estiver ausente, instale-o (lefthook install) ou registre nas notas de revisão da Etapa 6 que as portas locais estavam inativas para este branch, para que ninguém leia uma execução local verde como a porta de mesclagem
• Marcador de classificação ausente — .claude/.tdd-active, .claude/.tdd-skipped, e .claude/.lfg-active não existem na worktree (lousa limpa; a Etapa 3 cria um)
• Flags de bloqueio pós-revisão ausentes — .claude/.review-stamped e .claude/.fix-findings-active não existem. Ambos pertencem ao branch anterior da revisão: /pre-merge Fase 4 escreve o primeiro, /fix-findings escreve o segundo, e /closeout e /fix-findings respectivamente os removem no final daquele branch. Um .review-stamped vazado recusa toda escrita de implementação nesta fatia antes que ela comece; um .fix-findings-active vazado mantém o bloqueio aberto para toda a fatia, que é a direção silenciosa. Exclua qualquer um que você encontrar — você está no início de um branch que não teve nenhuma revisão, então nenhum pode estar descrevendo este

Portão de forma e bloqueador da issue. Se a tarefa for uma issue do GitHub, confirme que é uma fatia executável antes de implementá-la: não um PRD não decomposto, não bloqueada, e não já sendo fechada por um PR aberto de outra pessoa. Uma única leitura do GraphQL responde a todas as três, e o bloco decide — não julgue nenhuma delas a olho:

N=<n>
VERDICT_JQ='
def lines: split("\n")[];
[inputs][0] | if (.errors // [] | length) > 0 then "unknown" else
.data.repository.issue as $i
| if $i == null or $i.number != $n or (($i.title // "") == "")
     or ($i.bo