synapos 2.5.0

package/.synapos/core/pipelines/pre-execution.yaml

@@ -0,0 +1,107 @@
+name: "Pré-Execução: Investigação + Arquitetura + Planejamento"
+description: "Pipeline universal de preparação. Roda antes de qualquer pipeline principal de qualquer squad. Gera context.md, architecture.md e plan.md que são injetados automaticamente na execução principal."
+version: "1.0.0"
+
+# agent_override: quando definido em squad.yaml como pre_pipeline.agent,
+# sobrescreve {lead_agent} para usar o agente do squad em vez de leo-engenheiro.
+# Se não definido, o runner usa leo-engenheiro se disponível, senão usa o primeiro agent base do squad.
+agent_override: "{lead_agent}"
+
+# Arquivos salvos em: docs/.squads/sessions/{feature-slug}/
+session_files:
+  context: context.md
+  architecture: architecture.md
+  plan: plan.md
+
+steps:
+  - id: pre-01-gate
+    name: "Verificação de Integridade"
+    execution: checkpoint
+    gate: GATE-0
+    file: ../../squad-templates/engineer/pipeline/steps/01-gate.md
+
+  - id: pre-02-preparacao
+    name: "Preparação"
+    agent: "{lead_agent}"
+    execution: inline
+    model_tier: fast
+    file: ../../squad-templates/engineer/pipeline/steps/02-preparacao.md
+    depends_on: [pre-01-gate]
+
+  - id: pre-03-investigacao
+    name: "Investigação"
+    agent: "{lead_agent}"
+    execution: inline
+    model_tier: powerful
+    file: ../../squad-templates/engineer/pipeline/steps/03-investigacao.md
+    depends_on: [pre-02-preparacao]
+    output_files:
+      - context.md
+    veto_conditions:
+      - "context.md sem seção de Motivação preenchida"
+      - "context.md sem Meta mensurável"
+      - "context.md sem seção de ADRs Relevantes"
+
+  - id: pre-04-checkpoint-contexto
+    name: "Aprovação do Contexto"
+    execution: checkpoint
+    gate: GATE-2
+    file: ../../squad-templates/engineer/pipeline/steps/04-checkpoint-contexto.md
+    depends_on: [pre-03-investigacao]
+
+  - id: pre-05-arquitetura
+    name: "Estruturação Arquitetural"
+    agent: "{lead_agent}"
+    execution: subagent
+    model_tier: powerful
+    file: ../../squad-templates/engineer/pipeline/steps/05-arquitetura.md
+    depends_on: [pre-04-checkpoint-contexto]
+    output_files:
+      - architecture.md
+    veto_conditions:
+      - "architecture.md sem seção de Verificação de Consistência"
+      - "architecture.md sem lista de ADRs Aplicadas"
+      - "architecture.md sem lista de arquivos a modificar/criar"
+
+  - id: pre-05b-visual-spec
+    name: "Especificação Visual (condicional)"
+    agent: "{lead_agent}"
+    execution: inline
+    model_tier: powerful
+    file: ../../squad-templates/engineer/pipeline/steps/visual-spec.md
+    depends_on: [pre-05-arquitetura]
+    output_files:
+      - visual-spec.md
+    veto_conditions:
+      - "visual-spec.md sem seção de Verificação GATE-DESIGN"
+      - "Componente interativo sem estado focus ou error"
+      - "Contraste não declarado para nenhum componente com texto"
+    skip_condition: "Nenhum agent do squad tem tasks de design-system, component-spec ou ux-review"
+
+  - id: pre-06-checkpoint-arquitetura
+    name: "Aprovação da Arquitetura"
+    execution: checkpoint
+    gate: GATE-ADR
+    # GATE-DESIGN também é verificado neste checkpoint quando visual-spec.md foi gerado
+    file: ../../squad-templates/engineer/pipeline/steps/06-checkpoint-arquitetura.md
+    depends_on: [pre-05b-visual-spec]
+
+  - id: pre-07-planejamento
+    name: "Planejamento de Execução"
+    agent: "{lead_agent}"
+    execution: subagent
+    model_tier: powerful
+    file: ../../squad-templates/engineer/pipeline/steps/07-planejamento.md
+    depends_on: [pre-06-checkpoint-arquitetura]
+    output_files:
+      - plan.md
+    veto_conditions:
+      - "plan.md sem agents/skills atribuídos por fase"
+      - "Alguma fase excede estimativa de 2h sem justificativa"
+      - "plan.md sem referência a context.md e architecture.md"
+
+  - id: pre-08-checkpoint-plano
+    name: "Aprovação do Plano"
+    execution: checkpoint
+    file: ../../squad-templates/engineer/pipeline/steps/08-checkpoint-plano.md
+    depends_on: [pre-07-planejamento]

package/.synapos/core/rules/product-agent.mdc

@@ -0,0 +1,59 @@
+---
+description: Master Prompt - Assistente de Gestão de Projetos AI AI Frontiers
+globs:
+alwaysApply: true
+---
+
+# Assistente de PM
+
+## Identidade Profissional
+Você é um assistente AI híbrido que combina três funções críticas:
+- **Product Owner**: Define e prioriza features com foco no valor do cliente
+- **Delivery Manager**: Garante entregas no prazo e gestão eficiente do projeto
+- **Solution Architect**: Especifica soluções técnicas e arquitetura de implementação
+
+## Traços Fundamentais
+- **Lógico e Analítico**: Sempre baseie recomendações em dados e evidências concretas
+- **Direto e Conciso**: Vá direto ao ponto sem rodeios ou explicações desnecessárias
+- **Desafiador Construtivo**: Questione assumptions e proponha alternativas quando identificar pontos fracos
+- **Independente**: Tome iniciativa de propor soluções completas sem precisar de micro-direcionamento
+- **Estratégico**: Sempre considere impactos de longo prazo, não apenas soluções imediatas
+
+## Estilo de Comunicação
+- **Sem fluff**: Elimine pleasantries desnecessários e vá direto ao valor
+- **Estruturado**: Use bullets, numeração e hierarquia clara de informações
+- **Evidence-based**: Sempre explique o "porquê" com lógica sólida
+- **Honest feedback**: Se algo não faz sentido ou tem riscos, diga claramente
+- **Proativo**: Antecipe próximos passos e possíveis problemas
+
+## Responsabilidades Primárias
+1. **Gestão de Projetos**
+   - Manter iniciativas, tarefas e deadlines organizados no Linear
+   - Monitorar progresso e identificar bloqueios
+   - Alertar sobre prazos críticos e riscos
+
+2. **Especificação Técnica**
+   - Detalhar funcionalidades com clareza total
+   - Analisar código existente e propor arquiteturas
+   - Mapear componentes afetados e pontos de teste
+   - Sugerir bibliotecas priorizando stack conhecido
+
+## Framework de Análise de Impacto
+1. **ESCOPO**: O que muda / O que não muda
+2. **COMPONENTES AFETADOS**: Diretos / Indiretos
+3. **RISCOS**: Técnicos / De negócio / De prazo
+4. **MITIGAÇÃO**: Ações preventivas / Plano B
+
+## Metodologia AI Frontiers
+1. **Diagnóstico (Inception)**: Descobrir talentos e oportunidades de valor com AI
+2. **Experimentação**: Pesquisar e testar diferentes soluções
+3. **Prototipagem**: Criar protótipos funcionais que confirmam entrega de valor
+4. **Wrap-up**: Preparação para handoff com documentação, treinamento e deployment
+
+## Ferramentas
+- **Linear**: Projects (Clientes) → Milestones → Issues (Team: AI Frontiers)
+- **GitHub**: Branches por feature + Pull requests + Reviews
+- **Master Docs**: Documentos "DNA" do projeto para validação
+
+## Princípio Fundamental
+**SEMPRE levante a mão quando algo não estiver claro.** Confirme sempre seu entendimento antes de prosseguir.

package/.synapos/core/skills-engine.md

@@ -0,0 +1,207 @@
+---
+name: synapos-skills-engine
+version: 1.1.0
+description: Engine de gerenciamento de skills — MCP, scripts e instruções de comportamento
+---
+
+# SYNAPOS SKILLS ENGINE v1.0.0
+
+> Skills são capacidades adicionais injetadas nos agents durante execução de pipelines.
+> Tipos: MCP (servidor de ferramentas), script (Node/Python/Bash), prompt (instruções).
+
+---
+
+## ESTRUTURA DE UMA SKILL
+
+Toda skill vive em `.synapos/skills/{skill-name}/` com um arquivo `SKILL.md`:
+
+```markdown
+---
+name: skill-name
+displayName: "Nome da Skill"
+version: "1.0.0"
+type: mcp | script | hybrid | prompt
+description: "O que esta skill faz"
+categories: [search, browser, database, file, communication, ...]
+---
+
+## O Que Faz
+{descrição do que a skill habilita}
+
+## Instalação
+{passos para instalar/configurar}
+
+## Configuração MCP (se type: mcp)
+{configuração para settings.json / mcp.json do IDE}
+
+## Variáveis de Ambiente (se necessário)
+{lista de env vars necessárias}
+
+## Instruções para o Agent
+{instruções de comportamento adicionadas ao contexto do agent quando esta skill está ativa}
+```
+
+---
+
+## TIPOS DE SKILL
+
+### `mcp` — Model Context Protocol Server
+Adiciona ferramentas via protocolo MCP (compatível com Claude, Cursor, etc.)
+
+Exemplo:
+```yaml
+type: mcp
+mcp_config:
+  command: npx
+  args: [-y, "@modelcontextprotocol/server-brave-search"]
+  env:
+    BRAVE_API_KEY: ${BRAVE_API_KEY}
+```
+
+### `script` — Script executável
+Executa via ferramenta Bash do agente.
+
+Exemplo:
+```yaml
+type: script
+script:
+  runtime: node | python | bash
+  file: scripts/run.js
+  args: []
+```
+
+### `prompt` — Instruções de comportamento
+Adiciona instruções ao contexto do agent (sem ferramentas externas).
+
+Exemplo: instruções de formatação, tom de voz, padrões de output.
+
+### `hybrid` — MCP + Script
+Combina servidor MCP com scripts auxiliares.
+
+---
+
+## RESOLUÇÃO DE SKILLS (antes de executar pipeline)
+
+O pipeline-runner executa este protocolo antes de cada pipeline:
+
+### 1. Ler skills do squad.yaml
+```yaml
+# Em squad.yaml
+skills:
+  - brave-search
+  - playwright-browser
+```
+
+### 2. Para cada skill listada:
+- Verificar se `.synapos/skills/{skill}/SKILL.md` existe — diretório real **ou symlink**
+- Se não existe → apresentar opções:
+  ```
+  ⚠ Skill '{skill}' não está instalada.
+  [1] Instalar agora
+  [2] Pular (o agent funcionará sem esta skill)
+  [3] Cancelar execução
+  ```
+
+### 3. Para skills do tipo `mcp`:
+- Verificar se está configurada no IDE (settings.json / mcp.json)
+- Se não → mostrar instrução de configuração
+
+### 4. Para skills do tipo `script`:
+- Verificar se runtime está disponível (node, python, bash)
+- Verificar dependências (package.json, requirements.txt)
+
+---
+
+## INJEÇÃO DE SKILLS NOS AGENTS
+
+Quando um step tem skills, o pipeline-runner injeta no contexto do agent:
+
+```
+[Agent Persona]
+[Contexto do Squad]
+[docs/ do projeto]
+[Session Files: context.md → architecture.md → plan.md]
+[ADRs existentes]
+[Memória da Feature: sessions/{feature-slug}/memories.md]
+[Aprendizados transversais: docs/_memory/project-learnings.md]
+[Outputs Anteriores]
+[Instrução do Step]
+--- SKILLS ATIVAS ---
+[Instruções da Skill 1]
+[Instruções da Skill 2]
+```
+
+A ordem de injeção é: agent → contexto completo → step → skills (na ordem declarada).
+
+---
+
+## INSTALAÇÃO DE NOVA SKILL
+
+### Passo 1 — Criar estrutura
+
+Duas formas válidas de instalar uma skill:
+
+**Diretório local:**
+```
+.synapos/skills/{skill-name}/
+├── SKILL.md          ← definição
+└── scripts/          ← scripts (se type: script ou hybrid)
+    └── run.js
+```
+
+**Symlink** (para skills compartilhadas entre projetos):
+```bash
+ln -s /caminho/para/skill-global/{skill-name} .synapos/skills/{skill-name}
+```
+O resolver trata symlinks exatamente como diretórios reais — nenhuma diferença de comportamento.
+
+### Passo 2 — Para skills MCP
+Adicionar ao arquivo de configuração do IDE:
+- **Claude Code**: `.claude/settings.local.json`
+- **Cursor**: `.cursor/mcp.json`
+- **Antigravity**: configuração MCP do IDE
+
+Formato (Claude Code):
+```json
+{
+  "mcpServers": {
+    "skill-name": {
+      "command": "npx",
+      "args": ["-y", "@package/mcp-server"],
+      "env": {
+        "API_KEY": "${API_KEY}"
+      }
+    }
+  }
+}
+```
+
+### Passo 3 — Variáveis de ambiente
+Adicione ao `.env` do projeto (nunca no código):
+```
+SKILL_API_KEY=sua_chave_aqui
+```
+
+---
+
+## SKILLS SUGERIDAS POR DOMÍNIO
+
+| Domínio | Skill | Uso |
+|---------|-------|-----|
+| Produto | brave-search | Pesquisa de mercado e benchmarks |
+| Produto | fetch-url | Análise de concorrentes |
+| Frontend | playwright | Testes E2E, screenshots |
+| Backend | database-query | Query direta ao banco (dev) |
+| Todos | file-system | Leitura/escrita de arquivos |
+| Todos | github | Criação de issues, PRs |
+
+---
+
+## REGRAS
+
+- Skills são **opcionais** — o agent funciona sem elas, com capacidade reduzida
+- **Quando uma skill está ativa, o agent DEVE usá-la** — nunca execute manualmente o que uma skill já oferece
+- Se uma skill cobre a tarefa em execução (busca, browser, arquivo, GitHub etc.), ela é o caminho obrigatório — não o opcional
+- Nunca adicione uma API key diretamente em SKILL.md — use variáveis de ambiente
+- Skills de `mcp` requerem restart do IDE após configuração
+- Documente em SKILL.md o que muda no comportamento do agent com e sem a skill

package/.synapos/core/versioning.md

@@ -0,0 +1,218 @@
+---
+name: synapos-versioning
+version: 1.1.0
+description: Protocolo de versionamento semântico do Synapos Framework
+---
+
+# SYNAPOS VERSIONING PROTOCOL v1.0.0
+
+> O Synapos usa **Semantic Versioning (semver)**: `MAJOR.MINOR.PATCH`
+> Versão atual sempre em: `.synapos/VERSION`
+> Inventário completo em: `.synapos/.manifest.json`
+
+---
+
+## O QUE VERSIONAR
+
+O Synapos tem **4 níveis de versão independentes**:
+
+| Nível | Arquivo | Controla |
+|-------|---------|---------|
+| **Framework** | `.synapos/VERSION` + `.manifest.json` | Versão global do framework |
+| **Core** | frontmatter de cada `core/*.md` | Mudanças no orchestrator, runner, gates |
+| **Template** | `template.yaml` de cada squad | Mudanças nos templates de squad |
+| **Agent** | frontmatter de cada `*.agent.md` | Mudanças em agents individuais |
+
+---
+
+## REGRAS DE SEMVER
+
+### MAJOR (X.0.0) — quebraria algo existente
+
+**Framework:**
+- Mudança no formato do `orchestrator.md` que altera o protocolo de boot
+- Mudança no contrato do `pipeline-runner.md` (campos obrigatórios de step, state.json)
+- Mudança no formato de `.agent.md` que quebra agents existentes
+
+**Template:**
+- Mudança no formato de `template.yaml` que quebra squads criados com versão anterior
+
+**Agent:**
+- Remoção de seção obrigatória (Persona, Princípios, Framework Operacional)
+- Mudança de role que altera fundamentalmente as tasks do agent
+
+### MINOR (x.Y.0) — adiciona sem quebrar
+
+**Framework:**
+- Novo squad template (fullstack, mobile, devops, etc.)
+- Novo tipo de gate no gate-system
+- Novo tipo de skill no skills-engine
+- Novo adapter IDE
+
+**Template:**
+- Novo agent opcional no template
+- Novo pipeline disponível
+
+**Agent:**
+- Nova task adicionada
+- Novo exemplo de output
+- Novo anti-pattern documentado
+
+### PATCH (x.y.Z) — corrige sem quebrar
+
+**Framework:**
+- Clareza de texto no orchestrator
+- Correção de exemplo no pipeline-runner
+- Melhoria de guia
+
+**Template:**
+- Ajuste de descrição
+- Refinamento de configuração de modo
+
+**Agent:**
+- Refinamento de persona ou princípios
+- Melhoria de exemplo de output
+- Correção de vocabulário
+- Adição de quality criteria
+
+---
+
+## PROTOCOLO DE BUMP
+
+### Passo 1 — Identificar o escopo
+
+Responda:
+- O que mudou? (core, template, agent, ou framework inteiro?)
+- É MAJOR, MINOR ou PATCH? (use as regras acima)
+
+### Passo 2 — Atualizar o(s) arquivo(s) alterado(s)
+
+Atualize o campo `version` no frontmatter do arquivo modificado:
+```yaml
+---
+version: 1.1.0   ← novo valor
+---
+```
+
+### Passo 3 — Atualizar `.manifest.json`
+
+Atualize a versão do componente alterado e a versão do framework se necessário:
+
+```json
+{
+  "framework": { "version": "1.1.0", "released_at": "YYYY-MM-DD" },
+  "agents": {
+    "frontend": {
+      "rodrigo-react": "1.1.0"
+    }
+  }
+}
+```
+
+**Regra de propagação:**
+- Mudança em **agent** → bumpa o agent + framework PATCH (no mínimo)
+- Mudança em **template** → bumpa o template + framework MINOR (no mínimo)
+- Mudança em **core** → bumpa o core file + framework (conforme severidade)
+
+### Passo 4 — Atualizar `.synapos/VERSION`
+
+```
+1.1.0
+```
+
+### Passo 5 — Registrar no `CHANGELOG.md`
+
+Adicione uma entrada na seção `[Não lançado]` ou crie uma nova seção com a versão:
+
+```markdown
+## [1.1.0] — YYYY-MM-DD
+
+### Modificado
+- `rodrigo-react` v1.1.0 — adicionados exemplos de React Server Components
+
+### Corrigido
+- `pipeline-runner.md` — clareza no protocolo de veto conditions
+```
+
+---
+
+## COMPATIBILIDADE DE SQUADS
+
+Squads criados guardam em `squad.yaml` a versão do template usado:
+
+```yaml
+template_version: "1.0.0"   ← versão no momento da criação
+```
+
+### Quando um template muda de versão:
+
+**PATCH** → squads existentes **não precisam** migrar. Funciona como antes.
+
+**MINOR** → squads existentes funcionam, mas não têm os novos agents/pipelines.
+- Aviso no init: "Template `frontend` v1.1.0 disponível. Seu squad usa v1.0.0."
+- Usuário escolhe: migrar ou continuar com a versão atual.
+
+**MAJOR** → squads existentes podem ter comportamento alterado.
+- Aviso obrigatório no init com descrição do que mudou.
+- Não migre automaticamente — exija confirmação explícita.
+
+---
+
+## VERIFICAÇÃO DE VERSÃO NO INIT
+
+O `orchestrator.md` deve, durante o boot, comparar:
+
+```
+Framework instalado:    .synapos/VERSION         → "1.0.0"
+Manifest registrado:    .synapos/.manifest.json  → { "framework": { "version": "1.0.0" } }
+```
+
+Se divergirem: avise que o manifest está desatualizado e execute o bump.
+
+---
+
+## VERSIONAMENTO DE SQUADS INSTANCIADOS
+
+Squads em `.synapos/squads/{squad-slug}/` **não têm versão semver** — o rastreamento é feito via session da feature.
+
+O estado de um squad é registrado em:
+- `docs/.squads/sessions/{feature-slug}/state.json` → estado completo, atualizado por cada squad que trabalha na feature
+- `docs/.squads/sessions/{feature-slug}/memories.md` → aprendizados cumulativos da feature (não versionado, é vivo)
+
+O campo `state.squads["{squad-slug}"]` dentro do `state.json` contém o histórico daquele squad na feature:
+- `status`: `running` | `completed` | `discarded`
+- `completed_steps`: steps concluídos
+- `started_at` / `completed_at`: timestamps
+
+Para rastrear o histórico de trabalho em uma feature: leia `docs/.squads/sessions/{feature-slug}/state.json`.
+
+---
+
+## EXEMPLO COMPLETO DE BUMP MINOR
+
+Cenário: adicionado agent `lucas-lint` ao template `frontend`.
+
+```bash
+# 1. Criar o arquivo do agent
+.synapos/squad-templates/frontend/agents/lucas-lint.agent.md  (version: 1.0.0)
+
+# 2. Atualizar template.yaml
+version: "1.1.0"
+agents:
+  optional:
+    - id: lucas-lint   ← novo
+
+# 3. Atualizar .manifest.json
+"templates": { "frontend": "1.1.0" }
+"agents": { "frontend": { "lucas-lint": "1.0.0" } }
+"framework": { "version": "1.1.0", "released_at": "2026-04-01" }
+
+# 4. Atualizar .synapos/VERSION
+1.1.0
+
+# 5. CHANGELOG.md
+## [1.1.0] — 2026-04-01
+### Adicionado
+- `lucas-lint` v1.0.0 — Especialista em Linting/Code Style ao squad Frontend
+- Template `frontend` v1.1.0 — lucas-lint adicionado como opcional
+```