specrails-core 3.2.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,12 +693,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.
@@ -1414,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.

package/docs/local-tickets.md

@@ -0,0 +1,218 @@
+# Local Ticket Management
+
+specrails-core ships with a built-in, file-based ticket management system. It is the **default backlog provider** — no GitHub account, CLI tool, or external service required.
+
+---
+
+## Overview
+
+Tickets live in `.claude/local-tickets.json` at your project root. Because it's a plain JSON file, tickets are:
+
+- **Version-controlled** — tracked by git, diffable in PRs
+- **Offline-first** — no network calls, no rate limits
+- **Tool-agnostic** — readable by any script or editor
+
+The file is shared between specrails-core (which reads and writes tickets during command execution) and specrails-hub (which provides a visual ticket panel with real-time sync).
+
+---
+
+## Storage format
+
+`.claude/local-tickets.json`:
+
+```json
+{
+  "schema_version": "1.0",
+  "revision": 7,
+  "last_updated": "2026-03-23T10:00:00.000Z",
+  "next_id": 8,
+  "tickets": {
+    "1": {
+      "id": 1,
+      "title": "Add dark mode",
+      "description": "Support system-level dark mode preference via CSS variables.",
+      "status": "todo",
+      "priority": "medium",
+      "labels": ["area:frontend", "effort:medium"],
+      "assignee": null,
+      "prerequisites": [],
+      "metadata": {
+        "vpc_scores": { "persona-a": 4, "persona-b": 3 },
+        "effort_level": "Medium",
+        "user_story": "As a user working at night, I want dark mode...",
+        "area": "frontend"
+      },
+      "comments": [],
+      "created_at": "2026-03-20T09:00:00.000Z",
+      "updated_at": "2026-03-20T09:00:00.000Z",
+      "created_by": "sr-product-manager",
+      "source": "product-backlog"
+    }
+  }
+}
+```
+
+### Field reference
+
+**Root fields**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `schema_version` | string | Always `"1.0"` for the current format |
+| `revision` | number | Incremented on every write — used for optimistic concurrency control |
+| `last_updated` | ISO-8601 | Timestamp of the most recent mutation |
+| `next_id` | number | Auto-increment counter for new ticket IDs |
+| `tickets` | object | Map of ticket ID (as string) → ticket object |
+
+**Ticket fields**
+
+| Field | Type | Values | Description |
+|-------|------|--------|-------------|
+| `id` | number | Auto-assigned | Numeric ID, referenced as `#<id>` |
+| `title` | string | — | Short title |
+| `description` | string | Markdown | Full description |
+| `status` | string | `todo`, `in_progress`, `done`, `cancelled` | Current state |
+| `priority` | string | `critical`, `high`, `medium`, `low` | Priority level |
+| `labels` | string[] | Freeform | Tag strings; convention: `area:*`, `effort:*` |
+| `assignee` | string\|null | — | Agent name or user, if assigned |
+| `prerequisites` | number[] | — | IDs of tickets that must be done first |
+| `metadata` | object | — | VPC scores, effort level, user story, area (set by agents) |
+| `comments` | array | — | Progress notes appended during implementation |
+| `created_at` | ISO-8601 | — | Creation timestamp |
+| `updated_at` | ISO-8601 | — | Last mutation timestamp |
+| `created_by` | string | — | Agent name or `"user"` |
+| `source` | string | `manual`, `product-backlog`, `propose-spec` | How the ticket was created |
+
+---
+
+## Setup
+
+Local tickets become the default during `/setup`. The wizard prompts:
+
+```
+## Backlog Provider
+
+Use local ticket management or connect an external provider?
+
+1. Local tickets (default, recommended) — lightweight JSON-based ticket management.
+   No external tools or accounts required.
+2. External provider — connect GitHub Issues, JIRA, or disable backlog commands
+```
+
+Pressing **Enter** or selecting **1** initializes `.claude/local-tickets.json` with an empty ticket store and writes `.claude/backlog-config.json`:
+
+```json
+{
+  "provider": "local",
+  "write_access": true,
+  "git_auto": true
+}
+```
+
+To switch providers later, re-run the setup wizard:
+
+```bash
+npx specrails-core@latest init --root-dir .
+> /setup
+```
+
+---
+
+## Concurrency model
+
+Both CLI agents and specrails-hub can modify `local-tickets.json` simultaneously. The system uses two complementary mechanisms:
+
+### Advisory file lock
+
+Before every write, the agent creates `.claude/local-tickets.json.lock`:
+
+```json
+{
+  "agent": "sr-product-manager",
+  "timestamp": "2026-03-23T10:00:00.000Z"
+}
+```
+
+If the lock file already exists:
+- **Fresh lock** (< 30 seconds old): wait 500 ms and retry, up to 5 attempts
+- **Stale lock** (≥ 30 seconds old): treat as orphaned, delete it, proceed
+
+The lock is deleted immediately after the write completes. The window is minimal: read → modify in memory → write → release.
+
+### Revision counter
+
+Every write increments `revision`. Readers that want to detect external changes compare the `revision` they last saw against the current value. This is how specrails-hub avoids echoing its own writes back through the file watcher.
+
+---
+
+## Command integration
+
+### `/sr:implement`
+
+Pass local ticket IDs the same way you would GitHub issue numbers:
+
+```bash
+/sr:implement #1, #4, #7
+```
+
+The command reads each ticket from `local-tickets.json`, extracts metadata (area, effort, description), and tracks the ticket through the pipeline — updating status to `in_progress` on start and `done` on successful completion.
+
+### `/sr:product-backlog`
+
+```bash
+/sr:product-backlog              # all areas
+/sr:product-backlog UI, Backend  # filter by area
+```
+
+Reads all `todo` and `in_progress` tickets, scores them by VPC match, respects the `prerequisites` dependency graph, and recommends the top 3 for your next sprint.
+
+### `/sr:update-product-driven-backlog`
+
+```bash
+/sr:update-product-driven-backlog            # explore all areas
+/sr:update-product-driven-backlog Analytics  # focus on one area
+```
+
+Runs product discovery using your VPC personas. Creates new local tickets for discovered feature ideas, tagged with `source: "product-backlog"` and `labels: ["product-driven-backlog", "area:<area>"]`. Existing tickets are checked for duplicates before creating new ones.
+
+### `/sr:propose-spec`
+
+When a proposal is finalized, a local ticket is created automatically:
+
+```
+Created local ticket #12: Add analytics export
+```
+
+The ticket captures the full proposal as its description and is tagged `source: "propose-spec"` with the label `spec-proposal`.
+
+---
+
+## integration-contract.json
+
+The `ticketProvider` section tells specrails-hub where to find and how to use the ticket store:
+
+```json
+{
+  "ticketProvider": {
+    "type": "local",
+    "storageFile": "local-tickets.json",
+    "lockFile": "local-tickets.json.lock",
+    "capabilities": ["crud", "labels", "status", "priorities", "dependencies", "comments"]
+  }
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `type` | `"local"` — file-based storage (the only supported type currently) |
+| `storageFile` | Filename relative to the project's specrails dir (`.claude/` or `.codex/`) |
+| `lockFile` | Advisory lock filename, same directory |
+| `capabilities` | Features the hub enables based on what the provider supports |
+
+specrails-hub reads this file when it loads a project. If the file is missing or the `ticketProvider` key is absent, hub falls back to safe defaults (`type: "local"`, `storageFile: "local-tickets.json"`).
+
+---
+
+## Migrating from GitHub Issues or JIRA
+
+See the [Migration Guide](./migration-guide.md).

package/docs/migration-guide.md

@@ -0,0 +1,141 @@
+# Migration Guide: Switching to Local Tickets
+
+This guide is for teams currently using GitHub Issues or JIRA as their specrails backlog provider who want to switch to the built-in local ticket system.
+
+Switching is optional. GitHub Issues and JIRA remain fully supported. Local tickets are the recommended default for new projects.
+
+---
+
+## Should you switch?
+
+**Switch to local tickets if:**
+- Your team prefers a simple, zero-dependency setup
+- You want tickets version-controlled alongside your code
+- You use specrails-hub and want the visual ticket panel
+- You don't need GitHub/JIRA for other workflows (project boards, external stakeholders)
+
+**Stay on GitHub Issues / JIRA if:**
+- Other teams or stakeholders manage tickets in those tools
+- You rely on GitHub Projects, Milestones, or JIRA sprints
+- You want PR auto-close on issue merge (requires GitHub Issues)
+
+---
+
+## Step 1: Switch the provider
+
+Edit `.claude/backlog-config.json` in your project root:
+
+```json
+{
+  "provider": "local",
+  "write_access": true,
+  "git_auto": true
+}
+```
+
+Then initialize the ticket store if it doesn't exist yet:
+
+```bash
+# Inside Claude Code or Codex
+/sr:implement --setup-local-tickets
+```
+
+Or create the file manually:
+
+```bash
+cat > .claude/local-tickets.json << 'EOF'
+{
+  "schema_version": "1.0",
+  "revision": 0,
+  "last_updated": null,
+  "next_id": 1,
+  "tickets": {}
+}
+EOF
+```
+
+---
+
+## Step 2: Import existing issues (one-time migration)
+
+### From GitHub Issues
+
+Use the `sr:migrate-from-github` command (requires `gh` CLI):
+
+```bash
+# Inside Claude Code
+/sr:migrate-from-github
+```
+
+This command:
+1. Fetches all open issues labeled `product-driven-backlog` (the label specrails uses)
+2. Maps GitHub issue fields to local ticket schema:
+   - `number` → `id` (uses next available local ID)
+   - `title` → `title`
+   - `body` → `description`
+   - `labels` → `labels`
+   - `state: open` → `status: todo`
+3. Writes each ticket to `local-tickets.json`
+4. Prints a summary: `Imported 14 tickets from GitHub Issues`
+
+To import all open issues regardless of label:
+
+```bash
+/sr:migrate-from-github --all
+```
+
+To do a dry run (preview without writing):
+
+```bash
+/sr:migrate-from-github --dry-run
+```
+
+**After import:** Your GitHub Issues are unchanged. The migration is additive — it only creates local tickets. You can continue using GitHub Issues in parallel until you're ready to stop.
+
+### From JIRA
+
+Use the `sr:migrate-from-jira` command (requires `jira` CLI or REST API credentials in `.claude/backlog-config.json`):
+
+```bash
+# Inside Claude Code
+/sr:migrate-from-jira
+```
+
+This command:
+1. Fetches all open issues from the configured JIRA project
+2. Maps JIRA fields to local ticket schema:
+   - Issue key (`PROJECT-123`) → stored in `metadata.jira_key`
+   - `summary` → `title`
+   - `description` → `description`
+   - `priority` → `priority` (Critical/High/Medium/Low mapped directly)
+   - `status: To Do / Backlog` → `status: todo`
+   - `status: In Progress` → `status: in_progress`
+   - `labels` → `labels`
+3. Writes each ticket to `local-tickets.json`
+
+The original JIRA key is preserved in `metadata.jira_key` so you can cross-reference during the transition.
+
+---
+
+## Step 3: Regenerate commands (optional but recommended)
+
+Command templates are generated at `/setup` time with provider-specific instructions baked in. After switching providers, regenerate them so commands use the local file operations instead of GitHub/JIRA CLI calls:
+
+```bash
+npx specrails-core@latest init --root-dir .
+> /setup --update
+```
+
+The `--update` flag regenerates only the backlog commands (`product-backlog`, `update-product-driven-backlog`, `implement`) without re-running the full stack analysis.
+
+---
+
+## Rollback
+
+To revert to GitHub Issues:
+
+1. Edit `.claude/backlog-config.json` and set `"provider": "github"`
+2. Re-run `/setup --update` to regenerate commands
+3. Your `local-tickets.json` is preserved — switch back any time
+
+Local tickets and external provider data are independent. Switching providers does not delete tickets from either system.

package/docs/user-docs/faq.md

@@ -14,17 +14,20 @@ It creates a `.claude/` directory with agent templates, commands, and configurat
 
 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?**
+**Do I need 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:
+No. SpecRails ships with a built-in local ticket system — no GitHub account required. Local tickets are the default. Commands like `/sr:implement` accept ticket IDs or plain text:
 
 ```
+/sr:implement #1, #4
 /sr:implement "add rate limiting to the API"
 ```
 
+You can switch to GitHub Issues or JIRA during `/setup` (Phase 3) if you prefer.
+
 **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.
+The full wizard takes about 5 minutes — most of the time is Phase 2 (persona research via web search). For a faster start, use `/setup --lite`: three questions, under a minute, no web research.
 
 ---
 

package/docs/user-docs/installation.md

@@ -95,7 +95,7 @@ codex     # Codex
 /setup
 ```
 
-The wizard runs 5 phases:
+By default, `/setup` runs the full 5-phase wizard:
 
 | Phase | What happens |
 |-------|-------------|
@@ -105,6 +105,8 @@ The wizard runs 5 phases:
 | **4. Generate** | Fills all templates with your project-specific context |
 | **5. Cleanup** | Removes setup files, leaving only your tailored workflow |
 
+**In a hurry?** Run `/setup --lite` instead — three questions, sensible defaults, done in under a minute.
+
 After setup, `.claude/` contains fully configured agents and commands ready to use. The `/setup` command removes itself — it only runs once.
 
 ## Verify

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

@@ -46,7 +46,7 @@ Then run:
 /setup
 ```
 
-The wizard runs automatically and takes about 5 minutes. It analyzes your codebase and configures SpecRails for your specific project:
+The wizard runs the full 5-phase setup (about 5 minutes). It analyzes your codebase and configures SpecRails for your specific project:
 
 ```
 Phase 1/5  Analyzing codebase...
@@ -59,14 +59,14 @@ Phase 2/5  Generating user personas...
            → Created 3 VPC profiles
 
 Phase 3/5  Configuration...
-           → Backlog provider: GitHub Issues
+           → Backlog provider: local
            → 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
+           → 11 more agents
 
 Phase 5/5  Cleanup complete. /setup removed.
 
@@ -75,6 +75,8 @@ Phase 5/5  Cleanup complete. /setup removed.
 
 After setup, the `/setup` command is gone — it's a one-time wizard.
 
+**In a hurry?** Use `/setup --lite` for a 3-question quick setup (under a minute). You can always run the full wizard later.
+
 ## Step 3: Implement your first feature
 
 Pick something small. Either reference a GitHub Issue or describe it in plain text:
@@ -129,7 +131,7 @@ One command. The PR is ready for human review.
 /sr:product-backlog
 ```
 
-See your GitHub Issues ranked by persona fit and effort. The top 3 are safe to implement next.
+See your tickets ranked by persona fit and effort. The top 3 are safe to implement next. Uses local tickets by default.
 
 **Generate new feature ideas:**
 
@@ -137,7 +139,7 @@ See your GitHub Issues ranked by persona fit and effort. The top 3 are safe to i
 /sr:update-product-driven-backlog
 ```
 
-The Product Manager researches your competitive landscape and creates well-formed GitHub Issues for new features.
+The Product Manager researches your competitive landscape and creates new tickets (local by default, or GitHub Issues if configured).
 
 **Run multiple features in parallel:**
 

package/docs/workflows.md

@@ -126,7 +126,7 @@ View your prioritized product backlog, ranked by VPC fit and effort.
 
 ### What it shows
 
-The Product Analyst reads your GitHub Issues (labeled `product-driven-backlog`) and produces:
+The Product Analyst reads your backlog (local tickets in `.claude/local-tickets.json` by default, or GitHub Issues labeled `product-driven-backlog` if configured) and produces:
 
 - **Backlog table** per area — sorted by Total Persona Score
 - **Top 3 recommendations** — ranked by VPC score / effort ratio, filtered to Wave 1 of the safe implementation order
@@ -166,7 +166,7 @@ Generate new feature ideas through product discovery. The Product Manager (Opus)
 2. Researches competitors via web search
 3. Generates 2–4 feature ideas per area
 4. Scores each against every persona (0–5)
-5. Creates GitHub Issues (if write access) or displays for manual creation
+5. Creates tickets in your active backlog provider (local tickets by default; GitHub Issues or JIRA if configured) or displays for manual creation
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specrails-core",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "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"