taskplane 0.1.11 → 0.1.12

package/README.md

@@ -1,2 +1,180 @@
-# taskplane
-Multi-agent AI orchestration system designed to drive successful coding outcomes with a high level of transparency (think more light-factory than dark-factory).
+# Taskplane
+
+Multi-agent AI orchestration for [pi](https://github.com/badlogic/pi-mono) — parallel task execution with checkpoint discipline, fresh-context worker loops, cross-model reviews, and automated merges.
+
+> **Status:** Experimental / Early — APIs and config formats may change between releases.
+
+## What It Does
+
+Taskplane turns your coding project into an AI-managed task board. You define tasks as structured markdown files. Taskplane's agents execute them autonomously — one at a time with `/task`, or many in parallel with `/orch`.
+
+### Key Features
+
+- **Task Runner** (`/task`) — Autonomous single-task execution. Workers run in fresh-context loops with STATUS.md as persistent memory. Every checkbox gets a git checkpoint. Cross-model reviewers catch what the worker missed.
+- **Task Orchestrator** (`/orch`) — Parallel multi-task execution using git worktrees for full filesystem isolation. Dependency-aware wave scheduling. Automated merges with conflict resolution.
+- **Web Dashboard** — Live browser-based monitoring via `taskplane dashboard`. SSE streaming, lane/task progress, wave visualization, batch history.
+- **Structured Tasks** — PROMPT.md defines the mission, steps, and constraints. STATUS.md tracks progress. Agents follow the plan, not vibes.
+- **Checkpoint Discipline** — Every completed checkbox item triggers a git commit. Work is never lost, even if a worker crashes mid-task.
+- **Cross-Model Review** — Reviewer agent uses a different model than the worker. Independent quality gate before merge.
+
+## 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.
+
+### Option A: Global Install (all projects)
+
+```bash
+pi install npm:taskplane
+```
+
+### Option B: Project-Local Install (recommended for teams)
+
+```bash
+cd my-project
+pi install -l npm:taskplane
+```
+
+Then scaffold your project:
+
+```bash
+taskplane init
+```
+
+Verify the installation:
+
+```bash
+taskplane doctor
+```
+
+## Quickstart
+
+### 1. Initialize a project
+
+```bash
+cd my-project
+taskplane init --preset full
+```
+
+This creates config files in `.pi/`, agent prompts, and two example tasks.
+
+### 2. Launch the dashboard (recommended)
+
+In a separate terminal:
+
+```bash
+taskplane dashboard
+```
+
+Opens a live web dashboard at `http://localhost:8099` with real-time batch monitoring.
+
+### 3. Run your first orchestration
+
+```bash
+pi
+```
+
+Inside the pi session:
+
+```
+/orch-plan all     # Preview waves, lanes, and dependencies
+/orch all          # Execute all pending tasks in parallel
+/orch-status       # Monitor batch progress
+```
+
+The default scaffold includes two independent example tasks, so `/orch all` gives you an immediate orchestrator + dashboard experience.
+
+### 4. Optional: run one task directly
+
+`/task` is still useful for single-task execution and focused debugging:
+
+```
+/task taskplane-tasks/EXAMPLE-001-hello-world/PROMPT.md
+/task-status
+```
+
+Important distinction:
+
+- `/task` runs in your **current branch/worktree**.
+- `/orch` runs tasks in **isolated worktrees** and merges back.
+
+Because workers checkpoint with git commits, `/task` can capture unrelated local edits if you're changing files in parallel. For safer isolation (even with one task), prefer:
+
+```text
+/orch taskplane-tasks/EXAMPLE-001-hello-world/PROMPT.md
+```
+
+Orchestrator lanes execute tasks through task-runner under the hood, so `/task` and `/orch` share the same core task execution model.
+
+## Commands
+
+### Pi Session Commands
+
+| Command | Description |
+|---------|-------------|
+| `/task <path/to/PROMPT.md>` | Execute one task in the current branch/worktree |
+| `/task-status` | Show current task progress |
+| `/task-pause` | Pause after current worker iteration finishes |
+| `/task-resume` | Resume a paused task |
+| `/orch <areas\|paths\|all>` | Execute tasks via isolated worktrees (recommended default) |
+| `/orch-plan <areas\|paths\|all>` | Preview execution plan without running |
+| `/orch-status` | Show batch progress |
+| `/orch-pause` | Pause batch after current tasks finish |
+| `/orch-resume` | Resume a paused batch |
+| `/orch-abort [--hard]` | Abort batch (graceful or immediate) |
+| `/orch-deps <areas\|paths\|all>` | Show dependency graph |
+| `/orch-sessions` | List active worker sessions |
+
+### CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `taskplane init` | Scaffold project config (interactive or `--preset`) |
+| `taskplane doctor` | Validate installation and config |
+| `taskplane version` | Show version info |
+| `taskplane dashboard` | Launch the web dashboard |
+| `taskplane uninstall` | Remove Taskplane project files and optionally uninstall package (`--package`) |
+
+## How It Works
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    ORCHESTRATOR (/orch)                      │
+│  Parse tasks → Build dependency DAG → Compute waves         │
+│  Assign lanes → Spawn workers → Monitor → Merge             │
+└──────┬──────────┬──────────┬────────────────────────────────┘
+       │          │          │
+  ┌────▼────┐ ┌──▼─────┐ ┌──▼─────┐
+  │ Lane 1  │ │ Lane 2 │ │ Lane 3 │    ← Git worktrees
+  │ /task   │ │ /task  │ │ /task  │       (isolated)
+  │ Worker  │ │ Worker │ │ Worker │
+  │ Review  │ │ Review │ │ Review │
+  └────┬────┘ └──┬─────┘ └──┬─────┘
+       │         │          │
+       └─────────┼──────────┘
+                 │
+          ┌──────▼──────┐
+          │ Merge Agent │    ← Conflict resolution
+          │ Integration │      & verification
+          │   Branch    │
+          └─────────────┘
+```
+
+**Single task** (`/task`): Worker iterates in fresh-context loops. STATUS.md is persistent memory. Each checkbox → git checkpoint. Reviewer validates on completion.
+
+**Parallel batch** (`/orch`): Tasks are sorted into dependency waves. Each wave runs in parallel across lanes (git worktrees). Completed lanes merge into the integration branch before the next wave starts.
+
+## Documentation
+
+📖 **[Full Documentation](docs/README.md)**
+
+Start at the docs index for tutorials, how-to guides, reference docs, and architecture explanations.
+
+## Contributing
+
+See **[CONTRIBUTING.md](CONTRIBUTING.md)** for development setup, testing, and contribution guidelines.
+
+Maintainers: GitHub governance and branch protection guidance is in [docs/maintainers/repository-governance.md](docs/maintainers/repository-governance.md).
+
+## License
+
+[MIT](LICENSE) © Henry Lach

package/bin/taskplane.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 /**
- * Taskplane CLI — Project scaffolding, diagnostics, and dashboard launcher.
+ * Taskplane CLI — Project scaffolding, diagnostics, uninstall, and dashboard launcher.
  *
  * This CLI handles what the pi package system cannot: project-local config
  * scaffolding, installation health checks, and dashboard management.
@@ -291,6 +291,238 @@ async function autoCommitTaskFiles(projectRoot, tasksRoot) {
 	}
 }
 
+function discoverTaskAreaPaths(projectRoot) {
+	const runnerPath = path.join(projectRoot, ".pi", "task-runner.yaml");
+	if (!fs.existsSync(runnerPath)) return [];
+
+	const raw = readYaml(runnerPath);
+	if (!raw) return [];
+
+	const lines = raw.split(/\r?\n/);
+	let inTaskAreas = false;
+	const paths = new Set();
+
+	for (const line of lines) {
+		const trimmed = line.trim();
+
+		if (!inTaskAreas) {
+			if (/^task_areas:\s*$/.test(trimmed)) {
+				inTaskAreas = true;
+			}
+			continue;
+		}
+
+		// End of task_areas block when we hit next top-level key
+		if (/^[A-Za-z0-9_]+\s*:\s*$/.test(line)) {
+			break;
+		}
+
+		const m = line.match(/^\s{4}path:\s*["']?([^"'\n#]+)["']?\s*(?:#.*)?$/);
+		if (m?.[1]) {
+			paths.add(m[1].trim());
+		}
+	}
+
+	return [...paths];
+}
+
+function pruneEmptyDir(dirPath) {
+	try {
+		if (!fs.existsSync(dirPath)) return false;
+		if (fs.readdirSync(dirPath).length !== 0) return false;
+		fs.rmdirSync(dirPath);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function listExampleTaskTemplates() {
+	const tasksTemplatesDir = path.join(TEMPLATES_DIR, "tasks");
+	try {
+		return fs.readdirSync(tasksTemplatesDir, { withFileTypes: true })
+			.filter((entry) => entry.isDirectory() && /^EXAMPLE-\d+/i.test(entry.name))
+			.map((entry) => entry.name)
+			.sort();
+	} catch {
+		return [];
+	}
+}
+
+async function cmdUninstall(args) {
+	const projectRoot = process.cwd();
+	const dryRun = args.includes("--dry-run");
+	const yes = args.includes("--yes") || args.includes("-y");
+	const removePackage = args.includes("--package") || args.includes("--all") || args.includes("--package-only");
+	const packageOnly = args.includes("--package-only");
+	const removeProject = !packageOnly;
+	const removeTasks = removeProject && (args.includes("--remove-tasks") || args.includes("--all"));
+	const local = args.includes("--local");
+	const global = args.includes("--global");
+
+	if (local && global) {
+		die("Choose either --local or --global, not both.");
+	}
+
+	console.log(`\n${c.bold}Taskplane Uninstall${c.reset}\n`);
+
+	const managedFiles = [
+		".pi/task-runner.yaml",
+		".pi/task-orchestrator.yaml",
+		".pi/taskplane.json",
+		".pi/agents/task-worker.md",
+		".pi/agents/task-reviewer.md",
+		".pi/agents/task-merger.md",
+		".pi/batch-state.json",
+		".pi/batch-history.json",
+		".pi/orch-abort-signal",
+	];
+
+	const sidecarPrefixes = [
+		"lane-state-",
+		"worker-conversation-",
+		"merge-result-",
+		"merge-request-",
+	];
+
+	const filesToDelete = managedFiles
+		.map(rel => ({ rel, abs: path.join(projectRoot, rel) }))
+		.filter(({ abs }) => fs.existsSync(abs));
+
+	const piDir = path.join(projectRoot, ".pi");
+	const sidecarsToDelete = fs.existsSync(piDir)
+		? fs.readdirSync(piDir)
+			.filter(name => sidecarPrefixes.some(prefix => name.startsWith(prefix)))
+			.map(name => ({ rel: path.join(".pi", name), abs: path.join(piDir, name) }))
+		: [];
+
+	let taskDirsToDelete = [];
+	if (removeTasks) {
+		const areaPaths = discoverTaskAreaPaths(projectRoot);
+		const rootPrefix = path.resolve(projectRoot) + path.sep;
+		taskDirsToDelete = areaPaths
+			.map(rel => ({ rel, abs: path.resolve(projectRoot, rel) }))
+			.filter(({ abs }) => abs.startsWith(rootPrefix) && fs.existsSync(abs));
+	}
+
+	const inferredInstallType = /[\\/]\.pi[\\/]/.test(PACKAGE_ROOT) ? "local" : "global";
+	const packageScope = local ? "local" : global ? "global" : inferredInstallType;
+	const piRemoveCmd = packageScope === "local"
+		? "pi remove -l npm:taskplane"
+		: "pi remove npm:taskplane";
+
+	if (!removeProject && !removePackage) {
+		console.log(`  ${WARN} Nothing to do. Use one of:`);
+		console.log(`    ${c.cyan}taskplane uninstall${c.reset}              # remove project-scaffolded files`);
+		console.log(`    ${c.cyan}taskplane uninstall --package${c.reset}    # remove installed package via pi`);
+		console.log();
+		return;
+	}
+
+	if (removeProject) {
+		console.log(`${c.bold}Project cleanup:${c.reset}`);
+		if (filesToDelete.length === 0 && sidecarsToDelete.length === 0 && taskDirsToDelete.length === 0) {
+			console.log(`  ${c.dim}No Taskplane-managed project files found.${c.reset}`);
+		}
+		for (const f of filesToDelete) console.log(`  - remove ${f.rel}`);
+		for (const f of sidecarsToDelete) console.log(`  - remove ${f.rel}`);
+		for (const d of taskDirsToDelete) console.log(`  - remove dir ${d.rel}`);
+		if (removeTasks && taskDirsToDelete.length === 0) {
+			console.log(`  ${c.dim}No task area directories found from .pi/task-runner.yaml.${c.reset}`);
+		}
+		if (!removeTasks) {
+			console.log(`  ${c.dim}Task directories are preserved by default (use --remove-tasks to delete them).${c.reset}`);
+		}
+		console.log();
+	}
+
+	if (removePackage) {
+		console.log(`${c.bold}Package cleanup:${c.reset}`);
+		console.log(`  - run ${piRemoveCmd}`);
+		console.log(`  ${c.dim}(removes extensions, skills, and dashboard files from this install scope)${c.reset}`);
+		console.log();
+	}
+
+	if (dryRun) {
+		console.log(`${INFO} Dry run complete. No files were changed.\n`);
+		return;
+	}
+
+	if (!yes) {
+		const proceed = await confirm("Proceed with uninstall?", false);
+		if (!proceed) {
+			console.log("  Aborted.");
+			return;
+		}
+		if (removeTasks) {
+			const taskConfirm = await confirm("This will delete task area directories recursively. Continue?", false);
+			if (!taskConfirm) {
+				console.log("  Aborted.");
+				return;
+			}
+		}
+	}
+
+	let removedCount = 0;
+	let failedCount = 0;
+
+	if (removeProject) {
+		for (const item of [...filesToDelete, ...sidecarsToDelete]) {
+			try {
+				fs.unlinkSync(item.abs);
+				removedCount++;
+			} catch (err) {
+				failedCount++;
+				console.log(`  ${WARN} Failed to remove ${item.rel}: ${err.message}`);
+			}
+		}
+
+		for (const dir of taskDirsToDelete) {
+			try {
+				fs.rmSync(dir.abs, { recursive: true, force: true });
+				removedCount++;
+			} catch (err) {
+				failedCount++;
+				console.log(`  ${WARN} Failed to remove directory ${dir.rel}: ${err.message}`);
+			}
+		}
+
+		// Best-effort cleanup of empty folders
+		pruneEmptyDir(path.join(projectRoot, ".pi", "agents"));
+		pruneEmptyDir(path.join(projectRoot, ".pi"));
+	}
+
+	if (removePackage) {
+		if (!commandExists("pi")) {
+			failedCount++;
+			console.log(`  ${FAIL} pi is not on PATH; could not run: ${piRemoveCmd}`);
+		} else {
+			try {
+				execSync(piRemoveCmd, { cwd: projectRoot, stdio: "inherit" });
+			} catch {
+				failedCount++;
+				console.log(`  ${FAIL} Package uninstall failed: ${piRemoveCmd}`);
+			}
+		}
+	}
+
+	console.log();
+	if (failedCount === 0) {
+		console.log(`${OK} ${c.bold}Uninstall complete.${c.reset}`);
+		if (removeProject) {
+			console.log(`  Removed ${removedCount} project artifact(s).`);
+		}
+		console.log();
+	} else {
+		console.log(`${FAIL} Uninstall completed with ${failedCount} error(s).`);
+		if (removeProject) {
+			console.log(`  Removed ${removedCount} project artifact(s).`);
+		}
+		console.log();
+		process.exit(1);
+	}
+}
+
 // ─── init ───────────────────────────────────────────────────────────────────
 
 async function cmdInit(args) {
@@ -326,9 +558,11 @@ async function cmdInit(args) {
 		vars = await getInteractiveVars(projectRoot);
 	}
 
+	const exampleTemplateDirs = noExamples ? [] : listExampleTaskTemplates();
+
 	if (dryRun) {
 		console.log(`\n${c.bold}Dry run — files that would be created:${c.reset}\n`);
-		printFileList(vars, noExamples, preset);
+		printFileList(vars, noExamples, preset, exampleTemplateDirs);
 		return;
 	}
 
@@ -382,37 +616,41 @@ async function cmdInit(args) {
 		{ skipIfExists, label: `${vars.tasks_root}/CONTEXT.md` }
 	);
 
-	// Example task
+	// Example tasks
 	if (!noExamples) {
-		const exampleDir = path.join(TEMPLATES_DIR, "tasks", "EXAMPLE-001-hello-world");
-		const destDir = path.join(projectRoot, vars.tasks_root, "EXAMPLE-001-hello-world");
-		for (const file of ["PROMPT.md", "STATUS.md"]) {
-			const src = fs.readFileSync(path.join(exampleDir, file), "utf-8");
-			writeFile(path.join(destDir, file), interpolate(src, vars), {
-				skipIfExists,
-				label: `${vars.tasks_root}/EXAMPLE-001-hello-world/${file}`,
-			});
+		for (const exampleName of exampleTemplateDirs) {
+			const exampleDir = path.join(TEMPLATES_DIR, "tasks", exampleName);
+			const destDir = path.join(projectRoot, vars.tasks_root, exampleName);
+			for (const file of ["PROMPT.md", "STATUS.md"]) {
+				const srcPath = path.join(exampleDir, file);
+				if (!fs.existsSync(srcPath)) continue;
+				const src = fs.readFileSync(srcPath, "utf-8");
+				writeFile(path.join(destDir, file), interpolate(src, vars), {
+					skipIfExists,
+					label: `${vars.tasks_root}/${exampleName}/${file}`,
+				});
+			}
+		}
+		if (exampleTemplateDirs.length === 0) {
+			console.log(`  ${WARN} No example task templates found under templates/tasks/EXAMPLE-*`);
 		}
 	}
 
 	// Auto-commit task files to git so they're available in worktrees
-	if (!dryRun) {
-		await autoCommitTaskFiles(projectRoot, vars.tasks_root);
-	}
+	await autoCommitTaskFiles(projectRoot, vars.tasks_root);
 
 	// Report
 	console.log(`\n${OK} ${c.bold}Taskplane initialized!${c.reset}\n`);
 	console.log(`${c.bold}Quick start:${c.reset}`);
 	console.log(`  ${c.cyan}pi${c.reset}                                             # start pi (taskplane auto-loads)`);
-	if (!noExamples) {
-		console.log(
-			`  ${c.cyan}/task ${vars.tasks_root}/EXAMPLE-001-hello-world/PROMPT.md${c.reset}  # run the example task`
-		);
-	}
 	if (preset !== "runner-only") {
-		console.log(
-			`  ${c.cyan}/orch all${c.reset}                                         # orchestrate all pending tasks`
-		);
+		console.log(`  ${c.cyan}/orch-plan all${c.reset}                                   # preview waves/lanes/dependencies`);
+		console.log(`  ${c.cyan}/orch all${c.reset}                                        # run examples via orchestrator`);
+	}
+	if (!noExamples && exampleTemplateDirs.length > 0) {
+		const firstExample = exampleTemplateDirs[0];
+		console.log(`  ${c.dim}optional single-task mode:${c.reset}`);
+		console.log(`  ${c.cyan}/task ${vars.tasks_root}/${firstExample}/PROMPT.md${c.reset}`);
 	}
 	console.log();
 }
@@ -465,7 +703,7 @@ async function getInteractiveVars(projectRoot) {
 	};
 }
 
-function printFileList(vars, noExamples, preset) {
+function printFileList(vars, noExamples, preset, exampleTemplateDirs = []) {
 	const files = [
 		".pi/agents/task-worker.md",
 		".pi/agents/task-reviewer.md",
@@ -476,8 +714,10 @@ function printFileList(vars, noExamples, preset) {
 	files.push(".pi/taskplane.json");
 	files.push(`${vars.tasks_root}/CONTEXT.md`);
 	if (!noExamples) {
-		files.push(`${vars.tasks_root}/EXAMPLE-001-hello-world/PROMPT.md`);
-		files.push(`${vars.tasks_root}/EXAMPLE-001-hello-world/STATUS.md`);
+		for (const exampleName of exampleTemplateDirs) {
+			files.push(`${vars.tasks_root}/${exampleName}/PROMPT.md`);
+			files.push(`${vars.tasks_root}/${exampleName}/STATUS.md`);
+		}
 	}
 	for (const f of files) console.log(`  ${c.green}create${c.reset} ${f}`);
 	console.log();
@@ -690,11 +930,12 @@ ${c.bold}Commands:${c.reset}
   ${c.cyan}doctor${c.reset}      Validate installation and project configuration
   ${c.cyan}version${c.reset}     Show version information
   ${c.cyan}dashboard${c.reset}   Launch the web-based orchestrator dashboard
+  ${c.cyan}uninstall${c.reset}   Remove Taskplane project files and/or package install
   ${c.cyan}help${c.reset}        Show this help message
 
 ${c.bold}Init options:${c.reset}
   --preset <name>   Use a preset: minimal, full, runner-only
-  --no-examples     Skip example task scaffolding
+  --no-examples     Skip example tasks scaffolding
   --force           Overwrite existing files without prompting
   --dry-run         Show what would be created without writing
 
@@ -702,13 +943,25 @@ ${c.bold}Dashboard options:${c.reset}
   --port <number>   Port to listen on (default: 8099)
   --no-open         Don't auto-open browser
 
+${c.bold}Uninstall options:${c.reset}
+  --dry-run         Show what would be removed
+  --yes, -y         Skip confirmation prompts
+  --package         Also remove installed package via pi remove
+  --package-only    Only remove installed package (skip project cleanup)
+  --local           Force package uninstall from project-local scope
+  --global          Force package uninstall from global scope
+  --remove-tasks    Also remove task area directories from task-runner.yaml
+  --all             Equivalent to --package + --remove-tasks
+
 ${c.bold}Examples:${c.reset}
-  taskplane init                    # Interactive project setup
-  taskplane init --preset full      # Quick setup with defaults
-  taskplane init --dry-run          # Preview what would be created
-  taskplane doctor                  # Check installation health
-  taskplane dashboard               # Launch web dashboard
-  taskplane dashboard --port 3000   # Dashboard on custom port
+  taskplane init                        # Interactive project setup
+  taskplane init --preset full          # Quick setup with defaults
+  taskplane init --dry-run              # Preview what would be created
+  taskplane doctor                      # Check installation health
+  taskplane dashboard                   # Launch web dashboard
+  taskplane dashboard --port 3000       # Dashboard on custom port
+  taskplane uninstall --dry-run         # Preview uninstall actions
+  taskplane uninstall --package --yes   # Remove project files + package install
 
 ${c.bold}Getting started:${c.reset}
   1. pi install npm:taskplane       # Install the pi package
@@ -738,6 +991,9 @@ switch (command) {
 	case "dashboard":
 		cmdDashboard(args);
 		break;
+	case "uninstall":
+		await cmdUninstall(args);
+		break;
 	case "help":
 	case "--help":
 	case "-h":

package/package.json

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

package/templates/agents/task-merger.md

@@ -73,8 +73,8 @@ Use the source branch and merge message from the merge request.
 Run each verification command from the merge request. Typical commands:
 
 ```bash
-go build ./...                     # All services compile
-cd web && npm run type-check       # Frontend types valid
+npm test                           # Unit/integration checks
+npm run build                      # Build/compile checks
 ```
 
 **If verification passes:** Write result with `status: "SUCCESS"` (or
@@ -95,29 +95,29 @@ Write a `BUILD_FAILURE` result with the error output from the failed command.
 | Different files modified | N/A (git handles automatically) | No action needed |
 | Same file, different sections | Yes — accept both changes | Edit file to include both changes, remove conflict markers |
 | Same file, same lines | **No** — needs human review | Abort merge immediately |
-| Generated files (`go.sum`, `package-lock.json`) | Yes — regenerate | Run `go mod tidy` / `npm install` to regenerate |
-| `STATUS.md` / `.DONE` files | Yes — keep both | Accept the incoming (theirs) version for STATUS.md; keep both .DONE files |
-| `CONTEXT.md` (append-only sections) | Yes — keep both additions | Merge both additions into the relevant sections |
+| Generated files (`package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`) | Yes — regenerate | Run package manager install command to regenerate |
+| `STATUS.md` / `.DONE` files | Yes — keep both | Accept incoming STATUS.md; keep `.DONE` markers |
+| `CONTEXT.md` (append-only sections) | Yes — keep both additions | Merge both additions into relevant sections |
 
 ### Auto-Resolution Rules
 
 1. **Same file, different sections:** Open the file, identify conflict markers
    (`<<<<<<<`, `=======`, `>>>>>>>`). If the conflicting hunks are in clearly
-   different sections (different functions, different list items, different
-   paragraphs), keep both changes. Remove all conflict markers.
+   different sections, keep both changes and remove markers.
 
-2. **Generated files:** Do NOT manually edit. Instead:
-   - `go.sum` → Run `go mod tidy` in the affected module directory
-   - `package-lock.json` → Run `npm install` in the affected package directory
-   - Then `git add` the regenerated file
+2. **Generated files:** Do NOT manually edit. Regenerate lockfiles using your
+   project's package manager command (for example `npm install`,
+   `pnpm install`, or `yarn install`), then `git add` the regenerated file.
 
-3. **STATUS.md:** These are per-task tracking files. Accept theirs (`git checkout --theirs STATUS.md && git add STATUS.md`). Each task has its own STATUS.md so there is no meaningful merge — the incoming version is always more current.
+3. **STATUS.md:** These are per-task tracking files. Accept theirs:
+   ```bash
+   git checkout --theirs STATUS.md && git add STATUS.md
+   ```
 
-4. **`.DONE` marker files:** These are empty sentinel files. If both sides created one, keep it (`git add .DONE`).
+4. **`.DONE` marker files:** Keep marker files if either side created one.
 
 5. **Same lines / ambiguous conflicts:** Do NOT attempt to resolve. Run
-   `git merge --abort` and report `CONFLICT_UNRESOLVED`. The orchestrator will
-   pause the batch for human intervention.
+   `git merge --abort` and report `CONFLICT_UNRESOLVED`.
 
 ---
 
@@ -130,7 +130,7 @@ Write your result as JSON to the path specified in the merge request
 {
   "status": "SUCCESS",
   "source_branch": "task/lane-1-abc123",
-  "target_branch": "develop",
+  "target_branch": "main",
   "merge_commit": "abc1234def5678",
   "conflicts": [],
   "verification": {
@@ -147,42 +147,25 @@ Write your result as JSON to the path specified in the merge request
 |-------|------|-------------|
 | `status` | string | One of: `SUCCESS`, `CONFLICT_RESOLVED`, `CONFLICT_UNRESOLVED`, `BUILD_FAILURE` |
 | `source_branch` | string | The lane branch that was merged (from merge request) |
-| `target_branch` | string | The target branch (from merge request, typically `develop`) |
-| `merge_commit` | string | The merge commit SHA (only present if merge succeeded) |
+| `target_branch` | string | Target branch from merge request (typically integration branch, e.g. `main`) |
+| `merge_commit` | string | Merge commit SHA (present only if merge succeeded) |
 | `conflicts` | array | List of conflict entries (empty if no conflicts) |
-| `conflicts[].file` | string | Path to the conflicted file |
-| `conflicts[].type` | string | Classification: `different-sections`, `same-lines`, `generated`, `status-file` |
-| `conflicts[].resolved` | boolean | Whether the conflict was auto-resolved |
-| `conflicts[].resolution` | string | How it was resolved (e.g., `"kept both changes"`, `"regenerated"`, `"accepted theirs"`) |
+| `conflicts[].file` | string | Path to conflicted file |
+| `conflicts[].type` | string | Classification (`different-sections`, `same-lines`, `generated`, `status-file`) |
+| `conflicts[].resolved` | boolean | Whether conflict was auto-resolved |
+| `conflicts[].resolution` | string | Resolution summary |
 | `verification.ran` | boolean | Whether verification commands were executed |
-| `verification.passed` | boolean | Whether all verification commands passed |
-| `verification.output` | string | Command output (populated only on failure, truncated to 2000 chars) |
+| `verification.passed` | boolean | Whether verification commands passed |
+| `verification.output` | string | Verification output (useful on failures) |
 
 ### Status Definitions
 
 | Status | Meaning | Orchestrator Action |
 |--------|---------|---------------------|
-| `SUCCESS` | Merge completed, no conflicts, verification passed | Continue to next lane |
-| `CONFLICT_RESOLVED` | Conflicts occurred but were auto-resolved, verification passed | Log details, continue |
-| `CONFLICT_UNRESOLVED` | Conflicts that require human intervention | Pause batch, notify user |
-| `BUILD_FAILURE` | Merge succeeded but verification failed (merge was reverted) | Pause batch, notify user |
-
-### Example: Clean Merge
-
-```json
-{
-  "status": "SUCCESS",
-  "source_branch": "task/lane-1-abc123",
-  "target_branch": "develop",
-  "merge_commit": "abc1234def5678",
-  "conflicts": [],
-  "verification": {
-    "ran": true,
-    "passed": true,
-    "output": ""
-  }
-}
-```
+| `SUCCESS` | Merge completed, verification passed | Continue to next lane |
+| `CONFLICT_RESOLVED` | Conflicts auto-resolved, verification passed | Log details, continue |
+| `CONFLICT_UNRESOLVED` | Conflict requires human intervention | Pause batch, notify user |
+| `BUILD_FAILURE` | Merge succeeded but verification failed (merge reverted) | Pause batch, notify user |
 
 ### Example: Conflict Resolved
 
@@ -190,20 +173,20 @@ Write your result as JSON to the path specified in the merge request
 {
   "status": "CONFLICT_RESOLVED",
   "source_branch": "task/lane-2-abc123",
-  "target_branch": "develop",
+  "target_branch": "main",
   "merge_commit": "def4567abc8901",
   "conflicts": [
     {
-      "file": "go.sum",
+      "file": "package-lock.json",
       "type": "generated",
       "resolved": true,
-      "resolution": "regenerated via go mod tidy"
+      "resolution": "regenerated via npm install"
     },
     {
-      "file": "services/time-service/internal/interfaces/http/routes/routes.go",
+      "file": "src/routes/api.ts",
       "type": "different-sections",
       "resolved": true,
-      "resolution": "kept both changes — different route groups"
+      "resolution": "kept both route additions"
     }
   ],
   "verification": {
@@ -214,43 +197,19 @@ Write your result as JSON to the path specified in the merge request
 }
 ```
 
-### Example: Unresolved Conflict
-
-```json
-{
-  "status": "CONFLICT_UNRESOLVED",
-  "source_branch": "task/lane-3-abc123",
-  "target_branch": "develop",
-  "merge_commit": "",
-  "conflicts": [
-    {
-      "file": "services/identity-service/internal/domain/services/auth_service.go",
-      "type": "same-lines",
-      "resolved": false,
-      "resolution": ""
-    }
-  ],
-  "verification": {
-    "ran": false,
-    "passed": false,
-    "output": ""
-  }
-}
-```
-
 ### Example: Build Failure
 
 ```json
 {
   "status": "BUILD_FAILURE",
   "source_branch": "task/lane-1-abc123",
-  "target_branch": "develop",
+  "target_branch": "main",
   "merge_commit": "",
   "conflicts": [],
   "verification": {
     "ran": true,
     "passed": false,
-    "output": "services/time-service/internal/domain/services/pto_service.go:142:35: undefined: NewAccrualEngine"
+    "output": "src/server.ts:42:17 - error TS2304: Cannot find name 'createApiRouter'"
   }
 }
 ```

package/templates/config/task-orchestrator.yaml

@@ -19,10 +19,10 @@ orchestrator:
   max_lanes: 3
 
   # Where to create worktree directories.
-  # "sibling"       = ../{prefix}-{N}          (e.g. ../taskplane-wt-1)
-  # "subdirectory"  = .worktrees/{prefix}-{N}  (e.g. .worktrees/taskplane-wt-1)
+  # "sibling"       = ../{prefix}-{N}          (e.g. ../project-wt-1)
+  # "subdirectory"  = .worktrees/{prefix}-{N}  (e.g. .worktrees/project-wt-1)
   worktree_location: "subdirectory"
-  worktree_prefix: "taskplane-wt"
+  worktree_prefix: "project-wt"
 
   # Integration branch that lanes merge into.
   integration_branch: "main"

package/templates/config/task-runner.yaml

@@ -10,8 +10,8 @@
 # ── Project ───────────────────────────────────────────────────────────
 
 project:
-  name: "Example Project"
-  description: "Replace with a short description of your project"
+  name: "Your Project"
+  description: "Short description of your project"
 
 paths:
   tasks: "tasks"

package/templates/tasks/EXAMPLE-001-hello-world/PROMPT.md

@@ -21,9 +21,17 @@
 ## Mission
 
 Create a simple `hello-taskplane.md` file in the project root to verify that
-the Taskplane task runner is working correctly. This is a smoke test — if the
-worker can read this prompt, create the file, and mark the task done, the
-installation is healthy.
+Taskplane task execution is working correctly. This is a smoke test — if the
+worker can read this prompt, create the file, checkpoint progress, and mark the
+task done, the installation is healthy.
+
+## Expected File Content
+
+`hello-taskplane.md` should include:
+
+- A title line (for example: `# Hello from Taskplane`)
+- A line containing the task ID: `EXAMPLE-001`
+- A line containing today's date
 
 ## Dependencies
 
@@ -51,12 +59,12 @@ _No additional context needed._
 
 ### Step 1: Create Hello File
 
-- [ ] Create `hello-taskplane.md` in the project root with a friendly message
-- [ ] Include the current date and the task ID (EXAMPLE-001)
+- [ ] Create `hello-taskplane.md` in the project root
+- [ ] Add a title plus lines containing today's date and task ID `EXAMPLE-001`
 
 ### Step 2: Verification
 
-- [ ] Verify `hello-taskplane.md` exists and contains the expected content
+- [ ] Verify `hello-taskplane.md` exists and matches the expected content
 
 ### Step 3: Delivery
 
@@ -70,6 +78,7 @@ _No additional context needed._
 ## Completion Criteria
 
 - [ ] `hello-taskplane.md` exists in the project root
+- [ ] `hello-taskplane.md` includes a title, task ID (`EXAMPLE-001`), and current date
 - [ ] `.DONE` exists in the task folder
 
 ## Git Commit Convention

package/templates/tasks/EXAMPLE-001-hello-world/STATUS.md

@@ -22,14 +22,14 @@
 **Status:** ⬜ Not Started
 
 - [ ] Create `hello-taskplane.md` in project root
-- [ ] Include date and task ID
+- [ ] Add title, date, and task ID (EXAMPLE-001)
 
 ---
 
 ### Step 2: Verification
 **Status:** ⬜ Not Started
 
-- [ ] Verify file exists with expected content
+- [ ] Verify file exists and matches expected content
 
 ---
 

package/templates/tasks/EXAMPLE-002-parallel-smoke/PROMPT.md

@@ -0,0 +1,98 @@
+# Task: EXAMPLE-002 — Parallel Smoke
+
+**Created:** {{date}}
+**Size:** S
+
+## Review Level: 0 (None)
+
+**Assessment:** Trivial parallel-safe smoke task to demonstrate orchestrator lanes.
+**Score:** 0/8 — Blast radius: 0, Pattern novelty: 0, Security: 0, Reversibility: 0
+
+## Canonical Task Folder
+
+```
+{{tasks_root}}/EXAMPLE-002-parallel-smoke/
+├── PROMPT.md   ← This file (immutable above --- divider)
+├── STATUS.md   ← Execution state (worker updates this)
+├── .reviews/   ← Reviewer output (task-runner creates this)
+└── .DONE       ← Created when complete
+```
+
+## Mission
+
+Create a simple `hello-taskplane-2.md` file in the project root. This task is
+intentionally independent from EXAMPLE-001 so both can run in parallel when
+using `/orch`.
+
+## Expected File Content
+
+`hello-taskplane-2.md` should include:
+
+- A title line (for example: `# Parallel Hello from Taskplane`)
+- A line containing the task ID: `EXAMPLE-002`
+- A short note that this task is parallel-safe
+
+## Dependencies
+
+- **None**
+
+## Context to Read First
+
+_No additional context needed._
+
+## Environment
+
+- **Workspace:** Project root
+- **Services required:** None
+
+## File Scope
+
+- `hello-taskplane-2.md`
+
+## Steps
+
+### Step 0: Preflight
+
+- [ ] Verify this PROMPT.md is readable
+- [ ] Verify STATUS.md exists in the same folder
+
+### Step 1: Create Parallel Hello File
+
+- [ ] Create `hello-taskplane-2.md` in the project root
+- [ ] Add title plus lines containing task ID `EXAMPLE-002` and a parallel-safe note
+
+### Step 2: Verification
+
+- [ ] Verify `hello-taskplane-2.md` exists and matches the expected content
+
+### Step 3: Delivery
+
+- [ ] `.DONE` created in this folder
+
+## Documentation Requirements
+
+**Must Update:** None
+**Check If Affected:** None
+
+## Completion Criteria
+
+- [ ] `hello-taskplane-2.md` exists in the project root
+- [ ] `hello-taskplane-2.md` includes a title, task ID (`EXAMPLE-002`), and a parallel-safe note
+- [ ] `.DONE` exists in the task folder
+
+## Git Commit Convention
+
+- **Implementation:** `feat(EXAMPLE-002): description`
+- **Checkpoints:** `checkpoint: EXAMPLE-002 description`
+
+## Do NOT
+
+- Modify any existing project files
+- Create files outside the project root
+- Add dependencies between EXAMPLE-001 and EXAMPLE-002
+
+---
+
+## Amendments (Added During Execution)
+
+<!-- Workers add amendments here if issues discovered during execution. -->

package/templates/tasks/EXAMPLE-002-parallel-smoke/STATUS.md

@@ -0,0 +1,73 @@
+# EXAMPLE-002: Parallel Smoke — Status
+
+**Current Step:** Not Started
+**Status:** 🔵 Ready for Execution
+**Last Updated:** {{date}}
+**Review Level:** 0
+**Review Counter:** 0
+**Iteration:** 0
+**Size:** S
+
+---
+
+### Step 0: Preflight
+**Status:** ⬜ Not Started
+
+- [ ] Verify PROMPT.md is readable
+- [ ] Verify STATUS.md exists
+
+---
+
+### Step 1: Create Parallel Hello File
+**Status:** ⬜ Not Started
+
+- [ ] Create `hello-taskplane-2.md` in project root
+- [ ] Add title, task ID (EXAMPLE-002), and parallel-safe note
+
+---
+
+### Step 2: Verification
+**Status:** ⬜ Not Started
+
+- [ ] Verify file exists and matches expected content
+
+---
+
+### Step 3: Delivery
+**Status:** ⬜ Not Started
+
+- [ ] `.DONE` created
+
+---
+
+## Reviews
+
+| # | Type | Step | Verdict | File |
+|---|------|------|---------|------|
+
+---
+
+## Discoveries
+
+| Discovery | Disposition | Location |
+|-----------|-------------|----------|
+
+---
+
+## Execution Log
+
+| Timestamp | Action | Outcome |
+|-----------|--------|---------|
+| {{date}} | Task staged | PROMPT.md and STATUS.md created |
+
+---
+
+## Blockers
+
+*None*
+
+---
+
+## Notes
+
+*This is an example task created by `taskplane init` to demonstrate orchestrator-first onboarding.*