pi-todo 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mrg2400xx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,117 @@
+# pi-todo
+
+Persistent per-project todo tracker with a live TUI widget for [Pi](https://github.com/nicobailon/pi-coding-agent).
+
+## What It Does
+
+- Registers a `todo` tool the LLM can call to manage a task list
+- Stores tasks in `.pi/todo.json` in the project root (per-project, persistent)
+- Shows a **live widget** above the editor with the current todo state
+- Auto-loads existing todos on session start
+
+## Installation
+
+Add the extension path to `~/.pi/agent/settings.json`:
+
+```json
+{
+  "extensions": ["~/.pi/agent/extensions/todo/src/index.ts"]
+}
+```
+
+Or if you already have extensions:
+
+```json
+{
+  "extensions": ["~/.pi/agent/extensions/todo/src/index.ts", "other/extension/path"]
+}
+```
+
+Then restart Pi (or run `/reload`).
+
+## Tool: `todo`
+
+### Actions
+
+| Action | Required Fields | Description |
+|--------|----------------|-------------|
+| `add` | `text` | Create a new todo item |
+| `update` | `id` | Modify an item's text/status/priority/assignee/blockedBy |
+| `toggle` | `id` | Cycle status: pending → in-progress → done → pending |
+| `remove` | `id` | Delete an item |
+| `list` | — | List all items (optional: `filter`) |
+| `clear` | — | Remove all completed items |
+| `reorder` | `id`, `direction` | Move an item up or down in the list |
+
+### Parameters
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `action` | `string` | yes | One of: add, update, toggle, remove, list, clear, reorder |
+| `id` | `string` | conditional | Task ID (e.g. T-001) |
+| `text` | `string` | conditional | Task description |
+| `status` | `string` | no | pending, in-progress, done, blocked |
+| `priority` | `string` | no | low, medium, high, critical (default: medium) |
+| `assignee` | `string` | no | Who's doing it |
+| `filter` | `string` | no | Filter for list: all, pending, in-progress, done, blocked |
+| `blockedBy` | `string` | no | Task ID this is blocked by |
+| `direction` | `string` | no | Reorder direction: up or down |
+
+### Examples
+
+```
+todo({ action: "add", text: "Build StorefrontController", priority: "high", assignee: "Ultron" })
+todo({ action: "toggle", id: "T-001" })
+todo({ action: "list", filter: "pending" })
+todo({ action: "reorder", id: "T-003", direction: "up" })
+todo({ action: "clear" })
+```
+
+## Slash Commands
+
+- `/todo` — List all todo items
+- `/todo clear` — Clear completed items
+
+## Storage
+
+Tasks are stored in `.pi/todo.json` in the project root:
+
+```json
+{
+  "items": [
+    {
+      "id": "T-001",
+      "text": "Build StorefrontController",
+      "status": "in-progress",
+      "priority": "high",
+      "assignee": "Ultron",
+      "createdAt": "2026-07-05T19:02:00Z",
+      "updatedAt": "2026-07-05T19:02:00Z",
+      "blockedBy": null
+    }
+  ],
+  "counter": 1
+}
+```
+
+## Widget
+
+The live widget appears above the editor and shows:
+
+```
+📋 TODO · 3 tasks
+  2 pending · 1 active
+  ⚪ T-001 [HIGH] Build StorefrontController · Ultron
+  ⚪ T-002 [MED]  Port landing.html · Maya
+  🔵 T-003 [LOW]  Verify storefront routes · Quinn
+```
+
+Status icons: ⚪ pending, 🔵 in-progress, ✅ done, 🔴 blocked
+
+## Design Decisions
+
+- **Per-project, not global** — Each project has its own todo list
+- **Main agent only** — Subagents cannot call the todo tool
+- **Auto-generated IDs** — T-001, T-002, T-003...
+- **Synchronous file I/O** — Avoids race conditions (Node single-threaded)
+- **No external dependencies** — Uses only Pi's built-in typebox

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "pi-todo",
+  "version": "1.0.0",
+  "description": "Persistent per-project todo tracker with live TUI widget for Pi",
+  "author": "mrg2400xx",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mrg2400xx/pi-todo.git"
+  },
+  "homepage": "https://github.com/mrg2400xx/pi-todo#readme",
+  "bugs": {
+    "url": "https://github.com/mrg2400xx/pi-todo/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "todo",
+    "task-tracker",
+    "productivity"
+  ],
+  "files": [
+    "src/**/*.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "dependencies": {
+    "typebox": "^1.1.24"
+  }
+}

package/src/index.ts

@@ -0,0 +1,346 @@
+/**
+ * pi-todo — Persistent per-project todo tracker with live TUI widget
+ *
+ * Registers a `todo` tool the LLM can call to manage a task list stored in
+ * `.pi/todo.json` in the project root. A live widget above the editor shows
+ * the current state at all times.
+ */
+
+import * as fs from "node:fs";
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import { type ExtensionAPI, type ExtensionContext, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Text, type Component } from "@earendil-works/pi-tui";
+import { TodoParams } from "./schemas.ts";
+import {
+	addItem,
+	clearCompleted,
+	listItems,
+	readStore,
+	removeItem,
+	reorderItem,
+	toggleItem,
+	updateItem,
+	type TodoItem,
+	type TodoPriority,
+	type TodoStatus,
+} from "./store.ts";
+import { createWidgetComponent, renderTodoResult } from "./render.ts";
+
+const WIDGET_KEY = "todo";
+
+/** Update the live widget from the current store state */
+function refreshWidget(pi: ExtensionAPI, cwd: string): void {
+	// We need a UI context — grab it from the last known context
+	// The widget is set via ctx.ui, but we can also use pi's event system
+	// For now, we store the last context and use it here
+	const ctx = lastCtx;
+	if (!ctx || !ctx.hasUI) return;
+	const store = readStore(cwd);
+	if (store.items.length === 0) {
+		ctx.ui.setWidget(WIDGET_KEY, undefined);
+		return;
+	}
+	ctx.ui.setWidget(WIDGET_KEY, createWidgetComponent(store.items));
+}
+
+// Track the last known UI context for widget updates
+let lastCtx: ExtensionContext | null = null;
+
+interface TodoDetails {
+	action: string;
+	items: TodoItem[];
+	item?: TodoItem;
+	removed?: number;
+	moved?: boolean;
+	error?: string;
+}
+
+export default function registerTodoExtension(pi: ExtensionAPI): void {
+	const tool: ToolDefinition<typeof TodoParams, TodoDetails> = {
+		name: "todo",
+		label: "Todo",
+		description: `Manage a persistent per-project todo list stored in .pi/todo.json. The list survives across sessions and is shown as a live widget above the editor.
+
+Actions:
+- add: Create a new todo item (requires text, optional: priority, assignee, blockedBy)
+- update: Modify an existing item by ID (requires id, optional: text, status, priority, assignee, blockedBy)
+- toggle: Cycle status pending → in-progress → done → pending (requires id)
+- remove: Delete an item by ID (requires id)
+- list: List all items, optionally filtered by status (optional: filter)
+- clear: Remove all completed items
+- reorder: Move an item up or down in the list (requires id, direction)
+
+Only the main agent can modify the todo list. Subagents cannot call this tool.`,
+		parameters: TodoParams,
+		promptSnippet: "Manage a persistent todo list with add, update, toggle, remove, list, clear, and reorder actions.",
+		promptGuidelines: [
+			"Use the todo tool to track multi-step tasks — add items before starting work, toggle to in-progress when beginning, toggle to done when complete.",
+			"Always set the assignee field to the agent doing the work (e.g. Ultron, Marcus, Quinn, Maya).",
+			"Use blockedBy to mark tasks that can't start until another task is done.",
+		],
+
+		async execute(toolCallId, params, _signal, _onUpdate, ctx): Promise<AgentToolResult<TodoDetails>> {
+			lastCtx = ctx;
+			const cwd = ctx.cwd;
+			const width = process.stdout.columns || 120;
+
+			try {
+				switch (params.action) {
+					case "add": {
+						if (!params.text) {
+							return {
+								content: [{ type: "text", text: "Error: 'text' is required for add action." }],
+								isError: true,
+								details: { action: "add", items: [], error: "text is required" },
+							};
+						}
+						const item = addItem(
+							cwd,
+							params.text,
+							params.priority as TodoPriority | undefined,
+							params.assignee,
+							params.blockedBy,
+						);
+						refreshWidget(pi, cwd);
+						const all = listItems(cwd);
+						return {
+							content: [{ type: "text", text: `Added: ${item.id} — ${item.text}` }],
+							details: { action: "add", items: all, item },
+						};
+					}
+
+					case "update": {
+						if (!params.id) {
+							return {
+								content: [{ type: "text", text: "Error: 'id' is required for update action." }],
+								isError: true,
+								details: { action: "update", items: [], error: "id is required" },
+							};
+						}
+						const updated = updateItem(cwd, params.id, {
+							text: params.text,
+							status: params.status as TodoStatus | undefined,
+							priority: params.priority as TodoPriority | undefined,
+							assignee: params.assignee,
+							blockedBy: params.blockedBy,
+						});
+						if (!updated) {
+							return {
+								content: [{ type: "text", text: `Error: Item ${params.id} not found.` }],
+								isError: true,
+								details: { action: "update", items: [], error: "item not found" },
+							};
+						}
+						refreshWidget(pi, cwd);
+						const all = listItems(cwd);
+						return {
+							content: [{ type: "text", text: `Updated: ${updated.id} — ${updated.text} [${updated.status}]` }],
+							details: { action: "update", items: all, item: updated },
+						};
+					}
+
+					case "toggle": {
+						if (!params.id) {
+							return {
+								content: [{ type: "text", text: "Error: 'id' is required for toggle action." }],
+								isError: true,
+								details: { action: "toggle", items: [], error: "id is required" },
+							};
+						}
+						const toggled = toggleItem(cwd, params.id);
+						if (!toggled) {
+							return {
+								content: [{ type: "text", text: `Error: Item ${params.id} not found.` }],
+								isError: true,
+								details: { action: "toggle", items: [], error: "item not found" },
+							};
+						}
+						refreshWidget(pi, cwd);
+						const all = listItems(cwd);
+						return {
+							content: [{ type: "text", text: `Toggled: ${toggled.id} — ${toggled.text} → ${toggled.status}` }],
+							details: { action: "toggle", items: all, item: toggled },
+						};
+					}
+
+					case "remove": {
+						if (!params.id) {
+							return {
+								content: [{ type: "text", text: "Error: 'id' is required for remove action." }],
+								isError: true,
+								details: { action: "remove", items: [], error: "id is required" },
+							};
+						}
+						const removed = removeItem(cwd, params.id);
+						if (!removed) {
+							return {
+								content: [{ type: "text", text: `Error: Item ${params.id} not found.` }],
+								isError: true,
+								details: { action: "remove", items: [], error: "item not found" },
+							};
+						}
+						refreshWidget(pi, cwd);
+						const all = listItems(cwd);
+						return {
+							content: [{ type: "text", text: `Removed: ${params.id}` }],
+							details: { action: "remove", items: all },
+						};
+					}
+
+					case "list": {
+						const items = listItems(cwd, params.filter);
+						return {
+							content: [{ type: "text", text: formatListText(items) }],
+							details: { action: "list", items },
+						};
+					}
+
+					case "clear": {
+						const count = clearCompleted(cwd);
+						refreshWidget(pi, cwd);
+						const all = listItems(cwd);
+						return {
+							content: [{ type: "text", text: `Cleared ${count} completed item${count === 1 ? "" : "s"}.` }],
+							details: { action: "clear", items: all, removed: count },
+						};
+					}
+
+					case "reorder": {
+						if (!params.id) {
+							return {
+								content: [{ type: "text", text: "Error: 'id' is required for reorder action." }],
+								isError: true,
+								details: { action: "reorder", items: [], error: "id is required" },
+							};
+						}
+						if (!params.direction) {
+							return {
+								content: [{ type: "text", text: "Error: 'direction' is required for reorder action." }],
+								isError: true,
+								details: { action: "reorder", items: [], error: "direction is required" },
+							};
+						}
+						const moved = reorderItem(cwd, params.id, params.direction);
+						if (!moved) {
+							return {
+								content: [{ type: "text", text: `Error: Could not reorder ${params.id} (not found or already at ${params.direction === "up" ? "top" : "bottom"}).` }],
+								isError: true,
+								details: { action: "reorder", items: [], error: "cannot reorder" },
+							};
+						}
+						refreshWidget(pi, cwd);
+						const all = listItems(cwd);
+						return {
+							content: [{ type: "text", text: `Reordered: ${params.id} ${params.direction}` }],
+							details: { action: "reorder", items: all, moved: true },
+						};
+					}
+
+					default:
+						return {
+							content: [{ type: "text", text: `Error: Unknown action '${params.action}'.` }],
+							isError: true,
+							details: { action: String(params.action), items: [], error: "unknown action" },
+						};
+				}
+			} catch (error) {
+				const msg = error instanceof Error ? error.message : String(error);
+				return {
+					content: [{ type: "text", text: `Error: ${msg}` }],
+					isError: true,
+					details: { action: String(params.action), items: [], error: msg },
+				};
+			}
+		},
+
+		renderCall(args, theme) {
+			const action = args.action || "?";
+			if (action === "list") {
+				return new Text(`${theme.fg("toolTitle", theme.bold("todo "))}list${args.filter ? ` ${theme.fg("dim", args.filter)}` : ""}`, 0, 0);
+			}
+			if (action === "add" && args.text) {
+				const preview = args.text.length > 50 ? `${args.text.slice(0, 49)}…` : args.text;
+				return new Text(`${theme.fg("toolTitle", theme.bold("todo "))}add ${theme.fg("accent", `"${preview}"`)}`, 0, 0);
+			}
+			const target = args.id || "";
+			return new Text(`${theme.fg("toolTitle", theme.bold("todo "))}${action}${target ? ` ${theme.fg("accent", target)}` : ""}`, 0, 0);
+		},
+
+		renderResult(result, options, theme, _context) {
+			const details = result.details as TodoDetails | undefined;
+			if (!details) {
+				const text = typeof result.content === "string"
+					? result.content
+					: result.content.map((c) => (c.type === "text" ? c.text : "")).join("");
+				return new Text(text, 0, 0);
+			}
+			if (result.isError) {
+				const text = typeof result.content === "string"
+					? result.content
+					: result.content.map((c) => (c.type === "text" ? c.text : "")).join("");
+				return new Text(theme.fg("error", text), 0, 0);
+			}
+			const width = process.stdout.columns || 120;
+			return renderTodoResult(details.items, theme, width);
+		},
+	};
+
+	pi.registerTool(tool);
+
+	// Slash command: /todo
+	pi.registerCommand("todo", {
+		description: "List all todo items, or clear completed items with '/todo clear'",
+		async handler(args, ctx) {
+			lastCtx = ctx;
+			const cwd = ctx.cwd;
+			const arg = args.trim();
+
+			if (arg === "clear") {
+				const count = clearCompleted(cwd);
+				refreshWidget(pi, cwd);
+				ctx.ui.notify(`Cleared ${count} completed item${count === 1 ? "" : "s"}.`, "info");
+				return;
+			}
+
+			const items = listItems(cwd);
+			if (items.length === 0) {
+				ctx.ui.notify("No todo items.", "info");
+				return;
+			}
+			ctx.ui.notify(formatListText(items), "info");
+		},
+	});
+
+	// Session start: load existing todos and render widget
+	pi.on("session_start", (_event, ctx) => {
+		lastCtx = ctx;
+		const cwd = ctx.cwd;
+		const todoPath = `${cwd}/.pi/todo.json`;
+		if (!fs.existsSync(todoPath)) return;
+		const store = readStore(cwd);
+		if (store.items.length === 0) return;
+		if (ctx.hasUI) {
+			ctx.ui.setWidget(WIDGET_KEY, createWidgetComponent(store.items));
+		}
+	});
+
+	// Session shutdown: clear widget
+	pi.on("session_shutdown", (_event, ctx) => {
+		if (ctx.hasUI) {
+			ctx.ui.setWidget(WIDGET_KEY, undefined);
+		}
+	});
+}
+
+/** Format items as a plain text list for slash command output */
+function formatListText(items: TodoItem[]): string {
+	if (items.length === 0) return "No todo items.";
+	const lines: string[] = [];
+	for (const item of items) {
+		const icon = item.status === "done" ? "✅" : item.status === "in-progress" ? "🔵" : item.status === "blocked" ? "🔴" : "⚪";
+		const assignee = item.assignee ? ` · ${item.assignee}` : "";
+		const blocked = item.blockedBy ? ` (blocked by ${item.blockedBy})` : "";
+		lines.push(`${icon} ${item.id} [${item.priority.toUpperCase()}] ${item.text}${assignee}${blocked}`);
+	}
+	return lines.join("\n");
+}

package/src/render.ts

@@ -0,0 +1,121 @@
+/**
+ * TUI rendering for the todo extension — widget and tool result components
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Container, Text, type Component } from "@earendil-works/pi-tui";
+import type { TodoItem, TodoStatus, TodoPriority } from "./store.ts";
+
+type Theme = ExtensionContext["ui"]["theme"];
+
+const STATUS_ICON: Record<TodoStatus, string> = {
+	pending: "⚪",
+	"in-progress": "🔵",
+	done: "✅",
+	blocked: "🔴",
+};
+
+const PRIORITY_LABEL: Record<TodoPriority, string> = {
+	low: "LOW",
+	medium: "MED",
+	high: "HIGH",
+	critical: "CRIT",
+};
+
+const PRIORITY_COLOR: Record<TodoPriority, string> = {
+	low: "dim",
+	medium: "dim",
+	high: "warning",
+	critical: "error",
+};
+
+/** Truncate text to fit within maxWidth (visible characters) */
+function truncate(text: string, maxWidth: number): string {
+	if (text.length <= maxWidth) return text;
+	return text.slice(0, maxWidth - 1) + "…";
+}
+
+/** Build the widget content lines for the todo list */
+export function buildWidgetLines(items: TodoItem[], theme: Theme, width: number): string[] {
+	if (items.length === 0) return [];
+
+	const lines: string[] = [];
+	const header = `${theme.fg("accent", theme.bold("📋 TODO"))} ${theme.fg("dim", `· ${items.length} task${items.length === 1 ? "" : "s"}`)}`;
+	lines.push(truncate(header, width));
+
+	const pending = items.filter((i) => i.status === "pending").length;
+	const inProgress = items.filter((i) => i.status === "in-progress").length;
+	const done = items.filter((i) => i.status === "done").length;
+	const blocked = items.filter((i) => i.status === "blocked").length;
+
+	const parts: string[] = [];
+	if (pending > 0) parts.push(`${pending} pending`);
+	if (inProgress > 0) parts.push(`${inProgress} active`);
+	if (blocked > 0) parts.push(`${blocked} blocked`);
+	if (done > 0) parts.push(`${done} done`);
+	if (parts.length > 0) {
+		lines.push(truncate(`  ${theme.fg("dim", parts.join(" · "))}`, width));
+	}
+
+	const maxItems = Math.min(items.length, 8);
+	for (let i = 0; i < maxItems; i++) {
+		const item = items[i]!;
+		const icon = STATUS_ICON[item.status];
+		const priColor = PRIORITY_COLOR[item.priority] ?? "dim";
+		const priLabel = PRIORITY_LABEL[item.priority] ?? "MED";
+		const assignee = item.assignee ? ` ${theme.fg("dim", `· ${item.assignee}`)}` : "";
+		const blocked = item.blockedBy ? ` ${theme.fg("error", `(blocked by ${item.blockedBy})`)}` : "";
+		const text = truncate(item.text, width - 20);
+		lines.push(
+			truncate(`  ${icon} ${theme.fg(priColor, `[${priLabel}]`)} ${text}${assignee}${blocked}`, width),
+		);
+	}
+
+	if (items.length > maxItems) {
+		lines.push(truncate(`  ${theme.fg("dim", `… and ${items.length - maxItems} more`)}`, width));
+	}
+
+	return lines;
+}
+
+/** Create the widget component factory for setWidget() */
+export function createWidgetComponent(items: TodoItem[]): (tui: unknown, theme: Theme) => Component {
+	return (_tui: unknown, theme: Theme) => {
+		const width = process.stdout.columns || 120;
+		const lines = buildWidgetLines(items, theme, width);
+		const container = new Container();
+		for (const line of lines) {
+			container.addChild(new Text(line, 1, 0));
+		}
+		return container;
+	};
+}
+
+/** Render the tool result as a text summary */
+export function renderTodoResult(items: TodoItem[], theme: Theme, width: number): Component {
+	const container = new Container();
+	container.addChild(new Text("", 0, 0));
+
+	if (items.length === 0) {
+		container.addChild(new Text(theme.fg("dim", "  No todo items found."), 0, 0));
+		return container;
+	}
+
+	for (const item of items) {
+		const icon = STATUS_ICON[item.status];
+		const priColor = PRIORITY_COLOR[item.priority] ?? "dim";
+		const priLabel = PRIORITY_LABEL[item.priority] ?? "MED";
+		const assignee = item.assignee ? ` · ${item.assignee}` : "";
+		const blocked = item.blockedBy ? ` (blocked by ${item.blockedBy})` : "";
+		const text = truncate(item.text, width - 25);
+		container.addChild(
+			new Text(
+				`  ${icon} ${theme.bold(item.id)} ${theme.fg(priColor, `[${priLabel}]`)} ${text}${theme.fg("dim", assignee)}${blocked ? theme.fg("error", blocked) : ""}`,
+				0,
+				0,
+			),
+		);
+	}
+
+	return container;
+}

package/src/schemas.ts

@@ -0,0 +1,47 @@
+/**
+ * TypeBox parameter schema for the todo tool
+ */
+
+import { Type } from "typebox";
+
+const StatusEnum = Type.Unsafe({
+	type: "string",
+	enum: ["pending", "in-progress", "done", "blocked"],
+	description: "Task status: pending, in-progress, done, or blocked",
+});
+
+const PriorityEnum = Type.Unsafe({
+	type: "string",
+	enum: ["low", "medium", "high", "critical"],
+	description: "Task priority: low, medium, high, or critical",
+});
+
+const ActionEnum = Type.Unsafe({
+	type: "string",
+	enum: ["add", "update", "toggle", "remove", "list", "clear", "reorder"],
+	description: "Action to perform on the todo list",
+});
+
+const FilterEnum = Type.Unsafe({
+	type: "string",
+	enum: ["all", "pending", "in-progress", "done", "blocked"],
+	description: "Filter for list action: all, pending, in-progress, done, or blocked",
+});
+
+const DirectionEnum = Type.Unsafe({
+	type: "string",
+	enum: ["up", "down"],
+	description: "Reorder direction: up (earlier) or down (later)",
+});
+
+export const TodoParams = Type.Object({
+	action: ActionEnum,
+	id: Type.Optional(Type.String({ description: "Task ID (e.g. T-001). Required for update, toggle, remove, reorder." })),
+	text: Type.Optional(Type.String({ description: "Task description text. Required for add, optional for update." })),
+	status: Type.Optional(StatusEnum),
+	priority: Type.Optional(PriorityEnum),
+	assignee: Type.Optional(Type.String({ description: "Who is assigned to this task (e.g. Ultron, Marcus, Quinn)" })),
+	filter: Type.Optional(FilterEnum),
+	blockedBy: Type.Optional(Type.String({ description: "Task ID this item is blocked by (null to clear)" })),
+	direction: Type.Optional(DirectionEnum),
+});

package/src/store.ts

@@ -0,0 +1,163 @@
+/**
+ * File-based todo store — reads and writes .pi/todo.json in the project root.
+ * All operations are synchronous to avoid race conditions (Node single-threaded).
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export type TodoStatus = "pending" | "in-progress" | "done" | "blocked";
+export type TodoPriority = "low" | "medium" | "high" | "critical";
+
+export interface TodoItem {
+	id: string;
+	text: string;
+	status: TodoStatus;
+	priority: TodoPriority;
+	assignee: string | null;
+	createdAt: string;
+	updatedAt: string;
+	blockedBy: string | null;
+}
+
+export interface TodoStore {
+	items: TodoItem[];
+	counter: number;
+}
+
+const DEFAULT_PRIORITY: TodoPriority = "medium";
+
+/** Get the path to the todo file for the given project root */
+export function getTodoPath(cwd: string): string {
+	return path.join(cwd, ".pi", "todo.json");
+}
+
+/** Read the todo store from disk. Returns empty store if file doesn't exist. */
+export function readStore(cwd: string): TodoStore {
+	const todoPath = getTodoPath(cwd);
+	try {
+		const raw = fs.readFileSync(todoPath, "utf-8");
+		const parsed = JSON.parse(raw) as TodoStore;
+		if (!parsed.items || !Array.isArray(parsed.items)) {
+			return { items: [], counter: 0 };
+		}
+		return parsed;
+	} catch {
+		return { items: [], counter: 0 };
+	}
+}
+
+/** Write the todo store to disk. Creates .pi/ directory if needed. */
+export function writeStore(cwd: string, store: TodoStore): void {
+	const todoPath = getTodoPath(cwd);
+	const dir = path.dirname(todoPath);
+	fs.mkdirSync(dir, { recursive: true });
+	fs.writeFileSync(todoPath, JSON.stringify(store, null, "\t") + "\n", "utf-8");
+}
+
+/** Generate the next task ID */
+function nextId(counter: number): string {
+	return `T-${String(counter).padStart(3, "0")}`;
+}
+
+/** Create a new todo item */
+export function addItem(
+	cwd: string,
+	text: string,
+	priority?: TodoPriority,
+	assignee?: string,
+	blockedBy?: string,
+): TodoItem {
+	const store = readStore(cwd);
+	store.counter += 1;
+	const now = new Date().toISOString();
+	const item: TodoItem = {
+		id: nextId(store.counter),
+		text,
+		status: "pending",
+		priority: priority ?? DEFAULT_PRIORITY,
+		assignee: assignee ?? null,
+		createdAt: now,
+		updatedAt: now,
+		blockedBy: blockedBy ?? null,
+	};
+	store.items.push(item);
+	writeStore(cwd, store);
+	return item;
+}
+
+/** Update an existing todo item by ID. Returns the updated item or null if not found. */
+export function updateItem(
+	cwd: string,
+	id: string,
+	updates: Partial<Pick<TodoItem, "text" | "status" | "priority" | "assignee" | "blockedBy">>,
+): TodoItem | null {
+	const store = readStore(cwd);
+	const item = store.items.find((i) => i.id === id);
+	if (!item) return null;
+	if (updates.text !== undefined) item.text = updates.text;
+	if (updates.status !== undefined) item.status = updates.status;
+	if (updates.priority !== undefined) item.priority = updates.priority;
+	if (updates.assignee !== undefined) item.assignee = updates.assignee;
+	if (updates.blockedBy !== undefined) item.blockedBy = updates.blockedBy;
+	item.updatedAt = new Date().toISOString();
+	writeStore(cwd, store);
+	return item;
+}
+
+/** Toggle status: pending → in-progress → done → pending. Returns updated item or null. */
+export function toggleItem(cwd: string, id: string): TodoItem | null {
+	const store = readStore(cwd);
+	const item = store.items.find((i) => i.id === id);
+	if (!item) return null;
+	const cycle: Record<TodoStatus, TodoStatus> = {
+		pending: "in-progress",
+		"in-progress": "done",
+		done: "pending",
+		blocked: "in-progress",
+	};
+	item.status = cycle[item.status];
+	item.updatedAt = new Date().toISOString();
+	writeStore(cwd, store);
+	return item;
+}
+
+/** Remove an item by ID. Returns true if removed, false if not found. */
+export function removeItem(cwd: string, id: string): boolean {
+	const store = readStore(cwd);
+	const before = store.items.length;
+	store.items = store.items.filter((i) => i.id !== id);
+	if (store.items.length === before) return false;
+	writeStore(cwd, store);
+	return true;
+}
+
+/** List items, optionally filtered by status. */
+export function listItems(cwd: string, filter?: string): TodoItem[] {
+	const store = readStore(cwd);
+	if (!filter || filter === "all") return store.items;
+	return store.items.filter((i) => i.status === filter);
+}
+
+/** Remove all completed items. Returns the count removed. */
+export function clearCompleted(cwd: string): number {
+	const store = readStore(cwd);
+	const before = store.items.length;
+	store.items = store.items.filter((i) => i.status !== "done");
+	const removed = before - store.items.length;
+	if (removed > 0) writeStore(cwd, store);
+	return removed;
+}
+
+/** Reorder an item up (earlier) or down (later) in the list. Returns true if moved. */
+export function reorderItem(cwd: string, id: string, direction: "up" | "down"): boolean {
+	const store = readStore(cwd);
+	const index = store.items.findIndex((i) => i.id === id);
+	if (index === -1) return false;
+	if (direction === "up" && index === 0) return false;
+	if (direction === "down" && index === store.items.length - 1) return false;
+	const swapWith = direction === "up" ? index - 1 : index + 1;
+	[store.items[index], store.items[swapWith]] = [store.items[swapWith]!, store.items[index]!];
+	writeStore(cwd, store);
+	return true;
+}