specrails-core 4.0.3 → 4.0.5

package/README.md

@@ -7,16 +7,16 @@
 [![Claude Code](https://img.shields.io/badge/Built%20for-Claude%20Code-blueviolet)](https://docs.anthropic.com/en/docs/claude-code)
 [![Codex](https://img.shields.io/badge/Built%20for-OpenAI%20Codex-412991)](https://github.com/openai/codex)
 
-**Your AI development team. From idea to production code.**
+**Your agentic development team. From idea to production code.**
 
-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.
+One command turns your repo into a spec-driven pipeline with a team of specialized AI agents — architect, developers, reviewers, product manager — all adapted to your codebase.
 
 ```bash
-claude plugin install sr   # Claude Code plugin (recommended)
-/specrails:enrich                 # configure for your project
+npx specrails-core@latest init   # install into the current repo
+/specrails:enrich                # optional: deep codebase analysis
 ```
 
-> **Requirements:** [Claude Code](https://docs.anthropic.com/en/docs/claude-code) or [Codex CLI](https://github.com/openai/codex) (choose one), git
+> **Requirements:** [Claude Code](https://docs.anthropic.com/en/docs/claude-code) or [Codex CLI](https://github.com/openai/codex) (one of them), git, Node 18+.
 
 ---
 
@@ -27,93 +27,75 @@ Idea  →  Architecture  →  Implementation  →  Review  →  PR
          (sr-architect)   (sr-developer)    (sr-reviewer)
 ```
 
-Run `/specrails: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.
 
-Every artifact (agents, rules, personas) is generated **specifically for your project** by analyzing your actual codebase, tech stack, and CI setup. Not generic templates.
+Every artifact (agents, rules, personas) is generated **specifically for your project** by analysing your actual codebase, tech stack, and CI setup. Not generic templates.
 
 ---
 
 ## Quick start
 
-### Claude Code plugin (recommended)
-
 ```bash
-claude plugin install sr   # install the sr plugin
-/specrails:enrich                 # run the 5-phase wizard (~5 min)
+# 1. Install into the current repo
+npx specrails-core@latest init
 ```
 
-Updates automatically: `claude plugin update sr`
+The TUI asks you to pick a tier:
 
-### Scaffold method (alternative)
+- **Quick** (default) — agents and commands installed straight to `.claude/`, ready to use immediately. No AI interaction.
+- **Full** — same as Quick plus `/specrails:enrich` (5-phase deep analysis: stack detection, VPC personas, competitive research). ~5 min.
 
 ```bash
-npx specrails-core@latest init --root-dir .   # TUI: select agents, choose tier
-```
-
-**Quick tier** (default) — agents installed directly, ready to use immediately. No AI interaction.
-**Full tier** — run `/specrails:enrich` after install for deep codebase analysis, VPC personas, and competitive research.
+# 2. Optional — run enrich later if you picked Quick
+/specrails:enrich
 
-### Start building
-
-```bash
+# 3. Start building
 > /specrails:implement "add user authentication"
-> /specrails:implement #1, #2                 # from local tickets (default)
-> /specrails:implement #42, #43               # from GitHub Issues (if configured)
+> /specrails:implement #1, #2          # from local tickets (default)
+> /specrails:implement #42             # from GitHub Issues (if configured)
 ```
 
 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:enrich` 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:enrich` 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`)
+Everything lands in your repo — nothing auto-updates, nothing phones home. You own it, you commit it.
 
 | Category | Location | Purpose |
 |----------|----------|---------|
-| **Agents** | Plugin | 14 specialized AI agents |
-| **Commands** | Plugin | 17 workflow commands: `/specrails:implement`, `/specrails:get-backlog-specs`, `/specrails:why`, and more |
-| **Skills** | Plugin | OpenSpec skills (`/opsx:*`) included |
-| **Hooks & References** | Plugin | Agent hooks, reference docs |
-
-### Project data (generated by `/specrails:enrich` — lives in your repo)
-
-| Category | Files | Purpose |
-|----------|-------|---------|
+| **Agents** | `.claude/agents/` | 14 specialised AI agents |
+| **Commands** | `.claude/commands/specrails/` | 17 workflow commands (`/specrails:implement`, `/specrails:get-backlog-specs`, `/specrails:why`, …) |
+| **OpenSpec skills** | `.claude/commands/opsx/` | `/opsx:*` commands for spec artefacts |
 | **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 |
 
+To update, re-run the installer:
+
+```bash
+npx specrails-core@latest init
+```
+
+It refreshes the agents/commands while leaving your `.specrails/` data untouched.
+
 ---
 
-## Why SpecRails
+## Why specrails
 
-| | SpecRails | Plain Claude Code | Cursor / Copilot |
+| | specrails | Plain Claude Code | Cursor / Copilot |
 |---|---|---|---|
 | Structured pipeline | ✅ Architect → Dev → Review → PR | ❌ Manual | ❌ Manual |
-| Adapts to your codebase | ✅ Reads your actual stack/CI | ⚠️ Prompts only | ❌ |
+| Adapts to your codebase | ✅ Reads your real stack/CI | ⚠️ Prompts only | ❌ |
 | Product-driven backlog | ✅ VPC persona scoring | ❌ | ❌ |
 | Parallel feature builds | ✅ Git worktrees | ❌ | ❌ |
 | Institutional memory | ✅ Agents learn across sessions | ❌ | ❌ |
 | Open source | ✅ MIT | N/A | ❌ |
 
-SpecRails is not a chat interface. It's a **development pipeline** that coordinates multiple specialized agents through your existing tools (GitHub Issues, JIRA, git, CI).
+specrails is not a chat interface. It's a **development pipeline** that coordinates multiple specialised agents through your existing tools (GitHub Issues, JIRA, git, CI).
 
 ---
 
@@ -123,8 +105,8 @@ SpecRails is not a chat interface. It's a **development pipeline** that coordina
 |-------|-------|------|
 | **sr-architect** | Sonnet | Designs features: proposal, technical design, task breakdown |
 | **sr-developer** | Sonnet | Full-stack implementation |
-| **sr-backend-developer** | Sonnet | Backend-specialized implementation |
-| **sr-frontend-developer** | Sonnet | Frontend-specialized implementation |
+| **sr-backend-developer** | Sonnet | Backend-specialised implementation |
+| **sr-frontend-developer** | Sonnet | Frontend-specialised implementation |
 | **sr-reviewer** | Sonnet | Quality gate: runs CI, fixes issues, records learnings |
 | **sr-backend-reviewer** | Sonnet | Backend code review: API design, DB patterns, performance |
 | **sr-frontend-reviewer** | Sonnet | Frontend code review: UX, accessibility, component design |
@@ -134,7 +116,7 @@ SpecRails is not a chat interface. It's a **development pipeline** that coordina
 | **sr-merge-resolver** | Sonnet | AI-powered merge conflict resolution for multi-feature pipelines |
 | **sr-performance-reviewer** | Sonnet | Performance regression detection after implementation |
 | **sr-product-manager** | Opus | Product discovery: competitive analysis, VPC evaluation |
-| **sr-product-analyst** | Haiku | Read-only backlog analysis and prioritization |
+| **sr-product-analyst** | Haiku | Read-only backlog analysis and prioritisation |
 
 ---
 
@@ -144,7 +126,7 @@ SpecRails is not a chat interface. It's a **development pipeline** that coordina
 
 ```bash
 /specrails:implement "add dark mode"        # from a description
-/specrails:implement #85, #71               # from GitHub Issues
+/specrails:implement #85, #71               # from tickets
 /specrails:implement UI, Analytics          # explore areas, pick the best ideas
 ```
 
@@ -173,14 +155,14 @@ To discard without applying:
 rm -rf .claude/.dry-run/add-dark-mode/
 ```
 
-### `/specrails:get-backlog-specs` — View prioritized backlog
+### `/specrails:get-backlog-specs` — View prioritised backlog
 
 ```bash
 /specrails:get-backlog-specs                  # show all areas
 /specrails:get-backlog-specs UI, Decks        # filter by area
 ```
 
-Reads your tickets (local or GitHub Issues), scores by VPC persona match, recommends top 3 for next sprint.
+Reads your tickets (local or GitHub Issues), scores by VPC persona match, recommends top 3 for the next sprint.
 
 ### `/specrails:auto-propose-backlog-specs` — Discover features
 
@@ -199,13 +181,13 @@ specrails-core ships with a built-in ticket system — no GitHub account or exte
 
 Tickets live in `.specrails/local-tickets.json` alongside your code. They're plain JSON and git-friendly.
 
-**Local tickets are the default.** The `/specrails:enrich` wizard defaults to local tickets and skips GitHub/JIRA credential setup unless you opt in.
+**Local tickets are the default.** The `/specrails:enrich` wizard skips GitHub/JIRA credential setup unless you opt in.
 
 ```bash
-/specrails:implement #1, #4           # implement by ticket ID
-/specrails:get-backlog-specs            # view prioritized backlog
-/specrails:auto-propose-backlog-specs  # discover and create tickets with AI
-/specrails:propose-spec               # create a ticket from a spec proposal
+/specrails:implement #1, #4                # implement by ticket ID
+/specrails:get-backlog-specs               # view prioritised backlog
+/specrails:auto-propose-backlog-specs      # 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.
@@ -216,7 +198,7 @@ Migrating from GitHub Issues or JIRA? See [docs/migration-guide.md](./docs/migra
 
 ## VPC persona scoring
 
-Features are scored against your user personas using the VPC framework:
+Features are scored against your user personas using the Value Proposition Canvas framework:
 
 ```
 +-----------------------------+    +-----------------------------+
@@ -227,7 +209,7 @@ Features are scored against your user personas using the VPC framework:
 +-----------------------------+    +-----------------------------+
 ```
 
-Each persona scores features 0-5. Features are ranked by score/effort ratio. No gut-feel product decisions.
+Each persona scores features 0–5. Features are ranked by score / effort ratio. No gut-feel product decisions.
 
 ---
 
@@ -235,13 +217,13 @@ Each persona scores features 0-5. Features are ranked by score/effort ratio. No
 
 | Tool | Required | Purpose |
 |------|----------|---------|
-| **Claude Code** | Yes | AI agent runtime — [install](https://docs.anthropic.com/en/docs/claude-code) |
+| **Claude Code** or **Codex CLI** | Yes (one of them) | AI agent runtime |
 | **git** | Yes | Repository detection |
-| **npm / Node 18+** | For scaffold method only | Needed for `npx specrails-core@latest init` |
+| **Node 18+** | Yes | 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 plugin method has no Node.js requirement. The scaffold method checks for prerequisites and offers to install missing ones.
+The installer checks for prerequisites and offers to install missing ones.
 
 ---
 
@@ -249,18 +231,18 @@ The plugin method has no Node.js requirement. The scaffold method checks for pre
 
 Stack-agnostic. The `/specrails:enrich` 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
-**Database:** PostgreSQL, MySQL, SQLite, MongoDB, Redis
-**CI/CD:** GitHub Actions, GitLab CI, Jenkins, Makefile
-**Testing:** pytest, vitest, jest, go test, cargo test, rspec
+- **Backend:** Python/FastAPI, Node/Express, Go/Gin, Rust/Actix, Java/Spring, Ruby/Rails, .NET
+- **Frontend:** React, Vue, Angular, Svelte, Next.js, Nuxt
+- **Database:** PostgreSQL, MySQL, SQLite, MongoDB, Redis
+- **CI/CD:** GitHub Actions, GitLab CI, Jenkins, Makefile
+- **Testing:** pytest, vitest, jest, go test, cargo test, rspec
 
 ---
 
 ## Design principles
 
-1. **Two-step install** — Shell handles prerequisites, Claude handles intelligence. No API keys beyond Claude Code auth.
-2. **Self-cleaning** — All scaffolding removed after setup. Only final, project-specific files remain.
+1. **Local by default** — Everything lives in your repo. No cloud services, no telemetry, no phone home.
+2. **Self-cleaning** — Installer scaffolding is removed after setup. Only final, project-specific files remain.
 3. **Context-first** — Every generated file uses your real paths, patterns, and CI commands.
 4. **Persona-driven** — Product decisions grounded in researched user personas, not assumptions.
 5. **Institutional memory** — Agents learn across sessions. Reviewer learnings feed back to future developers.
@@ -270,14 +252,11 @@ Stack-agnostic. The `/specrails:enrich` wizard detects and adapts to whatever yo
 
 ## FAQ
 
-**Can I customize the agents after installation?**
-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 customise the agents after installation?**
+Yes. Everything under `.claude/` and `.specrails/` is yours to edit — agent prompts, personas, rules, config. Commit what makes sense, gitignore what's transient.
 
 **Can I re-run the wizard?**
-Run `/specrails:enrich` again at any time to regenerate or update project data files.
-
-**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.
+Run `/specrails:enrich` again at any time to regenerate or update project data files. Re-running `npx specrails-core@latest init` refreshes the agents/commands without touching `.specrails/`.
 
 **Does this work without GitHub CLI?**
 Yes. Local tickets are the default and need no external tools. `/specrails:implement "description"` also works without `gh` — it just skips automated PR creation.
@@ -289,16 +268,17 @@ Not simultaneously for the same project — backlog commands use one active prov
 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.
+Yes. Everything runs locally through Claude Code (or Codex). No external services beyond the model 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).
+**How do I use specrails with Codex?**
+Same install path: `npx specrails-core@latest init --root-dir .`. The TUI detects Codex and adjusts the agent configuration. See [docs/user-docs/getting-started-codex.md](./docs/user-docs/getting-started-codex.md).
 
 ---
 
-## Also in the SpecRails ecosystem
+## Related
 
-- **Product Hunt** — [Vote for SpecRails on launch day](https://www.producthunt.com) _(link goes live on launch day — star this repo to get notified)_
+- **[specrails-hub](https://github.com/fjpulidop/specrails-hub)** — desktop dashboard that visualises specrails pipelines (macOS, open source).
+- **[specrails.dev](https://specrails.dev)** — landing page and documentation.
 
 ---
 

package/install.sh

@@ -521,9 +521,9 @@ _openspec_pkg_version=""
 if [[ -f "$SCRIPT_DIR/package.json" ]]; then
     _openspec_pkg_version=$(python3 -c "import json; d=json.load(open('$SCRIPT_DIR/package.json')); print(d.get('specrails',{}).get('openspecVersion',''))" 2>/dev/null || true)
 fi
-_openspec_install_spec="@openspec/cli"
+_openspec_install_spec="@fission-ai/openspec"
 if [[ -n "$_openspec_pkg_version" ]]; then
-    _openspec_install_spec="@openspec/cli@${_openspec_pkg_version}"
+    _openspec_install_spec="@fission-ai/openspec@${_openspec_pkg_version}"
 fi
 
 if command -v openspec &> /dev/null; then
@@ -543,19 +543,26 @@ else
         fi
         if [ "$INSTALL_OPENSPEC" = "y" ] || [ "$INSTALL_OPENSPEC" = "Y" ]; then
             info "Installing ${_openspec_install_spec}..."
-            npm install -g "${_openspec_install_spec}" 2>/dev/null && {
+            _npm_log="$(mktemp)"
+            if npm install -g "${_openspec_install_spec}" >"$_npm_log" 2>&1; then
                 ok "OpenSpec CLI installed ($(openspec --version 2>/dev/null || echo "${_openspec_pkg_version}"))"
                 HAS_OPENSPEC=true
-            } || {
-                warn "Global install failed. Trying local..."
-                cd "$REPO_ROOT" && npm install "${_openspec_install_spec}" 2>/dev/null && {
-                    ok "OpenSpec CLI installed locally"
+                rm -f "$_npm_log"
+            else
+                warn "Global install failed (often EACCES on fresh macOS). Trying local install in ${REPO_ROOT}..."
+                # Show last few lines of npm error for context
+                tail -n 5 "$_npm_log" | sed 's/^/      /' >&2 || true
+                if ( cd "$REPO_ROOT" && npm install "${_openspec_install_spec}" >"$_npm_log" 2>&1 ); then
+                    ok "OpenSpec CLI installed locally (${REPO_ROOT}/node_modules/.bin/openspec)"
                     HAS_OPENSPEC=true
-                } || {
-                    fail "Could not install OpenSpec CLI."
+                else
+                    fail "Could not install OpenSpec CLI. npm output:"
+                    tail -n 10 "$_npm_log" | sed 's/^/      /' >&2 || true
+                    echo "      Manual fix: npm install -g ${_openspec_install_spec}" >&2
                     HAS_OPENSPEC=false
-                }
-            }
+                fi
+                rm -f "$_npm_log"
+            fi
         else
             warn "Skipping OpenSpec install. Spec-driven workflow will be limited."
             HAS_OPENSPEC=false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specrails-core",
-  "version": "4.0.3",
+  "version": "4.0.5",
   "description": "AI agent workflow system for Claude Code — installs 12 specialized agents, orchestration commands, and persona-driven product discovery into any repository",
   "bin": {
     "specrails-core": "bin/specrails-core.js"

package/templates/commands/specrails/implement.md

@@ -48,7 +48,7 @@ gh auth status 2>&1
 which openspec && openspec --version
 ```
 
-- If missing: try `npm install -g @openspec/cli`
+- If missing: try `npm install -g @fission-ai/openspec`
 - If install fails: **STOP** — openspec is required.
 
 #### 3. Project dependencies

package/templates/skills/sr-implement/SKILL.md

@@ -48,7 +48,7 @@ gh auth status 2>&1
 which openspec && openspec --version
 ```
 
-- If missing: try `npm install -g @openspec/cli`
+- If missing: try `npm install -g @fission-ai/openspec`
 - If install fails: **STOP** — openspec is required.
 
 #### 3. Project dependencies