Plugin para Claude Code especializado em ADVPL e TLPP para desenvolvimento no ecossistema TOTVS Protheus — para desenvolvedores e consultores funcionais.
Documentacao completa: https://thalysjuvenal.github.io/advpl-specialist
- Quick Start
- Funcionalidades
- Instalacao
- Commands
- Exemplos
- Agents
- Referencia Interna
- Estrutura do Projeto
- Referencia Embutida
- Contribuindo
- Changelog
- Licenca
Repositorio: https://github.com/thalysjuvenal/advpl-specialist
# 1. Adicione o marketplace do plugin (dentro do Claude Code)
/plugin marketplace add thalysjuvenal/advpl-specialist
# 2. Instale o plugin
/plugin install advpl-specialist@thalysjuvenal-advpl-specialist
# 3. Abra um projeto Protheus e use os comandos
/advpl-specialist:generate function FATA050 --module FAT
/advpl-specialist:diagnose "Variable does not exist: cCodCli"
/advpl-specialist:docs FWExecView- Geracao de codigo - Funcoes, classes TLPP, MVC, REST APIs, Web Services, pontos de entrada, TReport, FWFormBrowse, Jobs, Workflow
- Migracao ADVPL -> TLPP - Conversao de codigo procedural para orientado a objetos
- Diagnostico de erros - Analise de erros de compilacao, runtime, performance e locks
- Revisao de codigo - Analise com 24 regras de boas praticas, performance, seguranca e modernizacao (inclui deteccao de funcoes restritas da TOTVS e variaveis reservadas do sistema)
- Testes ProBat - Geracao de testes unitarios para codigo TLPP
- Referencia de documentacao - Funcoes nativas, dicionario SX, APIs REST, parametros MV_, funcoes FW de empresa/filial, lista de funcoes restritas da TOTVS
- Processos de negocio - Consulta de rotinas, tabelas, integracoes e fluxos de 8 modulos ERP
- Explicacao de codigo - Explicacao em linguagem simples com niveis junior, senior e funcional
- Refatoracao - Sugestoes de melhoria de estrutura com 6 padroes (RF-001 a RF-006)
- Documentacao automatica - Cabecalho Protheus.doc, documentacao completa e documentacao de API
- Changelog - Geracao de changelog a partir do git diff com classificacao de impacto
- Explicacao de codigo - Nivel funcional: entenda customizacoes sem ler codigo
- Geracao de dicionario SX - Descreva campos em linguagem natural e gere scripts SX3, SIX, SX1, SX5 e SX7
- Changelog - Documento de mudancas pronto para entregar ao cliente
Adicione o marketplace e instale o plugin:
# Dentro do Claude Code, adicione o marketplace
/plugin marketplace add thalysjuvenal/advpl-specialist
# Instale o plugin
/plugin install advpl-specialist@thalysjuvenal-advpl-specialistClone o repositorio e inicie o Claude Code com a flag --plugin-dir:
git clone https://github.com/thalysjuvenal/advpl-specialist.git
claude --plugin-dir ./advpl-specialistO plugin detecta automaticamente projetos Protheus (.prw, .tlpp, .prx, .ch) ao iniciar uma sessao.
O plugin utiliza o Playwright MCP como fallback quando o acesso direto a documentacao (WebSearch/WebFetch) falha. Com ele, o plugin abre a pagina em um navegador real para extrair o conteudo:
claude mcp add playwright -- npx @anthropic-ai/mcp-playwright@latestPara uma experiencia completa, recomendamos instalar o plugin oficial superpowers que adiciona skills de planejamento, brainstorming, debugging sistematico e code review:
/plugin marketplace add anthropics/claude-code-plugins
/plugin install superpowers@anthropics-claude-code-plugins| Comando | Descricao |
|---|---|
/advpl-specialist:generate |
Gerar codigo ADVPL/TLPP (funcoes, classes, MVC, REST, PE, TReport, FWFormBrowse, Jobs, Workflow) |
/advpl-specialist:migrate |
Migrar codigo ADVPL procedural para TLPP orientado a objetos |
/advpl-specialist:diagnose |
Diagnosticar erros e problemas em codigo ADVPL/TLPP |
/advpl-specialist:docs |
Consultar documentacao de funcoes, APIs e dicionario Protheus |
/advpl-specialist:review |
Revisar codigo ADVPL/TLPP (boas praticas, performance, seguranca, modernizacao) |
/advpl-specialist:test |
Gerar testes unitarios ProBat para codigo TLPP |
/advpl-specialist:process |
Consultar processos de negocio, rotinas e integracoes entre modulos |
/advpl-specialist:explain |
Explicar codigo em linguagem simples (nivel junior, senior ou funcional) |
/advpl-specialist:refactor |
Sugerir refatoracoes de estrutura sem mudar comportamento |
/advpl-specialist:document |
Gerar documentacao tecnica automatica (header, full, api) |
/advpl-specialist:changelog |
Gerar changelog formatado a partir do git diff |
/advpl-specialist:sxgen |
Gerar scripts de dicionario SX a partir de descricao em linguagem natural |
# Gerar uma User Function para o modulo de faturamento
/advpl-specialist:generate function FATA050 --module FAT
# Gerar uma classe TLPP
/advpl-specialist:generate class PedidoService
# Gerar estrutura MVC completa
/advpl-specialist:generate mvc CadProduto --module EST
# Migrar arquivo ADVPL para TLPP
/advpl-specialist:migrate src/FATA001.prw
# Diagnosticar um erro
/advpl-specialist:diagnose "Variable does not exist: cCodCli"
# Consultar documentacao de funcao
/advpl-specialist:docs FWExecView
# Explicar codigo para consultor funcional
/advpl-specialist:explain src/MATA461.prw --level funcional
# Sugerir refatoracoes
/advpl-specialist:refactor src/FATA001.prw
# Gerar documentacao completa
/advpl-specialist:document src/MATA461.prw --type full
# Gerar changelog desde uma data
/advpl-specialist:changelog --since 2026-03-01 --format markdown
# Gerar script de dicionario SX3
/advpl-specialist:sxgen --type sx3Consulte a pasta examples/ para seis cenarios end-to-end prontos para executar, com prompts exatos, output esperado e variacoes.
| # | Cenario | Comando principal |
|---|---|---|
| 01 | Gerar MVC completo para tabela customizada ZA1 | /advpl-specialist:generate |
| 02 | Migrar ADVPL procedural (FATA001) para TLPP | /advpl-specialist:migrate |
| 03 | Diagnosticar erro de lock infinito em RecLock |
/advpl-specialist:diagnose |
| 04 | Criar endpoint REST em TLPP com namespace | /advpl-specialist:generate |
| 05 | Revisar codigo focando em performance | /advpl-specialist:review |
| 06 | Gerar dicionario SX3 + SIX + SX1 para nova tabela | /advpl-specialist:sxgen |
| Agent | Descricao |
|---|---|
code-generator |
Gera codigo ADVPL/TLPP seguindo convencoes e boas praticas |
migrator |
Converte codigo procedural ADVPL para TLPP com classes e namespaces |
debugger |
Diagnostica erros de compilacao, runtime, performance e locks |
docs-reference |
Consulta referencia local + TDN para funcoes, tabelas SX e APIs |
code-reviewer |
Analisa codigo existente para boas praticas, performance, seguranca e modernizacao |
process-consultant |
Consulta processos de negocio, rotinas, tabelas e integracoes entre modulos |
refactorer |
Analisa codigo e sugere refatoracoes de estrutura com before/after |
doc-generator |
Gera documentacao tecnica automatica a partir do codigo-fonte |
changelog-generator |
Analisa git diff e gera changelog formatado com classificacao de impacto |
sx-configurator |
Gera scripts de dicionario SX a partir de descricao em linguagem natural |
Os agents e commands carregam automaticamente bases de conhecimento internas (skills/*/reference.md) conforme necessario. Estas referencias nao aparecem como skills invocaveis — o usuario interage exclusivamente pelos Commands acima.
| Referencia | Descricao |
|---|---|
advpl-code-generation |
Padroes e templates para geracao de codigo (MVC, REST, PE, SOAP, TReport, FWFormBrowse, Jobs, Workflow) |
advpl-to-tlpp-migration |
Regras de conversao, checklist e exemplos before/after |
advpl-debugging |
Top 50 erros comuns, metodologia de debug, dicas de performance |
advpl-code-review |
24 regras de revisao de codigo (boas praticas, performance, seguranca, modernizacao) |
probat-testing |
Framework ProBat para testes unitarios TLPP (annotations, assertions, patterns) |
protheus-reference |
190+ funcoes nativas, dicionario SX, referencia REST API, funcoes FW*, lista de funcoes restritas |
protheus-business |
8 modulos ERP com tabelas, rotinas, parametros MV_* e integracoes |
embedded-sql |
BeginSQL/EndSQL, macros %table%, %notDel%, %xfilial%, %exp%, column types |
code-explanation |
Metodologia de explicacao de codigo com 3 niveis de audiencia |
advpl-refactoring |
6 padroes de refatoracao com before/after e regras de seguranca |
documentation-patterns |
Templates para Protheus.doc header, documentacao completa e API REST |
changelog-patterns |
Tipos de mudanca, niveis de impacto e formatos markdown/texto |
sx-configuration |
Definicoes completas SX3/SIX/SX1/SX5/SX7 com validacoes e pictures |
tdn-lookup |
Estrategia de busca online no TDN via API REST do Confluence (4 tiers) |
advpl-specialist/
├── .claude-plugin/
│ ├── plugin.json # Metadata do plugin
│ └── marketplace.json # Catalogo do marketplace
├── .github/
│ ├── ISSUE_TEMPLATE/
│ │ ├── bug_report.md # Template para reportar bugs
│ │ └── feature_request.md # Template para sugestoes
│ └── pull_request_template.md # Template para PRs
├── agents/ # 10 agents especializados
│ ├── code-generator.md
│ ├── code-reviewer.md
│ ├── migrator.md
│ ├── debugger.md
│ ├── docs-reference.md
│ ├── process-consultant.md
│ ├── refactorer.md
│ ├── doc-generator.md
│ ├── changelog-generator.md
│ └── sx-configurator.md
├── commands/ # 12 commands invocaveis
│ ├── generate.md
│ ├── migrate.md
│ ├── diagnose.md
│ ├── docs.md
│ ├── review.md
│ ├── test.md
│ ├── process.md
│ ├── explain.md
│ ├── refactor.md
│ ├── document.md
│ ├── changelog.md
│ └── sxgen.md
├── skills/ # 14 referencias internas (reference.md + supporting files)
│ ├── advpl-code-generation/ # Padroes MVC, REST, SOAP, PE, TReport, FWFormBrowse, Jobs, Workflow
│ ├── advpl-to-tlpp-migration/ # Regras e checklist de migracao
│ ├── advpl-debugging/ # Erros comuns e performance
│ ├── advpl-code-review/ # 24 regras de revisao de codigo
│ ├── probat-testing/ # Testes unitarios ProBat (TLPP)
│ ├── protheus-business/ # 8 modulos ERP (COM, EST, FAT, FIN, CTB, FIS, PCP, MNT)
│ ├── embedded-sql/ # BeginSQL/EndSQL, macros, patterns
│ ├── protheus-reference/ # 190+ funcoes nativas, SX, REST API, funcoes restritas
│ ├── code-explanation/ # Explicacao de codigo com 3 niveis de audiencia
│ ├── advpl-refactoring/ # 6 padroes de refatoracao com before/after
│ ├── documentation-patterns/ # Templates Protheus.doc, documentacao completa, API
│ ├── changelog-patterns/ # Tipos de mudanca, impacto, formatos
│ ├── sx-configuration/ # Dicionario SX3/SIX/SX1/SX5/SX7 completo
│ └── tdn-lookup/ # Busca online no TDN via API Confluence
├── hooks/ # SessionStart hook
│ ├── hooks.json
│ └── session-start
├── CHANGELOG.md # Historico de versoes
├── CODE_OF_CONDUCT.md # Codigo de conduta
├── CONTRIBUTING.md # Guia de contribuicao
├── LICENSE # Licenca MIT
├── SECURITY.md # Politica de seguranca
└── README.md
O plugin inclui referencia local para consulta rapida:
- 190+ funcoes nativas documentadas com sintaxe, parametros e exemplos
- 10 funcoes FW* de gestao de empresa/filial (FWCodFil, FWCodEmp, FWFilial, FWCompany, etc.)
- 195+ funcoes restritas da TOTVS catalogadas com alternativas documentadas
- 9 tabelas SX (SX1-SX9, SIX) com campos e uso programatico
- REST API patterns completos para WsRestFul e TLPP annotations
- 50 erros comuns com causa e solucao
- 10 categorias de otimizacao de performance com before/after
- 16 pontos de entrada mais usados por modulo
- Templates de classes TLPP (Service, Repository, DTO)
- MVC completo com MenuDef, ModelDef, ViewDef e FWMVCRotAuto
- Embedded SQL completo com BeginSQL/EndSQL, macros, JOINs, aggregations
Para casos nao cobertos localmente, o plugin busca no TDN (TOTVS Developer Network) automaticamente. Se o acesso ao TDN falhar (timeout, erro ou conteudo vazio), o plugin utiliza o Playwright MCP como fallback — abrindo a pagina em um navegador real para extrair a documentacao via snapshot de texto ou captura visual.
Contribuicoes sao bem-vindas! Leia o CONTRIBUTING.md para saber como participar.
Veja o CHANGELOG.md para o historico completo de versoes.