@mrclrchtr/supi-flow 0.10.1 → 0.11.0

package/extensions/tools/tndm-cli.ts

@@ -1,3 +1,5 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
 import { type Static, Type } from "typebox";
 import { StringEnum } from "@earendil-works/pi-ai";
 import { tndm, tndmJson } from "../cli.js";
@@ -8,6 +10,12 @@ export const actionEnum = StringEnum([
   "show",
   "list",
   "awareness",
+  "task_add",
+  "task_list",
+  "task_complete",
+  "task_remove",
+  "task_edit",
+  "task_set",
 ] as const);
 
 export const supi_tndm_cli_params = Type.Object({
@@ -71,6 +79,35 @@ export const supi_tndm_cli_params = Type.Object({
   against: Type.Optional(
     Type.String({ description: "Git ref to run awareness against (required for awareness)" }),
   ),
+
+  // Task params
+  task_title: Type.Optional(
+    Type.String({ description: "Task title (required for task_add)" }),
+  ),
+  task_number: Type.Optional(
+    Type.Number({ description: "Task number (required for task_complete, task_remove, task_edit)" }),
+  ),
+  task_files: Type.Optional(
+    Type.Array(Type.String(), { description: "File paths for the task" }),
+  ),
+  task_clear_files: Type.Optional(
+    Type.Boolean({ description: "Clear all file paths for the task" }),
+  ),
+  task_verification: Type.Optional(
+    Type.String({ description: "Verification command for the task" }),
+  ),
+  task_notes: Type.Optional(
+    Type.String({ description: "Extra notes for the task" }),
+  ),
+  task_detail: Type.Optional(
+    Type.String({ description: "Optional markdown body for a task detail doc" }),
+  ),
+  task_clear_detail: Type.Optional(
+    Type.Boolean({ description: "Explicitly detach a task detail doc link" }),
+  ),
+  task_json: Type.Optional(
+    Type.String({ description: "JSON array of tasks (required for task_set)" }),
+  ),
 });
 
 /**
@@ -82,6 +119,12 @@ export const supi_tndm_cli_params = Type.Object({
  *   show       → tndm ticket show <id> --json
  *   list       → tndm ticket list [--all] [--definition <state>] --json
  *   awareness  → tndm awareness --against <ref> --json
+ *   task_add       → tndm ticket task add <id> --title <title> [--file <path> ...] [--verification] [--notes] --json, optionally followed by task detail ensure + sync when task_detail is provided
+ *   task_list      → tndm ticket task list <id> --json
+ *   task_complete  → tndm ticket task complete <id> <number> --json
+ *   task_remove    → tndm ticket task remove <id> <number> --json
+ *   task_edit      → tndm ticket task edit <id> <number> [--title] [--file <path> ...] [--verification] [--notes] --json, optionally followed by task detail ensure/clear
+ *   task_set       → tndm ticket task set <id> --tasks <json> --json
  *   doc_create and sync are internal operations used by flow tools, not exposed here.
  */
 export type TndmCliParams = Static<typeof supi_tndm_cli_params>;
@@ -157,18 +200,24 @@ export async function executeTndmCli(params: TndmCliParams) {
       if (params.all) args.push("--all");
       if (params.definition) args.push("--definition", params.definition);
 
-      const result = await tndmJson<Record<string, unknown>[]>(args);
+      const rawResult = await tndmJson<
+        Record<string, unknown>[] | { schema_version?: number; tickets?: Record<string, unknown>[] }
+      >(args);
+      const envelope = Array.isArray(rawResult)
+        ? { schema_version: 1, tickets: rawResult }
+        : rawResult;
+      const tickets = Array.isArray(envelope.tickets) ? envelope.tickets : [];
       return {
         content: [
           {
             type: "text" as const,
             text:
-              result.length > 0
-                ? JSON.stringify(result, null, 2)
+              tickets.length > 0
+                ? JSON.stringify(envelope, null, 2)
                 : "No tickets found.",
           },
         ],
-        details: { action: "list", tickets: result },
+        details: { action: "list", tickets, envelope },
       };
     }
 
@@ -186,6 +235,142 @@ export async function executeTndmCli(params: TndmCliParams) {
         details: { action: "awareness", awareness: result },
       };
     }
+
+    // ── Task actions ────────────────────────────────────────────
+
+    case "task_add": {
+      if (!params.id) throw new Error("supi_tndm_cli: id is required for task_add");
+      if (!params.task_title) throw new Error("supi_tndm_cli: task_title is required for task_add");
+      const args: string[] = ["ticket", "task", "add", params.id, "--title", params.task_title];
+      for (const file of params.task_files ?? []) {
+        args.push("--file", file);
+      }
+      if (params.task_verification) args.push("--verification", params.task_verification);
+      if (params.task_notes) args.push("--notes", params.task_notes);
+      const result = await tndmJson<Record<string, unknown>>(args);
+      let finalResult = result;
+
+      if (params.task_detail !== undefined) {
+        const taskNumber = extractLatestTaskNumber(result);
+        const detailResult = await ensureTaskDetailDoc(params.id, taskNumber);
+        writeTaskDetailDoc(detailResult.path, taskNumber, params.task_title, params.task_detail);
+        await tndm(["ticket", "sync", params.id]);
+        finalResult = await loadTicket(params.id);
+      }
+
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(finalResult, null, 2) }],
+        details: { action: "task_add", ticketId: params.id, result: finalResult },
+      };
+    }
+
+    case "task_list": {
+      if (!params.id) throw new Error("supi_tndm_cli: id is required for task_list");
+      const result = await tndmJson<Record<string, unknown>[]>([
+        "ticket", "task", "list", params.id,
+      ]);
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+        details: { action: "task_list", ticketId: params.id, tasks: result },
+      };
+    }
+
+    case "task_complete": {
+      if (!params.id) throw new Error("supi_tndm_cli: id is required for task_complete");
+      if (params.task_number === undefined) throw new Error("supi_tndm_cli: task_number is required for task_complete");
+      const result = await tndmJson<Record<string, unknown>>([
+        "ticket", "task", "complete", params.id, String(params.task_number),
+      ]);
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+        details: { action: "task_complete", ticketId: params.id, taskNumber: params.task_number, result },
+      };
+    }
+
+    case "task_remove": {
+      if (!params.id) throw new Error("supi_tndm_cli: id is required for task_remove");
+      if (params.task_number === undefined) throw new Error("supi_tndm_cli: task_number is required for task_remove");
+      const result = await tndmJson<Record<string, unknown>>([
+        "ticket", "task", "remove", params.id, String(params.task_number),
+      ]);
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+        details: { action: "task_remove", ticketId: params.id, taskNumber: params.task_number, result },
+      };
+    }
+
+    case "task_edit": {
+      if (!params.id) throw new Error("supi_tndm_cli: id is required for task_edit");
+      if (params.task_number === undefined) throw new Error("supi_tndm_cli: task_number is required for task_edit");
+      if (params.task_detail !== undefined && params.task_clear_detail) {
+        throw new Error("supi_tndm_cli: task_detail and task_clear_detail cannot be used together");
+      }
+      const args: string[] = ["ticket", "task", "edit", params.id, String(params.task_number)];
+      if (params.task_title !== undefined) args.push("--title", params.task_title);
+      if (params.task_files !== undefined) {
+        if (params.task_files.length === 0) {
+          args.push("--clear-files");
+        } else {
+          for (const file of params.task_files) args.push("--file", file);
+        }
+      } else if (params.task_clear_files) {
+        args.push("--clear-files");
+      }
+      if (params.task_verification !== undefined) args.push("--verification", params.task_verification);
+      if (params.task_notes !== undefined) args.push("--notes", params.task_notes);
+
+      const hasManifestFieldChanges = args.length > 5;
+      const result = hasManifestFieldChanges
+        ? await tndmJson<Record<string, unknown>>(args)
+        : undefined;
+      let finalResult = result;
+
+      if (params.task_detail !== undefined) {
+        const detailResult = await ensureTaskDetailDoc(params.id, params.task_number);
+        const taskSnapshot = result ?? await loadTicket(params.id);
+        const taskTitle =
+          params.task_title ??
+          extractTaskTitle(taskSnapshot, params.task_number) ??
+          `Task ${params.task_number}`;
+        writeTaskDetailDoc(
+          detailResult.path,
+          params.task_number,
+          taskTitle,
+          params.task_detail,
+        );
+        await tndm(["ticket", "sync", params.id]);
+        finalResult = await loadTicket(params.id);
+      } else if (params.task_clear_detail) {
+        await tndmJson([
+          "ticket",
+          "task",
+          "detail",
+          "clear",
+          params.id,
+          String(params.task_number),
+        ]);
+        finalResult = await loadTicket(params.id);
+      } else if (!finalResult) {
+        finalResult = await tndmJson<Record<string, unknown>>(args);
+      }
+
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(finalResult, null, 2) }],
+        details: { action: "task_edit", ticketId: params.id, taskNumber: params.task_number, result: finalResult },
+      };
+    }
+
+    case "task_set": {
+      if (!params.id) throw new Error("supi_tndm_cli: id is required for task_set");
+      if (!params.task_json) throw new Error("supi_tndm_cli: task_json is required for task_set");
+      const result = await tndmJson<Record<string, unknown>>([
+        "ticket", "task", "set", params.id, "--tasks", params.task_json,
+      ]);
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+        details: { action: "task_set", ticketId: params.id, result },
+      };
+    }
   }
 }
 
@@ -201,3 +386,63 @@ function addOptionalFlags(
     args.push(`--${flagName}`, String(value));
   }
 }
+
+// NOTE: This assumes task numbers are auto-incremented (1, 2, 3…). If task_add ever
+// supports explicit task numbering, this will need to use a more precise source
+// of truth (e.g. a top-level `task_number` field in the JSON response).
+function extractLatestTaskNumber(result: Record<string, unknown>): number {
+  const tasks = extractTasks(result);
+  const numbers = tasks
+    .map((task) => task.number)
+    .filter((value): value is number => typeof value === "number");
+
+  if (numbers.length === 0) {
+    throw new Error("supi_tndm_cli: task_add did not return a task list; cannot attach task detail");
+  }
+
+  return Math.max(...numbers);
+}
+
+function extractTaskTitle(result: Record<string, unknown>, taskNumber: number): string | undefined {
+  return extractTasks(result).find((task) => task.number === taskNumber)?.title;
+}
+
+function extractTasks(result: Record<string, unknown>): Array<{ number?: number; title?: string }> {
+  if (Array.isArray(result.tasks)) {
+    return result.tasks.filter(
+      (task): task is { number?: number; title?: string } => typeof task === "object" && task !== null,
+    );
+  }
+
+  const ticket = result.ticket;
+  if (typeof ticket === "object" && ticket !== null) {
+    const state = (ticket as { state?: unknown }).state;
+    if (typeof state === "object" && state !== null && Array.isArray((state as { tasks?: unknown }).tasks)) {
+      return ((state as { tasks: unknown[] }).tasks).filter(
+        (task): task is { number?: number; title?: string } => typeof task === "object" && task !== null,
+      );
+    }
+  }
+
+  return [];
+}
+
+async function loadTicket(id: string): Promise<Record<string, unknown>> {
+  return tndmJson<Record<string, unknown>>(["ticket", "show", id]);
+}
+
+async function ensureTaskDetailDoc(id: string, taskNumber: number): Promise<{ path: string }> {
+  return tndmJson<{ path: string }>([
+    "ticket",
+    "task",
+    "detail",
+    "ensure",
+    id,
+    String(taskNumber),
+  ]);
+}
+
+function writeTaskDetailDoc(path: string, taskNumber: number, title: string, detail: string): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `# Task ${taskNumber}: ${title}\n\n${detail}\n`, "utf-8");
+}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@mrclrchtr/supi-flow",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "private": false,
-  "description": "PI extension for spec-driven workflow (brainstorm → plan → apply → archive) with TNDM ticket coordination, custom tools, and 5 auto-discovered skills",
+  "description": "PI extension for spec-driven workflow (brainstorm → plan → apply → archive) with TNDM ticket coordination, 6 custom tools, and 5 auto-discovered skills",
   "keywords": [
     "pi-package",
     "pi-extension",
@@ -30,9 +30,9 @@
     "README.md"
   ],
   "devDependencies": {
-    "@earendil-works/pi-ai": "0.74.0",
-    "@earendil-works/pi-coding-agent": "0.74.0",
-    "@types/node": "25.7.0",
+    "@earendil-works/pi-ai": "0.75.1",
+    "@earendil-works/pi-coding-agent": "0.75.1",
+    "@types/node": "25.8.0",
     "vitest": "4.1.6"
   }
 }

package/skills/supi-flow-apply/SKILL.md

@@ -15,15 +15,17 @@ If you haven't run the verification command for this task, you cannot check it o
 
 ## Step 1: Find the plan
 
-- A TNDM-ID was set during plan phase. Read the ticket metadata first:
-  `supi_tndm_cli { action: "show", id: "<ID>" }` — find the registered `plan` document path, then read `plan.md` from that path.
-  Then mark the ticket as in progress and move the flow tag:
-  `supi_tndm_cli { action: "update", id: "<ID>", status: "in_progress", add_tags: "flow:applying", remove_tags: "flow:planned" }`
+- A TNDM-ID was set during plan phase. Start apply with:
+  `supi_flow_apply { ticket_id: "<ID>" }`
+  This loads the approved overview from `content.md`, returns the structured task list with status, title, files, verification, and any linked `detail_path`, moves `flow:planned` tickets into `status=in_progress` with `flow:applying`, and preserves the current `in_progress` or `blocked` status for already-applying tickets.
+- Read the returned overview before starting work. If a task has a linked task doc (`detail_path`), read that task doc before implementing so you do not miss task detail captured outside the manifest.
+- If `supi_flow_apply` reports a missing overview, empty task manifest, or invalid lifecycle state, stop and resolve that gap before editing.
+- If `supi_flow_apply` returns `status: "blocked"`, stop and resolve the blocker before resuming implementation.
 - If no plan is available: ask which change to implement.
 
 ## Step 2: Review the plan critically
 
-Read the whole plan before starting.
+Read the whole plan before starting, including the approved overview loaded by `supi_flow_apply`.
 
 Raise questions before editing if:
 
@@ -40,7 +42,7 @@ Do not start implementation until those concerns are resolved.
 For each unchecked task, in order:
 
 1. Announce which task you are working on.
-2. Follow the task as written.
+2. Follow the task as written. If the task references a linked task doc via `detail_path`, read it first and treat it as part of the task definition.
 3. Run the verification for that task and read the result carefully.
 4. If verification passes: call `supi_flow_complete_task { ticket_id: "<ID>", task_number: <N> }` to check the task off in the ticket.
 5. If verification fails: stop, diagnose, fix, and re-verify before moving on.

package/skills/supi-flow-archive/SKILL.md

@@ -18,7 +18,7 @@ Before claiming the change is done, the docs are accurate, or the ticket can be
 ## Step 1: Find the change
 
 - A TNDM-ID was set during plan phase. Read the ticket metadata first:
-  `supi_tndm_cli { action: "show", id: "<ID>" }` — inspect `content_path` and the registered documents, then read `content.md` for the approved design and `plan.md` for the executed checklist.
+  `supi_tndm_cli { action: "show", id: "<ID>" }` — inspect `content_path` and the registered documents, then read `content.md` for the approved design and list tasks with `supi_tndm_cli { action: "task_list", id: "<ID>" }`.
 - Archive runs only when a ticket exists. Trivial flows that skipped the ticket close out directly in conversation — do not run archive.
 - If nothing is clear: ask which change to archive.
 
@@ -66,7 +66,7 @@ Do not assume documentation is correct just because it sounds right.
 ## Step 5: Close out
 
 - Call `supi_flow_close { ticket_id: "<ID>", verification_results: "..." }` with the full verification evidence.
-  This will set status=done, tags=flow:done, and store verification results in archive.md.
+  `supi_flow_close` requires nonblank `verification_results`, refuses to close while structured tasks remain incomplete, then sets `status=done`, tags=`flow:done`, and stores the evidence in `archive.md`.
 - There is no ticket-less closeout.
 
 ## Step 6: Commit or finish

package/skills/supi-flow-brainstorm/SKILL.md

@@ -74,9 +74,9 @@ Keep each section proportional to the complexity. A small change may only need a
 
 After approval:
 
-- **Default to conversation-first.** The design can live in the chat for small, single-session work.
-- **Offer saving to a ticket** when the work is larger, likely multi-session, or would benefit from a durable reference.
-- If a ticket exists, save the design to the ticket's canonical `content.md` via `supi_tndm_cli { action: "update", id: "<ID>", content: "<outcome>" }`.
+- **Default to conversation-first for trivial work.** Small single-session changes can keep the design in chat and implement directly without a ticket.
+- **Create a ticket for non-trivial work.** When the change is multi-file, needs tests/docs, spans multiple steps, or is likely multi-session, call `supi_flow_start` and persist the approved design in `content.md`.
+- If a ticket exists, save the design to the ticket's canonical `content.md` via `supi_tndm_cli { action: "update", id: "<ID>", content: "<outcome>" }`. During plan phase, keep task authoring separate: the overview stays in `content.md`, and executable tasks are later authored one at a time via `supi_flow_task`.
 - **Retroactive escalation:** if a trivial change grows in scope mid-implementation, stop, create a retroactive ticket via `supi_flow_start`, and store a summary of completed work + new scope.
 
 ## Self-review

package/skills/supi-flow-plan/SKILL.md

@@ -33,9 +33,21 @@ Before writing tasks, list which files will be created or modified and what each
 - Follow existing codebase patterns.
 - Include doc targets when the change affects user-facing or maintainer-facing behavior.
 
-## Step 5: Write ordered tasks
+## Step 5: Write the overview, then define ordered tasks separately
 
-A good plan is broken into small, verifiable tasks. For each task, include:
+The approved overview belongs in `content.md`. It can be pure design / plan prose and may contain zero tasks.
+
+After the overview is approved and persisted, define executable tasks separately in `state.toml`. Start by inspecting the current manifest with `supi_tndm_cli { action: "task_list", id: "<ID>" }`.
+
+For the normal path, use `supi_flow_task` to add, edit, or remove **one task at a time** instead of building raw `task_json` or managing `detail_path` manually:
+
+- **Empty ticket / no tasks yet:** create the manifest with repeated `supi_flow_task { operation: "add", ... }` calls.
+- **Replan / tasks already exist:** reconcile the existing manifest to the new final shape.
+  - same task, new details → `supi_flow_task { operation: "edit", task_number: <N>, ... }`
+  - task no longer belongs in the plan → `supi_flow_task { operation: "remove", task_number: <N> }`
+  - genuinely new task → `supi_flow_task { operation: "add", ... }`
+
+For each task, include:
 
 - the goal
 - exact file paths
@@ -45,18 +57,9 @@ A good plan is broken into small, verifiable tasks. For each task, include:
 
 Use enough detail that an agent can execute without guessing, but do not force huge code blocks into every step.
 
-**Task numbering convention**: Tasks must be numbered sequentially starting at 1:
-
-```markdown
-- [ ] **Task 1**: Create the CLI helper module
-  - File: `extensions/cli.ts`
-  - Verification: `pnpm exec tsc --noEmit`
-- [ ] **Task 2**: Register the tools
-  - File: `extensions/tools/tndm-cli.ts`
-  - Verification: `pnpm exec vitest run`
-```
+**Task numbering convention**: On an empty ticket, adds through `supi_flow_task` start at 1 and increase sequentially. On a ticket that already has tasks, `add` returns the next available task number. Always use the returned task number for later edits, removals, and completion.
 
-The task number must be in the `**Task N**` format so `supi_flow_complete_task` can find and check it off.
+Use headline-only tasks when the title is enough. If a task needs real implementation detail or notices, pass `detail` markdown through `supi_flow_task` so it creates or updates the canonical `tasks/task-XX.md` task doc automatically.
 
 ## TDD by default
 
@@ -112,6 +115,6 @@ Fix issues inline before handing off.
 
 Write the plan in the lightest form that will still survive execution:
 
-- **If a ticket exists:** use `supi_flow_plan { ticket_id: "<ID>", plan_content: "..." }` to store the executable checklist in `plan.md` while leaving `content.md` as the approved design summary.
+- **If a ticket exists:** use `supi_flow_plan { ticket_id: "<ID>", plan_content: "..." }` to store the approved overview in `content.md`. Then list the current tasks. If the manifest is empty, build it with repeated `supi_flow_task { operation: "add", ... }` calls. If tasks already exist, reconcile them to the new final plan with `supi_flow_task` edit/remove/add operations. Keep `supi_tndm_cli` task_* actions as lower-level escape hatches for advanced/manual repair cases.
 - **If no ticket exists:** default to conversation-first. Offer saving to a ticket or file if the work is larger or likely multi-session.
 - Close with: `Plan ready. Review it and approve before we start. Then run /supi-flow-apply TNDM-XXXXXX.`