sincron-auto 1.0.0

package/docs/metricas-performance.md

@@ -0,0 +1,371 @@
+# Métricas de Performance - Sincron-Auto
+
+## Visão Geral
+
+Este documento explica o sistema de métricas de performance do Sincron-Auto, incluindo o que pode e não pode ser medido, e como interpretar os dados fornecidos.
+
+## Limitações CRÍTICAS
+
+### ⚠️ O Plugin NÃO Tem Acesso aos Tokens da API Claude
+
+**IMPORTANTE**: O Sincron-Auto, como qualquer plugin do Claude Code CLI, **NÃO** tem acesso direto às métricas de tokens consumidos pela API Claude.
+
+As métricas fornecidas são **aproximações** baseadas em:
+- Duração de execução (timestamps)
+- Número de operações (arquivos lidos, comandos executados)
+- Complexidade estrutural (tentativas, subagentes)
+- Heurísticas baseadas em experiência
+
+## O Que NÃO Podemos Medir
+
+❌ **Tokens exatos consumidos por prompt**
+- Não temos acesso à contagem de tokens de entrada
+- Não sabemos quantos tokens foram usados na resposta
+
+❌ **Tokens de entrada vs saída**
+- Não conseguimos diferenciar input tokens de output tokens
+
+❌ **Custo real em USD**
+- Sem tokens exatos, não podemos calcular custo preciso
+- Custos variam por modelo (Sonnet vs Opus vs Haiku)
+
+❌ **Uso exato da janela de contexto (200K)**
+- Não sabemos quanto do contexto foi usado em cada prompt
+- Não temos visibilidade de compactação automática
+
+❌ **Métricas por modelo**
+- Não sabemos se agente usou Sonnet, Opus ou Haiku
+- Cada modelo tem custos e performance diferentes
+
+## O Que Podemos Medir
+
+### ✅ Duração
+
+**Como medimos**:
+- `created_at` → `started_at` → `completed_at` timestamps
+- Calculamos diferença em segundos/minutos
+- Somamos para obter duração total do projeto
+
+**Utilidade**:
+- Entender tempo total de execução
+- Identificar tasks que demoraram muito
+- Comparar tempo entre tentativas
+
+**Exemplo**:
+```json
+{
+  "created_at": "2026-01-27T10:00:00Z",
+  "started_at": "2026-01-27T10:05:00Z",
+  "completed_at": "2026-01-27T10:45:00Z",
+  "duration_seconds": 2400
+}
+```
+
+### ✅ Tentativas de Avaliação
+
+**Como medimos**:
+- Contador `evaluation_attempts` incrementado a cada avaliação
+- Máximo de 5 tentativas por task
+
+**Utilidade**:
+- Tasks com muitas tentativas indicam complexidade ou ambiguidade
+- Taxa de sucesso na primeira tentativa indica qualidade de critérios
+
+**Exemplo**:
+```json
+{
+  "evaluation_attempts": 3,
+  "max_evaluation_attempts": 5
+}
+```
+
+### ✅ Subagentes Spawned
+
+**Como medimos**:
+- Construtor registra quantos subagentes paralelos foram usados
+- Gestor armazena esse número na task
+
+**Utilidade**:
+- Mais subagentes = maior paralelização = potencialmente mais tokens
+- Indica complexidade da implementação
+
+**Exemplo**:
+```json
+{
+  "subagents_spawned": 5
+}
+```
+
+### ✅ Arquivos Lidos
+
+**Como medimos**:
+- Avaliador conta quantos arquivos leu durante avaliação
+- Soma tamanho total dos arquivos (KB)
+
+**Utilidade**:
+- Mais arquivos lidos = mais contexto consumido
+- Tamanho total dá noção de volume de código
+
+**Exemplo**:
+```json
+{
+  "files_read_count": 12,
+  "files_read_total_size_kb": 256
+}
+```
+
+### ✅ Comandos Playwright Executados
+
+**Como medimos**:
+- Contador incrementado a cada comando MCP Playwright
+- Inclui: navigate, click, fill, eval, screenshot, etc.
+
+**Utilidade**:
+- Mais comandos Playwright = testes visuais mais completos
+- Indica investimento em qualidade visual
+
+**Exemplo**:
+```json
+{
+  "playwright_commands_executed": 8
+}
+```
+
+### ✅ Estimativa de Complexidade
+
+**Como calculamos**:
+
+Pontuação baseada em 4 fatores:
+
+1. **Tasks com ≥3 tentativas**: +1 ponto
+   - Indica dificuldade em atender critérios
+
+2. **Subagentes ≥5 por task**: +1 ponto
+   - Indica implementação complexa/paralela
+
+3. **Arquivos lidos ≥50 total**: +1 ponto
+   - Indica contexto grande
+
+4. **Comandos Playwright ≥20 total**: +1 ponto
+   - Indica testes visuais extensivos
+
+**Interpretação**:
+- **0-1 pontos**: Baixa complexidade
+  - Projeto simples, poucas iterações
+  - Consumo de tokens provavelmente moderado
+
+- **2-3 pontos**: Média complexidade
+  - Projeto com desafios moderados
+  - Consumo de tokens substancial
+
+- **4+ pontos**: Alta complexidade
+  - Projeto complexo, muitas iterações
+  - Consumo de tokens elevado
+
+**Exemplo de Cálculo**:
+```
+Projeto X:
+- 2 tasks tiveram 3+ tentativas → +1
+- 1 task usou 6 subagentes → +1
+- Total de 35 arquivos lidos → 0
+- Total de 25 comandos Playwright → +1
+
+Score: 3 pontos = Média complexidade
+```
+
+## Como Obter Métricas Exatas de Tokens
+
+Se você precisa de métricas EXATAS de tokens consumidos, você precisará:
+
+### Opção 1: Monitorar Logs do Claude Code
+
+Se o Claude Code expõe logs com informações de API:
+```bash
+claude --verbose [command]
+# Procure por logs com "tokens" ou "usage"
+```
+
+### Opção 2: Usar API Diretamente com Logging
+
+Em vez do Claude Code CLI, use a API Anthropic diretamente:
+
+```python
+import anthropic
+
+client = anthropic.Anthropic(api_key="...")
+
+response = client.messages.create(
+    model="claude-sonnet-4.5-20250929",
+    max_tokens=1024,
+    messages=[...]
+)
+
+# response.usage contém tokens exatos
+print(f"Input tokens: {response.usage.input_tokens}")
+print(f"Output tokens: {response.usage.output_tokens}")
+print(f"Total cost: ${calculate_cost(response.usage)}")
+```
+
+### Opção 3: Modificar Claude Code (Avançado)
+
+Se você tem acesso ao código-fonte do Claude Code:
+- Adicione logging customizado na camada de API
+- Capture `usage` de cada resposta
+- Exporte para arquivo JSON
+
+### Opção 4: Dashboard da Anthropic
+
+Acesse o dashboard da Anthropic Console:
+- https://console.anthropic.com/usage
+- Veja uso total, custos, breakdown por API key
+- Não mostra detalhes por task individual
+
+## Interpretando Métricas Aproximadas
+
+### Quando Métricas São Úteis
+
+Mesmo sem tokens exatos, as métricas aproximadas são úteis para:
+
+✅ **Comparação relativa**
+- "Task A demorou 3x mais que Task B"
+- "Projeto X usou 2x mais subagentes que Projeto Y"
+
+✅ **Identificação de problemas**
+- Task com 5 tentativas → critérios ambíguos?
+- 0 comandos Playwright → faltou teste visual?
+
+✅ **Estimativa de esforço**
+- Projeto complexo (score 4) vs simples (score 1)
+- Duração total indica investimento de tempo
+
+✅ **Otimização futura**
+- "Tasks com muitas tentativas custam mais"
+- "Paralelização acelera mas aumenta tokens"
+
+### Quando Métricas NÃO São Úteis
+
+❌ **Cálculo exato de custos**
+- Não use para faturamento
+- Não confie para budget preciso
+
+❌ **Otimização de tokens específica**
+- Não sabemos qual prompt consumiu mais tokens
+- Não podemos otimizar prompts individuais
+
+❌ **Comparação entre modelos**
+- Não sabemos se usou Sonnet, Opus ou Haiku
+- Custos variam muito entre modelos
+
+## Exemplo de Relatório de Métricas
+
+No relatório final, você verá algo como:
+
+```markdown
+### 📊 Métricas de Performance
+
+**Duração Total**: 2h 35min
+
+**Por Task**:
+
+| Task | Duração | Tentativas | Subagentes |
+|------|---------|------------|------------|
+| task-001 | 8 min | 1 | 3 |
+| task-002 | 23 min | 3 | 5 |
+| task-003 | 12 min | 2 | 4 |
+
+**Estatísticas Gerais**:
+- **Total de avaliações**: 6
+- **Taxa de aprovação primeira tentativa**: 33% (1/3)
+- **Média de tentativas por task**: 2.0
+- **Total de subagentes spawned**: 12
+
+**Consumo Aproximado de Contexto**:
+
+⚠️ **Nota**: Valores aproximados. Claude Code não expõe tokens exatos.
+
+- **Arquivos lidos**: 35 arquivos (~420KB)
+- **Comandos Playwright**: 24 comandos
+- **Agentes invocados**: 18 invocações
+- **Estimativa de complexidade**: Média (3 pontos)
+
+**Como Complexidade foi Calculada**:
+- Tasks com ≥3 tentativas: +1 (task-002)
+- Subagentes ≥5: +1 (task-002)
+- Arquivos ≥50: 0 (35 total)
+- Playwright ≥20: +1 (24 total)
+
+**Interpretação**: 3 pontos = Média complexidade
+```
+
+## Expectativas Realistas
+
+### O Que Esperar
+
+✅ **Insights qualitativos**
+- Tasks complexas vs simples
+- Qualidade de critérios (taxa de sucesso)
+- Cobertura de testes (Playwright)
+
+✅ **Comparações relativas**
+- Entre tasks do mesmo projeto
+- Entre execuções diferentes
+
+✅ **Detecção de anomalias**
+- Task que demorou muito tempo
+- Task com muitas tentativas
+
+### O Que NÃO Esperar
+
+❌ **Precisão financeira**
+- Não use para contabilidade
+- Não confie para previsão de custos
+
+❌ **Otimização granular**
+- Não identifica prompts específicos caros
+- Não mostra onde contexto foi usado
+
+❌ **Detalhes técnicos de API**
+- Não mostra cache hits/misses
+- Não mostra compactação de contexto
+
+## Recomendações
+
+### Para Usuários Casuais
+
+Se você usa Sincron-Auto ocasionalmente:
+- ✅ Use métricas aproximadas para entender complexidade
+- ✅ Foque em duração e taxa de sucesso
+- ✅ Não se preocupe com tokens exatos
+
+### Para Uso Profissional/Comercial
+
+Se você usa Sincron-Auto em produção:
+- ⚠️ Monitore custos via dashboard Anthropic
+- ⚠️ Configure limites de orçamento na API key
+- ⚠️ Use métricas aproximadas apenas como guia
+- ⚠️ Implemente logging customizado se precisar de precisão
+
+### Para Desenvolvimento/Debugging
+
+Se você está melhorando o Sincron-Auto:
+- 🔧 Métricas aproximadas ajudam a identificar gargalos
+- 🔧 Duração indica onde otimizar
+- 🔧 Tentativas indicam critérios ambíguos
+- 🔧 Subagentes indicam paralelização
+
+## Conclusão
+
+As métricas de performance do Sincron-Auto são **aproximadas mas úteis**. Elas não substituem métricas exatas de tokens da API, mas fornecem insights valiosos sobre:
+
+- Complexidade do projeto
+- Qualidade dos critérios
+- Eficiência da execução
+- Áreas de melhoria
+
+**Expectativa correta**: Use como guia qualitativo, não como contabilidade precisa.
+
+**Para métricas exatas**: Monitore via dashboard Anthropic ou implemente logging customizado na API.
+
+---
+
+*Este documento faz parte do Sincron-Auto, desenvolvido por [Sincron.Digital](https://sincroni.digital)*

package/docs/relatorio-final-exemplo.md

@@ -0,0 +1,200 @@
+# Exemplo de Relatório Final (User-Friendly)
+
+Este é um exemplo do relatório final gerado pelo Orquestrador usando a Skill RelatorioFinal.
+
+---
+
+# Relatório de Desenvolvimento: API de Gerenciamento de Usuários
+
+**Projeto**: Sistema de Gerenciamento
+**Data de Conclusão**: 26 de Janeiro de 2026
+**Duração**: 3 horas
+
+---
+
+## Resumo Executivo
+
+O desenvolvimento da API de Gerenciamento de Usuários foi concluído com sucesso. Todas as 5 tasks planejadas foram implementadas e aprovadas após rigoroso processo de avaliação. O sistema agora conta com endpoints REST completos, autenticação JWT, e interface de dashboard responsiva.
+
+---
+
+## Tasks Completadas
+
+### 1. ✅ Implementar API de Usuários
+**Status**: Completo
+**Iterações**: 2
+**Tempo de Desenvolvimento**: ~45 minutos
+
+**O que foi feito**:
+- Criados endpoints REST (GET, POST, PUT, DELETE)
+- Implementada validação de dados
+- Configurada resposta JSON padronizada
+
+**Problemas Encontrados e Resolvidos**:
+- **Iteração 1**: Faltava validação de autenticação no middleware
+  - **Solução**: Adicionado middleware de autenticação JWT antes dos handlers
+
+---
+
+### 2. ✅ Implementar Autenticação JWT
+**Status**: Completo
+**Iterações**: 1
+**Tempo de Desenvolvimento**: ~30 minutos
+
+**O que foi feito**:
+- Endpoint POST /login retornando token JWT
+- Configuração de expiração (24 horas)
+- Middleware de validação em rotas protegidas
+
+**Problemas Encontrados**: Nenhum (aprovado na primeira iteração)
+
+---
+
+### 3. ✅ Implementar Dashboard UI
+**Status**: Completo
+**Iterações**: 3
+**Tempo de Desenvolvimento**: ~60 minutos
+
+**O que foi feito**:
+- Interface responsiva com gráficos
+- Integração com API de usuários
+- Design consistente com paleta do projeto
+
+**Problemas Encontrados e Resolvidos**:
+- **Iteração 1**: Sobreposição de elementos no mobile
+  - **Solução**: Ajustados breakpoints CSS e uso de flexbox
+- **Iteração 2**: Tamanho de fonte inconsistente
+  - **Solução**: Aplicada escala tipográfica do design system
+
+---
+
+### 4. ✅ Implementar CRUD de Produtos
+**Status**: Completo
+**Iterações**: 1
+**Tempo de Desenvolvimento**: ~35 minutos
+
+**O que foi feito**:
+- Endpoints REST para produtos
+- Validação de campos obrigatórios
+- Relacionamento com usuários (criador)
+
+**Problemas Encontrados**: Nenhum
+
+---
+
+### 5. ✅ Implementar Relatórios
+**Status**: Completo
+**Iterações**: 2
+**Tempo de Desenvolvimento**: ~50 minutos
+
+**O que foi feito**:
+- Geração de relatórios em PDF
+- Filtros por data e usuário
+- Exportação de dados
+
+**Problemas Encontrados e Resolvidos**:
+- **Iteração 1**: Botão de download não funcionava
+  - **Solução**: Corrigida URL de download e headers HTTP
+
+---
+
+## Estatísticas do Projeto
+
+- **Total de Tasks**: 5
+- **Tasks Aprovadas na 1ª Iteração**: 2 (40%)
+- **Tasks que Precisaram de Retrabalho**: 3 (60%)
+- **Média de Iterações por Task**: 1.8
+- **Total de Avaliações Realizadas**: 9
+
+---
+
+## Aspectos de Qualidade
+
+### ✅ Funcionalidade
+- Todos os endpoints implementados conforme especificação
+- Autenticação JWT funcionando corretamente
+- Integração entre componentes bem-sucedida
+
+### ✅ Qualidade Visual
+- Interface responsiva em todos os breakpoints
+- Coesão estética mantida em todo o projeto
+- Alinhamentos e espaçamentos consistentes
+- Tipografia padronizada
+
+### ✅ Testes
+- Botões e links testados com MCP Playwright
+- Navegação entre páginas funcionando
+- Validações de formulário operacionais
+
+---
+
+## Principais Desafios e Soluções
+
+### Dashboard UI (Task 3)
+**Desafio**: Interface apresentava problemas de responsividade e consistência visual.
+**Solução**: Foram necessárias 3 iterações para ajustar breakpoints CSS, corrigir sobreposições e padronizar tamanhos de fonte. O resultado final atende todos os critérios de design.
+
+### API de Usuários (Task 1)
+**Desafio**: Primeira versão não incluía validação de autenticação.
+**Solução**: Implementado middleware JWT que protege todas as rotas sensíveis.
+
+---
+
+## Tecnologias Utilizadas
+
+- **Backend**: Node.js, Express
+- **Banco de Dados**: PostgreSQL
+- **Autenticação**: JWT (JSON Web Tokens)
+- **Frontend**: React, TailwindCSS
+- **Testes**: Playwright
+
+---
+
+## Estrutura de Arquivos Criada
+
+```
+src/
+├── api/
+│   ├── users/
+│   │   ├── controller.js
+│   │   ├── routes.js
+│   │   └── validation.js
+│   ├── products/
+│   │   ├── controller.js
+│   │   └── routes.js
+│   └── auth/
+│       ├── jwt.js
+│       └── middleware.js
+├── ui/
+│   ├── dashboard/
+│   │   ├── Dashboard.jsx
+│   │   └── Charts.jsx
+│   └── reports/
+│       └── ReportGenerator.jsx
+└── config/
+    └── database.js
+```
+
+---
+
+## Próximos Passos Sugeridos
+
+1. Implementar testes unitários automatizados
+2. Adicionar logging e monitoramento
+3. Configurar CI/CD pipeline
+4. Documentar API com Swagger/OpenAPI
+5. Implementar rate limiting para proteção contra abuso
+
+---
+
+## Conclusão
+
+O projeto foi concluído com sucesso. Todas as funcionalidades planejadas foram implementadas e validadas. O código está pronto para deploy em ambiente de produção, seguindo os critérios de qualidade estabelecidos nas user stories.
+
+**Taxa de Sucesso**: 100%
+**Qualidade Final**: ✅ Aprovado em todos os critérios
+
+---
+
+*Relatório gerado automaticamente pelo Sincron-Auto*
+*Data: 2026-01-26 18:45:00*

package/docs/skills-vs-agents.md

@@ -0,0 +1,107 @@
+# Skills vs Agents - Quick Reference
+
+## CRITICAL DISTINCTION
+
+**Skills** and **Agents** are DIFFERENT and use DIFFERENT tools!
+
+### Skills
+
+**Skills** are invoked using the `Skill` tool.
+
+**Syntax**:
+```
+Skill(sincron-auto:skill-name)
+```
+
+**Available Skills**:
+- `sincron-auto:autorizacao` - Configure permissions
+- `sincron-auto:instalar-mcp` - Install MCPs
+- `sincron-auto:projetar` - Create project plan
+- `sincron-auto:gerenciar` - Manage task queue
+- `sincron-auto:avaliacao` - Evaluate implementation
+- `sincron-auto:relatorio-final` - Generate final report
+
+**When to use**: For executing specific, contained workflows within an agent.
+
+---
+
+### Agents
+
+**Agents** are invoked using the `Task` tool.
+
+**Syntax**:
+```
+Task(
+  subagent_type: "sincron-auto:agent-name",
+  prompt: "Instructions for the agent",
+  description: "Short description"
+)
+```
+
+**Available Agents**:
+- `sincron-auto:orquestrador` - Main orchestrator
+- `sincron-auto:estrutura` - First-run setup
+- `sincron-auto:gestor-projeto` - Project manager
+- `sincron-auto:construtor` - Code builder
+- `sincron-auto:avaliador` - QA tester
+
+**When to use**: For delegating work to specialized autonomous agents.
+
+---
+
+## Common Mistakes (DO NOT DO)
+
+❌ **WRONG**:
+```
+Skill(sincron-auto:estrutura)        # estrutura is an AGENT, not a Skill!
+Skill(sincron-auto:gestor-projeto)   # gestor-projeto is an AGENT, not a Skill!
+Skill(sincron-auto:construtor)       # construtor is an AGENT, not a Skill!
+```
+
+✅ **CORRECT**:
+```
+Task(subagent_type: "sincron-auto:estrutura", ...)
+Task(subagent_type: "sincron-auto:gestor-projeto", ...)
+Task(subagent_type: "sincron-auto:construtor", ...)
+```
+
+---
+
+## Agent Delegation Map
+
+```
+Orquestrador
+  ├─ Skill(sincron-auto:relatorio-final)
+  ├─ Task(sincron-auto:estrutura)
+  │    ├─ Skill(sincron-auto:autorizacao)
+  │    ├─ Skill(sincron-auto:instalar-mcp)
+  │    └─ Task(sincron-auto:gestor-projeto)
+  └─ Task(sincron-auto:gestor-projeto)
+       ├─ Skill(sincron-auto:projetar)
+       ├─ Skill(sincron-auto:gerenciar)
+       ├─ Task(sincron-auto:construtor)
+       │    └─ Task(general-purpose) [max 2 parallel]
+       └─ Task(sincron-auto:avaliador)
+            └─ Skill(sincron-auto:avaliacao)
+```
+
+---
+
+## Memory Limits
+
+**IMPORTANT**: To prevent out of memory errors:
+
+- Construtor: Maximum 2 parallel subagents
+- Gestor Projeto: ONE task at a time (sequential)
+- Never nest agents more than 4 levels deep
+
+---
+
+## Rule of Thumb
+
+- **Calling a SKILL?** → Use `Skill(sincron-auto:name)`
+- **Calling an AGENT?** → Use `Task(subagent_type: "sincron-auto:name", ...)`
+
+**Still confused?**
+- Check if it's in `skills/` folder → It's a Skill
+- Check if it's in `agents/` folder → It's an Agent