specrails-core 3.5.2 → 3.6.0

package/templates/commands/specrails/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,28 +39,30 @@ 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/backlog-config.json` if it exists — contains stored provider configuration needed for command placeholder substitution.
 
+7. Read `.specrails/agents.yaml` if it exists — contains agent model configuration. Validate all `model:` values (only `opus`, `sonnet`, `haiku` are valid). Store as `AGENTS_CONFIG` for use in Phase U4. If the file does not exist, set `AGENTS_CONFIG = null`.
+
 ### Phase U2: Quick Codebase Re-Analysis
 
 Perform the same analysis as Phase 1 of the full setup wizard, but silently — do not prompt the user and do not show the findings table. Just execute and store results internally.
@@ -82,28 +84,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 +146,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
@@ -158,10 +160,15 @@ For each agent in the "changed" list:
    - `{{KEY_FILE_PATHS}}` → important file paths detected in Phase U2
    - `{{WARNINGS}}` → read from existing `CLAUDE.md` if present
    - `{{MEMORY_PATH}}` → `$SPECRAILS_DIR/agent-memory/sr-<agent-name>/`
-3. Write the adapted agent using the format for the active provider (same dual-format rules as Phase 4.1):
+3. Resolve the agent's model using `AGENTS_CONFIG` (loaded in Phase U1, step 7):
+   - Check `AGENTS_CONFIG.agents.<agent-name>.model` (per-agent override)
+   - If not present, check `AGENTS_CONFIG.defaults.model` (global default)
+   - If `AGENTS_CONFIG` is null, use the model from the template frontmatter
+   - Replace the `model:` field in the YAML frontmatter with the resolved value before writing
+4. Write the adapted agent using the format for the active provider (same dual-format rules as Phase 4.1):
    - `cli_provider == "claude"`: write to `$SPECRAILS_DIR/agents/sr-<name>.md` (Markdown with YAML frontmatter)
    - `cli_provider == "codex"`: write to `$SPECRAILS_DIR/agents/sr-<name>.toml` (TOML format with `name`, `description`, `model`, `prompt` fields)
-4. Show: `✓ Regenerated sr-<name>`
+5. Show: `✓ Regenerated sr-<name>`
 
 After regenerating all changed agents, verify no unresolved placeholders remain:
 ```bash
@@ -176,8 +183,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 +221,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 +237,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 +305,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 +389,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,10 +403,12 @@ 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)
 
+If `.specrails/agents.yaml` exists, read it and apply model resolution (per-agent override → defaults → template value) before writing each agent file.
+
 Fill placeholders with best-effort values from the limited context available:
 - `{{PROJECT_NAME}}` → directory name or README first heading
 - `{{PROJECT_DESCRIPTION}}` → `QS_PROJECT_DESCRIPTION`
@@ -436,7 +445,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 +453,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 +461,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 +569,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 +638,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
@@ -661,6 +670,62 @@ Display each generated persona to the user:
 
 Wait for confirmation. If the user wants edits, apply them.
 
+### 2.5 Initialize agent config
+
+Check for `.specrails/agents.yaml`:
+
+1. If the file **exists**:
+   - Read it
+   - Validate all `model:` values — only `opus`, `sonnet`, and `haiku` are valid
+   - If any value is invalid, warn the user and fall back to the template default for that agent
+   - Store as `AGENTS_CONFIG` for use in Phase 4
+
+2. If the file **does not exist**:
+   - Generate it with the default model assignments matching the template hard-coded values:
+
+   ```yaml
+   # specrails agent configuration
+   # Modify model assignments and other agent settings
+   # Valid models: opus, sonnet, haiku
+
+   defaults:
+     model: sonnet
+
+   agents:
+     sr-architect:
+       model: sonnet
+     sr-developer:
+       model: sonnet
+     sr-reviewer:
+       model: sonnet
+     sr-product-manager:
+       model: opus
+     sr-product-analyst:
+       model: haiku
+     sr-test-writer:
+       model: sonnet
+     sr-security-reviewer:
+       model: sonnet
+     sr-backend-developer:
+       model: sonnet
+     sr-frontend-developer:
+       model: sonnet
+     sr-backend-reviewer:
+       model: sonnet
+     sr-frontend-reviewer:
+       model: sonnet
+     sr-doc-sync:
+       model: sonnet
+     sr-merge-resolver:
+       model: sonnet
+     sr-performance-reviewer:
+       model: sonnet
+   ```
+
+   - Write this file to `.specrails/agents.yaml`
+   - Store as `AGENTS_CONFIG` for use in Phase 4
+   - Log: "Generated `.specrails/agents.yaml` with default model assignments"
+
 ---
 
 ## Phase 3: Configuration
@@ -986,9 +1051,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 +1062,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
@@ -1037,7 +1102,12 @@ When generating each agent:
    - `{{TECH_EXPERTISE}}` → detected languages, frameworks, and test frameworks from Phase 1
    - `{{LAYER_CLAUDE_MD_PATHS}}` → comma-separated paths to per-layer rules files (e.g., `$SPECRAILS_DIR/rules/backend.md`, `$SPECRAILS_DIR/rules/frontend.md`)
    - `{{SECURITY_EXEMPTIONS_PATH}}` → `$SPECRAILS_DIR/security-exemptions.yaml`
-3. Write the final file in the format for the active provider:
+3. Resolve the agent's model using `AGENTS_CONFIG` (loaded in Phase 2.5):
+   - Check `AGENTS_CONFIG.agents.<agent-name>.model` (per-agent override)
+   - If not present, check `AGENTS_CONFIG.defaults.model` (global default)
+   - If `AGENTS_CONFIG` was not loaded (e.g., re-run without config), use the model from the template frontmatter (current behavior)
+   - Replace the `model:` field in the YAML frontmatter with the resolved value before writing
+4. Write the final file in the format for the active provider:
 
 **If `cli_provider == "claude"`:** Write as Markdown with YAML frontmatter — the template file as-is (frontmatter preserved).
 
@@ -1058,7 +1128,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 +1148,28 @@ 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`
+- `.specrails/setup-templates/commands/specrails/reconfig.md` → `.claude/commands/specrails/reconfig.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`
+- `.specrails/setup-templates/commands/specrails/reconfig.md` → `.agents/skills/sr-reconfig/SKILL.md` (wrap with YAML frontmatter)
+
+**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 +1271,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 +1286,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 +1299,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 +1340,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 +1353,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 +1399,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 +1474,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

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