@tianhai/pi-workflow-kit 0.4.1 → 0.5.0

package/extensions/workflow-monitor/workflow-next-completions.ts

@@ -0,0 +1,68 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { AutocompleteItem } from "@mariozechner/pi-tui";
+
+const WORKFLOW_NEXT_PHASES = ["brainstorm", "plan", "execute", "finalize"] as const;
+const ARTIFACT_SUFFIX_BY_PHASE = {
+  brainstorm: null,
+  plan: "-design.md",
+  execute: "-implementation.md",
+  finalize: "-implementation.md",
+} as const;
+
+type WorkflowNextPhase = (typeof WORKFLOW_NEXT_PHASES)[number];
+
+function getPhaseCompletions(prefix: string): AutocompleteItem[] | null {
+  const normalized = prefix.replace(/^\s+/, "");
+  const firstToken = normalized.split(/\s+/, 1)[0] ?? "";
+  const completingFirstArg = normalized.length === 0 || !/\s/.test(normalized);
+
+  if (completingFirstArg || !WORKFLOW_NEXT_PHASES.includes(firstToken as WorkflowNextPhase)) {
+    const phasePrefix = completingFirstArg ? normalized : firstToken;
+    const items = WORKFLOW_NEXT_PHASES.filter((phase) => phase.startsWith(phasePrefix)).map((phase) => ({
+      value: phase,
+      label: phase,
+    }));
+    return items.length > 0 ? items : null;
+  }
+
+  return null;
+}
+
+function listArtifactsForPhase(phase: WorkflowNextPhase, typedPrefix: string): AutocompleteItem[] | null {
+  const suffix = ARTIFACT_SUFFIX_BY_PHASE[phase];
+  if (!suffix) return null;
+
+  const plansDir = path.join(process.cwd(), "docs", "plans");
+  if (!fs.existsSync(plansDir)) return null;
+
+  try {
+    const items = fs
+      .readdirSync(plansDir)
+      .filter((name) => name.endsWith(suffix))
+      .map((name) => path.join("docs", "plans", name))
+      .filter((relPath) => relPath.startsWith(typedPrefix))
+      .map((relPath) => ({ value: relPath, label: relPath }));
+
+    return items.length > 0 ? items : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function getWorkflowNextCompletions(prefix: string): Promise<AutocompleteItem[] | null> {
+  const phaseCompletions = getPhaseCompletions(prefix);
+  if (phaseCompletions) return phaseCompletions;
+
+  const normalized = prefix.replace(/^\s+/, "");
+  const match = normalized.match(/^(\S+)(?:\s+(.*))?$/);
+  const phase = match?.[1] as WorkflowNextPhase | undefined;
+  const artifactPrefix = match?.[2] ?? "";
+  const startingSecondArg = /\s$/.test(prefix) || artifactPrefix.length > 0;
+
+  if (phase && WORKFLOW_NEXT_PHASES.includes(phase) && startingSecondArg) {
+    return listArtifactsForPhase(phase, artifactPrefix);
+  }
+
+  return null;
+}

package/extensions/workflow-monitor/workflow-next-state.ts

@@ -0,0 +1,112 @@
+/**
+ * Pure helper functions for /workflow-next handoff validation and derived state.
+ *
+ * These functions have no side effects and no dependencies on the extension runtime,
+ * making them straightforward to test and reason about.
+ */
+
+import { type Phase, type PhaseStatus, WORKFLOW_PHASES, type WorkflowTrackerState } from "./workflow-tracker";
+
+/** Map of each phase to its immediate next phase (null for finalize). */
+const NEXT_PHASE: Record<Phase, Phase | null> = {
+  brainstorm: "plan",
+  plan: "execute",
+  execute: "finalize",
+  finalize: null,
+};
+
+/**
+ * Validate whether a `/workflow-next` request is allowed.
+ *
+ * Rules:
+ * - A current phase must exist in the workflow state.
+ * - The current phase must have status exactly "complete".
+ * - The requested phase must be the immediate next phase.
+ *
+ * Returns `null` if the handoff is valid, or an error message string.
+ */
+export function validateNextWorkflowPhase(currentState: WorkflowTrackerState, requestedPhase: Phase): string | null {
+  const current = currentState.currentPhase;
+
+  if (!current) {
+    return "No workflow phase is active. Start a workflow first or use /workflow-reset.";
+  }
+
+  const next = NEXT_PHASE[current];
+  if (next === null) {
+    return `Cannot hand off: ${current} is the final phase. Use /workflow-reset for a new task.`;
+  }
+
+  const currentStatus = currentState.phases[current];
+
+  // Same-phase handoff
+  if (requestedPhase === current) {
+    return `Cannot hand off to ${requestedPhase} from ${current}. Use /workflow-reset for a new task or continue in this session.`;
+  }
+
+  // Backward handoff
+  const currentIdx = WORKFLOW_PHASES.indexOf(current);
+  const requestedIdx = WORKFLOW_PHASES.indexOf(requestedPhase);
+  if (requestedIdx < currentIdx) {
+    return `Cannot hand off to ${requestedPhase} from ${current}: backward transitions are not allowed.`;
+  }
+
+  // Current phase not complete
+  if (currentStatus !== "complete") {
+    return `Cannot hand off to ${requestedPhase} because ${current} is not complete (status: ${currentStatus}).`;
+  }
+
+  // Direct jump (skipping intermediate phases)
+  if (requestedPhase !== next) {
+    return `Cannot hand off to ${requestedPhase} from ${current}. /workflow-next only supports the immediate next phase: ${next}.`;
+  }
+
+  return null;
+}
+
+/**
+ * Derive the workflow state snapshot for a new session created by `/workflow-next`.
+ *
+ * Rules:
+ * - All phases before the requested phase are marked "complete".
+ * - The requested phase is marked "active".
+ * - All phases after the requested phase are marked "pending".
+ * - currentPhase is set to the requested phase.
+ * - Artifacts and prompted flags are preserved for earlier phases.
+ */
+export function deriveWorkflowHandoffState(
+  currentState: WorkflowTrackerState,
+  requestedPhase: Phase,
+): WorkflowTrackerState {
+  const requestedIdx = WORKFLOW_PHASES.indexOf(requestedPhase);
+
+  const newPhases = { ...currentState.phases };
+  const newArtifacts = { ...currentState.artifacts };
+  const newPrompted = { ...currentState.prompted };
+
+  for (let i = 0; i < WORKFLOW_PHASES.length; i++) {
+    const phase = WORKFLOW_PHASES[i]!;
+
+    if (i < requestedIdx) {
+      // Earlier phases: mark complete, preserve artifacts/prompted
+      newPhases[phase] = "complete";
+    } else if (i === requestedIdx) {
+      // Target phase: active
+      newPhases[phase] = "active";
+      newArtifacts[phase] = currentState.artifacts[phase] ?? null;
+      newPrompted[phase] = false;
+    } else {
+      // Later phases: pending, clear artifacts/prompted
+      newPhases[phase] = "pending";
+      newArtifacts[phase] = null;
+      newPrompted[phase] = false;
+    }
+  }
+
+  return {
+    phases: newPhases as Record<Phase, PhaseStatus>,
+    currentPhase: requestedPhase,
+    artifacts: newArtifacts as Record<Phase, string | null>,
+    prompted: newPrompted as Record<Phase, boolean>,
+  };
+}

package/extensions/workflow-monitor.ts

@@ -27,7 +27,16 @@ import {
   getTddViolationWarning,
   getVerificationViolationWarning,
 } from "./workflow-monitor/warnings";
-import { createWorkflowHandler, type Violation, type WorkflowHandler } from "./workflow-monitor/workflow-handler";
+import {
+  createWorkflowHandler,
+  DEBUG_DEFAULTS,
+  TDD_DEFAULTS,
+  VERIFICATION_DEFAULTS,
+  type Violation,
+  type WorkflowHandler,
+} from "./workflow-monitor/workflow-handler";
+import { getWorkflowNextCompletions } from "./workflow-monitor/workflow-next-completions";
+import { deriveWorkflowHandoffState, validateNextWorkflowPhase } from "./workflow-monitor/workflow-next-state";
 import {
   computeBoundaryToPrompt,
   type Phase,
@@ -55,10 +64,14 @@ async function selectValue<T extends string>(
 
 const SUPERPOWERS_STATE_ENTRY_TYPE = "superpowers_state";
 
-export function getStateFilePath(): string {
+function getLegacyStateFilePath(): string {
   return path.join(process.cwd(), ".pi", "superpowers-state.json");
 }
 
+export function getStateFilePath(): string {
+  return path.join(process.cwd(), ".pi", "workflow-kit-state.json");
+}
+
 export function reconstructState(ctx: ExtensionContext, handler: WorkflowHandler, stateFilePath?: string | false) {
   handler.resetState();
 
@@ -68,10 +81,17 @@ export function reconstructState(ctx: ExtensionContext, handler: WorkflowHandler
 
   if (stateFilePath !== false) {
     try {
-      const statePath = stateFilePath ?? getStateFilePath();
-      if (fs.existsSync(statePath)) {
-        const raw = fs.readFileSync(statePath, "utf-8");
+      const newPath = stateFilePath ?? getStateFilePath();
+      if (fs.existsSync(newPath)) {
+        const raw = fs.readFileSync(newPath, "utf-8");
         fileData = JSON.parse(raw);
+      } else if (stateFilePath === undefined) {
+        // Legacy fallback: try the old filename only when no explicit path is given.
+        const legacyPath = getLegacyStateFilePath();
+        if (fs.existsSync(legacyPath)) {
+          const raw = fs.readFileSync(legacyPath, "utf-8");
+          fileData = JSON.parse(raw);
+        }
       }
     } catch (err) {
       log.warn(
@@ -812,6 +832,7 @@ export default function (pi: ExtensionAPI) {
 
   pi.registerCommand("workflow-next", {
     description: "Start a fresh session for the next workflow phase (optionally referencing an artifact path)",
+    getArgumentCompletions: getWorkflowNextCompletions,
     async handler(args, ctx) {
       if (!ctx.hasUI) {
         ctx.ui.notify("workflow-next requires interactive mode", "error");
@@ -828,8 +849,38 @@ export default function (pi: ExtensionAPI) {
         return;
       }
 
+      // Validate handoff against current workflow state
+      const currentWorkflowState = handler.getWorkflowState();
+      if (currentWorkflowState?.currentPhase) {
+        const validationError = validateNextWorkflowPhase(currentWorkflowState, phase as Phase);
+        if (validationError) {
+          ctx.ui.notify(validationError, "error");
+          return;
+        }
+      }
+
+      // Derive handoff state for session seeding
+      const derivedWorkflow = currentWorkflowState
+        ? deriveWorkflowHandoffState(currentWorkflowState, phase as Phase)
+        : undefined;
+
       const parentSession = ctx.sessionManager.getSessionFile();
-      const res = await ctx.newSession({ parentSession });
+      const res = await ctx.newSession({
+        parentSession,
+        setup: derivedWorkflow
+          ? async (sm) => {
+              const fullState = handler.getFullState();
+              sm.appendCustomEntry(SUPERPOWERS_STATE_ENTRY_TYPE, {
+                ...fullState,
+                workflow: derivedWorkflow,
+                tdd: { ...TDD_DEFAULTS, testFiles: [], sourceFiles: [] },
+                debug: { ...DEBUG_DEFAULTS },
+                verification: { ...VERIFICATION_DEFAULTS },
+                savedAt: Date.now(),
+              });
+            }
+          : undefined,
+      });
       if (res.cancelled) return;
 
       const lines: string[] = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tianhai/pi-workflow-kit",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Workflow skills and enforcement extensions for pi",
   "keywords": [
     "pi-package"