specrails-core 3.3.0 → 3.4.0

package/docs/user-docs/cli-reference.md

@@ -21,15 +21,15 @@ codex    # Codex
 
 ## Core workflow
 
-### `/sr:implement` ✅ Both
+### `/specrails:implement` ✅ Both
 
 Implement a feature through the full agent pipeline: design → code → tests → docs → review → PR.
 
 ```
-/sr:implement #85
-/sr:implement #85, #71, #63
-/sr:implement "add a health check endpoint"
-/sr:implement UI, Analytics
+/specrails:implement #85
+/specrails:implement #85, #71, #63
+/specrails:implement "add a health check endpoint"
+/specrails:implement UI, Analytics
 ```
 
 **Flags:**
@@ -60,16 +60,16 @@ A single issue runs sequentially on the current branch. Multiple issues run in p
 
 ---
 
-### `/sr:telemetry` ✅ Both
+### `/specrails:telemetry` ✅ Both
 
 Inspect per-agent execution metrics: token usage, estimated API cost, run count, average duration, and success/failure rate.
 
 ```
-/sr:telemetry
-/sr:telemetry --period today
-/sr:telemetry --agent sr-developer
-/sr:telemetry --format json
-/sr:telemetry --save
+/specrails:telemetry
+/specrails:telemetry --period today
+/specrails:telemetry --agent sr-developer
+/specrails:telemetry --format json
+/specrails:telemetry --save
 ```
 
 **Flags:**
@@ -83,14 +83,14 @@ Inspect per-agent execution metrics: token usage, estimated API cost, run count,
 
 ---
 
-### `/sr:merge-resolve` ✅ Both
+### `/specrails:merge-resolve` ✅ Both
 
 Resolve git conflict markers using AI-powered context analysis.
 
 ```
-/sr:merge-resolve
-/sr:merge-resolve --files src/api/routes.ts
-/sr:merge-resolve --context openspec/changes/
+/specrails:merge-resolve
+/specrails:merge-resolve --files src/api/routes.ts
+/specrails:merge-resolve --context openspec/changes/
 ```
 
 **Flags:**
@@ -105,15 +105,15 @@ Reads OpenSpec context bundles from the features that produced each conflict, in
 
 ---
 
-### `/sr:retry` ✅ Both
+### `/specrails:retry` ✅ Both
 
-Resume a failed `/sr:implement` run from the last successful phase.
+Resume a failed `/specrails:implement` run from the last successful phase.
 
 ```
-/sr:retry <feature-name>
-/sr:retry --list
-/sr:retry <feature-name> --from architect
-/sr:retry <feature-name> --dry-run
+/specrails:retry <feature-name>
+/specrails:retry --list
+/specrails:retry <feature-name> --from architect
+/specrails:retry <feature-name> --dry-run
 ```
 
 **Flags:**
@@ -130,15 +130,15 @@ Pipeline state is saved to `.claude/pipeline-state/<feature-name>.json` after ea
 
 ---
 
-### `/sr:batch-implement` ⚠️ Limited on Codex
+### `/specrails:batch-implement` ⚠️ Limited on Codex
 
 Implement multiple independent features in parallel using git worktrees.
 
 ```
-/sr:batch-implement #85, #71, #63
+/specrails:batch-implement #85, #71, #63
 ```
 
-Each feature gets its own worktree, its own agent pipeline, and its own PR. Use this instead of `/sr:implement` with multiple issues when you want explicit control over parallel execution.
+Each feature gets its own worktree, its own agent pipeline, and its own PR. Use this instead of `/specrails:implement` with multiple issues when you want explicit control over parallel execution.
 
 > **Codex note**: Worktree isolation is limited in Codex CLI beta. Prefer Codex Cloud for parallel batch work.
 
@@ -146,26 +146,26 @@ Each feature gets its own worktree, its own agent pipeline, and its own PR. Use
 
 ## Product and backlog
 
-### `/sr:product-backlog` ✅ Both
+### `/specrails:product-backlog` ✅ Both
 
 View your prioritized product backlog, ranked by VPC persona fit and estimated effort.
 
 ```
-/sr:product-backlog
-/sr:product-backlog UI, API
+/specrails:product-backlog
+/specrails:product-backlog UI, API
 ```
 
 Reads GitHub Issues labeled `product-driven-backlog`. Produces a ranked table per area, top 3 recommendations, and a safe implementation order based on issue dependencies.
 
 ---
 
-### `/sr:update-product-driven-backlog` ✅ Both
+### `/specrails:update-product-driven-backlog` ✅ Both
 
 Generate new feature ideas through product discovery and create GitHub Issues.
 
 ```
-/sr:update-product-driven-backlog
-/sr:update-product-driven-backlog UI, API
+/specrails:update-product-driven-backlog
+/specrails:update-product-driven-backlog UI, API
 ```
 
 The Product Manager researches your competitive landscape, generates 2–4 feature ideas per area, and scores each against your user personas. Creates GitHub Issues with full VPC evaluation if write access is available.
@@ -174,85 +174,73 @@ The Product Manager researches your competitive landscape, generates 2–4 featu
 
 ## Analysis and inspection
 
-### `/sr:health-check` ✅ Both
-
-Run a comprehensive codebase quality analysis.
-
-```
-/sr:health-check
-```
-
-Analyzes code quality, test coverage, technical debt, complexity, and dependency health. Compares with previous runs to detect regressions.
-
----
-
-### `/sr:refactor-recommender` ✅ Both
+### `/specrails:refactor-recommender` ✅ Both
 
 Scan the codebase for refactoring opportunities, ranked by impact/effort ratio.
 
 ```
-/sr:refactor-recommender
+/specrails:refactor-recommender
 ```
 
 Identifies duplicates, overly long functions, large files, dead code, outdated patterns, and complex logic. Optionally creates GitHub Issues for tracking.
 
 ---
 
-### `/sr:compat-check` ✅ Both
+### `/specrails:compat-check` ✅ Both
 
 Analyze the backwards-compatibility impact of a proposed change.
 
 ```
-/sr:compat-check #85
-/sr:compat-check #85 --save
+/specrails:compat-check #85
+/specrails:compat-check #85 --save
 ```
 
 Detects removed endpoints, changed method signatures, changed response shapes, and behavioral changes. When breaking changes are found, generates a migration guide.
 
 `--save` updates the stored API baseline so future checks compare against the new surface.
 
-The Architect runs this automatically as part of every `/sr:implement` pipeline.
+The Architect runs this automatically as part of every `/specrails:implement` pipeline.
 
 ---
 
-### `/sr:why` ✅ Both
+### `/specrails:why` ✅ Both
 
 Search agent explanation records in plain language.
 
 ```
-/sr:why "why did we choose this database schema"
-/sr:why "explain the auth middleware design"
-/sr:why "why is pagination implemented this way"
+/specrails:why "why did we choose this database schema"
+/specrails:why "explain the auth middleware design"
+/specrails:why "why is pagination implemented this way"
 ```
 
-Agents write decision rationale to `.claude/agent-memory/explanations/` as they work. `/sr:why` searches these records semantically. Useful for onboarding, code review, and revisiting past decisions.
+Agents write decision rationale to `.claude/agent-memory/explanations/` as they work. `/specrails:why` searches these records semantically. Useful for onboarding, code review, and revisiting past decisions.
 
 ---
 
-### `/sr:vpc-drift` ✅ Both
+### `/specrails:vpc-drift` ✅ Both
 
 Detect when your VPC personas have drifted from what your product actually delivers.
 
 ```
-/sr:vpc-drift
-/sr:vpc-drift --persona "Alex,Sara"
-/sr:vpc-drift --verbose
-/sr:vpc-drift --format json
+/specrails:vpc-drift
+/specrails:vpc-drift --persona "Alex,Sara"
+/specrails:vpc-drift --verbose
+/specrails:vpc-drift --format json
 ```
 
 Compares persona Jobs/Pains/Gains against your backlog, implemented features, and agent memory. Produces a per-persona alignment score and recommendations for updating your VPC.
 
 ---
 
-### `/sr:memory-inspect` ✅ Both
+### `/specrails:memory-inspect` ✅ Both
 
 Inspect and clean up agent memory directories.
 
 ```
-/sr:memory-inspect
-/sr:memory-inspect sr-developer
-/sr:memory-inspect --stale 14
-/sr:memory-inspect --prune
+/specrails:memory-inspect
+/specrails:memory-inspect sr-developer
+/specrails:memory-inspect --stale 14
+/specrails:memory-inspect --prune
 ```
 
 **Flags:**
@@ -266,12 +254,12 @@ Agent memory lives in `.claude/agent-memory/sr-*/` (Claude Code) or `.codex/agen
 
 ---
 
-### `/sr:propose-spec` ✅ Both
+### `/specrails:propose-spec` ✅ Both
 
 Explore a feature idea and produce a structured proposal ready for the OpenSpec pipeline.
 
 ```
-/sr:propose-spec "add rate limiting to the API"
+/specrails:propose-spec "add rate limiting to the API"
 ```
 
 Produces: problem statement, proposed solution, out-of-scope items, acceptance criteria, technical considerations, and a complexity estimate.
@@ -358,14 +346,14 @@ Open-ended thinking mode for brainstorming, investigating problems, or clarifyin
 
 ---
 
-### `/sr:opsx-diff` — Spec Change Diff
+### `/specrails:opsx-diff` — Spec Change Diff
 
 Visualize the before/after diff of an OpenSpec change.
 
 ```
-/sr:opsx-diff <change-name>
-/sr:opsx-diff my-feature --format json
-/sr:opsx-diff my-feature --summary-only
+/specrails:opsx-diff <change-name>
+/specrails:opsx-diff my-feature --format json
+/specrails:opsx-diff my-feature --summary-only
 ```
 
 **Flags:**

package/docs/user-docs/codex-vs-claude-code.md

@@ -12,7 +12,7 @@ SpecRails supports both **OpenAI Codex** and **Anthropic Claude Code** as AI age
 | **CLI** | `claude` | `codex` |
 | **Config directory** | `.claude/` | `.codex/` |
 | **Agent instructions** | `CLAUDE.md` | `AGENTS.md` |
-| **Skills (`/sr:*`, `/opsx:*`)** | ✅ Full support | ✅ Full support |
+| **Skills (`/specrails:*`, `/opsx:*`)** | ✅ Full support | ✅ Full support |
 | **OpenSpec workflow** | ✅ Full support | ✅ Full support |
 | **Parallel worktrees** | ✅ Native | ⚠️ Limited |
 | **Agent definitions** | Markdown frontmatter | TOML |
@@ -27,11 +27,10 @@ SpecRails supports both **OpenAI Codex** and **Anthropic Claude Code** as AI age
 
 ### Skills
 
-SpecRails Skills use `SKILL.md` format, which is shared between Codex and Claude Code. All `/sr:*` and `/opsx:*` skills run identically on both platforms:
+SpecRails Skills use `SKILL.md` format, which is shared between Codex and Claude Code. All `/specrails:*` and `/opsx:*` skills run identically on both platforms:
 
-- `/sr:implement` — full pipeline (design → code → review → PR)
-- `/sr:product-backlog` — VPC-ranked backlog view
-- `/sr:health-check` — codebase quality analysis
+- `/specrails:implement` — full pipeline (design → code → review → PR)
+- `/specrails:product-backlog` — VPC-ranked backlog view
 - `/opsx:ff` — OpenSpec fast-forward
 - All other workflow skills
 
@@ -53,7 +52,7 @@ Both platforms use file-based memory. Claude Code uses `.claude/agent-memory/`.
 
 ### Parallel execution and worktrees
 
-`/sr:batch-implement` (multiple issues in parallel) uses git worktree isolation. On Claude Code this runs locally with full isolation. On Codex:
+`/specrails:batch-implement` (multiple issues in parallel) uses git worktree isolation. On Claude Code this runs locally with full isolation. On Codex:
 
 - **Codex CLI**: Parallel execution is supported but worktree isolation is limited in the current beta. Multiple issues may share a working directory.
 - **Codex Cloud**: Native async parallelism — each task gets an isolated cloud environment. Well-suited for batch work.
@@ -84,10 +83,10 @@ Claude Code and Codex have different non-interactive modes:
 
 ```bash
 # Claude Code
-claude --print "run /sr:implement #42"
+claude --print "run /specrails:implement #42"
 
 # Codex
-codex exec "run /sr:implement #42"
+codex exec "run /specrails:implement #42"
 ```
 
 Skills themselves are the same — only the CLI invocation differs.

package/docs/user-docs/faq.md

@@ -8,26 +8,26 @@ Yes. SpecRails runs on top of Claude Code, which requires an Anthropic account.
 
 **What does the installer actually do to my project?**
 
-It creates a `.claude/` directory with agent templates, commands, and configuration files. It does not modify your source code, create commits, or push anything. Your project is unchanged — `.claude/` is the only addition.
+The plugin method (`claude plugin install sr`) installs logic into Claude Code's plugin system — nothing is added to your project until you run `/specrails:setup`. The scaffold method (`npx specrails-core@latest init`) copies templates into `.claude/`. Neither method modifies your source code, creates commits, or pushes anything.
 
 **Do I need Node.js if my project is not JavaScript?**
 
-Yes. Node 18+ is required to run `npx specrails-core@latest`. Once installed, SpecRails works with any language or framework — the agents adapt to whatever stack your project uses.
+Not for the plugin method (`claude plugin install sr`). Node.js 18+ is only required for the scaffold method (`npx specrails-core@latest init`). Once installed, SpecRails works with any language or framework.
 
 **Do I need GitHub Issues?**
 
-No. SpecRails ships with a built-in local ticket system — no GitHub account required. Local tickets are the default. Commands like `/sr:implement` accept ticket IDs or plain text:
+No. SpecRails ships with a built-in local ticket system — no GitHub account required. Local tickets are the default. Commands like `/specrails:implement` accept ticket IDs or plain text:
 
 ```
-/sr:implement #1, #4
-/sr:implement "add rate limiting to the API"
+/specrails:implement #1, #4
+/specrails:implement "add rate limiting to the API"
 ```
 
-You can switch to GitHub Issues or JIRA during `/setup` (Phase 3) if you prefer.
+You can switch to GitHub Issues or JIRA during `/specrails:setup` (Phase 3) if you prefer.
 
-**How long does /setup take?**
+**How long does /specrails:setup take?**
 
-The full wizard takes about 5 minutes — most of the time is Phase 2 (persona research via web search). For a faster start, use `/setup --lite`: three questions, under a minute, no web research.
+The full wizard takes about 5 minutes — most of the time is Phase 2 (persona research via web search). For a faster start, use `/specrails:setup --lite`: three questions, under a minute, no web research.
 
 ---
 
@@ -35,28 +35,28 @@ The full wizard takes about 5 minutes — most of the time is Phase 2 (persona r
 
 **Can I run SpecRails on an existing project with existing code?**
 
-Yes, that's the intended use case. The `/setup` wizard analyzes your existing codebase — your tech stack, layers, CI commands, and conventions — and generates agents configured specifically for it.
+Yes, that's the intended use case. The `/specrails:setup` wizard analyzes your existing codebase — your tech stack, layers, CI commands, and conventions — and generates agents configured specifically for it.
 
-**Does /sr:implement always create a PR?**
+**Does /specrails:implement always create a PR?**
 
 By default, yes. If you want to preview the changes first without creating commits or a PR, use dry-run mode:
 
 ```
-/sr:implement --dry-run "add dark mode"
+/specrails:implement --dry-run "add dark mode"
 ```
 
 Then apply the cached result when you're ready:
 
 ```
-/sr:implement --apply dark-mode
+/specrails:implement --apply dark-mode
 ```
 
 **What happens if the pipeline fails mid-run?**
 
-SpecRails saves pipeline state after each phase. If a run fails, use `/sr:retry` to resume from the last successful phase instead of starting over:
+SpecRails saves pipeline state after each phase. If a run fails, use `/specrails:retry` to resume from the last successful phase instead of starting over:
 
 ```
-/sr:retry dark-mode
+/specrails:retry dark-mode
 ```
 
 **Can I implement multiple features at once?**
@@ -64,20 +64,20 @@ SpecRails saves pipeline state after each phase. If a run fails, use `/sr:retry`
 Yes. Pass multiple issue numbers or descriptions:
 
 ```
-/sr:implement #42, #43, #44
+/specrails:implement #42, #43, #44
 ```
 
 Each feature gets an isolated git worktree. Pipelines run concurrently and the results are merged automatically at the end.
 
 **Can I customize the agents?**
 
-Yes. After setup, the generated agent files are in `.claude/agents/`. Edit them directly to change behavior, add constraints, or update instructions. Changes take effect on the next run.
+Yes. With the plugin method, edit your project data files in `.specrails/` — personas, rules, config. With the scaffold method, agent files in `.claude/agents/` are also directly editable. Changes take effect on the next run.
 
-For layer-specific coding conventions, edit `.claude/rules/*.md`.
+For layer-specific coding conventions, edit `.specrails/rules/*.md` (plugin) or `.claude/rules/*.md` (scaffold).
 
 **What is a VPC persona?**
 
-VPC stands for Value Proposition Canvas. Personas are structured profiles of your target users with their Jobs (what they're trying to accomplish), Pains (what frustrates them), and Gains (what they want). The Product Manager and Architect use these to make better design decisions. They're generated during `/setup` and stored in `.claude/agents/personas/`.
+VPC stands for Value Proposition Canvas. Personas are structured profiles of your target users with their Jobs (what they're trying to accomplish), Pains (what frustrates them), and Gains (what they want). The Product Manager and Architect use these to make better design decisions. They're generated during `/specrails:setup` and stored in `.specrails/personas/` (plugin) or `.claude/agents/personas/` (scaffold).
 
 ---
 
@@ -85,11 +85,11 @@ VPC stands for Value Proposition Canvas. Personas are structured profiles of you
 
 **Does SpecRails work with monorepos?**
 
-Yes. During `/setup`, the architect detects your monorepo structure and generates separate layer configurations for each package or service.
+Yes. During `/specrails:setup`, the architect detects your monorepo structure and generates separate layer configurations for each package or service.
 
 **Which languages and frameworks are supported?**
 
-SpecRails works with any stack. The agents are general-purpose and adapt based on what `/setup` detects in your codebase. It's been used with Node.js, Python, Go, Ruby, Rust, and mixed-stack projects.
+SpecRails works with any stack. The agents are general-purpose and adapt based on what `/specrails:setup` detects in your codebase. It's been used with Node.js, Python, Go, Ruby, Rust, and mixed-stack projects.
 
 **Does it work with private repositories?**
 
@@ -101,13 +101,19 @@ Yes, for code generation. For features that require GitHub integration (PR creat
 
 **How do I update SpecRails?**
 
-Run the installer again in your project:
+Plugin method:
+
+```bash
+claude plugin update sr
+```
+
+Scaffold method:
 
 ```bash
 npx specrails-core@latest init --root-dir .
 ```
 
-Then re-run `/setup` to regenerate agents with any new templates. See the [updating guide](../updating.md) for details.
+Then re-run `/specrails:setup` to regenerate project data with any new templates. See the [updating guide](../updating.md) for details.
 
 **How do I know which version is installed?**
 
@@ -119,17 +125,17 @@ cat .specrails-version
 
 ## Troubleshooting
 
-**The /setup command isn't available after installing.**
+**The /specrails:setup command isn't available after installing.**
 
-Claude Code loads commands from `.claude/commands/`. Make sure you opened Claude Code from inside your project directory (the one where you ran `npx specrails-core@latest init`).
+For the plugin method: make sure the plugin is installed (`claude plugin list` should show `sr`). For the scaffold method: Claude Code loads commands from `.claude/commands/` — make sure you opened Claude Code from inside your project directory.
 
 **Generated files contain `{{PLACEHOLDER}}` text.**
 
-The `/setup` wizard did not complete all phases. Re-run `/setup` — it will pick up where it left off.
+The `/specrails:setup` wizard did not complete all phases. Re-run `/specrails:setup` — it will pick up where it left off.
 
 **The pipeline created a PR but the CI checks failed.**
 
-The reviewer agent runs your CI suite and attempts to fix failures automatically. If it can't fix them within its budget, it creates the PR with a note describing what failed and why. You can fix the remaining issues manually or run `/sr:retry` to try the reviewer phase again.
+The reviewer agent runs your CI suite and attempts to fix failures automatically. If it can't fix them within its budget, it creates the PR with a note describing what failed and why. You can fix the remaining issues manually or run `/specrails:retry` to try the reviewer phase again.
 
 **I got a "409 Conflict" error during a pipeline run.**
 

package/docs/user-docs/getting-started-codex.md

@@ -64,7 +64,7 @@ The installer detects Codex CLI automatically and generates configuration in `.c
 your-project/
 ├── AGENTS.md                          # SpecRails agent instructions for Codex
 └── .codex/
-    ├── skills/                        # Workflow skills (/sr:*, /opsx:*)
+    ├── skills/                        # Workflow skills (/specrails:*, /opsx:*)
     ├── agents/                        # Agent definitions (TOML)
     ├── rules/                         # Per-layer coding conventions
     ├── agent-memory/                  # Persistent agent memory
@@ -84,13 +84,13 @@ codex
 Then invoke the setup skill:
 
 ```
-/setup
+/specrails:setup
 ```
 
 Or run it non-interactively:
 
 ```bash
-codex exec "run /setup --yes"
+codex exec "run /specrails:setup --yes"
 ```
 
 The wizard runs 5 phases:
@@ -114,13 +114,13 @@ codex
 ```
 
 ```
-/sr:implement "add a health check endpoint"
+/specrails:implement "add a health check endpoint"
 ```
 
 Or with a GitHub issue number:
 
 ```
-/sr:implement #42
+/specrails:implement #42
 ```
 
 This runs the full SpecRails pipeline: Architect → Developer → Reviewer → PR.
@@ -131,7 +131,7 @@ This runs the full SpecRails pipeline: Architect → Developer → Reviewer →
 
 If you prefer the web interface, SpecRails Skills also work in **Codex Cloud** at [chatgpt.com/codex](https://chatgpt.com/codex). Connect your repository and use Skills from the UI.
 
-Note that Codex Cloud runs asynchronously — long-running skills like `/sr:implement` are well-suited to this environment.
+Note that Codex Cloud runs asynchronously — long-running skills like `/specrails:implement` are well-suited to this environment.
 
 ---
 
@@ -186,7 +186,7 @@ The installer warns if SpecRails artifacts already exist. You can merge or abort
 
 ### Placeholders not resolved
 
-If you see `{{PLACEHOLDER}}` in generated files, `/setup` did not complete. Re-run `/setup` or fill the values manually.
+If you see `{{PLACEHOLDER}}` in generated files, `/specrails:setup` did not complete. Re-run `/specrails:setup` or fill the values manually.
 
 ---