Módulos avançados: Builder, Test Architect e Loop

Pense em três necessidades diferentes. Sua empresa repete um procedimento e quer transformá-lo em um assistente? Examine o Builder. Seu produto exige mais cuidado com falhas e você precisa decidir o que testar primeiro? Examine o Test Architect. Seu plano já está suficientemente claro e você quer encadear várias entregas sem acompanhar cada conversa? Examine o Loop. Essas são as especialidades declaradas na tabela BMad Ecosystem, não três etapas obrigatórias do método.

As recomendações da tabela são critérios editoriais do guia, derivados das funções dos módulos. Para testes, existe uma recomendação explícita da documentação: a maioria dos projetos deve começar por bmad-qa-generate-e2e-tests, incluída em bmm, e usar TEA quando a geração mais elaborada fizer sentido.

Antes de usar os Pedidos em seu projeto, deixe o BMAD instalado conforme a Aula 04 · Instalação no macOS e entenda como salvar alterações conforme a Aula 05 · Git e GitHub. Para compreender o percurso da ideia à entrega, consulte a Aula 06 · Fluxo completo, da ideia ao go-live. Esta aula pressupõe esse ambiente; não ensina novamente sua instalação.

Vamos usar um negócio fictício: a Oficina Aurora, que quer organizar pedidos de manutenção. O Builder pode ajudar a padronizar a triagem das solicitações; o TEA, a verificar orçamento, autorização e encerramento; o Loop, a construir uma sequência já planejada de melhorias no sistema. Os nomes de pastas e arquivos desse exemplo são escolhas didáticas, não saídas obrigatórias dos módulos.

/bmad-help Estou avaliando os módulos Builder, Test Architect e Loop para o sistema da Oficina Aurora. Confira as versões e as skills disponíveis nesta pasta. Use a fonte do BMAD 6.12.4 e as tags dos módulos registradas no manifesto; se uma documentação apontar para outra versão, diga a diferença. Minha necessidade atual é padronizar a triagem das solicitações de manutenção. Recomende apenas o recurso que ajuda nisso agora, explique o motivo e diga o que posso deixar para depois. Não instale nem execute setups nesta conferência. Responda em português do Brasil.

bmad-help consulta o catálogo, configurações e artefatos do projeto — arquivos que registram resultados do trabalho para recomendar os próximos recursos. A existência de um arquivo não é prova de que uma etapa terminou: suas instruções mandam procurar evidências de conclusão. Abra uma conversa nova quando passar a uma skill de execução.

Quando a ajuda e esta aula discordarem: a ajuda também pode consultar a documentação indicada pelo módulo nas linhas _meta de seu catálogo. Esses endereços podem acompanhar a documentação atual, sem fixar a versão instalada. Peça a comparação com os arquivos locais e as tags desta aula antes de trocar um nome de skill ou um procedimento. Isso não torna a ajuda inútil; esclarece qual versão sua orientação precisa explicar.

Conferência da Etapa:

• você sabe qual problema quer resolver, consegue explicar por que o método básico não basta nesse ponto e reconhece que instalar o módulo não comprova que ele funciona no seu ambiente.

O desenho é uma simulação didática da decisão, baseada no registro de módulos, no instalador e nas skills de setup; não representa uma instalação executada.

Os três módulos são mantidos em repositórios oficiais diferentes. Repositório é a pasta com arquivos e histórico de um projeto; no GitHub, você consulta uma cópia publicada desse histórico. Versão fixada é a escolha de uma edição específica, em vez de aceitar automaticamente a mais recente.

As versões e origens da tabela foram lidas em _bmad/_config/manifest.yaml e comparadas aos repositórios oficiais. Esse arquivo é o manifesto, o inventário da instalação. O comentário Version: 6.12.4 nos arquivos config.yaml dos módulos identifica o instalador que os gerou; não significa que o TEA ou o Builder tenham versão 6.12.4.

No registro da 6.12, tea está fixado em v1.27.2. Builder e Loop seguem o canal stable por padrão. Canal é uma regra para escolher uma versão: nesta implementação, stable consulta tags do GitHub e escolhe a maior versão numérica válida sem indicação de prévia, como alpha, beta ou rc; next acompanha a ponta do desenvolvimento. Uma tag não precisa ter uma página de lançamento no GitHub para entrar nessa escolha. Portanto, fixar o instalador em bmad-method@6.12.4 não fixa sozinho todos os módulos externos. Para reproduzir esta aula, você também precisa dos três números da tabela.

Quando a origem não tem tag estável: o resolvedor pode devolver o canal next, sinalizando que recorreu a outra origem. Por isso, a palavra stable sozinha não é prova de uma versão estável efetivamente instalada. Leia o aviso, confira a tag e a revisão registradas no manifesto e interrompa a reprodução da aula se o resultado divergir. A escolha explícita por --pin é o caminho apresentado aqui para evitar depender dessa resolução automática. Essa condição foi conferida no código, sem provocar uma instalação de teste.

O instalador aceita --pin CODE=TAG, repetido para módulos diferentes. Flag é uma opção acrescentada a um Comando; tag é o nome de uma referência no histórico, frequentemente usada para identificar uma versão. Assim, --pin tea=v1.27.2 fixa o TEA. --channel stable e seu equivalente --all-stable escolhem o canal estável; --channel next e --all-next escolhem o canal de desenvolvimento; --next bmb faz essa escolha para um módulo. Há uma precedência importante: as opções globais --channel e --all-* não anulam o pin do registro oficial; --pin e --next para o módulo podem substituí-lo. Usar canais, em vez das tags explícitas desta aula, não garante a mesma combinação de versões. Não misture as opções por tentativa.

Em 15/11/2026, a consulta de leitura npm view bmad-method dist-tags --json, repetida nesta revisão, retornou latest: 6.12.4. Isso registra o que estava disponível na conferência. Se houver outra versão quando você ler a aula, mantenha os números conferidos para estudar este procedimento; atualizar exige conferir novamente a compatibilidade. A consulta lê metadados do pacote e não executa o instalador.

Conferência da Etapa:

• você distingue versão do método, versão do módulo e versão do orquestrador, o programa que coordena a sequência de trabalho e que o setup do Loop instala depois.

Faça esta etapa na pasta do projeto de estudo. O instalador da 6.12 oferece a ação Modify BMAD Installation, correspondente a --action update, para revisar a seleção. A ação Quick Update, correspondente a --action quick-update, atualiza o conjunto já instalado e preserva suas configurações; ela não abre a seleção para acrescentar um módulo.

Confira se esta é a pasta do meu projeto de estudo e leia o manifesto da instalação do BMAD. Acrescente somente o módulo bmb na versão v2.2.2, usando o instalador bmad-method@6.12.4 em atualização completa. Preserve os outros módulos, as ferramentas de IA e as configurações já escolhidas; não substitua a lista existente por apenas bmb. Mantenha a conversa e os documentos em português do Brasil. Não execute bmad-bmb-setup nem avaliadores. Ao terminar, mostre as versões registradas e os caminhos das cinco skills do Builder.

Para o TEA, use o mesmo Pedido trocando o objetivo por “acrescente tea na versão v1.27.2” e peça a conferência do agente e dos nove fluxos. Para o Loop, peça “acrescente bmad-loop na versão v0.13.2” e escreva expressamente “não execute bmad-loop-setup”. Essas frases são exemplos autorais. O instalador registra um aviso de ação pendente para o Loop: as skills de automação dependem do setup para funcionar.

Esse Comando pressupõe uma instalação existente. No menu, mantenha os módulos e ferramentas que já usa e selecione somente a extensão necessária. Informar três versões com --pin não obriga selecionar os três módulos; o instalador pode avisar que uma fixação corresponde a um módulo não selecionado. O ponto em --directory . representa a pasta atual do terminal. npx executa um programa fornecido por um pacote npm, localizado no ambiente ou obtido do registro, e é usado pelo instalador oficial. A seleção interativa não foi executada nesta revisão.

Se você quiser automatizar a instalação pelo terminal depois de conferir tudo, existem estas opções. Não é necessário decorá-las; elas ajudam a entender o Comando que o Claude Code montar:

Há uma armadilha específica: numa instalação existente, --yes sem --action update pode escolher Quick Update mesmo que você tenha escrito --modules. O código só força atualização completa automaticamente para certas opções, como --custom-source. Por isso, a ação explícita faz parte do procedimento de acrescentar ou retirar módulos.

O que deve existir ao terminar, segundo a fonte: os módulos escolhidos constam no manifesto; seus diretórios têm configuração e catálogo; as skills ficam na pasta correspondente à ferramenta de IA. Essa é a conferência esperada, não uma saída capturada nesta aula.

Conferência da Etapa:

• a seleção preservou os módulos necessários, os números conferem e nenhum setup adicional foi confundido com parte automática desta instalação.

No projeto conferido, _bmad/bmb/, _bmad/tea/ e _bmad/bmad-loop/ contêm config.yaml e module-help.csv. O primeiro guarda configurações do módulo; o segundo é um catálogo de recursos e orientação. As instruções completas estão em .claude/skills/<nome-da-skill>/SKILL.md; para outras ferramentas, como Codex, o instalador também pode usar .agents/skills/. A documentação do Claude Code confirma a estrutura de skills por projeto com um arquivo SKILL.md por pasta.

Divergência documentada: o desenho em docs/customize/add-modules.md mostra skills dentro de _bmad/<módulo>/. No instalador desta versão, _cleanupSkillDirs remove essas cópias depois de preparar as pastas das ferramentas de IA. Portanto, não conclua que uma instalação está quebrada porque não encontrou SKILL.md dentro de _bmad/bmb/. Confira .claude/skills/.

Há também _bmad/config.toml, uma configuração central. TOML e YAML são formatos de texto para registrar opções com nomes e valores. O resolvedor do método combina a configuração central, a pessoal e as substituições em _bmad/custom/; algumas skills de módulos ainda leem seus próprios arquivos YAML. Portanto, siga o arquivo que a skill instalada manda ler, em vez de supor que todo recurso interpreta a mesma configuração da mesma maneira.

Confira a instalação sem alterar arquivos. Leia o manifesto e localize as skills do módulo que acabei de adicionar. Compare seus nomes com o module-help.csv, mas confirme cada recurso no SKILL.md real. Diga qual configuração cada skill usa, a versão instalada e qualquer diferença entre o catálogo e o código. Não execute as skills nem setups para fazer essa conferência.

Para retirar um módulo, repita a atualização completa e desmarque somente o módulo que quer remover. A remoção apaga a pasta _bmad/<módulo> inteira: se você guardou trabalho autoral indevidamente ali, copie-o para uma pasta própria antes. Pedir “preserve meus arquivos” não muda esse comportamento do instalador. No terminal, use o Comando da Etapa 03 e revise a seleção. Pelo chat, você pode usar este Pedido:

Quero remover o módulo bmb deste projeto de estudo. Confira o manifesto e use a atualização completa do instalador bmad-method@6.12.4 para retirar apenas esse módulo, preservando os demais módulos e ferramentas. Preserve meus arquivos de trabalho e os recursos autorais. Ao terminar, confira o manifesto e as pastas de skills. Se encontrar componentes instalados por um setup separado, descreva-os antes de propor sua remoção.

Esse Pedido é um exemplo autoral para Builder. Substitua o código somente depois de saber qual módulo deseja retirar. Remover o módulo pelo instalador não é uma garantia de desfazer instalações globais, hooks ou arquivos produzidos por seus fluxos. Hook é uma ação automática disparada em um evento da ferramenta; pode continuar existindo fora da pasta do módulo. O caso do Loop exige examinar separadamente programa, configuração do projeto e hooks.

Outra divergência: o fim de docs/reference/skills-and-agents.md diz que o instalador não apaga diretórios antigos de skills. O código 6.12.4 faz limpeza a partir dos identificadores registrados anteriormente e reinstala o conjunto selecionado. Isso não permite prometer que qualquer pasta desconhecida será removida. Confira o resultado, mas não apague toda .claude/skills/, que pode conter recursos seus.

Conferência da Etapa:

• você localiza as instruções reais, sabe qual configuração elas usam e distingue retirar um módulo de desfazer tudo que já foi feito por ele.

Além da lista oficial, o instalador recebe uma origem Git ou uma pasta local pela opção --custom-source. Um módulo compartilhado por outra pessoa entra pelo mesmo caminho. A documentação orienta confiar na origem antes de instalar e informa que uma origem por endereço pode ser apresentada como módulo não verificado. Um texto de instruções também pode orientar a IA a ler arquivos e executar programas; por isso, examine o conteúdo que está acrescentando.

Você não precisa publicar algo na internet para experimentar um módulo do Builder. Pode manter o código em uma pasta própria e instalá-lo em outra pasta de estudo. A origem local é referenciada pelo caminho; ao alterar o módulo, a reinstalação lê os novos arquivos. Se apagar a origem, o instalador preserva os arquivos instalados e pula sua atualização até a origem voltar a existir.

Quero experimentar o módulo autoral da Oficina Aurora em uma pasta de estudo separada. Primeiro localize a pasta-fonte que contém as skills e confira seu conteúdo. Verifique se já existe BMAD no destino. Se existir, leia o manifesto e monte a lista completa de módulos a preservar; use --action update e --modules com essa lista. Use o instalador bmad-method@6.12.4 com --custom-source apontando para a origem autoral. Mostre quais módulos foram descobertos, quais arquivos foram instalados e qual origem foi registrada no manifesto. Não publique o módulo nem execute os recursos instalados.

Substitua os dois caminhos antes de copiar. Este exemplo instala o núcleo e o módulo autoral; não inclui necessariamente bmm. Para uma instalação existente, use o Pedido anterior, que exige primeiro ler o manifesto e montar a lista completa a conservar. O Comando equivalente deverá incluir --action update e --modules com essa lista real. Sem --modules nem --yes, o ramo de atualização com --custom-source começa com a lista oficial vazia e acrescenta a origem personalizada e o núcleo: não oferece um menu posterior para resgatar os módulos omitidos. Por isso, o Comando simples acima fica restrito à pasta nova.

O instalador tem dois modos de descoberta. Se a origem contém .claude-plugin/marketplace.json, lê a lista de pacotes e oferece os encontrados. Sem esse arquivo, procura diretórios com SKILL.md e trata a origem como um módulo direto. O nome .claude-plugin é uma convenção desse instalador; não obriga usar Claude como ferramenta de IA.

Uma origem por Git também aceita @ref, por exemplo https://github.com/organizacao/repositorio@v1.0.0; esse endereço é ilustrativo, não um repositório recomendado. Ref é uma referência do histórico, como uma tag. As origens podem ser separadas por vírgulas. Em execução sem perguntas, todos os módulos descobertos nas origens são instalados; uma origem que falha pode ser ignorada enquanto as demais continuam. Leia o relatório final: terminar não significa que todos os módulos pretendidos entraram.

Para manutenção, a atualização rápida tenta atualizar as origens registradas. Se uma origem Git não estiver acessível, pode usar a cópia em cache, isto é, uma cópia local guardada de uma leitura anterior, com aviso. A atualização completa permite mudar a seleção. A capacidade de repetir uma instalação depende de conservar as origens e as versões, não apenas o Pedido usado naquele dia.

Conferência da Etapa:

• você conhece a procedência do módulo, sabe onde está sua pasta-fonte e conferiu o que foi efetivamente descoberto e instalado. Esta aula não executou esse procedimento.

Minha recomendação para o empresário é começar por uma tarefa que já foi feita algumas vezes e cuja qualidade você sabe reconhecer. Se a equipe ainda não concorda sobre o processo, primeiro esclareça o processo. Se o pedido só vai acontecer uma vez, faça o pedido diretamente à IA. O próprio Workflow Builder orienta examinar se a ideia merece uma skill, se é uma tarefa isolada e quem receberá o resultado; ele pede conhecimento real da empresa, como procedimentos, exemplos e correções feitas durante o trabalho.

Vamos continuar com a Oficina Aurora, nossa empresa fictícia de manutenção comercial: ela recebe pedidos vagos de orçamento. O vendedor entrevista o cliente, outro funcionário interpreta as anotações e alguém descobre depois que faltava informação. A primeira skill poderia transformar as anotações em um diagnóstico padronizado: o que o cliente pediu, o que falta saber, quais condições afetam o serviço e quais pontos precisam de aprovação humana. Não precisa começar com cinco agentes nem fazer o sistema enviar propostas sozinho. Esse recorte e os nomes dos exemplos a seguir são escolhas didáticas desta aula.

O que foi conferido: as cinco skills estão instaladas no projeto. A comparação desta revisão encontrou conteúdo idêntico nos 123 arquivos distribuídos nas cinco pastas, incluindo seus SKILL.md, em relação à tag oficial v2.2.2. O manifesto registra v2.2.2 e o commit 4a1422274a2acb0fb0ec0511753da6263948f072. Nenhuma delas foi executada para esta aula. Os resultados abaixo são os previstos nas instruções, e não saídas observadas em uma experiência prática.

O catálogo module-help.csv do Builder não lista bmad-eval-runner, embora a skill esteja instalada. Para inventariar os recursos, confira também as pastas de skills: a ausência de uma linha na ajuda não prova ausência do recurso.

Um script é um programa auxiliar que automatiza uma tarefa. O Builder chama scripts por uv run; uv é o gerenciador que prepara o ambiente Python para executá-los. Antes de usar criação ou análise, peça ao Claude Code para conferir o uv e os requisitos declarados nos scripts envolvidos. Os requisitos variam: o README da tag orienta Python 3.11 ou posterior, enquanto scripts individuais podem declarar outros mínimos. Esta aula não instalou nem testou essas dependências.

Antes do Pedido, prepare três coisas: um exemplo de entrada, um exemplo de resultado considerado bom e os erros que a empresa não aceita. No nosso caso, a entrada é uma anotação de atendimento; o resultado é um diagnóstico; o erro inaceitável é inventar prazo ou preço quando isso não foi informado. Esses materiais dão ao Builder conhecimento específico, em vez de obrigá-lo a adivinhar como a empresa trabalha.

/bmad-workflow-builder Quero criar uma skill chamada com-diagnostico para uma empresa de manutenção comercial. Ela recebe anotações de atendimento e produz um diagnóstico com: necessidade do cliente, informações confirmadas, lacunas, riscos para o serviço e próximos passos. Nunca deve inventar preço, prazo, visita realizada ou aprovação do cliente. Vou fornecer um atendimento anonimizado e um diagnóstico considerado bom. Comece pela versão mais simples, explique as decisões e mantenha o envio ao cliente fora do escopo.

O identificador bmad-workflow-builder é conferido na instalação. O nome com-diagnostico e todo o texto depois da skill são exemplos desta aula. O Builder aceita uma descrição inicial; para alterar ou analisar algo existente, aceita o caminho da skill e palavras que deixem clara a intenção. Ele distingue Build, para construir; Edit, para alterar; e Analyze, para examinar a qualidade. Build e Edit usam o mesmo processo, aplicado a uma ideia nova ou a um trabalho existente.

No caminho interativo, o Builder abre espaço para você explicar a necessidade e as referências. Depois trabalha em ciclos: entende o resultado, examina se a ideia faz sentido, propõe capacidades que faltaram, registra as decisões, escreve a menor versão útil e procura evidências para justificar mais estrutura. O código instalado diz expressamente que esse processo não é uma sequência fixa de fases. Assim, não espere um questionário com o mesmo número de perguntas em toda execução.

O Builder registra as decisões em .memlog.md, dentro da pasta da skill construída. Esse arquivo é um diário do trabalho de construção: permite retomar a conversa sem depender apenas do histórico do chat. Uma skill nova usa a pasta configurada em bmad_builder_output_folder; no projeto conferido, ela é {project-root}/skills. Aqui, {project-root} significa a raiz do projeto. Uma skill existente conserva seu próprio caminho.

Para alterar o fluxo, diga o que muda e o que precisa continuar verdadeiro. Para analisar, peça análise e forneça o caminho. São pedidos distintos:

/bmad-workflow-builder Edite a skill em skills/com-diagnostico. Acrescente uma seção de informações que dependem de visita técnica. Preserve a proibição de inventar preço e prazo. Mostre quais arquivos mudaram e registre o motivo da alteração.

/bmad-workflow-builder Analise a skill em skills/com-diagnostico. Quero identificar instruções contraditórias, etapas desnecessárias e situações em que ela poderia preencher uma lacuna como se fosse um fato. Entregue o relatório de análise antes de propor alterações.

Analyze combina verificações por scripts com cinco perspectivas: excesso de instruções; organização; tarefas que deveriam ser resolvidas de forma previsível por código; customização; e oportunidades de melhoria. Produz findings.json, skill-analysis-report.html e skill-analysis-report.md em uma pasta .analysis/<data-hora>/ junto à skill analisada. O relatório avalia as instruções e a estrutura; não prova, por si só, que a skill funcionará bem em atendimentos reais.

Criar, editar e validar não são três botões universais. Para uma skill que produz documentos, o Builder recomenda separar as intenções de criar, atualizar e validar: criar começa um trabalho; atualizar modifica um artefato existente; validar o examina contra os padrões. Esse é um padrão que você pode pedir para a skill gerada. Na própria ferramenta Workflow Builder, os nomes conferidos são Build, Edit e Analyze. Não invente um comando C, E ou V supondo que todas as skills o reconheçam.

Há uma escolha adicional: a skill será fixa ou permitirá customização por outras equipes? O padrão é não criar uma superfície de customização sem necessidade. Se você a quiser, o Builder gera customize.toml e pontos de extensão apropriados, como modelos e caminhos de saída. As alterações da equipe ficam em _bmad/custom/<nome-da-skill>.toml; as pessoais, em _bmad/custom/<nome-da-skill>.user.toml. O customize.toml distribuído com a skill é a base gerada e pode ser substituído numa atualização. Não confunda essa customização da skill construída com a configuração do próprio Builder.

Sobre -H e --headless: as duas formas pedem que o Builder trabalhe sem conversa interativa. Elas fazem sentido quando a descrição, as entradas e as regras já estão claras. Em Build e Edit, a resposta final desse caminho é um objeto JSON, isto é, dados organizados em campos, com estado, intenção e caminhos. Pode ser complete ou blocked, quando faltam condições para concluir. Analyze também tem uma resposta estruturada, mas usa campos próprios, como avaliação, contagem de problemas e caminhos dos relatórios; não presuma que todos os caminhos devolvem o mesmo formato. No primeiro uso, recomendo o caminho interativo: o ganho está justamente em decidir bem o processo.

Na entrega interativa, o Workflow Builder manda executar verificações de estrutura, convenções de caminhos e scripts; problemas graves devem ser corrigidos. Se a skill criada contiver scripts, também pede seus testes. Depois oferece a análise completa. Essas verificações da construção e a análise das instruções não equivalem a testar todos os resultados de negócio.

Antes de seguir, confira se você consegue explicar o resultado da skill em uma frase, forneceu exemplos sem dados sensíveis, sabe onde ela grava e revisou o diário de decisões. Construir a pasta da skill não significa instalá-la automaticamente em todas as ferramentas. A documentação da versão orienta colocá-la no diretório de skills reconhecido pela ferramenta; para Claude Code, cita .claude/skills/. Faça isso com uma skill sua, preservando as pastas do BMAD gerenciadas pelo instalador.

Se a primeira tentativa ficar grande demais: volte ao atendimento que motivou a skill e identifique o problema concreto. A fonte orienta acrescentar estrutura quando a comparação entre versões mostra uma falha, e não apenas porque existem mais recursos disponíveis. Para uma empresa pequena, um diagnóstico com poucas seções e revisão humana pode ser suficiente. Em uma operação com várias equipes, modelos de saída e padrões compartilhados podem justificar customização. O tamanho da empresa é uma pista; a evidência de uma necessidade repetida é o critério desta recomendação.

Use bmad-agent-builder quando a identidade e a forma de trabalhar do especialista fazem parte do valor. No exemplo comercial, isso poderia ser um supervisor que ajuda o vendedor a perceber lacunas e formular perguntas melhores. Se você precisa apenas converter anotações em um documento padronizado, o fluxo anterior pode bastar. O próprio Agent Builder examina se a necessidade é recorrente, se a memória trará valor e se o escopo pede um agente ou mais de um.

/bmad-agent-builder Quero criar o agente com-agent-supervisor para ajudar vendedores a revisar diagnósticos de manutenção comercial. Ele deve conversar de forma direta, explicar por que cada informação importa e apontar lacunas antes da proposta. Cada atendimento é independente; comece sem memória entre sessões. Quando houver uma skill com-diagnostico disponível, avalie se deve reutilizá-la. Ele não pode prometer preço, prazo nem enviar mensagens ao cliente.

O nome e o caso são exemplos. A skill aceita descrição inicial, caminho de agente existente e intenção de criar, editar, analisar ou reconstruir. Editar preserva a identidade e muda comportamentos específicos. Reconstruir volta ao objetivo e à identidade, usando o agente antigo como referência, sem conservar automaticamente sua estrutura. Analisar produz um relatório, em vez de ser um pedido para refazer o agente.

O Builder não pede que você escolha uma arquitetura por um nome difícil logo na entrada. Ele descobre três necessidades: lembrar entre sessões, aprender novas capacidades depois de instalado e agir sem alguém conversando naquele momento. Dessas respostas surgem as variantes abaixo.

O termo sanctum é o nome que o Builder dá à pasta de memória de execução do agente. O caminho previsto é _bmad/memory/<nome-da-skill>/. Ela contém arquivos para identidade, regras, relacionamento com o usuário, memória acumulada, capacidades e índice; o agente autônomo acrescenta PULSE.md. Isso é diferente de .memlog.md: o primeiro conjunto guarda o estado do agente em uso; o segundo registra as decisões tomadas por quem o construiu. Não coloque dados reais de clientes ali sem decidir o que deve ser guardado, quem poderá ler e quando será removido.

Também há duas experiências de primeira utilização, chamadas First Breath, ou configuração inicial. A de calibração se destina a uma relação mais profunda e continuada; a de configuração é mais curta e adequada a um especialista focado. Permitir que o agente aprenda novas capacidades é outra decisão, separada da memória: o Builder pode incluir a orientação para acrescentá-las depois. Não marque todas as opções só porque estão disponíveis.

Como decidir se precisa de memória: pense no trigésimo uso. Se o supervisor puder avaliar esse atendimento apenas com as anotações e as regras atuais, o caminho sem memória continua adequado. Se precisar considerar acordos e preferências acumulados em sessões anteriores, há motivo para estudar memória. A própria referência propõe comparar a primeira sessão com a trigésima. Se você mudar de ideia depois e passar de um agente sem memória para um com memória, a orientação instalada trata isso como reconstrução, pois muda a estrutura do agente.

PULSE também precisa de uma forma de iniciar a execução. O modelo PULSE-template.md descreve frequência, tarefas e períodos de silêncio, e wake-template.py escolhe o modo quando é chamado com --pulse. Esses arquivos não instalam, por si, um agendador que acorde o agente. Portanto, escrever “verifique toda segunda-feira” no agente não comprova que ele será iniciado naquele horário. A configuração do agendamento depende do ambiente que chamará a skill; não foi montada nem testada nesta aula.

Para capacidades específicas, o Builder decide entre escrever uma capacidade interna e referenciar uma skill já instalada. Quando houver dependências externas, ele sugere o Module Builder para distribuir o conjunto. O resultado inclui SKILL.md, referências e recursos necessários; agentes gerados sempre têm o bloco de metadados, isto é, informações de identificação, chamado [agent] em customize.toml, enquanto os pontos de customização de comportamento dependem da decisão tomada na construção.

Analyze usa seis perspectivas em todos os agentes e uma sétima para os que têm memória. Além de estrutura e qualidade das instruções, examina se a personalidade combina com as capacidades. Os relatórios ficam em .analysis/<data-hora>/, com findings.json, agent-analysis-report.html e agent-analysis-report.md. Ao alterar um agente que já possui memória, observe um detalhe: mudar os modelos de memória afeta futuras inicializações; não significa que os arquivos de memória em uso foram automaticamente atualizados.

Não confunda autonomias. -H ou --headless tornam a construção pelo Builder não interativa. --pulse pertence à ativação do agente autônomo criado. Nenhuma dessas expressões significa, por si só, executar um épico de software — um conjunto de entregas relacionadas a um objetivo — com o módulo Loop. São recursos com propósitos diferentes.

Você não precisa de um módulo para usar uma única skill pessoal. O empacotamento ganha valor quando várias pessoas ou projetos precisam instalar um conjunto coerente e encontrá-lo na ajuda. bmad-module-builder oferece três caminhos: IM, planejar o módulo; CM, criar sua infraestrutura a partir das skills; e VM, validar a estrutura e os registros. Planejar não constrói todas as skills automaticamente, e criar o módulo não substitui a construção delas.

/bmad-module-builder Quero planejar um módulo comercial de código com. A primeira necessidade é transformar atendimentos em diagnósticos; a segunda é revisar as lacunas com um supervisor. Compare uma única skill com duas skills, explique o custo de manutenção de cada escolha e produza um plano com entradas, saídas, limites e ordem de construção. Não inclua envio de mensagens nem aprovação automática de propostas.

IM explora a ideia, fixa nome e código do módulo, examina a organização e a memória, detalha configurações e dependências, descreve cada skill, revisa as capacidades e fecha um plano. O plano é salvo na pasta de relatórios configurada; no projeto lido, skills/reports. Cada descrição de skill deve ser suficiente para que o Agent Builder ou o Workflow Builder possa construí-la depois. O código do módulo deve ser escolhido cedo porque orienta os nomes; bmad- é reservado às criações oficiais.

Há decisões que merecem tempo nessa conversa. Um agente com várias capacidades simplifica a experiência quando tudo pertence ao mesmo domínio. Agentes separados podem fazer sentido se as especialidades, os usuários ou as memórias forem diferentes. Vários fluxos podem fazer sentido quando os resultados e as ferramentas necessárias são diferentes. Se houver vários agentes, o plano deve dizer se cada um mantém memória própria, se há memória compartilhada e como um passa trabalho para outro. A documentação admite um agente coordenador, mas apresenta o custo adicional dessa escolha.

Depois de construir e revisar as skills, use CM:

/bmad-module-builder Crie a infraestrutura do módulo a partir das skills autorais com-diagnostico e com-agent-supervisor já construídas sob skills. Use o código com. Localize em skills/reports o plano desse módulo e confira que ele está aprovado. Não inclua outras skills que por acaso existam na pasta. Identifique se é um módulo de uma skill ou de várias. Mostre a configuração, os registros de ajuda e as dependências antes de escrever a estrutura final.

Se houver várias skills, CM gera uma skill de configuração <código>-setup, com SKILL.md, scripts de integração, assets/module.yaml e assets/module-help.csv. Se houver uma só, pode acrescentar o registro ao próprio pacote: assets/module-setup.md, os arquivos de configuração e ajuda, scripts de integração e ../.claude-plugin/marketplace.json para distribuição. Nesse caminho, .. indica a pasta imediatamente acima da skill: o manifesto não fica dentro dela. O primeiro uso pode registrar o módulo se faltar configuração; os argumentos setup e configure permitem configurar de novo.

Quando pular o planejamento de módulo: se você já tem uma única skill pessoal útil, pode continuar usando-a sem IM, CM ou VM. Se as skills já estão prontas e o conjunto está bem definido, CM aceita o caminho delas mesmo sem um plano anterior; a própria referência, porém, recomenda fornecer o plano quando ele existe, porque carrega identidade, dependências e ordem das capacidades. Em um conjunto maior, faça a conferência por skill: quais entradas recebe, qual resultado entrega, do que depende e quem usa esse resultado. Empacotar várias pastas sem responder a isso produz um catálogo difícil de manter.

module.yaml descreve a identidade do pacote e as perguntas de configuração. module-help.csv registra suas capacidades para a ajuda. As opções podem ser texto, escolha única (single-select), múltipla escolha (multi-select) ou confirmação (confirm); também podem exigir preenchimento, validar o formato, apresentar exemplo, criar diretórios e mostrar notas após a instalação. Uma variável com user_setting: true vai para a configuração pessoal. Você não precisa usar todas essas possibilidades: cada pergunta acrescenta uma decisão para quem vai instalar.

Se o módulo depender de ferramentas externas, serviços ou uma interface própria, o Builder captura essas necessidades, mas avisa que a configuração gerada pode exigir ajustes manuais para atendê-las. Um pacote com conexão ao sistema financeiro da empresa, por exemplo, não passa a ter essa conexão só porque foi empacotado.

Em seguida, use VM:

/bmad-module-builder Valide o módulo com cuja infraestrutura foi criada sob skills na etapa anterior. Confira se todas as capacidades estão registradas, se os nomes e caminhos existem e se as relações entre as skills fazem sentido. Apresente os problemas antes de qualquer correção e salve o relatório na pasta de relatórios configurada.

VM procura a estrutura apropriada para uma ou várias skills, confere os metadados, registros ausentes ou duplicados, referências entre capacidades e coerência do cadastro dos agentes. Combina uma verificação por script com leitura crítica das descrições. A referência oferece salvar o relatório como module-validation-<código>-<data>.md na pasta de relatórios; o Pedido acima já declara que você quer esse arquivo. Isso valida a embalagem e os registros. A qualidade dos resultados reais das skills precisa de exemplos e avaliações próprios.

Atenção a uma divergência da versão: o SKILL.md anuncia -H para CM e VM, mas sua regra final de ativação manda --headless ou -H diretamente para CM. Por isso, os exemplos desta aula pedem a validação explicitamente e sem essa opção. Para CM sem interação, a referência exige o código do módulo e um caminho de skills ou informações suficientes num plano; nome, descrição, versão inicial e ordem podem ser inferidos e devem aparecer como suposições na resposta. Não use esse modo para pular decisões ainda abertas.

bmad-bmb-setup não é o comando geral de instalação do BMAD. É a skill de configuração do Builder depois que suas skills estão disponíveis. Ela coleta preferências e integra os dados no projeto. O projeto usado como fonte já tem _bmad/bmb/config.yaml; os builders conseguem ler esse formato antigo como alternativa. Portanto, não trate rodar o Setup como uma obrigação antes de qualquer tentativa de usar o Builder na instalação 6.12.4.

O Setup pode produzir uma migração, isto é, trocar a organização antiga por uma nova organização de arquivos. Ele escreve as configurações compartilhadas em _bmad/config.yaml, as preferências pessoais em _bmad/config.user.yaml e as capacidades em _bmad/module-help.csv. Nome e idioma da conversa ficam exclusivamente no arquivo pessoal; idioma dos documentos e pasta de saída ficam no compartilhado. As preferências específicas do Builder são a pasta das skills geradas e a dos relatórios, cujos padrões são skills e skills/reports na raiz.

Ao coletar preferências, o setup dá prioridade à configuração nova já existente; depois aproveita o YAML legado; por último, usa os padrões de module.yaml. Só migra as chaves pertencentes ao esquema atual. Uma chave antiga desconhecida não ganha preservação automática por estar no arquivo anterior. Confira esse resultado antes da limpeza.

Antes de decidir pela migração, use um Pedido de inspeção. O texto abaixo pede leitura e proíbe a execução do Setup: o objetivo é entender o procedimento antes de aplicá-lo.

Leia a skill bmad-bmb-setup instalada neste projeto, os scripts que ela chama e a configuração atual, sem executá-la. Liste os arquivos que seriam criados, alterados ou removidos, inclusive core e _config. Confira como as outras skills instaladas carregam configuração e onde está o manifesto de versões. Proponha uma forma de testar a migração numa cópia do projeto antes de aplicá-la ao projeto de trabalho.

Quando houver uma decisão explícita de executar essa migração num projeto apropriado, o Pedido pode chamar bmad-bmb-setup e informar idioma e pastas desejadas. A skill aceita valores na própria mensagem, --headless ou uma instrução para aceitar os padrões; nesses casos pula as perguntas, mas ainda deve mostrar o resumo do que fez. Não use a ausência de perguntas como justificativa para deixar de revisar as remoções.

Uma avaliação, chamada eval, é um caso com entrada, critérios de aprovação e, quando necessário, arquivos de exemplo. O bmad-eval-runner executa casos já definidos; se não encontrar os casos, para em vez de inventá-los. O arquivo de casos previsto pelos builders é evals/cases.json dentro da skill criada. O runner, isto é, o executor dos casos de avaliação, também aceita um caminho explícito e procura casos em outros locais documentados.

Para o diagnóstico comercial, bons critérios seriam “identifica que o endereço não foi informado”, “não inventa valor” e “separa o prazo solicitado pelo cliente de um prazo aceito pela empresa”. “O texto está bom” é difícil de verificar; “o arquivo existe” pode aprovar até um arquivo vazio. Esses são exemplos didáticos da diferença entre critérios discriminantes e fracos descrita na referência.

Para preparar os casos sem transformar esta aula em programação, descreva situações como estas. Elas são exemplos autorais, ainda não executados:

O runner permite um state_prefix, um trecho que informa em que ponto da conversa o caso começa. Isso ajuda a representar uma correção ou retomada sem reproduzir toda a conversa. Não comprova, porém, que o agente conduzirá bem uma relação inteira: a referência ressalva situações em que o percurso da conversa é o próprio resultado. Para habilidades subjetivas, como a qualidade da conversa de um supervisor, a fonte prevê julgamento humano. Você pode conferir critérios objetivos do diagnóstico e, separadamente, pedir a um vendedor experiente que avalie a utilidade das perguntas.

As opções expostas pela skill são: caminho da skill; --evals para escolher os casos; --mode para selecionar um ou mais modos; --variant-path para comparar versões; --project-root para indicar o projeto; --output-dir para escolher o destino; --runs para repetir os casos; e --headless ou -H para produzir o resultado sem confirmações interativas. Se houver configuração de relatórios, o destino padrão é <bmad_builder_reports>/eval-runs/; caso contrário, ~/bmad-evals/, dentro da pasta pessoal do usuário. As execuções mantêm transcrição, arquivos produzidos e medidas; grading.json aparece quando a avaliação de qualidade é realizada.

Uma repetição não elimina a variação das respostas. A opção --runs existe para repetir os casos e permitir examinar a dispersão dos resultados. Como baseline executa cada caso com e sem a skill, três casos repetidos três vezes implicam 18 chamadas da ferramenta de IA, antes de eventuais avaliações adicionais. É uma conta derivada do modo de execução, não uma previsão de preço. Comece com poucos casos representativos, examine os registros e amplie quando a dúvida justificar.

A separação de pastas também não transforma os arquivos originais em somente leitura. No código conferido, stage_skill tenta criar um link simbólico — uma referência à pasta original — e só copia a skill se isso falhar. Esse trecho não aplica uma proteção de escrita ao destino. Assim, “diretório limpo para o caso” descreve a preparação da avaliação, sem garantir proteção do restante da máquina ou da skill original. A inspeção do adaptador e do ambiente precisa considerar esse comportamento concreto.

Um adaptador é o arquivo que diz ao runner como chamar a ferramenta de IA. A implementação permite escolher outro por --adapter, pela variável BMAD_EVAL_ADAPTER ou por um arquivo junto aos casos. Uma pessoa técnica pode preparar e revisar um adaptador que respeite as permissões do projeto. Sem adaptador resolvido, os scripts apenas preparam os casos e registram que foram ignorados; isso não deve ser apresentado como avaliação aprovada.

Leia a skill bmad-eval-runner e o adaptador disponível neste projeto, sem iniciar execuções. Para a skill skills/com-diagnostico, confira se existem casos com entradas anonimizadas e critérios objetivos. Explique quais casos faltam e qual modo avalia cada dúvida. Verifique se o adaptador respeita as permissões do projeto; se ele as desativar, registre o impedimento e proponha um adaptador separado para revisão técnica. Não altere a skill instalada do BMAD.

Os builders oferecem avaliações durante a construção. Por padrão elas são opcionais, mas uma equipe pode configurar evals_required como baseline ou any: no primeiro caso é preciso passar numa comparação com o modelo sem a skill; no segundo, ao menos um caso deve existir e passar. Se esse requisito não puder ser atendido, a construção deve ser declarada bloqueada. Isso evita chamar de concluída uma skill que a própria equipe exigiu verificar.

Você também pode definir padrões para o próprio trabalho dos builders, sem alterar os arquivos instalados. As substituições da equipe ficam em _bmad/custom/bmad-workflow-builder.toml e _bmad/custom/bmad-agent-builder.toml; as pessoais usam o mesmo nome com .user.toml. Esses arquivos configuram como construir novas skills; são diferentes da configuração emitida dentro de cada skill construída.

Ao combinar esses arquivos, valores simples, como um limite de tokens, são substituídos pela camada mais específica; listas comuns são acrescentadas. Por isso, uma lista pessoal vazia não apaga os padrões que a equipe já definiu. Na prática, confira o resultado combinado antes de concluir que uma regra deixou de valer. Há mais um limite: se o carregamento de customização falhar, os SKILL.md dos dois builders orientam usar os padrões do customize.toml distribuído. Uma exigência da equipe não deve ser considerada aplicada sem confirmar que sua camada foi carregada.

O resultado desta Fase: você deve sair sabendo se a necessidade pede um fluxo, um agente ou um módulo; o que fornecer ao Builder; como examinar o pacote criado; e como distinguir análise de instruções de execução real de casos. No exemplo, a sequência mais simples é construir o diagnóstico, examiná-lo com atendimentos anonimizados, corrigir o que falhar e só então decidir se vale acrescentar um agente e empacotar o conjunto. Essa sequência é a recomendação didática da aula, não uma promessa de que todos os negócios precisam das cinco skills.

Divergências da fonte que afetam o uso do Builder 2.2.2

O código instalado foi usado como referência principal. É útil reconhecer quatro diferenças para não seguir instruções de outra geração:

1. A documentação de comandos da própria tag v2.2.2 ainda apresenta BP/QO, seis fases e um modo de conversão --convert. O CSV instalado também registra “Convert a Skill”. Porém, o SKILL.md instalado de bmad-workflow-builder roteia apenas Build, Edit e Analyze, e não há referência convert-process.md na pasta instalada. Esta aula ensina alteração ou reconstrução com intenção explícita e não promete o antigo relatório de conversão.
2. O CSV aponta relatórios para bmad_builder_reports, mas as referências instaladas de Analyze mandam gravá-los em .analysis/<data-hora>/ junto à skill ou agente. O caminho informado ao final de cada execução deve ser conferido.
3. A documentação de eval da tag fala nos modos artifact, trigger e both. A skill instalada apresenta baseline, variant, quality e trigger, que são os ensinados aqui. A documentação antiga também descreve reutilização de credencial, enquanto a referência instalada diz que não copia arquivos de credenciais para o ambiente de avaliação.
4. O Module Builder menciona bmad-builder-setup num aviso de configuração ausente, mas a skill que existe e está registrada é bmad-bmb-setup. Seu assets/module.yaml contém module_version: 1.0.0; para identificar a versão distribuída, esta aula usa o manifesto da instalação e o package.json da tag, ambos correspondentes a 2.2.2.

Este é o percurso didático recomendado, não uma sequência obrigatória de todas as skills. A análise documental e a execução dos casos são trabalhos diferentes.

Na Oficina Aurora, vamos considerar também uma operação com empresas clientes, cujos dados precisam ficar separados. Esse é um recorte fictício para os exemplos desta fase. O Test Architect entra quando “o teste ficou verde” já não responde à pergunta do negócio. Você quer saber se o cliente consegue aprovar um orçamento, se um usuário enxerga somente os próprios dados, se uma operação continua confiável depois de uma alteração e quais riscos permanecem antes de liberar a versão. O módulo organiza o planejamento, a geração e a revisão dos testes e a relação entre o que foi prometido e o que foi verificado. TEA significa Test Engineering Architect; o nome comprido bmad-method-test-architecture-enterprise identifica o pacote e o repositório.

O que foi conferido nesta fase: os dez arquivos SKILL.md instalados — um papel de especialista e nove fluxos — foram lidos e comparados com a tag oficial v1.27.2; são iguais. O manifesto instalado registra o mesmo commit da tag: d99ad29c62697c152e3393351406686d5bcd323c. Nenhuma dessas skills foi executada para preparar esta aula. Os resultados descritos abaixo são os resultados previstos nas instruções, não uma execução observada.

Teste automatizado é uma verificação que o computador consegue repetir. Cobertura, nesta fase, significa quais comportamentos ou requisitos têm verificações; não confunda isso com uma porcentagem de linhas de código executadas.

O método básico já oferece bmad-qa-generate-e2e-tests para funcionalidades implementadas. Ele reconhece a ferramenta de testes existente, gera verificações de API quando há serviços e de ponta a ponta quando há interface, executa os testes e corrige falhas. API é uma interface pela qual sistemas trocam dados. Teste de ponta a ponta, também chamado E2E, acompanha uma jornada completa do usuário. Essa geração básica se concentra no caminho esperado e em alguns erros importantes; não monta estruturas complexas de preparação de testes.

O TEA acrescenta planejamento por risco, organização mais elaborada dos testes, auditoria da qualidade dos próprios testes, análise de evidências de desempenho e segurança e rastreamento dos requisitos até as verificações. Isso não torna obrigatório usar todas as skills. A documentação da 6.12 permite chamar bmad-testarch-automate sozinho para ampliar testes do código existente: bmad-testarch-test-design antes e bmad-testarch-trace depois são opcionais nesse uso.

NFR é um requisito de qualidade, como desempenho, segurança e confiabilidade. Escolha pelo problema que existe agora:

Pedido — exemplo autoral. O nome da skill é oficial; todo o texto que o acompanha neste e nos demais Pedidos desta fase é um exemplo para adaptar.

/bmad-tea Quero decidir como testar o cadastro de clientes do meu sistema. Ele já funciona e tem alguns testes. Primeiro me explique, em português do Brasil, se precisamos planejar novos testes, ampliar os existentes ou revisar a qualidade deles. Considere o risco de uma empresa acessar os dados de outra. Não comece pela instalação de ferramentas.

A skill bmad-tea ativa o arquiteto mestre de testes e consultor de qualidade (Murat), cujo título oficial é Master Test Architect and Quality Advisor. Se o objetivo corresponder claramente a uma opção do menu, ele pode encaminhar diretamente ao fluxo; se houver mais de uma interpretação, suas instruções pedem uma pergunta curta que esclareça a escolha. Esse papel permanece ativo na conversa até você dispensá-lo.

Confira antes de continuar:

• a resposta deve separar o que já existe, o risco que importa e o próximo trabalho. Ter instalado o módulo não significa que uma análise foi feita nem que os testes foram executados.

Quando pular o TEA: se a empresa já dispõe de uma equipe e de uma suíte confiável, e nenhuma das perguntas acima está sem resposta, mantenha o processo existente. A documentação chama esse caminho de No TEA. Ela também admite TEA Solo, em que você usa apenas a especialidade de qualidade com seus próprios requisitos, sem adotar o planejamento completo do BMAD. Portanto, usar o módulo não obriga a reescrever a documentação de um projeto que já está bem organizado. O critério é a lacuna que ele resolve.

Você pode chamar qualquer uma das nove skills diretamente, sem abrir antes o arquiteto mestre de testes e consultor de qualidade (Murat). Dentro da conversa com ele, os códigos curtos do menu oferecem os mesmos caminhos. GATE é uma opção de encaminhamento do menu, não uma décima skill de trabalho: ela identifica as evidências disponíveis e recomenda revisão de testes, auditoria de NFR e decisão de rastreamento, conforme a necessidade.

Os oito fluxos com nome bmad-testarch-* oferecem quatro entradas: Create, para iniciar; Resume, para retomar uma execução interrompida; Validate, para conferir as entregas pela lista de critérios do fluxo; e Edit, para revisar entregas existentes. No menu, aparecem como C, R, V e E. Retomar não significa confiar na memória do chat: os fluxos usam arquivos de progresso e verificam o que já foi produzido.

Validação de uma entrega também não significa execução dos testes do sistema. Por exemplo, conferir se um plano contém os riscos e cenários exigidos é diferente de abrir a aplicação e comprovar que ela funciona. A saída de Validate é um relatório próprio com o escopo e um identificador de horário, preservando relatórios anteriores.

Não existe um Comando universal de terminal que substitua esses Pedidos: eles carregam instruções no assistente. O terminal entra quando o fluxo precisa instalar uma dependência ou executar os testes do projeto. Peça que o assistente identifique o comando real nos arquivos do seu projeto e relate o resultado; não copie um comando de Playwright para um projeto que usa outra ferramenta.

Esta skill é uma formação interativa, chamada TEA Academy. Ela pergunta seu papel, experiência e objetivos para adaptar os exemplos. Pode começar do zero, retomar o progresso e permitir que uma pessoa experiente vá a uma sessão específica. Para o empresário, o ganho é aprender a fazer perguntas melhores e interpretar as entregas; não é necessário concluir as sete sessões para usar as demais skills.

As sete sessões cobrem: primeiros passos; conceitos de risco e prioridade; organização dos testes e preparação de dados; desenho do plano; testes antes e depois da implementação; qualidade e rastreamento; e padrões avançados. Os tempos publicados são estimativas de ensino, não uma promessa de duração para sua empresa. O fluxo registra avaliações e progresso; a documentação usa 70% como referência de aprovação nos questionários.

/bmad-teach-me-testing Quero começar a aprender testes como dono de uma empresa, sem experiência em programação. Use exemplos de cadastro de clientes, orçamento e cobrança e explique tudo em português do Brasil. Quero entender que evidência pedir antes de aceitar uma entrega.

A saída prevista inclui um arquivo de progresso em {test_artifacts}/teaching-progress/{user_name}-tea-progress.yaml, notas de cada sessão em {test_artifacts}/tea-academy/{user_name}/session-{N}-notes.md e, ao completar as sete, tea-completion-summary.md na mesma pasta de notas. As expressões entre chaves representam valores resolvidos da configuração; não são nomes para copiar literalmente como pastas.

Aqui há uma diferença importante de menu: os modos Create, Validate e Edit da Academy tratam, respectivamente, da jornada de aprendizagem, da validação do próprio fluxo de ensino e da modificação desse fluxo. Eles não representam “fazer, corrigir ou validar uma prova do seu produto”. Retomar as aulas entra pelo modo de aprendizagem, que procura o progresso já salvo.

Use esta skill quando precisa decidir o que testar antes de gastar esforço escrevendo testes. Ela trabalha em duas escalas. Escala do sistema examina requisitos e arquitetura para organizar como o produto será verificável. Escala do épico planeja os testes de um conjunto de funcionalidades relacionadas.

Na escala do sistema, o fluxo pede requisitos do produto, registros das decisões de arquitetura e arquitetura ou especificação técnica. Arquitetura é a definição de como as partes principais do sistema se organizam; ADR é um registro de uma decisão de arquitetura e de seu motivo. Na escala do épico, ele exige o épico ou as histórias — entregas menores com condições claras de aceitação — e aproveita o contexto de arquitetura disponível. Se os documentos necessários não existem, o caminho é prepará-los, não fingir que o módulo os deduziu com a mesma segurança.

/bmad-testarch-test-design Crie o plano de testes do épico de cadastro de clientes, em português do Brasil. Use o épico e seus critérios de aceitação disponíveis no projeto. Priorize isolamento entre empresas, prevenção de cadastro duplicado e recuperação de erros. Mostre as lacunas dos documentos e não invente limites de desempenho.

A análise atribui probabilidade e impacto aos riscos e separa a prioridade dos testes. Na explicação oficial, ambos recebem notas de 1 a 3; a multiplicação produz uma pontuação entre 1 e 9. Prioridades P0 a P3 indicam, em ordem, o que é crítico, importante, secundário e menos urgente. A pontuação de risco ajuda a decidir a prioridade, mas não substitui o julgamento sobre receita, segurança, integridade dos dados e uso do produto.

No exemplo de negócio, trocar a cor de um botão e impedir que uma empresa leia a carteira de clientes de outra não merecem a mesma profundidade. O plano deve mostrar essa diferença e indicar onde verificar cada regra. Um teste unitário isola uma pequena regra; um teste de integração verifica a cooperação entre partes; um teste E2E acompanha o percurso completo. A orientação do TEA é escolher o nível mais simples capaz de provar o comportamento, evitando repetir a mesma verificação em todas as camadas sem motivo.

As entregas previstas são:

A opção mode admite auto-detect, system-level e epic-level. Informar o escopo em português no Pedido evita depender da detecção; se houver documentos de sistema e de épico, o fluxo prefere começar pelo sistema. O metadado design_level declara full, targeted e minimal, mas não foi encontrado consumo desse campo nos passos instalados. Seu efeito operacional não está confirmado. Informe o recorte desejado em português no Pedido, sem tratar esses valores como flags de terminal.

Cada trabalho salva um progresso próprio: test-design-progress-system.md ou test-design-progress-epic-{epic_num}.md. Se você interrompeu o planejamento de um épico e começou outro, os arquivos têm identidades distintas. Quando encontra uma execução inacabada do mesmo escopo, o fluxo oferece retomá-la ou começar novamente; reiniciar substitui aquele registro de progresso.

Confira antes de continuar:

• o plano deve ligar risco, comportamento, prioridade e evidência esperada. Um documento com muitas páginas e sem essa relação ainda não resolve a decisão de negócio.

Um framework de testes é o conjunto de ferramentas e convenções que permite escrever e executar testes de maneira organizada. Esta skill prepara essa base. Ela examina os arquivos do projeto e distingue interface web, serviços de servidor, aplicação com as duas partes e aplicativo móvel. Embora o resumo do SKILL.md cite Playwright e Cypress, os passos instalados também têm caminhos para testes de serviços e para dispositivos móveis.

Se você já tem uma estrutura funcionando, não comece criando outra. O primeiro passo interrompe o caminho de criação quando encontra uma configuração E2E existente ou uma estrutura de testes de servidor que entraria em conflito. Para um sistema existente, normalmente faz mais sentido entender a base com trace e test-review e expandi-la com automate.

/bmad-testarch-framework Prepare a estrutura de testes para este projeto em português do Brasil. Primeiro identifique o tipo de aplicação e verifique se já existe uma base de testes. Se houver conflito, pare e explique como aproveitar a base atual. Antes de instalar bibliotecas, apresente o que será acrescentado. Inclua no resumo os hooks e arquivos de configuração que este fluxo criar ou alterar.

Para interface web, o fluxo prefere Playwright, mas admite Cypress quando o contexto justificar. Para servidor, escolhe de acordo com a linguagem, como pytest para Python e JUnit para Java. Para aplicativos móveis, o caminho preparado é Maestro, junto dos testes unitários ou de componentes da própria aplicação; uma infraestrutura Appium existente é tratada como configuração alternativa. Uma aplicação com interface web e servidor pode precisar das duas estruturas. Não é necessário que o empresário escolha uma tecnologia pelo nome: descreva a aplicação e peça a justificativa da escolha.

Reconhecer a tecnologia não significa oferecer a mesma profundidade em todas elas. A referência oficial distingue suporte completo, suporte de geração, uso como evidência e uso apenas do núcleo de planejamento. Navegadores, contratos Pact e aplicativos móveis com Maestro têm caminhos mais completos. Para Python, Java, Go, C# e Ruby, há geração e configuração, mas a avaliação de qualidade dos testes é parcial: a base de critérios ainda contém muitas regras próprias de JavaScript e navegador. Rust aparece na seleção, porém o próprio módulo declara sua preparação incompleta. Aplicações de computador, sistemas embarcados e fluxos de dados podem aproveitar planejamento e rastreamento, mas esta versão não promete gerar seus testes.

Se a mesma pasta contém um aplicativo móvel e seu servidor, a detecção automática dá precedência ao aplicativo móvel. O passo de preparação orienta separar os trabalhos ou indicar explicitamente o recorte de servidor. No exemplo da Oficina Aurora, isso evita que verificar o aplicativo do técnico seja confundido com verificar as permissões do serviço que guarda os clientes. A separação do exemplo é didática; a precedência está nas instruções instaladas.

O fluxo cria configuração, exemplos e apoios reutilizáveis. Fixture é a preparação controlada necessária para um teste; fábrica de dados cria dados de exemplo consistentes. A documentação de uso fica em tests/README.md, salvo ajuste de test_dir; arquivos concretos dependem da tecnologia detectada. Na configuração web, exemplos de saídas são playwright.config.ts ou cypress.config.ts, além da organização sob tests/.

As opções declaradas incluem framework_preference com auto, playwright ou cypress, project_size com auto, small ou large, e use_typescript, que prefere configuração em TypeScript quando aplicável. TypeScript é JavaScript com informações adicionais de tipos. Essas opções não anulam a análise do tipo de aplicação e não transformam um serviço Python em um projeto de navegador.

A integração com @seontechnologies/playwright-utils depende da opção estar ativa e do pacote fazer sentido para o projeto. O passo de criação pede autorização antes de instalar a biblioteca e alterar package.json; se a instalação for recusada, a estrutura deve seguir sem importações para uma biblioteca ausente. Para os testes de contrato com Pact, há condição semelhante e uma verificação adicional de necessidade real. Teste de contrato verifica se dois sistemas concordam sobre as mensagens que trocam. Não basta ter uma ideia de “arquitetura com vários serviços” para criar automaticamente uma suíte, ou conjunto de testes, de contratos.

Confira antes de continuar:

• a base deve documentar como instalar as dependências e executar os testes, explicar os arquivos criados e informar as alterações de hooks. Arquivos gerados não são evidência de que a execução funcionou na sua máquina.

Integração contínua, ou CI, é a execução automática de verificações quando o código muda. Pipeline é a sequência dessas verificações. Esta skill prepara os arquivos da sequência de qualidade para a plataforma usada pelo projeto; ela não é um Pedido genérico para consertar qualquer teste que falhou.

O caminho verifica se existe um repositório Git, identifica a ferramenta de testes e exige que os testes passem localmente antes de preparar a integração. Quando encontra um pipeline existente, pede a decisão entre atualizar ou substituir. Se a aplicação já tem regras de publicação, o Pedido deve esclarecer que a tarefa é preparar verificações, para evitar misturar a decisão de testar com a de colocar uma versão no ar.

/bmad-testarch-ci Prepare a integração dos testes com a plataforma que este projeto já usa. Explique em português do Brasil quais verificações rodarão quando o código mudar e quais arquivos serão alterados. Aproveite a configuração existente. Se os testes locais falharem, relate o bloqueio e as evidências. O escopo deste pedido é a verificação de qualidade.

As plataformas reconhecidas incluem GitHub Actions, GitLab CI, CircleCI, Jenkins, Azure DevOps e Harness. ci_platform: auto procura arquivos existentes e pode usar a origem do repositório para decidir; na ausência de identificação, o passo instalado usa GitHub Actions. No caminho GitHub, o arquivo padrão é .github/workflows/test.yml; outras plataformas recebem seus respectivos arquivos.

O fluxo pode distribuir testes em partes executadas em paralelo, repetir testes para descobrir instabilidade e guardar relatórios. Essa repetição é chamada burn-in: várias execuções ajudam a revelar testes que passam e falham sem uma alteração relevante. O desenho varia pelo tipo da aplicação; testes de servidor não precisam receber automaticamente a instalação de um navegador. A documentação prevê docs/ci.md para orientar a operação e docs/ci-secrets-checklist.md para listar os nomes dos segredos necessários. Os valores dos segredos ficam no mecanismo apropriado da plataforma, não no texto da aula nem em arquivos versionados.

Confira antes de continuar:

• diferencie “arquivo de CI criado” de “execução na plataforma concluída”. Exija o endereço ou registro da execução real quando chegar a hora de aceitar o pipeline; esta aula não executou nenhum deles.

Para um projeto pequeno, confirme primeiro a execução local e a sequência indispensável de verificações. Para um projeto grande, a divisão em partes paralelas pode reduzir o tempo de espera, mas deve respeitar a independência dos testes. Os modelos distribuídos pelo TEA partem principalmente de Node.js e navegador e são adaptados durante a geração; CircleCI é reconhecido, mas não tem um modelo próprio incluído nesta versão. Em um serviço Python ou Java, confira se os comandos finais correspondem à aplicação. Reconhecer uma plataforma não é ter executado nela.

ATDD significa desenvolver a partir de testes de aceitação: primeiro transformar o comportamento combinado em verificações, depois implementar até atendê-las. A skill prepara os testes antes de existir a funcionalidade e produz uma lista de implementação. Ela exige uma história aprovada, com critérios de aceitação claros, a estrutura de testes configurada e um ambiente de desenvolvimento disponível.

O ciclo conhecido como “vermelho, verde, reorganizar” significa provar que a verificação falha sem o comportamento, fazê-la passar com a implementação e só depois reorganizar o código preservando o resultado. Há uma particularidade importante desta versão: os exemplos de testes de aceitação são gerados inicialmente desativados com test.skip(). Quem implementa deve ativar cada teste, confirmar que ele falha pelo motivo esperado e então implementar. Uma suíte verde porque os testes ficaram desativados não comprova aceitação.

/bmad-testarch-atdd Prepare os testes de aceitação da história aprovada de impedir clientes duplicados, antes da implementação. Use os critérios disponíveis no projeto e explique em português do Brasil. Entregue a lista do que precisa ser implementado, os testes preparados e a orientação para ativá-los e confirmar a falha inicial. Não trate testes desativados como cobertura concluída.

O modo normal gera a partir dos critérios, documentação e código. Quando já existe uma interface esqueleto e a interação é complexa, o fluxo pode observar ou registrar o navegador para verificar elementos e passos. Para serviços de servidor, o passo escolhe a geração a partir da documentação e do código, sem gravação de navegador. A disponibilidade de ferramentas e a opção tea_browser_automation determinam se essa observação pode ocorrer.

A entrega central é {test_artifacts}/atdd-checklist-{story_key}.md, acompanhada dos arquivos de teste e apoios. story_key identifica a história, normalmente derivado do nome do arquivo. O fluxo preserva os identificadores fornecidos que seguem exatamente o formato AC-<inteiro positivo>, como AC-1, rejeita identificadores repetidos e atribui os números livres aos critérios ainda sem identificador. Essa regra permite relacionar a lista e os testes à mesma história sem trocar os nomes a cada execução.

Divergência de vocabulário a conhecer: o catálogo instalado do TEA coloca ATDD entre bmad-create-story:create e bmad-dev-story. O catálogo principal da série 6.12 já apresenta bmad-build como o caminho de construção. Nesta aula, o papel permanece: usar ATDD antes de implementar a história e entregar seus arquivos a quem construirá. Não copie os nomes antigos do catálogo do módulo como se fossem a recomendação atual do fluxo principal.

Esta é a porta de entrada mais curta do TEA para um sistema que já existe. A skill identifica lacunas e gera verificações prioritárias do comportamento implementado. Pode trabalhar integrada a histórias, especificações e plano de testes ou analisar diretamente o código, em modo independente. Independente aqui significa sem exigir os documentos do método; ainda precisa encontrar a estrutura de testes adequada.

/bmad-testarch-automate Amplie os testes do cadastro de clientes já implementado. Use a estrutura existente e priorize isolamento entre empresas, duplicidade e erros de gravação. Evite repetir casos que já estão bem cobertos. Explique em português do Brasil os arquivos criados, as suposições e quais testes foram realmente executados; se algum não puder rodar, registre o motivo.

A opção coverage_target admite critical-paths, comprehensive e selective: concentrar nas jornadas críticas, buscar cobertura ampla ou limitar a seleção. Escolha em linguagem de negócio. “Cubra tudo” costuma esconder decisões; “priorize impedir acesso indevido e cobrança duplicada” orienta uma primeira execução com fronteiras claras. O metadado standalone_mode permite o trabalho sem artefatos BMAD; o primeiro passo também detecta se há documentos para integrar.

Os caminhos de geração variam conforme a aplicação: API, interface de navegador, servidor ou dispositivo móvel. O fluxo consulta testes já existentes para evitar repetição e produz ou ajusta preparação de dados e apoios. Para mobile, a ausência da estrutura exigida interrompe o início; a ausência do executável Maestro permite gerar os arquivos, mas exige registrar que os testes não puderam ser executados naquele ambiente.

A saída declarada é {test_artifacts}/automation-summary.md, com plano por nível e prioridade, arquivos alterados, suposições, riscos e próximos passos. Quando integrações de bibliotecas estiverem ativas, o resumo também registra desvios justificados. Não aceite “testes gerados” como sinônimo de “testes executados e aprovados”: o checklist menciona execução e correção automática condicionais, mas auto_validate e auto_heal_failures não aparecem vinculados no workflow.yaml nem nos passos de criação desta instalação. Peça explicitamente que o resumo diferencie testes gerados, executados, aprovados e não executados.

Um teste pode estar mal escrito e continuar mostrando verde. Esta skill examina os próprios testes: se dependem uns dos outros, se usam esperas frágeis, se suas verificações realmente detectam um erro e se podem ser mantidos. Teste instável, também chamado flaky, é aquele que alterna entre passar e falhar sem uma mudança relevante no comportamento testado. A revisão produz avaliação de qualidade; medir quais requisitos estão cobertos pertence a trace.

/bmad-testarch-test-review Revise a qualidade dos testes do cadastro de clientes. Quero um relatório em português do Brasil sobre verificações que não detectam defeitos, dependência entre testes e instabilidade. Comece apenas com o relatório, sem inserir comentários nos arquivos. Diferencie problemas graves de recomendações e explique a decisão final.

O escopo pode ser um arquivo (single), uma pasta (directory) ou toda a suíte (suite). Suíte é o conjunto de testes considerado. O relatório padrão é {test_artifacts}/test-review.md; a variável output_file_override permite escolher outro caminho para aquela execução. review_files delimita explicitamente os arquivos avaliados; context_files identifica materiais somente para contexto, sem pontuá-los como testes.

A nota parte de 100, perde 10 pontos por ocorrência crítica, 5 por alta, 2 por média e 1 por baixa e pode receber bônus definidos. Depois, o código instalado limita a nota efetiva pela maior gravidade encontrada: no máximo 69 com ocorrência crítica, 79 com alta, 89 com média e 99 com baixa. A decisão também segue regras: uma ocorrência crítica bloqueia; uma ocorrência alta ou nota menor que 70 pede mudanças; pendências médias ou baixas com nota suficiente geram aprovação com comentários; ausência de pendências gera aprovação. Portanto, bônus não apagam um teste incapaz de detectar o defeito que deveria encontrar.

Divergência documental: o README.md da tag ilustra uma nota 94 acompanhada de bloqueio por ocorrência crítica, mas esse exemplo não incorpora o limite de gravidade presente no passo instalado. Nesta aula, vale o código: nesse caso, a nota efetiva seria limitada a 69 e o bloqueio permaneceria.

Por padrão, generate_inline_comments: false produz somente o relatório. Ativar a opção permite escrever comentários TODO (TEA Review) nos arquivos de teste. Já headless: true faz a revisão iniciar o modo Create sem saudação ou menu e sem perguntas, usando os valores fornecidos e configurados; essa é uma capacidade específica desta revisão, não uma autorização para dizer que todas as skills TEA trabalham sem acompanhamento.

Há também um programa de terminal chamado tea-test-review, separado da chamada da skill na conversa. Ele executa a revisão sem interação, limita os arquivos avaliados e devolve um resultado que a integração contínua consegue ler. Sua presença no pacote oficial não significa que o Comando esteja instalado na máquina só porque a pasta da skill existe. A referência distingue a instalação do programa e a disponibilidade da skill. Esse programa não foi instalado nem executado nesta revisão.

Esse caminho faz sentido quando a equipe precisa repetir a mesma revisão a cada alteração. Há uma diferença importante entre examinar o que mudou e auditar o conjunto inteiro: na comparação de alterações do Git, o programa normalmente usa os problemas introduzidos ou modificados para decidir; em uma lista explícita de arquivos, considera todos os problemas encontrados. E um código de saída 0 pode significar revisão aprovada, revisão dispensada por falta de arquivos alterados ou exceção registrada. Exija também a leitura do resultado estruturado, para saber qual situação ocorreu. Os códigos 1, 2 e 3 distinguem reprovação, problema de ambiente/configuração e falha do agente ou do relatório. Essa exceção pertence ao programa de revisão; ela não altera as regras de dispensa de Trace explicadas na Etapa 22.

NFR, ou requisito não funcional, descreve uma qualidade que a solução precisa ter: por exemplo, tempo de resposta, controle de acesso, capacidade de recuperação e facilidade de manutenção. A skill bmad-testarch-nfr audita evidências de desempenho, segurança, confiabilidade e manutenção. O nome curto nfr-assess aparece na documentação, mas a skill instalada se chama bmad-testarch-nfr.

Defina os limites no planejamento com test-design; use a auditoria quando houver implementação e evidências. Um relatório de carga, resultados de varredura, registros de erro e dados de monitoramento são exemplos de evidências. Escrever “a aplicação é rápida” no pedido não substitui medir o que foi combinado. A auditoria não é um teste de invasão de um sistema real e não deve inventar limites ausentes.

/bmad-testarch-nfr Audite as evidências de segurança, desempenho e confiabilidade desta entrega, em português do Brasil. Compare os resultados disponíveis com os limites já definidos nos requisitos e no plano de testes. Não invente limites nem medições. Diga quais evidências sustentam a avaliação e quais faltam antes da liberação.

O resultado previsto é {test_artifacts}/nfr-assessment.md, com avaliação por categoria, lacunas e ações de mitigação. Os achados podem receber quatro estados: PASS, para implementação sustentada por evidência e dentro do limite; CONCERNS, para fragilidade, ressalva ou evidência insuficiente; FAIL, para falha ou problema crítico que compromete o critério; e N/A, quando ele não se aplica. Limite desconhecido deve permanecer identificado como UNKNOWN e resultar em CONCERNS, nunca em aprovação por ausência de medida.

A variável custom_nfr_categories permite registrar categorias adicionais, mas não cria automaticamente um novo avaliador. Os quatro domínios avaliados pelos trabalhos de auditoria são segurança, desempenho, confiabilidade e manutenção. Requisitos de outras categorias ficam registrados para o relatório; não entram automaticamente no cálculo desses quatro domínios nem na decisão. Por exemplo, planos de recuperação de desastre podem trazer prazo de recuperação, cópias de segurança e restauração, mas o passo instalado declara que não há um trabalho automatizado específico para avaliá-los. Se isso é essencial para sua operação, peça uma avaliação própria e mantenha essa pendência visível.

Divergência documental relevante: a página oficial permite uma auditoria com evidências incompletas e orienta marcar lacunas como CONCERNS. O primeiro passo instalado, porém, manda interromper se a implementação ou as fontes de evidência não estiverem disponíveis. A leitura segura nesta aula é: evidência parcial permite explicitar o que falta; ausência total dos pré-requisitos não deve virar uma auditoria fictícia. Vale o passo instalado quando o caso concreto entrar em conflito com a descrição geral.

Rastreabilidade é a ligação entre um requisito e a evidência que o verifica. A skill monta uma matriz dessas relações, aponta cobertura completa, parcial ou ausente e, quando há condições, produz uma decisão de qualidade. Gate é esse ponto de decisão: o conjunto de critérios usados para avaliar se as evidências permitem seguir. Não é um comando de publicação.

/bmad-testarch-trace Relacione os critérios de aceitação do cadastro de clientes com os testes existentes. Faça o relatório em português do Brasil e mostre o que está completamente coberto, parcialmente coberto e sem prova. Diferencie testes ativos de testes desativados. Se usar comportamentos inferidos do código porque faltam requisitos, identifique essa limitação. Esta execução é um diagnóstico de cobertura, sem decisão de liberação: use allow_gate false.

allow_gate é uma variável oficial do fluxo; a frase que a usa é exemplo de Pedido, não uma flag de terminal. Com ela falsa, a execução mantém o diagnóstico sem emitir a decisão. O fluxo tem duas partes internas: construir a matriz e, quando elegível, avaliar a decisão. Essas partes não são as Fases numeradas desta Aula.

A fonte dos requisitos é resolvida em ordem: requisitos formais; especificações ou contratos existentes; referências externas acessíveis por integrações compatíveis; por último, comportamentos inferidos do código, quando permitido. allow_external_pointer_resolution controla a tentativa de resolver as referências externas; allow_synthetic_oracle controla essa última inferência. Oráculo de cobertura, expressão da documentação, é a lista tomada como referência para decidir o que deveria estar coberto. Quando a lista é inferida do próprio código, ela não tem automaticamente o mesmo valor de requisitos aceitos pelo negócio.

As opções de escopo são story, epic, release e hotfix, na variável gate_type: uma história, um épico, uma liberação ou uma correção urgente. coverage_levels seleciona níveis como e2e, api, component, unit e live; component verifica uma peça de interface ou aplicação e live representa observações de execução registradas. decision_mode admite decisão por regras (deterministic) ou decisão da equipe (manual), mas o algoritmo instalado nunca concede sozinho uma dispensa de risco.

A opção collection_mode distingue análise estática dos contratos (contract_static), inventário (inventory_only), leitura de registros de execução (runtime_manifest) e situações em que a coleta foi adiada (deferred_shared), dispensada (waived), restringida (restricted) ou ficou inacessível (inaccessible). Os quatro últimos estados não devem virar uma decisão fabricada sobre evidência incompleta. A variável allow_gate e o estado real de coleta controlam a emissão.

A saída principal é {test_artifacts}/traceability-matrix.md. O fluxo também escreve e2e-trace-summary.json, um resumo estruturado para outras ferramentas, e pode escrever gate-decision.json quando há coleta elegível e a decisão está habilitada. JSON é um formato de dados que programas conseguem ler de maneira padronizada.

A classificação depende do que a verificação comprova. FULL significa que todos os cenários daquele critério foram demonstrados; isso pode acontecer em uma única camada de teste. Um teste de API suficiente não vira cobertura incompleta apenas por não existir outro teste de navegador. Por outro lado, colocar “impede cliente duplicado” no nome de um teste que só verifica se a página abriu não comprova a regra. O passo de mapeamento exige examinar as verificações e registrar evidências rejeitadas. Nos percentuais usados pela decisão, contam os critérios completamente cobertos: cobertura parcial não recebe o mesmo peso de FULL.

Os critérios automáticos desta versão exigem 100% de cobertura P0, pelo menos 80% de cobertura geral e pelo menos 80% de P1. Com os dois primeiros limites atendidos, P1 a partir de 90% permite PASS; entre 80% e abaixo de 90% resulta em CONCERNS; abaixo dos mínimos resulta em FAIL. Se não há requisitos P1, o algoritmo trata esse critério como atendido e continua avaliando os demais. Não são percentuais mágicos aplicáveis a qualquer empresa: são regras concretas desta implementação, que devem ser entendidas antes de usar seu resultado em uma decisão.

Há limites adicionais. Um requisito coberto somente por observação de execução registrada limita a decisão a CONCERNS; uma referência inferida sem confiança alta também pode impedir PASS. O fluxo lê live-verification-results.json, mas não executa por conta própria as verificações descritas nele. Para uma observação contar, ela precisa apontar um requisito reconhecido, um identificador único, resultado aprovado e a mesma revisão de código analisada. Evidência antiga ou sem comprovação não se transforma em cobertura por estar dentro de um arquivo.

WAIVED significa que uma pessoa responsável concedeu uma exceção formal, não que a IA decidiu ignorar o risco. O algoritmo instalado nunca deriva esse estado automaticamente e nem um registro em gate-waivers.md altera a decisão calculada: o fluxo lê, verifica e relata o registro. A exceção exige responsável pela aprovação, data, motivo, vencimento, monitoramento e responsável e prazo de correção. As lacunas continuam na matriz e nas porcentagens.

Confira antes de continuar:

• o relatório deve permitir seguir o caminho de uma promessa até uma prova concreta. “Temos cem testes” não informa se algum deles verifica o que mais importa para o cliente.

A instalação consultada usa _bmad/tea/config.yaml e concentra as entregas em _bmad-output/test-artifacts. Esse é o local definido por test_artifacts; arquivos de teste e arquivos de CI ficam nos locais próprios do projeto. As configurações não são um inventário de ferramentas já instaladas: ativar uma preferência não comprova que a dependência ou conexão existe.

CLI significa interface de linha de comando. MCP é um protocolo de conexão entre o assistente e ferramentas externas. Nenhum deles é uma promessa de que haverá acesso ao navegador ou ao serviço de contratos. Com a detecção ativa, o modo automático de execução procura equipe de agentes, depois subagentes e, por fim, execução sequencial; o formato das entregas não muda só porque o trabalho foi dividido.

Há quatro opções que exigem especial atenção: risk_threshold, test_design_output, test_review_output e trace_output aparecem na configuração instalada, mas a versão oficial as declara futuras e ainda não ligadas aos fluxos. Alterá-las não muda hoje o limite de risco ou redireciona essas entregas. Para encontrar os arquivos, siga test_artifacts e os caminhos efetivamente declarados no fluxo.

A referência oficial sugere editar a configuração, mas as regras deste guia reservam os arquivos gerados ao instalador e usam bmad-customize para personalizações de skills. Para uma mudança permanente, peça ao assistente para identificar a opção suportada e o mecanismo adequado, sem editar cegamente os arquivos distribuídos. Para uma execução específica, informe no Pedido escopo, idioma e resultado esperado.

Para um projeto novo que precisa da integração completa, a ordem oficial é planejar os testes do sistema → preparar a estrutura → preparar CI. Depois, em cada história, os testes de aceitação podem vir antes da construção e a ampliação dos testes vem depois. Para fechar um épico ou uma liberação, a revisão dos testes e a auditoria das evidências alimentam a análise de cobertura e a decisão. A aprendizagem fica fora dessa sequência e pode ocorrer em paralelo ao trabalho.

Para um sistema existente, comece descobrindo o que há: rastrear a cobertura → revisar a qualidade → escolher as lacunas prioritárias → ampliar os testes → avaliar novamente. Não recrie a estrutura só para seguir o desenho de um projeto novo. Se faltam documentos, o rastreamento admite fontes alternativas e inferências identificadas; isso ajuda a começar sem confundir comportamento observado com requisito aprovado.

Para testar uma funcionalidade pronta sem adotar a sequência inteira, o caminho menor continua válido: estrutura existente → bmad-testarch-automate → leitura do resumo e execução conferida. Planejamento e rastreamento podem entrar quando acrescentarem valor à decisão.

Se o trabalho é uma correção de defeito: reproduza o erro em um teste, corrija o comportamento, confirme que o teste passa e acrescente-o ao conjunto de regressão. Regressão é a volta de um defeito ou a quebra de algo que já funcionava. A revisão de qualidade pode ser limitada ao teste acrescentado. Você não precisa refazer o planejamento do sistema inteiro para corrigir uma falha localizada.

Se o sistema é grande: escolha uma funcionalidade ou uma área de maior risco para o primeiro diagnóstico, registre a cobertura atual e compare o resultado depois das correções. A documentação orienta priorizar os requisitos P0, depois os testes instáveis e as lacunas P1, sem tentar modernizar a suíte inteira de uma vez. Para uma operação pequena, a mesma lógica pode caber em uma única história. A profundidade acompanha o impacto: um sistema pequeno que separa dados de empresas ainda exige atenção séria a permissões.

Divergência de ordem nas fontes: o tutorial oficial “TEA Lite” mostra uma experiência didática com framework antes de test-design. O README.md da própria tag e o module-help.csv instalado registram test-design → framework → ci para a preparação integrada. Esta aula adota a sequência do código instalado: planejar primeiro permite que os riscos e as evidências necessárias influenciem a estrutura. O tutorial não deve ser convertido em uma obrigação de reinstalar ferramentas em todo projeto.

Conclua esta fase quando:

• você conseguir dizer qual pergunta de qualidade quer responder, qual skill responde a ela, que documentos ou código ela precisa ler e qual evidência concreta deve entregar. Para o exemplo do cadastro, isso significa saber demonstrar o isolamento dos dados, a regra de duplicidade e a reação a uma falha de gravação — e conseguir apontar o que ainda não foi comprovado.

O desenho resume as escolhas, sem transformar todos os fluxos em obrigação. Em sistemas com testes existentes, também é possível começar pelo diagnóstico de Trace e Test Review, explicado na Etapa 24.

Você já sabe delegar uma mudança. No sistema da Oficina Aurora, imagine três entregas combinadas: cadastrar clientes, registrar pedidos e consultar o histórico. Você quer que a IA termine a primeira, confira o resultado e só então passe à segunda. Esse é o espaço do Loop: coordenar uma fila de trabalho que já foi definida. Ele acrescenta um programa de controle ao método; não elimina a necessidade de dizer o que o negócio quer.

A distinção mais importante é esta: Build Auto não é um laço que percorre o projeto. Uma chamada trata exatamente uma unidade, mesmo quando recebe uma pasta que contém várias histórias. Ele não escolhe a próxima, não coordena vários épicos e não faz a retrospectiva do conjunto. Essas decisões pertencem à pessoa ou ao orquestrador.

Também não é correto prometer que toda história recebe duas revisões completas por padrão. Build Auto já faz sua revisão interna. O Loop pode abrir outra sessão, com contexto novo, para revisar o resultado novamente. Na política padrão da 0.13.2, essa revisão adicional depende da recomendação registrada pela primeira execução; existe a opção de pedi-la sempre.

/bmad-build-auto Pasta da especificação: _bmad-output/specs/oficina-aurora. Identificador da história: 1. Execute somente essa história. Use os critérios de aceite já registrados. Se houver uma decisão de negócio que os documentos não respondem, registre o bloqueio. Ao terminar, informe o arquivo de resultado, as verificações feitas e os riscos restantes.

O nome bmad-build-auto é real. O texto depois dele é um exemplo nosso de instrução. A pasta oficina-aurora e o identificador 1 são ilustrativos: substitua-os por uma pasta e um identificador existentes. A forma de entrada “pasta + identificador” é suportada, mas não deve apontar também para um arquivo específico de história no mesmo pedido.

Um checkpoint é um ponto de parada para conferir e decidir se o trabalho pode continuar. Se você quer examinar o plano antes da implementação, acrescente ao Pedido uma instrução explícita para parar após o planejamento. Build Auto pode terminar em ready-for-dev nessa situação; uma nova chamada para a mesma especificação retoma a implementação. Isso não é o comportamento padrão: sem essa instrução, ele segue.

O que fica registrado: a especificação contém um campo status e, ao final, uma seção Auto Run Result, com mudança realizada, verificações, achados de revisão e riscos. Em uma chamada por pasta e identificador, o arquivo fica em stories/<id>-<nome>.md dentro daquela pasta. Na entrada livre, o padrão é spec-<nome>.md na pasta configurada de artefatos de implementação. Há uma exceção importante: se a execução bloquear antes de ter uma especificação válida, fora do modo “pasta + identificador”, tenta gravar bmad-build-auto-result-<slug-or-timestamp>.md nessa pasta. slug é um nome curto adequado a arquivo; timestamp é uma marca de data e hora. No modo “pasta + identificador”, o bloqueio fica no próprio arquivo sob stories/, mesmo que ele contenha apenas o registro mínimo do problema.

Um arquivo já marcado blocked não volta a executar só porque o problema externo foi corrigido. Na chamada direta por pasta e identificador, a documentação exige retirar o arquivo bloqueado para que o identificador volte a ser tratado como trabalho novo; preserve a evidência antes. Quando quem coordena é o Loop, use o procedimento de recuperação da Etapa 30: o orquestrador prepara os arquivos e o estado da nova tentativa. Não troque blocked por done para fazer a fila andar.

Build Auto exige suporte a subagentes, que são sessões auxiliares chamadas para tarefas como implementar e revisar. Sem essa capacidade, termina bloqueado com no subagents. Quando há Git, exige uma cópia de trabalho limpa e permissão para atualizar os metadados do repositório. No sucesso, faz commits locais e não envia as mudanças para o servidor remoto.

Checklist da Etapa

• Você sabe se está delegando uma entrega ou uma fila.
• O objetivo e os critérios de aceite estão registrados.
• Você sabe onde ler o resultado; não depende apenas da última mensagem do chat.
• Entendeu que done significa conclusão daquele fluxo, não autorização para publicar o produto.

Instalar o módulo pelo instalador do BMAD coloca suas skills no projeto. Isso ainda não instala o programa Python que controla a fila. A skill bmad-loop-setup completa essa segunda parte: instala ou atualiza o programa, prepara o projeto e executa uma conferência de prontidão. Portanto, ela não é uma consulta inofensiva sobre como o Loop funciona.

Um hook é uma ação automática disparada por um evento da ferramenta, como o término de uma sessão. O Loop registra hooks para receber sinais das sessões de IA. O uv é o gerenciador usado pelo setup para instalar o programa Python em um ambiente próprio da ferramenta. CLI é a interface de linha de comando de um programa, usada pelo terminal; o Claude Code é a ferramenta de linha de comando principal desta aula. Os conceitos de ambiente de ferramenta do uv e hooks do Claude Code também foram conferidos na documentação de seus fabricantes.

O setup percorre estas decisões:

1. 1

   Identifica o módulo e o projeto.

   Lê assets/module.yaml, verifica se há _bmad/ e se _bmad/bmad-loop/ existe. A ausência do registro do módulo não impede a instalação do programa; ela deve ser relatada. O registro no BMAD e o catálogo geral de ajuda continuam sob responsabilidade do instalador.

2. 2

   Distingue instalação nova de atualização.

   Confere bmad-loop --version e uv tool list. Encontrar o executável no terminal não basta: ele pode estar vindo de uma cópia de desenvolvimento ou de outro ambiente Python. Se o uv já gerencia a ferramenta, ou o pedido diz upgrade ou update, a skill trata como atualização.

3. 3

   Instala o programa na máquina.

   Usa o repositório público oficial. O extra [tui] acrescenta as dependências do painel visual no terminal. Fixar a versão do módulo no BMAD não fixa automaticamente esta instalação separada do programa: a tag precisa ser informada também nesta parte.

4. 4

   Inicializa o projeto.

   Executa bmad-loop init, registrando os hooks das CLIs escolhidas, copiando as três skills do Loop, criando .bmad-loop/policy.toml e acrescentando entradas ao .gitignore. O arquivo de política guarda as decisões desta máquina sobre a execução.

5. 5

   Confere prontidão.

   Executa bmad-loop validate, que aponta itens como configuração, fila, Git, ferramenta de terminal e CLI. Um projeto ainda sem fila pronta pode reprovar essa conferência apesar de a instalação ter funcionado.

6. 6

   Relata o resultado.

   Deve mostrar a versão, as CLIs preparadas, o resultado da validação e, numa atualização, a versão anterior e a nova.

Na instalação voltada ao Claude Code, as skills ficam em .claude/skills/ e os hooks entram em .claude/settings.json. O programa também usa .bmad-loop/ para política e registros. As entradas acrescentadas ao .gitignore incluem .bmad-loop/runs/, .bmad-loop/cache/ e .bmad-loop/policy.toml. A política é local à máquina; não presuma que outra pessoa recebeu as mesmas regras só porque clonou o projeto.

O setup atualiza somente _bmad/bmad-loop/module-help.csv dentro de _bmad/. Ele não deve reescrever _bmad/config.toml, o manifesto nem o catálogo central _bmad/_config/bmad-help.csv. Se o módulo nunca passou pelo instalador do BMAD, a cópia desse CSV não faz os itens aparecerem imediatamente na ajuda central: o instalador precisa reconstruí-la.

Leia a skill bmad-loop-setup instalada nesta pasta, sem executá-la. Confira a versão do módulo no manifesto e identifique o que seria instalado na máquina, quais arquivos e hooks seriam alterados no projeto, quais permissões o adaptador do Claude Code usaria e quais pré-requisitos estão ausentes. Apresente o plano usando a versão 0.13.2. Não instale nem inicialize nada nesta conferência.

Esse primeiro Pedido pede uma leitura. Ele não começa com /bmad-loop-setup justamente porque invocar a skill normalmente significa autorizar sua instalação e configuração. Depois de revisar o plano e decidir fazer a preparação, use o Pedido seguinte.

/bmad-loop-setup Prepare somente esta pasta para o Claude Code. Instale o orquestrador fixado na tag v0.13.2, com o painel TUI. Se já estiver instalado, mantenha essa versão e atualize as cópias das skills do projeto quando necessário. Registre os hooks, execute a validação e explique o que mudou na máquina e no projeto. Não inicie nenhuma fila de implementação.

O endereço, o extra [tui], a fixação por tag, init, --project, --cli e validate estão previstos na skill; a tag v0.13.2 foi conferida no repositório oficial. O ponto em --project . significa a pasta atual. Não cole o bloco em outra pasta.

Para substituir uma instalação existente por essa versão específica, a alternativa documentada usa uv tool install --force com a mesma referência Git e, depois, bmad-loop init --project . --cli claude --force-skills. --force-skills sobrescreve as cópias das skills do Loop; sem ele, init preserva diretórios que já existem e uma atualização pode deixar programa e skills em versões diferentes. As customizações em _bmad/custom/ são preservadas.

Antes da primeira execução pelo Loop, abra o Claude Code uma vez na pasta do projeto e conclua autenticação, confiança na pasta e aprovação dos hooks, quando solicitadas. As sessões abertas automaticamente não conseguem responder por você a esses diálogos iniciais. Essa preparação interativa também não foi testada nesta aula.

Há duas outras ramificações do setup. Informar upgrade pede atualização; o procedimento padrão usa uv tool upgrade bmad-loop --reinstall, seguindo a origem já instalada, que pode ser uma tag fixa ou a linha principal de desenvolvimento. Informar skills only ou --no-tool pede para não instalar o programa. A segunda opção não produz um Loop operacional sozinha. --headless e instruções como accept all defaults dispensam perguntas do setup; não tornam a operação somente leitura.

A skill instalada oferece claude, codex, gemini, copilot e antigravity. Escolher várias CLIs registra os hooks de todas, com --cli repetido. Quem executa cada papel é definido separadamente na política: [adapter] escolhe o padrão; [adapter.dev], [adapter.review] e [adapter.triage] podem substituí-lo por etapa. Só registrar o hook do segundo programa não faz a revisão passar a usá-lo. A documentação do programa 0.13.2 também menciona OpenCode, mas esse adaptador não aparece na orientação da skill instalada; mantemos o caminho de Claude Code conferido aqui.

Checklist da Etapa

• Você distinguiu a versão das skills da versão do programa.
• O plano identifica os hooks e arquivos afetados.
• A instalação foi fixada, em vez de seguir uma atualização silenciosa.
• As pendências de validate foram lidas; instalar não foi confundido com estar pronto para executar.

O Loop 0.13.2 se apresenta como beta inicial, anterior à versão 1.0, com possibilidade de mudanças incompatíveis entre versões. Seu caminho principal documentado usa Python 3.11 ou posterior, Git 2.34 ou posterior, um gerenciador de sessões de terminal como tmux — mínimo suportado 3.2 no caminho padrão — e uma CLI configurada. O tmux mantém as sessões de terminal organizadas para o orquestrador. Para esta aula, a suposição de operação é macOS com Claude Code; não há teste de instalação nem de execução em nenhum sistema.

Há uma diferença prática em relação a chamar Build Auto sozinho: o Loop exige Git. Ele usa o repositório para conferir, registrar e recuperar cada unidade; antes de iniciar, a cópia de trabalho precisa estar limpa. Também exige BMAD 6.10.0 ou posterior, a skill completa bmad-build-auto e as skills de revisão que ela utiliza. Na instalação 6.12.4 conferida, existe bmad-review. Uma antiga skill de redirecionamento chamada bmad-dev-auto, sozinha, não substitui os arquivos necessários do Build Auto. A validação deve conferir essas presenças, além da versão do executável.

O campo extra_args da política pode substituir os argumentos padrão do perfil; uma lista vazia retira esses argumentos. Porém, essa mudança pode fazer a sessão parar à espera de permissões, e não foi testada aqui. Não se deve prometer simultaneamente execução totalmente desacompanhada e um modo restrito que ninguém validou. Quando a política da empresa exige aprovações que impedem esse funcionamento, continue com bmad-build acompanhado até existir um ambiente autorizado e testado.

Há também o isolamento do código. Uma worktree é uma pasta adicional de trabalho ligada ao mesmo repositório Git. No uso que o Loop faz dela, a unidade recebe uma branch própria — uma linha separada de alterações. O Git também permite worktrees sem branch, mas essa não é a configuração descrita aqui. No padrão, [scm] isolation = "none", o Loop trabalha diretamente na cópia atual. Com isolation = "worktree", cada unidade pode trabalhar em uma pasta e branch próprias e depois ser integrada localmente à branch de destino. Isso reduz mistura de alterações; não restringe por si só o acesso do programa à máquina, à rede ou às credenciais.

Não deixe outro agente ou processo mudar a mesma cópia durante uma execução no modo padrão. A própria documentação reconhece que uma alteração posterior em arquivo rastreado pode comprovar que houve trabalho, mas não identifica qual sessão fez aquilo. A worktree melhora a atribuição das mudanças. O padrão max_parallel = 1 continua significando execução serial; aumentar esse número não habilita uma equipe paralela nesta versão.

Confira a política do bmad-loop nesta pasta e proponha a configuração para uma primeira história. Mostre: a fila escolhida, a branch de destino, se haverá worktree, os pontos de aprovação humana, os comandos de verificação que já existem no projeto, os limites de tentativas e de duração, o comportamento de orçamento e os argumentos de permissão do adaptador. Não invente comandos de teste, não retire proteções e não inicie a execução. Identifique qualquer condição incompatível com as regras deste projeto.

O arquivo a revisar é .bmad-loop/policy.toml. A tabela abaixo explica as decisões que mudam a experiência do empresário; os nomes são os da versão 0.13.2.

Há uma diferença importante de nomenclatura: apesar do nome per-story-spec-approval, o código coloca essa parada geral depois da fase de desenvolvimento. O controle de planejamento anterior ao código é o spec_checkpoint explicado na próxima Etapa.

Há ainda max_followup_reviews = 1 em [limits]: limita rodadas extras motivadas apenas por uma revisão que já concluiu a história, mas continua recomendando outra opinião. Ao gastar essa concessão, o Loop pode encaminhar a recomendação residual ao trabalho adiado e concluir, respeitando as demais verificações. Isso evita confundir “há limite de três ciclos” com “sempre haverá três revisões”.

Um token é uma unidade de texto processada pela IA; serve para medir uso, mas não equivale a uma moeda nem a um preço único. O Loop exibe totais ponderados e brutos. A ponderação de leitura em cache parte de cache_read_weight = 0.1; o aviso por história tem padrão de 2 milhões de tokens ponderados e o controle por sessão, 4 milhões. Em enforce, o programa pede encerramento e, depois do período configurado, pode terminar uma sessão excedente. A documentação registra limites de observação em alguns adaptadores. Portanto, esses controles não substituem o acompanhamento do consumo da sua conta.

Checklist da Etapa

• O modo de permissão do adaptador foi analisado e é compatível com as regras locais.
• Há uma decisão sobre cópia de trabalho, branch e isolamento.
• Os comandos de verificação foram escolhidos a partir do projeto real.
• Está claro o que gera apenas aviso e o que interrompe a execução.
• A pessoa sabe onde haverá uma parada para decisão.

O Loop aceita duas fontes de histórias. No modo de sprint, padrão, consulta sprint-status.yaml, produzido pelo planejamento do BMAD. No modo de histórias, usa stories.yaml, ao lado de SPEC.md na pasta de especificação do épico. A segunda forma combina diretamente com uma especificação curta desdobrada em entregas.

_bmad-output/specs/oficina-aurora/
├── SPEC.md
├── stories.yaml
└── stories/
    ├── 1-cadastro-de-clientes.md
    ├── 2-registro-de-pedidos.md
    └── 3-historico-do-cliente.md

Os nomes de negócio acima são ilustrativos. SPEC.md, stories.yaml e o diretório stories/ fazem parte do formato documentado. Os arquivos individuais são criados ou retomados pelo Build; não é preciso inventar seus nomes para despachar a primeira execução por pasta e identificador.

A lista é sequencial. O Loop não calcula sozinho quais histórias dependem de quais: se o registro de pedidos precisa do cadastro de clientes, o cadastro deve aparecer antes. --story 2 seleciona somente a história 2; não significa “comece na 2 e continue até o fim”.

No modo de histórias, cada entrada exige id, title e description. O id é uma string: escreva o número entre aspas. Os controles opcionais incluem spec_checkpoint, done_checkpoint, invoke_dev_with e closes_deferred. Não acrescente status ao manifesto: o estado fica no arquivo individual da história. Os identificadores precisam ser únicos, usar letras, números e hífens e não colidir por prefixo seguido de hífen: 3 e 31 podem coexistir; 3 e 3-2 não. Diferenças apenas entre maiúsculas e minúsculas também são rejeitadas. Essa regra evita que a procura pelo arquivo de uma história encontre o de outra.

Build Auto lê title e description da entrada; o chamador é quem interpreta checkpoints e acrescenta a orientação.

Exemplo de trecho de stories.yaml, criado para esta aula:

- id: "1"
  title: "Cadastro de clientes"
  description: "Permitir que a equipe cadastre e consulte clientes com os campos e regras definidos em SPEC.md."
  spec_checkpoint: true
  done_checkpoint: true
  invoke_dev_with: "Use as regras de duplicidade já aprovadas na especificação."

Esse trecho demonstra o formato; não é uma especificação pronta para o seu negócio. A descrição depende de um SPEC.md real que responda quais campos são obrigatórios e como tratar duplicidade. Não substitua uma regra ausente por “use bom senso” quando ela altera o atendimento ao cliente.

No modo de histórias não existem limites entre épicos dentro daquela lista plana. Por isso, deixar apenas o padrão per-epic não cria uma pausa de aprovação nesse modo. Configure os checkpoints das histórias que precisam de leitura humana.

Ao percorrer a lista, o Loop pula histórias já done; não as revisa outra vez automaticamente como faria uma chamada direta de Build Auto ao arquivo concluído. Uma história bloqueada, um arquivo ambíguo ou um estado desconhecido interrompe a sequência normal. Esse comportamento torna importante ler o manifesto junto dos arquivos em stories/, e não apenas contar linhas da fila.

Confira a fila em _bmad-output/specs/oficina-aurora/stories.yaml e sua SPEC.md. Verifique ordem, identificadores, critérios já definidos e checkpoints. Depois execute somente a validação do Loop para essa pasta e a simulação da história 1. Mostre a história selecionada, o que está pendente e onde haverá parada. Não inicie sessões de implementação.

--spec seleciona o modo de histórias para essa chamada. --dry-run mostra o plano sem abrir sessões de agentes. Esses comandos foram conferidos no parser oficial, mas não executados para a aula. No modo de sprint, a alternativa de simulação de um épico é bmad-loop run --project . --epic 1 --dry-run.

Checklist da Etapa

• A fila corresponde ao projeto e à especificação certos.
• As dependências aparecem antes de quem precisa delas.
• A simulação mostra a seleção esperada.
• A primeira execução tem um tamanho pequeno e um resultado verificável.

Inicie o bmad-loop nesta pasta para somente a história 1 de _bmad-output/specs/oficina-aurora. Use a política já revisada e os checkpoints do arquivo. Não mude permissões, limites, testes nem a fila para fazer a execução passar. Informe o identificador da execução e como acompanhar ou interromper. Se houver bloqueio, preserve a evidência e pare conforme as regras do Loop.

Para uma primeira execução limitada pelo número de histórias, há --max-stories 1. Para a fila inteira da pasta, retire a seleção --story; para um épico do modo de sprint, use --epic N com o número real. Esses seletores definem escopo, não resolvem dependências ausentes.

O percurso normal tem cinco movimentos, com ramificações de aprovação e falha:

1. 1

   Escolher a unidade.

   O orquestrador lê a fila e verifica se a história pode começar. No modo de histórias, um checkpoint de especificação pode dividir a execução em planejamento e implementação.

2. 2

   Implementar em uma sessão nova.

   Build Auto planeja ou retoma o plano, implementa, revisa internamente e registra seu resultado. A sessão pode produzir commits locais; o Loop não depende só da frase “terminei”.

3. 3

   Verificar por fora da conversa.

   O Loop confere os artefatos e executa os comandos da política. Uma falha de teste pode gerar uma tentativa de correção com a saída do erro. Falta de ambiente é tratada separadamente quando identificada pelas regras configuradas.

4. 4

   Revisar outra vez, quando a política pedir.

   Abre uma sessão nova apontando Build Auto para a especificação done. Há limites de repetição. Não é uma conversa infinita entre agentes.

5. 5

   Consolidar e seguir.

   O Loop consolida os commits da unidade e, quando configurado com worktree, integra a branch localmente. Depois respeita as paradas configuradas e escolhe a próxima história. Nenhuma dessas etapas equivale a publicar um site ou aprovar o produto em nome do empresário.

Consulte o status da execução do bmad-loop nesta pasta. Explique qual história está ativa, a fase atual, as tentativas, os avisos e qualquer decisão pendente. Mostre o identificador da execução. Não retome nem altere a execução só para responder ao status.

list ajuda a encontrar a execução; status mostra o resumo; tui abre o painel, se o extra [tui] foi instalado. Você também pode usar status ID_DA_EXECUCAO e attach ID_DA_EXECUCAO para uma execução específica. ID_DA_EXECUCAO é um marcador do exemplo: substitua-o pelo identificador real.

O painel é um observador e lançador. Fechá-lo não é o mesmo que parar as execuções que ele iniciou. Para parar após a unidade em andamento terminar, existe stop --graceful; para interromper imediatamente, existe stop sem essa opção. “Imediatamente” descreve a intenção de abandonar a unidade, não uma garantia de latência zero: o programa precisa receber e processar a solicitação, o que pode levar alguns segundos ou aguardar uma chamada em andamento. A parada imediata abandona a unidade em andamento e encerra sua sessão; ela exige uma conferência do estado antes da retomada.

Peça ao bmad-loop uma parada organizada da execução ID_DA_EXECUCAO: conclua somente a unidade já em andamento e não inicie a próxima. Relate o estado final e os arquivos que preciso revisar antes de retomar.

Para uma interrupção imediata:

Para retomar uma execução parada ou pausada, depois de entender a causa:

As três formas estão no parser oficial. Uma pausa por ambiguidade crítica pode precisar de resolve, descrito a seguir, e não apenas de resume.

Os registros principais ficam em .bmad-loop/runs/<run-id>/: state.json guarda o estado da execução, journal.jsonl registra eventos, logs/ guarda o texto das sessões, verify/ guarda saídas de verificações e ATTENTION reúne alertas para a pessoa. O canal de eventos dos hooks também usa uma área de estado do usuário fora do projeto. Por isso, apagar a pasta local manualmente não é uma estratégia correta de recuperação ou desinstalação.

Checklist da Etapa

• Você sabe qual execução iniciou e qual história está em andamento.
• Sabe diferenciar fechar o painel de parar a execução.
• Consegue consultar as verificações reais, não apenas o resumo da IA.
• Vai revisar a primeira história antes de ampliar a autonomia.

Ao implementar uma história, uma revisão pode descobrir um problema verdadeiro que pertence a outra entrega. Build Auto registra esses achados em deferred no arquivo de resultado; o orquestrador decide como encaminhá-los. O Loop usa um registro de trabalho adiado chamado deferred-work.md, com entradas identificadas por DW-<n>. A existência de uma entrada não prova que o defeito ainda existe: outra história pode tê-lo corrigido.

bmad-loop-sweep: verificar e organizar o trabalho adiado

A skill bmad-loop-sweep não é um comando para o empresário chamar diretamente no chat. Ela é uma etapa interna de bmad-loop sweep. A skill verifica se está num contexto de automação; fora dele, deve informar essa limitação e terminar. Durante a triagem comum, lê o código e o registro, não modifica código nem o registro de pendências, não pergunta à pessoa e entrega um result.json. Quem executa as decisões e correções depois é o orquestrador.

Ela classifica cada entrada selecionada uma única vez:

A skill prevê uma exceção restrita para um ajuste de intenção congelada claramente benéfico, não destrutivo e que apenas aperta o comportamento; na dúvida, exige decisão. Essa exceção não deve ser lida como autorização geral para renegociar o produto.

Mostre a prévia das pendências abertas do bmad-loop nesta pasta, sem iniciar sessões de triagem ou correção. Depois explique quais seletores posso usar para limitar a próxima rodada a itens específicos ou a uma gravidade mínima. Não trate uma decisão de negócio como autorizada por estar no registro.

Essa simulação lista a seleção de entradas; ela não é a triagem com leitura detalhada do código pela skill. Para executar a triagem e responder às decisões sem iniciar grupos de correção, existe bmad-loop sweep --project . --decisions-only. Apesar de não implementar grupos, essa segunda chamada roda triagem e pode registrar decisões; não é somente leitura.

As opções de sweep são ramificações úteis, e seus efeitos merecem leitura antes de copiar:

• --only DW-1,DW-3 seleciona exatamente entradas abertas com esses identificadores. Um identificador desconhecido ou já fechado é erro, não uma seleção silenciosamente reduzida.
• --min-severity high seleciona essa gravidade e as superiores. Os valores aceitos são low, medium, high e critical; entradas sem gravidade reconhecida ficam fora e são relatadas. Não pode ser combinado com --only.
• --max-bundles 1 limita a quantidade de grupos de correção executados, depois da triagem. Não significa limitar a triagem a uma entrada.
• --no-prompt executa apenas o que não depende de respostas: decisões humanas continuam abertas. Não significa aprovar todas as opções recomendadas.
• --repeat faz novas rodadas sobre trabalho adiado que surgir; --max-cycles N limita essas rodadas. O padrão da política não repete, e o limite padrão quando há repetição é cinco ciclos.
• --archive arquiva entradas fechadas em deferred-work-archive.md, preservando referências no registro principal. --before DATA restringe por data de fechamento e --dry-run permite prévia. Os seletores de triagem não se combinam com esse arquivamento.

Decisões que ficaram sem resposta podem ser vistas com bmad-loop decisions --list --project . e respondidas com bmad-loop decisions --project .. As opções de negócio se traduzem em construir, fechar ou manter aberto. Para uma rodada pequena de correção, um exemplo de comando é bmad-loop sweep --project . --only DW-1,DW-3 --max-bundles 1; troque os identificadores por entradas reais e leia a prévia antes.

Há uma ramificação interna de migração: bmad-loop-sweep --migrate converte registros antigos para o formato atual. Nessa situação excepcional a skill pode editar o registro. Os argumentos internos --feedback e --only também podem ser fornecidos pelo orquestrador para corrigir uma triagem rejeitada ou delimitar seu universo. Eles não são um convite para criar um result.json à mão.

bmad-loop-resolve: resolver a ambiguidade com uma pessoa

O catálogo instalado do Loop lista Setup e Sweep, mas não Resolve. A terceira skill existe em .claude/skills/bmad-loop-resolve/SKILL.md e foi comparada com a tag oficial. Essa é outra razão para conferir as instruções reais quando a ajuda parecer incompleta.

Uma escalada é a transferência de uma decisão que a automação não consegue tomar com segurança para quem responde pelo produto. Uma escalada CRITICAL pausa o trabalho e preserva evidências. A skill bmad-loop-resolve existe para essa conversa, aberta pelo comando bmad-loop resolve. Diferentemente do Sweep automático, ela pressupõe uma pessoa presente, apresenta de duas a quatro opções e exige uma decisão real.

O caminho normal é: ler o contexto da pausa, ler a especificação afetada, explicar a contradição, discutir opções, registrar a decisão no documento e escrever resolution.json. A skill de resolução não implementa a história, não executa os testes e não faz commit. O orquestrador é quem prepara a nova tentativa e oferece retomar. Se a informação continua ausente, a skill não escreve uma resolução falsa; a execução permanece pausada.

Abra a resolução da execução ID_DA_EXECUCAO do bmad-loop. Apresente a evidência da pausa, a regra de negócio que ficou ambígua e as opções de decisão. Mostre em qual especificação a decisão será registrada e de qual cópia a nova tentativa lerá essa regra. Não marque a decisão como resolvida sem minha resposta.

Não use a skill bmad-loop-resolve isoladamente para fingir esse contexto. O orquestrador prepara variáveis e um context.json com a história, a causa da pausa, os caminhos e a forma de recuperação.

Se o problema é no ambiente — por exemplo, o serviço necessário à verificação parou — a resposta correta é corrigir o ambiente. Não reescreva o requisito de negócio para esconder essa falha. --reverify pode reaproveitar trabalho preservado e repetir verificações nos casos suportados, sem nova sessão de implementação. Já --no-interactive é para quando a correção foi feita por uma pessoa: pula a conversa, não decide o requisito automaticamente.

Outras opções exigem entender a evidência: --story escolhe a história; --no-resume prepara a retomada sem iniciá-la; --restore-patch pode restaurar uma tentativa preservada quando o contrato foi esclarecido a favor daquela implementação. Essa alternativa depende de restore_supported no contexto: não é oferecida quando a nova tentativa descarta a worktree, quando falta uma especificação registrada ou quando o bloqueio ocorreu antes de existir implementação para restaurar. Uma patch é um arquivo que registra diferenças de código e permite reaplicá-las. Não aplique essa patch manualmente dentro da conversa de Resolve: o protocolo determina que o orquestrador faça isso.

Existe também --adopt-branch, disponível para unidades com isolamento em worktree e não para execuções de Sweep, que aceita a branch preservada sem repetir revisão, comandos de verificação nem os fluxos anteriores ao commit. Esta aula não recomenda essa opção para sair de uma falha: ela transfere a validação para a pessoa. --adopt-branch, --restore-patch e --reverify são alternativas mutuamente exclusivas.

Com worktrees, a resolução precisa alcançar a cópia que será lida na nova tentativa. O contexto informa spec_reaches_the_redrive e redrive_base_ref: quando a base é uma branch, a correção precisa estar commitada nela; quando a base é HEAD e a retomada ocorre na cópia principal, a correção precisa estar nessa cópia, sem inventar um commit em outra branch. Resolve deve explicar essa diferença, porque uma edição na worktree descartada pode parecer salva e desaparecer da próxima tentativa.

Há dois casos especiais. Se não foi possível nem planejar, o arquivo de história pode ser um registro mínimo de bloqueio, com sufixo unresolved ou ambiguous; a correção deve atingir SPEC.md ou a entrada de stories.yaml, e o orquestrador preserva e remove esse registro ao preparar uma nova tentativa. Se há vários arquivos que correspondem ao mesmo identificador, é preciso decidir qual é a história válida e corrigir essa ambiguidade; apenas retomar repete o bloqueio.

Checklist da Etapa

• Você chama Sweep pelo orquestrador, e entende que sua skill interna só faz triagem.
• Decisões em aberto não foram transformadas em autorizações automáticas.
• Sabe diferenciar uma interrupção retomável de uma escalada que pede Resolve.
• Uma decisão só é considerada registrada quando está na especificação que a nova tentativa lerá.

O desenho simplifica as transições para explicar o trabalho. “Sem acompanhamento” não significa ausência de checkpoints ou garantia de chegar ao fim: um bloqueio pode devolver a decisão à pessoa. A revisão adicional usa sua própria condição de término e seus limites; a seta de retorno não propõe repetir para sempre.

Combinar módulos não exige ligar todos ao mesmo tempo. Exige que cada recurso receba a decisão ou a evidência de que precisa. Um artefato é o arquivo que registra um resultado de trabalho: a especificação, o plano de testes, o relatório de avaliação ou o registro da implementação. A documentação do método organiza a passagem entre planejamento, construção e verificação por esses resultados.

Na Oficina Aurora, podemos começar por um procedimento humano bem definido: receber a solicitação, identificar a categoria do serviço, conferir dados faltantes e preparar um resumo para o responsável. Um fluxo autoral do Builder padroniza essa triagem. Esse fluxo não vira automaticamente uma funcionalidade do sistema; ele pode continuar sendo uma ferramenta interna usada no chat. Se o negócio quiser colocar a triagem no aplicativo, será preciso descrever e construir a funcionalidade pelo método. Essa separação é uma recomendação editorial: ferramenta de trabalho e produto entregue ao cliente têm objetivos diferentes.

Quando o requisito do produto estiver escrito, o TEA pode apontar o risco de classificar incorretamente uma solicitação urgente ou de permitir encerramento sem autorização. A construção usa os critérios resultantes. Se houver várias entregas pequenas, ordenadas e verificáveis, o Loop pode encadeá-las. O relatório de testes e o registro de cada construção continuam sendo evidências a ler; a presença dos três módulos não substitui essa leitura.

Caminho pequeno: se a oficina precisa apenas corrigir o encerramento sem autorização, uma entrega acompanhada com critérios claros e verificação pode ser suficiente; não é necessário montar uma fila nem ligar o plugin TEA. Caminho maior: quando existem várias frentes, o Loop pode cuidar da lista ordenada de um épico, enquanto uma pessoa ou uma coordenação superior cuida das dependências entre frentes e da integração. O método também permite que uma sessão de IA coordene uma chamada de Build Auto por unidade. Isso exige que cada trabalhador consiga abrir os subagentes de revisão; não basta a sessão principal ter essa capacidade.

/bmad-help Leia os artefatos do sistema da Oficina Aurora e proponha o próximo passo. Já temos a triagem descrita e queremos impedir o encerramento de uma ordem sem autorização do cliente. Separe o que ainda é decisão de negócio, o que deve ser construído e a evidência necessária para aceitar a mudança. Recomende o recurso mínimo para o próximo passo. Se sugerir Builder, TEA ou Loop, explique exatamente qual entrada ele recebe e qual resultado devo conferir. Não execute ainda o recurso recomendado.

O texto após bmad-help é um exemplo autoral. A skill está documentada para orientar conforme módulos e artefatos existentes; o Pedido delimita a decisão desejada.

Conferência da Etapa:

• cada recurso tem uma entrada, um resultado e um responsável por conferir a passagem. Você consegue retirar um módulo da sequência se ele não acrescentar evidência ou economia real.

O Loop 0.13.2 inclui um plugin, uma extensão que entra em pontos definidos de sua execução, para chamar o TEA. Esse plugin vem no pacote do Loop, mas fica inativo até ser habilitado. Ele não inclui a instalação do TEA: pressupõe que o módulo já exista no projeto.

Esta combinação é opcional e não foi executada para a aula. Leia primeiro os dois módulos separadamente. Cada etapa adicional pode abrir uma nova sessão de IA, consumir tempo e produzir mais arquivos para conferir. O ganho só existe quando essas avaliações ajudam a decidir sobre a entrega.

No arquivo .bmad-loop/policy.toml, a seção [plugins] com enabled = ["tea"] habilita a extensão. Preserve outros plugins já configurados ao montar a lista. As opções específicas ficam na seção [plugins.tea]. Depois de habilitar, as seis opções de execução vêm ligadas: td_enabled, atdd_enabled, automate_enabled, trace_enabled, nfr_enabled e review_enabled. Cada uma pode ser desativada individualmente com false.

Build Auto pode já ter criado commits locais durante o desenvolvimento; a etapa do plugin precede a consolidação final feita pelo Loop e não garante ausência de commits anteriores.

As opções trace_blocking, nfr_blocking e review_blocking vêm como false: os resultados orientam, mas não impedem o commit por padrão. Com uma dessas opções em true, um resultado reconhecido como FAIL ou CONCERNS pode interromper a unidade para revisão humana. A opção require_tea, inicialmente true, verifica a presença de _bmad/tea/config.yaml no início.

Confira também a origem do relatório. O plugin procura nomes fixos sob test_artifacts: para Trace, tenta gate-decision.json, e2e-trace-summary.json e traceability-matrix.md, nessa ordem; para NFR, nfr-assessment.md; para Test Review, test-review.md. Ele aproveita o primeiro resultado que consegue interpretar. Nessa leitura, o código não compara data, identificador da história ou revisão Git para provar que o relatório pertence à unidade atual. Um relatório antigo pode, portanto, influenciar a decisão; um caminho personalizado do TEA pode ficar fora dessa procura. Antes de confiar no bloqueio, confira o arquivo efetivamente produzido, sua ligação com a mudança atual e o resultado reconhecido pelo plugin. Essa limitação foi identificada por leitura do código; não houve ensaio da integração.

A integração alcança também os grupos de correção de Sweep, que usam a mesma sequência de desenvolvimento e revisão. Por isso, habilitar as seis chamadas pode acrescentá-las tanto às histórias quanto às correções posteriores; considere esse trabalho ao escolher o que ativar.

Confira se o TEA 1.27.2 e o Loop 0.13.2 estão disponíveis neste projeto. Leia o plugin TEA do Loop e a política existente. Proponha quais das seis chamadas ajudam no nosso caso e estime o trabalho adicional. Queremos testes de aceitação antes da construção, portanto explique como evitar confundir a chamada posterior de ATDD do plugin com essa prática. Mostre também o que acontece se um relatório obrigatório não existir ou não puder ser lido. Não habilite o plugin nem inicie execuções nesta análise.

Não há um Comando de terminal equivalente a essa análise editorial. Depois de aceitar uma configuração concreta, o responsável pode pedir sua aplicação e executar o procedimento do Loop. O arquivo de política é a alternativa de configuração manual, com as chaves acima; não copie um arquivo inteiro de outro projeto sobre o seu.

O guia do plugin cita .claude/commands/bmad/tea/, uma organização antiga. Na instalação conferida, os recursos TEA estão em .claude/skills/. O próprio plugin inclui padrões dessa pasta ao preparar uma cópia de trabalho. Use o caminho instalado, sem criar a pasta antiga para satisfazer um exemplo da documentação.

Conferência da Etapa:

• você sabe quando cada chamada acontece, quais resultados interrompem o fluxo e quem verifica evidências ausentes. A integração não foi ligada nesta aula.

1. Instalei o módulo, mas a skill não aparece. Por onde começo?

   Confira a pasta do projeto, a ferramenta escolhida no instalador e o diretório da skill. Para Claude Code, procure .claude/skills/<nome>/SKILL.md. Confira no manifesto se o módulo entrou. Se necessário, reabra a ferramenta para que ela releia os recursos.

2. Acrescentei --modules, mas o módulo novo não entrou.

   Você pode ter executado a atualização rápida. Use --action update e confira o conjunto final. Não informe apenas o módulo novo se há outros que devem permanecer.

3. O catálogo anuncia uma opção que a skill não oferece.

   Abra o SKILL.md instalado e suas referências. O Builder desta aula é um exemplo: o catálogo anuncia conversão, mas a skill de fluxos instalada não oferece esse caminho da mesma forma. Use somente o caminho sustentado pelo código. Não transforme código de menu em flag inventada.

4. Preciso rodar o setup do Builder para conversar sobre uma ideia?

   Você pode estudar o módulo e formular sua ideia antes de executar qualquer setup. Quando uma skill precisar da configuração, confira os arquivos esperados e o plano da migração descrita na Fase 02. Não rode o setup apenas para tentar corrigir qualquer erro.

5. A análise do Builder deu boa nota. A skill está pronta?

   Uma análise documental não comprova o comportamento em todos os casos. Use exemplos normais, informação faltante e situações fora do escopo. Os avaliadores examinam execuções, mas têm requisitos e efeitos próprios. Não confunda a análise desta aula com avaliações realizadas.

6. O TEA precisa executar todos os fluxos para criar testes?

   Não. Para código existente, bmad-testarch-automate pode trabalhar de forma independente; Test Design é opcional antes, e Trace é opcional depois. Para uma necessidade simples, o QA básico pode bastar.

7. ATDD deixou testes falhando. Isso é defeito?

   Se o comportamento ainda não existe, a falha prevista demonstra o que falta implementar. Isso é diferente de erro de sintaxe, ambiente quebrado ou teste falhando por motivo errado. Leia a evidência. Não enfraqueça o teste apenas para obter uma indicação verde.

8. O relatório fala em evidência insuficiente. Posso pedir aprovação mesmo assim?

   Você pode decidir sobre um risco de negócio, mas o relatório precisa distinguir o comprovado do não comprovado. Peça as evidências ausentes, sua importância e o próximo teste necessário. Não transforme ausência de medição em aprovação técnica.

9. Instalei o Loop, mas o programa não funciona.

   Instalar as skills pelo BMAD e instalar/configurar o orquestrador são operações diferentes. O registro oficial pede o setup adicional. Confira programa, projeto e política conforme a Fase 04. Nesta aula, não rodamos o setup para produzir uma saída de sucesso.

10. O Loop parou em blocked. Devo mandar ignorar?

    Leia a condição de bloqueio e o registro da unidade. Pode faltar uma decisão, uma ferramenta, capacidade de criar subagentes ou clareza do requisito. Corrija a causa e use a retomada correspondente. Corrigir a causa não reativa sozinho um arquivo de história já bloqueado; confira o procedimento de recuperação da Etapa 30 antes de mandar executar de novo. A Fase 04 explica Resolve e a diferença entre corrigir a causa e reativar uma unidade.

11. Marquei uma story e esperava executar todas as seguintes.

    Selecionar uma story executa aquela story, não significa “comece daqui e siga até o fim”. Para percorrer a lista, escolha o modo correspondente e confira sua ordem. O agendador linear não calcula sozinho as dependências.

12. Posso remover o Loop apagando _bmad/bmad-loop/?

    Essa pasta não representa tudo que o setup instala. Há programa na máquina, configuração e hooks no projeto. Pare a execução, inventarie os componentes e planeje a remoção conforme o que foi instalado. Não apague configurações compartilhadas inteiras. Esta aula não testou a desinstalação completa do orquestrador.

    A versão 0.13.2 não oferece bmad-loop uninstall. A documentação descreve uma remoção em partes: encerrar execuções, preservar os registros necessários, limpar cópias de trabalho e sessões restantes com o programa ainda disponível, retirar o estado e somente os hooks do Loop, retirar suas skills e entradas específicas do .gitignore, remover o módulo pelo instalador e, por fim, desinstalar o programa. Faça a parte de cada projeto antes de retirar a instalação compartilhada da máquina. A área de eventos fora do projeto pode atender vários projetos; não apague sua raiz inteira para retirar apenas um.

    Pelo Claude Code

    Pedido para o Claude Code — exemplo autoral de inventário para remoção

    Faça um inventário para remover o bmad-loop deste projeto: execuções ativas, histórico a preservar, cópias de trabalho, hooks, skills, política e entradas do gitignore. Verifique se outros projetos dependem do programa instalado na máquina. Apresente a ordem documentada de remoção e os arquivos exatos, sem apagar nada nesta primeira conferência.

    Pelo terminal

    Pelo terminal — somente a última operação, depois de retirar as integrações dos projetos que dependem dela

    $uv tool uninstall bmad-loop

    Esse Comando desinstala a ferramenta administrada pelo uv; não substitui a limpeza específica de cada projeto. Não foi executado nesta aula.

13. A documentação mais nova mostra outros nomes. Qual sigo?

    Para reproduzir esta aula, siga a instalação e os links de versão aqui citados. docs.bmad-method.org descreve outra geração do método e não foi usado como fonte dos fatos da 6.12. Se você já estiver em outra versão, peça a comparação antes de copiar os procedimentos.