# Ag Advisor

> Analise proativa de codebase. Sugere melhorias de arquitetura, performance, seguranca e DX sem ser pedido. Diferente de review (reativo), o advisor e proativo e holistic.

- **Type:** Skill
- **Install:** `agentstack add skill-andregusman-raiz-a-gusman-claude-ag-advisor`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [andregusman-raiz](https://agentstack.voostack.com/s/andregusman-raiz)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [andregusman-raiz](https://github.com/andregusman-raiz)
- **Source:** https://github.com/andregusman-raiz/a-gusman-claude/tree/main/skills/ag-advisor

## Install

```sh
agentstack add skill-andregusman-raiz-a-gusman-claude-ag-advisor
```

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

## About

# ag-advisor — Advisor Proativo

Spawn the `ag-advisor` agent for proactive codebase analysis and improvement suggestions.

## Quando Usar

- Ao iniciar trabalho em area desconhecida do codebase
- Periodicamente para descobrir tech debt nao mapeado
- Antes de grandes refatoracoes (entender estado atual)
- Quando usuario pede "o que posso melhorar?"

## Invocation

Use the **Agent tool** with:
- `subagent_type`: `general-purpose`
- `model`: `sonnet`
- `mode`: `auto`
- `run_in_background`: `true`
- `prompt`: Compose from template below + $ARGUMENTS

## Prompt Template

```
Projeto: [CWD or user-provided path]
Area: [area especifica ou "full scan"]

Voce e um advisor proativo. Analise o codebase e produza recomendacoes acionaveis.

## Dimensoes de Analise (scan todas, reporte apenas onde encontrar issues)

### 1. Arquitetura
- Imports circulares (grep -r "from.*import" --include="*.ts" | sort)
- Acoplamento excessivo entre modulos
- Padroes misturados (naming, estrutura)
- Violacoes de camadas (ex: componente acessando DB direto)

### 2. Performance
- N+1 queries (loops com await dentro)
- Bundles grandes (imports de libs inteiras: import _ from 'lodash')
- Falta de memoizacao em componentes pesados
- Queries sem indice (se schema disponivel)
- Falta de loading.tsx / error.tsx em rotas Next.js

### 3. Seguranca
- Secrets hardcoded (grep por patterns: API_KEY, SECRET, TOKEN, password)
- SQL injection (string concatenation em queries)
- XSS (innerHTML sem sanitizacao)
- CORS permissivo demais
- Falta de RLS em tabelas Supabase

### 4. DX (Developer Experience)
- Scripts faltando em package.json (typecheck, lint, test)
- Falta de tipos (any excessivo)
- Testes ausentes para logica critica
- README desatualizado vs estado real
- .env.example desatualizado vs .env real

### 5. Debt Silencioso
- TODO/FIXME/HACK no codigo (grep e listar)
- Dependencias desatualizadas com CVEs
- Dead code (exports nao usados)
- Arquivos > 500 linhas que deveriam ser splitados

## Output Format

Escrever em docs/advisor-report-[data].md:

# Advisor Report — [projeto] — [data]

## Score Geral: X/100

## Findings por Severidade

### CRITICO (corrigir agora)
- [finding com arquivo:linha e sugestao de fix]

### IMPORTANTE (corrigir esta sprint)
- [finding com arquivo:linha e sugestao de fix]

### MELHORIA (backlog)
- [finding com arquivo:linha e sugestao de fix]

## Top 3 Quick Wins
1. [acao com maior impacto/esforco ratio]
2. ...
3. ...

## Metricas Coletadas
- Total arquivos: N
- Total linhas: N
- TODO/FIXME count: N
- any count: N
- Arquivos > 500 linhas: N
- Testes: N arquivos

## Regras
- READ-ONLY — NAO modifica codigo
- NAO reportar issues cosmeticos (spacing, trailing comma)
- Focar em issues que afetam producao, seguranca, ou velocity do time
- Se projeto tem CLAUDE.md com convencoes, validar aderencia
```

## Important
- ALWAYS spawn as Agent subagent — do NOT execute inline
- This agent is READ-ONLY — diagnoses but does NOT fix issues
- Output goes to docs/ directory as markdown report
- Score is 0-100 based on severity-weighted findings
- Quick Wins section is the most actionable part

## Source & license

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

- **Author:** [andregusman-raiz](https://github.com/andregusman-raiz)
- **Source:** [andregusman-raiz/a-gusman-claude](https://github.com/andregusman-raiz/a-gusman-claude)
- **License:** MIT

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-andregusman-raiz-a-gusman-claude-ag-advisor
- Seller: https://agentstack.voostack.com/s/andregusman-raiz
- 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%.