specrails-core 3.3.1 → 3.4.0

package/docs/agents.md

@@ -21,7 +21,7 @@ The result: better quality at every stage, with clear accountability.
 |-|-|
 | **Color** | Blue |
 | **Model** | Opus (creative reasoning) |
-| **Trigger** | `/opsx:explore`, `/sr:update-product-driven-backlog` |
+| **Trigger** | `/opsx:explore`, `/specrails:update-product-driven-backlog` |
 | **Role** | Feature ideation and product strategy |
 
 The Product Manager is the **starting point** of the pipeline. It researches your competitive landscape (via web search), evaluates ideas against your user personas using the VPC framework, and produces prioritized feature recommendations.
@@ -42,7 +42,7 @@ The Product Manager is the **starting point** of the pipeline. It researches you
 |-|-|
 | **Color** | Cyan |
 | **Model** | Haiku (fast, read-only) |
-| **Trigger** | `/sr:product-backlog` |
+| **Trigger** | `/specrails:product-backlog` |
 | **Role** | Backlog analysis and reporting |
 
 The Product Analyst is a **read-only** agent. It reads your backlog, specs, and archived changes to produce structured reports. It never writes code or makes decisions — it just gives you the data.
@@ -62,7 +62,7 @@ The Product Analyst is a **read-only** agent. It reads your backlog, specs, and
 |-|-|
 | **Color** | Green |
 | **Model** | Sonnet |
-| **Trigger** | `/opsx:ff`, `/opsx:continue`, `/sr:implement` (Phase 3a) |
+| **Trigger** | `/opsx:ff`, `/opsx:continue`, `/specrails:implement` (Phase 3a) |
 | **Role** | System design and task breakdown |
 
 The Architect translates **what to build** into **how to build it**. It reads the relevant specs, analyzes the codebase, and produces a detailed implementation design with ordered tasks.
@@ -76,7 +76,7 @@ The Architect translates **what to build** into **how to build it**. It reads th
 - Risks and considerations
 - Backwards compatibility impact report (Phase 6 auto-check against API surface)
 
-The Architect also records decision rationale in `.claude/agent-memory/explanations/` — queryable later with `/sr:why`.
+The Architect also records decision rationale in `.claude/agent-memory/explanations/` — queryable later with `/specrails:why`.
 
 ---
 
@@ -86,7 +86,7 @@ The Architect also records decision rationale in `.claude/agent-memory/explanati
 |-|-|
 | **Color** | Purple |
 | **Model** | Sonnet |
-| **Trigger** | `/opsx:apply`, `/sr:implement` (Phase 3b) |
+| **Trigger** | `/opsx:apply`, `/specrails:implement` (Phase 3b) |
 | **Role** | Full-stack implementation |
 
 The Developer is the **workhorse**. It reads the Architect's design, loads the relevant layer conventions, and writes production-quality code across all layers. It follows a strict process: understand, plan, implement, verify.
@@ -106,7 +106,7 @@ Before starting implementation, the Developer reads any **failure records** from
 |-|-|
 | **Colors** | Purple (backend), Blue (frontend) |
 | **Model** | Sonnet |
-| **Trigger** | `/sr:implement` with parallel pipeline |
+| **Trigger** | `/specrails:implement` with parallel pipeline |
 | **Role** | Layer-specific implementation |
 
 For large full-stack features, SpecRails can split work between **Backend Developer** and **Frontend Developer** running in **parallel git worktrees**. Each has a lighter prompt focused on their stack and runs only the relevant CI checks.
@@ -121,7 +121,7 @@ For large full-stack features, SpecRails can split work between **Backend Develo
 |-|-|
 | **Color** | Cyan |
 | **Model** | Sonnet |
-| **Trigger** | `/sr:implement` (Phase 3c) |
+| **Trigger** | `/specrails:implement` (Phase 3c) |
 | **Role** | Automated test generation |
 
 After the Developer finishes, the Test Writer generates comprehensive tests for the new code. It auto-detects your test framework, reads 3 existing tests to learn your patterns, and targets >80% coverage of new code.
@@ -143,7 +143,7 @@ After the Developer finishes, the Test Writer generates comprehensive tests for
 |-|-|
 | **Color** | Yellow |
 | **Model** | Sonnet |
-| **Trigger** | `/sr:implement` (Phase 3d) |
+| **Trigger** | `/specrails:implement` (Phase 3d) |
 | **Role** | Keep documentation in sync with code |
 
 Doc Sync detects and updates your project's documentation after implementation:
@@ -162,7 +162,7 @@ Doc Sync detects and updates your project's documentation after implementation:
 |-|-|
 | **Color** | Cyan |
 | **Model** | Sonnet |
-| **Trigger** | `/sr:implement` (Phase 4b, parallel) |
+| **Trigger** | `/specrails:implement` (Phase 4b, parallel) |
 | **Role** | Frontend-specific quality audit |
 
 The Frontend Reviewer runs in parallel with the Backend Reviewer during Phase 4b, specializing in client-side concerns that a generalist reviewer might miss.
@@ -180,7 +180,7 @@ The Frontend Reviewer runs in parallel with the Backend Reviewer during Phase 4b
 |-|-|
 | **Color** | Cyan |
 | **Model** | Sonnet |
-| **Trigger** | `/sr:implement` (Phase 4b, parallel) |
+| **Trigger** | `/specrails:implement` (Phase 4b, parallel) |
 | **Role** | Backend-specific quality audit |
 
 The Backend Reviewer runs in parallel with the Frontend Reviewer during Phase 4b, specializing in server-side concerns.
@@ -199,7 +199,7 @@ The Backend Reviewer runs in parallel with the Frontend Reviewer during Phase 4b
 |-|-|
 | **Color** | Orange |
 | **Model** | Sonnet |
-| **Trigger** | `/sr:implement` (Phase 4) |
+| **Trigger** | `/specrails:implement` (Phase 4) |
 | **Role** | Security audit |
 
 The Security Reviewer scans new code for:
@@ -221,7 +221,7 @@ You can suppress known false positives via `.claude/security-exemptions.yaml`.
 |-|-|
 | **Color** | Red |
 | **Model** | Sonnet |
-| **Trigger** | `/sr:implement` (Phase 4b), after all developers complete |
+| **Trigger** | `/specrails:implement` (Phase 4b), after all developers complete |
 | **Role** | Final quality gate |
 
 The Reviewer is the **last agent before ship**. It:
@@ -251,7 +251,7 @@ The Reviewer is the **last agent before ship**. It:
 |-|-|
 | **Color** | Yellow |
 | **Model** | Sonnet |
-| **Trigger** | `/sr:merge-resolve`, `/sr:implement` (Phase 4a, after worktree merge) |
+| **Trigger** | `/specrails:merge-resolve`, `/specrails:implement` (Phase 4a, after worktree merge) |
 | **Role** | AI-powered merge conflict resolution |
 
 When a multi-feature pipeline merges worktrees and produces conflict markers, the Merge Resolver analyzes each conflict block using the OpenSpec context bundles from both features. It applies resolutions where confidence is high enough and leaves clean markers for the conflicts it cannot safely resolve.
@@ -273,7 +273,7 @@ When a multi-feature pipeline merges worktrees and produces conflict markers, th
 |-|-|
 | **Color** | Yellow |
 | **Model** | Sonnet |
-| **Trigger** | `/sr:implement` (Phase 4, after Security Reviewer) |
+| **Trigger** | `/specrails:implement` (Phase 4, after Security Reviewer) |
 | **Role** | Performance regression detection |
 
 The Performance Reviewer benchmarks modified code paths after implementation, compares metrics against configured thresholds, and outputs a structured report. It never fixes code — findings above the threshold trigger the Developer to address them before the pipeline continues.
@@ -301,7 +301,7 @@ Every agent stores observations in `.claude/agent-memory/<agent>/MEMORY.md`. Thi
 └── ...
 ```
 
-Memory is automatic — you don't need to manage it. Agents read relevant memories at the start of each task and write new observations as they work. Use `/sr:why` to search the explanations directory in plain language.
+Memory is automatic — you don't need to manage it. Agents read relevant memories at the start of each task and write new observations as they work. Use `/specrails:why` to search the explanations directory in plain language.
 
 ## What's next?
 

package/docs/changelog.md

@@ -8,8 +8,8 @@ All notable changes to SpecRails are listed here, newest first.
 
 ### New commands
 
-- **`/sr:merge-conflict`** — Smart merge conflict resolver. Analyzes conflict context, understands intent of both sides, and proposes the correct resolution with an explanation.
-- **`/sr:refactor-recommender` (enhanced)** — Now includes VPC context-aware scoring: debt items are ranked against persona Jobs/Pains/Gains for product-aligned prioritization.
+- **`/specrails:merge-conflict`** — Smart merge conflict resolver. Analyzes conflict context, understands intent of both sides, and proposes the correct resolution with an explanation.
+- **`/specrails:refactor-recommender` (enhanced)** — Now includes VPC context-aware scoring: debt items are ranked against persona Jobs/Pains/Gains for product-aligned prioritization.
 
 ### Agents
 
@@ -41,8 +41,8 @@ All notable changes to SpecRails are listed here, newest first.
 
 ### New commands
 
-- **`/sr:opsx-diff`** — Change diff visualizer. Shows a structured, human-readable diff of what changed between two points in time across agents, commands, and templates.
-- **`/sr:telemetry`** — Agent telemetry and cost tracking. Reports per-agent token usage, run counts, and cost estimates with trend analysis.
+- **`/specrails:opsx-diff`** — Change diff visualizer. Shows a structured, human-readable diff of what changed between two points in time across agents, commands, and templates.
+- **`/specrails:telemetry`** — Agent telemetry and cost tracking. Reports per-agent token usage, run counts, and cost estimates with trend analysis.
 
 ### Agents
 
@@ -54,8 +54,8 @@ All notable changes to SpecRails are listed here, newest first.
 
 ### New commands
 
-- **`/sr:vpc-drift`** — Detects when your VPC personas have drifted from what your product actually delivers. Compares persona Jobs/Pains/Gains against the backlog and agent memory; produces per-persona alignment scores and concrete update recommendations.
-- **`/sr:memory-inspect`** — Inspect and manage agent memory directories. Shows per-agent stats, recent entries, and stale file detection with optional pruning.
+- **`/specrails:vpc-drift`** — Detects when your VPC personas have drifted from what your product actually delivers. Compares persona Jobs/Pains/Gains against the backlog and agent memory; produces per-persona alignment scores and concrete update recommendations.
+- **`/specrails:memory-inspect`** — Inspect and manage agent memory directories. Shows per-agent stats, recent entries, and stale file detection with optional pruning.
 
 ---
 
@@ -63,7 +63,7 @@ All notable changes to SpecRails are listed here, newest first.
 
 ### New commands
 
-- **`/sr:retry`** — Smart failure recovery. Resumes a failed `/sr:implement` pipeline from the last successful phase without restarting from scratch. Reads saved pipeline state to identify what completed, then re-executes only the remaining phases.
+- **`/specrails:retry`** — Smart failure recovery. Resumes a failed `/specrails:implement` pipeline from the last successful phase without restarting from scratch. Reads saved pipeline state to identify what completed, then re-executes only the remaining phases.
 
 ### Agents
 
@@ -75,7 +75,7 @@ All notable changes to SpecRails are listed here, newest first.
 
 ### Improvements
 
-- **`/sr:health-check` extended with static code analysis** — Now includes complexity metrics, dead code detection, and architectural pattern analysis in addition to test coverage and dependency health.
+- **`/specrails:health-check` extended with static code analysis** — Now includes complexity metrics, dead code detection, and architectural pattern analysis in addition to test coverage and dependency health.
 
 ---
 
@@ -107,7 +107,7 @@ Initial stable release.
 
 ### ⚠ Breaking changes
 
-All commands renamed from `/<name>` to `/sr:<name>`. All agent files renamed from `<name>.md` to `sr-<name>.md`. Existing installations are auto-migrated by `update.sh`.
+All commands renamed from `/<name>` to `/specrails:<name>`. All agent files renamed from `<name>.md` to `sr-<name>.md`. Existing installations are auto-migrated by `update.sh`.
 
 ### What shipped in 1.0
 
@@ -117,17 +117,17 @@ All commands renamed from `/<name>` to `/sr:<name>`. All agent files renamed fro
 - Security Reviewer, Doc Sync, Product Analyst
 
 **11 commands**
-- `/sr:implement` — full 8-phase pipeline (architecture → code → tests → docs → review → PR)
-- `/sr:batch-implement` — parallel multi-feature orchestrator using git worktrees
-- `/sr:health-check` — codebase quality dashboard with regression detection
-- `/sr:compat-check` — backwards compatibility analyzer and migration guide generator
-- `/sr:product-backlog` — VPC-scored backlog view with safe implementation ordering
-- `/sr:update-product-driven-backlog` — AI-powered product discovery via personas
-- `/sr:refactor-recommender` — tech debt scanner ranked by impact/effort
-- `/sr:why` — semantic search over agent decision records
-- `/sr:retry` — smart failure recovery (added in 1.3)
-- `/sr:vpc-drift` — persona drift detection (added in 1.4)
-- `/sr:propose-spec` — structured feature proposal generator
+- `/specrails:implement` — full 8-phase pipeline (architecture → code → tests → docs → review → PR)
+- `/specrails:batch-implement` — parallel multi-feature orchestrator using git worktrees
+- `/specrails:health-check` — codebase quality dashboard with regression detection
+- `/specrails:compat-check` — backwards compatibility analyzer and migration guide generator
+- `/specrails:product-backlog` — VPC-scored backlog view with safe implementation ordering
+- `/specrails:update-product-driven-backlog` — AI-powered product discovery via personas
+- `/specrails:refactor-recommender` — tech debt scanner ranked by impact/effort
+- `/specrails:why` — semantic search over agent decision records
+- `/specrails:retry` — smart failure recovery (added in 1.3)
+- `/specrails:vpc-drift` — persona drift detection (added in 1.4)
+- `/specrails:propose-spec` — structured feature proposal generator
 
 **Pipeline Monitor (web-manager)**
 - Real-time job queue dashboard

package/docs/concepts.md

@@ -153,17 +153,17 @@ Before starting implementation, the Developer reads matching failure records as
 
 The Architect, Developer, and Reviewer record **decision rationale** in `.claude/agent-memory/explanations/` as they work. These records capture the "why" behind implementation choices — which library was chosen and why, which trade-off was accepted, which alternative was rejected.
 
-Use `/sr:why` to search this memory in plain language:
+Use `/specrails:why` to search this memory in plain language:
 
 ```
-/sr:why "why did we switch to event sourcing"
+/specrails:why "why did we switch to event sourcing"
 ```
 
 This gives you an audit trail from product decision to implementation choice, without digging through git history or asking the original author.
 
 ## Dependency-Aware Ordering
 
-When `/sr:product-backlog` is run, the Product Analyst parses `Prerequisites:` fields from GitHub Issue bodies and builds a **dependency DAG** (directed acyclic graph). It then:
+When `/specrails:product-backlog` is run, the Product Analyst parses `Prerequisites:` fields from GitHub Issue bodies and builds a **dependency DAG** (directed acyclic graph). It then:
 
 1. Detects cycles and reports them as errors (circular dependencies block ordering)
 2. Computes a safe implementation order via topological sort

package/docs/customization.md

@@ -4,7 +4,20 @@ Everything SpecRails generates is editable markdown. Here's how to adapt it to y
 
 ## What gets generated
 
-After running `/setup`, your `.claude/` directory looks like this:
+After running `/specrails:setup`, your project data lives in `.specrails/` (plugin method) or `.claude/` (scaffold method):
+
+**Plugin method — `.specrails/`**
+
+```
+.specrails/
+├── config.yaml           # Stack, CI commands, git workflow
+├── personas/             # VPC user personas
+├── rules/                # Per-layer conventions
+├── agent-memory/         # Persistent agent memory
+└── pipeline/             # In-flight feature state
+```
+
+**Scaffold method — `.claude/`**
 
 ```
 .claude/
@@ -17,7 +30,7 @@ After running `/setup`, your `.claude/` directory looks like this:
 └── security-exemptions.yaml
 ```
 
-All files are standard Markdown or JSON/YAML. Edit them directly — no special tools needed.
+All files are standard Markdown or YAML. Edit them directly — no special tools needed.
 
 ## Agents
 
@@ -228,13 +241,13 @@ Both agents run in parallel during Phase 4b and feed their findings into the gen
 
 ## Backwards compatibility baseline
 
-Use `/sr:compat-check --save` to snapshot your current API surface as a baseline:
+Use `/specrails:compat-check --save` to snapshot your current API surface as a baseline:
 
 ```
-/sr:compat-check --save
+/specrails:compat-check --save
 ```
 
-This writes the current API surface to `.claude/compat-baseline.json`. Future runs of `/sr:compat-check` and the Architect's Phase 6 auto-check compare against this baseline to detect breaking changes. Re-run `--save` after any intentional breaking release to advance the baseline.
+This writes the current API surface to `.claude/compat-baseline.json`. Future runs of `/specrails:compat-check` and the Architect's Phase 6 auto-check compare against this baseline to detect breaking changes. Re-run `--save` after any intentional breaking release to advance the baseline.
 
 ---
 

package/docs/deployment.md

@@ -6,16 +6,30 @@ SpecRails runs locally — no cloud infrastructure required. Choose the setup th
 
 | Option | Best for | Setup time |
 |--------|----------|------------|
-| [Local (npx)](#local-npx) | Quick start, individual developers | ~2 minutes |
+| [Plugin](#plugin-recommended) | Quick start, individual developers | ~1 minute |
+| [Local (npx)](#local-npx) | Scaffold/Codex, full offline control | ~2 minutes |
 | [Local (git clone)](#local-git-clone) | Customization, contributing | ~5 minutes |
 | [Docker](#docker) | Reproducible environments, teams | ~5 minutes |
 | [CI/CD](#cicd-github-actions) | Automated workflows, GitHub Actions | ~10 minutes |
 
 ---
 
+## Plugin (recommended)
+
+The fastest way to get started. No Node.js required.
+
+```bash
+claude plugin install sr
+/specrails:setup
+```
+
+**Requirements:** Claude Code, git
+
+---
+
 ## Local — npx
 
-The fastest way to get started. No install required.
+For Codex users or when you need full control over agent files.
 
 ```bash
 npx specrails-core@latest init --root-dir .
@@ -23,10 +37,11 @@ npx specrails-core@latest init --root-dir .
 
 This will:
 1. Scaffold a `.claude/` directory in your project
-2. Install the default agent set
-3. Run the `/setup` wizard to configure your preferences
+2. Install agent templates and the `/specrails:setup` wizard
+
+After install, open Claude Code or Codex and run `/specrails:setup` to configure.
 
-**Requirements:** Node.js ≥18, Claude API key
+**Requirements:** Node.js ≥18, Claude Code or Codex CLI
 
 ---
 

package/docs/getting-started.md

@@ -12,7 +12,6 @@ Think of it as hiring a full engineering team that lives inside your CLI.
 
 You need:
 
-- **Node.js 18+** — required for the installer (`node --version` to check)
 - **Git** — your project must be a git repository
 - **[Claude Code](https://claude.ai/claude-code)** — Anthropic's CLI tool
 
@@ -20,53 +19,43 @@ Optional (recommended):
 
 - **[GitHub CLI](https://cli.github.com/)** (`gh`) — for automatic PR creation and issue tracking
 
-> **Using OpenAI Codex instead of Claude Code?** See [Installation](user-docs/installation.md) for Codex-specific setup.
+> **Using OpenAI Codex instead of Claude Code?** See [getting-started-codex.md](user-docs/getting-started-codex.md) for Codex-specific setup.
 
 ## Install
 
-Pick your preferred method:
-
-**npx (recommended)**
+**Plugin method (recommended) — no Node.js required**
 
 ```bash
-npx specrails-core@latest init --root-dir <your-project>
+claude plugin install sr
 ```
 
-**git clone**
+**Scaffold method (for Codex users or full offline control)**
 
 ```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>
 ```
 
-The installer will:
-
-1. Check your prerequisites
-2. Copy templates and commands into `.claude/`
-3. Initialize OpenSpec (if available)
-4. Track the installed version for future updates
-
-> **Note:** Run this from the repo where you want SpecRails — not from the SpecRails source repo itself.
+See [installation.md](installation.md) for full details on both methods and when to use each.
 
 ## Run the Setup Wizard
 
 Open Claude Code in your project and run:
 
 ```
-/setup
+/specrails:setup
 ```
 
-By default, `/setup` runs the **full 5-phase wizard** — deep stack analysis, researched user personas, and fully adapted agents.
+By default, `/specrails:setup` runs the **full 5-phase wizard** — deep stack analysis, researched user personas, and fully adapted agents.
 
 | Phase | What happens |
 |-------|-------------|
 | **1. Analyze** | Detects your tech stack, architecture layers, CI commands, and conventions |
 | **2. Personas** | Researches your competitive landscape and generates full VPC user personas |
 | **3. Configure** | Asks about your backlog provider, git workflow, and which agents to enable |
-| **4. Generate** | Fills all templates with your project-specific context |
-| **5. Cleanup** | Removes the wizard and templates, leaving only your tailored workflow files |
+| **4. Generate** | Generates your project data files (`.specrails/`) with project-specific context |
+| **5. Cleanup** | Removes the wizard scaffolding, leaving only your tailored workflow files |
 
-**In a hurry?** Run `/setup --lite` for the quick version: three questions, sensible defaults, done in under a minute.
+**In a hurry?** Run `/specrails:setup --lite` for the quick version: three questions, sensible defaults, done in under a minute.
 
 | Question | What it configures |
 |----------|-------------------|
@@ -76,14 +65,14 @@ By default, `/setup` runs the **full 5-phase wizard** — deep stack analysis, r
 
 Lite mode installs the four core agents (architect, developer, reviewer, product manager), all workflow commands, and local ticket storage. You can run the full wizard later to deepen the configuration.
 
-After either mode, your `.claude/` directory contains adapted agents, commands, and rules — ready to use.
+After either mode, your project data files are ready to use and your `/specrails:*` commands are live.
 
 ## Your first feature
 
 Let's implement something. Pick an issue from your backlog, or describe a feature:
 
 ```
-/sr:implement "add a health check endpoint"
+/specrails:implement "add a health check endpoint"
 ```
 
 SpecRails will:
@@ -102,9 +91,9 @@ That's it. One command, full pipeline.
 
 Once you have a feature running, a few commands help you understand what's happening and why:
 
-- `/sr:why "question"` — search agent explanation records in plain language. Ask why a design decision was made, why a library was chosen, or why a particular pattern is used. Agents record their reasoning as they work.
-- `/sr:product-backlog` — see your prioritized backlog with safe implementation ordering. Good first stop before picking what to build next.
-- `/sr:compat-check #N` — check whether an issue's implementation would break existing API consumers before you commit to it.
+- `/specrails:why "question"` — search agent explanation records in plain language. Ask why a design decision was made, why a library was chosen, or why a particular pattern is used. Agents record their reasoning as they work.
+- `/specrails:product-backlog` — see your prioritized backlog with safe implementation ordering. Good first stop before picking what to build next.
+- `/specrails:compat-check #N` — check whether an issue's implementation would break existing API consumers before you commit to it.
 
 ## What's next?