@jwilger/pi-development-system 0.55.0 → 0.57.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.57.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, each with an **Acceptance** list (observable checks that say the increment is done) and a final Release step (commit, push, CI green, publish, update) followed by a STOP for the user; for every task a task record whose header is `## <id> — <title>` and whose sections are written exactly as `**Goal:**`, `**Files:**`, `**Interfaces:**`, `**First failing test:**`, `**Steps:**`, `**Run:**`, `**Expected:**`, `**Out of scope:**` (label and colon inside the bold, one section per label); 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, one increment at a time, stopping after each increment's Release step". 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 the sections, each written as a bold label with the colon inside, `**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/planning/intake-tool.ts

@@ -1,11 +1,11 @@
 import type { ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { type Static, Type } from "typebox";
 import { parseSizing } from "../core/sizing.ts";
-import { isParseError, type Sizing, type SliceRef } from "../core/types.ts";
+import { type DevsysState, isParseError, type Sizing, type SliceRef } from "../core/types.ts";
 import type { Jev } from "../jev/client.ts";
 import { judgeSizing } from "../jev/questions/sizing.ts";
 import type { SessionState } from "../state/session-state.ts";
-import { phaseFor, proposeArtifacts, renderProposal, sliceSlug } from "./intake.ts";
+import { phaseFor, proposeArtifacts, renderProposal, sliceSlug, uniqueSlice } from "./intake.ts";
 
 const Parameters = Type.Object({
   request: Type.String({ description: "What the user asked for, in their words." }),
@@ -28,6 +28,13 @@ const sizeChoices = (proposed: Sizing): string[] => [
   ...SIZES.filter((s) => s !== proposed),
 ];
 
+const slicesInUse = (state: DevsysState): Set<string> =>
+  new Set([
+    ...(state.activeSlice === undefined ? [] : [state.activeSlice]),
+    ...(state.reviews ?? []).map((r) => r.slice),
+    ...state.openDepartures.flatMap((d) => (d.scope.kind === "slice" ? [d.scope.slice] : [])),
+  ]);
+
 /** `devsys_intake`: Jev proposes a size and artifact set; the user confirms; state moves to the first phase. */
 export function createIntakeTool(deps: {
   state: SessionState;
@@ -65,7 +72,7 @@ export function createIntakeTool(deps: {
       if (picked === undefined) return reply(`${proposal}\nIntake cancelled; nothing changed.`);
       const sizing = parseSizing(picked);
       if (isParseError(sizing)) return reply(sizing.message, true);
-      const slice = sliceSlug(request) as SliceRef;
+      const slice = uniqueSlice(sliceSlug(request), slicesInUse(deps.state.get())) as SliceRef;
       deps.state.update((s) => ({
         ...s,
         phase: phaseFor(sizing),

package/src/planning/intake.ts

@@ -5,6 +5,13 @@ const SLUG_MAX = 40;
 /** Jev need at or above this offers an artifact the sizing table did not list. */
 const CONSIDER_AT = 0.5;
 
+/** `base`, or `base-2`, `base-3`… when earlier work already used the name, so a new slice never inherits old review or departure state. */
+export const uniqueSlice = (base: string, taken: ReadonlySet<string>): string => {
+  let slice = base;
+  for (let n = 2; taken.has(slice); n++) slice = `${base}-${n}`;
+  return slice;
+};
+
 export const sliceSlug = (request: string): string => {
   const slug = request
     .toLowerCase()
@@ -20,14 +27,26 @@ export type ArtifactProposal = {
   readonly consider: readonly ArtifactId[];
 };
 
+/** Light and full forms of one artifact; offering several of a family at once is noise. */
+const FAMILIES: readonly (readonly ArtifactId[])[] = [
+  ["brief-lite", "brief", "decision-register"],
+  ["lens-review-optional", "lens-review"],
+];
+
+const familyOf = (id: ArtifactId): readonly ArtifactId[] =>
+  FAMILIES.find((f) => f.includes(id)) ?? [id];
+
 export const proposeArtifacts = (
   sizing: Sizing,
   artifactNeed: Readonly<Partial<Record<ArtifactId, number>>>,
 ): ArtifactProposal => {
   const recommended = recommendedArtifacts(sizing);
-  const consider = ARTIFACTS.filter(
-    (id) => !recommended.includes(id) && (artifactNeed[id] ?? 0) >= CONSIDER_AT,
-  );
+  const consider = ARTIFACTS.filter((id) => {
+    const family = familyOf(id);
+    if (family.some((member) => recommended.includes(member))) return false;
+    const first = family.find((member) => (artifactNeed[member] ?? 0) >= CONSIDER_AT);
+    return first === id;
+  });
   return { recommended, consider };
 };
 

package/src/planning/task-check-tool.ts

@@ -11,6 +11,11 @@ const Parameters = Type.Object({
   path: Type.String({
     description: "Path to the task record markdown file, inside the repository.",
   }),
+  id: Type.Optional(
+    Type.String({
+      description: "Which task record to check when the file (such as a plan) holds several.",
+    }),
+  ),
 });
 
 const reply = (text: string, isError = false) => ({
@@ -50,7 +55,7 @@ export function createTaskCheckTool(deps: {
           true,
         );
       }
-      const record = parseTaskRecord(markdown);
+      const record = parseTaskRecord(markdown, params.id);
       if (isParseError(record))
         return reply(`${params.path} is not ready: ${record.message}`, true);
       const judged = await judgeTaskReadiness(deps.jev(ctx), record);

package/src/planning/task-record.ts

@@ -1,4 +1,4 @@
-import { type ParseError, parseError } from "../core/types.ts";
+import { isParseError, type ParseError, parseError } from "../core/types.ts";
 
 /** Appendix C of the plan: the one-task-per-implementer format a weaker model can follow. */
 export type TaskRecord = {
@@ -27,7 +27,7 @@ const SECTIONS = [
 type Section = (typeof SECTIONS)[number];
 
 const HEADER = /^## (\S+) [—-] (.+)$/;
-const SECTION_LINE = /^\*\*([^:*]+):\*\*\s*(.*)$/;
+const SECTION_LINE = /^\*\*([^:*]+)(?::\*\*|\*\*:)\s*(.*)$/;
 const STEP = /^\s*(?:\d+[.)]|[-*])\s+(.*)$/;
 const STEPS_MIN = 3;
 const STEPS_MAX = 7;
@@ -36,19 +36,43 @@ const PLACEHOLDER = /^(?:n\/?a|none|todo|tbc|-|…|\.\.\.|works?|it works|passes
 
 const isSection = (name: string): name is Section => SECTIONS.some((s) => s === name);
 
+type Sections = { readonly text: Map<Section, string>; readonly duplicates: Section[] };
+
 /** Splits the body into section texts keyed by name; text may continue over several lines. */
-function splitSections(lines: readonly string[]): Map<Section, string> {
+function splitSections(lines: readonly string[]): Sections {
   const found = new Map<Section, string[]>();
+  const duplicates: Section[] = [];
   let current: string[] | undefined;
   for (const line of lines) {
     const match = SECTION_LINE.exec(line);
     const name = match?.[1]?.trim();
     if (match !== null && name !== undefined && isSection(name)) {
+      if (found.has(name)) duplicates.push(name);
       current = match[2] === "" ? [] : [match[2] ?? ""];
       found.set(name, current);
     } else current?.push(line);
   }
-  return new Map([...found].map(([name, text]) => [name, text.join("\n").trim()]));
+  const text = new Map([...found].map(([name, body]) => [name, body.join("\n").trim()] as const));
+  return { text, duplicates };
+}
+
+type Located = { readonly id: string; readonly title: string; readonly lines: readonly string[] };
+
+/** Every `## <id> — <title>` block; any other `## ` heading ends the block before it. */
+function recordsIn(lines: readonly string[]): Located[] {
+  const records: { id: string; title: string; lines: string[] }[] = [];
+  let open: { id: string; title: string; lines: string[] } | undefined;
+  for (const line of lines) {
+    if (line.startsWith("## ")) {
+      const header = HEADER.exec(line);
+      open =
+        header === null
+          ? undefined
+          : { id: header[1] ?? "", title: header[2]?.trim() ?? "", lines: [] };
+      if (open !== undefined) records.push(open);
+    } else open?.lines.push(line);
+  }
+  return records;
 }
 
 const stripTicks = (text: string): string => text.replace(/^`+|`+$/g, "").trim();
@@ -72,8 +96,12 @@ function concrete(name: "Run" | "Expected", text: string): string | undefined {
 const get = (sections: ReadonlyMap<Section, string>, s: Section): string => sections.get(s) ?? "";
 
 /** Every readiness problem in the sections, so the author fixes them in one pass. */
-function problemsOf(markdown: string, sections: ReadonlyMap<Section, string>): string[] {
+function problemsOf(markdown: string, split: Sections): string[] {
+  const sections = split.text;
   const problems: string[] = [];
+  if (split.duplicates.length > 0) {
+    problems.push(`duplicate section: ${[...new Set(split.duplicates)].join(", ")}`);
+  }
   const missing = SECTIONS.filter((s) => get(sections, s) === "");
   if (missing.length > 0) problems.push(`missing section: ${missing.join(", ")}`);
   if (/\bTBD\b/.test(markdown)) problems.push("contains TBD; decide it or split the task");
@@ -94,21 +122,35 @@ const filesOf = (text: string): string[] =>
     .map((f) => stripTicks(f.trim()))
     .filter((f) => f !== "");
 
-/** Parses one task record, reporting every problem together. */
-export function parseTaskRecord(markdown: string): TaskRecord | ParseError {
-  const lines = markdown.split("\n");
-  const headerAt = lines.findIndex((l) => l.startsWith("## "));
-  const header = headerAt < 0 ? null : HEADER.exec(lines[headerAt] ?? "");
-  if (header === null) {
-    return parseError("header must be `## <id> — <title>` (an id, an em dash, then the title)");
+const NO_HEADER = "header must be `## <id> — <title>` (an id, an em dash, then the title)";
+
+function locate(markdown: string, id: string | undefined): Located | ParseError {
+  const records = recordsIn(markdown.split("\n"));
+  const names = records.map((r) => r.id).join(", ");
+  if (id !== undefined) {
+    return (
+      records.find((r) => r.id === id) ??
+      parseError(`no task record "${id}" (found: ${names || "none"})`)
+    );
   }
-  const sections = splitSections(lines.slice(headerAt + 1));
-  const problems = problemsOf(markdown, sections);
+  const [only, ...rest] = records;
+  if (only === undefined) return parseError(NO_HEADER);
+  return rest.length === 0
+    ? only
+    : parseError(`the file holds ${records.length} task records (${names}); name the one to check`);
+}
+
+/** Parses one task record (the only one in the file, or the one named by `id`), reporting every problem together. */
+export function parseTaskRecord(markdown: string, id?: string): TaskRecord | ParseError {
+  const found = locate(markdown, id);
+  if (isParseError(found)) return found;
+  const split = splitSections(found.lines);
+  const problems = problemsOf(found.lines.join("\n"), split);
   if (problems.length > 0) return parseError(problems.join("; "));
-  const text = (s: Section): string => get(sections, s);
+  const text = (s: Section): string => get(split.text, s);
   return {
-    id: header[1] ?? "",
-    title: header[2]?.trim() ?? "",
+    id: found.id,
+    title: found.title,
     goal: text("Goal"),
     files: filesOf(text("Files")),
     interfaces: text("Interfaces"),

package/src/tracker/github.ts

@@ -0,0 +1,211 @@
+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);
+};
+
+/** Label changes that make the issue's labels exactly `wanted` (plus the in-progress marker when asked for). */
+const labelFlags = (current: WorkItem, patch: WorkItemPatch): string[] => {
+  const wanted = patch.labels ?? current.labels;
+  const marked = (patch.status ?? current.status) === "in-progress";
+  const add = [
+    ...wanted.filter((l) => !current.labels.includes(l)),
+    ...(marked ? [IN_PROGRESS] : []),
+  ];
+  const remove = [
+    ...current.labels.filter((l) => !wanted.includes(l)),
+    ...(marked ? [] : [IN_PROGRESS]),
+  ];
+  return [
+    ...add.flatMap((l) => ["--add-label", l]),
+    ...remove.flatMap((l) => ["--remove-label", l]),
+  ];
+};
+
+const editFlags = (current: WorkItem, patch: WorkItemPatch): string[] => [
+  ...(patch.title === undefined ? [] : ["--title", patch.title]),
+  ...(patch.body === undefined ? [] : ["--body", patch.body]),
+  ...(patch.labels === undefined && patch.status === undefined ? [] : labelFlags(current, patch)),
+];
+
+/** Closing or reopening only when the issue is not already in the wanted state. */
+const stateCommand = (current: WorkItem, status: WorkStatus | undefined): string | undefined => {
+  if (status === undefined) return undefined;
+  if (status === "done") return current.status === "done" ? undefined : "close";
+  return current.status === "done" ? "reopen" : undefined;
+};
+
+/**
+ * Labels are replaced, as in the repo-files tracker. Order: make sure the marker label exists, apply every
+ * edit in one `gh issue edit`, then close or reopen last, so a failure before the state change leaves the
+ * issue's open/closed state alone.
+ */
+const updateIssue = async (
+  gh: Gh,
+  id: string,
+  patch: WorkItemPatch,
+): Promise<TrackerResult<WorkItem>> => {
+  const current = await view(gh, id);
+  if (!current.ok) return current;
+  if (patch.status === "in-progress") {
+    const made = await gh(["label", "create", IN_PROGRESS, "--force"]);
+    if (!made.ok) return made;
+  }
+  const flags = editFlags(current.value, patch);
+  if (flags.length > 0) {
+    const edited = await gh(["issue", "edit", id, ...flags]);
+    if (!edited.ok) return edited;
+  }
+  const command = stateCommand(current.value, patch.status);
+  if (command !== undefined) {
+    const changed = await gh(["issue", command, id]);
+    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,90 @@
+import { ok } from "../core/result.ts";
+import {
+  type TrackerResult,
+  trackerError,
+  WORK_STATUSES,
+  type WorkItem,
+  type WorkStatus,
+} from "./types.ts";
+
+const COMMENTS = "\n## Comments\n";
+
+/** Comment lines are quoted so nothing a comment says can look like one of our headings. */
+const quote = (text: string): string =>
+  text
+    .split("\n")
+    .map((line) => (line === "" ? ">" : `> ${line}`))
+    .join("\n");
+
+const unquote = (text: string): string =>
+  text
+    .split("\n")
+    .map((line) => line.replace(/^> ?/, ""))
+    .join("\n");
+
+/** What the file format cannot hold, or undefined when the item can be written and read back. */
+export const unwritable = (item: Pick<WorkItem, "title" | "labels">): string | undefined => {
+  if (/[\r\n]/.test(item.title)) return "a work item title must be a single line";
+  if (item.title.trim() === "") return "a work item title cannot be blank";
+  const bad = item.labels.find((l) => /[\r\n,]/.test(l) || l.trim() === "");
+  return bad === undefined
+    ? undefined
+    : `label ${JSON.stringify(bad)} is blank or holds a comma or line break`;
+};
+
+export const renderItem = (item: WorkItem): string => {
+  const comments = item.comments.map((c) => `\n### Comment\n\n${quote(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) => unquote(c.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,137 @@
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { ok } from "../core/result.ts";
+import { parseItem, renderBacklog, renderItem, unwritable } 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>> => {
+  const problem = unwritable(item);
+  if (problem !== undefined) return trackerError(problem);
+  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 problem = unwritable({ title: input.title, labels: input.labels ?? [] });
+  if (problem !== undefined) return trackerError(problem);
+  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);
+    },
+  };
+}