@tianhai/pi-workflow-kit 0.4.1

package/extensions/workflow-monitor/workflow-handler.ts

@@ -0,0 +1,358 @@
+import type { SessionEntry } from "@mariozechner/pi-coding-agent";
+import type { PlanTrackerDetails, PlanTrackerTask } from "../plan-tracker.js";
+import { DebugMonitor, type DebugViolation } from "./debug-monitor";
+import { isSourceFile } from "./heuristics";
+import { isInvestigationCommand, isInvestigationToolCall } from "./investigation";
+import { TddMonitor, type TddPhase, type TddViolation } from "./tdd-monitor";
+import { parseTestCommand, parseTestResult } from "./test-runner";
+import { VerificationMonitor, type VerificationViolation } from "./verification-monitor";
+import { type Phase, type PhaseStatus, WorkflowTracker, type WorkflowTrackerState } from "./workflow-tracker";
+
+export type Violation = TddViolation | DebugViolation;
+
+export interface ToolCallResult {
+  violation: Violation | null;
+}
+
+export interface SuperpowersStateSnapshot {
+  workflow: WorkflowTrackerState;
+  tdd: {
+    phase: TddPhase;
+    testFiles: string[];
+    sourceFiles: string[];
+    redVerificationPending: boolean;
+    nonCodeMode: boolean;
+  };
+  debug: {
+    active: boolean;
+    investigated: boolean;
+    fixAttempts: number;
+  };
+  verification: {
+    verified: boolean;
+    verificationWaived: boolean;
+  };
+}
+
+export type SuperpowersStatePatch = {
+  workflow?: Partial<WorkflowTrackerState> & {
+    phases?: Partial<Record<Phase, PhaseStatus>>;
+    artifacts?: Partial<Record<Phase, string | null>>;
+    prompted?: Partial<Record<Phase, boolean>>;
+  };
+  tdd?: Partial<SuperpowersStateSnapshot["tdd"]>;
+  debug?: Partial<SuperpowersStateSnapshot["debug"]>;
+  verification?: Partial<SuperpowersStateSnapshot["verification"]>;
+};
+
+export const TDD_DEFAULTS = {
+  phase: "idle" as TddPhase,
+  testFiles: [] as string[],
+  sourceFiles: [] as string[],
+  redVerificationPending: false,
+  nonCodeMode: false,
+};
+
+export const DEBUG_DEFAULTS = {
+  active: false,
+  investigated: false,
+  fixAttempts: 0,
+};
+
+export const VERIFICATION_DEFAULTS = {
+  verified: false,
+  verificationWaived: false,
+};
+
+export interface WorkflowHandler {
+  handleToolCall(toolName: string, input: Record<string, unknown>): ToolCallResult;
+  handleReadOrInvestigation(toolName: string, path: string): void;
+  handleBashResult(command: string, output: string, exitCode: number | undefined): void;
+  /** @internal Used in tests; will be wired to bash events in future */
+  handleBashInvestigation(command: string): void;
+  isDebugActive(): boolean;
+  getDebugFixAttempts(): number;
+  getTddPhase(): string;
+  getWidgetText(): string;
+  getTddState(): ReturnType<TddMonitor["getState"]>;
+  checkCommitGate(command: string): VerificationViolation | null;
+  recordVerificationWaiver(): void;
+  restoreTddState(phase: TddPhase, testFiles: string[], sourceFiles: string[], redVerificationPending?: boolean): void;
+  handleInputText(text: string): boolean;
+  handleFileWritten(path: string): boolean;
+  handlePlanTrackerToolCall(input: Record<string, unknown>): boolean;
+  handlePlanTrackerToolResult(details: PlanTrackerDetails | undefined): boolean;
+  getWorkflowState(): WorkflowTrackerState | null;
+  getFullState(): SuperpowersStateSnapshot;
+  setFullState(snapshot: SuperpowersStatePatch): void;
+  restoreWorkflowStateFromBranch(branch: SessionEntry[]): void;
+  markWorkflowPrompted(phase: Phase): boolean;
+  completeCurrentWorkflowPhase(): boolean;
+  advanceWorkflowTo(phase: Phase): boolean;
+  skipWorkflowPhases(phases: Phase[]): boolean;
+  handleSkillFileRead(path: string): boolean;
+  resetState(): void;
+}
+
+function deriveNonCodeMode(tasks: PlanTrackerTask[]): boolean {
+  const activeTask = tasks.find((task) => task.status === "in_progress");
+  return activeTask?.type === "non-code";
+}
+
+function areAllTasksTerminal(tasks: PlanTrackerTask[]): boolean {
+  return tasks.length > 0 && tasks.every((task) => task.status === "complete" || task.status === "blocked");
+}
+
+export function createWorkflowHandler(): WorkflowHandler {
+  const tdd = new TddMonitor();
+  const debug = new DebugMonitor();
+  const verification = new VerificationMonitor();
+  const tracker = new WorkflowTracker();
+  let debugFailStreak = 0;
+
+  return {
+    handleToolCall(toolName: string, input: Record<string, unknown>): ToolCallResult {
+      // Track investigation from tool calls (LSP, kota, web search)
+      if (isInvestigationToolCall(toolName, input)) {
+        debug.onInvestigation();
+      }
+
+      if (toolName === "write" || toolName === "edit") {
+        const path = input.path as string | undefined;
+        if (path) {
+          if (isSourceFile(path)) {
+            verification.onSourceWritten();
+          }
+
+          // Debug violations take precedence, and when debug is active we don't
+          // additionally enforce TDD write-order violations.
+          if (debug.isActive() && isSourceFile(path)) {
+            const debugViolation = debug.onSourceWritten(path);
+            return { violation: debugViolation };
+          }
+
+          const tddViolation = tdd.onFileWritten(path);
+          return { violation: tddViolation };
+        }
+      }
+      return { violation: null };
+    },
+
+    handleReadOrInvestigation(toolName: string, _path: string): void {
+      if (toolName === "read") {
+        debug.onInvestigation();
+      }
+    },
+
+    handleBashResult(command: string, output: string, exitCode: number | undefined): void {
+      if (isInvestigationCommand(command)) {
+        debug.onInvestigation();
+      }
+
+      if (/\bgit\s+commit\b/.test(command)) {
+        debugFailStreak = 0;
+        tdd.onCommit();
+        debug.onCommit();
+        return;
+      }
+
+      if (parseTestCommand(command)) {
+        const passed = parseTestResult(output, exitCode);
+        if (passed !== null) {
+          if (passed) {
+            verification.recordVerification();
+          } else {
+            verification.reset();
+          }
+
+          const excludeFromDebug = !passed && tdd.getPhase() === "red-pending";
+
+          tdd.onTestResult(passed);
+
+          if (passed) {
+            debugFailStreak = 0;
+            debug.onTestPassed();
+          } else if (!excludeFromDebug) {
+            debugFailStreak += 1;
+            const tddPhase = tdd.getPhase();
+            if (debugFailStreak >= 1 && tddPhase === "idle") {
+              debug.onTestFailed();
+            }
+          }
+        }
+      }
+    },
+
+    handleBashInvestigation(command: string): void {
+      if (isInvestigationCommand(command)) {
+        debug.onInvestigation();
+      }
+    },
+
+    isDebugActive(): boolean {
+      return debug.isActive();
+    },
+
+    getDebugFixAttempts(): number {
+      return debug.getFixAttempts();
+    },
+
+    getTddPhase(): string {
+      return tdd.getPhase();
+    },
+
+    getWidgetText(): string {
+      const parts: string[] = [];
+
+      const phase = tdd.getPhase();
+      if (phase !== "idle") {
+        parts.push(`TDD: ${phase.toUpperCase()}`);
+      }
+
+      if (debug.isActive()) {
+        parts.push("Debug: ACTIVE");
+      }
+
+      return parts.join(" | ");
+    },
+
+    getTddState() {
+      return tdd.getState();
+    },
+
+    checkCommitGate(command: string) {
+      return verification.checkCommitGate(command);
+    },
+
+    recordVerificationWaiver() {
+      verification.recordVerificationWaiver();
+    },
+
+    restoreTddState(phase: TddPhase, testFiles: string[], sourceFiles: string[], redVerificationPending = false) {
+      tdd.setState(phase, testFiles, sourceFiles, redVerificationPending);
+    },
+
+    handleInputText(text: string) {
+      return tracker.onInputText(text);
+    },
+
+    handleFileWritten(path: string) {
+      return tracker.onFileWritten(path);
+    },
+
+    handlePlanTrackerToolCall(input: Record<string, unknown>) {
+      if (input.action === "init") {
+        tdd.setNonCodeMode(false);
+        return tracker.onPlanTrackerInit();
+      }
+      return false;
+    },
+
+    handlePlanTrackerToolResult(details: PlanTrackerDetails | undefined) {
+      if (!details) return false;
+
+      let changed = false;
+      const nextNonCodeMode = deriveNonCodeMode(details.tasks);
+      if (tdd.getState().nonCodeMode !== nextNonCodeMode) {
+        tdd.setNonCodeMode(nextNonCodeMode);
+        changed = true;
+      }
+
+      if (areAllTasksTerminal(details.tasks) && tracker.getState().currentPhase === "execute") {
+        changed = tracker.completeCurrent() || changed;
+      }
+
+      return changed;
+    },
+
+    getWorkflowState() {
+      return tracker.getState();
+    },
+
+    getFullState() {
+      return {
+        workflow: tracker.getState(),
+        tdd: tdd.getState(),
+        debug: debug.getState(),
+        verification: verification.getState(),
+      };
+    },
+
+    setFullState(snapshot: SuperpowersStatePatch) {
+      if (snapshot.workflow) {
+        const defaultWorkflow = new WorkflowTracker().getState();
+        tracker.setState({
+          ...defaultWorkflow,
+          ...snapshot.workflow,
+          phases: { ...defaultWorkflow.phases, ...snapshot.workflow.phases },
+          artifacts: { ...defaultWorkflow.artifacts, ...snapshot.workflow.artifacts },
+          prompted: { ...defaultWorkflow.prompted, ...snapshot.workflow.prompted },
+        });
+      }
+      if (snapshot.tdd) {
+        const tddState = { ...TDD_DEFAULTS, ...snapshot.tdd };
+        tdd.setState(
+          tddState.phase,
+          tddState.testFiles,
+          tddState.sourceFiles,
+          tddState.redVerificationPending,
+          tddState.nonCodeMode,
+        );
+      }
+      if (snapshot.debug) {
+        debug.setState({ ...DEBUG_DEFAULTS, ...snapshot.debug });
+      }
+      if (snapshot.verification) {
+        verification.setState({ ...VERIFICATION_DEFAULTS, ...snapshot.verification });
+      }
+      debugFailStreak = 0;
+    },
+
+    restoreWorkflowStateFromBranch(branch: SessionEntry[]) {
+      const state = WorkflowTracker.reconstructFromBranch(branch);
+      if (state) {
+        tracker.setState(state);
+      }
+    },
+
+    markWorkflowPrompted(phase: Phase) {
+      return tracker.markPrompted(phase);
+    },
+
+    completeCurrentWorkflowPhase() {
+      return tracker.completeCurrent();
+    },
+
+    advanceWorkflowTo(phase) {
+      return tracker.advanceTo(phase);
+    },
+
+    skipWorkflowPhases(phases) {
+      return tracker.skipPhases(phases);
+    },
+
+    handleSkillFileRead(path: string) {
+      return tracker.onSkillFileRead(path);
+    },
+
+    resetState() {
+      const freshState: SuperpowersStateSnapshot = {
+        workflow: new WorkflowTracker().getState(),
+        tdd: { ...TDD_DEFAULTS, testFiles: [], sourceFiles: [] },
+        debug: { ...DEBUG_DEFAULTS },
+        verification: { ...VERIFICATION_DEFAULTS },
+      };
+
+      tracker.setState(freshState.workflow);
+      tdd.setState(
+        freshState.tdd.phase,
+        freshState.tdd.testFiles,
+        freshState.tdd.sourceFiles,
+        freshState.tdd.redVerificationPending,
+      );
+      debug.setState(freshState.debug);
+      verification.setState(freshState.verification);
+      debugFailStreak = 0;
+    },
+  };
+}

package/extensions/workflow-monitor/workflow-tracker.ts

@@ -0,0 +1,231 @@
+import type { SessionEntry } from "@mariozechner/pi-coding-agent";
+
+export const WORKFLOW_PHASES = ["brainstorm", "plan", "execute", "finalize"] as const;
+
+export type Phase = (typeof WORKFLOW_PHASES)[number];
+export type PhaseStatus = "pending" | "active" | "complete" | "skipped";
+
+export interface WorkflowTrackerState {
+  phases: Record<Phase, PhaseStatus>;
+  currentPhase: Phase | null;
+  artifacts: Record<Phase, string | null>;
+  prompted: Record<Phase, boolean>;
+}
+
+export type TransitionBoundary = "design_committed" | "plan_ready" | "execution_complete";
+
+export function computeBoundaryToPrompt(state: WorkflowTrackerState): TransitionBoundary | null {
+  if (state.phases.brainstorm === "complete" && !state.prompted.brainstorm) {
+    return "design_committed";
+  }
+  if (state.phases.plan === "complete" && !state.prompted.plan) {
+    return "plan_ready";
+  }
+  if (state.phases.execute === "complete" && !state.prompted.execute) {
+    return "execution_complete";
+  }
+  return null;
+}
+
+function cloneState(state: WorkflowTrackerState): WorkflowTrackerState {
+  return JSON.parse(JSON.stringify(state)) as WorkflowTrackerState;
+}
+
+function emptyState(): WorkflowTrackerState {
+  const phases = Object.fromEntries(WORKFLOW_PHASES.map((p) => [p, "pending"])) as Record<Phase, PhaseStatus>;
+
+  const artifacts = Object.fromEntries(WORKFLOW_PHASES.map((p) => [p, null])) as Record<Phase, string | null>;
+
+  const prompted = Object.fromEntries(WORKFLOW_PHASES.map((p) => [p, false])) as Record<Phase, boolean>;
+
+  return { phases, currentPhase: null, artifacts, prompted };
+}
+
+export const WORKFLOW_TRACKER_ENTRY_TYPE = "workflow_tracker_state";
+
+export function parseSkillName(line: string): string | null {
+  const slashMatch = line.match(/^\s*\/skill:([^\s]+)/);
+  const xmlMatch = line.match(/<skill\s+name="([^"]+)"/);
+  return slashMatch?.[1] ?? xmlMatch?.[1] ?? null;
+}
+
+export const SKILL_TO_PHASE: Record<string, Phase> = {
+  brainstorming: "brainstorm",
+  "writing-plans": "plan",
+  "using-git-worktrees": "plan", // pre-execute worktree setup belongs to plan
+  "executing-tasks": "execute",
+  "systematic-debugging": "execute", // used within execute phase
+  "dispatching-parallel-agents": "execute", // used within execute phase
+  "test-driven-development": "execute", // makes TDD skill phase-aware
+  "receiving-code-review": "finalize", // post-PR external review
+};
+
+export function resolveSkillPhase(skill: string, state: WorkflowTrackerState | null | undefined): Phase | null {
+  if (skill === "executing-tasks") {
+    if (state?.currentPhase === "finalize" || state?.phases.execute === "complete") {
+      return "finalize";
+    }
+    return "execute";
+  }
+
+  return SKILL_TO_PHASE[skill] ?? null;
+}
+
+const PLANS_DIR_RE = /^docs\/plans\//;
+const DESIGN_RE = /-design\.md$/;
+const IMPLEMENTATION_RE = /-implementation\.md$/;
+
+export class WorkflowTracker {
+  private state: WorkflowTrackerState = emptyState();
+
+  getState(): WorkflowTrackerState {
+    return cloneState(this.state);
+  }
+
+  setState(state: WorkflowTrackerState): void {
+    this.state = cloneState(state);
+  }
+
+  reset(): void {
+    this.state = emptyState();
+  }
+
+  advanceTo(phase: Phase): boolean {
+    const current = this.state.currentPhase;
+    const nextIdx = WORKFLOW_PHASES.indexOf(phase);
+
+    if (current) {
+      const curIdx = WORKFLOW_PHASES.indexOf(current);
+      if (nextIdx <= curIdx) {
+        // Backward or same-phase navigation = new task. Reset everything.
+        this.reset();
+        // Fall through to activate the target phase below.
+      } else {
+        // Forward advance: auto-complete the current phase.
+        if (this.state.phases[current] === "active") {
+          this.state.phases[current] = "complete";
+        }
+      }
+    }
+
+    for (const p of WORKFLOW_PHASES) {
+      if (p !== phase && this.state.phases[p] === "active") {
+        this.state.phases[p] = "complete";
+      }
+    }
+
+    this.state.currentPhase = phase;
+    if (this.state.phases[phase] === "pending") {
+      this.state.phases[phase] = "active";
+    }
+
+    return true;
+  }
+
+  skipPhase(phase: Phase): boolean {
+    const status = this.state.phases[phase];
+    if (status !== "pending" && status !== "active") return false;
+    this.state.phases[phase] = "skipped";
+    return true;
+  }
+
+  skipPhases(phases: Phase[]): boolean {
+    let changed = false;
+    for (const p of phases) changed = this.skipPhase(p) || changed;
+    return changed;
+  }
+
+  completeCurrent(): boolean {
+    const phase = this.state.currentPhase;
+    if (!phase) return false;
+    if (this.state.phases[phase] === "complete") return false;
+    this.state.phases[phase] = "complete";
+    return true;
+  }
+
+  recordArtifact(phase: Phase, path: string): boolean {
+    if (this.state.artifacts[phase] === path) return false;
+    this.state.artifacts[phase] = path;
+    return true;
+  }
+
+  markPrompted(phase: Phase): boolean {
+    if (this.state.prompted[phase]) return false;
+    this.state.prompted[phase] = true;
+    return true;
+  }
+
+  onInputText(text: string): boolean {
+    const lines = text.split(/\r?\n/);
+    let changed = false;
+
+    for (const line of lines) {
+      const skill = parseSkillName(line);
+      if (!skill) continue;
+      const phase = resolveSkillPhase(skill, this.state);
+      if (!phase) continue;
+      // Guard against backward navigation: skills shared across phases (e.g. executing-tasks
+      // covers both execute and finalize) must not reset state when re-invoked in a later phase.
+      const currentIdx = this.state.currentPhase ? WORKFLOW_PHASES.indexOf(this.state.currentPhase) : -1;
+      const targetIdx = WORKFLOW_PHASES.indexOf(phase);
+      if (targetIdx <= currentIdx) continue;
+      if (this.advanceTo(phase)) changed = true;
+    }
+
+    return changed;
+  }
+
+  onSkillFileRead(path: string): boolean {
+    const match = path.match(/\/skills\/([^/]+)\/SKILL\.md$/);
+    if (!match) return false;
+    const phase = resolveSkillPhase(match[1], this.state);
+    if (!phase) return false;
+    // Guard against backward navigation: some skills (e.g. executing-tasks) serve
+    // multiple phases. Re-reading their SKILL.md during a later phase (e.g. finalize)
+    // must not reset workflow state. Rely on plan_tracker init or explicit /workflow-reset
+    // to restart from scratch.
+    const currentIdx = this.state.currentPhase ? WORKFLOW_PHASES.indexOf(this.state.currentPhase) : -1;
+    const targetIdx = WORKFLOW_PHASES.indexOf(phase);
+    if (targetIdx <= currentIdx) return false;
+    return this.advanceTo(phase);
+  }
+
+  onFileWritten(path: string): boolean {
+    if (!PLANS_DIR_RE.test(path)) return false;
+
+    if (DESIGN_RE.test(path)) {
+      const changedArtifact = this.recordArtifact("brainstorm", path);
+      const changedPhase = this.advanceTo("brainstorm");
+      return changedArtifact || changedPhase;
+    }
+
+    if (IMPLEMENTATION_RE.test(path)) {
+      const changedArtifact = this.recordArtifact("plan", path);
+      const changedPhase = this.advanceTo("plan");
+      return changedArtifact || changedPhase;
+    }
+
+    return false;
+  }
+
+  onPlanTrackerInit(): boolean {
+    return this.advanceTo("execute");
+  }
+
+  static reconstructFromBranch(branch: SessionEntry[]): WorkflowTrackerState | null {
+    let last: WorkflowTrackerState | null = null;
+
+    for (const entry of branch) {
+      if (entry.type !== "custom") continue;
+      // biome-ignore lint/suspicious/noExplicitAny: pi SDK session entry type
+      if ((entry as any).customType !== WORKFLOW_TRACKER_ENTRY_TYPE) continue;
+      // biome-ignore lint/suspicious/noExplicitAny: pi SDK session entry type
+      const data = (entry as any).data as WorkflowTrackerState | undefined;
+      if (data && typeof data === "object") {
+        last = cloneState(data);
+      }
+    }
+
+    return last;
+  }
+}

package/extensions/workflow-monitor/workflow-transitions.ts

@@ -0,0 +1,55 @@
+import type { Phase, TransitionBoundary } from "./workflow-tracker";
+
+export type TransitionChoice = "next" | "fresh" | "skip" | "discuss";
+
+export interface TransitionPrompt {
+  boundary: TransitionBoundary;
+  title: string;
+  nextPhase: Phase;
+  artifactPath: string | null;
+  options: { choice: TransitionChoice; label: string }[];
+}
+
+const BASE_OPTIONS: TransitionPrompt["options"] = [
+  { choice: "next", label: "Next step (this session)" },
+  { choice: "fresh", label: "Fresh session → next step" },
+  { choice: "skip", label: "Skip" },
+  { choice: "discuss", label: "Discuss" },
+];
+
+export function getTransitionPrompt(boundary: TransitionBoundary, artifactPath: string | null): TransitionPrompt {
+  switch (boundary) {
+    case "design_committed":
+      return {
+        boundary,
+        title: "Design committed. What next?",
+        nextPhase: "plan",
+        artifactPath,
+        options: BASE_OPTIONS,
+      };
+    case "plan_ready":
+      return {
+        boundary,
+        title: "Plan ready. What next?",
+        nextPhase: "execute",
+        artifactPath,
+        options: BASE_OPTIONS,
+      };
+    case "execution_complete":
+      return {
+        boundary,
+        title: "All tasks complete. What next?",
+        nextPhase: "finalize",
+        artifactPath,
+        options: BASE_OPTIONS,
+      };
+    default:
+      return {
+        boundary,
+        title: "What next?",
+        nextPhase: "plan",
+        artifactPath,
+        options: BASE_OPTIONS,
+      };
+  }
+}