specrails-core 3.4.0 → 3.4.2

package/README.md

@@ -246,7 +246,7 @@ The plugin method has no Node.js requirement. The scaffold method checks for pre
 
 ## 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

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
 
 # ─────────────────────────────────────────────

package/commands/setup.md

@@ -39,7 +39,7 @@ Read the following files to understand the current installation state:
    }
    ```
    If this file does not exist, inform the user:
-   > "No `.specrails-manifest.json` found. This looks like a pre-versioning installation. Run `update.sh` first to initialize the manifest, then re-run `/setup --update`."
+   > "No `.specrails-manifest.json` found. This looks like a pre-versioning installation. Run `update.sh` first to initialize the manifest, then re-run `/specrails:setup --update`."
    Then stop.
 
 2. Read `.specrails-version` — contains the current version string (e.g., `0.2.0`). If it does not exist, treat version as `0.1.0 (legacy)`.
@@ -405,10 +405,10 @@ Fill placeholders with best-effort values from the limited context available:
 - `{{PROJECT_DESCRIPTION}}` → `QS_PROJECT_DESCRIPTION`
 - `{{TARGET_USERS}}` → `QS_TARGET_USERS`
 - `{{GIT_ACCESS}}` → `QS_GIT_ACCESS`
-- `{{ARCHITECTURE_DIAGRAM}}` → "(Lite Mode — run `/setup` for full architecture analysis)"
-- `{{TECH_EXPERTISE}}` → "(Lite Mode — run `/setup` for codebase-specific expertise)"
+- `{{ARCHITECTURE_DIAGRAM}}` → "(Lite Mode — run `/specrails:setup` for full architecture analysis)"
+- `{{TECH_EXPERTISE}}` → "(Lite Mode — run `/specrails:setup` for codebase-specific expertise)"
 - `{{LAYER_TAGS}}` → detect from package.json / Gemfile / go.mod if present; otherwise leave empty
-- All other placeholders → "(not configured — run `/setup`)"
+- All other placeholders → "(not configured — run `/specrails:setup`)"
 
 Create memory directories: `$SPECRAILS_DIR/agent-memory/sr-<name>/`
 
@@ -436,7 +436,7 @@ 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/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=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 /specrails: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/specrails/<name>.md` already exists:
 - If it exists: skip it — show `✓ Already installed: /specrails:<name>`
@@ -444,7 +444,7 @@ If `QS_IS_RERUN=true` (gap-fill mode): for each command in the list above, check
 
 **If `cli_provider == "codex"`:**
 
-If `QS_IS_RERUN=false` (fresh install): for each core command, read the corresponding skill template from `$SPECRAILS_DIR/setup-templates/skills/sr-<name>/SKILL.md`, substitute the backlog placeholders with local values and stub persona placeholders with `(Lite Mode — run /setup to configure personas)`, then write to `.agents/skills/sr-<name>/SKILL.md` (create the directory first).
+If `QS_IS_RERUN=false` (fresh install): for each core command, read the corresponding skill template from `$SPECRAILS_DIR/setup-templates/skills/sr-<name>/SKILL.md`, substitute the backlog placeholders with local values and stub persona placeholders with `(Lite Mode — run /specrails:setup to configure personas)`, then write to `.agents/skills/sr-<name>/SKILL.md` (create the directory first).
 
 If `QS_IS_RERUN=true` (gap-fill mode): for each command in the list above, check if `.agents/skills/sr-<name>/SKILL.md` already exists:
 - If it exists: skip it — show `✓ Already installed: $sr-<name>`
@@ -1154,7 +1154,7 @@ All write operations must follow the **advisory file locking protocol** defined
 | Placeholder | Substituted value |
 |-------------|-------------------|
 | `{{BACKLOG_PROVIDER_NAME}}` | `Local Tickets` |
-| `{{BACKLOG_PREFLIGHT}}` | `[[ -f "$SPECRAILS_DIR/local-tickets.json" ]] && echo "Local tickets storage: OK" \|\| echo "WARNING: $SPECRAILS_DIR/local-tickets.json not found — run /setup to initialize"` |
+| `{{BACKLOG_PREFLIGHT}}` | `[[ -f "$SPECRAILS_DIR/local-tickets.json" ]] && echo "Local tickets storage: OK" \|\| echo "WARNING: $SPECRAILS_DIR/local-tickets.json not found — run /specrails:setup to initialize"` |
 | `{{BACKLOG_FETCH_CMD}}` | Read `$SPECRAILS_DIR/local-tickets.json`. Parse the `tickets` map and return all entries where `status` is `"todo"` or `"in_progress"`. |
 | `{{BACKLOG_FETCH_ALL_CMD}}` | Read `$SPECRAILS_DIR/local-tickets.json`. Parse the `tickets` map and return all entries regardless of status. |
 | `{{BACKLOG_FETCH_CLOSED_CMD}}` | Read `$SPECRAILS_DIR/local-tickets.json`. Parse the `tickets` map and return all entries where `status` is `"done"` or `"cancelled"`. |
@@ -1270,7 +1270,7 @@ The setup process installed temporary files that are only needed during installa
 # 1. Remove setup templates (used as structural references during generation)
 rm -rf .claude/setup-templates/
 
-# 2. Remove the /setup command itself — it's a one-time installer, not a permanent command
+# 2. Remove the /specrails:setup command itself — it's a one-time installer, not a permanent command
 rm -f .claude/commands/setup.md
 
 # 3. Remove the specrails/ directory from the repo if it exists at the root

package/docs/changelog.md

@@ -33,7 +33,7 @@ All notable changes to SpecRails are listed here, newest first.
 
 ### Improvements
 
-- **`/setup --update` template checksums** — The update command now checks command template checksums before overwriting, so manual customizations are detected and preserved rather than silently clobbered.
+- **`/specrails:setup --update` template checksums** — The update command now checks command template checksums before overwriting, so manual customizations are detected and preserved rather than silently clobbered.
 
 ---
 
@@ -84,8 +84,8 @@ All notable changes to SpecRails are listed here, newest first.
 ### Agents
 
 - **Doc Sync agent enhanced** — Added drift detection with severity levels. The agent now classifies documentation drift as `critical`, `major`, or `minor` and prioritizes accordingly.
-- **Test Writer wired into `/setup`** — New installations now include the Test Writer agent by default.
-- **Security Reviewer wired into `/setup`** — New installations now include the Security Reviewer agent by default.
+- **Test Writer wired into `/specrails:setup`** — New installations now include the Test Writer agent by default.
+- **Security Reviewer wired into `/specrails:setup`** — New installations now include the Security Reviewer agent by default.
 
 ### Onboarding
 

package/docs/research/codex-compatibility-analysis.md

@@ -271,7 +271,7 @@ specrails-hub se comunica con specrails-core vía `integration-contract.json`. E
 | Codex memory system poco maduro | Alta | Bajo | Usar patterns file-based (MEMORY.md) en ambas |
 | API de subagentes distinta | Media | Alto | Abstraer en Skills para no depender de tool-calling nativo |
 | Double mantenimiento de templates | Media | Medio | Approach B minimiza esto |
-| Fragmentación de usuarios | Baja | Medio | UX clara en /setup para elegir provider |
+| Fragmentación de usuarios | Baja | Medio | UX clara en /specrails:setup para elegir provider |
 
 ---
 
@@ -338,7 +338,7 @@ Si el board aprueba proceder:
 | `/specrails:implement` | Slash command | Skill (mismo `SKILL.md`) |
 | `/specrails:product-backlog` | Slash command | Skill |
 | `/opsx:ff` | Slash command | Skill |
-| `/setup` | Slash command | `codex exec "run setup"` |
+| `/specrails:setup` | Slash command | `codex exec "run setup"` |
 | Agent `sr-architect` | `.claude/agents/sr-architect.md` | `.codex/agents/sr-architect.toml` |
 | Permissions | `.claude/settings.json` | `.codex/config.toml` |
 

package/docs/research/mcp-feasibility-analysis.md

@@ -34,7 +34,7 @@ MCP servers run as local processes (stdio) or remote services (HTTP+SSE). Any MC
 ### Distribution & Execution Model
 
 ```
-npx specrails-core@latest init    →   install.sh (bash)    →   /setup (Claude Code command)
+npx specrails-core@latest init    →   install.sh (bash)    →   /specrails:setup (Claude Code command)
                                         │                         │
                                         ├── Copy templates        ├── Detect codebase
                                         ├── Create dirs           ├── Generate agents
@@ -337,7 +337,7 @@ These capabilities require Claude Code's runtime and should NOT be exposed via M
 | `/specrails:batch-implement` | Requires git worktree isolation |
 | Agent invocation (sr-*) | Requires Claude Code's Agent subagent system |
 | OpenSpec artifact creation | Interactive, context-heavy (requires conversation) |
-| `/setup` wizard | Multi-step interactive configuration |
+| `/specrails:setup` wizard | Multi-step interactive configuration |
 | Template substitution (write) | Modifies project files, requires user consent |
 
 **Principle:** MCP = knowledge access. Claude Code = orchestration engine.

package/install.sh

@@ -3,7 +3,7 @@ set -euo pipefail
 
 # specrails installer
 # Installs the agent workflow system into any repository.
-# Step 1 of 2: Prerequisites + scaffold. Step 2: Run /setup inside Claude Code.
+# Step 1 of 2: Prerequisites + scaffold. Step 2: Run /specrails:setup inside Claude Code.
 
 # Detect pipe mode (curl | bash) vs local execution
 if [[ -z "${BASH_SOURCE[0]:-}" || "${BASH_SOURCE[0]:-}" == "bash" ]]; then
@@ -169,13 +169,13 @@ generate_manifest() {
         artifacts_json="${artifacts_json},"
     fi
     artifacts_json="${artifacts_json}
-    \"commands/setup.md\": \"${setup_checksum}\""
+    \"commands/specrails/setup.md\": \"${setup_checksum}\""
 
     # Include commands/doctor.md
     local doctor_checksum
     doctor_checksum="sha256:$(shasum -a 256 "$SCRIPT_DIR/commands/doctor.md" | awk '{print $1}')"
     artifacts_json="${artifacts_json},
-    \"commands/doctor.md\": \"${doctor_checksum}\""
+    \"commands/specrails/doctor.md\": \"${doctor_checksum}\""
 
     cat > "$REPO_ROOT/.specrails-manifest.json" << EOF
 {
@@ -433,8 +433,8 @@ if command -v jira &> /dev/null; then
     HAS_JIRA=true
 else
     HAS_JIRA=false
-    # Don't warn here — JIRA is only relevant if chosen during /setup.
-    # If the user selects JIRA in /setup and it's not installed, the setup
+    # Don't warn here — JIRA is only relevant if chosen during /specrails:setup.
+    # If the user selects JIRA in /specrails:setup and it's not installed, the setup
     # wizard will offer to install it (go-jira via brew/go, or Atlassian CLI).
 fi
 
@@ -491,7 +491,7 @@ if [[ "$CLI_PROVIDER" == "codex" ]]; then
     mkdir -p "$REPO_ROOT/.agents/skills/setup"
     mkdir -p "$REPO_ROOT/.agents/skills/doctor"
 else
-    mkdir -p "$REPO_ROOT/$SPECRAILS_DIR/commands"
+    mkdir -p "$REPO_ROOT/$SPECRAILS_DIR/commands/specrails"
 fi
 mkdir -p "$REPO_ROOT/$SPECRAILS_DIR/setup-templates/agents"
 mkdir -p "$REPO_ROOT/$SPECRAILS_DIR/setup-templates/commands"
@@ -503,7 +503,7 @@ mkdir -p "$REPO_ROOT/$SPECRAILS_DIR/setup-templates/settings"
 mkdir -p "$REPO_ROOT/$SPECRAILS_DIR/setup-templates/prompts"
 mkdir -p "$REPO_ROOT/$SPECRAILS_DIR/agent-memory/explanations"
 
-# Copy the /setup and /doctor commands (or skills for Codex)
+# Copy the /specrails:setup and /specrails:doctor commands (or skills for Codex)
 if [[ "$CLI_PROVIDER" == "codex" ]]; then
     # Codex uses Agent Skills in .agents/skills/<name>/SKILL.md
     {
@@ -536,12 +536,12 @@ if [[ "$CLI_PROVIDER" == "codex" ]]; then
     } > "$REPO_ROOT/.agents/skills/doctor/SKILL.md"
     ok "Installed \$doctor skill"
 else
-    # Claude Code uses commands in .claude/commands/
-    cp "$SCRIPT_DIR/commands/setup.md" "$REPO_ROOT/$SPECRAILS_DIR/commands/setup.md"
-    ok "Installed /setup command"
+    # Claude Code uses commands in .claude/commands/specrails/ (namespaced as /specrails:*)
+    cp "$SCRIPT_DIR/commands/setup.md" "$REPO_ROOT/$SPECRAILS_DIR/commands/specrails/setup.md"
+    ok "Installed /specrails:setup command"
 
-    cp "$SCRIPT_DIR/commands/doctor.md" "$REPO_ROOT/$SPECRAILS_DIR/commands/doctor.md"
-    ok "Installed /doctor command"
+    cp "$SCRIPT_DIR/commands/doctor.md" "$REPO_ROOT/$SPECRAILS_DIR/commands/specrails/doctor.md"
+    ok "Installed /specrails:doctor command"
 fi
 
 # Install bin/doctor.sh for standalone use
@@ -556,7 +556,7 @@ tar -C "$SCRIPT_DIR/templates" --exclude='node_modules' --exclude='package-lock.
     | tar -C "$REPO_ROOT/$SPECRAILS_DIR/setup-templates/" -xf -
 ok "Installed setup templates (commands + skills)"
 
-# Write OSS detection results for /setup
+# Write OSS detection results for /specrails:setup
 cat > "$REPO_ROOT/$SPECRAILS_DIR/setup-templates/.oss-detection.json" << EOF
 {
   "is_oss": $IS_OSS,
@@ -632,7 +632,7 @@ if [[ "$CLI_PROVIDER" == "codex" ]]; then
     echo "    .agents/skills/setup/SKILL.md        ← The \$setup skill"
     echo "    .agents/skills/doctor/SKILL.md       ← The \$doctor skill"
 else
-    echo "    $SPECRAILS_DIR/commands/setup.md          ← The /setup command"
+    echo "    $SPECRAILS_DIR/commands/specrails/setup.md  ← The /specrails:setup command"
 fi
 echo "    $SPECRAILS_DIR/setup-templates/           ← Templates: commands + skills (temporary, removed after setup)"
 echo "    .specrails-version                       ← Installed specrails version"
@@ -658,7 +658,7 @@ echo ""
 if [[ "$CLI_PROVIDER" == "codex" ]]; then
     echo -e "     ${BOLD}\$setup${NC}"
 else
-    echo -e "     ${BOLD}/setup${NC}"
+    echo -e "     ${BOLD}/specrails:setup${NC}"
 fi
 echo ""
 if [[ "$CLI_PROVIDER" == "codex" ]]; then

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specrails-core",
-  "version": "3.4.0",
+  "version": "3.4.2",
   "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/agents/sr-reviewer.md

@@ -57,7 +57,7 @@ These are the most common reasons code passes locally but fails in CI:
 
 The orchestrator runs specialized layer reviewers in parallel before you launch. Their reports are injected here. A value of `"SKIPPED"` means no files of that layer type were in the changeset.
 
-**These are NOT `/setup` placeholders. They use `[injected]` notation, not `{{...}}` notation.** The `[injected]` markers below are replaced by the actual report text when the orchestrator launches you.
+**These are NOT `/specrails:setup` placeholders. They use `[injected]` notation, not `{{...}}` notation.** The `[injected]` markers below are replaced by the actual report text when the orchestrator launches you.
 
 FRONTEND_REVIEW_REPORT:
 [injected]

package/templates/claude-md/CLAUDE-quickstart.md

@@ -46,7 +46,7 @@ specrails doctor
 Or inside Claude Code:
 
 ```
-/doctor
+/specrails:doctor
 ```
 
 ---

package/templates/commands/specrails/doctor.md

@@ -0,0 +1,62 @@
+# Doctor: specrails Health Check
+
+Run the specrails health check to validate that all prerequisites are correctly configured for this repository.
+
+---
+
+## What it checks
+
+| Check | Pass condition |
+|-------|---------------|
+| Claude Code CLI | `claude` binary found in PATH |
+| Claude API key | `claude config list` shows a key OR `ANTHROPIC_API_KEY` env var set |
+| Agent files | `agents/` directory exists with at least 1 `AGENTS.md` file |
+| CLAUDE.md | `CLAUDE.md` present in the repo root |
+| Git initialized | `.git/` directory present |
+| npm | `npm` binary found in PATH |
+
+## How to run
+
+This command delegates to the standalone health check script installed at `.specrails/bin/doctor.sh`. Run it directly:
+
+```
+Bash tool: bash .specrails/bin/doctor.sh
+```
+
+Or via the npm CLI wrapper:
+
+```
+npx specrails-core@latest doctor
+```
+
+## Output
+
+Each check is displayed as ✅ (pass) or ❌ (fail with fix instruction).
+
+On all checks passed:
+```
+All 6 checks passed. Run /specrails:product-backlog to get started.
+```
+
+On failure:
+```
+❌ API key: not configured
+   Fix: Run: claude config set api_key <your-key>  |  Get a key: https://console.anthropic.com/
+
+1 check(s) failed.
+```
+
+## Exit codes
+
+- `0` — all checks passed
+- `1` — one or more checks failed
+
+## Log file
+
+Each run appends a timestamped summary to `~/.specrails/doctor.log`:
+
+```
+2026-03-20T10:00:00Z  checks=6 passed=6 failed=0
+```
+
+The `~/.specrails/` directory is created automatically if it does not exist.

package/templates/commands/specrails/refactor-recommender.md

@@ -40,7 +40,7 @@ Always exclude the following from all analysis:
 
 ## Phase 1.5: VPC Context
 
-Check whether persona files exist at `.claude/agents/personas/`. This path is present in any repo that has run `/setup`.
+Check whether persona files exist at `.claude/agents/personas/`. This path is present in any repo that has run `/specrails:setup`.
 
 ```bash
 ls .claude/agents/personas/ 2>/dev/null
@@ -208,5 +208,5 @@ Issues created: {N}  (or "dry-run: no issues created")
 ```
 
 Where:
-- `{vpc_header}` is `VPC personas loaded: {persona names}` when `VPC_AVAILABLE=true`, or `VPC personas: not found (run /setup to enable)` otherwise.
+- `{vpc_header}` is `VPC personas loaded: {persona names}` when `VPC_AVAILABLE=true`, or `VPC personas: not found (run /specrails:setup to enable)` otherwise.
 - `{vpc_detail}` is `**VPC Value**: {vpc_value}/5 — {vpc_persona}: {vpc_rationale}` when `VPC_AVAILABLE=true`, omitted otherwise.