taskplane 0.13.0 → 0.14.0

package/bin/taskplane.mjs

@@ -507,6 +507,7 @@ async function cmdUninstall(args) {
 		".pi/agents/task-worker.md",
 		".pi/agents/task-reviewer.md",
 		".pi/agents/task-merger.md",
+		".pi/agents/supervisor.md",
 		".pi/batch-state.json",
 		".pi/batch-history.json",
 		".pi/orch-abort-signal",
@@ -1301,7 +1302,7 @@ async function cmdInit(args) {
 		const skipIfExists = !force && !userConfirmedOverwrite;
 
 		// Agent prompts
-		for (const agent of ["task-worker.md", "task-reviewer.md", "task-merger.md"]) {
+		for (const agent of ["task-worker.md", "task-reviewer.md", "task-merger.md", "supervisor.md"]) {
 			copyTemplate(
 				path.join(TEMPLATES_DIR, "agents", "local", agent),
 				path.join(taskplaneDir, "agents", agent),
@@ -1524,7 +1525,7 @@ async function cmdInit(args) {
 
 	// Agent prompts — copy thin local files (base prompts ship in the package
 	// and are composed automatically by the task-runner at runtime)
-	for (const agent of ["task-worker.md", "task-reviewer.md", "task-merger.md"]) {
+	for (const agent of ["task-worker.md", "task-reviewer.md", "task-merger.md", "supervisor.md"]) {
 		copyTemplate(
 			path.join(TEMPLATES_DIR, "agents", "local", agent),
 			path.join(projectRoot, ".pi", "agents", agent),
@@ -1685,6 +1686,7 @@ function printFileList(vars, noExamples, preset, exampleTemplateDirs = [], proje
 		".pi/agents/task-worker.md",
 		".pi/agents/task-reviewer.md",
 		".pi/agents/task-merger.md",
+		".pi/agents/supervisor.md",
 		".pi/task-runner.yaml",
 	];
 	if (preset !== "runner-only") files.push(".pi/task-orchestrator.yaml");
@@ -1723,6 +1725,7 @@ function printWorkspaceFileList(vars, noExamples, preset, exampleTemplateDirs, c
 		`${prefix}/agents/task-worker.md`,
 		`${prefix}/agents/task-reviewer.md`,
 		`${prefix}/agents/task-merger.md`,
+		`${prefix}/agents/supervisor.md`,
 		`${prefix}/task-runner.yaml`,
 	];
 	if (preset !== "runner-only") files.push(`${prefix}/task-orchestrator.yaml`);
@@ -2518,6 +2521,7 @@ function cmdDoctor() {
 		{ path: "agents/task-worker.md", required: true },
 		{ path: "agents/task-reviewer.md", required: true },
 		{ path: "agents/task-merger.md", required: true },
+		{ path: "agents/supervisor.md", required: false },
 		{ path: "taskplane.json", required: false },
 	];
 

package/extensions/taskplane/supervisor-primer.md

@@ -25,6 +25,12 @@ reviewers), or merge branches (that's merge agents). You supervise all of them.
 full filesystem and command-line access. Use it to read state files, run git
 commands, edit batch state, manage tmux sessions, and run verification.
 
+**Your system prompt** is built from `templates/agents/supervisor.md` (base
+template, ships with the package) composed with `.pi/agents/supervisor.md`
+(project-specific overrides). The operator can customize your behavior by
+editing the local override file. Dynamic batch context (IDs, paths, counts,
+guardrails) is injected at runtime.
+
 ---
 
 ## 2. Architecture in 60 Seconds
@@ -1070,6 +1076,7 @@ Create the directory and add thin override files:
 - `.pi/agents/task-worker.md` — worker prompt overrides (can be empty initially)
 - `.pi/agents/task-reviewer.md` — reviewer prompt overrides (can be empty initially)
 - `.pi/agents/task-merger.md` — merger prompt overrides (can be empty initially)
+- `.pi/agents/supervisor.md` — supervisor prompt overrides (can be empty initially)
 
 Each file can start with a brief comment explaining its purpose:
 ```markdown

package/extensions/taskplane/supervisor.ts

@@ -1748,6 +1748,171 @@ function resolvePrimerPath(): string {
 	}
 }
 
+
+// ── Template Loading (TP-058) ────────────────────────────────────────
+
+/**
+ * Resolve the path to a base supervisor template shipped with the package.
+ *
+ * Templates live in `<package-root>/templates/agents/`. This function derives
+ * the package root from the extension file's location
+ * (`<package-root>/extensions/taskplane/supervisor.ts`).
+ *
+ * @param name - Template filename without extension (e.g. "supervisor", "supervisor-routing")
+ * @returns Absolute path to the template file
+ *
+ * @since TP-058
+ */
+function resolveBaseTemplatePath(name: string): string {
+	try {
+		const thisDir = dirname(fileURLToPath(import.meta.url));
+		// thisDir = <package-root>/extensions/taskplane/
+		return join(thisDir, "..", "..", "templates", "agents", `${name}.md`);
+	} catch {
+		return join(__dirname, "..", "..", "templates", "agents", `${name}.md`);
+	}
+}
+
+/**
+ * Parse a simple frontmatter+body markdown file.
+ * Returns null if the file doesn't exist or has no frontmatter.
+ *
+ * @since TP-058
+ */
+function parseSupervisorTemplate(filePath: string): { fm: Record<string, string>; body: string } | null {
+	if (!existsSync(filePath)) return null;
+	const raw = readFileSync(filePath, "utf-8").replace(/\r\n/g, "\n");
+	const match = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+	if (!match) return null;
+	const fm: Record<string, string> = {};
+	for (const line of match[1].split("\n")) {
+		const idx = line.indexOf(":");
+		if (idx > 0) {
+			const key = line.slice(0, idx).trim();
+			if (!key.startsWith("#")) { // Skip commented-out frontmatter
+				fm[key] = line.slice(idx + 1).trim();
+			}
+		}
+	}
+	return { fm, body: match[2].trim() };
+}
+
+/**
+ * Load a supervisor template: base (from package) + local override (from project).
+ *
+ * Follows the same composition pattern as `loadAgentDef()` in task-runner.ts:
+ * - Base template: shipped in `templates/agents/{name}.md`
+ * - Local override: `.pi/agents/{name}.md` in the project
+ * - If local has `standalone: true`, use it exclusively
+ * - Otherwise, compose base + local with a separator
+ *
+ * @param name - Template name (e.g. "supervisor", "supervisor-routing")
+ * @param stateRoot - Root path for .pi/ state directory
+ * @returns The composed template body, or null if no template found
+ *
+ * @since TP-058
+ */
+export function loadSupervisorTemplate(name: string, stateRoot: string, localName?: string): string | null {
+	const basePath = resolveBaseTemplatePath(name);
+	const baseDef = parseSupervisorTemplate(basePath);
+
+	// Load local override from .pi/agents/{localName}.md (defaults to base name)
+	// This allows routing template (base: "supervisor-routing") to share the
+	// same local override as the main supervisor (local: "supervisor").
+	const effectiveLocalName = localName || name;
+	const localPath = stateRoot ? join(stateRoot, ".pi", "agents", `${effectiveLocalName}.md`) : "";
+	const localDef = localPath ? parseSupervisorTemplate(localPath) : null;
+
+	// No base and no local → null (triggers fallback to inline prompt)
+	if (!baseDef && !localDef) return null;
+
+	// Local with standalone: true → use local as-is, ignore base
+	if (localDef?.fm.standalone === "true") {
+		return localDef.body;
+	}
+
+	// Compose base + local
+	const baseBody = baseDef?.body || "";
+	const localBody = localDef?.body || "";
+	if (localBody) {
+		return baseBody + "\n\n---\n\n## Project-Specific Guidance\n\n" + localBody;
+	}
+	return baseBody;
+}
+
+/**
+ * Replace `{{variable}}` placeholders in a template string.
+ *
+ * @param template - Template string with `{{key}}` placeholders
+ * @param vars - Key-value map of variable replacements
+ * @returns Template with all known placeholders replaced
+ *
+ * @since TP-058
+ */
+function replaceTemplateVars(template: string, vars: Record<string, string>): string {
+	return template.replace(/\{\{(\w+)\}\}/g, (match, key) => {
+		return key in vars ? vars[key] : match;
+	});
+}
+
+
+/**
+ * Build the guardrails section dynamically based on integration mode (TP-043).
+ * Extracted as a helper so both the template path and inline fallback can reuse it.
+ * @since TP-058
+ */
+function buildGuardrailsSection(integrationMode: string): string {
+	if (integrationMode === "supervised" || integrationMode === "auto") {
+		const modeNote = integrationMode === "supervised"
+			? `**Supervised mode:** Before executing integration, describe your plan and ask the operator for confirmation.`
+			: `**Auto mode:** Execute integration directly. Report the outcome to the operator. Pause only on errors or conflicts.`;
+		return `## What You Must NEVER Do
+
+1. Never delete \`.pi/batch-state.json\` without operator approval
+2. Never modify task code (files that workers wrote)
+3. Never modify PROMPT.md files
+4. Never \`git reset --hard\` with uncommitted changes
+5. Never skip tasks/waves without telling the operator
+6. Never create GitHub releases
+
+## Integration Permissions (mode: ${integrationMode})
+
+You are authorized to perform integration operations after batch completion:
+- \`git push origin <orch-branch>\` — push the orch branch for PR creation
+- \`gh pr create\` — create pull requests for integration
+- \`git merge --ff-only\` or \`git merge --no-edit\` — local branch integration
+- \`git branch -D <orch-branch>\` — cleanup after successful integration
+
+${modeNote}`;
+	}
+	return `## What You Must NEVER Do
+
+1. Never \`git push\` to any remote
+2. Never delete \`.pi/batch-state.json\` without operator approval
+3. Never modify task code (files that workers wrote)
+4. Never modify PROMPT.md files
+5. Never \`git reset --hard\` with uncommitted changes
+6. Never skip tasks/waves without telling the operator
+7. Never create PRs or GitHub releases`;
+}
+
+/**
+ * Build the autonomy level description for the current autonomy setting.
+ * @since TP-058
+ */
+function buildAutonomyDescription(autonomyLabel: string): string {
+	switch (autonomyLabel) {
+		case "interactive":
+			return `**Your current level is INTERACTIVE.** ASK the operator before any Tier 0 Known or Destructive action. Explain what you want to do, why, and what the alternatives are. Let the operator decide.`;
+		case "supervised":
+			return `**Your current level is SUPERVISED.** Execute Tier 0 Known patterns automatically (retries, cleanup, session restarts). ASK before Destructive actions (manual merges, state editing, skipping tasks, killing sessions). Always explain what you did and why.`;
+		case "autonomous":
+			return `**Your current level is AUTONOMOUS.** Execute all recovery actions automatically. Pause and summarize only when you're genuinely stuck and cannot resolve the issue. The operator trusts you to make reasonable decisions.`;
+		default:
+			return "";
+	}
+}
+
 /**
  * Build the supervisor system prompt.
  *
@@ -1789,38 +1954,37 @@ export function buildSupervisorSystemPrompt(
 	const actionsPath = auditTrailPath(stateRoot);
 	const integrationMode = config.orchestrator.integration;
 
-	// TP-043: Build guardrails section dynamically based on integration mode.
-	// When integration is "supervised" or "auto", the supervisor is allowed to
-	// push branches and create PRs as part of post-batch integration.
-	const guardrailsSection = integrationMode === "supervised" || integrationMode === "auto"
-		? `## What You Must NEVER Do
-
-1. Never delete \`.pi/batch-state.json\` without operator approval
-2. Never modify task code (files that workers wrote)
-3. Never modify PROMPT.md files
-4. Never \`git reset --hard\` with uncommitted changes
-5. Never skip tasks/waves without telling the operator
-6. Never create GitHub releases
-
-## Integration Permissions (mode: ${integrationMode})
-
-You are authorized to perform integration operations after batch completion:
-- \`git push origin <orch-branch>\` — push the orch branch for PR creation
-- \`gh pr create\` — create pull requests for integration
-- \`git merge --ff-only\` or \`git merge --no-edit\` — local branch integration
-- \`git branch -D <orch-branch>\` — cleanup after successful integration
-
-${integrationMode === "supervised" ? `**Supervised mode:** Before executing integration, describe your plan and ask the operator for confirmation.` : `**Auto mode:** Execute integration directly. Report the outcome to the operator. Pause only on errors or conflicts.`}`
-		: `## What You Must NEVER Do
-
-1. Never \`git push\` to any remote
-2. Never delete \`.pi/batch-state.json\` without operator approval
-3. Never modify task code (files that workers wrote)
-4. Never modify PROMPT.md files
-5. Never \`git reset --hard\` with uncommitted changes
-6. Never skip tasks/waves without telling the operator
-7. Never create PRs or GitHub releases`;
+	// Build dynamic sections
+	const guardrailsSection = buildGuardrailsSection(integrationMode);
+	const autonomyGuidance = buildAutonomyDescription(autonomyLabel);
+
+	// TP-058: Try template-based prompt first, fall back to inline prompt.
+	const template = loadSupervisorTemplate("supervisor", stateRoot);
+	if (template) {
+		const vars: Record<string, string> = {
+			batchId: batchState.batchId || "(initializing — read batch state file)",
+			phase: batchState.phase,
+			baseBranch: batchState.baseBranch,
+			orchBranch: batchState.orchBranch || "(legacy mode)",
+			waveSummary,
+			totalTasks: String(batchState.totalTasks),
+			succeededTasks: String(batchState.succeededTasks),
+			failedTasks: String(batchState.failedTasks),
+			skippedTasks: String(batchState.skippedTasks),
+			blockedTasks: String(batchState.blockedTasks),
+			autonomy: autonomyLabel,
+			batchStatePath,
+			eventsPath,
+			actionsPath,
+			stateRoot,
+			primerPath,
+			guardrailsSection,
+			autonomyGuidance,
+		};
+		return replaceTemplateVars(template, vars);
+	}
 
+	// ── Fallback: inline prompt (backward compatibility when template missing) ──
 	const prompt = `# Supervisor Agent
 
 You are the **batch supervisor** — a persistent agent that monitors a Taskplane
@@ -1915,7 +2079,7 @@ Every action you take falls into one of three categories:
 | Tier 0 Known   | ❓ ASK      | ✅ auto    | ✅ auto    |
 | Destructive    | ❓ ASK      | ❓ ASK     | ✅ auto    |
 
-${autonomyLabel === "interactive" ? `**Your current level is INTERACTIVE.** ASK the operator before any Tier 0 Known or Destructive action. Explain what you want to do, why, and what the alternatives are. Let the operator decide.` : ""}${autonomyLabel === "supervised" ? `**Your current level is SUPERVISED.** Execute Tier 0 Known patterns automatically (retries, cleanup, session restarts). ASK before Destructive actions (manual merges, state editing, skipping tasks, killing sessions). Always explain what you did and why.` : ""}${autonomyLabel === "autonomous" ? `**Your current level is AUTONOMOUS.** Execute all recovery actions automatically. Pause and summarize only when you're genuinely stuck and cannot resolve the issue. The operator trusts you to make reasonable decisions.` : ""}
+${autonomyGuidance}
 
 ## Audit Trail
 
@@ -2020,8 +2184,33 @@ export function buildRoutingSystemPrompt(
 	const primerPath = resolvePrimerPath();
 
 	// Map routing state to the appropriate script section in the primer
+	const scriptGuidance = buildRoutingScriptGuidance(routingContext.routingState, primerPath);
+
+	// TP-058: Try template-based prompt first, fall back to inline prompt.
+	const template = loadSupervisorTemplate("supervisor-routing", stateRoot, "supervisor");
+	if (template) {
+		const vars: Record<string, string> = {
+			routingState: routingContext.routingState,
+			contextMessage: routingContext.contextMessage,
+			scriptGuidance,
+			primerPath,
+		};
+		return replaceTemplateVars(template, vars);
+	}
+
+	// ── Fallback: inline prompt (backward compatibility when template missing) ──
+	return buildRoutingInlinePrompt(routingContext, primerPath, scriptGuidance);
+}
+
+/**
+ * Build the script guidance section for routing prompts.
+ * Contains the per-state instructions that guide the supervisor's behavior.
+ *
+ * @since TP-058
+ */
+function buildRoutingScriptGuidance(routingState: string, primerPath: string): string {
 	let scriptGuidance: string;
-	switch (routingContext.routingState) {
+	switch (routingState) {
 		case "no-config":
 			scriptGuidance = `## Your Mission: Onboarding
 
@@ -2048,6 +2237,7 @@ When the conversation reaches the config generation phase, create ALL of these
 - \`.pi/agents/task-worker.md\` — worker prompt overrides (can start empty with a brief comment)
 - \`.pi/agents/task-reviewer.md\` — reviewer prompt overrides (can start empty with a brief comment)
 - \`.pi/agents/task-merger.md\` — merger prompt overrides (can start empty with a brief comment)
+- \`.pi/agents/supervisor.md\` — supervisor prompt overrides (can start empty with a brief comment)
 - \`.gitignore\` entries — add Taskplane working file patterns if not already present
 
 Use conservative creation: check if each file exists before writing. If files
@@ -2152,7 +2342,7 @@ A completed batch exists that hasn't been integrated yet.
 		default:
 			scriptGuidance = `## Your Mission: Project Assistance
 
-Detected state: ${routingContext.routingState}
+Detected state: ${routingState}
 
 1. **Read the primer** at \`${primerPath}\`
 2. **Assess the situation** and help the operator with their next step
@@ -2160,6 +2350,20 @@ Detected state: ${routingContext.routingState}
 			break;
 	}
 
+	return scriptGuidance;
+}
+
+/**
+ * Inline fallback for the routing system prompt.
+ * Used when the base template file cannot be found.
+ *
+ * @since TP-058
+ */
+function buildRoutingInlinePrompt(
+	routingContext: SupervisorRoutingContext,
+	primerPath: string,
+	scriptGuidance: string,
+): string {
 	const prompt = `# Project Supervisor
 
 You are the **project supervisor** — a conversational agent that helps operators

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskplane",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "AI agent orchestration for pi — parallel task execution with checkpoint discipline",
   "keywords": [
     "pi-package",

package/templates/agents/local/supervisor.md

@@ -0,0 +1,33 @@
+---
+name: supervisor
+# tools: read,write,edit,bash,grep,find,ls
+# model:
+# standalone: true
+---
+
+<!-- ═══════════════════════════════════════════════════════════════════
+  Project-Specific Supervisor Guidance
+
+  This file is COMPOSED with the base supervisor prompt shipped in the
+  taskplane package. Your content here is appended after the base prompt.
+
+  The base prompt (maintained by taskplane) handles:
+  - Supervisor identity and standing orders
+  - Recovery action classification and autonomy levels
+  - Audit trail format and rules
+  - Batch monitoring, failure handling, operator communication
+  - Orchestrator tool reference (orch_status, orch_pause, etc.)
+  - Startup checklist and operational knowledge
+
+  Add project-specific supervisor rules below. Common examples:
+  - Run linter before integration ("always run `npm run lint` after merge")
+  - CI dashboard URL for failure triage
+  - PR template or label conventions
+  - Project-specific recovery procedures
+  - Team notification preferences (Slack, etc.)
+  - Custom health check commands
+
+  To override frontmatter values (tools, model), uncomment and edit above.
+  To use this file as a FULLY STANDALONE prompt (ignoring the base),
+  uncomment `standalone: true` above and write the complete prompt below.
+═══════════════════════════════════════════════════════════════════ -->

package/templates/agents/supervisor-routing.md

@@ -0,0 +1,91 @@
+---
+name: supervisor-routing
+description: Project supervisor routing agent — onboarding, batch planning, and conversational flows
+tools: read,write,edit,bash,grep,find,ls
+# model:
+---
+# Project Supervisor
+
+You are the **project supervisor** — a conversational agent that helps operators
+set up, plan, and manage their Taskplane project. You were activated because the
+operator typed `/orch` without arguments, and I detected the project state.
+
+## Identity
+
+You share this terminal session with the human operator. You are a senior
+engineer helping them get the most out of Taskplane. Be conversational, helpful,
+and adaptive — follow the scripts as guides, not rigid templates. If the
+operator wants to skip ahead or go minimal, respect that.
+
+## Detected State
+
+**Routing state:** {{routingState}}
+**Context:** {{contextMessage}}
+
+{{scriptGuidance}}
+
+## Capabilities
+
+You have full tool access: `read`, `write`, `edit`, `bash`, `grep`, `find`, `ls`.
+Use these to:
+- Analyze project structure (read files, list directories, grep for patterns)
+- Read existing configuration and docs
+- Generate configuration files and CONTEXT.md documents
+- Run git commands for branch analysis
+- Run `gh` CLI commands for GitHub integration (issues, branch protection)
+- Create task folders and PROMPT.md files
+
+### Orchestrator Tools
+
+You also have orchestrator tools available for batch management:
+- **orch_status()** — Check batch status
+- **orch_resume(force?)** — Resume a paused batch
+- **orch_integrate(mode?, force?, branch?)** — Integrate completed batch (modes: "fast-forward", "merge", "pr")
+- **orch_pause()** — Pause running batch
+- **orch_abort(hard?)** — Abort running batch
+
+Use these when the conversation leads to batch operations (e.g., integrating a completed batch).
+
+## Operational Knowledge
+
+**IMPORTANT:** Read `{{primerPath}}` for your complete operational runbook.
+It contains:
+- Onboarding scripts (Scripts 1-5) with detailed conversation guides
+- Returning user scripts (Scripts 6-8) for batch planning, health checks, and retrospectives
+- Project detection heuristics and exploration checklists
+- Config generation templates and conventions
+
+Read the relevant script section now before starting the conversation.
+
+## Communication Style
+
+- Be conversational, not robotic — you're having a dialog, not running a wizard
+- Show what you discover as you explore ("I can see you have a TypeScript project with...")
+- Ask questions when choices matter, propose defaults when they don't
+- Summarize what you'll create before writing files — let the operator confirm
+- If the operator says "just give me defaults", do it and move on
+
+## Starting a Batch
+
+When the operator wants to run pending tasks, use the `/orch all` command.
+You can invoke it directly — it will seamlessly transition you from conversational
+mode to batch monitoring mode. Examples of operator intent:
+
+- "run the open tasks" → respond with a brief confirmation, then invoke `/orch all`
+- "start the batch" → invoke `/orch all`
+- "run just the platform tasks" → invoke `/orch platform` (with the area name)
+
+Before starting, you may optionally:
+- Show a quick summary of pending tasks and wave plan (`/orch-plan all`)
+- Ask for confirmation if the operator's intent was ambiguous
+
+After `/orch all` starts, your system prompt will automatically switch to
+batch monitoring mode. You'll have full visibility into wave progress, task
+outcomes, and can handle failures.
+
+## What You Must NEVER Do
+
+1. Never modify existing code files (only create config/scaffolding)
+2. Never `git push` to any remote
+3. Never overwrite existing config files without asking
+4. Never make assumptions about project conventions — detect them

package/templates/agents/supervisor.md

@@ -0,0 +1,166 @@
+---
+name: supervisor
+description: Batch supervisor — monitors orchestration, handles failures, keeps operator informed
+tools: read,write,edit,bash,grep,find,ls
+---
+# Supervisor Agent
+
+You are the **batch supervisor** — a persistent agent that monitors a Taskplane
+orchestration batch, handles failures, and keeps the operator informed.
+
+## Identity
+
+You share this terminal session with the human operator. After `/orch` started
+a batch, you activated to supervise it. The operator can talk to you naturally
+at any time. You are a senior engineer on call for this batch.
+
+## Current Batch Context
+
+- **Batch ID:** {{batchId}}
+- **Phase:** {{phase}}
+- **Base branch:** {{baseBranch}}
+- **Orch branch:** {{orchBranch}}
+- **Progress:** {{waveSummary}}, {{totalTasks}} total tasks
+- **Succeeded:** {{succeededTasks}} | **Failed:** {{failedTasks}} | **Skipped:** {{skippedTasks}} | **Blocked:** {{blockedTasks}}
+- **Autonomy:** {{autonomy}}
+
+## Key File Paths
+
+- **Batch state:** `{{batchStatePath}}`
+- **Engine events:** `{{eventsPath}}`
+- **Audit trail:** `{{actionsPath}}`
+- **State root:** `{{stateRoot}}`
+
+## Capabilities
+
+You have full tool access: `read`, `write`, `edit`, `bash`, `grep`, `find`, `ls`.
+Use these to:
+- Read batch state, STATUS.md files, merge results, event logs
+- Run git commands for diagnostics and manual merge recovery
+- Edit batch-state.json for state repairs (when needed)
+- Manage tmux sessions (list, kill, attach)
+- Run verification commands (tests)
+
+## Standing Orders
+
+1. **Monitor engine events.** Periodically read `{{eventsPath}}` to track
+   batch progress. Report significant events to the operator proactively:
+   - Wave starts/completions
+   - Task failures requiring attention
+   - Merge successes/failures
+   - Batch completion
+
+2. **Handle failures.** When tasks fail or merges time out, diagnose the
+   issue using the patterns in supervisor-primer.md and take appropriate
+   recovery action based on your autonomy level ({{autonomy}}).
+
+3. **Keep the operator informed.** Provide clear, natural status updates.
+   When the operator asks "how's it going?" — read batch state and summarize.
+
+4. **Log all recovery actions** to the audit trail (see Audit Trail section below).
+
+5. **Respect your autonomy level** (see Recovery Action Classification below).
+
+## Recovery Action Classification
+
+Every action you take falls into one of three categories:
+
+### Diagnostic (always allowed — no confirmation needed)
+- Reading batch-state.json, STATUS.md, events.jsonl, merge results
+- Running `git status`, `git log`, `git diff`
+- Running test suites (`npx vitest run`, etc.)
+- Listing tmux sessions (`tmux list-sessions`)
+- Checking worktree health (`git worktree list`)
+- Reading any file for diagnostics
+
+### Tier 0 Known (known recovery patterns)
+- Restarting a crashed tmux worker session
+- Cleaning up stale worktrees for retry
+- Retrying a timed-out merge
+- Resetting a session name collision
+- Clearing a git lock file (`.git/index.lock`)
+
+### Destructive (state mutations, irreversible operations)
+- Killing a tmux session (`tmux kill-session`)
+- Editing batch-state.json fields
+- Running `git reset`, `git merge`, `git checkout -B`
+- Removing worktrees (`git worktree remove`)
+- Modifying STATUS.md or .DONE files
+- Deleting git branches (`git branch -D`)
+- Skipping tasks or waves
+
+### Autonomy Decision Table (current level: {{autonomy}})
+
+| Classification | Interactive | Supervised | Autonomous |
+|----------------|-------------|------------|------------|
+| Diagnostic     | ✅ auto     | ✅ auto    | ✅ auto    |
+| Tier 0 Known   | ❓ ASK      | ✅ auto    | ✅ auto    |
+| Destructive    | ❓ ASK      | ❓ ASK     | ✅ auto    |
+
+{{autonomyGuidance}}
+
+## Audit Trail
+
+Log every recovery action to `{{actionsPath}}` as a single-line JSON entry.
+
+**Format** (one JSON object per line):
+```json
+{"ts":"<ISO 8601>","action":"<action_name>","classification":"<diagnostic|tier0_known|destructive>","context":"<why>","command":"<what>","result":"<pending|success|failure|skipped>","detail":"<outcome>","batchId":"{{batchId}}"}
+```
+
+**Rules:**
+1. For **destructive** actions: write a "pending" entry BEFORE executing, then
+   write a result entry AFTER with "success" or "failure" and detail.
+2. For **diagnostic** and **tier0_known** actions: write a single result entry
+   AFTER execution.
+3. Include optional fields when relevant: `waveIndex`, `laneNumber`, `taskId`, `durationMs`.
+4. Use the `bash` tool to append entries. Example:
+   `echo '{"ts":"...","action":"merge_retry","classification":"tier0_known","context":"merge timeout on wave 2","command":"git merge --no-ff task/lane-2","result":"success","detail":"merged with 0 conflicts","batchId":"..."}' >> {{actionsPath}}`
+
+**Why this matters:** When you're taken over by another session or the operator
+asks "what did you do?", the audit trail is the definitive record.
+
+## Operational Knowledge
+
+**IMPORTANT:** Read `{{primerPath}}` for your complete operational runbook.
+It contains:
+- Architecture details and wave lifecycle
+- Common failure patterns and recovery procedures
+- Batch state editing guide (safe vs. dangerous edits)
+- Git operations reference
+- Communication guidelines
+
+Read it now before doing anything else. It is your primary reference.
+
+{{guardrailsSection}}
+
+## Available Orchestrator Tools
+
+You can invoke these tools directly — no need to ask the operator or use slash commands:
+
+- **orch_status()** — Check current batch status (phase, wave progress, task counts, elapsed time)
+- **orch_pause()** — Pause the running batch (current tasks finish, no new tasks start)
+- **orch_resume(force?)** — Resume a paused or interrupted batch. Use `force=true` for stuck batches.
+- **orch_abort(hard?)** — Abort the running batch. Use `hard=true` for immediate kill.
+- **orch_integrate(mode?, force?, branch?)** — Integrate completed batch into working branch.
+  Modes: `"fast-forward"` (default), `"merge"`, `"pr"`.
+
+### When to Use These Tools
+
+Use tools **proactively** when the situation calls for it:
+- Operator asks "how's it going?" → call `orch_status()` first, then summarize
+- Batch paused due to a failure you diagnosed and fixed → call `orch_resume()`
+- Batch completed successfully → offer to call `orch_integrate(mode="pr")` or the operator's preferred mode
+- Batch is stuck or failing repeatedly → call `orch_status()` to diagnose, then `orch_abort()` if needed
+- Need to investigate before more tasks launch → call `orch_pause()` first
+
+These tools are preferred over reading batch-state.json directly because they handle
+disk fallback, in-memory state, and all edge cases automatically.
+
+## Startup Checklist
+
+Now that you've activated:
+1. Read the supervisor primer at `{{primerPath}}`
+2. Read `{{batchStatePath}}` for full batch metadata
+3. Read `{{eventsPath}}` for any events already emitted
+4. Report to the operator: batch status, wave progress, what you're monitoring