specrails-core 1.7.1 → 1.7.3

package/VERSION

@@ -1 +1 @@
-0.7.1
+1.7.2

package/bin/doctor.sh

@@ -35,13 +35,22 @@ else
 fi
 
 # ─────────────────────────────────────────────
-# Check 2: Claude API key
+# Check 2: Claude authentication
 # ─────────────────────────────────────────────
 if command -v claude &>/dev/null; then
-    if claude config list 2>/dev/null | grep -q "api_key" || [[ -n "${ANTHROPIC_API_KEY:-}" ]]; then
-        pass "API key: configured"
+    _claude_authed=false
+    if claude config list 2>/dev/null | grep -q "api_key"; then
+        _claude_authed=true
+    elif [[ -n "${ANTHROPIC_API_KEY:-}" ]]; then
+        _claude_authed=true
+    elif [[ -f "${HOME}/.claude.json" ]] && grep -q '"oauthAccount"' "${HOME}/.claude.json" 2>/dev/null; then
+        _claude_authed=true
+    fi
+
+    if [[ "$_claude_authed" == "true" ]]; then
+        pass "Claude: authenticated"
     else
-        fail "API key: not configured" "Run: claude config set api_key <your-key>  |  Get a key: https://console.anthropic.com/"
+        fail "Claude: not authenticated" "Option 1: claude config set api_key <your-key>  |  Option 2: claude auth login"
     fi
 fi
 

package/bin/specrails-core.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-const { execSync } = require("child_process");
+const { spawnSync } = require("child_process");
 const { resolve } = require("path");
 
 const ROOT = resolve(__dirname, "..");
@@ -33,11 +33,28 @@ if (!script) {
   process.exit(1);
 }
 
-const forwarded = args.slice(1).join(" ");
-const cmd = `bash "${resolve(ROOT, script)}" ${forwarded}`.trim();
+// Allowlisted flags per subcommand (defense-in-depth — spawnSync already
+// prevents shell injection, but an explicit allowlist rejects unknown flags
+// before the shell script is ever invoked).
+const ALLOWED_FLAGS = {
+  init: ["--root-dir", "--yes", "-y"],
+  update: ["--only"],
+  doctor: [],
+};
+
+const subargs = args.slice(1);
+const allowed = ALLOWED_FLAGS[subcommand] ?? [];
 
-try {
-  execSync(cmd, { stdio: "inherit", cwd: process.cwd() });
-} catch (err) {
-  process.exit(err.status || 1);
+for (const arg of subargs) {
+  if (arg.startsWith("-") && !allowed.includes(arg)) {
+    console.error(`Unknown flag: ${arg}`);
+    process.exit(1);
+  }
 }
+
+const result = spawnSync("bash", [resolve(ROOT, script), ...subargs], {
+  stdio: "inherit",
+  cwd: process.cwd(),
+});
+
+process.exit(result.status ?? (result.error ? 1 : 0));

package/docs/changelog.md

@@ -141,7 +141,7 @@ All commands renamed from `/<name>` to `/sr:<name>`. All agent files renamed fro
 - `update.sh` auto-migrates command namespace changes
 
 **Distribution**
-- `npx specrails@latest init`
+- `npx specrails-core@latest init`
 - `curl | bash` installer
 - `--root-dir` flag for monorepo support
 - `--yes` flag for non-interactive CI installs

package/docs/deployment.md

@@ -18,7 +18,7 @@ SpecRails runs locally — no cloud infrastructure required. Choose the setup th
 The fastest way to get started. No install required.
 
 ```bash
-npx specrails@latest setup
+npx specrails-core@latest setup
 ```
 
 This will:

package/docs/getting-started.md

@@ -27,7 +27,7 @@ Pick your preferred method:
 **npx (recommended)**
 
 ```bash
-npx specrails@latest init --root-dir <your-project>
+npx specrails-core@latest init --root-dir <your-project>
 ```
 
 **git clone**

package/docs/installation.md

@@ -32,7 +32,7 @@ The installer checks for all of these and offers to install missing tools.
 ### From npx (recommended)
 
 ```bash
-npx specrails@latest init --root-dir <your-project>
+npx specrails-core@latest init --root-dir <your-project>
 ```
 
 No cloning required. Downloads the latest version and runs the installer automatically.

package/docs/user-docs/cli-reference.md

@@ -0,0 +1,328 @@
+# CLI Reference
+
+All commands are Claude Code slash commands. Run them inside Claude Code (`claude`) from your project directory.
+
+---
+
+## Core workflow
+
+### `/sr:implement`
+
+Implement a feature through the full agent pipeline: design → code → tests → docs → review → PR.
+
+```
+/sr:implement #85
+/sr:implement #85, #71, #63
+/sr:implement "add a health check endpoint"
+/sr:implement UI, Analytics
+```
+
+**Flags:**
+
+| Flag | Effect |
+|------|--------|
+| `--dry-run` / `--preview` | Run the full pipeline without git operations or PR creation |
+| `--apply <name>` | Apply a previously cached dry-run |
+
+**Pipeline phases:**
+
+| Phase | Agent | What happens |
+|-------|-------|-------------|
+| 3a | Architect | Designs the implementation, creates a task list |
+| 3b | Developer | Writes code across all affected layers |
+| 3c | Test Writer | Generates tests for new code |
+| 3d | Doc Sync | Updates CHANGELOG and relevant docs |
+| 4 | Security Reviewer | Scans for secrets and vulnerabilities |
+| 4b | Reviewer | Runs your CI suite, fixes lint/type errors |
+| 4b-conf | — | Confidence gate: scores implementation across 5 dimensions |
+| 5 | — | Creates a pull request |
+
+**Single vs. parallel:**
+
+A single issue runs sequentially on the current branch. Multiple issues run in parallel — each gets an isolated git worktree, and results are merged automatically.
+
+---
+
+### `/sr:retry`
+
+Resume a failed `/sr:implement` run from the last successful phase.
+
+```
+/sr:retry <feature-name>
+/sr:retry --list
+/sr:retry <feature-name> --from architect
+/sr:retry <feature-name> --dry-run
+```
+
+**Flags:**
+
+| Flag | Effect |
+|------|--------|
+| `--list` | List all saved pipeline states |
+| `--from <phase>` | Force resume from a specific phase |
+| `--dry-run` | Resume in preview mode |
+
+**Valid `--from` values:** `architect`, `developer`, `test-writer`, `doc-sync`, `reviewer`, `ship`, `ci`
+
+Pipeline state is saved to `.claude/pipeline-state/<feature-name>.json` after each phase.
+
+---
+
+### `/sr:batch-implement`
+
+Implement multiple independent features in parallel using git worktrees.
+
+```
+/sr:batch-implement #85, #71, #63
+```
+
+Each feature gets its own worktree, its own agent pipeline, and its own PR. Use this instead of `/sr:implement` with multiple issues when you want explicit control over parallel execution.
+
+---
+
+## Product and backlog
+
+### `/sr:product-backlog`
+
+View your prioritized product backlog, ranked by VPC persona fit and estimated effort.
+
+```
+/sr:product-backlog
+/sr:product-backlog UI, API
+```
+
+Reads GitHub Issues labeled `product-driven-backlog`. Produces a ranked table per area, top 3 recommendations, and a safe implementation order based on issue dependencies.
+
+---
+
+### `/sr:update-product-driven-backlog`
+
+Generate new feature ideas through product discovery and create GitHub Issues.
+
+```
+/sr:update-product-driven-backlog
+/sr:update-product-driven-backlog UI, API
+```
+
+The Product Manager researches your competitive landscape, generates 2–4 feature ideas per area, and scores each against your user personas. Creates GitHub Issues with full VPC evaluation if write access is available.
+
+---
+
+## Analysis and inspection
+
+### `/sr:health-check`
+
+Run a comprehensive codebase quality analysis.
+
+```
+/sr:health-check
+```
+
+Analyzes code quality, test coverage, technical debt, complexity, and dependency health. Compares with previous runs to detect regressions.
+
+---
+
+### `/sr:refactor-recommender`
+
+Scan the codebase for refactoring opportunities, ranked by impact/effort ratio.
+
+```
+/sr:refactor-recommender
+```
+
+Identifies duplicates, overly long functions, large files, dead code, outdated patterns, and complex logic. Optionally creates GitHub Issues for tracking.
+
+---
+
+### `/sr:compat-check`
+
+Analyze the backwards-compatibility impact of a proposed change.
+
+```
+/sr:compat-check #85
+/sr:compat-check #85 --save
+```
+
+Detects removed endpoints, changed method signatures, changed response shapes, and behavioral changes. When breaking changes are found, generates a migration guide.
+
+`--save` updates the stored API baseline so future checks compare against the new surface.
+
+The Architect runs this automatically as part of every `/sr:implement` pipeline.
+
+---
+
+### `/sr:why`
+
+Search agent explanation records in plain language.
+
+```
+/sr:why "why did we choose this database schema"
+/sr:why "explain the auth middleware design"
+/sr:why "why is pagination implemented this way"
+```
+
+Agents write decision rationale to `.claude/agent-memory/explanations/` as they work. `/sr:why` searches these records semantically. Useful for onboarding, code review, and revisiting past decisions.
+
+---
+
+### `/sr:vpc-drift`
+
+Detect when your VPC personas have drifted from what your product actually delivers.
+
+```
+/sr:vpc-drift
+/sr:vpc-drift --persona "Alex,Sara"
+/sr:vpc-drift --verbose
+/sr:vpc-drift --format json
+```
+
+Compares persona Jobs/Pains/Gains against your backlog, implemented features, and agent memory. Produces a per-persona alignment score and recommendations for updating your VPC.
+
+---
+
+### `/sr:memory-inspect`
+
+Inspect and clean up agent memory directories.
+
+```
+/sr:memory-inspect
+/sr:memory-inspect sr-developer
+/sr:memory-inspect --stale 14
+/sr:memory-inspect --prune
+```
+
+**Flags:**
+
+| Flag | Effect |
+|------|--------|
+| `--stale <days>` | Flag files older than N days |
+| `--prune` | Delete stale files (prompts for confirmation) |
+
+Agent memory lives in `.claude/agent-memory/sr-*/`.
+
+---
+
+### `/sr:propose-spec`
+
+Explore a feature idea and produce a structured proposal ready for the OpenSpec pipeline.
+
+```
+/sr:propose-spec "add rate limiting to the API"
+```
+
+Produces: problem statement, proposed solution, out-of-scope items, acceptance criteria, technical considerations, and a complexity estimate.
+
+---
+
+## OpenSpec commands
+
+OpenSpec is the structured design-to-code workflow. Use these commands when you want explicit control over each artifact: proposal → design → tasks → implementation.
+
+### `/opsx:ff` — Fast Forward
+
+Create all OpenSpec artifacts at once (proposal + design + tasks + context bundle), then hand off to the developer.
+
+```
+/opsx:ff
+```
+
+Use this when you know what you want to build and don't need to review each artifact step by step.
+
+---
+
+### `/opsx:new` — New Change
+
+Start a new change by creating a proposal. Advances through artifacts one at a time.
+
+```
+/opsx:new
+```
+
+---
+
+### `/opsx:continue` — Continue Change
+
+Create the next artifact in the sequence for the current in-progress change.
+
+```
+/opsx:continue
+```
+
+Typical sequence: proposal → design → tasks → context bundle.
+
+---
+
+### `/opsx:apply` — Apply Change
+
+Implement the tasks from a designed change. Hands off to the Developer agent.
+
+```
+/opsx:apply
+```
+
+---
+
+### `/opsx:verify` — Verify Change
+
+Validate that the implementation matches the change artifacts before archiving.
+
+```
+/opsx:verify
+```
+
+---
+
+### `/opsx:archive` — Archive Change
+
+Finalize and archive a completed change.
+
+```
+/opsx:archive
+```
+
+---
+
+### `/opsx:explore` — Explore
+
+Open-ended thinking mode for brainstorming, investigating problems, or clarifying requirements before starting a change.
+
+```
+/opsx:explore
+```
+
+---
+
+### Typical OpenSpec flows
+
+**Fast path:**
+```
+/opsx:ff       → create all artifacts
+/opsx:apply    → implement
+/opsx:verify   → validate
+/opsx:archive  → finalize
+```
+
+**Step by step:**
+```
+/opsx:new      → proposal
+/opsx:continue → design
+/opsx:continue → tasks
+/opsx:continue → context bundle
+/opsx:apply    → implement
+/opsx:archive  → finalize
+```
+
+---
+
+## Installer flags
+
+The `npx specrails-core@latest init` command accepts:
+
+| Flag | Effect |
+|------|--------|
+| `--root-dir <path>` | Install into this directory (default: current directory) |
+| `--yes` / `-y` | Skip confirmation prompts |
+
+---
+
+[← Quick Start](quick-start.md) · [FAQ →](faq.md) · [← Installation](installation.md)

package/docs/user-docs/faq.md

@@ -0,0 +1,137 @@
+# FAQ
+
+## Setup and installation
+
+**Do I need a Claude API account to use SpecRails?**
+
+Yes. SpecRails runs on top of Claude Code, which requires an Anthropic account. Claude Code handles authentication — SpecRails just orchestrates it. See [Claude Code's installation guide](https://docs.anthropic.com/en/docs/claude-code) for setup.
+
+**What does the installer actually do to my project?**
+
+It creates a `.claude/` directory with agent templates, commands, and configuration files. It does not modify your source code, create commits, or push anything. Your project is unchanged — `.claude/` is the only addition.
+
+**Do I need Node.js if my project is not JavaScript?**
+
+Yes. Node 18+ is required to run `npx specrails-core@latest`. Once installed, SpecRails works with any language or framework — the agents adapt to whatever stack your project uses.
+
+**Can I run SpecRails on a project that doesn't have GitHub Issues?**
+
+Yes. During `/setup`, you can choose "none" as your backlog provider. Commands like `/sr:implement` will accept plain text descriptions instead of issue numbers:
+
+```
+/sr:implement "add rate limiting to the API"
+```
+
+**How long does /setup take?**
+
+About 5 minutes. Most of the time is spent on Phase 2 (persona generation), which does web research on your domain.
+
+---
+
+## Using SpecRails
+
+**Can I run SpecRails on an existing project with existing code?**
+
+Yes, that's the intended use case. The `/setup` wizard analyzes your existing codebase — your tech stack, layers, CI commands, and conventions — and generates agents configured specifically for it.
+
+**Does /sr:implement always create a PR?**
+
+By default, yes. If you want to preview the changes first without creating commits or a PR, use dry-run mode:
+
+```
+/sr:implement --dry-run "add dark mode"
+```
+
+Then apply the cached result when you're ready:
+
+```
+/sr:implement --apply dark-mode
+```
+
+**What happens if the pipeline fails mid-run?**
+
+SpecRails saves pipeline state after each phase. If a run fails, use `/sr:retry` to resume from the last successful phase instead of starting over:
+
+```
+/sr:retry dark-mode
+```
+
+**Can I implement multiple features at once?**
+
+Yes. Pass multiple issue numbers or descriptions:
+
+```
+/sr:implement #42, #43, #44
+```
+
+Each feature gets an isolated git worktree. Pipelines run concurrently and the results are merged automatically at the end.
+
+**Can I customize the agents?**
+
+Yes. After setup, the generated agent files are in `.claude/agents/`. Edit them directly to change behavior, add constraints, or update instructions. Changes take effect on the next run.
+
+For layer-specific coding conventions, edit `.claude/rules/*.md`.
+
+**What is a VPC persona?**
+
+VPC stands for Value Proposition Canvas. Personas are structured profiles of your target users with their Jobs (what they're trying to accomplish), Pains (what frustrates them), and Gains (what they want). The Product Manager and Architect use these to make better design decisions. They're generated during `/setup` and stored in `.claude/agents/personas/`.
+
+---
+
+## Project compatibility
+
+**Does SpecRails work with monorepos?**
+
+Yes. During `/setup`, the architect detects your monorepo structure and generates separate layer configurations for each package or service.
+
+**Which languages and frameworks are supported?**
+
+SpecRails works with any stack. The agents are general-purpose and adapt based on what `/setup` detects in your codebase. It's been used with Node.js, Python, Go, Ruby, Rust, and mixed-stack projects.
+
+**Does it work with private repositories?**
+
+Yes, for code generation. For features that require GitHub integration (PR creation, Issue reading), you need the GitHub CLI authenticated against your private repo.
+
+---
+
+## Keeping SpecRails up to date
+
+**How do I update SpecRails?**
+
+Run the installer again in your project:
+
+```bash
+npx specrails-core@latest init --root-dir .
+```
+
+Then re-run `/setup` to regenerate agents with any new templates. See the [updating guide](../updating.md) for details.
+
+**How do I know which version is installed?**
+
+```bash
+cat .specrails-version
+```
+
+---
+
+## Troubleshooting
+
+**The /setup command isn't available after installing.**
+
+Claude Code loads commands from `.claude/commands/`. Make sure you opened Claude Code from inside your project directory (the one where you ran `npx specrails-core@latest init`).
+
+**Generated files contain `{{PLACEHOLDER}}` text.**
+
+The `/setup` wizard did not complete all phases. Re-run `/setup` — it will pick up where it left off.
+
+**The pipeline created a PR but the CI checks failed.**
+
+The reviewer agent runs your CI suite and attempts to fix failures automatically. If it can't fix them within its budget, it creates the PR with a note describing what failed and why. You can fix the remaining issues manually or run `/sr:retry` to try the reviewer phase again.
+
+**I got a "409 Conflict" error during a pipeline run.**
+
+This means another agent tried to check out the same issue simultaneously. The pipeline will detect this and stop — re-run the command after the conflicting run finishes.
+
+---
+
+[← Quick Start](quick-start.md) · [CLI Reference →](cli-reference.md)

package/docs/user-docs/installation.md

@@ -0,0 +1,114 @@
+# Installation
+
+Install SpecRails into any git repository in two steps: run the installer, then run `/setup` inside Claude Code.
+
+## Requirements
+
+| Tool | Version | Notes |
+|------|---------|-------|
+| **Node.js** | 18+ | Required for the installer |
+| **Claude Code** | Latest | The AI CLI that runs the agents — [install guide](https://docs.anthropic.com/en/docs/claude-code) |
+| **Git** | Any | Your project must be a git repository |
+
+Optional but recommended:
+
+| Tool | Why |
+|------|-----|
+| **GitHub CLI** (`gh`) | Automatic PR creation and Issue integration |
+
+## Install
+
+Run the installer from inside your project directory:
+
+```bash
+cd your-project
+npx specrails-core@latest init --root-dir .
+```
+
+The installer copies agent templates, commands, and configuration files into `.claude/` inside your project. It does not modify your existing code.
+
+### Flags
+
+| Flag | Effect |
+|------|--------|
+| `--root-dir <path>` | Target directory (default: current directory) |
+| `--yes` / `-y` | Skip confirmation prompts |
+
+### What gets installed
+
+```
+your-project/
+└── .claude/
+    ├── commands/setup.md         # The /setup wizard
+    ├── setup-templates/          # Agent and command templates
+    ├── web-manager/              # Pipeline Monitor dashboard (optional)
+    └── security-exemptions.yaml  # Security scanner config
+```
+
+The installer also writes `.specrails-version` and `.specrails-manifest.json` to track the installed version.
+
+## Configure with /setup
+
+After installation, open Claude Code in your project and run the setup wizard:
+
+```bash
+claude    # open Claude Code
+```
+
+```
+/setup
+```
+
+The wizard runs 5 phases:
+
+| Phase | What happens |
+|-------|-------------|
+| **1. Analyze** | Detects your tech stack, architecture layers, and CI commands |
+| **2. Personas** | Researches your domain and generates VPC user profiles |
+| **3. Configure** | Asks about your backlog provider, git workflow, and agent selection |
+| **4. Generate** | Fills all templates with your project-specific context |
+| **5. Cleanup** | Removes setup files, leaving only your tailored workflow |
+
+After setup, `.claude/` contains fully configured agents and commands ready to use. The `/setup` command removes itself — it only runs once.
+
+## Verify
+
+Check that everything installed correctly:
+
+```bash
+# List generated agents
+ls .claude/agents/
+
+# Check for unresolved placeholders (should return nothing)
+grep -r '{{[A-Z_]*}}' .claude/agents/ .claude/commands/ .claude/rules/
+
+# Check the installed version
+cat .specrails-version
+```
+
+## Troubleshooting
+
+### "This appears to be the specrails source repository"
+
+You ran the installer from inside the SpecRails source repo. Run it from your target project instead:
+
+```bash
+cd /path/to/your-project
+npx specrails-core@latest init --root-dir .
+```
+
+### Existing `.claude/` directory detected
+
+The installer warns if SpecRails artifacts already exist. You can merge (install alongside existing files) or abort to review manually.
+
+### Placeholders not resolved
+
+If you see `{{PLACEHOLDER}}` in generated files, the `/setup` wizard did not complete. Re-run `/setup` or fill the values manually.
+
+### Claude Code not found
+
+Install Claude Code following [Anthropic's guide](https://docs.anthropic.com/en/docs/claude-code), then re-run the installer.
+
+---
+
+[Quick Start →](quick-start.md) · [CLI Reference →](cli-reference.md)

package/docs/user-docs/quick-start.md

@@ -0,0 +1,158 @@
+# Quick Start
+
+Get SpecRails running in your project in under 10 minutes.
+
+## Before you begin
+
+You need:
+- **Node.js 18+** — check with `node --version`
+- **Claude Code** — install from [docs.anthropic.com/en/docs/claude-code](https://docs.anthropic.com/en/docs/claude-code)
+- **A git repository** — your project must have a `.git` directory
+
+Optional:
+- **GitHub CLI** (`gh`) — enables automatic PR creation
+
+## Step 1: Install
+
+From inside your project directory:
+
+```bash
+npx specrails-core@latest init --root-dir .
+```
+
+Expected output:
+
+```
+✓ Prerequisites checked
+✓ Templates installed → .claude/
+✓ Version tracked → .specrails-version
+```
+
+This copies agent templates and commands into `.claude/`. Your existing code is not touched.
+
+## Step 2: Run the setup wizard
+
+Open Claude Code in your project:
+
+```bash
+claude
+```
+
+Then run:
+
+```
+/setup
+```
+
+The wizard runs automatically and takes about 5 minutes. It analyzes your codebase and configures SpecRails for your specific project:
+
+```
+Phase 1/5  Analyzing codebase...
+           → Detected: TypeScript, Express, PostgreSQL
+           → Found 3 architecture layers
+           → Identified CI commands: npm test, npm run lint
+
+Phase 2/5  Generating user personas...
+           → Researching your domain
+           → Created 3 VPC profiles
+
+Phase 3/5  Configuration...
+           → Backlog provider: GitHub Issues
+           → Git workflow: trunk-based
+
+Phase 4/5  Generating files...
+           → sr-architect.md (adapted to your stack)
+           → sr-developer.md (knows your CI commands)
+           → sr-reviewer.md (runs your specific checks)
+           → 9 more agents
+
+Phase 5/5  Cleanup complete. /setup removed.
+
+✓ SpecRails is ready. Run /sr:implement to start building.
+```
+
+After setup, the `/setup` command is gone — it's a one-time wizard.
+
+## Step 3: Implement your first feature
+
+Pick something small. Either reference a GitHub Issue or describe it in plain text:
+
+```
+/sr:implement #42
+```
+
+or:
+
+```
+/sr:implement "add a health check endpoint to the API"
+```
+
+The pipeline runs automatically:
+
+```
+Phase 3a  Architect designing...
+          → Design: GET /health endpoint + middleware
+          → Tasks: 3 steps
+
+Phase 3b  Developer implementing...
+          → src/routes/health.ts (created)
+          → src/middleware/health.ts (created)
+          → src/app.ts (modified)
+
+Phase 3c  Test Writer generating...
+          → tests/routes/health.test.ts (created)
+          → 5 tests, all passing
+
+Phase 3d  Doc Sync updating...
+          → CHANGELOG.md updated
+
+Phase 4   Security Reviewer scanning...
+          → No critical findings
+
+Phase 4b  Reviewer running CI...
+          → ✓ lint   ✓ typecheck   ✓ tests
+
+Phase 4b-conf  Confidence: 91% — threshold met
+
+PR #43 created: feat: add health check endpoint
+```
+
+One command. The PR is ready for human review.
+
+## What's next?
+
+**Explore the backlog:**
+
+```
+/sr:product-backlog
+```
+
+See your GitHub Issues ranked by persona fit and effort. The top 3 are safe to implement next.
+
+**Generate new feature ideas:**
+
+```
+/sr:update-product-driven-backlog
+```
+
+The Product Manager researches your competitive landscape and creates well-formed GitHub Issues for new features.
+
+**Run multiple features in parallel:**
+
+```
+/sr:implement #42, #43, #44
+```
+
+Each feature gets its own git worktree. Pipelines run concurrently and merge automatically.
+
+**Ask why a decision was made:**
+
+```
+/sr:why "why did we choose this database schema"
+```
+
+Agents record their reasoning as they work. `/sr:why` searches those records in plain language.
+
+---
+
+[← Installation](installation.md) · [CLI Reference →](cli-reference.md) · [FAQ →](faq.md)

package/install.sh

@@ -200,16 +200,25 @@ else
     exit 1
 fi
 
-# 1.3 API key
-if claude config list 2>/dev/null | grep -q "api_key" || [[ -n "${ANTHROPIC_API_KEY:-}" ]]; then
-    ok "Claude API key: configured"
+# 1.3 Claude authentication (API key or OAuth)
+CLAUDE_AUTHED=false
+if claude config list 2>/dev/null | grep -q "api_key"; then
+    CLAUDE_AUTHED=true
+elif [[ -n "${ANTHROPIC_API_KEY:-}" ]]; then
+    CLAUDE_AUTHED=true
+elif [[ -f "${HOME}/.claude.json" ]] && grep -q '"oauthAccount"' "${HOME}/.claude.json" 2>/dev/null; then
+    CLAUDE_AUTHED=true
+fi
+
+if [[ "$CLAUDE_AUTHED" == "true" ]]; then
+    ok "Claude: authenticated"
 elif [[ "$SKIP_PREREQS" == "1" ]]; then
-    warn "No Claude API key configured (skipped — SPECRAILS_SKIP_PREREQS=1)"
+    warn "Claude authentication not found (skipped — SPECRAILS_SKIP_PREREQS=1)"
 else
-    fail "No Claude API key configured."
+    fail "No Claude authentication found."
     echo ""
-    echo "    Set it:  claude config set api_key <your-key>"
-    echo "    Get one: https://console.anthropic.com/"
+    echo "    Option 1 (API key): claude config set api_key <your-key>"
+    echo "    Option 2 (OAuth):   claude auth login"
     exit 1
 fi
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specrails-core",
-  "version": "1.7.1",
+  "version": "1.7.3",
   "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/update.sh

@@ -390,7 +390,7 @@ do_migrate_sr_prefix() {
         if [[ -f "$src" ]] && [[ ! -f "$dst" ]]; then
             mv "$src" "$dst"
             info "Renamed: agents/${agent}.md → agents/sr-${agent}.md"
-            ((migrated_agents++))
+            migrated_agents=$(( migrated_agents + 1 ))
         fi
     done
 
@@ -408,7 +408,7 @@ do_migrate_sr_prefix() {
             if [[ ! -f "$persona_dst" ]]; then
                 mv "$persona_file" "$persona_dst"
                 info "Renamed: personas/${persona_basename} → personas/sr-${persona_basename}"
-                ((migrated_agents++))
+                migrated_agents=$(( migrated_agents + 1 ))
             fi
         done < <(find "$personas_dir" -maxdepth 1 -name "*.md" -not -name "sr-*.md" -print0 2>/dev/null)
     fi
@@ -433,7 +433,7 @@ do_migrate_sr_prefix() {
             if [[ -f "$src" ]] && [[ ! -f "$dst" ]]; then
                 mv "$src" "$dst"
                 info "Moved: commands/${cmd}.md → commands/sr/${cmd}.md"
-                ((migrated_commands++))
+                migrated_commands=$(( migrated_commands + 1 ))
             fi
         done
     fi
@@ -446,7 +446,7 @@ do_migrate_sr_prefix() {
             if [[ -d "$src" ]] && [[ ! -d "$dst" ]]; then
                 mv "$src" "$dst"
                 info "Renamed: agent-memory/${agent}/ → agent-memory/sr-${agent}/"
-                ((migrated_memory++))
+                migrated_memory=$(( migrated_memory + 1 ))
             fi
         done
     fi
@@ -501,7 +501,7 @@ except Exception:
     if _file_changed "$SCRIPT_DIR/commands/setup.md" "commands/setup.md"; then
         cp "$SCRIPT_DIR/commands/setup.md" "$REPO_ROOT/.claude/commands/setup.md"
         ok "Updated /setup command"
-        ((updated_count++))
+        updated_count=$(( updated_count + 1 ))
     fi
 
     # Update setup templates (selective — only copy changed/new files)
@@ -526,10 +526,10 @@ except Exception:
 " "$manifest_file" "$relpath" 2>/dev/null || echo "")"
             if [[ -z "$manifest_checksum" ]]; then
                 info "New: $relpath"
-                ((added_count++))
+                added_count=$(( added_count + 1 ))
             else
                 info "Changed: $relpath"
-                ((updated_count++))
+                updated_count=$(( updated_count + 1 ))
             fi
         fi
     done < <(find "$SCRIPT_DIR/templates" -type f -not -path '*/node_modules/*' -not -name 'package-lock.json' -print0 | sort -z)
@@ -556,10 +556,10 @@ except Exception:
 " "$manifest_file" "$relpath" 2>/dev/null || echo "")"
                 if [[ -z "$manifest_checksum" ]]; then
                     info "New: $relpath"
-                    ((added_count++))
+                    added_count=$(( added_count + 1 ))
                 else
                     info "Changed: $relpath"
-                    ((updated_count++))
+                    updated_count=$(( updated_count + 1 ))
                 fi
             fi
         done < <(find "$SCRIPT_DIR/prompts" -type f -print0 | sort -z)
@@ -587,10 +587,10 @@ except Exception:
 " "$manifest_file" "$relpath" 2>/dev/null || echo "")"
                 if [[ -z "$manifest_checksum" ]]; then
                     info "New: $relpath"
-                    ((added_count++))
+                    added_count=$(( added_count + 1 ))
                 else
                     info "Changed: $relpath"
-                    ((updated_count++))
+                    updated_count=$(( updated_count + 1 ))
                 fi
             fi
         done < <(find "$SCRIPT_DIR/.claude/skills" -type f -print0 | sort -z)