wellwelwel/blue-spec

Simulando um comando Blue Spec

Esta habilidade existe porque simular um comando é enganosamente fácil de errar de uma forma que desperdiça o tempo e a confiança do usuário. Sessões difíceis produziram quatro regras inegociáveis e um método. Siga-as exatamente.

Use esta habilidade sempre que o usuário pedir para "simular", "demonstrar", "mostrar na prática", "executar" ou "ver em ação" qualquer comando /bluespec.* (charter, detect, plan, harden, verify), ou para pré-visualizar como um comando se comporta antes de enviá-lo.

Antes de começar (obrigatório)

Não inicie uma simulação, construa um cenário ou copie um fixture até que ambos estejam resolvidos, nesta ordem:

1. O usuário deve dizer qual comando Blue Spec simular. Isso é obrigatório, nunca assuma ou escolha um. Se o usuário não nomeou um comando (charter, detect, plan, harden ou verify), pergunte qual antes de fazer qualquer outra coisa. Se nomeou mais de um, confirme a ordem em que você os executará.
2. Em seguida, sugira o fixture, enumerado, e deixe o usuário escolher. Assim que o comando for conhecido, liste os fixtures disponíveis (de .claude/skills/simulate/fixtures/) como uma lista numerada, cada um com uma descrição de uma linha do seu cenário, e peça ao usuário para escolher um pelo número. Não use um fixture silenciosamente como padrão. Se apenas um fixture existir, ainda assim o apresente e confirme antes de usá-lo. Se nenhum atender ao comando, diga isso e ofereça-se para adicionar um novo fixture (veja a seção de fixtures).

Apenas depois que o comando for nomeado e o fixture escolhido você prossegue para as regras e o método abaixo.

Por que esta habilidade existe (leia isto primeiro)

Um comando Blue Spec não é um programa independente. É um arquivo de instruções (spec/commands/bluespec.<phase>.md, estruturado como uma habilidade que o agente lê) que diz a um agente de IA como fazer uma fase do trabalho de segurança. "Executar o comando" significa um agente seguindo essas instruções. Não existe um binário que emite um resultado determinístico independente do agente. Portanto, uma "simulação" é o agente executando as etapas do comando de verdade, contra um cenário real, enquanto mostra seu trabalho.

O modo de falha a evitar: narrar o que você imagina que o comando produziria, formatando para parecer um terminal, e apresentando como se tivesse sido executado. Isso é teatro. O usuário não consegue distinguir saída inventada de saída real, e ele vai (com razão) chamar de farsa. Tudo abaixo é projetado para tornar a simulação real e verificável pelo usuário, não uma performance.

As quatro regras rígidas

Regra 1: Execute o cenário dentro de ./temp

Construa tudo que a simulação toca (o fixture, os artefatos de .bluespec/memory/ que as fases produzem, quaisquer entradas) dentro de ./temp na raiz do repositório, nunca no /tmp do sistema.

• /tmp é invisível para o usuário: ele não pode abrir esses arquivos no seu editor, então tudo que você faz lá se torna "confie em mim". ./temp está no espaço de trabalho dele, aberto, inspecionável.
• ./temp está no gitignore, então a simulação nunca polui os commits.
• Limpe ./temp quando o usuário terminar, ou deixe-o para ele inspecionar, mas pergunte primeiro.

Os fixtures: comece toda simulação a partir de um

Projetos de amostra neutros acompanham esta habilidade, cada um em seu próprio diretório sob .claude/skills/simulate/fixtures/<nome>/. Escolha o fixture cujo cenário se encaixa no que o comando precisa, ou adicione um novo (veja abaixo). Cada fixture é um pequeno projeto real que contém deliberadamente código robusto e frágil, em pares neutros para que o comando precise analisar o código, não ler um rótulo.

Fixtures disponíveis:

• image-upload-service: um pequeno serviço HTTP ESM que aceita uploads de imagens e as serve de volta.
• template-toolkit: um pacote npm ESM publicável (uma biblioteca mais um CLI tmpl) para renderizar templates e analisar texto.

Sempre comece uma simulação copiando um fixture cru para dentro de ./temp. Se ./temp já existir e não estiver vazio, limpe-o primeiro, para que cada execução comece limpa (substitua <nome> pelo fixture que você escolheu):

rm -rf ./temp && mkdir -p ./temp
cp -R .claude/skills/simulate/fixtures/<nome>/. ./temp/

Em seguida, construa a cadeia em cima de ./temp executando as fases upstream de verdade (conforme a Regra 4), para que o artefato .bluespec/memory/*.md que o comando lê seja produzido por sua própria fase, não escrito à mão. Execute as etapas do comando contra ./temp, seguindo sua especificação à risca (conforme a Regra 3), e mostre a saída de cada etapa de acordo com a Regra 2.

Para adicionar um fixture, crie .claude/skills/simulate/fixtures/<novo-nome>/ como um pequeno projeto real com seu próprio package.json, mantenha código robusto e frágil em pares neutros, não adicione comentários ou nomes reveladores, e liste-o acima. Adicione um quando um comando precisar de material que os fixtures atuais não cobrem (uma linguagem ou stack diferente, tratamento de segredos, autenticação, um banco de dados, e assim por diante).

Regra 2: Exponha prompts e respostas como blocos de código demarcados DENTRO da mensagem do chat

Esta é a regra que levou mais tempo para aprender. Quando você executa uma ferramenta (Bash, Read), a interface do usuário mostra uma prévia truncada do IN e OUT dessa ferramenta. Você não controla quanto é mostrado, e geralmente é cortado. Se a evidência que sustenta uma alegação vive apenas dentro da saída de uma chamada de ferramenta, o usuário não a vê, e qualquer frase que você escrever descrevendo-a soará como invenção.

Portanto:

• Depois de executar uma ferramenta, copie a saída bruta relevante para um bloco de código demarcado (três crases) na sua mensagem normal do chat. O bloco demarcado renderiza completamente e de forma idêntica em todas as interfaces. Estas são as "letras amarelas" que o usuário quer dizer: um bloco de código markdown.
• O prompt e a interação do comando (o que /bluespec.<phase> mostra enquanto executa: o passo a passo, a decisão de escopo, os vereditos) também vão em um bloco de código demarcado, estilizado como uma transcrição.
• Nunca escreva "a saída acima mostra X" apontando para uma chamada de ferramenta. Aponte para o bloco demarcado que você colou, que o usuário pode ler por completo.
• Quando um número ou linha na sua transcrição veio de uma execução real, ele deve corresponder à saída bruta que você colou. Se você escrever uma linha de transcrição que não é respaldada pela saída bruta colada, você está inventando, então pare.

Um padrão confiável: execute o comando, redirecione a saída bruta para um arquivo dentro de ./temp (por exemplo ./temp/run.log), então Read esse arquivo (o resultado do Read é mostrado a você por completo) e cole seu conteúdo em um bloco demarcado. O usuário também pode abrir ./temp/run.log para verificar.

Mostre conforme avança, nunca em lote no final. O gatilho é por etapa: no momento em que uma etapa produz algo que o usuário deve ver (uma entrada que leu, sua transcrição, o artefato que escreveu), cole-o em um bloco demarcado na mesma mensagem, antes da próxima etapa. Se você estiver prestes a começar a próxima fase ou correção e a saída da etapa anterior ainda não estiver na tela, pare e cole-a primeiro. Se o usuário tiver que lembrá-lo de mostrar a saída de um comando, a regra já falhou.

Regra 3: Você é o comando, então siga sua especificação à risca

"Executar o comando" é você executar spec/commands/bluespec.<phase>.md passo a passo, não fazer a fase do seu jeito e chamá-la de comando.

• Abra essa especificação primeiro e trate-a como a única fonte da verdade. Siga suas etapas em ordem. Não execute a fase de memória ou a partir do resumo desta habilidade.
• Realize cada parada de confirmação que a especificação exige, de verdade. harden deve confirmar antes de editar qualquer código, uma varredura completa de detect deve ser confirmada porque consome muitos tokens. Apresente o que a especificação diz para apresentar, em um bloco de transcrição, e aguarde. Nunca edite código ou execute uma etapa bloqueada sem a confirmação primeiro.
• Decida escopo, vereditos, correções, prioridades e descobertas da forma como as etapas da especificação decidem, contra o cenário real. Se você não consegue apontar para a etapa da especificação que justifica uma linha de saída, você está agindo como você mesmo, então pare e siga a especificação.

Regra 4: A entrada de cada fase deve vir da execução da fase anterior, não de você

A cadeia é charter → detect → plan → harden → verify, cada fase lendo o que a anterior escreveu. Criar manualmente um artefato downstream com as respostas que você espera (um harden.md que registra exatamente o que você quer que verify confirme ou pegue) é a falha: a fase downstream é então testada contra sua previsão, não contra a realidade, então ela perde tudo que você perdeu.

• Produza cada artefato upstream executando sua fase, sob sua própria especificação, mostrado conforme a Regra 2. Para demonstrar verify, execute detect (lê o código), depois plan (lê detect.md), depois harden (lê plan.md, edita o código). Mesmo quando o usuário começa no meio da cadeia, construa os artefatos ausentes desta forma, em ordem.
• Deixe o artefato dizer o que a execução realmente produziu, lacunas incluídas: um Partial, um Blocked, uma descoberta que você não previu. Um artefato suspeitamente limpo é o sinal de que esta regra foi quebrada.
• Um cenário deliberadamente divergente é aceitável (harden aplica tudo, então o código é revertido para que verify tenha que detectar o desvio), mas introduza a divergência visivelmente (reverta em uma chamada de ferramenta mostrada, mantenha os artefatos reais), nunca escrevendo manualmente um registro que a execução nunca produziu.

O método, passo a passo

Cada fase lê a anterior e escreve um artefato. Conheça esta cadeia e não a quebre:

Fase	Lê	Escreve
charter	o contexto do projeto	.bluespec/memory/charter.md
detect	o código	.bluespec/memory/detect.md
plan	apenas detect.md, nunca o código	.bluespec/memory/plan.md
harden	apenas plan.md mais o charter, e edita o código do usuário	.bluespec/memory/harden.md
verify	harden.md e o código, confrontando registro contra realidade, sem mudar nada	.bluespec/memory/verify.md

Em seguida, para o comando que você está simulando:

1. Copie o fixture cru para dentro de ./temp (Regra 1).
2. Construa a cadeia executando cada fase upstream, em ordem, contra ./temp (Regra 4).
3. Execute a fase alvo sob sua spec/commands/bluespec.<phase>.md, à risca (Regra 3).
4. Mostre cada entrada, transcrição e artefato em um bloco demarcado conforme você avança (Regra 2). Escreva cada artefato de saída como um arquivo real, depois Read e mostre-o.

Verificações de honestidade antes de apresentar qualquer coisa

• Isso foi realmente executado, ou estou digitando o que acho que aconteceria?
• Cada linha da transcrição é respaldada pela saída bruta que colei, ou por um arquivo ./temp que o usuário pode abrir, em vez de uma chamada de ferramenta truncada? (Regra 2)
• Já colei a saída de cada etapa até agora, para que o usuário nunca tenha que perguntar? (Regra 2)
• Eu segui a especificação de cada fase, paradas de confirmação incluídas, em vez de agir como eu mesmo? (Regra 3)
• Cada artefato upstream veio da execução de sua fase, não de mim escrevendo manualmente o resultado que eu queria? (Regra 4)
• O cenário está sob ./temp, não escondido em /tmp? (Regra 1)

Se alguma resposta for não, corrija-a antes de enviar. O usuário prefere ver uma saída real e modesta do que uma invenção polida.