specrails-core 3.1.0 → 3.3.0

package/README.md

@@ -65,7 +65,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 +78,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:health-check`, `/sr:why`, and more |
 | **Rules** | `.claude/rules/*.md` | Per-layer coding conventions, loaded by file path |
 | **Memory** | `.claude/agent-memory/` | Persistent knowledge — agents learn across sessions |
 | **Config** | `.claude/settings.json`, `CLAUDE.md` | Permissions, architecture reference |
@@ -115,6 +116,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 +165,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 +174,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, git-friendly, and bidirectionally synced with specrails-hub in real time.
+
+**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 +224,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 +266,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.

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.
 
 ---
 
@@ -308,9 +308,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 +332,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 +379,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 +406,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>/`
 
@@ -422,24 +422,35 @@ Core commands (always install if missing):
 - `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**
 
@@ -682,19 +693,99 @@ 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.
+2. **GitHub Issues** — uses `gh` CLI to read/create issues with labels and VPC scores
+3. **JIRA** — uses JIRA CLI or REST API to read/create tickets in a JIRA project
+4. **None** — skip backlog commands (you can still use /implement with text descriptions)
+```
+
+Wait for the user's choice. Set `BACKLOG_PROVIDER` to `local`, `github`, `jira`, or `none`.
+
+#### If Local Tickets
+
+No external tools or credentials required. Initialize the storage file:
+
+1. Copy `templates/local-tickets-schema.json` to `$SPECRAILS_DIR/local-tickets.json`
+2. Set `last_updated` to the current ISO-8601 timestamp
+
+Store configuration in `$SPECRAILS_DIR/backlog-config.json`:
+```json
+{
+  "provider": "local",
+  "write_access": true,
+  "git_auto": true
+}
+```
 
-1. **GitHub Issues** — uses `gh` CLI to read/create issues with labels and VPC scores
-2. **JIRA** — uses JIRA CLI or REST API to read/create tickets in a JIRA project
-3. **None** — skip backlog commands (you can still use /implement with text descriptions)
+Local tickets are always read-write — there is no "read only" mode since the file is local.
+
+**Ticket schema** — each entry in the `tickets` map has these fields:
+
+```json
+{
+  "id": 1,
+  "title": "Feature title",
+  "description": "Markdown description",
+  "status": "todo",
+  "priority": "medium",
+  "labels": ["area:frontend", "effort:medium"],
+  "assignee": null,
+  "prerequisites": [],
+  "metadata": {
+    "vpc_scores": {},
+    "effort_level": "Medium",
+    "user_story": "",
+    "area": ""
+  },
+  "comments": [],
+  "created_at": "<ISO-8601>",
+  "updated_at": "<ISO-8601>",
+  "created_by": "user",
+  "source": "manual"
+}
 ```
 
-Wait for the user's choice. Set `BACKLOG_PROVIDER` to `github`, `jira`, or `none`.
+**Status values:** `todo`, `in_progress`, `done`, `cancelled`
+**Priority values:** `critical`, `high`, `medium`, `low`
+**Labels:** Freeform strings following the `area:*` and `effort:*` convention
+**Source values:** `manual`, `product-backlog`, `propose-spec`
+
+**Advisory file locking protocol** (CLI agents and hub server must both follow this):
+
+The `revision` counter in the JSON root enables optimistic concurrency — increment it on **every** write. The lock file prevents concurrent corruption:
+
+1. **Acquire lock:** Check for `$SPECRAILS_DIR/local-tickets.json.lock`
+   - If the file exists and its `timestamp` is less than 30 seconds old: wait 500ms and retry (max 5 attempts before aborting with an error)
+   - If the file exists and its `timestamp` is 30+ seconds old (stale): delete it and proceed
+   - If no lock file exists: proceed immediately
+2. **Create lock file:** Write `{"agent": "<agent-name-or-process>", "timestamp": "<ISO-8601>"}` to `$SPECRAILS_DIR/local-tickets.json.lock`
+3. **Minimal lock window:** Read the JSON → modify in memory → write back → release
+4. **Release lock:** Delete `$SPECRAILS_DIR/local-tickets.json.lock`
+5. **Always increment `revision`** by 1 and update `last_updated` on every successful write
+
+The hub server uses `proper-lockfile` (or equivalent) to honor the same protocol via the `.lock` file path.
 
 #### If GitHub Issues
 
@@ -1059,6 +1150,27 @@ When adapting `update-product-driven-backlog.md` and `product-backlog.md`, subst
 
 **When `IS_OSS=false`**: All Kai-related persona references are omitted. `{{MAX_SCORE}}` reduces by 5. Tables and inline scores contain only user-generated personas.
 
+#### Local Tickets (`BACKLOG_PROVIDER=local`)
+
+For the local provider, backlog placeholders resolve to **inline file-operation instructions** embedded in the generated command markdown — not shell commands. Agents execute these by reading/writing `$SPECRAILS_DIR/local-tickets.json` directly using their file tools.
+
+All write operations must follow the **advisory file locking protocol** defined in Phase 3.2. Always increment `revision` and update `last_updated` on every write.
+
+| 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_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"`. |
+| `{{BACKLOG_VIEW_CMD}}` | Read `$SPECRAILS_DIR/local-tickets.json`. Parse JSON and return the full ticket object at `tickets["{id}"]`, or an error if not found. |
+| `{{BACKLOG_CREATE_CMD}}` | Write to `$SPECRAILS_DIR/local-tickets.json` using the advisory locking protocol: acquire lock → read file → set `id = next_id`, increment `next_id`, set all ticket fields, set `created_at` and `updated_at` to now, bump `revision`, update `last_updated` → write → release lock. |
+| `{{BACKLOG_UPDATE_CMD}}` | Write to `$SPECRAILS_DIR/local-tickets.json` using the advisory locking protocol: acquire lock → read file → update fields in `tickets["{id}"]`, set `updated_at` to now, bump `revision`, update `last_updated` → write → release lock. |
+| `{{BACKLOG_DELETE_CMD}}` | Write to `$SPECRAILS_DIR/local-tickets.json` using the advisory locking protocol: acquire lock → read file → delete `tickets["{id}"]`, bump `revision`, update `last_updated` → write → release lock. |
+| `{{BACKLOG_COMMENT_CMD}}` | Write to `$SPECRAILS_DIR/local-tickets.json` using the advisory locking protocol: acquire lock → read file → append `{"author": "<agent-name>", "body": "<comment>", "created_at": "<ISO-8601>"}` to `tickets["{id}"].comments` (create the array if absent), set `updated_at` to now, bump `revision`, update `last_updated` → write → release lock. |
+| `{{BACKLOG_PARTIAL_COMMENT_CMD}}` | Same as `{{BACKLOG_COMMENT_CMD}}` but append `{"author": "<agent-name>", "body": "<comment>", "type": "progress", "created_at": "<ISO-8601>"}`. |
+| `{{BACKLOG_INIT_LABELS_CMD}}` | No label initialization required. Local tickets use freeform label strings. Standard label conventions: `area:frontend`, `area:backend`, `area:api`, `effort:low`, `effort:medium`, `effort:high`. |
+
 #### GitHub Issues (`BACKLOG_PROVIDER=github`)
 - Issue fetch: `gh issue list --label "product-driven-backlog" --state open --limit 100 --json number,title,labels,body`
 - Issue create: `gh issue create --title "..." --label "..." --body "..."`
@@ -1087,7 +1199,7 @@ When adapting `update-product-driven-backlog.md` and `product-backlog.md`, subst
   }
   ```
 
-The command templates use `{{BACKLOG_FETCH_CMD}}`, `{{BACKLOG_CREATE_CMD}}`, `{{BACKLOG_VIEW_CMD}}`, and `{{BACKLOG_PREFLIGHT}}` placeholders that get filled with the provider-specific commands.
+The command templates use `{{BACKLOG_FETCH_CMD}}`, `{{BACKLOG_CREATE_CMD}}`, `{{BACKLOG_VIEW_CMD}}`, `{{BACKLOG_PREFLIGHT}}`, and related placeholders that get filled with the provider-specific commands (for `local`) or instructions (for `github`, `jira`). The `{{BACKLOG_PROVIDER_NAME}}` placeholder is substituted with a human-readable provider label in all three cases.
 
 ### 4.4 Generate rules
 
@@ -1327,7 +1439,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:
 

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/getting-started.md

@@ -54,17 +54,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
 

package/docs/installation.md

@@ -87,6 +87,19 @@ After installation, open Claude Code in your project and run:
 /setup
 ```
 
+There are two modes:
+
+| Mode | Command | When to use |
+|------|---------|-------------|
+| **Full wizard** (default) | `/setup` | Deep stack analysis, researched personas, fully adapted agents — takes 5–10 min |
+| **Lite** | `/setup --lite` | Fastest path — 3 questions, sensible defaults, done in under a minute |
+
+---
+
+### Full Wizard (default)
+
+The full 5-phase wizard — takes 5–10 minutes and produces deeply adapted agents.
+
 ### Phase 1: Codebase Analysis
 
 The wizard scans your project to detect:
@@ -116,10 +129,10 @@ Interactive prompts for:
 
 | Setting | Options |
 |---------|---------|
-| **Backlog provider** | GitHub Issues, JIRA, or none |
+| **Backlog provider** | Local tickets (default), GitHub Issues, JIRA, or none |
 | **Access mode** | Read-write or read-only |
 | **Git workflow** | Trunk-based, Git Flow, or custom |
-| **Agents** | Which agents to enable |
+| **Agents** | Which agents to enable (up to 14) |
 | **Commands** | Which commands to install |
 
 ### Phase 4: File Generation
@@ -132,7 +145,7 @@ The wizard fills all templates with your project-specific context:
 - `{{BACKEND_TECH_LIST}}` → your backend technologies
 - Every `{{PLACEHOLDER}}` resolved with real data
 
-**Generated files:**
+**Generated files (full set):**
 
 ```
 .claude/
@@ -145,13 +158,19 @@ The wizard fills all templates with your project-specific context:
 │   ├── sr-test-writer.md        # Uses your test framework
 │   ├── sr-security-reviewer.md  # Scans your patterns
 │   ├── sr-doc-sync.md           # Updates your doc format
+│   ├── sr-backend-developer.md  # Backend-specialized
+│   ├── sr-frontend-developer.md # Frontend-specialized
+│   ├── sr-backend-reviewer.md   # Backend quality audit
+│   ├── sr-frontend-reviewer.md  # Frontend quality audit
+│   ├── sr-merge-resolver.md     # AI-powered conflict resolution
+│   ├── sr-performance-reviewer.md # Performance regression detection
 │   └── [personas].md            # Your user personas
 ├── commands/
 │   └── sr/
 │       ├── implement.md
 │       ├── product-backlog.md
 │       ├── batch-implement.md
-│       └── ...
+│       └── ...                  # 17 commands total
 ├── rules/
 │   ├── backend.md
 │   ├── frontend.md
@@ -171,6 +190,27 @@ After this phase, `/setup` is no longer available — your workflow is ready.
 
 ---
 
+### Lite Mode (`/setup --lite`)
+
+The quick path — three questions, sensible defaults, done in under a minute.
+
+1. What is this project? (one sentence)
+2. Who are the target users?
+3. Git access for agents — read-only or read-write?
+
+**What gets installed:**
+
+| Item | Detail |
+|------|--------|
+| Core agents | sr-architect, sr-developer, sr-reviewer, sr-product-manager |
+| All workflow commands | `/sr:implement`, `/sr:health-check`, `/sr:product-backlog`, and 14 more |
+| Backlog storage | Local tickets (`.claude/local-tickets.json`) — no GitHub or JIRA required |
+| CLAUDE.md | Project-level context for agents |
+
+You can run the full wizard later to deepen configuration: personas, stack analysis, layer-specific conventions.
+
+---
+
 ## Pipeline Monitor (optional)
 
 SpecRails includes a web dashboard for visualizing pipeline execution.