sincron-auto 1.0.0

package/docs/installation-guide.md

@@ -0,0 +1,535 @@
+# Instalação do Sincron-Auto Plugin
+
+Guia detalhado para instalação e configuração do plugin Sincron-Auto.
+
+## Pré-requisitos
+
+### Obrigatórios
+
+1. **Claude Code CLI** instalado e funcionando
+   - Versão mínima recomendada: (verificar versão compatível)
+   - Instalação: https://claude.com/claude-code
+
+2. **Node.js e npm/npx** (para Playwright MCP)
+   - Versão mínima: Node.js 16+
+   - Download: https://nodejs.org/
+   - Verificar instalação:
+     ```bash
+     node --version
+     npm --version
+     npx --version
+     ```
+
+3. **Conexão com internet** (para Context7 MCP)
+   - Context7 requer acesso a https://mcp.context7.com
+
+### Opcionais
+
+- **Git** (para versionamento do plugin)
+- **Editor de texto** (VS Code, Sublime, etc.)
+
+---
+
+## Métodos de Instalação
+
+### Método 1: Download do .zip (Recomendado)
+
+1. **Download**
+   ```bash
+   # Baixe sincron-auto.zip do repositório
+   # Exemplo:
+   wget https://github.com/sincronia-digital/sincron-auto/releases/download/v1.0.0/sincron-auto.zip
+   ```
+
+2. **Extrair**
+   ```bash
+   # Extraia em um diretório de sua preferência
+   unzip sincron-auto.zip -d ~/claude-plugins/
+
+   # Ou em qualquer outro local
+   unzip sincron-auto.zip -d /caminho/para/plugins/
+   ```
+
+3. **Verificar estrutura**
+   ```bash
+   cd ~/claude-plugins/sincron-auto
+   ls -la
+
+   # Deve mostrar:
+   # .claude-plugin/
+   # agents/
+   # commands/
+   # skills/
+   # templates/
+   # .mcp.json
+   # README.md
+   # LICENSE
+   # etc.
+   ```
+
+4. **Testar carregamento**
+   ```bash
+   # Navegue até o diretório do plugin
+   cd ~/claude-plugins/sincron-auto
+
+   # Inicie Claude Code CLI
+   claude
+
+   # Verifique se o plugin aparece
+   /help
+
+   # Deve listar:
+   # /sincron-auto - Start automated development workflow
+   ```
+
+### Método 2: Clone do Repositório (Para desenvolvedores)
+
+```bash
+# Clone o repositório
+git clone https://github.com/sincronia-digital/sincron-auto.git
+
+# Entre no diretório
+cd sincron-auto
+
+# Verifique os arquivos
+ls -la
+
+# Inicie Claude Code CLI neste diretório
+claude
+```
+
+### Método 3: Instalação Manual
+
+1. **Criar estrutura de diretórios**
+   ```bash
+   mkdir -p ~/claude-plugins/sincron-auto/{.claude-plugin,agents,commands,skills/{autorizacao,instalar-mcp,projetar,gerenciar,avaliacao,relatorio-final},templates}
+   ```
+
+2. **Copiar arquivos**
+   - Copie todos os arquivos do plugin para a estrutura criada
+   - Mantenha a hierarquia de diretórios
+
+3. **Verificar permissões**
+   ```bash
+   chmod -R 755 ~/claude-plugins/sincron-auto
+   ```
+
+---
+
+## Configuração Inicial
+
+### 1. Verificar Claude Code CLI
+
+```bash
+# Verifique a versão
+claude --version
+
+# Teste o CLI
+claude --help
+```
+
+### 2. Preparar Diretório de Trabalho
+
+```bash
+# Crie ou navegue para seu projeto
+mkdir -p ~/projetos/meu-projeto
+cd ~/projetos/meu-projeto
+
+# Inicialize .claude se necessário
+mkdir -p .claude
+```
+
+### 3. Primeira Execução (Two-Phase Setup)
+
+#### Fase 1: Setup e Configuração
+
+```bash
+# Inicie Claude Code CLI
+claude
+
+# Execute o comando do plugin
+/sincron-auto criar meu primeiro projeto
+
+# O plugin irá:
+# 1. Perguntar nível de automação (Total/Parcial/Nenhuma)
+# 2. Configurar permissões em .claude/settings.local.json
+# 3. Instalar MCPs (Context7 + Playwright)
+# 4. Criar sincron-auto-state.json
+# 5. ORIENTAR você a REINICIAR o Claude Code
+```
+
+**IMPORTANTE**: Após o setup, você DEVE reiniciar o Claude Code para que as permissões sejam carregadas.
+
+#### Fase 2: Desenvolvimento (Após Reiniciar)
+
+```bash
+# Saia do Claude Code
+exit
+
+# Reinicie na mesma pasta
+claude
+
+# Execute o MESMO comando novamente
+/sincron-auto criar meu primeiro projeto
+
+# Agora o plugin irá:
+# 1. Detectar que já está configurado
+# 2. Iniciar planejamento imediatamente
+# 3. Executar COM ZERO PROMPTS de permissão
+```
+
+---
+
+## Instalação de MCPs
+
+Os MCPs são instalados automaticamente na primeira execução, mas você pode instalá-los manualmente se necessário.
+
+### Context7 MCP (Busca de Código)
+
+```bash
+claude mcp add \
+  --transport http \
+  context7 \
+  https://mcp.context7.com/mcp \
+  --header "Header-Name: ctx7sk-f1688803-3139-4a02-93df-55bf946be647"
+```
+
+**Verificar instalação:**
+```bash
+claude mcp list | grep context7
+```
+
+**Testar conectividade:**
+```bash
+curl -s https://mcp.context7.com/mcp \
+  -H "Header-Name: ctx7sk-f1688803-3139-4a02-93df-55bf946be647"
+```
+
+### Playwright MCP (Testes Visuais)
+
+```bash
+claude mcp add playwright npx @playwright/mcp@latest
+```
+
+**Verificar instalação:**
+```bash
+claude mcp list | grep playwright
+```
+
+**Testar Playwright:**
+```bash
+npx @playwright/mcp@latest --version
+```
+
+---
+
+## Configuração de Permissões
+
+### Níveis de Automação
+
+Escolha durante a primeira execução ou configure manualmente.
+
+#### Total (Recomendado para novos projetos)
+
+```bash
+# Copie o template
+cp ~/claude-plugins/sincron-auto/templates/settings-total.json \
+   .claude/settings.local.json
+
+# Ou edite .claude/settings.local.json e cole:
+```
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "Read", "Write", "Edit", "Glob", "Grep",
+      "Bash(git *)", "Bash(npm *)", "Bash(node *)",
+      "Bash(mkdir *)", "Bash(npx *)",
+      "WebFetch", "WebSearch", "Task", "Skill(*)",
+      "mcp__playwright__*", "mcp__context7__*",
+      "NotebookEdit", "AskUserQuestion"
+    ]
+  }
+}
+```
+
+#### Parcial (Maior controle)
+
+```bash
+cp ~/claude-plugins/sincron-auto/templates/settings-parcial.json \
+   .claude/settings.local.json
+```
+
+Habilita apenas ferramentas core, pede aprovação para Bash e MCPs.
+
+#### Nenhuma (Máximo controle)
+
+```bash
+cp ~/claude-plugins/sincron-auto/templates/settings-nenhuma.json \
+   .claude/settings.local.json
+```
+
+Nenhuma permissão pré-aprovada. Você aprova cada ação.
+
+---
+
+## Verificação da Instalação
+
+### Checklist
+
+- [ ] Claude Code CLI instalado e funcionando
+- [ ] Node.js e npx disponíveis
+- [ ] Plugin extraído no diretório correto
+- [ ] Comando `/sincron-auto` aparece no `/help`
+- [ ] Context7 MCP instalado (`claude mcp list`)
+- [ ] Playwright MCP instalado (`claude mcp list`)
+- [ ] Permissões configuradas (`.claude/settings.local.json`)
+
+### Comando de Teste
+
+```bash
+# Navegue até o diretório do plugin
+cd ~/claude-plugins/sincron-auto
+
+# Inicie Claude Code CLI
+claude
+
+# No CLI, execute:
+/sincron-auto criar projeto de teste
+
+# Deve:
+# 1. Perguntar automação (se primeira vez)
+# 2. Instalar MCPs (se primeira vez)
+# 3. Criar sincron-auto-state.json
+# 4. Iniciar planejamento
+```
+
+---
+
+## Troubleshooting de Instalação
+
+### Plugin não aparece no /help
+
+**Causa**: Claude Code CLI não encontrou o plugin
+
+**Solução**:
+```bash
+# Verifique se está no diretório correto
+pwd
+
+# Deve mostrar o caminho do plugin ou de um projeto
+# que usa o plugin
+
+# Verifique se .claude-plugin/plugin.json existe
+ls -la .claude-plugin/plugin.json
+
+# Se não existir, a estrutura está incorreta
+```
+
+### MCPs não instalam
+
+**Causa 1**: Sem internet
+
+**Solução**:
+```bash
+# Teste conectividade
+ping google.com
+curl https://mcp.context7.com
+```
+
+**Causa 2**: Node.js não instalado
+
+**Solução**:
+```bash
+# Instale Node.js
+# macOS: brew install node
+# Ubuntu: sudo apt install nodejs npm
+# Windows: baixe de nodejs.org
+```
+
+**Causa 3**: Firewall bloqueando
+
+**Solução**:
+- Configure firewall para permitir claude CLI
+- Permita conexões HTTPS para mcp.context7.com
+
+### Erro ao criar sincron-auto-state.json
+
+**Causa**: Sem permissão de escrita
+
+**Solução**:
+```bash
+# Verifique permissões
+ls -la
+
+# Dê permissão de escrita
+chmod 755 .
+
+# Ou execute em diretório com permissão
+cd ~/projetos/meu-projeto
+```
+
+### Playwright não funciona
+
+**Causa**: npx não encontrado
+
+**Solução**:
+```bash
+# Atualize npm
+npm install -g npm
+
+# Verifique npx
+npx --version
+
+# Reinstale Node.js se necessário
+```
+
+---
+
+## Desinstalação
+
+### Remover Plugin
+
+```bash
+# Simplesmente delete o diretório
+rm -rf ~/claude-plugins/sincron-auto
+```
+
+### Remover MCPs
+
+```bash
+# Liste MCPs instalados
+claude mcp list
+
+# Remova Context7
+claude mcp remove context7
+
+# Remova Playwright
+claude mcp remove playwright
+```
+
+### Limpar Configurações
+
+```bash
+# Em cada projeto que usou o plugin
+cd ~/projetos/meu-projeto
+
+# Delete os arquivos de estado
+rm -f sincron-auto-state.json
+rm -f relatorio-avaliacao.json
+rm -rf reports/
+rm -rf .sincron-auto/
+
+# Remova as permissões do plugin (opcional)
+# Edite .claude/settings.local.json manualmente
+```
+
+---
+
+## Atualizações
+
+### Atualizar para Nova Versão
+
+1. **Backup do estado atual** (se em meio a projeto)
+   ```bash
+   cp sincron-auto-state.json sincron-auto-state.json.backup
+   cp relatorio-avaliacao.json relatorio-avaliacao.json.backup
+   ```
+
+2. **Baixar nova versão**
+   ```bash
+   wget https://github.com/sincronia-digital/sincron-auto/releases/download/vX.X.X/sincron-auto.zip
+   ```
+
+3. **Substituir arquivos**
+   ```bash
+   # Faça backup do plugin atual
+   mv ~/claude-plugins/sincron-auto ~/claude-plugins/sincron-auto-old
+
+   # Extraia nova versão
+   unzip sincron-auto.zip -d ~/claude-plugins/
+
+   # Verifique se funciona
+   cd ~/claude-plugins/sincron-auto
+   claude
+   /help
+
+   # Se tudo OK, remova backup
+   rm -rf ~/claude-plugins/sincron-auto-old
+   ```
+
+4. **Restaurar estado** (se necessário)
+   ```bash
+   cd ~/projetos/meu-projeto
+   cp sincron-auto-state.json.backup sincron-auto-state.json
+   ```
+
+---
+
+---
+
+## FAQ - Perguntas Frequentes
+
+### Por que preciso reiniciar na primeira execução?
+
+**Resposta:** O Claude Code carrega as permissões apenas no **início da sessão**.
+
+**Fluxo:**
+1. Primeira execução: Configura permissões e MCPs
+2. Reiniciar: Carrega permissões configuradas
+3. Segunda execução: Desenvolvimento com zero prompts
+
+**Benefício:** Garante que você NUNCA verá prompts de permissão durante desenvolvimento!
+
+### Posso pular o reinício?
+
+**Não recomendado.** Se você executar sem reiniciar:
+- Verá prompts de permissão durante toda a execução
+- Terá que aprovar manualmente cada ação
+- Perde o benefício da automação completa
+
+**Melhor:** Reiniciar leva 10 segundos e elimina todos os prompts!
+
+### O que acontece se eu executar /sincron-auto de novo sem reiniciar?
+
+O sistema detecta que já está configurado (arquivo `sincron-auto-state.json` existe)
+e prossegue com desenvolvimento, mas ainda com permissões antigas. Você verá prompts.
+
+**Solução:** Apenas reinicie o Claude Code e execute novamente.
+
+### Preciso reiniciar toda vez que usar o plugin?
+
+**NÃO!** Apenas na primeira execução em um novo projeto.
+
+Após configurar uma vez, todas as execuções seguintes funcionam normalmente:
+- `/sincron-auto continuar` - Zero prompts
+- `/sincron-auto adicionar feature` - Zero prompts
+- `/sincron-auto retomar` - Zero prompts
+
+O reinício é só para carregar as permissões configuradas inicialmente.
+
+---
+
+## Suporte
+
+### Documentação
+
+- README.md - Guia geral de uso
+- CHANGELOG.md - Histórico de versões
+- docs/ - Documentação técnica detalhada
+
+### Issues
+
+Reporte problemas em:
+https://github.com/sincronia-digital/sincron-auto/issues
+
+### Contato
+
+- Site: https://sincronia.digital
+- Desenvolvedor: Matheus Massari
+
+---
+
+**Versão deste guia**: 1.0.5
+**Última atualização**: 2026-01-27

package/docs/mcp-instalacao.md

@@ -0,0 +1,118 @@
+# Instalação de MCPs no Sincron-Auto
+
+## MCPs Necessários
+
+O Sincron-Auto requer dois MCPs para funcionar corretamente:
+
+### 1. Context7 MCP
+**Propósito**: Fornecer contexto do projeto para os agentes
+
+**Instalação**:
+```bash
+claude mcp add --transport http context7 https://mcp.context7.com/mcp --header "Header-Name: ctx7sk-f1688803-3139-4a02-93df-55bf946be647"
+```
+
+**Características**:
+- Transport: HTTP
+- Requer header de autenticação customizado
+- Fornece contexto rico sobre o projeto
+
+---
+
+### 2. Playwright MCP
+**Propósito**: Testes visuais e funcionais
+
+**Instalação**:
+```bash
+claude mcp add playwright npx @playwright/mcp@latest
+```
+
+**Características**:
+- Executa via npx
+- Sempre usa versão latest
+- Usado pelo Agente Avaliador para:
+  - Verificação de coesão estética
+  - Teste de botões e links
+  - Verificação de alinhamentos
+  - Detecção de sobreposições indesejadas
+
+---
+
+## Skill Instalar MCP (Agente Estrutura)
+
+### Fluxo de Verificação e Instalação
+
+```
+1. Verificar se Context7 está disponível
+   ├─ Disponível → Prossegue
+   └─ Não disponível → Instala Context7
+
+2. Verificar se Playwright está disponível
+   ├─ Disponível → Prossegue
+   └─ Não disponível → Instala Playwright
+
+3. Confirmar instalações bem-sucedidas
+   └─ Passa controle para Gestor Projeto
+```
+
+### Como Verificar Disponibilidade
+
+A Skill deve verificar se os MCPs estão configurados no projeto:
+- Possivelmente consultando arquivo de configuração do Claude CLI
+- Ou tentando usar uma função básica do MCP para validar
+
+### Tratamento de Erros
+
+Se alguma instalação falhar:
+- Registrar erro detalhado
+- Informar usuário
+- Permitir continuação manual ou retry
+
+---
+
+## Configurações dos MCPs
+
+### Context7
+```json
+{
+  "name": "context7",
+  "transport": "http",
+  "url": "https://mcp.context7.com/mcp",
+  "headers": {
+    "Header-Name": "ctx7sk-f1688803-3139-4a02-93df-55bf946be647"
+  }
+}
+```
+
+### Playwright
+```json
+{
+  "name": "playwright",
+  "command": "npx",
+  "args": ["@playwright/mcp@latest"]
+}
+```
+
+---
+
+## Uso pelos Agentes
+
+### Context7 (Potencial uso)
+- **Gestor Projeto**: Analisar contexto completo do projeto ao criar tasks
+- **Construtor**: Entender padrões e estrutura do código existente
+- **Avaliador**: Verificar consistência com resto do projeto
+
+### Playwright
+- **Avaliador**: Única fonte de uso confirmada
+  - Testes visuais automatizados
+  - Verificação de UI/UX
+  - Validação de funcionalidades interativas
+
+---
+
+## Notas Técnicas
+
+1. **Primeira Execução**: MCPs são instalados apenas uma vez, na configuração inicial
+2. **Atualizações**: Playwright usa `@latest`, então sempre pega versão mais recente
+3. **Permissões**: A instalação dos MCPs requer permissões adequadas no sistema
+4. **Ordem**: Context7 primeiro, Playwright depois (ordem não é crítica)