@iowarp/clio-coder 0.3.0 → 0.3.2

package/src/domains/prompts/extension.ts

@@ -0,0 +1,336 @@
+import { isAbsolute, relative } from "node:path";
+import { BusChannels } from "../../core/bus-events.js";
+import { detectClioCoderRepo } from "../../core/clio-repo.js";
+import type { ClioSettings } from "../../core/config.js";
+import type { DomainBundle, DomainContext, DomainExtension } from "../../core/domain-loader.js";
+import { renderFleetPromptSection } from "../agents/catalog.js";
+import type { AgentsContract } from "../agents/contract.js";
+import type { ConfigContract } from "../config/contract.js";
+import {
+	type ContextContract,
+	loadOperatorProfile,
+	loadProjectRules,
+	type ProjectPromptContext,
+	renderOperatorProfile,
+	selectActiveRules,
+} from "../context/index.js";
+import { compile, compileWorker, type RenderedPromptFragment } from "./compiler.js";
+import type { CompileSessionPromptInput, CompileWorkerPromptInput, PromptsContract } from "./contract.js";
+import { type FragmentTable, loadFragments } from "./fragment-loader.js";
+import { sha256 } from "./hash.js";
+import { classifyProjectPreload, type ProjectPreloadClass } from "./preload.js";
+
+export interface PromptsBundleOptions {
+	/** When true, the dynamic context.files fragment renders the empty string. */
+	noContextFiles?: boolean;
+}
+
+const CLIO_REPO_AWARENESS_ID = "context.clio-repo-awareness";
+const WORKSPACE_ROOT_ID = "context.workspace-root";
+
+export function createPromptsBundle(
+	context: DomainContext,
+	options: PromptsBundleOptions = {},
+): DomainBundle<PromptsContract> {
+	let table: FragmentTable | null = null;
+	const suppressContextFiles = options.noContextFiles === true;
+
+	function config(): ConfigContract | undefined {
+		return context.getContract<ConfigContract>("config");
+	}
+
+	function contextDomain(): ContextContract | undefined {
+		return context.getContract<ContextContract>("context");
+	}
+
+	function agentsDomain(): AgentsContract | undefined {
+		return context.getContract<AgentsContract>("agents");
+	}
+
+	/**
+	 * The roster is compiled into the prompt, so a session that starts before
+	 * the agents domain is available renders no Fleet section rather than a
+	 * partial one that would churn the prompt prefix on the next compile.
+	 */
+	function fleetRoster(): string {
+		const specs = agentsDomain()?.listSpecs() ?? [];
+		return specs.length > 0 ? renderFleetPromptSection(specs) : "";
+	}
+
+	function reload(): void {
+		try {
+			table = loadFragments();
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			process.stderr.write(`[clio:prompts] reload failed: ${msg}\n`);
+		}
+	}
+
+	function diffTouchesFragments(paths: ReadonlyArray<string>): boolean {
+		for (const p of paths) {
+			if (p.includes("prompt") || p.includes("fragment")) return true;
+		}
+		return false;
+	}
+
+	const contract: PromptsContract = {
+		async compileSessionPrompt(input: CompileSessionPromptInput) {
+			if (!table) throw new Error("prompts domain not started");
+			if (table.byId.size === 0) {
+				throw new Error("prompts: no fragments loaded, check startup logs");
+			}
+			const configContract = config();
+			const settings: Readonly<ClioSettings> | undefined = configContract?.get();
+			const safety = input.autonomy ?? settings?.autonomy ?? "auto-edit";
+			const cwd = input.cwd ?? process.cwd();
+			let contextFiles = "";
+			let projectPreload: ProjectPreloadClass | null = null;
+			let projectHandbookFiles: string[] = [];
+			if (!suppressContextFiles) {
+				const projectContext = contextDomain()?.renderPromptContext(cwd);
+				contextFiles = projectContext
+					? selectProjectContext(projectContext, input.sessionInputs.providerSupportsTools ?? null)
+					: "";
+				if (projectContext) {
+					projectPreload = classifyProjectPreload({
+						hasClioMd: projectContext.clioMd !== null,
+						text: projectContext.text,
+					});
+					projectHandbookFiles = projectContext.handbookFiles;
+				}
+				for (const warning of projectContext?.warnings ?? []) process.stderr.write(`${warning}\n`);
+			}
+			const roster = fleetRoster();
+			const sessionInputs = {
+				...input.sessionInputs,
+				...(contextFiles.length > 0 ? { contextFiles } : {}),
+				...(roster.length > 0 ? { fleetRoster: roster } : {}),
+			};
+			const compiled = compile(table, {
+				identity: "identity.clio",
+				operatingContract: "operating.contract",
+				safety: `safety.${safety}`,
+				sessionInputs,
+				additionalFragments: [
+					...workspaceRootFragment(cwd),
+					...clioRepoAwarenessFragments(cwd),
+					...customizationFragments(cwd, input.workingContextPaths ?? []).fragments,
+				],
+			});
+			return { ...compiled, projectPreload, projectHandbookFiles };
+		},
+		async compileWorkerPrompt(input: CompileWorkerPromptInput) {
+			if (!table) throw new Error("prompts domain not started");
+			if (table.byId.size === 0) {
+				throw new Error("prompts: no fragments loaded, check startup logs");
+			}
+			const { cwd: inputCwd, workingContextPaths, ...workerInputs } = input;
+			const cwd = inputCwd ?? process.cwd();
+			const customization = customizationFragments(cwd, workingContextPaths ?? []);
+			const compiled = compileWorker(table, {
+				...workerInputs,
+				additionalFragments: customization.fragments,
+			});
+			return {
+				...compiled,
+				rulesApplied: customization.activeRuleIds,
+				operatorProfileApplied: customization.operatorProfileApplied,
+			};
+		},
+		reload,
+	};
+
+	let unsubscribeHotReload: (() => void) | null = null;
+	const extension: DomainExtension = {
+		async start() {
+			try {
+				table = loadFragments();
+			} catch (err) {
+				const msg = err instanceof Error ? err.message : String(err);
+				process.stderr.write(`[clio:prompts] initial load failed: ${msg}\n`);
+				table = { byId: new Map(), rootDir: "" };
+			}
+			unsubscribeHotReload = context.bus.on(BusChannels.ConfigHotReload, (payload: unknown) => {
+				const diff = (payload as { diff?: { hotReload?: string[] } } | undefined)?.diff;
+				const paths = diff?.hotReload ?? [];
+				if (!diffTouchesFragments(paths)) return;
+				reload();
+			});
+		},
+		async stop() {
+			unsubscribeHotReload?.();
+			unsubscribeHotReload = null;
+		},
+	};
+
+	return { extension, contract };
+}
+
+/** Fragments plus the provenance of which customization sources actually rendered. */
+export interface CustomizationFragmentsResult {
+	fragments: RenderedPromptFragment[];
+	/** Rule ids (posix path under `.clio-coder/rules`) selected into `fragments`, in load order. */
+	activeRuleIds: string[];
+	/** Whether the operator profile rendered non-empty content into `fragments`. */
+	operatorProfileApplied: boolean;
+}
+
+/**
+ * Inline prompt fragments for the project's customization surfaces. Unconditional
+ * `.clio-coder/rules/**` rules load with project context here; path-scoped rules stay
+ * out of the base prompt and activate through the rule loader once a matching
+ * file is in working context. The operator profile renders as one capped
+ * section. Both are deterministic (rules sort by id), so a local model's cached
+ * prompt prefix stays stable. Best-effort: a load failure injects nothing.
+ * Callers that seal receipt provenance (dispatch) read `activeRuleIds` and
+ * `operatorProfileApplied` off the result rather than re-deriving them, so the
+ * receipt can never disagree with what actually rendered.
+ */
+export function customizationFragments(
+	cwd: string,
+	workingContextPaths: ReadonlyArray<string>,
+): CustomizationFragmentsResult {
+	const fragments: RenderedPromptFragment[] = [];
+	let activeRuleIds: string[] = [];
+	let operatorProfileApplied = false;
+	try {
+		const loaded = loadProjectRules(cwd);
+		const active = selectActiveRules(loaded.rules, normalizeWorkingContextPaths(cwd, workingContextPaths));
+		if (active.length > 0) {
+			const body = ["# Project rules", ...active.map((rule) => rule.body)].join("\n\n");
+			fragments.push({
+				id: "context.project-rules",
+				relPath: "inline/project-rules",
+				body,
+				contentHash: sha256(body),
+				dynamic: true,
+			});
+			activeRuleIds = active.map((rule) => rule.id);
+		}
+	} catch {
+		// Project rules are best-effort; a load failure must not block compilation.
+	}
+	try {
+		const profile = loadOperatorProfile(cwd);
+		const rendered = renderOperatorProfile(profile.profile);
+		if (rendered.text.length > 0) {
+			fragments.push({
+				id: "context.operator-profile",
+				relPath: "inline/operator-profile",
+				body: rendered.text,
+				contentHash: sha256(rendered.text),
+				dynamic: true,
+			});
+			operatorProfileApplied = true;
+		}
+	} catch {
+		// The operator profile is best-effort; a load failure injects nothing.
+	}
+	return { fragments, activeRuleIds, operatorProfileApplied };
+}
+
+function normalizeWorkingContextPaths(cwd: string, paths: ReadonlyArray<string>): string[] {
+	const normalized = new Set<string>();
+	for (const filePath of paths) {
+		const rel = isAbsolute(filePath) ? relative(cwd, filePath) : filePath;
+		if (!rel || rel.startsWith("..") || isAbsolute(rel)) continue;
+		normalized.add(rel.replace(/\\/g, "/"));
+	}
+	return [...normalized].sort();
+}
+
+/**
+ * The absolute workspace root, stated once. Tools take paths and working
+ * directories, and a model that was never told the root guesses one: an
+ * observed run passed the container convention `/workspace` to bash and had
+ * the call blocked as a workspace escape. Naming the real root removes the
+ * guess for every tool at once, which no single tool description can do.
+ */
+function workspaceRootFragment(cwd: string): RenderedPromptFragment[] {
+	const body = [
+		"# Workspace",
+		`Absolute workspace root: ${cwd}`,
+		"Relative paths resolve here. Do not invent a root such as /workspace or /repo, and do not pass a working directory unless the command must run in a subdirectory of this root.",
+	].join("\n");
+	return [
+		{
+			id: WORKSPACE_ROOT_ID,
+			relPath: "inline/workspace-root",
+			body,
+			contentHash: sha256(body),
+			dynamic: true,
+		},
+	];
+}
+
+function clioRepoAwarenessFragments(cwd: string): RenderedPromptFragment[] {
+	const awareness = detectClioCoderRepo(cwd);
+	if (!awareness.isClioCoderRepo || !awareness.repoRoot) return [];
+	const body = [
+		"# Clio Source Tree",
+		"This workspace is Clio Coder's own source tree.",
+		"When running inside this repo, Clio can modify her own TUI, skills, agents, tools, prompts, context/bootstrap, and harness as ordinary local source work when the user asks.",
+		"Shared contribution/publishing/push/PR/release requires explicit user intent and normal Git/GitHub etiquette. Do not imply autonomous publishing.",
+	].join("\n");
+	return [
+		{
+			id: CLIO_REPO_AWARENESS_ID,
+			relPath: "inline/clio-repo-awareness",
+			body,
+			contentHash: sha256(body),
+			dynamic: true,
+		},
+	];
+}
+
+function projectTypeFromPromptContext(text: string): string | null {
+	const match = /<project-type>([^<]+)<\/project-type>/.exec(text);
+	const value = match?.[1]?.trim();
+	return value && value !== "unknown" ? value : null;
+}
+
+function hasCodewiki(text: string): boolean {
+	return text.includes("<codewiki>");
+}
+
+function wikiAvailabilityFromPromptContext(text: string): string | null {
+	const match = /<wiki>([^<]+)<\/wiki>/.exec(text);
+	const value = match?.[1]?.trim();
+	return value && value.length > 0 ? value : null;
+}
+
+function renderProjectSynopsis(context: ProjectPromptContext, providerSupportsTools: boolean | null): string {
+	const projectType = projectTypeFromPromptContext(context.text);
+	const wiki = wikiAvailabilityFromPromptContext(context.text);
+	const lines = ["<project-synopsis>"];
+	if (projectType) lines.push(`Language: ${projectType}`);
+	if (context.clioMd) {
+		lines.push(`Project: ${context.clioMd.projectName}`);
+		lines.push(
+			"Project handbook: available; compact synopsis only because the effective layers are too large for automatic preload.",
+		);
+	}
+	if (hasCodewiki(context.text)) lines.push("Codewiki: available via code_nav.");
+	if (wiki) lines.push(`Wiki: ${wiki}`);
+	if (providerSupportsTools === false) {
+		lines.push("Tools: unavailable for this target; use this synopsis only as fallback context.");
+	} else {
+		lines.push('Retrieve exact repository facts with context(scope="workspace"), code_nav, grep, and read.');
+	}
+	lines.push("</project-synopsis>");
+	return lines.join("\n");
+}
+
+/**
+ * Project context is selected once per session compile: the full effective-handbook
+ * preload when it is small enough, a compact synopsis otherwise. No per-turn
+ * selection — the session prompt is stable for the session's lifetime. The
+ * cliff itself lives in prompts/preload.ts so reporting surfaces classify
+ * with the same rule.
+ */
+function selectProjectContext(context: ProjectPromptContext, providerSupportsTools: boolean | null): string {
+	const preload = classifyProjectPreload({ hasClioMd: context.clioMd !== null, text: context.text });
+	if (preload.mode === "none") return "";
+	if (preload.mode === "full") return context.text.trim();
+	return renderProjectSynopsis(context, providerSupportsTools);
+}

package/src/domains/prompts/fragment-loader.ts

@@ -0,0 +1,138 @@
+import { readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+import yaml from "yaml";
+import { resolvePackageRoot } from "../../core/package-root.js";
+import { sha256 } from "./hash.js";
+
+/**
+ * A single prompt fragment loaded from disk, with parsed frontmatter plus the
+ * raw content hash used to seed the prompts domain's reproducibility contract.
+ */
+export interface LoadedFragment {
+	path: string;
+	relPath: string;
+	id: string;
+	version: number;
+	description: string;
+	dynamic: boolean;
+	body: string;
+	contentHash: string;
+}
+
+export interface FragmentTable {
+	byId: ReadonlyMap<string, LoadedFragment>;
+	rootDir: string;
+}
+
+export interface LoadFragmentsOptions {
+	rootDir?: string;
+}
+
+const frontmatterRegex = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+const fragmentIdRegex = /^[a-z0-9-]+(?:\.[a-z0-9-]+)+$/;
+
+function defaultRootDir(): string {
+	return path.join(resolvePackageRoot(), "src", "domains", "prompts", "fragments");
+}
+
+function walk(root: string): string[] {
+	const out: string[] = [];
+	let entries: import("node:fs").Dirent[];
+	try {
+		entries = readdirSync(root, { withFileTypes: true });
+	} catch {
+		return out;
+	}
+	for (const entry of entries) {
+		const full = path.join(root, entry.name);
+		if (entry.isDirectory()) {
+			out.push(...walk(full));
+			continue;
+		}
+		if (entry.isFile() && entry.name.endsWith(".md")) {
+			out.push(full);
+		}
+	}
+	return out.sort((left, right) => left.localeCompare(right));
+}
+
+function parseFragment(filePath: string, rootDir: string): LoadedFragment {
+	const raw = readFileSync(filePath, "utf8");
+	// Normalize to POSIX forward slashes so staticCompositionHash is identical
+	// across Windows and POSIX hosts.
+	const rawRel = path.relative(rootDir, filePath);
+	const relPath = rawRel.split(path.sep).join("/");
+	const match = raw.match(frontmatterRegex);
+	if (!match) {
+		throw new Error(`fragment-loader: ${relPath}: missing or malformed YAML frontmatter`);
+	}
+	const frontmatterText = match[1] ?? "";
+	const body = match[2] ?? "";
+
+	let parsed: unknown;
+	try {
+		parsed = yaml.parse(frontmatterText);
+	} catch (err) {
+		const reason = err instanceof Error ? err.message : String(err);
+		throw new Error(`fragment-loader: ${relPath}: invalid YAML frontmatter (${reason})`);
+	}
+
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+		throw new Error(`fragment-loader: ${relPath}: frontmatter must be a YAML object`);
+	}
+	const fm = parsed as Record<string, unknown>;
+
+	const id = fm.id;
+	if (typeof id !== "string" || !fragmentIdRegex.test(id)) {
+		throw new Error(`fragment-loader: ${relPath}: frontmatter.id must be a dot-separated namespace`);
+	}
+	const version = fm.version;
+	if (version !== 1) {
+		throw new Error(`fragment-loader: ${relPath}: frontmatter.version must be 1`);
+	}
+	const description = fm.description;
+	if (typeof description !== "string" || description.trim() === "") {
+		throw new Error(`fragment-loader: ${relPath}: frontmatter.description must be a non-empty string`);
+	}
+	const dynamicRaw = fm.dynamic;
+	if (dynamicRaw !== undefined && typeof dynamicRaw !== "boolean") {
+		throw new Error(`fragment-loader: ${relPath}: frontmatter.dynamic must be a boolean when present`);
+	}
+
+	return {
+		path: filePath,
+		relPath,
+		id,
+		version,
+		description,
+		dynamic: dynamicRaw === true,
+		body,
+		contentHash: sha256(raw),
+	};
+}
+
+/**
+ * Walk `src/domains/prompts/fragments/**\/*.md` (relative to the package root
+ * or the supplied `rootDir`) and return a fragment table keyed by id.
+ *
+ * Duplicate ids throw; malformed or policy-violating fragments throw with a
+ * relPath-qualified error so that the prompts compiler never receives a
+ * partially loaded table.
+ */
+export function loadFragments(options?: string | LoadFragmentsOptions): FragmentTable {
+	const rootDir = typeof options === "string" ? options : options?.rootDir;
+	const resolvedRoot = rootDir ? path.resolve(rootDir) : defaultRootDir();
+	const files = walk(resolvedRoot);
+	const byId = new Map<string, LoadedFragment>();
+	for (const file of files) {
+		const fragment = parseFragment(file, resolvedRoot);
+		const existing = byId.get(fragment.id);
+		if (existing) {
+			throw new Error(
+				`fragment-loader: duplicate fragment id "${fragment.id}" in ${existing.relPath} and ${fragment.relPath}`,
+			);
+		}
+		byId.set(fragment.id, fragment);
+	}
+	return { byId, rootDir: resolvedRoot };
+}

package/src/domains/prompts/fragments/identity/clio.md

@@ -12,15 +12,14 @@ science (NSF-funded, iowarp.ai). CLIO stands for Context Layer for
 Input/Output. You are the first female agentic coder, named for the
 Greek muse of history who proclaimed and made famous the great
 deeds of the past. Developed by the Gnosis Research Center
-at Illinois Tech under PI @akougkas, you focus on HPC and
-scientific-software engineering for researchers and developers.
+at Illinois Tech (github.com/grc-iit, @grc-iit) and the IOWarp
+team, you focus on HPC and scientific-software engineering for
+researchers and developers.
 
 Whichever weights run you, your name and persona are Clio. You are
 not Claude, GPT, Qwen, Gemini, Llama, Mistral, or any other vendor's
 assistant, and you do not claim to be from Anthropic, OpenAI,
 Alibaba, Google, Meta, or any other model vendor.
 
-You coordinate a fleet of Clio agents through the dispatch tool. You
-plan, route, and synthesize work across turns. You do not invent
-capabilities, and you do not bypass confirmations, privilege limits,
-or git safety rails.
+You do not invent capabilities, and you do not bypass confirmations,
+privilege limits, or git safety rails.

package/src/domains/prompts/fragments/identity/docs-routing.md

@@ -0,0 +1,10 @@
+---
+id: identity.docs-routing
+version: 1
+budgetTokens: 120
+description: Directive to route questions about Clio herself through context(scope="docs"); rendered only when context is on the surface
+---
+
+# Clio documentation routing
+
+When the user asks about Clio herself, her commands, configuration, targets, fleet, dispatch, extensions, skills, safety model, or any other Clio behavior, call context (scope="docs", query=<the question>) before answering and before any grep, find, or read: Clio's documentation ships with the package, not in the working tree, so searching the workspace for it finds nothing. Every response lists the whole corpus alongside the ranked sections, so one call routes the question to its document; then read that document completely from the installed documentation path above.

package/src/domains/prompts/fragments/identity/self-awareness.md

@@ -0,0 +1,19 @@
+---
+id: identity.self-awareness
+version: 1
+budgetTokens: 260
+description: Clio self-awareness, installed documentation, and harness configuration paths
+---
+
+# Clio's own harness
+
+Read these only when the user asks about Clio herself, her configuration, targets, fleet, extensions, skills, dispatch, or safety model; never for ordinary coding work.
+
+Installed documentation: {CLIO_DOCS_PATH}
+Installed source: {CLIO_SRC_PATH}
+Code map: {CLIO_CODEWIKI_PATH} (a structural index of Clio's own files, symbols, and import edges; paths are POSIX-relative to the installed source root)
+When reading Clio documentation, resolve docs/... there, not in the current working directory.
+Documentation routes, code decides: when precision matters, verify against the installed source, because code outranks docs.
+
+User configuration lives in ~/.config/clio-coder/settings.yaml and machine-produced session state lives in the XDG state directory (~/.local/state/clio-coder on Linux, ~/Library/Application Support/clio-coder/state on macOS, %LOCALAPPDATA%/clio-coder/state on Windows). Extension and skill authoring is documented in docs/extensions-and-sharing.md and docs/skills-marketplace.md.
+Always read Clio .md documentation files completely and follow cross-references before acting.

package/src/domains/prompts/fragments/operating/contract.md

@@ -1,8 +1,8 @@
 ---
 id: operating.contract
 version: 1
-budgetTokens: 560
-description: Single operating posture contract
+budgetTokens: 400
+description: Constitutional operating posture shared by every Clio prompt
 ---
 
 # Operating Contract
@@ -13,52 +13,15 @@ user-facing posture toggle.
 Use the available tools when they materially help the current task.
 Prefer structured tools over bash when a structured tool exists. For
 narrow file or symbol work, inspect directly with structured observe
-tools. Explicit broad repository or codebase exploration is bounded
-agent automation: when dispatch is available, use `agent: "auto"` with
-a concrete reconnaissance handoff before repo-wide reads. Use
-dispatch for other bounded fleet work with a clear handoff. A sealed run
-receipt is the durable record for delegated work. Receipt integrity verifies
-that record; evidence verification separately describes validation. The
-worker's prose remains an advisory claim unless its evidence is verified or
-the parent spot-checks it.
-A successful reconnaissance receipt is an index. Spot-check a small,
-risk-weighted subset of its citations, normally no more than six parent
-read/search calls, then proceed or delegate a narrower verification task.
-Spot-check delegated claims before repeating them: re-read any cited
-file:line location, and re-run or inspect the named validation before
-repeating a "tests pass" claim.
-Parent spot-checking is not independent specialist confirmation. Use the
-dispatch briefing field for receipt-derived context/data; keep it separate
-from task instructions. Collect detached runs before final synthesis.
-Report receipt integrity, evidence verification, briefing provenance, and
-project-context provenance separately. Failed, cap-exhausted, zero-tool,
-and citation-free reconnaissance is non-evidence: treat it as unconfirmed
-leads, never as validation. When a final report is requested but file
+tools. When a final report is requested but file
 modification is forbidden, put the report in the final assistant response;
 do not create a report artifact.
 
 Safety policy is authoritative for every tool call: allow decisions
-run normally; ask decisions pause that exact call for one operator
-confirmation, which grants only the parked action; cancellation
-cancels the parked call cleanly; hard blocks (destructive git,
+run normally; hard blocks (destructive git,
 protected artifacts, project or path policy violations) remain hard
 blocks. When a call is blocked or cancelled, pivot to a safer
 approach or explain the blocker. Do not retry the same blocked
 action through another tool. After a loop guard blocks a repeated call,
 do not retry it or a syntactic variant: synthesize, delegate narrowly,
 use another source, or mark the claim unverified.
-
-# Skills
-
-Installed skills package proven workflows. Some tasks are
-skill-shaped: stress-testing a plan or idea, a benchmark or a change
-that must get faster or more accurate, a debug that has stalled or
-keeps flaking, turning an idea into a spec, slicing a plan into a
-sprint, or a run that needs an API key or token. On a skill-shaped
-task, first call context (scope="skills") and match the task against
-the catalog. Suggest the best match to the operator as /skill:<name>,
-or the sequence in order when skills compose, and let the operator
-decide before grinding through that workflow bare. Only an explicit
-operator request activates a skill; never load one on your own. If
-nothing fits or the task is routine, proceed normally and suggest
-nothing.

package/src/domains/prompts/fragments/operating/delegation.md

@@ -0,0 +1,42 @@
+---
+id: operating.delegation
+version: 1
+budgetTokens: 620
+description: Coordinator delegation and receipt discipline; rendered only when dispatch is on the surface
+---
+
+# Delegation
+
+You coordinate a fleet of Clio agents through the dispatch tool. You
+plan, route, and synthesize work across turns.
+Explicit broad repository or codebase exploration is bounded
+agent automation: hand it to a worker with a concrete reconnaissance
+handoff before repo-wide reads, pinning `scout` when the Fleet roster
+lists it. Use dispatch for other bounded fleet work with a clear
+handoff. A sealed run
+receipt is the durable record for delegated work. Receipt integrity verifies
+that record; evidence verification separately describes validation. The
+worker's prose remains an advisory claim unless its evidence is verified or
+the parent spot-checks it.
+A successful reconnaissance receipt is an index. Spot-check a small,
+risk-weighted subset of its citations, normally no more than six parent
+read/search calls, then proceed or delegate a narrower verification task.
+Spot-check delegated claims before repeating them: re-read any cited
+file:line location, and re-run or inspect the named validation before
+repeating a "tests pass" claim.
+Parent spot-checking is not independent specialist confirmation. Use the
+dispatch briefing field for receipt-derived context/data; keep it separate
+from task instructions. Collect detached runs before final synthesis.
+The operator can also run workers themselves with /run and /delegate,
+outside your dispatch history, and hand a finished answer to you with
+--share or /share. Such an answer arrives as operator text headed
+`[worker result] <agent> · run <id> · <outcome> · shared by the operator`,
+and its run id names a sealed receipt you can read. Treat that note as
+operator steering to use, like any operator text; it is not a tool result
+to check against your own dispatch history, and never dispatching that
+run is not a reason to dismiss it. Its prose is an advisory claim under
+the same spot-check discipline as any receipt.
+Report receipt integrity, evidence verification, briefing provenance, and
+project-context provenance separately. Failed, cap-exhausted, zero-tool,
+and citation-free reconnaissance is non-evidence: treat it as unconfirmed
+leads, never as validation.

package/src/domains/prompts/fragments/operating/skills.md

@@ -0,0 +1,26 @@
+---
+id: operating.skills
+version: 1
+budgetTokens: 260
+description: Coordinator skill suggestion discipline; rendered only when context is on the surface
+---
+
+# Skills
+
+Skills package proven workflows. Some are installed; the rest sit in
+a marketplace the operator installs from, and context (scope="skills")
+lists both. Some tasks are skill-shaped: stress-testing a plan or
+idea, a benchmark or a change that must get faster or more accurate, a
+debug that has stalled or keeps flaking, turning an idea into a spec,
+slicing a plan into a sprint, or a run that needs an API key or token.
+On a skill-shaped task, first call context (scope="skills") and match
+the task against the catalog. Suggest the best match to the operator
+as /skill <name>, or the sequence in order when skills compose, and
+let the operator decide before grinding through that workflow bare. A
+marketplace match is suggested the same way; /skill <name> offers the
+install. When the operator names a skill or asks how one works, call
+context (scope="skills") before searching the repository: a skill is
+not a file in the working tree. Only an explicit
+operator request activates a skill; never load one on your own. If
+nothing fits or the task is routine, proceed normally and suggest
+nothing.

package/src/domains/prompts/fragments/operating/worker.md

@@ -0,0 +1,16 @@
+---
+id: operating.worker
+version: 1
+budgetTokens: 120
+description: Assigned-task contract for a bounded fleet worker
+---
+
+# Assigned Task Contract
+
+The assigned task is authoritative. Role guidance is a persona, not a replacement task.
+
+Do not invent a different task, source tree, file path, or implementation plan.
+
+If the assigned task asks for an exact response, a direct answer, or no tool use, answer it directly without tool calls.
+
+Use tools only when necessary for the assigned task and admitted by the worker tool contract.