magnus919/agent-skills

BMad: Protocolo de Plano de Controle de Intenção à Entrega

BMad é um método de entrega de software construído em uma ideia: a intenção humana deve ser progressivamente esclarecida, registrada, revisada e entregue a agentes como contexto durável, em vez de improvisada em chat. Esta skill transforma esse método em um protocolo que qualquer harness de agente pode seguir — sem necessidade de instalador oficial do BMad.

O ciclo: classificar a solicitação → comprimir a intenção em um contrato → rotear para o menor caminho seguro → implementar uma unidade delimitada → revisar como triagem → rotear falha para a camada onde a ambiguidade entrou → limitar autonomia com base em aceitação observável → aprender com o trabalho concluído.

Quando usar esta skill

Carregue quando uma solicitação de mudança, funcionalidade, relatório de bug, construção delegada ou épico multiagente precisar de:

• captura de intenção antes da implementação — um contrato, não uma vibe;
• uma decisão sobre quanta cerimônia o trabalho merece;
• artefatos duráveis para que o trabalho seja retomável entre sessões ou agentes;
• revisão que tria descobertas em vez de enumerar ruído;
• autonomia que para com segurança quando o limite é inseguro.

Classificação do trabalho (menor caminho seguro)

Classe	Forma	Processo
Direto	objetivo claro, mudança local, padrões estabelecidos, pequeno raio de impacto	implementar imediatamente após esclarecimento mínimo
Delimitado	mudança coerente que precisa de um contrato e plano curtos	contrato de intenção → plano → implementar → revisar
Iniciativa	multicomponente, multi-história, alto risco ou estrategicamente incerto	análise → planejamento → solução → implementação → aprendizado

Carregue references/classification.md para a tabela de decisão, a regra de uma pergunta e as condições de parada.

O contrato de intenção (cinco campos)

Para trabalho delimitado ou de iniciativa, estabeleça um contrato antes da implementação:

1. Porquê — o resultado e por que é importante.
2. Capacidades — o que o sistema deve ser capaz de fazer.
3. Restrições — técnicas, operacionais, legais, de segurança, privacidade, tempo, custo, limites organizacionais.
4. Não-objetivos — o que está explicitamente fora do escopo.
5. Sinal de sucesso — como saberemos que o resultado funciona e é aceitável.

Se um campo for materialmente ambíguo, faça uma pergunta de alto impacto, proponha uma resposta recomendada e aguarde a decisão. Para mudanças triviais, o contrato pode ser cinco marcadores em conversa; para trabalhos maiores, torna-se um arquivo de especificação versionado.

Carregue references/spec.md para a criação de SPEC e o vocabulário de status. Modelos: templates/SPEC.md e templates/INTENT.md.

O ciclo canônico

1. Inspecione o repositório e o contexto disponível antes de perguntar qualquer coisa.
2. Classifique o trabalho; declare a rota proposta.
3. Estabeleça ou retome o contrato de intenção; faça no máximo uma pergunta material.
4. Apresente um plano para trabalho não trivial; aguarde no ponto de verificação de aprovação.
5. Implemente a menor mudança coerente; execute testes focados primeiro, depois verificações mais amplas.
6. Revise para correção, escopo, segurança, regressões, capacidade de manutenção.
7. Corrija descobertas que pertencem a esta mudança; adie descobertas não relacionadas explicitamente.
8. Relate intenção, comportamento, arquivos, risco, verificação, disposição das descobertas e uma escolha entre aceitar / retrabalhar / investigar.

Vocabulário de status da especificação

Status legível por máquina para trabalho retomável:

Status	Significado
draft	A especificação existe, mas não está pronta
ready-for-dev	Aprovada na prontidão; pronta para implementar
in-progress	Implementação em andamento
in-review	Revisão ou triagem em andamento
done	Fluxo de trabalho concluído com sucesso
blocked	Não é possível continuar com segurança sem supervisão

blocked é um sinal de roteamento, não uma falha: um orquestrador de nível superior, outro fluxo de trabalho ou um humano assume. Valide uma especificação deterministicamente com scripts/check-spec.py.

Roteamento de falhas

Quando algo estiver errado, diagnostique a camada onde a falha entrou:

Falha	Rota
Resultado errado ou problema errado	intenção / análise
Requisito ausente ou contraditório	contrato / planejamento
Abordagem técnica conflitante	arquitetura
Código local incorreto	implementação
Teste ou avaliação insuficiente	verificação
Problema pré-existente não relacionado	adiar explicitamente
Ambiguidade insegura	bloquear e perguntar

Não continue corrigindo código quando a especificação é o verdadeiro problema.

Portão de autonomia

A execução autônoma é permitida apenas quando todas as seguintes condições são atendidas: contrato de intenção coerente, aceitação observável, limite explícito, repositório seguro para modificar, testes ou avaliações executáveis, status durável gravável, escalonamento definido. Durante o trabalho autônomo: uma mudança coerente por vez; nunca expanda o escopo com melhorias não relacionadas; nunca mescle, implante ou altere sistemas externos sem autorização; pare em lacunas de intenção, capacidade ausente, ambiguidade destrutiva, falha de verificação ou reparo não convergente.

Arquivos de referência

Referência	Carregue quando
references/protocol.md	Você precisa do protocolo operacional completo e pronto para colar para um agente
references/classification.md	Classificando uma solicitação ou escolhendo a profundidade da cerimônia
references/spec.md	Escrevendo ou retomando uma SPEC / contrato de intenção
references/lifecycle.md	Executando uma iniciativa através de todas as quatro fases
references/project-context.md	Configurando ou auditando regras do repositório (AGENTS.md)
references/review-and-failure-routing.md	Executando uma revisão ou diagnosticando uma falha
references/autonomy.md	Configurando ou executando trabalho autônomo (Build Auto)
references/party-mode.md	Deliberação, trade-offs, debates de design, post-mortems
references/adoption.md	Adotando o protocolo incrementalmente ou mapeando para uma fábrica escura

Modelos

Modelo	Propósito
templates/SPEC.md	Contrato de máquina versionado para trabalho delimitado/de iniciativa
templates/INTENT.md	Contrato leve de cinco campos para trabalho delimitado
templates/STORY.md	Uma unidade de trabalho delimitada e despachável
templates/REVIEW.md	Ponto de verificação humano final: intenção → comportamento → risco → verificação

Scripts

Script	Quando executar
scripts/check-spec.py	Após escrever ou editar uma especificação: valide cinco campos + vocabulário de status (stdlib apenas, saída --json)

Roteamento para skills adjacentes

• Upstream (antes do BMad): product-discovery valida se um problema é real; product-shaping define um apetite e produz um pitch; product-strategy e product-roadmapping-and-portfolio enquadram o contexto estratégico.
• Downstream (durante o BMad): spec-driven-development para pipelines formais de especificação/portão; implementation-planning para um plano de entrega com consciência de dependências; adr-authoring para decisões de arquitetura; software-architecture-analysis para engenharia reversa de uma base de código existente.
• Execução e portões: neckbeard para o fluxo de entrega de issue para PR; verification-methodology para evidências de aceitação; qa-methodology para estratégia de teste; agent-evals-and-observability para avaliadores independentes; agent-council para deliberação multiagente no estilo Party Mode; release-engineering para portões de implantação; kanban-guru para política de backlog e despacho.

Quando não usar

• O problema em si não é validado → product-discovery. BMad comprime a intenção; não estabelece se o problema é real.
• Nenhuma decisão ainda sobre quanto o trabalho vale → product-shaping primeiro (apetite, pitch, aposta). BMad começa a partir de uma intenção colocada.
• Você precisa de um formato de especificação formal mais portões de fase como pipeline de fábrica → spec-driven-development é dono do formato SPEC e da mecânica dos portões; BMad fornece o protocolo de plano de controle ao redor deles.
• Você está executando um fluxo de entrega de issue para PR com seus próprios portões → neckbeard. BMad o complementa; não execute dois ciclos de vida de entrega concorrentes.
• Você precisa de revisão independente → role-play não é independência. Use agent-council, avaliadores separados ou agent-evals-and-observability; nunca reivindique separação de persona como revisão independente.
• Operando o instalador/ferramentas oficiais do BMad → esta skill emula o método; ela não instala ou opera pacotes npm bmad-method.

Desvio de versão e atribuição

BMad está evoluindo ativamente (repositório oficial: bmadcode/bmad-method; BMAD™ e BMAD-METHOD™ são marcas registradas da BMad Code, LLC). Artigos mais antigos diferem em expansão de nome, agentes, nomes de arquivos e comandos. Ao instalar as ferramentas oficiais, trate a documentação oficial e o código-fonte instalado como autoritativos. Esta skill é uma destilação original do método como um protocolo agnóstico a harness; ela não reproduz conteúdo do instalador oficial.