sinapse-ai 1.25.1 → 1.25.2

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

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