sinapse-ai 1.25.1 → 1.25.3

package/docs/installation/faq.md

@@ -75,11 +75,11 @@ npx sinapse-ai install
 The installer will:
 
 - Create `.sinapse-ai/` directory (framework files)
-- Create IDE configuration (`.claude/`, etc.)
+- Create Claude Code and Codex adapters (`.claude/`, `.codex/`, and `.agents/skills/`)
 - NOT modify your existing source code
 - NOT overwrite existing documentation unless you choose to
 
-**Important:** If you have an existing `.claude/` directory, the installer will ask before modifying.
+**Important:** Existing provider directories are reconciled conservatively; keep custom files outside framework-managed adapter names.
 
 ---
 
@@ -106,26 +106,26 @@ Factors affecting installation time:
 
 **Answer:** SINAPSE creates the following structure:
 
-```
+```text
 your-project/
-├── .sinapse-ai/                 # Framework core (200+ files)
-│   ├── agents/                 # 11+ agent definitions
-│   ├── tasks/                  # 60+ task workflows
-│   ├── templates/              # 20+ document templates
-│   ├── checklists/             # Validation checklists
-│   ├── scripts/                # Utility scripts
-│   └── core-config.yaml        # Framework configuration
+├── .sinapse-ai/                 # Runtime, configuration, and development assets
+│   └── core-config.yaml         # Framework configuration
 │
 ├── .claude/                    # Claude Code (if selected)
-│   └── agents/                    # Native Claude agents
+│   ├── agents/                 # Native Claude agent adapters
+│   └── skills/                 # Claude Code skills
+│
+├── .codex/                     # Codex (if selected)
+│   └── agents/                 # Native Codex agent descriptors
+│
+├── .agents/skills/             # Codex-compatible SINAPSE skills
 │
 ├── docs/                       # Documentation structure
 │   ├── stories/                # Development stories
 │   ├── architecture/           # Architecture docs
 │   └── prd/                    # Product requirements
 │
-└── Squads/            # (if installed)
-    └── squad-brand/             # HybridOps pack
+└── squads/                      # 17 squad definitions and their assets
 ```
 
 ---
@@ -219,8 +219,19 @@ mv .sinapse-ai.backup .sinapse-ai
 # Install once with internet
 npx sinapse-ai install
 
-# Package for offline use
-tar -czvf sinapse-offline.tar.gz .sinapse-ai/ .claude/
+# Package every available component (macOS, Linux, or Git Bash)
+set --
+for path in .sinapse-ai .claude .codex .agents squads; do
+  [ ! -e "$path" ] || set -- "$@" "$path"
+done
+tar -czvf sinapse-offline.tar.gz "$@"
+```
+
+```powershell
+# PowerShell: omit provider directories that are not installed
+$paths = @('.sinapse-ai', '.claude', '.codex', '.agents', 'squads') |
+  Where-Object { Test-Path -LiteralPath $_ }
+tar -czvf sinapse-offline.tar.gz $paths
 ```
 
 **On air-gapped machine:**
@@ -251,7 +262,20 @@ tar -xzvf sinapse-offline.tar.gz
    # Install and package
    npx sinapse-ai install
    cd your-project
-   tar -czvf sinapse-transfer.tar.gz .sinapse-ai/ .claude/ docs/
+
+   # Include every component that exists (macOS, Linux, or Git Bash)
+   set --
+   for path in .sinapse-ai .claude .codex .agents squads docs; do
+     [ ! -e "$path" ] || set -- "$@" "$path"
+   done
+   tar -czvf sinapse-transfer.tar.gz "$@"
+   ```
+
+   ```powershell
+   # PowerShell equivalent
+   $paths = @('.sinapse-ai', '.claude', '.codex', '.agents', 'squads', 'docs') |
+     Where-Object { Test-Path -LiteralPath $_ }
+   tar -czvf sinapse-transfer.tar.gz $paths
    ```
 
 2. **Transfer the archive** via USB, secure transfer, etc.
@@ -273,18 +297,26 @@ tar -xzvf sinapse-offline.tar.gz
 
 **Answer:**
 
-| IDE             | Status       | Agent Activation    |
-| --------------- | ------------ | ------------------- |
-| **Claude Code** | Full Support | `/dev`, `/qa`, etc. |
-| **Codex CLI**   | Limited      | `/skills` flow      |
+| IDE             | Status       | Agent Activation                    |
+| --------------- | ------------ | ----------------------------------- |
+| **Claude Code** | Full Support | `@developer`, `@quality-gate`, etc. |
+| **Codex CLI**   | Full Support | `$snps` or `$sinapse-agent <id>`    |
 
 ---
 
 ### Q12: Can I configure SINAPSE for multiple IDEs?
 
-**Answer:** Yes! Select multiple IDEs during installation:
+**Answer:** Yes. Claude Code and Codex can use the same canonical SINAPSE
+installation. Run `npx sinapse-ai install`; the installer generates the
+provider-native adapters:
+
+- Claude Code agents: `.claude/agents/`
+- Codex agents: `.codex/agents/`
+- Codex skills: `.agents/skills/`
 
-The installer configures supported IDEs automatically. Claude Code uses `.claude/commands/` for agent configuration.
+Activate with `@developer` in Claude Code or `$sinapse-agent developer` in
+Codex. Use `$snps` in Codex when you want the primary orchestrator to route the
+request.
 
 ---
 
@@ -299,7 +331,7 @@ If `.sinapse-ai/` is committed to your repository:
 git clone your-repo
 cd your-repo
 
-# Optionally configure their preferred IDE
+# Generate or reconcile the Claude Code and Codex adapters
 npx sinapse-ai install
 ```
 
@@ -319,55 +351,37 @@ npx sinapse-ai install
 
 ### Q14: What agents are included?
 
-**Answer:** SINAPSE includes 11+ specialized agents:
-
-| Agent           | Role                 | Best For                        |
-| --------------- | -------------------- | ------------------------------- |
-| `dev`           | Full-Stack Developer | Code implementation, debugging  |
-| `qa`            | QA Engineer          | Testing, code review            |
-| `architect`     | System Architect     | Design, architecture decisions  |
-| `pm`            | Project Manager      | Planning, tracking              |
-| `po`            | Product Owner        | Backlog, requirements           |
-| `sm`            | Scrum Master         | Facilitation, sprint management |
-| `analyst`       | Business Analyst     | Requirements analysis           |
-| `ux-expert`     | UX Designer          | User experience design          |
-| `data-engineer` | Data Engineer        | Data pipelines, ETL             |
-| `devops`        | DevOps Engineer      | CI/CD, deployment               |
-| `db-sage`       | Database Architect   | Schema design, queries          |
+**Answer:** SINAPSE includes **172 agents across 17 squads**. The squad layer
+contains 160 members, and the framework layer contains 12. The framework set is:
+
+| Agent | Persona | Role |
+| ----- | ------- | ---- |
+| `snps-orqx` | Imperator | Primary cross-squad orchestrator |
+| `developer` | Pixel | Full-stack implementation and debugging |
+| `quality-gate` | Litmus | Testing, review, and quality gates |
+| `architect` | Stratum | System architecture and technology decisions |
+| `project-lead` | Beacon | Product management and epics |
+| `product-lead` | Axis | Story validation and prioritization |
+| `sprint-lead` | Sync | Story creation and sprint facilitation |
+| `analyst` | Scope | Research and business analysis |
+| `data-engineer` | Tensor | Database design, migrations, and RLS |
+| `ux-design-expert` | Mosaic | UX/UI and design systems |
+| `devops` | Pipeline | CI/CD, exclusive push authority, and releases |
+| `squad-creator` | Loom | Squad creation and extension |
+
+In Claude Code, activate an agent with `@agent-id`. In Codex, use `$snps` for
+routing or `$sinapse-agent agent-id` for direct activation. Both providers
+resolve the same canonical agent and task sources.
 
 ---
 
 ### Q15: How do I create a custom agent?
 
-**Answer:**
-
-1. **Copy an existing agent:**
-
-   ```bash
-   cp .sinapse-ai/agents/developer.md .sinapse-ai/agents/my-agent.md
-   ```
-
-2. **Edit the YAML frontmatter:**
-
-   ```yaml
-   agent:
-     name: MyAgent
-     id: my-agent
-     title: My Custom Agent
-     icon: 🔧
-
-   persona:
-     role: Expert in [your domain]
-     style: [communication style]
-   ```
-
-3. **Add to IDE configuration:**
-
-   ```bash
-   npx sinapse-ai install --ide claude-code
-   ```
-
-4. **Activate:** `/my-agent` or `@my-agent`
+**Answer:** Keep framework agents immutable and create extensions through the
+squad workflow. In Claude Code, activate `@squad-creator`; in Codex, use
+`$sinapse-agent squad-creator`. After the squad definition is validated, run
+`npx sinapse-ai@latest install --reconfigure` to regenerate the selected provider
+adapters from the canonical source.
 
 ---
 
@@ -380,10 +394,10 @@ npx sinapse-ai install
 - Logs all decisions in `.ai/decision-log-{story-id}.md`
 - Can be stopped at any time
 
-**Enable yolo mode:**
+**Enable yolo mode:** Activate `@developer` in Claude Code or
+`$sinapse-agent developer` in Codex, then run:
 
-```bash
-/dev
+```text
 *develop-yolo docs/stories/your-story.md
 ```
 

package/docs/installation/linux.md

@@ -180,8 +180,9 @@ The installer automatically:
 
 - ✅ Detects your Linux distribution and applies optimizations
 - ✅ Creates necessary directories with proper Unix permissions (755/644)
-- ✅ Configures IDE paths for Linux:
-  - Claude: `~/.claude/`
+- ✅ Configures provider adapters in the project:
+  - Claude Code agents: `.claude/agents/`
+  - Codex agents and skills: `.codex/agents/` and `.agents/skills/`
 - ✅ Sets up shell scripts with Unix line endings (LF)
 - ✅ Respects XDG Base Directory specification
 - ✅ Handles symbolic links properly
@@ -190,16 +191,15 @@ The installer automatically:
 
 ## IDE-Specific Setup
 
-### Claude Code (CLI)
+### Claude Code
 
-1. Install Claude Code:
+1. Agent adapters are installed in `.claude/agents/`.
+2. Use `@developer` or another canonical agent ID to activate an agent.
 
-   ```bash
-   npm install -g @anthropic-ai/claude-code
-   ```
+### Codex
 
-2. Commands are installed to `.claude/commands/SINAPSE/`
-3. Use `/agent-name` to activate agents
+1. Agent descriptors are installed in `.codex/agents/`, with skills in `.agents/skills/`.
+2. Use `$snps` for routing or `$sinapse-agent developer` for direct activation.
 
 ---
 
@@ -360,11 +360,8 @@ See the complete [Uninstallation Guide](./uninstallation.md) for detailed steps.
 Quick uninstall:
 
 ```bash
-# Remove SINAPSE from a project
-rm -rf .sinapse-ai .claude/commands/SINAPSE
-
-# Remove global installation
-rm -rf ~/.sinapse-ai-source ~/.npm-global/lib/node_modules/@sinapse
+# Remove SINAPSE through the package-managed uninstaller
+npx sinapse-ai uninstall
 ```
 
 ---

package/docs/installation/macos.md

@@ -73,8 +73,9 @@ The installer automatically:
 
 - ✅ Detects macOS and applies platform-specific configurations
 - ✅ Creates necessary directories with proper permissions
-- ✅ Configures IDE paths for macOS locations:
-  - Claude: `~/.claude/`
+- ✅ Configures provider adapters in the project:
+  - Claude Code agents: `.claude/agents/`
+  - Codex agents and skills: `.codex/agents/` and `.agents/skills/`
 - ✅ Sets up shell scripts with Unix line endings
 - ✅ Handles case-sensitive filesystems properly
 
@@ -82,8 +83,13 @@ The installer automatically:
 
 ### Claude Code
 
-1. Commands are installed to `.claude/commands/SINAPSE/`
-2. Use `/agent-name` to activate agents
+1. Agent adapters are installed in `.claude/agents/`.
+2. Use `@developer` or another canonical agent ID to activate an agent.
+
+### Codex
+
+1. Agent descriptors are installed in `.codex/agents/`, with skills in `.agents/skills/`.
+2. Use `$snps` for routing or `$sinapse-agent developer` for direct activation.
 
 ## Troubleshooting
 

package/docs/installation/troubleshooting.md

@@ -539,7 +539,8 @@ nvm use 16
 
 ### Issue 20: "Agents not appearing in IDE"
 
-**Symptoms:** Agent commands (`/dev`, `@dev`) don't work after installation.
+**Symptoms:** Provider-native activation (`@developer` in Claude Code or
+`$sinapse-agent developer` in Codex) doesn't work after installation.
 
 **Solution:**
 
@@ -549,6 +550,10 @@ nvm use 16
    ```bash
    # Claude Code
    ls .claude/agents/
+
+   # Codex
+   ls .codex/agents/
+   ls .agents/skills/
    ```
 
 3. Check IDE settings allow custom commands
@@ -565,9 +570,10 @@ nvm use 16
 
 **Solution:**
 
-1. Check IDE version is compatible
-2. For Claude Code: Native agent files should be in `.claude/agents/`; `.claude/commands/` is only for slash commands
-3. Restart IDE after installation
+1. Check that the provider version is compatible.
+2. For Claude Code, native agents should be in `.claude/agents/`.
+3. For Codex, check `.codex/agents/` and `.agents/skills/`.
+4. Restart the provider after installation.
 
 ---
 

package/docs/installation/v4-quick-start.md

@@ -107,24 +107,24 @@ Type *help to see available commands.
 
 ## Step 4: Explore Available Agents
 
-| Agent               | Activation        | Purpose                         |
+| Activation          | Role              | Purpose                         |
 | ------------------- | ----------------- | ------------------------------- |
-| `@dev` (Dex)        | Development       | Code implementation, debugging  |
-| `@qa` (Quinn)       | Quality Assurance | Testing and validation          |
-| `@architect` (Aria) | Architecture      | System design and documentation |
-| `@pm` (Sage)        | Product Manager   | Requirements and planning       |
-| `@devops` (Gage)    | DevOps            | Git push, PR creation, CI/CD    |
-| `@po` (Maven)       | Product Owner     | Story creation and backlog      |
-| `@sm` (River)       | Scrum Master      | Sprint management               |
-| `@analyst` (Nova)   | Business Analyst  | Requirements analysis           |
+| `@developer` (Pixel)     | Development       | Code implementation, debugging  |
+| `@quality-gate` (Litmus) | Quality Assurance | Testing and validation          |
+| `@architect` (Stratum)   | Architecture      | System design and documentation |
+| `@project-lead` (Beacon) | Product Manager   | Requirements and planning       |
+| `@devops` (Pipeline)     | DevOps            | Git push, PR creation, CI/CD    |
+| `@product-lead` (Axis)   | Product Owner     | Story validation and backlog    |
+| `@sprint-lead` (Sync)    | Scrum Master      | Sprint management               |
+| `@analyst` (Scope)       | Business Analyst  | Requirements analysis           |
 
 ### Example: Activate Developer Agent
 
-```
-@dev
+```text
+@developer
 ```
 
-The developer agent (Dex) will activate with a greeting showing:
+The developer agent (Pixel) will activate with a greeting showing:
 
 - Project status
 - Quick commands
@@ -188,7 +188,7 @@ your-project/
 │   │   └── quality-gates/         # Quality validation layers
 │   ├── development/               # Development assets
 │   │   ├── agents/                # Agent definitions (12 agents)
-│   │   ├── tasks/                 # Task workflows (~140 tasks)
+│   │   ├── tasks/                 # Development workflows (211 development tasks)
 │   │   └── workflows/             # Multi-step workflows
 │   ├── product/                   # Product assets
 │   │   ├── templates/             # Document templates

package/docs/installation/windows.md

@@ -155,8 +155,9 @@ The installer automatically:
 
 - ✅ Detects Windows and applies platform-specific configurations
 - ✅ Creates necessary directories with proper permissions
-- ✅ Configures IDE paths for Windows locations:
-  - Claude: `%USERPROFILE%\.claude\`
+- ✅ Configures provider adapters in the project:
+  - Claude Code agents: `.claude\agents\`
+  - Codex agents and skills: `.codex\agents\` and `.agents\skills\`
 - ✅ Handles Windows path separators (backslashes)
 - ✅ Configures line endings correctly (CRLF for batch, LF for scripts)
 - ✅ Sets up npm scripts compatible with cmd.exe and PowerShell
@@ -165,16 +166,15 @@ The installer automatically:
 
 ## IDE-Specific Setup
 
-### Claude Code (CLI)
+### Claude Code
 
-1. Install Claude Code:
+1. Agent adapters are installed in `.claude\agents\`.
+2. Use `@developer` or another canonical agent ID to activate an agent.
 
-   ```powershell
-   npm install -g @anthropic-ai/claude-code
-   ```
+### Codex
 
-2. Commands are installed to `.claude\commands\SINAPSE\`
-3. Use `/agent-name` to activate agents
+1. Agent descriptors are installed in `.codex\agents\`, with skills in `.agents\skills\`.
+2. Use `$snps` for routing or `$sinapse-agent developer` for direct activation.
 
 ---
 
@@ -403,12 +403,8 @@ See the complete [Uninstallation Guide](./uninstallation.md) for detailed steps.
 Quick uninstall via PowerShell:
 
 ```powershell
-# Remove SINAPSE from project
-Remove-Item -Recurse -Force .sinapse-ai
-Remove-Item -Recurse -Force .claude\commands\SINAPSE
-
-# Remove global npm packages
-npm uninstall -g @sinapse/sinapse
+# Remove SINAPSE through the package-managed uninstaller
+npx sinapse-ai uninstall
 ```
 
 ---

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

@@ -32,10 +32,11 @@ Isso fornece contexto imediato sobre seu trabalho sem precisar executar manualme
 
 ## Exemplo de Exibição
 
-Quando você ativa um agente (ex: `/dev`), você verá:
+Quando você ativa um agente (`@developer` no Claude Code ou
+`$sinapse-agent developer` no Codex), você verá:
 
-```
-Dex (Builder) ready. Let's build something great!
+```text
+Pixel the Builder ready to innovate!
 
 Current Project Status:
   - Branch: main
@@ -52,24 +53,15 @@ Type *help to see available commands!
 ### Pré-requisitos
 
 - **Repositório Git** - Projeto deve ser inicializado com `git init`
-- **Framework SINAPSE-FullStack** instalado
+- **Framework SINAPSE AI** instalado
 - **Node.js 18+** com pacotes necessários
 
 ### Configuração Inicial
 
-Execute o comando de inicialização via agente @devops:
-
-```bash
-/devops
-*init-project-status
-```
-
-Isso irá:
-1. Detectar seu repositório git
-2. Habilitar `projectStatus` no `core-config.yaml`
-3. Criar arquivo de cache `.sinapse/project-status.yaml`
-4. Adicionar arquivo de cache ao `.gitignore`
-5. Testar a exibição do status
+Nenhum comando de agente é necessário. Nas instalações atuais, `projectStatus`
+fica habilitado em `.sinapse-ai/core-config.yaml` e carrega automaticamente na
+ativação dos agentes. O loader detecta o repositório Git e mantém
+`.sinapse/project-status.yaml` como cache de runtime.
 
 **Configuração Manual Alternativa:**
 
@@ -219,19 +211,24 @@ Mostra apenas stories com status: `InProgress` ou `In Progress`.
 
 ## Agentes Afetados
 
-Todos os 11 agentes SINAPSE exibem status do projeto:
-
-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)
+O SINAPSE inclui 172 agentes especializados em 17 squads. O status de projeto
+é uma capacidade compartilhada do framework; a lista abaixo é o subconjunto
+core de desenvolvimento, não o catálogo completo:
+
+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)
+
+Ative esses IDs com `@agent-id` no Claude Code ou `$sinapse-agent agent-id` no
+Codex; para roteamento principal no Codex, use `$snps`.
 
 ---
 
@@ -247,12 +244,9 @@ Todos os 11 agentes SINAPSE exibem status do projeto:
 3. O arquivo `.sinapse-ai/infrastructure/scripts/project-status-loader.js` existe?
 4. Há erros na saída de ativação do agente?
 
-**Solução:**
-```bash
-# Re-run initialization
-/devops
-*init-project-status
-```
+**Solução:** Execute `npx sinapse-ai@latest doctor`, confirme as verificações
+acima e reinicie a sessão do provider. O status recarrega automaticamente; não
+existe task pointer público `init-project-status` no Codex.
 
 ### Dados de Status Desatualizados
 
@@ -368,28 +362,15 @@ await clearCache();
 
 ### Remoção Completa
 
-Para remover completamente a funcionalidade:
+Não apague scripts, testes ou tasks do framework. Desabilite a funcionalidade
+em `.sinapse-ai/core-config.yaml` e remova somente o cache de runtime:
 
 ```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>
 ```
 
+Defina `projectStatus.enabled: false`; os arquivos protegidos permanecem instalados.
+
 ---
 
 ## Compatibilidade de Versão do Git
@@ -463,7 +444,7 @@ R: Sim, todos os agentes usam o mesmo arquivo de cache (`.sinapse/project-status
 - **Story:** `docs/stories/sinapse migration/story-6.1.2.4-project-status-context.md`
 - **Config:** `.sinapse-ai/core-config.yaml` (seção projectStatus)
 - **Script:** `.sinapse-ai/infrastructure/scripts/project-status-loader.js`
-- **Task de Init:** `.sinapse-ai/tasks/init-project-status.md`
+- **Inicialização:** automática quando `projectStatus.enabled` está habilitado
 - **Testes:** `.sinapse-ai/infrastructure/scripts/__tests__/project-status-loader.test.js`
 
 ---
@@ -471,4 +452,3 @@ R: Sim, todos os agentes usam o mesmo arquivo de cache (`.sinapse/project-status
 **Versão:** 1.0
 **Status:** Pronto para Produção
 **Última Atualização:** 2025-01-14
-