hwipit/plugin

Hwip Auto — Modo de Trabalho Autônomo com Limite de Tempo

Trabalhe autonomamente por um orçamento de tempo fixo: explore → planeje → implemente → verifique → confirme (commit), uma unidade de cada vez. O usuário direciona do celular através de botões do hwip_ask; quando não respondem, você prossegue com um padrão seguro declarado, em vez de travar. Toda a execução acontece em uma única resposta — encerrar seu turno encerra o modo.

Pré-condições — recuse iniciar se não forem atendidas

• Um hook id está configurado — hookId em ~/.hwip/config.json (o que o hwip install escreve), ou a variável de ambiente HWIP_HOOK_ID. O contexto SessionStart termina com Mode: two-way (notify + ask) quando um está presente; Mode: one-way significa que não há canal de direcionamento — recuse e aponte o usuário para /hwip-config.
• Não está silenciado. Se /hwip-mode reportar NOTIFICATIONS: muted, recuse: modo autônomo sem notificações é trabalho não supervisionado sem direcionamento. Sugira /hwip-mode unmute.
• Invocação explícita do usuário. Nunca acione este modo automaticamente porque uma tarefa "parece longa". O usuário opta com /hwip-auto ....

Argumentos

/hwip-auto [duração] [descrição da tarefa...]

• duração — 2h, 90m, 1h30m ou um número simples significando minutos. Padrão: 1h. Limitado entre 10m e 8h.
• tarefa — tudo após a duração. Se omitido, derive da conversa até o momento; se não houver nenhuma, proponha 2–3 tarefas candidatas na pergunta inicial (ex.: corrigir testes falhando, limpar avisos de lint, uma varredura de TODO).

Configuração

1. Registre o prazo final (um arquivo de estado sobrevive à compactação de contexto — releia-o sempre que não tiver certeza de quanto tempo resta):

   HASH=$(printf '%s' "${CLAUDE_PROJECT_DIR:-$(pwd)}" | cksum | cut -d' ' -f1)
   STATE_DIR="${XDG_STATE_HOME:-$HOME/.local/state}/hwip"
   mkdir -p "$STATE_DIR"
   MINUTES=120   # analisado do argumento de duração
   DEADLINE=$(( $(date +%s) + MINUTES * 60 ))
   printf '%s %s\n' "$DEADLINE" "$MINUTES" > "$STATE_DIR/auto-$HASH"
   date -r "$DEADLINE" 2>/dev/null || date -d "@$DEADLINE"   # macOS | Linux
   

2. Proteção de branch — nunca trabalhe diretamente em main/master/develop:

   BRANCH=$(git branch --show-current 2>/dev/null)
   case "$BRANCH" in
     main|master|develop) git checkout -b "auto/$(date +%Y%m%d)-<slug-da-tarefa>" ;;
   esac
   

3. Descubra o verificador antes de escrever qualquer código: as verificações determinísticas do projeto (comandos de teste / lint / typecheck / build do package.json, Makefile, config de CI). Elas controlam cada commit. Se o projeto não tiver nenhuma, informe isso na pergunta inicial e trate "código compila/executa" como o limite mínimo.

4. Pergunta inicial — um hwip_ask antes de tocar em qualquer coisa:

   • title: "Modo auto: (<orçamento>)"
   • body: plano de 2–3 linhas + qual verificador controla os commits + o nome do branch
   • actions: [{id:"start", label:"Iniciar", style:"primary"}, {id:"stop", label:"Cancelar"}] (se a tarefa era ambígua, substitua "Iniciar" por 2–3 botões de tarefas candidatas)
   • placeholder: "ajuste o plano ou escopo..."
   • timeout: 180, fallback: "start" (ou o candidato recomendado)

   Respostas de texto livre alteram o plano; stop cancela o modo (remova o arquivo de estado).

O Loop

Divida a tarefa em unidades: os menores blocos independentemente verificáveis e comittáveis (~15–45 min cada). Então, para cada unidade:

1. Verificação de tempo (antes de iniciar cada unidade):

   HASH=$(printf '%s' "${CLAUDE_PROJECT_DIR:-$(pwd)}" | cksum | cut -d' ' -f1)
   read -r DEADLINE MINUTES < "${XDG_STATE_HOME:-$HOME/.local/state}/hwip/auto-$HASH"
   echo "restante: $(( (DEADLINE - $(date +%s)) / 60 ))m de ${MINUTES}m"
   

   Se o tempo restante estiver abaixo do limite de encerramento — 10% do orçamento, pelo menos 5 minutos — não inicie uma nova unidade; vá para Encerramento.

2. Explore → planeje a unidade (leia o código relevante primeiro; sem edições cegas).

3. Implemente a unidade.

4. Verifique com as verificações determinísticas. Verde é o único sinal de aprovação — "parece correto" não é um verificador, e nunca enfraqueça ou remova um teste falhando para ficar verde. Em caso de falha, corrija e verifique novamente, no máximo 3 tentativas; se ainda vermelho, reverta as alterações da unidade (git checkout -- <arquivos> / git stash) para que a árvore permaneça limpa, registre como pulada e siga em frente.

5. Confirme (commit) a unidade verde com uma mensagem convencional clara. NÃO faça push.

6. Batimento cardíaco — após um commit, um hwip_notify curto ("✅ — m restantes"), mas no máximo um a cada ~15 minutos; agrupe unidades pequenas. Bloqueios são a exceção: envie um notify com priority: "high" no instante em que um aparecer.

Repita até que as unidades sejam concluídas ou o limite de encerramento seja atingido.

Protocolo de Perguntas — nunca pare, nunca destrua

Perguntas durante a execução passam pelo hwip_ask (nunca AskUserQuestion, nunca texto simples — as regras 3/10 do CORE_RULES se aplicam):

• Coloque o padrão recomendado primeiro, observe no corpo que prossegue automaticamente em caso de timeout, defina timeout: 180 (até 600 para decisões genuinamente grandes) e fallback para o id desse padrão.
• Registre cada decisão resolvida por fallback — o relatório final as lista para que o usuário possa auditar o que foi decidido sem ele.
• Qualquer resposta é uma instrução direta: aplique-a imediatamente. Uma resposta stop (ou finalizador de sessão em texto livre) significa encerrar agora.
• Ações irreversíveis ou voltadas para o exterior nunca são elegíveis para fallback: push, PR/publicar, deploy, exclusão de dados, remoção de schema, operações forçadas, qualquer coisa fora da árvore de trabalho. Para estas, o fallback DEVE ser skip — em caso de timeout, você pula a ação e a registra, não a executa. Apenas um toque explícito em botão a autoriza.

Encerramento

1. Finalize ou reverta a unidade em andamento (mesma regra de 3 tentativas — nunca deixe a árvore vermelha ou suja).
2. Remova o arquivo de estado: rm -f "${XDG_STATE_HOME:-$HOME/.local/state}/hwip/auto-$HASH".
3. Relatório final no texto da sua resposta: unidades concluídas (com hashes de commit), unidades puladas e por quê, cada decisão resolvida por fallback e o que resta.
4. Pergunta final:
   • actions: [{id:"extend", label:"+30m"}, {id:"review", label:"Revisar"}, {id:"done", label:"Concluído", style:"primary"}]
   • timeout: 300, fallback: "done"
   • extend → escreva um novo prazo (+30m) no arquivo de estado e reentre no loop; review → percorra o diff; done → encerre.

Se Algo Der Errado

• Sem hook id (Mode: one-way) — ferramentas de duas vias estão indisponíveis; o modo automático não pode ser executado. Execute /hwip-config para configurá-lo.
• Arquivo de estado ausente durante a execução (ex.: diretório de estado limpo): trate o prazo como agora — encerre em vez de adivinhar quanto orçamento resta.
• Usuário digita no terminal durante a execução: essa mensagem é entrada de direcionamento, igual a uma resposta de hwip_ask. Aplique-a e continue o loop.
• Verificador é instável (mesmo comando alterna verde/vermelho sem alteração): não queime tentativas em reexecuções — reporte como bloqueio via hwip_notify (priority: "high") e vá para a próxima unidade.