@davidorex/pi-workflows 0.1.0 → 0.2.0

package/README.md

@@ -1,23 +1,39 @@
 # pi-workflows
 
-Workflow orchestration extension for [Pi](https://github.com/badlogic/pi-mono). Define multi-step workflows in YAML, execute them as DAGs with typed data flow between agents, and resume from checkpoints on failure.
+Schema-driven workflow orchestration for [Pi](https://github.com/badlogic/pi-mono).
+
+Data flows through workflows as typed JSON, not strings. Each agent step declares an `output.schema` — the agent's output is validated against a JSON Schema before it's accepted into the pipeline. The expression engine passes typed fields between steps (`${{ steps.investigate.output.findings }}`), not raw text. Templates compose typed data into agent prompts, so agents receive structured context. The entire pipeline is schema-governed: **schema defines shape → agent produces to shape → validator enforces shape → next step consumes typed fields.**
+
+The schemas in `schemas/` (investigation-findings, decomposition-specs, execution-results, etc.) are the typed contracts between workflow steps. They're not metadata — they're the enforcement boundary.
 
 ## Install
 
 ```bash
-pi install pi-workflows
+pi install npm:@davidorex/pi-project    # peer dependency
+pi install npm:@davidorex/pi-workflows
+```
+
+Or install both at once: `pi install npm:@davidorex/pi-project-workflows`
+
+## Getting Started
+
+```
+/workflow init
 ```
 
-Requires `pi-project` as a peer dependency (installed separately).
+Creates `.workflows/` for run state. Workflow YAML specs are discovered automatically from the package's bundled workflows — no setup needed to start running them.
 
 ## What It Does
 
 pi-workflows replaces ad-hoc agent chaining with composable, typed workflow orchestration. Workflows are YAML specs. Steps run as subprocesses (`pi --mode json`) with their own context windows. The main conversation is the control plane; workflows are subordinate.
 
+Workflows consume project blocks as typed input via `readBlock()` — structured data, not raw files. When workflow agents write back to project blocks, pi-project's schema validation enforces the shape at write time. The two extensions form a typed loop: project state → workflow input → agent output → validated project state.
+
 **Tool registered:**
 - `workflow` — run a named workflow with typed input
 
 **Commands registered:**
+- `/workflow init` — scaffold `.workflows/` directory for run state
 - `/workflow list` — discover and select a workflow to run
 - `/workflow run <name> [--input '<json>']` — execute a workflow
 - `/workflow resume <name>` — resume an incomplete run from checkpoint
@@ -28,7 +44,7 @@ pi-workflows replaces ad-hoc agent chaining with composable, typed workflow orch
 
 ## Workflow Spec Format
 
-Workflows are `.workflow.yaml` files discovered from `.pi/workflows/` (project), `~/.pi/agent/workflows/` (user), or the package's `workflows/` directory (builtin).
+Workflows are `.workflow.yaml` files discovered from `.workflows/` (project), `~/.pi/agent/workflows/` (user), or the package's `workflows/` directory (builtin).
 
 ```yaml
 name: my-workflow
@@ -143,7 +159,7 @@ declaredSchemaRefs(spec): string[]
 - DAG planner infers parallelism from `${{ steps.X }}` references — no manual dependency declaration
 - Agent specs are `.agent.yaml` only. Compiled to prompts via Nunjucks at dispatch time.
 - State persisted atomically after each step (tmp + rename). State write failure is fatal.
-- Three-tier resource search: project `.pi/` > user `~/.pi/agent/` > package builtin
+- Three-tier resource search: project (`.workflows/`, `.pi/agents/`, `.pi/templates/`) > user `~/.pi/agent/` > package builtin
 - `completion` field controls what message is sent back to the main conversation after a workflow finishes
 
 ## For LLMs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davidorex/pi-workflows",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Workflow orchestration extension for Pi",
   "license": "MIT",
   "author": "David Ryan",

package/src/checkpoint.test.ts

@@ -18,7 +18,7 @@ describe("findIncompleteRun", () => {
     const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-ckpt-"));
     t.after(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
 
-    const runDir = path.join(tmpDir, ".pi", "workflow-runs", "test", "runs", "test-20260314-120000-abcd");
+    const runDir = path.join(tmpDir, ".workflows", "runs", "test", "runs", "test-20260314-120000-abcd");
     fs.mkdirSync(runDir, { recursive: true });
     writeState(runDir, { input: {}, steps: {}, status: "completed" });
 
@@ -30,7 +30,7 @@ describe("findIncompleteRun", () => {
     const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-ckpt-"));
     t.after(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
 
-    const runDir = path.join(tmpDir, ".pi", "workflow-runs", "test", "runs", "test-20260314-120000-abcd");
+    const runDir = path.join(tmpDir, ".workflows", "runs", "test", "runs", "test-20260314-120000-abcd");
     fs.mkdirSync(runDir, { recursive: true });
 
     const state: ExecutionState = {
@@ -57,7 +57,7 @@ describe("findIncompleteRun", () => {
     const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-ckpt-"));
     t.after(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
 
-    const runDir = path.join(tmpDir, ".pi", "workflow-runs", "test", "runs", "test-20260314-120000-abcd");
+    const runDir = path.join(tmpDir, ".workflows", "runs", "test", "runs", "test-20260314-120000-abcd");
     fs.mkdirSync(runDir, { recursive: true });
 
     const state: ExecutionState = {
@@ -88,7 +88,7 @@ describe("findIncompleteRun", () => {
     const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-ckpt-"));
     t.after(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
 
-    const runsBase = path.join(tmpDir, ".pi", "workflow-runs", "test", "runs");
+    const runsBase = path.join(tmpDir, ".workflows", "runs", "test", "runs");
 
     // Older run (completed)
     const oldDir = path.join(runsBase, "test-20260314-100000-aaaa");

package/src/checkpoint.ts

@@ -8,6 +8,7 @@ import fs from "node:fs";
 import path from "node:path";
 import type { ExecutionState, WorkflowSpec } from "./types.ts";
 import { readState } from "./state.ts";
+import { WORKFLOWS_DIR } from "./workflows-dir.ts";
 
 export interface IncompleteRun {
   runId: string;
@@ -21,14 +22,14 @@ export interface IncompleteRun {
 /**
  * Find the most recent incomplete run for a workflow.
  *
- * Scans .pi/workflow-runs/<name>/runs/ for state.json files
+ * Scans .workflows/runs/<name>/runs/ for state.json files
  * with status "running" or "failed". Returns the most recent one
  * (by directory name, which encodes timestamp).
  *
  * Returns null if no incomplete runs exist.
  */
 export function findIncompleteRun(cwd: string, workflowName: string): IncompleteRun | null {
-  const runsDir = path.join(cwd, ".pi", "workflow-runs", workflowName, "runs");
+  const runsDir = path.join(cwd, WORKFLOWS_DIR, "runs", workflowName, "runs");
   if (!fs.existsSync(runsDir)) return null;
 
   const entries = fs.readdirSync(runsDir)

package/src/dispatch.test.ts

@@ -6,13 +6,15 @@ import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
 
-// Skip integration tests if pi is not available
+// Skip integration tests unless RUN_INTEGRATION=1 and pi is available
 let hasPi = false;
-try {
-  const { execSync } = await import("node:child_process");
-  execSync("pi --version", { stdio: "ignore" });
-  hasPi = true;
-} catch {}
+if (process.env.RUN_INTEGRATION === "1") {
+  try {
+    const { execSync } = await import("node:child_process");
+    execSync("pi --version", { stdio: "ignore" });
+    hasPi = true;
+  } catch {}
+}
 
 // ── Unit tests: extractText ──
 

package/src/graduated-failure.test.ts

@@ -199,7 +199,7 @@ describe("graduated failure retry", () => {
   beforeEach(() => {
     tmpDir = makeTmpDir();
     // Create minimal run dir structure
-    const runDir = path.join(tmpDir, ".pi", "workflow-runs", "test", "runs");
+    const runDir = path.join(tmpDir, ".workflows", "runs", "test", "runs");
     fs.mkdirSync(runDir, { recursive: true });
   });
 

package/src/index.ts

@@ -7,7 +7,9 @@ import { executeWorkflow, requestPause } from "./workflow-executor.ts";
 import { findIncompleteRun, validateResumeCompatibility, formatIncompleteRun } from "./checkpoint.ts";
 import { createAgentLoader } from "./agent-spec.ts";
 import type { WorkflowResult } from "./types.ts";
+import { WORKFLOWS_DIR } from "./workflows-dir.ts";
 import fs from "node:fs";
+import path from "node:path";
 
 import { Key } from "@mariozechner/pi-tui";
 import { Type } from "@sinclair/typebox";
@@ -126,7 +128,7 @@ function formatToolResult(result: WorkflowResult): string {
 async function handleList(ctx: ExtensionCommandContext, pi: ExtensionAPI): Promise<void> {
   const workflows = discoverWorkflows(ctx.cwd);
   if (workflows.length === 0) {
-    ctx.ui.notify("No workflows found in .pi/workflows/ or ~/.pi/agent/workflows/", "info");
+    ctx.ui.notify("No workflows found in .workflows/ or ~/.pi/agent/workflows/", "info");
     return;
   }
 
@@ -333,6 +335,30 @@ async function handleResume(rawArgs: string, ctx: ExtensionCommandContext, pi: E
   }
 }
 
+/**
+ * /workflow init — scaffold .workflows/ directory for user workflow specs
+ * and run state. Idempotent.
+ */
+function handleWorkflowInit(ctx: ExtensionCommandContext): void {
+  const workflowsDir = path.join(ctx.cwd, WORKFLOWS_DIR);
+  const runsDir = path.join(workflowsDir, "runs");
+
+  const created: string[] = [];
+
+  for (const dir of [workflowsDir, runsDir]) {
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+      created.push(path.relative(ctx.cwd, dir) + "/");
+    }
+  }
+
+  if (created.length > 0) {
+    ctx.ui.notify(`Workflows initialized: created ${created.join(", ")}`, "info");
+  } else {
+    ctx.ui.notify("Workflows already initialized — nothing to do.", "info");
+  }
+}
+
 // ── Extension factory ───────────────────────────────────────────────────────
 
 const extension = (pi: ExtensionAPI) => {
@@ -341,7 +367,7 @@ const extension = (pi: ExtensionAPI) => {
   pi.registerTool({
     name: "workflow",
     label: "Workflow",
-    description: "Run a named workflow with typed input. Discovers workflows from .pi/workflows/ and ~/.pi/agent/workflows/.",
+    description: "Run a named workflow with typed input. Discovers workflows from .workflows/ and ~/.pi/agent/workflows/.",
     promptSnippet: "Run a multi-step workflow with typed data flow between agents",
     parameters: Type.Object({
       workflow: Type.String({ description: "Name of the workflow to run" }),
@@ -403,7 +429,7 @@ const extension = (pi: ExtensionAPI) => {
   pi.registerCommand("workflow", {
     description: "List and run workflows",
     getArgumentCompletions: (prefix: string) => {
-      const subcommands = ["run", "list", "resume"];
+      const subcommands = ["init", "run", "list", "resume"];
       return subcommands
         .filter((s) => s.startsWith(prefix))
         .map((s) => ({ value: s, label: s }));
@@ -415,14 +441,16 @@ const extension = (pi: ExtensionAPI) => {
       const subcommand = spaceIdx === -1 ? trimmed || "list" : trimmed.slice(0, spaceIdx);
       const rest = spaceIdx === -1 ? "" : trimmed.slice(spaceIdx + 1);
 
-      if (subcommand === "list") {
+      if (subcommand === "init") {
+        handleWorkflowInit(ctx);
+      } else if (subcommand === "list") {
         await handleList(ctx, pi);
       } else if (subcommand === "run") {
         await handleRun(rest, ctx, pi);
       } else if (subcommand === "resume") {
         await handleResume(rest, ctx, pi);
       } else {
-        ctx.ui.notify(`Unknown subcommand: ${subcommand}. Use: list, run, resume`, "warning");
+        ctx.ui.notify(`Unknown subcommand: ${subcommand}. Use: init, list, run, resume`, "warning");
       }
     },
   });

package/src/loop.test.ts

@@ -17,13 +17,15 @@ function defaultOptions(tmpDir?: string) {
   };
 }
 
-// Skip if pi is not available
+// Skip integration tests unless RUN_INTEGRATION=1 and pi is available
 let hasPi = false;
-try {
-  const { execSync } = await import("node:child_process");
-  execSync("pi --version", { stdio: "ignore" });
-  hasPi = true;
-} catch {}
+if (process.env.RUN_INTEGRATION === "1") {
+  try {
+    const { execSync } = await import("node:child_process");
+    execSync("pi --version", { stdio: "ignore" });
+    hasPi = true;
+  } catch {}
+}
 
 describe("loop steps", () => {
   it("breaks on gate pass", async (t: any) => {

package/src/state.ts

@@ -3,6 +3,7 @@ import path from "node:path";
 import crypto from "node:crypto";
 import type { ExecutionState, WorkflowResult, WorkflowSpec, StepResult, StepUsage } from "./types.ts";
 import { formatDuration, formatCost } from "./format.ts";
+import { WORKFLOWS_DIR } from "./workflows-dir.ts";
 
 /**
  * Generate a unique run ID.
@@ -24,11 +25,11 @@ export function generateRunId(workflowName: string): string {
 /**
  * Initialize the run directory structure.
  * Creates:
- *   .pi/workflow-runs/<workflowName>/runs/<runId>/
- *   .pi/workflow-runs/<workflowName>/runs/<runId>/sessions/
- *   .pi/workflow-runs/<workflowName>/runs/<runId>/outputs/
+ *   .workflows/runs/<workflowName>/runs/<runId>/
+ *   .workflows/runs/<workflowName>/runs/<runId>/sessions/
+ *   .workflows/runs/<workflowName>/runs/<runId>/outputs/
  *
- * Each workflow owns a directory under .pi/workflow-runs/<name>/.
+ * Each workflow owns a directory under .workflows/runs/<name>/.
  * Run state goes in runs/<runId>/; artifacts live at the workflow level.
  *
  * @param cwd - project root
@@ -37,7 +38,7 @@ export function generateRunId(workflowName: string): string {
  * @returns absolute path to the run directory
  */
 export function initRunDir(cwd: string, workflowName: string, runId: string): string {
-  const runDir = path.join(cwd, ".pi", "workflow-runs", workflowName, "runs", runId);
+  const runDir = path.join(cwd, WORKFLOWS_DIR, "runs", workflowName, "runs", runId);
   fs.mkdirSync(path.join(runDir, "sessions"), { recursive: true });
   fs.mkdirSync(path.join(runDir, "outputs"), { recursive: true });
   return runDir;
@@ -49,10 +50,10 @@ export function initRunDir(cwd: string, workflowName: string, runId: string): st
  *
  * @param cwd - project root
  * @param workflowName - name of the workflow
- * @returns absolute path to .pi/workflow-runs/<workflowName>/
+ * @returns absolute path to .workflows/runs/<workflowName>/
  */
 export function getWorkflowDir(cwd: string, workflowName: string): string {
-  return path.join(cwd, ".pi", "workflow-runs", workflowName);
+  return path.join(cwd, WORKFLOWS_DIR, "runs", workflowName);
 }
 
 /**

package/src/types.ts

@@ -159,7 +159,7 @@ export interface WorkflowResult {
   output?: unknown;                      // final workflow output (last step's output, or explicit)
   totalUsage: StepUsage;
   totalDurationMs: number;
-  runDir: string;                        // absolute path to .pi/workflow-runs/<name>/runs/<run-id>/
+  runDir: string;                        // absolute path to .workflows/runs/<name>/runs/<run-id>/
   artifacts?: Record<string, string>;    // name → absolute path of written artifact files
 }
 

package/src/workflow-discovery.test.ts

@@ -11,7 +11,7 @@ const NO_BUILTINS = path.join(os.tmpdir(), "wf-no-builtins-nonexistent");
 describe("discoverWorkflows", () => {
   it("discovers workflows from project directory", () => {
     const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "wf-test-"));
-    const wfDir = path.join(tmpDir, ".pi", "workflows");
+    const wfDir = path.join(tmpDir, ".workflows");
     fs.mkdirSync(wfDir, { recursive: true });
     fs.writeFileSync(
       path.join(wfDir, "test.workflow.yaml"),
@@ -35,7 +35,7 @@ describe("discoverWorkflows", () => {
 
   it("skips invalid specs with warning (no throw)", () => {
     const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "wf-test-"));
-    const wfDir = path.join(tmpDir, ".pi", "workflows");
+    const wfDir = path.join(tmpDir, ".workflows");
     fs.mkdirSync(wfDir, { recursive: true });
     fs.writeFileSync(path.join(wfDir, "bad.workflow.yaml"), "not: valid: workflow");
     fs.writeFileSync(
@@ -52,7 +52,7 @@ describe("discoverWorkflows", () => {
 
   it("project specs shadow user specs with same name", () => {
     const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "wf-test-"));
-    const projectDir = path.join(tmpDir, ".pi", "workflows");
+    const projectDir = path.join(tmpDir, ".workflows");
     fs.mkdirSync(projectDir, { recursive: true });
     fs.writeFileSync(
       path.join(projectDir, "shared.workflow.yaml"),
@@ -83,7 +83,7 @@ describe("discoverWorkflows", () => {
 describe("findWorkflow", () => {
   it("finds a workflow by name", () => {
     const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "wf-test-"));
-    const wfDir = path.join(tmpDir, ".pi", "workflows");
+    const wfDir = path.join(tmpDir, ".workflows");
     fs.mkdirSync(wfDir, { recursive: true });
     fs.writeFileSync(
       path.join(wfDir, "bugfix.workflow.yaml"),

package/src/workflow-discovery.ts

@@ -3,12 +3,13 @@ import path from "node:path";
 import os from "node:os";
 import type { WorkflowSpec } from "./types.ts";
 import { parseWorkflowSpec } from "./workflow-spec.ts";
+import { WORKFLOWS_DIR } from "./workflows-dir.ts";
 
 /**
  * Discover all workflow specs from project, user, and builtin directories.
  *
  * Scans (highest priority first):
- *   1. .pi/workflows/             (project-level, source: "project")
+ *   1. .workflows/                (project-level, source: "project")
  *   2. ~/.pi/agent/workflows/     (user-level, source: "user")
  *   3. <package>/workflows/       (builtin workflows, source: "user")
  *
@@ -20,7 +21,7 @@ import { parseWorkflowSpec } from "./workflow-spec.ts";
  *          skipped with a warning (logged to stderr), not thrown.
  */
 export function discoverWorkflows(cwd: string, builtinDir?: string): WorkflowSpec[] {
-  const projectDir = path.join(cwd, ".pi", "workflows");
+  const projectDir = path.join(cwd, WORKFLOWS_DIR);
   const userDir = path.join(os.homedir(), ".pi", "agent", "workflows");
   const demoDir = builtinDir ?? path.resolve(import.meta.dirname, "..", "workflows");
 

package/src/workflow-executor.test.ts

@@ -7,13 +7,15 @@ import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
 
-// Skip if pi is not available
+// Skip integration tests unless RUN_INTEGRATION=1 and pi is available
 let hasPi = false;
-try {
-  const { execSync } = await import("node:child_process");
-  execSync("pi --version", { stdio: "ignore" });
-  hasPi = true;
-} catch {}
+if (process.env.RUN_INTEGRATION === "1") {
+  try {
+    const { execSync } = await import("node:child_process");
+    execSync("pi --version", { stdio: "ignore" });
+    hasPi = true;
+  } catch {}
+}
 
 describe("executeWorkflow", { skip: !hasPi ? "pi not available" : undefined }, () => {
   it("runs a single-step workflow", async () => {
@@ -529,8 +531,8 @@ describe("artifacts", () => {
 
     assert.strictEqual(result.status, "completed");
     assert.ok(result.artifacts);
-    // Artifact path should be under .pi/workflow-runs/<workflow-name>/
-    const workflowDir = path.join(tmpDir, ".pi", "workflow-runs", "test-artifact-rel");
+    // Artifact path should be under .workflows/runs/<workflow-name>/
+    const workflowDir = path.join(tmpDir, ".workflows", "runs", "test-artifact-rel");
     const expectedPath = path.resolve(workflowDir, "latest.json");
     assert.strictEqual(result.artifacts!.report, expectedPath);
     assert.ok(fs.existsSync(expectedPath));

package/src/workflows-dir.ts

@@ -0,0 +1,2 @@
+/** Workflow directory name — project-level workflow specs and run state */
+export const WORKFLOWS_DIR = ".workflows";