pi-comprehensive-tasks 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rizquuula
+
+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,133 @@
+# pi-comprehensive-tasks
+
+A task tree in `TODO.md` for the [pi coding agent](https://pi.dev), seeded from a
+[pi-comprehensive-planning](https://github.com/rizquuula/pi-comprehensive-planning) plan.
+
+```bash
+pi install npm:pi-comprehensive-tasks
+```
+
+The plan is intent, written once and reviewed. The task list is live state, rewritten as
+the work actually goes. Keeping those two in one file is how plans rot, so this package
+keeps them apart.
+
+```markdown
+# Tasks
+
+- [ ] Slice A: the file format <!-- plan:§9#A -->
+  - [x] parse the tree <!-- plan:§8#1 -->
+  - [ ] toggle a child <!-- plan:§8#2 -->
+- [ ] Unassigned
+  - [ ] wiring only <!-- plan:§8#9 -->
+```
+
+## Install
+
+```bash
+# from npm
+pi install npm:pi-comprehensive-tasks
+
+# from GitHub
+pi install git:github.com/rizquuula/pi-comprehensive-tasks
+
+# try it without installing anything
+pi -e npm:pi-comprehensive-tasks
+```
+
+Add `-l` to install into the current project instead of globally. Requires pi v0.85 or
+newer. Nothing to compile — pi loads the TypeScript directly.
+
+## Seeding from a plan
+
+```
+/tasks seed
+```
+
+Reads `PLAN.md` and builds a two-level tree: each **§9 slice** becomes a parent, each
+**§8 cycle** becomes a child of the slice that owns a file the cycle names.
+
+```
+- [ ] A: the file format          ← §9 slice
+  - [ ] `task-file.test.ts` …     ← §8 cycle, filed here because slice A owns the file
+- [ ] Unassigned
+  - [ ] wiring only               ← §8 cycle whose files no slice claims
+```
+
+Seeding is **idempotent**. Each item is tagged with its origin, so running it twice adds
+nothing the second time and never touches work you have already done.
+
+Two things worth knowing:
+
+- **File paths must be in backticks** in §8 and §9. That is what the plan template does,
+  and it is how cycles are matched to slices. If they are missing, seeding says so rather
+  than silently doing nothing.
+- **The match is a heuristic.** A cycle is filed under the first slice that owns a file it
+  names. Anything unmatched lands under `Unassigned`, which is visible on purpose.
+
+No plan? The package works standalone. `/tasks add <text>` and the tools below do not
+need a `PLAN.md` anywhere.
+
+## The extension
+
+**Three tools** the agent uses as it works:
+
+| Tool | What it does |
+|---|---|
+| `task_list` | The numbered tree plus progress. Numbers are stable positions in that list. |
+| `task_add` | Adds a task, optionally under a parent and tagged with a plan ref. Adding a ref twice is a no-op. |
+| `task_complete` | Ticks a task, or reopens it with `done: false`. |
+
+**`/tasks`** for you:
+
+```
+/tasks                  pick a task to toggle, repeatedly, until Esc
+/tasks seed             build the tree from PLAN.md
+/tasks add <text>       add a top-level task
+/tasks done <ref|num>   tick one
+/tasks undone <ref|num> reopen one
+```
+
+**A widget** under the editor: `TODO.md · 3/7 done`, with the tree beneath it. A branch
+whose cycles are all finished collapses to one dimmed line carrying its count.
+
+The glyph is always the task's own state, never a summary of its children. A slice whose
+cycles are all done but which is itself unticked stays `[ ]` — that is the one thing left
+to do, and reporting it as finished would be a lie.
+
+## Working with pi-comprehensive-planning
+
+They are independent packages. Neither imports the other, and each installs and versions
+on its own.
+
+| | |
+|---|---|
+| `PLAN.md` | Intent. Written once by `/plan-comprehensively`, checked by `plan_validate`. |
+| `TODO.md` | State. Written continuously by this package. |
+
+Planning shows a `PLAN.md · 7 cycles` widget; this one shows `TODO.md · 3/7 done`. They
+answer different questions, so both stay. Disable either with `pi config` if the pair
+feels noisy.
+
+## Development
+
+No build step. A clone runs as-is:
+
+```bash
+pi -e ./ --no-skills     # load this package in isolation
+npm test                 # node --test, no dependencies installed
+```
+
+The tests cover the three modules with rules worth pinning down: `task-file` (parse,
+toggle round-trip, add), `seed` (tree shape, `Unassigned` fallback, idempotency), and
+`render` (indentation, dimming, the collapse rule).
+
+## Security
+
+The extension reads and writes two files in the working directory, registers three tools,
+one command, and one widget, and handles one event. It runs no subprocesses, opens no
+sockets, and makes no network calls. Read the source before installing it — it is about
+600 lines.
+
+## License
+
+MIT

package/extensions/index.ts

@@ -0,0 +1,306 @@
+/**
+ * pi-comprehensive-tasks — the extension half.
+ *
+ * TODO.md is the store. This wires three tools, a /tasks command, and a widget that
+ * collapses branches as they finish. It reads PLAN.md exactly once, at seed time.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import {
+  addTask,
+  createTaskFile,
+  findTask,
+  flatten,
+  parseTaskFile,
+  progress,
+  serializeTaskFile,
+  setDone,
+  type TaskFile,
+} from "./task-file.ts";
+import { applySeed, seedFromPlan, seedWarning } from "./seed.ts";
+import { renderWidget } from "./render.ts";
+
+const TASKS_FILENAME = "TODO.md";
+const PLAN_FILENAME = "PLAN.md";
+const WIDGET_ID = "tasks";
+
+function tasksPath(ctx: ExtensionContext): string {
+  return join(ctx.cwd, TASKS_FILENAME);
+}
+
+/** Read TODO.md, or an empty in-memory file when it does not exist yet. */
+function load(ctx: ExtensionContext): TaskFile {
+  const path = tasksPath(ctx);
+  if (!existsSync(path)) return createTaskFile(path);
+  return parseTaskFile(path, readFileSync(path, "utf-8"));
+}
+
+function save(ctx: ExtensionContext, file: TaskFile): void {
+  const text = serializeTaskFile(file);
+  // Always end the file with a newline, even when the last line was just inserted.
+  writeFileSync(tasksPath(ctx), text.endsWith("\n") ? text : `${text}\n`, "utf-8");
+}
+
+function refresh(ctx: ExtensionContext): void {
+  if (!ctx.hasUI) return;
+  const file = load(ctx);
+  const lines = renderWidget(file, {
+    dim: (text) => ctx.ui.theme.fg("dim", text),
+    accent: (text) => ctx.ui.theme.fg("accent", text),
+    width: 72,
+  });
+  ctx.ui.setWidget(WIDGET_ID, lines.length > 0 ? lines : undefined, { placement: "belowEditor" });
+}
+
+/** The numbered tree, in the same pre-order `findTask` resolves numbers against. */
+function numberedList(file: TaskFile): string {
+  const all = flatten(file);
+  if (all.length === 0) return `No tasks yet. Seed from a plan with /tasks seed, or add one.`;
+  return all
+    .map((task, index) => {
+      const indent = "   ".repeat(task.depth);
+      const ref = task.planRef ? `  (${task.planRef})` : "";
+      return `${index + 1}. ${indent}${task.done ? "[x]" : "[ ]"} ${task.text}${ref}`;
+    })
+    .join("\n");
+}
+
+function summary(file: TaskFile): string {
+  const { done, total } = progress(file);
+  return total === 0 ? `${TASKS_FILENAME} · empty` : `${TASKS_FILENAME} · ${done}/${total} done`;
+}
+
+function readPlan(ctx: ExtensionContext): string | null {
+  const path = join(ctx.cwd, PLAN_FILENAME);
+  return existsSync(path) ? readFileSync(path, "utf-8") : null;
+}
+
+export default function (pi: ExtensionAPI) {
+  pi.on("session_start", async (_event, ctx) => {
+    refresh(ctx);
+  });
+
+  // Keep the widget in step when the file is edited by hand or by another tool.
+  pi.on("tool_result", async (event, ctx) => {
+    const path = (event.input as { path?: string }).path;
+    if (path && path.endsWith(TASKS_FILENAME)) refresh(ctx);
+  });
+
+  // ------------------------------------------------------------------ tools
+
+  pi.registerTool({
+    name: "task_list",
+    label: "List Tasks",
+    description: `List every task in ${TASKS_FILENAME} as a numbered tree, with progress. Numbers are stable positions in that list and can be passed to task_complete.`,
+    promptSnippet: `List the task tree from ${TASKS_FILENAME}`,
+    promptGuidelines: [
+      "Use task_list to read the current task state instead of guessing from memory.",
+      "Use task_list before task_complete when you need the number of a task.",
+    ],
+    parameters: Type.Object({}),
+
+    async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+      const file = load(ctx);
+      return {
+        content: [{ type: "text" as const, text: `${summary(file)}\n\n${numberedList(file)}` }],
+        details: { done: progress(file).done, total: progress(file).total },
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "task_add",
+    label: "Add Task",
+    description: `Add a task to ${TASKS_FILENAME}. Omit parent to add at the top level. Adding a planRef that is already present is a no-op, so this is safe to call twice.`,
+    promptSnippet: `Add a task to ${TASKS_FILENAME}`,
+    promptGuidelines: [
+      "Use task_add when work appears that the plan did not cover, rather than keeping it in your head.",
+      "Use task_add with a parent to file a task under the slice it belongs to.",
+    ],
+    parameters: Type.Object({
+      text: Type.String({ description: "What the task is. One line." }),
+      parent: Type.Optional(
+        Type.String({ description: "Plan ref or number of the parent task, for example §9#A. Omit for top level." }),
+      ),
+      planRef: Type.Optional(
+        Type.String({ description: "Plan origin to tag the task with, for example §8#5. Makes a repeat call a no-op." }),
+      ),
+    }),
+
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const file = load(ctx);
+      const result = addTask(file, {
+        text: params.text,
+        planRef: params.planRef ?? null,
+        parentRef: params.parent ?? null,
+      });
+
+      if (!result.added) {
+        return {
+          content: [{ type: "text" as const, text: `Not added: ${result.reason}.` }],
+          details: { added: false, reason: result.reason },
+        };
+      }
+
+      save(ctx, file);
+      refresh(ctx);
+      return {
+        content: [{ type: "text" as const, text: `Added. ${summary(file)}\n\n${numberedList(file)}` }],
+        details: { added: true },
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "task_complete",
+    label: "Complete Task",
+    description: `Mark a task in ${TASKS_FILENAME} done, or reopen it with done false. Identify it by plan ref (§8#3) or by its number from task_list.`,
+    promptSnippet: `Mark a task done, or reopen it`,
+    promptGuidelines: [
+      "Use task_complete as soon as a cycle passes, so the task list reflects reality.",
+      "Use task_complete with done false to reopen a task that turned out to be unfinished.",
+    ],
+    parameters: Type.Object({
+      task: Type.String({ description: "Plan ref such as §8#3, or the number shown by task_list." }),
+      done: Type.Optional(Type.Boolean({ description: "True to complete, false to reopen. Defaults to true." })),
+    }),
+
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const file = load(ctx);
+      const done = params.done ?? true;
+
+      // Resolve before mutating, so the reply can name the task it changed.
+      const target = findTask(file, params.task);
+      if (!target) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `No task matches "${params.task}". Run task_list to see the refs and numbers.`,
+            },
+          ],
+          details: { updated: false },
+        };
+      }
+
+      setDone(file, params.task, done);
+      save(ctx, file);
+      refresh(ctx);
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `${done ? "Completed" : "Reopened"} "${target.text}". ${summary(file)}\n\n${numberedList(file)}`,
+          },
+        ],
+        details: { updated: true, done, task: target.text },
+      };
+    },
+  });
+
+  // ------------------------------------------------------------------ /tasks
+
+  async function togglePicker(ctx: ExtensionContext): Promise<void> {
+    for (;;) {
+      const file = load(ctx);
+      const all = flatten(file);
+      if (all.length === 0) {
+        ctx.ui.notify("No tasks yet. Run /tasks seed, or /tasks add <text>.", "info");
+        return;
+      }
+
+      const options = all.map(
+        (task, index) => `${index + 1}. ${task.done ? "[x]" : "[ ]"} ${"  ".repeat(task.depth)}${task.text}`,
+      );
+      const choice = await ctx.ui.select(`${summary(file)} — pick one to toggle, Esc to close`, options);
+      if (!choice) return;
+
+      const number = /^(\d+)\./.exec(choice)?.[1];
+      if (!number) return;
+      setDone(file, number, !all[Number(number) - 1]!.done);
+      save(ctx, file);
+      refresh(ctx);
+    }
+  }
+
+  pi.registerCommand("tasks", {
+    description: "List, seed, add, or toggle tasks in TODO.md",
+    handler: async (args, ctx) => {
+      const input = (args ?? "").trim();
+      const [verb, ...rest] = input.split(/\s+/);
+      const remainder = rest.join(" ").trim();
+
+      if (verb === "seed") {
+        const plan = readPlan(ctx);
+        if (!plan) {
+          ctx.ui.notify(`No ${PLAN_FILENAME} in this directory. Run /plan-comprehensively first.`, "warning");
+          return;
+        }
+        const warning = seedWarning(plan);
+        if (warning) {
+          ctx.ui.notify(warning, "warning");
+          return;
+        }
+        const file = load(ctx);
+        const result = applySeed(file, seedFromPlan(plan));
+        save(ctx, file);
+        refresh(ctx);
+        ctx.ui.notify(
+          result.added > 0
+            ? `Seeded ${result.added} task(s) from ${PLAN_FILENAME}, skipped ${result.skipped}. ${summary(file)}`
+            : `Nothing to seed: all ${result.skipped} task(s) were already there.`,
+          "info",
+        );
+        return;
+      }
+
+      if (verb === "add") {
+        if (!remainder) {
+          ctx.ui.notify("Usage: /tasks add <text>", "error");
+          return;
+        }
+        const file = load(ctx);
+        const result = addTask(file, { text: remainder });
+        if (!result.added) {
+          ctx.ui.notify(`Not added: ${result.reason}.`, "error");
+          return;
+        }
+        save(ctx, file);
+        refresh(ctx);
+        ctx.ui.notify(`Added. ${summary(file)}`, "info");
+        return;
+      }
+
+      if (verb === "done" || verb === "undone") {
+        if (!remainder) {
+          ctx.ui.notify(`Usage: /tasks ${verb} <ref|number>`, "error");
+          return;
+        }
+        const file = load(ctx);
+        if (!setDone(file, remainder, verb === "done")) {
+          ctx.ui.notify(`No task matches "${remainder}". Run /tasks to see the numbers.`, "error");
+          return;
+        }
+        save(ctx, file);
+        refresh(ctx);
+        ctx.ui.notify(`${verb === "done" ? "Completed" : "Reopened"}. ${summary(file)}`, "info");
+        return;
+      }
+
+      if (verb) {
+        ctx.ui.notify("Usage: /tasks [seed | add <text> | done <ref> | undone <ref>]", "error");
+        return;
+      }
+
+      if (!ctx.hasUI) {
+        const file = load(ctx);
+        ctx.ui.notify(`${summary(file)}\n${numberedList(file)}`, "info");
+        return;
+      }
+      await togglePicker(ctx);
+    },
+  });
+}

package/extensions/render.ts

@@ -0,0 +1,96 @@
+/**
+ * Turning a task tree into widget lines.
+ *
+ * Pure on purpose: the collapse rule is the interesting part of the display, so it is
+ * unit-tested rather than eyeballed. Colour arrives as injected functions, which keeps
+ * this module free of any theme dependency.
+ */
+
+import { flatten, progress, type Task, type TaskFile } from "./task-file.ts";
+
+export interface RenderOptions {
+  dim?: (text: string) => string;
+  accent?: (text: string) => string;
+  /** Collapse a branch whose descendants are all done. On by default. */
+  collapse?: boolean;
+  /** Truncate each line to this width. Default 72. */
+  width?: number;
+}
+
+const CHECKED = "[x]";
+const OPEN = "[ ]";
+
+/** Every descendant of a task, at all depths. */
+function descendants(task: Task): Task[] {
+  const out: Task[] = [];
+  const walk = (tasks: Task[]) => {
+    for (const child of tasks) {
+      out.push(child);
+      walk(child.children);
+    }
+  };
+  walk(task.children);
+  return out;
+}
+
+function truncate(text: string, width: number): string {
+  if (text.length <= width) return text;
+  return `${text.slice(0, Math.max(1, width - 1))}…`;
+}
+
+function label(task: Task): string {
+  return `${task.done ? CHECKED : OPEN} ${task.text}`;
+}
+
+/**
+ * One line per visible task, indented by depth. A branch whose descendants are all
+ * done collapses to a single line carrying its own count.
+ *
+ * The glyph is always the task's own state, never a summary of its children: a slice
+ * whose cycles are all finished but which is itself unticked stays `[ ]`, because that
+ * is the one thing left to do.
+ */
+export function renderTasks(file: TaskFile, options: RenderOptions = {}): string[] {
+  const { dim = (text) => text, collapse = true, width = 72 } = options;
+  const lines: string[] = [];
+
+  const walk = (tasks: Task[]) => {
+    for (const task of tasks) {
+      const indent = "  ".repeat(task.depth);
+      const kids = descendants(task);
+      const branchDone = kids.length > 0 && kids.every((child) => child.done);
+
+      if (collapse && branchDone) {
+        const done = kids.filter((child) => child.done).length;
+        lines.push(dim(truncate(`${indent}${label(task)} · ${done}/${kids.length}`, width)));
+        continue;
+      }
+
+      const line = `${indent}${label(task)}`;
+      lines.push(truncate(task.done ? dim(line) : line, width));
+      walk(task.children);
+    }
+  };
+
+  walk(file.tasks);
+  return lines;
+}
+
+/** `TODO.md · 3/7 done`, or `TODO.md · empty` when there is nothing to do. */
+export function renderHeader(file: TaskFile, options: RenderOptions = {}): string {
+  const { accent = (text) => text } = options;
+  const { done, total } = progress(file);
+  const name = file.path.split("/").pop() ?? "TODO.md";
+  if (total === 0) return accent(`${name} · empty`);
+  return accent(`${name} · ${done}/${total} done`);
+}
+
+/** The whole widget body: header first, then the tree. */
+export function renderWidget(file: TaskFile, options: RenderOptions = {}): string[] {
+  const body = renderTasks(file, options);
+  if (body.length === 0) return [];
+  return [renderHeader(file, options), ...body];
+}
+
+/** Re-exported so callers can size the widget without importing task-file twice. */
+export { flatten, progress };

package/extensions/seed.ts

@@ -0,0 +1,216 @@
+/**
+ * Seeding TODO.md from a plan.
+ *
+ * Reads two tables out of PLAN.md and nowhere else:
+ *   §9 Work sequencing  -> one parent per slice, with the files it owns
+ *   §8 Step-by-step     -> one child per cycle, filed under the slice that owns its files
+ *
+ * A cycle whose files match no slice lands under an `Unassigned` parent. Filing it
+ * wrongly is recoverable; dropping it silently is not.
+ *
+ * Nothing here imports the planning package. The two table shapes are duplicated on
+ * purpose, so this package versions and installs independently.
+ */
+
+import { addTask, findTask, type TaskFile } from "./task-file.ts";
+
+export interface SeedChild {
+  ref: string;
+  text: string;
+}
+
+export interface SeedParent {
+  ref: string;
+  text: string;
+  children: SeedChild[];
+}
+
+export interface SliceRow {
+  ref: string;
+  text: string;
+  files: string[];
+}
+
+export interface CycleRow {
+  ref: string;
+  text: string;
+  files: string[];
+}
+
+export const UNASSIGNED_REF = "unassigned";
+
+const FILE_LIKE =
+  /\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|cpp|cc|cxx|h|hpp|kt|kts|dart|java|rb|php|cs|swift|sql|json|ya?ml|toml|md|proto|sh|tf)$/i;
+
+/** Split on `## N. Title` / `### N. Title` headings, keyed by the number. */
+function sections(raw: string): Map<string, string> {
+  const found = new Map<string, string>();
+  let current: string | null = null;
+  let buffer: string[] = [];
+
+  const flush = () => {
+    if (current !== null) found.set(current, buffer.join("\n").trim());
+  };
+
+  for (const line of raw.split(/\r?\n/)) {
+    const heading = /^#{2,4}\s+(\d+)[.)]\s+/.exec(line);
+    if (heading) {
+      flush();
+      current = heading[1]!;
+      buffer = [];
+      continue;
+    }
+    if (current !== null) buffer.push(line);
+  }
+  flush();
+  return found;
+}
+
+function tableRows(body: string): string[][] {
+  const rows: string[][] = [];
+  let seenHeader = false;
+
+  for (const line of body.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("|")) {
+      if (seenHeader && rows.length > 0 && trimmed === "") seenHeader = false;
+      continue;
+    }
+    const cells = trimmed
+      .replace(/^\|/, "")
+      .replace(/\|$/, "")
+      .split("|")
+      .map((cell) => cell.trim());
+
+    if (cells.every((cell) => /^:?-{2,}:?$/.test(cell))) continue;
+    if (!seenHeader) {
+      seenHeader = true;
+      continue;
+    }
+    rows.push(cells);
+  }
+  return rows;
+}
+
+function backticked(text: string): string[] {
+  return [...text.matchAll(/`([^`]+)`/g)]
+    .map((match) => match[1]!.trim().replace(/^\.\//, ""))
+    .filter((value) => value !== "" && FILE_LIKE.test(value));
+}
+
+function clean(text: string): string {
+  return text.replace(/\s+/g, " ").replace(/<!--[\s\S]*?-->/g, "").trim();
+}
+
+/** `A: the file format` -> `A`. Falls back to the row's position. */
+function sliceLabel(cell: string, index: number): string {
+  const match = /^([A-Za-z][A-Za-z0-9]*)\s*[:：\-–—]/.exec(cell.trim());
+  return match ? match[1]! : String(index + 1);
+}
+
+export function readPlanTables(planRaw: string): { slices: SliceRow[]; cycles: CycleRow[] } {
+  const parts = sections(planRaw);
+
+  const slices = tableRows(parts.get("9") ?? "").map((cells, index) => ({
+    ref: `§9#${sliceLabel(cells[0] ?? "", index)}`,
+    text: clean(cells[0] ?? ""),
+    files: backticked(cells[1] ?? ""),
+  }));
+
+  const cycles = tableRows(parts.get("8") ?? "").map((cells) => ({
+    ref: `§8#${(cells[0] ?? "").replace(/[^A-Za-z0-9]/g, "")}`,
+    text: clean(cells[1] ?? ""),
+    files: [...backticked(cells[1] ?? ""), ...backticked(cells[2] ?? "")],
+  }));
+
+  return { slices, cycles };
+}
+
+/**
+ * Build the tree a plan implies. Slice order is preserved; `Unassigned` comes last
+ * and only when something actually landed there.
+ */
+export function seedFromPlan(planRaw: string): SeedParent[] {
+  const { slices, cycles } = readPlanTables(planRaw);
+
+  const parents: SeedParent[] = slices.map((slice) => ({
+    ref: slice.ref,
+    text: slice.text,
+    children: [],
+  }));
+  const unassigned: SeedParent = { ref: UNASSIGNED_REF, text: "Unassigned", children: [] };
+
+  for (const cycle of cycles) {
+    const owner = slices.find((slice) =>
+      slice.files.some((owned) => cycle.files.includes(owned)),
+    );
+    const child: SeedChild = { ref: cycle.ref, text: cycle.text };
+    if (!owner) {
+      unassigned.children.push(child);
+      continue;
+    }
+    parents.find((parent) => parent.ref === owner.ref)!.children.push(child);
+  }
+
+  if (unassigned.children.length > 0) parents.push(unassigned);
+  return parents;
+}
+
+export interface SeedResult {
+  added: number;
+  skipped: number;
+}
+
+/**
+ * Explain why a seed would do nothing, instead of silently doing nothing.
+ * Returns null when the plan looks seedable.
+ */
+export function seedWarning(planRaw: string): string | null {
+  const parts = sections(planRaw);
+
+  if (!parts.has("8") || !parts.has("9")) {
+    const missing = ["8", "9"].filter((key) => !parts.has(key));
+    const label = missing.length === 2 ? "§8 and §9" : `§${missing[0]}`;
+    return `PLAN.md has no ${label} section. Seeding reads §9 for slices and §8 for cycles.`;
+  }
+
+  const { slices, cycles } = readPlanTables(planRaw);
+  if (cycles.length === 0) return "§8 has no table rows, so there are no cycles to seed.";
+  if (slices.length === 0) return "§9 has no table rows, so there are no slices to group under.";
+
+  if (cycles.every((cycle) => cycle.files.length === 0)) {
+    return "§8 names no file paths. Wrap them in backticks, for example `src/cache.ts`, so cycles can be matched to slices.";
+  }
+  if (slices.every((slice) => slice.files.length === 0)) {
+    return "§9 lists no file paths. Wrap them in backticks so cycles can be matched to slices.";
+  }
+  return null;
+}
+
+/** Merge a seed into an open task file. Idempotent: a ref already present is skipped. */
+export function applySeed(file: TaskFile, parents: SeedParent[]): SeedResult {
+  let added = 0;
+  let skipped = 0;
+
+  for (const parent of parents) {
+    if (findTask(file, parent.ref)) {
+      skipped += 1;
+    } else {
+      const result = addTask(file, { text: parent.text, planRef: parent.ref });
+      if (result.added) added += 1;
+      else skipped += 1;
+    }
+
+    for (const child of parent.children) {
+      if (findTask(file, child.ref)) {
+        skipped += 1;
+        continue;
+      }
+      const result = addTask(file, { text: child.text, planRef: child.ref, parentRef: parent.ref });
+      if (result.added) added += 1;
+      else skipped += 1;
+    }
+  }
+
+  return { added, skipped };
+}

package/extensions/task-file.ts

@@ -0,0 +1,204 @@
+/**
+ * Reading and writing TODO.md.
+ *
+ * The file is the interface: plain Markdown nested checkboxes, so it renders as a real
+ * checklist on GitHub. Only checkbox lines are ever rewritten — prose the user added
+ * around the list passes through untouched.
+ *
+ *   # Tasks
+ *
+ *   - [ ] Slice A: the file format <!-- plan:§9#A -->
+ *     - [ ] parse the tree <!-- plan:§8#1 -->
+ *     - [x] toggle a child <!-- plan:§8#2 -->
+ */
+
+export interface Task {
+  text: string;
+  done: boolean;
+  /** Origin in the plan, for example `§8#1`. Null for tasks a human added. */
+  planRef: string | null;
+  /** Nesting level, 0 for a root. Two spaces of indent per level. */
+  depth: number;
+  /** Index into `TaskFile.lines`. */
+  line: number;
+  children: Task[];
+}
+
+export interface TaskFile {
+  path: string;
+  /** Raw lines. Mutations rewrite this, then re-parse. */
+  lines: string[];
+  tasks: Task[];
+}
+
+const ITEM_RE = /^([ \t]*)-[ \t]+\[([ xX])\][ \t]*(.*)$/;
+const TAG_RE = /<!--\s*plan:([^\s>]+)\s*-->/;
+const INDENT_PER_LEVEL = 2;
+
+/** Tabs become two spaces so depth is measured from spaces alone. */
+function expandTabs(line: string): string {
+  return line.replace(/\t/g, " ".repeat(INDENT_PER_LEVEL));
+}
+
+function depthOf(expandedLine: string): number {
+  const indent = /^[ \t]*/.exec(expandedLine)![0];
+  return Math.floor(expandTabs(indent).length / INDENT_PER_LEVEL);
+}
+
+export function parseTaskFile(path: string, raw: string): TaskFile {
+  const lines = raw.split(/\r?\n/);
+  const tasks: Task[] = [];
+  const stack: Task[] = [];
+
+  lines.forEach((line, index) => {
+    const match = ITEM_RE.exec(expandTabs(line));
+    if (!match) return;
+
+    const body = match[3] ?? "";
+    const tag = TAG_RE.exec(body);
+    const text = body.replace(TAG_RE, "").trim();
+    const depth = depthOf(line);
+
+    const task: Task = {
+      text,
+      done: (match[2] ?? " ").toLowerCase() === "x",
+      planRef: tag ? tag[1]! : null,
+      depth,
+      line: index,
+      children: [],
+    };
+
+    while (stack.length > 0 && stack[stack.length - 1]!.depth >= depth) stack.pop();
+    const parent = stack[stack.length - 1];
+    if (parent) parent.children.push(task);
+    else tasks.push(task);
+
+    stack.push(task);
+  });
+
+  return { path, lines, tasks };
+}
+
+export function createTaskFile(path: string): TaskFile {
+  return parseTaskFile(path, "# Tasks\n");
+}
+
+export function serializeTaskFile(file: TaskFile): string {
+  return file.lines.join("\n");
+}
+
+/** Depth-first order, the order the widget and `task_list` both use. */
+export function flatten(file: TaskFile): Task[] {
+  const out: Task[] = [];
+  const walk = (tasks: Task[]) => {
+    for (const task of tasks) {
+      out.push(task);
+      walk(task.children);
+    }
+  };
+  walk(file.tasks);
+  return out;
+}
+
+/**
+ * Find a task by plan ref (`§8#3`) or by its 1-based position in `flatten`.
+ * Numbers shift as the file changes, so a ref is the durable way to name one.
+ */
+export function findTask(file: TaskFile, ref: string): Task | undefined {
+  const wanted = ref.trim();
+  if (wanted === "") return undefined;
+
+  const byRef = flatten(file).find((task) => task.planRef === wanted);
+  if (byRef) return byRef;
+
+  if (/^\d+$/.test(wanted)) {
+    const index = Number(wanted);
+    const list = flatten(file);
+    if (index >= 1 && index <= list.length) return list[index - 1];
+  }
+  return undefined;
+}
+
+/**
+ * Rebuild the parsed tree after mutating `lines`.
+ *
+ * Every mutation must call this. A stale tree makes the next `findTask` miss a task that
+ * was just added, which silently turns a full seed into a partial one.
+ */
+function reparse(file: TaskFile): void {
+  file.tasks = parseTaskFile(file.path, file.lines.join("\n")).tasks;
+}
+
+export function setDone(file: TaskFile, ref: string, done: boolean): boolean {
+  const task = findTask(file, ref);
+  if (!task) return false;
+
+  const line = file.lines[task.line] ?? "";
+  const next = line.replace(/\[([ xX])\]/, done ? "[x]" : "[ ]");
+  if (next === line) return true;
+
+  file.lines[task.line] = next;
+  reparse(file);
+  return true;
+}
+
+export interface AddOptions {
+  text: string;
+  /** Plan origin to tag the new task with, for example `§8#1`. */
+  planRef?: string | null;
+  /** Plan ref of the parent. Omit to add at the top level. */
+  parentRef?: string | null;
+}
+
+export interface AddResult {
+  added: boolean;
+  reason?: string;
+  task?: Task;
+}
+
+/** Index of the last line belonging to this task or any of its descendants. */
+function lastLineOf(task: Task): number {
+  let last = task.line;
+  for (const child of task.children) last = Math.max(last, lastLineOf(child));
+  return last;
+}
+
+export function addTask(file: TaskFile, options: AddOptions): AddResult {
+  const text = options.text.trim();
+  if (text === "") return { added: false, reason: "empty text" };
+
+  const ref = options.planRef?.trim() || null;
+  if (ref && findTask(file, ref)) {
+    return { added: false, reason: `already present: ${ref}` };
+  }
+
+  let depth = 0;
+  let insertAt = file.lines.length;
+
+  if (options.parentRef) {
+    const parent = findTask(file, options.parentRef);
+    if (!parent) return { added: false, reason: `no such parent: ${options.parentRef}` };
+    depth = parent.depth + 1;
+    insertAt = lastLineOf(parent) + 1;
+  } else {
+    // Append after the last task so prose below the list keeps its place.
+    const all = flatten(file);
+    if (all.length > 0) insertAt = Math.max(...all.map((task) => lastLineOf(task))) + 1;
+  }
+
+  const line = `${" ".repeat(depth * INDENT_PER_LEVEL)}- [ ] ${text}${ref ? ` <!-- plan:${ref} -->` : ""}`;
+  file.lines.splice(insertAt, 0, line);
+  reparse(file);
+  return { added: true };
+}
+
+/** Done and total counts across every level. */
+export function progress(file: TaskFile): { done: number; total: number } {
+  const all = flatten(file);
+  return { done: all.filter((task) => task.done).length, total: all.length };
+}
+
+/** Plan refs already present, used to keep seeding idempotent. */
+export function presentRefs(file: TaskFile): Set<string> {
+  return new Set(flatten(file).map((task) => task.planRef).filter((ref): ref is string => ref !== null));
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "pi-comprehensive-tasks",
+  "version": "0.1.0",
+  "description": "A task tree in TODO.md for the pi coding agent, seeded from a pi-comprehensive-planning plan and collapsed as branches finish.",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "tasks",
+    "todo",
+    "checklist",
+    "planning",
+    "extension",
+    "skill"
+  ],
+  "license": "MIT",
+  "author": "Rizquuula",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rizquuula/pi-comprehensive-tasks.git"
+  },
+  "homepage": "https://github.com/rizquuula/pi-comprehensive-tasks#readme",
+  "bugs": {
+    "url": "https://github.com/rizquuula/pi-comprehensive-tasks/issues"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.ts"
+  },
+  "files": [
+    "extensions",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/skills/comprehensive-tasks/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: comprehensive-tasks
+description: Keep TODO.md honest while implementing a plan. Use when working through a plan's cycles, when a task turns out to be bigger or different than the plan said, when new work appears mid-flight, or when deciding whether a task is really done. Covers when to add a task rather than hold it in your head, when to complete one, when to reopen one, and how to file a task under the right slice.
+---
+
+# Comprehensive Tasks
+
+`TODO.md` is the live state of the work. `PLAN.md` is the intent.
+The plan is written once and reviewed. The task list changes as reality does.
+
+## The shape
+
+```markdown
+# Tasks
+
+- [ ] Slice A: the file format <!-- plan:§9#A -->
+  - [ ] parse the tree <!-- plan:§8#1 -->
+  - [x] toggle a child <!-- plan:§8#2 -->
+- [ ] Unassigned
+  - [ ] wiring only <!-- plan:§8#9 -->
+```
+
+Two spaces of indent per level. The `<!-- plan:… -->` comment records where the task came
+from, so a task can be traced back to its cycle. Keep the tag when you edit a line.
+
+## Workflow
+
+1. **Read the list before you start.** `task_list` gives the numbers and refs.
+2. **Work one task at a time**, in order. The list is ordered for a reason.
+3. **Complete a task the moment its done-criterion holds** — not when the code looks
+   right, but when the test in its Red column passes. `task_complete §8#3`.
+4. **Reopen it if you were wrong.** `task_complete` with `done: false`. A stale tick is
+   worse than an unticked box.
+5. **Add work you discover**, rather than holding it in your head. File it under the
+   slice it belongs to, or at the top level if it belongs to none.
+6. **Finish with a truthful list.** Every box ticked means every criterion in §1a holds.
+
+## Adding a task
+
+Use `task_add` when:
+
+- The plan did not cover something you had to do. Add it and keep going.
+- A cycle turned out to be two behaviours. Add the second rather than quietly widening
+  the first.
+- You found a follow-up worth keeping. If it is genuinely out of scope, put it in the
+  plan's §13 instead — the list is for work you are actually doing.
+
+Do not add a task for something you are about to do in the same breath. The list is a
+commitment, not a log.
+
+## Filing
+
+A task belongs under the slice that owns the files it touches. If nothing owns them, it
+belongs under `Unassigned` — that parent exists on purpose, and a visible mis-filing is
+better than a silent one.
+
+## Do / Don't
+
+| Do | Don't |
+|---|---|
+| Tick a task when its test passes | Tick it because the code is written |
+| Reopen a task you closed too early | Leave a wrong tick in place |
+| Add the work you discovered, with a short line | Keep three undone things in your head |
+| File a task under its slice | Dump everything at the top level |
+| Keep the `<!-- plan:… -->` tag when editing | Strip the tag and lose the trail |
+| Leave prose outside the list alone | Rewrite the whole file to change one box |