sinapse-ai 1.25.1 → 1.25.3

package/docs/guides/codex-config.md

@@ -1,6 +1,6 @@
 # AGENTS.md - SINAPSE
 
-Este arquivo configura o comportamento esperado de agentes no Codex CLI neste repositorio.
+Este arquivo configura o comportamento esperado de agentes no Codex CLI neste repositório.
 
 ## Constitution
 
@@ -14,7 +14,7 @@ Siga `.sinapse-ai/constitution.md` como fonte de verdade:
 - Ecosystem Metrics Accuracy (NON-NEGOTIABLE)
 - Mandatory Delegation (NON-NEGOTIABLE)
 
-## Workflow Obrigatorio
+## Workflow Obrigatório
 
 1. Inicie por uma story em `docs/stories/`
 2. Implemente apenas o que os acceptance criteria pedem
@@ -35,31 +35,31 @@ npm test
 - CLI: `bin/`
 - Pacotes: `packages/`
 - Testes: `tests/`
-- Documentacao: `docs/`
+- Documentação: `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`
+- Rodar paridade Claude/Codex: `npm run validate:parity`
 - Sync Claude Code: `npm run sync:ide:claude`
-- Sincronizar Gemini CLI: `npm run sync:ide:gemini`
+- Sincronizar Codex: `npm run sync:ide:codex`
 - 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`
+- Validar matriz de delegação do Codex: `npm run validate:codex-delegation`
 - Gerar skills locais do Codex: `npm run sync:skills:codex`
-- Este repositorio usa **local-first**: `.agents/skills` e a unica raiz de skills SINAPSE versionada no projeto
+- Este repositório usa **local-first**: `.agents/skills` é a única raiz de skills SINAPSE versionada 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:
+Quando um agente no Codex receber um `*comando`, prefira resolver a execução 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.
+Isso evita "file hunting" manual e torna a execução de workflows/tasks mais determinística no Codex.
 
 ## Delegation Resolution (Codex)
 
@@ -72,68 +72,52 @@ Quando um orqx no Codex precisar decidir um handoff:
    - `codex-shim`
    - `exploratory`
 
-No Codex, nao trate handoffs exploratorios como se fossem caminhos garantidos pelo validator.
+No Codex, não trate handoffs exploratórios como se fossem caminhos garantidos pelo validator.
 
-## Agent Shortcuts (Codex)
+## Ativação de agentes (Codex)
 
-Preferencia de ativacao no Codex CLI:
-1. Use `/skills` e selecione `sinapse-<agent-id>` vindo de `.agents/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
+- Use `$snps` para roteamento pelo orquestrador principal.
+- Use `$sinapse-agent <agent-id>` para ativação direta, por exemplo
+  `$sinapse-agent developer` ou `$sinapse-agent architect`.
+- O ativador paramétrico resolve a fonte canônica e apenas tasks existentes;
+  não interprete `@agent`, slash commands ou aliases curtos como ativação Codex.
 
 ## Orquestradores (18 orqx: 17 squad + 1 master)
 
-Cada orqx coordena um squad completo de agentes especializados. Ative via `/skills` > `sinapse-<orqx>` ou `@<orqx>`:
+Cada orqx coordena um squad completo de agentes especializados. Use `$snps` para
+roteamento ou `$sinapse-agent <orqx-id>` para ativação direta:
 
 | 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 |
+| `brand-orqx` | Brand | Estratégia de marca, arquétipos, auditoria |
+| `copy-orqx` | Copy | Copywriting persuasivo, headlines, conversão |
+| `content-orqx` | Content | Governança editorial, estratégia de conteúdo |
+| `storytelling-orqx` | Storytelling | Narrativa, roteiros, frameworks de história |
 | `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 |
+| `research-orqx` | Research | Market analysis, inteligência competitiva |
+| `product-orqx` | Product | Product discovery, estratégia, operações |
 | `design-orqx` | Design | Design systems, componentes, tokens |
-| `animations-orqx` | Animations | Motion design, CSS, particulas, 3D |
-| `cyber-orqx` | Cybersecurity | Seguranca, threat intel, pentest |
+| `animations-orqx` | Animations | Motion design, CSS, partículas, 3D |
+| `cyber-orqx` | Cybersecurity | Segurança, threat intel, pentest |
 | `finance-orqx` | Finance | Budget, pricing, profitability |
-| `courses-orqx` | Courses | Curriculos, assessments, launch |
+| `courses-orqx` | Courses | Currículos, assessments, launch |
 | `cloning-orqx` | Cloning | Clonagem cognitiva, mind synthesis |
-| `council-orqx` | Council | Advisors estrategicos (Munger, Dalio, Thiel) |
-| `swarm-orqx` | Mastery | Claude Code, MCP, integracao avancada |
+| `council-orqx` | Council | Advisors estratégicos (Munger, Dalio, Thiel) |
+| `swarm-orqx` | Mastery | Claude Code, MCP, integração avançada |
 
-Agents de arquivo: `.codex/agents/<orqx>.md` ou `.claude/agents/<orqx>.md`
+Adapters de arquivo: `.claude/agents/sinapse-<orqx-id>.md` no Claude Code e
+`.codex/agents/<orqx-id>.toml` (com companion `.md`) no Codex.
 
 ## Agentes Especializados (160)
 
-Existem 172 agentes organizados em 17 squads (160 em squads + 12 framework agents, incluindo o master orchestrator). Eles sao acessiveis via:
-- `.codex/agents/<agent-name>.md` - arquivo direto
+Existem 172 agentes organizados em 17 squads (160 em squads + 12 framework agents, incluindo o master orchestrator). Eles são acessíveis via:
+- `.claude/agents/sinapse-<agent-id>.md` - agent nativo do Claude Code
+- `.codex/agents/<agent-id>.toml` e `.codex/agents/<agent-id>.md` - adapters Codex
 - 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.
+Use `*help` dentro de qualquer orqx para ver os especialistas disponíveis no squad.

package/docs/guides/ide-integration.md

@@ -19,40 +19,39 @@ SINAPSE supports the following AI-powered development platforms:
 
 | IDE/CLI | Overall Status | How to Activate an Agent | Auto-Checks Before/After Actions |
 | --- | --- | --- | --- |
-| Claude Code | Works | `/agent-name` commands | Works (full) |
-| Codex CLI | Limited | `/skills` then `sinapse-<agent-id>` | Limited (some checks need manual sync) |
+| Claude Code | Works | `@agent-name` | 20 native hook registrations |
+| Codex CLI | Works | `$snps` or `$sinapse-agent <id>` | 9 lifecycle events through the bridge |
 
 Legend:
-- `Works`: fully recommended for new users.
-- `Limited`: usable with the documented workaround.
+- `Works`: supported by provider-native adapters and release validators.
 
-### What You Lose Without Full Auto-Checks
+### Provider-Native Differences
 
-Some IDEs run automatic checks before and after each action (e.g., validating context, enforcing rules). Where this is not available, you compensate manually:
+Both providers expose native lifecycle surfaces. Their registration models differ, so parity is measured semantically instead of by requiring identical hook files:
 
-| IDE | Auto-Check Level | What Is Reduced | How to Compensate |
-| --- | --- | --- | --- |
-| Claude Code | Full | Nothing | Built-in checks handle everything |
-| Codex CLI | Partial | Less automatic session tracking; some pre/post-action checks need manual trigger | Use `AGENTS.md` + `/skills` + sync/validation scripts |
+| Measured surface | Claude Code | Codex CLI |
+| --- | --- | --- |
+| Native agents | 172 | 172 |
+| Installed skills | 36 | 37 |
+| Registered hooks | 20 native registrations | 9 lifecycle events through the bridge |
+| Activation | `@agent-name` | `$snps` or `$sinapse-agent <id>` |
 
 ### Beginner Decision Guide
 
 If your goal is to get started as fast as possible:
 
-1. **Best option:** Use `Claude Code` -- it has the most automation and fewest manual steps.
-2. **Good option:** Use `Codex CLI` if you prefer a terminal-first workflow and can follow the `/skills` activation flow.
+1. Use **Claude Code** when you want its native `@agent-name` interaction.
+2. Use **Codex CLI** when you want `$snps`, direct parametric activation and its terminal-first workflow.
 
 ### Practical Consequences by Capability
 
 - **Session tracking** (automatic start/end detection):
-  - Automatic on Claude Code.
-  - Manual or partial on Codex CLI.
+  - Registered through native lifecycle adapters on both providers.
 - **Pre/post-action guardrails** (checks that run before and after each tool use):
-  - Full on Claude Code.
-  - Partial on Codex CLI (run sync scripts to compensate).
+  - Claude Code uses native hook registrations.
+  - Codex maps native lifecycle events through the compatibility bridge.
 - **Automatic audit trail** (record of what happened in each session):
-  - Richest on Claude Code.
-  - Reduced on Codex CLI (compensate with manual logging or validator output).
+  - Provider-specific telemetry uses the same canonical SINAPSE governance sources.
 
 ---
 
@@ -60,12 +59,12 @@ If your goal is to get started as fast as possible:
 
 ### Claude Code
 
-**Recommendation Level:** Best SINAPSE integration
+**Recommendation Level:** Native SINAPSE integration
 
 ```yaml
 config_file: .claude/CLAUDE.md
 agent_folder: .claude/agents
-activation: /agent-name (slash commands)
+activation: '@agent-name'
 format: full-markdown-yaml
 mcp_support: native
 special_features:
@@ -79,7 +78,7 @@ special_features:
 **Setup:**
 
 1. SINAPSE automatically creates `.claude/` directory on init
-2. Agents are available as slash commands: `/dev`, `/qa`, `/architect`
+2. Agents are available through `@developer`, `@quality-gate`, `@architect`, etc.
 3. Configure MCP servers in `~/.claude.json`
 
 **Configuration:**
@@ -107,7 +106,7 @@ format: markdown
 mcp_support: native via Codex tooling
 special_features:
   - AGENTS.md project instructions
-  - /skills activators (sinapse-<agent-id>)
+  - $snps and $sinapse-agent <id> activators
   - Strong CLI workflow support
   - Easy integration with repository scripts
   - Notify command plus emerging tool hooks in recent Codex releases
@@ -118,7 +117,7 @@ special_features:
 1. Keep `AGENTS.md` at repository root
 2. Run `npm run sync:ide:codex` to sync auxiliary agent files
 3. Run `npm run sync:skills:codex` to generate project-local skills in `.agents/skills`
-4. Use `/skills` and choose `sinapse-architect`, `sinapse-dev`, etc.
+4. Use `$snps` or `$sinapse-agent architect`, `$sinapse-agent developer`, etc.
 5. Use `npm run sync:skills:codex:global` only when you explicitly want global installation
 
 **Configuration:**

package/docs/guides/project-status-feature.md

@@ -26,10 +26,11 @@ This gives you immediate context about your work without manually running `git s
 
 ## Example Display
 
-When you activate an agent (e.g., `/dev`), you'll see:
+When you activate an agent (`@developer` in Claude Code or
+`$sinapse-agent developer` in Codex), you'll see:
 
-```
-💻 Dex (Builder) ready. Let's build something great!
+```text
+💻 Pixel the Builder ready to innovate!
 
 Current Project Status:
   - Branch: main
@@ -46,24 +47,15 @@ Type *help to see available commands!
 ### Prerequisites
 
 - **Git repository** - Project must be initialized with `git init`
-- **SINAPSE-FullStack** framework installed
+- **SINAPSE AI** framework installed
 - **Node.js 18+** with required packages
 
 ### Initial Setup
 
-Run the initialization command via @devops agent:
-
-```bash
-/devops
-*init-project-status
-```
-
-This will:
-1. Detect your git repository
-2. Enable `projectStatus` in `core-config.yaml`
-3. Create `.sinapse/project-status.yaml` cache file
-4. Add cache file to `.gitignore`
-5. Test the status display
+No agent command is required. In current installations, `projectStatus` is
+enabled in `.sinapse-ai/core-config.yaml` and loads automatically during agent
+activation. The loader detects the Git repository and maintains
+`.sinapse/project-status.yaml` as a runtime cache.
 
 **Alternative Manual Setup:**
 
@@ -213,19 +205,24 @@ Only shows stories with status: `InProgress` or `In Progress`.
 
 ## Affected Agents
 
-All 11 SINAPSE agents display project status:
-
-1. **@dev** (Dex - Builder)
-2. **@po** (Pax - Balancer)
-3. **@qa** (Quinn - Guardian)
-4. **@sm** (River - Facilitator)
-5. **@pm** (Morgan - Strategist)
-6. **@architect** (Aria - Visionary)
-7. **@analyst** (Atlas - Decoder)
-8. **@devops** (Gage - Operator)
-9. **@data-engineer** (Dara - Sage)
-10. **@ux-design-expert** (Uma - Empathizer)
-11. **@sinapse-orqx** (Orion - Orchestrator)
+SINAPSE includes 172 specialized agents across 17 squads. Project status is a
+shared framework capability; the list below is the core development subset, not
+the complete agent catalog:
+
+1. `developer` (Pixel)
+2. `product-lead` (Axis)
+3. `quality-gate` (Litmus)
+4. `sprint-lead` (Sync)
+5. `project-lead` (Beacon)
+6. `architect` (Stratum)
+7. `analyst` (Scope)
+8. `devops` (Pipeline)
+9. `data-engineer` (Tensor)
+10. `ux-design-expert` (Mosaic)
+11. `snps-orqx` (Imperator)
+
+Activate these IDs with `@agent-id` in Claude Code or
+`$sinapse-agent agent-id` in Codex; use `$snps` for primary Codex routing.
 
 ---
 
@@ -241,12 +238,9 @@ All 11 SINAPSE agents display project status:
 3. Does `.sinapse-ai/infrastructure/scripts/project-status-loader.js` exist?
 4. Any errors in agent activation output?
 
-**Solution:**
-```bash
-# Re-run initialization
-/devops
-*init-project-status
-```
+**Solution:** Run `npx sinapse-ai@latest doctor`, confirm the checks above, and
+restart the provider session. Project status reloads automatically; there is no
+public Codex `init-project-status` task pointer.
 
 ### Stale Status Data
 
@@ -362,28 +356,15 @@ await clearCache();
 
 ### Complete Removal
 
-To fully remove the feature:
+Do not delete framework scripts, tests, or task files. Disable the feature in
+`.sinapse-ai/core-config.yaml` and remove only its runtime cache:
 
 ```bash
-# Remove script
-rm .sinapse-ai/infrastructure/scripts/project-status-loader.js
-
-# Remove task
-rm .sinapse-ai/tasks/init-project-status.md
-
-# Remove cache
 rm .sinapse/project-status.yaml
-
-# Remove tests
-rm .sinapse-ai/infrastructure/scripts/__tests__/project-status-loader.test.js
-
-# Remove config section from core-config.yaml
-# (manually edit file)
-
-# Revert agent files to pre-6.1.2.4 state
-git revert <commit-hash>
 ```
 
+Set `projectStatus.enabled: false`; protected framework files remain installed.
+
 ---
 
 ## Git Version Compatibility
@@ -457,7 +438,7 @@ A: Yes, all agents use the same cache file (`.sinapse/project-status.yaml`).
 - **Story:** `docs/stories/sinapse migration/story-6.1.2.4-project-status-context.md`
 - **Config:** `.sinapse-ai/core-config.yaml` (projectStatus section)
 - **Script:** `.sinapse-ai/infrastructure/scripts/project-status-loader.js`
-- **Init Task:** `.sinapse-ai/tasks/init-project-status.md`
+- **Initialization:** automatic when `projectStatus.enabled` is true
 - **Tests:** `.sinapse-ai/infrastructure/scripts/__tests__/project-status-loader.test.js`
 
 ---
@@ -465,4 +446,3 @@ A: Yes, all agents use the same cache file (`.sinapse/project-status.yaml`).
 **Version:** 1.0
 **Status:** ✅ Production Ready
 **Last Updated:** 2025-01-14
-

package/docs/guides/user-guide.md

@@ -42,13 +42,15 @@ cd my-project
 # List available agents
 npx sinapse-ai agents list
 
-# Activate an agent
+# Claude Code: activate an agent
 @developer
 
 # Get help
 *help
 ```
 
+In Codex, use `$snps` for routing or `$sinapse-agent developer` for direct activation.
+
 ---
 
 ## Core Concepts
@@ -66,7 +68,7 @@ SINAPSE provides orchestrated structure while allowing flexibility in communicat
 
 | Traditional AI Dev            | SINAPSE                                    |
 | ----------------------------- | --------------------------------------- |
-| Uncoordinated agents          | 11 specialized agents with clear roles  |
+| Uncoordinated agents          | 172 specialized agents across 17 squads |
 | Inconsistent results          | Structured workflows with quality gates |
 | Context lost between sessions | Persistent memory and learning          |
 | Reinventing the wheel         | Reusable tasks, workflows, and squads   |
@@ -75,7 +77,10 @@ SINAPSE provides orchestrated structure while allowing flexibility in communicat
 
 ## Agents
 
-SINAPSE includes 11 specialized agents, each with a distinct role and personality:
+SINAPSE includes 172 specialized agents across 17 squads. The table below highlights the core development agents:
+
+IDs in the table use Claude Code's `@agent-name` syntax. In Codex, replace it
+with `$sinapse-agent agent-id`; use `$snps` for the primary orchestrator.
 
 | Agent     | ID               | Archetype    | Responsibility          |
 | --------- | ---------------- | ------------ | ----------------------- |
@@ -94,7 +99,7 @@ SINAPSE includes 11 specialized agents, each with a distinct role and personalit
 ### Agent Activation
 
 ```bash
-# Activate an agent using @ syntax
+# Claude Code: activate an agent using @ syntax
 @developer                # Activate Pixel (Developer)
 @quality-gate                 # Activate Litmus (QA)
 @architect          # Activate Stratum (Architect)
@@ -106,6 +111,13 @@ SINAPSE includes 11 specialized agents, each with a distinct role and personalit
 *exit               # Deactivate agent
 ```
 
+Codex activation:
+
+```text
+$snps
+$sinapse-agent developer
+```
+
 ### Agent Context
 
 When an agent is active:
@@ -373,16 +385,15 @@ NODE_ENV=development
 SINAPSE_DEBUG=false
 ```
 
-### IDE Integration
+### Provider Integration
 
-SINAPSE supports multiple IDEs. Configuration is synchronized across:
+SINAPSE synchronizes the same canonical agents for both supported providers:
 
-- Claude Code (`.claude/`)
-- Cursor (`.cursor/`)
-- VS Code (`.vscode/`)
+- Claude Code agents: `.claude/agents/` (activate with `@developer`)
+- Codex agents and skills: `.codex/agents/` and `.agents/skills/` (activate with `$snps` or `$sinapse-agent developer`)
 
 ```bash
-# Sync agents to your IDE
+# Sync Claude Code and Codex adapters
 npm run sync:ide
 ```
 

package/docs/installation/README.md

@@ -76,10 +76,10 @@ npx sinapse-ai@latest update
 
 ## Supported IDEs
 
-| IDE         | Agent Activation    |
-| ----------- | ------------------- |
-| Claude Code | `/dev`, `/qa`, etc. |
-| Codex CLI   | `/skills` flow      |
+| IDE         | Agent Activation                    |
+| ----------- | ----------------------------------- |
+| Claude Code | `@developer`, `@quality-gate`, etc. |
+| Codex CLI   | `$snps` or `$sinapse-agent <id>`    |
 
 ---