Repo Auditor

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 ( 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 das 37 skills 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 logs

Arquivo 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

1. current.md nunca duplica conteudo dos splits — apenas referencia com ponteiro
2. Cada split cabe em ~200 linhas — se passar, resumir mais agressivamente
3. Notacao compacta — usar fn nome(args): tipo, [auth,db] pra tags, (c) pra client components
4. Geracao incremental — so re-gerar split se arquivos relevantes mudaram (verificar via git diff)
5. 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 de app.get/post/put/delete, router., @Get/@Post, urlpatterns, api/ dir com handlers
• schema.md: existencia de schema.prisma, *.entity.ts, models.py, diretorio migrations/
• components.md: existencia de .tsx/.vue/.svelte em src/components/ ou app/
• services.md: existencia de *Service.ts, *UseCase.ts, services/ dir, usecases/ dir
• infra.md: existencia de Dockerfile, .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

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.

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.md criado 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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: felvieira
• Source: felvieira/claude-skills-fv
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.