toyin-software-factory/audit

Estilo de saída (palavras simples, sem traços, sem hífens)

Escreva tudo que essa skill produz, arquivos e mensagens, em linguagem simples e clara. Fale com o leitor como você, de forma calorosa e direta como um colega, e apresente cada passo como uma recomendação que pode ser executada ou ignorada, nunca uma ordem. Mantenha os termos técnicos que carregam significado real; explique cada um em palavras simples. Nunca use um travessão ou hífen como pontuação: sem travessão longo, sem travessão médio e sem compostos hifenizados. Escreva somente leitura, não somente-leitura. Diga em palavras simples ou reformule a frase. Código, caminhos de arquivo, flags de comando e valores que outras skills usam para correspondência mantêm seus hífens. Use frases curtas, vírgulas ou parênteses. Clareza vence esperteza.

O que essa skill faz

O inicializador de contexto: escreve os arquivos AGENTS.md que toda skill posterior e ferramenta de IA lê.

• Projeto verde (sem código ainda): pergunte sobre padrões de codificação, crie o AGENTS.md raiz a partir das respostas, mais a abordagem de construção (nome e princípio de uma linha) do cabeçalho de escopo se /scope definiu um. Executa após o projeto ser estruturado com sua stack escolhida (/scope → /architect decide a stack → estrutura → /audit); antes disso é prematuro.
• Projeto existente, sem documentação (código, sem AGENTS.md): escaneie todo o projeto, escreva AGENTS.md raiz e arquivos <area>/AGENTS.md aninhados, julgando o que é global (raiz) vs específico da área (aninhado).
• Projeto existente, parcialmente documentado: verifique os documentos raiz e aninhados existentes em relação a toda a base de código; adicione apenas o que está faltando (novos fatos globais, documentos aninhados para áreas não documentadas); nunca sobrescreva conteúdo curado.

Não cria especificações (quem faz isso é o /architect), não mantém arquivos após mudanças (quem faz isso é o /sync) e não escreve o escopo de funcionalidade (quem faz isso é o /scope com docs/scope/).

Convenção de arquivos de contexto (AGENTS.md é canônico)

O contexto durável vive no AGENTS.md independente de ferramenta (raiz e aninhado); todo agente (Codex, Cursor, Claude Code e outros) o lê. CLAUDE.md é apenas um ponteiro de uma linha cujo corpo inteiro importa o AGENTS.md irmão via importação @ do Claude Code (corpo do ponteiro exato em agent-prompt.md); o conteúdo nunca é duplicado entre os dois.

• Escreva conhecimento em AGENTS.md. Crie-o quando estiver faltando. Nunca sobrescreva um AGENTS.md existente (pode ter sido criado pelo usuário ou por uma ferramenta); preencha lacunas com cuidado, com permissão.
• Migre conteúdo legado: um CLAUDE.md com conteúdo, mas sem AGENTS.md → peça permissão, mova seu conteúdo para um novo AGENTS.md, substitua CLAUDE.md pelo ponteiro. Nunca descarte silenciosamente conteúdo curado.
• A raiz deve ser curta e global; AGENTS.md aninhados apenas para áreas significativas com convenções reais (mesmas regras de raiz/aninhado aplicadas anteriormente a CLAUDE.md).

Escopo

Um argumento de caminho de área (ex.: auth, src/payments) aciona a Fase 3. Sem argumento, os sinais de Pré-verificação abaixo roteiam para a Fase 0 (ambíguo: perguntar se novo vs existente), Fase 1 (projeto verde: perguntar padrões, semear raiz), Fase 2 (estabelecido, sem AGENTS.md raiz: varredura completa do repositório) ou Fase 4 (AGENTS.md raiz existe: preencher lacunas). Um CLAUDE.md legado com conteúdo, mas sem AGENTS.md, é migrado e então tratado como Fase 4.

Ações vs perguntas

A Fase 1 faz perguntas sobre padrões de codificação via múltipla escolha antes de criar o AGENTS.md raiz. A Fase 2 age imediatamente, sem perguntas; ela escreve a raiz e os documentos aninhados que julgar necessários. As Fases 3 e 4 agem para explorar, mas pedem permissão antes de modificar um AGENTS.md raiz existente ou migrar um CLAUDE.md legado; a Fase 4 relata a criação de documentos aninhados para áreas não documentadas primeiro e, em seguida, aplica após confirmação.

Propriedade dos artefatos

Os arquivos AGENTS.md contêm o conteúdo: crie a raiz se estiver faltando (Fases 1, 2) e <area>/AGENTS.md se estiver faltando e for justificado, por julgamento (Fases 2, 3, 4); quando um existir, preencha lacunas ou proponha adições com permissão; nunca sobrescreva. Os arquivos CLAUDE.md são apenas ponteiros (raiz e área), criados se estiverem faltando; um legado com conteúdo é migrado para AGENTS.md com permissão. Ao criar um AGENTS.md aninhado, adicione exatamente uma linha de ponteiro para o AGENTS.md raiz em ## Context files: - [<area>/AGENTS.md](<area>/AGENTS.md) (<descrição de uma linha>). Nunca um por subpasta, apenas onde existem convenções distintas.

Portabilidade (qualquer SO, qualquer agente)

• Comandos: git é o único CLI necessário, igual em todos os SOs. Outros trechos de shell (contagens de arquivos, find, [ -f ]) são referência POSIX, não scripts literais; use as ferramentas de arquivo multiplataforma do seu agente (pesquisa/glob, leitura, escrita) para listar, contar e verificar existência.
• Os arquivos incluídos residem na pasta desta skill: agent-prompt.md, os arquivos de modo de fase (modes/*.md) e as predefinições de padrões (patterns/*.md). Resolva a pasta para um caminho absoluto. Leia o arquivo de modo de fase correspondente ao rotear, depois agent-prompt.md mais a predefinição de padrão SELECIONADA no momento da escrita. Seus placeholders EM_MAIÚSCULAS (PHASE, AREA, ADDITIONAL_STANDARDS, MONOREPO_OR_NO, INSTALLED_SKILLS, DECLINED_TOOLS e assim por diante) são as entradas que você coletou na pré-verificação e nas rodadas de perguntas; aplique cada um conforme lê.
• Sem suporte a perguntas interativas? Faça qualquer pergunta de múltipla escolha como texto simples com as mesmas opções.

Execução

O fluxo principal faz a escrita em cada fase; ele nunca entrega a escrita de AGENTS.md a um subagente. O único subagente é um scout somente leitura (modelo mais barato, Claude Code: haiku, nunca o modelo da sessão), gerado apenas para uma varredura grande; ele retorna um mapa compacto a partir do qual o fluxo principal escreve. Uma estrutura pequena ou uma única área não precisa de scout; leia diretamente. Imediatamente antes de escrever, leia agent-prompt.md (persona, instruções por fase, modelos) mais, na Fase 1, a predefinição de padrão selecionada; então escreva seguindo-o. Leia agent-prompt.md apenas no momento da escrita, não durante a pré-verificação.

Pré-verificação (o fluxo principal faz isso antes de qualquer outra coisa)

Reúna vários sinais (uma contagem de arquivos sozinha engana: uma estrutura a infla, uma linguagem desconhecida a zera):

1. Arquivos de contexto: AGENTS.md raiz presente → ROOT_EXISTS; um CLAUDE.md com conteúdo apenas → ROOT_LEGACY; nenhum → ROOT_MISSING.
2. Contagem de fontes em ecossistemas comuns (extensões como .ts/.tsx/.js/.jsx/.py/.go/.rs/.java/.rb/.swift/.kt/.php/.cs/.dart/.ex/.exs/.scala/.c/.cpp/.h/.lua/.clj), excluindo diretórios de terceiros/gerados (node_modules, .git, dist, build) e arquivos de configuração (*.config.*).
3. Sinais estabelecidos: git log --oneline para profundidade do histórico de commits; um manifesto real (package.json, pyproject.toml, go.mod, Cargo.toml, composer.json, *.csproj, pubspec.yaml, mix.exs, Gemfile).
4. Sinal de monorepo: marcadores de workspace (pnpm-workspace.yaml, turbo.json, um campo "workspaces" em package.json) ou qualquer apps/*/package.json / packages/*/package.json próximo à raiz.
5. Sinal de configuração de fluxo de trabalho (WORKFLOW_SETUP): o AGENTS.md raiz está FALTANDO enquanto o fluxo de trabalho já decidiu a stack, ou seja, uma especificação de arquitetura docs/specs/ existe (uma seção ## Proposed stack), e/ou docs/scope/ tem uma funcionalidade "Stack and architecture" (ou similar de estrutura fundamental). Esta é a ordem pretendida de projeto verde (/scope → /architect decide a stack → /develop estrutura → /audit): recém-estruturado, ainda precisa capturar padrões de codificação. Quando isso acontece, o manifesto e o código-fonte da estrutura que agora existem são a estrutura, não uma base de código existente.

Escolha a fase. A ordem das verificações importa: o sinal de configuração de fluxo de trabalho supera a contagem bruta de código, porque uma estrutura nova tem um manifesto e arquivos de origem, mas ainda é um projeto verde.

Condição	Fase
Caminho de área fornecido como argumento	Fase 3
ROOT_EXISTS (ou ROOT_LEGACY após migração)	Fase 4
ROOT_MISSING e WORKFLOW_SETUP (especificação de stack e/ou funcionalidade de escopo de stack)	Fase 1, mesmo que um manifesto e código-fonte de estrutura existam agora. Pergunte sobre os padrões de codificação; semeie a raiz a partir da stack da especificação. Nunca trate um projeto de fluxo de trabalho recém-estruturado como base de código existente.
ROOT_MISSING, sem WORKFLOW_SETUP, sem arquivos de origem E sem manifesto	Fase 1
ROOT_MISSING, sem WORKFLOW_SETUP, tem código (origem ≥ 10 ou um manifesto), ≥ 2 commits e claramente código de funcionalidade real (não apenas estrutura)	Fase 2, qualquer linguagem
ROOT_MISSING, sem WORKFLOW_SETUP, tem código, mas parece estrutura intocada, ou ≤ 1 commit, ou você não consegue distinguir projeto verde de base existente	Fase 0, pergunte

Por que essa ordem: uma estrutura nova tem um manifesto e arquivos iniciais, mas ainda é um projeto verde, então uma contagem bruta de código sozinha o interpretaria erroneamente como base existente e pularia as perguntas sobre padrões; o sinal de configuração de fluxo de trabalho captura isso e roteia para projeto verde. Base existente real (Fase 2) significa código de funcionalidade real, histórico real e nenhuma configuração de fluxo de trabalho em andamento. Qualquer coisa ambígua cai na Fase 0; nunca assuma que um projeto talvez verde é base existente.

Monorepo (MONOREPO=yes): raiz mais um stub leve por workspace, aprofunde sob demanda. Cada workspace (apps/*, packages/*) é uma área de primeira classe; seu documento principal reside na raiz do workspace (packages/api/AGENTS.md), nunca enterrado mais profundamente. Uma execução de repositório inteiro não faz varredura profunda em cada workspace; escreva o AGENTS.md raiz do repositório (ferramentas de todo o monorepo, convenções compartilhadas) mais um stub leve por workspace a partir de seu manifesto, sem varredura de código, com ponteiros raiz. A varredura completa de convenções/gotchas/arquivos chave acontece quando o engenheiro executa /audit packages/api (Fase 3) ou constrói lá pela primeira vez. Um ponto dentro de um workspace que justifica seu próprio documento (packages/ui/src/mdx/) recebe um, além do documento raiz do workspace, vinculado a ele. Um documento já enterrado em um workspace sem documento raiz do workspace: pergunte: "packages/ui tem um arquivo de contexto em src/mdx/, mas nenhum em sua raiz. Mover para packages/ui/AGENTS.md, ou mantê-lo como documento aninhado sob um novo packages/ui/AGENTS.md?" Em caso de movimentação: realoque para a raiz do workspace. Em caso de manter aninhado: crie o AGENTS.md raiz do workspace E mantenha o profundo, vinculado da raiz. Migre o conteúdo legado de CLAUDE.md conforme a convenção acima. Aplique MONOREPO=yes mais a lista de workspaces ao escrever.

Migração legada (qualquer fase): em ROOT_LEGACY, antes de prosseguir, peça permissão: "Encontrei um CLAUDE.md com contexto de projeto, mas sem AGENTS.md. Vou mover seu conteúdo para um novo AGENTS.md (para que todas as ferramentas o leiam) e substituir CLAUDE.md por um ponteiro. Prosseguir?" Em caso afirmativo: copie o conteúdo literalmente para AGENTS.md, depois substitua CLAUDE.md pelo ponteiro; AGENTS.md agora existe, então continue como Fase 4 (preenchimento de lacunas). Em caso negativo: deixe ambos intactos e continue sem migrar. O mesmo para qualquer <area>/CLAUDE.md aninhado.

Roteie para a fase selecionada

A Fase 0 (ambígua) é tratada inline abaixo. Para as Fases 1 a 4, leia apenas o arquivo de modo correspondente e siga-o:

• Fase 1 (configuração de projeto verde) → modes/greenfield.md
• Fase 2 (varredura de repositório inteiro) → modes/whole-repo.md
• Fase 3 (varredura de área) → modes/area.md
• Fase 4 (preenchimento de lacunas) → modes/gapfill.md

Não leia os outros arquivos de modo. Os modos de projeto verde e repositório inteiro leem adicionalmente modes/tool-skills.md para a varredura de Agent Skills / MCP (pule para execuções de área e preenchimento de lacunas).

Fase 0: Classificar (apenas quando a pré-verificação é ambígua)

Não adivinhe. Pergunte uma vez através do seletor de opções interativo do seu agente (AskUserQuestion no Claude Code), ou texto simples com as mesmas opções. Marque uma opção (recomendado) pelo sinal que for mais forte (uma árvore semelhante a estrutura com um manifesto, mas pouco histórico, tende a Novo; código de funcionalidade real e histórico profundo tende a Existente), e o seletor adiciona um slot personalizado de texto livre por último:

• pergunta: "Não consigo dizer se este é um projeto novo ou uma base de código existente (<explique o motivo: ex.: 'um manifesto existe, mas não vejo código-fonte em uma linguagem que reconheço', ou 'os arquivos parecem estrutura intocada'>). Qual é?"
• cabeçalho: "Estado do projeto"
• opções: 1. Novo projeto, "Vou perguntar sobre seus padrões de codificação e semear o contexto." → Fase 1 (leia o manifesto/estrutura para a stack; ainda pergunte os padrões). 2. Base de código existente, "Vou escanear o que está aqui e documentar." → Fase 2.

Após todas as fases

Se nenhum AGENTS.md foi escrito quando deveria ter sido (o arquivo está faltando/vazio), relate a falha e faça novamente; não relate sucesso se não produziu. Caso contrário, relate o relatório: o que foi descoberto (2 a 4 marcadores), o que foi escrito (caminhos de arquivo), o que foi proposto ou pulado (se arquivos existentes foram encontrados).

Predefinições de padrões

Veja patterns/ para as quatro predefinições de estilo de codificação usadas na Fase 1 (modo projeto verde).

Guia de escrita

Veja agent-prompt.md (o fluxo principal o lê no momento da escrita; suas instruções por fase e modelos de AGENTS.md).