sinapse-ai 9.2.0 → 9.4.0

package/docs/framework/squad-creation-standards.md

@@ -0,0 +1,331 @@
+# Squad Creation Standards — Sinapse
+
+> Guia definitivo para criar squads de IA com qualidade maxima.
+> Todas as regras e padroes aqui documentados foram extraidos da experiencia de criar 9 squads
+> (~1,030 arquivos) e da auditoria completa de qualidade.
+
+---
+
+## 1. Estrutura de Diretorios (Obrigatoria)
+
+```
+squad-{nome}/
+├── squad.yaml              # Manifesto (OBRIGATORIO)
+├── agents/                 # Definicoes de agentes (.md)
+├── tasks/                  # Tarefas executaveis (.md)
+├── workflows/              # Workflows multi-step (.yaml)
+├── knowledge-base/         # Knowledge bases (.md) — SINGULAR, nao "knowledge-bases"
+├── checklists/             # Checklists de validacao (.md)
+├── templates/              # Templates reutilizaveis (.md)
+└── preferences/            # Preferencias do squad (opcional)
+```
+
+### Regras de Naming
+- **Diretorio do squad:** `squad-{nome-em-kebab-case}` (ex: `squad-brand`)
+- **Arquivos:** SEMPRE kebab-case (`define-brand-positioning.md`, NAO `defineBrandPositioning.md`)
+- **Knowledge base:** SEMPRE `knowledge-base/` (SINGULAR)
+- **Regex de validacao:** `/^[a-z0-9]+(-[a-z0-9]+)*$/`
+
+---
+
+## 2. squad.yaml — Manifesto (Formato Obrigatorio)
+
+```yaml
+name: squad-{nome}                    # kebab-case, 2-50 chars
+version: "1.0.0"                      # SEMVER obrigatorio (NAO "1.0")
+description: >
+  Descricao completa do squad.
+author: Caio Imori
+license: UNLICENSED
+slashPrefix: {prefixo}                # Prefixo para comandos slash
+
+sinapse:
+  minVersion: "1.0.0"
+  type: squad
+
+metadata:
+  created_at: "YYYY-MM-DD"
+  updated_at: "YYYY-MM-DD"
+  created_by: "squad-creator (Craft)"
+  agents_count: N
+  tasks_count: N
+  knowledge_bases_count: N
+  workflows_count: N
+  checklists_count: N
+  templates_count: N
+
+# Agents (listar todos)
+agents:
+  - id: agent-id
+    name: PersonaName
+    file: agents/agent-id.md
+    role: "Descricao do papel"
+    tasks:
+      - task-name-1
+      - task-name-2
+
+# Knowledge bases
+knowledge_bases:
+  - name: kb-name
+    file: knowledge-base/kb-name.md   # SINGULAR: knowledge-base/
+    description: "..."
+
+# Workflows
+workflows:
+  - name: workflow-name
+    file: workflows/workflow-name.yaml
+    description: "..."
+
+# Checklists
+checklists:
+  - name: checklist-name
+    file: checklists/checklist-name.md
+
+# Templates
+templates:
+  - name: template-name
+    file: templates/template-name.md
+```
+
+### Campos OBRIGATORIOS no squad.yaml
+| Campo | Tipo | Regra |
+|-------|------|-------|
+| `name` | string | kebab-case, 2-50 chars |
+| `version` | string | Semver (ex: "1.0.0") |
+| `description` | string | Descricao clara |
+| `sinapse.minVersion` | string | Minimo "1.0.0" |
+| `sinapse.type` | string | "squad" |
+| `author` | string | Nome do criador |
+| `slashPrefix` | string | Prefixo de comando |
+
+---
+
+## 3. Tasks — TASK-FORMAT-SPECIFICATION-V1
+
+**TODA task DEVE ter frontmatter YAML com 7 campos obrigatorios:**
+
+```yaml
+---
+task: nome-da-task                     # kebab-case, mesmo que o filename
+responsavel: "@agent-id"              # ID do agente (NAO persona name)
+responsavel_type: Agent
+atomic_layer: Task
+elicit: false
+
+Entrada:
+  - campo: context
+    tipo: object
+    origem: "workflow ou manual"
+    obrigatorio: true
+
+Saida:
+  - campo: resultado
+    tipo: document
+    destino: "stakeholders"
+
+Checklist:
+  - "[ ] Validar inputs e pre-condicoes"
+  - "[ ] Executar steps conforme documentado"
+  - "[ ] Verificar criterios de qualidade"
+  - "[ ] Gerar output no formato especificado"
+---
+
+# Task: Nome da Task
+
+## Metadata
+- **Agent:** agent-id (PersonaName)
+- **Squad:** squad-nome
+- **Complexity:** STANDARD | HIGH | CRITICAL
+...
+```
+
+### ERROS COMUNS a evitar
+| Erro | Correto |
+|------|---------|
+| `responsavel: "@Convert"` (persona) | `responsavel: "@ga-cro-specialist"` (agent ID) |
+| Sem frontmatter YAML | SEMPRE incluir os 7 campos |
+| `elicit: true` sem formato | Se elicit=true, definir formato de interacao |
+| Filename PascalCase | SEMPRE kebab-case |
+
+### Convencao de Nomes de Task
+- Prefixar com verbo de acao: `define-`, `create-`, `analyze-`, `build-`, `execute-`
+- Agente-especifica: `{agent-prefix}-{action}-{object}` (ex: `ga-cro-run-ab-test`)
+- Generica: `{action}-{object}` (ex: `define-brand-positioning`)
+
+---
+
+## 4. Agents — Formato
+
+### Campos Essenciais (obrigatorios)
+| Campo | Descricao |
+|-------|-----------|
+| Name/Persona | Nome humano do agente |
+| ID | Identificador kebab-case unico no squad |
+| Icon | Emoji representativo |
+| Role | Descricao do papel |
+| Core Principles | 3-6 principios norteadores |
+| Responsibilities | Lista de responsabilidades |
+
+### Formato Aceito: Markdown com Headers
+
+```markdown
+# Agent: PersonaName — Role Title
+
+## Identidade
+- **ID:** agent-id
+- **Nome:** PersonaName
+- **Icon:** EMOJI
+- **Arquetipo:** ArchetypeName
+- **Squad:** squad-nome
+
+## Role
+Descricao completa do papel.
+
+## Principios
+1. Principio 1
+2. Principio 2
+
+## Responsabilidades
+- Responsabilidade 1
+- Responsabilidade 2
+
+## Delegacao
+| Tarefa | Delegar para |
+|--------|-------------|
+| ... | ... |
+
+## Cross-Squad Handoffs
+...
+```
+
+### Formato Aceito: YAML Code Block (mais machine-parseable)
+
+```markdown
+# agent-id — PersonaName
+
+\`\`\`yaml
+agent:
+  name: "PersonaName"
+  id: "squad-name/agent-id"
+  title: "Role Title"
+  icon: "EMOJI"
+
+persona:
+  role: "Descricao do papel"
+  core_principles:
+    - "Principio 1"
+    - "Principio 2"
+\`\`\`
+```
+
+---
+
+## 5. Knowledge Bases — Formato
+
+- Diretorio: `knowledge-base/` (SINGULAR)
+- Formato: Markdown (.md)
+- Conteudo: Frameworks, metodologias, referencias, patterns
+- Deve incluir: fontes academicas, autores referencia, exemplos praticos
+- Naming: kebab-case descritivo (`research-frameworks-encyclopedia.md`)
+
+---
+
+## 6. Workflows — Formato
+
+```yaml
+name: workflow-name
+description: "Descricao"
+trigger: "Quando este workflow e acionado"
+agents_involved:
+  - agent-id-1
+  - agent-id-2
+
+phases:
+  - name: "Phase 1: Nome"
+    agent: agent-id
+    tasks:
+      - task-name-1
+    output: "artifact-name.md"
+    quality_gate: "Criterios de qualidade"
+
+  - name: "Phase 2: Nome"
+    agent: agent-id-2
+    depends_on: ["Phase 1"]
+    tasks:
+      - task-name-2
+```
+
+---
+
+## 7. Metricas de Qualidade Minimas
+
+| Metrica | Minimo | Ideal |
+|---------|--------|-------|
+| Agents | 6 | 7-12 |
+| Tasks | 50 | 65-100 |
+| Workflows | 3 | 6 |
+| Knowledge Bases | 8 | 9-17 |
+| Checklists | 2 | 3 |
+| Templates | 3 | 5-7 |
+| Tasks por agent (media) | 2 | 8-12 |
+
+---
+
+## 8. Cross-Squad Integration
+
+Todo squad deve documentar:
+
+1. **Inbound handoffs:** O que recebe de outros squads
+2. **Outbound handoffs:** O que entrega para outros squads
+3. **Shared knowledge bases:** KBs que servem como ponte
+
+### Exemplo de Handoff no Agent
+```yaml
+cross_squad_handoffs:
+  inbound:
+    - from: squad-research
+      artifact: "research-report.md"
+      when: "Pesquisa concluida"
+  outbound:
+    - to: squad-content
+      artifact: "brand-guidelines.md"
+      when: "Guidelines finalizadas"
+```
+
+---
+
+## 9. Checklist Pre-Publicacao
+
+- [ ] `squad.yaml` tem TODOS os campos obrigatorios
+- [ ] `version` em formato semver (X.Y.Z)
+- [ ] `sinapse` section com minVersion e type
+- [ ] TODOS os tasks tem frontmatter YAML com 7 campos
+- [ ] `responsavel` usa agent ID (NAO persona name)
+- [ ] Diretorio `knowledge-base/` (SINGULAR)
+- [ ] TODOS os filenames em kebab-case
+- [ ] Minimo 6 agents, 50 tasks, 3 workflows, 8 KBs
+- [ ] Cross-squad handoffs documentados
+- [ ] Cada agent tem: name, ID, icon, role, principles
+- [ ] Workflows referenciam tasks e agents existentes
+- [ ] Knowledge bases tem fontes e referencias
+
+---
+
+## 10. Mapa dos 9 Squads Existentes
+
+| # | Squad | Agents | Tasks | Workflows | KBs | Total |
+|---|-------|--------|-------|-----------|-----|-------|
+| 01 | squad-brand | 12 | 91 | 4 | 17 | 136 |
+| 02 | squad-content | 7 | 90 | 6 | 15 | 130 |
+| 03 | squad-research | 7 | 72 | 6 | 12 | 108 |
+| 04 | squad-copy | 7 | 68 | 6 | 11 | 104 |
+| 05 | squad-design | 8 | 101 | 6 | 11 | 138 |
+| 06 | squad-growth | 7 | 72 | 6 | 9 | 105 |
+| 07 | squad-commercial | 7 | 66 | 6 | 9 | 99 |
+| 08 | squad-product | 7 | 75 | 6 | 9 | 107 |
+| 09 | (deprecated) | - | - | - | - | - |
+| **TOTAL** | **9 squads** | **69** | **705** | **52** | **102** | **~1,029** |
+
+---
+
+*Documento criado em 2026-03-15. Baseado na auditoria completa dos 9 squads.*

package/docs/{versioning-and-releases.md → framework/versioning-and-releases.md}

@@ -138,3 +138,4 @@ npm publish
 ---
 
 *Last updated: Story 6.17 - Semantic Release Automation*
+

package/docs/guides/README.md

@@ -125,3 +125,4 @@ Use the DevOps agent: `@devops` then `*setup-mcp-docker`
 
 **Last Updated:** 2025-12-17
 **Version:** 2.1 (Story 6.14)
+

package/docs/guides/ade-guide.md

@@ -444,3 +444,4 @@ cat docs/stories/STORY-42/spec-critique.json
 ---
 
 _SINAPSE Autonomous Development Engine - Turning Ideas into Code Autonomously_
+

package/docs/guides/agent-reference.md

@@ -1,203 +1,140 @@
-# Referencia de Agentes
-
-> Indice navegavel de todos os agentes do ecossistema SINAPSE-AI.
-
----
-
-## 12 Agentes Core
-
-Os agentes core cobrem o ciclo completo de desenvolvimento de software.
-
-| ID | Persona | Papel | Comandos Principais |
-|----|---------|-------|---------------------|
-| `@developer` | Pixel | Implementacao de codigo | `*develop`, `*task`, `*improve-code-quality` |
-| `@quality-gate` | Litmus | Testes e qualidade | `*qa-gate`, `*qa-loop`, `*review` |
-| `@architect` | Stratum | Arquitetura e design tecnico | `*create-doc architecture`, `*assess-complexity` |
-| `@project-lead` | Beacon | Product Management e epics | `*create-epic`, `*execute-epic`, `*spec-pipeline` |
-| `@product-lead` | Axis | Product Owner, stories e backlog | `*validate-story-draft`, `*create-story`, `*backlog` |
-| `@sprint-lead` | Sync | Scrum Master e criacao de stories | `*draft`, `*create-story`, `*sprint-plan` |
-| `@analyst` | Scope | Pesquisa e analise | `*research`, `*analyze`, `*report` |
-| `@data-engineer` | Tensor | Database e engenharia de dados | `*create-migration`, `*schema-design`, `*db-audit` |
-| `@ux-design-expert` | Mosaic | UX/UI design | `*create-wireframe`, `*ux-audit`, `*design-system` |
-| `@devops` | Pipeline | CI/CD, git push (EXCLUSIVO) | `*push`, `*release`, `*setup-ci` |
-| `@sinapse-orqx` | Imperator | Orquestrador principal | `*diagnose`, `*route`, `*orchestrate` |
-| `@squad-creator` | Loom | Criacao de novos squads | `*create-squad`, `*scaffold` |
-
----
-
-## 18 Squads
-
-Squads sao agrupamentos tematicos de agentes especialistas. Cada squad tem um orquestrador (*-orqx) que coordena o trabalho interno.
-
-| Squad | Agentes | Dominio | Orquestrador |
-|-------|---------|---------|-------------|
-| squad-animations | Especialistas em motion | Animacoes web, micro-interacoes | @animations-orqx (Kinetic) |
-| squad-brand | Especialistas em marca | Branding, identidade visual | @brand-orqx (Meridian) |
-| squad-claude | Especialistas Claude Code | Mastery de Claude Code | @claude-orqx (Nucleus) |
-| squad-cloning | Especialistas em clonagem | Clonagem cognitiva de personas | @cloning-orqx (Helix) |
-| squad-commercial | Especialistas em vendas | Vendas, CRM, pipeline | @commercial-orqx (Pipeline) |
-| squad-content | Especialistas em conteudo | Editorial, estrategia de conteudo | @content-orqx |
-| squad-copy | Especialistas em copy | Copywriting, persuasao | @copy-orqx (Quill) |
-| squad-council | Conselheiros estrategicos | Conselho estrategico, decisoes | @council-orqx (Zenith) |
-| squad-courses | Especialistas em cursos | Cursos, workshops, educacao | @courses-orqx (Syllabus) |
-| squad-cybersecurity | Especialistas em seguranca | Seguranca, compliance, LGPD | @cyber-orqx (Fortress) |
-| squad-design | Especialistas em design | UX/UI, design system | @design-orqx (Nexus) |
-| squad-finance | Especialistas financeiros | Financeiro, pricing, valuation | @finance-orqx (Ledger) |
-| squad-growth | Especialistas em growth | SEO, analytics, growth hacking | @growth-orqx (Catalyst) |
-| squad-paidmedia | Especialistas em midia paga | Ads, campanhas, ROAS | @paidmedia-orqx (Apex) |
-| squad-product | Especialistas em produto | Roadmap, discovery, metricas | @product-orqx (Vector) |
-| squad-research | Especialistas em pesquisa | Pesquisa, inteligencia competitiva | @research-orqx (Prism) |
-| squad-storytelling | Especialistas em narrativa | Storytelling, pitch, apresentacoes | @storytelling-orqx (Arc) |
-| claude-code-mastery | Especialistas avancados | Tecnicas avancadas de Claude Code | (integrado ao squad-claude) |
-
-**Total: 186 agentes** (12 core + 163 em squads)
-
----
-
-## Como Ativar Agentes
-
-### Metodo 1: Comando direto
+# AGENTS.md - SINAPSE
 
-```
-@developer
-```
-
-Digite `@` seguido do ID do agente. O SYNAPSE Engine carrega a persona, dependencias e contexto automaticamente.
-
-### Metodo 2: Comando completo
-
-```
-/SINAPSE:agents:developer
-```
-
-Formato completo com namespace. Util em ambientes onde `@` tem outro significado.
-
-### O que acontece na ativacao
-
-1. SYNAPSE Engine detecta o comando
-2. Pipeline de 8 camadas (L0-L7) carrega contexto
-3. Greeting personalizado e exibido
-4. Agente aguarda seu comando (HALT)
-
-**O agente NAO executa acoes automaticamente.** Ele apresenta o greeting e espera.
-
----
+Este arquivo configura o comportamento esperado de agentes no Codex CLI neste repositorio.
 
-## Como Usar Comandos
+## Constitution
 
-Todos os comandos de agentes usam o prefixo `*`:
+Siga `.sinapse-ai/constitution.md` como fonte de verdade:
+- CLI First (NON-NEGOTIABLE)
+- Agent Authority (NON-NEGOTIABLE)
+- Documentation-First Development (NON-NEGOTIABLE)
+- No Invention (MUST)
+- Quality First (MUST)
+- Absolute Imports (SHOULD)
+- Ecosystem Metrics Accuracy (NON-NEGOTIABLE)
+- Mandatory Delegation (NON-NEGOTIABLE)
 
-| Comando | Funcao | Exemplo |
-|---------|--------|---------|
-| `*help` | Lista comandos disponiveis do agente ativo | `*help` |
-| `*create-story` | Cria uma story de desenvolvimento | `*create-story` |
-| `*task {nome}` | Executa uma task especifica | `*task develop-story` |
-| `*exit` | Sai do modo agente atual | `*exit` |
+## Workflow Obrigatorio
 
-### Exemplos de Uso
+1. Inicie por uma story em `docs/stories/`
+2. Implemente apenas o que os acceptance criteria pedem
+3. Atualize checklist (`[ ]` -> `[x]`) e file list
+4. Execute quality gates antes de concluir
 
-```
-@developer          --> ativa Pixel (developer)
-*help               --> lista comandos do Pixel
-*develop            --> inicia desenvolvimento da story
-*task fix-qa-issues --> executa task de correcao de QA
-```
-
-```
-@quality-gate       --> ativa Litmus (QA)
-*qa-gate            --> executa quality gate na story
-*qa-loop 8.15       --> inicia loop de QA para story 8.15
-```
+## Quality Gates
 
+```bash
+npm run lint
+npm run typecheck
+npm test
 ```
-@sprint-lead        --> ativa Sync (Scrum Master)
-*draft              --> cria rascunho de nova story
-*create-story       --> cria story completa
-```
-
----
-
-## Protocolo de Handoff entre Agentes
-
-Quando voce troca de agente (`@developer` → `@quality-gate`), o SINAPSE executa um protocolo de compactacao:
-
-1. **Agente anterior** gera um artefato de handoff (~379 tokens) com:
-   - Story ativa e status
-   - Decisoes tomadas
-   - Arquivos modificados
-   - Blockers ativos
-   - Proxima acao sugerida
-
-2. **Agente novo** recebe:
-   - Sua propria persona completa
-   - Artefato de handoff do agente anterior
-   - NAO recebe a persona completa do agente anterior
-
-**Resultado:** economia de 33-57% de contexto por troca de agente.
-
-Limite: maximo 3 handoffs retidos. O mais antigo e descartado no 4o switch.
-
----
-
-## Criando Agentes Customizados
-
-O SINAPSE permite criar novos squads com agentes especializados usando @squad-creator (Loom):
-
-```
-@squad-creator
-*create-squad
-```
-
-Loom guia voce pelo processo:
-
-1. Define o dominio do squad
-2. Identifica especialistas necessarios
-3. Cria a estrutura de arquivos (orquestrador + especialistas)
-4. Registra no ecossistema
-
-**Localizacao dos squads:** `squads/squad-{nome}/`
-
-Cada squad segue a mesma estrutura:
-```
-squads/squad-{nome}/
-  squad.yaml          # Configuracao do squad
-  agents/             # Definicoes dos agentes
-  tasks/              # Tasks especificas do dominio
-  templates/          # Templates do dominio
-```
-
----
-
-## Mapeamento Agente → Codebase
-
-Cada agente core tem diretorios primarios de atuacao:
-
-| Agente | Diretorios Principais |
-|--------|----------------------|
-| @developer (Pixel) | `packages/`, `.sinapse-ai/core/`, `bin/` |
-| @architect (Stratum) | `docs/architecture/`, system design |
-| @data-engineer (Tensor) | `packages/db/`, migrations, schema |
-| @quality-gate (Litmus) | `tests/`, `*.test.js`, quality gates |
-| @product-lead (Axis) | Stories, epics, requirements |
-| @devops (Pipeline) | `.github/`, CI/CD, git operations |
-
----
-
-## Autoridade Exclusiva
-
-Cada agente tem operacoes que SOMENTE ele pode executar:
-
-| Operacao | Agente Exclusivo | Outros Agentes |
-|----------|-----------------|----------------|
-| `git push` | @devops (Pipeline) | BLOQUEADO |
-| Criar PR | @devops (Pipeline) | BLOQUEADO |
-| Criar story | @sprint-lead (Sync) | BLOQUEADO |
-| Validar story | @product-lead (Axis) | BLOQUEADO |
-| Decisoes de arquitetura | @architect (Stratum) | BLOQUEADO |
-| Verdicts de qualidade | @quality-gate (Litmus) | BLOQUEADO |
-
-Violacoes de autoridade sao bloqueadas via hooks (Constitution Art. II).
-
----
 
-_Veja tambem: [Workflows Overview](workflows-overview.md) | [Architecture Overview](../architecture-overview.md) | [Guiding Principles](../guiding-principles.md)_
+## Estrutura Principal
+
+- Core framework: `.sinapse-ai/`
+- CLI: `bin/`
+- Pacotes: `packages/`
+- Testes: `tests/`
+- Documentacao: `docs/`
+
+## IDE/Agent Sync
+
+- Sincronizar regras/agentes: `npm run sync:ide`
+- Validar drift: `npm run sync:ide:check`
+- Rodar paridade multi-IDE (Claude/Codex/Gemini): `npm run validate:parity`
+- Sync Claude Code: `npm run sync:ide:claude`
+- Sincronizar Gemini CLI: `npm run sync:ide:gemini`
+- Validar Codex sync/integration: `npm run validate:codex-sync`; `npm run validate:codex-integration`
+- Validar command/task registry do Codex: `npm run validate:codex-commands`
+- Validar matriz de delegacao do Codex: `npm run validate:codex-delegation`
+- Gerar skills locais do Codex: `npm run sync:skills:codex`
+- Este repositorio usa **local-first**: prefira `.codex/skills` versionado no projeto
+- Use `sync:skills:codex:global` apenas para testes fora deste repo
+
+## Command Resolution (Codex)
+
+Quando um agente no Codex receber um `*comando`, prefira resolver a execucao por esta ordem:
+
+1. Consultar `.codex/command-registry.json`
+2. Opcionalmente usar `node .codex/scripts/resolve-codex-command.js <skill-ou-agent> <comando>`
+3. Carregar a task/workflow/checklist/template mapeada
+
+Isso evita "file hunting" manual e torna a execucao de workflows/tasks mais deterministica no Codex.
+
+## Delegation Resolution (Codex)
+
+Quando um orqx no Codex precisar decidir um handoff:
+
+1. Consultar `.codex/delegation-matrix.json`
+2. Opcionalmente usar `node .codex/scripts/resolve-codex-delegation.js <source-agent> <route>`
+3. Distinguir entre:
+   - `validator-backed`
+   - `codex-shim`
+   - `exploratory`
+
+No Codex, nao trate handoffs exploratorios como se fossem caminhos garantidos pelo validator.
+
+## Agent Shortcuts (Codex)
+
+Preferencia de ativacao no Codex CLI:
+1. Use `/skills` e selecione `sinapse-<agent-id>` vindo de `.codex/skills` (ex.: `sinapse-architect`)
+2. Se preferir, use os atalhos abaixo (`@architect`, `/architect`, etc.)
+
+Quando a mensagem do usuario for um atalho de agente, carregue o arquivo correspondente em `.sinapse-ai/development/agents/` (fallback: `.codex/agents/`), renderize o greeting via `generate-greeting.js` e assuma a persona ate receber `*exit`.
+
+Atalhos aceitos por agente (nome completo + alias):
+- `@sinapse-orqx` -> `.sinapse-ai/development/agents/sinapse-orqx.md`
+- `@developer` ou `@dev` -> `.sinapse-ai/development/agents/developer.md`
+- `@quality-gate` ou `@qa` -> `.sinapse-ai/development/agents/quality-gate.md`
+- `@project-lead` ou `@pm` -> `.sinapse-ai/development/agents/project-lead.md`
+- `@product-lead` ou `@po` -> `.sinapse-ai/development/agents/product-lead.md`
+- `@sprint-lead` ou `@sm` -> `.sinapse-ai/development/agents/sprint-lead.md`
+- `@analyst` -> `.sinapse-ai/development/agents/analyst.md`
+- `@architect` -> `.sinapse-ai/development/agents/architect.md`
+- `@data-engineer` -> `.sinapse-ai/development/agents/data-engineer.md`
+- `@devops` -> `.sinapse-ai/development/agents/devops.md`
+- `@squad-creator` -> `.sinapse-ai/development/agents/squad-creator.md`
+- `@ux-design-expert` -> `.sinapse-ai/development/agents/ux-design-expert.md`
+
+Resposta esperada ao ativar atalho:
+1. Confirmar agente ativado
+2. Mostrar 3-6 comandos principais (`*help`, etc.)
+3. Seguir na persona do agente
+
+## Orquestradores (19 orqx: 18 squad + 1 master)
+
+Cada orqx coordena um squad completo de agentes especializados. Ative via `/skills` > `sinapse-<orqx>` ou `@<orqx>`:
+
+| Orqx | Squad | Foco |
+|------|-------|------|
+| `sinapse-orqx` | Core | Orquestrador principal de todos os squads |
+| `brand-orqx` | Brand | Estrategia de marca, arquetipos, auditoria |
+| `copy-orqx` | Copy | Copywriting persuasivo, headlines, conversao |
+| `content-orqx` | Content | Governanca editorial, estrategia de conteudo |
+| `storytelling-orqx` | Storytelling | Narrativa, roteiros, frameworks de historia |
+| `commercial-orqx` | Commercial | Vendas, funil, revenue, pipeline |
+| `paidmedia-orqx` | Paid Media | Meta Ads, Google Ads, campanhas |
+| `growth-orqx` | Growth | Analytics, CRO, SEO, growth hacking |
+| `research-orqx` | Research | Market analysis, inteligencia competitiva |
+| `product-orqx` | Product | Product discovery, estrategia, operacoes |
+| `design-orqx` | Design | Design systems, componentes, tokens |
+| `animations-orqx` | Animations | Motion design, CSS, particulas, 3D |
+| `cyber-orqx` | Cybersecurity | Seguranca, threat intel, pentest |
+| `finance-orqx` | Finance | Budget, pricing, profitability |
+| `courses-orqx` | Courses | Curriculos, assessments, launch |
+| `cloning-orqx` | Cloning | Clonagem cognitiva, mind synthesis |
+| `council-orqx` | Council | Advisors estrategicos (Munger, Dalio, Thiel) |
+| `claude-orqx` | Claude | Claude Code, MCP, integracao avancada |
+| `swarm-orqx` | Mastery | Dominio avancado do Claude Code |
+
+Agents de arquivo: `.codex/agents/<orqx>.md` ou `.claude/agents/<orqx>.md`
+
+## Agentes Especializados (175)
+
+Existem 186 agentes especializados organizados por 18 squads (174 em squads + 1 master orchestrator). Eles sao acessiveis via:
+- `.codex/agents/<agent-name>.md` - arquivo direto
+- Chamada interna pelo orqx do squad
+
+Exemplos: `brand-strategist`, `ad-copywriter`, `penetration-tester`, `content-writer`, `ga-analytics-engineer`, etc.
+
+Use `*help` dentro de qualquer orqx para ver os especialistas disponiveis no squad.

package/docs/guides/agent-selection-guide.md

@@ -287,3 +287,4 @@ Retries < 3? → @developer retry with variation
 ---
 
 **Version:** 2.0 | **ADE:** v2.2.0 | **Date:** 2026-01-29
+

package/docs/guides/agents/ANALYST-SYSTEM.md

@@ -671,3 +671,4 @@ template:
 ---
 
 *-- Atlas, investigando a verdade :mag_right:*
+

package/docs/guides/agents/ARCHITECT-SYSTEM.md

@@ -733,3 +733,4 @@ Ative @github-devops para operacoes de push:
 ---
 
 *-- Aria, arquitetando o futuro*
+