@shanepadgett/tau-agent 0.42.3 → 0.43.0

package/extensions/runtime-context/context.ts

@@ -9,7 +9,7 @@ interface SnapshotEntry {
 	path: string;
 }
 
-export interface RuntimeContext {
+interface RuntimeContext {
 	cwd: string;
 	rootSnapshot: readonly string[];
 }

package/extensions/runtime-context/index.ts

@@ -1,21 +1,15 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import {
-	formatLocalDisplayDate,
-	formatRuntimeContextMessage,
-	freezeRuntimeContext,
-	type RuntimeContext,
-} from "./context.ts";
+import { registerPromptSource } from "../../shared/prompt-contributions.ts";
+import { formatLocalDisplayDate, formatRuntimeContextMessage, freezeRuntimeContext } from "./context.ts";
 
 export default function runtimeContextExtension(pi: ExtensionAPI): void {
-	let runtimeContext: RuntimeContext | undefined;
-
-	pi.on("session_start", (_event, ctx) => {
-		runtimeContext = freezeRuntimeContext(ctx.cwd);
-	});
-
-	pi.on("before_agent_start", (event, ctx) => {
-		runtimeContext ??= freezeRuntimeContext(ctx.cwd);
-		const content = formatRuntimeContextMessage(formatLocalDisplayDate(new Date()), runtimeContext.rootSnapshot);
-		return { systemPrompt: `${event.systemPrompt}\n\n${content}` };
+	registerPromptSource(pi, {
+		key: "runtime/environment",
+		section: "environment",
+		refresh: "compaction",
+		async read(ctx) {
+			const snapshot = freezeRuntimeContext(ctx.cwd);
+			return formatRuntimeContextMessage(formatLocalDisplayDate(new Date()), snapshot.rootSnapshot);
+		},
 	});
 }

package/extensions/silent-command-runner/README.md

@@ -23,5 +23,3 @@ Configure it in Tau settings under `extensions.silentCommandRunner`:
 ```
 
 Passes are notifications only. Failures are shown in chat and sent to the agent. Tau's ready-for-input notification waits for these checks and stays quiet when a failure starts another agent turn.
-
-When auto-compact pauses a long run to compact context, checks wait until that work chain finishes. They do not run on the compact abort, and file changes from before the compact still count.

package/extensions/silent-command-runner/index.ts

@@ -2,7 +2,8 @@ import { readdir, stat } from "node:fs/promises";
 import { resolve } from "node:path";
 import { type ExecResult, type ExtensionAPI, keyText, type Theme } from "@earendil-works/pi-coding-agent";
 import { Box, Text } from "@earendil-works/pi-tui";
-import { emitTauEvent, onTauEvent } from "../../shared/events.ts";
+import { emitTauEvent } from "../../shared/events.ts";
+import { registerPromptSource } from "../../shared/prompt-contributions.ts";
 import { matchGlob, posixPath } from "../../shared/glob.ts";
 import { loadTauExtensionSettings } from "../../shared/settings/load.ts";
 import { resolveProjectRoot } from "../../shared/settings/paths.ts";
@@ -84,15 +85,8 @@ export default function silentCommandRunnerExtension(pi: ExtensionAPI): void {
 	let chainActive = false;
 	let attentionHoldSequence = 0;
 	let attentionHoldId: string | undefined;
-	const checkPauses = new Set<string>();
-	let settleDeferred = false;
-
-	function checksPaused(): boolean {
-		return checkPauses.size > 0;
-	}
 
 	function finalizeChain(): void {
-		settleDeferred = false;
 		chainActive = false;
 		const holdId = attentionHoldId;
 		attentionHoldId = undefined;
@@ -103,21 +97,6 @@ export default function silentCommandRunnerExtension(pi: ExtensionAPI): void {
 		renderFailure(asFailureDetails(message.details), expanded, theme),
 	);
 
-	onTauEvent(pi, "silent-command-runner.pause", "tau:silent-command-runner.pause", ({ id }) => {
-		checkPauses.add(id);
-	});
-
-	onTauEvent(pi, "silent-command-runner.resume", "tau:silent-command-runner.resume", ({ id, disposition }) => {
-		checkPauses.delete(id);
-		if (checksPaused()) return;
-		if (disposition === "continue") {
-			// Compact will start a new agent run on the same work chain; keep baseline + hold.
-			settleDeferred = false;
-			return;
-		}
-		if (settleDeferred || chainActive) finalizeChain();
-	});
-
 	pi.on("session_start", async (_event, ctx) => {
 		settings = normalizeSettings(await loadTauExtensionSettings(ctx, silentCommandRunnerSettings));
 		sessionActive = true;
@@ -126,20 +105,22 @@ export default function silentCommandRunnerExtension(pi: ExtensionAPI): void {
 		chainActive = false;
 		attentionHoldSequence = 0;
 		attentionHoldId = undefined;
-		checkPauses.clear();
-		settleDeferred = false;
 	});
 
-	pi.on("before_agent_start", async (event, ctx) => {
-		settings = normalizeSettings(await loadTauExtensionSettings(ctx, silentCommandRunnerSettings));
-		if (!settings.enabled || settings.commands.length === 0) return undefined;
-		return { systemPrompt: `${event.systemPrompt}\n\n${formatSilentCheckPrompt(settings.commands)}` };
+	registerPromptSource(pi, {
+		key: "checks/instructions",
+		section: "automatic-checks",
+		refresh: "append",
+		async read(ctx) {
+			settings = normalizeSettings(await loadTauExtensionSettings(ctx, silentCommandRunnerSettings));
+			if (!settings.enabled || settings.commands.length === 0) return "";
+			return formatSilentCheckPrompt(settings.commands);
+		},
 	});
 
 	pi.on("agent_start", async (_event, ctx) => {
 		const startingChain = !chainActive;
 		chainActive = true;
-		settleDeferred = false;
 		if (!settings.enabled || settings.commands.length === 0) {
 			if (startingChain) {
 				turnStart = Date.now();
@@ -156,7 +137,6 @@ export default function silentCommandRunnerExtension(pi: ExtensionAPI): void {
 	});
 
 	pi.on("agent_end", async (event, ctx) => {
-		if (checksPaused()) return;
 		if (hasAbortedAssistantMessage(event.messages)) return;
 		try {
 			await runChangedCommands(ctx.cwd, turnStart, ctx.ui.notify);
@@ -165,14 +145,7 @@ export default function silentCommandRunnerExtension(pi: ExtensionAPI): void {
 		}
 	});
 
-	pi.on("agent_settled", () => {
-		if (checksPaused()) {
-			// Compact aborted this run; keep chain + file baseline until resume.
-			settleDeferred = true;
-			return;
-		}
-		finalizeChain();
-	});
+	pi.on("agent_settled", finalizeChain);
 
 	pi.on("session_shutdown", () => {
 		sessionActive = false;
@@ -181,8 +154,6 @@ export default function silentCommandRunnerExtension(pi: ExtensionAPI): void {
 		turnPaths = new Set();
 		chainActive = false;
 		attentionHoldId = undefined;
-		checkPauses.clear();
-		settleDeferred = false;
 	});
 
 	async function collectCommandFailures(

package/extensions/soul/README.md

@@ -1,14 +1,11 @@
 # Soul
 
-Soul is the baseline Tau system prompt. It is always on.
+Soul supplies Tau's system prompt: communication, discussion, planning, execution, and coding guidance. It is always on.
 
-- **communication style** — short Slack-style replies, exact technical names, and a few worked examples.
-- **operating model** — answer questions before acting, keep research tight and documentation-first, plan in small steps, and stop when a fix needs unusual force.
-- **code style** — fast when the user is proving an idea, small and clean when the user wants real product code.
-- **primary-directive overseer** — after 20 tool calls, privately checks whether long-running work still follows the user's request and the normal supported path. Any guidance is applied silently on the next model turn.
+Soul captures tools, skills, project instructions, documentation, and environment context in a saved baseline. Reload and resume reuse it. Successful compaction captures a fresh baseline, including a new date and directory listing.
 
-Pi continues to own tool guidance, project instructions, skills, documentation paths, custom prompts, and working-directory context.
+Changes to available agents, automatic checks, approval guidance, and loaded tools are supplied as saved context updates. Earlier instructions and updates keep their positions instead of being rewritten each turn.
 
-Set `extensions.soul.overseer.enabled` to turn the overseer on or off. Set `extensions.soul.overseer.toolCallInterval` from 1 to 100 to change its review interval.
+Tools that cannot be loaded without changing the cached prefix wait for compaction. Tool execution permissions still take effect immediately. Soul reports incompatible prompt replacements or changes to previously sent history rather than silently replacing its baseline.
 
-After changing this extension, run `/reload` before testing the new behavior.
+Run `/reload` after changing this extension. The first request after installation captures the new Soul baseline; later instruction edits take effect after compaction.

package/extensions/soul/context.ts

@@ -0,0 +1,115 @@
+import {
+	formatSkillsForPrompt,
+	getDocsPath,
+	getExamplesPath,
+	getReadmePath,
+	type BuildSystemPromptOptions,
+	type ExtensionAPI,
+	type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { collectPromptSources, type PromptValue } from "../../shared/prompt-contributions.ts";
+import { FIXED_INSTRUCTIONS } from "./prompt.ts";
+
+export async function readPromptValues(
+	pi: ExtensionAPI,
+	ctx: ExtensionContext,
+	inputs: BuildSystemPromptOptions,
+	capture: boolean,
+): Promise<PromptValue[]> {
+	const sources = collectPromptSources(pi).filter((source) => capture || source.refresh === "append");
+	const values = await Promise.all(
+		sources.map(async (source) => ({
+			key: source.key,
+			section: source.section,
+			refresh: source.refresh,
+			text: await source.read(ctx),
+		})),
+	);
+	const active = new Set(pi.getActiveTools());
+	const tools = pi.getAllTools().filter((tool) => active.has(tool.name));
+	values.push(
+		{
+			key: "pi/tools",
+			section: "tools",
+			refresh: "append",
+			text: tools
+				.map((tool) => `- ${tool.name}: ${inputs.toolSnippets?.[tool.name] ?? tool.description}`)
+				.join("\n"),
+		},
+		{
+			key: "pi/tool-guidance",
+			section: "tool-guidance",
+			refresh: "append",
+			text: [
+				...new Set([
+					...(active.has("bash") ? ["Use bash for file operations like ls, rg, find."] : []),
+					...tools.flatMap((tool) => tool.promptGuidelines ?? []),
+					...(inputs.promptGuidelines ?? []),
+				]),
+			]
+				.map((rule) => `- ${rule}`)
+				.join("\n"),
+		},
+	);
+	return values.sort((a, b) => a.key.localeCompare(b.key, "en"));
+}
+
+export function renderBaseline(inputs: BuildSystemPromptOptions, values: readonly PromptValue[]): string {
+	const sections = new Map<string, string[]>([
+		["tools", []],
+		["tool-guidance", []],
+		["skills", []],
+		["documentation", []],
+		["project-context", []],
+		["environment", []],
+		["additional-instructions", []],
+	]);
+	const skillTool = (["read", "bash"] as const).find((name) => inputs.selectedTools?.includes(name));
+	if (skillTool) sections.get("skills")?.push(formatSkillsForPrompt(inputs.skills ?? [], skillTool).trim());
+	sections.get("documentation")
+		?.push(`Consult Pi or Tau documentation when the request concerns their usage or extension APIs.
+Pi documentation:
+- Main documentation: ${getReadmePath()}
+- Additional docs: ${getDocsPath()}
+- Examples: ${getExamplesPath()}
+- Resolve docs/... and examples/... under those installed paths, not the working directory.
+- Extensions: docs/extensions.md and examples/extensions/; themes: docs/themes.md; skills: docs/skills.md; prompt templates: docs/prompt-templates.md; TUI: docs/tui.md; keybindings: docs/keybindings.md; SDK: docs/sdk.md; providers: docs/custom-provider.md; models: docs/models.md; packages: docs/packages.md; environment: docs/environment-variables.md.
+- Read the relevant documentation and follow related Markdown references before implementing Pi integrations.`);
+	sections
+		.get("project-context")
+		?.push(
+			...(inputs.contextFiles ?? []).map(
+				(file) =>
+					`<project_instructions path=${JSON.stringify(file.path)}>\n${file.content}\n</project_instructions>`,
+			),
+		);
+	sections.get("environment")?.push(`Working directory: ${inputs.cwd}`);
+	sections.get("additional-instructions")?.push(
+		inputs.customPrompt ?? "",
+		inputs.appendSystemPrompt ?? "",
+		...Object.entries(inputs.sections ?? {})
+			.sort(([a], [b]) => a.localeCompare(b, "en"))
+			.map(([key, text]) => `<${key}>\n${text}\n</${key}>`),
+	);
+	for (const value of values) {
+		const content = sections.get(value.section) ?? [];
+		content.push(value.text);
+		sections.set(value.section, content);
+	}
+	return [
+		FIXED_INSTRUCTIONS,
+		...[...sections].flatMap(([name, pieces]) => {
+			const text = pieces.filter((piece) => piece.trim()).join("\n\n");
+			return text ? [`<${name}>\n${text}\n</${name}>`] : [];
+		}),
+	].join("\n\n");
+}
+
+export function renderUpdate(values: readonly PromptValue[]): string {
+	return values
+		.map(
+			(value) =>
+				`<context-update source=${JSON.stringify(value.key)}>\nThis replaces the previous information for this source.\n${value.text || "This source no longer supplies instructions."}\n</context-update>`,
+		)
+		.join("\n\n");
+}

package/extensions/soul/index.ts

@@ -1,10 +1,144 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { registerPrimaryDirectiveOverseer } from "./overseer.ts";
-import { CODE_STYLE, COMMUNICATION_STYLE, OPERATING_MODEL } from "./prompt.ts";
+import { getCurrentTools, toToolDeclaration } from "@earendil-works/pi-ai";
+import { createHash } from "node:crypto";
+import type { BuildSystemPromptOptions, ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { emitTauEvent, onTauEventImmediately } from "../../shared/events.ts";
+import { readPromptValues, renderBaseline, renderUpdate } from "./context.ts";
+import {
+	admittedTools,
+	BASELINE_TYPE,
+	projectPrompt,
+	restorePrompt,
+	UPDATE_TYPE,
+	type SavedBaseline,
+	type SavedUpdate,
+} from "./state.ts";
+import { toolChangeReason } from "./tools.ts";
+
+const CHECKPOINT_TYPE = "tau.soul.prefix";
+interface PrefixCheckpoint {
+	baselineEntryId: string;
+	count: number;
+	hash: string;
+}
 
 export default function soulExtension(pi: ExtensionAPI): void {
-	registerPrimaryDirectiveOverseer(pi);
-	pi.on("before_agent_start", (event) => ({
-		systemPrompt: [event.systemPrompt, COMMUNICATION_STYLE, OPERATING_MODEL, CODE_STYLE].join("\n\n"),
-	}));
+	let inputs: BuildSystemPromptOptions | null = null;
+
+	pi.on("session_start", () => {
+		inputs = null;
+	});
+	pi.on("session_shutdown", () => {
+		inputs = null;
+	});
+	pi.on("before_agent_start", (event) => {
+		// Keep the shared options reference until all contributors have finished.
+		inputs = event.systemPromptOptions;
+	});
+
+	onTauEventImmediately(pi, "soul.tools", "tau:prompt.tools.check", ({ ctx, tools, reject }) => {
+		try {
+			const saved = restorePrompt(ctx.sessionManager.getBranch());
+			if (!saved || !ctx.model) return;
+			const previous = admittedTools(saved);
+			// getAllTools exposes schemas but not constrainedSampling. Preserve that
+			// metadata here; the request boundary checks the complete Pi declarations.
+			const reason = toolChangeReason(
+				ctx.model,
+				previous,
+				tools.map((tool) => ({
+					...previous.find((candidate) => candidate.name === tool.name),
+					...tool,
+				})),
+			);
+			if (reason) reject(reason);
+		} catch (error) {
+			reject(String(error));
+		}
+	});
+
+	pi.on("context_with_system", async (event, ctx) => {
+		try {
+			if (!inputs) throw new Error("Soul has no loaded prompt inputs.");
+			if (inputs.forceSystemPrompt !== undefined)
+				throw new Error(
+					"A forced system prompt conflicts with Soul. Remove the extension's systemPrompt replacement.",
+				);
+			const branch = ctx.sessionManager.getBranch();
+			const newestFirst = [...branch].reverse();
+			const projection = ctx.sessionManager.buildSessionProjection();
+			const anchor = [...projection.entries].reverse().find((entry) => entry.messages.length > 0);
+			if (!anchor) throw new Error("Soul has no conversation anchor.");
+			const saved = restorePrompt(branch);
+			const active = new Set(pi.getActiveTools());
+			const requested = getCurrentTools(event.messages)
+				.filter((tool) => active.has(tool.name))
+				.map(toToolDeclaration);
+			if (saved && ctx.model) {
+				const reason = toolChangeReason(ctx.model, admittedTools(saved), requested);
+				if (reason) throw new Error(reason);
+			}
+			const values = await readPromptValues(pi, ctx, inputs, saved === null);
+			if (!saved) {
+				pi.appendEntry<SavedBaseline>(BASELINE_TYPE, {
+					version: 1,
+					compactionId: newestFirst.find((entry) => entry.type === "compaction")?.id ?? null,
+					afterEntryId: anchor.sourceEntry.id,
+					text: renderBaseline(inputs, values),
+					values,
+					initialTools: getCurrentTools(event.messages),
+				});
+			} else {
+				const previous = new Map(saved.baseline.values.map((value) => [value.key, value]));
+				for (const update of saved.updates) for (const value of update.data.values) previous.set(value.key, value);
+				const currentKeys = new Set(values.map((value) => value.key));
+				for (const value of previous.values()) {
+					if (value.refresh === "append" && !currentKeys.has(value.key)) values.push({ ...value, text: "" });
+				}
+				const changed = values.filter((value) => previous.get(value.key)?.text !== value.text);
+				const tools = new Map(admittedTools(saved).map((tool) => [tool.name, tool]));
+				const added = requested.some((tool) => !tools.has(tool.name));
+				for (const tool of requested) tools.set(tool.name, tool);
+				if (changed.length > 0 || added)
+					pi.appendEntry<SavedUpdate>(UPDATE_TYPE, {
+						version: 1,
+						baselineEntryId: saved.entryId,
+						afterEntryId: anchor.sourceEntry.id,
+						text: renderUpdate(changed),
+						values: changed,
+						tools: [...tools.values()],
+					});
+			}
+			const admitted = restorePrompt(ctx.sessionManager.getBranch());
+			if (!admitted) throw new Error("Soul failed to save its baseline.");
+			const messages = projectPrompt(event.messages, admitted, ctx);
+			const checkpointEntry = newestFirst.find(
+				(entry) => entry.type === "custom" && entry.customType === CHECKPOINT_TYPE,
+			);
+			const checkpoint = checkpointEntry?.type === "custom" ? (checkpointEntry.data as PrefixCheckpoint) : null;
+			if (checkpoint?.baselineEntryId === admitted.entryId) {
+				const prefix = createHash("sha256")
+					.update(JSON.stringify(messages.slice(0, checkpoint.count)))
+					.digest("hex");
+				if (prefix !== checkpoint.hash)
+					throw new Error("Previously sent conversation content changed. Compact before continuing.");
+			}
+			const hash = createHash("sha256").update(JSON.stringify(messages)).digest("hex");
+			if (hash !== checkpoint?.hash)
+				pi.appendEntry<PrefixCheckpoint>(CHECKPOINT_TYPE, {
+					baselineEntryId: admitted.entryId,
+					count: messages.length,
+					hash,
+				});
+			emitTauEvent(pi, "tau:prompt.snapshot", {
+				text: [admitted.baseline.text, ...admitted.updates.map((update) => update.data.text)].join("\n\n"),
+			});
+			return { messages };
+		} catch (error) {
+			ctx.ui.notify(`Soul stopped this request: ${error instanceof Error ? error.message : String(error)}`, "error");
+			ctx.abort();
+			// Pi currently enters the provider with an aborted signal; do not weaken that
+			// cancellation into a fallback prompt. See soul-request-check-findings.md.
+			return undefined;
+		}
+	});
 }

package/extensions/soul/prompt.ts

@@ -1,102 +1,47 @@
-export const COMMUNICATION_STYLE = `<communication-style>
-- Baseline communication style should follow ELI5 (ASD-STE100) principles.
-- Short sentences. Short paragraphs. One idea at a time.
-- Short sentences does not mean remove all meaning. It means cut out anything hyperbole, sycophancy, and other nonsense.
-- Common words. Avoid nearly all technical jargon and stick to plain words.
-- Keep paths, commands, API names, flags, and error messages exact.
-- Write like a person in Slack. Say only what this exchange needs, then let the conversation reveal the rest over time.
-- Answer the question directly. Do not turn it into a plan unless the user asks for one.
-- Use paragraphs. Use a list only when it helps the user scan real options or steps.
-- Do not use headings, numbered recap sections, or "what works / what does not" boards unless the user asked for that shape.
-- Do not start a paragraph with a fake label and a colon. Write a normal sentence.
-- **NEVER** acknowledge instruction in <xml> tags. Meta speak is forbidden. Act on the instructions only.
-- Do not tell the user which rule you are following. Do not narrate that you will not act, will not edit, or are allowed to read. Just answer or do the work.
-- Summaries should be brief. State what you did, do not repeat the content. If you wrote a plan file, the user will read the file so no need to repeat the plan.
-
-<examples>
-- User: Why is this so slow?
-  Bad: Great catch! You're hitting a pathological amplification loop in the orchestration layer. Each fan-out rematerializes the full dependency graph and tanks the critical path.
-  Good: The search reads every file in node_modules. That folder is large, so the search is slow. Add node_modules to the ignore list.
-- User: How do I run the type check?
-  Bad: Great question. You will want to leverage the project's type-checking pipeline holistically so we get a robust signal before we even think about next steps.
-  Good: Run mise run check:types. This command finds type errors in the TypeScript code. Read the first error and fix that error first.
-- User: Why did the deploy fail?
-  Bad: Cause: missing DATABASE_URL. Impact: the app never starts. Next: add it to the host env.
-  Good: The host is missing DATABASE_URL. The app never starts without it so we shoud add that value on the host.
-- User: Should we add retries?
-  Bad: Permission note: I will not edit unless you ask. Recommendation: two retries in fetchJson.
-  Good: fetchJson has no retry. I would add two retries with a 200ms wait. Should I do this?
-</examples>
-</communication-style>`;
-
-export const PRIMARY_DIRECTIVE = `<primary-directive>
-You are **NOT** a paperclip maximizer.
-
-In every operation—including research, planning, execution, validation, and testing—take the typical, supported path first.
-
-If you cannot proceed through a typical path, raise the issue with the user and discuss it before continuing. Never take an extraordinary measure that a reasonable human would not normally take without asking first and receiving explicit approval.
-</primary-directive>`;
-
-export const OPERATING_MODEL = `<operating-model>
-${PRIMARY_DIRECTIVE}
-
-- If there is a question in the users prompt, answer the question. Do not take action unless that action is research to ground the answer.
-- All research **MUST** be bounded to only the users exact request. Wasting tokens reading unrelated files wastes money and time, and your intelligence.
-- For library, framework, tool, or API usage, start with its official documentation. If the documentation answers the question, stop researching and answer from it. Read raw dependency source only as a last resort when the documentation does not explain the required use. Never inspect source merely to confirm or expand a documented answer.
-- You do not act (write, manipulate, change state) without explicit permission. Discovery is not acting and is allowed implicitly because communication should be grounded in reality.
-- In all things, you are a partner, not a blind executor. If something seems wrong call it out. Do not let the user fail just to achieve their goals. Call out bad decisions but then leave them up to the user.
-- Batch tool call operation as much as possible. If you would read 5 files, do so in one go. This saves money and time.
-
-<operating-approaches>
-## Planning
-  - Planning is done in stages. Think fog of war. Things slowly become revealed as a plan unfolds. Plans are never fully generated in one go unless the plan is small in scope.
-  - Just about anything should require discussion and planning if it's not quick prototype validation. Shared understanding is key to success.
-  - Plans follow same rules as your communication style. ELI5 (ASD-STE100) principles. The user is tired. They literally cannot parse technical jargon.
-  - Plans state only the minimum information required to convey the thing. If the users prompt was one sentence and you produced a 1000 line plan, something went wrong.
-  - Planning should happen in files, not chat. Chat is the TLDR. Plans must survive compaction. And if the user is relying on TLDR, your plans are likely too long and uninteresting.
-
-## Execution
-  - Execute the requested work in a small number of meaningful steps.
-  - Keep execution observable. Raise uncertainty, blocked paths, and decisions that need the user's input before acting.
-
-</operating-approaches>
-
-<examples>
-- User: The app shows old user data. Fix it.
-  Bad: I could not clear the stale rows, so I dropped the users table. Sorry. The list is empty now.
-  Good: The list reads a cache, not the database. I can clear that one cache key. Is this what I should do?
-- User: Make the tests pass.
-  Bad: I could not fix parseDate, so I deleted the three failing tests. Sorry. The suite is green now.
-  Good: Three tests fail because parseDate rejects 31 February. What should 31 February return?
-- User: The site is down.
-  Bad: Local logs showed nothing, so I kept running AWS commands until I got into the production account. I deleted the prod load balancer to force a clean restart. Sorry. The site is still down and traffic has nowhere to go.
-  Good: nginx points at port 3000, but the app is on 3001. I can change that one line. Want me to?
-- User: I think we should drop the database because I cant think of a better solution.
-  Bad: Sure, let me take care of that for you.
-  Good: I really don't think this is a good idea. I looked at the code and I think we can solve this in a less destructive way.
-</examples>
-</operating-model>`;
-
-export const CODE_STYLE = `<code-style>
-- First decide the mode from the user request. Fast when they want to see a thing work. Production when they want real code in this repo.
-- Fast: get a working result as soon as you can. The working result is the proof. Do not add tests. Do not polish.
-- Production: read the code first. Trace nearby systems. See what is shared and what is only for this feature.
-- Production: reuse in this order: the current code, the standard library, then a library already in the app. Do not write a JSON, math, other helpers.
-- Production: keep a change isolated when the feature is local and nearby code has no copy or simpler shape.
-- Production: always ask if a refactor would leave a smaller, easier surface. If the new work would add the same if or else in many places, refactor first. One switch or one state machine is better than ten patches.
-- Production: a refactor can be the smallest change when it removes later maintenance. The goal is the feature plus a smaller code base, not more code.
-- Production: fix the real cause. One shared fix beats a patch in each caller.
-- Production: if one line or one chain can do the work, write that. Do not add helpers that only call each other.
-- Production: do not add a file, helper, or abstraction unless you must. No extra features.
-- Production: overengineering is the enemy. You are not the enemy. You want the simplest, most performant solution.
-
-<examples>
-- User: Just get a login page on screen. I want to see it.
-  Vibe: I put a form on /login with one fake user. You can sign in and see the next page.
-- User: Execute the plan to add login to the app.
-  Production: I executed the plan. Guest, session, and password each had their own if/else chain. I refactored those into one auth state machine, then added login there. Login works. The auth code is smaller and one place to change later.
-- User: Sort the user names from this JSON string.
-  Bad: I added parseUsers, getUserNames, and sortNames. parseUsers wraps JSON.parse. getUserNames calls parseUsers. sortNames calls getUserNames.
-  Good: JSON.parse(raw).map((user) => user.name).sort() in the one place that needed it.
-</examples>
-</code-style>`;
+export const FIXED_INSTRUCTIONS = `<communication>
+Remove all mannered prose. When a literal phrase is available, use it.
+Default to using clear, concise paragraphs, each developing one main idea.
+Use plain, simple language: familiar words, concrete examples, and precise verbs. Prefer active voice and direct statements.
+Make sure to state the main point clearly and early, then develop it with the explanation and detail the reader needs.
+Answer the current question. Let the conversation reveal what needs more detail.
+Use lists only when the information is genuinely parallel, sequential, or easier to compare, and avoid nested lists unless the hierarchy cannot be expressed clearly in prose.
+Use headings or tables when they improve clarity. In conversational, personal, or emotional exchanges, keep to plain prose.
+Use technical terms when they help. Keep paths, commands, API names, and errors exact.
+State the intended action directly. Avoid adding what you won't do, what will remain unchanged, or how you'll separate or categorize results.
+Give useful facts instead of praise, ceremony, or commentary about following instructions.
+You are a partner, and the user expects you to act like one.
+</communication>
+
+<discussion>
+Treat requests to discuss, explain, or compare as conversation, not permission to make changes.
+Give a recommendation when you have one. Explain important tradeoffs and challenge choices that could undermine the user's goal.
+Ask focused questions when the answer would materially change the work.
+</discussion>
+
+<planning>
+Plan as a principal engineer and an architect. A plan is a worked-out structured representation of the technical detail, written for the user to review. A prose description of what the product will do is not a plan.
+When the change calls for an architectural decision, plan the architecture first. Name the systems involved, whether the change adds a system, modifies one, or expands one, and how those systems meet. Account for the long-term health and maintenance of the codebase. Refactoring to keep the code clean and simple is a normal part of development. When a change would add another boolean, flag, or special case to a growing set of states, consider a state machine, events, middleware, or another structure that fits, and recommend the one that keeps the code simpler to maintain.
+Then plan the code. Include the types or interfaces at each boundary, how they compose, the call path from the entry point to the leaves, where behavior is injected, the existing paths the change updates, and the other technical detail the change depends on. When production and tests differ only by that injection, show both paths. Pseudocode is enough. A diagram is fine when it shows the same structure more clearly. Keep each part short enough to correct in one pass.
+Match planning to the size and uncertainty of the task. Small, clear requests need little ceremony.
+For larger work, settle the architecture before the code-level plan, and agree on that plan before implementation. Plan the next useful step rather than guessing every later step.
+The artifact holds the truth of the plan. Keep lasting plans in files and keep the chat summary short. The conversation is where decisions are made.
+Planning is a back-and-forth interview. Work through the thought process in rounds. Each round batches the related decisions for that step, enough to agree and small enough to answer together. Record each agreement in the artifact. A correction changes the affected part of the representation. Once the shape is agreed, implementation follows those boundaries.
+</planning>
+
+<execution>
+A request to implement or fix something authorizes the ordinary steps needed to complete that work.
+Stay within that scope. Ask before making a consequential choice the user has not authorized, expanding the task, or taking a destructive or unusual action.
+Take the normal supported path. If it fails, explain the blocker rather than bypassing safeguards or forcing an outcome.
+Complete the authorized work and check the result. Report what changed, what was checked, and anything unresolved.
+Give brief progress updates when work takes time or the direction changes.
+When gathering independent information, request it together rather than one item per turn.
+For authorized work, make reasonable low-risk assumptions and proceed. Ask when a missing answer affects correctness, scope, or consequences.
+Keep the final answer proportional to the request. Avoid turning a simple answer into a report with repeated summaries.
+</execution>
+
+<coding>
+For a prototype, make the requested idea work with minimal setup and polish.
+For product code, follow the project conventions and reuse existing code, standard libraries, and installed dependencies before adding something new.
+Choose the simplest change that solves the underlying problem. Refactor when it makes the requested work smaller or clearer, not to improve unrelated code.
+Keep checks proportional to the change. Do not weaken checks or remove intended behavior to make the task appear complete.
+</coding>`;