sincron-auto 1.0.0

package/docs/duvidas.md

@@ -0,0 +1,170 @@
+# Dúvidas sobre o Sincron-Auto
+
+## ✅ RESOLVIDO
+
+### 1. Skill "Autorização" (Agente Estrutura)
+**Resposta**:
+- Edita apenas o `settings.local.json`
+- NÃO cria o `sincron-auto-state`
+- O `sincron-auto-state` é criado pelo **Gestor Projeto**
+
+### 2. Arquivo `sincron-auto-state`
+**Resposta**:
+- Formato: **JSON**
+- Criado por: **Gestor Projeto**
+- Conteúdo: Ver `docs/estruturas-dados.md`
+
+### 3. Níveis de Automação
+**Resposta**:
+- **Total**: Todas as permissões do template completo
+- **Parcial**: Apenas ferramentas core (Read, Write, Edit, Glob, Grep, WebFetch, WebSearch, Task, Skill(*), NotebookEdit, AskUserQuestion)
+- **Nenhuma**: Mantém permissões existentes no `settings.local.json` sem incluir novas
+
+### 4. Ponto de Saída do Sistema
+**Resposta**: O sistema finaliza quando todas as tasks têm `status: completo`
+
+### 5. Skills "Projetar" vs "Gerenciar" (Gestor Projeto)
+**Resposta**:
+- **Projetar**:
+  - Analisa projeto e escopo
+  - Cria User Stories
+  - Define critérios de aprovação
+  - Usado para planejar ou revisar planejamento
+- **Gerenciar**:
+  - Lista tasks
+  - Pega próxima task pendente/em execução
+  - Encaminha UMA task por vez para Construtor
+
+### 6. Tipos de Demanda (Gestor Projeto)
+**Resposta**: O Gestor identifica 3 tipos:
+- **Continuar desenvolvimento**: Usa apenas Skill Gerenciar
+- **Planejar novos itens**: Usa Skill Projetar, depois Gerenciar
+- **Revisar planejamento**: Usa Skill Projetar, depois Gerenciar
+
+### 7. Status de Task
+**Resposta**: 3 status possíveis:
+- `pendente`: Aguardando execução
+- `em execução`: Sendo trabalhada pelo Construtor
+- `completo`: Aprovada pelo Avaliador
+
+### 8. Construtor e Subagentes
+**Resposta**: Construtor usa subagentes quando fizer sentido para tornar execução mais rápida
+
+### 9. Avaliação Visual (Avaliador)
+**Resposta**: Usando MCP Playwright, verifica:
+- Coesão estética com resto do projeto
+- Alinhamentos
+- Tamanho de fonte
+- Sobreposição indesejada de elementos
+
+### 10. Relatório de Avaliação
+**Resposta**:
+- Arquivo: `relatorio-avaliacao.json`
+- Criado e atualizado pelo Avaliador
+- Contém histórico de todas as avaliações
+- Registra aprovações e rejeições com detalhes
+- Ver estrutura em `docs/estruturas-dados.md`
+
+### 11. Loop de Retorno (Task Não Aprovada)
+**Resposta**:
+- Avaliador registra problemas no relatório
+- Retorna para Construtor com recomendações detalhadas
+- Construtor corrige e reenvia
+- Nova avaliação atualiza registro no relatório
+
+### 12. Ciclo de Aprovação de Task
+**Resposta**:
+- Avaliador aprova task → Notifica Gestor Projeto
+- Gestor Projeto atualiza task para `completo` no `sincron-auto-state`
+- Gestor Projeto pega próxima task e envia para Construtor
+- Ciclo repete até todas as tasks estarem `completo`
+
+### 13. Finalização do Projeto
+**Resposta**:
+- Quando todas as tasks estão `completo`:
+  - Gestor Projeto notifica Orquestrador
+  - Orquestrador usa Skill RelatorioFinal
+  - Compila relatório baseado no `relatorio-avaliacao.json`
+  - (Formato e destino do relatório a definir)
+
+### 14. Skill RelatorioFinal (Orquestrador)
+**Resposta**:
+- Acionada quando todas as tasks estão completas
+- Compila relatório final user-friendly baseado no `relatorio-avaliacao.json`
+- Formato: Markdown (.md)
+- Nome: Definido pelo Orquestrador refletindo estrutura desenvolvida
+- Local: Pasta `reports/` do projeto
+- Conteúdo: Texto amigável com todos os pontos relevantes do desenvolvimento
+
+### 15. Skill Instalar MCP (Agente Estrutura)
+**Resposta**:
+- Verifica se há acesso aos MCPs: Context7 e Playwright
+- Se não houver, instala via comandos:
+  - `claude mcp add --transport http context7 https://mcp.context7.com/mcp --header "Header-Name: ctx7sk-f1688803-3139-4a02-93df-55bf946be647"`
+  - `claude mcp add playwright npx @playwright/mcp@latest`
+- Executada junto com Skill Autorização na primeira execução
+
+### 16. Priorização de Tasks (Gestor Projeto)
+**Resposta**:
+- **Critério**: FIFO (primeiro criado, primeiro executado)
+- Dependências são gerenciadas pela **ordem de execução**
+- Não há campo explícito de dependências no JSON
+- Apenas tasks com status `pendente` são consideradas
+
+### 17. Atualização de Status de Task
+**Resposta**:
+- **pendente → em execução**: Gestor Projeto quando envia para Construtor
+- **em execução → completo**: Gestor Projeto quando recebe aprovação do Avaliador
+- Apenas Gestor Projeto atualiza o `sincron-auto-state`
+
+### 18. Construtor não gera relatórios
+**Resposta**:
+- Construtor NÃO tem skill de relatório
+- Apenas desenvolve e notifica Avaliador via JSON
+- Apenas Avaliador e Orquestrador geram relatórios
+
+## Agente Estrutura
+
+---
+
+## 🔄 PENDENTE
+
+---
+
+## Fluxo Geral
+
+### Interação com Usuário Durante Execução
+**Pergunta**: O usuário é consultado/notificado durante a execução?
+- Recebe notificação quando cada task é concluída?
+- É informado sobre rejeições e correções?
+- Pode acompanhar progresso em tempo real?
+- **Aguardando**: Continuação da explicação
+
+### 19. Adicionar Tasks Durante Execução
+**Resposta**:
+- **Comando**: `/sincron-auto vamos adicionar notificações por email`
+- **Processo**:
+  - Gestor Projeto recebe demanda
+  - Cria user stories e critérios de aprovação
+  - Adiciona nova task à lista (segue FIFO, vai para o final)
+  - Continua execução normal
+
+### 20. Abandonar Task Desnecessária
+**Resposta**:
+- Gestor Projeto marca task como `completo`
+- Define campos:
+  - `abandoned: true`
+  - `abandonment_reason: "Motivo do abandono"`
+- Task não é executada pelo Construtor
+- Conta como "completa" para finalização do projeto
+- Aparece no relatório final com indicação de abandono
+
+### 21. Retomar Após Interrupção (Ctrl+C)
+**Resposta**:
+- **Comando**: `/sincron-auto vamos retomar` (ou similar)
+- **Processo**:
+  - Orquestrador recebe demanda
+  - Passa para Gestor Projeto
+  - Gestor pega próxima task `em execução` ou `pendente`
+  - Envia para Construtor
+- Se task estava `em execução`: Construtor reconstrói do zero (não retoma parcialmente)

package/docs/estruturas-dados.md

@@ -0,0 +1,377 @@
+# Estruturas de Dados do Sincron-Auto
+
+## Task (dentro de sincron-auto-state)
+
+```json
+{
+  "id": "task-001",
+  "name": "Nome da Task",
+  "description": "Descrição detalhada do que deve ser feito",
+  "user_stories": [
+    "Como [tipo de usuário], eu quero [ação] para [benefício]",
+    "Como desenvolvedor, eu quero uma API REST para gerenciar usuários"
+  ],
+  "acceptance_criteria": [
+    "Critério 1: Deve haver endpoint GET /users",
+    "Critério 2: Deve retornar JSON com lista de usuários",
+    "Critério 3: Deve ter validação de autenticação"
+  ],
+  "status": "pendente | em execução | completo",
+  "created_at": "2026-01-26T10:30:00Z",
+  "updated_at": "2026-01-26T14:45:00Z",
+  "started_at": "2026-01-26T10:35:00Z",
+  "completed_at": "2026-01-26T14:45:00Z",
+  "duration_seconds": 15600,
+  "assigned_to": "construtor",
+  "execution_order": 1,
+  "evaluation_attempts": 2,
+  "subagents_spawned": 4,
+  "abandoned": false,
+  "abandonment_reason": null
+}
+```
+
+### Campos Opcionais
+- **abandoned**: `true` se task foi abandonada pelo Gestor Projeto
+- **abandonment_reason**: Motivo pelo qual a task foi abandonada (ex: "Feature não é mais necessária para o escopo atual")
+- **started_at**: Timestamp ISO 8601 quando task iniciou execução (atribuído pelo Gestor)
+- **completed_at**: Timestamp ISO 8601 quando task foi finalizada (atribuído pelo Gestor)
+- **duration_seconds**: Duração em segundos (calculado: completed_at - started_at)
+- **evaluation_attempts**: Número de tentativas de avaliação (atualizado pelo Gestor)
+- **subagents_spawned**: Número de subagentes spawned pelo Construtor (informado ao Gestor)
+
+**Nota sobre dependências**:
+- Não há campo explícito de dependências
+- Dependências são gerenciadas pela **ordem de execução** (FIFO)
+- Campo `execution_order` ou ordem no array `tasks` define a sequência
+- Tasks são executadas na ordem em que foram criadas pelo Gestor Projeto
+
+### Status de Task
+- **pendente**: Task criada, aguardando execução
+- **em execução**: Task sendo trabalhada pelo Construtor (atualizado pelo Gestor ao enviar para Construtor)
+- **completo**: Task aprovada pelo Avaliador OU abandonada pelo Gestor (atualizado pelo Gestor)
+
+### Transições de Status
+```
+Gestor cria task → pendente
+Gestor envia para Construtor → em execução
+Avaliador aprova → Gestor atualiza → completo
+
+OU
+
+Gestor abandona task → completo (com abandoned: true e abandonment_reason)
+```
+
+Apenas o **Gestor Projeto** pode alterar o status das tasks.
+
+### Task Abandonada
+Quando uma task não é mais necessária:
+- **Status**: Marcado como `completo`
+- **Campo abandoned**: `true`
+- **Campo abandonment_reason**: Explicação do motivo
+- **Exemplo**: "Feature descontinuada após revisão de escopo com stakeholders"
+
+Tasks abandonadas:
+- São contadas como "completas" para finalização do projeto
+- Não são executadas pelo Construtor
+- Aparecem no relatório final com indicação de abandono
+
+---
+
+## User Story
+
+Formato padrão:
+```
+Como [tipo de usuário],
+Eu quero [realizar alguma ação],
+Para [obter algum benefício/valor]
+```
+
+Exemplo:
+```
+Como usuário final,
+Eu quero fazer login com email e senha,
+Para acessar minha área restrita
+```
+
+---
+
+## Critérios de Aprovação
+
+Lista de condições que devem ser satisfeitas para a task ser considerada completa.
+
+Exemplo:
+```json
+"acceptance_criteria": [
+  "Formulário de login deve ter campos email e senha",
+  "Botão de submit deve ser desabilitado se campos vazios",
+  "Deve exibir mensagem de erro se credenciais inválidas",
+  "Deve redirecionar para dashboard após login bem-sucedido",
+  "Design deve seguir paleta de cores do projeto"
+]
+```
+
+---
+
+## Avaliação (dentro de relatorio-avaliacao.json)
+
+```json
+{
+  "task_id": "task-001",
+  "evaluation_number": 1,
+  "timestamp": "2026-01-26T15:30:00Z",
+  "duration_seconds": 180,
+  "files_read_count": 12,
+  "files_read_total_size_kb": 256,
+  "playwright_commands_executed": 8,
+  "status": "aprovada | rejeitada",
+
+  "functional_checks": {
+    "description": "Verificações de funcionalidade",
+    "passed": [
+      "Endpoint GET /users implementado",
+      "Retorna JSON corretamente"
+    ],
+    "failed": [
+      "Validação de autenticação não implementada"
+    ]
+  },
+
+  "visual_checks": {
+    "aesthetic_cohesion": {
+      "status": "pass | fail",
+      "notes": "Cores e tipografia consistentes com o projeto"
+    },
+    "alignment": {
+      "status": "pass | fail",
+      "notes": "Elementos alinhados corretamente"
+    },
+    "font_sizes": {
+      "status": "pass | fail",
+      "notes": "Tamanhos de fonte apropriados e consistentes"
+    },
+    "unwanted_overlaps": {
+      "status": "pass | fail",
+      "notes": "Nenhuma sobreposição indesejada detectada"
+    }
+  },
+
+  "playwright_tests": {
+    "buttons_tested": ["btn-submit", "btn-cancel"],
+    "links_tested": ["/dashboard", "/profile"],
+    "results": [
+      {
+        "element": "btn-submit",
+        "test": "click",
+        "result": "pass | fail",
+        "error": "Descrição do erro se houver"
+      }
+    ]
+  },
+
+  "issues_found": [
+    {
+      "type": "functional | visual",
+      "severity": "critical | high | medium | low",
+      "description": "Validação de autenticação não implementada",
+      "recommendation": "Adicionar middleware de autenticação antes do handler do endpoint",
+      "related_criteria": "Critério 3: Deve ter validação de autenticação"
+    }
+  ],
+
+  "notes": "Observações gerais do avaliador"
+}
+```
+
+---
+
+## Relatório de Avaliação Completo
+
+```json
+{
+  "project_name": "Nome do Projeto",
+  "created_at": "2026-01-26T10:00:00Z",
+  "last_updated": "2026-01-26T15:30:00Z",
+
+  "summary": {
+    "total_evaluations": 5,
+    "approved_first_try": 3,
+    "required_rework": 2,
+    "average_iterations": 1.4
+  },
+
+  "evaluations": [
+    {
+      "task_id": "task-001",
+      "evaluation_number": 1,
+      "timestamp": "2026-01-26T15:30:00Z",
+      "status": "rejeitada",
+      "functional_checks": { /* ... */ },
+      "visual_checks": { /* ... */ },
+      "issues_found": [ /* ... */ ],
+      "notes": "..."
+    },
+    {
+      "task_id": "task-001",
+      "evaluation_number": 2,
+      "timestamp": "2026-01-26T16:15:00Z",
+      "status": "aprovada",
+      "functional_checks": { /* ... */ },
+      "visual_checks": { /* ... */ },
+      "issues_found": [],
+      "notes": "Todas as correções implementadas com sucesso"
+    }
+  ]
+}
+```
+
+---
+
+## Status de Progresso (status-progresso.json)
+
+Arquivo criado em `.sincron-auto/status-progresso.json` para tracking em tempo real do progresso da execução.
+
+```json
+{
+  "fase_atual": "setup | planejamento | construcao | avaliacao | relatorio",
+  "task_atual": {
+    "id": "task-001",
+    "nome": "Nome da Task",
+    "execution_order": 1,
+    "total_tasks": 5
+  },
+  "tentativa_avaliacao": 2,
+  "max_tentativas": 5,
+  "timestamp": "2026-01-27T14:30:22Z",
+  "agente_ativo": "orquestrador | estrutura | gestor | construtor | avaliador"
+}
+```
+
+### Campos
+
+- **fase_atual**: Fase atual do processo
+  - `setup`: Configurando ambiente (Estrutura)
+  - `planejamento`: Criando user stories e tasks (Gestor)
+  - `construcao`: Implementando task (Construtor)
+  - `avaliacao`: Validando task (Avaliador)
+  - `relatorio`: Gerando relatório final (Orquestrador)
+
+- **task_atual**: Informações da task sendo trabalhada
+  - `id`: ID da task
+  - `nome`: Nome descritivo
+  - `execution_order`: Posição na fila (ex: 1 de 5)
+  - `total_tasks`: Total de tasks no projeto
+
+- **tentativa_avaliacao**: Número da tentativa atual de avaliação (1-5)
+- **max_tentativas**: Limite de tentativas (sempre 5)
+- **timestamp**: Última atualização (ISO 8601)
+- **agente_ativo**: Qual agente está executando
+
+### Uso
+
+- **Criado por**: Estrutura (primeira vez) ou Orquestrador (retomada)
+- **Atualizado por**: Todos os agentes
+- **Lido por**: Usuário (via mensagens visuais dos agentes)
+
+---
+
+## Estado do Projeto Completo (sincron-auto-state)
+
+```json
+{
+  "project": {
+    "name": "Sistema de Gerenciamento",
+    "description": "API REST para gerenciamento de usuários e produtos",
+    "created_at": "2026-01-26T10:00:00Z",
+    "last_updated": "2026-01-26T16:15:00Z",
+    "automation_level": "total | parcial | nenhuma",
+    "version": "1.0.0"
+  },
+
+  "scope": {
+    "features": [
+      "Autenticação de usuários",
+      "CRUD de produtos",
+      "Relatórios"
+    ],
+    "technologies": ["Node.js", "Express", "PostgreSQL"],
+    "current_phase": "desenvolvimento"
+  },
+
+  "tasks": [
+    {
+      "id": "task-001",
+      "name": "Implementar API de Usuários",
+      "description": "Criar endpoints REST para gerenciar usuários",
+      "user_stories": [
+        "Como desenvolvedor, eu quero uma API REST para gerenciar usuários"
+      ],
+      "acceptance_criteria": [
+        "Endpoint GET /users implementado",
+        "Endpoint POST /users implementado",
+        "Validação de autenticação presente",
+        "Retorna JSON formatado corretamente"
+      ],
+      "status": "completo",
+      "created_at": "2026-01-26T10:30:00Z",
+      "updated_at": "2026-01-26T16:15:00Z",
+      "assigned_to": "construtor",
+      "priority": 1,
+      "evaluation_history": [
+        {
+          "evaluation_number": 1,
+          "status": "rejeitada",
+          "timestamp": "2026-01-26T15:30:00Z"
+        },
+        {
+          "evaluation_number": 2,
+          "status": "aprovada",
+          "timestamp": "2026-01-26T16:15:00Z"
+        }
+      ]
+    },
+    {
+      "id": "task-002",
+      "name": "Implementar Dashboard UI",
+      "description": "Criar interface de dashboard com gráficos",
+      "user_stories": [
+        "Como usuário, eu quero visualizar métricas em um dashboard"
+      ],
+      "acceptance_criteria": [
+        "Dashboard responsivo",
+        "Gráficos carregam dados da API",
+        "Design consistente com projeto"
+      ],
+      "status": "em execução",
+      "created_at": "2026-01-26T10:35:00Z",
+      "updated_at": "2026-01-26T16:20:00Z",
+      "assigned_to": "construtor",
+      "priority": 2
+    },
+    {
+      "id": "task-003",
+      "name": "Implementar Autenticação JWT",
+      "description": "Adicionar autenticação baseada em JWT",
+      "user_stories": [
+        "Como usuário, eu quero fazer login seguro com token JWT"
+      ],
+      "acceptance_criteria": [
+        "Endpoint POST /login retorna token JWT",
+        "Token expira após 24 horas",
+        "Middleware valida token em rotas protegidas"
+      ],
+      "status": "pendente",
+      "created_at": "2026-01-26T10:40:00Z",
+      "updated_at": "2026-01-26T10:40:00Z",
+      "priority": 3
+    }
+  ],
+
+  "statistics": {
+    "total_tasks": 3,
+    "completed_tasks": 1,
+    "in_progress_tasks": 1,
+    "pending_tasks": 1
+  }
+}
+```