gentle-pi 0.11.1 → 0.11.3

package/README.md

@@ -88,9 +88,9 @@ pi
 ## Quick start
 
 ```text
-/gentle-ai:status          Check package, SDD assets, OpenSpec, and global model config.
-/gentle-ai:doctor          Run read-only diagnostics for SDD assets, config, tools, and guards.
-/gentle-ai:sdd-preflight   Run or reuse the session SDD preflight explicitly.
+/gentle:status          Check package, SDD assets, OpenSpec, and global model config.
+/gentle:doctor          Run read-only diagnostics for SDD assets, config, tools, and guards.
+/gentle:sdd-preflight   Run or reuse the session SDD preflight explicitly.
 /sdd-init                  Create or refresh openspec/config.yaml.
 /gentle:models             Assign global model/effort routing to SDD/custom agents.
 /gentle:persona            Switch between gentleman and neutral persona modes.
@@ -100,7 +100,7 @@ pi
 Typical flow:
 
 1. Open Pi in your repo.
-2. Run `/gentle-ai:status`.
+2. Run `/gentle:status`.
 3. Run `/sdd-init` once per project, or when test/project capabilities change. This also runs the session SDD preflight.
 4. For a substantial change, ask Pi to use SDD. Natural-language requests are classified by the parent agent, not by brittle runtime regexes.
 5. Review the phase artifacts instead of trusting floating chat context.
@@ -228,7 +228,7 @@ Engram-only mode is different by design: Engram is working memory and does not m
 
 ## SDD preflight and project files
 
-`gentle-pi` does not require SDD agents to be copied into every project. The package ensures global Pi SDD assets exist under the Pi agent home and treats project-local files only as overrides/debug copies. Slash SDD flows such as `/sdd-*`, `/sdd-init`, and the explicit `/gentle-ai:sdd-preflight` command run a lazy preflight and ask for session-scoped SDD preferences. For natural-language requests, the parent agent decides whether the work should use SDD and must run/reuse `/gentle-ai:sdd-preflight` before continuing.
+`gentle-pi` does not require SDD agents to be copied into every project. The package ensures global Pi SDD assets exist under the Pi agent home and treats project-local files only as overrides/debug copies. Slash SDD flows such as `/sdd-*`, `/sdd-init`, and the explicit `/gentle:sdd-preflight` command run a lazy preflight and ask for session-scoped SDD preferences. For natural-language requests, the parent agent decides whether the work should use SDD and must run/reuse `/gentle:sdd-preflight` before continuing.
 
 ```text
 ~/.pi/agent/agents/sdd-*.md
@@ -246,13 +246,12 @@ The preflight choices are reused for later SDD flows in the same session:
 It does **not** overwrite existing global assets unless you explicitly run:
 
 ```text
-/gentle-ai:install-sdd --force
+/gentle:install-sdd --force
 ```
 
-Manual preflight commands:
+Manual preflight command:
 
 ```text
-/gentle-ai:sdd-preflight
 /gentle:sdd-preflight
 ```
 
@@ -356,10 +355,12 @@ A project can still override the global default with:
 
 The modal discovers:
 
-- project agents in `.pi/agents/` and `.agents/`;
-- user agents in `~/.pi/agent/agents/` and `~/.agents/`;
+- project agents in `.pi/subagents/`, `.pi/agents/`, and `.agents/`;
+- user agents in `~/.pi/agent/subagents/`, `~/.pi/agent/agents/`, and `~/.agents/`;
 - built-in agents from `pi-subagents-j0k3r` when present.
 
+When applying routing, project agents write runtime profiles to `.pi/subagents.json`; global and built-in agents write profiles to `~/.pi/agent/subagents.json`.
+
 Recommended model/effort shape:
 
 | Agent kind                 | Recommended model                                    | Recommended effort (`thinking`) |
@@ -400,8 +401,8 @@ Legacy string entries are still accepted and treated as `model`-only config.
 
 | Command                          | What it does                                                        |
 | -------------------------------- | ------------------------------------------------------------------- |
-| `/gentle-ai:status`              | Shows package, SDD asset, OpenSpec, and global model config status. |
-| `/gentle-ai:doctor`              | Runs read-only diagnostics for SDD assets, model/persona config, memory tools, and safety guards. |
+| `/gentle:status`              | Shows package, SDD asset, OpenSpec, and global model config status. |
+| `/gentle:doctor`              | Runs read-only diagnostics for SDD assets, model/persona config, memory tools, and safety guards. |
 | `/gentle:models`                 | Opens global model + effort assignment UI. Press `x` to export and `r` to restore saved routing. |
 | `/gentle:persona`                | Switches global persona mode, with project override support.        |
 | `/gentle:banner`                 | Configures startup banner rose, text logo, and color preset.        |
@@ -409,14 +410,14 @@ Legacy string entries are still accepted and treated as `model`-only config.
 | `/gentle:toggle-text-logo`       | Toggles the startup text logo.                                      |
 | `/gentle:banner-color`           | Selects a startup banner color preset.                              |
 | `/sdd-init`                      | Initializes or refreshes `openspec/config.yaml`.                    |
-| `/gentle-ai:install-sdd`         | Repairs missing global SDD runtime assets without overwriting files. |
-| `/gentle-ai:install-sdd --force` | Force-refreshes installed global SDD assets.                         |
+| `/gentle:install-sdd`         | Repairs missing global SDD runtime assets without overwriting files. |
+| `/gentle:install-sdd --force` | Force-refreshes installed global SDD assets.                         |
 | `/skill-registry:refresh`        | Regenerates `.atl/skill-registry.md`.                               |
 | `/skill-creation`                | Creates or updates an LLM-first skill using the packaged `skill-creator` contract and style guide. |
 
 Package-owned global SDD runtime assets are also refreshed automatically on session start when `gentle-pi` changes. Project-local `.pi/agents` and `.pi/chains` remain manual overrides and are never overwritten by startup refresh.
 
-Startup banner settings are global and default to the current pink rose + text logo. Supported color presets are `pink`, `cyan`, `yellow`, and `green`. The `/gentle-ai:*` aliases are also available for every banner command.
+Startup banner settings are global and default to the current pink rose + text logo. Supported color presets are `pink`, `cyan`, `yellow`, and `green`.
 
 Startup flag:
 
@@ -426,19 +427,6 @@ pi --no-skill-registry
 
 Use it when you want skills available normally but do not want Gentle AI to refresh/watch `.atl/skill-registry.md` on startup. `pi -ns` / `pi --no-skills` also skip the registry startup work because Pi is already disabling skill loading.
 
-Compatibility aliases:
-
-```text
-/gentle-ai:models
-/gentleman:models
-/gentle-ai:persona
-/gentleman:persona
-/gentle-ai:banner
-/gentle-ai:toggle-rose
-/gentle-ai:toggle-text-logo
-/gentle-ai:banner-color
-```
-
 ## Included skills
 
 - `gentle-ai` — harness discipline for controlled Pi work.

package/assets/sdd-orchestrator-workflow.md

@@ -55,14 +55,14 @@ Do not guess the active change. If change selection is ambiguous, ask the user a
 
 ## Lazy SDD Preflight
 
-Do not ask SDD setup questions on session start. The first time the user initiates an SDD process in a Pi session, run the SDD preflight once and keep those choices for the rest of that session. Runtime trigger detection is intentionally deterministic: slash SDD flows and `/sdd-init` run preflight automatically; for natural-language requests, the parent/orchestrator decides semantically whether SDD is needed and must run/reuse `/gentle-ai:sdd-preflight` before continuing.
+Do not ask SDD setup questions on session start. The first time the user initiates an SDD process in a Pi session, run the SDD preflight once and keep those choices for the rest of that session. Runtime trigger detection is intentionally deterministic: slash SDD flows and `/sdd-init` run preflight automatically; for natural-language requests, the parent/orchestrator decides semantically whether SDD is needed and must run/reuse `/gentle:sdd-preflight` before continuing.
 
 **Hard gate:** `openspec/config.yaml`, existing SDD changes, installed `.pi`/global SDD assets, or a todo named "preflight" are not session preflight. They are project context only. Do not mark SDD preflight complete, start `sdd-init`, launch SDD subagents/chains, or move to explore/proposal/spec/design/tasks until this session has either:
 
 1. an injected `## SDD Session Preflight` block, or
 2. an explicit user answer in the current conversation covering all four preflight choices below.
 
-If neither exists and `/gentle-ai:sdd-preflight` cannot be invoked from the current context, ask the four choices manually with `ask_user_question` before any SDD phase work. Treat missing Engram availability as a reason to ask/confirm artifact store, not as permission to assume defaults.
+If neither exists and `/gentle:sdd-preflight` cannot be invoked from the current context, ask the four choices manually with `ask_user_question` before any SDD phase work. Treat missing Engram availability as a reason to ask/confirm artifact store, not as permission to assume defaults.
 
 The preflight captures:
 
@@ -78,7 +78,7 @@ The package should ensure SDD assets are present as global Pi runtime assets wit
 ~/.pi/agent/chains/sdd-*.chain.md
 ```
 
-Manual install commands are recovery/debug paths, not the happy path. `/gentle-ai:sdd-preflight` and `/gentle:sdd-preflight` are the explicit preflight commands for agent/orchestrator use. If the user explicitly changes SDD preferences later in the same session, follow the new instruction.
+Manual install commands are recovery/debug paths, not the happy path. `/gentle:sdd-preflight` is the explicit preflight command for agent/orchestrator use. If the user explicitly changes SDD preferences later in the same session, follow the new instruction.
 
 ## Init Guard
 
@@ -132,6 +132,28 @@ skill_resolution
 
 The parent should synthesize these envelopes, not paste long raw reports unless needed.
 
+## Automatic Mode Gatekeeper
+
+In `auto` execution mode, the parent/orchestrator is the quality gate between SDD phases. After a delegated phase returns and before launching the next phase, validate that the phase actually reached its objective. This validation is autonomous: do not ask the user on the happy path, but stop and report if the gate catches a real problem.
+
+Check every phase result against the Result Contract:
+
+- **Contract conformance:** the phase returned `status`, `executive_summary`, `artifacts`, `next_recommended`, `risks`, and `skill_resolution`, and `status` indicates success rather than partial, failed, or blocked.
+- **Artifact existence:** every declared artifact exists and is readable in the active backend. For memory-backed flows, retrieve the topic with the available memory tools; for OpenSpec/file-backed flows, read the declared path. A successful phase with no retrievable artifact fails the gate.
+- **No hallucinated references:** spot-check concrete file paths, symbols, commands, and artifacts the phase claims it created or used. Referenced paths or artifacts that do not resolve fail the gate.
+- **No scope drift:** the output must stay consistent with its inputs and the dependency graph: spec stays within proposal scope, design answers the proposal, tasks cover spec and design, apply implements the tasks, verify checks the implementation against the spec, and sync reflects the verified state before archive.
+- **Routing coherence:** `next_recommended` must follow the SDD dependency graph, and no unaddressed critical risk may be carried silently into the next phase.
+
+Use cost-aware validation:
+
+- For lower-risk phases (`sdd-explore`, `sdd-spec`, `sdd-tasks`, `sdd-sync`, `sdd-archive`), the parent may validate inline by reading artifacts back and checking claims.
+- For higher-risk phases (`sdd-design`, `sdd-apply`), run fresh-context validation/review before continuing because errors there compound downstream.
+- If an inline gate finds any smell — missing artifact, status mismatch, unresolved path, likely drift, or critical risk — escalate to fresh-context validation before deciding.
+
+On gate pass, continue automatically to the next phase. On gate fail, rerun the same phase exactly once with corrective feedback naming the specific failures. Validate the rerun. If it fails again, stop the automatic chain and report the phase, failures from both attempts, and the recommended fix. Never advance to dependent phases on a failed gate.
+
+The gatekeeper is additive: it does not relax the Review Workload Guard, Strict TDD Forwarding, native status dependency checks, or mandatory delegation/review rules.
+
 ## SDD Phase Delegation Mode
 
 Launch SDD phase subagents with `subagent_run` `mode: "task"` when the parent needs the phase result to route the next step. Do not use `mode: "background"` for SDD phases that must feed continuation; background completion is a notification/history mechanism, not an orchestration resume guarantee.

package/extensions/gentle-ai.ts

@@ -1004,14 +1004,16 @@ async function listBuiltinAgentNamesAsync(cwd: string): Promise<Set<string>> {
 }
 
 function listDiscoverableAgents(cwd: string): AgentEntry[] {
-	const globalAgentDir = join(gentlePiAgentHome(), "agents");
+	const globalAgentHome = gentlePiAgentHome();
 	const builtinDirs = builtinAgentDirs(cwd);
 	const agents = [
 		...builtinDirs.flatMap((dir) => listAgentsFromDir(dir, "builtin")),
-		...listAgentsFromDir(globalAgentDir, "user"),
+		...listAgentsFromDir(join(globalAgentHome, "agents"), "user"),
+		...listAgentsFromDir(join(globalAgentHome, "subagents"), "user"),
 		...listAgentsFromDir(join(homedir(), ".agents"), "user"),
 		...listAgentsFromDir(join(cwd, ".agents"), "project"),
 		...listAgentsFromDir(join(cwd, ".pi", "agents"), "project"),
+		...listAgentsFromDir(join(cwd, ".pi", "subagents"), "project"),
 	];
 	const byName = new Map<string, AgentEntry>();
 	for (const agent of agents) byName.set(agent.name, agent);
@@ -1019,17 +1021,19 @@ function listDiscoverableAgents(cwd: string): AgentEntry[] {
 }
 
 async function listDiscoverableAgentsAsync(cwd: string): Promise<AgentEntry[]> {
-	const globalAgentDir = join(gentlePiAgentHome(), "agents");
+	const globalAgentHome = gentlePiAgentHome();
 	const builtinDirs = builtinAgentDirs(cwd);
 	const agents: AgentEntry[] = [];
 	for (const dir of builtinDirs) {
 		agents.push(...(await listAgentsFromDirAsync(dir, "builtin")));
 	}
 	const otherDirs: Array<[string, AgentSource]> = [
-		[globalAgentDir, "user"],
+		[join(globalAgentHome, "agents"), "user"],
+		[join(globalAgentHome, "subagents"), "user"],
 		[join(homedir(), ".agents"), "user"],
 		[join(cwd, ".agents"), "project"],
 		[join(cwd, ".pi", "agents"), "project"],
+		[join(cwd, ".pi", "subagents"), "project"],
 	];
 	for (const [dir, source] of otherDirs) {
 		agents.push(...(await listAgentsFromDirAsync(dir, source)));
@@ -1049,92 +1053,179 @@ function orderDiscoverableAgents(agents: AgentEntry[]): AgentEntry[] {
 	return [...coreFirst, ...rest];
 }
 
-function projectSettingsPath(cwd: string): string {
-	return join(cwd, ".pi", "settings.json");
-}
-
 function isClearRoutingEntry(entry: AgentRoutingEntry): boolean {
 	return entry.model === undefined && entry.thinking === undefined;
 }
 
-function updateBuiltinModelOverride(
-	cwd: string,
+function agentModelProfileConfigPath(cwd: string, source: AgentSource): string {
+	return source === "project"
+		? join(cwd, ".pi", "subagents.json")
+		: join(gentlePiAgentHome(), "subagents.json");
+}
+
+function modelProfileForRoutingEntry(
+	entry: AgentRoutingEntry | undefined,
+): Record<string, string> | undefined {
+	if (!entry || isClearRoutingEntry(entry)) return undefined;
+	const profile: Record<string, string> = {};
+	if (entry.model) profile.model = entry.model;
+	if (entry.thinking) profile.effort = entry.thinking;
+	return Object.keys(profile).length > 0 ? profile : undefined;
+}
+
+function updateSubagentModelProfileAtPath(
+	path: string,
 	name: string,
 	entry: AgentRoutingEntry | undefined,
+	options: { preserveExisting?: boolean } = {},
 ): boolean {
-	const path = projectSettingsPath(cwd);
-	let settings: Record<string, unknown> = {};
+	let config: Record<string, unknown> = {};
 	if (existsSync(path)) {
 		try {
 			const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
-			if (isRecord(parsed)) settings = parsed;
+			if (isRecord(parsed)) config = { ...parsed };
 		} catch {
-			settings = {};
+			config = {};
 		}
 	}
-	const subagents = isRecord(settings.subagents)
-		? { ...settings.subagents }
-		: {};
-	const agentOverrides = isRecord(subagents.agentOverrides)
-		? { ...subagents.agentOverrides }
-		: {};
-	const current = isRecord(agentOverrides[name])
-		? { ...agentOverrides[name] }
+	const modelProfiles = isRecord(config.model_profiles)
+		? { ...config.model_profiles }
 		: {};
-	if (entry?.model === undefined) delete current.model;
-	else current.model = entry.model;
-	if (entry?.thinking === undefined) delete current.thinking;
-	else current.thinking = entry.thinking;
-	if (Object.keys(current).length > 0) agentOverrides[name] = current;
-	else delete agentOverrides[name];
-	if (Object.keys(agentOverrides).length > 0)
-		subagents.agentOverrides = agentOverrides;
-	else delete subagents.agentOverrides;
-	if (Object.keys(subagents).length > 0) settings.subagents = subagents;
-	else delete settings.subagents;
+	const profile = modelProfileForRoutingEntry(entry);
+	if (profile) {
+		if (options.preserveExisting && isRecord(modelProfiles[name])) return false;
+		modelProfiles[name] = profile;
+	} else delete modelProfiles[name];
+	if (Object.keys(modelProfiles).length > 0) config.model_profiles = modelProfiles;
+	else delete config.model_profiles;
 	mkdirSync(dirname(path), { recursive: true });
-	writeFileSync(path, `${JSON.stringify(settings, null, "\t")}\n`);
+	writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`);
 	return true;
 }
 
-async function updateBuiltinModelOverrideAsync(
-	cwd: string,
+async function updateSubagentModelProfileAtPathAsync(
+	path: string,
 	name: string,
 	entry: AgentRoutingEntry | undefined,
+	options: { preserveExisting?: boolean } = {},
 ): Promise<boolean> {
-	const path = projectSettingsPath(cwd);
-	let settings: Record<string, unknown> = {};
+	let config: Record<string, unknown> = {};
 	if (await pathExists(path)) {
 		try {
 			const parsed: unknown = JSON.parse(await readFile(path, "utf8"));
-			if (isRecord(parsed)) settings = parsed;
+			if (isRecord(parsed)) config = { ...parsed };
 		} catch {
-			settings = {};
+			config = {};
 		}
 	}
+	const modelProfiles = isRecord(config.model_profiles)
+		? { ...config.model_profiles }
+		: {};
+	const profile = modelProfileForRoutingEntry(entry);
+	if (profile) {
+		if (options.preserveExisting && isRecord(modelProfiles[name])) return false;
+		modelProfiles[name] = profile;
+	} else delete modelProfiles[name];
+	if (Object.keys(modelProfiles).length > 0) config.model_profiles = modelProfiles;
+	else delete config.model_profiles;
+	await mkdir(dirname(path), { recursive: true });
+	await writeFile(path, `${JSON.stringify(config, null, 2)}\n`);
+	return true;
+}
+
+function updateSubagentModelProfile(
+	cwd: string,
+	source: AgentSource,
+	name: string,
+	entry: AgentRoutingEntry | undefined,
+	options: { preserveExisting?: boolean } = {},
+): boolean {
+	return updateSubagentModelProfileAtPath(
+		agentModelProfileConfigPath(cwd, source),
+		name,
+		entry,
+		options,
+	);
+}
+
+function projectSettingsPath(cwd: string): string {
+	return join(cwd, ".pi", "settings.json");
+}
+
+function removeLegacyAgentOverridesFromSettings(
+	settingsPath: string,
+	settings: Record<string, unknown>,
+): void {
 	const subagents = isRecord(settings.subagents)
 		? { ...settings.subagents }
-		: {};
-	const agentOverrides = isRecord(subagents.agentOverrides)
-		? { ...subagents.agentOverrides }
-		: {};
-	const current = isRecord(agentOverrides[name])
-		? { ...agentOverrides[name] }
-		: {};
-	if (entry?.model === undefined) delete current.model;
-	else current.model = entry.model;
-	if (entry?.thinking === undefined) delete current.thinking;
-	else current.thinking = entry.thinking;
-	if (Object.keys(current).length > 0) agentOverrides[name] = current;
-	else delete agentOverrides[name];
-	if (Object.keys(agentOverrides).length > 0)
-		subagents.agentOverrides = agentOverrides;
-	else delete subagents.agentOverrides;
+		: undefined;
+	if (!subagents) return;
+	delete subagents.agentOverrides;
 	if (Object.keys(subagents).length > 0) settings.subagents = subagents;
 	else delete settings.subagents;
-	await mkdir(dirname(path), { recursive: true });
-	await writeFile(path, `${JSON.stringify(settings, null, "\t")}\n`);
-	return true;
+	mkdirSync(dirname(settingsPath), { recursive: true });
+	writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+}
+
+function isValidJsonObjectFileOrMissing(path: string): boolean {
+	if (!existsSync(path)) return true;
+	try {
+		return isRecord(JSON.parse(readFileSync(path, "utf8")));
+	} catch {
+		return false;
+	}
+}
+
+function migrateLegacyProjectModelOverrides(cwd: string): number {
+	const settingsPath = projectSettingsPath(cwd);
+	if (!existsSync(settingsPath)) return 0;
+	let settings: Record<string, unknown>;
+	try {
+		const parsed: unknown = JSON.parse(readFileSync(settingsPath, "utf8"));
+		if (!isRecord(parsed)) return 0;
+		settings = { ...parsed };
+	} catch {
+		return 0;
+	}
+	const subagents = isRecord(settings.subagents) ? settings.subagents : undefined;
+	const agentOverrides = isRecord(subagents?.agentOverrides)
+		? subagents.agentOverrides
+		: undefined;
+	if (!agentOverrides) return 0;
+	const agentsByName = new Map(listDiscoverableAgents(cwd).map((agent) => [agent.name, agent]));
+	const migratableEntries = Object.entries(agentOverrides)
+		.map(([name, value]) => ({ name, entry: normalizeRoutingEntry(value) }))
+		.filter((item): item is { name: string; entry: AgentRoutingEntry } =>
+			item.entry !== undefined && !isClearRoutingEntry(item.entry),
+		);
+	const targetPaths = new Set(
+		migratableEntries.map(({ name }) =>
+			agentModelProfileConfigPath(cwd, agentsByName.get(name)?.source ?? "project"),
+		),
+	);
+	if (![...targetPaths].every(isValidJsonObjectFileOrMissing)) return 0;
+	let migrated = 0;
+	for (const { name, entry } of migratableEntries) {
+		const source = agentsByName.get(name)?.source ?? "project";
+		if (updateSubagentModelProfile(cwd, source, name, entry, { preserveExisting: true })) migrated += 1;
+	}
+	removeLegacyAgentOverridesFromSettings(settingsPath, settings);
+	return migrated;
+}
+
+async function updateSubagentModelProfileAsync(
+	cwd: string,
+	source: AgentSource,
+	name: string,
+	entry: AgentRoutingEntry | undefined,
+	options: { preserveExisting?: boolean } = {},
+): Promise<boolean> {
+	return updateSubagentModelProfileAtPathAsync(
+		agentModelProfileConfigPath(cwd, source),
+		name,
+		entry,
+		options,
+	);
 }
 
 export function applyModelConfig(
@@ -1143,28 +1234,17 @@ export function applyModelConfig(
 ): { updated: number; skipped: number } {
 	let updated = 0;
 	let skipped = 0;
-	const builtinNames = listBuiltinAgentNames(cwd);
 	const seenAgents = new Set<string>();
 	for (const agent of listDiscoverableAgents(cwd)) {
 		seenAgents.add(agent.name);
 		const entry = config[agent.name];
-		if (agent.source === "builtin") {
-			if (entry === undefined) {
-				skipped += 1;
-				continue;
-			}
-			if (updateBuiltinModelOverride(cwd, agent.name, entry)) updated += 1;
-			else skipped += 1;
-			continue;
-		}
 		if (entry === undefined) {
 			skipped += 1;
 			continue;
 		}
-		if (builtinNames.has(agent.name) || isClearRoutingEntry(entry)) {
-			if (updateBuiltinModelOverride(cwd, agent.name, entry)) updated += 1;
-			else skipped += 1;
-		}
+		if (updateSubagentModelProfile(cwd, agent.source, agent.name, entry)) updated += 1;
+		else skipped += 1;
+		if (agent.source === "builtin") continue;
 		if (!agent.filePath || !existsSync(agent.filePath)) {
 			skipped += 1;
 			continue;
@@ -1180,7 +1260,7 @@ export function applyModelConfig(
 	}
 	for (const [name, entry] of Object.entries(config)) {
 		if (!seenAgents.has(name) && isClearRoutingEntry(entry)) {
-			if (updateBuiltinModelOverride(cwd, name, entry)) updated += 1;
+			if (updateSubagentModelProfile(cwd, "user", name, entry)) updated += 1;
 			else skipped += 1;
 		}
 	}
@@ -1193,30 +1273,18 @@ export async function applyModelConfigAsync(
 ): Promise<{ updated: number; skipped: number }> {
 	let updated = 0;
 	let skipped = 0;
-	const builtinNames = await listBuiltinAgentNamesAsync(cwd);
 	const seenAgents = new Set<string>();
 	for (const agent of await listDiscoverableAgentsAsync(cwd)) {
 		seenAgents.add(agent.name);
 		const entry = config[agent.name];
-		if (agent.source === "builtin") {
-			if (entry === undefined) {
-				skipped += 1;
-				continue;
-			}
-			if (await updateBuiltinModelOverrideAsync(cwd, agent.name, entry))
-				updated += 1;
-			else skipped += 1;
-			continue;
-		}
 		if (entry === undefined) {
 			skipped += 1;
 			continue;
 		}
-		if (builtinNames.has(agent.name) || isClearRoutingEntry(entry)) {
-			if (await updateBuiltinModelOverrideAsync(cwd, agent.name, entry))
-				updated += 1;
-			else skipped += 1;
-		}
+		if (await updateSubagentModelProfileAsync(cwd, agent.source, agent.name, entry))
+			updated += 1;
+		else skipped += 1;
+		if (agent.source === "builtin") continue;
 		if (!agent.filePath || !(await pathExists(agent.filePath))) {
 			skipped += 1;
 			continue;
@@ -1232,7 +1300,7 @@ export async function applyModelConfigAsync(
 	}
 	for (const [name, entry] of Object.entries(config)) {
 		if (!seenAgents.has(name) && isClearRoutingEntry(entry)) {
-			if (await updateBuiltinModelOverrideAsync(cwd, name, entry))
+			if (await updateSubagentModelProfileAsync(cwd, "user", name, entry))
 				updated += 1;
 			else skipped += 1;
 		}
@@ -1785,6 +1853,7 @@ async function showSddModelPanel(
 }
 
 async function handleModelsCommand(ctx: ExtensionContext): Promise<void> {
+	migrateLegacyProjectModelOverrides(ctx.cwd);
 	const savedConfig = await readSavedModelConfigAsync(ctx.cwd);
 	if (savedConfig.status === "invalid") {
 		ctx.ui.notify(
@@ -2078,6 +2147,7 @@ export default function gentleAi(pi: ExtensionAPI): void {
 	pi.on("session_start", async (_event, ctx) => {
 		try {
 			const installResult = installSddAssets(ctx.cwd, true);
+			migrateLegacyProjectModelOverrides(ctx.cwd);
 			const modelResult = await applySavedModelConfig(ctx);
 			if (ctx.hasUI && modelResult.invalidPath) {
 				ctx.ui.notify(
@@ -2153,7 +2223,7 @@ export default function gentleAi(pi: ExtensionAPI): void {
 		return confirmCommand(event.input.command, ctx);
 	});
 
-	pi.registerCommand("gentle-ai:install-sdd", {
+	pi.registerCommand("gentle:install-sdd", {
 		description:
 			"Repair or refresh global Gentle AI SDD subagent and chain assets.",
 		handler: async (args, ctx) => {
@@ -2166,7 +2236,7 @@ export default function gentleAi(pi: ExtensionAPI): void {
 		},
 	});
 
-	pi.registerCommand("gentle-ai:sdd-preflight", {
+	pi.registerCommand("gentle:sdd-preflight", {
 		description:
 			"Run or reuse the lazy SDD preflight for this Pi session.",
 		handler: async (_args, ctx) => {
@@ -2174,13 +2244,6 @@ export default function gentleAi(pi: ExtensionAPI): void {
 		},
 	});
 
-	pi.registerCommand("gentle:sdd-preflight", {
-		description: "Compatibility alias for /gentle-ai:sdd-preflight.",
-		handler: async (_args, ctx) => {
-			await runSddPreflight(ctx);
-		},
-	});
-
 	const handleSddStatusCommand = (args: string, ctx: ExtensionContext) => {
 		const parsed = parseSddStatusCommandArgs(args);
 		const status = resolveSddStatus({
@@ -2202,13 +2265,6 @@ export default function gentleAi(pi: ExtensionAPI): void {
 		},
 	});
 
-	pi.registerCommand("gentle-ai:sdd-status", {
-		description: "Compatibility alias for /sdd-status.",
-		handler: async (args, ctx) => {
-			handleSddStatusCommand(args, ctx);
-		},
-	});
-
 	const handleSddContinueCommand = (args: string, ctx: ExtensionContext) => {
 		const parsed = parseSddStatusCommandArgs(args);
 		const status = resolveSddStatus({
@@ -2230,13 +2286,6 @@ export default function gentleAi(pi: ExtensionAPI): void {
 		},
 	});
 
-	pi.registerCommand("gentle-ai:sdd-continue", {
-		description: "Compatibility alias for /sdd-continue.",
-		handler: async (args, ctx) => {
-			handleSddContinueCommand(args, ctx);
-		},
-	});
-
 	pi.registerCommand("gentle:models", {
 		description: "Configure global per-agent models for el Gentleman.",
 		handler: async (_args, ctx) => {
@@ -2244,20 +2293,6 @@ export default function gentleAi(pi: ExtensionAPI): void {
 		},
 	});
 
-	pi.registerCommand("gentle-ai:models", {
-		description: "Compatibility alias for /gentle:models.",
-		handler: async (_args, ctx) => {
-			await handleModelsCommand(ctx);
-		},
-	});
-
-	pi.registerCommand("gentleman:models", {
-		description: "Compatibility alias for /gentle:models.",
-		handler: async (_args, ctx) => {
-			await handleModelsCommand(ctx);
-		},
-	});
-
 	pi.registerCommand("gentle:persona", {
 		description: "Switch el Gentleman persona between gentleman and neutral.",
 		handler: async (_args, ctx) => {
@@ -2265,21 +2300,7 @@ export default function gentleAi(pi: ExtensionAPI): void {
 		},
 	});
 
-	pi.registerCommand("gentle-ai:persona", {
-		description: "Compatibility alias for /gentle:persona.",
-		handler: async (_args, ctx) => {
-			await handlePersonaCommand(ctx);
-		},
-	});
-
-	pi.registerCommand("gentleman:persona", {
-		description: "Compatibility alias for /gentle:persona.",
-		handler: async (_args, ctx) => {
-			await handlePersonaCommand(ctx);
-		},
-	});
-
-	pi.registerCommand("gentle-ai:doctor", {
+	pi.registerCommand("gentle:doctor", {
 		description: "Run read-only Gentle AI diagnostics for this Pi workspace.",
 		handler: async (_args, ctx) => {
 			const agentsInstalled = existsSync(
@@ -2311,7 +2332,7 @@ export default function gentleAi(pi: ExtensionAPI): void {
 				`${engramActive ? "pass" : "warn"}: Engram memory tools ${engramActive ? "active" : "not active in this session"}`,
 			];
 			if (!agentsInstalled || !chainsInstalled) {
-				lines.push("remedy: run /gentle-ai:install-sdd --force to refresh global SDD assets intentionally");
+				lines.push("remedy: run /gentle:install-sdd --force to refresh global SDD assets intentionally");
 			}
 			if (modelConfig.status === "invalid") {
 				lines.push(`remedy: fix or remove ${modelConfig.path}`);
@@ -2326,7 +2347,7 @@ export default function gentleAi(pi: ExtensionAPI): void {
 		},
 	});
 
-	pi.registerCommand("gentle-ai:status", {
+	pi.registerCommand("gentle:status", {
 		description: "Show Gentle AI package status for this project.",
 		handler: async (_args, ctx) => {
 			const agentsInstalled = existsSync(
@@ -2349,7 +2370,7 @@ export default function gentleAi(pi: ExtensionAPI): void {
 					`Global SDD chains: ${chainsInstalled ? "installed" : "not installed"}`,
 					`Global SDD assets stale: ${staleSddAssets} file(s)${
 						staleSddAssets > 0
-							? " — run /gentle-ai:install-sdd --force to refresh intentionally"
+							? " — run /gentle:install-sdd --force to refresh intentionally"
 							: ""
 					}`,
 					`Project-local SDD agent overrides: ${localSddAgentOverrides} file(s)${

package/extensions/startup-banner.ts

@@ -585,12 +585,10 @@ export default function (pi: ExtensionAPI) {
       },
     });
   };
-  for (const prefix of ["gentle", "gentle-ai"] as const) {
-    registerBannerCommand(`${prefix}:banner`);
-    registerToggleCommand(`${prefix}:toggle-rose`, "showRose");
-    registerToggleCommand(`${prefix}:toggle-text-logo`, "showTextLogo");
-    registerColorCommand(`${prefix}:banner-color`);
-  }
+  registerBannerCommand("gentle:banner");
+  registerToggleCommand("gentle:toggle-rose", "showRose");
+  registerToggleCommand("gentle:toggle-text-logo", "showTextLogo");
+  registerColorCommand("gentle:banner-color");
 
   pi.on("session_start", async (_event, ctx) => {
     if (!ctx.hasUI) return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gentle-pi",
-  "version": "0.11.1",
+  "version": "0.11.3",
   "description": "Turn Pi into el Gentleman: a senior-architect development harness with SDD/OpenSpec, subagents, strict TDD evidence, review guardrails, and skill discovery.",
   "license": "MIT",
   "type": "module",

package/skills/gentle-ai/SKILL.md

@@ -69,4 +69,4 @@ Never request a subagent named `reviewer`; it is an intent, not an installed age
 
 If multiple rows match, run the narrow set that covers the risk. Example: shell integration that mutates live state should use `review-reliability` plus `review-resilience`, not `review-readability` by default.
 
-The package ensures SDD agents and chains are available as global Pi runtime assets. Project-local SDD files are overrides/debug copies only. Use `/gentle-ai:install-sdd --force` only for recovery or intentional global refresh.
+The package ensures SDD agents and chains are available as global Pi runtime assets. Project-local SDD files are overrides/debug copies only. Use `/gentle:install-sdd --force` only for recovery or intentional global refresh.

package/tests/runtime-harness.mjs

@@ -22,31 +22,37 @@ const EXPECTED_BANNER_COMMANDS = [
 	"gentle:toggle-rose",
 	"gentle:toggle-text-logo",
 	"gentle:banner-color",
-	"gentle-ai:banner",
-	"gentle-ai:toggle-rose",
-	"gentle-ai:toggle-text-logo",
-	"gentle-ai:banner-color",
 ];
 
 const EXPECTED_COMMANDS = [
-	"gentle-ai:install-sdd",
-	"gentle-ai:sdd-preflight",
+	"gentle:install-sdd",
 	"gentle:sdd-preflight",
 	"sdd-status",
-	"gentle-ai:sdd-status",
 	"sdd-continue",
-	"gentle-ai:sdd-continue",
 	"gentle:models",
+	"gentle:persona",
+	"gentle:status",
+	"gentle:doctor",
+	"sdd-init",
+	"skill-registry:refresh",
+	...EXPECTED_BANNER_COMMANDS,
+];
+
+const FORBIDDEN_COMPAT_COMMANDS = [
+	"gentle-ai:install-sdd",
+	"gentle-ai:sdd-preflight",
+	"gentle-ai:sdd-status",
+	"gentle-ai:sdd-continue",
 	"gentle-ai:models",
 	"gentleman:models",
-	"gentle:persona",
 	"gentle-ai:persona",
 	"gentleman:persona",
 	"gentle-ai:status",
 	"gentle-ai:doctor",
-	"sdd-init",
-	"skill-registry:refresh",
-	...EXPECTED_BANNER_COMMANDS,
+	"gentle-ai:banner",
+	"gentle-ai:toggle-rose",
+	"gentle-ai:toggle-text-logo",
+	"gentle-ai:banner-color",
 ];
 
 function createPi() {
@@ -161,12 +167,16 @@ async function run() {
 	process.env.GENTLE_PI_CONFIG_HOME = globalConfigHome;
 	process.env.GENTLE_PI_AGENT_HOME = globalAgentHome;
 	const globalModelsPath = join(globalConfigHome, "models.json");
+	const globalSubagentsPath = join(globalAgentHome, "subagents.json");
 	const { pi, hooks, commands, flags } = createPi();
 	await loadExtensions(pi);
 
 	for (const name of EXPECTED_COMMANDS) {
 		assert.ok(commands.has(name), `missing command ${name}`);
 	}
+	for (const name of FORBIDDEN_COMPAT_COMMANDS) {
+		assert.equal(commands.has(name), false, `compat command should not be registered: ${name}`);
+	}
 	assert.ok(flags.has("no-skill-registry"), "missing no-skill-registry flag");
 	assert.ok(hooks.has("session_start"), "missing session_start hook");
 	assert.ok(hooks.has("session_shutdown"), "missing session_shutdown hook");
@@ -313,7 +323,7 @@ async function run() {
 		assert.equal(bannerConfig.showRose, false);
 		assert.equal(bannerConfig.showTextLogo, true);
 		assert.equal(bannerConfig.color, "pink");
-		await commands.get("gentle-ai:toggle-text-logo").handler("", ctx);
+		await commands.get("gentle:toggle-text-logo").handler("", ctx);
 		bannerConfig = JSON.parse(await readFile(join(globalConfigHome, "banner.json"), "utf8"));
 		assert.equal(bannerConfig.showTextLogo, false);
 		await commands.get("gentle:banner-color").handler("cyan", ctx);
@@ -500,7 +510,7 @@ async function run() {
 		assert.equal(ctx.ui.selections.length, 3);
 		assert.deepEqual(ctx.ui.selections[1].options, ["openspec"]);
 		assert.match(ctx.ui.notifications.at(-1).message, /SDD preflight complete/);
-		await commands.get("gentle-ai:status").handler("", ctx);
+		await commands.get("gentle:status").handler("", ctx);
 		assert.match(ctx.ui.notifications.at(-1).message, /Global SDD assets stale: 0 file\(s\)/);
 		assert.doesNotMatch(ctx.ui.notifications.at(-1).message, /install-sdd --force/);
 
@@ -543,7 +553,7 @@ async function run() {
 	const commandSddCwd = await tempWorkspace();
 	try {
 		const ctx = createCtx(commandSddCwd, true, "command-session");
-		await commands.get("gentle-ai:sdd-preflight").handler("", ctx);
+		await commands.get("gentle:sdd-preflight").handler("", ctx);
 		assert.equal(existsSync(join(commandSddCwd, ".pi", "agents", "sdd-apply.md")), false);
 		assert.equal(existsSync(join(globalAgentHome, "agents", "sdd-apply.md")), true);
 		assert.equal(ctx.ui.selections.length, 3);
@@ -622,7 +632,7 @@ async function run() {
 	try {
 		await writeFile(globalModelsPath, "{ invalid json");
 		const ctx = createCtx(invalidPreflightCwd, true, "invalid-preflight-session");
-		await commands.get("gentle-ai:sdd-preflight").handler("", ctx);
+		await commands.get("gentle:sdd-preflight").handler("", ctx);
 		assert.equal(ctx.ui.notifications.at(-1).level, "warning");
 		assert.match(ctx.ui.notifications.at(-1).message, /Model routing skipped:/);
 		assert.match(ctx.ui.notifications.at(-1).message, /invalid JSON or not an object/);
@@ -635,7 +645,7 @@ async function run() {
 	try {
 		pi.setActiveTools(["read", "bash", "edit", "write", "mem_save"]);
 		const ctx = createCtx(engramSddCwd, true, "engram-session");
-		await commands.get("gentle-ai:sdd-preflight").handler("", ctx);
+		await commands.get("gentle:sdd-preflight").handler("", ctx);
 		assert.deepEqual(ctx.ui.selections[1].options, ["openspec", "engram", "both"]);
 	} finally {
 		pi.setActiveTools(["read", "bash", "edit", "write"]);
@@ -646,7 +656,7 @@ async function run() {
 	try {
 		pi.setActiveTools(["read", "bash", "edit", "write", "engram_mem_save"]);
 		const ctx = createCtx(directEngramToolCwd, true, "direct-engram-session");
-		await commands.get("gentle-ai:sdd-preflight").handler("", ctx);
+		await commands.get("gentle:sdd-preflight").handler("", ctx);
 		assert.deepEqual(ctx.ui.selections[1].options, ["openspec"]);
 	} finally {
 		pi.setActiveTools(["read", "bash", "edit", "write"]);
@@ -656,7 +666,7 @@ async function run() {
 	const installCwd = await tempWorkspace();
 	try {
 		const ctx = createCtx(installCwd, true);
-		await commands.get("gentle-ai:install-sdd").handler("", ctx);
+		await commands.get("gentle:install-sdd").handler("", ctx);
 		assert.match(ctx.ui.notifications.at(-1).message, /Global Gentle AI SDD assets installed/);
 		assert.equal(existsSync(join(installCwd, ".pi", "agents", "sdd-apply.md")), false);
 		assert.equal(existsSync(join(globalAgentHome, "agents", "sdd-apply.md")), true);
@@ -677,17 +687,17 @@ async function run() {
 		await writeFile(join(staleAssetsCwd, ".pi", "chains", "sdd-full.chain.md"), "stale chain\n");
 		await writeFile(join(staleAssetsCwd, ".pi", "gentle-ai", "support", "sdd-status-contract.md"), "stale status contract\n");
 		const ctx = createCtx(staleAssetsCwd, true);
-		await commands.get("gentle-ai:status").handler("", ctx);
+		await commands.get("gentle:status").handler("", ctx);
 		assert.match(ctx.ui.notifications.at(-1).message, /Project-local SDD agent overrides: 2 file\(s\)/);
 		assert.match(ctx.ui.notifications.at(-1).message, /local SDD agents shadow package assets/);
-		await commands.get("gentle-ai:doctor").handler("", ctx);
+		await commands.get("gentle:doctor").handler("", ctx);
 		assert.match(ctx.ui.notifications.at(-1).message, /el Gentleman doctor/);
 		assert.match(ctx.ui.notifications.at(-1).message, /Sensitive-path guard active/);
 		pi.setActiveTools([{ name: "engram.mem_save" }]);
-		await commands.get("gentle-ai:doctor").handler("", ctx);
+		await commands.get("gentle:doctor").handler("", ctx);
 		assert.match(ctx.ui.notifications.at(-1).message, /Engram memory tools active/);
 		pi.setActiveTools([{ name: "engram_mem_save" }]);
-		await commands.get("gentle-ai:doctor").handler("", ctx);
+		await commands.get("gentle:doctor").handler("", ctx);
 		assert.match(ctx.ui.notifications.at(-1).message, /Engram memory tools not active in this session/);
 		pi.setActiveTools(["read", "bash", "edit", "write"]);
 	} finally {
@@ -709,7 +719,7 @@ async function run() {
 		assert.match(ctx.ui.notifications[0].message, /SDD preflight complete/);
 		assert.match(ctx.ui.notifications.at(-1).message, /Wrote openspec\/config\.yaml/);
 
-		await commands.get("gentle-ai:sdd-preflight").handler("", ctx);
+		await commands.get("gentle:sdd-preflight").handler("", ctx);
 		assert.equal(ctx.ui.selections.length, 3, "/sdd-init preflight should be reused by later manual preflight");
 	} finally {
 		await rm(sddCwd, { recursive: true, force: true });
@@ -789,20 +799,6 @@ async function run() {
 		assert.equal(await readFile(globalModelsPath, "utf8"), "{ invalid json");
 		assert.equal(legacyCtx.ui.notifications.at(-1).level, "warning");
 		assert.match(legacyCtx.ui.notifications.at(-1).message, /cannot open model config/);
-		await writeFile(
-			join(legacyModelsCwd, ".pi", "settings.json"),
-			JSON.stringify(
-				{
-					subagents: {
-						agentOverrides: {
-							"sdd-apply": { model: "settings/provider-model", thinking: "high" },
-						},
-					},
-				},
-				null,
-				2,
-			),
-		);
 		await writeFile(globalModelsPath, JSON.stringify({}, null, 2));
 		await hooks.get("session_start")[0]({ reason: "startup" }, legacyCtx);
 		const emptyGlobalPreservesAgent = await readFile(
@@ -810,12 +806,12 @@ async function run() {
 			"utf8",
 		);
 		assert.match(emptyGlobalPreservesAgent, /model: global\/provider-model/);
-		const emptyGlobalPreservesSettings = JSON.parse(
-			await readFile(join(legacyModelsCwd, ".pi", "settings.json"), "utf8"),
+		const emptyGlobalPreservesProfiles = JSON.parse(
+			await readFile(join(legacyModelsCwd, ".pi", "subagents.json"), "utf8"),
 		);
 		assert.equal(
-			emptyGlobalPreservesSettings.subagents.agentOverrides["sdd-apply"].model,
-			"settings/provider-model",
+			emptyGlobalPreservesProfiles.model_profiles["sdd-apply"].model,
+			"global/provider-model",
 		);
 		await writeFile(
 			globalModelsPath,
@@ -827,12 +823,12 @@ async function run() {
 			"utf8",
 		);
 		assert.match(invalidEntryPreservesAgent, /model: global\/provider-model/);
-		const invalidEntryPreservesSettings = JSON.parse(
-			await readFile(join(legacyModelsCwd, ".pi", "settings.json"), "utf8"),
+		const invalidEntryPreservesProfiles = JSON.parse(
+			await readFile(join(legacyModelsCwd, ".pi", "subagents.json"), "utf8"),
 		);
 		assert.equal(
-			invalidEntryPreservesSettings.subagents.agentOverrides["sdd-apply"].model,
-			"settings/provider-model",
+			invalidEntryPreservesProfiles.model_profiles["sdd-apply"].model,
+			"global/provider-model",
 		);
 		await writeFile(globalModelsPath, JSON.stringify({ "sdd-apply": {} }, null, 2));
 		await hooks.get("session_start")[0]({ reason: "startup" }, legacyCtx);
@@ -841,10 +837,10 @@ async function run() {
 			"utf8",
 		);
 		assert.doesNotMatch(explicitInheritClearsAgent, /model:/);
-		const explicitInheritClearsSettings = JSON.parse(
-			await readFile(join(legacyModelsCwd, ".pi", "settings.json"), "utf8"),
+		const explicitInheritClearsProfiles = JSON.parse(
+			await readFile(join(legacyModelsCwd, ".pi", "subagents.json"), "utf8"),
 		);
-		assert.equal(explicitInheritClearsSettings.subagents, undefined);
+		assert.equal(explicitInheritClearsProfiles.model_profiles, undefined);
 	} finally {
 		await rm(legacyModelsCwd, { recursive: true, force: true });
 		await rm(globalModelsPath, { force: true });
@@ -852,15 +848,12 @@ async function run() {
 
 	const staleSettingsOnlyCwd = await tempWorkspace();
 	try {
-		await mkdir(join(staleSettingsOnlyCwd, ".pi"), { recursive: true });
 		await writeFile(
-			join(staleSettingsOnlyCwd, ".pi", "settings.json"),
+			globalSubagentsPath,
 			JSON.stringify(
 				{
-					subagents: {
-						agentOverrides: {
-							worker: { model: "stale/model", thinking: "high" },
-						},
+					model_profiles: {
+						worker: { model: "stale/model", effort: "high" },
 					},
 				},
 				null,
@@ -869,18 +862,126 @@ async function run() {
 		);
 		await writeFile(globalModelsPath, JSON.stringify({ worker: {} }, null, 2));
 		await hooks.get("session_start")[0]({ reason: "startup" }, createCtx(staleSettingsOnlyCwd, true));
-		const staleOnlyClearedSettings = JSON.parse(
-			await readFile(join(staleSettingsOnlyCwd, ".pi", "settings.json"), "utf8"),
+		const staleOnlyClearedProfiles = JSON.parse(
+			await readFile(globalSubagentsPath, "utf8"),
 		);
-		assert.equal(staleOnlyClearedSettings.subagents, undefined);
+		assert.equal(staleOnlyClearedProfiles.model_profiles, undefined);
 	} finally {
 		await rm(staleSettingsOnlyCwd, { recursive: true, force: true });
 		await rm(globalModelsPath, { force: true });
+		await rm(globalSubagentsPath, { force: true });
+	}
+
+	const legacySettingsMigrationCwd = await tempWorkspace();
+	try {
+		await mkdir(join(legacySettingsMigrationCwd, ".pi", "subagents"), { recursive: true });
+		await mkdir(join(globalAgentHome, "subagents"), { recursive: true });
+		await writeFile(
+			join(legacySettingsMigrationCwd, ".pi", "subagents", "local-worker.md"),
+			`---\nname: local-worker\ndescription: Local worker\n---\n`,
+		);
+		await writeFile(
+			join(legacySettingsMigrationCwd, ".pi", "subagents", "local-new.md"),
+			`---\nname: local-new\ndescription: Local new worker\n---\n`,
+		);
+		await writeFile(
+			join(globalAgentHome, "subagents", "global-worker.md"),
+			`---\nname: global-worker\ndescription: Global worker\n---\n`,
+		);
+		await writeFile(
+			join(globalAgentHome, "subagents", "global-new.md"),
+			`---\nname: global-new\ndescription: Global new worker\n---\n`,
+		);
+		await writeFile(
+			join(legacySettingsMigrationCwd, ".pi", "subagents.json"),
+			JSON.stringify({ model_profiles: { "local-worker": { model: "existing/local", effort: "medium" } } }, null, 2),
+		);
+		await writeFile(
+			globalSubagentsPath,
+			JSON.stringify({ model_profiles: { "global-worker": { model: "existing/global", effort: "medium" } } }, null, 2),
+		);
+		await writeFile(
+			join(legacySettingsMigrationCwd, ".pi", "settings.json"),
+			JSON.stringify(
+				{
+					theme: "keep-me",
+					subagents: {
+						history: "keep-me-too",
+						agentOverrides: {
+							"local-worker": {},
+							"local-new": { model: "local/new-model", thinking: "minimal" },
+							"global-worker": {},
+							"global-new": { model: "global/new-model", thinking: "xhigh" },
+							"unknown-project": { model: "unknown/project-model", thinking: "low" },
+						},
+					},
+				},
+				null,
+				2,
+			),
+		);
+		await hooks.get("session_start")[0]({ reason: "startup" }, createCtx(legacySettingsMigrationCwd, true));
+		const migratedProjectProfiles = JSON.parse(
+			await readFile(join(legacySettingsMigrationCwd, ".pi", "subagents.json"), "utf8"),
+		);
+		assert.equal(migratedProjectProfiles.model_profiles["local-worker"].model, "existing/local");
+		assert.equal(migratedProjectProfiles.model_profiles["local-worker"].effort, "medium");
+		assert.equal(migratedProjectProfiles.model_profiles["local-new"].model, "local/new-model");
+		assert.equal(migratedProjectProfiles.model_profiles["local-new"].effort, "minimal");
+		assert.equal(migratedProjectProfiles.model_profiles["unknown-project"].model, "unknown/project-model");
+		assert.equal(migratedProjectProfiles.model_profiles["unknown-project"].effort, "low");
+		const migratedGlobalProfiles = JSON.parse(await readFile(globalSubagentsPath, "utf8"));
+		assert.equal(migratedGlobalProfiles.model_profiles["global-worker"].model, "existing/global");
+		assert.equal(migratedGlobalProfiles.model_profiles["global-worker"].effort, "medium");
+		assert.equal(migratedGlobalProfiles.model_profiles["global-new"].model, "global/new-model");
+		assert.equal(migratedGlobalProfiles.model_profiles["global-new"].effort, "xhigh");
+		const migratedSettings = JSON.parse(
+			await readFile(join(legacySettingsMigrationCwd, ".pi", "settings.json"), "utf8"),
+		);
+		assert.equal(migratedSettings.theme, "keep-me");
+		assert.equal(migratedSettings.subagents.history, "keep-me-too");
+		assert.equal(migratedSettings.subagents.agentOverrides, undefined);
+	} finally {
+		await rm(legacySettingsMigrationCwd, { recursive: true, force: true });
+		await rm(globalSubagentsPath, { force: true });
+	}
+
+	const invalidMigrationTargetCwd = await tempWorkspace();
+	try {
+		await mkdir(join(invalidMigrationTargetCwd, ".pi", "subagents"), { recursive: true });
+		await writeFile(
+			join(invalidMigrationTargetCwd, ".pi", "subagents", "local-bad.md"),
+			`---\nname: local-bad\ndescription: Local bad target\n---\n`,
+		);
+		await mkdir(join(globalAgentHome, "subagents"), { recursive: true });
+		await writeFile(
+			join(globalAgentHome, "subagents", "global-bad.md"),
+			`---\nname: global-bad\ndescription: Global bad target\n---\n`,
+		);
+		await writeFile(join(invalidMigrationTargetCwd, ".pi", "subagents.json"), "{ invalid json");
+		await writeFile(globalSubagentsPath, "{ invalid global json");
+		await writeFile(
+			join(invalidMigrationTargetCwd, ".pi", "settings.json"),
+			JSON.stringify({ subagents: { agentOverrides: { "local-bad": { model: "legacy/model", thinking: "low" }, "global-bad": { model: "legacy/global-model", thinking: "high" } } } }, null, 2),
+		);
+		await hooks.get("session_start")[0]({ reason: "startup" }, createCtx(invalidMigrationTargetCwd, true));
+		assert.equal(await readFile(join(invalidMigrationTargetCwd, ".pi", "subagents.json"), "utf8"), "{ invalid json");
+		assert.equal(await readFile(globalSubagentsPath, "utf8"), "{ invalid global json");
+		const preservedLegacySettings = JSON.parse(
+			await readFile(join(invalidMigrationTargetCwd, ".pi", "settings.json"), "utf8"),
+		);
+		assert.equal(preservedLegacySettings.subagents.agentOverrides["local-bad"].model, "legacy/model");
+		assert.equal(preservedLegacySettings.subagents.agentOverrides["global-bad"].model, "legacy/global-model");
+	} finally {
+		await rm(invalidMigrationTargetCwd, { recursive: true, force: true });
+		await rm(globalSubagentsPath, { force: true });
 	}
 
 	const modelsCwd = await tempWorkspace();
 	try {
 		await mkdir(join(modelsCwd, ".pi", "agents"), { recursive: true });
+		await mkdir(join(modelsCwd, ".pi", "subagents"), { recursive: true });
+		await mkdir(join(globalAgentHome, "subagents"), { recursive: true });
 		await mkdir(
 			join(modelsCwd, ".pi", "npm", "node_modules", "pi-subagents-j0k3r", "agents"),
 			{ recursive: true },
@@ -905,6 +1006,10 @@ async function run() {
 			join(modelsCwd, ".pi", "agents", "worker.md"),
 			`---\nname: worker\ndescription: Project worker\nmodel: existing/project-worker\nthinking: high\n---\n`,
 		);
+		await writeFile(
+			join(modelsCwd, ".pi", "subagents", "worker.md"),
+			`---\nname: worker\ndescription: Project subagents worker\nmodel: existing/project-subagent-worker\nthinking: medium\n---\n`,
+		);
 		await writeFile(
 			join(
 				modelsCwd,
@@ -921,6 +1026,14 @@ async function run() {
 			join(modelsCwd, ".pi", "agents", "sdd-apply.md"),
 			`---\nname: sdd-apply\ndescription: Apply phase\n---\n\nbody\n`,
 		);
+		await writeFile(
+			join(modelsCwd, ".pi", "subagents", "project-special.md"),
+			`---\nname: project-special\ndescription: Project subagent dir fixture\n---\n\nbody\n`,
+		);
+		await writeFile(
+			join(globalAgentHome, "subagents", "global-special.md"),
+			`---\nname: global-special\ndescription: Global subagent dir fixture\n---\n\nbody\n`,
+		);
 		for (let i = 0; i < 25; i++) {
 			const name = `large-agent-${String(i).padStart(2, "0")}`;
 			await writeFile(
@@ -933,13 +1046,11 @@ async function run() {
 			`---\nname: evil\u001b]52;c;Zm9v\u0007-agent\ndescription: Escape fixture\n---\n`,
 		);
 		await writeFile(
-			join(modelsCwd, ".pi", "settings.json"),
+			join(modelsCwd, ".pi", "subagents.json"),
 			JSON.stringify(
 				{
-					subagents: {
-						agentOverrides: {
-							worker: { model: "existing/model", thinking: "high" },
-						},
+					model_profiles: {
+						worker: { model: "existing/model", effort: "high" },
 					},
 				},
 				null,
@@ -948,35 +1059,44 @@ async function run() {
 		);
 		await writeFile(globalModelsPath, JSON.stringify({}, null, 2));
 		await hooks.get("session_start")[0]({ reason: "startup" }, createCtx(modelsCwd, true));
-		const preservedSettings = JSON.parse(
-			await readFile(join(modelsCwd, ".pi", "settings.json"), "utf8"),
+		const preservedProfiles = JSON.parse(
+			await readFile(join(modelsCwd, ".pi", "subagents.json"), "utf8"),
 		);
 		assert.equal(
-			preservedSettings.subagents.agentOverrides.worker.model,
+			preservedProfiles.model_profiles.worker.model,
 			"existing/model",
 		);
-		assert.equal(
-			preservedSettings.subagents.agentOverrides.worker.thinking,
-			"high",
-		);
+		assert.equal(preservedProfiles.model_profiles.worker.effort, "high");
 		const preservedProjectWorker = await readFile(
 			join(modelsCwd, ".pi", "agents", "worker.md"),
 			"utf8",
 		);
 		assert.match(preservedProjectWorker, /model: existing\/project-worker/);
 		assert.match(preservedProjectWorker, /thinking: high/);
+		const preservedProjectSubagentWorker = await readFile(
+			join(modelsCwd, ".pi", "subagents", "worker.md"),
+			"utf8",
+		);
+		assert.match(preservedProjectSubagentWorker, /model: existing\/project-subagent-worker/);
+		assert.match(preservedProjectSubagentWorker, /thinking: medium/);
 		await writeFile(globalModelsPath, JSON.stringify({ worker: {} }, null, 2));
 		await hooks.get("session_start")[0]({ reason: "startup" }, createCtx(modelsCwd, true));
-		const clearedSettings = JSON.parse(
-			await readFile(join(modelsCwd, ".pi", "settings.json"), "utf8"),
+		const clearedProfiles = JSON.parse(
+			await readFile(join(modelsCwd, ".pi", "subagents.json"), "utf8"),
 		);
-		assert.equal(clearedSettings.subagents, undefined);
-		const clearedProjectWorker = await readFile(
+		assert.equal(clearedProfiles.model_profiles, undefined);
+		const unchangedProjectWorker = await readFile(
 			join(modelsCwd, ".pi", "agents", "worker.md"),
 			"utf8",
 		);
-		assert.doesNotMatch(clearedProjectWorker, /model:/);
-		assert.doesNotMatch(clearedProjectWorker, /thinking:/);
+		assert.match(unchangedProjectWorker, /model: existing\/project-worker/);
+		assert.match(unchangedProjectWorker, /thinking: high/);
+		const clearedProjectSubagentWorker = await readFile(
+			join(modelsCwd, ".pi", "subagents", "worker.md"),
+			"utf8",
+		);
+		assert.doesNotMatch(clearedProjectSubagentWorker, /model:/);
+		assert.doesNotMatch(clearedProjectSubagentWorker, /thinking:/);
 
 		await writeFile(
 			globalModelsPath,
@@ -1059,6 +1179,8 @@ async function run() {
 					"sdd-apply": { model: "openai/gpt-5", thinking: "high" },
 					worker: { model: "openai/gpt-5-mini", thinking: "low" },
 					researcher: { model: "openai/gpt-5-mini", thinking: "low" },
+					"project-special": { model: "openai/gpt-5-mini", thinking: "low" },
+					"global-special": { model: "openai/gpt-5-mini", thinking: "low" },
 				},
 			});
 		await commands.get("gentle:models").handler("", ctx);
@@ -1088,19 +1210,48 @@ async function run() {
 		assert.match(applyAgent, /model: openai\/gpt-5/);
 		assert.match(applyAgent, /thinking: high/);
 
-		const settings = JSON.parse(
-			await readFile(join(modelsCwd, ".pi", "settings.json"), "utf8"),
+		const projectSubagents = JSON.parse(
+			await readFile(join(modelsCwd, ".pi", "subagents.json"), "utf8"),
+		);
+		assert.equal(
+			projectSubagents.model_profiles["sdd-apply"].model,
+			"openai/gpt-5",
+		);
+		assert.equal(projectSubagents.model_profiles["sdd-apply"].effort, "high");
+		assert.equal(
+			projectSubagents.model_profiles.worker.model,
+			"openai/gpt-5-mini",
+		);
+		assert.equal(projectSubagents.model_profiles.worker.effort, "low");
+		const routedProjectSubagentWorker = await readFile(
+			join(modelsCwd, ".pi", "subagents", "worker.md"),
+			"utf8",
+		);
+		assert.match(routedProjectSubagentWorker, /model: openai\/gpt-5-mini/);
+		assert.match(routedProjectSubagentWorker, /thinking: low/);
+		const shadowedProjectAgentWorker = await readFile(
+			join(modelsCwd, ".pi", "agents", "worker.md"),
+			"utf8",
+		);
+		assert.match(shadowedProjectAgentWorker, /model: existing\/project-worker/);
+		assert.match(shadowedProjectAgentWorker, /thinking: high/);
+		assert.equal(
+			projectSubagents.model_profiles["project-special"].model,
+			"openai/gpt-5-mini",
 		);
+		assert.equal(projectSubagents.model_profiles["project-special"].effort, "low");
+		const globalSubagents = JSON.parse(await readFile(globalSubagentsPath, "utf8"));
 		assert.equal(
-			settings.subagents.agentOverrides.worker.model,
+			globalSubagents.model_profiles.researcher.model,
 			"openai/gpt-5-mini",
 		);
-		assert.equal(settings.subagents.agentOverrides.worker.thinking, "low");
+		assert.equal(globalSubagents.model_profiles.researcher.effort, "low");
 		assert.equal(
-			settings.subagents.agentOverrides.researcher.model,
+			globalSubagents.model_profiles["global-special"].model,
 			"openai/gpt-5-mini",
 		);
-		assert.equal(settings.subagents.agentOverrides.researcher.thinking, "low");
+		assert.equal(globalSubagents.model_profiles["global-special"].effort, "low");
+		assert.equal(existsSync(join(modelsCwd, ".pi", "settings.json")), false);
 
 		const kittyE = "\x1b[101u";
 		assert.notEqual(kittyE, "e");
@@ -1196,6 +1347,7 @@ async function run() {
 	} finally {
 		await rm(modelsCwd, { recursive: true, force: true });
 		await rm(globalModelsPath, { force: true });
+		await rm(globalSubagentsPath, { force: true });
 	}
 
 	const registryCwd = await tempWorkspace();