specrails-core 3.2.0 → 3.3.1

package/README.md

@@ -17,18 +17,6 @@ npx specrails-core@latest init --root-dir .
 
 > **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)
--->
-
 ---
 
 ## How it works
@@ -65,7 +53,8 @@ codex       # OpenAI Codex (beta)
 
 ```bash
 > /sr:implement "add user authentication"
-> /sr:implement #42, #43               # from GitHub Issues
+> /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
 ```
 
@@ -77,9 +66,9 @@ That's it. The pipeline takes over.
 
 | Category | Files | Purpose |
 |----------|-------|---------|
-| **Agents** | `.claude/agents/*.md` | 12 specialized AI agents |
+| **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` | `/sr:implement`, `/sr:product-backlog`, `/sr:update-product-driven-backlog` |
+| **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 |
@@ -115,6 +104,8 @@ SpecRails is not a chat interface. It's a **development pipeline** that coordina
 | **sr-test-writer** | Sonnet | Generates unit, integration, and e2e tests |
 | **sr-security-reviewer** | Sonnet | Secrets detection, OWASP checks, dependency vulnerabilities |
 | **sr-doc-sync** | Sonnet | Updates changelogs, READMEs, API docs |
+| **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 |
 
@@ -162,7 +153,7 @@ rm -rf .claude/.dry-run/add-dark-mode/
 /sr:product-backlog UI, Decks        # filter by area
 ```
 
-Reads your 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 next sprint.
 
 ### `/sr:update-product-driven-backlog` — Discover features
 
@@ -171,7 +162,28 @@ Reads your GitHub Issues, scores by VPC persona match, recommends top 3 for next
 /sr:update-product-driven-backlog Analytics   # focus on one area
 ```
 
-AI product discovery using your personas. Evaluates ideas, creates GitHub Issues for the best ones.
+AI product discovery using your personas. Evaluates ideas, creates tickets (local or GitHub Issues) for the best ones.
+
+---
+
+## Local ticket management
+
+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 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.
+
+```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
+```
+
+See [docs/local-tickets.md](./docs/local-tickets.md) for the full schema reference, concurrency model, and command integration details.
+
+Migrating from GitHub Issues or JIRA? See [docs/migration-guide.md](./docs/migration-guide.md).
 
 ---
 
@@ -200,8 +212,8 @@ Each persona scores features 0-5. Features are ranked by score/effort ratio. No
 | **git** | Yes | Repository detection |
 | **npm / Node 18+** | Recommended | Needed for npx install and OpenSpec CLI |
 | **OpenSpec CLI** | Recommended | Structured design artifacts for `/sr:implement` |
-| **GitHub CLI** (`gh`) | Optional | Backlog sync to GitHub Issues, PR creation |
-| **JIRA CLI** (`jira`) | Optional | Backlog sync to JIRA |
+| **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.
 
@@ -242,7 +254,10 @@ Run `npx specrails-core@latest init --root-dir <path>` again to re-scaffold, the
 Partially. Product discovery commands and individual agents work. `/sr:implement` and sr-architect rely on OpenSpec for structured design artifacts.
 
 **Does this work without GitHub CLI?**
-Yes. Use JIRA instead, or skip backlog commands. `/sr:implement "description"` works without `gh` — it just skips automated PR creation.
+Yes. Local tickets are the default and need no external tools. `/sr: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.
@@ -254,8 +269,6 @@ Yes. Everything runs locally through Claude Code. No external services beyond th
 
 ## 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/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/setup.md

@@ -10,11 +10,11 @@ Interactive wizard to configure the full agent workflow system for this reposito
 
 Check `$ARGUMENTS` in this order:
 
-1. If `--update` is present → execute **Update Mode** (below), then stop. Do NOT continue to Phase 1 or Quick Start.
-2. If `--advanced` is present → skip directly to **Phase 1** and execute the full 5-phase wizard.
-3. Otherwise (no flags) → execute **Quick Start Mode** (below), then stop. Do NOT execute Phase 1.
+1. If `--update` is present → execute **Update Mode** (below), then stop. Do NOT continue to Phase 1 or Lite Mode.
+2. If `--lite` is present → execute **Lite Mode** (below), then stop. Do NOT execute Phase 1.
+3. Otherwise (no flags) → skip directly to **Phase 1** and execute the full 5-phase wizard.
 
-**Default is Quick Start.** The full wizard only runs when `--advanced` is explicitly passed.
+**Default is the full wizard.** Lite Mode only runs when `--lite` is explicitly passed.
 
 ---
 
@@ -56,7 +56,7 @@ Read the following files to understand the current installation state:
    ```bash
    ls $SPECRAILS_DIR/setup-templates/commands/sr/
    ```
-   Command template files include `implement.md`, `batch-implement.md`, `health-check.md`, `compat-check.md`, `refactor-recommender.md`, `why.md`, `product-backlog.md`, `update-product-driven-backlog.md`.
+   Command template files include `implement.md`, `batch-implement.md`, `compat-check.md`, `refactor-recommender.md`, `why.md`, `product-backlog.md`, `update-product-driven-backlog.md`.
    If this directory does not exist, skip command template checking for this update.
 
 6. Read `$SPECRAILS_DIR/backlog-config.json` if it exists — contains stored provider configuration needed for command placeholder substitution.
@@ -130,7 +130,6 @@ Display the combined analysis to the user:
 - refactor-recommender.md
 
 ### Commands — Unchanged (keeping current)
-- health-check.md
 - compat-check.md
 - why.md
 ```
@@ -308,9 +307,9 @@ Update `.specrails-manifest.json` to reflect the new checksums for all regenerat
 
 ---
 
-## Quick Start Mode
+## Lite Mode
 
-When no flags are passed (the default), run this streamlined 3-question setup. Do NOT run Phase 1–5. When QS4 is complete, stop.
+When `--lite` is passed, run this streamlined 3-question setup. Do NOT run Phase 1–5. When QS4 is complete, stop.
 
 ### QS1: Ask the 3 questions
 
@@ -332,14 +331,14 @@ Store the answers as:
 
 Use these defaults for all configuration not asked in QS1:
 
-| Setting | Quick Start Default |
-|---------|-------------------|
+| Setting | Lite Mode Default |
+|---------|------------------|
 | Agents enabled | sr-architect, sr-developer, sr-reviewer, sr-product-manager |
 | Git mode | Derived from QS_GIT_ACCESS |
 | CLAUDE.md template | `templates/CLAUDE-quickstart.md` |
 | OpenSpec enabled | Yes if `openspec` CLI is detected in PATH, No otherwise |
 | Telemetry | Not configured (deferred to PRD-002) |
-| Backlog provider | None (user can configure later with `/setup --advanced`) |
+| Backlog provider | local (lightweight JSON-based, no external tools needed) |
 
 Detect whether this is an existing codebase or new project:
 - **Existing codebase**: `package.json`, `Gemfile`, `pyproject.toml`, `go.mod`, or `pom.xml` found in the repo root
@@ -379,7 +378,7 @@ For CLAUDE.md/AGENTS.md and agent files, the existing per-file prompts already h
 
 ### QS3: Generate files
 
-Generate files using the Quick Start defaults.
+Generate files using the Lite Mode defaults.
 
 **1. CLAUDE.md**
 
@@ -406,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}}` → "(Quick Start — run `/setup --advanced` for full architecture analysis)"
-- `{{TECH_EXPERTISE}}` → "(Quick Start — run `/setup --advanced` for codebase-specific expertise)"
+- `{{ARCHITECTURE_DIAGRAM}}` → "(Lite Mode — run `/setup` for full architecture analysis)"
+- `{{TECH_EXPERTISE}}` → "(Lite Mode — run `/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 --advanced`)"
+- All other placeholders → "(not configured — run `/setup`)"
 
 Create memory directories: `$SPECRAILS_DIR/agent-memory/sr-<name>/`
 
@@ -419,27 +418,37 @@ Core commands (always install if missing):
 - `implement.md`
 - `batch-implement.md`
 - `propose-spec.md`
-- `health-check.md`
 - `compat-check.md`
 - `why.md`
+- `product-backlog.md`
+- `update-product-driven-backlog.md`
 
-Do NOT copy `product-backlog.md` or `update-product-driven-backlog.md` (no backlog provider configured).
+**Initialize local ticket storage** (backlog provider defaults to `local`):
+1. Copy `templates/local-tickets-schema.json` to `$SPECRAILS_DIR/local-tickets.json` and set `last_updated` to the current ISO-8601 timestamp. Skip if the file already exists.
+2. Write `$SPECRAILS_DIR/backlog-config.json` (skip if already exists):
+   ```json
+   {
+     "provider": "local",
+     "write_access": true,
+     "git_auto": true
+   }
+   ```
 
 **If `cli_provider == "claude"`:**
 
-If `QS_IS_RERUN=false` (fresh install): copy all core commands from `$SPECRAILS_DIR/setup-templates/commands/sr/` to `.claude/commands/sr/`.
+If `QS_IS_RERUN=false` (fresh install): for each core command, read the template from `$SPECRAILS_DIR/setup-templates/commands/sr/<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/sr/<name>.md`.
 
 If `QS_IS_RERUN=true` (gap-fill mode): for each command in the list above, check if `.claude/commands/sr/<name>.md` already exists:
 - If it exists: skip it — show `✓ Already installed: /sr:<name>`
-- If it does NOT exist: copy from `$SPECRAILS_DIR/setup-templates/commands/sr/<name>.md` — show `✓ Added /sr:<name> (was missing)`
+- If it does NOT exist: read template, substitute placeholders as above, write to `.claude/commands/sr/<name>.md` — show `✓ Added /sr:<name> (was missing)`
 
 **If `cli_provider == "codex"`:**
 
-If `QS_IS_RERUN=false` (fresh install): for each core command, copy the corresponding skill from `$SPECRAILS_DIR/setup-templates/skills/sr-<name>/SKILL.md` 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 /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>`
-- If it does NOT exist: copy from `$SPECRAILS_DIR/setup-templates/skills/sr-<name>/SKILL.md` — show `✓ Added $sr-<name> (was missing)`
+- If it does NOT exist: read template, substitute placeholders as above, write to `.agents/skills/sr-<name>/SKILL.md` — show `✓ Added $sr-<name> (was missing)`
 
 **4. Cleanup**
 
@@ -452,7 +461,7 @@ Remove `commands/setup.md` from `.claude/commands/` if it was copied there by th
 After generating all files, display the setup complete message.
 
 Then, based on `QS_IS_EXISTING_CODEBASE`:
-- **Existing codebase** (`true`): recommend `/sr:health-check`
+- **Existing codebase** (`true`): recommend `/sr:refactor-recommender`
 - **New project** (`false`): recommend `/sr:product-backlog`
 
 If `QS_IS_RERUN=false`, display:
@@ -462,7 +471,7 @@ If `QS_IS_RERUN=false`, display:
 Try your first command:
   > /sr:product-backlog
 ```
-(Replace `/sr:product-backlog` with `/sr:health-check` for existing codebases.)
+(Replace `/sr:product-backlog` with `/sr:refactor-recommender` for existing codebases.)
 
 If `QS_IS_RERUN=true`, display the gap-fill summary and stop:
 ```
@@ -682,12 +691,26 @@ Which agents do you want to install?
 
 ### 3.2 Backlog provider
 
-Ask the user where they manage their product backlog:
+Ask the user how they want to manage their product backlog. Default is local — no external tools or accounts required:
 
 ```
 ## Backlog Provider
 
-Where do you track your product backlog?
+Use local ticket management or connect an external provider?
+
+1. **Local tickets** (default, recommended) — lightweight JSON-based ticket management built into the project.
+   No external tools or accounts required. Tickets stored in `.claude/local-tickets.json`, version-controlled and diffable.
+2. **External provider** — connect GitHub Issues, JIRA, or disable backlog commands
+```
+
+If the user selects **1** or presses Enter without typing anything: set `BACKLOG_PROVIDER=local` and proceed directly to **If Local Tickets** below. Do NOT ask about GitHub CLI, JIRA credentials, or any external provider configuration.
+
+If the user selects **2**: display the secondary menu:
+
+```
+## External Backlog Provider
+
+Which external provider?
 
 1. **Local tickets** (recommended) — lightweight JSON-based ticket management built into the project.
    No external tools required. Tickets stored in `.claude/local-tickets.json`, version-controlled and diffable.
@@ -925,7 +948,6 @@ If automatic, also check if `gh` is authenticated (for PR creation). If not, war
 | /sr:propose-spec | Interactively propose and refine a feature spec, then create a GitHub issue | GitHub CLI |
 | /sr:product-backlog | View prioritized backlog with VPC scores | sr-product-analyst + Backlog provider |
 | /sr:update-product-driven-backlog | Generate new feature ideas via product discovery | sr-product-manager + Backlog provider |
-| /sr:health-check | Run tests, linting, coverage, complexity, and dependency audit | None |
 | /sr:compat-check | Snapshot API surface and detect breaking changes | None |
 | /sr:refactor-recommender | Scan for refactoring opportunities ranked by impact/effort | None |
 | /sr:why | Search past architectural decisions from agent memory | None |
@@ -1061,7 +1083,6 @@ For each selected command, read the template and adapt.
 - `setup-templates/commands/sr/propose-spec.md` → `.claude/commands/sr/propose-spec.md`
 - `setup-templates/commands/sr/product-backlog.md` → `.claude/commands/sr/product-backlog.md` (if `BACKLOG_PROVIDER != none`)
 - `setup-templates/commands/sr/update-product-driven-backlog.md` → `.claude/commands/sr/update-product-driven-backlog.md` (if `BACKLOG_PROVIDER != none`)
-- `setup-templates/commands/sr/health-check.md` → `.claude/commands/sr/health-check.md`
 - `setup-templates/commands/sr/compat-check.md` → `.claude/commands/sr/compat-check.md`
 - `setup-templates/commands/sr/refactor-recommender.md` → `.claude/commands/sr/refactor-recommender.md`
 - `setup-templates/commands/sr/why.md` → `.claude/commands/sr/why.md`
@@ -1072,7 +1093,6 @@ For each selected command, read the template and adapt.
 - `setup-templates/commands/sr/propose-spec.md` → `.agents/skills/sr-propose-spec/SKILL.md` (wrap with YAML frontmatter if no skill template exists)
 - `setup-templates/commands/sr/product-backlog.md` → `.agents/skills/sr-product-backlog/SKILL.md` (if `BACKLOG_PROVIDER != none`; wrap with frontmatter)
 - `setup-templates/commands/sr/update-product-driven-backlog.md` → `.agents/skills/sr-update-product-driven-backlog/SKILL.md` (if `BACKLOG_PROVIDER != none`; wrap with frontmatter)
-- `setup-templates/skills/sr-health-check/SKILL.md` → `.agents/skills/sr-health-check/SKILL.md`
 - `setup-templates/skills/sr-compat-check/SKILL.md` → `.agents/skills/sr-compat-check/SKILL.md`
 - `setup-templates/skills/sr-refactor-recommender/SKILL.md` → `.agents/skills/sr-refactor-recommender/SKILL.md`
 - `setup-templates/skills/sr-why/SKILL.md` → `.agents/skills/sr-why/SKILL.md`
@@ -1356,7 +1376,6 @@ Display the complete installation summary:
 | /sr:propose-spec | .claude/commands/sr/propose-spec.md |
 | /sr:product-backlog | .claude/commands/sr/product-backlog.md |
 | /sr:update-product-driven-backlog | .claude/commands/sr/update-product-driven-backlog.md |
-| /sr:health-check | .claude/commands/sr/health-check.md |
 | /sr:compat-check | .claude/commands/sr/compat-check.md |
 | /sr:refactor-recommender | .claude/commands/sr/refactor-recommender.md |
 | /sr:why | .claude/commands/sr/why.md |
@@ -1368,7 +1387,6 @@ Display the complete installation summary:
 | $sr-propose-spec | .agents/skills/sr-propose-spec/SKILL.md |
 | $sr-product-backlog | .agents/skills/sr-product-backlog/SKILL.md |
 | $sr-update-product-driven-backlog | .agents/skills/sr-update-product-driven-backlog/SKILL.md |
-| $sr-health-check | .agents/skills/sr-health-check/SKILL.md |
 | $sr-compat-check | .agents/skills/sr-compat-check/SKILL.md |
 | $sr-refactor-recommender | .agents/skills/sr-refactor-recommender/SKILL.md |
 | $sr-why | .agents/skills/sr-why/SKILL.md |
@@ -1414,7 +1432,7 @@ Note: Only commands/skills selected during setup are shown. Backlog commands are
 - `$sr-update-product-driven-backlog` — discover new features using VPC
 ```
 
-## First Task Prompt (Advanced Mode)
+## First Task Prompt (Full Wizard)
 
 After displaying the setup complete summary above, detect the project type and output:
 
@@ -1435,9 +1453,9 @@ Try your first spec:
 
 Try your first spec:
 [If cli_provider == "claude":]
-  > /sr:health-check
+  > /sr:refactor-recommender
 [If cli_provider == "codex":]
-  > $sr-health-check
+  > $sr-refactor-recommender
 ```
 
 Then stop.

package/docs/agents.md

@@ -1,6 +1,6 @@
 # Agents
 
-SpecRails ships with **12 specialized agents**. Each has a clear role, a dedicated AI model, and knows exactly when to stay in its lane.
+SpecRails ships with **14 specialized agents**. Each has a clear role, a dedicated AI model, and knows exactly when to stay in its lane.
 
 ## Why specialized agents?
 
@@ -245,6 +245,48 @@ The Reviewer is the **last agent before ship**. It:
 
 ---
 
+### Merge Resolver
+
+| | |
+|-|-|
+| **Color** | Yellow |
+| **Model** | Sonnet |
+| **Trigger** | `/sr:merge-resolve`, `/sr:implement` (Phase 4a, after worktree merge) |
+| **Role** | AI-powered merge conflict resolution |
+
+When a multi-feature pipeline merges worktrees and produces conflict markers, the Merge Resolver analyzes each conflict block using the OpenSpec context bundles from both features. It applies resolutions where confidence is high enough and leaves clean markers for the conflicts it cannot safely resolve.
+
+**Configuration (in `.claude/agents/sr-merge-resolver.md`):**
+- `tone`: `terse` (default) or `verbose`
+- `risk_tolerance`: `conservative` (default) or `aggressive`
+- `confidence_threshold`: 0–100, default `70`
+
+**What it produces:**
+- Resolved conflict blocks written in place
+- Structured resolution report (file, block, confidence, resolution or left-as-marker)
+
+---
+
+### Performance Reviewer
+
+| | |
+|-|-|
+| **Color** | Yellow |
+| **Model** | Sonnet |
+| **Trigger** | `/sr:implement` (Phase 4, after Security Reviewer) |
+| **Role** | Performance regression detection |
+
+The Performance Reviewer benchmarks modified code paths after implementation, compares metrics against configured thresholds, and outputs a structured report. It never fixes code — findings above the threshold trigger the Developer to address them before the pipeline continues.
+
+**Configuration:** Create `.specrails/perf-thresholds.yml` to set custom thresholds per metric. The agent falls back to built-in defaults if the file is missing.
+
+**What it produces:**
+- Execution time, memory usage, and throughput metrics for modified paths
+- Pass/fail report against configured thresholds
+- `PERF_STATUS` result consumed by the pipeline orchestrator
+
+---
+
 ## Agent memory
 
 Every agent stores observations in `.claude/agent-memory/<agent>/MEMORY.md`. This memory persists across sessions, so agents get smarter over time:

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-core@latest setup
+npx specrails-core@latest init --root-dir .
 ```
 
 This will:
@@ -35,10 +35,10 @@ This will:
 Clone the repository for full control and the ability to customize agents.
 
 ```bash
-git clone https://github.com/specrails-ai/specrails-core
+git clone https://github.com/fjpulidop/specrails-core
 cd specrails-core
 npm install
-npm run setup
+./install.sh --root-dir <your-project>
 ```
 
 ### Updating
@@ -90,7 +90,7 @@ docker compose run specrails setup
 ### Building locally
 
 ```bash
-git clone https://github.com/specrails-ai/specrails-core
+git clone https://github.com/fjpulidop/specrails-core
 cd specrails-core
 docker build -t specrails:local .
 docker run -it \

package/docs/getting-started.md

@@ -10,16 +10,18 @@ Think of it as hiring a full engineering team that lives inside your CLI.
 
 ## Prerequisites
 
-You only need two things:
+You need:
 
+- **Node.js 18+** — required for the installer (`node --version` to check)
 - **Git** — your project must be a git repository
 - **[Claude Code](https://claude.ai/claude-code)** — Anthropic's CLI tool
 
 Optional (recommended):
 
-- **npm** — for installing the Pipeline Monitor dashboard
 - **[GitHub CLI](https://cli.github.com/)** (`gh`) — for automatic PR creation and issue tracking
 
+> **Using OpenAI Codex instead of Claude Code?** See [Installation](user-docs/installation.md) for Codex-specific setup.
+
 ## Install
 
 Pick your preferred method:
@@ -33,8 +35,8 @@ npx specrails-core@latest init --root-dir <your-project>
 **git clone**
 
 ```bash
-git clone https://github.com/fjpulidop/specrails.git
-./specrails/install.sh --root-dir <your-project>
+git clone https://github.com/fjpulidop/specrails-core.git
+./specrails-core/install.sh --root-dir <your-project>
 ```
 
 The installer will:
@@ -54,17 +56,27 @@ Open Claude Code in your project and run:
 /setup
 ```
 
-The wizard walks you through 5 phases:
+By default, `/setup` runs the **full 5-phase wizard** — deep stack analysis, researched user personas, and fully adapted agents.
 
 | Phase | What happens |
 |-------|-------------|
 | **1. Analyze** | Detects your tech stack, architecture layers, CI commands, and conventions |
-| **2. Personas** | Researches your competitive landscape and generates user personas (VPC profiles) |
-| **3. Configure** | Asks about your backlog provider, git workflow, and which agents/commands to enable |
+| **2. Personas** | Researches your competitive landscape and generates full VPC user personas |
+| **3. Configure** | Asks about your backlog provider, git workflow, and which agents to enable |
 | **4. Generate** | Fills all templates with your project-specific context |
 | **5. Cleanup** | Removes the wizard and templates, leaving only your tailored workflow files |
 
-After setup, your `.claude/` directory contains fully adapted agents, commands, and rules — ready to use.
+**In a hurry?** Run `/setup --lite` for the quick version: three questions, sensible defaults, done in under a minute.
+
+| Question | What it configures |
+|----------|-------------------|
+| What is this project? | Agent context and CLAUDE.md |
+| Who are the target users? | Persona stubs for product discovery |
+| Git access — read-only or read-write? | Whether agents can commit |
+
+Lite mode installs the four core agents (architect, developer, reviewer, product manager), all workflow commands, and local ticket storage. You can run the full wizard later to deepen the configuration.
+
+After either mode, your `.claude/` directory contains adapted agents, commands, and rules — ready to use.
 
 ## Your first feature
 
@@ -104,4 +116,6 @@ Now that you're running, learn how the system thinks:
 
 ---
 
+**Looking for step-by-step guides?** See [Quick Start](user-docs/quick-start.md) for a walkthrough of your first feature, or [Installation](user-docs/installation.md) for detailed install options including Codex support.
+
 [← Back to Docs](README.md) · [Core Concepts →](concepts.md)