sinapse-ai 1.25.0 → 1.25.2

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/ide-integration.md

@@ -5,7 +5,7 @@
 | IDE | Status | Instructions File | Delegation | Skills |
 |-----|--------|------------------|------------|--------|
 | Claude Code | Works | `.claude/CLAUDE.md` | `.claude/rules/mandatory-delegation.md` | `.claude/commands/` |
-| Codex CLI | Limited | `.codex/instructions.md` | `.codex/delegation-matrix.json` | `.codex/skills/` |
+| Codex CLI | Native | `AGENTS.md` | `.codex/delegation-matrix.json` | `.agents/skills/` |
 
 ## Parity Requirements
 
@@ -19,7 +19,7 @@
 - instructions.md with agent activation rules
 - Delegation matrix in `.codex/delegation-matrix.json`
 - Delegation parity in `.codex/delegation-parity.json`
-- Skills in `.codex/skills/`
+- Skills in `.agents/skills/`
 - Agents in `.codex/agents/`
 
 ## Cross-IDE Contracts

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>`    |
 
 ---
 

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)
-│   └── commands/SINAPSE/agents/   # Agent slash commands
+│   ├── 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:**
 
@@ -548,7 +549,11 @@ nvm use 16
 
    ```bash
    # Claude Code
-   ls .claude/commands/SINAPSE/agents/
+   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: Files should be in `.claude/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
@@ -198,7 +198,7 @@ your-project/
 │       ├── integrations/          # PM tool adapters
 │       └── templates/             # Config templates
 ├── .claude/                       # Claude Code configuration
-│   ├── commands/SINAPSE/agents/      # Agent skills
+│   ├── agents/                       # Native Claude agents
 │   └── rules/                     # Agent rules
 ├── docs/                          # Documentation
 │   └── stories/                   # Development stories

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/contributing.md

@@ -149,7 +149,7 @@ Agents sao personas de IA com expertise e comandos especificos.
 > **Cross-IDE parity (Story 10.18)**
 >
 > O diretorio `.sinapse-ai/development/agents/` e a fonte unica de verdade.
-> Ele se espelha automaticamente para `.claude/commands/SINAPSE/agents/` e
+> Ele se espelha automaticamente para `.claude/agents/` e
 > `.codex/agents/` via `npm run sync:ide`. O hook `lint-staged` ja roda o
 > sync quando voce comita um arquivo de agent, mas se voce editar um agent
 > e empurrar sem deixar o lint-staged rodar, o hook `pre-push` BLOQUEIA o

package/docs/pt/guides/development-setup.md

@@ -225,7 +225,7 @@ sinapse-ai/
 │       └── checklists/            # Checklists de produto
 │
 ├── .claude/                       # Configuração do Claude Code
-│   ├── commands/SINAPSE/agents/      # Comandos de skill dos agentes
+│   ├── agents/                       # Agentes nativos do Claude
 │   ├── hooks/                     # Hooks de governança
 │   └── rules/                     # Regras de comportamento da IA
 │
@@ -1112,4 +1112,3 @@ node --inspect node_modules/.bin/jest
 
 _SINAPSE Development Setup Guide v1.0.0_
 _Última Atualização: 2026-01-29_
-