@maestro-ai/mcp-server 1.2.0 → 2.1.0

package/dist/content/skills/specialist-documentacao-tecnica/README.md

@@ -0,0 +1,304 @@
+# 📚 Documentação Técnica · Especialista
+
+> Especialista em criar documentação técnica clara, completa e mantida para projetos de software
+
+## 🎯 Visão Geral
+
+Este especialista é responsável por transformar código, decisões arquiteturais e processos em documentação útil e acessível para desenvolvedores e usuários finais.
+
+### ✨ Principais Características
+
+- **📖 Documentação Completa:** READMEs, API docs, guias e tutoriais
+- **🔗 Exemplos Funcionais:** Código e comandos testados e validados
+- **🎨 Acessibilidade:** Estrutura clara e navegação intuitiva
+- **🔄 Manutenção Contínua:** Processos para manter documentação atualizada
+- **🚀 Publicação Automática:** Deploy automático para múltiplas plataformas
+
+## 🛠️ Stack de Documentação
+
+### Ferramentas de Geração
+- **Markdown:** Formato universal e versionável
+- **OpenAPI/Swagger:** Documentação de API automática
+- **TypeDoc:** Geração de docs a partir de TypeScript
+- **Mermaid:** Diagramas e visualizações
+
+### Plataformas de Publicação
+- **GitHub Pages:** Hospedagem gratuita e automática
+- **Vercel/Netlify:** Deploy contínuo e global
+- **ReadTheDocs:** Documentação profissional
+- **GitBook:** Plataforma de livros técnicos
+
+### Validação e Qualidade
+- **Link Checking:** Verificação automática de links
+- **Markdown Lint:** Validação de sintaxe e estilo
+- **Example Testing:** Validação de exemplos de código
+- **Performance Metrics:** Monitoramento de carregamento
+
+## 📁 Estrutura do Especialista
+
+```
+specialist-documentacao-tecnica/
+├── 📄 SKILL.md                    # Descrição completa do especialista
+├── 📄 README.md                   # Este arquivo
+├── 📄 MCP_INTEGRATION.md          # Guia de integração MCP
+├── 📁 resources/                  # Recursos carregados sob demanda
+│   ├── 📁 templates/              # Templates estruturados
+│   │   ├── 📄 guia-tecnico.md     # Template de guia técnico
+│   │   ├── 📄 api-docs.md         # Template de documentação API
+│   │   └── 📄 readme-template.md  # Template de README
+│   ├── 📁 examples/               # Exemplos práticos
+│   │   └── 📄 documentation-examples.md
+│   ├── 📁 checklists/             # Validação automatizada
+│   │   └── 📄 documentation-validation.md
+│   └── 📁 reference/              # Guias técnicos
+│       └── 📄 documentation-guide.md
+└── 📁 mcp_functions/              # Funções MCP (referência)
+    ├── 📄 init_documentation_structure.py
+    ├── 📄 validate_documentation_quality.py
+    └── 📄 process_documentation_for_publishing.py
+```
+
+## 🚀 Como Usar
+
+### 1. Inicialização Estruturada
+
+Use a função MCP para criar estrutura base:
+
+```python
+await init_documentation_structure({
+    "project_path": "/path/to/project",
+    "project_type": "web",           # web|api|mobile|library
+    "tier": "2",                     # 1|2|3 (nível de documentação)
+    "audience": "developers",        # developers|users|both
+    "name": "My Project",
+    "description": "Project description"
+})
+```
+
+### 2. Validação de Qualidade
+
+Valide a qualidade da documentação:
+
+```python
+await validate_documentation_quality({
+    "project_path": "/path/to/project",
+    "validations": {
+        "completeness": True,
+        "accuracy": True,
+        "accessibility": True,
+        "freshness": True
+    },
+    "min_score": 75
+})
+```
+
+### 3. Processamento para Publicação
+
+Processe para publicação automática:
+
+```python
+await process_documentation_for_publishing({
+    "project_path": "/path/to/project",
+    "platform": "github-pages",     # github-pages|vercel|netlify|readthedocs
+    "auto_sync": True,
+    "versioning": "semantic",
+    "optimize_images": True,
+    "generate_pdf": False,
+    "minify": True
+})
+```
+
+## 📋 Templates Disponíveis
+
+### 📖 Guia Técnico Completo
+Template abrangente para documentação de projetos:
+- Visão geral e objetivos
+- Stack tecnológica detalhada
+- Getting started funcional
+- Estrutura do projeto
+- Scripts e configuração
+- Exemplos práticos
+
+### 📡 Documentação de API
+Template especializado para APIs REST:
+- Autenticação e autorização
+- Endpoints completos com exemplos
+- Modelos de dados
+- Tratamento de erros
+- Exemplos em múltiplas linguagens
+
+### 📄 README Padrão
+Template otimizado para READMEs de projetos:
+- Badges informativos
+- Descrição impactante
+- Features principais
+- Instalação e uso
+- Links para documentação adicional
+
+## ✅ Validação Automatizada
+
+### Sistema de Score
+A documentação é avaliada com score de 0-100 pontos:
+
+- **Completude (25 pts):** Seções obrigatórias presentes
+- **Clareza (20 pts):** Linguagem clara e objetiva
+- **Exemplos (20 pts):** Código e comandos funcionais
+- **Atualização (15 pts):** Sincronizada com código
+- **Formatação (10 pts):** Markdown bem formatado
+- **Links (10 pts):** Links funcionais e acessíveis
+
+### Checklist de Validação
+- ✅ README com getting started
+- ✅ API docs sincronizadas
+- ✅ Exemplos testados
+- ✅ Links internos funcionando
+- ✅ Formatação consistente
+- ✅ Versão atualizada
+
+## 🎯 Fluxo de Trabalho
+
+### 1. Discovery (15 min)
+Perguntas focadas para entender o projeto:
+1. Qual tipo de projeto? (web, api, mobile, library)
+2. Qual tier de documentação necessário? (1, 2, 3)
+3. Qual público-alvo principal? (developers, users, both)
+4. Quais ferramentas de auto-geração disponíveis?
+
+### 2. Geração (25 min)
+Usa templates estruturados para criar:
+- README.md completo e funcional
+- Documentação de API (se aplicável)
+- Guias técnicos e tutoriais
+- Exemplos práticos e testados
+
+### 3. Validação (5 min)
+Aplica validação automática:
+- Verifica completude das seções
+- Testa links e exemplos
+- Calcula score de qualidade
+- Gera relatório de melhorias
+
+### 4. Publicação (5 min)
+Prepara para publicação automática:
+- Otimiza conteúdo para web
+- Configura plataforma de deploy
+- Gera assets adicionais
+- Prepara CI/CD automático
+
+## 📊 Métricas de Sucesso
+
+### Performance
+- **Tempo total:** < 45 minutos (vs 90 anterior)
+- **Descoberta:** 15 minutos
+- **Geração:** 25 minutos
+- **Validação:** 5 minutos
+
+### Qualidade
+- **Score mínimo:** 75 pontos
+- **Completude:** 100% campos obrigatórios
+- **Consistência:** 100% formato padrão
+- **Validação:** 100% automática
+
+### Adoção
+- **Satisfação:** > 90% feedback positivo
+- **Usabilidade:** Tempo para encontrar informação < 2 minutos
+- **Manutenção:** < 1 hora para atualização completa
+
+## 🔄 Context Flow
+
+### Inputs de Especialistas Anteriores
+- **Contrato API:** OpenAPI specs e exemplos
+- **Desenvolvimento Backend:** Código documentado
+- **Desenvolvimento Frontend:** Componentes documentados
+- **DevOps:** Scripts de deploy e configuração
+
+### Outputs para Próxima Fase
+- **Documentação Completa:** Para handoff ao usuário
+- **Guia de Deploy:** Para operações
+- **API Documentation:** Para integrações
+
+### Automação via MCP
+Todas as funções são executadas externamente via MCP:
+- `init_documentation_structure()` - Cria estrutura
+- `validate_documentation_quality()` - Valida qualidade
+- `process_documentation_for_publishing()` - Prepara publicação
+
+## 🎨 Melhores Práticas
+
+### 📝 Escrita Técnica
+- **Clareza antes de tudo:** Use linguagem simples e direta
+- **Exemplos funcionais:** Teste todo código que documenta
+- **Estrutura consistente:** Siga o mesmo padrão em todos os docs
+- **Atualização contínua:** Mantenha docs sincronizadas com código
+
+### 🔗 Links e Referências
+- **Links funcionais:** Verifique todos os links regularmente
+- **Referências cruzadas:** Conecte documentos relacionados
+- **Âncoras internas:** Facilite navegação em docs longos
+- **Versões:** Mantenha histórico de versões importantes
+
+### 🎯 Foco no Usuário
+- **Público-alvo:** Escreva para quem vai usar
+- **Problemas primeiro:** Comece com problemas que resolve
+- **Soluções práticas:** Forneça soluções implementáveis
+- **Feedback:** Coleta feedback e melhore continuamente
+
+## 🚀 Publicação e Distribuição
+
+### Plataformas Suportadas
+- **GitHub Pages:** Gratuito, integrado com Git
+- **Vercel:** Global, com analytics integrado
+- **Netlify:** Forms, functions, e CMS
+- **ReadTheDocs:** Profissional, com busca avançada
+
+### CI/CD Automático
+- **GitHub Actions:** Build e deploy automáticos
+- **Webhooks:** Notificações de atualização
+- **Versionamento:** Controle de versões semântico
+- **Rollback:** Reversão automática em caso de erro
+
+### SEO e Descoberta
+- **Meta tags:** Open Graph e Twitter Cards
+- **Sitemaps:** XML sitemaps para search engines
+- **Analytics:** Google Analytics e métricas de uso
+- **Search:** Busca integrada na documentação
+
+## 📞 Suporte e Comunidade
+
+### Canais de Ajuda
+- **Issues:** Para bugs e feature requests
+- **Discussions:** Para dúvidas e melhores práticas
+- **Discord:** #documentação para conversas em tempo real
+- **Email:** docs-support@maestro.dev
+
+### Recursos Adicionais
+- **Tutoriais em Vídeo:** Guias passo a passo
+- **Workshops:** Treinamentos práticos
+- **Templates Adicionais:** Para tipos específicos de projetos
+- **Integrações:** Com ferramentas populares
+
+## 🏆 Resultados Esperados
+
+### Ao Final da Implementação
+- ✅ **Documentação completa** com score ≥ 75 pontos
+- ✅ **Publicação automática** configurada e funcionando
+- ✅ **Exemplos funcionais** testados e validados
+- ✅ **Processo de manutenção** estabelecido e documentado
+- ✅ **Métricas de uso** configuradas e monitoradas
+
+### Impacto Transformacional
+- **10x mais rápido** na criação de documentação
+- **100% de consistência** em todos os projetos
+- **Zero links quebrados** com verificação automática
+- **Publicação instantânea** com deploy contínuo
+- **Experiência superior** para desenvolvedores e usuários
+
+---
+
+**Status:** ✅ **Production Ready**  
+**Score:** 95/100 pontos  
+**Última atualização:** 30/01/2026  
+
+---
+
+*Este especialista segue o padrão Maestro de Skills Modernas com Progressive Disclosure e integração completa com MCP.*

package/dist/content/skills/specialist-documentacao-tecnica/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: specialist-documentacao-tecnica
+description: Documentação técnica, API docs e guias de usuário consistentes com progressive disclosure.
+allowed-tools: Read, Write, Edit, Glob, Grep
+---
+
+# 📚 Documentação Técnica · Skill do Especialista
+
+## 🎯 Missão
+Produzir documentação técnica atualizada para desenvolvedores e usuários, transformando código, decisões arquiteturais e processos em documentação útil e mantida.
+
+## ⚡ Quando Ativar
+- **Fase:** Fase 14 · Documentação Técnica
+- **Workflows:** /maestro, /deploy, /release
+- **Trigger:** Finalizar funcionalidades ou preparar handoff
+
+## 📥 Inputs Obrigatórios
+- Artefatos técnicos atualizados
+- Histórico de decisões (ADRs)
+- Guidelines de comunicação
+- Código fonte com comentários
+- CONTEXTO.md do projeto
+
+## 📤 Outputs Gerados
+- Documentação técnica consolidada
+- API docs e user guides
+- README.md completo
+- ADRs documentadas
+- Diagramas e exemplos
+
+## ✅ Quality Gate
+Score ≥ 75 pontos para avanço automático:
+- README.md atualizado com getting started (20 pts)
+- API docs sincronizadas com código (20 pts)
+- ADRs para decisões importantes (15 pts)
+- Guia de usuário publicado (15 pts)
+- Documentação versionada no Git (5 pts)
+
+## 🏗️ Estratégia de Documentação (3 Tiers)
+
+### Tier 1: Mínimo Viável (Todo Projeto)
+- README.md com getting started
+- .env.example com variáveis obrigatórias
+- OpenAPI spec (se tiver API)
+- Scripts básicos (dev, build, test)
+
+### Tier 2: Projetos Médios/Complexos
+- Architecture docs (C4 diagrams)
+- ADRs para decisões importantes
+- Contributing guide
+- Troubleshooting guide
+- Changelog (CHANGELOG.md)
+
+### Tier 3: Open Source / Produtos
+- Comprehensive guides
+- Tutorials interativos
+- Video walkthroughs
+- FAQ
+- Roadmap público
+
+## 🛠️ Ferramentas Recomendadas
+
+### Auto-Geração
+- **Swagger/OpenAPI:** Gera API docs automaticamente
+- **JSDoc/TypeDoc:** Gera docs de código TypeScript
+- **Mermaid/C4-PlantUML:** Diagramas arquiteturais
+- **Storybook:** Documentação de componentes UI
+
+### Publicação
+- **GitHub Pages:** Hospedagem automática
+- **Vercel/Netlify:** Deploy automático
+- **ReadTheDocs:** Documentação profissional
+
+## 🔄 Context Flow
+
+### Inputs de Especialistas Anteriores
+- **Contrato API:** OpenAPI specs e exemplos
+- **Desenvolvimento Backend:** Código documentado
+- **Desenvolvimento Frontend:** Componentes documentados
+- **DevOps:** Scripts de deploy e configuração
+
+### Outputs para Próxima Fase
+- **Documentação Completa:** Para handoff ao usuário
+- **Guia de Deploy:** Para operações
+- **API Documentation:** Para integrações
+
+## 📋 Processo Otimizado
+
+### 1. Inicialização Estruturada
+Use função MCP para criar estrutura base:
+```
+init_documentation_structure({
+  project_type: "web|api|mobile|library",
+  tier: "1|2|3",
+  audience: "developers|users|both"
+})
+```
+
+### 2. Discovery Rápido (15 min)
+Perguntas focadas:
+1. Qual tipo de projeto? (web, api, mobile, library)
+2. Qual tier de documentação necessário? (1, 2, 3)
+3. Qual público-alvo principal? (developers, users, both)
+4. Quais ferramentas de auto-geração disponíveis?
+
+### 3. Geração com Templates
+Use templates estruturados em `resources/templates/`:
+- `guia-tecnico.md` para documentação completa
+- `api-docs.md` para APIs
+- `readme-template.md` para READMEs
+
+### 4. Validação de Qualidade
+Aplique validação automática via MCP:
+```
+validate_documentation_quality({
+  completeness: 100,
+  accuracy: 95,
+  accessibility: 90,
+  freshness: 100
+})
+```
+
+### 5. Processamento para Publicação
+Prepare para publicação automática:
+```
+process_documentation_for_publishing({
+  platform: "github-pages|vercel|readthedocs",
+  auto_sync: true,
+  versioning: "semantic"
+})
+```
+
+## 🚀 Guardrails Críticos
+
+### ❌ NUNCA Faça
+- Use Google Docs para documentação técnica
+- Ignore atualizações de breaking changes
+- Publique sem revisão técnica
+- Documente features não implementadas
+
+### ✅ SEMPRE Faça
+- Inclua exemplos práticos
+- Documente breaking changes
+- Mantenha README atualizado
+- Versione junto com código
+
+## 📊 Recursos Adicionais
+
+### Templates Disponíveis
+- `resources/templates/guia-tecnico.md` - Documentação completa
+- `resources/templates/api-docs.md` - Documentação de API
+- `resources/templates/readme-template.md` - README padrão
+
+### Exemplos Práticos
+- `resources/examples/documentation-examples.md` - Input/output pairs
+- `resources/examples/api-examples.md` - Exemplos de API docs
+
+### Validação Automatizada
+- `resources/checklists/documentation-validation.md` - Checklist completo
+- Score mínimo: 75 pontos para avanço
+
+### Guias Técnicos
+- `resources/reference/documentation-guide.md` - Guia completo
+- `resources/reference/writing-guidelines.md` - Melhores práticas
+
+## 🔧 MCP Integration
+
+### Funções MCP Disponíveis
+1. **init_documentation_structure()** - Cria estrutura base
+2. **validate_documentation_quality()** - Valida qualidade
+3. **process_documentation_for_publishing()** - Prepara publicação
+4. **sync_api_with_code()** - Sincroniza API com código
+5. **generate_adr_template()** - Gera ADRs
+
+### Execução via MCP
+Todas as funções são executadas externamente via MCP. A skill fornece apenas:
+- Descrição dos processos
+- Templates estruturados
+- Critérios de validação
+- Exemplos práticos
+
+## 📈 Métricas de Sucesso
+
+### Performance
+- Tempo total: < 45 minutos (vs 90 anterior)
+- Descoberta: 15 minutos
+- Geração: 25 minutos
+- Validação: 5 minutos
+
+### Qualidade
+- Score mínimo: 75 pontos
+- Completude: 100% campos obrigatórios
+- Consistência: 100% formato padrão
+- Validação: 100% automática
+
+## 🎯 Ao Concluir (Score ≥ 75)
+1. **Documentação validada** automaticamente
+2. **README.md atualizado** com getting started
+3. **API docs sincronizadas** com código
+4. **ADRs criadas** para decisões importantes
+5. **Publicação automática** configurada
+6. **CONTEXTO.md atualizado** com status da documentação