# Repo Auditor

> |

- **Type:** Skill
- **Install:** `agentstack add skill-felvieira-claude-skills-fv-18-repo-auditor`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [felvieira](https://agentstack.voostack.com/s/felvieira)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [felvieira](https://github.com/felvieira)
- **Source:** https://github.com/felvieira/claude-skills-fv/tree/main/skills/18-repo-auditor

## Install

```sh
agentstack add skill-felvieira-claude-skills-fv-18-repo-auditor
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

```markdown
## 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](https://github.com/felvieira)
- **Source:** [felvieira/claude-skills-fv](https://github.com/felvieira/claude-skills-fv)
- **License:** Apache-2.0

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-felvieira-claude-skills-fv-18-repo-auditor
- Seller: https://agentstack.voostack.com/s/felvieira
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.