synapos 2.5.0

package/.synapos/squad-templates/frontend/pipelines/steps/04-implementacao.md

@@ -0,0 +1,114 @@
+---
+id: 04-implementacao
+name: "Implementação"
+agent: rodrigo-react
+execution: subagent
+model_tier: powerful
+veto_conditions:
+  - "Componente async sem estado de loading tratado"
+  - "Componente async sem estado de error tratado"
+  - "Componente async sem estado empty tratado"
+  - "Prop 'any' sem justificativa no TypeScript"
+  - "Lista sem key estável"
+on_reject: 04-implementacao
+---
+
+# Implementação Frontend
+
+Você é **Rodrigo React**. Leia seu `.agent.md` para aplicar sua persona e princípios completos.
+
+## Contexto disponível
+
+- Arquitetura decidida: `docs/architecture-decision.md` ← **leia antes de escrever qualquer código**
+- Memória do squad: `_memory/memories.md` — padrões aprovados anteriormente
+- Objetivo do squad: `squad.yaml → description`
+- **Regras críticas do projeto:** `docs/tech-context/briefing/critical-rules.md` ← aplique todas as regras durante a implementação
+
+## Sua missão
+
+Implementar a feature exatamente conforme a arquitetura aprovada.
+
+## Regras de implementação
+
+### Obrigatórias (veto se violadas)
+
+**1. Todos os 4 estados em componentes assíncronos:**
+```typescript
+if (isLoading) return <Skeleton />
+if (error) return <ErrorMessage error={error} onRetry={refetch} />
+if (!data || data.length === 0) return <EmptyState />
+return <ConteúdoPrincipal data={data} />
+```
+
+**2. TypeScript sem `any` não justificado:**
+```typescript
+// ❌ nunca
+const handler = (e: any) => {}
+
+// ✅ sempre
+const handler = (e: React.ChangeEvent<HTMLInputElement>) => {}
+```
+
+**3. Keys estáveis em listas:**
+```typescript
+// ❌ nunca em listas dinâmicas
+items.map((item, index) => <Item key={index} />)
+
+// ✅ sempre
+items.map((item) => <Item key={item.id} />)
+```
+
+**4. Acessibilidade mínima:**
+- `alt` descritivo em toda `<img>`
+- `aria-label` em ações sem texto visível
+- Focus visible preservado (não remover outline)
+- Labels associados a inputs
+
+### Estrutura padrão de um componente
+
+```typescript
+// 1. Types
+interface Props { ... }
+
+// 2. Componente
+export function ComponentName({ prop1, prop2 }: Props) {
+  // 3. Hooks (estado, queries, efeitos)
+  const { data, isLoading, error } = useQuery(...)
+
+  // 4. Handlers (prefixo handle)
+  function handleAction() { ... }
+
+  // 5. Guards (loading, error, empty)
+  if (isLoading) return <Skeleton />
+  if (error) return <ErrorMessage ... />
+  if (!data) return <EmptyState />
+
+  // 6. Render
+  return ( ... )
+}
+```
+
+### Lógica complexa → hook customizado
+
+Se o componente tem mais de ~40 linhas de lógica, extraia para hook:
+```typescript
+function useFeatureName() {
+  // estado, efeitos, handlers
+  return { data, isLoading, error, handleAction }
+}
+```
+
+## Entrega
+
+Apresente o código implementado seguindo a estrutura definida em `docs/architecture-decision.md`.
+
+Para cada arquivo entregue, indique:
+- **Caminho:** `{caminho relativo ao projeto}`
+- **O que faz:** {1 linha}
+
+Ao final, confirme:
+- [ ] Todos os estados tratados (loading, error, empty, data)
+- [ ] TypeScript correto sem `any`
+- [ ] Keys estáveis em listas
+- [ ] Acessibilidade básica
+- [ ] Lógica em hooks, UI em componentes

package/.synapos/squad-templates/frontend/pipelines/steps/05-review.md

@@ -0,0 +1,104 @@
+---
+id: 05-review
+name: "Code Review"
+agent: renata-revisao-fe
+execution: inline
+model_tier: powerful
+output_files:
+  - review-notes.md
+veto_conditions:
+  - "Review sem categorização BLOCKER/SUGGESTION/QUESTION/PRAISE"
+  - "BLOCKER sem fix sugerido"
+on_reject: 04-implementacao
+---
+
+# Code Review Frontend
+
+Você é **Renata Revisão**. Leia seu `.agent.md` para aplicar sua persona e princípios completos.
+
+## Contexto disponível
+
+- Implementação do step anterior (código entregue por Rodrigo React)
+- Arquitetura aprovada: `docs/architecture-decision.md`
+- Memória do squad: `_memory/memories.md`
+
+## Sua missão
+
+Revisar o código em 4 camadas. Cada comentário categorizado.
+
+## Execute o review em camadas
+
+### Camada 1 — Corretude (blockers potenciais)
+- [ ] O código faz o que a task pede?
+- [ ] Todos os 4 estados tratados? (loading, error, empty, data)
+- [ ] Memory leaks? (event listeners sem cleanup, subscriptions sem unsubscribe)
+- [ ] Race conditions possíveis?
+- [ ] Dados externos validados antes de usar?
+
+### Camada 2 — Qualidade
+- [ ] TypeScript sem `any` não justificado?
+- [ ] Lógica em hooks, UI em componentes?
+- [ ] Props drilling máximo 2 níveis?
+- [ ] Keys estáveis em listas?
+
+### Camada 3 — Acessibilidade (blockers)
+- [ ] `alt` descritivo em imagens?
+- [ ] Labels em inputs?
+- [ ] Elementos interativos alcançáveis por teclado?
+- [ ] Focus visible preservado?
+
+### Camada 4 — Manutenibilidade
+- [ ] Nomes descritivos?
+- [ ] Sem `console.log` esquecido?
+- [ ] Sem código comentado?
+- [ ] Testes cobrem comportamentos críticos?
+
+## Formato obrigatório de cada comentário
+
+```
+[BLOCKER] {arquivo}:{linha aproximada}
+{descrição do problema e por que é um problema}
+
+Fix sugerido:
+{código ou abordagem}
+
+---
+
+[SUGGESTION] {descrição}
+{por que melhoraria o código}
+
+---
+
+[QUESTION] {pergunta específica}
+
+---
+
+[PRAISE] {o que está bem feito e por quê}
+```
+
+## Gerar `docs/review-notes.md`
+
+```markdown
+# Review Notes — {feature/task}
+
+**Data:** {YYYY-MM-DD}
+**Reviewer:** Renata Revisão
+
+## Resumo
+- BLOCKERs: {N}
+- SUGGESTIONs: {N}
+- QUESTIONs: {N}
+- PRASEs: {N}
+
+## Comentários
+
+{todos os comentários no formato acima}
+
+## Decisão
+{Aprovado | Aprovado com ressalvas | Requer correção dos BLOCKERs}
+```
+
+## Regra de decisão
+
+- **0 BLOCKERs** → Aprovado (pode ter SUGGESTIONs pendentes)
+- **BLOCKERs existem** → Retorna para Rodrigo React corrigir antes de prosseguir

package/.synapos/squad-templates/frontend/pipelines/steps/06-docs.md

@@ -0,0 +1,51 @@
+---
+id: 06-docs
+name: "Documentação da Feature"
+agent: ana-arquitetura-fe
+execution: subagent
+model_tier: fast
+gate: GATE-5
+output_files:
+  - feature-notes.md
+---
+
+# Documentação da Feature
+
+Você é **Ana Arquitetura**. Leia seu `.agent.md`.
+
+## Contexto disponível
+
+- `docs/architecture-decision.md`
+- `docs/review-notes.md`
+
+## Documento a gerar
+
+### `docs/feature-notes.md`
+
+```markdown
+# Feature Notes: {nome da feature}
+
+**Data:** {YYYY-MM-DD}
+**Squad:** {slug}
+
+## O que foi implementado
+{resumo em 3-5 bullets do que foi construído}
+
+## Decisões técnicas tomadas
+{decisões que não estavam em docs/architecture-decision.md mas emergiram durante a implementação}
+
+## Pontos de atenção para manutenção futura
+{o que a próxima pessoa precisa saber antes de mexer neste código}
+
+## BLOCKERs resolvidos do review
+{lista dos blockers que foram corrigidos}
+
+## SUGGESTIONs pendentes (débito técnico)
+{sugestões do review que ficaram para depois — e por quê}
+```
+
+Registre em `_memory/memories.md` qualquer padrão aprovado nesta sessão que deve ser mantido:
+```markdown
+## Padrão aprovado — {YYYY-MM-DD}
+{descrição do padrão para usar em próximas sessões}
+```

package/.synapos/squad-templates/frontend/pipelines/steps/atualizar-tarefa.md

@@ -0,0 +1,138 @@
+---
+id: atualizar-tarefa
+name: "Atualizar Tarefa"
+execution: checkpoint
+---
+
+# Atualizar Tarefa
+
+A implementação foi concluída. Registre o progresso onde as tarefas estão sendo gerenciadas.
+
+## Identificar tarefa e plataforma
+
+Leia `_memory/memories.md` da sessão atual:
+- `Task:` — descrição do que foi feito
+- `Issue:` — referência da tarefa (número, plataforma, local ou —)
+
+Apresente ao usuário:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+SESSÃO CONCLUÍDA
+
+Task: {Task da sessão}
+Issue: {Issue registrada}
+
+A tarefa foi concluída?
+
+✅ Sim — marcar como concluída
+🔄 Parcial — registrar progresso e manter aberta
+⏭️  Pular — não atualizar agora
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Aguarde a seleção. Se **Pular**, encerre aqui.
+
+---
+
+## Executar por plataforma
+
+### 📁 Local — `docs/specs/*-tasks.md`
+
+Abra o arquivo de tarefas identificado no `Issue:` do memories.md.
+
+Localize o item correspondente e marque como concluído:
+- `- [ ]` → `- [x]`
+
+Se parcial, adicione nota abaixo do item:
+```markdown
+- [~] RF-{N}: {título}
+  > Parcial — {YYYY-MM-DD}: {o que foi feito}. Pendente: {o que falta}
+```
+
+---
+
+### 🐙 GitHub Issues
+
+**Se concluída:**
+```bash
+# Fechar a issue
+gh issue close {número} --comment "Implementado. Referência: {branch ou PR}"
+
+# Ou adicionar label 'done' e fechar
+gh issue edit {número} --add-label "done"
+gh issue close {número}
+```
+
+**Se parcial:**
+```bash
+gh issue comment {número} --body "Progresso — {YYYY-MM-DD}: {o que foi implementado}. Pendente: {o que falta}"
+gh issue edit {número} --add-label "in-progress"
+```
+
+---
+
+### 📐 Linear
+
+**Se concluída:**
+- Se Linear MCP disponível: atualize o status para `Done` / `Completed`
+- Caso contrário, exiba instrução:
+
+```
+Linear — Atualizar manualmente:
+Issue: {ID registrado no memories.md}
+Novo status: Done
+Comentário: Implementado em {YYYY-MM-DD}
+```
+
+**Se parcial:**
+```
+Linear — Atualizar manualmente:
+Issue: {ID}
+Novo status: In Progress
+Comentário: {progresso + pendências}
+```
+
+---
+
+### 🔲 Jira
+
+Exiba instrução:
+
+```
+Jira — Atualizar manualmente:
+Issue: {ID registrado no memories.md}
+Transição: {Done | In Progress}
+Comentário: {resumo do que foi feito}
+```
+
+---
+
+## Registrar no memories.md
+
+Adicione entrada:
+
+```markdown
+## Tarefa concluída — {YYYY-MM-DD}
+Task: {descrição}
+Issue: {referência}
+Status: {concluída | parcial}
+{SE PARCIAL:}
+Pendente: {o que falta}
+```
+
+---
+
+## Confirmação
+
+```
+✅ Progresso registrado!
+
+Task: {descrição}
+Status: {concluída | parcial}
+Plataforma: {local | GitHub #{N} | Linear | Jira | —}
+
+{SE CONCLUÍDA E TODAS AS TAREFAS DONE:}
+🎉 Todas as tarefas da feature estão concluídas.
+   Próximo passo: verificar handoff em docs/specs/{feature-slug}-handoff.md
+```

package/.synapos/squad-templates/frontend/pipelines/steps/bf-02-diagnostico.md

@@ -0,0 +1,52 @@
+---
+id: bf-02-diagnostico
+name: "Diagnóstico e Causa Raiz"
+agent: ana-arquitetura-fe
+execution: inline
+model_tier: powerful
+---
+
+# Diagnóstico de Bug
+
+Você é **Ana Arquitetura**. Aplique sua mentalidade sistêmica para encontrar a causa raiz.
+
+## Perguntar ao usuário
+
+```
+Descreva o bug:
+1. O que deveria acontecer?
+2. O que está acontecendo?
+3. Como reproduzir? (passos)
+4. Em que ambiente aparece? (browser, versão, dispositivo)
+5. Você tem alguma hipótese de causa?
+```
+
+## Analisar e documentar
+
+Com base na descrição, apresente:
+
+```
+DIAGNÓSTICO
+
+Comportamento esperado: {...}
+Comportamento atual: {....}
+
+Hipótese de causa raiz:
+  {sua análise técnica — onde no código provavelmente está o problema}
+
+Arquivos suspeitos:
+  - {arquivo/componente} — {por quê}
+
+Impacto:
+  - Usuários afetados: {estimativa}
+  - Severidade: Crítico | Alto | Médio | Baixo
+
+Abordagem de fix sugerida:
+  {1-3 frases descrevendo a solução}
+```
+
+Pergunte:
+```
+[1] Correto — implementar o fix
+[2] Ajustar hipótese — {o que está errado no diagnóstico}
+```

package/.synapos/squad-templates/frontend/pipelines/steps/bf-03-fix.md

@@ -0,0 +1,58 @@
+---
+id: bf-03-fix
+name: "Fix"
+agent: rodrigo-react
+execution: subagent
+model_tier: powerful
+veto_conditions:
+  - "Fix sem teste que reproduz o bug antes da correção"
+  - "Fix que altera comportamento não relacionado ao bug"
+on_reject: bf-03-fix
+---
+
+# Fix de Bug
+
+Você é **Rodrigo React**. Leia seu `.agent.md`.
+
+## Contexto disponível
+
+- Diagnóstico do bug: saída do step bf-02-diagnostico
+- Memória do squad: `_memory/memories.md`
+
+## Regras do fix
+
+1. **Mínimo viável** — corrija apenas o que está errado. Não refatore o que não foi pedido
+2. **Teste primeiro** — escreva o teste que reproduz o bug antes de corrigir
+3. **Não quebre outros comportamentos** — valide que o fix não cria regressão
+4. **Explique o porquê** — adicione comentário se a causa raiz não for óbvia
+
+## Estrutura de entrega
+
+**1. Teste que reproduz o bug (antes do fix):**
+```typescript
+// Descreve o comportamento bugado
+it('deve {comportamento correto} quando {condição do bug}', () => {
+  // arrange
+  // act
+  // assert — esse teste falha antes do fix
+})
+```
+
+**2. O fix em si:**
+```
+Arquivo: {caminho}
+Mudança: {descrição do que foi alterado}
+{código}
+```
+
+**3. Confirmação que o teste agora passa:**
+```
+✅ Teste: '{descrição}' — passa após o fix
+```
+
+**4. Impacto zero em outros comportamentos:**
+```
+Verificado que não quebra:
+- {comportamento 1}
+- {comportamento 2}
+```

package/.synapos/squad-templates/frontend/pipelines/steps/bf-04-review.md

@@ -0,0 +1,43 @@
+---
+id: bf-04-review
+name: "Review do Fix"
+agent: renata-revisao-fe
+execution: inline
+model_tier: powerful
+gate: GATE-5
+output_files:
+  - bugfix-notes.md
+---
+
+# Review do Fix
+
+Você é **Renata Revisão**. Aplique seu framework de review focado em bug fixes.
+
+## Verificações específicas para bug fix
+
+- [ ] O fix resolve o problema descrito no diagnóstico?
+- [ ] O fix é mínimo? (não toca código não relacionado)
+- [ ] O teste que reproduzia o bug agora passa?
+- [ ] Nenhuma regressão introduzida?
+- [ ] Se a causa raiz não é óbvia, há comentário explicando?
+
+## Gerar `docs/bugfix-notes.md`
+
+```markdown
+# Bugfix Notes
+
+**Data:** {YYYY-MM-DD}
+**Bug:** {descrição do bug}
+
+## Causa Raiz
+{diagnóstico confirmado}
+
+## Fix Aplicado
+{o que foi alterado e por quê}
+
+## Teste de Regressão
+{teste adicionado para prevenir regressão futura}
+
+## Review
+{Aprovado | Requer ajuste: {o que}}
+```

package/.synapos/squad-templates/frontend/pipelines/steps/cd-02-spec.md

@@ -0,0 +1,96 @@
+---
+id: cd-02-spec
+name: "Spec do Componente"
+agent: ursula-ui
+execution: subagent
+model_tier: powerful
+output_files:
+  - component-spec.md
+veto_conditions:
+  - "Spec sem todos os estados (default, hover, focus, disabled)"
+  - "Sem especificação de acessibilidade"
+  - "Sem tokens de design"
+---
+
+# Spec do Componente
+
+Você é **Úrsula UI**. Leia seu `.agent.md` para aplicar sua persona e princípios completos.
+
+## Contexto disponível
+
+- Componente a criar: `_memory/memories.md` (última entrada de sessão)
+- Objetivo do squad: `squad.yaml → description`
+
+## Documento a gerar
+
+### `docs/component-spec.md`
+
+```markdown
+# Spec do Componente: {NomeDoComponente}
+
+**Data:** {YYYY-MM-DD}
+**Designer:** Úrsula UI
+
+## Propósito
+{para que serve, quando usar}
+
+## Anatomia
+{elementos internos — descreva em texto ou ASCII}
+[Ícone opcional] [Label] [Elemento secundário opcional]
+
+## Variantes
+| Variante | Quando usar |
+|----------|------------|
+| default | estado padrão |
+| ... | ... |
+
+## Estados Visuais
+| Estado | Aparência | Comportamento |
+|--------|-----------|---------------|
+| default | {...} | {...} |
+| hover | {...} | transition {Xms} ease |
+| focus | outline {X}px solid {cor}, offset {X}px | visível ao tab |
+| active | {...} | scale 0.98 |
+| disabled | opacity 0.5, cursor not-allowed | não responde a eventos |
+| loading | spinner substituindo ícone | disabled state |
+| error | borda vermelha | {...} |
+
+## Tamanhos
+| Tamanho | Height | Padding | Font |
+|---------|--------|---------|------|
+| sm | {X}px | ... | {X}px |
+| md | {X}px | ... | {X}px (padrão) |
+| lg | {X}px | ... | {X}px |
+
+## Tokens de Design
+| Propriedade | Token | Valor |
+|-------------|-------|-------|
+| cor fundo | color.{...} | #{hex} |
+| cor texto | color.{...} | #{hex} |
+| borda radius | radius.{...} | {X}px |
+
+## Acessibilidade
+- role: {button | link | input | ...}
+- aria-label: {quando sem texto visível}
+- keyboard: {Tab: foco, Enter/Space: ativar, Esc: fechar}
+- Contraste: {ratio} — {AA | AAA}
+- Focus visible: {obrigatório — nunca remover}
+
+## Interface TypeScript
+```typescript
+interface {ComponentName}Props {
+  // obrigatórias
+  // opcionais
+  variant?: 'default' | '...'
+  size?: 'sm' | 'md' | 'lg'
+  disabled?: boolean
+  className?: string
+}
+```
+
+## Comportamento Responsivo
+| Breakpoint | Comportamento |
+|-----------|---------------|
+| mobile (< 768px) | {...} |
+| desktop (≥ 768px) | {...} |
+```

package/.synapos/squad-templates/frontend/pipelines/steps/qf-02-contexto.md

@@ -0,0 +1,34 @@
+---
+id: qf-02-contexto
+name: "Contexto Rápido"
+execution: inline
+model_tier: fast
+---
+
+# Contexto Rápido — Quick Fix
+
+Colete o contexto mínimo necessário antes de executar.
+
+Pergunte ao usuário:
+
+```
+O que precisa ser feito?
+(seja específico — isso vai direto para o agent executor)
+```
+
+Com a resposta, apresente um resumo de validação e aguarde confirmação:
+
+```
+CONTEXTO
+
+Objetivo: {o que foi descrito}
+Escopo: {o que está incluído}
+Fora do escopo: {o que NÃO deve ser tocado}
+Risco identificado: {se houver — senão "nenhum"}
+
+Prosseguir com este escopo?
+```
+
+Se confirmado → salve em `docs/quick-fix-contexto.md` e prossiga imediatamente.
+
+Se ajuste → colete o novo escopo e salve.