@jwilger/pi-development-system 0.75.0 → 0.76.0

package/extensions/development-system.ts

@@ -7,6 +7,8 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 import { cadenceLine, DEFAULT_PUSH_MINUTES } from "../src/context/cadence.ts";
 import { appendContextTail, renderContextTail } from "../src/context/context-tail.ts";
+import { createPhaseTool } from "../src/context/devsys-tool.ts";
+import { applyIntentGuideline } from "../src/context/intent-trigger.ts";
 import { registerModelAdvice } from "../src/context/model-advice.ts";
 import { renderStatus, renderStatusLine, STATUS_KEY } from "../src/context/status.ts";
 import { applyPromptSection } from "../src/context/system-prompt.ts";
@@ -87,8 +89,9 @@ export function createDevelopmentSystem(pi: ExtensionAPI) {
   pi.on("session_start", (_event, ctx) => rebuild(ctx));
   pi.on("session_tree", (_event, ctx) => rebuild(ctx));
 
-  pi.on("before_agent_start", (event) => {
+  pi.on("before_agent_start", async (event, ctx) => {
     applyPromptSection(event, state.get(), nonNegotiables);
+    await applyIntentGuideline(event, state.get(), jevHolder.forContext(ctx));
   });
 
   pi.on("context", (event) => {
@@ -156,6 +159,7 @@ export function createDevelopmentSystem(pi: ExtensionAPI) {
   ];
   for (const tool of rarelyUsed) pi.registerTool(tool);
   pi.on("session_start", () => declareWithoutCodemode(pi, rarelyUsed));
+  pi.registerTool(createPhaseTool({ state }));
   pi.registerTool(createBeginWorkTool({ state }));
   pi.registerTool(createIntakeTool({ pi, state, jev: (ctx) => jevHolder.forContext(ctx) }));
   const reviewDeps = {

package/package.json

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

package/src/context/devsys-tool.ts

@@ -0,0 +1,34 @@
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import type { SessionState } from "../state/session-state.ts";
+import { phaseGuide } from "./phase-guide.ts";
+
+const BASE =
+  "What the development system expects in the current workflow phase, and which tools to use. Call it when unsure what comes next.";
+
+/** `devsys`: a model-only tool whose description is rewritten each turn with the current phase's guidance. */
+export function createPhaseTool(deps: { state: SessionState }): ToolDefinition {
+  return {
+    name: "devsys",
+    label: "Workflow guide",
+    description: BASE,
+    promptSnippet: "Show what the workflow expects in the current phase",
+    parameters: Type.Object({}),
+    exposure: "model-only",
+    prepareLoadout: () => ({
+      descriptions: {
+        devsys: `${BASE} Current phase (${deps.state.get().phase}): ${phaseGuide(deps.state.get().phase)}`,
+      },
+    }),
+    execute() {
+      const { phase, sizing, activeSlice } = deps.state.get();
+      const text = [
+        `phase: ${phase}`,
+        `sizing: ${sizing ?? "none"}`,
+        `slice: ${activeSlice ?? "none"}`,
+        phaseGuide(phase),
+      ].join("\n");
+      return Promise.resolve({ content: [{ type: "text" as const, text }], details: undefined });
+    },
+  };
+}

package/src/context/intent-trigger.ts

@@ -0,0 +1,43 @@
+import type { BeforeAgentStartEvent } from "@earendil-works/pi-coding-agent";
+import type { DevsysState } from "../core/types.ts";
+import type { Jev } from "../jev/client.ts";
+import { type Intent, judgeIntent } from "../jev/questions/intent.ts";
+
+/** Probability at or above which an intent is acted on. */
+export const INTENT_AT = 0.7;
+
+/** Pure: the one guideline line an intent earns in a phase, or undefined. Questions and continuations earn none. */
+export function intentGuideline(
+  intent: Intent,
+  confidence: number,
+  phase: DevsysState["phase"],
+): string | undefined {
+  if (confidence < INTENT_AT) return undefined;
+  const idle = phase === "idle";
+  if ((intent === "new-work" || intent === "fix") && (idle || intent === "new-work")) {
+    return "This prompt asks for new work: call devsys_intake with the request before editing anything, so it is sized and the planning artifacts it needs are named.";
+  }
+  if (intent === "review" && idle) {
+    return "This prompt asks for a review: call devsys_review_start for a fresh-context review instead of reviewing in this conversation.";
+  }
+  return undefined;
+}
+
+/** Slash commands and empty prompts are not judged. */
+const judgeable = (prompt: string): boolean => {
+  const trimmed = prompt.trim();
+  return trimmed !== "" && !trimmed.startsWith("/");
+};
+
+/** Adapter: judge the prompt, and add the line to this run's guidelines. Jev trouble adds nothing. */
+export async function applyIntentGuideline(
+  event: BeforeAgentStartEvent,
+  state: DevsysState,
+  jev: Jev,
+): Promise<void> {
+  if (!judgeable(event.prompt)) return;
+  const judged = await judgeIntent(jev, { prompt: event.prompt, phase: state.phase });
+  if (!judged.ok) return;
+  const line = intentGuideline(judged.value.intent, judged.value.confidence, state.phase);
+  if (line !== undefined) event.systemPromptOptions.promptGuidelines.push(line);
+}

package/src/context/phase-guide.ts

@@ -0,0 +1,21 @@
+import { assertNever } from "../core/exhaustive.ts";
+import type { Phase } from "../core/types.ts";
+
+/** What to do in each phase, in one paragraph. Pure; the `devsys` tool and its description both use it. */
+export function phaseGuide(phase: Phase): string {
+  switch (phase) {
+    case "idle":
+      return "Nothing is in flight. For new work or a fix, call devsys_intake with the user's request before editing: it sizes the work and names the planning artifacts it needs.";
+    case "intake":
+    case "planning":
+      return "Planning. Produce the artifacts the sizing asked for, write task records (check each with devsys_task_check), and when the user approves the plan call devsys_begin_work.";
+    case "implementing":
+      return "Implementing one slice. Write a failing test first, make it pass with the least code, run the tests and read the result before claiming anything. Push small, verified increments.";
+    case "reviewing":
+      return "Reviewing. Call devsys_review_start for a fresh-context review, pass its packet and diffDigest to devsys_review_record, fix every blocking and should-fix finding, and repeat until the round is clean.";
+    case "delivering":
+      return "Delivering. Commit with a rationale, push to trunk, wait for CI to go green, and release before starting the next slice. A red trunk is repaired first.";
+    default:
+      return assertNever(phase);
+  }
+}

package/src/jev/questions/intent.ts

@@ -0,0 +1,40 @@
+import type { ClassifierChoiceQuestion } from "@earendil-works/pi-ai";
+import { redactSecrets } from "../../core/redact.ts";
+import { err, ok, type Result } from "../../core/result.ts";
+import type { Jev, JevError } from "../client.ts";
+
+export const INTENTS = ["new-work", "fix", "review", "question", "continuation"] as const;
+export type Intent = (typeof INTENTS)[number];
+
+export const INTENT_QUESTION: ClassifierChoiceQuestion = {
+  type: "choice",
+  instructions:
+    "What does the user's `prompt` ask the assistant to do, given the workflow `phase` the session is in? Judge the request itself, not its tone. A short reply that answers or approves what the assistant just said is a continuation.",
+  criteria: {
+    "new-work":
+      "Asks to build, add, change, remove, rename or restructure something in the code, docs or configuration",
+    fix: "Reports something broken, failing or wrong and wants it repaired",
+    review: "Asks for existing work, a diff, a plan or a document to be reviewed or checked",
+    question:
+      "Asks for an explanation, information or an opinion and does not ask for any change to be made",
+    continuation:
+      "A short reply to the assistant's last message: a confirmation, a choice, 'continue', 'yes', 'go ahead', or an answer to its question",
+  },
+};
+
+const PROMPT_MAX = 1500;
+const isIntent = (value: string): value is Intent => INTENTS.some((i) => i === value);
+
+export async function judgeIntent(
+  jev: Jev,
+  input: { prompt: string; phase: string },
+): Promise<Result<{ intent: Intent; confidence: number }, JevError>> {
+  const prompt = redactSecrets(input.prompt.slice(0, PROMPT_MAX * 2)).slice(0, PROMPT_MAX);
+  const asked = await jev.ask({ prompt, phase: input.phase }, { intent: INTENT_QUESTION });
+  if (!asked.ok) return asked;
+  const answer = asked.value.intent;
+  if (answer?.type !== "choice" || !isIntent(answer.choice)) {
+    return err({ kind: "provider", message: "missing or unknown intent answer" });
+  }
+  return ok({ intent: answer.choice, confidence: answer.confidence });
+}