npm - specrails-core - Versions diffs - 3.5.2 → 3.5.3 - Mend

specrails-core 3.5.2 → 3.5.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/commands/setup.md +76 -76
package/docs/installation.md +4 -4
package/docs/updating.md +4 -4
package/docs/user-docs/faq.md +1 -1
package/docs/user-docs/getting-started-codex.md +1 -1
package/docs/user-docs/installation.md +2 -2
package/install.sh +20 -20
package/package.json +1 -1
package/templates/commands/specrails/setup.md +76 -76
package/update.sh +44 -17

package/commands/setup.md CHANGED Viewed

@@ -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,22 +39,22 @@ 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.
@@ -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,8 +176,8 @@ 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`
+   - 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
@@ -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)
@@ -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
@@ -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>
@@ -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 CHANGED Viewed

@@ -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/updating.md CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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

package/install.sh CHANGED Viewed

@@ -143,7 +143,7 @@ generate_manifest() {
     installed_at="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
     # Write version file
-    printf '%s\n' "$version" > "$REPO_ROOT/.specrails-version"
+    printf '%s\n' "$version" > "$REPO_ROOT/.specrails/specrails-version"
     # Build artifact checksums for all files under templates/
     local artifacts_json=""
@@ -177,7 +177,7 @@ generate_manifest() {
     artifacts_json="${artifacts_json},
     \"commands/specrails/doctor.md\": \"${doctor_checksum}\""
-    cat > "$REPO_ROOT/.specrails-manifest.json" << EOF
+    cat > "$REPO_ROOT/.specrails/specrails-manifest.json" << EOF
 {
   "version": "${version}",
   "installed_at": "${installed_at}",
@@ -493,14 +493,14 @@ if [[ "$CLI_PROVIDER" == "codex" ]]; then
 else
     mkdir -p "$REPO_ROOT/$SPECRAILS_DIR/commands/specrails"
 fi
-mkdir -p "$REPO_ROOT/$SPECRAILS_DIR/setup-templates/agents"
-mkdir -p "$REPO_ROOT/$SPECRAILS_DIR/setup-templates/commands"
-mkdir -p "$REPO_ROOT/$SPECRAILS_DIR/setup-templates/skills"
-mkdir -p "$REPO_ROOT/$SPECRAILS_DIR/setup-templates/rules"
-mkdir -p "$REPO_ROOT/$SPECRAILS_DIR/setup-templates/personas"
-mkdir -p "$REPO_ROOT/$SPECRAILS_DIR/setup-templates/claude-md"
-mkdir -p "$REPO_ROOT/$SPECRAILS_DIR/setup-templates/settings"
-mkdir -p "$REPO_ROOT/$SPECRAILS_DIR/setup-templates/prompts"
+mkdir -p "$REPO_ROOT/.specrails/setup-templates/agents"
+mkdir -p "$REPO_ROOT/.specrails/setup-templates/commands"
+mkdir -p "$REPO_ROOT/.specrails/setup-templates/skills"
+mkdir -p "$REPO_ROOT/.specrails/setup-templates/rules"
+mkdir -p "$REPO_ROOT/.specrails/setup-templates/personas"
+mkdir -p "$REPO_ROOT/.specrails/setup-templates/claude-md"
+mkdir -p "$REPO_ROOT/.specrails/setup-templates/settings"
+mkdir -p "$REPO_ROOT/.specrails/setup-templates/prompts"
 mkdir -p "$REPO_ROOT/$SPECRAILS_DIR/agent-memory/explanations"
 # Copy the /specrails:setup and /specrails:doctor commands (or skills for Codex)
@@ -553,11 +553,11 @@ ok "Installed specrails doctor (bin/doctor.sh)"
 # Copy templates (includes commands, skills, agents, rules, personas, settings)
 # Use tar to exclude node_modules and package-lock.json for performance
 tar -C "$SCRIPT_DIR/templates" --exclude='node_modules' --exclude='package-lock.json' -cf - . \
-    | tar -C "$REPO_ROOT/$SPECRAILS_DIR/setup-templates/" -xf -
+    | tar -C "$REPO_ROOT/.specrails/setup-templates/" -xf -
 ok "Installed setup templates (commands + skills)"
 # Write OSS detection results for /specrails:setup
-cat > "$REPO_ROOT/$SPECRAILS_DIR/setup-templates/.oss-detection.json" << EOF
+cat > "$REPO_ROOT/.specrails/setup-templates/.oss-detection.json" << EOF
 {
   "is_oss": $IS_OSS,
   "signals": {
@@ -570,7 +570,7 @@ EOF
 ok "OSS detection results written"
 # Write provider detection results for /setup
-cat > "$REPO_ROOT/$SPECRAILS_DIR/setup-templates/.provider-detection.json" << EOF
+cat > "$REPO_ROOT/.specrails/setup-templates/.provider-detection.json" << EOF
 {
   "cli_provider": "$CLI_PROVIDER",
   "specrails_dir": "$SPECRAILS_DIR",
@@ -578,7 +578,7 @@ cat > "$REPO_ROOT/$SPECRAILS_DIR/setup-templates/.provider-detection.json" << EO
   "agent_teams": $AGENT_TEAMS
 }
 EOF
-ok "Provider detection results written ($CLI_PROVIDER → $SPECRAILS_DIR/)"
+ok "Provider detection results written ($CLI_PROVIDER → .specrails/setup-templates/)"
 # Copy security exemptions config (skip if already exists — preserve user exemptions)
 if [ ! -f "${REPO_ROOT}/$SPECRAILS_DIR/security-exemptions.yaml" ]; then
@@ -588,7 +588,7 @@ fi
 # Copy prompts
 if [ -d "$SCRIPT_DIR/prompts" ] && [ "$(ls -A "$SCRIPT_DIR/prompts" 2>/dev/null)" ]; then
-    cp -r "$SCRIPT_DIR/prompts/"* "$REPO_ROOT/$SPECRAILS_DIR/setup-templates/prompts/"
+    cp -r "$SCRIPT_DIR/prompts/"* "$REPO_ROOT/.specrails/setup-templates/prompts/"
     ok "Installed prompts"
 fi
@@ -609,8 +609,8 @@ fi
 step "Phase 3b: Writing version and manifest"
 generate_manifest
-ok "Written .specrails-version ($(cat "$REPO_ROOT/.specrails-version"))"
-ok "Written .specrails-manifest.json"
+ok "Written .specrails/specrails-version ($(cat "$REPO_ROOT/.specrails/specrails-version"))"
+ok "Written .specrails/specrails-manifest.json"
 # ─────────────────────────────────────────────
 # Phase 4: Summary & next steps
@@ -634,9 +634,9 @@ if [[ "$CLI_PROVIDER" == "codex" ]]; then
 else
     echo "    $SPECRAILS_DIR/commands/specrails/setup.md  ← The /specrails:setup command"
 fi
-echo "    $SPECRAILS_DIR/setup-templates/           ← Templates: commands + skills (temporary, removed after setup)"
-echo "    .specrails-version                       ← Installed specrails version"
-echo "    .specrails-manifest.json                 ← Artifact checksums for update detection"
+echo "    .specrails/setup-templates/              ← Templates: commands + skills (temporary, removed after setup)"
+echo "    .specrails/specrails-version             ← Installed specrails version"
+echo "    .specrails/specrails-manifest.json       ← Artifact checksums for update detection"
 echo ""
 echo -e "${BOLD}Prerequisites:${NC}"

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "specrails-core",
-  "version": "3.5.2",
+  "version": "3.5.3",
   "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/setup.md CHANGED Viewed

@@ -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,22 +39,22 @@ 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.
@@ -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,8 +176,8 @@ 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`
+   - 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
@@ -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)
@@ -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
@@ -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>
@@ -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/update.sh CHANGED Viewed

@@ -149,7 +149,7 @@ generate_manifest() {
     updated_at="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
     # Write version file
-    printf '%s\n' "$version" > "$REPO_ROOT/.specrails-version"
+    printf '%s\n' "$version" > "$REPO_ROOT/.specrails/specrails-version"
     # Build artifact checksums for all files under templates/
     local artifacts_json=""
@@ -201,7 +201,7 @@ generate_manifest() {
         done < <(find "$SCRIPT_DIR/.claude/skills" -type f -print0 | sort -z)
     fi
-    cat > "$REPO_ROOT/.specrails-manifest.json" << EOF
+    cat > "$REPO_ROOT/.specrails/specrails-manifest.json" << EOF
 {
   "version": "${version}",
   "installed_at": "${updated_at}",
@@ -223,9 +223,33 @@ if [[ -z "$REPO_ROOT" ]]; then
     exit 1
 fi
-VERSION_FILE="$REPO_ROOT/.specrails-version"
+VERSION_FILE="$REPO_ROOT/.specrails/specrails-version"
 AGENTS_DIR="$REPO_ROOT/.claude/agents"
+# Migrate old root-level metadata files to .specrails/ (path change introduced in v3.6.0)
+if [[ ! -f "$VERSION_FILE" ]] && [[ -f "$REPO_ROOT/.specrails-version" ]]; then
+    mkdir -p "$REPO_ROOT/.specrails"
+    mv "$REPO_ROOT/.specrails-version" "$REPO_ROOT/.specrails/specrails-version"
+    ok "Migrated .specrails-version → .specrails/specrails-version"
+fi
+if [[ -f "$REPO_ROOT/.specrails-manifest.json" ]]; then
+    mkdir -p "$REPO_ROOT/.specrails"
+    mv "$REPO_ROOT/.specrails-manifest.json" "$REPO_ROOT/.specrails/specrails-manifest.json"
+    ok "Migrated .specrails-manifest.json → .specrails/specrails-manifest.json"
+fi
+# Migrate old provider-specific setup-templates to .specrails/setup-templates/
+_MIGRATED_SETUP_TEMPLATES=false
+for _old_templates in "$REPO_ROOT/.claude/setup-templates" "$REPO_ROOT/.codex/setup-templates"; do
+    if [[ -d "$_old_templates" ]]; then
+        mkdir -p "$REPO_ROOT/.specrails/setup-templates"
+        cp -r "$_old_templates/." "$REPO_ROOT/.specrails/setup-templates/"
+        rm -rf "$_old_templates"
+        ok "Migrated ${_old_templates#"$REPO_ROOT/"} → .specrails/setup-templates/"
+        _MIGRATED_SETUP_TEMPLATES=true
+    fi
+done
+unset _old_templates
 # Detect installation state
 INSTALLED_VERSION=""
 IS_LEGACY=false
@@ -253,7 +277,7 @@ fi
 # Content-aware up-to-date check (skip for legacy migrations and agent-only runs)
 if [[ "$INSTALLED_VERSION" == "$AVAILABLE_VERSION" ]] && [[ "$IS_LEGACY" == false ]] && [[ "$UPDATE_COMPONENT" != "agents" ]] && [[ "$FORCE_UPDATE" == false ]]; then
     # Same version — check if any template content has actually changed
-    local_manifest="$REPO_ROOT/.specrails-manifest.json"
+    local_manifest="$REPO_ROOT/.specrails/specrails-manifest.json"
     HAS_CHANGES=false
     if [[ -f "$local_manifest" ]]; then
@@ -310,13 +334,13 @@ fi
 if [[ "$IS_LEGACY" == true ]]; then
     step "Phase 2: Legacy migration"
-    warn "No .specrails-version found — assuming v0.1.0 (pre-versioning install)"
+    warn "No .specrails/specrails-version found — assuming v0.1.0 (pre-versioning install)"
     info "Generating baseline manifest from current specrails templates..."
     generate_manifest
     # Overwrite with legacy version so the update flow sees "0.1.0 → current"
     printf '0.1.0\n' > "$VERSION_FILE"
-    ok "Written .specrails-version as 0.1.0"
-    ok "Written .specrails-manifest.json"
+    ok "Written .specrails/specrails-version as 0.1.0"
+    ok "Written .specrails/specrails-manifest.json"
 fi
 # ─────────────────────────────────────────────
@@ -348,6 +372,9 @@ ok "Backed up .claude/ to .claude.specrails.backup/ (excluding node_modules)"
 # ─────────────────────────────────────────────
 NEEDS_SETUP_UPDATE=false
+if [[ "$_MIGRATED_SETUP_TEMPLATES" == true ]]; then
+    NEEDS_SETUP_UPDATE=true
+fi
 FORCE_AGENTS=false
 do_migrate_sr_prefix() {
@@ -461,7 +488,7 @@ do_migrate_sr_prefix() {
 do_core() {
     step "Updating core artifacts (commands, skills, setup-templates)"
-    local manifest_file="$REPO_ROOT/.specrails-manifest.json"
+    local manifest_file="$REPO_ROOT/.specrails/specrails-manifest.json"
     local updated_count=0
     local added_count=0
@@ -509,7 +536,7 @@ except Exception:
         relpath="templates/${filepath#"$SCRIPT_DIR/templates/"}"
         if _file_changed "$filepath" "$relpath"; then
-            local dest="$REPO_ROOT/.claude/setup-templates/${filepath#"$SCRIPT_DIR/templates/"}"
+            local dest="$REPO_ROOT/.specrails/setup-templates/${filepath#"$SCRIPT_DIR/templates/"}"
             mkdir -p "$(dirname "$dest")"
             cp "$filepath" "$dest"
@@ -540,7 +567,7 @@ except Exception:
             relpath="prompts/${filepath#"$SCRIPT_DIR/prompts/"}"
             if _file_changed "$filepath" "$relpath"; then
-                local dest="$REPO_ROOT/.claude/setup-templates/prompts/${filepath#"$SCRIPT_DIR/prompts/"}"
+                local dest="$REPO_ROOT/.specrails/setup-templates/prompts/${filepath#"$SCRIPT_DIR/prompts/"}"
                 mkdir -p "$(dirname "$dest")"
                 cp "$filepath" "$dest"
@@ -605,10 +632,10 @@ except Exception:
 do_agents() {
     step "Checking adapted artifacts (agents, rules)"
-    local manifest_file="$REPO_ROOT/.specrails-manifest.json"
+    local manifest_file="$REPO_ROOT/.specrails/specrails-manifest.json"
     if [[ ! -f "$manifest_file" ]]; then
-        warn "No .specrails-manifest.json found — cannot detect template changes."
+        warn "No .specrails/specrails-manifest.json found — cannot detect template changes."
         warn "Run update.sh without --only to regenerate the manifest."
         return
     fi
@@ -748,8 +775,8 @@ with open(user_path, 'w') as f:
 do_stamp() {
     step "Writing version stamp and manifest"
     generate_manifest
-    ok "Updated .specrails-version to v${AVAILABLE_VERSION}"
-    ok "Updated .specrails-manifest.json"
+    ok "Updated .specrails/specrails-version to v${AVAILABLE_VERSION}"
+    ok "Updated .specrails/specrails-manifest.json"
 }
 # ─────────────────────────────────────────────
@@ -795,9 +822,9 @@ rm -rf "$BACKUP_DIR"
 ok "Backup removed"
 # Clean up setup-templates if no /specrails:setup re-run is needed
-if [[ "$NEEDS_SETUP_UPDATE" != true ]] && [[ -d "$REPO_ROOT/.claude/setup-templates" ]]; then
-    rm -rf "$REPO_ROOT/.claude/setup-templates"
-    ok "Cleaned up setup-templates (no /specrails:setup re-run needed)"
+if [[ "$NEEDS_SETUP_UPDATE" != true ]] && [[ -d "$REPO_ROOT/.specrails/setup-templates" ]]; then
+    rm -rf "$REPO_ROOT/.specrails/setup-templates"
+    ok "Cleaned up .specrails/setup-templates (no /specrails:setup re-run needed)"
 fi
 echo ""