@jwilger/pi-development-system 0.53.0 → 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.53.0",
+  "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/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");
+};