specrails-core 4.0.8 → 4.1.1

package/README.md

@@ -177,6 +177,68 @@ AI product discovery using your personas. Evaluates ideas, creates tickets (loca
 
 ---
 
+## Agent profiles
+
+> Available in `specrails-core >= 4.1.0`. Optional — without a profile, the pipeline behaves exactly as before.
+
+Profiles are declarative JSON files that tell `/specrails:implement` which agents to use, which models to run them with, and how to route tasks to specialists. One project can define many profiles (e.g. `default`, `data-heavy`, `security-heavy`) and run different features with different profiles — useful for concurrent rails in `/specrails:batch-implement`.
+
+### File layout
+
+```
+<project>/.specrails/
+  profiles/
+    default.json          # checked into git, team-shared
+    data-heavy.json       # checked into git, team-shared
+    .user-preferred.json  # gitignored, your personal default
+```
+
+### Resolution order
+
+When running the pipeline, the active profile is resolved in this order:
+
+1. `$SPECRAILS_PROFILE_PATH` environment variable (absolute path to a JSON snapshot)
+2. `<cwd>/.specrails/profiles/project-default.json`
+3. No profile — legacy behavior (identical to pre-4.1.0)
+
+Tools such as [specrails-hub](https://github.com/fjpulidop/specrails-hub) set `$SPECRAILS_PROFILE_PATH` to a job-scoped snapshot so concurrent rails can run independent profiles.
+
+### Schema
+
+The v1 profile schema is published at [`schemas/profile.v1.json`](./schemas/profile.v1.json). Example:
+
+```json
+{
+  "schemaVersion": 1,
+  "name": "data-heavy",
+  "description": "Data engineering rail with stricter review",
+  "orchestrator": { "model": "opus" },
+  "agents": [
+    { "id": "sr-architect",     "model": "opus",   "required": true },
+    { "id": "sr-data-engineer", "model": "sonnet" },
+    { "id": "sr-developer",     "model": "sonnet", "required": true },
+    { "id": "sr-reviewer",      "model": "opus",   "required": true }
+  ],
+  "routing": [
+    { "tags": ["etl", "schema", "data"], "agent": "sr-data-engineer" },
+    { "default": true, "agent": "sr-developer" }
+  ]
+}
+```
+
+Baseline agents (`sr-architect`, `sr-developer`, `sr-reviewer`) MUST appear in `agents[]`. The `routing` array is ordered — first rule whose `tags` intersects the task's tags wins; the terminal `default: true` rule catches everything else.
+
+### Reserved paths
+
+The following paths are **reserved** — `update.sh` will never create, modify, or delete anything inside them:
+
+- `.specrails/profiles/**` — profile JSON files (yours and hub-authored).
+- `.claude/agents/custom-*.md` — your custom agents. Use the `custom-` prefix to opt in to this protection.
+
+This contract is what lets you safely hand-author (or let specrails-hub author) profiles and custom agents without fear of the next `update` overwriting your work. Other paths managed by specrails-core (`.specrails/install-config.yaml`, `.specrails/specrails-version`, etc.) remain under `update.sh`'s control.
+
+---
+
 ## Local ticket management
 
 specrails-core ships with a built-in ticket system — no GitHub account or external tools required.

package/VERSION

@@ -1 +1 @@
-4.0.7
+4.1.1

package/bin/specrails-core.js

@@ -11,6 +11,7 @@ const COMMANDS = {
   "perf-check": "bin/perf-check.sh",
   enrich: null,
   version: null,
+  profile: null,
 };
 
 const args = process.argv.slice(2);
@@ -33,6 +34,7 @@ Usage:
   specrails-core doctor                                      Run health checks
   specrails-core perf-check [--files <list>]                 Performance regression check (CI)
   specrails-core enrich     [--from-config <path>]           Run /specrails:enrich via Claude CLI
+  specrails-core profile    <validate|show> [<path>]         Validate or pretty-print a profile JSON
   specrails-core version                                     Show installed version
 
 Flags for init:
@@ -65,6 +67,7 @@ const ALLOWED_FLAGS = {
   "perf-check": ["--files", "--context"],
   enrich: ["--from-config", "--quick"],
   version: [],
+  profile: [],
 };
 
 const subargs = args.slice(1);
@@ -85,6 +88,87 @@ if (subcommand === "version") {
   process.exit(0);
 }
 
+// ─── profile subcommand ──────────────────────────────────────────────────────
+// `specrails-core profile validate [path]`  — validate a profile JSON against v1 schema
+// `specrails-core profile show [path]`      — pretty-print the resolved profile
+// Resolution order when no path: $SPECRAILS_PROFILE_PATH → .specrails/profiles/project-default.json
+
+if (subcommand === "profile") {
+  const { existsSync, readFileSync } = require("fs");
+  const action = subargs[0];
+  const pathArg = subargs[1];
+
+  if (!action || (action !== "validate" && action !== "show")) {
+    console.error("Usage: specrails-core profile validate [<path>]");
+    console.error("       specrails-core profile show     [<path>]");
+    process.exit(1);
+  }
+
+  const resolveProfilePath = () => {
+    if (pathArg) return resolve(pathArg);
+    if (process.env.SPECRAILS_PROFILE_PATH) return resolve(process.env.SPECRAILS_PROFILE_PATH);
+    const projectDefault = resolve(process.cwd(), ".specrails/profiles/project-default.json");
+    if (existsSync(projectDefault)) return projectDefault;
+    return null;
+  };
+
+  const profilePath = resolveProfilePath();
+  if (!profilePath) {
+    console.error("No profile path given and none could be resolved.");
+    console.error("Pass an explicit path or set SPECRAILS_PROFILE_PATH, or place a profile at");
+    console.error("  .specrails/profiles/project-default.json");
+    process.exit(1);
+  }
+  if (!existsSync(profilePath)) {
+    console.error(`Profile file not found: ${profilePath}`);
+    process.exit(1);
+  }
+
+  let profile;
+  try {
+    profile = JSON.parse(readFileSync(profilePath, "utf8"));
+  } catch (e) {
+    console.error(`Profile is not valid JSON: ${e.message}`);
+    process.exit(1);
+  }
+
+  if (action === "show") {
+    console.log(JSON.stringify(profile, null, 2));
+    process.exit(0);
+  }
+
+  // action === "validate"
+  const schemaPath = resolve(ROOT, "schemas/profile.v1.json");
+  if (!existsSync(schemaPath)) {
+    console.error(`Schema not found at ${schemaPath} — install may be corrupt`);
+    process.exit(1);
+  }
+
+  let Ajv;
+  try {
+    Ajv = require("ajv/dist/2020.js").default;
+  } catch {
+    console.error("'ajv' is not installed. Run `npm install` in the specrails-core package directory first,");
+    console.error("or rely on the hub's own validator for user-facing flows.");
+    process.exit(1);
+  }
+
+  const schema = JSON.parse(readFileSync(schemaPath, "utf8"));
+  const ajv = new Ajv({ allErrors: true, strict: false });
+  const validate = ajv.compile(schema);
+
+  if (validate(profile)) {
+    console.log(`✓ ${profilePath} is a valid v1 profile.`);
+    process.exit(0);
+  } else {
+    console.error(`✗ ${profilePath} failed validation:`);
+    for (const err of validate.errors || []) {
+      console.error(`    ${err.instancePath || "/"} ${err.message} (${JSON.stringify(err.params)})`);
+    }
+    process.exit(1);
+  }
+}
+
 // ─── enrich subcommand ───────────────────────────────────────────────────────
 // Launches `claude --command "/specrails:enrich [flags]"` so the AI-powered
 // enrichment runs inside Claude Code with full model access.

package/bin/tui-installer.mjs

@@ -64,10 +64,12 @@ const CORE_AGENTS = new Set([
   'sr-merge-resolver',
 ]);
 
+// Only the CORE agents are pre-selected. Optional agents (product manager,
+// test writer, layer specialists, reviewers, utilities) are opt-in so the
+// default install is as lean as possible. Users can add optional agents via
+// `/specrails:enrich` or by re-running init.
 const DEFAULT_SELECTED = new Set([
   ...CORE_AGENTS,
-  'sr-test-writer',
-  'sr-product-manager',
 ]);
 
 // ─── Model presets ────────────────────────────────────────────────────────────
@@ -178,12 +180,35 @@ function writeDefaultConfig(specrailsDir, provider) {
 async function run() {
   const rawArgs  = process.argv.slice(2);
   const autoYes  = rawArgs.includes('--yes') || rawArgs.includes('-y');
+  const withProfiles = rawArgs.includes('--with-profiles');
   const rootArg  = rawArgs.find(a => !a.startsWith('-'));
   const inputDir = rootArg ? resolve(rootArg) : process.cwd();
   const rootDir  = detectGitRoot(inputDir);
 
   const specrailsDir = resolve(rootDir, '.specrails');
 
+  // Optional: scaffold .specrails/profiles/project-default.json from the shipped template.
+  // Off by default to keep standalone installs zero-noise.
+  if (withProfiles) {
+    try {
+      const { readFileSync, writeFileSync, existsSync, mkdirSync } = await import('node:fs');
+      const { dirname } = await import('node:path');
+      const scriptDir = new URL('..', import.meta.url).pathname;
+      const templatePath = resolve(scriptDir, 'templates/profiles/default.json');
+      const profilesDir = resolve(specrailsDir, 'profiles');
+      const targetPath = resolve(profilesDir, 'project-default.json');
+      if (existsSync(templatePath) && !existsSync(targetPath)) {
+        mkdirSync(profilesDir, { recursive: true });
+        writeFileSync(targetPath, readFileSync(templatePath));
+        console.log(`  ✓ Profile scaffolded at .specrails/profiles/project-default.json`);
+      } else if (existsSync(targetPath)) {
+        console.log(`  ↷ Profile already exists at .specrails/profiles/project-default.json — skipped`);
+      }
+    } catch (e) {
+      console.warn(`  ⚠  Could not scaffold profile: ${e.message}`);
+    }
+  }
+
   // Auto-yes: write defaults and exit (no TUI needed)
   //
   // Codex (OpenAI) support is currently being tested in our lab ("Coming Soon").
@@ -296,7 +321,8 @@ async function run() {
     message: 'Agents to install:',
     choices: buildCheckboxChoices(),
     pageSize: agentPageSize,
-    validate: (selected) => selected.length > 0 || 'Select at least one agent.',
+    // Core agents are installed unconditionally (disabled rows above), so an
+    // empty optional selection is valid — means "only core, nothing extra".
   });
 
   // Core agents are always included regardless of checkbox state

package/install.sh

@@ -4,6 +4,19 @@ set -euo pipefail
 # specrails installer
 # Installs the agent workflow system into any repository.
 # Step 1 of 2: Prerequisites + scaffold. Step 2: Run /specrails:enrich inside Claude Code.
+#
+# ─────────────────────────────────────────────────────────────────────────────
+# Reserved paths (MUST NOT be created, modified, or deleted by this script):
+#   - <repo>/.specrails/profiles/**        (project + hub-authored profile JSON)
+#   - <repo>/.claude/agents/custom-*.md    (user-authored custom agents)
+#
+# Rationale: these paths hold user/team configuration that must survive
+# re-running the installer. specrails-hub writes profile files here.
+# Audited by tests/test-profiles.sh.
+#
+# Other paths under .specrails/ (install-config.yaml, specrails-version,
+# specrails-manifest.json, setup-templates/) ARE managed by this script.
+# ─────────────────────────────────────────────────────────────────────────────
 
 # Detect pipe mode (curl | bash) vs local execution
 if [[ -z "${BASH_SOURCE[0]:-}" || "${BASH_SOURCE[0]:-}" == "bash" ]]; then

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specrails-core",
-  "version": "4.0.8",
+  "version": "4.1.1",
   "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"
@@ -13,6 +13,7 @@
     ".claude/skills/",
     "commands/",
     "docs/",
+    "schemas/",
     "VERSION"
   ],
   "engines": {
@@ -58,6 +59,9 @@
   "dependencies": {
     "@inquirer/prompts": "^7.0.0"
   },
+  "devDependencies": {
+    "ajv": "^8.18.0"
+  },
   "license": "MIT",
   "author": "fjpulidop"
 }

package/schemas/profile.v1.json

@@ -0,0 +1,145 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/fjpulidop/specrails-core/main/schemas/profile.v1.json",
+  "title": "specrails agent profile (v1)",
+  "description": "Declarative configuration for the specrails implement pipeline. Describes which agents participate, which models they run with, and how tasks are routed to specialists. Consumed by `implement.md` and produced by tools like specrails-hub.",
+  "type": "object",
+  "required": ["schemaVersion", "name", "orchestrator", "agents", "routing"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": {
+      "const": 1,
+      "description": "Profile schema version. v1 is the only supported value at this time."
+    },
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]*$",
+      "minLength": 1,
+      "maxLength": 64,
+      "description": "Human-readable identifier for this profile (kebab-case)."
+    },
+    "description": {
+      "type": "string",
+      "maxLength": 512,
+      "description": "Optional short summary of when to use this profile."
+    },
+    "orchestrator": {
+      "type": "object",
+      "required": ["model"],
+      "additionalProperties": false,
+      "properties": {
+        "model": {
+          "$ref": "#/$defs/modelAlias",
+          "description": "Model used to run the top-level implement orchestrator."
+        }
+      }
+    },
+    "agents": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/agentEntry" },
+      "description": "Ordered chain of agents that participate in the pipeline when this profile is active.",
+      "allOf": [
+        {
+          "description": "Required baseline agent: sr-architect",
+          "contains": {
+            "type": "object",
+            "properties": { "id": { "const": "sr-architect" } },
+            "required": ["id"]
+          }
+        },
+        {
+          "description": "Required baseline agent: sr-developer",
+          "contains": {
+            "type": "object",
+            "properties": { "id": { "const": "sr-developer" } },
+            "required": ["id"]
+          }
+        },
+        {
+          "description": "Required baseline agent: sr-reviewer",
+          "contains": {
+            "type": "object",
+            "properties": { "id": { "const": "sr-reviewer" } },
+            "required": ["id"]
+          }
+        }
+      ]
+    },
+    "routing": {
+      "type": "array",
+      "minItems": 1,
+      "description": "Ordered routing rules. The first rule whose `tags` intersects the task's tag set wins. Exactly one terminal entry with `default: true` MUST appear as the last element.",
+      "items": { "$ref": "#/$defs/routingRule" }
+    }
+  },
+  "$defs": {
+    "modelAlias": {
+      "type": "string",
+      "enum": ["sonnet", "opus", "haiku"],
+      "description": "Accepted model alias. Resolved to the current concrete model ID by the pipeline."
+    },
+    "agentEntry": {
+      "type": "object",
+      "required": ["id"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^(sr|custom)-[a-z0-9][a-z0-9-]*$",
+          "description": "Agent identifier. MUST correspond to a file at `.claude/agents/<id>.md`."
+        },
+        "model": {
+          "$ref": "#/$defs/modelAlias",
+          "description": "Model override for this agent when this profile is active. When omitted, the agent's frontmatter `model:` is used as a fallback."
+        },
+        "required": {
+          "type": "boolean",
+          "default": false,
+          "description": "If true, the agent cannot be routed past. Baseline agents (sr-architect, sr-developer, sr-reviewer) SHOULD be marked required."
+        }
+      }
+    },
+    "routingRule": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": ["tags", "agent"],
+          "additionalProperties": false,
+          "properties": {
+            "tags": {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "type": "string",
+                "pattern": "^[a-z0-9][a-z0-9-]*$"
+              },
+              "description": "Task tags that trigger this rule. Rule wins if any tag intersects."
+            },
+            "agent": {
+              "type": "string",
+              "pattern": "^(sr|custom)-[a-z0-9][a-z0-9-]*$",
+              "description": "Agent to route the task to when this rule wins."
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["default", "agent"],
+          "additionalProperties": false,
+          "properties": {
+            "default": {
+              "const": true,
+              "description": "Marks this rule as the terminal catch-all. Exactly one entry with `default: true` is allowed, and it MUST be the last element of `routing`."
+            },
+            "agent": {
+              "type": "string",
+              "pattern": "^(sr|custom)-[a-z0-9][a-z0-9-]*$",
+              "description": "Agent to route the task to when no earlier rule matched."
+            }
+          }
+        }
+      ]
+    }
+  }
+}

package/templates/commands/specrails/batch-implement.md

@@ -34,6 +34,7 @@ Scan `$ARGUMENTS` for control flags:
 - If `--deps "<spec>"` is present: capture the quoted string as `DEPS_SPEC`. Strip from arguments.
 - If `--concurrency N` is present: set `CONCURRENCY=N` (integer ≥ 1). Default: 3.
 - If `--wave-size N` is present: set `WAVE_SIZE=N` (integer ≥ 1). Default: unlimited (no per-wave cap).
+- If `--profiles "<spec>"` is present: parse a per-rail profile map of the form `ref=profile-name,ref=profile-name,...`. Capture as `PROFILE_MAP` and strip from arguments. Each mapped ref's `/specrails:implement` invocation will run under the named profile (the profile must exist at `.specrails/profiles/<profile-name>.json`). Unmapped refs inherit the batch-level profile resolution (see below).
 
 **If `DRY_RUN=true`**, print:
 ```
@@ -189,14 +190,18 @@ For each wave `W`:
 
 1. Print: `[wave W/TOTAL_WAVES] Starting — features: <ref-list>`
 2. For each feature batch of size ≤ `CONCURRENCY` within the wave:
+   - For every ref in the batch, determine the profile spawn env:
+     - If `PROFILE_MAP` contains an entry for this ref, set `SPECRAILS_PROFILE_PATH=<abs path to .specrails/profiles/<mapped-name>.json>` for this invocation only.
+     - Otherwise, inherit whatever `$SPECRAILS_PROFILE_PATH` was set by the caller (e.g. specrails-hub), or leave unset so the rail falls back to `.specrails/profiles/project-default.json` or legacy mode.
    - Invoke `/specrails:implement` with the feature refs and forwarded flags:
      ```
-     /specrails:implement <ref1> <ref2> ... [--dry-run]
+     SPECRAILS_PROFILE_PATH=<resolved-per-rail-path> /specrails:implement <ref> [--dry-run]
      ```
+   - Each ref in the batch spawns with its own resolved profile path — **distinct rails in the same batch MAY use distinct profiles concurrently**.
    - Run invocations in the batch in parallel (`run_in_background: true`).
    - Wait for all in the batch to complete before starting the next batch.
 3. For each completed invocation, record outcome in `WAVE_RESULTS`:
-   - `{ref, wave, status: "done" | "failed", error_summary: "..." | null}`
+   - `{ref, wave, status: "done" | "failed", profile: "<name or empty>", error_summary: "..." | null}`
 
 ### Failure isolation
 

package/templates/commands/specrails/implement.md

@@ -61,13 +61,150 @@ which openspec && openspec --version
 
 #### 5. Agent discovery
 
-Scan the agents directory to determine which agents are installed:
+Agent discovery runs in one of two modes: **profile mode** (a profile JSON is active) or **legacy mode** (no profile — identical to pre-4.1.0 behavior).
+
+##### Profile detection
+
+A profile is active when either condition holds:
+
+1. The environment variable `SPECRAILS_PROFILE_PATH` is set AND points to a readable file. Tools like `specrails-hub` set this to a job-scoped snapshot.
+2. The file `.specrails/profiles/project-default.json` exists and is readable.
+
+If condition 1 holds, use `$SPECRAILS_PROFILE_PATH` as the profile path. Otherwise, if condition 2 holds, use `.specrails/profiles/project-default.json`. Otherwise, fall through to **legacy mode**.
+
+##### Preflight: `jq` availability (profile mode only)
+
+When running in profile mode, `jq` is required to read the profile JSON. Run:
+
+```bash
+command -v jq >/dev/null 2>&1 || { echo "[error] 'jq' is required for profile-aware mode. Install with: brew install jq / apt install jq / https://stedolan.github.io/jq/"; exit 1; }
+```
+
+##### Profile mode — load, validate, populate
+
+Read the profile:
+
+```bash
+PROFILE="$(cat "$PROFILE_PATH")"
+```
+
+Validate the schema version. Only `schemaVersion: 1` is supported:
+
+```bash
+SCHEMA_VERSION="$(jq -r '.schemaVersion // empty' <<<"$PROFILE")"
+case "$SCHEMA_VERSION" in
+  1) ;;
+  "") echo "[error] profile validation failed: missing required field 'schemaVersion'"; exit 1 ;;
+  *) echo "[error] profile validation failed: unsupported schemaVersion '$SCHEMA_VERSION'. Supported: 1"; exit 1 ;;
+esac
+```
+
+Validate required top-level fields. Every valid v1 profile MUST contain `name`, `orchestrator.model`, `agents` (non-empty array), and `routing` (non-empty array):
+
+```bash
+for field in name orchestrator agents routing; do
+  jq -e ".$field" <<<"$PROFILE" >/dev/null 2>&1 || { echo "[error] profile validation failed: missing required field '$field'"; exit 1; }
+done
+jq -e '.orchestrator.model' <<<"$PROFILE" >/dev/null 2>&1 || { echo "[error] profile validation failed: missing required field 'orchestrator.model'"; exit 1; }
+jq -e '.agents | length > 0' <<<"$PROFILE" >/dev/null 2>&1 || { echo "[error] profile validation failed: 'agents' must be a non-empty array"; exit 1; }
+jq -e '.routing | length > 0' <<<"$PROFILE" >/dev/null 2>&1 || { echo "[error] profile validation failed: 'routing' must be a non-empty array"; exit 1; }
+```
+
+Validate baseline agents — `sr-architect`, `sr-developer`, and `sr-reviewer` MUST appear in `agents[]`:
+
+```bash
+for required in sr-architect sr-developer sr-reviewer; do
+  jq -e --arg id "$required" '[.agents[].id] | index($id)' <<<"$PROFILE" >/dev/null 2>&1 \
+    || { echo "[error] profile validation failed: required baseline agent '$required' missing from 'agents[]'"; exit 1; }
+done
+```
+
+Validate routing terminal rule — exactly one entry SHALL have `default: true` and it MUST be the last element:
+
+```bash
+DEFAULT_COUNT="$(jq '[.routing[] | select(.default == true)] | length' <<<"$PROFILE")"
+if [[ "$DEFAULT_COUNT" -ne 1 ]]; then
+  echo "[error] profile validation failed: routing must contain exactly one entry with 'default: true' (found $DEFAULT_COUNT)"; exit 1
+fi
+IS_LAST="$(jq '(.routing | last | .default) == true' <<<"$PROFILE")"
+if [[ "$IS_LAST" != "true" ]]; then
+  echo "[error] profile validation failed: the 'default: true' routing rule must be the last element of 'routing'"; exit 1
+fi
+```
+
+Populate `AVAILABLE_AGENTS` from the profile and verify each referenced agent file exists on disk:
+
+```bash
+AVAILABLE_AGENTS="$(jq -r '.agents[].id' <<<"$PROFILE" | sort)"
+for id in $AVAILABLE_AGENTS; do
+  [[ -f ".claude/agents/$id.md" ]] \
+    || { echo "[error] profile references agent '$id' but .claude/agents/$id.md does not exist"; exit 1; }
+done
+```
+
+Also store per-agent model overrides and the orchestrator model for use in later phases:
+
+```bash
+# ORCHESTRATOR_MODEL is informational; the caller is responsible for spawning
+# the orchestrator with this model (e.g. specrails-hub reads this field directly).
+ORCHESTRATOR_MODEL="$(jq -r '.orchestrator.model' <<<"$PROFILE")"
+
+# Per-agent model overrides keyed by agent id.
+# Consumed by subagent invocation sites in later phases.
+declare -A AGENT_MODEL
+while IFS=$'\t' read -r id model; do
+  [[ -n "$model" && "$model" != "null" ]] && AGENT_MODEL[$id]="$model"
+done < <(jq -r '.agents[] | [.id, (.model // "null")] | @tsv' <<<"$PROFILE")
+
+# Routing rules (array), consumed by Phase 3b.
+ROUTING="$(jq '.routing' <<<"$PROFILE")"
+
+PROFILE_MODE="profile"
+PROFILE_NAME="$(jq -r '.name' <<<"$PROFILE")"
+```
+
+##### Apply per-agent model overrides (profile mode only)
+
+Claude Code's Agent tool determines a subagent's model from the `model:` line in the agent's `.md` frontmatter at invocation time — there is no per-call model parameter. When a profile is active, rewrite each agent's frontmatter `model:` value in-place to match `AGENT_MODEL[$id]`.
+
+This rewrite is safe because:
+- Multi-feature runs execute in **isolated git worktrees** (`isolation: worktree`), so each rail mutates its own copy of `.claude/agents/` without cross-rail contention.
+- Single-feature runs are sequential within a single checkout.
+- The hub writes a job-scoped snapshot of the profile and spawns `claude` with `$SPECRAILS_PROFILE_PATH` pointing at it; the frontmatter rewrite follows the snapshot, never the catalog.
+
+```bash
+for id in "${!AGENT_MODEL[@]}"; do
+  model="${AGENT_MODEL[$id]}"
+  file=".claude/agents/$id.md"
+  [[ -f "$file" ]] || continue
+  # Rewrite the first `model:` line within the frontmatter block (lines between the
+  # first two `---` separators). Use sed with portable syntax (macOS + Linux).
+  awk -v new="$model" '
+    BEGIN { in_fm=0; done=0 }
+    /^---$/ { in_fm = !in_fm; print; next }
+    in_fm && !done && /^model:[[:space:]]/ { print "model: " new; done=1; next }
+    { print }
+  ' "$file" > "$file.tmp" && mv "$file.tmp" "$file"
+done
+```
+
+If a profile does not declare `model` for a given agent (the field is optional), that agent's frontmatter is left untouched.
+
+##### Legacy mode — preserve current behavior
+
+If no profile is active, scan the agents directory exactly as before:
 
 ```bash
-ls .claude/agents/sr-*.md 2>/dev/null | sed 's|.*/||;s|\.md$||' | sort
+AVAILABLE_AGENTS="$(ls .claude/agents/sr-*.md 2>/dev/null | sed 's|.*/||;s|\.md$||' | sort)"
+PROFILE_MODE="legacy"
+PROFILE_NAME=""
 ```
 
-Store the result as `AVAILABLE_AGENTS` (a list of agent IDs). The pipeline adapts dynamically to the installed agents:
+Per-agent model overrides are empty in legacy mode — subagent invocations inherit the `model:` value from each agent's `.md` frontmatter. Routing in Phase 3b uses the hardcoded legacy rules.
+
+##### Agent roles (both modes)
+
+The pipeline adapts dynamically to the installed agents:
 
 | Agent | Role | Required? | Phase(s) affected |
 |-------|------|-----------|-------------------|
@@ -88,6 +225,7 @@ Store the result as `AVAILABLE_AGENTS` (a list of agent IDs). The pipeline adapt
 **Gate rules** (applied throughout the pipeline):
 - If an optional agent is NOT in `AVAILABLE_AGENTS`, **skip** that phase/sub-step silently and note `"<agent> not installed — skipping"`.
 - Core agents are guaranteed to exist. If a core agent is missing, **STOP** and print: `[error] Core agent <name> not found. Run /specrails:enrich or reinstall.`
+- In **profile mode**, the profile's `agents[]` IS the source of truth for `AVAILABLE_AGENTS`. Agents not listed are considered unavailable regardless of what is on disk.
 
 ### Summary
 
@@ -518,7 +656,47 @@ Produce three sets: `FRONTEND_TASKS`, `BACKEND_TASKS`, `OTHER_TASKS`.
 
 **Step 2 — Route tasks to developer agents:**
 
-Evaluate available developer agents in `AVAILABLE_AGENTS` and apply these rules in priority order:
+Routing operates in one of two modes depending on the value of `PROFILE_MODE` set in Phase -1.
+
+##### Profile mode (`PROFILE_MODE=profile`)
+
+When a profile is active, apply `ROUTING` rules in their array order. For each task, collect its tag set (layer tags plus any explicit `[tag]` markers in tasks.md). The first rule whose `tags` array intersects the task's tag set wins. The terminal `default: true` rule catches tasks matched by no earlier rule.
+
+Example (pseudocode):
+
+```bash
+assigned_agent_for_task() {
+  local -a task_tags=("$@")
+  local rule_count
+  rule_count=$(jq 'length' <<<"$ROUTING")
+  local i=0
+  while [[ $i -lt $rule_count ]]; do
+    local is_default rule_tags agent
+    is_default=$(jq -r ".[$i].default // false" <<<"$ROUTING")
+    agent=$(jq -r ".[$i].agent" <<<"$ROUTING")
+    if [[ "$is_default" == "true" ]]; then
+      echo "$agent"
+      return
+    fi
+    rule_tags=$(jq -r ".[$i].tags[]" <<<"$ROUTING")
+    for rtag in $rule_tags; do
+      for ttag in "${task_tags[@]}"; do
+        if [[ "$rtag" == "$ttag" ]]; then
+          echo "$agent"
+          return
+        fi
+      done
+    done
+    i=$((i + 1))
+  done
+}
+```
+
+Produce `DEVELOPER_ROUTING` from the per-task decisions, grouping by assigned agent. An agent assigned by the profile SHALL only be used if it also appears in `AVAILABLE_AGENTS` (the profile's own `agents[]`). If the profile routes a task to an agent not present in `agents[]`, that is a profile configuration bug — **STOP** and print: `[error] profile routing references agent '<id>' which is not declared in profile.agents[]`.
+
+##### Legacy mode (`PROFILE_MODE=legacy`)
+
+When no profile is active, evaluate available developer agents in `AVAILABLE_AGENTS` and apply these hardcoded rules in priority order:
 
 | Condition | Agent(s) selected | Mode |
 |-----------|-------------------|------|
@@ -531,6 +709,14 @@ Evaluate available developer agents in `AVAILABLE_AGENTS` and apply these rules
 
 Store the result as `DEVELOPER_ROUTING`: a map of `{agent_id: [task_list]}`.
 
+##### Routing trace (both modes)
+
+After computing `DEVELOPER_ROUTING`, optionally emit a trace line to aid debugging:
+
+```
+[phase-3b] routing decision: mode=$PROFILE_MODE profile=${PROFILE_NAME:-none} agents=[list]
+```
+
 **Step 3 — Print routing decision:**
 
 ```

package/templates/profiles/default.json

@@ -0,0 +1,27 @@
+{
+  "schemaVersion": 1,
+  "name": "default",
+  "description": "Baseline profile equivalent to pre-4.1.0 legacy behavior: full chain, per-agent models matching the shipped agent frontmatters, and legacy routing rules.",
+  "orchestrator": { "model": "sonnet" },
+  "agents": [
+    { "id": "sr-product-manager",     "model": "opus" },
+    { "id": "sr-product-analyst",     "model": "haiku" },
+    { "id": "sr-architect",           "model": "sonnet", "required": true },
+    { "id": "sr-developer",           "model": "sonnet", "required": true },
+    { "id": "sr-frontend-developer",  "model": "sonnet" },
+    { "id": "sr-backend-developer",   "model": "sonnet" },
+    { "id": "sr-test-writer",         "model": "sonnet" },
+    { "id": "sr-doc-sync",            "model": "sonnet" },
+    { "id": "sr-merge-resolver",      "model": "sonnet" },
+    { "id": "sr-reviewer",            "model": "sonnet", "required": true },
+    { "id": "sr-frontend-reviewer",   "model": "sonnet" },
+    { "id": "sr-backend-reviewer",    "model": "sonnet" },
+    { "id": "sr-security-reviewer",   "model": "sonnet" },
+    { "id": "sr-performance-reviewer","model": "sonnet" }
+  ],
+  "routing": [
+    { "tags": ["frontend"],          "agent": "sr-frontend-developer" },
+    { "tags": ["backend"],           "agent": "sr-backend-developer" },
+    { "default": true,               "agent": "sr-developer" }
+  ]
+}

package/update.sh

@@ -4,6 +4,19 @@ set -euo pipefail
 # specrails updater
 # Updates an existing specrails installation in a target repository.
 # Preserves project-specific customizations (agents, personas, rules).
+#
+# ─────────────────────────────────────────────────────────────────────────────
+# Reserved paths (MUST NOT be created, modified, or deleted by this script):
+#   - <repo>/.specrails/profiles/**        (project + hub-authored profile JSON)
+#   - <repo>/.claude/agents/custom-*.md    (user-authored custom agents)
+#
+# Rationale: these paths hold user/team configuration that survives across
+# specrails-core upgrades. specrails-hub writes profile files here. Breaking
+# this contract silently destroys user work. Audited by tests/test-profiles.sh.
+#
+# Other paths under .specrails/ (install-config.yaml, specrails-version,
+# specrails-manifest.json, setup-templates/) ARE managed by this script.
+# ─────────────────────────────────────────────────────────────────────────────
 
 # Detect pipe mode (curl | bash) vs local execution
 if [[ -z "${BASH_SOURCE[0]:-}" || "${BASH_SOURCE[0]:-}" == "bash" ]]; then