chasey-myagi/helm

O que helm faz?

Um quadro ao vivo para uma tarefa. O humano o mantém aberto em um navegador; você o atualiza com chamadas baratas helm conforme trabalha; um servidor local de curta duração transmite mudanças para a página no local. O humano pode pegar o volante — editar o objetivo / direção — e você o segue no seu próximo checkpoint.

As duas regras

1. Só chame helm. Nunca escreva ou edite HTML, o servidor ou state.json manualmente. Cada chamada helm são poucos tokens, que é o objetivo: manter o quadro honesto enquanto você trabalha continua barato. Reemitir uma página estilizada custaria 10x e derrotaria o propósito.
2. Releia a direção do humano em cada checkpoint (entre etapas do plano, antes de algo irreversível) com helm goal. Eles dirigem pela página; você só vê se olhar. Se o objetivo ou direção mudou, siga a nova versão e diga isso em um event.

O auxiliar

O helm é distribuído como um script Node.js construído e sem dependências em dist/helm.mjs (roda num node básico — nenhum npm install, nenhuma build na instalação). Capture o caminho uma vez e reutilize-o:

HELM="<caminho-deste-skill>/dist/helm.mjs"   # ex.: ~/.claude/skills/helm/dist/helm.mjs

Chame-o por este caminho — "$HELM" … funciona via seu shebang, ou use node "$HELM" …. Não crie um alias para helm puro se você usa Kubernetes — esse é um helm diferente. Após init, o quadro é encontrado automaticamente subindo a partir do diretório atual, então chamadas posteriores não precisam de --dir.

Fluxo de trabalho

1. Init uma vez, no início de uma tarefa que vale a pena acompanhar. Dê o objetivo para que o humano possa dirigir desde o primeiro segundo:

   "$HELM" init --title "Migrar auth para JWT" --agent "Claude Code" --model claude-opus-4-8 \
                --goal "Mover sessões de cookies para JWT sem estado, não perder ninguém"
   

   Isso inicia o servidor e abre o navegador. Diga ao usuário que o quadro está ativo e que ele pode editar o objetivo / direção a qualquer momento.

2. Monte o plano para que eles vejam a forma do trabalho, depois avançe por ele. step N marca etapas anteriores como concluídas, torna N a atividade atual e define o progresso — uma chamada move tudo:

   "$HELM" plan "Fazer backup dos usuários" "Adicionar emissão/verificação RS256" "Migrar sessões" "Fazer corte" "Regressão"
   "$HELM" step 2
   

3. Narre enquanto avança — pequeno, frequente, honesto. Cada um é uma chamada:

   "$HELM" event ok   "backup da tabela de usuários salvo em backups/users.sql"
   "$HELM" event warn "3 sessões usam o formato legado de cookie, precisam de migração manual"  # armadilhas também vão aqui
   "$HELM" decide "RS256 em vez de HS256 para que serviços verifiquem apenas com a chave pública"
   "$HELM" decide "Padrão para staging primeiro, produção aguarda um sim humano" --assumption     # sinalizar suposições não confirmadas
   

4. Checkpoint — leia a direção do humano e obedeça-a:

   "$HELM" goal      # imprime o OBJETIVO + DIREÇÃO; se eles editaram, essa linha diz isso — siga-a
   

   Se mudaram de direção, adapte-se e registre: "$HELM" event info "direção mudou → fazendo apenas staging".

5. Superfície bloqueadores reais no momento em que aparecem; resolva-os quando respondidos:

   "$HELM" ask "Migrar banco de staging ou produção primeiro?"   # apenas perguntas genuínas de humano-no-loop
   "$HELM" status "Aguardando sua decisão sobre produção" --state blocked   # bloqueado/novas perguntas notificam o humano
   "$HELM" resolve 1
   

6. Termine: "$HELM" done "Todas as sessões migradas, testes verdes". O quadro permanece visível, então o servidor fecha automaticamente quando ninguém mais está observando. "$HELM" stop encerra agora; "$HELM" open reabre.

Atualize frequentemente e em pequenas doses. Uma mudança de status, uma etapa concluída, uma armadilha, uma decisão, um novo artefato — cada um é uma chamada. O quadro merece seu lugar apenas quando rastreia a realidade minuto a minuto.

Comandos

Comando	O que faz
helm init --title T [--subtitle S] [--agent A] [--model M] [--goal G] [--theme light|dark] [--no-open]	Cria o quadro, inicia seu servidor, abre-o.
helm status TEXTO [--state running|blocked|waiting|done] [--phase P] [--pct N]	Define a linha de atividade atual (AGORA). blocked notifica o humano.
helm plan A B C … · helm plan --add TEXTO	Define as etapas do plano, ou anexa uma.
helm step N [--text AGORA]	Avança para a etapa N: etapas anteriores concluídas, N ativa, AGORA + progresso atualizados.
helm event KIND TEXTO	Anexa uma entrada na linha do tempo. KIND ∈ ok fail warn info run. Armadilhas/pontos mortos → warn/fail.
helm decide TEXTO [--assumption]	Registra uma decisão; --assumption a sinaliza como não confirmada (para o humano corrigi-la).
helm ask PERGUNTA · helm resolve N	Adiciona / remove um item "precisa de sua opinião" (notifica o humano).
helm goal · helm goal --set TEXTO	Lê o objetivo + direção do humano (faça isso nos checkpoints), ou define o objetivo.
helm link RÓTULO URL · helm image CAMINHO [--label L] · helm data RÓTULO VALOR	Anexa um artefato (link / imagem / estatística).
helm meta [--title …] [--subtitle …] [--theme …] [--agent …] [--model …]	Edita campos do cabeçalho posteriormente.
helm done [TEXTO] · helm stop · helm open	Finalizar · parar o servidor agora · reabrir o quadro.

Convenções (tratadas para você, ou exigidas)

• ask é apenas para decisões genuínas. Nunca preencha com perguntas já resolvidas ou retóricas. Se nada precisar do humano, deixe vazio — um quadro silencioso é um quadro verdadeiro.
• --state controla o pulso ao vivo, a cor e as notificações. Use running enquanto trabalha, blocked/waiting quando estiver travado ou esperando o humano (eles disparam uma notificação de desktop
  • um contador 🔴 no título da aba), done no final.
• Decisões vs suposições. decide simples para escolhas que você já se comprometeu; --assumption para coisas que você está assumindo mas não confirmou. A tag de suposição é exatamente onde o humano pegará você errando cedo, então sinalize-as honestamente.
• O rodapé de proveniência e a legenda de atividade são renderizados automaticamente — não os construa.
• O processo é de curta duração. Ele se encerra quando a tarefa termina e ninguém está assistindo, e nunca reinicia sozinho. Se atualizações acontecerem enquanto a página está fechada, elas ainda são salvas; helm open mostra as mais recentes.

Arquivos

O que é executado (commitado, sem dependências — dist/):

• dist/helm.mjs — a CLI que você chama para cada atualização.
• dist/server.mjs — o servidor local de curta duração: serve a UI, transmite estado via SSE, recebe gravações de direção, encerra-se quando abandonado.
• dist/board.html — a UI do quadro (duas colunas, lavanda claro + escuro) que o servidor serve.

Como é construído (apenas para desenvolvimento, não necessário para executar): src/*.ts (TypeScript escrito, um types.ts compartilhado para o modelo de dados), build.mjs (esbuild), package.json. Após editar src/, execute npm run build. Veja DEVRULES.md para os inegociáveis.