gentle-pi 0.3.0 → 0.3.1

package/README.md

@@ -49,6 +49,7 @@ Most coding-agent sessions fail for operational reasons, not model reasons:
 | **Rose startup intro**         | Adds a pink rose fade-in, compact project/runtime panel, and visible startup collaboration credit for @aporcelli's `pi-gentle-startup` ideas. |
 | **Work routing discipline**    | Small tasks stay inline. Context-heavy exploration can be delegated. Large or risky changes go through SDD/OpenSpec.                          |
 | **SDD/OpenSpec assets**        | Installs phase agents and chains for `init`, `explore`, `proposal`, `spec`, `design`, `tasks`, `apply`, `verify`, and `archive`.              |
+| **Lazy SDD preflight**         | Asks once per session for SDD mode, artifact store, PR chaining strategy, and review budget before the first SDD flow.                       |
 | **Subagent orchestration**     | Keeps one parent session responsible while child agents explore, implement, test, or review with focused context.                             |
 | **Strict TDD support**         | When project config declares a test command, apply/verify phases must record RED → GREEN → TRIANGULATE → REFACTOR evidence.                   |
 | **Reviewer protection**        | Surfaces review workload risk before a task turns into an oversized PR.                                                                       |
@@ -81,23 +82,24 @@ Then start Pi in a project:
 pi
 ```
 
-`gentle-pi` waits until the first SDD request in a session, then runs a one-time SDD preflight and installs local SDD assets without overwriting your edits.
+`gentle-pi` waits until the first SDD flow in a session, then runs a one-time SDD preflight and installs local SDD assets without overwriting your edits. Slash SDD commands trigger this automatically; for natural-language requests, el Gentleman decides when SDD is needed and runs the explicit preflight first.
 
 ## Quick start
 
 ```text
-/gentle-ai:status      Check package, SDD assets, OpenSpec, and model config.
-/sdd-init              Create or refresh openspec/config.yaml.
-/gentle:models         Assign models to SDD/custom agents.
-/gentle:persona        Switch between gentleman and neutral persona modes.
+/gentle-ai:status          Check package, SDD assets, OpenSpec, and model config.
+/gentle-ai:sdd-preflight   Run or reuse the session SDD preflight explicitly.
+/sdd-init                  Create or refresh openspec/config.yaml.
+/gentle:models             Assign models to SDD/custom agents.
+/gentle:persona            Switch between gentleman and neutral persona modes.
 ```
 
 Typical flow:
 
 1. Open Pi in your repo.
 2. Run `/gentle-ai:status`.
-3. Run `/sdd-init` once per project, or when test/project capabilities change.
-4. For a substantial change, ask Pi to use SDD.
+3. Run `/sdd-init` once per project, or when test/project capabilities change. This also runs the session SDD preflight.
+4. For a substantial change, ask Pi to use SDD. Natural-language requests are classified by the parent agent, not by brittle runtime regexes.
 5. Review the phase artifacts instead of trusting floating chat context.
 
 ## How the harness decides what to do

package/extensions/gentle-ai.ts

@@ -5,6 +5,13 @@ import {
 	readFileSync,
 	writeFileSync,
 } from "node:fs";
+import {
+	access,
+	mkdir,
+	readFile,
+	readdir,
+	writeFile,
+} from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -25,10 +32,26 @@ import {
 
 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();
+
+let orchestratorPromptCache: string | null = null;
+function getOrchestratorPrompt(): string {
+	if (orchestratorPromptCache === null) {
+		orchestratorPromptCache = readFileSync(
+			join(ASSETS_DIR, "orchestrator.md"),
+			"utf8",
+		).trim();
+	}
+	return orchestratorPromptCache;
+}
+
+async function pathExists(path: string): Promise<boolean> {
+	try {
+		await access(path);
+		return true;
+	} catch {
+		return false;
+	}
+}
 
 type PersonaMode = "gentleman" | "neutral";
 
@@ -76,7 +99,7 @@ Harness principles:
 - Protect the human reviewer: avoid oversized changes, surface review workload risk, and ask before turning one task into a large multi-area change.
 - 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}`;
+${getOrchestratorPrompt()}`;
 }
 
 const DENIED_BASH_PATTERNS: RegExp[] = [
@@ -263,6 +286,25 @@ export function readModelConfig(cwd: string): AgentModelConfig {
 	}
 }
 
+export async function readModelConfigAsync(
+	cwd: string,
+): Promise<AgentModelConfig> {
+	const path = modelConfigPath(cwd);
+	if (!(await pathExists(path))) return {};
+	try {
+		const parsed: unknown = JSON.parse(await readFile(path, "utf8"));
+		if (!isRecord(parsed)) return {};
+		const config: AgentModelConfig = {};
+		for (const [name, value] of Object.entries(parsed)) {
+			const entry = normalizeRoutingEntry(value);
+			if (entry) config[name] = entry;
+		}
+		return config;
+	} catch {
+		return {};
+	}
+}
+
 function writeModelConfig(cwd: string, config: AgentModelConfig): void {
 	const path = modelConfigPath(cwd);
 	mkdirSync(dirname(path), { recursive: true });
@@ -323,6 +365,23 @@ function parseAgentName(filePath: string): string | undefined {
 	return packageName ? `${packageName}.${name}` : name;
 }
 
+async function parseAgentNameAsync(
+	filePath: string,
+): Promise<string | undefined> {
+	let content: string;
+	try {
+		content = await readFile(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[] = [];
@@ -339,6 +398,30 @@ function listAgentFilesRecursive(dir: string): string[] {
 	return files;
 }
 
+async function listAgentFilesRecursiveAsync(dir: string): Promise<string[]> {
+	if (!(await pathExists(dir))) return [];
+	const files: string[] = [];
+	let entries;
+	try {
+		entries = await readdir(dir, { withFileTypes: true });
+	} catch {
+		return files;
+	}
+	for (const entry of entries) {
+		const path = join(dir, entry.name);
+		if (entry.isDirectory()) {
+			files.push(...(await listAgentFilesRecursiveAsync(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): AgentEntry | undefined => {
@@ -348,6 +431,19 @@ function listAgentsFromDir(dir: string, source: AgentSource): AgentEntry[] {
 		.filter((entry): entry is AgentEntry => entry !== undefined);
 }
 
+async function listAgentsFromDirAsync(
+	dir: string,
+	source: AgentSource,
+): Promise<AgentEntry[]> {
+	const filePaths = await listAgentFilesRecursiveAsync(dir);
+	const entries: AgentEntry[] = [];
+	for (const filePath of filePaths) {
+		const name = await parseAgentNameAsync(filePath);
+		if (name) entries.push({ name, source, filePath });
+	}
+	return entries;
+}
+
 function listDiscoverableAgents(cwd: string): AgentEntry[] {
 	const builtinDirs = [
 		join(PACKAGE_ROOT, "..", "pi-subagents", "agents"),
@@ -373,6 +469,37 @@ function listDiscoverableAgents(cwd: string): AgentEntry[] {
 	return [...sddFirst, ...rest];
 }
 
+async function listDiscoverableAgentsAsync(cwd: string): Promise<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: AgentEntry[] = [];
+	for (const dir of builtinDirs) {
+		agents.push(...(await listAgentsFromDirAsync(dir, "builtin")));
+	}
+	const otherDirs: Array<[string, AgentSource]> = [
+		[join(homedir(), ".pi", "agent", "agents"), "user"],
+		[join(homedir(), ".agents"), "user"],
+		[join(cwd, ".agents"), "project"],
+		[join(cwd, ".pi", "agents"), "project"],
+	];
+	for (const [dir, source] of otherDirs) {
+		agents.push(...(await listAgentsFromDirAsync(dir, source)));
+	}
+	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");
 }
@@ -417,6 +544,46 @@ function updateBuiltinModelOverride(
 	return true;
 }
 
+async function updateBuiltinModelOverrideAsync(
+	cwd: string,
+	name: string,
+	entry: AgentRoutingEntry | undefined,
+): Promise<boolean> {
+	const path = projectSettingsPath(cwd);
+	let settings: Record<string, unknown> = {};
+	if (await pathExists(path)) {
+		try {
+			const parsed: unknown = JSON.parse(await readFile(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 (entry?.model === undefined) delete current.model;
+	else current.model = entry.model;
+	if (entry?.thinking === undefined) delete current.thinking;
+	else current.thinking = entry.thinking;
+	if (Object.keys(current).length > 0) agentOverrides[name] = current;
+	else delete agentOverrides[name];
+	if (Object.keys(agentOverrides).length > 0)
+		subagents.agentOverrides = agentOverrides;
+	else delete subagents.agentOverrides;
+	if (Object.keys(subagents).length > 0) settings.subagents = subagents;
+	else delete settings.subagents;
+	await mkdir(dirname(path), { recursive: true });
+	await writeFile(path, `${JSON.stringify(settings, null, "\t")}\n`);
+	return true;
+}
+
 export function applyModelConfig(
 	cwd: string,
 	config: AgentModelConfig,
@@ -446,6 +613,36 @@ export function applyModelConfig(
 	return { updated, skipped };
 }
 
+export async function applyModelConfigAsync(
+	cwd: string,
+	config: AgentModelConfig,
+): Promise<{ updated: number; skipped: number }> {
+	let updated = 0;
+	let skipped = 0;
+	for (const agent of await listDiscoverableAgentsAsync(cwd)) {
+		const entry = config[agent.name];
+		if (agent.source === "builtin") {
+			if (await updateBuiltinModelOverrideAsync(cwd, agent.name, entry))
+				updated += 1;
+			else skipped += 1;
+			continue;
+		}
+		if (!agent.filePath || !(await pathExists(agent.filePath))) {
+			skipped += 1;
+			continue;
+		}
+		const original = await readFile(agent.filePath, "utf8");
+		const next = updateFrontmatterRouting(original, entry);
+		if (next === original) {
+			skipped += 1;
+			continue;
+		}
+		await writeFile(agent.filePath, next);
+		updated += 1;
+	}
+	return { updated, skipped };
+}
+
 function describeModelConfig(cwd: string, config: AgentModelConfig): string[] {
 	return listDiscoverableAgents(cwd).map((agent) => {
 		const entry = config[agent.name];
@@ -909,17 +1106,30 @@ export default function gentleAi(pi: ExtensionAPI): void {
 		return ensureSddPreflight(ctx, {
 			pi,
 			installAssets: (cwd) => installSddAssets(cwd, false),
-			applyModelConfig: (cwd) => applyModelConfig(cwd, readModelConfig(cwd)),
+			applyModelConfig: async (cwd) =>
+				applyModelConfigAsync(cwd, await readModelConfigAsync(cwd)),
 		});
 	}
 
-	pi.on("session_start", (_event, ctx) => {
-		const modelResult = applyModelConfig(ctx.cwd, readModelConfig(ctx.cwd));
-		if (ctx.hasUI && modelResult.updated > 0) {
-			ctx.ui.notify(
-				`el Gentleman applied SDD model config to ${modelResult.updated} agent(s).`,
-				"info",
-			);
+	pi.on("session_start", async (_event, ctx) => {
+		try {
+			const config = await readModelConfigAsync(ctx.cwd);
+			const modelResult = await applyModelConfigAsync(ctx.cwd, config);
+			if (ctx.hasUI && modelResult.updated > 0) {
+				ctx.ui.notify(
+					`el Gentleman applied SDD model config to ${modelResult.updated} agent(s).`,
+					"info",
+				);
+			}
+		} catch (error) {
+			if (ctx.hasUI) {
+				const message =
+					error instanceof Error ? error.message : String(error);
+				ctx.ui.notify(
+					`el Gentleman model config sweep failed: ${message}`,
+					"warning",
+				);
+			}
 		}
 	});
 

package/extensions/sdd-init.ts

@@ -6,7 +6,7 @@ import {
 	writeFileSync,
 } from "node:fs";
 import { basename, dirname, join, relative } from "node:path";
-import { applyModelConfig, readModelConfig } from "./gentle-ai.ts";
+import { applyModelConfigAsync, readModelConfigAsync } from "./gentle-ai.ts";
 import { ensureSddPreflight, installSddAssets } from "../lib/sdd-preflight.ts";
 type ExtensionAPI = any;
 
@@ -778,7 +778,8 @@ export default function (pi: ExtensionAPI) {
 			await ensureSddPreflight(ctx, {
 				pi,
 				installAssets: (cwd) => installSddAssets(cwd, false),
-				applyModelConfig: (cwd) => applyModelConfig(cwd, readModelConfig(cwd)),
+				applyModelConfig: async (cwd) =>
+					applyModelConfigAsync(cwd, await readModelConfigAsync(cwd)),
 			});
 			const configPath = join(ctx.cwd, CONFIG_REL_PATH);
 			if (existsSync(configPath)) {

package/extensions/skill-registry.ts

@@ -1,14 +1,14 @@
 import { createHash } from "node:crypto";
+import { watch } from "node:fs";
 import {
-	existsSync,
-	mkdirSync,
-	readFileSync,
-	readdirSync,
-	renameSync,
-	statSync,
-	watch,
-	writeFileSync,
-} from "node:fs";
+	access,
+	mkdir,
+	readFile,
+	readdir,
+	rename,
+	stat,
+	writeFile,
+} from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, join, normalize, relative, sep } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
@@ -26,6 +26,14 @@ 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";
+async function pathExists(path: string): Promise<boolean> {
+	try {
+		await access(path);
+		return true;
+	} catch {
+		return false;
+	}
+}
 
 interface SkillEntry {
 	name: string;
@@ -75,15 +83,15 @@ function projectSkillDirs(cwd: string): string[] {
 	];
 }
 
-function findSkillFiles(root: string): string[] {
-	if (!existsSync(root)) return [];
+async function findSkillFiles(root: string): Promise<string[]> {
+	if (!(await pathExists(root))) return [];
 	const out: string[] = [];
 	const stack: string[] = [root];
 	while (stack.length > 0) {
 		const dir = stack.pop()!;
 		let entries;
 		try {
-			entries = readdirSync(dir, { withFileTypes: true });
+			entries = await readdir(dir, { withFileTypes: true });
 		} catch {
 			continue;
 		}
@@ -205,22 +213,22 @@ function comparablePath(path: string): string {
 	return clean.length > 1 ? clean.replace(/[\\/]+$/, "") : clean;
 }
 
-function uniqueExistingDirs(dirs: string[]): string[] {
+async function uniqueExistingDirs(dirs: string[]): Promise<string[]> {
 	const seen = new Set<string>();
 	const out: string[] = [];
 	for (const dir of dirs) {
 		const clean = comparablePath(dir);
-		if (seen.has(clean) || !existsSync(clean)) continue;
+		if (seen.has(clean) || !(await pathExists(clean))) continue;
 		seen.add(clean);
 		out.push(clean);
 	}
 	return out;
 }
 
-function loadSkill(file: string): SkillEntry | undefined {
+async function loadSkill(file: string): Promise<SkillEntry | undefined> {
 	let source: string;
 	try {
-		source = readFileSync(file, "utf8");
+		source = await readFile(file, "utf8");
 	} catch {
 		return undefined;
 	}
@@ -261,18 +269,17 @@ function dedupeBySkillName(entries: SkillEntry[], cwd: string): SkillEntry[] {
 	return out.sort((a, b) => a.name.localeCompare(b.name));
 }
 
-function fingerprint(files: string[]): string {
-	const lines = [
-		`schema:${REGISTRY_SCHEMA_VERSION}`,
-		...files.map((f) => {
-			try {
-				const stat = statSync(f);
-				return `${f}:${stat.mtimeMs}:${stat.size}`;
-			} catch {
-				return `${f}:missing`;
-			}
-		}),
-	].sort();
+async function fingerprint(files: string[]): Promise<string> {
+	const lines: string[] = [`schema:${REGISTRY_SCHEMA_VERSION}`];
+	for (const file of files) {
+		try {
+			const info = await stat(file);
+			lines.push(`${file}:${info.mtimeMs}:${info.size}`);
+		} catch {
+			lines.push(`${file}:missing`);
+		}
+	}
+	lines.sort();
 	return createHash("sha1").update(lines.join("\n")).digest("hex");
 }
 
@@ -321,11 +328,11 @@ interface RegenResult {
 	reason: string;
 }
 
-function ensureAtlIgnored(cwd: string): void {
+async function ensureAtlIgnored(cwd: string): Promise<void> {
 	const gitignorePath = join(cwd, ".gitignore");
 	let existing = "";
-	if (existsSync(gitignorePath)) {
-		existing = readFileSync(gitignorePath, "utf8");
+	if (await pathExists(gitignorePath)) {
+		existing = await readFile(gitignorePath, "utf8");
 	}
 	const hasAtlIgnore = existing
 		.split("\n")
@@ -334,7 +341,7 @@ function ensureAtlIgnored(cwd: string): void {
 	if (hasAtlIgnore) return;
 	const prefix = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
 	const header = existing.includes("# Local Pi runtime state") ? "" : "# Local Pi runtime state\n";
-	writeFileSync(gitignorePath, `${existing}${prefix}${header}${ATL_IGNORE_ENTRY}\n`);
+	await writeFile(gitignorePath, `${existing}${prefix}${header}${ATL_IGNORE_ENTRY}\n`);
 }
 
 function isGeneratedLegacyProjectRegistry(source: string): boolean {
@@ -349,65 +356,84 @@ function isGeneratedLegacyProjectRegistry(source: string): boolean {
 	);
 }
 
-function nextLegacyDisabledPath(cwd: string): string {
+async function nextLegacyDisabledPath(cwd: string): Promise<string> {
 	const base = join(cwd, LEGACY_PROJECT_REGISTRY_DISABLED_REL_PATH);
-	if (!existsSync(base)) return base;
+	if (!(await pathExists(base))) return base;
 	for (let i = 1; i < 100; i++) {
 		const candidate = `${base}.${i}`;
-		if (!existsSync(candidate)) return candidate;
+		if (!(await pathExists(candidate))) return candidate;
 	}
 	return `${base}.${Date.now()}`;
 }
 
-function quarantineLegacyProjectRegistry(cwd: string): boolean {
+async function quarantineLegacyProjectRegistry(cwd: string): Promise<boolean> {
 	const legacyPath = join(cwd, LEGACY_PROJECT_REGISTRY_REL_PATH);
-	if (!existsSync(legacyPath)) return false;
+	if (!(await pathExists(legacyPath))) return false;
 	let source = "";
 	try {
-		source = readFileSync(legacyPath, "utf8");
+		source = await readFile(legacyPath, "utf8");
 	} catch {
 		return false;
 	}
 	if (!isGeneratedLegacyProjectRegistry(source)) return false;
-	const disabledPath = nextLegacyDisabledPath(cwd);
+	const disabledPath = await nextLegacyDisabledPath(cwd);
 	try {
-		renameSync(legacyPath, disabledPath);
+		await rename(legacyPath, disabledPath);
 		return true;
 	} catch {
 		return false;
 	}
 }
 
-function regenerateRegistry(cwd: string, force: boolean): RegenResult {
-	const existingDirs = uniqueExistingDirs([...projectSkillDirs(cwd), ...userSkillDirs()]);
-	const files = existingDirs.flatMap(findSkillFiles);
+async function regenerateRegistry(
+	cwd: string,
+	force: boolean,
+): Promise<RegenResult> {
+	const existingDirs = await uniqueExistingDirs([
+		...projectSkillDirs(cwd),
+		...userSkillDirs(),
+	]);
+	const files: string[] = [];
+	for (const dir of existingDirs) {
+		files.push(...(await findSkillFiles(dir)));
+	}
 	const cachePath = join(cwd, CACHE_REL_PATH);
 	const registryPath = join(cwd, REGISTRY_REL_PATH);
-	const fp = fingerprint(files);
+	const fp = await fingerprint(files);
 	let cached: string | undefined;
-	if (existsSync(cachePath)) {
+	if (await pathExists(cachePath)) {
 		try {
-			cached = (JSON.parse(readFileSync(cachePath, "utf8")) as { fingerprint?: string }).fingerprint;
+			cached = (
+				JSON.parse(await readFile(cachePath, "utf8")) as {
+					fingerprint?: string;
+				}
+			).fingerprint;
 		} catch {
 			cached = undefined;
 		}
 	}
-	if (!force && cached === fp && existsSync(registryPath)) {
+	if (!force && cached === fp && (await pathExists(registryPath))) {
 		return { regenerated: false, skillCount: 0, reason: "cache-hit" };
 	}
-	const entries = files
-		.map(loadSkill)
-		.filter((e): e is SkillEntry => Boolean(e));
+	const entries: SkillEntry[] = [];
+	for (const file of files) {
+		const entry = await loadSkill(file);
+		if (entry) entries.push(entry);
+	}
 	const deduped = dedupeBySkillName(entries, cwd);
 	const sources = existingDirs.map((d) => {
 		const rel = relative(cwd, d);
 		return rel.startsWith("..") ? d : rel || ".";
 	});
 	const md = renderRegistry(cwd, sources, deduped);
-	mkdirSync(join(cwd, ".atl"), { recursive: true });
-	writeFileSync(registryPath, md);
-	writeFileSync(cachePath, JSON.stringify({ fingerprint: fp }, null, 2));
-	return { regenerated: true, skillCount: deduped.length, reason: force ? "forced" : "fingerprint-changed" };
+	await mkdir(join(cwd, ".atl"), { recursive: true });
+	await writeFile(registryPath, md);
+	await writeFile(cachePath, JSON.stringify({ fingerprint: fp }, null, 2));
+	return {
+		regenerated: true,
+		skillCount: deduped.length,
+		reason: force ? "forced" : "fingerprint-changed",
+	};
 }
 
 const watchedCwds = new Set<string>();
@@ -432,22 +458,30 @@ function shouldSkipSkillRegistryStartup(
 	);
 }
 
-function startSkillRegistryWatcher(cwd: string, notify: (message: string) => void): void {
+async function startSkillRegistryWatcher(
+	cwd: string,
+	notify: (message: string) => void,
+): Promise<void> {
 	if (watchedCwds.has(cwd)) return;
 	watchedCwds.add(cwd);
-	const dirs = uniqueExistingDirs([...projectSkillDirs(cwd), ...userSkillDirs()]);
+	const dirs = await uniqueExistingDirs([
+		...projectSkillDirs(cwd),
+		...userSkillDirs(),
+	]);
 	let timer: ReturnType<typeof setTimeout> | undefined;
 	const refresh = () => {
 		if (timer) clearTimeout(timer);
 		timer = setTimeout(() => {
-			try {
-				const result = regenerateRegistry(cwd, false);
-				if (result.regenerated) {
-					notify(`Skill registry refreshed (${result.skillCount} skills)`);
+			void (async () => {
+				try {
+					const result = await regenerateRegistry(cwd, false);
+					if (result.regenerated) {
+						notify(`Skill registry refreshed (${result.skillCount} skills)`);
+					}
+				} catch {
+					// Keep the watcher best-effort; session_start/manual refresh surfaces detailed failures.
 				}
-			} catch {
-				// Keep the watcher best-effort; session_start/manual refresh surfaces detailed failures.
-			}
+			})();
 		}, WATCH_DEBOUNCE_MS);
 	};
 	for (const dir of dirs) {
@@ -479,11 +513,14 @@ export default function (pi: ExtensionAPI) {
 	pi.on("session_start", async (_event, ctx) => {
 		if (shouldSkipSkillRegistryStartup(pi)) return;
 		try {
-			ensureAtlIgnored(ctx.cwd);
-			const quarantinedLegacy = quarantineLegacyProjectRegistry(ctx.cwd);
-			const result = regenerateRegistry(ctx.cwd, quarantinedLegacy);
+			await ensureAtlIgnored(ctx.cwd);
+			const quarantinedLegacy = await quarantineLegacyProjectRegistry(ctx.cwd);
+			const result = await regenerateRegistry(ctx.cwd, quarantinedLegacy);
 			if (result.regenerated && ctx.hasUI) {
-				ctx.ui.notify(`Skill registry refreshed (${result.skillCount} skills)`, "info");
+				ctx.ui.notify(
+					`Skill registry refreshed (${result.skillCount} skills)`,
+					"info",
+				);
 			}
 			if (quarantinedLegacy && ctx.hasUI) {
 				ctx.ui.notify(
@@ -491,22 +528,28 @@ export default function (pi: ExtensionAPI) {
 					"warning",
 				);
 			}
-			startSkillRegistryWatcher(ctx.cwd, (message) => {
+			await startSkillRegistryWatcher(ctx.cwd, (message) => {
 				if (ctx.hasUI) ctx.ui.notify(message, "info");
 			});
 			if (quarantinedLegacy) {
 				setTimeout(() => {
-					try {
-						regenerateRegistry(ctx.cwd, true);
-					} catch {
-						// Best-effort same-session self-heal in case the stale extension already ran.
-					}
+					void (async () => {
+						try {
+							await regenerateRegistry(ctx.cwd, true);
+						} catch {
+							// Best-effort same-session self-heal in case the stale extension already ran.
+						}
+					})();
 				}, WATCH_DEBOUNCE_MS);
 			}
 		} catch (error) {
 			if (ctx.hasUI) {
-				const message = error instanceof Error ? error.message : String(error);
-				ctx.ui.notify(`Skill registry refresh failed: ${message}`, "warning");
+				const message =
+					error instanceof Error ? error.message : String(error);
+				ctx.ui.notify(
+					`Skill registry refresh failed: ${message}`,
+					"warning",
+				);
 			}
 		}
 	});
@@ -515,8 +558,8 @@ export default function (pi: ExtensionAPI) {
 		description: "Regenerate .atl/skill-registry.md from local skill sources.",
 		handler: async (_args, ctx) => {
 			try {
-				ensureAtlIgnored(ctx.cwd);
-				const result = regenerateRegistry(ctx.cwd, true);
+				await ensureAtlIgnored(ctx.cwd);
+				const result = await regenerateRegistry(ctx.cwd, true);
 				ctx.ui.notify(
 					`Skill registry: ${result.skillCount} skill(s) written to ${REGISTRY_REL_PATH}`,
 					"info",

package/extensions/startup-banner.ts

@@ -280,15 +280,50 @@ function buildLetterStrokeMap(letterIdx: number): { orderMap: Map<string, number
   return { orderMap, maxOrder: Math.max(1, order - 1) };
 }
 
-const LETTER_STROKES = LETTER_SPANS.map((_, i) => buildLetterStrokeMap(i));
+type LetterStroke = { orderMap: Map<string, number>; maxOrder: number };
+
 const WRITING_START_TICK = 6;
-const LETTER_TICKS = LETTER_STROKES.map((s) =>
-  Math.max(5, Math.ceil(((s.maxOrder + 8) / 11) * 0.48)),
-);
-const LETTER_START_TICKS = LETTER_TICKS.map((_, i) =>
-  WRITING_START_TICK + LETTER_TICKS.slice(0, i).reduce((a, b) => a + b, 0),
+const FALLBACK_LETTER_TICKS = 8;
+
+const LETTER_STROKES: Array<LetterStroke | null> = LETTER_SPANS.map(() => null);
+const LETTER_TICKS: number[] = LETTER_SPANS.map(() => FALLBACK_LETTER_TICKS);
+const LETTER_START_TICKS: number[] = LETTER_SPANS.map(
+  (_, i) => WRITING_START_TICK + i * FALLBACK_LETTER_TICKS,
 );
-const WRITING_END_TICK = WRITING_START_TICK + LETTER_TICKS.reduce((a, b) => a + b, 0);
+let WRITING_END_TICK =
+  WRITING_START_TICK + LETTER_TICKS.reduce((a, b) => a + b, 0);
+
+function recomputeLetterTicks(): void {
+  for (let i = 0; i < LETTER_STROKES.length; i++) {
+    const stroke = LETTER_STROKES[i];
+    LETTER_TICKS[i] = stroke
+      ? Math.max(5, Math.ceil(((stroke.maxOrder + 8) / 11) * 0.48))
+      : FALLBACK_LETTER_TICKS;
+  }
+  let acc = WRITING_START_TICK;
+  for (let i = 0; i < LETTER_TICKS.length; i++) {
+    LETTER_START_TICKS[i] = acc;
+    acc += LETTER_TICKS[i];
+  }
+  WRITING_END_TICK = acc;
+}
+
+function allStrokesReady(): boolean {
+  for (const stroke of LETTER_STROKES) if (stroke === null) return false;
+  return true;
+}
+
+let warmupStarted = false;
+async function warmupLetterStrokes(): Promise<void> {
+  if (warmupStarted) return;
+  warmupStarted = true;
+  for (let i = 0; i < LETTER_SPANS.length; i++) {
+    if (LETTER_STROKES[i] !== null) continue;
+    LETTER_STROKES[i] = buildLetterStrokeMap(i);
+    recomputeLetterTicks();
+    await new Promise<void>((resolve) => setImmediate(resolve));
+  }
+}
 
 function buildPenLogoLine(
   line: string,
@@ -307,6 +342,10 @@ function buildPenLogoLine(
 
     const letterIdx = letterIndexAtX(x);
     const stroke = LETTER_STROKES[letterIdx];
+    if (stroke === null) {
+      out.push({ char: ch, type: "logo-ink" });
+      continue;
+    }
     const startTick = LETTER_START_TICKS[letterIdx];
     const duration = LETTER_TICKS[letterIdx];
     const progress = (tick - startTick) / Math.max(1, duration);
@@ -371,6 +410,29 @@ class LayoutBuilder {
   }
 }
 
+const FULL_INTRO_MIN_ROWS = 30;
+const FULL_INTRO_MIN_COLS = 80;
+const MINIMAL_INTRO_MIN_ROWS = 20;
+const MINIMAL_INTRO_MIN_COLS = 40;
+const RESIZE_DEBOUNCE_MS = 150;
+const RESIZE_GRACE_PERIOD_MS = 300;
+
+type IntroMode = "full" | "minimal" | "skip";
+
+function pickIntroMode(rows: number, cols: number): IntroMode {
+  if (rows >= FULL_INTRO_MIN_ROWS && cols >= FULL_INTRO_MIN_COLS) return "full";
+  if (rows >= MINIMAL_INTRO_MIN_ROWS && cols >= MINIMAL_INTRO_MIN_COLS) return "minimal";
+  return "skip";
+}
+
+function currentIntroMode(): IntroMode {
+  // process.stdout.rows/columns reflejan el tamaño real del TTY del proceso;
+  // el TUI no expone alto en render(width) y por eso lo leemos directo acá.
+  const rows = process.stdout.rows ?? 0;
+  const cols = process.stdout.columns ?? 0;
+  return pickIntroMode(rows, cols);
+}
+
 export default function (pi: ExtensionAPI) {
   pi.on("session_start", async (_event, ctx) => {
     if (!ctx.hasUI) return;
@@ -381,6 +443,12 @@ export default function (pi: ExtensionAPI) {
       !process.argv.every((arg) => arg.startsWith("-") || arg.endsWith(".ts"));
     if (isCLICommand) return;
 
+    if (currentIntroMode() === "skip") return;
+
+    // Fire-and-forget: el setup geométrico de cada letra corre en background
+    // para que la animación arranque en el primer frame sin bloquear el event loop.
+    void warmupLetterStrokes();
+
     process.stdout.write("\x1b[2J\x1b[3J\x1b[H");
 
     const roseBase = padLines(normalizeAscii(ROSE_LARGE_RAW));
@@ -442,33 +510,80 @@ export default function (pi: ExtensionAPI) {
     }, 200);
 
     let tick = 0;
-    const state = { timer: null as NodeJS.Timeout | null };
+    const state = {
+      timer: null as NodeJS.Timeout | null,
+      mode: currentIntroMode() as IntroMode,
+      resizeHandler: null as (() => void) | null,
+      resizeDebounceTimer: null as NodeJS.Timeout | null,
+    };
+
+    const cleanup = () => {
+      if (state.timer) {
+        clearInterval(state.timer);
+        state.timer = null;
+      }
+      if (state.resizeHandler) {
+        process.stdout.off("resize", state.resizeHandler);
+        state.resizeHandler = null;
+      }
+      if (state.resizeDebounceTimer) {
+        clearTimeout(state.resizeDebounceTimer);
+        state.resizeDebounceTimer = null;
+      }
+    };
 
     setTimeout(() => {
       ctx.ui.setHeader((tui, theme) => {
         if (state.timer) clearInterval(state.timer);
 
+        const animStart = Date.now();
+        const HARD_TIMEOUT_MS = 5000;
+
         state.timer = setInterval(() => {
           tick++;
-          if (tick > WRITING_END_TICK + 22) {
-            if (state.timer) {
-              clearInterval(state.timer);
-              state.timer = null;
-            }
+          const elapsed = Date.now() - animStart;
+          const finishedAnimation =
+            allStrokesReady() && tick > WRITING_END_TICK + 22;
+          if (finishedAnimation || elapsed > HARD_TIMEOUT_MS) {
+            cleanup();
             return;
           }
           try {
             tui.requestRender();
           } catch {
-            if (state.timer) {
-              clearInterval(state.timer);
-              state.timer = null;
-            }
+            cleanup();
           }
         }, 25);
 
+        // Grace period: pi-tui emite resizes transitorios mientras compone su layout inicial.
+        const bootStart = Date.now();
+        const resizeHandler = () => {
+          if (Date.now() - bootStart < RESIZE_GRACE_PERIOD_MS) return;
+          if (state.resizeDebounceTimer) clearTimeout(state.resizeDebounceTimer);
+          state.resizeDebounceTimer = setTimeout(() => {
+            state.resizeDebounceTimer = null;
+            const next = currentIntroMode();
+            if (next === state.mode) return;
+            state.mode = next;
+            if (next === "skip") {
+              cleanup();
+              process.stdout.write("\x1b[2J\x1b[3J\x1b[H");
+              return;
+            }
+            try {
+              tui.requestRender();
+            } catch {
+              cleanup();
+            }
+          }, RESIZE_DEBOUNCE_MS);
+        };
+        state.resizeHandler = resizeHandler;
+        process.stdout.on("resize", resizeHandler);
+
         return {
           render(width: number): string[] {
+            if (state.mode === "skip") return [];
+
             const flashStartTick = 10;
             const roseOpacity = Math.min(1, tick / 10);
             const flashPhase =
@@ -479,14 +594,29 @@ export default function (pi: ExtensionAPI) {
 
             const sideBySideMinWidth = roseBase.width + 3 + logoBase.width + 4;
             const wideStatsMinWidth = 122;
-            const horizontal = width >= sideBySideMinWidth;
+            const horizontal =
+              state.mode === "full" && width >= sideBySideMinWidth;
             const wideStats = width >= wideStatsMinWidth;
 
             const b = new LayoutBuilder();
             b.addRow();
             b.center(width);
 
-            if (horizontal) {
+            if (state.mode === "minimal") {
+              for (let logoI = 0; logoI < logoBase.lines.length; logoI++) {
+                const logoLine = logoBase.lines[logoI];
+                b.addRow();
+                b.lines[b.lines.length - 1].push(
+                  ...buildPenLogoLine(
+                    logoLine,
+                    logoI,
+                    logoBase.lines.length,
+                    tick,
+                  ),
+                );
+                b.center(width);
+              }
+            } else if (horizontal) {
               const rowCount = Math.max(
                 roseBase.lines.length,
                 logoBase.lines.length,
@@ -560,91 +690,93 @@ export default function (pi: ExtensionAPI) {
               }
             }
 
-            b.addRow();
-            b.center(width);
-
-            const fit = (v: unknown, w: number) =>
-              String(v ?? "")
-                .replace(/\s+/g, " ")
-                .trim()
-                .slice(0, w)
-                .padEnd(w);
-            const addWideRow = (
-              l1: string,
-              v1: string,
-              l2: string,
-              v2: string,
-            ) => {
+            if (state.mode === "full") {
               b.addRow();
-              b.add("label", fit(l1, 10));
-              b.add("none", " ");
-              b.add("value", fit(v1, 48));
-              b.add("none", "   ");
-              b.add("label", fit(l2, 12));
-              b.add("none", " ");
-              b.add("value", fit(v2, 46));
               b.center(width);
-            };
-            const narrowRows: Array<[string, string]> = [
-              ["GIT:", gitBranch],
-              ["PATH:", ctx.cwd],
-              ["MCP:", `${mcpServersCount} server(s)`],
-              ["PLUGINS:", `${packagesCount} package(s)`],
-              ["AGENTS:", `${skills.length} loaded`],
-              ["EXTENSIONS:", `${extensionsCount} active`],
-              ["VER:", `v${VERSION}`],
-              ["TOOLS:", `${customTools.length} custom`],
-            ];
-            const narrowLabelW = Math.max(...narrowRows.map(([l]) => l.length));
-            const narrowValueW = Math.max(
-              0,
-              Math.min(
-                Math.max(...narrowRows.map(([, v]) => v.length)),
-                Math.max(8, width - narrowLabelW - 4),
-              ),
-            );
-            const addNarrowRow = (label: string, value: string) => {
+
+              const fit = (v: unknown, w: number) =>
+                String(v ?? "")
+                  .replace(/\s+/g, " ")
+                  .trim()
+                  .slice(0, w)
+                  .padEnd(w);
+              const addWideRow = (
+                l1: string,
+                v1: string,
+                l2: string,
+                v2: string,
+              ) => {
+                b.addRow();
+                b.add("label", fit(l1, 10));
+                b.add("none", " ");
+                b.add("value", fit(v1, 48));
+                b.add("none", "   ");
+                b.add("label", fit(l2, 12));
+                b.add("none", " ");
+                b.add("value", fit(v2, 46));
+                b.center(width);
+              };
+              const narrowRows: Array<[string, string]> = [
+                ["GIT:", gitBranch],
+                ["PATH:", ctx.cwd],
+                ["MCP:", `${mcpServersCount} server(s)`],
+                ["PLUGINS:", `${packagesCount} package(s)`],
+                ["AGENTS:", `${skills.length} loaded`],
+                ["EXTENSIONS:", `${extensionsCount} active`],
+                ["VER:", `v${VERSION}`],
+                ["TOOLS:", `${customTools.length} custom`],
+              ];
+              const narrowLabelW = Math.max(...narrowRows.map(([l]) => l.length));
+              const narrowValueW = Math.max(
+                0,
+                Math.min(
+                  Math.max(...narrowRows.map(([, v]) => v.length)),
+                  Math.max(8, width - narrowLabelW - 4),
+                ),
+              );
+              const addNarrowRow = (label: string, value: string) => {
+                b.addRow();
+                b.add("label", label.padEnd(narrowLabelW));
+                b.add("none", "  ");
+                b.add("value", fit(value, narrowValueW));
+                b.center(width);
+              };
+
+              if (wideStats) {
+                addWideRow("GIT:", gitBranch, "PATH:", ctx.cwd);
+                addWideRow(
+                  "MCP:",
+                  `${mcpServersCount} server(s)`,
+                  "PLUGINS:",
+                  `${packagesCount} package(s)`,
+                );
+                addWideRow(
+                  "AGENTS:",
+                  `${skills.length} loaded`,
+                  "EXTENSIONS:",
+                  `${extensionsCount} active`,
+                );
+                addWideRow(
+                  "VER:",
+                  `v${VERSION}`,
+                  "TOOLS:",
+                  `${customTools.length} custom`,
+                );
+              } else {
+                addNarrowRow("GIT:", gitBranch);
+                addNarrowRow("PATH:", ctx.cwd);
+                addNarrowRow("MCP:", `${mcpServersCount} server(s)`);
+                addNarrowRow("PLUGINS:", `${packagesCount} package(s)`);
+                addNarrowRow("AGENTS:", `${skills.length} loaded`);
+                addNarrowRow("EXTENSIONS:", `${extensionsCount} active`);
+                addNarrowRow("VER:", `v${VERSION}`);
+                addNarrowRow("TOOLS:", `${customTools.length} custom`);
+              }
+
               b.addRow();
-              b.add("label", label.padEnd(narrowLabelW));
-              b.add("none", "  ");
-              b.add("value", fit(value, narrowValueW));
               b.center(width);
-            };
-
-            if (wideStats) {
-              addWideRow("GIT:", gitBranch, "PATH:", ctx.cwd);
-              addWideRow(
-                "MCP:",
-                `${mcpServersCount} server(s)`,
-                "PLUGINS:",
-                `${packagesCount} package(s)`,
-              );
-              addWideRow(
-                "AGENTS:",
-                `${skills.length} loaded`,
-                "EXTENSIONS:",
-                `${extensionsCount} active`,
-              );
-              addWideRow(
-                "VER:",
-                `v${VERSION}`,
-                "TOOLS:",
-                `${customTools.length} custom`,
-              );
-            } else {
-              addNarrowRow("GIT:", gitBranch);
-              addNarrowRow("PATH:", ctx.cwd);
-              addNarrowRow("MCP:", `${mcpServersCount} server(s)`);
-              addNarrowRow("PLUGINS:", `${packagesCount} package(s)`);
-              addNarrowRow("AGENTS:", `${skills.length} loaded`);
-              addNarrowRow("EXTENSIONS:", `${extensionsCount} active`);
-              addNarrowRow("VER:", `v${VERSION}`);
-              addNarrowRow("TOOLS:", `${customTools.length} custom`);
             }
 
-            b.addRow();
-            b.center(width);
-
             const out: string[] = [];
             const layout = b.lines;
 
@@ -776,10 +908,7 @@ export default function (pi: ExtensionAPI) {
             return out;
           },
           invalidate() {
-            if (state.timer) {
-              clearInterval(state.timer);
-              state.timer = null;
-            }
+            cleanup();
           },
         };
       });

package/lib/sdd-preflight.ts

@@ -24,13 +24,24 @@ export interface SddPreflightPreferences {
 
 interface SddPreflightCallbacks {
 	pi: ExtensionAPI;
-	installAssets?: (cwd: string) => {
-		agents: number;
-		chains: number;
-		support: number;
-		skipped: number;
-	};
-	applyModelConfig?: (cwd: string) => { updated: number; skipped: number };
+	installAssets?: (cwd: string) =>
+		| {
+				agents: number;
+				chains: number;
+				support: number;
+				skipped: number;
+		  }
+		| Promise<{
+				agents: number;
+				chains: number;
+				support: number;
+				skipped: number;
+		  }>;
+	applyModelConfig?: (
+		cwd: string,
+	) =>
+		| { updated: number; skipped: number }
+		| Promise<{ updated: number; skipped: number }>;
 }
 
 const DEFAULT_SDD_PREFLIGHT: SddPreflightPreferences = {
@@ -219,8 +230,13 @@ export async function ensureSddPreflight(
 	const promise = (async () => {
 		const engramAvailable = hasWritableEngramTool(callbacks.pi);
 		const prefs = await collectSddPreflightPreferences(ctx, engramAvailable);
-		const result = callbacks.installAssets?.(ctx.cwd) ?? installSddAssets(ctx.cwd, false);
-		const modelResult = callbacks.applyModelConfig?.(ctx.cwd) ?? { updated: 0, skipped: 0 };
+		const result =
+			(await callbacks.installAssets?.(ctx.cwd)) ??
+			installSddAssets(ctx.cwd, false);
+		const modelResult = (await callbacks.applyModelConfig?.(ctx.cwd)) ?? {
+			updated: 0,
+			skipped: 0,
+		};
 		if (ctx.hasUI) {
 			ctx.ui.notify(
 				[

package/package.json

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

package/tests/skill-registry.test.ts

@@ -105,12 +105,15 @@ test("project-scoped duplicate wins over user duplicate", () => {
 	assert.equal(chosen.path, projectPath);
 });
 
-test("uniqueExistingDirs normalizes duplicates and ignores missing roots", () => {
+test("uniqueExistingDirs normalizes duplicates and ignores missing roots", async () => {
 	const root = join(tmpdir(), `gentle-pi-existing-${Date.now()}`);
 	const existing = join(root, "skills");
 	mkdirSync(existing, { recursive: true });
 
-	assert.deepEqual(__testing.uniqueExistingDirs([existing, join(root, "skills/"), join(root, "missing")]), [existing]);
+	assert.deepEqual(
+		await __testing.uniqueExistingDirs([existing, join(root, "skills/"), join(root, "missing")]),
+		[existing],
+	);
 });
 
 test("startup skip honors no skill registry controls", () => {