claudeup 6.6.0 → 6.8.0

package/src/__tests__/models-presets-marketplace.test.ts

@@ -0,0 +1,168 @@
+/**
+ * The agent tier table and the workflow list are keyed by agent id, and nothing else
+ * checks those ids.
+ *
+ * `DEFAULT_AGENT_GRADES` in `data/models-presets.ts` names
+ * agents as `plugin:name`. A rename in the marketplace (`code-search:analyze` →
+ * something else, `dev:synthesizer` → `dev:aggregator`) breaks the key with no signal: the
+ * renamed agent silently falls to the preset's fallback, and the stale key routes nothing.
+ * This test reads the marketplace source tree beside this repo and fails on either drift.
+ *
+ * Two directions:
+ *   (a) every preset key names an agent that exists (or is a Claude Code built-in);
+ *   (b) every marketplace agent is classified — in the tier table, in the frontmatter map,
+ *       a vision agent, or explicitly left to the fallback in FALLBACK_BY_DESIGN below.
+ *       Absence is a legitimate routing choice (fallback = `normal`), but it must be a
+ *       choice: a new agent fails here until someone decides.
+ */
+import { describe, expect, test } from "bun:test";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import {
+	DEFAULT_AGENT_GRADES,
+	VISION_AGENTS,
+	WORKFLOWS,
+} from "../data/models-presets.js";
+import { PREDEFINED_PROFILES } from "../data/predefined-profiles.js";
+
+const REPO = resolve(import.meta.dir, "..", "..", "..", "..");
+const MARKETPLACE = join(REPO, ".claude-plugin", "marketplace.json");
+const inMagusSrc = existsSync(MARKETPLACE) && existsSync(join(REPO, "plugins"));
+
+/** Claude Code's own agents: not in any marketplace, addressed by bare name. */
+const BUILT_IN = new Set([
+	"Explore",
+	"Plan",
+	"general-purpose",
+	"statusline-setup",
+	"claude-code-guide",
+]);
+
+/**
+ * Marketplace agents deliberately left to the preset's `fallback` grade. Each entry is a
+ * decision, not an omission: remove the line when the agent gets a tier. A NEW agent is not
+ * on this list, so adding one to the marketplace fails (b) until it is placed somewhere.
+ */
+const FALLBACK_BY_DESIGN = new Set([
+	"dev:developer",
+	"dev:devops",
+	"dev:frontend-developer",
+	"dev:researcher",
+	"dev:qa-engineer",
+	"madbench:bench",
+	"video-editing:timeline-builder",
+	"video-editing:transcriber",
+	"video-editing:video-processor",
+]);
+
+interface MarketplaceAgent {
+	id: string;
+	file: string;
+	frontmatterModel: string | undefined;
+}
+
+/** Every `plugins/<p>/agents/*.md` of every plugin the marketplace lists, by frontmatter name. */
+function marketplaceAgents(): MarketplaceAgent[] {
+	const manifest = JSON.parse(readFileSync(MARKETPLACE, "utf8")) as {
+		plugins: { name: string; source: string }[];
+	};
+	const out: MarketplaceAgent[] = [];
+	for (const plugin of manifest.plugins) {
+		const agentsDir = join(REPO, plugin.source, "agents");
+		if (!existsSync(agentsDir)) continue;
+		for (const entry of readdirSync(agentsDir)) {
+			if (!entry.endsWith(".md")) continue;
+			const file = join(agentsDir, entry);
+			const text = readFileSync(file, "utf8");
+			const fm = text.match(/^---\n([\s\S]*?)\n---/);
+			if (!fm) continue;
+			const name = fm[1].match(/^name:\s*(.+?)\s*$/m)?.[1];
+			if (!name) continue;
+			const model = fm[1].match(/^model:\s*(.+?)\s*$/m)?.[1];
+			out.push({
+				id: `${plugin.name}:${name}`,
+				file: join(plugin.source, "agents", entry),
+				frontmatterModel: model,
+			});
+		}
+	}
+	return out;
+}
+
+describe.skipIf(!inMagusSrc)(
+	"models-presets agent ids track the marketplace",
+	() => {
+		const agents = marketplaceAgents();
+		const ids = new Set(agents.map((a) => a.id));
+		const presetKeys = [...Object.keys(DEFAULT_AGENT_GRADES)];
+
+		test("reads a non-trivial marketplace", () => {
+			expect(agents.length).toBeGreaterThan(10);
+		});
+
+		test("(a) every preset key names an existing agent or a built-in", () => {
+			const dead = presetKeys.filter((k) => !BUILT_IN.has(k) && !ids.has(k));
+			expect(dead).toEqual([]);
+		});
+
+		/**
+		 * (c) `WORKFLOWS` names agent ids too, and until now nothing checked them.
+		 *
+		 * These ids drive the per-workflow spread graphic. A stale one matches no agent, so
+		 * its segment silently vanishes and the chart goes on drawing a confident answer
+		 * about a workflow it has mis-measured — the same silent-drift failure (a) exists to
+		 * catch, one array over. Measured: the 13.0.0 `code-analysis` → `code-search` rename
+		 * reached this array through a rebase conflict rather than through this gate.
+		 *
+		 * Deliberately NOT folded into `presetKeys`. Being named in a workflow is not a
+		 * routing classification, so counting it in (b) would let a workflow mention excuse
+		 * an agent from ever being given a tier.
+		 */
+		test("(c) every workflow agent names an existing agent or a built-in", () => {
+			const workflowKeys = WORKFLOWS.flatMap((w) => [
+				...w.agents,
+				...w.external.map((step) => step.agent),
+			]);
+			const dead = workflowKeys.filter((k) => !BUILT_IN.has(k) && !ids.has(k));
+			expect(dead).toEqual([]);
+		});
+
+		test("(b) every marketplace agent is classified somewhere", () => {
+			const classified = new Set<string>([
+				...presetKeys,
+				...VISION_AGENTS,
+				...FALLBACK_BY_DESIGN,
+			]);
+			const unplaced = agents
+				.filter((a) => !classified.has(a.id))
+				.map((a) => a.id);
+			expect(unplaced).toEqual([]);
+		});
+
+		test("FALLBACK_BY_DESIGN and VISION_AGENTS name agents that still exist", () => {
+			const stale = [...FALLBACK_BY_DESIGN, ...VISION_AGENTS].filter(
+				(k) => !ids.has(k),
+			);
+			expect(stale).toEqual([]);
+		});
+
+		// A profile's magusPlugins is an install list, not documentation: resolver.ts expands
+		// each entry to `<name>@<marketplace>: latest`. A plugin rename moves under it silently,
+		// which is how 13.0.0's code-analysis -> code-search rename left six profiles installing
+		// a plugin the marketplace no longer lists. The agent checks above never read this array.
+		test("(d) every predefined profile names plugins the marketplace still lists", () => {
+			const marketplace = JSON.parse(readFileSync(MARKETPLACE, "utf8")) as {
+				plugins: { name: string }[];
+			};
+			const known = new Set(marketplace.plugins.map((p) => p.name));
+			const dead: string[] = [];
+			for (const profile of PREDEFINED_PROFILES) {
+				for (const entry of profile.magusPlugins ?? []) {
+					const name = entry.split("@")[0];
+					if (!known.has(name)) dead.push(`${profile.id}: ${entry}`);
+				}
+			}
+			expect(dead).toEqual([]);
+		});
+	},
+);

package/src/__tests__/models-screen-state.test.ts

@@ -24,6 +24,11 @@ function snapshot(over: Partial<ModelsSnapshot> = {}): ModelsSnapshot {
 	};
 }
 
+/** Drop `//` line comments and block comments, so a source guard matches code only. */
+function stripComments(source: string): string {
+	return source.replace(/\/\*[\s\S]*?\*\//g, "").replace(/\/\/[^\n]*/g, "");
+}
+
 /** Navigating away and back is what unmounts the screen. */
 const roundTrip: AppAction[] = [
 	{ type: "NAVIGATE", route: { screen: "plugins" } },
@@ -36,6 +41,9 @@ describe("models screen initial state", () => {
 		expect(initialState.models.searchQuery).toBe("");
 		expect(initialState.models.status).toBeNull();
 		expect(initialState.models.isApplying).toBe(false);
+		// The mate slots are not drawn until something says they can be served. Starting
+		// true would put three rows on screen before anything had been asked.
+		expect(initialState.models.matesAvailable).toBe(false);
 	});
 
 	test("the models route is reachable and NAVIGATE keeps the screen's state", () => {
@@ -194,6 +202,44 @@ describe("apply-in-flight state", () => {
 	});
 });
 
+describe("the mate slots' availability", () => {
+	test("survives the screen unmounting, so the lookup happens once a session", () => {
+		// Unlike the two file reads this screen does on mount, this answer costs a
+		// marketplace resolution with network timeouts behind it. Held locally it would die
+		// on every tab switch and be paid for again on every return — for something that
+		// cannot change while the TUI is open.
+		const available = run([
+			{ type: "MODELS_MATES_AVAILABLE", available: true },
+		]);
+		expect(available.models.matesAvailable).toBe(true);
+		expect(run(roundTrip, available).models.matesAvailable).toBe(true);
+	});
+
+	test("a false answer is recorded, not treated as no answer", () => {
+		// "Not installed" and "never asked" render the same, and that is deliberate — but
+		// the reducer still has to hold the difference, or a later dispatch could not undo it.
+		const state = run([
+			{ type: "MODELS_MATES_AVAILABLE", available: true },
+			{ type: "MODELS_MATES_AVAILABLE", available: false },
+		]);
+		expect(state.models.matesAvailable).toBe(false);
+	});
+
+	test("it touches no other part of the models state", () => {
+		const before = run([
+			{ type: "MODELS_SELECT", index: 2 },
+			{ type: "MODELS_DATA_SUCCESS", snapshot: snapshot() },
+		]);
+		const after = run(
+			[{ type: "MODELS_MATES_AVAILABLE", available: true }],
+			before,
+		);
+		expect(after.models.selectedIndex).toBe(2);
+		expect(after.models.data).toBe(before.models.data);
+		expect(after.styles).toBe(before.styles);
+	});
+});
+
 describe("selection state", () => {
 	test("select records the index verbatim", () => {
 		expect(
@@ -253,7 +299,17 @@ describe("ModelsScreen keybindings", () => {
 	test("screen state is held in the reducer, never in useState", async () => {
 		// The rule the two "survives unmounting" tests above enforce at runtime,
 		// pinned at the source so a new piece of state cannot quietly opt out.
-		const src = await fs.readFile(SCREEN, "utf8");
+		//
+		// Comments are stripped first, the way hook-import-policy.test.ts does it. The rule
+		// is about CODE, and this screen documents why each piece of its state lives in the
+		// reducer — naming the hook it is deliberately not using is the clearest way to say
+		// that, and a guard reading the prose would forbid the explanation along with the
+		// thing explained.
+		const src = stripComments(await fs.readFile(SCREEN, "utf8"));
 		expect(src).not.toContain("useState");
+		// Negative control: stripping must not have eaten the code being guarded. A guard
+		// over an empty string passes forever.
+		expect(src).toContain("useEffect");
+		expect(src).toContain("useCallback");
 	});
 });

package/src/__tests__/plugin-manager-fallback.test.ts

@@ -83,7 +83,7 @@ describe("resolveMarketplacePlugins — offline fallback", () => {
 				"magus",
 				buildLocalMarketplace("magus", [
 					{
-						name: "code-analysis",
+						name: "code-search",
 						version: "5.3.0",
 						description: "Codebase investigation tools",
 						category: "development",
@@ -108,12 +108,10 @@ describe("resolveMarketplacePlugins — offline fallback", () => {
 
 		expect(resolved.plugins).toHaveLength(2);
 		expect(resolved.plugins.map((p) => p.name).sort()).toEqual([
-			"code-analysis",
+			"code-search",
 			"dev",
 		]);
-		const codeAnalysis = resolved.plugins.find(
-			(p) => p.name === "code-analysis",
-		);
+		const codeAnalysis = resolved.plugins.find((p) => p.name === "code-search");
 		expect(codeAnalysis?.version).toBe("5.3.0");
 		expect(codeAnalysis?.description).toBe("Codebase investigation tools");
 		expect(codeAnalysis?.category).toBe("development");

package/src/__tests__/resolver.test.ts

@@ -91,9 +91,9 @@ describe("resolveExtends", () => {
 			extends: "growth-marketer",
 		};
 		const merged = resolveExtends(entry);
-		// image-generate/video-editing ship on the magus-marketing channel and
+		// image/video-editing ship on the magus-marketing channel and
 		// pin it explicitly — they must NOT be rewritten to @magus.
-		expect(merged.plugins!["image-generate@magus-marketing"]).toBe("latest");
+		expect(merged.plugins!["image@magus-marketing"]).toBe("latest");
 		expect(merged.plugins!["video-editing@magus-marketing"]).toBe("latest");
 		expect(merged.plugins!["image-generate@magus"]).toBeUndefined();
 		// Bare names still default to @magus.
@@ -302,7 +302,7 @@ describe("marketplaces derived from plugin ids", () => {
 				name: "Mixed",
 				plugins: {
 					"dev@magus": "latest",
-					"image-generate@magus-marketing": "latest",
+					"image@magus-marketing": "latest",
 					"feature-dev@claude-plugins-official": "latest",
 				},
 			},

package/src/cli/doctor.ts

@@ -21,7 +21,6 @@ import { readManifest } from "../services/manifest.js";
 import {
 	readModelsConfig,
 	readModelsStatus,
-	reapplyModels,
 } from "../services/models-manager.js";
 import { resolveAllProfiles } from "../services/resolver.js";
 import { activeProfile, profileDir } from "../services/symlink-manager.js";
@@ -172,19 +171,15 @@ async function checkModels(projectPath: string, fix: boolean): Promise<number> {
 		);
 	}
 
+	// No drift check. Settings differing from the config is what a CUSTOM config is, and
+	// `doctor` reports problems — a project running models no shipped preset names has none.
+	// So `doctor --fix` no longer reapplies anything: `invalid` returns early above (those
+	// are choices, not damage) and `unhooked` is repaired by registering the hook. Writing
+	// settings back from the config is `claudeup models use <preset>`, which is a decision
+	// the user makes, not a repair.
 	const status = await readModelsStatus(projectPath);
-	if (status.state === "stale") {
-		console.log("  ✗ settings have drifted from the config:");
-		for (const line of status.drift) console.log(`      ${line}`);
-		if (fix) {
-			await reapplyModels(projectPath);
-			console.log("    Re-applied the config (fixed).");
-		} else {
-			console.log("    Fix: claudeup doctor --fix");
-			problems++;
-		}
-	} else if (status.state === "on") {
-		console.log(`  ✓ preset "${status.preset}" applied, no drift.`);
+	if (status.state === "on") {
+		console.log("  ✓ routing is applied.");
 	}
 
 	for (const warning of status.warnings) console.log(`  ⚠ ${warning}`);

package/src/cli/models.ts

@@ -18,10 +18,20 @@ import {
 	presetLabel,
 	presetNames,
 } from "../data/models-presets.js";
+import {
+	loadMateCatalog,
+	stalenessNote,
+	unknownBindings,
+} from "../services/mate-catalog.js";
 import {
 	GRADES,
 	type ModelsConfig,
 	type ModelsState,
+	boundModel,
+	isMate,
+	mateEffort,
+	matesInUse,
+	sameRouting,
 } from "../services/models-core.js";
 import {
 	applyModelPreset,
@@ -35,13 +45,34 @@ import { ensureManifest } from "./bootstrap.js";
 const HEADLINE: Record<ModelsState, string> = {
 	off: "off — no .claude/models.json, subagents inherit the session model",
 	on: "on",
-	stale: "stale — settings no longer match the config",
 	invalid: "invalid — nothing is routed",
 	unhooked: "unhooked — the config is there, but nothing runs it",
 };
 
-/** `opus (medium)`, or `opus` when no effort is set. */
-function describeSpec(spec: { model: string; effort?: string }): string {
+/**
+ * `opus (medium)`, or `opus` when no effort is set.
+ *
+ * A mate prints the SLOT and what it is bound to — `mate1 → grok-4.6` — because both are
+ * answers to different questions the reader has: which role this tier plays, and which model
+ * plays it. The slot alone was all that could be printed before the `mates` block existed,
+ * and a bare `kangaroo` in a column of `opus (xhigh)` read as a model id nobody recognises.
+ *
+ * An effort on a mate is qualified `(declared)`, for the reason spelled out at
+ * `DECLARED_SUFFIX`: claudeup writes it for claudish and nothing applies it yet, so printing
+ * a bare `(high)` beside a tier where `(high)` IS in force would claim they do the same
+ * thing.
+ */
+function describeSpec(
+	config: ModelsConfig,
+	spec: { model: string; effort?: string },
+): string {
+	if (isMate(spec.model)) {
+		const bound = boundModel(config, spec.model);
+		const effort = spec.effort ?? mateEffort(config, spec.model);
+		const target = bound ?? "unbound";
+		const note = effort ? `${effort} declared, via claudish` : "via claudish";
+		return `${spec.model} → ${target} (${note})`;
+	}
 	return spec.effort ? `${spec.model} (${spec.effort})` : spec.model;
 }
 
@@ -58,24 +89,82 @@ function printPreset(preset: ModelsConfig, active: boolean): void {
 	console.log(
 		`${mark} ${presetLabel(preset.preset)}  —  ${preset.preset}${isDefault}`,
 	);
-	console.log(`    main       ${describeSpec(preset.main)}`);
+	console.log(`    main       ${describeSpec(preset, preset.main)}`);
 	for (const grade of GRADES) {
 		console.log(
-			`    ${grade.padEnd(10)} ${describeSpec(preset.grades[grade])}`,
+			`    ${grade.padEnd(10)} ${describeSpec(preset, preset.grades[grade])}`,
 		);
 	}
 }
 
 async function runList(projectPath: string): Promise<number> {
 	const { config } = await readModelsConfig(projectPath);
+
+	// Has the project diverged from the built-in it NAMES?
+	//
+	// The test used to be "does it name a preset the built-ins do not", which misses the
+	// ordinary case: `claudeup models use opus-lead` writes that name, and every hand edit
+	// afterwards leaves it in place. So a config with a `mates` block was reported as the
+	// built-in `opus-lead`, and the `●` sat on a preset that is not what runs. Compared by
+	// CONTENT, shared with the TUI through `sameRouting` so the two cannot disagree about
+	// which routing is in force.
+	const builtInNamed = BUILT_IN_PRESETS.find(
+		(preset) => preset.preset === config?.preset,
+	);
+	const diverged =
+		config !== null && (!builtInNamed || !sameRouting(config, builtInNamed));
+
 	console.log("\nModel tiers:\n");
 	for (const preset of BUILT_IN_PRESETS) {
-		printPreset(preset, config?.preset === preset.preset);
+		printPreset(preset, !diverged && config?.preset === preset.preset);
 		console.log();
 	}
-	if (config && !presetNames().includes(config.preset)) {
-		console.log(`● ${config.preset}  (this project's own, not a built-in)\n`);
+	if (config && diverged) {
+		// The project's own config gets its tiers PRINTED, not just its name.
+		//
+		// It is the routing actually in force, and it is the only config here that can name a
+		// mate — no built-in does — so printing the name alone hid the one line a reader came
+		// for. The built-ins above are shown in full; showing the active one in less detail
+		// than the ones it replaced was backwards.
+		printPreset(config, true);
+		console.log("    (this project's own, not a built-in)\n");
 	}
+
+	// Which agents leave Claude Code entirely.
+	//
+	// `models list` prints tiers, never agents, so a mate assigned per-agent — the ordinary
+	// way to use one — appears nowhere else in this command's output. It is also the one
+	// routing decision here that claudeup does not carry out itself, which makes it exactly
+	// the thing worth naming rather than leaving to be discovered in the file.
+	const mated = Object.entries(config?.agents ?? {}).filter(
+		([, assignment]) =>
+			typeof assignment !== "string" && isMate(assignment.model),
+	);
+	if (config && mated.length > 0) {
+		console.log("Routed outside Claude Code, through claudish:\n");
+		for (const [agent, assignment] of mated) {
+			const slot =
+				typeof assignment === "string" ? assignment : assignment.model;
+			// The SLOT and the model it names. The slot is what the file says and what the
+			// reader greps for; the bound id is what actually runs. Printing only the slot was
+			// the CLI's version of the screen's `mate1 mate1 —` — a role where a model belongs.
+			const bound = isMate(slot) ? boundModel(config, slot) : null;
+			const target = bound ?? "unbound — add it to the mates block";
+			console.log(`    ${agent.padEnd(28)} ${slot.padEnd(10)} ${target}`);
+		}
+		console.log();
+
+		// The staleness advisory, on the same terms as everywhere else: ADVISORY, and silent
+		// when the catalogue could not be read. `unknownBindings` returns nothing for an empty
+		// catalogue, so a machine without claudish prints no note rather than flagging every
+		// binding it cannot check.
+		const bound = matesInUse(config)
+			.map((mate) => boundModel(config, mate))
+			.filter((id): id is string => id !== null);
+		const note = stalenessNote(unknownBindings(bound, await loadMateCatalog()));
+		if (note) console.log(`⚠ ${note}\n`);
+	}
+
 	console.log(
 		"Tiers name what a subagent is FOR: `smart` takes the judgement calls, `cheap`",
 	);
@@ -97,11 +186,6 @@ async function runStatus(projectPath: string): Promise<number> {
 	if (status.drift.length > 0) {
 		console.log(status.state === "invalid" ? "\nErrors:" : "\nDrift:");
 		for (const line of status.drift) console.log(`  ✗ ${line}`);
-		if (status.state === "stale") {
-			console.log(
-				"\n  Fix: claudeup models use <preset>  (or claudeup doctor --fix)",
-			);
-		}
 		if (status.state === "unhooked")
 			console.log("\n  Fix: claudeup doctor --fix");
 	}

package/src/data/models-presets.ts

@@ -13,7 +13,7 @@
  * `medium`) rather than a harder-working one. What holds everywhere is the other half: the
  * thread dispatching the work is never strictly the biggest spend in the preset.
  */
-import type { Grade, ModelsConfig } from "../services/models-core.js";
+import type { Effort, Grade, ModelsConfig } from "../services/models-core.js";
 
 /**
  * Which tier each subagent gets, shared by every preset.
@@ -40,19 +40,18 @@ export const DEFAULT_AGENT_GRADES: Record<string, Grade> = {
 	// what is true; both were on `smart` because "writes an important document" got confused
 	// with "makes an expensive judgement".
 	"dev:spec-writer": "normal",
-	"dev:synthesizer": "normal",
+	"dev:aggregator": "normal",
 
 	// Reading a lot is not analysing.
 	//
-	// `detective` is read-only: it locates implementations, traces a path and reports
+	// `analyze` is read-only: it locates implementations, traces a path and reports
 	// file:line. That is high-volume retrieval with light inference — the same shape as
 	// `Explore`, with more structure in the output. It sat on `smart` because "investigates"
 	// sounds like thinking; what it actually does is look.
-	"code-analysis:detective": "cheap",
+	"code-search:analyze": "cheap",
 
-	// Search, transcription and bookkeeping: bounded, mechanical, high-volume.
+	// Search and bookkeeping: bounded, mechanical, high-volume.
 	Explore: "cheap",
-	"dev:scribe": "cheap",
 	"dev:stack-detector": "cheap",
 	"dev:docs": "cheap",
 	"terminal:tui-navigator": "cheap",
@@ -69,32 +68,73 @@ export const DEFAULT_AGENT_GRADES: Record<string, Grade> = {
  * answers to "what will this preset cost me", and the lump sum shows neither.
  *
  * Read out of `plugins/dev/commands/{dev,debug,investigate}.md` — agents only. Those files
- * also name skills (`dev:context-detection`, `code-analysis:investigate`) which are not
+ * also name skills (`dev:context-detection`, `code-search:investigate`) which are not
  * dispatched through the Agent tool and so are not routed at all.
+ *
+ * ## `external` — the steps that leave Claude Code, whatever the preset says
+ *
+ * A workflow's use of an outside model is a property of the WORKFLOW, not of the routing
+ * config. `/dev:dev` runs a multi-model plan review at Phase 3 and a multi-model code review
+ * at Phase 5 because its command file says so, and switching from `Sonnet` to `Opus main`
+ * does not change that. So these steps are declared here beside the agents and are drawn
+ * under every preset, rather than being read out of `config.agents` — where they would
+ * appear only for a project that happened to have hand-bound a slot.
+ *
+ * Read out of the same command files:
+ *   `plugins/dev/commands/dev.md:138`  Plan review (external models via claudish) → dev:architect
+ *   `plugins/dev/commands/dev.md:140`  Code review (external models via claudish) → dev:architect
+ *
+ * `debug.md` and `investigate.md` contain no claudish reference at all, so both are empty
+ * here — and that absence is worth drawing, because "this flow stays inside Claude Code" is
+ * exactly as useful to know as the opposite.
+ *
+ * A STEP, not an agent: `dev:architect` appears in `agents` above as well, because the same
+ * agent does the Phase 3 planning on a Claude model. Marking the agent external would be
+ * wrong in both directions — it would move the planning outside and merge the two reviews
+ * into it.
  */
-export const WORKFLOWS: { name: string; agents: string[] }[] = [
+export interface WorkflowStep {
+	/** What the phase is called in the command file, for the reader who goes looking. */
+	step: string;
+	/** The agent the step dispatches. Recorded for provenance; routing is claudish's. */
+	agent: string;
+}
+
+export interface Workflow {
+	name: string;
+	agents: string[];
+	external: WorkflowStep[];
+}
+
+export const WORKFLOWS: Workflow[] = [
 	{
 		name: "dev",
 		agents: [
 			"dev:stack-detector",
 			"dev:architect",
 			"dev:developer",
-			"dev:test-architect",
+			"dev:qa-engineer",
 			"dev:reviewer",
 		],
+		external: [
+			{ step: "plan review", agent: "dev:architect" },
+			{ step: "code review", agent: "dev:architect" },
+		],
 	},
 	{
 		name: "debug",
 		agents: [
 			"dev:stack-detector",
-			"code-analysis:detective",
+			"code-search:analyze",
 			"dev:debugger",
 			"dev:developer",
 		],
+		external: [],
 	},
 	{
 		name: "investigate",
-		agents: ["code-analysis:detective", "dev:researcher"],
+		agents: ["code-search:analyze", "dev:researcher"],
+		external: [],
 	},
 ];
 
@@ -102,7 +142,7 @@ export const WORKFLOWS: { name: string; agents: string[] }[] = [
  * Agents whose model is a CAPABILITY choice, not a spend choice.
  *
  * The three tiers answer "how much model", and that is the wrong question for an agent that
- * reads images. `designer:design-review` compares a rendered screen against a reference and
+ * reads images. `designer:review` compares a rendered screen against a reference and
  * `designer:ui` audits a screenshot for usability: what they need is the model that SEES
  * best, which is not a point on a cheap-to-smart line and does not move when the preset
  * changes.
@@ -112,12 +152,27 @@ export const WORKFLOWS: { name: string; agents: string[] }[] = [
  * preset's `fallback`, which is a defensible default and an honest one; pinning them to a
  * model id guessed here is neither.
  */
-export const VISION_AGENTS = ["designer:design-review", "designer:ui"] as const;
+export const VISION_AGENTS = ["designer:review", "designer:ui"] as const;
+
+/**
+ * The effort the external slots run at, per preset.
+ *
+ * A preset cannot say WHICH model serves a mate — a catalogue id shipped in this repo goes
+ * stale, which is the whole reason bindings live in a project's own `mates` block. It can say
+ * how hard that work should try, and that half does not depend on which model answers.
+ *
+ * `xhigh` almost everywhere: a slot is reached for the judgement calls — plan review, code
+ * review — and those are the calls worth spending on whichever model takes them. `Sonnet` is
+ * the exception because it is the economy preset, and a preset whose whole point is to spend
+ * less would be lying if the work it sent outside ignored that.
+ */
+const MATE_EFFORT_DEFAULT: Effort = "xhigh";
 
 function preset(
 	name: string,
 	main: ModelsConfig["main"],
 	grades: ModelsConfig["grades"],
+	mateEffort: Effort = MATE_EFFORT_DEFAULT,
 ): ModelsConfig {
 	return {
 		version: 1,
@@ -126,6 +181,7 @@ function preset(
 		grades,
 		agents: { ...DEFAULT_AGENT_GRADES },
 		fallback: "normal",
+		mateEffort,
 	};
 }
 
@@ -248,6 +304,8 @@ export const BUILT_IN_PRESETS: ModelsConfig[] = [
 	// effort is not throttled on top of it. Every routed agent runs sonnet at `xhigh`,
 	// including `cheap` — so the hook still pins the model (a session started on opus does
 	// not leak into its subagents) while the tier table itself makes no distinction.
+	// The one preset whose mates run at `medium` rather than `xhigh`: an economy preset that
+	// spent freely the moment work left Claude Code would not be one.
 	preset(
 		"sonnet-economy",
 		{ model: "sonnet", effort: "xhigh" },
@@ -256,6 +314,7 @@ export const BUILT_IN_PRESETS: ModelsConfig[] = [
 			normal: { model: "sonnet", effort: "xhigh" },
 			cheap: { model: "sonnet", effort: "xhigh" },
 		},
+		"medium",
 	),
 ];