@jwilger/pi-development-system 0.52.1 → 0.54.0

package/extensions/development-system.ts

@@ -19,6 +19,7 @@ import { registerRedFirstGuard } from "../src/gates/red-first-guard.ts";
 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 { createReviewRecordTool, createReviewStartTool } from "../src/review/review-tools.ts";
 import { registerCiCommand } from "../src/state/ci-command.ts";
 import { loadConfig } from "../src/state/config.ts";
@@ -138,6 +139,7 @@ export function createDevelopmentSystem(pi: ExtensionAPI) {
   pi.registerTool(createRequestApprovalTool({ pi, approvals }));
   pi.registerTool(createModelsTool());
   pi.registerTool(createRouteTaskTool({ jev: (ctx) => jevHolder.forContext(ctx) }));
+  pi.registerTool(createIntakeTool({ state, jev: (ctx) => jevHolder.forContext(ctx) }));
   const reviewDeps = {
     state,
     jev: (ctx: ExtensionContext) => jevHolder.forContext(ctx),

package/package.json

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

package/prompts/devsys-start.md

@@ -0,0 +1,10 @@
+---
+description: Size new work and get the planning artifacts it needs before building
+argument-hint: "<what you want done>"
+---
+Start new work with the work-intake-and-slicing skill.
+
+1. Call `devsys_intake` with `request` set to: $ARGUMENTS (if empty, ask the user what they want done first).
+2. Show the user the proposed size and artifacts. The tool asks them to confirm or change the size.
+3. Follow the recommended artifacts in order. To skip one, call `devsys_record_departure` with gate `artifact.skipped:<artifact>` and the reason; do not skip silently. The event model and architecture are recommendations, never gates.
+4. For `fix` and `change` the phase is already `implementing`: write the task record, then work it test-first.

package/src/core/sizing.ts

@@ -0,0 +1,51 @@
+import { type ParseError, parseError, type Sizing } from "./types.ts";
+
+export const ARTIFACTS = [
+  "task-record",
+  "review",
+  "adr-if-needed",
+  "brief-lite",
+  "brief",
+  "decision-register",
+  "journeys",
+  "event-model",
+  "architecture",
+  "lens-review-optional",
+  "lens-review",
+] as const;
+
+export type ArtifactId = (typeof ARTIFACTS)[number];
+
+const SIZINGS: readonly Sizing[] = ["fix", "change", "capability", "product"];
+
+/** The set the work needs by default; D4: proportional, and skipping any of it is a recorded departure. */
+const BY_SIZING: Readonly<Record<Sizing, readonly ArtifactId[]>> = {
+  fix: ["task-record"],
+  change: ["task-record", "review", "adr-if-needed"],
+  capability: [
+    "task-record",
+    "review",
+    "adr-if-needed",
+    "brief-lite",
+    "journeys",
+    "event-model",
+    "lens-review-optional",
+  ],
+  product: [
+    "task-record",
+    "review",
+    "adr-if-needed",
+    "brief",
+    "decision-register",
+    "journeys",
+    "event-model",
+    "architecture",
+    "lens-review",
+  ],
+};
+
+export const recommendedArtifacts = (sizing: Sizing): readonly ArtifactId[] => BY_SIZING[sizing];
+
+export const parseSizing = (value: string): Sizing | ParseError =>
+  SIZINGS.find((s) => s === value) ??
+  parseError(`unknown sizing "${value}": expected fix, change, capability or product`);

package/src/jev/questions/sizing.ts

@@ -0,0 +1,111 @@
+import type { ClassifierBoolQuestion, ClassifierChoiceQuestion } from "@earendil-works/pi-ai";
+import { redactSecrets } from "../../core/redact.ts";
+import { err, ok, type Result } from "../../core/result.ts";
+import type { ArtifactId } from "../../core/sizing.ts";
+import type { Sizing } from "../../core/types.ts";
+import type { Jev, JevError } from "../client.ts";
+import { medianLabel } from "./route.ts";
+
+const LEVELS: readonly Sizing[] = ["fix", "change", "capability", "product"];
+
+export const SIZING_QUESTION: ClassifierChoiceQuestion = {
+  type: "choice",
+  instructions:
+    "How big is the work in `request`, given `repoSummary`? Judge what must be understood and decided, not how much typing it takes. A bug with a known cause is a fix; a behaviour change inside one existing feature is a change; a new user-facing capability spanning several parts is a capability; a new product or a rethink of one is a product.",
+  criteria: {
+    fix: "A defect or small correction with a known cause, one place, no design decision",
+    change:
+      "A modification to existing behaviour inside one feature or module, with a clear shape and a test",
+    capability:
+      "A new user-visible capability that touches several parts, needs a design, or has more than one user journey",
+    product:
+      "A new product, a new bounded context, or a rethink of who the users are and what outcome they need",
+  },
+};
+
+const need = (instructions: string): ClassifierBoolQuestion => ({
+  type: "bool",
+  instructions,
+  criteria: {
+    true: "Skipping it would likely cost rework or a wrong build",
+    false: "The work is clear enough without it",
+  },
+});
+
+/** One independent judgement per artifact the sizing table does not settle on its own. */
+export const ARTIFACT_QUESTIONS = {
+  "adr-if-needed": need(
+    "Does `request` involve an architectural decision that is costly to reverse and that a future reader will ask 'why' about (a new dependency, data shape, boundary, protocol)?",
+  ),
+  brief: need(
+    "Is it unclear who the users are, what outcome they want, or why this work is worth doing, so a written product brief is needed before building?",
+  ),
+  journeys: need(
+    "Does `request` involve a user performing a sequence of actions to reach an outcome, such that listing those journeys would expose missing steps?",
+  ),
+  "event-model": need(
+    "Does `request` change how information flows through a system with commands, state and views, such that modelling that flow before coding would find gaps?",
+  ),
+  architecture: need(
+    "Does `request` need a statement of how the parts of the system fit together and where the boundaries are, because no such statement exists in `repoSummary`?",
+  ),
+  "lens-review": need(
+    "Do the product assumptions in `request` carry enough risk that independent product-lens critique (value, discovery, strategy) is worth running before building?",
+  ),
+} as const satisfies Partial<Record<ArtifactId, ClassifierBoolQuestion>>;
+
+export type SizingInput = { request: string; repoSummary: string };
+export type SizingJudgement = {
+  sizing: Sizing;
+  confidence: number;
+  artifactNeed: Record<ArtifactId, number>;
+};
+
+const REQUEST_MAX = 4000;
+const SUMMARY_MAX = 3000;
+const clip = (text: string, max: number): string =>
+  redactSecrets(text.slice(0, max * 2)).slice(0, max);
+
+export async function judgeSizing(
+  jev: Jev,
+  input: SizingInput,
+): Promise<Result<SizingJudgement, JevError>> {
+  const asked = await jev.ask(
+    {
+      request: clip(input.request, REQUEST_MAX),
+      repoSummary: clip(input.repoSummary, SUMMARY_MAX),
+    },
+    { sizing: SIZING_QUESTION, ...ARTIFACT_QUESTIONS },
+  );
+  if (!asked.ok) return asked;
+  const sizing = asked.value.sizing;
+  if (sizing?.type !== "choice") return err({ kind: "provider", message: "missing sizing answer" });
+  const label = medianLabel(LEVELS, sizing);
+  if (label === undefined) return err({ kind: "provider", message: "unknown sizing label" });
+  const probabilities: Partial<Record<string, number>> = {};
+  for (const key of Object.keys(ARTIFACT_QUESTIONS)) {
+    const answer = asked.value[key];
+    if (answer?.type !== "bool" || !Number.isFinite(answer.probability)) {
+      return err({ kind: "provider", message: `missing ${key} answer` });
+    }
+    probabilities[key] = answer.probability;
+  }
+  const p = (key: keyof typeof ARTIFACT_QUESTIONS): number => probabilities[key] ?? 0;
+  return ok({
+    sizing: label,
+    confidence: sizing.confidence,
+    artifactNeed: {
+      "task-record": 1,
+      review: 1,
+      "adr-if-needed": p("adr-if-needed"),
+      brief: p("brief"),
+      "brief-lite": p("brief"),
+      "decision-register": p("brief"),
+      journeys: p("journeys"),
+      "event-model": p("event-model"),
+      architecture: p("architecture"),
+      "lens-review": p("lens-review"),
+      "lens-review-optional": p("lens-review"),
+    },
+  });
+}

package/src/planning/intake-tool.ts

@@ -0,0 +1,79 @@
+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 { 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";
+
+const Parameters = Type.Object({
+  request: Type.String({ description: "What the user asked for, in their words." }),
+  repoSummary: Type.Optional(
+    Type.String({ description: "One or two sentences on the repository, if known." }),
+  ),
+});
+
+const SIZES: readonly Sizing[] = ["fix", "change", "capability", "product"];
+
+const reply = (text: string, isError = false) => ({
+  content: [{ type: "text" as const, text }],
+  details: undefined,
+  isError,
+});
+
+/** Proposed size first, so the default selection is the proposal. */
+const sizeChoices = (proposed: Sizing): string[] => [
+  proposed,
+  ...SIZES.filter((s) => s !== proposed),
+];
+
+/** `devsys_intake`: Jev proposes a size and artifact set; the user confirms; state moves to the first phase. */
+export function createIntakeTool(deps: {
+  state: SessionState;
+  jev: (ctx: ExtensionContext) => Jev;
+}): ToolDefinition<typeof Parameters> {
+  return {
+    name: "devsys_intake",
+    label: "Start work",
+    description:
+      "Size a request (fix, change, capability, product) and list the planning artifacts that size needs. " +
+      "The user confirms the size; then phase, sizing and the active slice are set. Call at the start of any non-trivial work.",
+    promptSnippet: "Size new work and propose the planning artifacts it needs",
+    parameters: Parameters,
+    exposure: "direct",
+    async execute(_id, params: Static<typeof Parameters>, _signal, _onUpdate, ctx) {
+      const request = params.request.trim();
+      if (request === "") return reply("request must not be empty", true);
+      const judged = await judgeSizing(deps.jev(ctx), {
+        request,
+        repoSummary: params.repoSummary ?? "",
+      });
+      const proposedSize: Sizing = judged.ok ? judged.value.sizing : "change";
+      const basis = judged.ok
+        ? `Jev judged ${judged.value.sizing} (confidence ${judged.value.confidence.toFixed(2)}).`
+        : `Jev unavailable (${judged.error.kind}); defaulted to change.`;
+      const artifactNeed = judged.ok ? judged.value.artifactNeed : {};
+      const proposalFor = (size: Sizing) => proposeArtifacts(size, artifactNeed);
+      const proposal = renderProposal({
+        sizing: proposedSize,
+        basis,
+        proposal: proposalFor(proposedSize),
+      });
+      if (!ctx.hasUI) return reply(`${proposal}\nHeadless: proposal only, not applied.`);
+      const picked = await ctx.ui.select(`Size this work (${basis})`, sizeChoices(proposedSize));
+      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;
+      deps.state.update((s) => ({
+        ...s,
+        phase: phaseFor(sizing),
+        sizing,
+        activeSlice: slice,
+      }));
+      const final = renderProposal({ sizing, basis, proposal: proposalFor(sizing) });
+      return reply(`${final}\nPhase: ${phaseFor(sizing)}. Active slice: ${slice}.`);
+    },
+  };
+}

package/src/planning/intake.ts

@@ -0,0 +1,54 @@
+import { ARTIFACTS, type ArtifactId, recommendedArtifacts } from "../core/sizing.ts";
+import type { Phase, Sizing } from "../core/types.ts";
+
+const SLUG_MAX = 40;
+/** Jev need at or above this offers an artifact the sizing table did not list. */
+const CONSIDER_AT = 0.5;
+
+export const sliceSlug = (request: string): string => {
+  const slug = request
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+/, "")
+    .slice(0, SLUG_MAX)
+    .replace(/-+$/, "");
+  return slug === "" ? "work" : slug;
+};
+
+export type ArtifactProposal = {
+  readonly recommended: readonly ArtifactId[];
+  readonly consider: readonly ArtifactId[];
+};
+
+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,
+  );
+  return { recommended, consider };
+};
+
+/** Small work starts building; bigger work plans first (D4: proportional). */
+export const phaseFor = (sizing: Sizing): Phase =>
+  sizing === "fix" || sizing === "change" ? "implementing" : "planning";
+
+export const renderProposal = (input: {
+  sizing: Sizing;
+  basis: string;
+  proposal: ArtifactProposal;
+}): string => {
+  const { sizing, basis, proposal } = input;
+  const lines = [
+    `Proposed sizing: ${sizing}. ${basis}`,
+    `Recommended artifacts: ${proposal.recommended.join(", ")}.`,
+  ];
+  if (proposal.consider.length > 0) lines.push(`Also consider: ${proposal.consider.join(", ")}.`);
+  lines.push(
+    "Skipping a recommended artifact is allowed but recorded: call devsys_record_departure with gate artifact.skipped:<artifact>.",
+    "The event model and architecture are never blocked by a gate; they are recommended, not enforced.",
+  );
+  return lines.join("\n");
+};