specrails-core 3.3.0 → 3.4.0

package/README.md

@@ -12,22 +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
-
-<!--
-  BOARD: Add demo GIF here — this is the #1 conversion driver on Product Hunt and npm.
-  Record a 60-90s screen capture showing:
-    1. `npx specrails-core@latest init --root-dir .` running
-    2. The `/setup` wizard completing (phases 1-5)
-    3. `/sr:implement "add dark mode"` → agents working → PR created
-  Recommended tools: Loom or QuickTime to record; Kap (https://getkap.co) to export as GIF.
-  Then replace this comment with:
-
-  ![specrails-core demo](./assets/demo.gif)
--->
+> **Requirements:** [Claude Code](https://docs.anthropic.com/en/docs/claude-code) or [Codex CLI](https://github.com/openai/codex) (choose one), git
 
 ---
 
@@ -38,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.
 
@@ -46,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:health-check`, `/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 |
 
 ---
 
@@ -125,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.
@@ -140,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.
@@ -149,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:
@@ -158,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.
@@ -182,15 +196,15 @@ AI product discovery using your personas. Evaluates ideas, creates tickets (loca
 
 specrails-core ships with a built-in ticket system — no GitHub account or external tools required.
 
-Tickets live in `.claude/local-tickets.json` alongside your code. They're plain JSON, git-friendly, and bidirectionally synced with specrails-hub in real time.
+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.
@@ -222,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.
 
 ---
 
@@ -257,32 +270,33 @@ 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
 
-- **[specrails-hub](https://github.com/fjpulidop/specrails-hub)** — GUI for specrails-core. Manage your agents, run commands, and view pipeline results from a web interface.
-- **[specrails.dev](https://specrails.dev)** — Official website and documentation.
 - **Product Hunt** — [Vote for SpecRails on launch day](https://www.producthunt.com) _(link goes live on launch day — star this repo to get notified)_
 
 ---

package/VERSION

@@ -1 +1 @@
-2.1.0
+3.3.0

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/bin/perf-check.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+# Performance regression check for specrails-core.
+# This is a template/installer repo — no runtime benchmarks apply.
+# Reports NO_PERF_IMPACT so the CI workflow exits cleanly.
+set -euo pipefail
+
+FILES="${MODIFIED_FILES_LIST:-}"
+CONTEXT="${2:-}"
+
+# Determine if any performance-sensitive files were modified.
+# For specrails-core (a shell installer + markdown template repo), there are
+# no runtime execution paths to benchmark. All changes are to installer scripts
+# or template files that have no measurable latency or throughput impact.
+
+echo "specrails-core performance check"
+echo "Modified files: ${FILES:-<none>}"
+echo ""
+echo "This repository contains shell installer scripts and Markdown templates."
+echo "No runtime benchmarks apply — skipping performance regression analysis."
+echo ""
+echo "PERF_STATUS: NO_PERF_IMPACT"

package/bin/specrails-core.js

@@ -8,6 +8,7 @@ const COMMANDS = {
   init: "install.sh",
   update: "update.sh",
   doctor: "bin/doctor.sh",
+  "perf-check": "bin/perf-check.sh",
 };
 
 const args = process.argv.slice(2);
@@ -17,9 +18,10 @@ if (!subcommand) {
   console.log(`specrails-core — Agent Workflow System for Claude Code
 
 Usage:
-  specrails-core init   [--root-dir <path>]     Install into a repository
-  specrails-core update [--only <component>]    Update an existing installation
-  specrails-core doctor                         Run health checks
+  specrails-core init       [--root-dir <path>]     Install into a repository
+  specrails-core update     [--only <component>]    Update an existing installation
+  specrails-core doctor                             Run health checks
+  specrails-core perf-check [--files <list>]        Performance regression check (CI)
 
 More info: https://github.com/fjpulidop/specrails-core`);
   process.exit(0);
@@ -29,7 +31,7 @@ const script = COMMANDS[subcommand];
 
 if (!script) {
   console.error(`Unknown command: ${subcommand}\n`);
-  console.error("Available commands: init, update, doctor");
+  console.error("Available commands: init, update, doctor, perf-check");
   process.exit(1);
 }
 
@@ -40,6 +42,7 @@ const ALLOWED_FLAGS = {
   init: ["--root-dir", "--yes", "-y"],
   update: ["--only"],
   doctor: [],
+  "perf-check": ["--files", "--context"],
 };
 
 const subargs = args.slice(1);

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: