specrails-core 3.5.0 → 3.5.2

package/README.md

@@ -196,7 +196,7 @@ AI product discovery using your personas. Evaluates ideas, creates tickets (loca
 
 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.
+Tickets live in `.specrails/local-tickets.json` alongside your code. They're plain JSON and git-friendly.
 
 **Local tickets are the default.** The `/specrails:setup` wizard defaults to local tickets and skips GitHub/JIRA credential setup unless you opt in.
 

package/commands/setup.md

@@ -59,7 +59,7 @@ Read the following files to understand the current installation state:
    Command template files include `implement.md`, `batch-implement.md`, `compat-check.md`, `refactor-recommender.md`, `why.md`, `get-backlog-specs.md`, `auto-propose-backlog-specs.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.
+6. Read `.specrails/backlog-config.json` if it exists — contains stored provider configuration needed for command placeholder substitution.
 
 ### Phase U2: Quick Codebase Re-Analysis
 
@@ -178,7 +178,7 @@ For each command in the "changed commands" list from Phase U3:
 1. Read the NEW template:
    - If `cli_provider == "claude"`: from `$SPECRAILS_DIR/setup-templates/commands/specrails/<name>.md`
    - If `cli_provider == "codex"`: from `$SPECRAILS_DIR/setup-templates/skills/sr-<name>/SKILL.md`
-2. Read stored backlog configuration from `$SPECRAILS_DIR/backlog-config.json` (if it exists) to resolve provider-specific placeholders:
+2. Read stored backlog configuration from `.specrails/backlog-config.json` (if it exists) to resolve provider-specific placeholders:
    - `BACKLOG_PROVIDER` → `provider` field (`github`, `jira`, or `none`)
    - `BACKLOG_WRITE` → `write_access` field
    - `JIRA_BASE_URL` → `jira_base_url` field
@@ -424,8 +424,8 @@ Core commands (always install if missing):
 - `auto-propose-backlog-specs.md`
 
 **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):
+1. Copy `templates/local-tickets-schema.json` to `.specrails/local-tickets.json` and set `last_updated` to the current ISO-8601 timestamp. Skip if the file already exists.
+2. Write `.specrails/backlog-config.json` (skip if already exists):
    ```json
    {
      "provider": "local",
@@ -699,7 +699,7 @@ Ask the user how they want to manage their product backlog. Default is local —
 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.
+   No external tools or accounts required. Tickets stored in `.specrails/local-tickets.json`, version-controlled and diffable.
 2. **External provider** — connect GitHub Issues, JIRA, or disable backlog commands
 ```
 
@@ -713,7 +713,7 @@ If the user selects **2**: display the secondary menu:
 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.
+   No external tools required. Tickets stored in `.specrails/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)
@@ -725,10 +725,10 @@ Wait for the user's choice. Set `BACKLOG_PROVIDER` to `local`, `github`, `jira`,
 
 No external tools or credentials required. Initialize the storage file:
 
-1. Copy `templates/local-tickets-schema.json` to `$SPECRAILS_DIR/local-tickets.json`
+1. Copy `templates/local-tickets-schema.json` to `.specrails/local-tickets.json`
 2. Set `last_updated` to the current ISO-8601 timestamp
 
-Store configuration in `$SPECRAILS_DIR/backlog-config.json`:
+Store configuration in `.specrails/backlog-config.json`:
 ```json
 {
   "provider": "local",
@@ -774,13 +774,13 @@ Local tickets are always read-write — there is no "read only" mode since the f
 
 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`
+1. **Acquire lock:** Check for `.specrails/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`
+2. **Create lock file:** Write `{"agent": "<agent-name-or-process>", "timestamp": "<ISO-8601>"}` to `.specrails/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`
+4. **Release lock:** Delete `.specrails/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.
@@ -895,7 +895,7 @@ Ask:
 
 Set `EPIC_LINK_FIELD` to `parent` or `customfield_10014`. Default: `parent`.
 
-Store the full configuration in `.claude/backlog-config.json`:
+Store the full configuration in `.specrails/backlog-config.json`:
 ```json
 {
   "provider": "jira",
@@ -1147,22 +1147,22 @@ When adapting `auto-propose-backlog-specs.md` and `get-backlog-specs.md`, substi
 
 #### 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.
+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/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 /specrails:setup to initialize"` |
-| `{{BACKLOG_FETCH_CMD}}` | Read `$SPECRAILS_DIR/local-tickets.json`. Parse the `tickets` map and return all entries where `status` is `"todo"` or `"in_progress"`. |
-| `{{BACKLOG_FETCH_ALL_CMD}}` | Read `$SPECRAILS_DIR/local-tickets.json`. Parse the `tickets` map and return all entries regardless of status. |
-| `{{BACKLOG_FETCH_CLOSED_CMD}}` | Read `$SPECRAILS_DIR/local-tickets.json`. Parse the `tickets` map and return all entries where `status` is `"done"` or `"cancelled"`. |
-| `{{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_PREFLIGHT}}` | `[[ -f ".specrails/local-tickets.json" ]] && echo "Local tickets storage: OK" \|\| echo "WARNING: .specrails/local-tickets.json not found — run /specrails:setup to initialize"` |
+| `{{BACKLOG_FETCH_CMD}}` | Read `.specrails/local-tickets.json`. Parse the `tickets` map and return all entries where `status` is `"todo"` or `"in_progress"`. |
+| `{{BACKLOG_FETCH_ALL_CMD}}` | Read `.specrails/local-tickets.json`. Parse the `tickets` map and return all entries regardless of status. |
+| `{{BACKLOG_FETCH_CLOSED_CMD}}` | Read `.specrails/local-tickets.json`. Parse the `tickets` map and return all entries where `status` is `"done"` or `"cancelled"`. |
+| `{{BACKLOG_VIEW_CMD}}` | Read `.specrails/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/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/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/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/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`. |
 
@@ -1183,7 +1183,7 @@ All write operations must follow the **advisory file locking protocol** defined
 - Issue view: `jira issue view {key}` or REST API
 - VPC scores stored in the issue description body (same markdown format, parsed from description)
 - Pre-flight check: `jira me` or test API connectivity
-- Store JIRA config in `$SPECRAILS_DIR/backlog-config.json`:
+- Store JIRA config in `.specrails/backlog-config.json`:
   ```json
   {
     "provider": "jira",

package/docs/installation.md

@@ -231,7 +231,7 @@ The quick path — three questions, sensible defaults, done in under a minute.
 |------|--------|
 | Core agents | sr-architect, sr-developer, sr-reviewer, sr-product-manager |
 | All workflow commands | `/specrails:implement`, `/specrails:get-backlog-specs`, and 14 more |
-| Backlog storage | Local tickets (`.claude/local-tickets.json`) — no GitHub or JIRA required |
+| Backlog storage | Local tickets (`.specrails/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.

package/docs/local-tickets.md

@@ -6,7 +6,7 @@ specrails-core ships with a built-in, file-based ticket management system. It is
 
 ## Overview
 
-Tickets live in `.claude/local-tickets.json` at your project root. Because it's a plain JSON file, tickets are:
+Tickets live in `.specrails/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
@@ -18,7 +18,7 @@ The file is read and written by specrails-core during command execution.
 
 ## Storage format
 
-`.claude/local-tickets.json`:
+`.specrails/local-tickets.json`:
 
 ```json
 {
@@ -99,7 +99,7 @@ Use local ticket management or connect an external provider?
 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`:
+Pressing **Enter** or selecting **1** initializes `.specrails/local-tickets.json` with an empty ticket store and writes `.specrails/backlog-config.json`:
 
 ```json
 {
@@ -123,7 +123,7 @@ Multiple agents can modify `local-tickets.json` simultaneously. The system uses
 
 ### Advisory file lock
 
-Before every write, the agent creates `.claude/local-tickets.json.lock`:
+Before every write, the agent creates `.specrails/local-tickets.json.lock`:
 
 ```json
 {

package/docs/migration-guide.md

@@ -22,7 +22,7 @@ Switching is optional. GitHub Issues and JIRA remain fully supported. Local tick
 
 ## Step 1: Switch the provider
 
-Edit `.claude/backlog-config.json` in your project root:
+Edit `.specrails/backlog-config.json` in your project root:
 
 ```json
 {
@@ -42,7 +42,7 @@ Then initialize the ticket store if it doesn't exist yet:
 Or create the file manually:
 
 ```bash
-cat > .claude/local-tickets.json << 'EOF'
+cat > .specrails/local-tickets.json << 'EOF'
 {
   "schema_version": "1.0",
   "revision": 0,
@@ -93,7 +93,7 @@ To do a dry run (preview without writing):
 
 ### From JIRA
 
-Use the `sr:migrate-from-jira` command (requires `jira` CLI or REST API credentials in `.claude/backlog-config.json`):
+Use the `sr:migrate-from-jira` command (requires `jira` CLI or REST API credentials in `.specrails/backlog-config.json`):
 
 ```bash
 # Inside Claude Code
@@ -133,7 +133,7 @@ The `--update` flag regenerates only the backlog commands (`get-backlog-specs`,
 
 To revert to GitHub Issues:
 
-1. Edit `.specrails/config.yaml` (or `.claude/backlog-config.json` for scaffold installs) and set `provider: github`
+1. Edit `.specrails/config.yaml` (or `.specrails/backlog-config.json` for scaffold installs) and set `provider: github`
 2. Re-run `/specrails:setup --update` to regenerate commands
 3. Your `local-tickets.json` is preserved — switch back any time
 

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 backlog (local tickets in `.claude/local-tickets.json` by default, or GitHub Issues labeled `product-driven-backlog` if configured) and produces:
+The Product Analyst reads your backlog (local tickets in `.specrails/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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specrails-core",
-  "version": "3.5.0",
+  "version": "3.5.2",
   "description": "AI agent workflow system for Claude Code — installs 12 specialized agents, orchestration commands, and persona-driven product discovery into any repository",
   "bin": {
     "specrails-core": "bin/specrails-core.js"

package/templates/commands/specrails/auto-propose-backlog-specs.md

@@ -67,7 +67,7 @@ After the Explore agent completes:
 
 1. **Display** results to the user.
 
-2. Read `.claude/backlog-config.json` and extract:
+2. Read `.specrails/backlog-config.json` and extract:
    - `BACKLOG_PROVIDER` (`local`, `github`, `jira`, or `none`)
    - `BACKLOG_WRITE` (from `write_access`)
 
@@ -100,7 +100,7 @@ After the Explore agent completes:
 
 ### If provider=local — Sync to Local Tickets
 
-Local tickets are always read-write. Sync directly to `$SPECRAILS_DIR/local-tickets.json`.
+Local tickets are always read-write. Sync directly to `.specrails/local-tickets.json`.
 
 3. **Fetch existing local tickets** to avoid duplicates:
    ```
@@ -196,7 +196,7 @@ Local tickets are always read-write. Sync directly to `$SPECRAILS_DIR/local-tick
 
 ### If provider=jira and BACKLOG_WRITE=true — Sync to JIRA
 
-Read from `.claude/backlog-config.json`:
+Read from `.specrails/backlog-config.json`:
 - `JIRA_BASE_URL`, `JIRA_PROJECT_KEY`, `AUTH_METHOD`
 - `PROJECT_LABEL` (may be empty string)
 - `EPIC_MAPPING` (object mapping area name → JIRA epic key)
@@ -262,7 +262,7 @@ For each unique area:
    If `PROJECT_LABEL` is non-empty, add it to the `labels` array.
    Set `EPIC_MAPPING[area] = <returned key>`.
 
-After all areas are processed: write the updated `EPIC_MAPPING` back to `.claude/backlog-config.json`.
+After all areas are processed: write the updated `EPIC_MAPPING` back to `.specrails/backlog-config.json`.
 
 #### Step E: Create Story tickets
 

package/templates/commands/specrails/get-backlog-specs.md

@@ -163,7 +163,7 @@ The product-analyst receives this prompt:
 
    #### If provider=local — Cache from Local Tickets
 
-   Read `$SPECRAILS_DIR/local-tickets.json` and parse the `tickets` map. For each ticket with `"product-driven-backlog"` in its `labels` array and `status` not `"cancelled"`, build a snapshot object:
+   Read `.specrails/local-tickets.json` and parse the `tickets` map. For each ticket with `"product-driven-backlog"` in its `labels` array and `status` not `"cancelled"`, build a snapshot object:
    - `number`: ticket `id` (integer)
    - `title`: ticket `title` string
    - `state`: map ticket `status` — `"done"` or `"cancelled"` → `"closed"`, otherwise → `"open"`

package/templates/commands/specrails/implement.md

@@ -26,11 +26,11 @@ Check the environment variable `CLAUDE_CODE_ENTRYPOINT`. If it contains `remote_
 
 #### 1. Backlog provider availability
 
-Read `.claude/backlog-config.json` and extract `BACKLOG_PROVIDER`.
+Read `.specrails/backlog-config.json` and extract `BACKLOG_PROVIDER`.
 
 **If `BACKLOG_PROVIDER=local`:**
 ```bash
-[[ -f "$SPECRAILS_DIR/local-tickets.json" ]] && echo "Local tickets storage: OK" || echo "WARNING: local-tickets.json not found"
+[[ -f ".specrails/local-tickets.json" ]] && echo "Local tickets storage: OK" || echo "WARNING: local-tickets.json not found"
 ```
 - Set `LOCAL_TICKETS_AVAILABLE=true/false` based on file existence.
 - Set `GH_AVAILABLE=false` (GitHub CLI not needed for local provider).
@@ -132,7 +132,7 @@ After fetching issue refs, capture a baseline snapshot for conflict detection.
 
 ##### If `BACKLOG_PROVIDER=local` and input mode was issue numbers:
 
-For each resolved ticket ID, read `$SPECRAILS_DIR/local-tickets.json` and extract the ticket object at `tickets["{id}"]`.
+For each resolved ticket ID, read `.specrails/local-tickets.json` and extract the ticket object at `tickets["{id}"]`.
 
 Build a snapshot object for each ticket:
 - `number`: ticket `id` (integer)
@@ -314,7 +314,7 @@ Pick the single idea with the best impact/effort ratio from each exploration. Pr
 
 Otherwise, re-fetch each issue in scope and diff against the Phase 0 snapshot:
 
-**If `BACKLOG_PROVIDER=local`:** For each ticket ID in `ISSUE_REFS`, read `$SPECRAILS_DIR/local-tickets.json` and extract the ticket at `tickets["{id}"]`. If the ticket does not exist (deleted): treat as a CRITICAL conflict — field `"state"`, was `<cached state>`, now `"deleted"`. Otherwise, reconstruct a current snapshot using the same mapping as the Phase 0 local snapshot.
+**If `BACKLOG_PROVIDER=local`:** For each ticket ID in `ISSUE_REFS`, read `.specrails/local-tickets.json` and extract the ticket at `tickets["{id}"]`. If the ticket does not exist (deleted): treat as a CRITICAL conflict — field `"state"`, was `<cached state>`, now `"deleted"`. Otherwise, reconstruct a current snapshot using the same mapping as the Phase 0 local snapshot.
 
 **If `BACKLOG_PROVIDER=github`:** For each issue number in `ISSUE_REFS`:
 
@@ -897,7 +897,7 @@ This check is independent of Phase 3a.0. Even if the user chose to continue thro
 
 Re-fetch each issue in `ISSUE_REFS` and diff against `.claude/backlog-cache.json` using the same algorithm as Phase 3a.0:
 
-**If `BACKLOG_PROVIDER=local`:** Read `$SPECRAILS_DIR/local-tickets.json` and extract each ticket by ID.
+**If `BACKLOG_PROVIDER=local`:** Read `.specrails/local-tickets.json` and extract each ticket by ID.
 
 **If `BACKLOG_PROVIDER=github`:**
 ```bash

package/templates/commands/specrails/propose-spec.md

@@ -47,7 +47,7 @@ Output ONLY the following structured markdown. Do not add any preamble or explan
 
 ## Backlog Sync
 
-After generating the proposal, read `.claude/backlog-config.json` to determine `BACKLOG_PROVIDER` and `BACKLOG_WRITE`.
+After generating the proposal, read `.specrails/backlog-config.json` to determine `BACKLOG_PROVIDER` and `BACKLOG_WRITE`.
 
 ### If provider=local — Create Local Ticket
 

package/templates/commands/specrails/setup.md

@@ -59,7 +59,7 @@ Read the following files to understand the current installation state:
    Command template files include `implement.md`, `batch-implement.md`, `compat-check.md`, `refactor-recommender.md`, `why.md`, `get-backlog-specs.md`, `auto-propose-backlog-specs.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.
+6. Read `.specrails/backlog-config.json` if it exists — contains stored provider configuration needed for command placeholder substitution.
 
 ### Phase U2: Quick Codebase Re-Analysis
 
@@ -178,7 +178,7 @@ For each command in the "changed commands" list from Phase U3:
 1. Read the NEW template:
    - If `cli_provider == "claude"`: from `$SPECRAILS_DIR/setup-templates/commands/specrails/<name>.md`
    - If `cli_provider == "codex"`: from `$SPECRAILS_DIR/setup-templates/skills/sr-<name>/SKILL.md`
-2. Read stored backlog configuration from `$SPECRAILS_DIR/backlog-config.json` (if it exists) to resolve provider-specific placeholders:
+2. Read stored backlog configuration from `.specrails/backlog-config.json` (if it exists) to resolve provider-specific placeholders:
    - `BACKLOG_PROVIDER` → `provider` field (`github`, `jira`, or `none`)
    - `BACKLOG_WRITE` → `write_access` field
    - `JIRA_BASE_URL` → `jira_base_url` field
@@ -424,8 +424,8 @@ Core commands (always install if missing):
 - `auto-propose-backlog-specs.md`
 
 **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):
+1. Copy `templates/local-tickets-schema.json` to `.specrails/local-tickets.json` and set `last_updated` to the current ISO-8601 timestamp. Skip if the file already exists.
+2. Write `.specrails/backlog-config.json` (skip if already exists):
    ```json
    {
      "provider": "local",
@@ -699,7 +699,7 @@ Ask the user how they want to manage their product backlog. Default is local —
 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.
+   No external tools or accounts required. Tickets stored in `.specrails/local-tickets.json`, version-controlled and diffable.
 2. **External provider** — connect GitHub Issues, JIRA, or disable backlog commands
 ```
 
@@ -713,7 +713,7 @@ If the user selects **2**: display the secondary menu:
 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.
+   No external tools required. Tickets stored in `.specrails/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)
@@ -725,10 +725,10 @@ Wait for the user's choice. Set `BACKLOG_PROVIDER` to `local`, `github`, `jira`,
 
 No external tools or credentials required. Initialize the storage file:
 
-1. Copy `templates/local-tickets-schema.json` to `$SPECRAILS_DIR/local-tickets.json`
+1. Copy `templates/local-tickets-schema.json` to `.specrails/local-tickets.json`
 2. Set `last_updated` to the current ISO-8601 timestamp
 
-Store configuration in `$SPECRAILS_DIR/backlog-config.json`:
+Store configuration in `.specrails/backlog-config.json`:
 ```json
 {
   "provider": "local",
@@ -774,13 +774,13 @@ Local tickets are always read-write — there is no "read only" mode since the f
 
 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`
+1. **Acquire lock:** Check for `.specrails/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`
+2. **Create lock file:** Write `{"agent": "<agent-name-or-process>", "timestamp": "<ISO-8601>"}` to `.specrails/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`
+4. **Release lock:** Delete `.specrails/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.
@@ -895,7 +895,7 @@ Ask:
 
 Set `EPIC_LINK_FIELD` to `parent` or `customfield_10014`. Default: `parent`.
 
-Store the full configuration in `.claude/backlog-config.json`:
+Store the full configuration in `.specrails/backlog-config.json`:
 ```json
 {
   "provider": "jira",
@@ -1147,22 +1147,22 @@ When adapting `auto-propose-backlog-specs.md` and `get-backlog-specs.md`, substi
 
 #### 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.
+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/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 /specrails:setup to initialize"` |
-| `{{BACKLOG_FETCH_CMD}}` | Read `$SPECRAILS_DIR/local-tickets.json`. Parse the `tickets` map and return all entries where `status` is `"todo"` or `"in_progress"`. |
-| `{{BACKLOG_FETCH_ALL_CMD}}` | Read `$SPECRAILS_DIR/local-tickets.json`. Parse the `tickets` map and return all entries regardless of status. |
-| `{{BACKLOG_FETCH_CLOSED_CMD}}` | Read `$SPECRAILS_DIR/local-tickets.json`. Parse the `tickets` map and return all entries where `status` is `"done"` or `"cancelled"`. |
-| `{{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_PREFLIGHT}}` | `[[ -f ".specrails/local-tickets.json" ]] && echo "Local tickets storage: OK" \|\| echo "WARNING: .specrails/local-tickets.json not found — run /specrails:setup to initialize"` |
+| `{{BACKLOG_FETCH_CMD}}` | Read `.specrails/local-tickets.json`. Parse the `tickets` map and return all entries where `status` is `"todo"` or `"in_progress"`. |
+| `{{BACKLOG_FETCH_ALL_CMD}}` | Read `.specrails/local-tickets.json`. Parse the `tickets` map and return all entries regardless of status. |
+| `{{BACKLOG_FETCH_CLOSED_CMD}}` | Read `.specrails/local-tickets.json`. Parse the `tickets` map and return all entries where `status` is `"done"` or `"cancelled"`. |
+| `{{BACKLOG_VIEW_CMD}}` | Read `.specrails/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/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/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/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/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`. |
 
@@ -1183,7 +1183,7 @@ All write operations must follow the **advisory file locking protocol** defined
 - Issue view: `jira issue view {key}` or REST API
 - VPC scores stored in the issue description body (same markdown format, parsed from description)
 - Pre-flight check: `jira me` or test API connectivity
-- Store JIRA config in `$SPECRAILS_DIR/backlog-config.json`:
+- Store JIRA config in `.specrails/backlog-config.json`:
   ```json
   {
     "provider": "jira",

package/templates/skills/sr-auto-propose-backlog-specs/SKILL.md

@@ -70,7 +70,7 @@ After the Explore agent completes:
 
 1. **Display** results to the user.
 
-2. Read `.claude/backlog-config.json` and extract:
+2. Read `.specrails/backlog-config.json` and extract:
    - `BACKLOG_PROVIDER` (`github`, `jira`, or `none`)
    - `BACKLOG_WRITE` (from `write_access`)
 
@@ -159,7 +159,7 @@ After the Explore agent completes:
 
 ### If provider=jira and BACKLOG_WRITE=true — Sync to JIRA
 
-Read from `.claude/backlog-config.json`:
+Read from `.specrails/backlog-config.json`:
 - `JIRA_BASE_URL`, `JIRA_PROJECT_KEY`, `AUTH_METHOD`
 - `PROJECT_LABEL` (may be empty string)
 - `EPIC_MAPPING` (object mapping area name → JIRA epic key)
@@ -225,7 +225,7 @@ For each unique area:
    If `PROJECT_LABEL` is non-empty, add it to the `labels` array.
    Set `EPIC_MAPPING[area] = <returned key>`.
 
-After all areas are processed: write the updated `EPIC_MAPPING` back to `.claude/backlog-config.json`.
+After all areas are processed: write the updated `EPIC_MAPPING` back to `.specrails/backlog-config.json`.
 
 #### Step E: Create Story tickets