gentle-pi 0.2.6 → 0.2.8

package/README.md

@@ -213,6 +213,7 @@ Behavior:
 
 - `.atl/` is added to `.gitignore` when needed;
 - the registry refreshes on session start;
+- startup refresh is skipped when Pi starts with `--no-skills` / `-ns`, `--no-skill-registry`, or `GENTLE_PI_NO_SKILL_REGISTRY=1`;
 - `/skill-registry:refresh` forces regeneration;
 - a best-effort watcher refreshes when skill files change;
 - `## Compact Rules` wins when present; otherwise the registry extracts compact rules from `## Hard Rules`, `## Critical Rules`, `## Critical Patterns`, `## Voice Rules`, and `## Decision Gates` using bullets, numbered lists, or simple tables.
@@ -245,7 +246,7 @@ Saved at:
 
 Run `/reload` or start a new Pi session after switching persona.
 
-## Model assignment
+## Model and effort assignment
 
 ```text
 /gentle:models
@@ -257,15 +258,15 @@ The modal discovers:
 - user agents in `~/.pi/agent/agents/` and `~/.agents/`;
 - built-in agents from `pi-subagents`.
 
-Recommended model shape:
+Recommended model/effort shape:
 
-| Agent kind                 | Recommended model                                    |
-| -------------------------- | ---------------------------------------------------- |
-| Explore, proposal, archive | Fast and cheap is usually enough.                    |
-| Spec, design, tasks        | Strong reasoning model.                              |
-| Apply                      | Strong coding and tool-use model.                    |
-| Verify / review            | Strong fresh-context model.                          |
-| Tiny utilities             | Inherit active/default model unless they bottleneck. |
+| Agent kind                 | Recommended model                                    | Recommended effort (`thinking`) |
+| -------------------------- | ---------------------------------------------------- | ------------------------------- |
+| Explore, proposal, archive | Fast and cheap is usually enough.                    | `off` to `low`                  |
+| Spec, design, tasks        | Strong reasoning model.                              | `medium` to `high`              |
+| Apply                      | Strong coding and tool-use model.                    | `medium` to `high`              |
+| Verify / review            | Strong fresh-context model.                          | `high`                          |
+| Tiny utilities             | Inherit active/default model unless they bottleneck. | `inherit`                       |
 
 Saved at:
 
@@ -273,18 +274,42 @@ Saved at:
 .pi/gentle-ai/models.json
 ```
 
+Config shape (per agent):
+
+```json
+{
+  "sdd-design": {
+    "model": "anthropic/claude-sonnet-4",
+    "thinking": "high"
+  },
+  "sdd-archive": {
+    "model": "openai/gpt-5-mini"
+  }
+}
+```
+
+Legacy string entries are still accepted and treated as `model`-only config.
+
 ## Commands
 
 | Command                          | What it does                                                 |
 | -------------------------------- | ------------------------------------------------------------ |
 | `/gentle-ai:status`              | Shows package, SDD asset, OpenSpec, and model config status. |
-| `/gentle:models`                 | Opens model assignment UI.                                   |
+| `/gentle:models`                 | Opens model + effort assignment UI.                          |
 | `/gentle:persona`                | Switches persona mode.                                       |
 | `/sdd-init`                      | Initializes or refreshes `openspec/config.yaml`.             |
 | `/gentle-ai:install-sdd`         | Reinstalls SDD assets without overwriting local files.       |
 | `/gentle-ai:install-sdd --force` | Force-refreshes installed SDD assets.                        |
 | `/skill-registry:refresh`        | Regenerates `.atl/skill-registry.md`.                        |
 
+Startup flag:
+
+```text
+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

package/assets/orchestrator.md

@@ -31,6 +31,8 @@ User-facing conversation should stay in the user's language and follow the curre
 
 Subagent-facing prompts should be written in English by default, even when the user speaks Spanish. Translate the user's request into concise English before delegation. This keeps token usage lower and gives built-in/project subagents a consistent operating language without changing the user-facing persona.
 
+Generated artifacts — whether by the parent inline or by subagents — (code, UI copy, comments, identifiers, commit messages, filenames, PR descriptions) default to English, regardless of the user's conversation language. Override only when the user explicitly requests another language for that artifact, or when extending a project whose existing convention is non-English.
+
 Exceptions:
 
 - Preserve exact user quotes, UI copy, error messages, filenames, commands, and domain terms in their original language when they are evidence.

package/extensions/gentle-ai.ts

@@ -101,7 +101,12 @@ const SDD_AGENT_NAMES = [
 ] as const;
 
 type SddAgentName = (typeof SDD_AGENT_NAMES)[number];
-type AgentModelConfig = Record<string, string>;
+type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+interface AgentRoutingEntry {
+	model?: string;
+	thinking?: ThinkingLevel;
+}
+type AgentModelConfig = Record<string, AgentRoutingEntry>;
 type AgentSource = "project" | "user" | "builtin";
 
 interface AgentEntry {
@@ -113,6 +118,16 @@ interface AgentEntry {
 const KEEP_CURRENT = "Keep current";
 const INHERIT_MODEL = "Inherit active/default model";
 const CUSTOM_MODEL = "Custom model id";
+const INHERIT_THINKING = "Inherit effort";
+const THINKING_OPTIONS: (ThinkingLevel | typeof INHERIT_THINKING)[] = [
+	INHERIT_THINKING,
+	"off",
+	"minimal",
+	"low",
+	"medium",
+	"high",
+	"xhigh",
+];
 
 const MODEL_CONTROL_OPTIONS = [
 	KEEP_CURRENT,
@@ -253,6 +268,32 @@ function writePersonaMode(cwd: string, mode: PersonaMode): void {
 	writeFileSync(path, `${JSON.stringify({ mode }, null, 2)}\n`);
 }
 
+function isThinkingLevel(value: unknown): value is ThinkingLevel {
+	return (
+		value === "off" ||
+		value === "minimal" ||
+		value === "low" ||
+		value === "medium" ||
+		value === "high" ||
+		value === "xhigh"
+	);
+}
+
+function normalizeRoutingEntry(value: unknown): AgentRoutingEntry | undefined {
+	if (typeof value === "string") {
+		const model = value.trim();
+		return model.length > 0 ? { model } : undefined;
+	}
+	if (!isRecord(value)) return undefined;
+	const model =
+		typeof value.model === "string" && value.model.trim().length > 0
+			? value.model.trim()
+			: undefined;
+	const thinking = isThinkingLevel(value.thinking) ? value.thinking : undefined;
+	if (!model && !thinking) return undefined;
+	return { model, thinking };
+}
+
 function readModelConfig(cwd: string): AgentModelConfig {
 	const path = modelConfigPath(cwd);
 	if (!existsSync(path)) return {};
@@ -261,9 +302,8 @@ function readModelConfig(cwd: string): AgentModelConfig {
 		if (!isRecord(parsed)) return {};
 		const config: AgentModelConfig = {};
 		for (const [name, value] of Object.entries(parsed)) {
-			if (typeof value === "string" && value.trim().length > 0) {
-				config[name] = value.trim();
-			}
+			const entry = normalizeRoutingEntry(value);
+			if (entry) config[name] = entry;
 		}
 		return config;
 	} catch {
@@ -274,12 +314,23 @@ function readModelConfig(cwd: string): AgentModelConfig {
 function writeModelConfig(cwd: string, config: AgentModelConfig): void {
 	const path = modelConfigPath(cwd);
 	mkdirSync(dirname(path), { recursive: true });
-	writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`);
+	const cleaned: AgentModelConfig = {};
+	for (const [name, value] of Object.entries(config)) {
+		const entry = normalizeRoutingEntry(value);
+		if (entry) cleaned[name] = entry;
+	}
+	writeFileSync(path, `${JSON.stringify(cleaned, null, 2)}\n`);
+}
+
+function cloneModelConfig(config: AgentModelConfig): AgentModelConfig {
+	return Object.fromEntries(
+		Object.entries(config).map(([name, entry]) => [name, { ...entry }]),
+	);
 }
 
-function updateFrontmatterModel(
+function updateFrontmatterRouting(
 	content: string,
-	model: string | undefined,
+	entry: AgentRoutingEntry | undefined,
 ): string {
 	if (!content.startsWith("---\n")) return content;
 	const endIndex = content.indexOf("\n---", 4);
@@ -288,14 +339,19 @@ function updateFrontmatterModel(
 	const body = content.slice(endIndex);
 	const lines = frontmatter
 		.split("\n")
-		.filter((line) => !line.startsWith("model:"));
-	if (model !== undefined) {
+		.filter(
+			(line) => !line.startsWith("model:") && !line.startsWith("thinking:"),
+		);
+	const toInsert: string[] = [];
+	if (entry?.model) toInsert.push(`model: ${entry.model}`);
+	if (entry?.thinking) toInsert.push(`thinking: ${entry.thinking}`);
+	if (toInsert.length > 0) {
 		const descriptionIndex = lines.findIndex((line) =>
 			line.startsWith("description:"),
 		);
 		const insertIndex =
 			descriptionIndex >= 0 ? descriptionIndex + 1 : Math.min(1, lines.length);
-		lines.splice(insertIndex, 0, `model: ${model}`);
+		lines.splice(insertIndex, 0, ...toInsert);
 	}
 	return `---\n${lines.join("\n")}${body}`;
 }
@@ -372,7 +428,7 @@ function projectSettingsPath(cwd: string): string {
 function updateBuiltinModelOverride(
 	cwd: string,
 	name: string,
-	model: string | undefined,
+	entry: AgentRoutingEntry | undefined,
 ): boolean {
 	const path = projectSettingsPath(cwd);
 	let settings: Record<string, unknown> = {};
@@ -393,8 +449,10 @@ function updateBuiltinModelOverride(
 	const current = isRecord(agentOverrides[name])
 		? { ...agentOverrides[name] }
 		: {};
-	if (model === undefined) delete current.model;
-	else current.model = model;
+	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)
@@ -414,9 +472,9 @@ function applyModelConfig(
 	let updated = 0;
 	let skipped = 0;
 	for (const agent of listDiscoverableAgents(cwd)) {
-		const model = config[agent.name];
+		const entry = config[agent.name];
 		if (agent.source === "builtin") {
-			if (updateBuiltinModelOverride(cwd, agent.name, model)) updated += 1;
+			if (updateBuiltinModelOverride(cwd, agent.name, entry)) updated += 1;
 			else skipped += 1;
 			continue;
 		}
@@ -425,7 +483,7 @@ function applyModelConfig(
 			continue;
 		}
 		const original = readFileSync(agent.filePath, "utf8");
-		const next = updateFrontmatterModel(original, model);
+		const next = updateFrontmatterRouting(original, entry);
 		if (next === original) {
 			skipped += 1;
 			continue;
@@ -437,9 +495,12 @@ function applyModelConfig(
 }
 
 function describeModelConfig(cwd: string, config: AgentModelConfig): string[] {
-	return listDiscoverableAgents(cwd).map(
-		(agent) => `${agent.name}: ${config[agent.name] ?? "inherit"}`,
-	);
+	return listDiscoverableAgents(cwd).map((agent) => {
+		const entry = config[agent.name];
+		const model = entry?.model ?? "inherit";
+		const thinking = entry?.thinking ?? "inherit";
+		return `${agent.name}: model=${model}, effort=${thinking}`;
+	});
 }
 
 async function getPiModelOptions(ctx: ExtensionContext): Promise<string[]> {
@@ -458,28 +519,33 @@ interface OverlayComponent {
 
 type ModelPanelResult =
 	| { type: "save"; config: AgentModelConfig }
-	| { type: "custom"; agent: string | "all" }
+	| { type: "custom"; agent: string | "all"; config: AgentModelConfig }
 	| { type: "cancel" };
 
 const SET_ALL_AGENTS = "Set all agents";
 
 class SddModelPanel implements OverlayComponent {
 	private cursor = 0;
-	private mode: "agents" | "models" = "agents";
+	private mode: "agents" | "models" | "effort" = "agents";
 	private selectedRow = SET_ALL_AGENTS;
 	private modelCursor = 0;
+	private effortCursor = 0;
 	private query = "";
 	private readonly draft: AgentModelConfig;
 	private readonly rows: string[];
+	private readonly modelOptions: string[];
+	private readonly done: (result: ModelPanelResult) => void;
 
 	constructor(
 		initialConfig: AgentModelConfig,
-		private readonly modelOptions: string[],
+		modelOptions: string[],
 		agents: string[],
-		private readonly done: (result: ModelPanelResult) => void,
+		done: (result: ModelPanelResult) => void,
 	) {
-		this.draft = { ...initialConfig };
+		this.draft = cloneModelConfig(initialConfig);
 		this.rows = [SET_ALL_AGENTS, ...agents];
+		this.modelOptions = modelOptions;
+		this.done = done;
 	}
 
 	invalidate(): void {}
@@ -489,13 +555,17 @@ class SddModelPanel implements OverlayComponent {
 			this.handleModelInput(data);
 			return;
 		}
+		if (this.mode === "effort") {
+			this.handleEffortInput(data);
+			return;
+		}
 		this.handleAgentInput(data);
 	}
 
 	render(width: number): string[] {
-		return this.mode === "models"
-			? this.renderModelPicker(width)
-			: this.renderAgentList(width);
+		if (this.mode === "models") return this.renderModelPicker(width);
+		if (this.mode === "effort") return this.renderEffortPicker(width);
+		return this.renderAgentList(width);
 	}
 
 	private handleAgentInput(data: string): void {
@@ -517,13 +587,21 @@ class SddModelPanel implements OverlayComponent {
 			return;
 		}
 		if (data === "i") {
-			this.applySelection(undefined);
+			this.applyInherit();
+			return;
+		}
+		if (data === "e") {
+			this.selectedRow = this.rows[this.cursor] ?? SET_ALL_AGENTS;
+			this.mode = "effort";
+			this.effortCursor = 0;
 			return;
 		}
 		if (data === "c") {
 			const row = this.rows[this.cursor];
-			if (row === SET_ALL_AGENTS) this.done({ type: "custom", agent: "all" });
-			else if (row) this.done({ type: "custom", agent: row });
+			if (row === SET_ALL_AGENTS)
+				this.done({ type: "custom", agent: "all", config: this.draft });
+			else if (row)
+				this.done({ type: "custom", agent: row, config: this.draft });
 			return;
 		}
 		if (!matchesKey(data, "return")) return;
@@ -578,6 +656,7 @@ class SddModelPanel implements OverlayComponent {
 				this.done({
 					type: "custom",
 					agent: this.selectedRow === SET_ALL_AGENTS ? "all" : this.selectedRow,
+					config: this.draft,
 				});
 				return;
 			}
@@ -585,7 +664,9 @@ class SddModelPanel implements OverlayComponent {
 				this.mode = "agents";
 				return;
 			}
-			this.applySelection(selected === INHERIT_MODEL ? undefined : selected);
+			this.applyModelSelection(
+				selected === INHERIT_MODEL ? undefined : selected,
+			);
 			this.mode = "agents";
 			return;
 		}
@@ -595,18 +676,52 @@ class SddModelPanel implements OverlayComponent {
 		}
 	}
 
-	private applySelection(model: string | undefined): void {
+	private applyModelSelection(model: string | undefined): void {
 		const row = this.rows[this.cursor];
 		if (row === SET_ALL_AGENTS) {
-			for (const name of this.rows.slice(1)) {
-				if (model === undefined) delete this.draft[name];
-				else this.draft[name] = model;
-			}
+			for (const name of this.rows.slice(1)) this.setModel(name, model);
 			return;
 		}
 		if (!row) return;
-		if (model === undefined) delete this.draft[row];
-		else this.draft[row] = model;
+		this.setModel(row, model);
+	}
+
+	private applyThinkingSelection(thinking: ThinkingLevel | undefined): void {
+		const row = this.selectedRow;
+		if (row === SET_ALL_AGENTS) {
+			for (const name of this.rows.slice(1)) this.setThinking(name, thinking);
+			return;
+		}
+		this.setThinking(row, thinking);
+	}
+
+	private applyInherit(): void {
+		const row = this.rows[this.cursor];
+		if (row === SET_ALL_AGENTS) {
+			for (const name of this.rows.slice(1)) this.clearEntry(name);
+			return;
+		}
+		if (row) this.clearEntry(row);
+	}
+
+	private setModel(name: string, model: string | undefined): void {
+		const current = this.draft[name] ?? {};
+		if (model === undefined) delete current.model;
+		else current.model = model;
+		if (!current.model && !current.thinking) delete this.draft[name];
+		else this.draft[name] = current;
+	}
+
+	private setThinking(name: string, thinking: ThinkingLevel | undefined): void {
+		const current = this.draft[name] ?? {};
+		if (thinking === undefined) delete current.thinking;
+		else current.thinking = thinking;
+		if (!current.model && !current.thinking) delete this.draft[name];
+		else this.draft[name] = current;
+	}
+
+	private clearEntry(name: string): void {
+		delete this.draft[name];
 	}
 
 	private filteredModelOptions(): string[] {
@@ -644,7 +759,7 @@ class SddModelPanel implements OverlayComponent {
 		lines.push("");
 		lines.push(
 			line(
-				"j/k: navigate • enter: change model / confirm • i: inherit • c: custom • ctrl+s: save • esc: back",
+				"j/k: navigate • enter: change model / confirm • e: change effort • i: inherit all • c: custom model • ctrl+s: save • esc: back",
 			),
 		);
 		return lines;
@@ -680,17 +795,70 @@ class SddModelPanel implements OverlayComponent {
 		return lines;
 	}
 
+	private handleEffortInput(data: string): void {
+		if (matchesKey(data, "ctrl+c")) {
+			this.done({ type: "cancel" });
+			return;
+		}
+		if (matchesKey(data, "escape")) {
+			this.mode = "agents";
+			return;
+		}
+		if (matchesKey(data, "down") || data === "j") {
+			this.effortCursor = Math.min(
+				Math.max(0, THINKING_OPTIONS.length - 1),
+				this.effortCursor + 1,
+			);
+			return;
+		}
+		if (matchesKey(data, "up") || data === "k") {
+			this.effortCursor = Math.max(0, this.effortCursor - 1);
+			return;
+		}
+		if (!matchesKey(data, "return")) return;
+		const selected = THINKING_OPTIONS[this.effortCursor];
+		if (selected === INHERIT_THINKING) this.applyThinkingSelection(undefined);
+		else this.applyThinkingSelection(selected);
+		this.mode = "agents";
+	}
+
+	private renderEffortPicker(width: number): string[] {
+		const lines: string[] = [];
+		const line = (text = "") =>
+			truncateToWidth(text, Math.max(1, width), "…", true);
+		lines.push(line(`Select effort for ${this.selectedRow}`));
+		lines.push("");
+		for (let i = 0; i < THINKING_OPTIONS.length; i++) {
+			const focused = i === this.effortCursor;
+			lines.push(line(`${focused ? "▸" : " "} ${THINKING_OPTIONS[i]}`));
+		}
+		lines.push("");
+		lines.push(line("j/k: navigate • enter: select • esc: back"));
+		return lines;
+	}
+
 	private renderSetAllLabel(row: string): string {
-		const values = this.rows
+		const models = this.rows
+			.slice(1)
+			.map((name) => this.draft[name]?.model ?? "inherit");
+		const efforts = this.rows
 			.slice(1)
-			.map((name) => this.draft[name] ?? "inherit");
-		const first = values[0] ?? "inherit";
-		const allSame = values.every((value) => value === first);
-		return `${row.padEnd(20)} ${allSame ? first : "mixed"}`;
+			.map((name) => this.draft[name]?.thinking ?? "inherit");
+		const firstModel = models[0] ?? "inherit";
+		const firstEffort = efforts[0] ?? "inherit";
+		const modelLabel = models.every((value) => value === firstModel)
+			? firstModel
+			: "mixed";
+		const effortLabel = efforts.every((value) => value === firstEffort)
+			? firstEffort
+			: "mixed";
+		return `${row.padEnd(20)} model=${modelLabel}, effort=${effortLabel}`;
 	}
 
 	private renderAgentLabel(row: string): string {
-		return `${row.padEnd(20)} ${this.draft[row] ?? "inherit"}`;
+		const model = this.draft[row]?.model ?? "inherit";
+		const effort = this.draft[row]?.thinking ?? "inherit";
+		return `${row.padEnd(20)} model=${model}, effort=${effort}`;
 	}
 }
 
@@ -719,8 +887,11 @@ async function handleModelsCommand(ctx: ExtensionContext): Promise<void> {
 	let config = readModelConfig(ctx.cwd);
 	let result = await showSddModelPanel(ctx, config);
 	while (result.type === "custom") {
+		config = cloneModelConfig(result.config);
 		const current =
-			result.agent === "all" ? "inherit" : (config[result.agent] ?? "inherit");
+			result.agent === "all"
+				? "inherit"
+				: (config[result.agent]?.model ?? "inherit");
 		const custom = await ctx.ui.input(
 			`${result.agent === "all" ? "all agents" : result.agent} custom model id`,
 			current === "inherit" ? "provider/model" : current,
@@ -729,11 +900,22 @@ async function handleModelsCommand(ctx: ExtensionContext): Promise<void> {
 		const trimmed = custom.trim();
 		if (trimmed.length > 0) {
 			if (result.agent === "all") {
-				config = Object.fromEntries(
-					listDiscoverableAgents(ctx.cwd).map((agent) => [agent.name, trimmed]),
-				);
+				const next: AgentModelConfig = { ...config };
+				for (const agent of listDiscoverableAgents(ctx.cwd)) {
+					next[agent.name] = {
+						...(next[agent.name] ?? {}),
+						model: trimmed,
+					};
+				}
+				config = next;
 			} else {
-				config = { ...config, [result.agent]: trimmed };
+				config = {
+					...config,
+					[result.agent]: {
+						...(config[result.agent] ?? {}),
+						model: trimmed,
+					},
+				};
 			}
 		}
 		result = await showSddModelPanel(ctx, config);

package/extensions/skill-registry.ts

@@ -21,6 +21,8 @@ const EXCLUDE_PREFIXES = ["sdd-"];
 const ATL_IGNORE_ENTRY = ".atl/";
 const WATCH_DEBOUNCE_MS = 500;
 const REGISTRY_SCHEMA_VERSION = 4;
+const NO_SKILL_REGISTRY_FLAG = "no-skill-registry";
+const NO_SKILL_REGISTRY_ENV = "GENTLE_PI_NO_SKILL_REGISTRY";
 const LEGACY_PROJECT_REGISTRY_REL_PATH = ".pi/extensions/skill-registry.ts";
 const LEGACY_PROJECT_REGISTRY_DISABLED_REL_PATH =
 	".pi/extensions/skill-registry.ts.disabled";
@@ -410,6 +412,26 @@ function regenerateRegistry(cwd: string, force: boolean): RegenResult {
 
 const watchedCwds = new Set<string>();
 
+function isTruthyEnv(value: string | undefined): boolean {
+	return value === "1" || value === "true" || value === "yes" || value === "on";
+}
+
+function hasCliArg(args: string[], ...names: string[]): boolean {
+	return args.some((arg) => names.includes(arg));
+}
+
+function shouldSkipSkillRegistryStartup(
+	pi: Pick<ExtensionAPI, "getFlag">,
+	argv = process.argv.slice(2),
+	env = process.env,
+): boolean {
+	return (
+		pi.getFlag(NO_SKILL_REGISTRY_FLAG) === true ||
+		isTruthyEnv(env[NO_SKILL_REGISTRY_ENV]) ||
+		hasCliArg(argv, "--no-skills", "-ns")
+	);
+}
+
 function startSkillRegistryWatcher(cwd: string, notify: (message: string) => void): void {
 	if (watchedCwds.has(cwd)) return;
 	watchedCwds.add(cwd);
@@ -444,10 +466,18 @@ export const __testing = {
 	extractTriggerDescription,
 	uniqueExistingDirs,
 	dedupeBySkillName,
+	shouldSkipSkillRegistryStartup,
 };
 
 export default function (pi: ExtensionAPI) {
+	pi.registerFlag(NO_SKILL_REGISTRY_FLAG, {
+		description: "Skip the Gentle AI skill registry refresh and watcher on startup.",
+		type: "boolean",
+		default: false,
+	});
+
 	pi.on("session_start", async (_event, ctx) => {
+		if (shouldSkipSkillRegistryStartup(pi)) return;
 		try {
 			ensureAtlIgnored(ctx.cwd);
 			const quarantinedLegacy = quarantineLegacyProjectRegistry(ctx.cwd);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gentle-pi",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "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",
@@ -32,7 +32,8 @@
     "README.md"
   ],
   "scripts": {
-    "test": "node --experimental-strip-types --test tests/*.test.ts",
+    "test": "node --experimental-strip-types --test tests/*.test.ts && pnpm run test:harness",
+    "test:harness": "node --experimental-strip-types tests/runtime-harness.mjs",
     "prepack": "pnpm test && node scripts/verify-package-files.mjs",
     "prepublishOnly": "pnpm test && node scripts/verify-package-files.mjs"
   },

package/tests/runtime-harness.mjs

@@ -0,0 +1,292 @@
+#!/usr/bin/env node
+import assert from "node:assert/strict";
+import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+const EXTENSIONS = [
+	"extensions/gentle-ai.ts",
+	"extensions/skill-registry.ts",
+	"extensions/sdd-init.ts",
+	"extensions/startup-banner.ts",
+];
+
+const EXPECTED_COMMANDS = [
+	"gentle-ai:install-sdd",
+	"gentle:models",
+	"gentle-ai:models",
+	"gentleman:models",
+	"gentle:persona",
+	"gentle-ai:persona",
+	"gentleman:persona",
+	"gentle-ai:status",
+	"sdd-init",
+	"skill-registry:refresh",
+];
+
+function createPi() {
+	const hooks = new Map();
+	const commands = new Map();
+	const flags = new Map();
+	const flagValues = new Map([["no-skill-registry", true]]);
+
+	const pi = {
+		on(name, handler) {
+			const list = hooks.get(name) ?? [];
+			list.push(handler);
+			hooks.set(name, list);
+		},
+		registerCommand(name, definition) {
+			commands.set(name, definition);
+		},
+		registerFlag(name, definition) {
+			flags.set(name, definition);
+		},
+		getFlag(name) {
+			return flagValues.get(name) ?? false;
+		},
+		setFlag(name, value) {
+			flagValues.set(name, value);
+		},
+		getCommands() {
+			return Array.from(commands, ([name, definition]) => ({ name, ...definition }));
+		},
+		getAllTools() {
+			return [
+				{ name: "read" },
+				{ name: "bash" },
+				{ name: "edit" },
+				{ name: "write" },
+			];
+		},
+	};
+
+	return { pi, hooks, commands, flags };
+}
+
+function createUi() {
+	const notifications = [];
+	return {
+		notifications,
+		notify(message, level = "info") {
+			notifications.push({ message, level });
+		},
+		async confirm() {
+			return false;
+		},
+		async select(_label, options) {
+			return options[0];
+		},
+		async input(_label, placeholder) {
+			return placeholder;
+		},
+		custom() {
+			return Promise.resolve({ type: "cancel" });
+		},
+	};
+}
+
+function createCtx(cwd, hasUI = false) {
+	return {
+		cwd,
+		hasUI,
+		ui: createUi(),
+		modelRegistry: {
+			async getAvailable() {
+				return [];
+			},
+		},
+	};
+}
+
+async function tempWorkspace() {
+	return mkdtemp(join(tmpdir(), "gentle-pi-runtime-"));
+}
+
+async function loadExtensions(pi) {
+	for (const [index, rel] of EXTENSIONS.entries()) {
+		const mod = await import(`${pathToFileURL(join(ROOT, rel)).href}?runtime-harness=${index}`);
+		assert.equal(typeof mod.default, "function", `${rel} must export a default function`);
+		mod.default(pi);
+	}
+}
+
+async function run() {
+	const { pi, hooks, commands, flags } = createPi();
+	await loadExtensions(pi);
+
+	for (const name of EXPECTED_COMMANDS) {
+		assert.ok(commands.has(name), `missing command ${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("before_agent_start"), "missing before_agent_start hook");
+	assert.ok(hooks.has("tool_call"), "missing tool_call hook");
+
+	const promptCwd = await tempWorkspace();
+	try {
+		const promptHook = hooks.get("before_agent_start")[0];
+		const promptResult = promptHook({ systemPrompt: "base" }, createCtx(promptCwd));
+		assert.match(promptResult.systemPrompt, /base/);
+		assert.match(promptResult.systemPrompt, /el Gentleman/);
+	} finally {
+		await rm(promptCwd, { recursive: true, force: true });
+	}
+
+	const toolCwd = await tempWorkspace();
+	try {
+		const toolHook = hooks.get("tool_call")[0];
+		assert.equal(await toolHook({ toolName: "bash", input: { command: "git status" } }, createCtx(toolCwd)), undefined);
+		const denied = await toolHook({ toolName: "bash", input: { command: "rm -rf /" } }, createCtx(toolCwd));
+		assert.equal(denied.block, true);
+		assert.match(denied.reason, /destructive/);
+		const needsConfirm = await toolHook({ toolName: "bash", input: { command: "git push" } }, createCtx(toolCwd));
+		assert.equal(needsConfirm.block, true);
+		assert.match(needsConfirm.reason, /confirmation/);
+	} finally {
+		await rm(toolCwd, { recursive: true, force: true });
+	}
+
+	const noUiCwd = await tempWorkspace();
+	try {
+		for (const handler of hooks.get("session_start")) {
+			await handler({ reason: "startup" }, createCtx(noUiCwd, false));
+		}
+	} finally {
+		await rm(noUiCwd, { recursive: true, force: true });
+	}
+
+	const installCwd = await tempWorkspace();
+	try {
+		const ctx = createCtx(installCwd, true);
+		await commands.get("gentle-ai:install-sdd").handler("", ctx);
+		assert.match(ctx.ui.notifications.at(-1).message, /SDD assets installed/);
+	} finally {
+		await rm(installCwd, { recursive: true, force: true });
+	}
+
+	const sddCwd = await tempWorkspace();
+	try {
+		const ctx = createCtx(sddCwd, true);
+		await commands.get("sdd-init").handler("", ctx);
+		assert.match(ctx.ui.notifications.at(-1).message, /Wrote openspec\/config\.yaml/);
+	} finally {
+		await rm(sddCwd, { recursive: true, force: true });
+	}
+
+	const modelsCwd = await tempWorkspace();
+	try {
+		await mkdir(join(modelsCwd, ".pi", "agents"), { recursive: true });
+		await mkdir(
+			join(modelsCwd, ".pi", "npm", "node_modules", "pi-subagents", "agents"),
+			{ recursive: true },
+		);
+		await writeFile(
+			join(
+				modelsCwd,
+				".pi",
+				"npm",
+				"node_modules",
+				"pi-subagents",
+				"agents",
+				"worker.md",
+			),
+			`---\nname: worker\ndescription: Builtin worker\n---\n`,
+		);
+		await writeFile(
+			join(modelsCwd, ".pi", "agents", "sdd-apply.md"),
+			`---\nname: sdd-apply\ndescription: Apply phase\n---\n\nbody\n`,
+		);
+		await mkdir(join(modelsCwd, ".pi", "gentle-ai"), { recursive: true });
+		await writeFile(
+			join(modelsCwd, ".pi", "gentle-ai", "models.json"),
+			JSON.stringify({ "sdd-apply": "openai/gpt-5" }, null, 2),
+		);
+
+		const ctx = createCtx(modelsCwd, true);
+		await hooks.get("session_start")[0]({ reason: "startup" }, ctx);
+		const legacyAppliedAgent = await readFile(
+			join(modelsCwd, ".pi", "agents", "sdd-apply.md"),
+			"utf8",
+		);
+		assert.match(legacyAppliedAgent, /model: openai\/gpt-5/);
+		assert.doesNotMatch(legacyAppliedAgent, /thinking:/);
+
+		ctx.ui.custom = () =>
+			Promise.resolve({
+				type: "save",
+				config: {
+					"sdd-apply": { model: "openai/gpt-5", thinking: "high" },
+					worker: { model: "openai/gpt-5-mini", thinking: "low" },
+				},
+			});
+		await commands.get("gentle:models").handler("", ctx);
+
+		const savedConfig = JSON.parse(
+			await readFile(join(modelsCwd, ".pi", "gentle-ai", "models.json"), "utf8"),
+		);
+		assert.deepEqual(savedConfig["sdd-apply"], {
+			model: "openai/gpt-5",
+			thinking: "high",
+		});
+
+		const applyAgent = await readFile(
+			join(modelsCwd, ".pi", "agents", "sdd-apply.md"),
+			"utf8",
+		);
+		assert.match(applyAgent, /model: openai\/gpt-5/);
+		assert.match(applyAgent, /thinking: high/);
+
+		const settings = JSON.parse(
+			await readFile(join(modelsCwd, ".pi", "settings.json"), "utf8"),
+		);
+		assert.equal(
+			settings.subagents.agentOverrides.worker.model,
+			"openai/gpt-5-mini",
+		);
+		assert.equal(settings.subagents.agentOverrides.worker.thinking, "low");
+
+		let customPanelCalls = 0;
+		ctx.ui.input = async () => "custom/provider-model";
+		ctx.ui.custom = (factory) =>
+			new Promise((resolve) => {
+				customPanelCalls += 1;
+				const panel = factory(null, null, null, resolve);
+				if (customPanelCalls === 1) {
+					panel.handleInput("e"); // effort picker for all agents
+					for (let i = 0; i < 4; i++) panel.handleInput("j"); // medium
+					panel.handleInput("\r");
+					panel.handleInput("c"); // custom model from the same unsaved draft
+					return;
+				}
+				panel.handleInput("\u0013"); // ctrl+s saves the draft reopened after custom model input
+			});
+		await commands.get("gentle:models").handler("", ctx);
+
+		const customSavedConfig = JSON.parse(
+			await readFile(join(modelsCwd, ".pi", "gentle-ai", "models.json"), "utf8"),
+		);
+		assert.deepEqual(customSavedConfig["sdd-apply"], {
+			model: "custom/provider-model",
+			thinking: "medium",
+		});
+	} finally {
+		await rm(modelsCwd, { recursive: true, force: true });
+	}
+
+	const registryCwd = await tempWorkspace();
+	try {
+		const ctx = createCtx(registryCwd, true);
+		await commands.get("skill-registry:refresh").handler("", ctx);
+		assert.match(ctx.ui.notifications.at(-1).message, /Skill registry:/);
+	} finally {
+		await rm(registryCwd, { recursive: true, force: true });
+	}
+}
+
+run().catch((error) => {
+	console.error(error);
+	process.exitCode = 1;
+});

package/tests/skill-registry.test.ts

@@ -112,3 +112,17 @@ test("uniqueExistingDirs normalizes duplicates and ignores missing roots", () =>
 
 	assert.deepEqual(__testing.uniqueExistingDirs([existing, join(root, "skills/"), join(root, "missing")]), [existing]);
 });
+
+test("startup skip honors no skill registry controls", () => {
+	const enabled = { getFlag: () => true };
+	const disabled = { getFlag: () => false };
+
+	assert.equal(__testing.shouldSkipSkillRegistryStartup(enabled, [], {}), true);
+	assert.equal(__testing.shouldSkipSkillRegistryStartup(disabled, ["--no-skills"], {}), true);
+	assert.equal(__testing.shouldSkipSkillRegistryStartup(disabled, ["-ns"], {}), true);
+	assert.equal(
+		__testing.shouldSkipSkillRegistryStartup(disabled, [], { GENTLE_PI_NO_SKILL_REGISTRY: "1" }),
+		true,
+	);
+	assert.equal(__testing.shouldSkipSkillRegistryStartup(disabled, [], {}), false);
+});