pi-better-goal 0.2.2 → 0.3.0

package/README.md

@@ -19,6 +19,19 @@ Use `pi-better-goal` when a Pi session should keep an explicit objective visible
 - A progress-aware follow-up loop that holds after repeated identical outcomes.
 - An observable-progress stall state for active goals.
 
+## Skill-Owned Workflows
+
+Skills that own execution and their own task plan can opt in through `SKILL.md` frontmatter:
+
+```yaml
+metadata:
+  pi-better-plan-workflow: coordinator
+```
+
+Invoke the skill with Pi's `/skill:name` command. The goal extension checks Pi's skill-command provenance, persists the owner on the session branch, and restores its instructions on resumed turns. It does not infer ownership from ordinary text or skill names. A goal such as `/goal /skill:name task` is rejected; invoke `/skill:name task` directly and use `/goal` only for a plain-language objective. Legacy slash-shaped goals pause on resume rather than running without the skill. `/workflow` shows the owner; call `release_workflow` after the workflow's completion audit (or use `/workflow clear` to release it manually). Completing an active goal also releases ownership.
+
+When `pi-better-plan` is installed, it defers its prompt, checklist, and `update_plan` tool to a skill-owned task plan. Skills without this metadata retain normal goal and plan behavior. The skill itself owns its planning format and worker policy; the harness does not enumerate skills or impose a shared workflow schema.
+
 ## Install
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-goal",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Pi extension for goal tracking with background-aware continuation.",
   "license": "MIT",
   "type": "module",
@@ -67,5 +67,8 @@
   },
   "engines": {
     "node": ">=22.0.0"
+  },
+  "dependencies": {
+    "yaml": "^2.9.1"
   }
 }

package/src/index.ts

@@ -1,5 +1,6 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { AutocompleteItem } from "@earendil-works/pi-tui";
+import { readFileSync } from "node:fs";
 import { Type } from "typebox";
 
 import {
@@ -33,6 +34,7 @@ import {
 } from "./goal-clock.js";
 import { createRenderScheduler } from "./shared-render-scheduler.js";
 import { collectSubagentActivity } from "./subagents.js";
+import { currentWorkflowOwner, skillCommandName, workflowEntry, workflowOwnerFromSkill, WORKFLOW_ENTRY_TYPE } from "./workflow.js";
 import {
   EVENT_ACTIVITY,
   EVENT_READY,
@@ -109,13 +111,15 @@ function wasTurnAborted(messages: readonly unknown[]): boolean {
   return false;
 }
 
-function continuationPrompt(goal: GoalSnapshot): string {
+function continuationPrompt(goal: GoalSnapshot, owner: ReturnType<typeof currentWorkflowOwner> = null): string {
   return [
     "Continue working toward the active thread goal.",
     "",
     `Goal: ${goal.objective}`,
     "",
-    "Keep working through clear low-risk next steps. Do not stop at a plan. Mark the goal complete only after an evidence-backed completion audit proves no required work remains.",
+    owner
+      ? `Continue the ${owner.name} workflow as its coordinator. Its own task plan is authoritative; do not implement product code in the parent. Mark the goal complete only after the workflow's completion audit.`
+      : "Keep working through clear low-risk next steps. Do not stop at a plan. Mark the goal complete only after an evidence-backed completion audit proves no required work remains.",
   ].join("\n");
 }
 
@@ -185,6 +189,20 @@ export default function (pi: ExtensionAPI): void {
   let lastAgentEvidence: ContinuationEvidence | null = null;
 
   const getGoal = (ctx: ExtensionContext): GoalSnapshot | null => currentGoalSnapshot(ctx);
+  const getWorkflow = (ctx: ExtensionContext) => currentWorkflowOwner(ctx.sessionManager.getBranch());
+  const workflowAvailable = (owner: NonNullable<ReturnType<typeof currentWorkflowOwner>>): boolean => {
+    const command = pi.getCommands?.().find((item) => item.name === `skill:${owner.name}` && item.source === "skill");
+    if (command?.sourceInfo.path !== owner.path) return false;
+    try {
+      return workflowOwnerFromSkill(owner.name, owner.path)?.planOwner === owner.planOwner;
+    } catch {
+      return false;
+    }
+  };
+  const recordWorkflow = (owner: ReturnType<typeof currentWorkflowOwner>): void => {
+    pi.appendEntry(WORKFLOW_ENTRY_TYPE, workflowEntry(owner));
+    pi.events.emit("pi-better-workflow:changed", owner);
+  };
 
   /** Only active goals receive autonomous pokes; paused, complete, and budget-limited goals never do. */
   const isPokeable = (goal: GoalSnapshot | null): goal is GoalSnapshot => goal?.status === "active";
@@ -241,6 +259,7 @@ export default function (pi: ExtensionAPI): void {
     const current = getGoal(ctx);
     const wasVisible = current !== null && isGoalClockVisible(current);
     pi.appendEntry(EXTENSION_NAME, goalClearEntry(current?.goalId ?? null, source));
+    if (getWorkflow(ctx)) recordWorkflow(null);
     continuationQueuedFor = null;
     backgroundDrainTracker = null;
     clearIdleContinuation();
@@ -248,6 +267,15 @@ export default function (pi: ExtensionAPI): void {
     refreshGoalWidget?.(wasVisible);
   };
 
+  const pauseGoalOnInterrupt = (ctx: ExtensionContext): void => {
+    const goal = getGoal(ctx);
+    if (!isPokeable(goal)) {
+      return;
+    }
+    setGoal(goalWithStatus(goal, "paused"), ctx, "runtime");
+    notifyGoal(ctx, "Goal paused (interrupted).");
+  };
+
   const queueGoalContinuation = (goal: GoalSnapshot): void => {
     if (!isPokeable(goal) || continuationQueuedFor === goal.goalId) {
       return;
@@ -258,7 +286,7 @@ export default function (pi: ExtensionAPI): void {
     pi.sendMessage(
       {
         customType: EXTENSION_NAME,
-        content: continuationPrompt(goal),
+        content: continuationPrompt(goal, currentCtx ? getWorkflow(currentCtx) : null),
         display: false,
         details: { kind: "continuation", goalId: goal.goalId },
       },
@@ -324,8 +352,8 @@ export default function (pi: ExtensionAPI): void {
     continuationQueuedFor = goal.goalId;
     const content = kind === "background-drained"
       ? "Background activity for the active goal is no longer running. Inspect any subagent callbacks or final results, then continue the completion audit before marking the goal complete.\n\n" +
-        continuationPrompt(goal)
-      : continuationPrompt(goal);
+        continuationPrompt(goal, getWorkflow(ctx))
+      : continuationPrompt(goal, getWorkflow(ctx));
     pi.sendMessage(
       {
         customType: EXTENSION_NAME,
@@ -345,6 +373,9 @@ export default function (pi: ExtensionAPI): void {
     ctx: ExtensionContext,
     source: "command",
   ): GoalSnapshot => {
+    if (skillCommandName(objective)) {
+      throw new Error("A skill command cannot be a goal objective. Invoke /skill:name directly so Pi loads the skill, then set a plain-language goal if needed.");
+    }
     const objectiveError = validateObjective(objective);
     if (objectiveError) {
       throw new Error(objectiveError);
@@ -557,6 +588,10 @@ export default function (pi: ExtensionAPI): void {
           notifyGoal(ctx, "Only paused goals can be resumed.", "warning");
           return;
         }
+        if (skillCommandName(current.objective)) {
+          notifyGoal(ctx, "Invoke the skill directly; this legacy slash-command goal cannot resume as plain text.", "error");
+          return;
+        }
         const goal = goalWithStatus(current, "active");
         setGoal(goal, ctx, "command");
         queueGoalContinuation(goal);
@@ -576,6 +611,7 @@ export default function (pi: ExtensionAPI): void {
           return;
         }
         setGoal(goalWithStatus(current, "complete"), ctx, "command");
+        if (getWorkflow(ctx)) recordWorkflow(null);
         notifyGoal(ctx, "Goal marked complete.");
         return;
       }
@@ -653,6 +689,7 @@ export default function (pi: ExtensionAPI): void {
       }
       const goal = goalWithStatus(current, "complete");
       setGoal(goal, ctx, "tool");
+      if (getWorkflow(ctx)) recordWorkflow(null);
       return {
         content: [{ type: "text", text: "Goal marked complete." }],
         details: { ok: true, goal },
@@ -669,6 +706,32 @@ export default function (pi: ExtensionAPI): void {
     },
   });
 
+  pi.registerCommand("workflow", {
+    description: "Inspect or clear the active skill-owned workflow",
+    handler: async (args, ctx) => {
+      if (args.trim() === "clear") {
+        recordWorkflow(null);
+        notifyGoal(ctx, "Workflow ownership cleared.");
+        return;
+      }
+      const owner = getWorkflow(ctx);
+      notifyGoal(ctx, owner ? `Workflow: ${owner.name} (${owner.path}); plan owned by workflow.` : "No workflow owns this session.");
+    },
+  });
+
+  pi.registerTool({
+    name: "release_workflow",
+    label: "Release Workflow",
+    description: "Release the active skill-owned workflow after its final handoff and completion audit.",
+    parameters: Type.Object({}),
+    async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+      const owner = getWorkflow(ctx);
+      if (!owner) return { content: [{ type: "text", text: "No workflow owns this session." }], details: { released: false } };
+      recordWorkflow(null);
+      return { content: [{ type: "text", text: `Released ${owner.name} workflow ownership.` }], details: { released: true, owner: owner.name } };
+    },
+  });
+
   pi.registerTool({
     name: "get_background_activity",
     label: "Get Background Activity",
@@ -688,6 +751,11 @@ export default function (pi: ExtensionAPI): void {
   pi.on("session_start", async (_event, ctx) => {
     currentCtx = ctx;
     foregroundRunning = !ctx.isIdle();
+    const restoredGoal = getGoal(ctx);
+    if (restoredGoal?.status === "active" && skillCommandName(restoredGoal.objective)) {
+      setGoal(goalWithStatus(restoredGoal, "paused"), ctx, "runtime");
+      notifyGoal(ctx, "Goal paused: invoke its skill directly before resuming.", "error");
+    }
     pi.events.emit(EVENT_READY, { version: EXTENSION_VERSION });
     installGoalWidget(ctx);
     latestSnapshot = await publishSnapshot(ctx);
@@ -698,6 +766,19 @@ export default function (pi: ExtensionAPI): void {
     if (event.source === "extension") {
       return;
     }
+    const skillName = skillCommandName(event.text ?? "");
+    if (skillName) {
+      const command = pi.getCommands?.().find((item) => item.name === `skill:${skillName}` && item.source === "skill");
+      if (command) {
+        try {
+          const owner = workflowOwnerFromSkill(skillName, command.sourceInfo.path);
+          if (owner) recordWorkflow(owner);
+        } catch (error) {
+          notifyGoal(ctx, error instanceof Error ? error.message : String(error), "error");
+          return { action: "handled" as const };
+        }
+      }
+    }
     const goal = getGoal(ctx);
     if (goal?.status === "active") {
       resetContinuationState(goal);
@@ -707,11 +788,32 @@ export default function (pi: ExtensionAPI): void {
   pi.on("before_agent_start", async (event, ctx) => {
     currentCtx = ctx;
     const goal = currentGoalSnapshot(ctx);
+    const owner = getWorkflow(ctx);
     const snapshot = await publishSnapshot(ctx);
-    if (!isPokeable(goal)) {
+    if (!isPokeable(goal) && !owner) {
       return;
     }
 
+    if (owner) {
+      if (!workflowAvailable(owner)) {
+        if (isPokeable(goal)) setGoal(goalWithStatus(goal, "paused"), ctx, "runtime");
+        recordWorkflow(null);
+        return { systemPrompt: `${event.systemPrompt}\n\nWorkflow ${owner.name} is no longer a registered, valid skill. Stop work and ask the user to reinvoke the skill.` };
+      }
+      let instructions: string;
+      try {
+        instructions = readFileSync(owner.path, "utf8");
+      } catch {
+        if (isPokeable(goal)) setGoal(goalWithStatus(goal, "paused"), ctx, "runtime");
+        return { systemPrompt: `${event.systemPrompt}\n\nWorkflow ${owner.name} is unavailable. Stop work and ask the user to restore or reinvoke the skill.` };
+      }
+      return {
+        systemPrompt: `${event.systemPrompt}\n\nActive workflow: ${owner.name} (${owner.path}). Its task plan owns planning and the parent is a coordinator, not a product-code implementer. Follow the workflow instructions below, including on resumed turns:\n\n${instructions}` +
+          (isPokeable(goal) ? `\n\nActive objective: ${goal.objective}. Complete it only after the workflow completion audit.` : ""),
+      };
+    }
+
+    if (!isPokeable(goal)) return;
     const backgroundInstruction = snapshot.backgroundRunning
       ? ` The goal still has delegated background work running (${summarizeActiveBackground(snapshot)}). Foreground idleness alone is not goal completion; keep any structured plan current and do not mark verification, the plan, or the goal complete until every relevant delegated task reaches a terminal state and its result or failure has been inspected and integrated.`
       : "";
@@ -728,6 +830,14 @@ export default function (pi: ExtensionAPI): void {
     clearIdleContinuation();
     continuationQueuedFor = null;
     lastAgentEvidence = null;
+    const turnSignal = ctx.signal;
+    if (turnSignal) {
+      if (turnSignal.aborted) {
+        pauseGoalOnInterrupt(ctx);
+      } else {
+        turnSignal.addEventListener("abort", () => pauseGoalOnInterrupt(ctx), { once: true });
+      }
+    }
     await publishSnapshot(ctx);
   });
 
@@ -738,13 +848,7 @@ export default function (pi: ExtensionAPI): void {
     // aborted (escape / ctrl+c while streaming), pause the active goal so it does
     // not auto-continue after the user stopped the agent.
     if (wasTurnAborted(event.messages)) {
-      const goal = getGoal(ctx);
-      if (isPokeable(goal)) {
-        setGoal(goalWithStatus(goal, "paused"), ctx, "runtime");
-        if (ctx.hasUI) {
-          ctx.ui.notify("Goal paused (interrupted).", "info");
-        }
-      }
+      pauseGoalOnInterrupt(ctx);
     }
   });
 

package/src/workflow.ts

@@ -0,0 +1,63 @@
+import { readFileSync } from "node:fs";
+import { parse } from "yaml";
+
+export const WORKFLOW_ENTRY_TYPE = "pi-better-workflow";
+
+export interface WorkflowOwner {
+  name: string;
+  path: string;
+  role: "coordinator";
+  planOwner: "workflow";
+}
+
+interface SessionEntryLike {
+  type: string;
+  customType?: string;
+  data?: unknown;
+}
+
+export function workflowOwnerFromSkill(name: string, path: string): WorkflowOwner | null {
+  const source = readFileSync(path, "utf8");
+  const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(source);
+  if (!match) return null;
+  const frontmatter: unknown = parse(match[1]!);
+  if (!frontmatter || typeof frontmatter !== "object") return null;
+  const metadata = (frontmatter as { metadata?: unknown }).metadata;
+  if (!metadata || typeof metadata !== "object") return null;
+  const fields = metadata as Record<string, unknown>;
+  if (fields["pi-better-plan-workflow"] === undefined) {
+    if (fields["pi-better-workflow-role"] !== undefined || fields["pi-better-plan-owner"] !== undefined) {
+      throw new Error(`Outdated workflow metadata in ${path}. Use pi-better-plan-workflow: coordinator.`);
+    }
+    return null;
+  }
+  if (fields["pi-better-plan-workflow"] !== "coordinator") {
+    throw new Error(`Invalid workflow metadata in ${path}. Expected pi-better-plan-workflow: coordinator.`);
+  }
+  return { name, path, role: "coordinator", planOwner: "workflow" };
+}
+
+export function workflowEntry(owner: WorkflowOwner | null) {
+  return owner === null
+    ? { version: 1, kind: "clear" as const }
+    : { version: 1, kind: "set" as const, owner };
+}
+
+export function currentWorkflowOwner(entries: Iterable<SessionEntryLike>): WorkflowOwner | null {
+  let owner: WorkflowOwner | null = null;
+  for (const entry of entries) {
+    if (entry.type !== "custom" || entry.customType !== WORKFLOW_ENTRY_TYPE) continue;
+    const data = entry.data as { version?: unknown; kind?: unknown; owner?: Partial<WorkflowOwner> } | null;
+    if (data?.version !== 1) continue;
+    if (data.kind === "clear") owner = null;
+    else if (data.kind === "set" && typeof data.owner?.name === "string" &&
+      typeof data.owner.path === "string" && data.owner.role === "coordinator" && data.owner.planOwner === "workflow") {
+      owner = data.owner as WorkflowOwner;
+    }
+  }
+  return owner;
+}
+
+export function skillCommandName(text: string): string | null {
+  return /^\/skill:([a-z0-9]+(?:-[a-z0-9]+)*)(?:\s|$)/.exec(text.trim())?.[1] ?? null;
+}