taskplane 0.2.9 → 0.3.1

package/README.md

@@ -19,7 +19,24 @@ Taskplane turns your coding project into an AI-managed task board. You define ta
 
 ## Install
 
-Taskplane is a [pi package](https://github.com/badlogic/pi-mono). You need [Node.js](https://nodejs.org/) ≥ 20 and [pi](https://github.com/badlogic/pi-mono) installed first.
+Taskplane is a [pi package](https://github.com/badlogic/pi-mono). You need [Node.js](https://nodejs.org/) ≥ 22 and [pi](https://github.com/badlogic/pi-mono) installed first.
+
+### Prerequisites
+
+| Dependency | Required | Notes |
+|-----------|----------|-------|
+| [Node.js](https://nodejs.org/) ≥ 22 | Yes | Runtime |
+| [pi](https://github.com/badlogic/pi-mono) | Yes | Agent framework |
+| [Git](https://git-scm.com/) | Yes | Version control, worktrees |
+| **tmux** | **Strongly recommended** | Required for `/orch` parallel execution |
+
+**tmux** is needed for the orchestrator to spawn parallel worker sessions. Without it, `/orch` will not work. On Windows, Taskplane can install it for you:
+
+```bash
+taskplane install-tmux
+```
+
+On macOS: `brew install tmux` · On Linux: `sudo apt install tmux` (or your distro's package manager)
 
 ### Option A: Global Install (all projects)
 
@@ -138,6 +155,7 @@ Orchestrator lanes execute tasks through task-runner under the hood, so `/task`
 |---------|-------------|
 | `taskplane init` | Scaffold project config (interactive or `--preset`) |
 | `taskplane doctor` | Validate installation and config |
+| `taskplane install-tmux` | Install or upgrade tmux for Git Bash (Windows) |
 | `taskplane version` | Show version info |
 | `taskplane dashboard` | Launch the web dashboard |
 | `taskplane uninstall` | Remove Taskplane project files and optionally uninstall package (`--package`) |

package/bin/taskplane.mjs

@@ -10,6 +10,18 @@
  * and auto-discovered by pi. This CLI is for everything else.
  */
 
+// ─── Node.js version gate (fail fast) ───────────────────────────────────────
+
+const MIN_NODE_MAJOR = 22;
+const nodeMajor = parseInt(process.versions.node.split(".")[0], 10);
+if (nodeMajor < MIN_NODE_MAJOR) {
+	console.error(
+		`\x1b[31m❌ Taskplane requires Node.js >= ${MIN_NODE_MAJOR}.0.0 (found ${process.versions.node}).\x1b[0m\n` +
+		`   Upgrade: https://nodejs.org/\n`
+	);
+	process.exit(1);
+}
+
 import fs from "node:fs";
 import path from "node:path";
 import readline from "node:readline";
@@ -633,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}` }
 		);
@@ -1249,10 +1262,10 @@ function cmdDoctor() {
 	const checks = [
 		{ label: "pi installed", check: () => commandExists("pi"), detail: () => getVersion("pi") },
 		{
-			label: "Node.js >= 20.0.0",
+			label: "Node.js >= 22.0.0",
 			check: () => {
 				const v = process.versions.node;
-				return parseInt(v.split(".")[0]) >= 20;
+				return parseInt(v.split(".")[0]) >= 22;
 			},
 			detail: () => `v${process.versions.node}`,
 		},

package/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 ─────────────────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskplane",
-  "version": "0.2.9",
+  "version": "0.3.1",
   "description": "AI agent orchestration for pi — parallel task execution with checkpoint discipline",
   "keywords": [
     "pi-package",
@@ -24,7 +24,7 @@
   },
   "type": "module",
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.0.0"
   },
   "files": [
     "bin/",

package/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.
+═══════════════════════════════════════════════════════════════════ -->

package/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.
+═══════════════════════════════════════════════════════════════════ -->

package/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.
+═══════════════════════════════════════════════════════════════════ -->