specrails-core 3.3.1 → 3.4.1

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,18 +236,17 @@ 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.
 
 ---
 
 ## Supported stacks
 
-Stack-agnostic. The `/setup` wizard detects and adapts to whatever you're running:
+Stack-agnostic. The `/specrails:setup` wizard detects and adapts to whatever you're running:
 
 **Backend:** Python/FastAPI, Node/Express, Go/Gin, Rust/Actix, Java/Spring, Ruby/Rails, .NET
 **Frontend:** React, Vue, Angular, Svelte, Next.js, Nuxt
@@ -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

@@ -76,7 +76,7 @@ fi
 if [[ -f "${PROJECT_ROOT}/CLAUDE.md" ]]; then
     pass "CLAUDE.md: present"
 else
-    fail "CLAUDE.md: missing" "Run /setup inside Claude Code to regenerate"
+    fail "CLAUDE.md: missing" "Run /specrails:setup inside Claude Code to regenerate"
 fi
 
 # ─────────────────────────────────────────────
@@ -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: