pi-agent-squad 0.7.0

package/message.ts

@@ -0,0 +1,572 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { randomUUID } from "node:crypto";
+import { Type } from "typebox";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+// ============================================================================
+// Generic messaging system (no identity concept at the bottom layer)
+//
+// Two parties communicate: `main` (the main agent) and any subagent. Identity
+// is defined entirely by each agent's prompt.
+// Messages = file channel + polling:
+//   send_message -> write <root>/<runId>/<agent>/<idx>/requests/<msgId>.json (to=target)
+//   reply_message -> write <root>/<runId>/<fromAgent>/<idx>/replies/<msgId>.json
+//   the waiting party polls replies/<msgId>.json
+// Main-side routing: to === "main" -> inject into main session; otherwise
+// forward to the target subagent's resident process.
+// ============================================================================
+
+// ---- env vars (injected when a subagent is spawned) ----
+export const ENV_CHANNEL_ROOT = "PI_SUBAGENT_CHANNEL_ROOT";
+export const ENV_RUN_ID = "PI_SUBAGENT_RUN_ID";
+export const ENV_AGENT = "PI_SUBAGENT_AGENT";
+export const ENV_CHILD_INDEX = "PI_SUBAGENT_CHILD_INDEX";
+export const ENV_ROLE = "PI_SUBAGENT_ROLE";
+export const ROLE_MAIN = "main";
+export const ROLE_CHILD = "child";
+
+/** Generic address of the main agent (no identity semantics, just "the main session") */
+export const MAIN_AGENT = "main";
+
+export const TOOL_SEND = "send_message";
+export const TOOL_READ = "read_inbox";
+export const TOOL_REPLY = "reply_message";
+
+const REQUESTS_DIR = "requests";
+const REPLIES_DIR = "replies";
+const MAX_MESSAGE_BYTES = 64 * 1024;
+const DEFAULT_WAIT_TIMEOUT_MS = 6 * 60 * 60 * 1000;
+const DEFAULT_ROUTE_TIMEOUT_SECONDS = 6 * 60 * 60;
+const MIN_ROUTE_TIMEOUT_SECONDS = 10;
+const MAX_ROUTE_TIMEOUT_SECONDS = 3 * 24 * 60 * 60;
+const CHANNEL_POLL_MS = 500;
+const REPLY_POLL_MS = 250;
+
+export interface MessageRequest {
+	type: "pi.message.request";
+	id: string;
+	createdAt: number;
+	from: string; // sender: main or a subagent name
+	to: string; // target: main or a subagent name
+	content: string;
+	expectsReply: boolean;
+	expiresAt?: number;
+	timeoutMs?: number;
+	requestFile: string;
+	// sender's channel location (so a reply can be written back)
+	fromRunId: string;
+	fromAgent: string;
+	fromChildIndex: number;
+}
+
+export interface MessageReply {
+	type: "pi.message.reply";
+	messageId: string;
+	content: string;
+	timestamp: number;
+}
+
+function safeSegment(value: string): string {
+	return value.replace(/[^\w.-]+/g, "_");
+}
+
+/** Channel directory of one agent instance */
+export function channelDir(root: string, runId: string, agent: string, childIndex: number): string {
+	return path.join(root, safeSegment(runId), safeSegment(agent), String(childIndex));
+}
+
+function requestPath(dir: string, id: string): string {
+	return path.join(dir, REQUESTS_DIR, `${safeSegment(id)}.json`);
+}
+function replyPath(dir: string, id: string): string {
+	return path.join(dir, REPLIES_DIR, `${safeSegment(id)}.json`);
+}
+
+export function ensureDir(dir: string): void {
+	fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+}
+
+function writeAtomic(filePath: string, data: string): void {
+	fs.writeFileSync(filePath, data, { encoding: "utf-8", mode: 0o600 });
+}
+
+// ============================================================================
+// Message client (shared by subagents and the main agent)
+// ============================================================================
+
+interface ClientMeta {
+	root: string;
+	runId: string;
+	agent: string;
+	childIndex: number;
+}
+
+function readClientMeta(): ClientMeta | undefined {
+	const root = process.env[ENV_CHANNEL_ROOT]?.trim();
+	const runId = process.env[ENV_RUN_ID]?.trim();
+	const agent = process.env[ENV_AGENT]?.trim();
+	const rawIndex = process.env[ENV_CHILD_INDEX]?.trim();
+	if (!root || !runId || !agent || rawIndex === undefined || !/^\d+$/.test(rawIndex)) return undefined;
+	return { root, runId, agent, childIndex: Number(rawIndex) };
+}
+
+function waitForReply(dir: string, messageId: string, deadline: number, signal?: AbortSignal): Promise<string> {
+	return new Promise((resolve, reject) => {
+		const file = replyPath(dir, messageId);
+		const tick = () => {
+			if (signal?.aborted) {
+				reject(new Error("Message wait cancelled."));
+				return;
+			}
+			if (Date.now() > deadline) {
+				reject(new Error("Timed out waiting for reply."));
+				return;
+			}
+			try {
+				if (fs.existsSync(file)) {
+					const parsed = JSON.parse(fs.readFileSync(file, "utf-8")) as MessageReply;
+					if (parsed.type === "pi.message.reply" && parsed.messageId === messageId && typeof parsed.content === "string") {
+						try {
+							fs.unlinkSync(file);
+						} catch {
+							/* ignore cleanup failure */
+						}
+						resolve(parsed.content);
+						return;
+					}
+				}
+			} catch {
+				/* ignore */
+			}
+			setTimeout(tick, REPLY_POLL_MS);
+		};
+		tick();
+	});
+}
+
+/** Send a message to any target (main or subagent); wait=true blocks for a reply */
+async function sendMessageInternal(
+	to: string,
+	content: string,
+	wait: boolean,
+	timeoutMs: number,
+	signal?: AbortSignal,
+): Promise<{ messageId: string; reply?: string }> {
+	const meta = readClientMeta();
+	if (!meta) throw new Error("Message channel is not available.");
+	const dir = channelDir(meta.root, meta.runId, meta.agent, meta.childIndex);
+	ensureDir(path.join(dir, REQUESTS_DIR));
+	ensureDir(path.join(dir, REPLIES_DIR));
+
+	const messageId = randomUUID();
+	const now = Date.now();
+	const deadline = now + (wait ? timeoutMs : DEFAULT_WAIT_TIMEOUT_MS);
+	const request: MessageRequest = {
+		type: "pi.message.request",
+		id: messageId,
+		createdAt: now,
+		from: meta.agent,
+		to,
+		content,
+		expectsReply: wait,
+		...(wait ? { expiresAt: deadline } : {}),
+		timeoutMs,
+		requestFile: requestPath(dir, messageId),
+		fromRunId: meta.runId,
+		fromAgent: meta.agent,
+		fromChildIndex: meta.childIndex,
+	};
+	const serialized = JSON.stringify(request, null, "\t");
+	if (Buffer.byteLength(serialized, "utf-8") > MAX_MESSAGE_BYTES) throw new Error("Message is too large.");
+	writeAtomic(requestPath(dir, messageId), serialized);
+
+	if (!wait) return { messageId };
+	try {
+		const reply = await waitForReply(dir, messageId, deadline, signal);
+		return { messageId, reply };
+	} catch (e) {
+		try {
+			fs.unlinkSync(requestPath(dir, messageId));
+		} catch {
+			/* router may already have consumed it */
+		}
+		throw e;
+	}
+}
+
+/** Reply to a message (locate the sender from the message, write the reply back) */
+function replyToMessage(root: string, messageId: string, content: string): boolean {
+	const request = findRequestInTree(root, messageId);
+	if (!request) return false;
+	const senderDir = channelDir(root, request.fromRunId, request.fromAgent, request.fromChildIndex);
+	ensureDir(path.join(senderDir, REPLIES_DIR));
+	const reply: MessageReply = { type: "pi.message.reply", messageId, content, timestamp: Date.now() };
+	writeAtomic(replyPath(senderDir, messageId), JSON.stringify(reply, null, 2));
+	// clean up the replied request
+	if (request.requestFile) {
+		try {
+			fs.unlinkSync(request.requestFile);
+		} catch {
+			/* ignore */
+		}
+	}
+	return true;
+}
+
+function findRequestInTree(root: string, messageId: string): MessageRequest | undefined {
+	try {
+		if (!fs.existsSync(root)) return undefined;
+		for (const run of fs.readdirSync(root)) {
+			const runDir = path.join(root, run);
+			if (!fs.statSync(runDir).isDirectory()) continue;
+			for (const agent of fs.readdirSync(runDir)) {
+				const agentDir = path.join(runDir, agent);
+				if (!fs.statSync(agentDir).isDirectory()) continue;
+				for (const idx of fs.readdirSync(agentDir)) {
+					const reqDir = path.join(agentDir, idx, REQUESTS_DIR);
+					if (!fs.existsSync(reqDir)) continue;
+					for (const f of fs.readdirSync(reqDir)) {
+						if (f !== `${safeSegment(messageId)}.json`) continue;
+						try {
+							return JSON.parse(fs.readFileSync(path.join(reqDir, f), "utf-8")) as MessageRequest;
+						} catch {
+							/* ignore */
+						}
+					}
+				}
+			}
+		}
+	} catch {
+		/* ignore */
+	}
+	return undefined;
+}
+
+/** Register the generic messaging tools for a child (subagent) */
+export function registerChildMessaging(pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: TOOL_SEND,
+		label: "Send Message",
+		description: [
+			"Send a message to any target: to='main' reaches the main agent, to=<agent name> reaches that subagent.",
+			"wait=true (ask): block until the other party replies before continuing; wait=false (send): fire and forget.",
+			"Use it to ask/confirm with the main agent or another subagent instead of leaving notes in normal output.",
+		].join(" "),
+		parameters: Type.Object({
+			to: Type.String({ description: "Target: main or a subagent name" }),
+			content: Type.String({ description: "Message content" }),
+			wait: Type.Optional(
+				Type.Boolean({ description: "true=wait for a reply (default true)" }),
+			),
+			timeoutSeconds: Type.Optional(
+				Type.Integer({
+					minimum: MIN_ROUTE_TIMEOUT_SECONDS,
+					maximum: MAX_ROUTE_TIMEOUT_SECONDS,
+					description: `Reply timeout in seconds. Omit unless the user explicitly requested a time; default ${DEFAULT_ROUTE_TIMEOUT_SECONDS}s (6 hours).`,
+				}),
+			),
+		}),
+		execute: async (_id, params, signal) => {
+			try {
+				const timeoutMs =
+					Math.min(
+						MAX_ROUTE_TIMEOUT_SECONDS,
+						Math.max(MIN_ROUTE_TIMEOUT_SECONDS, params.timeoutSeconds ?? DEFAULT_ROUTE_TIMEOUT_SECONDS),
+					) * 1000;
+				const { messageId, reply } = await sendMessageInternal(
+					params.to,
+					params.content,
+					params.wait !== false,
+					timeoutMs,
+					signal,
+				);
+				if (reply !== undefined) {
+					return {
+						content: [{ type: "text", text: `Reply from ${params.to}:\n${reply}` }],
+					};
+				}
+				return { content: [{ type: "text", text: `Sent message to ${params.to} (id ${messageId.slice(0, 8)})` }] };
+			} catch (e) {
+				return {
+					content: [{ type: "text", text: `Failed to send message: ${e instanceof Error ? e.message : String(e)}` }],
+				};
+			}
+		},
+	});
+
+	pi.registerTool({
+		name: TOOL_READ,
+		label: "Read Inbox",
+		description: "Read messages that others sent you.",
+		parameters: Type.Object({}),
+		execute: async (_id) => {
+			const meta = readClientMeta();
+			if (!meta) return { content: [{ type: "text", text: "Message channel is not available." }] };
+			const dir = channelDir(meta.root, meta.runId, meta.agent, meta.childIndex);
+			const reqDir = path.join(dir, REQUESTS_DIR);
+			if (!fs.existsSync(reqDir)) return { content: [{ type: "text", text: "Inbox is empty." }] };
+			const files = fs.readdirSync(reqDir).filter((f) => f.endsWith(".json"));
+			if (files.length === 0) return { content: [{ type: "text", text: "Inbox is empty." }] };
+			const lines = files.map((f) => {
+				try {
+					const r = JSON.parse(fs.readFileSync(path.join(reqDir, f), "utf-8")) as MessageRequest;
+					return `- [${r.id.slice(0, 8)}] from ${r.from}: ${r.content.slice(0, 150)}`;
+				} catch {
+					return "";
+				}
+			});
+			return { content: [{ type: "text", text: `Inbox (requests from other agents):\n${lines.join("\n")}` }] };
+		},
+	});
+
+	pi.registerTool({
+		name: TOOL_REPLY,
+		label: "Reply Message",
+		description: "Reply to a received message (message_id comes from the received message).",
+		parameters: Type.Object({
+			message_id: Type.String({ description: "The message id to reply to" }),
+			content: Type.String({ description: "Reply content" }),
+		}),
+		execute: async (_id, params) => {
+			const meta = readClientMeta();
+			if (!meta) return { content: [{ type: "text", text: "Message channel is not available." }] };
+			if (!replyToMessage(meta.root, params.message_id, params.content)) {
+				return { content: [{ type: "text", text: `Message not found: ${params.message_id.slice(0, 8)}` }] };
+			}
+			return { content: [{ type: "text", text: `Replied to ${params.message_id.slice(0, 8)}` }] };
+		},
+	});
+}
+
+// ============================================================================
+// Main-agent side: message router (poller)
+// ============================================================================
+
+export interface MessageRouterState {
+	root: string;
+	/** when to === "main": inject into the main session */
+	onMainMessage: (msg: MessageRequest) => void;
+	/** when to === some subagent: route to its resident process */
+	onChildMessage: (msg: MessageRequest, signal?: AbortSignal) => Promise<string> | string;
+	matchesContext: (msg: MessageRequest) => boolean;
+	/** notification hooks used by the main-side wait graph */
+	onMessageReplied?: (msg: MessageRequest) => void;
+	onMessageExpired?: (msg: MessageRequest) => void;
+}
+
+export interface MessageRouter {
+	start: () => void;
+	dispose: () => void;
+}
+
+/** Scan the channel tree for all pending message requests */
+export function scanMessages(root: string): MessageRequest[] {
+	const out: MessageRequest[] = [];
+	try {
+		if (!fs.existsSync(root)) return out;
+		for (const run of fs.readdirSync(root)) {
+			const runDir = path.join(root, run);
+			if (!fs.statSync(runDir).isDirectory()) continue;
+			for (const agent of fs.readdirSync(runDir)) {
+				const agentDir = path.join(runDir, agent);
+				if (!fs.statSync(agentDir).isDirectory()) continue;
+				for (const idx of fs.readdirSync(agentDir)) {
+					const reqDir = path.join(agentDir, idx, REQUESTS_DIR);
+					if (!fs.existsSync(reqDir)) continue;
+					for (const f of fs.readdirSync(reqDir)) {
+						if (!f.endsWith(".json")) continue;
+						try {
+							const req = JSON.parse(fs.readFileSync(path.join(reqDir, f), "utf-8")) as MessageRequest;
+							if (req.type === "pi.message.request" && req.id) {
+								req.requestFile = path.join(reqDir, f);
+								out.push(req);
+							}
+						} catch {
+							/* ignore */
+						}
+					}
+				}
+			}
+		}
+	} catch {
+		/* ignore */
+	}
+	return out;
+}
+
+export function writeReply(dir: string, messageId: string, content: string): void {
+	ensureDir(path.join(dir, REPLIES_DIR));
+	const reply: MessageReply = { type: "pi.message.reply", messageId, content, timestamp: Date.now() };
+	writeAtomic(replyPath(dir, messageId), JSON.stringify(reply, null, 2));
+}
+
+export function removeRequestFile(msg: MessageRequest): void {
+	try {
+		if (msg.requestFile) fs.unlinkSync(msg.requestFile);
+	} catch {
+		/* ignore */
+	}
+}
+
+/** Main agent creates a message router: poller scans, then splits main vs subagent */
+export function createMessageRouter(pi: ExtensionAPI, state: MessageRouterState): MessageRouter {
+	const seen = new Set<string>();
+	const inFlight = new Set<string>();
+	let poller: ReturnType<typeof setInterval> | undefined;
+
+	const poll = () => {
+		for (const msg of scanMessages(state.root)) {
+			if (msg.expiresAt !== undefined && msg.expiresAt < Date.now()) {
+				seen.delete(msg.id);
+				inFlight.delete(msg.id);
+				state.onMessageExpired?.(msg);
+				removeRequestFile(msg);
+				continue;
+			}
+			if (seen.has(msg.id) || inFlight.has(msg.id)) continue;
+			if (!state.matchesContext(msg)) continue;
+			if (msg.to === MAIN_AGENT) {
+				try {
+					state.onMainMessage(msg);
+					// A request to main remains on disk until reply_message is
+					// called, so remember successful delivery to avoid injecting
+					// it on every poll. Failed delivery is deliberately retried.
+					seen.add(msg.id);
+				} catch {
+					/* retry on the next poll */
+				}
+			} else {
+				inFlight.add(msg.id);
+				void Promise.resolve()
+					.then(() => state.onChildMessage(msg))
+					.then(() => {
+						seen.add(msg.id);
+					})
+					.catch(() => {
+						/* retry unexpected routing failures on the next poll */
+					})
+					.finally(() => {
+						inFlight.delete(msg.id);
+					});
+			}
+		}
+	};
+
+	return {
+		start: () => {
+			if (poller) return;
+			registerMainReplyTool(pi, state);
+			poll();
+			poller = setInterval(poll, CHANNEL_POLL_MS);
+			poller.unref?.();
+		},
+		dispose: () => {
+			if (poller) clearInterval(poller);
+			poller = undefined;
+		},
+	};
+}
+
+/** Main agent registers the generic messaging tools (send_message + reply_message) */
+function registerMainReplyTool(pi: ExtensionAPI, state: MessageRouterState): void {
+	// the main agent can also proactively message subagents
+	pi.registerTool({
+		name: TOOL_SEND,
+		label: "Send Message",
+		description: [
+			"Send a message to a subagent: to=<agent name>. wait=true waits for its reply.",
+			"The subagent processes the message and replies via reply_message.",
+		].join(" "),
+		parameters: Type.Object({
+			to: Type.String({ description: "Subagent name" }),
+			content: Type.String({ description: "Message content" }),
+			wait: Type.Optional(Type.Boolean({ description: "true=wait for a reply (default true)" })),
+			timeoutSeconds: Type.Optional(
+				Type.Integer({
+					minimum: MIN_ROUTE_TIMEOUT_SECONDS,
+					maximum: MAX_ROUTE_TIMEOUT_SECONDS,
+					description: `Task timeout in seconds. Omit unless the user explicitly requested a time; default ${DEFAULT_ROUTE_TIMEOUT_SECONDS}s (6 hours).`,
+				}),
+			),
+		}),
+		execute: async (_id, params, signal) => {
+			// the main agent has no child channel location; forward via the router
+			const wait = params.wait !== false;
+			const timeoutMs =
+				Math.min(
+					MAX_ROUTE_TIMEOUT_SECONDS,
+					Math.max(MIN_ROUTE_TIMEOUT_SECONDS, params.timeoutSeconds ?? DEFAULT_ROUTE_TIMEOUT_SECONDS),
+				) * 1000;
+			const msg = findOrCreateProxyRequest(state.root, params.content, wait, timeoutMs);
+			if (!msg) {
+				return { content: [{ type: "text", text: "Message channel is not ready." }] };
+			}
+			const routed = { ...msg, to: params.to };
+			if (!wait) {
+				void Promise.resolve(state.onChildMessage(routed)).catch(() => {
+					/* fire-and-forget failures cannot be returned to this completed tool call */
+				});
+				return { content: [{ type: "text", text: `Sent message to ${params.to}` }] };
+			}
+			try {
+				const reply = await state.onChildMessage(routed, signal);
+				return { content: [{ type: "text", text: `Reply from ${params.to}:\n${reply}` }] };
+			} catch (e) {
+				return {
+					content: [{ type: "text", text: `Failed to message ${params.to}: ${e instanceof Error ? e.message : String(e)}` }],
+				};
+			}
+		},
+	});
+
+	pi.registerTool({
+		name: TOOL_REPLY,
+		label: "Reply Message",
+		description: [
+			"Reply to a message from a subagent. message_id comes from the received message (like message_id=xxx).",
+			"After receiving a subagent message, use this tool; the content is sent back to the waiting subagent.",
+		].join(" "),
+		parameters: Type.Object({
+			message_id: Type.String({ description: "The message id to reply to" }),
+			content: Type.String({ description: "Reply content" }),
+		}),
+		execute: async (_id, params) => {
+			const msg = findRequestInTree(state.root, params.message_id);
+			if (!msg) {
+				return {
+					content: [{ type: "text", text: `Message not found: ${params.message_id.slice(0, 8)} (may already be handled)` }],
+				};
+			}
+			const dir = channelDir(state.root, msg.fromRunId, msg.fromAgent, msg.fromChildIndex);
+			writeReply(dir, msg.id, params.content);
+			removeRequestFile(msg);
+			state.onMessageReplied?.(msg);
+			return { content: [{ type: "text", text: `Replied to ${msg.from}` }] };
+		},
+	});
+}
+
+/** Proxy request for the main agent sending to a subagent (placeholder; routing actually delivers it) */
+function findOrCreateProxyRequest(
+	root: string,
+	content: string,
+	expectsReply: boolean,
+	timeoutMs: number,
+): MessageRequest | undefined {
+	if (!root) return undefined;
+	return {
+		type: "pi.message.request",
+		id: randomUUID(),
+		createdAt: Date.now(),
+		from: MAIN_AGENT,
+		to: "",
+		content,
+		expectsReply,
+		timeoutMs,
+		requestFile: "",
+		fromRunId: "main",
+		fromAgent: MAIN_AGENT,
+		fromChildIndex: 0,
+	};
+}

package/orchestrator.md

@@ -0,0 +1,131 @@
+---
+name: orchestrator
+description: Main agent system prompt — outcome ownership with optional specialist workflows
+---
+
+# You are the Orchestrator
+
+You are the primary owner of the user's outcome. Use specialists when their
+distinct capability materially improves the result. Choose the smallest
+workflow that delivers the outcome reliably, and remain responsible for
+reconnaissance, integration, user communication, and final delivery.
+
+## Working model
+
+Every task moves through some of these phases:
+
+1. **Discover** — understand the requested outcome and gather the facts needed to act.
+2. **Decide** — resolve consequential implementation choices that remain after discovery.
+3. **Execute** — implement a clear task brief or design decision.
+4. **Verify** — independently check completed work against the requested outcome.
+
+Not every task needs every phase or every specialist. Task size and decision
+uncertainty are separate: a large amount of clear work is execution, while a
+small change with a consequential unresolved choice may need design.
+
+## Specialists
+
+| Agent | Distinct capability | Model |
+|---|---|---|
+| `planner` | Resolve a concrete design decision and produce an actor-ready decision record | glm-5.3 |
+| `actor` | Implement a clear task brief or decision record | deepseek-v4-flash |
+| `reviewer` | Independently verify completed work against the requested outcome | gpt-5.6-sol |
+
+## Selecting the workflow
+
+For each user request:
+
+1. Define the concrete deliverable.
+2. Gather enough evidence to understand the current system.
+3. Determine whether the implementation direction is already clear.
+4. Select the specialist whose distinct output is needed next.
+5. Integrate the result and advance the active workflow.
+
+Use these workflow shapes:
+
+- **Main directly completes the work** when the necessary context and capabilities are already available.
+- **Main → actor** when the desired change, constraints, and verification criteria form a clear task brief.
+- **Main → planner → actor** when discovery exposes a consequential unresolved decision that prevents a clear task brief.
+- **Main or actor → reviewer** when independent correctness, regression, security, compatibility, or requirement coverage checks add meaningful value.
+- **Main → planner** when the user's requested deliverable is itself a design decision or implementation plan.
+
+## Planner readiness: Decision Brief
+
+Planner is the specialist for the **Decide** phase. Before invoking planner,
+form a Decision Brief containing:
+
+- **Decision to make** — one sentence naming the unresolved choice.
+- **Why it matters** — how the answer changes implementation, compatibility, migration, or risk.
+- **Known facts** — evidence established during discovery.
+- **Constraints** — requirements the decision must satisfy.
+- **Candidate approaches or unresolved boundary** — the viable directions or exact point of uncertainty.
+- **Downstream use** — how the result will change actor's implementation brief.
+
+Planner returns a decision record and an actor-ready implementation outline.
+Its value comes from resolving the decision, not from restating known facts or
+turning an already-clear implementation into a longer checklist.
+
+## Actor readiness: Task Brief
+
+Actor can work from either a direct Task Brief or a planner Decision Record. A
+separate planner result is optional.
+
+A useful Task Brief contains:
+
+- Desired outcome
+- Relevant subsystem or files
+- Required behavior
+- Constraints
+- Verification criteria
+
+Actor derives local execution steps, implements the change, verifies it, and
+reports changed files, results, and remaining blockers.
+
+## Reviewer readiness: Verification Brief
+
+Reviewer evaluates completed work using:
+
+- User outcome
+- Task Brief
+- Decision Record, when one exists
+- Relevant diff or files
+- Verification already performed
+
+Reviewer returns `Approved` or a prioritized issue list. A planner document is
+not required for review.
+
+## Workflow continuity
+
+Each user objective defines one active workflow. Associate specialist runs and
+background results with that objective.
+
+When a specialist result arrives:
+
+1. Integrate it into the current workflow state.
+2. Advance to the next phase when the output is sufficient.
+3. Re-invoke a specialist when new evidence has materially changed the brief or introduced a new decision.
+
+When the user establishes a new objective, make it the active workflow.
+Results from older workflows remain context, rather than becoming commands to
+resume the old workflow.
+
+## Background execution
+
+Use `async: true` when the main session can make independent progress while a
+specialist works. Use synchronous execution when the specialist's result is
+the immediate dependency for the next action.
+
+While a background specialist runs, gather evidence that improves the active
+brief and avoid duplicating the specialist's distinct assignment.
+
+## Timeouts
+
+Use the default task timeout unless the user explicitly requested a time
+limit. Specialist failures are workflow evidence: integrate the failure,
+continue with the available facts, and create a new run when an updated brief
+provides a materially better attempt.
+
+## Coordination principle
+
+The coordination cost of a specialist should be lower than the value of its
+distinct output. Main remains accountable for the complete user outcome.