@jwilger/pi-development-system 0.55.0 → 0.56.0

package/extensions/development-system.ts

@@ -30,6 +30,7 @@ import { createRouteTaskTool } from "../src/state/route-task-tool.ts";
 import { createSessionState } from "../src/state/session-state.ts";
 import { registerTestEvidence } from "../src/state/test-evidence.ts";
 import piSubagent from "../src/subagents/index.ts";
+import { createWorkItemTool } from "../src/tracker/work-item-tool.ts";
 
 const nonNegotiables = readFileSync(
   new URL("../principles/NON-NEGOTIABLES.md", import.meta.url),
@@ -142,6 +143,7 @@ export function createDevelopmentSystem(pi: ExtensionAPI) {
   pi.registerTool(createRouteTaskTool({ jev: (ctx) => jevHolder.forContext(ctx) }));
   pi.registerTool(createIntakeTool({ state, jev: (ctx) => jevHolder.forContext(ctx) }));
   pi.registerTool(createTaskCheckTool({ jev: (ctx) => jevHolder.forContext(ctx) }));
+  pi.registerTool(createWorkItemTool({ exec }));
   const reviewDeps = {
     state,
     jev: (ctx: ExtensionContext) => jevHolder.forContext(ctx),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwilger/pi-development-system",
-  "version": "0.55.0",
+  "version": "0.56.0",
   "description": "A pi extension package representing a seasoned approach to software development using a full AI SDLC.",
   "keywords": [
     "pi-package"

package/prompts/devsys-plan.md

@@ -0,0 +1,12 @@
+---
+description: Write the plan file for sized work, one task record per slice, and hand it to a goal
+argument-hint: "<slug> [what the plan covers]"
+---
+Write the plan for the current work with the work-intake-and-slicing skill.
+
+1. Slug and scope come from: $ARGUMENTS. If the slug is missing, derive one from the active slice and say which you chose.
+2. Write `docs/plan/<slug>.md` with these sections: Goal and why; Constraints (what must not change); Increments, each shippable on its own and small enough to release; for every task a task record in the format `## <id> — <title>` with **Goal**, **Files**, **Interfaces**, **First failing test**, **Steps**, **Run**, **Expected**, **Out of scope**; a Progress checklist with one box per increment.
+3. Write each task so that someone who sees only that task could finish it. Never write `TBD`.
+4. Run `devsys_task_check` on every task record you wrote and fix each one until it says ready. Split any that come back too-big.
+5. If a `create_goal` tool exists in this session, call it with the objective "complete docs/plan/<slug>.md honouring its Constraints and Progress checklist". Otherwise tell the user the plan path so they can start a goal on it. Do not depend on any goal tool's file format.
+6. Stop and ask the user to review the plan before any implementation starts.

package/skills/work-intake-and-slicing/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: work-intake-and-slicing
+description: Size new work, choose the planning artifacts it deserves, and cut it into task records a weaker implementer can finish. Use when starting any piece of work, when asked to plan, when a task feels too big, or before handing work to an implementer subagent.
+---
+
+# Work intake and slicing
+
+Planning is proportional: the size of the work decides the paperwork. A one-line fix does not get a product brief, and a new capability does not get coded from a sentence.
+
+## Size first
+
+Ask these in order and stop at the first yes:
+
+1. Does it change what the product is for, who uses it, or how it earns its place? That is a `product`.
+2. Does it add something a user can newly do, across several parts of the system? That is a `capability`.
+3. Does it change existing behaviour in one area? That is a `change`.
+4. Otherwise it is a `fix`.
+
+`/devsys-start` proposes a size with Jev and asks you to confirm. If you disagree, change it; the size is a judgement, not a rule.
+
+## Artifacts follow size
+
+- `fix`: a task record.
+- `change`: task record, review, an ADR if a decision is hard to reverse.
+- `capability`: add a brief-lite, journeys, an event model, and optionally lens review.
+- `product`: the full set, including brief, decision register and architecture.
+
+Skipping a recommended artifact is allowed and recorded: `devsys_record_departure` with gate `artifact.skipped:<artifact>` and the reason. The event model and architecture are never blocked by a gate; they are recommendations you accept or decline on the record.
+
+## A plan longer than the code has written the code
+
+If the plan spells out every line, it has become the implementation, and a reviewer cannot tell design from typing. A task record names files, interfaces, the first failing test and small steps. It does not contain the function bodies.
+
+## One slice, one clean context
+
+- Cut work into slices that each ship and release on their own.
+- Do one slice per clean context. When a slice is done and released, start the next from its task record, not from the memory of the last.
+- The implementer sees only its task record. If it needs something not in the record, the record is incomplete: fix the record, do not paste the conversation.
+
+## Task records
+
+Format: `## <id> — <title>` then **Goal**, **Files**, **Interfaces**, **First failing test**, **Steps** (3 to 7, each reviewable alone), **Run**, **Expected**, **Out of scope**.
+
+- Goal is one observable sentence.
+- Run is a command and Expected is its concrete result.
+- No `TBD`.
+- If describing the first failing test needs two tests, it is two tasks.
+
+Run `devsys_task_check` on each record. `needs-detail` names what to sharpen; `too-big` means split before anyone implements.
+
+## Where work items live
+
+Use `devsys_work_item` for the backlog. It reads `[tracker] kind` from `.development-system.toml`: `repo-files` (default, `work/backlog.md` and `work/items/<id>.md`) or `github` issues. Jira and Linear are configurable but not implemented yet.
+
+## Handing off
+
+`/devsys-plan <slug>` writes `docs/plan/<slug>.md` in this structure and, when a goal tool is available, starts a goal to complete it. Review the plan with the user before any implementation.

package/src/tracker/github.ts

@@ -0,0 +1,187 @@
+import type { Exec } from "../core/exec.ts";
+import { ok } from "../core/result.ts";
+import {
+  type ItemFilter,
+  type NewWorkItem,
+  type Tracker,
+  type TrackerResult,
+  trackerError,
+  type WorkItem,
+  type WorkItemPatch,
+  type WorkStatus,
+} from "./types.ts";
+
+const FIELDS = "number,title,body,state,labels,comments";
+const IN_PROGRESS = "in-progress";
+const ISSUE_NUMBER = /^[1-9][0-9]*$/;
+const STATE_ARG = { open: "open", "in-progress": "open", done: "closed" } as const;
+
+type GhIssue = {
+  number: number;
+  title: string;
+  state: string;
+  body?: string | null;
+  labels?: { name: string }[];
+  comments?: { body: string }[];
+};
+
+const isIssue = (value: unknown): value is GhIssue =>
+  typeof value === "object" &&
+  value !== null &&
+  "number" in value &&
+  typeof value.number === "number" &&
+  "title" in value &&
+  typeof value.title === "string" &&
+  "state" in value &&
+  typeof value.state === "string";
+
+const statusOf = (state: string, labels: readonly string[]): WorkStatus => {
+  if (state === "CLOSED") return "done";
+  return labels.includes(IN_PROGRESS) ? "in-progress" : "open";
+};
+
+const toItem = (issue: GhIssue): WorkItem => {
+  const names = (issue.labels ?? []).map((l) => l.name);
+  return {
+    id: String(issue.number),
+    title: issue.title,
+    body: issue.body ?? "",
+    status: statusOf(issue.state, names),
+    labels: names.filter((n) => n !== IN_PROGRESS),
+    comments: (issue.comments ?? []).map((c) => c.body),
+  };
+};
+
+const parseIssue = (text: string): GhIssue | undefined => {
+  try {
+    const value: unknown = JSON.parse(text);
+    return isIssue(value) ? value : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+const parseIssues = (text: string): GhIssue[] | undefined => {
+  try {
+    const value: unknown = JSON.parse(text);
+    return Array.isArray(value) && value.every(isIssue) ? value : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+export type GithubTrackerDeps = {
+  readonly exec: Exec;
+  readonly cwd: string;
+  /** `owner/name`; omitted means the repository of the working directory. */
+  readonly repo?: string;
+};
+
+type Gh = (args: string[]) => Promise<TrackerResult<string>>;
+
+const notNumber = (id: string) => trackerError(`"${id}" is not a GitHub issue number`);
+
+const bindGh =
+  (deps: GithubTrackerDeps): Gh =>
+  async (args) => {
+    const repoArgs = deps.repo === undefined ? [] : ["--repo", deps.repo];
+    const result = await deps.exec("gh", [...args, ...repoArgs], {
+      cwd: deps.cwd,
+      timeout: 30_000,
+    });
+    if (result.code === 0) return ok(result.stdout);
+    const why = result.stderr.trim() || `exit ${result.code}`;
+    return trackerError(`gh ${args.slice(0, 2).join(" ")} failed: ${why}`);
+  };
+
+const view = async (gh: Gh, id: string): Promise<TrackerResult<WorkItem>> => {
+  if (!ISSUE_NUMBER.test(id)) return notNumber(id);
+  const out = await gh(["issue", "view", id, "--json", FIELDS]);
+  if (!out.ok) return out;
+  const parsed = parseIssue(out.value);
+  return parsed === undefined
+    ? trackerError(`gh issue view ${id}: unexpected output`)
+    : ok(toItem(parsed));
+};
+
+const listIssues = async (gh: Gh, filter: ItemFilter): Promise<TrackerResult<WorkItem[]>> => {
+  const state = filter.status === undefined ? "all" : STATE_ARG[filter.status];
+  const out = await gh(["issue", "list", "--state", state, "--limit", "200", "--json", FIELDS]);
+  if (!out.ok) return out;
+  const parsed = parseIssues(out.value);
+  if (parsed === undefined) return trackerError("gh issue list: unexpected output");
+  const items = parsed.map(toItem);
+  return ok(filter.status === undefined ? items : items.filter((i) => i.status === filter.status));
+};
+
+const createIssue = async (gh: Gh, input: NewWorkItem): Promise<TrackerResult<WorkItem>> => {
+  const labels = (input.labels ?? []).flatMap((l) => ["--label", l]);
+  const out = await gh([
+    "issue",
+    "create",
+    "--title",
+    input.title,
+    "--body",
+    input.body ?? "",
+    ...labels,
+  ]);
+  if (!out.ok) return out;
+  const number = /\/issues\/(\d+)\s*$/.exec(out.value)?.[1];
+  if (number === undefined) return trackerError("gh issue create: no issue URL in the output");
+  return view(gh, number);
+};
+
+const applyStatus = async (
+  gh: Gh,
+  id: string,
+  status: WorkStatus,
+): Promise<TrackerResult<string>> => {
+  if (status === "done") return gh(["issue", "close", id]);
+  // Reopening an issue that is already open fails; only the label change below decides the result.
+  await gh(["issue", "reopen", id]);
+  const flag = status === "in-progress" ? "--add-label" : "--remove-label";
+  return gh(["issue", "edit", id, flag, IN_PROGRESS]);
+};
+
+const editArgs = (patch: WorkItemPatch): string[] => [
+  ...(patch.title === undefined ? [] : ["--title", patch.title]),
+  ...(patch.body === undefined ? [] : ["--body", patch.body]),
+  ...(patch.labels ?? []).flatMap((label) => ["--add-label", label]),
+];
+
+const updateIssue = async (
+  gh: Gh,
+  id: string,
+  patch: WorkItemPatch,
+): Promise<TrackerResult<WorkItem>> => {
+  if (!ISSUE_NUMBER.test(id)) return notNumber(id);
+  const edits = editArgs(patch);
+  if (edits.length > 0) {
+    const edited = await gh(["issue", "edit", id, ...edits]);
+    if (!edited.ok) return edited;
+  }
+  if (patch.status !== undefined) {
+    const changed = await applyStatus(gh, id, patch.status);
+    if (!changed.ok) return changed;
+  }
+  return view(gh, id);
+};
+
+const commentIssue = async (gh: Gh, id: string, body: string): Promise<TrackerResult<void>> => {
+  if (!ISSUE_NUMBER.test(id)) return notNumber(id);
+  const out = await gh(["issue", "comment", id, "--body", body]);
+  return out.ok ? ok(undefined) : out;
+};
+
+/** Work items as GitHub issues, through the `gh` CLI. Every value is its own argument, never shell text. */
+export function createGithubTracker(deps: GithubTrackerDeps): Tracker {
+  const gh = bindGh(deps);
+  return {
+    kind: "github",
+    list: (filter) => listIssues(gh, filter),
+    get: (id) => view(gh, id),
+    create: (input) => createIssue(gh, input),
+    update: (id, patch) => updateIssue(gh, id, patch),
+    comment: (id, body) => commentIssue(gh, id, body),
+  };
+}

package/src/tracker/item-format.ts

@@ -0,0 +1,67 @@
+import { ok } from "../core/result.ts";
+import {
+  type TrackerResult,
+  trackerError,
+  WORK_STATUSES,
+  type WorkItem,
+  type WorkStatus,
+} from "./types.ts";
+
+const COMMENTS = "\n## Comments\n";
+
+export const renderItem = (item: WorkItem): string => {
+  const comments = item.comments.map((c) => `\n### Comment\n\n${c}\n`).join("");
+  return [
+    `# ${item.title}`,
+    "",
+    `Status: ${item.status}`,
+    `Labels: ${item.labels.join(", ")}`,
+    "",
+    item.body,
+    COMMENTS + comments,
+  ].join("\n");
+};
+
+const isStatus = (value: string): value is WorkStatus =>
+  (WORK_STATUSES as readonly string[]).includes(value);
+
+const commentsOf = (section: string): string[] =>
+  section
+    .split(/^### Comment\n\n/m)
+    .slice(1)
+    .map((c) => c.replace(/\n$/, "").replace(/\n$/, ""));
+
+export const parseItem = (id: string, text: string): TrackerResult<WorkItem> => {
+  const marker = text.lastIndexOf(COMMENTS);
+  const main = marker < 0 ? text : text.slice(0, marker);
+  const comments = marker < 0 ? [] : commentsOf(text.slice(marker + COMMENTS.length));
+  const head = /^# (.+)\n\nStatus: (.*)\nLabels: (.*)\n\n?/.exec(main);
+  if (head === null)
+    return trackerError(`work item ${id}: expected "# title", Status and Labels lines`);
+  const [whole, title = "", status = "", labels = ""] = head;
+  if (!isStatus(status)) {
+    return trackerError(
+      `work item ${id}: unknown status "${status}" (use ${WORK_STATUSES.join(", ")})`,
+    );
+  }
+  return ok({
+    id,
+    title,
+    body: main.slice(whole.length).replace(/\n$/, ""),
+    status,
+    labels: labels === "" ? [] : labels.split(", "),
+    comments,
+  });
+};
+
+const RANK: Record<WorkStatus, number> = { "in-progress": 1, open: 0, done: 2 };
+
+/** Derived from the item files on every change, so it cannot drift from them. */
+export const renderBacklog = (items: readonly WorkItem[]): string => {
+  const ordered = items.toSorted((a, b) => RANK[a.status] - RANK[b.status]);
+  const lines = ordered.map((i) => {
+    const note = i.status === "in-progress" ? " (in-progress)" : "";
+    return `- [${i.status === "done" ? "x" : " "}] ${i.id} — ${i.title}${note}`;
+  });
+  return ["# Backlog", "", ...lines, ""].join("\n");
+};

package/src/tracker/repo-files.ts

@@ -0,0 +1,133 @@
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { ok } from "../core/result.ts";
+import { parseItem, renderBacklog, renderItem } from "./item-format.ts";
+import {
+  type ItemFilter,
+  type NewWorkItem,
+  type Tracker,
+  type TrackerResult,
+  trackerError,
+  type WorkItem,
+  type WorkItemPatch,
+} from "./types.ts";
+
+const ID = /^[a-z0-9][a-z0-9-]*$/;
+const ID_MAX = 60;
+
+const slugOf = (title: string): string =>
+  title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+/, "")
+    .slice(0, ID_MAX)
+    .replace(/-+$/, "");
+
+const isMissing = (cause: unknown): boolean =>
+  typeof cause === "object" && cause !== null && "code" in cause && cause.code === "ENOENT";
+
+const itemsDir = (root: string): string => join(root, "work", "items");
+const fileOf = (root: string, id: string): string => join(itemsDir(root), `${id}.md`);
+const byCodeUnit = (a: string, b: string): number => Number(a > b) - Number(a < b);
+
+const describe = (cause: unknown): string =>
+  cause instanceof Error ? cause.message : String(cause);
+
+const readItem = async (root: string, id: string): Promise<TrackerResult<WorkItem>> => {
+  if (!ID.test(id)) return trackerError(`work item "${id}": not a valid id`);
+  try {
+    return parseItem(id, await readFile(fileOf(root, id), "utf8"));
+  } catch (cause) {
+    if (isMissing(cause)) return trackerError(`work item "${id}" does not exist`);
+    return trackerError(`work item "${id}": ${describe(cause)}`);
+  }
+};
+
+const itemIds = async (root: string): Promise<string[]> => {
+  try {
+    const files = await readdir(itemsDir(root));
+    return files.flatMap((f) => (f.endsWith(".md") ? [f.slice(0, -3)] : []));
+  } catch (cause) {
+    if (isMissing(cause)) return [];
+    throw cause;
+  }
+};
+
+const readAll = async (root: string): Promise<TrackerResult<WorkItem[]>> => {
+  const items: WorkItem[] = [];
+  for (const id of (await itemIds(root)).toSorted(byCodeUnit)) {
+    const item = await readItem(root, id);
+    if (!item.ok) return item;
+    items.push(item.value);
+  }
+  return ok(items);
+};
+
+const save = async (root: string, item: WorkItem): Promise<TrackerResult<WorkItem>> => {
+  await mkdir(itemsDir(root), { recursive: true });
+  await writeFile(fileOf(root, item.id), renderItem(item));
+  const items = await readAll(root);
+  if (!items.ok) return items;
+  await writeFile(join(root, "work", "backlog.md"), renderBacklog(items.value));
+  return ok(item);
+};
+
+const freshId = async (root: string, title: string): Promise<string | undefined> => {
+  const base = slugOf(title);
+  if (base === "") return undefined;
+  const taken = new Set(await itemIds(root));
+  let id = base;
+  for (let n = 2; taken.has(id); n++) id = `${base}-${n}`;
+  return id;
+};
+
+const listItems = async (root: string, filter: ItemFilter): Promise<TrackerResult<WorkItem[]>> => {
+  const items = await readAll(root);
+  if (!items.ok || filter.status === undefined) return items;
+  return ok(items.value.filter((i) => i.status === filter.status));
+};
+
+const createItem = async (root: string, input: NewWorkItem): Promise<TrackerResult<WorkItem>> => {
+  const id = await freshId(root, input.title);
+  if (id === undefined) return trackerError("a work item title needs letters or digits");
+  return save(root, {
+    id,
+    title: input.title,
+    body: input.body ?? "",
+    status: "open",
+    labels: input.labels ?? [],
+    comments: [],
+  });
+};
+
+const updateItem = async (
+  root: string,
+  id: string,
+  patch: WorkItemPatch,
+): Promise<TrackerResult<WorkItem>> => {
+  const current = await readItem(root, id);
+  return current.ok ? save(root, { ...current.value, ...patch }) : current;
+};
+
+const commentItem = async (
+  root: string,
+  id: string,
+  body: string,
+): Promise<TrackerResult<void>> => {
+  const current = await readItem(root, id);
+  if (!current.ok) return current;
+  const saved = await save(root, { ...current.value, comments: [...current.value.comments, body] });
+  return saved.ok ? ok(undefined) : saved;
+};
+
+/** Work items as markdown files in the repo: `work/items/<id>.md`, with a derived `work/backlog.md`. */
+export function createRepoFilesTracker(root: string): Tracker {
+  return {
+    kind: "repo-files",
+    list: (filter) => listItems(root, filter),
+    get: (id) => readItem(root, id),
+    create: (input) => createItem(root, input),
+    update: (id, patch) => updateItem(root, id, patch),
+    comment: (id, body) => commentItem(root, id, body),
+  };
+}

package/src/tracker/select.ts

@@ -0,0 +1,34 @@
+import type { Exec } from "../core/exec.ts";
+import { ok } from "../core/result.ts";
+import type { DevsysConfig } from "../state/config.ts";
+import { createGithubTracker } from "./github.ts";
+import { createRepoFilesTracker } from "./repo-files.ts";
+import { type Tracker, type TrackerResult, trackerError } from "./types.ts";
+
+/** The adapter named by `[tracker] kind`. Jira and Linear are accepted in config but not built yet. */
+export function createTracker(deps: {
+  tracker: DevsysConfig["tracker"];
+  exec: Exec;
+  cwd: string;
+}): TrackerResult<Tracker> {
+  const { tracker, exec, cwd } = deps;
+  switch (tracker.kind) {
+    case "repo-files":
+      return ok(createRepoFilesTracker(cwd));
+    case "github":
+      return ok(
+        createGithubTracker({
+          exec,
+          cwd,
+          ...(tracker.repo === undefined ? {} : { repo: tracker.repo }),
+        }),
+      );
+    case "jira":
+    case "linear":
+      return trackerError(
+        `tracker kind "${tracker.kind}" is not implemented yet; use "repo-files" or "github" in .development-system.toml`,
+      );
+    default:
+      return trackerError(`unknown tracker kind "${String(tracker.kind satisfies never)}"`);
+  }
+}

package/src/tracker/types.ts

@@ -0,0 +1,42 @@
+import type { Result } from "../core/result.ts";
+
+export const WORK_STATUSES = ["open", "in-progress", "done"] as const;
+export type WorkStatus = (typeof WORK_STATUSES)[number];
+
+export type WorkItem = {
+  readonly id: string;
+  readonly title: string;
+  readonly body: string;
+  readonly status: WorkStatus;
+  readonly labels: readonly string[];
+  readonly comments: readonly string[];
+};
+
+export type NewWorkItem = {
+  readonly title: string;
+  readonly body?: string;
+  readonly labels?: readonly string[];
+};
+
+export type WorkItemPatch = Partial<Pick<WorkItem, "title" | "body" | "status" | "labels">>;
+
+export type ItemFilter = { readonly status?: WorkStatus };
+
+export type TrackerError = { readonly kind: "tracker-error"; readonly message: string };
+
+export type TrackerResult<T> = Result<T, TrackerError>;
+
+/** Where work items live. One adapter per `[tracker] kind`; callers never see the backend. */
+export interface Tracker {
+  readonly kind: string;
+  list(filter: ItemFilter): Promise<TrackerResult<WorkItem[]>>;
+  get(id: string): Promise<TrackerResult<WorkItem>>;
+  create(item: NewWorkItem): Promise<TrackerResult<WorkItem>>;
+  update(id: string, patch: WorkItemPatch): Promise<TrackerResult<WorkItem>>;
+  comment(id: string, body: string): Promise<TrackerResult<void>>;
+}
+
+export const trackerError = (message: string): { ok: false; error: TrackerError } => ({
+  ok: false,
+  error: { kind: "tracker-error", message },
+});

package/src/tracker/work-item-tool.ts

@@ -0,0 +1,141 @@
+import type { ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { type Static, Type } from "typebox";
+import type { Exec } from "../core/exec.ts";
+import { assertNever } from "../core/exhaustive.ts";
+import { CONFIG_FILE, loadConfig } from "../state/config.ts";
+import { createTracker } from "./select.ts";
+import type { Tracker, TrackerResult, WorkItem } from "./types.ts";
+
+const Parameters = Type.Object({
+  action: Type.Union(
+    [
+      Type.Literal("list"),
+      Type.Literal("get"),
+      Type.Literal("create"),
+      Type.Literal("update"),
+      Type.Literal("comment"),
+    ],
+    { description: "What to do with the work tracker." },
+  ),
+  id: Type.Optional(Type.String({ description: "Work item id (get, update, comment)." })),
+  title: Type.Optional(Type.String({ description: "Title (create; optional rename on update)." })),
+  body: Type.Optional(
+    Type.String({ description: "Description (create, update) or comment text (comment)." }),
+  ),
+  status: Type.Optional(
+    Type.Union([Type.Literal("open"), Type.Literal("in-progress"), Type.Literal("done")], {
+      description: "Status (update), or a filter (list).",
+    }),
+  ),
+  labels: Type.Optional(Type.Array(Type.String(), { description: "Labels (create, update)." })),
+});
+
+type Params = Static<typeof Parameters>;
+
+const reply = (text: string, isError = false) => ({
+  content: [{ type: "text" as const, text }],
+  details: undefined,
+  isError,
+});
+
+const line = (i: WorkItem): string => `${i.id} — ${i.title} (${i.status})`;
+
+const detail = (i: WorkItem): string =>
+  [
+    line(i),
+    i.labels.length > 0 ? `labels: ${i.labels.join(", ")}` : "",
+    "",
+    i.body,
+    ...i.comments.map((c) => `\ncomment: ${c}`),
+  ]
+    .join("\n")
+    .trim();
+
+const missing = (action: string, field: string) => reply(`${action} needs ${field}`, true);
+
+const show = <T>(result: TrackerResult<T>, render: (value: T) => string) =>
+  result.ok ? reply(render(result.value)) : reply(result.error.message, true);
+
+const optional = <K extends string, V>(key: K, value: V | undefined): { [P in K]?: V } =>
+  value === undefined ? {} : ({ [key]: value } as { [P in K]?: V });
+
+const patchOf = (p: Params) => ({
+  ...optional("status", p.status),
+  ...optional("title", p.title),
+  ...optional("body", p.body),
+  ...optional("labels", p.labels),
+});
+
+async function create(tracker: Tracker, p: Params) {
+  if (p.title === undefined) return missing("create", "title");
+  const made = await tracker.create({
+    title: p.title,
+    ...optional("body", p.body),
+    ...optional("labels", p.labels),
+  });
+  return show(made, (i) => `created ${line(i)}`);
+}
+
+async function update(tracker: Tracker, p: Params) {
+  if (p.id === undefined) return missing("update", "id");
+  const patch = patchOf(p);
+  if (Object.keys(patch).length === 0) return missing("update", "status, title, body or labels");
+  return show(await tracker.update(p.id, patch), (i) => `updated ${line(i)}`);
+}
+
+async function comment(tracker: Tracker, p: Params) {
+  const { id, body } = p;
+  if (id === undefined) return missing("comment", "id");
+  if (body === undefined) return missing("comment", "body");
+  return show(await tracker.comment(id, body), () => `commented on ${id}`);
+}
+
+async function run(tracker: Tracker, p: Params) {
+  switch (p.action) {
+    case "list": {
+      const items = await tracker.list(optional("status", p.status));
+      return show(items, (all) => (all.length === 0 ? "no work items" : all.map(line).join("\n")));
+    }
+    case "get":
+      return p.id === undefined ? missing("get", "id") : show(await tracker.get(p.id), detail);
+    case "create":
+      return create(tracker, p);
+    case "update":
+      return update(tracker, p);
+    case "comment":
+      return comment(tracker, p);
+    default:
+      return assertNever(p.action);
+  }
+}
+
+/** `devsys_work_item`: the one way planning reads and writes work items, whatever `[tracker] kind` says. */
+export function createWorkItemTool(deps: { exec: Exec }): ToolDefinition<typeof Parameters> {
+  return {
+    name: "devsys_work_item",
+    label: "Work items",
+    description:
+      "List, read, create, update or comment on work items in the project's tracker (repo files by default, GitHub issues when configured). " +
+      "Use it for the backlog instead of editing tracker files or running gh by hand.",
+    promptSnippet: "Read and write the project's work items",
+    parameters: Parameters,
+    exposure: "direct",
+    async execute(
+      _id,
+      params: Static<typeof Parameters>,
+      _signal,
+      _onUpdate,
+      ctx: ExtensionContext,
+    ) {
+      const config = await loadConfig(ctx.cwd);
+      if (!config.ok) return reply(`${CONFIG_FILE}: ${config.error.message}`, true);
+      const tracker = createTracker({
+        tracker: config.value.tracker,
+        exec: deps.exec,
+        cwd: ctx.cwd,
+      });
+      if (!tracker.ok) return reply(`${CONFIG_FILE}: ${tracker.error.message}`, true);
+      return run(tracker.value, params);
+    },
+  };
+}