specrails-core 3.3.1 → 3.4.0

package/README.md

@@ -12,10 +12,11 @@
 One command gives your repo a full team of specialized AI agents: architect, developer, reviewer, product manager — all working together through a structured pipeline, fully adapted to your codebase.
 
 ```bash
-npx specrails-core@latest init --root-dir .
+claude plugin install sr   # Claude Code plugin (recommended)
+/specrails:setup                  # configure for your project
 ```
 
-> **Requirements:** [Claude Code](https://docs.anthropic.com/en/docs/claude-code) or [Codex CLI](https://github.com/openai/codex) (choose one), Node 18+, git
+> **Requirements:** [Claude Code](https://docs.anthropic.com/en/docs/claude-code) or [Codex CLI](https://github.com/openai/codex) (choose one), git
 
 ---
 
@@ -26,7 +27,7 @@ Idea  →  Architecture  →  Implementation  →  Review  →  PR
          (sr-architect)   (sr-developer)    (sr-reviewer)
 ```
 
-Run `/sr:implement "add dark mode"` — the pipeline designs, builds, reviews, and ships a pull request. No hand-holding required.
+Run `/specrails:implement "add dark mode"` — the pipeline designs, builds, reviews, and ships a pull request. No hand-holding required.
 
 Every artifact (agents, rules, personas) is generated **specifically for your project** by analyzing your actual codebase, tech stack, and CI setup. Not generic templates.
 
@@ -34,44 +35,69 @@ Every artifact (agents, rules, personas) is generated **specifically for your pr
 
 ## Quick start
 
-**1. Install**
+### Claude Code plugin (recommended)
 
 ```bash
-npx specrails-core@latest init --root-dir .
+claude plugin install sr   # install the sr plugin
+/specrails:setup                  # run the 5-phase wizard (~5 min)
 ```
 
-**2. Run setup inside your AI CLI**
+Updates automatically: `claude plugin update sr`
+
+### Scaffold method (alternative)
 
 ```bash
-claude      # Claude Code
-# or
-codex       # OpenAI Codex (beta)
-> /setup    # run the 5-phase wizard (~5 min)
+npx specrails-core@latest init --root-dir .   # copy project files
+/specrails:setup                                      # run the wizard
 ```
 
-**3. Start building**
+### Start building
 
 ```bash
-> /sr:implement "add user authentication"
-> /sr:implement #1, #2                 # from local tickets (default)
-> /sr:implement #42, #43               # from GitHub Issues (if configured)
-> /sr:update-product-driven-backlog    # discover new features with AI
+> /specrails:implement "add user authentication"
+> /specrails:implement #1, #2                 # from local tickets (default)
+> /specrails:implement #42, #43               # from GitHub Issues (if configured)
+> /specrails:update-product-driven-backlog    # discover new features with AI
 ```
 
 That's it. The pipeline takes over.
 
 ---
 
+## Plugin vs scaffold
+
+| | Plugin | Scaffold |
+|--|--------|---------|
+| **What it contains** | Agents, skills, hooks, references | Nothing — project data only |
+| **Install** | `claude plugin install sr` | `npx specrails-core@latest init` |
+| **Updates** | `claude plugin update sr` | Re-run npx |
+| **Project data** | Generated by `/specrails:setup` into `.specrails/` | Same |
+| **Use case** | Recommended for most projects | When you need full offline control |
+
+The plugin contains the logic (agent prompts, skills, commands). Running `/specrails:setup` generates the project-specific data files (~8–10 files in `.specrails/`) — config, personas, memory, pipeline state. These are yours to edit and commit.
+
+---
+
 ## What gets installed
 
+### Plugin (logic — auto-updated via `claude plugin update sr`)
+
+| Category | Location | Purpose |
+|----------|----------|---------|
+| **Agents** | Plugin | 14 specialized AI agents |
+| **Commands** | Plugin | 17 workflow commands: `/specrails:implement`, `/specrails:product-backlog`, `/specrails:why`, and more |
+| **Skills** | Plugin | OpenSpec skills (`/opsx:*`) included |
+| **Hooks & References** | Plugin | Agent hooks, reference docs |
+
+### Project data (generated by `/specrails:setup` — lives in your repo)
+
 | Category | Files | Purpose |
 |----------|-------|---------|
-| **Agents** | `.claude/agents/*.md` | 14 specialized AI agents |
-| **Personas** | `.claude/agents/personas/*.md` | VPC user profiles, generated from your users |
-| **Commands** | `.claude/commands/sr/*.md` | 17 workflow commands: `/sr:implement`, `/sr:product-backlog`, `/sr:why`, and more |
-| **Rules** | `.claude/rules/*.md` | Per-layer coding conventions, loaded by file path |
-| **Memory** | `.claude/agent-memory/` | Persistent knowledge — agents learn across sessions |
-| **Config** | `.claude/settings.json`, `CLAUDE.md` | Permissions, architecture reference |
+| **Config** | `.specrails/config.yaml` | Stack, CI commands, git workflow |
+| **Personas** | `.specrails/personas/*.md` | VPC user profiles, generated from your users |
+| **Rules** | `.specrails/rules/*.md` | Per-layer coding conventions |
+| **Memory** | `.specrails/agent-memory/` | Persistent knowledge — agents learn across sessions |
+| **Pipeline state** | `.specrails/pipeline/` | In-flight feature state for parallel builds |
 
 ---
 
@@ -113,12 +139,12 @@ SpecRails is not a chat interface. It's a **development pipeline** that coordina
 
 ## Commands
 
-### `/sr:implement` — Build features
+### `/specrails:implement` — Build features
 
 ```bash
-/sr:implement "add dark mode"        # from a description
-/sr:implement #85, #71               # from GitHub Issues
-/sr:implement UI, Analytics          # explore areas, pick the best ideas
+/specrails:implement "add dark mode"        # from a description
+/specrails:implement #85, #71               # from GitHub Issues
+/specrails:implement UI, Analytics          # explore areas, pick the best ideas
 ```
 
 Architect designs → developer builds → reviewer validates → PR created. Multiple features run in parallel with git worktrees.
@@ -128,8 +154,8 @@ Architect designs → developer builds → reviewer validates → PR created. Mu
 Not ready to commit? Run the full pipeline without touching git or GitHub:
 
 ```bash
-/sr:implement "add dark mode" --dry-run
-/sr:implement #85 --preview            # --preview is an alias for --dry-run
+/specrails:implement "add dark mode" --dry-run
+/specrails:implement #85 --preview            # --preview is an alias for --dry-run
 ```
 
 All agents run normally. Generated files land in `.claude/.dry-run/<feature-name>/` instead of your working tree. No branches, commits, PRs, or issue updates are created.
@@ -137,7 +163,7 @@ All agents run normally. Generated files land in `.claude/.dry-run/<feature-name
 When you're happy with the preview, apply the cached output:
 
 ```bash
-/sr:implement --apply add-dark-mode    # copies files to real paths, then ships
+/specrails:implement --apply add-dark-mode    # copies files to real paths, then ships
 ```
 
 To discard without applying:
@@ -146,20 +172,20 @@ To discard without applying:
 rm -rf .claude/.dry-run/add-dark-mode/
 ```
 
-### `/sr:product-backlog` — View prioritized backlog
+### `/specrails:product-backlog` — View prioritized backlog
 
 ```bash
-/sr:product-backlog                  # show all areas
-/sr:product-backlog UI, Decks        # filter by area
+/specrails:product-backlog                  # show all areas
+/specrails:product-backlog UI, Decks        # filter by area
 ```
 
 Reads your tickets (local or GitHub Issues), scores by VPC persona match, recommends top 3 for next sprint.
 
-### `/sr:update-product-driven-backlog` — Discover features
+### `/specrails:update-product-driven-backlog` — Discover features
 
 ```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
 ```
 
 AI product discovery using your personas. Evaluates ideas, creates tickets (local or GitHub Issues) for the best ones.
@@ -172,13 +198,13 @@ specrails-core ships with a built-in ticket system — no GitHub account or exte
 
 Tickets live in `.claude/local-tickets.json` alongside your code. They're plain JSON and git-friendly.
 
-**Local tickets are the default.** The `/setup` wizard defaults to local tickets and skips GitHub/JIRA credential setup unless you opt in.
+**Local tickets are the default.** The `/specrails:setup` wizard defaults to local tickets and skips GitHub/JIRA credential setup unless you opt in.
 
 ```bash
-/sr:implement #1, #4           # implement by ticket ID
-/sr:product-backlog            # view prioritized backlog
-/sr:update-product-driven-backlog  # discover and create tickets with AI
-/sr:propose-spec               # create a ticket from a spec proposal
+/specrails:implement #1, #4           # implement by ticket ID
+/specrails:product-backlog            # view prioritized backlog
+/specrails:update-product-driven-backlog  # discover and create tickets with AI
+/specrails:propose-spec               # create a ticket from a spec proposal
 ```
 
 See [docs/local-tickets.md](./docs/local-tickets.md) for the full schema reference, concurrency model, and command integration details.
@@ -210,12 +236,11 @@ Each persona scores features 0-5. Features are ranked by score/effort ratio. No
 |------|----------|---------|
 | **Claude Code** | Yes | AI agent runtime — [install](https://docs.anthropic.com/en/docs/claude-code) |
 | **git** | Yes | Repository detection |
-| **npm / Node 18+** | Recommended | Needed for npx install and OpenSpec CLI |
-| **OpenSpec CLI** | Recommended | Structured design artifacts for `/sr:implement` |
+| **npm / Node 18+** | For scaffold method only | Needed for `npx specrails-core@latest init` |
 | **GitHub CLI** (`gh`) | Optional | Backlog sync to GitHub Issues, PR creation. Not needed with local tickets. |
 | **JIRA CLI** (`jira`) | Optional | Backlog sync to JIRA. Not needed with local tickets. |
 
-The installer checks for each tool and offers to install missing ones.
+The plugin method has no Node.js requirement. The scaffold method checks for prerequisites and offers to install missing ones.
 
 ---
 
@@ -245,26 +270,29 @@ Stack-agnostic. The `/setup` wizard detects and adapts to whatever you're runnin
 ## FAQ
 
 **Can I customize the agents after installation?**
-Yes. The generated files in `.claude/` are yours to edit — plain markdown. Edit agent personalities, adjust CI commands, add rules, create personas.
+With the plugin method, project data files in `.specrails/` are yours to edit — personas, rules, config. With the scaffold method, `.claude/` agent files are also editable. To update plugin logic, run `claude plugin update sr`.
 
 **Can I re-run setup?**
-Run `npx specrails-core@latest init --root-dir <path>` again to re-scaffold, then `/setup`.
+Run `/specrails:setup` again at any time to regenerate or update project data files.
 
-**Does this work without OpenSpec?**
-Partially. Product discovery commands and individual agents work. `/sr:implement` and sr-architect rely on OpenSpec for structured design artifacts.
+**Plugin vs scaffold — which should I use?**
+Plugin is recommended: it has no Node.js requirement, updates automatically, and separates logic from project data. Use scaffold if you need full offline control or want to version the agent prompts themselves.
 
 **Does this work without GitHub CLI?**
-Yes. Local tickets are the default and need no external tools. `/sr:implement "description"` also works without `gh` — it just skips automated PR creation.
+Yes. Local tickets are the default and need no external tools. `/specrails:implement "description"` also works without `gh` — it just skips automated PR creation.
 
 **Can I use local tickets and GitHub Issues together?**
 Not simultaneously for the same project — backlog commands use one active provider at a time. You can migrate from GitHub Issues to local tickets using the [migration guide](./docs/migration-guide.md).
 
 **How much does it cost to run?**
-A full `/sr:implement` cycle for one feature typically costs a few dollars in Claude API usage. The sr-product-manager uses Opus; all other agents use Sonnet or Haiku.
+A full `/specrails:implement` cycle for one feature typically costs a few dollars in Claude API usage. The sr-product-manager uses Opus; all other agents use Sonnet or Haiku.
 
 **Does it work with private repos?**
 Yes. Everything runs locally through Claude Code. No external services beyond the Claude API.
 
+**How do I use SpecRails with Codex?**
+Codex uses the scaffold method: `npx specrails-core@latest init --root-dir .`. See [docs/user-docs/getting-started-codex.md](./docs/user-docs/getting-started-codex.md).
+
 ---
 
 ## Also in the SpecRails ecosystem

package/bin/doctor.sh

@@ -108,7 +108,7 @@ echo ""
 
 if [[ "${FAIL}" -eq 0 ]]; then
     TOTAL=$((PASS + FAIL))
-    echo -e "All ${TOTAL} checks passed. Run ${BOLD}/sr:product-backlog${NC} to get started."
+    echo -e "All ${TOTAL} checks passed. Run ${BOLD}/specrails:product-backlog${NC} to get started."
 else
     echo "${FAIL} check(s) failed."
 fi

package/commands/doctor.md

@@ -35,7 +35,7 @@ Each check is displayed as ✅ (pass) or ❌ (fail with fix instruction).
 
 On all checks passed:
 ```
-All 6 checks passed. Run /sr:product-backlog to get started.
+All 6 checks passed. Run /specrails:product-backlog to get started.
 ```
 
 On failure:

package/commands/setup.md

@@ -52,9 +52,9 @@ Read the following files to understand the current installation state:
    ```
    Template files are named with `sr-` prefix (e.g., `sr-architect.md`, `sr-developer.md`).
 
-5. List all template files in `$SPECRAILS_DIR/setup-templates/commands/sr/` — these are the NEW command templates from the update:
+5. List all template files in `$SPECRAILS_DIR/setup-templates/commands/specrails/` — these are the NEW command templates from the update:
    ```bash
-   ls $SPECRAILS_DIR/setup-templates/commands/sr/
+   ls $SPECRAILS_DIR/setup-templates/commands/specrails/
    ```
    Command template files include `implement.md`, `batch-implement.md`, `compat-check.md`, `refactor-recommender.md`, `why.md`, `product-backlog.md`, `update-product-driven-backlog.md`.
    If this directory does not exist, skip command template checking for this update.
@@ -94,16 +94,16 @@ Build three lists for agents:
 2. **New agents**: template file exists in `.claude/setup-templates/agents/` but the agent name is NOT in the manifest → mark for evaluation
 3. **Unchanged agents**: agent name exists in manifest AND checksum matches → skip
 
-**Command templates:** If `.claude/setup-templates/commands/sr/` exists, for each command template file, find its entry in the manifest's `artifacts` map (keyed as `templates/commands/sr/<name>.md`). Compute the SHA-256 checksum of the corresponding file in `.claude/setup-templates/commands/sr/`:
+**Command templates:** If `.claude/setup-templates/commands/specrails/` exists, for each command template file, find its entry in the manifest's `artifacts` map (keyed as `templates/commands/specrails/<name>.md`). Compute the SHA-256 checksum of the corresponding file in `.claude/setup-templates/commands/specrails/`:
 
 ```bash
-sha256sum .claude/setup-templates/commands/sr/<name>.md
+sha256sum .claude/setup-templates/commands/specrails/<name>.md
 ```
 
 Build three lists for commands:
 
 1. **Changed commands**: command name exists in manifest AND the current template checksum differs from the manifest checksum → mark for update
-2. **New commands**: template file exists in `.claude/setup-templates/commands/sr/` but the command name is NOT in the manifest → mark for evaluation
+2. **New commands**: template file exists in `.claude/setup-templates/commands/specrails/` but the command name is NOT in the manifest → mark for evaluation
 3. **Unchanged commands**: command name exists in manifest AND checksum matches → skip
 
 Display the combined analysis to the user:
@@ -176,7 +176,7 @@ grep -r '{{[A-Z_]*}}' .codex/agents/sr-*.toml 2>/dev/null || echo "OK: no broken
 For each command in the "changed commands" list from Phase U3:
 
 1. Read the NEW template:
-   - If `cli_provider == "claude"`: from `$SPECRAILS_DIR/setup-templates/commands/sr/<name>.md`
+   - If `cli_provider == "claude"`: from `$SPECRAILS_DIR/setup-templates/commands/specrails/<name>.md`
    - If `cli_provider == "codex"`: from `$SPECRAILS_DIR/setup-templates/skills/sr-<name>/SKILL.md`
 2. Read stored backlog configuration from `$SPECRAILS_DIR/backlog-config.json` (if it exists) to resolve provider-specific placeholders:
    - `BACKLOG_PROVIDER` → `provider` field (`github`, `jira`, or `none`)
@@ -194,16 +194,16 @@ For each command in the "changed commands" list from Phase U3:
    - `{{BACKLOG_PREFLIGHT}}` → provider-specific preflight check from backlog config
    - Any other `{{PLACEHOLDER}}` values → use Phase U2 analysis data
 4. Write the updated file:
-   - If `cli_provider == "claude"`: to `.claude/commands/sr/<name>.md`
+   - If `cli_provider == "claude"`: to `.claude/commands/specrails/<name>.md`
    - If `cli_provider == "codex"`: to `.agents/skills/sr-<name>/SKILL.md`
 5. Show:
-   - If `cli_provider == "claude"`: `✓ Updated /sr:<name>`
+   - If `cli_provider == "claude"`: `✓ Updated /specrails:<name>`
    - If `cli_provider == "codex"`: `✓ Updated $sr-<name>`
 
 After updating all changed commands/skills, verify no unresolved placeholders remain:
 ```bash
 # If cli_provider == "claude":
-grep -l '{{[A-Z_]*}}' .claude/commands/sr/*.md 2>/dev/null || echo "OK: no broken placeholders"
+grep -l '{{[A-Z_]*}}' .claude/commands/specrails/*.md 2>/dev/null || echo "OK: no broken placeholders"
 # If cli_provider == "codex":
 grep -rl '{{[A-Z_]*}}' .agents/skills/sr-*/SKILL.md 2>/dev/null || echo "OK: no broken placeholders"
 ```
@@ -230,17 +230,17 @@ For each agent in the "new" list:
 For each command in the "new commands" list from Phase U3:
 
 1. Read the template:
-   - If `cli_provider == "claude"`: from `$SPECRAILS_DIR/setup-templates/commands/sr/<name>.md`
+   - If `cli_provider == "claude"`: from `$SPECRAILS_DIR/setup-templates/commands/specrails/<name>.md`
    - If `cli_provider == "codex"`: from `$SPECRAILS_DIR/setup-templates/skills/sr-<name>/SKILL.md`
 2. Prompt the user:
-   - If `cli_provider == "claude"`: `"New command available: /sr:<name> — [one-line description]. Install it? [Y/n]"`
+   - If `cli_provider == "claude"`: `"New command available: /specrails:<name> — [one-line description]. Install it? [Y/n]"`
    - If `cli_provider == "codex"`: `"New skill available: $sr-<name> — [one-line description]. Install it? [Y/n]"`
 3. If the user accepts (or presses Enter):
    - Apply placeholder substitution using the same rules as Phase U4b (backlog config + codebase analysis)
-   - If `cli_provider == "claude"`: write to `.claude/commands/sr/<name>.md` — show `✓ Added /sr:<name>`
+   - If `cli_provider == "claude"`: write to `.claude/commands/specrails/<name>.md` — show `✓ Added /specrails:<name>`
    - If `cli_provider == "codex"`: write to `.agents/skills/sr-<name>/SKILL.md` — show `✓ Added $sr-<name>`
 4. If the user declines:
-   - If `cli_provider == "claude"`: show `→ Skipped /sr:<name>`
+   - If `cli_provider == "claude"`: show `→ Skipped /specrails:<name>`
    - If `cli_provider == "codex"`: show `→ Skipped $sr-<name>`
 
 ### Phase U6: Update Workflow Commands
@@ -248,12 +248,12 @@ For each command in the "new commands" list from Phase U3:
 If any new agents were added in Phase U5:
 
 1. Read the implement command/skill:
-   - If `cli_provider == "claude"`: `.claude/commands/sr/implement.md`
+   - If `cli_provider == "claude"`: `.claude/commands/specrails/implement.md`
    - If `cli_provider == "codex"`: `.agents/skills/sr-implement/SKILL.md`
 2. Check if the file references agent names in its orchestration steps (look for `sr-architect`, `sr-developer`, `sr-reviewer` etc.)
 3. If newly added agents belong in the implementation pipeline (i.e., they are layer-specific developers such as `sr-frontend-developer` or `sr-backend-developer`), add them to the appropriate step in the implement command — specifically where parallel developer agents are launched
 4. Write the updated file if any changes were made:
-   - If `cli_provider == "claude"`: `.claude/commands/sr/implement.md`
+   - If `cli_provider == "claude"`: `.claude/commands/specrails/implement.md`
    - If `cli_provider == "codex"`: `.agents/skills/sr-implement/SKILL.md`
 5. Show which commands were updated, or "No command updates needed" if nothing changed
 
@@ -301,7 +301,7 @@ All agents and commands are now up to date.
 Update `.specrails-manifest.json` to reflect the new checksums for all regenerated/updated and added agents and commands:
 - For each regenerated agent: update its checksum entry to the new template's checksum (keyed as `templates/agents/sr-<name>.md`)
 - For each added agent: add a new entry with its checksum
-- For each updated command: update its checksum entry to the new template's checksum (keyed as `templates/commands/sr/<name>.md`)
+- For each updated command: update its checksum entry to the new template's checksum (keyed as `templates/commands/specrails/<name>.md`)
 - For each added command: add a new entry with its checksum
 - Update the `version` field to the version read from `.specrails-version`
 
@@ -351,9 +351,9 @@ Store as `QS_IS_EXISTING_CODEBASE=true/false`.
 Before generating files, check if this is a re-run:
 
 1. Check if commands/skills already exist:
-   - If `cli_provider == "claude"`: check if `.claude/commands/sr/` directory exists with any `.md` files:
+   - If `cli_provider == "claude"`: check if `.claude/commands/specrails/` directory exists with any `.md` files:
      ```bash
-     ls .claude/commands/sr/*.md 2>/dev/null
+     ls .claude/commands/specrails/*.md 2>/dev/null
      ```
    - If `cli_provider == "codex"`: check if `.agents/skills/sr-*/SKILL.md` files exist:
      ```bash
@@ -364,13 +364,13 @@ Before generating files, check if this is a re-run:
 
 In re-run mode, QS3 executes in **gap-fill mode** for command/skill files:
 - For each command in the list, check if it already exists:
-  - If `cli_provider == "claude"`: at `.claude/commands/sr/<name>.md`
+  - If `cli_provider == "claude"`: at `.claude/commands/specrails/<name>.md`
   - If `cli_provider == "codex"`: at `.agents/skills/sr-<name>/SKILL.md`
 - If it exists: skip it and show:
-  - Claude: `✓ Already installed: /sr:<name>`
+  - Claude: `✓ Already installed: /specrails:<name>`
   - Codex: `✓ Already installed: $sr-<name>`
 - If it does NOT exist: install it and show:
-  - Claude: `✓ Added /sr:<name> (was missing)`
+  - Claude: `✓ Added /specrails:<name> (was missing)`
   - Codex: `✓ Added $sr-<name> (was missing)`
 - Do NOT prompt the user for confirmation on missing files — install them automatically
 
@@ -436,11 +436,11 @@ Core commands (always install if missing):
 
 **If `cli_provider == "claude"`:**
 
-If `QS_IS_RERUN=false` (fresh install): for each core command, read the template from `$SPECRAILS_DIR/setup-templates/commands/sr/<name>.md`, substitute the backlog placeholders with local values (using the same table as Phase 4.3 "Local Tickets"), stub all persona placeholders with `(Lite Mode — run /setup to configure personas)`, then write to `.claude/commands/sr/<name>.md`.
+If `QS_IS_RERUN=false` (fresh install): for each core command, read the template from `$SPECRAILS_DIR/setup-templates/commands/specrails/<name>.md`, substitute the backlog placeholders with local values (using the same table as Phase 4.3 "Local Tickets"), stub all persona placeholders with `(Lite Mode — run /setup to configure personas)`, then write to `.claude/commands/specrails/<name>.md`.
 
-If `QS_IS_RERUN=true` (gap-fill mode): for each command in the list above, check if `.claude/commands/sr/<name>.md` already exists:
-- If it exists: skip it — show `✓ Already installed: /sr:<name>`
-- If it does NOT exist: read template, substitute placeholders as above, write to `.claude/commands/sr/<name>.md` — show `✓ Added /sr:<name> (was missing)`
+If `QS_IS_RERUN=true` (gap-fill mode): for each command in the list above, check if `.claude/commands/specrails/<name>.md` already exists:
+- If it exists: skip it — show `✓ Already installed: /specrails:<name>`
+- If it does NOT exist: read template, substitute placeholders as above, write to `.claude/commands/specrails/<name>.md` — show `✓ Added /specrails:<name> (was missing)`
 
 **If `cli_provider == "codex"`:**
 
@@ -461,25 +461,25 @@ Remove `commands/setup.md` from `.claude/commands/` if it was copied there by th
 After generating all files, display the setup complete message.
 
 Then, based on `QS_IS_EXISTING_CODEBASE`:
-- **Existing codebase** (`true`): recommend `/sr:refactor-recommender`
-- **New project** (`false`): recommend `/sr:product-backlog`
+- **Existing codebase** (`true`): recommend `/specrails:refactor-recommender`
+- **New project** (`false`): recommend `/specrails:product-backlog`
 
 If `QS_IS_RERUN=false`, display:
 ```
 ✅ Setup complete.
 
 Try your first command:
-  > /sr:product-backlog
+  > /specrails:product-backlog
 ```
-(Replace `/sr:product-backlog` with `/sr:refactor-recommender` for existing codebases.)
+(Replace `/specrails:product-backlog` with `/specrails:refactor-recommender` for existing codebases.)
 
 If `QS_IS_RERUN=true`, display the gap-fill summary and stop:
 ```
 ✅ Re-run complete.
 
 Commands status:
-  ✓ Already installed: /sr:<name>
-  ✓ Added /sr:<name> (was missing)
+  ✓ Already installed: /specrails:<name>
+  ✓ Added /specrails:<name> (was missing)
   [... one line per command ...]
 
 All commands are up to date.
@@ -913,8 +913,8 @@ Store the full configuration in `.claude/backlog-config.json`:
 
 #### If None
 
-- Skip `/sr:product-backlog` and `/sr:update-product-driven-backlog` commands.
-- The `/sr:implement` command will still work with text descriptions.
+- Skip `/specrails:product-backlog` and `/specrails:update-product-driven-backlog` commands.
+- The `/specrails:implement` command will still work with text descriptions.
 
 ### 3.3 Git & shipping workflow
 
@@ -943,14 +943,14 @@ If automatic, also check if `gh` is authenticated (for PR creation). If not, war
 
 | Command | Purpose | Requires |
 |---------|---------|----------|
-| /sr:implement | Full pipeline: sr-architect → sr-developer → sr-reviewer → ship | sr-architect + sr-developer + sr-reviewer |
-| /sr:batch-implement | Orchestrate multiple features in dependency-aware waves | sr-architect + sr-developer + sr-reviewer |
-| /sr:propose-spec | Interactively propose and refine a feature spec, then create a GitHub issue | GitHub CLI |
-| /sr:product-backlog | View prioritized backlog with VPC scores | sr-product-analyst + Backlog provider |
-| /sr:update-product-driven-backlog | Generate new feature ideas via product discovery | sr-product-manager + Backlog provider |
-| /sr:compat-check | Snapshot API surface and detect breaking changes | None |
-| /sr:refactor-recommender | Scan for refactoring opportunities ranked by impact/effort | None |
-| /sr:why | Search past architectural decisions from agent memory | None |
+| /specrails:implement | Full pipeline: sr-architect → sr-developer → sr-reviewer → ship | sr-architect + sr-developer + sr-reviewer |
+| /specrails:batch-implement | Orchestrate multiple features in dependency-aware waves | sr-architect + sr-developer + sr-reviewer |
+| /specrails:propose-spec | Interactively propose and refine a feature spec, then create a GitHub issue | GitHub CLI |
+| /specrails:product-backlog | View prioritized backlog with VPC scores | sr-product-analyst + Backlog provider |
+| /specrails:update-product-driven-backlog | Generate new feature ideas via product discovery | sr-product-manager + Backlog provider |
+| /specrails:compat-check | Snapshot API surface and detect breaking changes | None |
+| /specrails:refactor-recommender | Scan for refactoring opportunities ranked by impact/effort | None |
+| /specrails:why | Search past architectural decisions from agent memory | None |
 
 [All] [Custom selection]
 ```
@@ -1078,21 +1078,21 @@ Write each persona to `$SPECRAILS_DIR/agents/personas/`:
 For each selected command, read the template and adapt.
 
 **If `cli_provider == "claude"` (default):**
-- `setup-templates/commands/sr/implement.md` → `.claude/commands/sr/implement.md`
-- `setup-templates/commands/sr/batch-implement.md` → `.claude/commands/sr/batch-implement.md`
-- `setup-templates/commands/sr/propose-spec.md` → `.claude/commands/sr/propose-spec.md`
-- `setup-templates/commands/sr/product-backlog.md` → `.claude/commands/sr/product-backlog.md` (if `BACKLOG_PROVIDER != none`)
-- `setup-templates/commands/sr/update-product-driven-backlog.md` → `.claude/commands/sr/update-product-driven-backlog.md` (if `BACKLOG_PROVIDER != none`)
-- `setup-templates/commands/sr/compat-check.md` → `.claude/commands/sr/compat-check.md`
-- `setup-templates/commands/sr/refactor-recommender.md` → `.claude/commands/sr/refactor-recommender.md`
-- `setup-templates/commands/sr/why.md` → `.claude/commands/sr/why.md`
+- `setup-templates/commands/specrails/implement.md` → `.claude/commands/specrails/implement.md`
+- `setup-templates/commands/specrails/batch-implement.md` → `.claude/commands/specrails/batch-implement.md`
+- `setup-templates/commands/specrails/propose-spec.md` → `.claude/commands/specrails/propose-spec.md`
+- `setup-templates/commands/specrails/product-backlog.md` → `.claude/commands/specrails/product-backlog.md` (if `BACKLOG_PROVIDER != none`)
+- `setup-templates/commands/specrails/update-product-driven-backlog.md` → `.claude/commands/specrails/update-product-driven-backlog.md` (if `BACKLOG_PROVIDER != none`)
+- `setup-templates/commands/specrails/compat-check.md` → `.claude/commands/specrails/compat-check.md`
+- `setup-templates/commands/specrails/refactor-recommender.md` → `.claude/commands/specrails/refactor-recommender.md`
+- `setup-templates/commands/specrails/why.md` → `.claude/commands/specrails/why.md`
 
 **If `cli_provider == "codex"`:**
 - `setup-templates/skills/sr-implement/SKILL.md` → `.agents/skills/sr-implement/SKILL.md`
 - `setup-templates/skills/sr-batch-implement/SKILL.md` → `.agents/skills/sr-batch-implement/SKILL.md`
-- `setup-templates/commands/sr/propose-spec.md` → `.agents/skills/sr-propose-spec/SKILL.md` (wrap with YAML frontmatter if no skill template exists)
-- `setup-templates/commands/sr/product-backlog.md` → `.agents/skills/sr-product-backlog/SKILL.md` (if `BACKLOG_PROVIDER != none`; wrap with frontmatter)
-- `setup-templates/commands/sr/update-product-driven-backlog.md` → `.agents/skills/sr-update-product-driven-backlog/SKILL.md` (if `BACKLOG_PROVIDER != none`; wrap with frontmatter)
+- `setup-templates/commands/specrails/propose-spec.md` → `.agents/skills/sr-propose-spec/SKILL.md` (wrap with YAML frontmatter if no skill template exists)
+- `setup-templates/commands/specrails/product-backlog.md` → `.agents/skills/sr-product-backlog/SKILL.md` (if `BACKLOG_PROVIDER != none`; wrap with frontmatter)
+- `setup-templates/commands/specrails/update-product-driven-backlog.md` → `.agents/skills/sr-update-product-driven-backlog/SKILL.md` (if `BACKLOG_PROVIDER != none`; wrap with frontmatter)
 - `setup-templates/skills/sr-compat-check/SKILL.md` → `.agents/skills/sr-compat-check/SKILL.md`
 - `setup-templates/skills/sr-refactor-recommender/SKILL.md` → `.agents/skills/sr-refactor-recommender/SKILL.md`
 - `setup-templates/skills/sr-why/SKILL.md` → `.agents/skills/sr-why/SKILL.md`
@@ -1110,7 +1110,7 @@ metadata:
 ---
 ```
 
-For both providers, create the output directory before writing (`mkdir -p` for `.claude/commands/sr/` or `.agents/skills/sr-<name>/`).
+For both providers, create the output directory before writing (`mkdir -p` for `.claude/commands/specrails/` or `.agents/skills/sr-<name>/`).
 
 Adapt:
 - CI commands to match detected stack
@@ -1315,7 +1315,7 @@ After cleanup, verify that only the intended files remain:
 # If cli_provider == "claude":
 ls .claude/agents/sr-*.md
 ls .claude/agents/personas/*.md
-ls .claude/commands/sr/*.md
+ls .claude/commands/specrails/*.md
 ls .claude/rules/*.md
 ls .claude/agent-memory/
 
@@ -1371,14 +1371,14 @@ Display the complete installation summary:
 [If cli_provider == "claude":]
 | Command | File |
 |---------|------|
-| /sr:implement | .claude/commands/sr/implement.md |
-| /sr:batch-implement | .claude/commands/sr/batch-implement.md |
-| /sr:propose-spec | .claude/commands/sr/propose-spec.md |
-| /sr:product-backlog | .claude/commands/sr/product-backlog.md |
-| /sr:update-product-driven-backlog | .claude/commands/sr/update-product-driven-backlog.md |
-| /sr:compat-check | .claude/commands/sr/compat-check.md |
-| /sr:refactor-recommender | .claude/commands/sr/refactor-recommender.md |
-| /sr:why | .claude/commands/sr/why.md |
+| /specrails:implement | .claude/commands/specrails/implement.md |
+| /specrails:batch-implement | .claude/commands/specrails/batch-implement.md |
+| /specrails:propose-spec | .claude/commands/specrails/propose-spec.md |
+| /specrails:product-backlog | .claude/commands/specrails/product-backlog.md |
+| /specrails:update-product-driven-backlog | .claude/commands/specrails/update-product-driven-backlog.md |
+| /specrails:compat-check | .claude/commands/specrails/compat-check.md |
+| /specrails:refactor-recommender | .claude/commands/specrails/refactor-recommender.md |
+| /specrails:why | .claude/commands/specrails/why.md |
 [If cli_provider == "codex":]
 | Skill | File |
 |-------|------|
@@ -1410,9 +1410,9 @@ Note: Only commands/skills selected during setup are shown. Backlog commands are
 ### Next Steps
 [If cli_provider == "claude":]
 1. Review the generated files in .claude/
-2. Run `/sr:product-backlog` to see your backlog (if GitHub Issues exist)
-3. Run `/sr:update-product-driven-backlog` to generate feature ideas
-4. Run `/sr:implement #issue-number` to implement a feature
+2. Run `/specrails:product-backlog` to see your backlog (if GitHub Issues exist)
+3. Run `/specrails:update-product-driven-backlog` to generate feature ideas
+4. Run `/specrails:implement #issue-number` to implement a feature
 5. Commit the .claude/ directory to version control
 [If cli_provider == "codex":]
 1. Review the generated files in .codex/ and .agents/skills/
@@ -1423,9 +1423,9 @@ Note: Only commands/skills selected during setup are shown. Backlog commands are
 
 ### Quick Start
 [If cli_provider == "claude":]
-- `/sr:implement "describe a feature"` — implement something right now
-- `/sr:product-backlog` — see prioritized feature ideas
-- `/sr:update-product-driven-backlog` — discover new features using VPC
+- `/specrails:implement "describe a feature"` — implement something right now
+- `/specrails:product-backlog` — see prioritized feature ideas
+- `/specrails:update-product-driven-backlog` — discover new features using VPC
 [If cli_provider == "codex":]
 - `$sr-implement "describe a feature"` — implement something right now
 - `$sr-product-backlog` — see prioritized feature ideas
@@ -1442,7 +1442,7 @@ After displaying the setup complete summary above, detect the project type and o
 
 Try your first spec:
 [If cli_provider == "claude":]
-  > /sr:product-backlog
+  > /specrails:product-backlog
 [If cli_provider == "codex":]
   > $sr-product-backlog
 ```
@@ -1453,7 +1453,7 @@ Try your first spec:
 
 Try your first spec:
 [If cli_provider == "claude":]
-  > /sr:refactor-recommender
+  > /specrails:refactor-recommender
 [If cli_provider == "codex":]
   > $sr-refactor-recommender
 ```

package/docs/README.md

@@ -13,9 +13,10 @@ Welcome to the SpecRails docs. This guide will take you from zero to a fully aut
 
 | Guide | What it covers |
 |-------|----------------|
-| [Installation & Setup](installation.md) | Detailed setup, prerequisites, the `/setup` wizard |
+| [Installation & Setup](installation.md) | Detailed setup, prerequisites, the `/specrails:setup` wizard |
+| [Plugin Architecture](plugin-architecture.md) | Plugin vs scaffold, what lives where, how updates work |
 | [Agents](agents.md) | Every agent explained — role, when it runs, why it exists |
-| [Workflows & Commands](workflows.md) | How to use `/sr:implement`, `/sr:product-backlog`, and more |
+| [Workflows & Commands](workflows.md) | How to use `/specrails:implement`, `/specrails:product-backlog`, and more |
 | [Customization](customization.md) | Adapt agents, rules, personas, and conventions to your project |
 | [Updating](updating.md) | Keep SpecRails up to date without losing your customizations |