specrails-core 3.5.3 → 3.6.0

package/docs/customization.md

@@ -54,20 +54,50 @@ Example — adding a constraint to the developer:
 
 ### Agent model selection
 
-Each agent specifies its model in YAML frontmatter:
+Agent models are controlled by `.specrails/agents.yaml`, generated automatically when you first run `/specrails:setup`.
 
 ```yaml
----
-model: sonnet
----
+# specrails agent configuration
+# Valid models: opus, sonnet, haiku
+
+defaults:
+  model: sonnet
+
+agents:
+  sr-architect:
+    model: sonnet
+  sr-product-manager:
+    model: opus
+  sr-product-analyst:
+    model: haiku
+  # ... all 14 agents listed
 ```
 
-Available models:
+**Valid models:**
 - `opus` — best for creative/strategic tasks (Product Manager)
 - `sonnet` — balanced for implementation tasks (most agents)
 - `haiku` — fast and cheap for analysis tasks (Product Analyst)
 
-Change the model by editing the frontmatter.
+**Precedence rules:**
+1. Per-agent entry in `agents:` section overrides everything
+2. `defaults.model` applies to any agent not explicitly listed
+3. Template hard-coded value is the fallback when no config exists
+
+**Applying config changes:** After editing `.specrails/agents.yaml`, run `/specrails:reconfig` to update the generated agent files without re-running the full setup wizard:
+
+```
+/specrails:reconfig
+```
+
+Output example:
+```
+Updated 1 agent(s):
+  sr-developer: sonnet → opus
+
+Unchanged (13): sr-architect, sr-reviewer, ...
+```
+
+**Important:** `/specrails:reconfig` wins over direct edits to `.claude/agents/sr-*.md`. If you edit an agent file directly, that change will be overwritten the next time you run reconfig or setup. For permanent per-agent overrides, edit `.specrails/agents.yaml` instead.
 
 ### Adding a new agent
 

package/package.json

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

@@ -0,0 +1,89 @@
+# Reconfig: Apply Agent Config to Generated Files
+
+Reads `.specrails/agents.yaml` and updates the `model:` frontmatter field in all generated `.claude/agents/sr-*.md` files to match. No full re-setup needed — only model frontmatter is changed.
+
+---
+
+## Step 1: Locate generated agents directory
+
+Determine `$SPECRAILS_DIR`:
+
+1. Read `.specrails/setup-templates/.provider-detection.json` to get `cli_provider` and `specrails_dir`.
+2. If the file does not exist, default to `cli_provider = "claude"` and `specrails_dir = ".claude"`.
+3. Set `$AGENTS_DIR = $SPECRAILS_DIR/agents`
+
+## Step 2: Read agent config
+
+Read `.specrails/agents.yaml`.
+
+If the file does not exist, stop and display:
+
+```
+No .specrails/agents.yaml found.
+
+Run /specrails:setup to generate the config file, then edit it before running /specrails:reconfig.
+```
+
+If the file exists, parse it. Validate all `model:` values — only `opus`, `sonnet`, and `haiku` are accepted. If an invalid value is found, display a warning and skip that agent:
+
+```
+Warning: unknown model "gpt-4" for sr-developer — skipping (valid values: opus, sonnet, haiku)
+```
+
+## Step 3: Resolve model for each agent
+
+For each agent file found in `$AGENTS_DIR/sr-*.md`:
+
+1. Extract the agent name from the filename (e.g., `sr-developer.md` → `sr-developer`)
+2. Resolve the target model:
+   - Check `agents.<agent-name>.model` in config (per-agent override)
+   - If not present, check `defaults.model` in config (global default)
+   - If neither is present, skip this agent
+3. Read the current `model:` value from the file's YAML frontmatter
+4. If the current model matches the target model, mark as **unchanged**
+5. If they differ, record the change: `sr-<name>: <current> → <target>`
+
+## Step 4: Apply changes
+
+For each agent with a recorded change:
+
+1. Read the file
+2. Replace the `model:` line in the YAML frontmatter with the resolved value
+3. Write the file back
+
+The `model:` line is always in the frontmatter block (between the first `---` and second `---`). Replace only that specific line — do not modify any other content.
+
+**Codex format:** If `cli_provider == "codex"`, apply the same logic to `.codex/agents/sr-*.toml` files. Replace the `model = "..."` line with the mapped Codex model:
+- `sonnet` → `codex-mini-latest`
+- `opus` → `o3`
+- `haiku` → `codex-mini-latest`
+
+## Step 5: Report results
+
+Display a summary of what changed:
+
+```
+## Reconfig complete
+
+Updated 2 agent(s):
+  sr-developer:       sonnet → opus
+  sr-product-analyst: haiku  → sonnet
+
+Unchanged (3):
+  sr-architect, sr-reviewer, sr-product-manager
+
+Skipped (1):
+  sr-custom-agent (not in config)
+```
+
+If nothing changed:
+
+```
+All agents already match .specrails/agents.yaml — nothing to update.
+```
+
+If all agents were skipped due to validation errors, display:
+
+```
+No agents updated. Fix the validation errors in .specrails/agents.yaml and retry.
+```

package/templates/commands/specrails/setup.md

@@ -61,6 +61,8 @@ Read the following files to understand the current installation state:
 
 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.
@@ -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
@@ -400,6 +407,8 @@ For each default agent (sr-architect, sr-developer, sr-reviewer, sr-product-mana
 - `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`
@@ -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
@@ -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).
 
@@ -1086,6 +1156,7 @@ For each selected command, read the template and adapt.
 - `.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"`:**
 - `.specrails/setup-templates/skills/sr-implement/SKILL.md` → `.agents/skills/sr-implement/SKILL.md`
@@ -1096,6 +1167,7 @@ For each selected command, read the template and adapt.
 - `.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