sincron-auto 1.0.0

package/docs/arquitetura.md

@@ -0,0 +1,397 @@
+# Arquitetura Sincron-Auto v1.1.x
+
+## Visao Geral
+
+Sistema multi-agentes para automacao de desenvolvimento no Claude Code CLI.
+
+**Principio Fundamental**: Command controla TUDO. Agentes NUNCA chamam outros agentes.
+
+---
+
+## Arquitetura Central
+
+### Command como Controlador
+
+```
+Command (sincron-auto.md) - CONTROLADOR CENTRAL
+    |
+    +-- PHASE A: Estrutura    (setup only, returns restart_required)
+    +-- PHASE B: Gestor       (planning only, returns stories_created)
+    +-- PHASE C: [Approval]   (Command asks user directly)
+    +-- PHASE D: Loop
+    |       +-- Construtor    (1 story, returns build_complete)
+    |       +-- Avaliador     (1 eval, returns approved/rejected)
+    +-- PHASE E: Orquestrador (report only, returns report_complete)
+```
+
+### Por que esta Arquitetura?
+
+**Problema das versoes anteriores (v1.0.x)**:
+- Agentes chamavam outros agentes (Orquestrador -> Gestor -> Construtor -> Avaliador)
+- Cada nivel acumulava contexto em memoria
+- 5 niveis de aninhamento causavam OOM (heap out of memory)
+
+**Solucao (v1.1.0+)**:
+- Command controla TODO o fluxo
+- Agentes recebem UMA tarefa e RETORNAM ao Command
+- Maximo 2 niveis de aninhamento (Command -> Agente -> fim)
+- Memoria liberada apos cada retorno
+
+---
+
+## Fases de Execucao
+
+### PHASE A: First Run Setup
+
+**Condicao**: `sincron-auto-state.json` NAO existe
+
+```
+1. Command pergunta nivel de automacao (AskUserQuestion)
+2. Command escreve .sincron-auto/request.json
+3. Command chama Estrutura via Task
+4. Estrutura configura permissoes + instala MCPs
+5. Estrutura retorna restart_required
+6. Command mostra mensagem de reinicio e TERMINA
+```
+
+### PHASE B: Planning
+
+**Condicao**: `sincron-auto-state.json` existe, `status = "initialized"`
+
+```
+1. Command escreve .sincron-auto/request.json
+2. Command chama Gestor via Task
+3. Gestor analisa projeto e cria user stories
+4. Gestor escreve .sincron-auto/user-stories.md
+5. Gestor atualiza sincron-auto-state.json com stories array
+6. Gestor retorna stories_created
+7. Command vai para PHASE C
+```
+
+### PHASE C: Story Approval
+
+**Condicao**: `stories_approved = false`
+
+```
+1. Command le user-stories.md e sincron-auto-state.json
+2. Command mostra stories no formato Como/Quero/Para
+3. Command pergunta aprovacao (AskUserQuestion)
+4. Se aprovado: atualiza state, vai para PHASE D
+5. Se editar: mostra instrucao e TERMINA
+6. Se cancelar: deleta state e TERMINA
+```
+
+### PHASE D: Implementation Loop
+
+**Condicao**: `stories_approved = true`, existem stories pendentes
+
+```
+LOOP:
+1. Command encontra proxima story com status = "pending"
+2. Se nao encontrou: vai para PHASE E
+
+3. Command escreve .sincron-auto/current-story.json
+4. Command chama Construtor via Task
+5. Construtor implementa story
+6. Construtor escreve .sincron-auto/build-result.json
+7. Construtor retorna build_complete
+
+8. Command chama Avaliador via Task
+9. Avaliador avalia implementacao
+10. Avaliador escreve .sincron-auto/eval-result.json
+11. Avaliador retorna approved ou rejected
+
+12. Se approved:
+    - Command atualiza story status para "approved"
+    - Volta ao passo 1 (proxima story)
+
+13. Se rejected E attempt < 3:
+    - Command incrementa attempt
+    - Volta ao passo 4 (re-implementa)
+
+14. Se rejected E attempt >= 3:
+    - Command atualiza story status para "not_approved"
+    - Volta ao passo 1 (proxima story)
+```
+
+### PHASE E: Final Report
+
+**Condicao**: Nenhuma story pendente
+
+```
+1. Command atualiza state: status = "complete"
+2. Command chama Orquestrador via Task
+3. Orquestrador gera relatorio final
+4. Orquestrador escreve .sincron-auto/report.md
+5. Orquestrador retorna report_complete
+6. Command mostra resumo e TERMINA
+```
+
+---
+
+## Agentes
+
+### Estrutura
+
+**Responsabilidade**: Setup do projeto (APENAS primeira execucao)
+
+| Aspecto | Valor |
+|---------|-------|
+| Entrada | `.sincron-auto/request.json` (automation_level) |
+| Saida | `sincron-auto-state.json` criado |
+| Retorna | `restart_required` |
+| Tools | Read, Write, Edit, Bash |
+
+**Processo**:
+1. Le nivel de automacao do arquivo
+2. Configura permissoes em `.claude/settings.local.json`
+3. Instala MCPs (Context7 + Playwright)
+4. Cria arquivo de estado
+5. Retorna ao Command
+
+### Gestor Projeto
+
+**Responsabilidade**: Criar user stories (APENAS planejamento)
+
+| Aspecto | Valor |
+|---------|-------|
+| Entrada | `.sincron-auto/request.json` (original_request) |
+| Saida | `user-stories.md` + `sincron-auto-state.json` atualizado |
+| Retorna | `stories_created` |
+| Tools | Read, Write, Edit, Glob, Grep |
+
+**Processo**:
+1. Le requisicao original
+2. Analisa estrutura existente do projeto
+3. Cria user stories com criterios FUNCIONAL/VISUAL/COMPORTAMENTO
+4. Salva stories no formato Como/Quero/Para
+5. Retorna ao Command
+
+### Construtor
+
+**Responsabilidade**: Implementar UMA story
+
+| Aspecto | Valor |
+|---------|-------|
+| Entrada | `.sincron-auto/current-story.json` + `sincron-auto-state.json` |
+| Saida | `.sincron-auto/build-result.json` |
+| Retorna | `build_complete` |
+| Tools | Read, Write, Edit, Bash, Glob, Grep |
+
+**Processo**:
+1. Le story atual e seus criterios
+2. Implementa TODOS os criterios
+3. Escreve resultado (arquivos criados/modificados)
+4. Retorna ao Command
+
+**IMPORTANTE**: Construtor NUNCA usa subagentes. Implementa diretamente.
+
+### Avaliador
+
+**Responsabilidade**: Avaliar UMA story
+
+| Aspecto | Valor |
+|---------|-------|
+| Entrada | `.sincron-auto/current-story.json` + `build-result.json` |
+| Saida | `.sincron-auto/eval-result.json` |
+| Retorna | `approved` ou `rejected` |
+| Tools | Read, Write, Bash, Glob, mcp__playwright__* |
+
+**Processo**:
+1. Le story e resultado da construcao
+2. Avalia criterios FUNCIONAL (codigo)
+3. Avalia criterios VISUAL (Playwright)
+4. Avalia criterios COMPORTAMENTO (Playwright)
+5. Verifica automaticamente: sobreposicoes, botoes, links
+6. Escreve resultado com detalhes
+7. Retorna ao Command
+
+### Orquestrador
+
+**Responsabilidade**: Gerar relatorio final (APENAS no fim)
+
+| Aspecto | Valor |
+|---------|-------|
+| Entrada | `sincron-auto-state.json` (todas as stories) |
+| Saida | `.sincron-auto/report.md` |
+| Retorna | `report_complete` |
+| Tools | Read, Write, Glob |
+
+**Processo**:
+1. Le estado final do projeto
+2. Conta stories aprovadas/nao aprovadas
+3. Calcula estimativa de tokens
+4. Gera relatorio user-friendly
+5. Adiciona rodape Sincronia.Digital
+6. Retorna ao Command
+
+---
+
+## Arquivos de Comunicacao
+
+```
+.sincron-auto/
++-- request.json         # Command -> agentes (requisicao inicial)
++-- user-stories.md      # Gestor -> Command (stories para aprovacao)
++-- current-story.json   # Command -> Construtor/Avaliador (qual story)
++-- build-result.json    # Construtor -> Avaliador (o que foi feito)
++-- eval-result.json     # Avaliador -> Command (aprovado/rejeitado)
++-- report.md            # Orquestrador -> Command (relatorio final)
+
+sincron-auto-state.json  # Estado master (raiz do projeto)
+```
+
+### request.json
+
+```json
+{
+  "automation_level": "total|parcial|nenhuma",
+  "original_request": "criar site de portfolio..."
+}
+```
+
+### current-story.json
+
+```json
+{
+  "story_id": "US-001",
+  "attempt": 1,
+  "max_attempts": 3
+}
+```
+
+### build-result.json
+
+```json
+{
+  "files_changed": ["src/index.html", "src/styles.css"],
+  "summary": "Criado formulario de contato..."
+}
+```
+
+### eval-result.json
+
+```json
+{
+  "story_id": "US-001",
+  "result": "approved|rejected",
+  "attempt": 1,
+  "criteria_results": [...],
+  "issues": [...],
+  "summary": "..."
+}
+```
+
+---
+
+## Regras Criticas
+
+### 1. Agentes NUNCA chamam outros agentes
+
+```
+ERRADO: Construtor -> Task(Avaliador)
+CERTO:  Construtor -> retorna build_complete -> Command -> Task(Avaliador)
+```
+
+### 2. Command e o UNICO que usa AskUserQuestion
+
+```
+ERRADO: Estrutura usa AskUserQuestion (filtrado em subagentes)
+CERTO:  Command pergunta ANTES de chamar Estrutura
+```
+
+### 3. Maximo 2 niveis de aninhamento
+
+```
+Nivel 1: Command
+Nivel 2: Agente (qualquer um)
+Nivel 3: NAO EXISTE
+```
+
+### 4. Comunicacao via arquivos
+
+```
+ERRADO: Task(prompt com 5000 tokens de dados)
+CERTO:  Task(prompt curto) + agente le de arquivo
+```
+
+---
+
+## Comparacao de Arquiteturas
+
+| Aspecto | v1.0.x | v1.1.x |
+|---------|--------|--------|
+| Niveis de aninhamento | 5 | 2 (max) |
+| Quem controla loop | Gestor | Command |
+| Agentes chamam agentes | Sim | NUNCA |
+| Memoria | Acumula | Libera apos cada |
+| OOM em projetos grandes | Frequente | Eliminado |
+| AskUserQuestion funciona | Problematico | Sempre (no Command) |
+
+---
+
+## Diagramas
+
+### Fluxo de First Run
+
+```
+Usuario -> /sincron-auto criar X
+    |
+    v
+Command (PHASE A)
+    |-- AskUserQuestion: nivel de automacao?
+    |-- Write: .sincron-auto/request.json
+    |-- Task: Estrutura
+    |       |-- configura permissoes
+    |       |-- instala MCPs
+    |       |-- cria state file
+    |       +-- retorna: restart_required
+    |
+    +-- Mostra: "Reinicie o Claude Code"
+```
+
+### Fluxo de Implementacao
+
+```
+Command (PHASE D)
+    |
+    +-- LOOP para cada story pendente:
+        |
+        |-- Write: current-story.json
+        |-- Task: Construtor
+        |       +-- retorna: build_complete
+        |
+        |-- Task: Avaliador
+        |       +-- retorna: approved/rejected
+        |
+        +-- Se rejected e attempt < 3: retry
+            Se rejected e attempt >= 3: marca not_approved
+            Se approved: proxima story
+```
+
+---
+
+## Historico de Decisoes
+
+### Por que Command como controlador?
+
+**Problema**: v1.0.x tinha cadeia Orquestrador -> Gestor -> Construtor -> Avaliador. Cada nivel mantinha contexto do nivel anterior, causando OOM.
+
+**Solucao**: Command (que roda inline, nao como subagente) controla tudo. Cada agente e chamado separadamente e retorna, liberando memoria.
+
+### Por que maximo 3 tentativas?
+
+**Problema**: 5 tentativas acumulavam muito contexto (issues de cada tentativa).
+
+**Solucao**: 3 tentativas e suficiente para a maioria dos casos. Se nao aprovada em 3, provavelmente precisa de intervencao humana.
+
+### Por que Playwright no Avaliador?
+
+**Problema**: Avaliacoes visuais sao subjetivas e inconsistentes.
+
+**Solucao**: Playwright fornece verificacoes automaticas objetivas (sobreposicoes, botoes mortos, links quebrados).
+
+---
+
+**Ultima atualizacao**: 2026-01-30
+**Versao do documento**: 2.0 (arquitetura v1.1.x)

package/docs/cenarios-uso.md

@@ -0,0 +1,292 @@
+# Cenários de Uso do Sincron-Auto
+
+## 1. Primeira Execução - Novo Projeto
+
+### Comando
+```bash
+/sincron-auto criar um sistema de gerenciamento de tarefas
+```
+
+### Fluxo
+1. Orquestrador verifica que `sincron-auto-state` não existe
+2. Aciona Agente Estrutura
+3. Estrutura pergunta nível de automação (Total/Parcial/Nenhuma)
+4. Estrutura instala MCPs (Context7 e Playwright)
+5. Gestor Projeto cria `sincron-auto-state`
+6. Gestor Projeto analisa demanda e cria user stories
+7. Gestor Projeto define tasks com critérios de aprovação
+8. Execução inicia task por task
+
+---
+
+## 2. Continuar Desenvolvimento Existente
+
+### Comando
+```bash
+/sincron-auto vamos continuar
+```
+
+### Fluxo
+1. Orquestrador verifica que `sincron-auto-state` existe
+2. Passa para Gestor Projeto
+3. Gestor Projeto usa Skill Gerenciar
+4. Pega próxima task pendente (FIFO)
+5. Envia para Construtor
+6. Ciclo continua até todas as tasks estarem completas
+
+---
+
+## 3. Adicionar Nova Feature Durante Execução
+
+### Cenário
+- Sistema está na task 3 de 10
+- Usuário quer adicionar notificações por email
+
+### Comando
+```bash
+/sincron-auto vamos adicionar notificações por email
+```
+
+### Fluxo
+1. Orquestrador passa demanda para Gestor Projeto
+2. Gestor Projeto identifica como "adicionar nova feature"
+3. Usa Skill Projetar:
+   - Cria user stories para notificações
+   - Define critérios de aprovação
+   - Cria nova(s) task(s)
+4. Adiciona tasks ao final da lista (FIFO)
+5. Continua execução normal
+6. Novas tasks serão executadas após as tasks já planejadas
+
+### Resultado no `sincron-auto-state`
+```json
+{
+  "tasks": [
+    {"id": "task-001", "name": "API Usuários", "status": "completo"},
+    {"id": "task-002", "name": "API Produtos", "status": "completo"},
+    {"id": "task-003", "name": "Dashboard UI", "status": "em execução"},
+    {"id": "task-004", "name": "Relatórios", "status": "pendente"},
+    {"id": "task-011", "name": "Sistema de Notificações Email", "status": "pendente"},
+    {"id": "task-012", "name": "Templates de Email", "status": "pendente"}
+  ]
+}
+```
+
+---
+
+## 4. Abandonar Task Desnecessária
+
+### Cenário
+- 10 tasks planejadas
+- Task 3 já completa
+- Usuário decide que task 8 não é mais necessária
+
+### Comando
+```bash
+/sincron-auto a task de integração com sistema legado não é mais necessária
+```
+
+### Fluxo
+1. Gestor Projeto identifica qual task abandonar
+2. Atualiza task:
+   - Status: `completo`
+   - `abandoned: true`
+   - `abandonment_reason: "Sistema legado foi descontinuado"`
+3. Task não será executada pelo Construtor
+4. Conta como "completa" para finalização
+
+### Resultado no `sincron-auto-state`
+```json
+{
+  "id": "task-008",
+  "name": "Integração com Sistema Legado",
+  "status": "completo",
+  "abandoned": true,
+  "abandonment_reason": "Sistema legado foi descontinuado, feature não é mais necessária"
+}
+```
+
+### No Relatório Final
+```markdown
+### 8. ⊗ Integração com Sistema Legado
+**Status**: Abandonada
+**Motivo**: Sistema legado foi descontinuado, feature não é mais necessária
+```
+
+---
+
+## 5. Interrupção (Ctrl+C) e Retomada
+
+### Cenário
+- Task 5 está "em execução"
+- Usuário interrompe com Ctrl+C
+- Depois quer retomar
+
+### Comando para Retomar
+```bash
+/sincron-auto vamos retomar
+```
+
+### Fluxo
+1. Orquestrador recebe comando de retomada
+2. Passa para Gestor Projeto
+3. Gestor Projeto identifica como "retomar projeto"
+4. Busca próxima task com status:
+   - `em execução` (task interrompida)
+   - OU `pendente` (próxima da fila)
+5. Envia para Construtor
+6. **Importante**: Construtor reconstrói do zero, não retoma parcialmente
+
+### Estado Antes da Interrupção
+```json
+{
+  "tasks": [
+    {"id": "task-001", "status": "completo"},
+    {"id": "task-002", "status": "completo"},
+    {"id": "task-003", "status": "completo"},
+    {"id": "task-004", "status": "completo"},
+    {"id": "task-005", "status": "em execução"},  // ← Interrompida aqui
+    {"id": "task-006", "status": "pendente"}
+  ]
+}
+```
+
+### Estado Após Retomada
+```json
+{
+  "tasks": [
+    {"id": "task-001", "status": "completo"},
+    {"id": "task-002", "status": "completo"},
+    {"id": "task-003", "status": "completo"},
+    {"id": "task-004", "status": "completo"},
+    {"id": "task-005", "status": "em execução"},  // ← Retomada
+    {"id": "task-006", "status": "pendente"}
+  ]
+}
+```
+
+---
+
+## 6. Revisar Planejamento
+
+### Comando
+```bash
+/sincron-auto vamos revisar o planejamento, precisamos ajustar o escopo
+```
+
+### Fluxo
+1. Gestor Projeto identifica como "revisar planejamento"
+2. Usa Skill Projetar:
+   - Analisa projeto atual
+   - Analisa tasks existentes
+   - Ajusta user stories
+   - Redefine critérios se necessário
+   - Pode adicionar/remover/modificar tasks pendentes
+3. Usa Skill Gerenciar para continuar execução
+
+---
+
+## 7. Múltiplas Iterações de Correção
+
+### Cenário
+- Construtor implementa task
+- Avaliador rejeita (botão não funciona)
+- Construtor corrige
+- Avaliador aprova
+
+### Fluxo Detalhado
+```
+1. Construtor → Avaliador (tentativa 1)
+   ↓
+2. Avaliador testa
+   - Botão "Salvar" não funciona
+   - Registra em relatorio-avaliacao.json
+   ↓
+3. Avaliador → Construtor (rejeitada)
+   JSON: {
+     "issues_found": [
+       {
+         "type": "functional",
+         "description": "Botão Salvar não dispara submit",
+         "recommendation": "Adicionar event listener onClick"
+       }
+     ]
+   }
+   ↓
+4. Construtor corrige
+   - Adiciona onClick handler
+   ↓
+5. Construtor → Avaliador (tentativa 2)
+   ↓
+6. Avaliador testa
+   - Tudo funcionando
+   - Registra aprovação em relatorio-avaliacao.json
+   ↓
+7. Avaliador → Gestor Projeto (aprovada)
+   ↓
+8. Gestor atualiza task para "completo"
+   ↓
+9. Gestor pega próxima task
+```
+
+---
+
+## 8. Finalização e Relatório
+
+### Quando Todas as Tasks Estão Completas
+
+### Fluxo
+1. Última task aprovada pelo Avaliador
+2. Avaliador → Gestor Projeto (aprovada)
+3. Gestor atualiza para "completo"
+4. Gestor verifica: "Todas completas?"
+   - SIM → Notifica Orquestrador
+5. Orquestrador usa Skill RelatorioFinal:
+   - Lê `relatorio-avaliacao.json`
+   - Lê `sincron-auto-state`
+   - Compila relatório user-friendly
+   - Define nome: `relatorio-sistema-gerenciamento-tarefas-2026-01-26.md`
+   - Salva em `reports/`
+   - Apresenta resumo no terminal
+
+### Mensagem ao Usuário
+```
+✅ Projeto Concluído!
+
+📊 Estatísticas:
+   - Tasks completas: 10
+   - Tasks abandonadas: 1
+   - Iterações de correção: 5
+   - Taxa de sucesso: 90%
+
+📄 Relatório completo salvo em:
+   reports/relatorio-sistema-gerenciamento-tarefas-2026-01-26.md
+```
+
+---
+
+## Comandos de Exemplo
+
+### Iniciar Projeto
+- `/sincron-auto criar sistema de blog`
+- `/sincron-auto vamos desenvolver uma API REST`
+
+### Continuar
+- `/sincron-auto continuar`
+- `/sincron-auto vamos seguir`
+
+### Adicionar Feature
+- `/sincron-auto adicionar autenticação OAuth`
+- `/sincron-auto vamos incluir sistema de comentários`
+
+### Revisar
+- `/sincron-auto revisar planejamento`
+- `/sincron-auto vamos ajustar o escopo`
+
+### Retomar
+- `/sincron-auto retomar`
+- `/sincron-auto vamos continuar de onde paramos`
+
+### Abandonar Task
+- `/sincron-auto a integração com X não é mais necessária`
+- `/sincron-auto descartar a task de migração`