taskplane 0.3.1 → 0.4.0

package/README.md

@@ -6,16 +6,24 @@ Multi-agent AI orchestration for [pi](https://github.com/badlogic/pi-mono) — p
 
 ## 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`.
+### STEP 1: Create the tasks
+Taskplane turns your coding project into an AI-managed task orchestration system. You simply ask your agent to create tasks using the built-in "create-taskplane-tasks" skill. This skill provides an opinionated task definition template designed to drive successful coding outcomes. Tasks define both the prompt.md and the status.md files that together act as the persistent memory store that allows AI coding agents to survive context resets and succeed with very long running tasks that would typically exhaust an agent's context window.
+
+### STEP 2: Run batches of tasks
+The system works out the dependancy map for the entire batch of tasks then orchestrates them in waves, with appropriate parallelization and serialization. 
+
+The taskplane dashboard runs on a local port on your system and gives you elegant visibility into everything that's going on (a stark improvement over TUI-based dashboards).
+
+<img src="docs/images/orchrun-wave2of4-2lanes-withstatus.png" alt="image of taskplane dashboard" width="50%">
 
 ### 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.
+- **Task Orchestrator** — Parallel multi-task execution using git worktrees for full filesystem isolation. Dependency-aware wave scheduling. Automated merges with conflict resolution.
+- **Task Runner** — What the Orchestrator uses for autonomous single-task execution. Worker agents run in fresh-context loops with STATUS.md as persistent memory. Every checkbox gets a git checkpoint. Cross-model reviewer agents catch what the worker agents missed.
 - **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.
+- **Cross-Model Review** — Reviewer agent uses a different model than the worker agent (highly recommended, not enforced). Independent quality gate before merge.
 
 ## Install
 
@@ -72,7 +80,7 @@ cd my-project
 taskplane init --preset full
 ```
 
-This creates config files in `.pi/`, agent prompts, and two example tasks.
+This creates config files in `.pi/`, agent prompts, two example tasks, and adds `.gitignore` entries for runtime artifacts. Init auto-detects whether you're in a single repo or a multi-repo workspace. See the [install tutorial](docs/tutorials/install.md) for workspace mode and other scenarios.
 
 Already have a task folder (for example `docs/task-management`)? Use:
 
@@ -148,6 +156,7 @@ Orchestrator lanes execute tasks through task-runner under the hood, so `/task`
 | `/orch-abort [--hard]` | Abort batch (graceful or immediate) |
 | `/orch-deps <areas\|paths\|all>` | Show dependency graph |
 | `/orch-sessions` | List active worker sessions |
+| `/settings` | View and edit taskplane configuration interactively |
 
 ### CLI Commands
 

package/bin/gitignore-patterns.mjs

@@ -0,0 +1,78 @@
+/**
+ * Taskplane gitignore patterns and matching utilities.
+ *
+ * Extracted as a separate module so that pattern-matching logic can be
+ * tested independently from the CLI entrypoint.
+ */
+
+// ─── Constants ──────────────────────────────────────────────────────────────
+
+export const TASKPLANE_GITIGNORE_HEADER = "# Taskplane runtime artifacts (machine-specific, do not commit)";
+export const TASKPLANE_GITIGNORE_NPM_HEADER = "# Pi project-local packages (if using pi install -l)";
+
+/**
+ * Required gitignore entries for Taskplane projects.
+ * These patterns cover runtime artifacts that are machine-specific and must
+ * not be committed to git. Reused by both repo mode (Step 2) and workspace
+ * mode (Step 4) init flows.
+ */
+export const TASKPLANE_GITIGNORE_ENTRIES = [
+	".pi/batch-state.json",
+	".pi/batch-history.json",
+	".pi/lane-state-*",
+	".pi/merge-result-*",
+	".pi/merge-request-*",
+	".pi/worker-conversation-*",
+	".pi/orch-logs/",
+	".pi/orch-abort-signal",
+	".pi/settings.json",
+	".worktrees/",
+];
+
+export const TASKPLANE_GITIGNORE_NPM_ENTRIES = [
+	".pi/npm/",
+];
+
+/**
+ * All patterns that should be gitignored, used for tracked-artifact detection.
+ */
+export const ALL_GITIGNORE_PATTERNS = [...TASKPLANE_GITIGNORE_ENTRIES, ...TASKPLANE_GITIGNORE_NPM_ENTRIES];
+
+// ─── Pattern Matching ───────────────────────────────────────────────────────
+
+/**
+ * Convert a gitignore-style pattern to a regex for matching tracked file paths.
+ *
+ * - Trailing-slash directory patterns (e.g., `.pi/orch-logs/`) are treated as
+ *   prefix matches so that files underneath are correctly detected.
+ * - Wildcard `*` patterns (e.g., `.pi/lane-state-*`) match any characters.
+ * - Exact patterns (e.g., `.pi/batch-state.json`) match exactly.
+ *
+ * @param {string} pattern - Gitignore-style pattern
+ * @returns {RegExp} Regex that matches file paths covered by the pattern
+ */
+export function patternToRegex(pattern) {
+	// Directory patterns (trailing slash) → prefix match
+	if (pattern.endsWith("/")) {
+		const dirPath = pattern.slice(0, -1);
+		const escaped = dirPath.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+		return new RegExp("^" + escaped + "/.*");
+	}
+	// Escape regex special chars except *
+	const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+	// Replace * with .*
+	const regexStr = "^" + escaped.replace(/\*/g, ".*") + "$";
+	return new RegExp(regexStr);
+}
+
+/**
+ * Check whether a tracked file path matches any of the gitignore patterns.
+ *
+ * @param {string} filePath - Relative file path from git root
+ * @param {string[]} [patterns] - Patterns to match against (defaults to ALL_GITIGNORE_PATTERNS)
+ * @returns {boolean} True if the file matches any pattern
+ */
+export function matchesAnyGitignorePattern(filePath, patterns = ALL_GITIGNORE_PATTERNS) {
+	const regexes = patterns.map(p => patternToRegex(p));
+	return regexes.some(regex => regex.test(filePath));
+}