gentle-pi 0.1.3 → 0.1.12

package/README.md

@@ -1,66 +1,226 @@
-# Gentle Pi
+# el Gentleman
 
-`gentle-pi` is an opinionated Pi package for controlled autonomy: explicit Gentle Pi identity, SDD/OpenSpec workflow, strict TDD guidance, subagent-ready phase assets, review workload discipline, and a senior-architect persona.
+`gentle-pi` installs **el Gentleman** into Pi: a controlled-development harness with a senior architect persona, SDD/OpenSpec phase discipline, strict TDD evidence, subagent orchestration, and review-workload protection.
 
-It does not include persistent memory. Install a separate memory package, such as a future Engram package, when you want long-term recall.
+Install it when you want Pi to stop behaving like a generic chatbot and start acting like a disciplined development harness.
 
-## Install
+## Quick start
 
 ```bash
 pi install npm:gentle-pi
 ```
 
-For local development from this repo:
+Recommended companion packages:
 
 ```bash
-pi install ./pi-packages/gentle-ai
+pi install npm:pi-subagents
+pi install npm:pi-intercom
+```
+
+Then start Pi in your project:
+
+```bash
+pi
+```
+
+On session start, `gentle-pi` automatically installs SDD assets into the project without overwriting local edits.
+
+## What you get
+
+| Capability | What it does |
+|---|---|
+| el Gentleman identity | Answers as a Pi-specific harness, not a generic assistant. Defaults to the `gentleman` persona and can switch to `neutral`. |
+| SDD/OpenSpec routing | Small work stays inline, context-heavy work delegates, large/risky work uses SDD artifacts. |
+| SDD phase agents | Installs `sdd-init`, `sdd-explore`, `sdd-proposal`, `sdd-spec`, `sdd-design`, `sdd-tasks`, `sdd-apply`, `sdd-verify`, and `sdd-archive`. |
+| Strict TDD support | Preserves RED → GREEN → TRIANGULATE → REFACTOR evidence and verify-time compliance checks. |
+| Review workload guard | Forecasts large diffs and recommends chained PRs or explicit `size:exception`. |
+| Model assignment UI | Opens a modal to assign Pi models to project, user, and built-in agents, with SDD agents shown first. |
+| Foundation skills | Adds PR, issue, chained-PR, comment, docs, work-unit, and Judgment Day skills. |
+| Safety policy | Blocks destructive shell actions unless there is explicit user approval. |
+
+## Core commands
+
+```text
+/gentle-ai:status          Show package, SDD asset, OpenSpec, and model config status.
+/gentleman:models          Open the per-agent model assignment modal.
+/gentle-ai:models          Compatibility alias that points to /gentleman:models.
+/gentleman:persona         Switch between gentleman and neutral personas.
+/gentle-ai:persona         Compatibility alias that points to /gentleman:persona.
+/sdd-init                  Bootstrap or refresh openspec/config.yaml.
+/gentle-ai:install-sdd     Reinstall SDD assets without overwriting local files.
+/gentle-ai:install-sdd --force
+                           Force-refresh installed SDD assets.
+```
+
+## Switch persona
+
+Default persona: `gentleman`.
+
+Run:
+
+```text
+/gentleman:persona
+```
+
+Available modes:
+
+| Persona | Behavior |
+|---|---|
+| `gentleman` | Teaching-oriented senior architect persona with Rioplatense Spanish/voseo when the user writes Spanish. |
+| `neutral` | Same senior architect discipline and teaching philosophy, but with warm professional language and no regional expressions. |
+
+Saved config:
+
+```text
+.pi/gentle-ai/persona.json
+```
+
+Run `/reload` or start a new Pi session after switching if the current session already injected the previous persona.
+
+## Assign models to agents
+
+Run:
+
+```text
+/gentleman:models
+```
+
+This opens a modal similar to Gentle-AI's model picker. It discovers Pi subagents from project, user, and built-in sources, with SDD agents sorted first:
+
+```text
+Assign Models to Agents
+
+Current assignments:
+
+▸ Set all agents       mixed
+  sdd-init             inherit
+  sdd-explore          openai-codex/gpt-5.5
+  sdd-proposal         openai-codex/gpt-5.5
+  sdd-spec             anthropic/claude-sonnet-4
+  sdd-design           anthropic/claude-sonnet-4
+  sdd-tasks            anthropic/claude-sonnet-4
+  sdd-apply            anthropic/claude-sonnet-4
+  sdd-verify           google/gemini-3-pro
+  sdd-archive          inherit
+  delegate             inherit
+  my-custom-agent      anthropic/claude-sonnet-4
+
+Continue
+← Back
+
+j/k: navigate • enter: change model / confirm • i: inherit • c: custom • ctrl+s: save • esc: back
 ```
 
-## What it loads
+Model choices come from Pi itself via the active model registry. The modal also supports custom model IDs for advanced setups.
+
+The modal covers:
+
+- project agents from `.pi/agents/` and `.agents/`;
+- user agents from `~/.pi/agent/agents/` and `~/.agents/`;
+- built-in `pi-subagents` agents.
 
-- `extensions/gentle-ai.ts` — injects the parent-session Gentle AI orchestrator, auto-installs SDD assets non-destructively, registers `/gentle-ai:*` commands, and blocks high-risk shell commands.
-- `extensions/sdd-init.ts` — registers `/sdd-init` to bootstrap `openspec/config.yaml`.
-- `extensions/skill-registry.ts` — registers `/skill-registry:refresh` and maintains `.atl/skill-registry.md` from compact skill rules.
-- `skills/gentle-ai` — compact rules for Gentle AI orchestration.
-- `skills/branch-pr`, `skills/chained-pr`, `skills/work-unit-commits`, `skills/judgment-day`, `skills/cognitive-doc-design`, `skills/comment-writer`, and `skills/issue-creation` — foundation skills ported from Gentle-AI.
-- `prompts/` — reusable prompt templates with Gentle-prefixed names (`/gcl`, `/gis`, `/gpr`, `/gwr`) to avoid collisions with project prompts.
-- `assets/orchestrator.md` — parent-session SDD orchestration contract adapted from Gentle-AI.
-- `assets/support` — strict TDD apply/verify support files copied to `.pi/gentle-ai/support/`.
-- `assets/agents` and `assets/chains` — SDD assets auto-installed into projects that use `pi-subagents`.
+Small recommendation in English:
 
-## First run
+| Agent kind | Recommended model shape |
+|---|---|
+| Exploration, proposal, archive | Fast and cheap is usually enough. |
+| Spec, design, tasks | Strong reasoning model, because these phases shape the implementation. |
+| Apply | Strong coding model with good tool-use reliability. |
+| Verify / review agents | Strongest fresh-context model you can afford; verification benefits from independence. |
+| Tiny utility agents | Inherit the active/default model unless they become a bottleneck. |
+
+Saved config:
+
+```text
+.pi/gentle-ai/models.json
+```
 
-After installing, open Pi and start working. The package auto-installs SDD subagent assets into the current project when the session starts, without overwriting existing files.
+Applied configuration:
+
+```text
+.pi/agents/*.md                 # project/user markdown agents
+.pi/settings.json               # project overrides for built-in pi-subagents agents
+```
+
+Use `Inherit active/default model` to remove an agent override.
+
+## Installed project files
+
+`gentle-pi` installs these project-local assets on session start:
+
+```text
+.pi/agents/sdd-*.md
+.pi/chains/sdd-*.chain.md
+.pi/gentle-ai/support/strict-tdd.md
+.pi/gentle-ai/support/strict-tdd-verify.md
+```
 
-Useful diagnostics/recovery commands:
+Existing files are skipped. Your local edits remain unless you explicitly run:
 
 ```text
-/gentle-ai:status
-/sdd-init
 /gentle-ai:install-sdd --force
 ```
 
-`/gentle-ai:install-sdd` is a recovery command. The normal path is automatic. It copies SDD agents to `.pi/agents/` and chains to `.pi/chains/`; existing files are skipped unless `--force` is passed.
+## Package contents
+
+| Path | Purpose |
+|---|---|
+| `extensions/gentle-ai.ts` | Injects el Gentleman, installs assets, provides commands, applies model config, blocks unsafe shell commands. |
+| `extensions/sdd-init.ts` | Registers `/sdd-init` for OpenSpec project initialization. |
+| `extensions/skill-registry.ts` | Registers `/skill-registry:refresh` and maintains `.atl/skill-registry.md`. |
+| `assets/orchestrator.md` | Parent-session orchestration contract. |
+| `assets/agents/` | SDD phase agents copied into `.pi/agents/`. |
+| `assets/chains/` | SDD chains copied into `.pi/chains/`. |
+| `assets/support/` | Strict TDD apply/verify support docs. |
+| `skills/` | el Gentleman and foundation skills. |
+| `prompts/` | Gentle-prefixed prompt templates: `/gcl`, `/gis`, `/gpr`, `/gwr`. |
+
+## Foundation skills
+
+Included skills:
+
+- `gentle-ai` — el Gentleman harness discipline.
+- `branch-pr` — issue-first PR creation.
+- `chained-pr` — split oversized PRs into reviewable chains.
+- `work-unit-commits` — commit by deliverable work unit.
+- `judgment-day` — blind dual review and re-judgment flow.
+- `cognitive-doc-design` — documentation that reduces reviewer load.
+- `comment-writer` — concise collaboration comments.
+- `issue-creation` — issue-first GitHub workflow.
 
-## Optional companion packages
+## Memory is separate
 
-Recommended with this package:
+This package intentionally does **not** configure persistent memory.
+
+Use a separate memory package, for example:
 
 ```bash
-pi install npm:pi-subagents
-pi install npm:pi-intercom
+pi install npm:gentle-engram
 ```
 
-- `pi-subagents` runs the installed SDD agents and chains.
-- `pi-intercom` lets child agents ask the parent for decisions while running.
+el Gentleman may mention memory only when a memory package or callable memory tool is actually active.
+
+## Local development
 
-Persistent memory should remain separate; this package intentionally does not configure Engram or any other memory backend.
+From this repo:
+
+```bash
+pi install ./pi-packages/gentle-ai
+```
+
+Validate before publishing:
+
+```bash
+node --experimental-strip-types --check pi-packages/gentle-ai/extensions/gentle-ai.ts
+cd pi-packages/gentle-ai
+npm pack --dry-run
+```
 
 ## Design principles
 
 - Concepts before code.
-- Artifacts over floating context.
-- Strict TDD when tests exist, including evidence in apply and compliance checks in verify.
-- One orchestrator, focused subagents.
+- Artifacts over floating chat context.
+- Strict TDD evidence when tests exist.
+- One parent orchestrator, focused subagents.
 - Review workload is a first-class constraint.
-- Safety policy blocks destructive actions unless the user explicitly approves a safer path.
+- Human control beats agent momentum.

package/assets/orchestrator.md

@@ -1,15 +1,15 @@
-# Gentle Pi Orchestrator
+# el Gentleman Orchestrator
 
 Bind this to the parent Pi session only. Do not apply it to SDD executor phase agents.
 
 ## Identity Contract
 
-You are Gentle Pi: a Pi-specific coding-agent harness for controlled development work.
+You are el Gentleman: a Pi-specific coding-agent harness for controlled development work.
 
 When the user asks who or what you are, answer in this shape:
 
 ```text
-Soy Gentle Pi: un harness específico de Pi para desarrollo controlado, con persona de arquitecto senior. Trabajo con SDD/OpenSpec cuando la tarea lo justifica, coordino subagentes, uso artifacts de fase, corro comandos y edito archivos. No soy un chatbot genérico.
+Soy el Gentleman: un harness específico de Pi para desarrollo controlado, con persona de arquitecto senior. Trabajo con SDD/OpenSpec cuando la tarea lo justifica, coordino subagentes, uso artifacts de fase, corro comandos y edito archivos. No soy un chatbot genérico.
 ```
 
 Rules:
@@ -27,7 +27,7 @@ Keep synthesis short by default: decision, outcome, next action. Expand only whe
 
 ## Mental Model
 
-Gentle Pi is an ecosystem configurator and harness layer. After installation, the user should not memorize workflows or manually wire agents. The package should get out of the way:
+el Gentleman is an ecosystem configurator and harness layer. After installation, the user should not memorize workflows or manually wire agents. The package should get out of the way:
 
 - Small request: do it directly.
 - Substantial feature: suggest SDD organically.

package/extensions/gentle-ai.ts

@@ -1,30 +1,51 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import type { ExtensionAPI, ToolCallEventResult } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext, ToolCallEventResult } from "@earendil-works/pi-coding-agent";
+import { matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
 
 const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
 const ASSETS_DIR = join(PACKAGE_ROOT, "assets");
 const ORCHESTRATOR_PROMPT = readFileSync(join(ASSETS_DIR, "orchestrator.md"), "utf8").trim();
 
-const GENTLE_AI_PROMPT = `## Gentle Pi Identity and Harness
-You are Gentle Pi: a Pi-specific coding-agent harness for controlled development work.
+type PersonaMode = "gentleman" | "neutral";
+
+const PERSONA_OPTIONS = ["gentleman", "neutral"] as const;
+
+const GENTLEMAN_PERSONA_PROMPT = `Persona:
+- Be direct, technical, and concise.
+- When the user writes Spanish, answer in natural Rioplatense Spanish with voseo.
+- Act as a senior architect and teacher: concepts before code, no shortcuts.
+- Treat AI as a tool directed by the human; never present yourself as a default chatbot.
+- Push back when the user asks for code without enough context or understanding.
+- Correct errors directly, explain why, and show the better path.`;
+
+const NEUTRAL_PERSONA_PROMPT = `Persona:
+- Be direct, technical, concise, warm, and professional.
+- Always respond in the same language the user writes in.
+- Do not use slang or regional expressions.
+- Act as a senior architect and teacher: concepts before code, no shortcuts.
+- Treat AI as a tool directed by the human; never present yourself as a default chatbot.
+- Push back when the user asks for code without enough context or understanding.
+- Correct errors directly, explain why, and show the better path.`;
+
+function buildGentlePrompt(persona: PersonaMode): string {
+	const personaPrompt = persona === "neutral" ? NEUTRAL_PERSONA_PROMPT : GENTLEMAN_PERSONA_PROMPT;
+	return `## el Gentleman Identity and Harness
+You are el Gentleman: a Pi-specific coding-agent harness for controlled development work.
 
 Identity contract:
-- If the user asks who or what you are, answer as Gentle Pi, not as a generic assistant.
+- If the user asks who or what you are, answer as el Gentleman, not as a generic assistant.
 - Say you are a Pi-specific coding-agent harness with senior architect persona.
 - Mention SDD/OpenSpec phase artifacts and subagents as core capabilities.
 - Mention memory only when memory packages or callable memory tools are actually active; never invent persistent memory.
 - Do not claim portability outside the Pi runtime.
 
-Persona:
-- Be direct, technical, and concise.
-- When the user writes Spanish, answer in natural Rioplatense Spanish with voseo.
-- Act as a senior architect and teacher: concepts before code, no shortcuts.
-- Treat AI as a tool directed by the human; never present yourself as a default chatbot.
+${personaPrompt}
 
 Harness principles:
-- Gentle Pi is not prompt engineering. It is runtime discipline around powerful agents.
+- el Gentleman is not prompt engineering. It is runtime discipline around powerful agents.
 - Prefer SDD/OpenSpec artifacts over floating chat context for non-trivial work.
 - Clarify scope, constraints, acceptance criteria, and non-goals before implementation.
 - Use subagents when available for exploration, planning, implementation, and review, while keeping one parent session responsible for orchestration.
@@ -34,6 +55,7 @@ Harness principles:
 - Never claim persistent memory is available because of this package. Memory is provided by separate packages or MCP tools when installed and callable.
 
 ${ORCHESTRATOR_PROMPT}`;
+}
 
 const DENIED_BASH_PATTERNS: RegExp[] = [
 	/\brm\s+-rf\s+(?:\/|~|\$HOME|\.\.?)(?:\s|$)/,
@@ -52,6 +74,34 @@ const CONFIRM_BASH_PATTERNS: RegExp[] = [
 	/\bpi\s+remove\b/,
 ];
 
+const SDD_AGENT_NAMES = [
+	"sdd-init",
+	"sdd-explore",
+	"sdd-proposal",
+	"sdd-spec",
+	"sdd-design",
+	"sdd-tasks",
+	"sdd-apply",
+	"sdd-verify",
+	"sdd-archive",
+] as const;
+
+type SddAgentName = (typeof SDD_AGENT_NAMES)[number];
+type AgentModelConfig = Record<string, string>;
+type AgentSource = "project" | "user" | "builtin";
+
+interface AgentEntry {
+	name: string;
+	source: AgentSource;
+	filePath?: string;
+}
+
+const KEEP_CURRENT = "Keep current";
+const INHERIT_MODEL = "Inherit active/default model";
+const CUSTOM_MODEL = "Custom model id";
+
+const MODEL_CONTROL_OPTIONS = [KEEP_CURRENT, INHERIT_MODEL, CUSTOM_MODEL] as const;
+
 function evaluateCommand(command: string): ToolCallEventResult | undefined {
 	for (const pattern of DENIED_BASH_PATTERNS) {
 		if (pattern.test(command)) {
@@ -112,19 +162,436 @@ function installSddAssets(
 	};
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function modelConfigPath(cwd: string): string {
+	return join(cwd, ".pi", "gentle-ai", "models.json");
+}
+
+function personaConfigPath(cwd: string): string {
+	return join(cwd, ".pi", "gentle-ai", "persona.json");
+}
+
+function readPersonaMode(cwd: string): PersonaMode {
+	const path = personaConfigPath(cwd);
+	if (!existsSync(path)) return "gentleman";
+	try {
+		const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+		if (!isRecord(parsed)) return "gentleman";
+		return parsed.mode === "neutral" ? "neutral" : "gentleman";
+	} catch {
+		return "gentleman";
+	}
+}
+
+function writePersonaMode(cwd: string, mode: PersonaMode): void {
+	const path = personaConfigPath(cwd);
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, `${JSON.stringify({ mode }, null, 2)}\n`);
+}
+
+function readModelConfig(cwd: string): AgentModelConfig {
+	const path = modelConfigPath(cwd);
+	if (!existsSync(path)) return {};
+	try {
+		const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+		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();
+			}
+		}
+		return config;
+	} catch {
+		return {};
+	}
+}
+
+function writeModelConfig(cwd: string, config: AgentModelConfig): void {
+	const path = modelConfigPath(cwd);
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`);
+}
+
+function updateFrontmatterModel(content: string, model: string | undefined): string {
+	if (!content.startsWith("---\n")) return content;
+	const endIndex = content.indexOf("\n---", 4);
+	if (endIndex === -1) return content;
+	const frontmatter = content.slice(4, endIndex);
+	const body = content.slice(endIndex);
+	const lines = frontmatter.split("\n").filter((line) => !line.startsWith("model:"));
+	if (model !== undefined) {
+		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}`);
+	}
+	return `---\n${lines.join("\n")}${body}`;
+}
+
+function parseAgentName(filePath: string): string | undefined {
+	let content: string;
+	try {
+		content = readFileSync(filePath, "utf8");
+	} catch {
+		return undefined;
+	}
+	const name = content.match(/^name:\s*["']?([^"'\n]+)["']?\s*$/m)?.[1]?.trim();
+	if (!name) return undefined;
+	const packageName = content.match(/^package:\s*["']?([^"'\n]+)["']?\s*$/m)?.[1]?.trim();
+	return packageName ? `${packageName}.${name}` : name;
+}
+
+function listAgentFilesRecursive(dir: string): string[] {
+	if (!existsSync(dir)) return [];
+	const files: string[] = [];
+	for (const entry of readdirSync(dir, { withFileTypes: true })) {
+		const path = join(dir, entry.name);
+		if (entry.isDirectory()) files.push(...listAgentFilesRecursive(path));
+		else if (entry.isFile() && entry.name.endsWith(".md") && !entry.name.endsWith(".chain.md")) files.push(path);
+	}
+	return files;
+}
+
+function listAgentsFromDir(dir: string, source: AgentSource): AgentEntry[] {
+	return listAgentFilesRecursive(dir)
+		.map((filePath) => {
+			const name = parseAgentName(filePath);
+			return name ? { name, source, filePath } : undefined;
+		})
+		.filter((entry): entry is AgentEntry => entry !== undefined);
+}
+
+function listDiscoverableAgents(cwd: string): AgentEntry[] {
+	const builtinDirs = [
+		join(PACKAGE_ROOT, "..", "pi-subagents", "agents"),
+		join(cwd, ".pi", "npm", "node_modules", "pi-subagents", "agents"),
+		join(homedir(), ".local", "lib", "node_modules", "pi-subagents", "agents"),
+	];
+	const agents = [
+		...builtinDirs.flatMap((dir) => listAgentsFromDir(dir, "builtin")),
+		...listAgentsFromDir(join(homedir(), ".pi", "agent", "agents"), "user"),
+		...listAgentsFromDir(join(homedir(), ".agents"), "user"),
+		...listAgentsFromDir(join(cwd, ".agents"), "project"),
+		...listAgentsFromDir(join(cwd, ".pi", "agents"), "project"),
+	];
+	const byName = new Map<string, AgentEntry>();
+	for (const agent of agents) byName.set(agent.name, agent);
+	const discovered = Array.from(byName.values());
+	const sddFirst = SDD_AGENT_NAMES
+		.map((name) => discovered.find((agent) => agent.name === name))
+		.filter((agent): agent is AgentEntry => agent !== undefined);
+	const rest = discovered
+		.filter((agent) => !SDD_AGENT_NAMES.includes(agent.name as SddAgentName))
+		.sort((left, right) => left.name.localeCompare(right.name));
+	return [...sddFirst, ...rest];
+}
+
+function projectSettingsPath(cwd: string): string {
+	return join(cwd, ".pi", "settings.json");
+}
+
+function updateBuiltinModelOverride(cwd: string, name: string, model: string | undefined): boolean {
+	const path = projectSettingsPath(cwd);
+	let settings: Record<string, unknown> = {};
+	if (existsSync(path)) {
+		try {
+			const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+			if (isRecord(parsed)) settings = parsed;
+		} catch {
+			settings = {};
+		}
+	}
+	const subagents = isRecord(settings.subagents) ? { ...settings.subagents } : {};
+	const agentOverrides = isRecord(subagents.agentOverrides) ? { ...subagents.agentOverrides } : {};
+	const current = isRecord(agentOverrides[name]) ? { ...agentOverrides[name] } : {};
+	if (model === undefined) delete current.model;
+	else current.model = model;
+	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;
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, `${JSON.stringify(settings, null, "\t")}\n`);
+	return true;
+}
+
+function applyModelConfig(cwd: string, config: AgentModelConfig): { updated: number; skipped: number } {
+	let updated = 0;
+	let skipped = 0;
+	for (const agent of listDiscoverableAgents(cwd)) {
+		const model = config[agent.name];
+		if (agent.source === "builtin") {
+			if (updateBuiltinModelOverride(cwd, agent.name, model)) updated += 1;
+			else skipped += 1;
+			continue;
+		}
+		if (!agent.filePath || !existsSync(agent.filePath)) {
+			skipped += 1;
+			continue;
+		}
+		const original = readFileSync(agent.filePath, "utf8");
+		const next = updateFrontmatterModel(original, model);
+		if (next === original) {
+			skipped += 1;
+			continue;
+		}
+		writeFileSync(agent.filePath, next);
+		updated += 1;
+	}
+	return { updated, skipped };
+}
+
+function describeModelConfig(cwd: string, config: AgentModelConfig): string[] {
+	return listDiscoverableAgents(cwd).map((agent) => `${agent.name}: ${config[agent.name] ?? "inherit"}`);
+}
+
+async function getPiModelOptions(ctx: ExtensionContext): Promise<string[]> {
+	const models = await ctx.modelRegistry.getAvailable();
+	const modelIds = models
+		.map((model) => `${model.provider}/${model.id}`)
+		.sort((left, right) => left.localeCompare(right));
+	return [...MODEL_CONTROL_OPTIONS, ...modelIds];
+}
+
+interface OverlayComponent {
+	render(width: number): string[];
+	handleInput(data: string): void;
+	invalidate(): void;
+}
+
+type ModelPanelResult =
+	| { type: "save"; config: AgentModelConfig }
+	| { type: "custom"; agent: string | "all" }
+	| { type: "cancel" };
+
+const SET_ALL_AGENTS = "Set all agents";
+
+class SddModelPanel implements OverlayComponent {
+	private cursor = 0;
+	private mode: "agents" | "models" = "agents";
+	private selectedRow = SET_ALL_AGENTS;
+	private modelCursor = 0;
+	private query = "";
+	private readonly draft: AgentModelConfig;
+	private readonly rows: string[];
+
+	constructor(
+		initialConfig: AgentModelConfig,
+		private readonly modelOptions: string[],
+		agents: string[],
+		private readonly done: (result: ModelPanelResult) => void,
+	) {
+		this.draft = { ...initialConfig };
+		this.rows = [SET_ALL_AGENTS, ...agents];
+	}
+
+	invalidate(): void {}
+
+	handleInput(data: string): void {
+		if (this.mode === "models") {
+			this.handleModelInput(data);
+			return;
+		}
+		this.handleAgentInput(data);
+	}
+
+	render(width: number): string[] {
+		return this.mode === "models" ? this.renderModelPicker(width) : this.renderAgentList(width);
+	}
+
+	private handleAgentInput(data: string): void {
+		const maxCursor = this.rows.length + 1;
+		if (matchesKey(data, "ctrl+c") || matchesKey(data, "escape")) {
+			this.done({ type: "cancel" });
+			return;
+		}
+		if (matchesKey(data, "ctrl+s")) {
+			this.done({ type: "save", config: this.draft });
+			return;
+		}
+		if (matchesKey(data, "down") || data === "j") {
+			this.cursor = Math.min(maxCursor, this.cursor + 1);
+			return;
+		}
+		if (matchesKey(data, "up") || data === "k") {
+			this.cursor = Math.max(0, this.cursor - 1);
+			return;
+		}
+		if (data === "i") {
+			this.applySelection(undefined);
+			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 });
+			return;
+		}
+		if (!matchesKey(data, "return")) return;
+		if (this.cursor === this.rows.length) {
+			this.done({ type: "save", config: this.draft });
+			return;
+		}
+		if (this.cursor === this.rows.length + 1) {
+			this.done({ type: "cancel" });
+			return;
+		}
+		this.selectedRow = this.rows[this.cursor] ?? SET_ALL_AGENTS;
+		this.mode = "models";
+		this.modelCursor = 0;
+		this.query = "";
+	}
+
+	private handleModelInput(data: string): void {
+		const options = this.filteredModelOptions();
+		if (matchesKey(data, "ctrl+c")) {
+			this.done({ type: "cancel" });
+			return;
+		}
+		if (matchesKey(data, "escape")) {
+			this.mode = "agents";
+			this.query = "";
+			return;
+		}
+		if (matchesKey(data, "backspace")) {
+			this.query = this.query.slice(0, -1);
+			this.modelCursor = Math.min(this.modelCursor, Math.max(0, this.filteredModelOptions().length - 1));
+			return;
+		}
+		if (matchesKey(data, "down") || data === "j") {
+			this.modelCursor = Math.min(Math.max(0, options.length - 1), this.modelCursor + 1);
+			return;
+		}
+		if (matchesKey(data, "up") || data === "k") {
+			this.modelCursor = Math.max(0, this.modelCursor - 1);
+			return;
+		}
+		if (matchesKey(data, "return")) {
+			const selected = options[this.modelCursor];
+			if (!selected) return;
+			if (selected === CUSTOM_MODEL) {
+				this.done({ type: "custom", agent: this.selectedRow === SET_ALL_AGENTS ? "all" : this.selectedRow });
+				return;
+			}
+			if (selected === KEEP_CURRENT) {
+				this.mode = "agents";
+				return;
+			}
+			this.applySelection(selected === INHERIT_MODEL ? undefined : selected);
+			this.mode = "agents";
+			return;
+		}
+		if (data.length === 1 && data.charCodeAt(0) >= 32) {
+			this.query += data;
+			this.modelCursor = 0;
+		}
+	}
+
+	private applySelection(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;
+			}
+			return;
+		}
+		if (!row) return;
+		if (model === undefined) delete this.draft[row];
+		else this.draft[row] = model;
+	}
+
+	private filteredModelOptions(): string[] {
+		const query = this.query.trim().toLowerCase();
+		if (!query) return this.modelOptions;
+		return this.modelOptions.filter((option) => option.toLowerCase().includes(query));
+	}
+
+	private renderAgentList(width: number): string[] {
+		const lines: string[] = [];
+		const line = (text = "") => truncateToWidth(text, Math.max(1, width), "…", true);
+		lines.push(line("Assign Models to Agents"));
+		lines.push("");
+		lines.push(line("Current assignments:"));
+		lines.push("");
+		for (let i = 0; i < this.rows.length; i++) {
+			const row = this.rows[i] ?? SET_ALL_AGENTS;
+			const focused = i === this.cursor;
+			const label = row === SET_ALL_AGENTS ? this.renderSetAllLabel(row) : this.renderAgentLabel(row);
+			lines.push(line(`${focused ? "▸" : " "} ${label}`));
+		}
+		lines.push("");
+		lines.push(line(`${this.cursor === this.rows.length ? "▸" : " "} Continue`));
+		lines.push(line(`${this.cursor === this.rows.length + 1 ? "▸" : " "} ← Back`));
+		lines.push("");
+		lines.push(line("j/k: navigate • enter: change model / confirm • i: inherit • c: custom • ctrl+s: save • esc: back"));
+		return lines;
+	}
+
+	private renderModelPicker(width: number): string[] {
+		const lines: string[] = [];
+		const options = this.filteredModelOptions();
+		const line = (text = "") => truncateToWidth(text, Math.max(1, width), "…", true);
+		lines.push(line(`Select model for ${this.selectedRow}`));
+		lines.push("");
+		lines.push(line(`◎ ${this.query || "search..."}`));
+		lines.push("");
+		const maxVisible = 12;
+		const start = Math.max(0, Math.min(this.modelCursor - Math.floor(maxVisible / 2), Math.max(0, options.length - maxVisible)));
+		const end = Math.min(options.length, start + maxVisible);
+		for (let i = start; i < end; i++) {
+			const focused = i === this.modelCursor;
+			lines.push(line(`${focused ? "▸" : " "} ${options[i]}`));
+		}
+		if (options.length === 0) lines.push(line("  No matching models"));
+		lines.push("");
+		lines.push(line("j/k: navigate • type: search • enter: select • esc: back"));
+		return lines;
+	}
+
+	private renderSetAllLabel(row: string): string {
+		const values = 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"}`;
+	}
+
+	private renderAgentLabel(row: string): string {
+		return `${row.padEnd(20)} ${this.draft[row] ?? "inherit"}`;
+	}
+}
+
+async function showSddModelPanel(ctx: ExtensionContext, config: AgentModelConfig): Promise<ModelPanelResult> {
+	const modelOptions = await getPiModelOptions(ctx);
+	const agents = listDiscoverableAgents(ctx.cwd).map((agent) => agent.name);
+	return ctx.ui.custom<ModelPanelResult>((_tui, _theme, _keybindings, done) => new SddModelPanel(config, modelOptions, agents, done), {
+		overlay: true,
+		overlayOptions: { anchor: "center", width: "70%", minWidth: 72, maxHeight: "85%" },
+	});
+}
+
 export default function gentleAi(pi: ExtensionAPI): void {
 	pi.on("session_start", (_event, ctx) => {
 		const result = installSddAssets(ctx.cwd, false);
+		const modelResult = applyModelConfig(ctx.cwd, readModelConfig(ctx.cwd));
 		if (ctx.hasUI && (result.agents > 0 || result.chains > 0 || result.support > 0)) {
 			ctx.ui.notify(
 				`Gentle AI SDD assets auto-installed: ${result.agents} agent(s), ${result.chains} chain(s), ${result.support} support file(s).`,
 				"info",
 			);
 		}
+		if (ctx.hasUI && modelResult.updated > 0) {
+			ctx.ui.notify(`el Gentleman applied SDD model config to ${modelResult.updated} agent(s).`, "info");
+		}
 	});
 
-	pi.on("before_agent_start", (event) => ({
-		systemPrompt: `${event.systemPrompt}\n\n${GENTLE_AI_PROMPT}`,
+	pi.on("before_agent_start", (event, ctx) => ({
+		systemPrompt: `${event.systemPrompt}\n\n${buildGentlePrompt(readPersonaMode(ctx.cwd))}`,
 	}));
 
 	pi.on("tool_call", (event) => {
@@ -144,18 +611,91 @@ export default function gentleAi(pi: ExtensionAPI): void {
 		},
 	});
 
+	pi.registerCommand("gentleman:models", {
+		description: "Configure per-agent models for el Gentleman.",
+		handler: async (_args, ctx) => {
+			let config = readModelConfig(ctx.cwd);
+			let result = await showSddModelPanel(ctx, config);
+			while (result.type === "custom") {
+				const current = result.agent === "all" ? "inherit" : (config[result.agent] ?? "inherit");
+				const custom = await ctx.ui.input(
+					`${result.agent === "all" ? "all agents" : result.agent} custom model id`,
+					current === "inherit" ? "provider/model" : current,
+				);
+				if (custom === undefined) return;
+				const trimmed = custom.trim();
+				if (trimmed.length > 0) {
+					if (result.agent === "all") {
+						config = Object.fromEntries(listDiscoverableAgents(ctx.cwd).map((agent) => [agent.name, trimmed]));
+					} else {
+						config = { ...config, [result.agent]: trimmed };
+					}
+				}
+				result = await showSddModelPanel(ctx, config);
+			}
+			if (result.type !== "save") return;
+			writeModelConfig(ctx.cwd, result.config);
+			const applyResult = applyModelConfig(ctx.cwd, result.config);
+			ctx.ui.notify(
+				[
+					"el Gentleman model config saved.",
+					`Config: ${modelConfigPath(ctx.cwd)}`,
+					`Agents updated: ${applyResult.updated}`,
+					...describeModelConfig(ctx.cwd, result.config),
+				].join("\n"),
+				"info",
+			);
+		},
+	});
+
+	pi.registerCommand("gentle-ai:models", {
+		description: "Alias for /gentleman:models.",
+		handler: async (_args, ctx) => {
+			ctx.ui.notify("Use /gentleman:models to configure per-agent models.", "info");
+		},
+	});
+
+	pi.registerCommand("gentleman:persona", {
+		description: "Switch el Gentleman persona between gentleman and neutral.",
+		handler: async (_args, ctx) => {
+			const current = readPersonaMode(ctx.cwd);
+			const selected = await ctx.ui.select(`el Gentleman persona (current: ${current})`, [...PERSONA_OPTIONS]);
+			if (selected !== "gentleman" && selected !== "neutral") return;
+			writePersonaMode(ctx.cwd, selected);
+			ctx.ui.notify(
+				[
+					`el Gentleman persona set to: ${selected}`,
+					`Config: ${personaConfigPath(ctx.cwd)}`,
+					"Run /reload or start a new Pi session for already-injected prompts to refresh.",
+				].join("\n"),
+				"info",
+			);
+		},
+	});
+
+	pi.registerCommand("gentle-ai:persona", {
+		description: "Alias for /gentleman:persona.",
+		handler: async (_args, ctx) => {
+			ctx.ui.notify("Use /gentleman:persona to switch between gentleman and neutral personas.", "info");
+		},
+	});
+
 	pi.registerCommand("gentle-ai:status", {
 		description: "Show Gentle AI package status for this project.",
 		handler: async (_args, ctx) => {
 			const agentsInstalled = existsSync(join(ctx.cwd, ".pi", "agents", "sdd-apply.md"));
 			const chainsInstalled = existsSync(join(ctx.cwd, ".pi", "chains", "sdd-full.chain.md"));
 			const openspecConfigured = existsSync(join(ctx.cwd, "openspec", "config.yaml"));
+			const modelConfig = readModelConfig(ctx.cwd);
 			ctx.ui.notify(
 				[
-					"Gentle AI package is active.",
+					"el Gentleman package is active.",
+					`Persona: ${readPersonaMode(ctx.cwd)}`,
 					`SDD agents: ${agentsInstalled ? "installed" : "not installed"}`,
 					`SDD chains: ${chainsInstalled ? "installed" : "not installed"}`,
 					`OpenSpec config: ${openspecConfigured ? "present" : "missing"}`,
+					`Model config: ${existsSync(modelConfigPath(ctx.cwd)) ? "present" : "missing"}`,
+					...describeModelConfig(ctx.cwd, modelConfig),
 				].join("\n"),
 				"info",
 			);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gentle-pi",
-  "version": "0.1.3",
-  "description": "Opinionated Gentle Pi harness package: SDD/OpenSpec workflow, strict TDD guidance, subagent assets, and safety defaults.",
+  "version": "0.1.12",
+  "description": "Opinionated el Gentleman harness package for Pi: SDD/OpenSpec workflow, strict TDD guidance, subagent assets, and safety defaults.",
   "license": "MIT",
   "type": "module",
   "keywords": [
@@ -36,6 +36,9 @@
       "./skills"
     ]
   },
+  "dependencies": {
+    "@earendil-works/pi-tui": "*"
+  },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*"
   },

package/skills/gentle-ai/SKILL.md

@@ -3,13 +3,13 @@ name: gentle-ai
 description: "Use Gentle AI harness discipline for Pi work: clarify first, preserve OpenSpec artifacts, use strict TDD where available, delegate through subagents when useful, and protect review workload."
 ---
 
-# Gentle Pi Harness
+# el Gentleman Harness
 
 Use this skill when work is non-trivial, risky, multi-step, or likely to benefit from SDD/OpenSpec artifacts.
 
 ## Identity Rule
 
-When asked who or what you are, answer as Gentle Pi: a Pi-specific coding-agent harness with senior architect persona, SDD/OpenSpec artifacts, and subagent coordination. Do not answer as a generic assistant.
+When asked who or what you are, answer as el Gentleman: a Pi-specific coding-agent harness with senior architect persona, SDD/OpenSpec artifacts, and subagent coordination. Do not answer as a generic assistant.
 
 ## Compact Rules
 
@@ -20,7 +20,7 @@ When asked who or what you are, answer as Gentle Pi: a Pi-specific coding-agent
 - Prefer fresh-context reviewers for adversarial review and forked workers only after direction is approved.
 - Keep writes single-threaded unless the user explicitly approves isolated parallel worktrees.
 - Forecast review workload before large changes; ask before producing oversized or multi-area diffs.
-- Never claim persistent memory is available because of Gentle Pi itself; memory is provided by separate packages/tools when active.
+- Never claim persistent memory is available because of el Gentleman itself; memory is provided by separate packages/tools when active.
 
 ## Work Routing