synapos 2.5.0

package/.synapos/core/best-practices/product/user-research.md

@@ -0,0 +1,242 @@
+---
+id: user-research
+version: "1.0.0"
+domain: [produto]
+whenToUse: "Quando o squad realiza pesquisa de usuário ou mercado"
+---
+
+# User Research
+
+> Métodos, templates e síntese para pesquisa de usuário e mercado.
+
+---
+
+## Quando Pesquisar
+
+| Situação | Método recomendado |
+|----------|-------------------|
+| Entender um problema novo | Entrevistas qualitativas |
+| Validar hipótese de solução | Teste de usabilidade |
+| Medir satisfação | Survey / NPS |
+| Comparar opções de design | Teste A/B |
+| Entender o mercado | Desk research + benchmarks |
+| Priorizar features | Pesquisa de Jobs-to-be-Done |
+
+---
+
+## Entrevistas
+
+### Quando usar
+- Explorar problemas desconhecidos
+- Entender contexto e motivações profundas
+- Validar assumções antes de construir
+
+### Planejamento
+
+```markdown
+## Plano de Entrevistas
+
+**Objetivo:** Entender como freelancers gerenciam seus pagamentos hoje
+
+**Hipóteses a validar:**
+1. Freelancers perdem tempo controlando pagamentos manualmente
+2. A falta de visibilidade de inadimplência é o maior pain point
+
+**Perfil dos participantes:**
+- Freelancers PJ com 2+ anos de experiência
+- Pelo menos 3 clientes simultâneos
+- 5–8 participantes (saturação esperada)
+
+**Duração:** 45–60 minutos
+**Formato:** Videoconferência (gravado com consentimento)
+```
+
+### Roteiro de Entrevista
+
+```markdown
+## Roteiro — Gestão Financeira de Freelancers
+
+### Aquecimento (5 min)
+- Me conta um pouco sobre o seu trabalho: o que você faz, há quanto tempo freelancer?
+- Como é a sua semana típica de trabalho?
+
+### Exploração (30 min)
+- Me conta como você gerencia os pagamentos dos seus clientes hoje.
+- Quando você emite uma cobrança, o que acontece a seguir?
+- Já teve situação de cliente que não pagou? Me conta como foi.
+- O que você faz quando percebe que um pagamento está atrasado?
+- Quais ferramentas você usa para isso? Por quê essas?
+
+### Aprofundamento (10 min)
+- Qual é o maior incômodo nesse processo hoje?
+- Se você pudesse mudar uma coisa nesse fluxo, o que seria?
+
+### Encerramento (5 min)
+- Tem algo que você acha importante que eu saiba e não perguntei?
+- Posso entrar em contato para dúvidas de acompanhamento?
+```
+
+### Boas Práticas
+- Pergunte sobre **comportamento passado**, não futuro ("você faria X?" → não confiável)
+- Use silêncio produtivo — espere o entrevistado completar o pensamento
+- Pergunte "por quê" pelo menos 3 vezes para chegar ao motivador real
+- Não valide hipóteses durante a entrevista — observe, não dirija
+- Tome notas de citações diretas (entre aspas)
+
+---
+
+## Surveys
+
+### Quando usar
+- Validar ou quantificar achados qualitativos
+- Medir satisfação ou NPS
+- Coletar dados de uma amostra maior (n > 30)
+
+### Boas Práticas de Perguntas
+
+```markdown
+✅ "Com que frequência você emite cobranças para clientes?"
+   [ ] Diariamente  [ ] Semanalmente  [ ] Mensalmente  [ ] Raramente
+
+❌ "Você usa o sistema com frequência?" (vago, sem escala)
+
+✅ "Quão satisfeito você está com o processo de cobranças?"
+   [1 — Muito insatisfeito] ... [5 — Muito satisfeito]
+
+❌ "O processo de cobranças é bom?" (sim/não não gera insight)
+```
+
+### Estrutura de Survey
+
+1. **Introdução** (1 parágrafo): objetivo, tempo estimado, anonimato
+2. **Triagem** (1–2 perguntas): filtrar perfil correto
+3. **Perguntas principais** (5–10): foco no objetivo
+4. **NPS** (opcional): "De 0 a 10, você recomendaria X?"
+5. **Campo aberto** (opcional): "Tem algo mais que queira compartilhar?"
+
+### Tamanho da Amostra
+- Pesquisa exploratória: n ≥ 30
+- Validação quantitativa: n ≥ 100
+- Decisão de negócio de alto impacto: n ≥ 300
+
+---
+
+## Jobs-to-be-Done (JTBD)
+
+Framework para entender **por que** alguém "contrata" um produto ou feature.
+
+### Formato de Job Statement
+
+```
+Quando [situação],
+eu quero [motivação],
+para [resultado esperado].
+```
+
+### Exemplo
+
+```
+Quando percebo que um cliente está com pagamento atrasado,
+quero ser notificado automaticamente,
+para agir antes que vire inadimplência longa.
+```
+
+### Como coletar
+- Durante entrevistas: "Me conta a última vez que você precisou [situação]"
+- Identifique o gatilho (situação), a força de atração e os obstáculos
+
+---
+
+## Análise e Síntese
+
+### Affinity Mapping
+
+Agrupe observações por temas emergentes (não categorias pré-definidas):
+
+```
+Post-its / notas → Agrupamento → Temas → Insights → Recomendações
+```
+
+Ferramentas: FigJam, Miro, Notion
+
+### Template de Insight
+
+```markdown
+## Insight: {título em uma frase}
+
+**Evidência:** (citações diretas ou dados)
+> "Eu nunca sei se o cliente viu a cobrança ou simplesmente ignorou"
+> "Uso planilha porque o sistema não me avisa de nada"
+
+**Observação:** O que esse comportamento revela?
+Freelancers perdem confiança no processo de cobrança e compensam
+com ferramentas paralelas (planilhas, anotações) por falta de visibilidade.
+
+**Oportunidade:** Como podemos responder a isso?
+Notificações proativas de leitura/status da cobrança eliminariam
+a necessidade de workarounds e aumentariam confiança no produto.
+```
+
+### Relatório de Síntese — Estrutura Mínima
+
+```markdown
+# Síntese de Pesquisa — {Tema}
+
+**Data:** YYYY-MM-DD
+**Método:** Entrevistas (n=6) + Survey (n=84)
+**Responsável:** {nome}
+
+## Top 3 Insights
+1. ...
+2. ...
+3. ...
+
+## Personas Refinadas
+(atualizar personas existentes com novos dados)
+
+## Recomendações
+| Prioridade | Recomendação | Evidência |
+|------------|--------------|-----------|
+| Alta | ... | Insight #1 |
+
+## O que não encontramos
+(hipóteses que não se confirmaram — tão valioso quanto o que confirmamos)
+
+## Próximos passos
+- [ ] ...
+```
+
+---
+
+## Desk Research / Benchmarks
+
+### Quando usar
+- Entender o mercado antes de entrevistar usuários
+- Mapear soluções concorrentes
+- Identificar padrões de UX no setor
+
+### Estrutura de Benchmark
+
+| Critério | Produto A | Produto B | Produto C | Nossa solução atual |
+|----------|-----------|-----------|-----------|---------------------|
+| Onboarding | ... | ... | ... | ... |
+| Cobrança | ... | ... | ... | ... |
+| Notificações | ... | ... | ... | ... |
+| Mobile | ... | ... | ... | ... |
+
+### Fontes confiáveis
+- App Store / Play Store (reviews)
+- G2, Capterra (feedback de usuários reais)
+- ProductHunt (lançamentos e comentários)
+- Artigos de blog dos concorrentes (posicionamento)
+
+---
+
+## Ética em Pesquisa
+
+- Obtenha **consentimento informado** antes de gravar
+- Explique o uso das informações coletadas
+- Garanta anonimato quando prometido
+- Não colete dados desnecessários
+- Dê ao participante a opção de se retirar a qualquer momento
+- Nunca use dados de pesquisa para fins comerciais diretos sem consentimento

package/.synapos/core/commands/bump.md

@@ -0,0 +1,59 @@
+## PROTOCOLO DE BUMP
+
+### 1 — Ler estado atual
+- Leia `.synapos/VERSION` → versão atual do framework
+- Leia `.synapos/.manifest.json` → inventário completo
+- Leia `.synapos/CHANGELOG.md` → histórico de mudanças
+
+### 2 — Identificar o que mudou
+Pergunte ao usuário (se não informado nos argumentos):
+```
+O que foi alterado?
+  [1] Agent (qual?)
+  [2] Template de squad (qual?)
+  [3] Core (orchestrator / pipeline-runner / gate-system / skills-engine)
+  [4] Múltiplos
+
+Tipo de mudança:
+  [M] MAJOR — quebra compatibilidade
+  [m] MINOR — adiciona sem quebrar
+  [p] PATCH — corrige sem quebrar
+```
+
+### 3 — Calcular nova versão
+Use semver: `MAJOR.MINOR.PATCH`
+- PATCH: Z+1 (ex: 1.0.0 → 1.0.1)
+- MINOR: Y+1, Z=0 (ex: 1.0.3 → 1.1.0)
+- MAJOR: X+1, Y=0, Z=0 (ex: 1.2.1 → 2.0.0)
+
+### 4 — Executar o bump
+Execute em ordem:
+
+**4a.** Atualizar `version:` no frontmatter do(s) arquivo(s) modificado(s)
+
+**4b.** Atualizar `.synapos/.manifest.json`:
+- Versão do componente alterado
+- Versão do framework (`framework.version` e `framework.released_at`)
+
+**4c.** Atualizar `.synapos/VERSION` com a nova versão do framework
+
+**4d.** Adicionar entrada no `.synapos/CHANGELOG.md`:
+```markdown
+## [{nova_versão}] — {YYYY-MM-DD}
+
+### {Adicionado | Modificado | Corrigido | Removido}
+- `{componente}` v{versão} — {descrição da mudança}
+```
+
+### 5 — Confirmar
+Apresente um resumo do bump realizado:
+```
+Bump concluído!
+
+Versão: {anterior} → {nova}
+Arquivos atualizados:
+  ✅ .synapos/VERSION
+  ✅ .synapos/.manifest.json
+  ✅ .synapos/CHANGELOG.md
+  ✅ {arquivo do componente alterado}
+```

package/.synapos/core/commands/debug/session.md

@@ -0,0 +1,100 @@
+---
+description: Diagnóstico e recovery de sessions interrompidas ou corrompidas
+---
+
+# Debug: Session
+
+> Use quando uma session está em estado inconsistente, corrompida ou travada.
+
+---
+
+## Quando Usar
+
+- `state.json` não parseia (JSON inválido)
+- Squad mostra `status: "running"` mas não havia execução ativa
+- Pipeline parou sem anunciar o motivo
+- `memories.md` com conteúdo duplicado ou corrompido
+- Squad criado mas não aparece no menu do orchestrator
+
+---
+
+## Diagnóstico
+
+### Passo 1 — Localizar a session
+
+```
+docs/.squads/sessions/{feature-slug}/
+├── state.json       ← verifique primeiro
+├── memories.md
+└── ...
+```
+
+Se não sabe o `feature-slug`: liste `docs/.squads/sessions/` para ver sessions existentes.
+
+### Passo 2 — Verificar state.json
+
+Leia `docs/.squads/sessions/{feature-slug}/state.json`:
+
+| Situação | Diagnóstico |
+|----------|-------------|
+| Arquivo não existe | Session nunca foi iniciada ou foi deletada |
+| JSON inválido (erro de parse) | Corrupção — verifique `state.json.bak.*` |
+| Squad com `status: "running"` sem execução ativa | Session travada — precisa de reset |
+| Squad com `status: "awaiting_approval"` | Checkpoint assíncrono pendente — verifique `pending-approvals.md` |
+| Squad com `status: "blocked"` | Escalation pendente — verifique `open-decisions.md` |
+
+### Passo 3 — Recovery por situação
+
+**state.json corrompido:**
+1. Verifique se existe `state.json.bak.{timestamp}` na mesma pasta
+2. Se existir: renomeie o `.bak` para `state.json`
+3. Se não existir: reinicialize com estrutura mínima:
+   ```json
+   {
+     "feature": "{feature-slug}",
+     "created_at": "{data-atual}",
+     "updated_at": "{data-atual}",
+     "squads": {}
+   }
+   ```
+4. Execute `/init` → o squad pode ser recarregado
+
+**Squad travado em "running":**
+1. Edite `state.json`
+2. Mude `status: "running"` → `status: "discarded"` para o squad afetado
+3. Execute `/init` → crie novo squad para a mesma feature
+4. Na criação: selecione a session existente (os artefatos como `context.md` são preservados)
+
+**Checkpoint assíncrono pendente:**
+1. Leia `docs/.squads/sessions/{feature-slug}/pending-approvals.md`
+2. Revise o conteúdo do checkpoint
+3. Execute `/init` → selecione o squad → "Retomar de onde parou"
+4. O orchestrator apresentará o checkpoint para aprovação
+
+**Squad bloqueado por escalation:**
+1. Leia `docs/.squads/sessions/{feature-slug}/open-decisions.md`
+2. Para cada `[DECISÃO PENDENTE]` com `status: pending`:
+   - Escolha uma opção (A, B, ou defina outra)
+   - Atualize o campo `status: resolved` + registre a decisão tomada
+3. Execute `/init` → selecione o squad → "Retomar de onde parou"
+
+---
+
+## Comandos de Recovery Rápido
+
+| Situação | Ação |
+|----------|------|
+| state.json corrompido | Restaurar do `.bak` mais recente ou reinicializar |
+| Squad stuck em running | Marcar como `discarded`, criar novo squad |
+| memories.md duplicado | Remover duplicatas manualmente (é append-only, nunca bloqueia execução) |
+| output_file faltando | Reexecutar o step via retomada |
+| Squad não aparece no menu | Verificar se `.synapos/squads/{slug}/squad.yaml` existe |
+
+---
+
+## Prevenção
+
+- Nunca edite `state.json` diretamente durante execução de pipeline
+- Nunca delete `state.json` sem backup — use `status: "discarded"` no squad
+- Se interromper uma execução, use sempre o fluxo de retomada do orchestrator
+- Para features longas, consolide `memories.md` periodicamente (o pipeline-runner oferece automaticamente após 10 entradas)

package/.synapos/core/commands/migrate/v1-to-v2.md

@@ -0,0 +1,142 @@
+---
+description: Migration path de projetos Synapos v1.x para v2.0+
+---
+
+# Migration: v1.x → v2.0+
+
+> Para projetos que usavam Synapos antes da versão 2.0.0.
+
+---
+
+## O Que Mudou de v1 para v2
+
+### Breaking Changes
+
+| v1.x | v2.0+ | Impacto |
+|------|-------|---------|
+| Output em `docs/.squads/{slug}/output/{run_id}/` | Session em `docs/.squads/sessions/{feature-slug}/` | Todos os arquivos de output mudaram de lugar |
+| `squad.yaml` sem campos `feature` e `session` | Campos `feature` e `session` obrigatórios | GATE-1 falha sem esses campos |
+| `state.json` por squad em `docs/.squads/{slug}/` | `state.json` único por feature em `docs/.squads/sessions/{feature-slug}/` | Rastreamento centralizado |
+| `squad_memory` no squad.yaml | Campo removido | Usar `session` apontando para pasta de session |
+| `memories.md` por squad | `memories.md` por feature (compartilhada) | Aprendizados entre squads ficam visíveis |
+
+### Mudanças Não-Breaking (novas capacidades)
+
+- `pre_pipeline` em squad templates — disponível mas opcional
+- `leo-engenheiro` como agent opcional — disponível mas não obrigatório
+- `async_checkpoints` no squad.yaml — `false` por padrão
+- Compliance Obrigatório nos agents — adicionado mas compatível com agents existentes
+
+---
+
+## Passos de Migração
+
+### Passo 1 — Identificar sessions v1 existentes
+
+Liste as pastas de output antigas:
+```
+docs/.squads/{squad-slug}/output/
+```
+
+Para cada squad com runs anteriores, anote:
+- O `feature-slug` que corresponde a cada run
+- Quais arquivos importantes foram gerados (context.md, architecture.md, spec.md, etc.)
+
+### Passo 2 — Criar estrutura v2
+
+Para cada feature:
+```
+mkdir -p docs/.squads/sessions/{feature-slug}/
+```
+
+### Passo 3 — Migrar artefatos relevantes
+
+Copie os artefatos importantes do último run válido:
+```
+cp docs/.squads/{slug}/output/{run_id}/context.md     docs/.squads/sessions/{feature-slug}/
+cp docs/.squads/{slug}/output/{run_id}/architecture.md docs/.squads/sessions/{feature-slug}/
+cp docs/.squads/{slug}/output/{run_id}/spec.md         docs/.squads/sessions/{feature-slug}/
+# copie os demais arquivos relevantes
+```
+
+Se havia `_memory/memories.md` por squad:
+```
+cp docs/.squads/{slug}/_memory/memories.md docs/.squads/sessions/{feature-slug}/memories.md
+```
+
+### Passo 4 — Criar state.json inicial
+
+Crie `docs/.squads/sessions/{feature-slug}/state.json`:
+```json
+{
+  "feature": "{feature-slug}",
+  "created_at": "{data-atual}",
+  "updated_at": "{data-atual}",
+  "squads": {
+    "{squad-slug}": {
+      "domain": "{dominio}",
+      "pipeline": "{pipeline-usado}",
+      "started_at": "{data-original-se-souber}",
+      "completed_at": null,
+      "status": "migrated",
+      "completed_steps": [],
+      "current_step": null,
+      "suspended_at": null
+    }
+  }
+}
+```
+
+### Passo 5 — Atualizar squad.yaml
+
+Adicione os campos obrigatórios ao `.synapos/squads/{slug}/squad.yaml`:
+
+```yaml
+# Adicionar estes campos:
+feature: {feature-slug}
+session: docs/.squads/sessions/{feature-slug}/
+
+# Remover este campo (se existir):
+# squad_memory: docs/.squads/{slug}/_memory/
+```
+
+### Passo 6 — Verificar migração
+
+Execute `/init` → selecione o squad migrado.
+
+O orchestrator deve:
+1. Ler `feature` e `session` do squad.yaml ✅
+2. Encontrar `state.json` na session ✅
+3. Mostrar o squad como disponível no menu ✅
+
+Se GATE-1 falhar: verifique se os campos `feature` e `session` estão no squad.yaml.
+
+---
+
+## Projetos Sem v1 (onboarding limpo)
+
+Se não há estrutura v1: ignore este guia. Siga [GETTING_STARTED.md](../../../../GETTING_STARTED.md).
+
+---
+
+## Verificação Final
+
+Após migrar todos os squads:
+
+```
+docs/.squads/sessions/
+├── {feature-1}/
+│   ├── state.json        ← criado no Passo 4
+│   ├── context.md        ← migrado do run anterior
+│   └── memories.md       ← migrado de _memory/memories.md
+└── {feature-2}/
+    └── state.json
+```
+
+E em `.synapos/squads/{slug}/squad.yaml`:
+```yaml
+feature: {feature-slug}   ← obrigatório
+session: docs/.squads/sessions/{feature-slug}/  ← obrigatório
+```
+
+Se tudo estiver correto: `/init` deve funcionar normalmente com os squads migrados.