@jwilger/pi-development-system 0.54.0 → 0.56.0

package/extensions/development-system.ts

@@ -20,6 +20,7 @@ import { createRequestApprovalTool } from "../src/gates/request-approval-tool.ts
 import { registerTestGuard } from "../src/gates/test-guard.ts";
 import { createJevHolder } from "../src/jev/holder.ts";
 import { createIntakeTool } from "../src/planning/intake-tool.ts";
+import { createTaskCheckTool } from "../src/planning/task-check-tool.ts";
 import { createReviewRecordTool, createReviewStartTool } from "../src/review/review-tools.ts";
 import { registerCiCommand } from "../src/state/ci-command.ts";
 import { loadConfig } from "../src/state/config.ts";
@@ -29,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),
@@ -140,6 +142,8 @@ export function createDevelopmentSystem(pi: ExtensionAPI) {
   pi.registerTool(createModelsTool());
   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.54.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/jev/questions/readiness.ts

@@ -0,0 +1,82 @@
+import type { ClassifierBoolQuestion } from "@earendil-works/pi-ai";
+import { redactSecrets } from "../../core/redact.ts";
+import { err, ok, type Result } from "../../core/result.ts";
+import type { TaskRecord } from "../../planning/task-record.ts";
+import type { Jev, JevError } from "../client.ts";
+
+const vague = (instructions: string): ClassifierBoolQuestion => ({
+  type: "bool",
+  instructions,
+  criteria: {
+    true: "A weaker model implementing this alone would have to guess",
+    false: "It is specific enough to act on without guessing",
+  },
+});
+
+/** One narrow judgement per aspect; `tooBig` is separate because the fix is to split, not to add detail. */
+export const READINESS_QUESTIONS = {
+  goal: vague(
+    "`task.goal` should be one observable sentence: something a person or test could see change. Is it vague, a restatement of the title, or about activity rather than outcome?",
+  ),
+  interfaces: vague(
+    "`task.interfaces` should give exact signatures or contracts for what is created or changed. Is it missing signatures, hand-wavy ('a helper', 'some function') or inconsistent with `task.files`?",
+  ),
+  firstFailingTest: vague(
+    "`task.firstFailingTest` should name a test file and test and say what it asserts. Does it fail to say what would be asserted, or assert something unrelated to `task.goal`?",
+  ),
+  steps: vague(
+    "`task.steps` should be small steps a reviewer could reject independently. Are any steps large, combined ('implement and wire everything'), or out of order with the test-first step?",
+  ),
+  tooBig: {
+    type: "bool",
+    instructions:
+      "Is this more than one task: does it touch unrelated areas, or need more than one failing test to describe, so that it should be split before anyone implements it?",
+    criteria: {
+      true: "It should be split into two or more task records",
+      false: "It is one coherent task a single implementer can finish",
+    },
+  },
+} as const satisfies Record<string, ClassifierBoolQuestion>;
+
+type Readiness = "ready" | "needs-detail" | "too-big";
+export type ReadinessJudgement = { readiness: Readiness; missing: string[] };
+
+/** Probability at or above which an aspect counts as vague. */
+const VAGUE_AT = 0.6;
+
+const clip = (text: string, max: number): string =>
+  redactSecrets(text.slice(0, max * 2)).slice(0, max);
+
+export async function judgeTaskReadiness(
+  jev: Jev,
+  record: TaskRecord,
+): Promise<Result<ReadinessJudgement, JevError>> {
+  const asked = await jev.ask(
+    {
+      task: {
+        title: clip(record.title, 200),
+        goal: clip(record.goal, 600),
+        files: record.files.slice(0, 30).map((f) => clip(f, 200)),
+        interfaces: clip(record.interfaces, 1500),
+        firstFailingTest: clip(record.firstFailingTest, 600),
+        steps: record.steps.slice(0, 10).map((s) => clip(s, 300)),
+      },
+    },
+    READINESS_QUESTIONS,
+  );
+  if (!asked.ok) return asked;
+  const probability = new Map<string, number>();
+  for (const key of Object.keys(READINESS_QUESTIONS)) {
+    const answer = asked.value[key];
+    if (answer?.type !== "bool" || !Number.isFinite(answer.probability)) {
+      return err({ kind: "provider", message: `missing ${key} answer` });
+    }
+    probability.set(key, answer.probability);
+  }
+  if ((probability.get("tooBig") ?? 0) >= VAGUE_AT)
+    return ok({ readiness: "too-big", missing: [] });
+  const missing = Object.keys(READINESS_QUESTIONS).filter(
+    (k) => k !== "tooBig" && (probability.get(k) ?? 0) >= VAGUE_AT,
+  );
+  return ok({ readiness: missing.length > 0 ? "needs-detail" : "ready", missing });
+}

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

@@ -0,0 +1,73 @@
+import { readFile } from "node:fs/promises";
+import { isAbsolute, relative, resolve } from "node:path";
+import type { ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { type Static, Type } from "typebox";
+import { isParseError } from "../core/types.ts";
+import type { Jev } from "../jev/client.ts";
+import { judgeTaskReadiness } from "../jev/questions/readiness.ts";
+import { parseTaskRecord } from "./task-record.ts";
+
+const Parameters = Type.Object({
+  path: Type.String({
+    description: "Path to the task record markdown file, inside the repository.",
+  }),
+});
+
+const reply = (text: string, isError = false) => ({
+  content: [{ type: "text" as const, text }],
+  details: undefined,
+  isError,
+});
+
+const insideRepo = (cwd: string, target: string): boolean => {
+  const rel = relative(cwd, target);
+  return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+};
+
+/** `devsys_task_check`: structural readiness is deterministic; Jev adds "specific enough" and "one task". */
+export function createTaskCheckTool(deps: {
+  jev: (ctx: ExtensionContext) => Jev;
+}): ToolDefinition<typeof Parameters> {
+  return {
+    name: "devsys_task_check",
+    label: "Check task record",
+    description:
+      "Check a task record file against the task-record format and judge whether a weaker implementer could act on it. " +
+      "Run before handing a task record to an implementer subagent.",
+    promptSnippet: "Check a task record is ready for an implementer",
+    parameters: Parameters,
+    exposure: "direct",
+    async execute(_id, params: Static<typeof Parameters>, _signal, _onUpdate, ctx) {
+      const target = resolve(ctx.cwd, params.path);
+      if (!insideRepo(ctx.cwd, target))
+        return reply(`${params.path} is outside the repository`, true);
+      let markdown: string;
+      try {
+        markdown = await readFile(target, "utf8");
+      } catch (cause) {
+        return reply(
+          `cannot read ${params.path}: ${cause instanceof Error ? cause.message : String(cause)}`,
+          true,
+        );
+      }
+      const record = parseTaskRecord(markdown);
+      if (isParseError(record))
+        return reply(`${params.path} is not ready: ${record.message}`, true);
+      const judged = await judgeTaskReadiness(deps.jev(ctx), record);
+      if (!judged.ok) {
+        return reply(
+          `${record.id}: structure ok. Jev unavailable (${judged.error.kind}), so specificity and size were not judged; review the record yourself.`,
+        );
+      }
+      const { readiness, missing } = judged.value;
+      if (readiness === "ready")
+        return reply(`${record.id}: ready. Structure ok and specific enough for an implementer.`);
+      if (readiness === "too-big") {
+        return reply(
+          `${record.id}: too-big. Split it into task records that each need one failing test, then check each.`,
+        );
+      }
+      return reply(`${record.id}: needs-detail. Make these more specific: ${missing.join(", ")}.`);
+    },
+  };
+}

package/src/planning/task-record.ts

@@ -0,0 +1,121 @@
+import { 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 = {
+  readonly id: string;
+  readonly title: string;
+  readonly goal: string;
+  readonly files: readonly string[];
+  readonly interfaces: string;
+  readonly firstFailingTest: string;
+  readonly steps: readonly string[];
+  readonly run: string;
+  readonly expected: string;
+  readonly outOfScope: string;
+};
+
+const SECTIONS = [
+  "Goal",
+  "Files",
+  "Interfaces",
+  "First failing test",
+  "Steps",
+  "Run",
+  "Expected",
+  "Out of scope",
+] as const;
+type Section = (typeof SECTIONS)[number];
+
+const HEADER = /^## (\S+) [—-] (.+)$/;
+const SECTION_LINE = /^\*\*([^:*]+):\*\*\s*(.*)$/;
+const STEP = /^\s*(?:\d+[.)]|[-*])\s+(.*)$/;
+const STEPS_MIN = 3;
+const STEPS_MAX = 7;
+/** Words that stand in for a command or an observable result. */
+const PLACEHOLDER = /^(?:n\/?a|none|todo|tbc|-|…|\.\.\.|works?|it works|passes|ok)\.?$/i;
+
+const isSection = (name: string): name is Section => SECTIONS.some((s) => s === name);
+
+/** Splits the body into section texts keyed by name; text may continue over several lines. */
+function splitSections(lines: readonly string[]): Map<Section, string> {
+  const found = new Map<Section, string[]>();
+  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)) {
+      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 stripTicks = (text: string): string => text.replace(/^`+|`+$/g, "").trim();
+
+const stepsOf = (text: string): string[] =>
+  text.split("\n").flatMap((line) => {
+    const item = STEP.exec(line)?.[1]?.trim();
+    return item === undefined || item === "" ? [] : [item];
+  });
+
+function concrete(name: "Run" | "Expected", text: string): string | undefined {
+  const bare = stripTicks(text);
+  if (PLACEHOLDER.test(bare))
+    return `${name} must be a concrete ${name === "Run" ? "command" : "observable result"}, not "${bare}"`;
+  if (name === "Expected" && bare.split(/\s+/).length < 2) {
+    return "Expected must say what is observed (at least two words, e.g. a count, output or exit status)";
+  }
+  return 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[] {
+  const problems: string[] = [];
+  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");
+  const steps = stepsOf(get(sections, "Steps"));
+  if (!missing.includes("Steps") && (steps.length < STEPS_MIN || steps.length > STEPS_MAX)) {
+    problems.push(`Steps must be ${STEPS_MIN}-${STEPS_MAX} steps, found ${steps.length}`);
+  }
+  for (const name of ["Run", "Expected"] as const) {
+    const why = missing.includes(name) ? undefined : concrete(name, get(sections, name));
+    if (why !== undefined) problems.push(why);
+  }
+  return problems;
+}
+
+const filesOf = (text: string): string[] =>
+  text
+    .split(/[,\n]/)
+    .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 sections = splitSections(lines.slice(headerAt + 1));
+  const problems = problemsOf(markdown, sections);
+  if (problems.length > 0) return parseError(problems.join("; "));
+  const text = (s: Section): string => get(sections, s);
+  return {
+    id: header[1] ?? "",
+    title: header[2]?.trim() ?? "",
+    goal: text("Goal"),
+    files: filesOf(text("Files")),
+    interfaces: text("Interfaces"),
+    firstFailingTest: text("First failing test"),
+    steps: stepsOf(text("Steps")),
+    run: stripTicks(text("Run")),
+    expected: text("Expected"),
+    outOfScope: text("Out of scope"),
+  };
+}

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);
+    },
+  };
+}