feat: agent prompt inheritance — base prompts auto-update with package (#49)

Implements the 'inheritance by default' model from issue #18:
- Base agent prompts (task-worker, task-reviewer, task-merger) ship in the
  package at templates/agents/ and auto-update on pi update
- Local .pi/agents/ files are thin project-specific overrides
- loadAgentDef() composes: base prompt + separator + local content
- Local frontmatter (tools, model) overrides base values
- standalone: true in frontmatter opts out of inheritance entirely
- taskplane init now scaffolds thin local files with guidance comments
- Existing full-copy agent files continue to work (treated as standalone)

Closes #18

Author: HenryLach

bin/taskplane.mjs

@@ -645,10 +645,11 @@ async function cmdInit(args) {
 	console.log(`\n${c.bold}Creating files...${c.reset}\n`);
 	const skipIfExists = !force;
 
-	// Agent prompts
+	// 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"]) {
 		copyTemplate(
-			path.join(TEMPLATES_DIR, "agents", agent),
+			path.join(TEMPLATES_DIR, "agents", "local", agent),
 			path.join(projectRoot, ".pi", "agents", agent),
 			{ skipIfExists, label: `.pi/agents/${agent}` }
 		);

extensions/task-runner.ts

@@ -339,21 +339,141 @@ function clearConversationLog(prefix: string): void {
 
 // ── Agent Loader ─────────────────────────────────────────────────────
 
+/**
+ * Parse a markdown agent file into frontmatter key-value pairs and body content.
+ * Returns null if the file doesn't exist or has no frontmatter block.
+ */
+function parseAgentFile(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) fm[line.slice(0, idx).trim()] = line.slice(idx + 1).trim();
+	}
+	return { fm, body: match[2].trim() };
+}
+
+/** Cached package root — resolved once, reused for all agent file lookups. */
+let _packageRoot: string | null = null;
+
+/**
+ * Find the taskplane package root directory.
+ *
+ * Strategy: this file lives at <package-root>/extensions/task-runner.ts.
+ * When pi loads it via `-e`, it resolves the full path. We can find the
+ * package root by searching for package.json with name "taskplane"
+ * starting from known candidate locations.
+ */
+function findPackageRoot(): string {
+	if (_packageRoot !== null) return _packageRoot;
+
+	// Strategy 1: Walk up from this file's location via require.resolve or npm paths
+	const candidates: string[] = [];
+
+	// The extension is loaded by pi from the installed package location.
+	// Check well-known npm global paths.
+	const home = process.env.HOME || process.env.USERPROFILE || "";
+	if (home) {
+		candidates.push(join(home, "AppData", "Roaming", "npm", "node_modules", "taskplane"));
+		candidates.push(join(home, ".npm-global", "lib", "node_modules", "taskplane"));
+	}
+	candidates.push(join("/usr", "local", "lib", "node_modules", "taskplane"));
+
+	// Strategy 2: resolve from pi's node_modules peer
+	try {
+		const piPath = process.argv[1] || "";
+		const piPkgDir = resolve(piPath, "..", "..");
+		candidates.push(join(piPkgDir, "..", "taskplane"));
+	} catch { /* ignore */ }
+
+	// Strategy 3: Check TASKPLANE_WORKSPACE_ROOT project-local install
+	const wsRoot = process.env.TASKPLANE_WORKSPACE_ROOT;
+	if (wsRoot) {
+		candidates.push(join(wsRoot, ".pi", "npm", "node_modules", "taskplane"));
+		candidates.push(join(wsRoot, "node_modules", "taskplane"));
+	}
+
+	for (const dir of candidates) {
+		try {
+			const pkgPath = join(dir, "package.json");
+			if (existsSync(pkgPath)) {
+				const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+				if (pkg.name === "taskplane") {
+					_packageRoot = dir;
+					return dir;
+				}
+			}
+		} catch { /* ignore */ }
+	}
+
+	_packageRoot = "";
+	return "";
+}
+
+/**
+ * Resolve the package-shipped base agent file path.
+ * Base files live in the package's templates/agents/ directory.
+ */
+function resolveBaseAgentPath(name: string): string {
+	const root = findPackageRoot();
+	if (!root) return "";
+	return join(root, "templates", "agents", `${name}.md`);
+}
+
+/**
+ * Load an agent definition with prompt inheritance.
+ *
+ * Inheritance model (default: compose base + local):
+ * 1. Load base agent from the shipped package (templates/agents/{name}.md)
+ * 2. Load local agent from .pi/agents/{name}.md (if it exists)
+ * 3. If local file has `standalone: true` in frontmatter, use it as-is (no base)
+ * 4. Otherwise, compose: base prompt + separator + local content
+ * 5. Local frontmatter values (tools, model) override base values
+ *
+ * If no local file exists, the base file is used directly.
+ * If no base file exists (e.g., custom agent), local file is used as-is.
+ */
 function loadAgentDef(cwd: string, name: string): { systemPrompt: string; tools: string; model: string } | null {
-	const paths = [join(cwd, ".pi", "agents", `${name}.md`), join(cwd, "agents", `${name}.md`)];
-	for (const p of paths) {
-		if (!existsSync(p)) continue;
-		const raw = readFileSync(p, "utf-8").replace(/\r\n/g, "\n");
-		const match = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
-		if (!match) continue;
-		const fm: Record<string, string> = {};
-		for (const line of match[1].split("\n")) {
-			const idx = line.indexOf(":");
-			if (idx > 0) fm[line.slice(0, idx).trim()] = line.slice(idx + 1).trim();
-		}
-		return { systemPrompt: match[2].trim(), tools: fm.tools || "read,grep,find,ls", model: fm.model || "" };
+	const basePath = resolveBaseAgentPath(name);
+	const localPaths = [join(cwd, ".pi", "agents", `${name}.md`), join(cwd, "agents", `${name}.md`)];
+
+	// Load base from package
+	const baseDef = parseAgentFile(basePath);
+
+	// Load local override (first found wins)
+	let localDef: { fm: Record<string, string>; body: string } | null = null;
+	for (const p of localPaths) {
+		localDef = parseAgentFile(p);
+		if (localDef) break;
+	}
+
+	// No base and no local → null
+	if (!baseDef && !localDef) return null;
+
+	// Local with standalone: true → use local as-is, ignore base
+	if (localDef?.fm.standalone === "true") {
+		return {
+			systemPrompt: localDef.body,
+			tools: localDef.fm.tools || "read,grep,find,ls",
+			model: localDef.fm.model || "",
+		};
 	}
-	return null;
+
+	// Compose base + local
+	const basePrompt = baseDef?.body || "";
+	const localPrompt = localDef?.body || "";
+	const composedPrompt = localPrompt
+		? basePrompt + "\n\n---\n\n## Project-Specific Guidance\n\n" + localPrompt
+		: basePrompt;
+
+	// Local frontmatter overrides base (tools, model)
+	const tools = localDef?.fm.tools || baseDef?.fm.tools || "read,grep,find,ls";
+	const model = localDef?.fm.model || baseDef?.fm.model || "";
+
+	return { systemPrompt: composedPrompt.trim(), tools, model };
 }
 
 // ── PROMPT.md Parser ─────────────────────────────────────────────────

templates/agents/local/task-merger.md

@@ -0,0 +1,27 @@
+---
+name: task-merger
+# tools: read,write,edit,bash,grep,find,ls
+# model:
+# standalone: true
+---
+
+<!-- ═══════════════════════════════════════════════════════════════════
+  Project-Specific Merger Guidance
+
+  This file is COMPOSED with the base task-merger prompt shipped in the
+  taskplane package. Your content here is appended after the base prompt.
+
+  The base prompt (maintained by taskplane) handles:
+  - Branch merge workflow (fast-forward, 3-way, conflict resolution)
+  - Post-merge verification command execution
+  - Result file JSON format and writing conventions
+
+  Add project-specific merge rules below. Common examples:
+  - Post-merge verification commands (build, lint, test)
+  - Conflict resolution preferences
+  - Protected files that should never be auto-merged
+
+  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.
+═══════════════════════════════════════════════════════════════════ -->

templates/agents/local/task-reviewer.md

@@ -0,0 +1,29 @@
+---
+name: task-reviewer
+# tools: read,write,bash,grep,find,ls
+# model: openai/gpt-5.3-codex
+# standalone: true
+---
+
+<!-- ═══════════════════════════════════════════════════════════════════
+  Project-Specific Reviewer Guidance
+
+  This file is COMPOSED with the base task-reviewer prompt shipped in the
+  taskplane package. Your content here is appended after the base prompt.
+
+  The base prompt (maintained by taskplane) handles:
+  - Plan review and code review workflows
+  - Verdict format (APPROVE / REVISE)
+  - Review file output conventions
+  - Plan granularity guidance
+
+  Add project-specific review criteria below. Common examples:
+  - Required test coverage thresholds
+  - Security review checklist items
+  - Architecture constraints to enforce
+  - Performance requirements
+
+  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.
+═══════════════════════════════════════════════════════════════════ -->

templates/agents/local/task-worker.md

@@ -0,0 +1,30 @@
+---
+name: task-worker
+# tools: read,write,edit,bash,grep,find,ls
+# model: anthropic/claude-sonnet-4-20250514
+# standalone: true
+---
+
+<!-- ═══════════════════════════════════════════════════════════════════
+  Project-Specific Worker Guidance
+
+  This file is COMPOSED with the base task-worker prompt shipped in the
+  taskplane package. Your content here is appended after the base prompt.
+
+  The base prompt (maintained by taskplane) handles:
+  - STATUS.md-first workflow and checkpoint discipline
+  - Fresh-context loop behavior and iteration rules
+  - Git commit conventions and .DONE file creation
+  - Review response handling
+
+  Add project-specific rules below. Common examples:
+  - Preferred package manager (pnpm, yarn, bun)
+  - Test commands (make test, npm run test:unit)
+  - Coding standards (linting, formatting)
+  - Framework-specific patterns
+  - Environment or deployment constraints
+
+  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.
+═══════════════════════════════════════════════════════════════════ -->