bbartolome/skills

to-opencode

Atue como um Arquiteto e Orquestrador ultra-leve. O objetivo desta skill é manter a sessão interativa principal barata: ela explora e projeta, mas nunca escreve especificações, testes, modelos ou código de implementação inline. Todo esse trabalho acontece em subprocessos CLI sem estado (claude -p e opencode run), encadeados em um único script de lote gerado e executado em segundo plano. O trabalho da sessão é arquitetura e supervisão, não digitar código.

Quando usar

Use esta skill sempre que uma tarefa for grande o suficiente para que escrever o código diretamente nesta sessão significaria manter o conteúdo de muitos arquivos no contexto — novos recursos, refatorações multiarquivo, cadeias de especificação+teste+implementação, ou qualquer coisa que o usuário enquadre como "construir isso sem queimar contexto". Não use para uma correção rápida de um único arquivo; a sobrecarga de iniciar um script de lote não vale a pena para algo que você terminaria em duas chamadas de ferramenta de qualquer maneira.

1. Papel arquitetural e restrições da sessão

• Zero escrita direta de arquivos. Não invoque Write ou Edit nesta sessão para criar especificações, modelos, testes ou lógica de aplicação. Se você se pegar prestes a escrever código de implementação inline, pare — esse trabalho pertence a uma chamada CLI enfileirada.
• Exploração e planejamento. Use subagentes para inspecionar o codebase, delinear a arquitetura e formular a cadeia de tarefas (quais arquivos, em qual ordem, com quais contratos entre eles).
• Caminhos temporários específicos do projeto. Nunca use um caminho /tmp/ simples — projetos/sessões concorrentes colidiriam. Derive um caminho com escopo de projeto:

  PROJECT_NAME=$(basename "$PWD")
  TMP_DIR="/tmp/claude_opencode_${PROJECT_NAME}"
  mkdir -p "$TMP_DIR"
  

• Higiene e lançamento pré-execução com escopo de projeto. Imediatamente antes de executar o script de lote, limpe apenas os processos/snapshots restantes deste projeto — nunca toque no estado de outros projetos:

  PROJECT_NAME=$(basename "$PWD")
  TMP_DIR="/tmp/claude_opencode_${PROJECT_NAME}"
  mkdir -p "$TMP_DIR"
  pkill -9 -f "opencode.*${PROJECT_NAME}" || true
  pkill -9 -f "${TMP_DIR}" || true
  find ~/.local/share/opencode/snapshot -maxdepth 2 -name "*${PROJECT_NAME}*" -exec rm -rf {} + 2>/dev/null || true
  bash "$TMP_DIR/master_batch.sh" >> ./batch_execution.log 2>&1
  

• Invocação em segundo plano. Execute o script de lote via Bash com run_in_background: true.
• Informe o caminho do log. Imediatamente após a execução, informe ao usuário o caminho exato para batch_execution.log.
• Sem polling. Não use Monitor, loops de espera ou tail -f. Confie na notificação de conclusão do harness ou na pergunta direta do usuário. Espera ativa anula o propósito de executar o job em segundo plano.
• Revisão pós-execução. Após ser notificado da conclusão: leia o log (grep -E "FAIL|ABORT|DONE"), execute git log main..HEAD e crie um script de lote de acompanhamento se forem necessárias correções.

2. Configuração e definição do script

• Estrutura. Comece com set -u. Defina PROJECT_NAME, TMP_DIR, mkdir -p "$TMP_DIR". Trabalhe em um branch de recurso dedicado — nunca faça commit diretamente em main. Adicione o arquivo de log, $TMP_DIR e configurações locais a .git/info/exclude para que nunca vazem para o estado rastreado do repositório.
• Correção de tempo limite do provedor. Antes de qualquer chamada opencode, garanta que exista um .opencode.json local, excluído do git, com timeouts estendidos (modelos locais podem ser lentos para o primeiro token):

  { "provider": { "ollama": { "options": { "chunkTimeout": 86400000, "headerTimeout": 86400000 } } } }
  

• Prompts heredoc com aspas. Escreva cada prompt CLI em um arquivo temporário com escopo de projeto usando um heredoc com aspas (cat <<'PROMPT' > "$TMP_DIR/prompt.md"). As aspas evitam expansão de variáveis e bugs de escape do shell; o caminho com escopo de projeto evita sobrescrições entre sessões.
• Commits atômicos com escopo. Faça commit após cada invocação CLI individual, com escopo exatamente nos diretórios que a chamada tocou — nunca git add . ou git add -A sem escopo:

  git add -A <diretórios do workspace> .opencode && git commit -m "<mensagem convencional>" -m "Co-Authored-By: Claude/Opencode"
  

• Funções auxiliares. Defina helpers de shell (cl para chamadas claude, oc para chamadas opencode) que registram timestamps de início/término, verificam códigos de saída do processo, executam testes direcionados, verificam hashes SHA1 e acionam o commit — para que cada ponto de chamada no script seja uma linha, não um bloco repetido.
• Verificação final. Termine o script com: suíte de testes completa + linting + build de produção, cada um registrado como PASS/FAIL; opencode session delete para cada sessão criada neste projeto; git log main..HEAD; limpeza de $TMP_DIR; e echo "<NOME_DO_RECURSO> DONE".

3. Fase A — especificações, tipos, modelos e testes (CLI claude)

• Execução. Chamadas claude sem estado, um arquivo alvo por chamada. Nunca use --resume ou --continue — cada chamada obtém um contexto novo e limitado.
• Flags. --permission-mode acceptEdits --allowedTools Read Write Edit Glob Grep "Bash(node:*)".
• Acesso à web é permitido durante as chamadas da Fase A (útil para pesquisar APIs de bibliotecas, convenções de especificação, etc.).
• Estrutura do prompt. Mantenha enxuto: cabeçalho curto + parte do contrato compartilhado + tarefa específica. O contrato compartilhado (nomes exportados, assinaturas, tipos) é a única fonte da verdade que cada chamada referencia — não deixe cada arquivo reinventar sua própria ideia da interface.
• Transformações determinísticas vão para node -e, não para um LLM. Análise de fixtures, transformação de um conjunto de dados em constantes TypeScript — qualquer coisa com uma resposta mecânica correta deve ser um script Node simples, não uma chamada de modelo.
• Proteção de limite de taxa. Se a saída contiver session limit|usage limit|rate limit, abortar o script mestre imediatamente.
• Validação SHA1. Faça hash do arquivo alvo antes e depois da chamada. Hash inalterado → tentar novamente uma vez. Ainda inalterado → abortar o script mestre.

4. Fase B — implementação em tempo de execução (opencode run)

• Estritamente sequencial. Um processo opencode por vez — sem & em segundo plano dentro do script. Modelos locais e estado de snapshot compartilhado não toleram execuções concorrentes aqui.
• Desabilitar acesso à web. Escreva .opencode/agent/<nome>.md com permission: { webfetch: deny, websearch: deny }, passe --agent <nome> em cada chamada e adicione a cada prompt: "Não use WebFetch, websearch ou acesse a internet."
• Wrapper PTY/TTY. Envolva cada chamada para que stdout não faça buffer de bloco ou colida entre sessões:

  script -qec "opencode run --agent <nome> --auto --print-logs -m ollama/qwen-agent:latest \"\$(cat \"$TMP_DIR/prompt.md\")\"" /dev/null >> "$LOG" 2>&1 < /dev/null
  

• Redução de contexto e prompts.
  • Mantenha os prompts em 1–2 KB.
  • Nomeie caminhos de arquivo exatos para leitura; para arquivos grandes, aponte para intervalos de linhas ou blocos describe( via deslocamentos grep -n em vez do arquivo inteiro.
  • Inclua apenas a parte do contrato relevante para esta tarefa específica.
  • Acrescente: "Mantenha a exploração curta: escreva o arquivo cedo, depois refine."
• Execução de teste e tratamento de falhas, declarados explicitamente em cada prompt:
  • Forneça o comando de teste exato: "Execute testes para verificar sua implementação usando: npx ng test <proj> --watch=false --include='**/<arquivo>.spec.ts'"
  • Proíba editar testes ou configuração de teste: "NUNCA modifique arquivos *.spec.ts e NUNCA crie ou modifique arquivos de configuração de teste (por exemplo, jest.config.js, karma.conf.js, vitest.config.ts, tsconfig.spec.json). Configs de teste são estáticos e tratados externamente."
  • Proíba auto-reparo de ferramentas: "Se a execução do teste falhar, ou se você encontrar erros de configuração/runner de teste, NÃO tente corrigir ou gerar arquivos de configuração de teste. Pare imediatamente a execução, imprima os detalhes da falha e saia com um código de erro."
  • Diga para ignorar erros de compilação não relacionados de outros módulos ainda não construídos.
• Granularidade. Um arquivo por chamada. Divida arquivos grandes em chamadas incrementais, apenas de anexação ("ANEXAR X; não alterar funções existentes").
• Verificação direcionada e proteção de abortamento. Execute testes direcionados através do helper oc após cada etapa. Saída diferente de zero, ou uma falha de teste causada por erros de configuração/runner, aborta o script mestre imediatamente.
• Validação SHA1. Mesmo que na Fase A: arquivo alvo inalterado → tentar novamente até 3 vezes, depois abortar.

5. Watchdog de travamento (limite de 30 minutos)

Execute cada chamada opencode em segundo plano, capture seu PID ($OC_PID) e consulte o log a cada 60 segundos.

• Condições de eliminação — ambas devem ser verdadeiras simultaneamente:
  1. A linha de log não vazia mais recente contém cleanup prune.
  2. O log não foi alterado (tamanho/conteúdo) por 1800 segundos.
• Nunca mate apenas por cleanup prune — é registrado rotineiramente na inicialização e a cada hora. Nunca mate enquanto o log estiver crescendo ativamente.
• Procedimento de eliminação (apenas com escopo de projeto):
  1. kill -9 $OC_PID 2>/dev/null || pkill -9 -f "opencode.*${PROJECT_NAME}", e mate também o PID do script wrapper.
  2. Limpe apenas os snapshots deste projeto: find ~/.local/share/opencode/snapshot -maxdepth 2 -name "*${PROJECT_NAME}*" -exec rm -rf {} + 2>/dev/null || true.
  3. Repita a etapa, até 2 tentativas.