pi-squad 0.5.0 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-squad",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Multi-agent collaboration extension for pi — task decomposition, dependency management, parallel execution, TUI panel",
   "type": "module",
   "pi": {
@@ -8,7 +8,7 @@
       "src/index.ts"
     ],
     "skills": [
-      "src/skills/supervisor"
+      "src/skills/squad-supervisor"
     ]
   },
   "files": [

package/src/agent-pool.ts

@@ -11,6 +11,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import type { AgentDef, AgentActivity, Task, TaskMessage } from "./types.js";
 import { buildAgentSystemPrompt, type ProtocolBuildOptions } from "./protocol.js";
+import { debug, logError } from "./logger.js";
 
 // ============================================================================
 // Types
@@ -165,7 +166,7 @@ export class AgentPool {
 
 		// Spawn pi process — set env var to prevent recursive squad extension loading
 		const invocation = getPiInvocation(["--mode", "rpc", ...args]);
-		console.error(`[squad-pool] spawn ${agentDef.name}: ${invocation.command} ${invocation.args.slice(0, 3).join(" ")} ...`);
+		debug("squad-pool", `spawn ${agentDef.name}: ${invocation.command} ${invocation.args.slice(0, 3).join(" ")} ...`);
 		const proc = spawn(invocation.command, invocation.args, {
 			cwd,
 			stdio: ["pipe", "pipe", "pipe"],
@@ -214,7 +215,7 @@ export class AgentPool {
 		proc.on("exit", (code, signal) => {
 			// Log diagnostic info for debugging spawn failures
 			if (code !== 0 && code !== null) {
-				console.error(`[squad-pool] ${agentDef.name} exited: code=${code} signal=${signal} pid=${proc.pid} stdoutLines=${stdoutLines} stderr=${stderr.slice(0, 300) || "(empty)"}`);
+				logError("squad-pool", `${agentDef.name} exited: code=${code} signal=${signal} pid=${proc.pid} stdoutLines=${stdoutLines} stderr=${stderr.slice(0, 300) || "(empty)"}`);
 			}
 			// Clean up agents map so getRunningAgents() doesn't count dead processes
 			this.agents.delete(taskId);
@@ -377,7 +378,7 @@ export class AgentPool {
 			// Pi RPC mode emits agent_end when the agent loop finishes.
 			// The RPC process stays alive waiting for more commands,
 			// so we need to explicitly kill it and emit our own agent_end.
-			console.error(`[squad-pool] agent_end from RPC: ${agent.agentName} (task: ${agent.taskId})`);
+			debug("squad-pool", `agent_end from RPC: ${agent.agentName} (task: ${agent.taskId})`);
 			// Mark the guard to prevent double-emit from proc.on("exit")
 			const guardFn = (agent as any)._agentEndEmitted;
 			if (guardFn) guardFn();

package/src/index.ts

@@ -21,6 +21,7 @@ import { runPlanner } from "./planner.js";
 import { SquadPanel, type SquadPanelResult } from "./panel/squad-panel.js";
 import { setupSquadWidget, type SquadWidgetState } from "./panel/squad-widget.js";
 import * as store from "./store.js";
+import { debug, logError } from "./logger.js";
 
 // ============================================================================
 // State
@@ -348,15 +349,14 @@ export default function (pi: ExtensionAPI) {
 						switch (event.type) {
 							case "squad_completed": {
 								const tasks = store.loadAllTasks(squadId);
-								const summary = tasks
-									.filter((t) => t.status === "done")
-									.map((t) => `- ${t.id} (${t.agent}): ${t.output?.slice(0, 150) || "done"}`)
-									.join("\n");
 								const totalCost = tasks.reduce((sum, t) => sum + t.usage.cost, 0);
 								const s = schedulers.get(squadId); if (s) s.updateContext();
+								const overview = store.loadOverview(squadId);
 								pi.sendMessage({
 									customType: "squad-completed",
-									content: `[squad] Squad "${squadId}" completed all ${tasks.length} tasks.\n\nSummary:\n${summary}\n\nTotal cost: $${totalCost.toFixed(4)}`,
+									content: `[squad] Squad "${squadId}" completed all ${tasks.length} tasks.\n\n` +
+										(overview ? `## Squad Overview\n\n${overview}\n\n` : "") +
+										`Total cost: $${totalCost.toFixed(4)}`,
 									display: true,
 								});
 								schedulers.delete(squadId);
@@ -367,9 +367,12 @@ export default function (pi: ExtensionAPI) {
 								const tasks = store.loadAllTasks(squadId);
 								const failed = tasks.filter((t) => t.status === "failed");
 								const done = tasks.filter((t) => t.status === "done");
+								const overview = store.loadOverview(squadId);
 								pi.sendMessage({
 									customType: "squad-failed",
-									content: `[squad] Squad "${squadId}" has stalled. ${done.length}/${tasks.length} done, ${failed.length} failed.\nFailed: ${failed.map((t) => `${t.id}: ${t.error?.slice(0, 100)}`).join("; ")}`,
+									content: `[squad] Squad "${squadId}" has stalled. ${done.length}/${tasks.length} done, ${failed.length} failed.\n` +
+										`Failed: ${failed.map((t) => `${t.id}: ${t.error?.slice(0, 100)}`).join("; ")}` +
+										(overview ? `\n\n## Squad Overview\n\n${overview}` : ""),
 									display: true,
 								}, { triggerTurn: true });
 								forceWidgetUpdate();
@@ -389,7 +392,7 @@ export default function (pi: ExtensionAPI) {
 
 				const resumeSched = schedulers.get(squadId)!;
 				resumeSched.resume().catch((err) => {
-					console.error(`[squad] Resume error: ${(err as Error).message}`);
+					logError("squad", `Resume error: ${(err as Error).message}`);
 				});
 
 				const tasks = store.loadAllTasks(squadId);
@@ -440,7 +443,7 @@ export default function (pi: ExtensionAPI) {
 				case "resume_task": {
 					if (!params.taskId) return { content: [{ type: "text" as const, text: "Provide taskId." }] };
 					activeScheduler.resumeTask(params.taskId).catch((err) => {
-						console.error(`[squad] Resume task error: ${(err as Error).message}`);
+						logError("squad", `Resume task error: ${(err as Error).message}`);
 					});
 					return { content: [{ type: "text" as const, text: `Task '${params.taskId}' resumed.` }] };
 				}
@@ -1213,6 +1216,31 @@ async function startSquad(
 
 	store.saveSquad(squad);
 
+	// Create initial OVERVIEW.md with squad goal, task plan, and design contract
+	const planLines = [
+		`# Squad: ${params.goal}`,
+		``,
+		`**Created:** ${squad.created}`,
+		`**Tasks:** ${plan.tasks.length}`,
+		``,
+		`## Task Plan`,
+		``,
+		...plan.tasks.map((t) => {
+			const deps = t.depends.length > 0 ? ` (after: ${t.depends.join(", ")})` : "";
+			return `- **${t.id}** → ${t.agent}: ${t.title}${deps}`;
+		}),
+		``,
+	];
+
+	// Extract design contract from task descriptions — API paths, schemas,
+	// ports, file conventions — so parallel agents share a single source of truth.
+	const contractLines = buildDesignContract(plan.tasks, params.goal);
+	if (contractLines.length > 0) {
+		planLines.push(...contractLines);
+	}
+
+	store.appendOverview(squadId, planLines.join("\n"));
+
 	// Create task files
 	for (const taskDef of plan.tasks) {
 		const task: Task = {
@@ -1258,12 +1286,8 @@ async function startSquad(
 		// Update widget on every scheduler event
 		forceWidgetUpdate();
 		switch (event.type) {
-			case "squad_completed": {
+				case "squad_completed": {
 				const tasks = store.loadAllTasks(squadId);
-				const summary = tasks
-					.filter((t) => t.status === "done")
-					.map((t) => `- ${t.id} (${t.agent}): ${t.output?.slice(0, 150) || "done"}`)
-					.join("\n");
 				const totalCost = tasks.reduce((sum, t) => sum + t.usage.cost, 0);
 
 				// Final context update before clearing scheduler
@@ -1272,12 +1296,17 @@ async function startSquad(
 					completedSched.updateContext();
 				}
 
-				// Use sendMessage with display:true — visible to user but doesn't
-				// pollute LLM message history. No triggerTurn needed for completions.
+				// Load the full overview document — contains the narrative of
+				// each task's output, decisions, issues, and files modified.
+				const overview = store.loadOverview(squadId);
+
+				// Send into LLM context (not display-only) so the main agent
+				// knows exactly what happened. No triggerTurn — user decides
+				// what to do next.
 				pi.sendMessage({
 					customType: "squad-completed",
 					content: `[squad] Squad "${squadId}" completed all ${tasks.length} tasks.\n\n` +
-						`Summary:\n${summary}\n\n` +
+						(overview ? `## Squad Overview\n\n${overview}\n\n` : "") +
 						`Total cost: $${totalCost.toFixed(4)}`,
 					display: true,
 				});
@@ -1292,14 +1321,14 @@ async function startSquad(
 				const tasks = store.loadAllTasks(squadId);
 				const failed = tasks.filter((t) => t.status === "failed");
 				const done = tasks.filter((t) => t.status === "done");
+				const overview = store.loadOverview(squadId);
 
-				// Squad failed — notify user. Use triggerTurn so the agent can
-				// suggest next steps (retry, modify, cancel).
 				pi.sendMessage({
 					customType: "squad-failed",
 					content: `[squad] Squad "${squadId}" has stalled. ` +
 						`${done.length}/${tasks.length} tasks done, ${failed.length} failed.\n` +
 						`Failed: ${failed.map((t) => `${t.id}: ${t.error?.slice(0, 100)}`).join("; ")}\n` +
+						(overview ? `\n## Squad Overview\n\n${overview}\n\n` : "\n") +
 						`Use squad_status for details or squad_modify to adjust.`,
 					display: true,
 				}, { triggerTurn: true });
@@ -1327,7 +1356,7 @@ async function startSquad(
 	// We must return immediately so the main agent's turn completes
 	// and the user regains interactive control.
 	scheduler.start().catch((err) => {
-		console.error(`[squad] Scheduler start error: ${(err as Error).message}`);
+		logError("squad", `Scheduler start error: ${(err as Error).message}`);
 	});
 
 	// Build response
@@ -1360,3 +1389,99 @@ function getSquadSkillPaths(skillsDir: string): string[] {
 		.map((d) => path.join(skillsDir, d.name))
 		.filter((dir) => fs.existsSync(path.join(dir, "SKILL.md")));
 }
+
+/**
+ * Extract a design contract from task descriptions.
+ *
+ * Scans all tasks for API paths, ports, file names, data schemas, and
+ * shared conventions. Produces a "## Design Contract" section in the
+ * OVERVIEW.md so that ALL agents (including parallel ones) share a
+ * single source of truth before they start working.
+ */
+function buildDesignContract(
+	tasks: Array<{ id: string; title: string; description: string; agent: string; depends: string[] }>,
+	goal: string,
+): string[] {
+	const lines: string[] = [];
+
+	// Collect API routes mentioned in any task description
+	const apiRoutes: string[] = [];
+	const ports: string[] = [];
+	const files: string[] = [];
+	const schemas: string[] = [];
+
+	const allText = tasks.map((t) => `${t.title}\n${t.description}`).join("\n") + "\n" + goal;
+
+	// Extract API paths like GET /foo, POST /bar/:id
+	const routePattern = /\b(GET|POST|PUT|PATCH|DELETE|HEAD)\s+(\/[\w\/:]+)/gi;
+	for (const match of allText.matchAll(routePattern)) {
+		const route = `${match[1].toUpperCase()} ${match[2]}`;
+		if (!apiRoutes.includes(route)) apiRoutes.push(route);
+	}
+
+	// Extract port numbers
+	const portPattern = /\b(?:port|PORT|Port)\s*[=:]?\s*(\d{4,5})\b/gi;
+	for (const match of allText.matchAll(portPattern)) {
+		if (!ports.includes(match[1])) ports.push(match[1]);
+	}
+
+	// Extract key file names mentioned (e.g., server.js, index.html)
+	const filePattern = /\b([\w-]+\.(js|ts|json|html|css|sh|mjs|cjs))\b/gi;
+	for (const match of allText.matchAll(filePattern)) {
+		const f = match[1];
+		if (!files.includes(f) && !['package.json'].includes(f)) files.push(f);
+	}
+
+	// Extract data schemas like {field, field, field}
+	const schemaPattern = /\{([a-zA-Z_][\w,\s\[\]?]+)\}/g;
+	for (const match of allText.matchAll(schemaPattern)) {
+		const fields = match[1].trim();
+		if (fields.includes(',') && fields.length > 5 && fields.length < 200) {
+			if (!schemas.includes(fields)) schemas.push(fields);
+		}
+	}
+
+	// Only emit a contract section if we found shared design elements
+	if (apiRoutes.length === 0 && ports.length === 0 && schemas.length === 0) {
+		return [];
+	}
+
+	lines.push(`## Design Contract`);
+	lines.push(``);
+	lines.push(`> **All agents MUST follow these specifications.** Do not invent`);
+	lines.push(`> alternative paths, ports, or schemas. If you need to deviate,`);
+	lines.push(`> document the reason in your output.`);
+	lines.push(``);
+
+	if (ports.length > 0) {
+		lines.push(`### Server`);
+		lines.push(`- Port: **${ports.join(", ")}**`);
+		lines.push(``);
+	}
+
+	if (apiRoutes.length > 0) {
+		lines.push(`### API Endpoints`);
+		for (const r of apiRoutes) {
+			lines.push(`- \`${r}\``);
+		}
+		lines.push(``);
+	}
+
+	if (schemas.length > 0) {
+		lines.push(`### Data Schemas`);
+		for (const s of schemas) {
+			lines.push(`- \`{ ${s} }\``);
+		}
+		lines.push(``);
+	}
+
+	if (files.length > 0) {
+		lines.push(`### Key Files`);
+		for (const f of files) {
+			lines.push(`- \`${f}\``);
+		}
+		lines.push(``);
+	}
+
+	return lines;
+}

package/src/logger.ts

@@ -0,0 +1,68 @@
+/**
+ * logger.ts — Squad debug logging to file, NOT stderr.
+ *
+ * Writing to stderr (console.error) corrupts the TUI because it bypasses
+ * the TUI's differential renderer. All squad debug output goes to a log
+ * file instead: ~/.pi/squad/debug.log
+ *
+ * Set PI_SQUAD_DEBUG=1 to enable logging. Without it, logs are silent.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+
+const LOG_DIR = path.join(os.homedir(), ".pi", "squad");
+const LOG_FILE = path.join(LOG_DIR, "debug.log");
+const DEBUG = process.env.PI_SQUAD_DEBUG === "1";
+
+/** Max log file size before rotation (2MB) */
+const MAX_LOG_SIZE = 2 * 1024 * 1024;
+
+let rotationChecked = false;
+
+function ensureLogDir(): void {
+	try {
+		fs.mkdirSync(LOG_DIR, { recursive: true });
+	} catch { /* ignore */ }
+}
+
+function rotateIfNeeded(): void {
+	if (rotationChecked) return;
+	rotationChecked = true;
+	try {
+		const stat = fs.statSync(LOG_FILE);
+		if (stat.size > MAX_LOG_SIZE) {
+			const backup = LOG_FILE + ".old";
+			try { fs.unlinkSync(backup); } catch { /* ignore */ }
+			fs.renameSync(LOG_FILE, backup);
+		}
+	} catch { /* file doesn't exist yet, fine */ }
+}
+
+/**
+ * Log a debug message to ~/.pi/squad/debug.log.
+ * Only writes when PI_SQUAD_DEBUG=1 is set. Silent otherwise.
+ */
+export function debug(prefix: string, ...args: unknown[]): void {
+	if (!DEBUG) return;
+	write(prefix, ...args);
+}
+
+/**
+ * Always log to ~/.pi/squad/debug.log regardless of PI_SQUAD_DEBUG.
+ * Use for errors and critical events that should never be lost.
+ */
+export function logError(prefix: string, ...args: unknown[]): void {
+	write(prefix, ...args);
+}
+
+function write(prefix: string, ...args: unknown[]): void {
+	try {
+		ensureLogDir();
+		rotateIfNeeded();
+		const ts = new Date().toISOString();
+		const msg = args.map(a => typeof a === "string" ? a : JSON.stringify(a)).join(" ");
+		fs.appendFileSync(LOG_FILE, `[${ts}] [${prefix}] ${msg}\n`);
+	} catch { /* never throw from logging */ }
+}

package/src/panel/squad-widget.ts

@@ -1,15 +1,17 @@
 /**
- * squad-widget.ts — Simple string[] widget for squad status.
+ * squad-widget.ts — Compact widget for squad status above the editor.
  *
- * Uses the simple setWidget(key, string[]) API which pi-tui handles
- * reliably. Component-based widgets with variable height cause TUI
- * layout corruption.
+ * Uses a component factory for setWidget so it can access terminal width
+ * and truncate every line to prevent Text wrapping. Without truncation,
+ * long lines wrap inside the Text component, causing unpredictable
+ * widget height changes that corrupt the TUI diff renderer.
  *
  * Updates are pushed by calling requestUpdate() which rebuilds the
- * string[] and calls setWidget() again.
+ * lines and calls setWidget() again.
  */
 
-import { truncateToWidth } from "@mariozechner/pi-tui";
+import { truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
+import type { Component, TUI } from "@mariozechner/pi-tui";
 import type { Theme } from "@mariozechner/pi-coding-agent";
 import type { TaskStatus } from "../types.js";
 import * as store from "../store.js";
@@ -41,7 +43,10 @@ export interface SquadWidgetState {
 
 /**
  * Set up the squad widget. Returns control functions.
- * Uses simple string[] setWidget — no component factory.
+ *
+ * Uses a component factory so we can access TUI.terminal.columns and
+ * truncate every line, preventing Text word-wrapping that would cause
+ * unpredictable widget height changes.
  */
 export function setupSquadWidget(
 	ctx: { ui: { setWidget: Function; setStatus: Function; [key: string]: any }; hasUI?: boolean },
@@ -56,22 +61,16 @@ export function setupSquadWidget(
 	let renderTimer: ReturnType<typeof setTimeout> | null = null;
 	/** Cache key to skip redundant setWidget calls */
 	let lastCacheKey = "";
+	/** Last built lines — the factory re-uses these on each TUI render */
+	let currentLines: string[] = [];
 
-	function render(): void {
-		if (!state.enabled || !state.squadId) {
-			ctx.ui.setWidget("squad-tasks", undefined);
-			ctx.ui.setStatus("squad", undefined);
-			return;
-		}
+	function buildLines(): { lines: string[]; cacheKey: string; statusText: string } | null {
+		if (!state.enabled || !state.squadId) return null;
 
 		const th = ctx.ui.theme;
 		const tasks = store.loadAllTasks(state.squadId);
 		const squad = store.loadSquad(state.squadId);
-		if (!squad || tasks.length === 0) {
-			ctx.ui.setWidget("squad-tasks", undefined);
-			ctx.ui.setStatus("squad", undefined);
-			return;
-		}
+		if (!squad || tasks.length === 0) return null;
 
 		const lines: string[] = [];
 		const totalCost = tasks.reduce((sum, t) => sum + t.usage.cost, 0);
@@ -136,19 +135,77 @@ export function setupSquadWidget(
 			lines.push(`  ${th.fg("dim", `  +${tasks.length - maxVisible} more · ^q detail`)}`);
 		}
 
-		// Skip if nothing changed (avoid redundant setWidget calls that cause flicker)
 		const cacheKey = `${squad.status}:${tasks.map(t => `${t.id}=${t.status}:${t.usage.turns}`).join(",")}`;
-		if (cacheKey === lastCacheKey) return;
-		lastCacheKey = cacheKey;
 
-		ctx.ui.setWidget("squad-tasks", lines);
-
-		// Update status bar
 		const statusText = squad.status === "done"
 			? th.fg("success", `✓ squad ${doneCount}/${tasks.length}`)
 			: squad.status === "failed"
 			? th.fg("error", `✗ squad ${doneCount}/${tasks.length}`)
 			: th.fg("accent", `⏳ squad ${doneCount}/${tasks.length} $${totalCost.toFixed(2)}`);
+
+		return { lines, cacheKey, statusText };
+	}
+
+	/**
+	 * Widget component that renders pre-built lines truncated to terminal width.
+	 * Each line is guaranteed to fit on exactly one terminal row — no wrapping.
+	 * This keeps the widget height deterministic (= lines.length) so the TUI
+	 * diff renderer never sees unexpected height changes.
+	 */
+	class SquadWidgetComponent implements Component {
+		lines: string[] = [];
+
+		invalidate(): void { /* stateless — lines are rebuilt externally */ }
+
+		render(width: number): string[] {
+			// Truncate every line to terminal width so Text wrapping cannot
+			// add extra rows. One input line → exactly one output line.
+			return this.lines.map(line => {
+				const truncated = truncateToWidth(line, width);
+				// Pad to full width to prevent leftover characters from previous renders
+				const vw = visibleWidth(truncated);
+				const pad = Math.max(0, width - vw);
+				return truncated + " ".repeat(pad);
+			});
+		}
+	}
+
+	/** Persistent widget component instance — survives across setWidget calls */
+	let widgetComponent: SquadWidgetComponent | null = null;
+	let widgetInstalled = false;
+
+	function render(): void {
+		const result = buildLines();
+		if (!result) {
+			ctx.ui.setWidget("squad-tasks", undefined);
+			ctx.ui.setStatus("squad", undefined);
+			widgetInstalled = false;
+			return;
+		}
+
+		const { lines, cacheKey, statusText } = result;
+
+		// Skip if nothing changed (avoid redundant setWidget calls)
+		if (cacheKey === lastCacheKey) return;
+		lastCacheKey = cacheKey;
+
+		currentLines = lines;
+
+		if (!widgetInstalled) {
+			// Install the component factory once. On subsequent updates we just
+			// mutate widgetComponent.lines and requestRender — no setWidget churn.
+			widgetComponent = new SquadWidgetComponent();
+			widgetComponent.lines = lines;
+
+			const comp = widgetComponent;
+			ctx.ui.setWidget("squad-tasks", (_tui: TUI, _theme: Theme) => comp);
+			widgetInstalled = true;
+		} else if (widgetComponent) {
+			// Update lines in-place — the next TUI render picks them up.
+			// No setWidget call needed, avoiding component tree rebuild.
+			widgetComponent.lines = lines;
+		}
+
 		ctx.ui.setStatus("squad", statusText);
 	}
 

package/src/planner.ts

@@ -33,6 +33,14 @@ export async function runPlanner(options: PlannerOptions): Promise<PlannerOutput
 	const plannerDef = loadAgentDef("planner", cwd);
 	const allAgents = loadAllAgentDefs(cwd).filter((a) => a.name !== "planner" && !a.disabled);
 
+	if (allAgents.length === 0) {
+		throw new Error(
+			"No squad agents found. Agent definitions should be in ~/.pi/squad/agents/. " +
+			"This usually means the extension failed to load on first run (check /reload for errors). " +
+			"Try: /reload, then run the squad command again."
+		);
+	}
+
 	const agentList = allAgents
 		.map((a) => `- **${a.name}** (${a.role}): ${a.description} [tags: ${a.tags.join(", ")}]`)
 		.join("\n");
@@ -250,6 +258,13 @@ Respond with a JSON object (and nothing else outside the JSON):
 - Include a final QA/verification task if there are user-facing changes
 - Keep descriptions actionable — agent should know exactly what to build
 - Don't over-decompose — 3-7 tasks is usually right for most goals
+
+## Shared Contracts
+- When tasks share an interface (e.g., API endpoints, database schema, data formats), create a design/architecture task first that defines the contract, and make consuming tasks depend on it
+- If tasks run in parallel, they MUST depend on a shared spec task that defines the interface between them
+- Frontend tasks should depend on backend API tasks — the frontend agent needs a running API to test against
+- In each task description, specify the exact API paths, data schemas, and conventions that the agent should follow or create
+
 `;
 }
 

package/src/protocol.ts

@@ -11,7 +11,7 @@
  */
 
 import type { AgentDef, KnowledgeEntry, Squad, Task, TaskMessage } from "./types.js";
-import { loadAllKnowledge, loadAllTasks, loadMessages } from "./store.js";
+import { loadAllKnowledge, loadAllTasks, loadMessages, loadOverview } from "./store.js";
 
 // ============================================================================
 // Squad Protocol (injected into every agent)
@@ -54,7 +54,9 @@ The squad system will detect this and route help.
 ## Rules
 - Stay focused on YOUR task — don't do work assigned to other agents
 - Read the dependency outputs below — don't redo completed work
+- **Follow the Design Contract in the Squad Progress Document** — use the exact API paths, ports, schemas, and file names specified. Do NOT invent alternatives
 - Check the modified files list — coordinate before editing shared files
+- When creating APIs, clearly document all endpoints, request/response shapes, and status codes in your completion output
 - Ask for help if stuck — don't spin for more than a few minutes
 - Verify your work before claiming done
 `;
@@ -114,6 +116,20 @@ ${sections.join("\n---\n\n")}
 `;
 }
 
+// ============================================================================
+// Squad Progress Overview
+// ============================================================================
+
+export function buildOverviewSection(squadId: string): string {
+	const content = loadOverview(squadId);
+	if (!content.trim()) return "";
+
+	return `# Squad Progress Document
+
+${content.trim()}
+`;
+}
+
 // ============================================================================
 // Sibling Awareness
 // ============================================================================
@@ -293,6 +309,7 @@ export function buildAgentSystemPrompt(options: ProtocolBuildOptions): string {
 		buildTaskSection(task),
 		buildReworkContext(task, squadId),
 		buildChainContext(task, allTasks, squadId),
+		buildOverviewSection(squadId),
 		buildSiblingAwareness(task, allTasks, modifiedFiles),
 		buildKnowledgeSection(squadId),
 		buildQueuedMessages(queuedMessages),

package/src/scheduler.ts

@@ -14,6 +14,7 @@ import { AgentPool, type AgentEvent } from "./agent-pool.js";
 import { Monitor } from "./monitor.js";
 import { Router } from "./router.js";
 import * as store from "./store.js";
+import { debug, logError } from "./logger.js";
 import { buildAgentSystemPrompt } from "./protocol.js";
 
 // ============================================================================
@@ -183,13 +184,13 @@ export class Scheduler {
 	/** Find and spawn ready tasks up to concurrency limit */
 	private async scheduleReadyTasks(): Promise<void> {
 		if (!this.running) {
-			console.error("[squad-scheduler] scheduleReadyTasks: not running, skipping");
+			debug("squad-scheduler", "scheduleReadyTasks: not running, skipping");
 			return;
 		}
 
 		const squad = store.loadSquad(this.squadId);
 		if (!squad || squad.status !== "running") {
-			console.error(`[squad-scheduler] scheduleReadyTasks: squad status=${squad?.status}, skipping`);
+			debug("squad-scheduler", `scheduleReadyTasks: squad status=${squad?.status}, skipping`);
 			return;
 		}
 
@@ -197,22 +198,22 @@ export class Scheduler {
 		const runningCount = this.pool.getRunningAgents().length;
 		const available = squad.config.maxConcurrency - runningCount;
 
-		console.error(`[squad-scheduler] scheduleReadyTasks: ${tasks.length} tasks, ${runningCount} running, ${available} slots`);
+		debug("squad-scheduler", `scheduleReadyTasks: ${tasks.length} tasks, ${runningCount} running, ${available} slots`);
 
 		if (available <= 0) {
-			console.error("[squad-scheduler] scheduleReadyTasks: no available slots");
+			debug("squad-scheduler", "scheduleReadyTasks: no available slots");
 			return;
 		}
 
 		const ready = this.getReadyTasks(tasks);
-		console.error(`[squad-scheduler] scheduleReadyTasks: ${ready.length} ready tasks: ${ready.map(t => t.id).join(", ")}`);
+		debug("squad-scheduler", `scheduleReadyTasks: ${ready.length} ready tasks: ${ready.map(t => t.id).join(", ")}`);
 		const toSpawn = ready.slice(0, available);
 
 		for (const task of toSpawn) {
 			try {
 				await this.spawnAgentForTask(task, squad);
 			} catch (error) {
-				console.error(`[squad-scheduler] Failed to spawn ${task.id}: ${(error as Error).message}`);
+				logError("squad-scheduler", `Failed to spawn ${task.id}: ${(error as Error).message}`);
 				// MUST fail the task — otherwise it stays in_progress forever
 				// with no process (zombie state)
 				this.handleTaskFailed(task.id, `Spawn failed: ${(error as Error).message}`);
@@ -393,7 +394,7 @@ export class Scheduler {
 					if (!this.spawnRetries.has(retryKey)) {
 						this.spawnRetries.add(retryKey);
 						const stderr = event.data?.stderr || "";
-						console.error(`[squad-scheduler] Agent ${event.agentName} died instantly (code ${exitCode}). Retrying in 2s... stderr: ${stderr.slice(0, 200)}`);
+						logError("squad-scheduler", `Agent ${event.agentName} died instantly (code ${exitCode}). Retrying in 2s... stderr: ${stderr.slice(0, 200)}`);
 						store.updateTaskStatus(this.squadId, event.taskId, "pending");
 						store.appendMessage(this.squadId, event.taskId, {
 							ts: store.now(),
@@ -456,6 +457,10 @@ export class Scheduler {
 			text: "Task completed",
 		});
 
+		// Reload task after status update so overview has output, completed time, etc.
+		const updatedTask = store.loadTask(this.squadId, taskId) || task;
+		this.appendTaskOverview(updatedTask, taskId, messages);
+
 		this.emit({
 			type: "task_completed",
 			squadId: this.squadId,
@@ -470,7 +475,7 @@ export class Scheduler {
 
 		if (!reworkCreated) {
 			// Normal flow: auto-unblock dependents
-			console.error(`[squad-scheduler] handleTaskCompleted: ${taskId} done, auto-unblocking dependents`);
+			debug("squad-scheduler", `handleTaskCompleted: ${taskId} done, auto-unblocking dependents`);
 			this.autoUnblock(taskId);
 
 			// If this is a passing retest, also unblock dependents of the ORIGINAL
@@ -485,19 +490,19 @@ export class Scheduler {
 					rootId = root.retryOf;
 					root = allTasks.find((t) => t.id === rootId);
 				}
-				console.error(`[squad-scheduler] Retest passed — also unblocking dependents of original: ${rootId}`);
+				debug("squad-scheduler", `Retest passed — also unblocking dependents of original: ${rootId}`);
 				this.autoUnblock(rootId);
 			}
 		}
 
 		// Schedule next ready tasks (may spawn new agents)
-		console.error(`[squad-scheduler] handleTaskCompleted: scheduling next ready tasks`);
+		debug("squad-scheduler", `handleTaskCompleted: scheduling next ready tasks`);
 		await this.scheduleReadyTasks();
 
 		// Re-check squad completion with fresh data AFTER scheduling
 		const freshTasks = store.loadAllTasks(this.squadId);
 		const freshSquad = store.loadSquad(this.squadId);
-		console.error(`[squad-scheduler] handleTaskCompleted: final check — tasks: ${freshTasks.map(t => `${t.id}:${t.status}`).join(", ")}`);
+		debug("squad-scheduler", `handleTaskCompleted: final check — tasks: ${freshTasks.map(t => `${t.id}:${t.status}`).join(", ")}`);
 		if (freshSquad) {
 			this.checkSquadCompletion(freshTasks, freshSquad);
 		}
@@ -620,7 +625,7 @@ export class Scheduler {
 			const originalId = implTask.retryOf || implTask.id;
 
 			if (retryCount >= squad.config.maxRetries) {
-				console.error(`[squad-scheduler] Retry limit reached for ${originalId} (${retryCount}/${squad.config.maxRetries})`);
+				debug("squad-scheduler", `Retry limit reached for ${originalId} (${retryCount}/${squad.config.maxRetries})`);
 				this.emit({
 					type: "escalation",
 					squadId: this.squadId,
@@ -689,7 +694,7 @@ export class Scheduler {
 				message: `QA found issues in ${implTask.id}. Rework attempt ${fixN}.`,
 			});
 
-			console.error(`[squad-scheduler] Rework: ${reworkId} (${implTask.agent}) + retest ${retestId} (${task.agent})`);
+			debug("squad-scheduler", `Rework: ${reworkId} (${implTask.agent}) + retest ${retestId} (${task.agent})`);
 			createdAny = true;
 		}
 
@@ -931,6 +936,89 @@ export class Scheduler {
 			.map((p: any) => p.text);
 		return textParts.length > 0 ? textParts.join("\n") : null;
 	}
+
+	// =========================================================================
+	// Overview Document — append task summary after completion
+	// =========================================================================
+
+	/**
+	 * Build a concise markdown summary of a completed task and append it
+	 * to the squad's OVERVIEW.md. This gives subsequent agents a narrative
+	 * understanding of what was accomplished, issues hit, and decisions made.
+	 */
+	private appendTaskOverview(
+		task: Task,
+		taskId: string,
+		messages: import("./types.js").TaskMessage[],
+	): void {
+		try {
+			const lines: string[] = [];
+
+			// Header
+			lines.push(`## ${task.id}: ${task.title}`);
+			lines.push(``);
+			lines.push(`**Agent:** ${task.agent} | **Status:** ${task.status}`);
+			if (task.started && task.completed) {
+				const dur = new Date(task.completed).getTime() - new Date(task.started).getTime();
+				lines.push(`**Duration:** ${formatElapsed(dur)}`);
+			}
+			lines.push(``);
+
+			// Output
+			if (task.output) {
+				lines.push(`### Output`);
+				lines.push(task.output.slice(0, 800));
+				if (task.output.length > 800) lines.push(`... (truncated)`);
+				lines.push(``);
+			}
+
+			// Issues / errors encountered
+			const errors = messages.filter((m) => m.type === "error" && m.from !== "system");
+			if (errors.length > 0) {
+				lines.push(`### Issues Encountered`);
+				for (const err of errors.slice(-5)) {
+					lines.push(`- ${err.text.split("\n")[0].slice(0, 200)}`);
+				}
+				lines.push(``);
+			}
+
+			// Decisions — scan agent text for decision-like language
+			const decisionPatterns = /\b(decided|chose|approach|instead of|trade-?off|opted|going with|switched to|using .+ because)\b/i;
+			const agentTexts = messages.filter((m) => m.from === task.agent && m.type === "text");
+			const decisions: string[] = [];
+			for (const msg of agentTexts) {
+				for (const line of msg.text.split("\n")) {
+					if (decisionPatterns.test(line) && line.trim().length > 10) {
+						decisions.push(line.trim().slice(0, 200));
+					}
+				}
+			}
+			if (decisions.length > 0) {
+				lines.push(`### Decisions`);
+				for (const d of decisions.slice(-5)) {
+					lines.push(`- ${d}`);
+				}
+				lines.push(``);
+			}
+
+			// Files modified
+			const activity = this.pool.getActivity(taskId);
+			if (activity && activity.modifiedFiles.size > 0) {
+				lines.push(`### Files Modified`);
+				for (const f of Array.from(activity.modifiedFiles).slice(0, 15)) {
+					lines.push(`- ${f}`);
+				}
+				if (activity.modifiedFiles.size > 15) {
+					lines.push(`- ... and ${activity.modifiedFiles.size - 15} more`);
+				}
+				lines.push(``);
+			}
+
+			store.appendOverview(this.squadId, lines.join("\n"));
+		} catch (err) {
+			logError("squad-scheduler", `Failed to append overview for ${taskId}: ${(err as Error).message}`);
+		}
+	}
 }
 
 function formatElapsed(ms: number): string {

package/src/store.ts

@@ -405,6 +405,32 @@ export function loadAllKnowledge(squadId: string): KnowledgeEntry[] {
 	].sort((a, b) => a.ts.localeCompare(b.ts));
 }
 
+// ============================================================================
+// Overview Document (shared squad summary)
+// ============================================================================
+
+export function getOverviewPath(squadId: string): string {
+	return path.join(getSquadDir(squadId), "OVERVIEW.md");
+}
+
+export function loadOverview(squadId: string): string {
+	try {
+		return fs.readFileSync(getOverviewPath(squadId), "utf-8");
+	} catch {
+		return "";
+	}
+}
+
+export function appendOverview(squadId: string, section: string): void {
+	const filePath = getOverviewPath(squadId);
+	ensureDir(path.dirname(filePath));
+	const existing = loadOverview(squadId);
+	const content = existing
+		? existing.trimEnd() + "\n\n---\n\n" + section.trim() + "\n"
+		: section.trim() + "\n";
+	fs.writeFileSync(filePath, content, "utf-8");
+}
+
 // ============================================================================
 // Rework Helpers
 // ============================================================================