specrails-core 3.3.1 → 3.4.0

package/docs/installation.md

@@ -2,15 +2,26 @@
 
 This guide covers the complete installation process in detail. For the quick version, see [Getting Started](getting-started.md).
 
-## Prerequisites
+## Installation methods
 
-### Required
+SpecRails supports three distribution channels:
+
+| Method | Command | Best for |
+|--------|---------|----------|
+| **Claude Code plugin** (recommended) | `claude plugin install sr` | Most projects — no Node.js required, auto-updates |
+| **Claude Code scaffold** | `npx specrails-core@latest init` | Full offline control, Codex users, custom agent edits |
+| **Codex project** | `npx specrails-core@latest init` | OpenAI Codex CLI users |
+
+---
+
+## Method 1: Claude Code plugin (recommended)
+
+### Prerequisites
 
 | Tool | Why | Install |
 |------|-----|---------|
-| **Node.js 18+** | Required for the installer | [nodejs.org](https://nodejs.org/) or via [nvm](https://github.com/nvm-sh/nvm) |
-| **Git** | SpecRails operates on git repositories | [git-scm.com](https://git-scm.com/) |
 | **Claude Code** | The AI CLI that runs the agents | `npm install -g @anthropic-ai/claude-code` |
+| **Git** | SpecRails operates on git repositories | [git-scm.com](https://git-scm.com/) |
 
 ### Recommended
 
@@ -18,78 +29,81 @@ This guide covers the complete installation process in detail. For the quick ver
 |------|-----|---------|
 | **GitHub CLI** | Auto-create PRs, manage issues | `brew install gh` or [cli.github.com](https://cli.github.com/) |
 
-### Optional
+### Install
 
-| Tool | Why |
-|------|-----|
-| **JIRA CLI** | If using JIRA for backlog instead of GitHub Issues |
-
-The installer checks for all of these and offers to install missing tools.
+```bash
+claude plugin install sr
+```
 
-## Installation
+That's it. No cloning, no npm, no Node.js required.
 
-### From npx (recommended)
+To update the plugin later:
 
 ```bash
-npx specrails-core@latest init --root-dir <your-project>
+claude plugin update sr
 ```
 
-No cloning required. Downloads the latest version and runs the installer automatically.
+### What the plugin contains
 
-### From a local clone
+The plugin bundles the logic layer — agents, skills, commands, hooks, and references. It does **not** touch your project files.
+
+---
+
+## Method 2: Scaffold (npx)
+
+### Prerequisites
+
+| Tool | Why | Install |
+|------|-----|---------|
+| **Node.js 18+** | Required for the installer | [nodejs.org](https://nodejs.org/) or via [nvm](https://github.com/nvm-sh/nvm) |
+| **Git** | SpecRails operates on git repositories | [git-scm.com](https://git-scm.com/) |
+| **Claude Code** or **Codex CLI** | The AI CLI that runs the agents | See [codex-vs-claude-code.md](user-docs/codex-vs-claude-code.md) |
 
-If you prefer to clone the repo first:
+### Install
 
 ```bash
-git clone https://github.com/fjpulidop/specrails-core.git
-./specrails-core/install.sh --root-dir <your-project>
+npx specrails-core@latest init --root-dir <your-project>
 ```
 
-### From curl
+No cloning required. Downloads the latest version and runs the installer automatically.
 
-Alternatively, pipe the installer directly:
+### From a local clone
 
 ```bash
-curl -sL https://raw.githubusercontent.com/fjpulidop/specrails-core/main/install.sh | bash
+git clone https://github.com/fjpulidop/specrails-core.git
+./specrails-core/install.sh --root-dir <your-project>
 ```
 
-> **Important:** Always run the installer from the **target repository** — the project where you want SpecRails installed. If you run it from inside the SpecRails source repo, the installer will detect this and prompt you for the correct target path.
+> **Important:** Always run the installer from the **target repository** — the project where you want SpecRails installed.
 
-### What the installer does
+### What the scaffold installer does
 
-1. **Checks prerequisites** — validates Git, Claude Code; optionally installs npm, gh, OpenSpec
-2. **Detects existing setup** — warns if `.claude/agents/`, `.claude/commands/`, or `openspec/` already exist
+1. **Checks prerequisites** — validates Git, Claude Code; optionally installs npm and gh
+2. **Detects existing setup** — warns if SpecRails artifacts already exist
 3. **Installs artifacts:**
-   - `.claude/commands/setup.md` — the `/setup` wizard
-   - `.claude/setup-templates/` — agent and command templates (temporary, removed after `/setup`)
+   - `.claude/commands/specrails/setup.md` — the `/specrails:setup` wizard
+   - `.claude/setup-templates/` — agent and command templates (temporary, removed after `/specrails:setup`)
    - `.claude/security-exemptions.yaml` — security scanner config
-   - OpenSpec initialization (if CLI available)
 4. **Tracks version** — writes `.specrails-version` and `.specrails-manifest.json`
 
-### What it does NOT do
-
-The installer only copies files. It does not:
-
-- Modify your existing code
-- Create commits
-- Push to any remote
+The scaffold installer only copies files. It does not modify your existing code, create commits, or push to any remote.
 
 ---
 
 ## The Setup Wizard
 
-After installation, open Claude Code in your project and run:
+After either installation method, open Claude Code (or Codex) in your project and run:
 
 ```
-/setup
+/specrails:setup
 ```
 
 There are two modes:
 
 | Mode | Command | When to use |
 |------|---------|-------------|
-| **Full wizard** (default) | `/setup` | Deep stack analysis, researched personas, fully adapted agents — takes 5–10 min |
-| **Lite** | `/setup --lite` | Fastest path — 3 questions, sensible defaults, done in under a minute |
+| **Full wizard** (default) | `/specrails:setup` | Deep stack analysis, researched personas, fully adapted agents — takes 5–10 min |
+| **Lite** | `/specrails:setup --lite` | Fastest path — 3 questions, sensible defaults, done in under a minute |
 
 ---
 
@@ -142,7 +156,23 @@ The wizard fills all templates with your project-specific context:
 - `{{BACKEND_TECH_LIST}}` → your backend technologies
 - Every `{{PLACEHOLDER}}` resolved with real data
 
-**Generated files (full set):**
+**Generated files (full set, plugin method):**
+
+```
+.specrails/
+├── config.yaml               # Stack, CI commands, git workflow
+├── personas/
+│   ├── [persona-1].md        # Your user personas (VPC profiles)
+│   └── [persona-2].md
+├── rules/
+│   ├── backend.md            # Per-layer coding conventions
+│   ├── frontend.md
+│   └── ...
+├── agent-memory/             # Persistent agent knowledge
+└── pipeline/                 # In-flight feature state
+```
+
+**Generated files (full set, scaffold method):**
 
 ```
 .claude/
@@ -179,15 +209,15 @@ The wizard fills all templates with your project-specific context:
 
 The wizard removes itself:
 
-- Deletes `.claude/commands/setup.md`
+- Deletes `.claude/commands/specrails/setup.md`
 - Deletes `.claude/setup-templates/`
 - Leaves only the final generated files
 
-After this phase, `/setup` is no longer available — your workflow is ready.
+After this phase, `/specrails:setup` is no longer available until re-run — your workflow is ready.
 
 ---
 
-### Lite Mode (`/setup --lite`)
+### Lite Mode (`/specrails:setup --lite`)
 
 The quick path — three questions, sensible defaults, done in under a minute.
 
@@ -200,7 +230,7 @@ The quick path — three questions, sensible defaults, done in under a minute.
 | Item | Detail |
 |------|--------|
 | Core agents | sr-architect, sr-developer, sr-reviewer, sr-product-manager |
-| All workflow commands | `/sr:implement`, `/sr:product-backlog`, and 14 more |
+| All workflow commands | `/specrails:implement`, `/specrails:product-backlog`, and 14 more |
 | Backlog storage | Local tickets (`.claude/local-tickets.json`) — no GitHub or JIRA required |
 | CLAUDE.md | Project-level context for agents |
 
@@ -213,13 +243,16 @@ You can run the full wizard later to deepen configuration: personas, stack analy
 After setup, verify everything is in place:
 
 ```bash
-# Check generated agents
+# Plugin method: check generated project data
+ls .specrails/
+
+# Scaffold method: check generated agents
 ls .claude/agents/
 
-# Check for unresolved placeholders (should return nothing)
+# Scaffold method: check for unresolved placeholders (should return nothing)
 grep -r '{{[A-Z_]*}}' .claude/agents/ .claude/commands/ .claude/rules/
 
-# Check version
+# Scaffold method: check version
 cat .specrails-version
 ```
 
@@ -269,7 +302,7 @@ The installer warns if SpecRails artifacts already exist. You can:
 
 ### Placeholders not resolved
 
-If you see `{{PLACEHOLDER}}` in generated files, the `/setup` wizard didn't complete. Re-run `/setup` or manually fill the values.
+If you see `{{PLACEHOLDER}}` in generated files (scaffold method), the `/specrails:setup` wizard didn't complete. Re-run `/specrails:setup` or manually fill the values.
 
 ---
 

package/docs/local-tickets.md

@@ -87,7 +87,7 @@ The file is read and written by specrails-core during command execution.
 
 ## Setup
 
-Local tickets become the default during `/setup`. The wizard prompts:
+Local tickets become the default during `/specrails:setup`. The wizard prompts:
 
 ```
 ## Backlog Provider
@@ -112,8 +112,7 @@ Pressing **Enter** or selecting **1** initializes `.claude/local-tickets.json` w
 To switch providers later, re-run the setup wizard:
 
 ```bash
-npx specrails-core@latest init --root-dir .
-> /setup
+> /specrails:setup
 ```
 
 ---
@@ -147,35 +146,35 @@ Every write increments `revision`. Readers that want to detect external changes
 
 ## Command integration
 
-### `/sr:implement`
+### `/specrails:implement`
 
 Pass local ticket IDs the same way you would GitHub issue numbers:
 
 ```bash
-/sr:implement #1, #4, #7
+/specrails:implement #1, #4, #7
 ```
 
 The command reads each ticket from `local-tickets.json`, extracts metadata (area, effort, description), and tracks the ticket through the pipeline — updating status to `in_progress` on start and `done` on successful completion.
 
-### `/sr:product-backlog`
+### `/specrails:product-backlog`
 
 ```bash
-/sr:product-backlog              # all areas
-/sr:product-backlog UI, Backend  # filter by area
+/specrails:product-backlog              # all areas
+/specrails:product-backlog UI, Backend  # filter by area
 ```
 
 Reads all `todo` and `in_progress` tickets, scores them by VPC match, respects the `prerequisites` dependency graph, and recommends the top 3 for your next sprint.
 
-### `/sr:update-product-driven-backlog`
+### `/specrails:update-product-driven-backlog`
 
 ```bash
-/sr:update-product-driven-backlog            # explore all areas
-/sr:update-product-driven-backlog Analytics  # focus on one area
+/specrails:update-product-driven-backlog            # explore all areas
+/specrails:update-product-driven-backlog Analytics  # focus on one area
 ```
 
 Runs product discovery using your VPC personas. Creates new local tickets for discovered feature ideas, tagged with `source: "product-backlog"` and `labels: ["product-driven-backlog", "area:<area>"]`. Existing tickets are checked for duplicates before creating new ones.
 
-### `/sr:propose-spec`
+### `/specrails:propose-spec`
 
 When a proposal is finalized, a local ticket is created automatically:
 

package/docs/migration-guide.md

@@ -36,7 +36,7 @@ Then initialize the ticket store if it doesn't exist yet:
 
 ```bash
 # Inside Claude Code or Codex
-/sr:implement --setup-local-tickets
+/specrails:implement --setup-local-tickets
 ```
 
 Or create the file manually:
@@ -63,7 +63,7 @@ Use the `sr:migrate-from-github` command (requires `gh` CLI):
 
 ```bash
 # Inside Claude Code
-/sr:migrate-from-github
+/specrails:migrate-from-github
 ```
 
 This command:
@@ -80,13 +80,13 @@ This command:
 To import all open issues regardless of label:
 
 ```bash
-/sr:migrate-from-github --all
+/specrails:migrate-from-github --all
 ```
 
 To do a dry run (preview without writing):
 
 ```bash
-/sr:migrate-from-github --dry-run
+/specrails:migrate-from-github --dry-run
 ```
 
 **After import:** Your GitHub Issues are unchanged. The migration is additive — it only creates local tickets. You can continue using GitHub Issues in parallel until you're ready to stop.
@@ -97,7 +97,7 @@ Use the `sr:migrate-from-jira` command (requires `jira` CLI or REST API credenti
 
 ```bash
 # Inside Claude Code
-/sr:migrate-from-jira
+/specrails:migrate-from-jira
 ```
 
 This command:
@@ -118,11 +118,11 @@ The original JIRA key is preserved in `metadata.jira_key` so you can cross-refer
 
 ## Step 3: Regenerate commands (optional but recommended)
 
-Command templates are generated at `/setup` time with provider-specific instructions baked in. After switching providers, regenerate them so commands use the local file operations instead of GitHub/JIRA CLI calls:
+Command templates are generated at `/specrails:setup` time with provider-specific instructions baked in. After switching providers, regenerate them so commands use the local file operations instead of GitHub/JIRA CLI calls:
 
 ```bash
 npx specrails-core@latest init --root-dir .
-> /setup --update
+> /specrails:setup --update
 ```
 
 The `--update` flag regenerates only the backlog commands (`product-backlog`, `update-product-driven-backlog`, `implement`) without re-running the full stack analysis.
@@ -133,8 +133,8 @@ The `--update` flag regenerates only the backlog commands (`product-backlog`, `u
 
 To revert to GitHub Issues:
 
-1. Edit `.claude/backlog-config.json` and set `"provider": "github"`
-2. Re-run `/setup --update` to regenerate commands
+1. Edit `.specrails/config.yaml` (or `.claude/backlog-config.json` for scaffold installs) and set `provider: github`
+2. Re-run `/specrails:setup --update` to regenerate commands
 3. Your `local-tickets.json` is preserved — switch back any time
 
 Local tickets and external provider data are independent. Switching providers does not delete tickets from either system.

package/docs/playbook-parallel-dev.md

@@ -4,7 +4,7 @@
 
 ## How specrails parallelizes work
 
-When you pass multiple issue numbers to `/sr:batch-implement`, specrails spawns one git worktree per feature. Each worktree has its own branch, its own isolated copy of the working tree, and its own full agent pipeline running concurrently. Features do not queue — they run in parallel from Phase 3a (Architecture) through Phase 5 (PR creation).
+When you pass multiple issue numbers to `/specrails:batch-implement`, specrails spawns one git worktree per feature. Each worktree has its own branch, its own isolated copy of the working tree, and its own full agent pipeline running concurrently. Features do not queue — they run in parallel from Phase 3a (Architecture) through Phase 5 (PR creation).
 
 This is not a simulation of parallelism. Each pipeline is a separate Claude Code session with no shared state. The Architect for issue #71 has no visibility into the Architect for issue #63. Each Developer commits to its own branch. Each Reviewer runs CI independently. The worktrees are merged into the base branch at the end of the batch run.
 
@@ -22,7 +22,7 @@ Not every combination of features is safe to run in parallel. A feature is safe
 
 4. **Wave 1 in the dependency DAG**: the feature has no unimplemented prerequisites. A feature with `Prerequisites: #71` cannot run in the same batch as #71 — it must wait for #71 to ship first.
 
-When in doubt, run `/sr:product-backlog` to see the dependency ordering before composing your batch.
+When in doubt, run `/specrails:product-backlog` to see the dependency ordering before composing your batch.
 
 ## What's not safe
 
@@ -38,10 +38,10 @@ Some combinations look independent but are not:
 
 ## Reading the dependency DAG
 
-Run `/sr:product-backlog` before composing any parallel batch. The output includes a prioritized backlog table with dependency metadata. Wave 1 features — those with no unimplemented prerequisites — are your safe parallel batch candidates.
+Run `/specrails:product-backlog` before composing any parallel batch. The output includes a prioritized backlog table with dependency metadata. Wave 1 features — those with no unimplemented prerequisites — are your safe parallel batch candidates.
 
 ```
-/sr:product-backlog
+/specrails:product-backlog
 
 ┌─ API ──────────────────────────────────────────┐
 │ #  Issue   Score  Effort  Description           │
@@ -72,13 +72,13 @@ Reading the issue bodies:
 #71 and #63 are independent of each other and have no prerequisites. They are Wave 1. Run them in parallel:
 
 ```
-/sr:batch-implement #71, #63
+/specrails:batch-implement #71, #63
 ```
 
 Both pipelines run concurrently. Each produces a PR. After both PRs are merged, #85 is unblocked. Run it alone:
 
 ```
-/sr:implement #85
+/specrails:implement #85
 ```
 
 Attempting to include #85 in the first batch would have caused the Developer for #85 to run without the rate limiting middleware in place, producing code that imports a module that doesn't exist yet.
@@ -103,7 +103,7 @@ After all worktree pipelines complete, specrails attempts to merge each feature
 
 | Pattern | Why it works |
 |---------|-------------|
-| Run `/sr:product-backlog` before composing a batch | Surfaces the dependency DAG so you batch only Wave 1 features |
+| Run `/specrails:product-backlog` before composing a batch | Surfaces the dependency DAG so you batch only Wave 1 features |
 | Keep batches to 2–4 features | Smaller batches reduce conflict surface area and keep the merge step fast |
 | Ensure all specs are approved before starting the batch | Prevents mid-batch spec revisions that invalidate a running pipeline |
 | Sequence database migration features before features that consume the schema | Eliminates the most common class of parallel dev failures |
@@ -117,7 +117,7 @@ After all worktree pipelines complete, specrails attempts to merge each feature
 
 ## What's next?
 
-- [Workflows & Commands](workflows.md) — full reference for `/sr:batch-implement`, `/sr:implement`, and `/sr:product-backlog`
+- [Workflows & Commands](workflows.md) — full reference for `/specrails:batch-implement`, `/specrails:implement`, and `/specrails:product-backlog`
 
 ---
 

package/docs/playbook-product-discovery.md

@@ -45,7 +45,7 @@ The difference is not length — it is specificity. The Architect can produce a
 
 The Product Analyst reads your GitHub Issues labeled `product-driven-backlog` to build the dependency DAG and score your backlog. The issue body structure matters.
 
-**The `Prerequisites:` field** is how you tell the Product Analyst that one issue depends on another. When you run `/sr:product-backlog`, the dependency DAG is built from these declarations. Issues without prerequisites are Wave 1 candidates — safe to implement in parallel. Issues with prerequisites are scheduled after their dependencies complete.
+**The `Prerequisites:` field** is how you tell the Product Analyst that one issue depends on another. When you run `/specrails:product-backlog`, the dependency DAG is built from these declarations. Issues without prerequisites are Wave 1 candidates — safe to implement in parallel. Issues with prerequisites are scheduled after their dependencies complete.
 
 ```
 Prerequisites: #71 (rate limiting middleware must exist before we can display rate limit status)

package/docs/plugin-architecture.md

@@ -0,0 +1,137 @@
+# Plugin Architecture
+
+SpecRails is distributed as a **Claude Code plugin** (`sr`). This document explains what that means, how the plugin relates to your project, and the three available distribution channels.
+
+## Two-layer model
+
+SpecRails separates **logic** (the plugin) from **project data** (your repo).
+
+```
+┌─────────────────────────────────────┐
+│         sr plugin (logic)           │
+│  agents · skills · hooks · refs     │
+│  updated via: claude plugin update  │
+└────────────────┬────────────────────┘
+                 │  /specrails:setup generates
+                 ▼
+┌─────────────────────────────────────┐
+│       .specrails/ (project data)    │
+│  config · personas · rules · memory │
+│  lives in your repo, yours to edit  │
+└─────────────────────────────────────┘
+```
+
+### What lives in the plugin
+
+The plugin contains everything that doesn't change per project:
+
+| Component | Description |
+|-----------|-------------|
+| **Agent prompts** | sr-architect, sr-developer, sr-reviewer, sr-product-manager, and 10 more |
+| **Skills** | OpenSpec skills (`/opsx:*`), workflow commands (`/specrails:*`) |
+| **Hooks** | Pre/post-tool hooks for agent coordination |
+| **References** | Agent reference docs, API patterns, test conventions |
+
+You never edit these directly. To update them, run `claude plugin update sr`.
+
+### What lives in your project (`.specrails/`)
+
+`/specrails:setup` generates ~8–10 files adapted to your specific codebase:
+
+| File | Description |
+|------|-------------|
+| `config.yaml` | Stack overview, CI commands, git workflow, backlog provider |
+| `personas/*.md` | VPC user personas — researched from your domain |
+| `rules/*.md` | Per-layer coding conventions (backend, frontend, etc.) |
+| `agent-memory/` | Persistent agent knowledge — grows across sessions |
+| `pipeline/` | In-flight state for parallel feature builds |
+| `CLAUDE.md` (root) | Project architecture reference for agents |
+
+These files are committed to your repo. They are the "project intelligence" that makes agents adapt to your stack.
+
+## Distribution channels
+
+SpecRails supports three installation paths:
+
+### 1. Claude Code plugin (recommended)
+
+```bash
+claude plugin install sr   # install
+/specrails:setup                  # configure for your project
+claude plugin update sr    # update logic anytime
+```
+
+**Best for:** Most projects. No Node.js required. Plugin updates are one command and don't touch your project data.
+
+### 2. Claude Code scaffold
+
+```bash
+npx specrails-core@latest init --root-dir .   # copy templates
+/specrails:setup                                      # configure
+```
+
+The scaffold copies the full agent+command set into `.claude/` — you own and version those files. Updates require re-running `npx` and re-running `/specrails:setup`.
+
+**Best for:** Teams that want to version the agent prompts themselves, or projects that need full offline control.
+
+### 3. Codex project
+
+```bash
+npx specrails-core@latest init --root-dir .   # same as scaffold
+codex                                          # open Codex
+/specrails:setup                                      # configure
+```
+
+Codex does not support the Claude Code plugin system. Use the scaffold method.
+
+**Best for:** OpenAI Codex CLI users.
+
+## The `/specrails:setup` wizard
+
+`/specrails:setup` is a 5-phase setup wizard that generates your project data. It runs once (or re-runs to regenerate).
+
+| Phase | Output |
+|-------|--------|
+| **1. Analyze** | Detects stack, CI commands, architecture layers |
+| **2. Personas** | Researches domain, generates VPC user personas |
+| **3. Configure** | Backlog provider, git workflow, agent selection |
+| **4. Generate** | Writes `.specrails/config.yaml`, personas, rules, CLAUDE.md |
+| **5. Cleanup** | Removes wizard scaffolding |
+
+Quick mode: `/specrails:setup --lite` — three questions, done in under a minute.
+
+## OpenSpec skills
+
+The `sr` plugin bundles the full OpenSpec skill set. These are available as `/opsx:*` commands:
+
+| Skill | Purpose |
+|-------|---------|
+| `/opsx:ff` | Fast-forward through all change artifacts |
+| `/opsx:apply` | Implement an OpenSpec change |
+| `/opsx:verify` | Verify implementation matches spec |
+| `/opsx:archive` | Archive a completed change |
+| `/opsx:explore` | Explore ideas before writing a spec |
+
+OpenSpec is the structured design layer that powers `/specrails:implement` — the architect uses it to produce a technical design before the developer begins coding.
+
+## Updating
+
+### Update plugin logic
+
+```bash
+claude plugin update sr
+```
+
+Updates agents, skills, hooks, and references. Does not touch `.specrails/` project data.
+
+### Regenerate project data
+
+```bash
+/specrails:setup
+```
+
+Re-runs the wizard and regenerates `.specrails/`. Useful when your stack changes significantly or you want to refresh personas.
+
+---
+
+[← Installation](installation.md) · [Core Concepts →](concepts.md)

package/docs/research/codex-compatibility-analysis.md

@@ -12,7 +12,7 @@
 
 Claude Code y Codex han convergido arquitectónicamente de forma significativa durante 2025–2026. Comparten el mismo formato de Skills (OpenAI adoptó la spec de Anthropic en diciembre 2025), ambos soportan MCP como mecanismo de extensión, ambos usan ficheros Markdown jerárquicos como instrucciones de agente (`AGENTS.md` vs `CLAUDE.md`), y ambos soportan subagentes y ejecución paralela.
 
-El camino de menor resistencia para dar soporte a Codex **no requiere reescribir specrails-core** — requiere refactorizar los comandos `/sr:*` de slash commands Claude Code-only a Skills (formato ya compatible con ambas plataformas), y añadir una capa de abstracción mínima en el instalador.
+El camino de menor resistencia para dar soporte a Codex **no requiere reescribir specrails-core** — requiere refactorizar los comandos `/specrails:*` de slash commands Claude Code-only a Skills (formato ya compatible con ambas plataformas), y añadir una capa de abstracción mínima en el instalador.
 
 | Dimensión | Valoración |
 |-----------|-----------|
@@ -83,7 +83,7 @@ Esta es la finding más importante de la investigación.
 
 OpenAI adoptó en diciembre 2025 el **mismo formato `SKILL.md`** que publicó Anthropic. Esto significa que:
 
-> **Todos los Skills de specrails (`/sr:implement`, `/opsx:ff`, etc.) son compatible con Codex sin cambios de formato.**
+> **Todos los Skills de specrails (`/specrails:implement`, `/opsx:ff`, etc.) son compatible con Codex sin cambios de formato.**
 
 La implicación práctica: si specrails migra sus comandos de workflow de "slash commands Claude Code-only" a "Skills" (lo que en gran medida ya está ocurriendo), esos Skills funcionan en ambas plataformas.
 
@@ -103,12 +103,12 @@ La implicación práctica: si specrails migra sus comandos de workflow de "slash
 
 #### B. Comandos Slash vs Skills
 
-**Estado actual**: Los comandos `/sr:*` son slash commands Claude Code-only, definidos como markdown en `.claude/commands/sr/`. Codex no permite slash commands user-definables.
+**Estado actual**: Los comandos `/specrails:*` son slash commands Claude Code-only, definidos como markdown en `.claude/commands/specrails/`. Codex no permite slash commands user-definables.
 
-**Solución (crítica)**: Los Skills ya son el mecanismo correcto. specrails ya tiene muchos `/sr:*` implementados como Skills (el `.claude/skills/` directory). La migración es convertir los comandos restantes a formato Skill.
+**Solución (crítica)**: Los Skills ya son el mecanismo correcto. specrails ya tiene muchos `/specrails:*` implementados como Skills (el `.claude/skills/` directory). La migración es convertir los comandos restantes a formato Skill.
 
 ```markdown
-# Antes: .claude/commands/sr/implement.md (Claude Code-only)
+# Antes: .claude/commands/specrails/implement.md (Claude Code-only)
 # Después: .claude/skills/sr-implement/SKILL.md (compatible con ambos)
 ```
 
@@ -165,7 +165,7 @@ model = "codex-mini-latest"
 
 #### F. Variables de entorno Claude Code-specific
 
-**Estado actual**: El comando `/sr:implement` detecta `CLAUDE_CODE_ENTRYPOINT` y `CLAUDE_CODE_REMOTE`.
+**Estado actual**: El comando `/specrails:implement` detecta `CLAUDE_CODE_ENTRYPOINT` y `CLAUDE_CODE_REMOTE`.
 
 **Solución**: Abstracción — detectar environment vars de ambas CLIs o usar las propias del runner.
 
@@ -239,7 +239,7 @@ specrails-hub se comunica con specrails-core vía `integration-contract.json`. E
 
 ### Approach B: Skills-First (Recomendado)
 
-**Descripción**: Refactorizar los comandos `/sr:*` como Skills (ya compatibles con ambas plataformas). El core de workflow no depende de la CLI — funciona igual en Claude Code y Codex. La integración de agentes se hace vía Skills y MCP.
+**Descripción**: Refactorizar los comandos `/specrails:*` como Skills (ya compatibles con ambas plataformas). El core de workflow no depende de la CLI — funciona igual en Claude Code y Codex. La integración de agentes se hace vía Skills y MCP.
 
 **Por qué es el approach correcto**:
 - Skills son el mínimo común denominador entre CLIs
@@ -298,7 +298,7 @@ Hay señales claras de que Codex está ganando tracción rápidamente (open sour
 **Proceder con Approach B (Skills-First) como Phase 1, con roadmap hacia Approach A.**
 
 ### Fase 1 — Skills-First (Q2 2026, ~3-4 semanas)
-- Migrar comandos `/sr:*` a Skills format
+- Migrar comandos `/specrails:*` a Skills format
 - Añadir detección de CLI en install.sh
 - Soporte de `.codex/` directory como alternativa a `.claude/`
 - Hub detection layer
@@ -323,7 +323,7 @@ Si el board aprueba proceder:
 1. **Crear epic SPEA-Codex-Support** en specrails-core project
 2. **Asignar al Tech Lead (specrails-core)** el diseño técnico detallado de la abstracción de provider
 3. **Crear subtareas**:
-   - Skills migration completa (`/sr:*` → Skills format)
+   - Skills migration completa (`/specrails:*` → Skills format)
    - install.sh provider detection
    - Hub detection layer
    - Integration testing con Codex CLI
@@ -335,8 +335,8 @@ Si el board aprueba proceder:
 
 | specrails (actual) | Claude Code invocation | Codex invocation |
 |-------------------|----------------------|-----------------|
-| `/sr:implement` | Slash command | Skill (mismo `SKILL.md`) |
-| `/sr:product-backlog` | Slash command | Skill |
+| `/specrails:implement` | Slash command | Skill (mismo `SKILL.md`) |
+| `/specrails:product-backlog` | Slash command | Skill |
 | `/opsx:ff` | Slash command | Skill |
 | `/setup` | Slash command | `codex exec "run setup"` |
 | Agent `sr-architect` | `.claude/agents/sr-architect.md` | `.codex/agents/sr-architect.toml` |