repo-auditor
Skill28 starsChanged 3 months agoApache-2.0View on GitHub
Audita o repositorio e registra sua stack, riscos e convencoes. Trigger em: "repo audit", "auditar repositorio", "mapear stack do projeto", "harnessability score", "repo-audit", "auditoria de repo", "fotografia do repo", "current.md", "mapear convencoes do projeto", "inventariar o codebase".
- Reads credentials
1 other project uses a version of this.
Adopted by
Most recently taken up by
- creanlab/agent-genome-labtheir own version, first seen Jul 10, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- creanlab/agent-genome-lab★ 2same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository92 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- po-feature-specSkill
- ui-ux-designSkill
- backend-apiSkill
- frontend-integrationSkill
- qa-testingSkill
- security-reviewSkill
- deploy-dockerSkill
- context-managerSkill
- orchestratorSkill
- documenterSkill
- reviewerSkill
- motion-designSkill
- marketing-copySkill
- seo-specialistSkill
- mobile-tauriSkill
- image-generatorSkill
- asset-librarianSkill
- observability-sreSkill
- data-analyticsSkill
- accessibility-specialistSkill
- migration-refactor-specialistSkill
- release-managerSkill
- ai-integration-architectSkill
- prompt-engineerSkill
- video-integration-specialistSkill
- claude-md-generatorSkill
- design-intelligenceSkill
- cost-trackerSkill
- session-summarySkill
- smart-suggestionsSkill
- detective-specSkill
- static-analysisSkill
- skill-authorSkill
- web-asset-generatorSkill
- tdd-engineerSkill
- architecture-deepenerSkill
- program-routerSkill
- parallel-dispatcherSkill
- blog-publisherSkill
- blog-screenshotSkill
- canary-deploymentSkill
- zoom-outSkill
- handoff-contextSkill
- post-deploy-canary-monitorSkill
- pattern-conformitySkill
- research-prepSkill
- context-budgetSkill
- direct-response-copySkill
- ux-researchSkill
- ui-polishSkill
- doubt-driven-reviewSkill
- video-analysisSkill
- marketing-reporting-analyticsSkill
- responsive-conversionSkill
- mobile-ux-foundationsSkill
- i18n-localizationSkill
- closed-loop-revenueSkill
- app-reference-architectureSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 94
no primeiro contato com um repositorio
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Repo Auditor
O Repo Auditor cria uma fotografia operacional do repositorio para que o restante do sistema trabalhe com contexto persistido e enxuto.
Harnessability Score (v2.5.0+)
Inspirado em Birgitta Böckeler — "ambient affordances" tornam o codebase mais governável pelo agente. Ver
policies/harness-categories.md+docs/inspiration/harness-engineering.md.
Junto com a auditoria, calcule e reporte o harnessability score do projeto (0-100):
| Sinal | Pontos | Como detectar |
| Linguagem com static typing forte (TS strict, Rust, Go, Java) | +20 | tsconfig.json com strict:true, Cargo.toml, go.mod, pom.xml |
| Linter configurado | +15 | .eslintrc*, ruff.toml, clippy.toml, golangci.yml |
| Module boundaries claros | +15 | DDD (domains/), hexagonal (adapters/ + ports/), feature folders, monorepo tooling |
| Testes existentes c/ cobertura > 60% | +15 | tests/, __tests__/, coverage report ou badge ≥60% |
| CI configurado | +10 | .github/workflows/, .gitlab-ci.yml, Jenkinsfile, etc |
AGENTS.md ou CLAUDE.md presente | +10 | grep no root |
| Repo-audit recente (<30d) | +5 | docs/repo-audit/current.md modtime |
| Constitution definida | +5 | memory/constitution.md existe |
| Dependency scanner | +5 | dependabot config, .snyk, renovate config |
Deduções por Risco:
Além dos sinais positivos acima, certos marcadores de risco SUBTRAEM pontos quando detectados. Este é um modelo conceitual — os pesos abaixo são pontos de partida heurísticos a calibrar por projeto, não números empiricamente validados.
| Sinal de risco | Pontos | Como detectar |
| TODO/FIXME mencionando segurança sem issue rastreada | -10 | grep TODO/FIXME + termos de security/auth sem link de issue |
| Funções >100 linhas sem cobertura de teste | -5 (por instância, com cap) | análise de tamanho de função cruzada com coverage report |
| Dependência com CVE conhecido não tratado | -10 | npm audit, pip-audit, dependabot alerts abertos |
| God-file/god-class acima do threshold sem dono/doc | -5 | tamanho de arquivo + ausência de CODEOWNERS/doc de módulo |
Cap por categoria: nenhuma categoria de dedução sozinha pode subtrair mais que -20 pontos do total de 100 — isso evita que um único tipo de risco zere o score sozinho e preserva o sinal das outras categorias.
Score final = max(0, soma dos sinais positivos + soma das deduções, cada categoria capada).
Modelo de dedução-com-cap e seção "Parece problema, mas está correto" — ver ## Fontes no final deste arquivo.
Interpretação:
| Score | Nível | Recomendação |
| 0-30 | Baixa harnessability | Considerar skill 23 (migration-refactor) antes de feature work pesado. Modo /swarm autonomous arriscado — preferir /auto ou /loop com supervisão. |
| 31-60 | Média | Kit funcional, alguns gaps. Considerar skills 38 (architecture-deepener) + 06 (security-review) pra fortalecer. |
| 61-85 | Boa | Kit roda com pouca supervisão. Modo /swarm aceitável. |
| 86-100 | Alta | Modo /swarm autonomous totalmente viável. |
Ambient affordances: liste os 3 maiores presentes E os 3 maiores gaps no relatório, com recomendações concretas. Exemplo:
## Ambient Affordances
**Top 3 presentes:**
- TypeScript strict habilitado
- Feature folders em `src/features/` com co-location
- Husky + lint-staged em pre-commit
**Top 3 gaps:**
- Sem dependency scanner (recomendado: dependabot)
- Coverage < 40% (skill 05 sugere meta de 60%)
- ADRs ausentes (`docs/adr/` vazio)
**Score: 65/100 (Boa harnessability)**Governanca Global
Esta skill segue GLOBAL.md, policies/execution.md, policies/persistence.md, policies/token-efficiency.md, policies/handoffs.md, policies/tool-safety.md, policies/evals.md e policies/deliberate-simplification.md (consumidor do ledger de comentários simplify: — teto cruzado sem revisão vira achado de dívida técnica ativa).
Deteccao de governanca
Durante a auditoria, registrar em docs/repo-audit/current.md na secao "Governanca":
memory/constitution.mdexiste? (Se nao e o projeto e maduro/tem ADRs/PRDs: sugerir/constitutioncomo acao recomendada no relatorio)- ADRs em
docs/adr/? Quantos e status (accepted/proposed/superseded) policies/customizadas no projeto consumidor
Isso permite que as proximas skills saibam se podem ancorar decisoes em principios formais.
Para auditorias mais completas e revisoes incrementais, consultar docs/skill-guides/repo-auditor.md apenas quando necessario.
Quando Usar
- no primeiro contato com um repositorio
- quando a stack real divergir da stack de referencia do kit
- quando houver duvida sobre convencoes, assets, testes, docs ou risco tecnico
- antes de features grandes, migracoes ou automacoes novas
Quando Nao Usar
- para reanalisar tudo a cada task sem mudanca relevante
- para substituir investigacao pontual muito localizada
Entradas Esperadas
- repositorio atual
- estrutura de arquivos e docs existentes
- sinais de stack, tooling, testes, deploy e identidade visual
Saidas Esperadas
- auditoria curta e reutilizavel em markdown
- resumo executivo para o Orchestrator
- gaps, riscos e recomendacoes priorizadas
Responsabilidades
- Detectar stack, framework, ferramentas e convencoes reais do repositorio
- Identificar documentacao, testes, assets, pipeline e sinais de observabilidade
- Registrar identidade visual e contexto de imagens quando houver
- Persistir um resumo operacional reutilizavel para reduzir releitura futura
- Atualizar a auditoria apenas quando houver mudanca relevante no repositorio
- Encaminhar para
Asset Librarianquando o inventario visual precisar de organizacao dedicada - Recomendar automacoes Claude Code apropriadas ao codebase (modo
--recommend-automation)
Modo Recommend-Automation
Quando rodado com flag --recommend-automation (ou usuario pede explicitamente "recomendar automacoes"), apos a auditoria padrao gerar secao ## Automacoes Recomendadas no relatorio com:
Hooks recomendados (analisar o que o codebase pede)
| Detectado no repo | Hook sugerido | Why |
| Testes em CI demorando > 5min | PostToolUse rodando subset de tests afetados | Feedback rapido |
.env* files com secrets | PreToolUse block em commits que tocam .env* | Prevent leaks |
| Migrations SQL na raiz | PreToolUse warning ao editar migration ja aplicada | Safety |
package.json com 50+ deps | SessionStart mostrando audit/outdated | Awareness |
| Monorepo (turborepo/nx) | SessionStart listando workspaces ativos | Context |
Subagents recomendados
| Detectado | Subagent sugerido |
| Codebase grande (> 100 files) | code-reviewer para PRs |
| Codigo de seguranca (auth, payments, crypto) | security-auditor antes de release |
| Suite de testes complexa | test-engineer para gerar/revisar |
| Bug recorrente em log de issues | debugger para diagnostico sistematico |
Skills do kit recomendadas
Apontar quais skills do catálogo atual se aplicam ao projeto:
- Frontend? → skills 02, 04, 22 (a11y), 36 (web-assets)
- Backend? → skills 03, 06 (security), 20 (observability)
- Mobile? → skill 15 (mobile-tauri)
- IA features? → skills 25, 26, 27 + patterns/ai-integration/
MCP servers recomendados
Se o projeto usa serviços externos sem MCP server:
- GitHub heavy → MCP server do GitHub
- Banco frequente → MCP server do Postgres/Mongo
- Design system → Figma MCP
Slash commands relevantes
Sugerir 3-5 commands do kit que se aplicam ao workflow detectado.
Output format do recommend-automation
## Automacoes Recomendadas (skill 18 — modo recommend)
### Alta prioridade
- [ ] Instalar hook `pre-execution-gate.mjs` — detectado: testes em CI demoram 8min
- [ ] Adicionar subagent `security-auditor` — detectado: 23 files em src/auth/
- [ ] `/constitution` — projeto maduro (> 6m, 12 ADRs) sem governanca formal
### Media prioridade
- [ ] Skills 02/22/36 — projeto e frontend-heavy sem cobertura a11y
- [ ] MCP server do GitHub — 230 issues abertas, gh CLI usado em 14 scripts
### Baixa prioridade
- [ ] /consolidate-memory weekly schedule — vault tem 320 logsArquivo de Persistencia
Persistir em docs/repo-audit/current.md (indice) e splits dinamicos no mesmo diretorio.
Se o kit estiver instalado em .bot/, persistir em .bot/docs/repo-audit/.
Se houver reauditoria relevante, arquivar snapshots curtos em docs/repo-audit/history/.
Output Split
Ao auditar, gerar arquivos focados por tipo alem do current.md. Decidir quais gerar baseado no que o repo contem — nao gerar arquivos vazios.
Catalogo de Splits
| Arquivo | Gerar quando detectar | Conteudo |
current.md | sempre | Indice enxuto: stack, convencoes, riscos, gaps. Aponta para splits: Ver routes.md para endpoints |
routes.md | API routes (Express, Fastify, Next API, Django urls, Flask, etc.) | Endpoints por recurso, metodos HTTP, middlewares, auth |
schema.md | ORM/schema (Prisma, Drizzle, TypeORM, Sequelize, migrations) | Models, campos-chave, relacoes FK, enums |
components.md | Framework de componentes (React, Vue, Svelte, Angular) | Arvore por feature, props, client/server, lazy |
services.md | Camada de servicos/usecases (classes com patterns service/usecase) | Servicos, dependencias, metodos publicos |
infra.md | Docker, CI/CD, Terraform, k8s, serverless | Containers, pipelines, environments, secrets ref |
Regras do Split
- current.md nunca duplica conteudo dos splits — apenas referencia com ponteiro
- Cada split cabe em ~200 linhas — se passar, resumir mais agressivamente
- Notacao compacta — usar
fn nome(args): tipo,[auth,db]pra tags,(c)pra client components - Geracao incremental — so re-gerar split se arquivos relevantes mudaram (verificar via git diff)
- Path dos splits — mesmo diretorio do
current.md(docs/repo-audit/ou.bot/docs/repo-audit/)
Deteccao
Para decidir quais splits gerar, verificar:
routes.md: existencia deapp.get/post/put/delete,router.,@Get/@Post,urlpatterns,api/dir com handlersschema.md: existencia deschema.prisma,*.entity.ts,models.py, diretoriomigrations/components.md: existencia de.tsx/.vue/.svelteemsrc/components/ouapp/services.md: existencia de*Service.ts,*UseCase.ts,services/dir,usecases/dirinfra.md: existencia deDockerfile,.github/workflows/,terraform/,k8s/,docker-compose
Quando Reauditar
- auditoria ausente
- auditoria com sinais claros de desatualizacao
- mudanca relevante de stack, assets, testes, deploy ou observabilidade
- reestruturacao grande do repositorio
Gate de Orientação por Churn (dívida técnica)
Antes de auditar dívida técnica em repo grande, priorizar onde investigar em vez de varrer tudo:
# 20 maiores arquivos por linha
find . -name "*.ts" -o -name "*.tsx" -o -name "*.py" | xargs wc -l | sort -rn | head -20
# 20 arquivos mais modificados nos últimos 6 meses
git log --since="6 months ago" --name-only --pretty=format: | sort | uniq -c | sort -rn | head -20A interseção das duas listas — arquivo grande E frequentemente modificado — é onde dívida técnica real se concentra: código que já é difícil de entender e que continua mudando, sinal de que ninguém teve confiança de refatorá-lo. Auditar a interseção primeiro; o resto entra na varredura padrão.
Conteudo Minimo da Auditoria
- stack principal e ferramentas detectadas
- estrutura de codigo e docs relevantes
- padroes de auth, testes, deploy e observabilidade
- assets e identidade visual existentes
- riscos, gaps e areas que exigem cuidado extra
- ultima data de revisao
Estrutura Recomendada do Markdown
Usar templates/audit.md como base e manter secoes curtas, atualizaveis e reutilizaveis.
Checkpoint antes de persistir: para cada afirmação da auditoria ("usa Prisma", "testes com Vitest", "deploy via Docker"), confirmar contra um arquivo real do repo (package.json, docker-compose.yml, config de teste) — não contra memória de repos parecidos. Se uma seção não pôde ser confirmada, marcar explicitamente como não-verificado em vez de preencher por inferência silenciosa; uma auditoria com gap marcado é mais útil que uma completa e errada.
Seção obrigatória: "Parece problema, mas está correto"
Toda auditoria de dívida técnica ou de risco tem viés de over-flagging: é fácil apontar padrão incomum, é difícil confirmar que ele é deliberado e correto no contexto. Antes de fechar o relatório, listar explicitamente 2-3 itens que pareciam dívida técnica à primeira vista mas, ao investigar o contexto (histórico do arquivo, comentário, ADR, constraint externa), se confirmaram como decisão correta.
- Exemplos do que entra aqui: uma duplicação de código que existe porque os dois caminhos vão divergir em breve (feature flag em rollout); uma dependência "desatualizada" que está travada por incompatibilidade documentada; um arquivo grande que é gerado e não deveria ser modularizado.
- Se esta seção vier vazia, tratar como sinal de auditoria rasa — não como "o repo não tem nenhum caso desses". Investigar de novo antes de aceitar zero itens.
- Formato:
Item | Por que parecia problema | Por que está correto | Evidência (arquivo/commit/ADR).
## Parece problema, mas está correto
| Item | Por que parecia dívida | Por que está correto | Evidência |
|---|---|---|---|
| `checkout.ts` duplica validação de `cart.ts` | DRY violation óbvia | Os dois fluxos divergem no rollout do novo checkout (feature flag `NEW_CHECKOUT`) — unificar agora quebraria o rollback | `flags.ts:12`, ADR-014 |Regras de Economia de Token
- ler primeiro a auditoria existente antes de explorar o repo novamente
- atualizar apenas as secoes afetadas quando a base nao mudou muito
- evitar revarrer arquivos grandes se a auditoria ainda estiver valida
Evidencia de Conclusao
docs/repo-audit/current.mdcriado ou atualizado (indice enxuto)- splits relevantes gerados (
routes.md,schema.md, etc.) conforme deteccao - stack e convencoes reais mapeadas
- riscos e gaps principais registrados
Handoff
Entregar:
- caminho do arquivo de auditoria
- o que foi confirmado
- o que ainda esta incerto
- proxima skill que pode usar a auditoria
Seguir policies/handoffs.md e, quando util, templates/audit.md.
Fontes
- Modelo de dedução-com-cap do Harnessability Score inspirado na abordagem de health-scoring calibrado de repowise-dev/repowise (AGPL-3.0) — só o modelo conceitual foi adaptado, nenhum código ou peso específico de marcador foi copiado (a licença AGPL é o motivo de não herdar código).
- A seção "Parece problema, mas está correto" e o gate de orientação por churn foram inspirados no mecanismo de ksimback/tech-debt-skill (sem licença declarada) — por isso reimplementados integralmente com redação própria, sem copiar texto da fonte.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

