specrails-core 3.5.1 → 3.5.3

package/commands/setup.md

@@ -26,7 +26,7 @@ When `--update` is passed, execute this streamlined flow instead of the full wiz
 
 Read the following files to understand the current installation state:
 
-1. Read `.specrails-manifest.json` — contains agent template checksums from the last install/update. Structure:
+1. Read `.specrails/specrails-manifest.json` — contains agent template checksums from the last install/update. Structure:
    ```json
    {
      "version": "0.2.0",
@@ -39,27 +39,27 @@ Read the following files to understand the current installation state:
    }
    ```
    If this file does not exist, inform the user:
-   > "No `.specrails-manifest.json` found. This looks like a pre-versioning installation. Run `update.sh` first to initialize the manifest, then re-run `/specrails:setup --update`."
+   > "No `.specrails/specrails-manifest.json` found. This looks like a pre-versioning installation. Run `update.sh` first to initialize the manifest, then re-run `/specrails:setup --update`."
    Then stop.
 
-2. Read `.specrails-version` — contains the current version string (e.g., `0.2.0`). If it does not exist, treat version as `0.1.0 (legacy)`.
+2. Read `.specrails/specrails-version` — contains the current version string (e.g., `0.2.0`). If it does not exist, treat version as `0.1.0 (legacy)`.
 
-3. Determine `$SPECRAILS_DIR` by reading `$SPECRAILS_DIR/setup-templates/.provider-detection.json` — try `.claude/setup-templates/.provider-detection.json` first, then `.codex/setup-templates/.provider-detection.json`. Extract `cli_provider` and `specrails_dir`. If not found, default to `cli_provider = "claude"`, `specrails_dir = ".claude"`.
+3. Determine `$SPECRAILS_DIR` by reading `.specrails/setup-templates/.provider-detection.json`. Extract `cli_provider` and `specrails_dir`. If not found, default to `cli_provider = "claude"`, `specrails_dir = ".claude"`.
 
-4. List all template files in `$SPECRAILS_DIR/setup-templates/agents/` — these are the NEW agent templates from the update:
+4. List all template files in `.specrails/setup-templates/agents/` — these are the NEW agent templates from the update:
    ```bash
-   ls $SPECRAILS_DIR/setup-templates/agents/
+   ls .specrails/setup-templates/agents/
    ```
    Template files are named with `sr-` prefix (e.g., `sr-architect.md`, `sr-developer.md`).
 
-5. List all template files in `$SPECRAILS_DIR/setup-templates/commands/specrails/` — these are the NEW command templates from the update:
+5. List all template files in `.specrails/setup-templates/commands/specrails/` — these are the NEW command templates from the update:
    ```bash
-   ls $SPECRAILS_DIR/setup-templates/commands/specrails/
+   ls .specrails/setup-templates/commands/specrails/
    ```
    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
 
@@ -82,28 +82,28 @@ Store all results for use in Phases U4 and U5.
 
 ### Phase U3: Identify What Needs Regeneration
 
-**Agent templates:** For each agent template, find its entry in the manifest's `artifacts` map (keyed as `templates/agents/sr-<name>.md`). Compute the SHA-256 checksum of the corresponding file in `.claude/setup-templates/agents/`:
+**Agent templates:** For each agent template, find its entry in the manifest's `artifacts` map (keyed as `templates/agents/sr-<name>.md`). Compute the SHA-256 checksum of the corresponding file in `.specrails/setup-templates/agents/`:
 
 ```bash
-sha256sum .claude/setup-templates/agents/sr-<name>.md
+sha256sum .specrails/setup-templates/agents/sr-<name>.md
 ```
 
 Build three lists for agents:
 
 1. **Changed agents**: agent name exists in manifest AND the current template checksum differs from the manifest checksum → mark for regeneration
-2. **New agents**: template file exists in `.claude/setup-templates/agents/` but the agent name is NOT in the manifest → mark for evaluation
+2. **New agents**: template file exists in `.specrails/setup-templates/agents/` but the agent name is NOT in the manifest → mark for evaluation
 3. **Unchanged agents**: agent name exists in manifest AND checksum matches → skip
 
-**Command templates:** If `.claude/setup-templates/commands/specrails/` exists, for each command template file, find its entry in the manifest's `artifacts` map (keyed as `templates/commands/specrails/<name>.md`). Compute the SHA-256 checksum of the corresponding file in `.claude/setup-templates/commands/specrails/`:
+**Command templates:** If `.specrails/setup-templates/commands/specrails/` exists, for each command template file, find its entry in the manifest's `artifacts` map (keyed as `templates/commands/specrails/<name>.md`). Compute the SHA-256 checksum of the corresponding file in `.specrails/setup-templates/commands/specrails/`:
 
 ```bash
-sha256sum .claude/setup-templates/commands/specrails/<name>.md
+sha256sum .specrails/setup-templates/commands/specrails/<name>.md
 ```
 
 Build three lists for commands:
 
 1. **Changed commands**: command name exists in manifest AND the current template checksum differs from the manifest checksum → mark for update
-2. **New commands**: template file exists in `.claude/setup-templates/commands/specrails/` but the command name is NOT in the manifest → mark for evaluation
+2. **New commands**: template file exists in `.specrails/setup-templates/commands/specrails/` but the command name is NOT in the manifest → mark for evaluation
 3. **Unchanged commands**: command name exists in manifest AND checksum matches → skip
 
 Display the combined analysis to the user:
@@ -144,7 +144,7 @@ Then jump to Phase U7.
 
 For each agent in the "changed" list:
 
-1. Read the NEW template from `$SPECRAILS_DIR/setup-templates/agents/sr-<name>.md`
+1. Read the NEW template from `.specrails/setup-templates/agents/sr-<name>.md`
 2. Use the codebase analysis from Phase U2 to fill in all `{{PLACEHOLDER}}` values, using the same substitution rules as Phase 4.1 of the full setup:
    - `{{PROJECT_NAME}}` → project name (from README.md or directory name)
    - `{{ARCHITECTURE_DIAGRAM}}` → detected architecture layers
@@ -176,9 +176,9 @@ grep -r '{{[A-Z_]*}}' .codex/agents/sr-*.toml 2>/dev/null || echo "OK: no broken
 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:
+   - If `cli_provider == "claude"`: from `.specrails/setup-templates/commands/specrails/<name>.md`
+   - If `cli_provider == "codex"`: from `.specrails/setup-templates/skills/sr-<name>/SKILL.md`
+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
@@ -214,7 +214,7 @@ If any placeholders remain unresolved, warn the user:
 
 For each agent in the "new" list:
 
-1. Read the template from `.claude/setup-templates/agents/sr-<name>.md` to understand what stack or layer it targets (read its description and any layer-specific comments)
+1. Read the template from `.specrails/setup-templates/agents/sr-<name>.md` to understand what stack or layer it targets (read its description and any layer-specific comments)
 2. Match against the codebase detected in Phase U2:
    - If the template targets a layer/stack that IS present (e.g., `sr-frontend-developer` and React was detected), prompt:
      > "New agent available: `sr-<name>` — your project uses [detected tech]. Add it? [Y/n]"
@@ -230,8 +230,8 @@ For each agent in the "new" list:
 For each command in the "new commands" list from Phase U3:
 
 1. Read the 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`
+   - If `cli_provider == "claude"`: from `.specrails/setup-templates/commands/specrails/<name>.md`
+   - If `cli_provider == "codex"`: from `.specrails/setup-templates/skills/sr-<name>/SKILL.md`
 2. Prompt the user:
    - If `cli_provider == "claude"`: `"New command available: /specrails:<name> — [one-line description]. Install it? [Y/n]"`
    - If `cli_provider == "codex"`: `"New skill available: $sr-<name> — [one-line description]. Install it? [Y/n]"`
@@ -298,12 +298,12 @@ All agents and commands are now up to date.
 [list command names, or "(none)"]
 ```
 
-Update `.specrails-manifest.json` to reflect the new checksums for all regenerated/updated and added agents and commands:
+Update `.specrails/specrails-manifest.json` to reflect the new checksums for all regenerated/updated and added agents and commands:
 - For each regenerated agent: update its checksum entry to the new template's checksum (keyed as `templates/agents/sr-<name>.md`)
 - For each added agent: add a new entry with its checksum
 - For each updated command: update its checksum entry to the new template's checksum (keyed as `templates/commands/specrails/<name>.md`)
 - For each added command: add a new entry with its checksum
-- Update the `version` field to the version read from `.specrails-version`
+- Update the `version` field to the version read from `.specrails/specrails-version`
 
 ---
 
@@ -382,7 +382,7 @@ Generate files using the Lite Mode defaults.
 
 **1. CLAUDE.md**
 
-Read `setup-templates/claude-md/CLAUDE-quickstart.md` (or fall back to `setup-templates/claude-md/default.md` if quickstart template is not found).
+Read `.specrails/setup-templates/claude-md/CLAUDE-quickstart.md` (or fall back to `.specrails/setup-templates/claude-md/default.md` if quickstart template is not found).
 
 Replace placeholders:
 - `{{PROJECT_NAME}}` → derive from directory name or README.md first heading
@@ -396,7 +396,7 @@ Skip if user says no.
 
 **2. Agent files**
 
-For each default agent (sr-architect, sr-developer, sr-reviewer, sr-product-manager), read the template from `$SPECRAILS_DIR/setup-templates/agents/<name>.md` and generate the adapted agent file using the dual-format rules from Phase 4.1:
+For each default agent (sr-architect, sr-developer, sr-reviewer, sr-product-manager), read the template from `.specrails/setup-templates/agents/<name>.md` and generate the adapted agent file using the dual-format rules from Phase 4.1:
 - `cli_provider == "claude"`: write to `.claude/agents/<name>.md` (Markdown with frontmatter)
 - `cli_provider == "codex"`: write to `.codex/agents/<name>.toml` (TOML format)
 
@@ -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",
@@ -436,7 +436,7 @@ Core commands (always install if missing):
 
 **If `cli_provider == "claude"`:**
 
-If `QS_IS_RERUN=false` (fresh install): for each core command, read the template from `$SPECRAILS_DIR/setup-templates/commands/specrails/<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 /specrails:setup to configure personas)`, then write to `.claude/commands/specrails/<name>.md`.
+If `QS_IS_RERUN=false` (fresh install): for each core command, read the template from `.specrails/setup-templates/commands/specrails/<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 /specrails:setup to configure personas)`, then write to `.claude/commands/specrails/<name>.md`.
 
 If `QS_IS_RERUN=true` (gap-fill mode): for each command in the list above, check if `.claude/commands/specrails/<name>.md` already exists:
 - If it exists: skip it — show `✓ Already installed: /specrails:<name>`
@@ -444,7 +444,7 @@ If `QS_IS_RERUN=true` (gap-fill mode): for each command in the list above, check
 
 **If `cli_provider == "codex"`:**
 
-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 /specrails:setup to configure personas)`, then write 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/setup-templates/skills/sr-<name>/SKILL.md`, substitute the backlog placeholders with local values and stub persona placeholders with `(Lite Mode — run /specrails: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>`
@@ -452,7 +452,7 @@ If `QS_IS_RERUN=true` (gap-fill mode): for each command in the list above, check
 
 **4. Cleanup**
 
-Remove `setup-templates/` from `.claude/` (same as full wizard cleanup in Phase 5).
+Remove `.specrails/setup-templates/` (same as full wizard cleanup in Phase 5).
 
 Remove `commands/setup.md` from `.claude/commands/` if it was copied there by the installer.
 
@@ -560,7 +560,7 @@ Display the detected architecture to the user:
 
 ### OSS Project Detection
 
-Read `.claude/setup-templates/.oss-detection.json` if it exists.
+Read `.specrails/setup-templates/.oss-detection.json` if it exists.
 
 | Signal | Status |
 |--------|--------|
@@ -629,7 +629,7 @@ Search queries to use (adapt to the domain):
 
 ### 2.3 Generate VPC personas
 
-For each user type, generate a full Value Proposition Canvas persona file following the template at `.claude/setup-templates/personas/persona.md`.
+For each user type, generate a full Value Proposition Canvas persona file following the template at `.specrails/setup-templates/personas/persona.md`.
 
 Each persona must include:
 - **Profile**: Demographics, behaviors, tools used, spending patterns
@@ -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.
@@ -986,9 +986,9 @@ Wait for final confirmation.
 
 ## Phase 4: Generate Files
 
-Read each template from `.claude/setup-templates/` and generate the final files adapted to this project. Use the codebase analysis from Phase 1, personas from Phase 2, and configuration from Phase 3.
+Read each template from `.specrails/setup-templates/` and generate the final files adapted to this project. Use the codebase analysis from Phase 1, personas from Phase 2, and configuration from Phase 3.
 
-**Provider detection (required before any file generation):** Read `$SPECRAILS_DIR/setup-templates/.provider-detection.json` to determine `cli_provider` (`"claude"` or `"codex"`) and `specrails_dir` (`.claude` or `.codex`). All output paths in Phase 4 use `$SPECRAILS_DIR` as the base directory. If the file is missing, fall back to `cli_provider = "claude"` and `specrails_dir = ".claude"`.
+**Provider detection (required before any file generation):** Read `.specrails/setup-templates/.provider-detection.json` to determine `cli_provider` (`"claude"` or `"codex"`) and `specrails_dir` (`.claude` or `.codex`). All output paths in Phase 4 use `$SPECRAILS_DIR` as the base directory. If the file is missing, fall back to `cli_provider = "claude"` and `specrails_dir = ".claude"`.
 
 ### 4.1 Generate agents
 
@@ -997,26 +997,26 @@ For each selected agent, read the template and generate the adapted version.
 **Template → Output mapping:**
 
 **If `cli_provider == "claude"` (default):**
-- `setup-templates/agents/sr-architect.md` → `.claude/agents/sr-architect.md`
-- `setup-templates/agents/sr-developer.md` → `.claude/agents/sr-developer.md`
-- `setup-templates/agents/sr-reviewer.md` → `.claude/agents/sr-reviewer.md`
-- `setup-templates/agents/sr-test-writer.md` → `.claude/agents/sr-test-writer.md`
-- `setup-templates/agents/sr-security-reviewer.md` → `.claude/agents/sr-security-reviewer.md`
-- `setup-templates/agents/sr-product-manager.md` → `.claude/agents/sr-product-manager.md`
-- `setup-templates/agents/sr-product-analyst.md` → `.claude/agents/sr-product-analyst.md`
-- `setup-templates/agents/sr-backend-developer.md` → `.claude/agents/sr-backend-developer.md` (if backend layer)
-- `setup-templates/agents/sr-frontend-developer.md` → `.claude/agents/sr-frontend-developer.md` (if frontend layer)
+- `.specrails/setup-templates/agents/sr-architect.md` → `.claude/agents/sr-architect.md`
+- `.specrails/setup-templates/agents/sr-developer.md` → `.claude/agents/sr-developer.md`
+- `.specrails/setup-templates/agents/sr-reviewer.md` → `.claude/agents/sr-reviewer.md`
+- `.specrails/setup-templates/agents/sr-test-writer.md` → `.claude/agents/sr-test-writer.md`
+- `.specrails/setup-templates/agents/sr-security-reviewer.md` → `.claude/agents/sr-security-reviewer.md`
+- `.specrails/setup-templates/agents/sr-product-manager.md` → `.claude/agents/sr-product-manager.md`
+- `.specrails/setup-templates/agents/sr-product-analyst.md` → `.claude/agents/sr-product-analyst.md`
+- `.specrails/setup-templates/agents/sr-backend-developer.md` → `.claude/agents/sr-backend-developer.md` (if backend layer)
+- `.specrails/setup-templates/agents/sr-frontend-developer.md` → `.claude/agents/sr-frontend-developer.md` (if frontend layer)
 
 **If `cli_provider == "codex"`:**
-- `setup-templates/agents/sr-architect.md` → `.codex/agents/sr-architect.toml`
-- `setup-templates/agents/sr-developer.md` → `.codex/agents/sr-developer.toml`
-- `setup-templates/agents/sr-reviewer.md` → `.codex/agents/sr-reviewer.toml`
-- `setup-templates/agents/sr-test-writer.md` → `.codex/agents/sr-test-writer.toml`
-- `setup-templates/agents/sr-security-reviewer.md` → `.codex/agents/sr-security-reviewer.toml`
-- `setup-templates/agents/sr-product-manager.md` → `.codex/agents/sr-product-manager.toml`
-- `setup-templates/agents/sr-product-analyst.md` → `.codex/agents/sr-product-analyst.toml`
-- `setup-templates/agents/sr-backend-developer.md` → `.codex/agents/sr-backend-developer.toml` (if backend layer)
-- `setup-templates/agents/sr-frontend-developer.md` → `.codex/agents/sr-frontend-developer.toml` (if frontend layer)
+- `.specrails/setup-templates/agents/sr-architect.md` → `.codex/agents/sr-architect.toml`
+- `.specrails/setup-templates/agents/sr-developer.md` → `.codex/agents/sr-developer.toml`
+- `.specrails/setup-templates/agents/sr-reviewer.md` → `.codex/agents/sr-reviewer.toml`
+- `.specrails/setup-templates/agents/sr-test-writer.md` → `.codex/agents/sr-test-writer.toml`
+- `.specrails/setup-templates/agents/sr-security-reviewer.md` → `.codex/agents/sr-security-reviewer.toml`
+- `.specrails/setup-templates/agents/sr-product-manager.md` → `.codex/agents/sr-product-manager.toml`
+- `.specrails/setup-templates/agents/sr-product-analyst.md` → `.codex/agents/sr-product-analyst.toml`
+- `.specrails/setup-templates/agents/sr-backend-developer.md` → `.codex/agents/sr-backend-developer.toml` (if backend layer)
+- `.specrails/setup-templates/agents/sr-frontend-developer.md` → `.codex/agents/sr-frontend-developer.toml` (if frontend layer)
 
 When generating each agent:
 1. Read the template
@@ -1058,7 +1058,7 @@ When generating each agent:
 ### 4.2 Generate personas
 
 If IS_OSS=true:
-1. Copy `setup-templates/personas/the-maintainer.md` to `$SPECRAILS_DIR/agents/personas/the-maintainer.md`
+1. Copy `.specrails/setup-templates/personas/the-maintainer.md` to `$SPECRAILS_DIR/agents/personas/the-maintainer.md`
 2. Log: "Maintainer persona included"
 3. Set MAINTAINER_INCLUDED=true for use in template substitution
 4. Set `{{MAINTAINER_PERSONA_LINE}}` = `- \`$SPECRAILS_DIR/agents/personas/the-maintainer.md\` — "Kai" the Maintainer (open-source maintainer)`
@@ -1078,26 +1078,26 @@ Write each persona to `$SPECRAILS_DIR/agents/personas/`:
 For each selected command, read the template and adapt.
 
 **If `cli_provider == "claude"` (default):**
-- `setup-templates/commands/specrails/implement.md` → `.claude/commands/specrails/implement.md`
-- `setup-templates/commands/specrails/batch-implement.md` → `.claude/commands/specrails/batch-implement.md`
-- `setup-templates/commands/specrails/propose-spec.md` → `.claude/commands/specrails/propose-spec.md`
-- `setup-templates/commands/specrails/get-backlog-specs.md` → `.claude/commands/specrails/get-backlog-specs.md` (if `BACKLOG_PROVIDER != none`)
-- `setup-templates/commands/specrails/auto-propose-backlog-specs.md` → `.claude/commands/specrails/auto-propose-backlog-specs.md` (if `BACKLOG_PROVIDER != none`)
-- `setup-templates/commands/specrails/compat-check.md` → `.claude/commands/specrails/compat-check.md`
-- `setup-templates/commands/specrails/refactor-recommender.md` → `.claude/commands/specrails/refactor-recommender.md`
-- `setup-templates/commands/specrails/why.md` → `.claude/commands/specrails/why.md`
+- `.specrails/setup-templates/commands/specrails/implement.md` → `.claude/commands/specrails/implement.md`
+- `.specrails/setup-templates/commands/specrails/batch-implement.md` → `.claude/commands/specrails/batch-implement.md`
+- `.specrails/setup-templates/commands/specrails/propose-spec.md` → `.claude/commands/specrails/propose-spec.md`
+- `.specrails/setup-templates/commands/specrails/get-backlog-specs.md` → `.claude/commands/specrails/get-backlog-specs.md` (if `BACKLOG_PROVIDER != none`)
+- `.specrails/setup-templates/commands/specrails/auto-propose-backlog-specs.md` → `.claude/commands/specrails/auto-propose-backlog-specs.md` (if `BACKLOG_PROVIDER != none`)
+- `.specrails/setup-templates/commands/specrails/compat-check.md` → `.claude/commands/specrails/compat-check.md`
+- `.specrails/setup-templates/commands/specrails/refactor-recommender.md` → `.claude/commands/specrails/refactor-recommender.md`
+- `.specrails/setup-templates/commands/specrails/why.md` → `.claude/commands/specrails/why.md`
 
 **If `cli_provider == "codex"`:**
-- `setup-templates/skills/sr-implement/SKILL.md` → `.agents/skills/sr-implement/SKILL.md`
-- `setup-templates/skills/sr-batch-implement/SKILL.md` → `.agents/skills/sr-batch-implement/SKILL.md`
-- `setup-templates/commands/specrails/propose-spec.md` → `.agents/skills/sr-propose-spec/SKILL.md` (wrap with YAML frontmatter if no skill template exists)
-- `setup-templates/commands/specrails/get-backlog-specs.md` → `.agents/skills/sr-get-backlog-specs/SKILL.md` (if `BACKLOG_PROVIDER != none`; wrap with frontmatter)
-- `setup-templates/commands/specrails/auto-propose-backlog-specs.md` → `.agents/skills/sr-auto-propose-backlog-specs/SKILL.md` (if `BACKLOG_PROVIDER != none`; wrap with frontmatter)
-- `setup-templates/skills/sr-compat-check/SKILL.md` → `.agents/skills/sr-compat-check/SKILL.md`
-- `setup-templates/skills/sr-refactor-recommender/SKILL.md` → `.agents/skills/sr-refactor-recommender/SKILL.md`
-- `setup-templates/skills/sr-why/SKILL.md` → `.agents/skills/sr-why/SKILL.md`
-
-**Codex skill frontmatter wrapping:** When a dedicated skill template does not exist in `setup-templates/skills/` for a command, generate the `SKILL.md` by prepending YAML frontmatter to the command content:
+- `.specrails/setup-templates/skills/sr-implement/SKILL.md` → `.agents/skills/sr-implement/SKILL.md`
+- `.specrails/setup-templates/skills/sr-batch-implement/SKILL.md` → `.agents/skills/sr-batch-implement/SKILL.md`
+- `.specrails/setup-templates/commands/specrails/propose-spec.md` → `.agents/skills/sr-propose-spec/SKILL.md` (wrap with YAML frontmatter if no skill template exists)
+- `.specrails/setup-templates/commands/specrails/get-backlog-specs.md` → `.agents/skills/sr-get-backlog-specs/SKILL.md` (if `BACKLOG_PROVIDER != none`; wrap with frontmatter)
+- `.specrails/setup-templates/commands/specrails/auto-propose-backlog-specs.md` → `.agents/skills/sr-auto-propose-backlog-specs/SKILL.md` (if `BACKLOG_PROVIDER != none`; wrap with frontmatter)
+- `.specrails/setup-templates/skills/sr-compat-check/SKILL.md` → `.agents/skills/sr-compat-check/SKILL.md`
+- `.specrails/setup-templates/skills/sr-refactor-recommender/SKILL.md` → `.agents/skills/sr-refactor-recommender/SKILL.md`
+- `.specrails/setup-templates/skills/sr-why/SKILL.md` → `.agents/skills/sr-why/SKILL.md`
+
+**Codex skill frontmatter wrapping:** When a dedicated skill template does not exist in `.specrails/setup-templates/skills/` for a command, generate the `SKILL.md` by prepending YAML frontmatter to the command content:
 ```yaml
 ---
 name: sr-<name>
@@ -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",
@@ -1199,7 +1199,7 @@ The command templates use `{{BACKLOG_FETCH_CMD}}`, `{{BACKLOG_CREATE_CMD}}`, `{{
 ### 4.4 Generate rules
 
 For each detected layer, read the layer rule template and generate a layer-specific rules file:
-- `setup-templates/rules/layer.md` → `$SPECRAILS_DIR/rules/{layer-name}.md`
+- `.specrails/setup-templates/rules/layer.md` → `$SPECRAILS_DIR/rules/{layer-name}.md`
 
 Each rule file must:
 - Have the correct `paths:` frontmatter matching the layer's directory
@@ -1214,7 +1214,7 @@ Each rule file must:
 
 ### 4.6 Generate settings
 
-Read `.claude/setup-templates/.provider-detection.json` (written by `install.sh`) to determine `cli_provider` (`"claude"` or `"codex"`).
+Read `.specrails/setup-templates/.provider-detection.json` (written by `install.sh`) to determine `cli_provider` (`"claude"` or `"codex"`).
 
 **If `cli_provider == "claude"` (default):**
 
@@ -1227,9 +1227,9 @@ Create or merge `.claude/settings.json` with permissions for:
 
 **If `cli_provider == "codex"`:**
 
-1. Read `setup-templates/settings/codex-config.toml`. Write it to `.codex/config.toml` as-is (no substitutions needed — the TOML is static).
+1. Read `.specrails/setup-templates/settings/codex-config.toml`. Write it to `.codex/config.toml` as-is (no substitutions needed — the TOML is static).
 
-2. Read `setup-templates/settings/codex-rules.star`. Replace `{{CODEX_SHELL_RULES}}` with Starlark `prefix_rule(...)` lines for each detected tool allowance:
+2. Read `.specrails/setup-templates/settings/codex-rules.star`. Replace `{{CODEX_SHELL_RULES}}` with Starlark `prefix_rule(...)` lines for each detected tool allowance:
 
    | Detected tool/command | Starlark rule |
    |----------------------|---------------|
@@ -1268,7 +1268,7 @@ The setup process installed temporary files that are only needed during installa
 
 ```bash
 # 1. Remove setup templates (used as structural references during generation)
-rm -rf .claude/setup-templates/
+rm -rf .specrails/setup-templates/
 
 # 2. Remove the /specrails:setup command itself — it's a one-time installer, not a permanent command
 rm -f .claude/commands/setup.md
@@ -1281,7 +1281,7 @@ rm -f .claude/commands/setup.md
 **What gets removed:**
 | Artifact | Why |
 |----------|-----|
-| `.claude/setup-templates/` | Temporary — templates already rendered into final files |
+| `.specrails/setup-templates/` | Temporary — templates already rendered into final files |
 | `.claude/commands/setup.md` | One-time installer — running it again would overwrite customized agents |
 
 **What to do with `specrails/`:**
@@ -1327,7 +1327,7 @@ ls .codex/rules/*.md
 ls .codex/agent-memory/
 
 # These should NOT exist (scaffolding):
-# $SPECRAILS_DIR/setup-templates/  — GONE
+# .specrails/setup-templates/  — GONE
 # If cli_provider == "claude": $SPECRAILS_DIR/commands/setup.md  — GONE
 # If cli_provider == "codex": .agents/skills/setup/  — GONE (installer scaffold, not a generated sr-skill)
 ```
@@ -1402,7 +1402,7 @@ Note: Only commands/skills selected during setup are shown. Backlog commands are
 ### Scaffolding Removed
 | Artifact | Status |
 |----------|--------|
-| $SPECRAILS_DIR/setup-templates/ | Deleted |
+| .specrails/setup-templates/ | Deleted |
 [If cli_provider == "claude":] | .claude/commands/setup.md | Deleted |
 [If cli_provider == "codex":] | .agents/skills/setup/ | Deleted |
 | specrails/ | [User's choice] |

package/docs/installation.md

@@ -82,9 +82,9 @@ git clone https://github.com/fjpulidop/specrails-core.git
 2. **Detects existing setup** — warns if SpecRails artifacts already exist
 3. **Installs artifacts:**
    - `.claude/commands/specrails/setup.md` — the `/specrails:setup` wizard
-   - `.claude/setup-templates/` — agent and command templates (temporary, removed after `/specrails:setup`)
+   - `.specrails/setup-templates/` — agent and command templates (temporary, removed after `/specrails:setup`)
    - `.claude/security-exemptions.yaml` — security scanner config
-4. **Tracks version** — writes `.specrails-version` and `.specrails-manifest.json`
+4. **Tracks version** — writes `.specrails/specrails-version` and `.specrails/specrails-manifest.json`
 
 The scaffold installer only copies files. It does not modify your existing code, create commits, or push to any remote.
 
@@ -210,7 +210,7 @@ The wizard fills all templates with your project-specific context:
 The wizard removes itself:
 
 - Deletes `.claude/commands/specrails/setup.md`
-- Deletes `.claude/setup-templates/`
+- Deletes `.specrails/setup-templates/`
 - Leaves only the final generated files
 
 After this phase, `/specrails:setup` is no longer available until re-run — your workflow is ready.
@@ -253,7 +253,7 @@ ls .claude/agents/
 grep -r '{{[A-Z_]*}}' .claude/agents/ .claude/commands/ .claude/rules/
 
 # Scaffold method: check version
-cat .specrails-version
+cat .specrails/specrails-version
 ```
 
 ---

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/docs/updating.md

@@ -6,7 +6,7 @@ SpecRails includes an update system that pulls new templates while preserving yo
 
 The update system uses a **manifest-based approach**:
 
-1. During installation, SpecRails generates `.specrails-manifest.json` — a checksum of every installed file
+1. During installation, SpecRails generates `.specrails/specrails-manifest.json` — a checksum of every installed file
 2. On update, it compares the manifest against current files to detect what you've customized
 3. Customized files are preserved; unchanged files are updated to the latest version
 
@@ -25,7 +25,7 @@ bash /path/to/specrails/update.sh
 ### What happens
 
 1. **Backup** — creates `.claude.specrails.backup/` with your current files
-2. **Version check** — compares installed version (`.specrails-version`) with latest
+2. **Version check** — compares installed version (`.specrails/specrails-version`) with latest
 3. **Update files** — replaces unchanged files, preserves customized ones
 4. **Merge settings** — additively merges `settings.json` (your permissions are kept)
 5. **Update version** — writes new version and manifest
@@ -66,7 +66,7 @@ bash update.sh --only all
 
 If you installed SpecRails before the versioning system (pre-v0.1.0):
 
-- The updater detects missing `.specrails-version` and treats it as a legacy install
+- The updater detects missing `.specrails/specrails-version` and treats it as a legacy install
 - It migrates your installation to the versioned system
 - A manifest is generated from your current files
 - Future updates use the standard manifest comparison
@@ -78,7 +78,7 @@ If something goes wrong, restore from the automatic backup:
 ```bash
 # Backups are at .claude.specrails.backup/
 cp -r .claude.specrails.backup/.claude .claude
-cp .claude.specrails.backup/.specrails-version .specrails-version
+cp .claude.specrails.backup/.specrails/specrails-version .specrails/specrails-version
 ```
 
 ---

package/docs/user-docs/faq.md

@@ -118,7 +118,7 @@ Then re-run `/specrails:setup` to regenerate project data with any new templates
 **How do I know which version is installed?**
 
 ```bash
-cat .specrails-version
+cat .specrails/specrails-version
 ```
 
 ---

package/docs/user-docs/getting-started-codex.md

@@ -150,7 +150,7 @@ ls .codex/skills/
 grep -r '{{[A-Z_]*}}' .codex/agents/ .codex/skills/ 2>/dev/null
 
 # Check the installed version
-cat .specrails-version
+cat .specrails/specrails-version
 ```
 
 ---

package/docs/user-docs/installation.md

@@ -88,7 +88,7 @@ your-project/
     └── config.toml               # Permissions
 ```
 
-The installer also writes `.specrails-version` and `.specrails-manifest.json` to track the installed version.
+The installer also writes `.specrails/specrails-version` and `.specrails/specrails-manifest.json` to track the installed version.
 
 ## Configure with /specrails:setup
 
@@ -131,7 +131,7 @@ ls .claude/agents/
 grep -r '{{[A-Z_]*}}' .claude/agents/ .claude/commands/ .claude/rules/
 
 # Scaffold method: check the installed version
-cat .specrails-version
+cat .specrails/specrails-version
 ```
 
 ## Troubleshooting