specrails-core 3.3.0 → 3.4.0

package/docs/migration-guide.md

@@ -11,7 +11,6 @@ Switching is optional. GitHub Issues and JIRA remain fully supported. Local tick
 **Switch to local tickets if:**
 - Your team prefers a simple, zero-dependency setup
 - You want tickets version-controlled alongside your code
-- You use specrails-hub and want the visual ticket panel
 - You don't need GitHub/JIRA for other workflows (project boards, external stakeholders)
 
 **Stay on GitHub Issues / JIRA if:**
@@ -37,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:
@@ -64,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:
@@ -81,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.
@@ -98,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:
@@ -119,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.
@@ -134,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` |

package/docs/research/mcp-feasibility-analysis.md

@@ -45,7 +45,7 @@ npx specrails-core@latest init    →   install.sh (bash)    →   /setup (Claud
 
 ```
 Claude Code
-├── Commands (/sr:implement, /sr:product-backlog, ...)
+├── Commands (/specrails:implement, /specrails:product-backlog, ...)
 ├── Skills (/opsx:new, /opsx:apply, /opsx:ff, ...)
 ├── Agents (sr-architect, sr-developer, sr-reviewer, ...)
 ├── Rules (.claude/rules/ — layer-specific conventions)
@@ -146,7 +146,7 @@ The current architecture tightly couples specrails to Claude Code's command/skil
 │  Specs, Personas, Memory, Config, Analysis   │
 ├─────────────────────────────────────────────┤
 │         Claude Code (Orchestration)          │
-│  /sr:implement, /sr:batch-implement, agents  │
+│  /specrails:implement, /specrails:batch-implement, agents  │
 └─────────────────────────────────────────────┘
 ```
 
@@ -168,7 +168,7 @@ Skills and commands already provide strong Claude Code integration. MCP adds com
 
 #### B. Orchestration Can't Move to MCP
 
-The `/sr:implement` pipeline requires Claude Code's Agent tool (subagent spawning, worktree isolation, background execution). MCP tools are request/response — they can't replicate multi-phase orchestration.
+The `/specrails:implement` pipeline requires Claude Code's Agent tool (subagent spawning, worktree isolation, background execution). MCP tools are request/response — they can't replicate multi-phase orchestration.
 
 **Counter:** This is exactly why the recommendation is scoped. Orchestration stays in Claude Code; only knowledge access moves to MCP.
 
@@ -333,8 +333,8 @@ These capabilities require Claude Code's runtime and should NOT be exposed via M
 
 | Capability | Reason |
 |------------|--------|
-| `/sr:implement` pipeline | Requires Agent tool (subagent spawning) |
-| `/sr:batch-implement` | Requires git worktree isolation |
+| `/specrails:implement` pipeline | Requires Agent tool (subagent spawning) |
+| `/specrails:batch-implement` | Requires git worktree isolation |
 | Agent invocation (sr-*) | Requires Claude Code's Agent subagent system |
 | OpenSpec artifact creation | Interactive, context-heavy (requires conversation) |
 | `/setup` wizard | Multi-step interactive configuration |

package/docs/testing/test-matrix-codex.md

@@ -36,11 +36,10 @@ Epic: [SPEA-505](/SPEA/issues/SPEA-505) — Codex Compatibility Approach B
 
 | Feature | Claude Code | Codex |
 |---------|:-:|:-:|
-| Legacy slash commands `.claude/commands/sr/` | ✅ | ❌ |
+| Legacy slash commands `.claude/commands/specrails/` | ✅ | ❌ |
 | SKILL.md format `.claude/skills/sr-*/` | ✅ | ✅ |
 | `sr:implement` skill | ✅ | ✅ |
 | `sr:product-backlog` skill | ✅ | ✅ |
-| `sr:health-check` skill | ✅ | ✅ |
 | `sr:compat-check` skill | ✅ | ✅ |
 | `sr:why` skill | ✅ | ✅ |
 | `sr:refactor-recommender` skill | ✅ | ✅ |