specrails-core 3.5.1 → 3.5.2

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",
@@ -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.
@@ -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/migration-guide.md

@@ -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/package.json

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