From 913eb1df2ef0d390a5f899324b36a7a113776843 Mon Sep 17 00:00:00 2001
From: Michael Livshits <livsmichael@gmail.com>
Date: Sun, 31 May 2026 09:46:22 +0300
Subject: [PATCH] Add workflow authoring types

---
 README.md           | 10 +++++
 package.json        |  4 ++
 types/workflow.d.ts | 95 +++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 109 insertions(+)
 create mode 100644 types/workflow.d.ts

diff --git a/README.md b/README.md
index 87f7727..3279e86 100644
--- a/README.md
+++ b/README.md
@@ -75,6 +75,16 @@ return { inventory, summary }
 
 Phases are discovered as the script runs, so conditional and loop-created phases work naturally. If a branch is skipped, its phase does not show up as an empty progress row.
 
+### Editor IntelliSense
+
+Reusable workflow files can opt into editor hints for workflow globals:
+
+```js
+/// <reference types="pi-dynamic-workflows/workflow" />
+```
+
+This declares `agent`, `parallel`, `pipeline`, `phase`, `log`, `args`, `cwd`, and `budget` for TypeScript-aware editors.
+
 ### Available globals
 
 | Global | Description |
diff --git a/package.json b/package.json
index 2a2f124..e198927 100644
--- a/package.json
+++ b/package.json
@@ -9,12 +9,16 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./workflow": {
+      "types": "./types/workflow.d.ts"
     }
   },
   "files": [
     "dist/",
     "extensions/",
     "src/",
+    "types/",
     "README.md"
   ],
   "scripts": {
diff --git a/types/workflow.d.ts b/types/workflow.d.ts
new file mode 100644
index 0000000..83345b4
--- /dev/null
+++ b/types/workflow.d.ts
@@ -0,0 +1,95 @@
+/**
+ * Ambient globals available inside pi-dynamic-workflows workflow scripts.
+ *
+ * Add this to a JavaScript or TypeScript workflow file for editor IntelliSense:
+ *
+ *   /// <reference types="pi-dynamic-workflows/workflow" />
+ */
+
+export {};
+
+declare global {
+  /** Literal workflow metadata. Must be the first statement: `export const meta = { ... }`. */
+  interface WorkflowMeta {
+    name: string;
+    description: string;
+    whenToUse?: string;
+    /** Optional documentation for an expected outline. Live progress is driven by `phase(...)`. */
+    phases?: WorkflowMetaPhase[];
+  }
+
+  interface WorkflowMetaPhase {
+    title: string;
+    detail?: string;
+    model?: string;
+  }
+
+  interface WorkflowAgentOptions<TSchema = JsonSchema> {
+    /** Short label shown in the live progress UI. */
+    label?: string;
+    /** Override the current runtime phase for this agent. */
+    phase?: string;
+    /** JSON Schema for structured output. When present, the returned value is typed as unknown unless you provide a generic. */
+    schema?: TSchema;
+    /** Requested model name. Currently passed as subagent guidance. */
+    model?: string;
+    /** Requested isolation mode. */
+    isolation?: "worktree";
+    /** Requested subagent role/type. */
+    agentType?: string;
+  }
+
+  type JsonPrimitive = string | number | boolean | null;
+  type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
+  interface JsonObject {
+    [key: string]: JsonValue;
+  }
+
+  interface JsonSchema {
+    type?: string | string[];
+    properties?: Record<string, JsonSchema>;
+    items?: JsonSchema | JsonSchema[];
+    required?: string[];
+    additionalProperties?: boolean | JsonSchema;
+    enum?: JsonValue[];
+    const?: JsonValue;
+    description?: string;
+    [key: string]: unknown;
+  }
+
+  interface WorkflowBudget {
+    total: number | null;
+    spent(): number;
+    remaining(): number;
+  }
+
+  /** Spawn a subagent. Returns final text unless a structured-output schema is used with an explicit generic. */
+  function agent<T = string>(prompt: string, options?: WorkflowAgentOptions): Promise<T>;
+
+  /** Run independent async tasks concurrently. Pass functions, not already-created promises. */
+  function parallel<T>(thunks: Array<() => Promise<T>>): Promise<T[]>;
+
+  /** Run each item through sequential async stages while different items may run concurrently. */
+  function pipeline<TItem, TResult = unknown>(
+    items: TItem[],
+    ...stages: Array<(previous: unknown, original: TItem, index: number) => TResult | Promise<TResult>>
+  ): Promise<TResult[]>;
+
+  /** Mark the current workflow phase for progress grouping. */
+  function phase(title: string): void;
+
+  /** Append a workflow-level log line. */
+  function log(message: unknown): void;
+
+  /** Optional JSON args passed to the workflow tool. Narrow with a local type assertion when needed. */
+  const args: unknown;
+
+  /** Current working directory for the workflow/subagents. */
+  const cwd: string;
+
+  /** Deterministic process shim exposing only cwd(). */
+  const process: { cwd(): string };
+
+  /** Simple token-budget estimate for workflow runs. */
+  const budget: WorkflowBudget;
+}