synapos 2.5.0

package/.synapos/squad-templates/engineer/pipeline/steps/02-preparacao.md

@@ -0,0 +1,66 @@
+---
+id: 02-preparacao
+name: "Preparação"
+agent: leo-engenheiro
+execution: inline
+model_tier: fast
+---
+
+# Preparação
+
+## 1. Verificar branch de feature
+
+Execute:
+```bash
+git branch --show-current
+```
+
+- Se estiver em `main` ou `master`: apresente opção de criar branch de feature
+- Se já estiver em uma branch de feature: confirme e prossiga
+- Se o humano quiser criar: solicite o nome e execute `git checkout -b feature/{slug}`
+
+```
+[DECISÃO PENDENTE] branch-name
+Contexto: não há branch de feature ativa
+Opções:
+  A) Criar agora: git checkout -b feature/{nome-sugerido}
+  B) Continuar sem criar branch (não recomendado)
+Aguardando aprovação.
+```
+
+## 2. Verificar pasta de sessão
+
+Verifique se o diretório de output já existe e se há `context.md` ou `architecture.md` de uma sessão anterior:
+
+```
+docs/.squads/{slug}/output/{run_id}/context.md
+docs/.squads/{slug}/output/{run_id}/architecture.md
+```
+
+**Se existirem arquivos de sessão anterior** (run diferente do atual):
+```
+📂 Sessão anterior encontrada em: docs/.squads/{slug}/output/{run_id-anterior}/
+
+Arquivos existentes:
+  - context.md ✓
+  - architecture.md ✓ (ou ✗ se não existir)
+
+O que você quer fazer?
+
+- ▶️ Usar como base para esta sessão (continuar de onde parou)
+- 🔄 Ignorar e começar do zero
+```
+
+Aguarde seleção do usuário.
+
+## 3. Solicitar dados de entrada
+
+```
+Pronto para iniciar a investigação.
+
+Forneça os dados da feature:
+  - Cole os cartões do Linear (ID + descrição) ou descreva a feature livremente
+  - Se houver spec de negócio, indique o arquivo ou cole o conteúdo
+```
+
+Aguarde a resposta antes de avançar para o próximo step.

package/.synapos/squad-templates/engineer/pipeline/steps/03-investigacao.md

@@ -0,0 +1,110 @@
+---
+id: 03-investigacao
+name: "Investigação"
+agent: leo-engenheiro
+execution: inline
+model_tier: powerful
+output_files:
+  - context.md
+---
+
+# Investigação
+
+## Objetivo
+Transformar requisitos brutos em contexto estruturado e aprovado pelo humano, salvo em `context.md`.
+
+## 1. Verificar Project Briefing
+
+Antes de perguntar ao usuário, verifique:
+```
+docs/technical-context/project-briefing.md
+docs/technical-context/briefing/critical-rules.md
+docs/technical-context/briefing/adrs-summary.md
+```
+
+Se existirem: carregue as regras críticas e ADRs relevantes para incluir no context.md.
+
+## 2. Examinar os dados de entrada
+
+A partir dos cartões do Linear ou da descrição recebida no step anterior:
+
+Mapeie internamente:
+- **Motivação**: por que esta feature existe? qual problema resolve?
+- **Meta**: resultado esperado — mensurável e concreto
+- **Estratégia direcional**: como deve ser desenvolvido (alto nível, sem detalhes técnicos)
+- **Dependências**: o que precisa existir antes ou em paralelo?
+- **Limitações**: restrições conhecidas (tech, prazo, escopo)
+- **Validação**: como saber que está pronto?
+
+## 3. Formular perguntas de clarificação
+
+Reflita profundamente sobre o que está sendo pedido. Formule **3 a 5 perguntas críticas** — as que, se não respondidas, impediriam uma arquitetura sólida.
+
+Apresente ao humano:
+```
+Minha compreensão até agora:
+
+**Feature:** [nome]
+**Motivação:** [o que você entendeu]
+**Meta:** [resultado esperado]
+**Estratégia:** [direção geral]
+
+Antes de prosseguir, preciso de clarificação em:
+
+1. [Pergunta 1 — mais crítica]
+2. [Pergunta 2]
+3. [Pergunta 3]
+[...até 5]
+```
+
+Aguarde as respostas. Se necessário, continue o diálogo até ter contexto sólido.
+
+## 4. Verificar impacto em documentação de requisitos
+
+Se algo discutido aqui contradiz ou enriquece documentação existente:
+- Solicite permissão do humano para atualizar
+- Se o requisito está no Linear: atualize o cartão
+- Se é um arquivo local: atualize o arquivo
+
+## 5. Gerar context.md
+
+Quando o humano confirmar que a compreensão está correta, gere `context.md`:
+
+```markdown
+# Context: [Nome da Feature]
+
+## ⚠️ Regras Críticas do Projeto
+[Copiar de briefing/critical-rules.md se existir]
+[Se não existir: listar ADRs relevantes encontradas em docs/]
+
+## 📚 ADRs Relevantes
+[Lista de ADRs aplicáveis a esta feature com link/referência]
+
+## Motivação
+[Por que esta feature existe — contexto completo]
+
+## Meta
+[Resultado esperado — mensurável]
+
+## Estratégia
+[Direção geral — sem detalhes técnicos]
+
+## Dependências
+[O que precisa existir antes ou em paralelo]
+
+## Limitações
+[Restrições conhecidas]
+
+## Validação
+[Como saber que está pronto]
+
+## Questões Abertas
+[Itens que ainda precisam de resposta]
+
+## Frontend Integration (se aplicável)
+[Se envolve Lovable/frontend: listar mocks a integrar]
+```
+
+Apresente o context.md ao humano para revisão antes de salvar.
+
+**⛔ NÃO AVANCE. Aguarde o humano revisar e aprovar explicitamente o context.md antes de prosseguir para o checkpoint.**

package/.synapos/squad-templates/engineer/pipeline/steps/04-checkpoint-contexto.md

@@ -0,0 +1,24 @@
+---
+id: 04-checkpoint-contexto
+name: "Aprovação do Contexto"
+execution: checkpoint
+gate: GATE-2
+---
+
+# Aprovação do Contexto
+
+⏸ **CHECKPOINT — Revisão do context.md**
+
+O context.md foi gerado pelo step de Investigação. Revise-o antes de prosseguir.
+
+```
+O context.md está correto e completo?
+
+- ✅ Aprovar — prosseguir para Estruturação Arquitetural
+- ✏️ Ajustar contexto — voltar para Investigação com feedback
+- ⏭️ Pular revisão de arquitetura (avançar direto para Planejamento)
+```
+
+> Se ajustar: forneça o feedback específico e o step de Investigação será re-executado com esse feedback.
+
+> Se pular arquitetura: essa opção só é recomendada para features triviais onde a arquitetura é óbvia e consensual.

package/.synapos/squad-templates/engineer/pipeline/steps/05-arquitetura.md

@@ -0,0 +1,127 @@
+---
+id: 05-arquitetura
+name: "Estruturação Arquitetural"
+agent: leo-engenheiro
+execution: subagent
+model_tier: powerful
+output_files:
+  - architecture.md
+---
+
+# Estruturação Arquitetural
+
+## Contexto disponível
+Você recebe automaticamente:
+- `context.md` (aprovado pelo humano no step anterior)
+- Toda a documentação em `docs/` incluindo ADRs
+
+## Objetivo
+Produzir `architecture.md` — o design técnico completo da feature, alinhado com ADRs e convenções do projeto.
+
+## 1. Ler ADRs obrigatoriamente
+
+Antes de qualquer proposta técnica:
+- Leia todos os arquivos de ADR em `docs/` (arquivos com `ADR`, `adr`, `decisions`, `architecture-decision` no nome)
+- Liste as ADRs relevantes para esta feature
+- Entenda as restrições que impõem
+
+## 2. Examinar código-fonte
+
+Use as ferramentas disponíveis para:
+- Encontrar features similares já implementadas
+- Entender a estrutura de pastas e convenções do projeto
+- Identificar padrões (Repository, Service, Controller, etc.) usados atualmente
+- Verificar como dependências externas são utilizadas
+
+## 3. Construir architecture.md
+
+Estrutura obrigatória:
+
+```markdown
+# Architecture: [Nome da Feature]
+
+## Visão de Alto Nível
+[Estado atual do sistema → estado após a mudança]
+
+## Componentes Impactados
+[Lista de módulos, serviços, arquivos com suas relações e dependências]
+
+## Convenções Mantidas / Introduzidas
+[Padrões do projeto que serão seguidos — referenciar ADRs]
+
+## Dependências Externas
+[Libs, APIs, serviços externos necessários]
+
+## Principais Arquivos a Modificar/Criar
+[Lista com caminho completo e tipo de mudança]
+
+## Trade-offs e Alternativas
+[O que foi considerado e por que foi rejeitado — com referência a ADRs se aplicável]
+
+## Consequências
+[Efeitos colaterais, riscos, débito técnico introduzido]
+
+## Diagrama (Mermaid)
+[Opcional — adicionar quando agrega clareza real]
+
+## ADRs Aplicadas
+[Lista de cada ADR verificada:]
+- ADR-XXX: [título] → ✅ Respeitada (como?)
+- ADR-YYY: [título] → ✅ Respeitada (como?)
+- [Se há decisão que exige nova ADR:] → ➕ Nova ADR necessária: [descrever]
+```
+
+## 4. Verificação Cruzada (OBRIGATÓRIA)
+
+Compare `context.md` com `architecture.md`:
+
+| Item | Verificar |
+|------|-----------|
+| Problema principal | Descrito da mesma forma em ambos? |
+| Arquivos a modificar | Listas compatíveis? |
+| Abordagem técnica | Estratégia alinhada? |
+| Valores de negócio | Números, prazos, regras iguais? |
+| ADRs | Todas as relevantes foram consideradas? |
+
+**Ações:**
+- Inconsistências menores: corrija sem consultar o humano
+- Inconsistências de abordagem: alinhe aos padrões do projeto, informe o humano
+- Conflito com especificação de negócio: spec de negócio sempre vence — corrija os docs técnicos
+
+Adicione ao final de `architecture.md`:
+
+```markdown
+---
+
+## ✅ Verificação de Consistência
+
+**Data**: [YYYY-MM-DD]
+**Status**: ✅ APROVADO / ⚠️ CORRIGIDO
+
+### Checklist
+- [x] context.md e architecture.md consistentes
+- [x] Conforme especificação de negócio (se aplicável)
+- [x] ADRs verificadas e respeitadas
+- [x] Valores e regras de negócio conferidos
+
+### Correções Aplicadas
+[Descrever se houver]
+```
+
+## 5. Regra de decisões
+
+**Toda decisão técnica que não esteja explicitamente coberta pelo context.md aprovado ou pelas ADRs existentes DEVE ser apresentada como:**
+
+```
+[DECISÃO PENDENTE] {id}
+Contexto: {por que esta decisão é necessária}
+Opções:
+  A) {opção A} — {prós/contras}
+  B) {opção B} — {prós/contras}
+Recomendação: {opção recomendada e por quê}
+Aguardando aprovação para incluir na arquitetura.
+```
+
+**Nunca escolha unilateralmente. Pare e aguarde o humano.**
+
+**⛔ NÃO AVANCE. Aguarde o checkpoint de aprovação.**

package/.synapos/squad-templates/engineer/pipeline/steps/06-checkpoint-arquitetura.md

@@ -0,0 +1,27 @@
+---
+id: 06-checkpoint-arquitetura
+name: "Aprovação da Arquitetura"
+execution: checkpoint
+gate: GATE-ADR
+---
+
+# Aprovação da Arquitetura
+
+⏸ **CHECKPOINT — Revisão do architecture.md**
+
+O architecture.md foi gerado com Verificação de Consistência. Revise antes de prosseguir para o planejamento.
+
+Verifique especialmente:
+- A seção `## ✅ Verificação de Consistência` está marcada como APROVADO
+- Todas as ADRs relevantes foram listadas e respeitadas
+- Não há `[DECISÃO PENDENTE]` sem resposta no documento
+
+```
+O architecture.md está correto e pode seguir para planejamento?
+
+- ✅ Aprovar — prosseguir para Planejamento de Execução
+- ✏️ Ajustar arquitetura — voltar para Estruturação com feedback
+```
+
+> Se houver `[DECISÃO PENDENTE]` no architecture.md: resolva-os aqui antes de aprovar.
+> O GATE-ADR verifica automaticamente conformidade com ADRs antes de liberar este checkpoint.

package/.synapos/squad-templates/engineer/pipeline/steps/07-planejamento.md

@@ -0,0 +1,109 @@
+---
+id: 07-planejamento
+name: "Planejamento de Execução"
+agent: leo-engenheiro
+execution: subagent
+model_tier: powerful
+output_files:
+  - plan.md
+---
+
+# Planejamento de Execução
+
+## Contexto disponível
+Você recebe automaticamente:
+- `context.md` (aprovado)
+- `architecture.md` (aprovado com Verificação de Consistência)
+
+## 1. Inventário de Agents e Skills
+
+Antes de criar o plano, faça inventário do que está disponível no squad:
+
+```bash
+# Agents configurados no squad
+# (leia o squad.yaml e os .agent.md correspondentes)
+
+# Skills ativas
+# (leia .synapos/skills/*/SKILL.md se existirem)
+```
+
+Monte internamente:
+- `AGENTS_DISPONÍVEIS`: `{id} → {role} — {description}`
+- `SKILLS_DISPONÍVEIS`: `{nome} → {description}`
+
+## 2. Criar plan.md
+
+Divida a execução em fases onde **cada fase pode ser realizada em ~2 horas**.
+
+Regras:
+- Fase com backend + frontend juntos: separar em fases distintas, a menos que sejam trivialmente pequenas
+- Fases com dependências sequenciais: marcar com `→`
+- Fases que podem rodar em paralelo: marcar com `|`
+- Se `context.md` menciona "Frontend Integration" / Lovable: incluir fase de "Mock Removal"
+- Atribuir `Agent` e `Skill` a cada fase com base no inventário
+
+**Estrutura obrigatória do plan.md:**
+
+```markdown
+# Plan: [Nome da Feature]
+
+> Leia `context.md` e `architecture.md` antes de trabalhar em qualquer fase.
+> Atualize este arquivo ao concluir cada fase — marque tarefas e adicione comentários.
+
+## FASE 1: [Nome] [Não Iniciada ⏳]
+> Agents: [agentA | agentB] ou [agentA → agentB]
+> Skill: [nome] ou "nenhuma"
+> Estimativa: ~Xh
+
+[Descrição da fase]
+
+### Tarefa 1.1: [Nome] [Não Iniciada ⏳]
+[Detalhes — arquivos a criar/modificar, contratos, validações]
+
+### Tarefa 1.2: [Nome] [Não Iniciada ⏳]
+[Detalhes]
+
+### Comentários ADR:
+ADRs aplicáveis nesta fase:
+- ADR-XXX: [como se aplica]
+
+## FASE 2: [Nome] [Não Iniciada ⏳]
+> Agents: [...]
+> Skill: [...]
+> Estimativa: ~Xh
+> Depende de: FASE 1
+
+[...]
+
+## FASE N: Mock Removal — Frontend [Não Iniciada ⏳]
+(incluir apenas se Lovable/frontend estiver envolvido)
+> Agents: [rodrigo-react ou similar]
+> Skill: [nenhuma]
+> Depende de: FASE com os endpoints correspondentes
+
+### Mock #1: [Nome do componente] [Não Iniciada ⏳]
+
+**Pré-requisito backend:**
+- [ ] Endpoint [GET/POST/etc] /api/... criado e testado
+
+**Frontend:**
+- [ ] Remover mock em [arquivo:linha]
+- [ ] Substituir por hook/fetch real
+- [ ] Adicionar loading state
+- [ ] Adicionar error handling
+- [ ] Validar tipos TypeScript match
+```
+
+## 3. Verificar consistência com architecture.md
+
+Confirme que cada fase do plano está coberta pela arquitetura aprovada. Se encontrar lacuna:
+```
+[DECISÃO PENDENTE] plano-fase-X
+Contexto: architecture.md não cobre [aspecto específico]
+Opções:
+  A) Adicionar ao architecture.md antes de finalizar o plano
+  B) Tratar como decisão durante execução da fase
+Aguardando aprovação.
+```
+
+**⛔ NÃO AVANCE. Aguarde o checkpoint de aprovação do plano.**

package/.synapos/squad-templates/engineer/pipeline/steps/08-checkpoint-plano.md

@@ -0,0 +1,27 @@
+---
+id: 08-checkpoint-plano
+name: "Aprovação do Plano"
+execution: checkpoint
+---
+
+# Aprovação do Plano
+
+⏸ **CHECKPOINT — Revisão do plan.md**
+
+O plan.md foi gerado com fases divididas em ~2h, agents/skills atribuídos e dependências mapeadas.
+
+Verifique:
+- As fases fazem sentido na sequência proposta
+- As estimativas de 2h por fase são realistas para o seu contexto
+- Os agents atribuídos são os corretos para cada fase
+- Se há frontend Lovable: a fase de Mock Removal está presente
+
+```
+O plan.md está aprovado para iniciar a execução?
+
+- ✅ Aprovar — iniciar execução fase a fase
+- ✏️ Ajustar plano — voltar para Planejamento com feedback
+```
+
+> Após aprovação, a execução ocorre fase a fase com pausa e validação ao final de cada fase.
+> Você poderá validar o código antes de autorizar o avanço para a próxima fase.

package/.synapos/squad-templates/engineer/pipeline/steps/09-execucao.md

@@ -0,0 +1,121 @@
+---
+id: 09-execucao
+name: "Execução por Fases"
+agent: leo-engenheiro
+execution: inline
+model_tier: powerful
+gate: GATE-5
+---
+
+# Execução por Fases
+
+## Contexto disponível
+Você recebe automaticamente:
+- `context.md` (aprovado)
+- `architecture.md` (aprovado)
+- `plan.md` (aprovado)
+
+**Leia os três arquivos antes de qualquer ação.**
+
+## 1. Identificar fase atual
+
+Leia `plan.md` e identifique:
+- Qual fase está marcada como `[Em Progresso ⏰]`
+- Se nenhuma, qual é a primeira `[Não Iniciada ⏳]`
+
+Apresente ao humano:
+
+```
+Fase atual: FASE X — [Nome]
+Agents: [atribuídos]
+Skill: [atribuída]
+Estimativa: ~Xh
+
+Tarefas desta fase:
+1. [Tarefa 1.1]
+2. [Tarefa 1.2]
+
+ADRs aplicáveis:
+- ADR-XXX: [como se aplica]
+
+Como abordar:
+[Plano detalhado para esta fase específica]
+
+Pronto para iniciar?
+- ✅ Iniciar fase
+- ✏️ Ajustar abordagem antes de iniciar
+```
+
+## 2. Implementação Guiada por ADRs (Abordagem Proativa)
+
+**Antes de escrever qualquer código na fase:**
+
+1. Releia as ADRs aplicáveis da fase em `context.md` → seção "Regras Críticas"
+2. Planeje a implementação explicitamente:
+
+```
+Fase X — Plano de implementação ADR-guiado:
+
+ADRs aplicáveis:
+- ADR-007: [regra] → Ação: [o que fazer]
+- ADR-003: [regra] → Ação: [o que fazer]
+
+Ordem de criação:
+1. [arquivo/componente que é pré-requisito]
+2. [arquivo/componente que depende do anterior]
+3. [...]
+
+Resultado esperado: Código conforme ADRs desde o início.
+```
+
+3. Execute na ordem planejada
+
+## 3. Durante a implementação
+
+- Use sub-agentes de construção quando disponíveis para preservar contexto
+- Toda decisão fora do escopo do plan.md aprovado → `[DECISÃO PENDENTE]` obrigatório
+- Nenhuma biblioteca, padrão ou estrutura nova sem `[DECISÃO PENDENTE]` resolvido
+
+## 4. Ao concluir cada fase
+
+**Pause. Não avance para a próxima fase sem aprovação explícita.**
+
+Apresente ao humano:
+```
+✅ FASE X concluída — [Nome]
+
+Arquivos criados/modificados:
+  [lista]
+
+Conformidade ADR:
+  - ADR-XXX: ✅ Respeitada — [como]
+  - ADR-YYY: ✅ Respeitada — [como]
+
+Valide o código. Posso avançar para FASE X+1?
+
+- ✅ Aprovar e avançar para FASE X+1
+- ✏️ Ajustar — [informe o que corrigir]
+```
+
+## 5. Atualizar plan.md ao concluir cada fase
+
+Marque a fase como `[Completada ✅]` e adicione à seção `### Comentários`:
+
+```markdown
+### Comentários:
+#### Conformidade com ADRs (Abordagem Proativa)
+- ✅ ADRs consultadas ANTES da implementação
+- ✅ Código criado seguindo regras desde o início
+- Regras aplicadas: ADR-XXX → [como], ADR-YYY → [como]
+
+#### Decisões tomadas durante a fase
+[Listar qualquer [DECISÃO PENDENTE] que foi resolvido e como]
+```
+
+## 6. Atualizar Linear (se configurado)
+
+Se `task_tracker` em `preferences.md` é `linear`:
+- Ao **iniciar** fase: mover card para "In Progress"
+- Ao **concluir** fase: adicionar comentário com resumo
+- Ao **abrir PR**: mover para "In Review" + link do PR
+- Ao **concluir tudo**: mover para "Done"

package/.synapos/squad-templates/engineer/pipeline/steps/atualizar-tarefa.md

@@ -0,0 +1,27 @@
+---
+id: atualizar-tarefa
+name: "Atualizar Tarefa no Linear"
+execution: checkpoint
+---
+
+# Atualizar Tarefa
+
+Se `task_tracker` em `docs/_memory/preferences.md` é `linear`:
+
+Mova o card para "Done" e adicione comentário final:
+
+```markdown
+✅ **Feature entregue**
+
+Fases concluídas:
+[Listar fases do plan.md]
+
+Documentos gerados:
+- context.md
+- architecture.md
+- plan.md
+
+PR: [link se disponível]
+```
+
+Se `task_tracker: none` → este step é ignorado automaticamente.