pi-task-manager 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gil Assayag
+
+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 OF THE SOFTWARE, EVEN IF
+NOT ADVISED OF THE POSSIBILITY OF DAMAGE.

package/PLAN.md

@@ -0,0 +1,106 @@
+# pi-task-manager — Plan
+
+A pi extension that provides task/todo management via custom tools, with the task logic ported from Python to TypeScript.
+
+## Architecture
+
+**TypeScript extension** that registers tools with TypeBox schemas. The task management logic (parsing, editing, saving) is ported from `task_manager.py` to TypeScript — no Python subprocess needed.
+
+### Why migrate to TypeScript instead of wrapping Python?
+
+- **No subprocess overhead** — no spawn, no JSON serialization, no process lifecycle management
+- **Native pi integration** — runs in the same process, shares `ctx`, `signal`, etc.
+- **Simpler debugging** — one language, one runtime, one stack trace
+- **Better state management** — the singleton `_manager` pattern works naturally in TypeScript (no per-call process restart)
+- **No Python dependency** — users don't need Python installed
+
+## Project Structure
+
+```
+pi-task-manager/
+├── package.json            # pi package manifest + dependencies
+├── README.md               # User-facing docs
+├── PLAN.md                 # This file
+├── extension/
+│   ├── index.ts            # Extension entry: register tools, commands
+│   └── lib/
+│       ├── task-manager.ts # Core TaskManager class (ported from Python)
+│       ├── task.ts         # Task class / dataclass equivalent
+│       ├── parser.ts       # Markdown line parser (ported from _parse_task_line)
+│       └── tools.ts        # Tool definitions with TypeBox schemas
+└── skills/
+    └── task-manager/
+        └── SKILL.md        # Usage instructions for the LLM
+```
+
+## Porting from Python
+
+### Source files to reference
+
+- `~/agent/tools/task_manager.py` — Main implementation (TaskManager class, Task dataclass, parsing)
+- `~/agent/tools/task_manager_design.md` — Design rationale
+- `~/agent/tools/tasks_emojis_format.md` — Emoji conventions for tasks
+
+### Key Python constructs to port
+
+1. **Task dataclass** → TypeScript class/interface with fields:
+   - `id`, `text`, `completed`, `emoji`, `category`, `priority`, `project`, `context`, `tags`, `due`, `created`, `modified`, `indent`
+
+2. **TaskManager class** → TypeScript class with methods:
+   - `openFile(path)`, `addTask()`, `editTask()`, `moveTask()`, `getTask()`, `listTasks()`, `save()`, `closeFile()`
+
+3. **_parse_task_line** → TypeScript function returning parsed Task fields from a markdown line
+
+4. **Emoji handling** → Same emoji map, just TypeScript objects
+
+## Tool Definitions
+
+Each Python action maps to a pi tool:
+
+| Tool Name | Action | Description |
+|-----------|--------|-------------|
+| `task_open` | `open_file` | Open a TODO.md file for editing |
+| `task_add` | `add_task` | Add a new task |
+| `task_edit` | `edit_task` | Edit an existing task |
+| `task_move` | `move_task` | Move a task to a different category |
+| `task_get` | `get_task` | Get details of a single task |
+| `task_list` | `list_tasks` | List tasks (with filters) |
+| `task_save` | `save` | Save current state to disk |
+| `task_close` | `close_file` | Close the current file |
+
+## Implementation Steps
+
+### Phase 1: Core (Day 1)
+
+1. Create project structure with `package.json`
+2. Port `Task` dataclass → TypeScript interface
+3. Port `_parse_task_line` → TypeScript parser function
+4. Port `TaskManager` class → TypeScript (core methods only)
+5. Write basic tests for parser
+
+### Phase 2: Extension (Day 2)
+
+6. Create `extension/index.ts` with tool registrations
+7. Define TypeBox schemas for each tool
+8. Wire tool execute handlers to TaskManager methods
+9. Test extension in pi (load via `pi -e`)
+
+### Phase 3: Polish (Day 3)
+
+10. Create `skills/task-manager/SKILL.md` with usage instructions
+11. Add `resources_discover` handler for skill auto-discovery
+12. Write `README.md`
+13. Test full workflow end-to-end
+
+### Phase 4: Optional
+
+14. Add custom TUI rendering (status bar showing task counts)
+15. Add `/tasks` command for quick status
+16. Add `session_start` hook to auto-open TODO.md if present in cwd
+
+## Design Decisions
+
+- **State management**: The TaskManager singleton persists across tool calls within a session. `open_file` sets the active file, subsequent actions operate on it, `close_file` clears it. This matches the Python behavior.
+- **No subprocess**: Pure TypeScript, no Python dependency.
+- **TypeBox schemas**: Use `Type.Object()` for parameters, `StringEnum` for fixed choices (category, priority).
+- **Skill + Extension**: The extension provides the tools; the skill provides the LLM with usage instructions and conventions.

package/README.md

@@ -0,0 +1,85 @@
+# pi-task-manager
+
+A pi extension for hierarchical task management. Tasks live in a `TODO.md`
+file as an indented tree; the extension exposes 8 `task_*` tools backed by a
+pure-TypeScript port of the Python task manager — no subprocess, no Python
+dependency.
+
+## Install
+
+```bash
+pi install git:github.com/gilgil/pi-task-manager
+```
+
+Any git source works: `pi install https://github.com/gilgil/pi-task-manager`,
+`pi install /local/path`, or `pi install npm:pi-task-manager` once
+published to npm. Pin a tag for stability:
+`pi install git:github.com/gilgil/pi-task-manager@v0.1.0`;
+`pi update --extensions` reconciles the clone to the pinned ref.
+
+The extension registers the tools and the `task-manager` skill automatically.
+If a `TODO.md` exists in the working directory, it is opened automatically at
+session start (with a notification).
+
+## Task file format
+
+```markdown
+# TODO
+
+- [ ] Buy milk ➕ 2026-08-15 🖊️ 2026-08-15 (ID: `5Tvc0d`)
+  - [ ] Organic 📅 2026-08-20 (ID: `VpLDzY`)
+  - [x] Oat milk ✅ 2026-08-14 (ID: `Ab3x9Z`)
+- [> ] Write report ⏳ 2026-08-16 (ID: `Qw7m2K`)
+```
+
+- **Indentation** (2 spaces) defines the tree — each task's children are the
+  indented lines beneath it.
+- **Status** in the checkbox: ` ` open · `x` done · `>` in-progress ·
+  `!` failed · `-` cancelled
+- **Emoji annotations** between description and ID:
+  `⏳` scheduled · `🛫` start · `📅` due · `✅` done · `❌` cancelled ·
+  `➕` created · `🖊️` modified
+- **ID**: 6-char base62, stable, referenced by `parent_id`, `depends_on`, etc.
+- `depth`, `position`, and `parent_id` are always derived from the tree —
+  never stored.
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `task_open(path)` | Open `<path>/TODO.md` (created if missing). Call once first. |
+| `task_add(description, ...)` | Add a task. Returns the new ID. |
+| `task_edit(task_id, ...)` | Change fields; only provided fields change. |
+| `task_move(task_id, ...)` | Move a task **with its subtree**. No destination = delete task + subtree. |
+| `task_get(task_id)` | Full details of one task. |
+| `task_list(...)` | List with optional `parent_id` / `status` / `priority` filters. |
+| `task_save()` | Force save (mutations are auto-saved anyway). |
+| `task_close()` | Save and close. |
+
+### Hierarchy parameters
+
+- `parent_id` — add/move as **last child** of this task
+- `before_id` / `after_id` — insert at the **same level**, before/after that
+  sibling (must share the target's parent)
+- `task_move` with no `under_id`/`before_id`/`after_id` deletes the task and
+  its subtree
+
+### Other fields
+
+- `priority`: `lowest` `low` `normal` `medium` `high` `highest`
+- dates (`scheduled`, `start`, `due`): `YYYY-MM-DD`
+- `recurrence`: e.g. `weekly`, `every 2 weeks on Monday`
+- `depends_on`: list of task IDs (circular dependencies rejected)
+- `spec: true` — also create a `task-<id>.md` spec file
+- setting status to `x` / `-` stamps `date_done` / `date_cancelled`
+
+## Development
+
+```bash
+npm install
+node --test tests/parser.test.ts tests/task-manager.test.ts
+```
+
+Layout: `index.ts` (tool registration) · `lib/`
+(`task.ts` tree node, `parser.ts` line ⇄ tree, `task-manager.ts` mutations,
+`tools.ts` TypeBox schemas) · `skills/task-manager/SKILL.md` (LLM usage guide).

package/index.ts

@@ -0,0 +1,89 @@
+/**
+ * pi-task-manager — hierarchical task manager for pi.
+ *
+ * Registers 8 tools (task_open, task_add, task_edit, task_move, task_get,
+ * task_list, task_save, task_close) backed by a single TaskManager instance
+ * that manages one TODO.md file per session.
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { TaskManager } from "./lib/task-manager.ts";
+import { TOOLS } from "./lib/tools.ts";
+
+const manager = new TaskManager();
+
+type Result = Record<string, unknown>;
+
+const handlers: Record<string, (a: any) => Result> = {
+	task_open: (a) => manager.openFile(a.path),
+	task_add: (a) =>
+		manager.addTask(
+			a.description,
+			a.parent_id,
+			a.before_id,
+			a.after_id,
+			a.priority,
+			a.scheduled,
+			a.start,
+			a.due,
+			a.recurrence,
+			a.on_completion,
+			a.depends_on,
+			a.spec,
+		),
+	task_edit: (a) =>
+		manager.editTask(
+			a.task_id,
+			a.description,
+			a.status,
+			a.priority,
+			a.scheduled,
+			a.start,
+			a.due,
+			a.recurrence,
+			a.on_completion,
+			a.depends_on,
+		),
+	task_move: (a) => manager.moveTask(a.task_id, a.under_id, a.before_id, a.after_id),
+	task_get: (a) => manager.getTask(a.task_id),
+	task_list: (a) =>
+		manager.listTasks(a.parent_id, a.status, a.priority, a.include_subtasks),
+	task_save: () => manager.save(),
+	task_close: () => manager.closeFile(),
+};
+
+function format(result: Result): string {
+	if (result.status === "error") return `Error: ${result.error}`;
+	return JSON.stringify(result, null, 2);
+}
+
+export default function (pi: ExtensionAPI) {
+	pi.on("session_start", (_event, ctx) => {
+		const todoPath = join(ctx.cwd, "TODO.md");
+		if (!existsSync(todoPath)) return;
+		const result = manager.openFile(ctx.cwd);
+		if (!ctx.hasUI) return;
+		if (result.status === "ok")
+			ctx.ui.notify(`Tasks: opened ${todoPath} (${result.task_count} tasks)`, "info");
+		else
+			ctx.ui.notify(`Tasks: failed to open ${todoPath}: ${result.error}`, "warning");
+	});
+
+	for (const tool of TOOLS) {
+		pi.registerTool({
+			name: tool.name,
+			label: tool.label,
+			description: tool.description,
+			parameters: tool.parameters,
+			execute: async (_toolCallId, params: any) => {
+				const result = handlers[tool.name](params ?? {});
+				return {
+					content: [{ type: "text" as const, text: format(result) }],
+					details: result,
+				};
+			},
+		});
+	}
+}

package/lib/parser.ts

@@ -0,0 +1,345 @@
+/**
+ * TODO.md parser and serializer — ported from task_manager.py.
+ *
+ * Line format:
+ *   - [x] Description (ID: `abc123`)
+ *   - [ ] Setup ⏳ 2026-01-15 📅 2026-01-20 🔁 weekly (ID: `abc456`)
+ *
+ * 2 spaces of indent per hierarchy level. Annotations are inline emoji.
+ */
+
+import { newTask, type Task } from "./task.ts";
+
+export const MAX_DEPTH = 8;
+export const TODO_FILENAME = "TODO.md";
+
+export const BASE62_CHARS =
+	"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
+
+/** Priority emoji mapping (normal = no emoji, stored as null) */
+export const PRIORITY_EMOJI: Record<string, string> = {
+	lowest: "⏬",
+	low: "🔽",
+	medium: "🔼",
+	high: "⏫",
+	highest: "🔺",
+};
+
+export const PRIORITY_FROM_EMOJI: Record<string, string> = Object.fromEntries(
+	Object.entries(PRIORITY_EMOJI).map(([k, v]) => [v, k]),
+);
+
+/** Date emoji mapping */
+export const DATE_EMOJI: Record<string, string> = {
+	scheduled: "⏳",
+	start: "🛫",
+	due: "📅",
+	done: "✅",
+	cancelled: "❌",
+	created: "➕",
+	modified: "🖊️",
+};
+
+type DateKey =
+	| "scheduled"
+	| "start"
+	| "due"
+	| "done"
+	| "cancelled"
+	| "created"
+	| "modified";
+
+export const DATE_FROM_EMOJI: Record<string, DateKey> = Object.fromEntries(
+	Object.entries(DATE_EMOJI).map(([k, v]) => [v, k] as [string, DateKey]),
+);
+
+/** Status characters: ' '=open, 'x'=done, '>'=in-progress, '!'=failed, '-'=cancelled */
+export const STATUS_CHARS = [" ", "x", ">", "!", "-"];
+
+/**
+ * All emojis the parser treats as annotations. Descriptions must not
+ * contain them, or they get stripped/misparsed on reload.
+ */
+export const ANNOTATION_EMOJIS: string[] = [
+	...Object.values(PRIORITY_EMOJI),
+	...Object.values(DATE_EMOJI),
+	"🔁",
+	"🗑️",
+	"🏁",
+	"⛔",
+	"📎",
+	"🆔",
+];
+
+/** Returns the first annotation emoji found in text, or null. */
+export function findAnnotationEmoji(text: string): string | null {
+	for (const e of ANNOTATION_EMOJIS) if (text.includes(e)) return e;
+	return null;
+}
+
+const TASK_LINE_RE = /^( *)-\s+\[([ x>!-])\]\s+(.*?)\s*$/;
+const ID_RE = /\(ID:\s*`([A-Za-z0-9]{6})`\)\s*$/;
+const SPEC_RE = /📎\s*\[spec\]\(task-[A-Za-z0-9]+\.md\)\s*/;
+const DEPS_RE = /⛔\s*([A-Za-z0-9]+(?:,[A-Za-z0-9]+)*)\s*/;
+const RECUR_BEFORE_RE =
+	/🔁\s+(.+?)(?=\s+(?:⏬|🔽|🔼|⏫|🔺|⏳|🛫|📅|✅|❌|➕|🖊️|🗑️|🏁|⛔|📎|🆔))/;
+const RECUR_END_RE = /🔁\s+(.+?)(?=\s+$)/;
+const ID_REF_RE = /🆔\s*([A-Za-z0-9]+)\s*/;
+
+function escapeRegExp(s: string): string {
+	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+type Annotations = {
+	priority?: string;
+	scheduled?: string;
+	start?: string;
+	due?: string;
+	done?: string;
+	cancelled?: string;
+	created?: string;
+	modified?: string;
+	recurrence?: string;
+	on_completion?: string;
+	depends_on?: string[];
+	spec?: boolean;
+};
+
+/** Parse emoji annotations from the end of a task line. */
+export function parseAnnotations(text: string): [Annotations, string] {
+	const annotations: Annotations = {};
+	let remaining = text;
+
+	// 📎 spec link
+	const specMatch = remaining.match(SPEC_RE);
+	if (specMatch) {
+		annotations.spec = true;
+		remaining =
+			remaining.slice(0, specMatch.index) +
+			remaining.slice((specMatch.index ?? 0) + specMatch[0].length);
+	}
+
+	// ⛔ depends_on
+	const depMatch = remaining.match(DEPS_RE);
+	if (depMatch) {
+		annotations.depends_on = depMatch[1].split(",");
+		remaining =
+			remaining.slice(0, depMatch.index) +
+			remaining.slice((depMatch.index ?? 0) + depMatch[0].length);
+	}
+
+	// 🗑️ / 🏁 on_completion
+	if (remaining.includes("🗑️")) {
+		annotations.on_completion = "delete";
+		remaining = remaining.replace("🗑️", "").trim();
+	}
+	if (remaining.includes("🏁")) {
+		annotations.on_completion = "keep";
+		remaining = remaining.replace("🏁", "").trim();
+	}
+
+	// 🔁 recurrence (rule extends to the next emoji or end of text)
+	let recurMatch = remaining.match(RECUR_BEFORE_RE);
+	if (!recurMatch) recurMatch = remaining.match(RECUR_END_RE);
+	if (recurMatch) {
+		annotations.recurrence = recurMatch[1].trim();
+		remaining =
+			remaining.slice(0, recurMatch.index) +
+			remaining.slice((recurMatch.index ?? 0) + recurMatch[0].length);
+	}
+
+	// Date emojis followed by YYYY-MM-DD (in DATE_EMOJI order)
+	for (const [emoji, key] of Object.entries(DATE_FROM_EMOJI)) {
+		const re = new RegExp(`${escapeRegExp(emoji)}\\s*(\\d{4}-\\d{2}-\\d{2})\\s*`);
+		const m = remaining.match(re);
+		if (m) {
+			annotations[key] = m[1];
+			remaining =
+				remaining.slice(0, m.index) +
+				remaining.slice((m.index ?? 0) + m[0].length);
+		}
+	}
+
+	// Priority emojis
+	for (const [emoji, priority] of Object.entries(PRIORITY_FROM_EMOJI)) {
+		if (remaining.includes(emoji)) {
+			annotations.priority = priority;
+			remaining = remaining.replace(emoji, "").trim();
+		}
+	}
+
+	// 🆔 self-reference (informational only)
+	const idRef = remaining.match(ID_REF_RE);
+	if (idRef) {
+		remaining =
+			remaining.slice(0, idRef.index) +
+			remaining.slice((idRef.index ?? 0) + idRef[0].length);
+	}
+
+	return [annotations, remaining.trim()];
+}
+
+/** Parse a single task line. Returns null if the line is not a valid task. */
+export function parseTaskLine(line: string): Task | null {
+	const m = line.match(TASK_LINE_RE);
+	if (!m) return null;
+
+	const status = m[2];
+	let rest = m[3];
+
+	const idMatch = rest.match(ID_RE);
+	if (!idMatch) return null;
+	const id = idMatch[1];
+	rest = rest.slice(0, idMatch.index).trim();
+
+	const [annotations, description] = parseAnnotations(rest);
+
+	const task = newTask(id, description);
+	task.status = status;
+	if (annotations.priority) task.priority = annotations.priority;
+	if (annotations.scheduled) task.dateScheduled = annotations.scheduled;
+	if (annotations.start) task.dateStart = annotations.start;
+	if (annotations.due) task.dateDue = annotations.due;
+	if (annotations.done) task.dateDone = annotations.done;
+	if (annotations.cancelled) task.dateCancelled = annotations.cancelled;
+	if (annotations.created) task.dateCreated = annotations.created;
+	if (annotations.modified) task.dateModified = annotations.modified;
+	if (annotations.recurrence) task.recurrence = annotations.recurrence;
+	if (annotations.on_completion) task.onCompletion = annotations.on_completion;
+	if (annotations.depends_on) task.dependsOn = annotations.depends_on;
+	if (annotations.spec) task.hasSpec = true;
+
+	return task;
+}
+
+/**
+ * Parse entire TODO.md content into a tree of tasks (returns the roots).
+ * Hierarchy comes from indentation: each task is appended as a child of
+ * the most recent task at one shallower depth.
+ */
+export function parseTodoFile(content: string): Task[] {
+	const roots: Task[] = [];
+	const stack: (Task | null)[] = []; // stack[d] = most recent task at depth d
+
+	for (const line of content.split("\n")) {
+		const stripped = line.trim();
+		if (!stripped || stripped.startsWith("#") || !stripped.startsWith("-"))
+			continue;
+
+		const match = line.match(/^( *)-\s+\[/);
+		if (!match) continue;
+
+		const depth = Math.floor(match[1].length / 2);
+		if (depth > MAX_DEPTH) continue;
+
+		const task = parseTaskLine(line);
+		if (!task) continue;
+
+		const parent = depth === 0 ? null : stack[depth - 1] ?? null;
+		task.parent = parent;
+		(parent ? parent.children : roots).push(task);
+		stack[depth] = task;
+		stack.length = depth + 1;
+	}
+
+	return roots;
+}
+
+/** A structural problem found while scanning TODO.md content. */
+export type TodoIssue =
+	| { kind: "orphan"; line: number; id: string; depth: number }
+	| { kind: "tab"; line: number; id: string }
+	| { kind: "duplicate"; line: number; id: string; firstLine: number };
+
+/**
+ * Task line with tab (or mixed) indentation. The parser's indent regex only
+ * matches spaces, so such a line is silently dropped; we detect it here.
+ */
+const TAB_TASK_RE =
+	/^([\t ]+)-\s+\[([ x>!-])\]\s+.*\(ID:\s*`([A-Za-z0-9]{6})`\)\s*$/;
+
+/**
+ * Scan TODO.md content for structural problems the parser would silently
+ * mishandle: orphaned indented lines (no ancestor at the expected level),
+ * tab indentation (line dropped), and duplicate task IDs. Returns 1-based
+ * line numbers and task IDs for each problem.
+ */
+export function findTodoIssues(content: string): TodoIssue[] {
+	const issues: TodoIssue[] = [];
+	const stack: (Task | null)[] = [];
+	const idLines = new Map<string, number>();
+
+	content.split("\n").forEach((line, i) => {
+		const n = i + 1;
+		const stripped = line.trim();
+		if (!stripped || stripped.startsWith("#") || !stripped.startsWith("-"))
+			return;
+
+		const tabMatch = line.match(TAB_TASK_RE);
+		if (tabMatch && tabMatch[1].includes("\t")) {
+			issues.push({ kind: "tab", line: n, id: tabMatch[3] });
+			return;
+		}
+
+		const match = line.match(/^( *)-\s+\[/);
+		if (!match) return;
+		const depth = Math.floor(match[1].length / 2);
+		if (depth > MAX_DEPTH) return;
+		const task = parseTaskLine(line);
+		if (!task) return;
+
+		if (depth > 0 && !stack[depth - 1])
+			issues.push({ kind: "orphan", line: n, id: task.id, depth });
+
+		const first = idLines.get(task.id);
+		if (first !== undefined)
+			issues.push({ kind: "duplicate", line: n, id: task.id, firstLine: first });
+		else idLines.set(task.id, n);
+
+		stack[depth] = task;
+		stack.length = depth + 1;
+	});
+
+	return issues;
+}
+
+/** Serialize a task back to a markdown line (conventional annotation order). */
+export function buildTaskLine(task: Task, depth: number = 0): string {
+	const indent = "  ".repeat(depth);
+	const annotations: string[] = [];
+
+	if (task.priority && task.priority in PRIORITY_EMOJI)
+		annotations.push(PRIORITY_EMOJI[task.priority]);
+	if (task.dateScheduled) annotations.push(`⏳ ${task.dateScheduled}`);
+	if (task.dateStart) annotations.push(`🛫 ${task.dateStart}`);
+	if (task.dateDue) annotations.push(`📅 ${task.dateDue}`);
+	if (task.dateDone) annotations.push(`✅ ${task.dateDone}`);
+	if (task.dateCancelled) annotations.push(`❌ ${task.dateCancelled}`);
+	if (task.recurrence) annotations.push(`🔁 ${task.recurrence}`);
+	if (task.onCompletion === "delete") annotations.push("🗑️");
+	else if (task.onCompletion === "keep") annotations.push("🏁");
+	if (task.dependsOn.length > 0)
+		annotations.push(`⛔ ${task.dependsOn.join(",")}`);
+	if (task.hasSpec) annotations.push(`📎 [spec](task-${task.id}.md)`);
+	if (task.dateCreated) annotations.push(`➕ ${task.dateCreated}`);
+	if (task.dateModified) annotations.push(`🖊️ ${task.dateModified}`);
+
+	const annotationStr = annotations.join(" ");
+	if (annotationStr)
+		return `${indent}- [${task.status}] ${task.description} ${annotationStr} (ID: \`${task.id}\`)`;
+	return `${indent}- [${task.status}] ${task.description} (ID: \`${task.id}\`)`;
+}
+
+/** Convert a task tree to TODO.md markdown content (recursive DFS). */
+export function tasksToMarkdown(roots: Task[]): string {
+	const lines: string[] = ["# TODO", ""];
+	const walk = (tasks: Task[], depth: number): void => {
+		for (const task of tasks) {
+			lines.push(buildTaskLine(task, depth));
+			walk(task.children, depth + 1);
+		}
+	};
+	walk(roots, 0);
+	lines.push("");
+	return lines.join("\n");
+}