sincron-plan 1.0.0

package/commands/sincron-plan.md

@@ -0,0 +1,412 @@
+---
+name: sincron-plan
+description: Planejamento estruturado com questionamento profundo e geração de PRD
+allowed-tools:
+  - Read
+  - Write
+  - Glob
+  - Grep
+  - Bash
+  - Task
+  - AskUserQuestion
+  - WebSearch
+  - WebFetch
+---
+
+# /sincron-plan - Planejamento Estruturado
+
+## Propósito
+Conduzir questionamento profundo e gerar PRD + Roadmap + User Stories para um projeto.
+
+## Instruções de Execução
+
+### FASE 1: DETECÇÃO DE CONTEXTO
+
+**1.1 Verificar se existe código no diretório:**
+```
+- Glob para *.js, *.ts, *.py, *.java, *.go, etc
+- Verificar package.json, requirements.txt, go.mod, etc
+```
+
+**1.2 SE existe código:**
+Verificar se `.sincron-plan/codebase/` existe e está completo (4 documentos).
+
+**SE código existe MAS mapeamento NÃO existe:**
+Perguntar ao usuário usando AskUserQuestion:
+```
+header: "Mapeamento"
+question: "Detectei código existente mas sem mapeamento. Deseja mapear antes de planejar?"
+options:
+- label: "Sim, mapear primeiro (Recomendado)"
+  description: "Executa /sincron-map para entender o código existente"
+- label: "Não, pular mapeamento"
+  description: "Continua direto para planejamento (você assume o risco)"
+```
+
+**SE escolher "Sim":**
+Executar fluxo de `/sincron-map` primeiro, depois retornar aqui.
+
+**1.3 SE não existe código OU já tem mapeamento:**
+Continuar para Fase 2.
+
+---
+
+### FASE 2: QUESTIONAMENTO PROFUNDO
+
+**2.1 Verificar se PROJECT.md já existe:**
+Se `.sincron-plan/PROJECT.md` existe, perguntar:
+```
+header: "Projeto"
+question: "Encontrei definição de projeto existente. O que deseja fazer?"
+options:
+- label: "Usar existente"
+  description: "Continua com o PROJECT.md atual"
+- label: "Refazer"
+  description: "Inicia novo questionamento do zero"
+```
+
+**2.2 SE precisa criar PROJECT.md:**
+Spawnar agente Questionador:
+```
+Task(
+  subagent_type: "general-purpose",
+  prompt: "Você é o Questionador do Sincron-Plan.
+
+Sua missão: Conduzir questionamento profundo com o usuário para entender o que ele quer construir.
+
+Siga as instruções em sincron-plan/agents/questionador.md.
+
+Processo:
+1. Pergunte: 'O que você quer construir?'
+2. Faça follow-ups baseados nas respostas
+3. Use as técnicas: Challenge vagueness, Make concrete, Clarification, Success definition, Reveal motivation
+4. Quando tiver clareza, confirme o entendimento
+5. Escreva .sincron-plan/PROJECT.md
+
+IMPORTANTE: Este é um processo CONVERSACIONAL, não um checklist. Adapte suas perguntas às respostas do usuário.
+
+Retorne APENAS:
+project_defined
+File: .sincron-plan/PROJECT.md
+Lines: [N]"
+)
+```
+
+---
+
+### FASE 3: PESQUISA DE DOMÍNIO (Opcional)
+
+Perguntar ao usuário usando AskUserQuestion:
+```
+header: "Pesquisa"
+question: "Deseja pesquisar ecossistema e melhores práticas antes de definir requisitos?"
+options:
+- label: "Sim, pesquisar"
+  description: "Busca bibliotecas, frameworks e best practices relevantes"
+- label: "Não, pular"
+  description: "Vai direto para definição de requisitos"
+```
+
+**SE escolher "Sim":**
+```
+Task(
+  subagent_type: "general-purpose",
+  prompt: "Você é o Pesquisador do Sincron-Plan.
+
+Sua missão: Pesquisar o ecossistema relevante ao projeto definido em .sincron-plan/PROJECT.md.
+
+Siga as instruções em sincron-plan/agents/pesquisador.md.
+
+Processo:
+1. Ler .sincron-plan/PROJECT.md para contexto
+2. Identificar domínios de pesquisa
+3. Usar WebSearch para descoberta
+4. Usar WebFetch para documentação oficial
+5. Categorizar em Table Stakes, Differentiators, Anti-features
+6. Escrever .sincron-plan/research/SUMMARY.md
+
+Retorne APENAS:
+research_complete
+File: .sincron-plan/research/SUMMARY.md
+Lines: [N]
+Topics: [lista]"
+)
+```
+
+---
+
+### FASE 4: DEFINIÇÃO DE REQUISITOS
+
+**4.1 SE pesquisa foi feita:**
+Ler `.sincron-plan/research/SUMMARY.md` e apresentar features descobertas:
+
+```markdown
+## Features Descobertas na Pesquisa
+
+### Table Stakes (Essenciais)
+Estas features são expectativa mínima no mercado:
+1. [Feature 1]
+2. [Feature 2]
+
+### Differentiators (Oportunidades)
+Estas features podem destacar seu produto:
+1. [Feature 1]
+2. [Feature 2]
+
+### Anti-Features (Evitar)
+Complexidades que não agregam valor:
+1. [Feature 1]
+```
+
+**4.2 Coletar requisitos do usuário:**
+Usar AskUserQuestion para cada categoria de feature descoberta, ou perguntar diretamente se não houve pesquisa:
+
+```
+header: "Requisitos"
+question: "Quais features você quer incluir?"
+multiSelect: true
+options:
+- label: "[Feature 1]"
+  description: "[descrição breve]"
+- label: "[Feature 2]"
+  description: "[descrição breve]"
+...
+```
+
+**4.3 Classificar requisitos:**
+```
+header: "Priorização"
+question: "Para cada feature selecionada, classifique como:"
+options:
+- label: "v1 (MVP)"
+  description: "Precisa estar na primeira versão"
+- label: "v2 (Futuro)"
+  description: "Importante, mas pode esperar"
+- label: "Fora de escopo"
+  description: "Não faz parte deste projeto"
+```
+
+**4.4 Gerar REQUIREMENTS.md:**
+```markdown
+# Requirements: [Project Name]
+
+**Generated:** [YYYY-MM-DD]
+
+## v1 (MVP)
+| ID | Requirement | Source |
+|----|-------------|--------|
+| REQ-001 | [description] | User/Research |
+
+## v2 (Future)
+| ID | Requirement | Rationale for Deferral |
+|----|-------------|------------------------|
+| REQ-010 | [description] | [why not v1] |
+
+## Out of Scope
+| Feature | Reason |
+|---------|--------|
+| [feature] | [why excluded] |
+```
+
+Escrever em `.sincron-plan/REQUIREMENTS.md`.
+
+---
+
+### FASE 5: GERAÇÃO DO PRD
+
+Spawnar agente Planejador:
+```
+Task(
+  subagent_type: "general-purpose",
+  prompt: "Você é o Planejador do Sincron-Plan.
+
+Sua missão: Transformar os requisitos em PRD, Roadmap e User Stories.
+
+Inputs disponíveis em .sincron-plan/:
+- PROJECT.md (obrigatório)
+- REQUIREMENTS.md (obrigatório)
+- research/SUMMARY.md (se existir)
+- codebase/*.md (se existir)
+
+Siga as instruções em sincron-plan/agents/planejador.md.
+Use os templates em sincron-plan/templates/.
+
+Processo:
+1. Ler todos os inputs
+2. Agrupar requisitos em fases lógicas
+3. Identificar dependências
+4. Gerar success criteria observáveis
+5. Converter em user stories formato Sincron-Auto
+6. Escrever PRD.md, ROADMAP.md, user-stories.md
+
+Retorne APENAS:
+planning_complete
+Files:
+- .sincron-plan/PRD.md ([N] lines)
+- .sincron-plan/ROADMAP.md ([N] lines)
+- .sincron-plan/user-stories.md ([N] lines)
+Total User Stories: [N]
+Phases: [N]"
+)
+```
+
+---
+
+### FASE 6: APROVAÇÃO
+
+Apresentar resumo do plano gerado:
+```markdown
+## Plano Gerado
+
+**Projeto**: [nome]
+**Fases**: [N]
+**User Stories**: [N]
+**Requisitos v1**: [N]
+**Requisitos v2**: [N]
+
+### Fases
+1. [Phase 1 name] - [N] stories
+2. [Phase 2 name] - [N] stories
+...
+
+Documentos gerados:
+- `.sincron-plan/PRD.md`
+- `.sincron-plan/ROADMAP.md`
+- `.sincron-plan/user-stories.md`
+```
+
+Perguntar ao usuário:
+```
+header: "Aprovação"
+question: "Este plano funciona para você?"
+options:
+- label: "Aprovar"
+  description: "Plano está bom, finalizar"
+- label: "Ajustar"
+  description: "Preciso de modificações"
+```
+
+**SE "Ajustar":**
+Perguntar o que precisa mudar e regenerar a fase relevante.
+
+---
+
+### FASE 7: INTEGRAÇÃO COM SINCRON-AUTO
+
+**7.1 Detectar se Sincron-Auto está instalado:**
+Verificar se existe `.claude/commands/sincron-auto.md`.
+
+**7.2 SE instalado:**
+```
+header: "Sincron-Auto"
+question: "Sincron-Auto detectado. Copiar user-stories para execução?"
+options:
+- label: "Sim, copiar"
+  description: "Copia para .sincron-auto/user-stories.md"
+- label: "Não, manter apenas aqui"
+  description: "User stories ficam em .sincron-plan/"
+```
+
+**SE "Sim":**
+```bash
+mkdir -p .sincron-auto
+cp .sincron-plan/user-stories.md .sincron-auto/user-stories.md
+```
+
+**7.3 SE não instalado:**
+```
+User stories prontas em `.sincron-plan/user-stories.md`
+
+Para executar com Sincron-Auto:
+1. Instale o plugin Sincron-Auto
+2. Execute /sincron-auto para iniciar implementação
+```
+
+---
+
+### FASE 8: ATUALIZAR STATE
+
+Atualizar `.sincron-plan/state.json`:
+```json
+{
+  "status": "complete",
+  "project_name": "[nome]",
+  "has_codebase_map": true/false,
+  "has_research": true/false,
+  "phases": [
+    {
+      "id": 1,
+      "name": "[name]",
+      "requirements": ["REQ-001", "REQ-002"],
+      "stories": ["US-001", "US-002"],
+      "status": "pending"
+    }
+  ],
+  "requirements": {
+    "v1": ["REQ-001", "REQ-002"],
+    "v2": ["REQ-010"],
+    "out_of_scope": ["REQ-020"]
+  },
+  "planning_date": "[YYYY-MM-DD]"
+}
+```
+
+---
+
+### FASE 9: FINALIZAR
+
+```markdown
+## ✅ Planejamento Completo
+
+### Documentos Gerados
+| Documento | Descrição |
+|-----------|-----------|
+| `PROJECT.md` | Definição do projeto |
+| `REQUIREMENTS.md` | Requisitos classificados |
+| `PRD.md` | Product Requirements Document |
+| `ROADMAP.md` | Visão de fases |
+| `user-stories.md` | Stories para implementação |
+
+### Estatísticas
+- **Fases**: [N]
+- **User Stories**: [N]
+- **Requisitos v1**: [N]
+- **Requisitos v2**: [N]
+
+### Próximos Passos
+[Se Sincron-Auto detectado]
+Execute `/sincron-auto` para iniciar a implementação.
+
+[Se não]
+Use as user stories em `.sincron-plan/user-stories.md` como guia de implementação.
+```
+
+## Tratamento de Erros
+
+### Agente Questionador Não Consegue Clareza
+```
+"Não consegui entender completamente o projeto após várias tentativas.
+Pontos ainda confusos:
+- [ponto 1]
+- [ponto 2]
+
+Podemos tentar novamente com mais contexto?"
+```
+
+### Pesquisa Retorna Pouco
+```
+"A pesquisa retornou poucos resultados relevantes.
+Isso pode acontecer com domínios muito nichados.
+
+Deseja continuar sem pesquisa ou tentar termos diferentes?"
+```
+
+### Planejador Não Consegue Gerar
+```
+"Não consegui gerar o plano. Possíveis causas:
+- Requisitos muito vagos
+- Conflitos entre requisitos
+- Escopo muito amplo
+
+Deseja revisar os requisitos?"
+```

package/docs/arquitetura.md

@@ -0,0 +1,106 @@
+# Arquitetura do Sincron-Plan
+
+## Visão Geral
+
+O Sincron-Plan é um plugin independente que adiciona capacidades de planejamento estruturado e mapeamento de codebase ao ecossistema Sincron.
+
+## Decisões Arquiteturais
+
+| Decisão | Escolha | Rationale |
+|---------|---------|-----------|
+| Arquitetura | Plugin Separado | Independência, pode ser usado com ou sem Sincron-Auto |
+| Fluxo Brownfield | Oferecer mapeamento | Pergunta se quer mapear, mas permite pular (greenfield) |
+| Documentos de Mapeamento | 4 essenciais | STACK, ARCHITECTURE, STRUCTURE, CONCERNS |
+
+## Arquitetura Anti-OOM
+
+**Regra Fundamental**: Máximo 2 níveis de aninhamento.
+
+```
+Command (sincron-plan.md ou sincron-map.md)
+    ├─ Task(Questionador) → retorna project_defined
+    ├─ Task(Pesquisador) → retorna research_complete
+    ├─ Task(Mapeador x2 paralelo) → retorna mapping_complete
+    └─ Task(Planejador) → retorna planning_complete
+```
+
+### Restrições dos Agentes
+
+Agentes NUNCA:
+- Chamam outros agentes
+- Usam AskUserQuestion (apenas Command usa)
+- Retornam conteúdo volumoso (apenas status + file paths)
+
+### Comunicação via Arquivos
+
+```
+.sincron-plan/
+├── request.json          # Command → Agentes
+├── PROJECT.md            # Questionador output
+├── codebase/             # Mapeador output
+│   ├── STACK.md
+│   ├── ARCHITECTURE.md
+│   ├── STRUCTURE.md
+│   └── CONCERNS.md
+├── research/
+│   └── SUMMARY.md        # Pesquisador output
+├── REQUIREMENTS.md       # Command gera após seleção
+├── PRD.md                # Planejador output
+├── ROADMAP.md            # Planejador output
+└── user-stories.md       # Planejador output (Sincron-Auto format)
+```
+
+## State Management
+
+**Arquivo**: `.sincron-plan/state.json`
+
+```json
+{
+  "status": "initialized | mapped | planned | complete",
+  "project_name": "...",
+  "has_codebase_map": true,
+  "has_research": false,
+  "phases": [
+    {
+      "id": 1,
+      "name": "Foundation",
+      "requirements": ["REQ-001", "REQ-002"],
+      "status": "pending"
+    }
+  ],
+  "requirements": {
+    "v1": ["REQ-001", "REQ-002"],
+    "v2": ["REQ-010"],
+    "out_of_scope": ["REQ-020"]
+  }
+}
+```
+
+## Integração com Sincron-Auto
+
+Quando Sincron-Auto está instalado:
+
+1. **Detecção automática**: Verificar se `.claude/commands/sincron-auto.md` existe
+2. **Conversão**: User stories geradas já seguem formato Sincron-Auto
+3. **Cópia opcional**: Perguntar se quer copiar para `.sincron-auto/user-stories.md`
+4. **Bypass setup**: Se Sincron-Plan já rodou, Sincron-Auto pode pular fase de planejamento
+
+## Fluxo de Dados
+
+```
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│   User Input    │────▶│    Command      │────▶│    Agentes      │
+└─────────────────┘     └────────┬────────┘     └────────┬────────┘
+                                 │                       │
+                                 │                       ▼
+                                 │              ┌─────────────────┐
+                                 │              │  .sincron-plan/ │
+                                 │              │    (arquivos)   │
+                                 │              └────────┬────────┘
+                                 │                       │
+                                 ▼                       │
+                        ┌─────────────────┐              │
+                        │  State Machine  │◀─────────────┘
+                        │  (state.json)   │
+                        └─────────────────┘
+```

package/docs/fluxo.md

@@ -0,0 +1,166 @@
+# Fluxo do Sincron-Plan
+
+## Fluxo Visual Completo
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        /sincron-plan                            │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+                    ┌─────────────────┐
+                    │ Código existe?  │
+                    └────────┬────────┘
+                             │
+              ┌──────────────┴──────────────┐
+              │                             │
+              ▼                             ▼
+    ┌─────────────────┐           ┌─────────────────┐
+    │   SIM - Mapear? │           │  NÃO - Greenfield│
+    └────────┬────────┘           └────────┬────────┘
+             │                             │
+     ┌───────┴───────┐                     │
+     │               │                     │
+     ▼               ▼                     │
+┌─────────┐    ┌─────────┐                 │
+│ /map    │    │  Pular  │                 │
+└────┬────┘    └────┬────┘                 │
+     │              │                      │
+     └──────────────┴──────────────────────┘
+                              │
+                              ▼
+                    ┌─────────────────┐
+                    │  Questionador   │
+                    │   (PROJECT.md)  │
+                    └────────┬────────┘
+                             │
+                              ▼
+                    ┌─────────────────┐
+                    │  Pesquisar?     │
+                    └────────┬────────┘
+                             │
+              ┌──────────────┴──────────────┐
+              │                             │
+              ▼                             ▼
+    ┌─────────────────┐           ┌─────────────────┐
+    │   Pesquisador   │           │     Pular       │
+    │  (SUMMARY.md)   │           │                 │
+    └────────┬────────┘           └────────┬────────┘
+             │                             │
+             └──────────────┬──────────────┘
+                            │
+                            ▼
+                  ┌─────────────────┐
+                  │ Seleção de Reqs │
+                  │ (REQUIREMENTS)  │
+                  └────────┬────────┘
+                           │
+                           ▼
+                  ┌─────────────────┐
+                  │   Planejador    │
+                  │ (PRD + Stories) │
+                  └────────┬────────┘
+                           │
+                           ▼
+                  ┌─────────────────┐
+                  │   Aprovação     │
+                  └────────┬────────┘
+                           │
+              ┌────────────┴────────────┐
+              │                         │
+              ▼                         ▼
+    ┌─────────────────┐       ┌─────────────────┐
+    │Sincron-Auto     │       │  Finalizar      │
+    │detectado? Copiar│       │                 │
+    └─────────────────┘       └─────────────────┘
+```
+
+## Descrição das Fases
+
+### FASE 1: DETECÇÃO DE CONTEXTO
+- Verificar se existe código no diretório
+- SE existe código E NÃO existe `.sincron-plan/codebase/`:
+  - Perguntar: "Detectei código existente. Deseja mapear antes de planejar?"
+  - Sim → Executar /sincron-map primeiro
+  - Não → Continuar (usuário assume risco)
+- SE não existe código OU já tem mapeamento:
+  - Continuar para Fase 2
+
+### FASE 2: QUESTIONAMENTO PROFUNDO
+- Spawnar agente Questionador
+- Processo conversacional (NÃO checklist):
+  1. "O que você quer construir?"
+  2. Follow-ups baseados na resposta
+  3. Clarificar: problema, usuários, definição de "pronto"
+  4. Desafiar vaguidões: "Quando você diz X, quer dizer A ou B?"
+- Gate de decisão: "Entendi o suficiente. Criar PROJECT.md?"
+  - Sim → Escrever `.sincron-plan/PROJECT.md`
+  - Continuar explorando → Loop
+- Retornar ao Command com: `project_defined`
+
+### FASE 3: PESQUISA DE DOMÍNIO (Opcional)
+- Perguntar: "Pesquisar ecossistema/melhores práticas antes de definir requisitos?"
+- SE Sim:
+  - Spawnar agente Pesquisador
+  - Usar Context7 PRIMEIRO (libraries/frameworks)
+  - WebSearch para descoberta
+  - Gerar `.sincron-plan/research/SUMMARY.md`
+  - Retornar: `research_complete`
+- SE Não:
+  - Pular para Fase 4
+
+### FASE 4: DEFINIÇÃO DE REQUISITOS
+- Apresentar features descobertas (se pesquisa feita)
+  - Table stakes (essenciais)
+  - Differentiators (diferenciais)
+  - Anti-features (não fazer)
+- Usuário seleciona: v1 / v2 / fora de escopo
+- Gerar `.sincron-plan/REQUIREMENTS.md` com REQ-IDs
+- Retornar: `requirements_defined`
+
+### FASE 5: GERAÇÃO DO PRD
+- Spawnar agente Planejador
+- Inputs:
+  - PROJECT.md
+  - REQUIREMENTS.md
+  - research/SUMMARY.md (se existe)
+  - codebase/*.md (se existe)
+- Processo:
+  1. Agrupar requirements em fases lógicas
+  2. Identificar dependências
+  3. Definir success criteria (perspectiva do usuário)
+  4. Gerar PRD.md com user stories formato Sincron-Auto
+- Gate de aprovação: "Este plano funciona para você?"
+  - Aprovar → Finalizar
+  - Ajustar → Feedback e regenerar
+- Saída final:
+  - `.sincron-plan/PRD.md` (PRD completo)
+  - `.sincron-plan/ROADMAP.md` (visão de fases)
+  - `.sincron-plan/user-stories.md` (formato Sincron-Auto)
+
+### FASE 6: INTEGRAÇÃO COM SINCRON-AUTO (se disponível)
+- Detectar se Sincron-Auto está instalado
+- SE instalado:
+  - Perguntar: "Sincron-Auto detectado. Copiar user-stories para execução?"
+  - Sim → Copiar para `.sincron-auto/user-stories.md`
+  - Não → Apenas manter em `.sincron-plan/`
+- SE não instalado:
+  - Exibir: "User stories prontas em `.sincron-plan/user-stories.md`"
+
+## Fluxo do /sincron-map
+
+```
+1. Verificar se .sincron-plan/codebase/ existe
+   ├─ Existe → Perguntar: Atualizar / Usar existente / Ignorar
+   └─ Não existe → Continuar
+
+2. Spawnar 2 agentes mapeadores em paralelo (arquitetura anti-OOM):
+   ├─ Agente 1: STACK.md + ARCHITECTURE.md
+   └─ Agente 2: STRUCTURE.md + CONCERNS.md
+
+3. Aguardar confirmações (file paths + line counts apenas)
+
+4. Verificar outputs (todos 4 documentos existem, >20 linhas cada)
+
+5. Exibir resumo e sugerir: /sincron-plan para iniciar planejamento
+```