@davidorex/pi-workflows 0.2.0 → 0.3.0

package/workflows/typed-analysis.workflow.yaml

@@ -26,7 +26,7 @@ steps:
       path: ${{ input.path }}
     output:
       format: json
-      schema: schemas/structure-analysis.schema.json
+      schema: ../schemas/structure-analysis.schema.json
 
   analyze-quality:
     agent: quality-analyzer
@@ -35,7 +35,7 @@ steps:
       path: ${{ input.path }}
     output:
       format: json
-      schema: schemas/quality-analysis.schema.json
+      schema: ../schemas/quality-analysis.schema.json
 
   analyze-patterns:
     agent: pattern-analyzer
@@ -44,7 +44,7 @@ steps:
       path: ${{ input.path }}
     output:
       format: json
-      schema: schemas/pattern-analysis.schema.json
+      schema: ../schemas/pattern-analysis.schema.json
 
   synthesize:
     agent: synthesizer
@@ -54,7 +54,7 @@ steps:
       patterns: ${{ steps.analyze-patterns.output }}
     output:
       format: json
-      schema: schemas/synthesis.schema.json
+      schema: ../schemas/synthesis.schema.json
 
 completion:
   message: |

package/src/agent-spec.test.ts

@@ -1,289 +0,0 @@
-import { describe, it } from "node:test";
-import assert from "node:assert";
-import fs from "node:fs";
-import path from "node:path";
-import os from "node:os";
-import { parseAgentYaml, createAgentLoader, AgentNotFoundError, AgentParseError } from "./agent-spec.ts";
-import { compileAgentSpec } from "./step-shared.ts";
-import { createTemplateEnv } from "./template.ts";
-
-describe("parseAgentYaml", () => {
-  it("parses YAML agent spec with all fields", (t) => {
-    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-agent-"));
-    t.after(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
-
-    const specPath = path.join(tmpDir, "test.agent.yaml");
-    fs.writeFileSync(specPath, `
-name: test-agent
-role: sensor
-description: A test agent
-model: anthropic/claude-sonnet-4-6
-thinking: low
-tools: [read, bash]
-extensions: [./ext.ts]
-skills: [coding]
-input:
-  type: object
-  required: [path]
-  properties:
-    path: { type: string }
-output:
-  format: json
-  schema: test.schema.json
-  file: result.json
-prompt:
-  system: test/system.md
-  task: test/task.md
-`);
-
-    const spec = parseAgentYaml(specPath);
-    assert.strictEqual(spec.name, "test-agent");
-    assert.strictEqual(spec.role, "sensor");
-    assert.strictEqual(spec.description, "A test agent");
-    assert.strictEqual(spec.model, "anthropic/claude-sonnet-4-6");
-    assert.strictEqual(spec.thinking, "low");
-    assert.deepStrictEqual(spec.tools, ["read", "bash"]);
-    assert.deepStrictEqual(spec.extensions, ["./ext.ts"]);
-    assert.deepStrictEqual(spec.skills, ["coding"]);
-    assert.strictEqual(spec.promptTemplate, "test/system.md");
-    assert.strictEqual(spec.taskTemplate, "test/task.md");
-    assert.strictEqual(spec.outputFormat, "json");
-    assert.strictEqual(spec.outputSchema, "test.schema.json");
-    assert.strictEqual(spec.output, "result.json");
-    assert.deepStrictEqual(spec.inputSchema?.required, ["path"]);
-  });
-
-  it("uses filename as name when name field is missing", (t) => {
-    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-agent-"));
-    t.after(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
-
-    const specPath = path.join(tmpDir, "my-agent.agent.yaml");
-    fs.writeFileSync(specPath, "tools: [read]\n");
-
-    const spec = parseAgentYaml(specPath);
-    assert.strictEqual(spec.name, "my-agent");
-  });
-
-  it("throws AgentParseError for malformed YAML", (t) => {
-    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-agent-"));
-    t.after(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
-
-    const specPath = path.join(tmpDir, "bad.agent.yaml");
-    fs.writeFileSync(specPath, `
-name: bad-agent
-tools: [read
-  this is not valid yaml: {{{}}}
-`);
-
-    assert.throws(
-      () => parseAgentYaml(specPath),
-      (err: any) => {
-        assert.strictEqual(err.name, "AgentParseError");
-        assert.strictEqual(err.agentName, "bad");
-        assert.strictEqual(err.filePath, specPath);
-        assert.ok(err.message.includes("bad"), "error message should include agent name");
-        assert.ok(err.message.includes(specPath), "error message should include file path");
-        return true;
-      },
-    );
-  });
-
-  it("throws AgentParseError for empty file", (t) => {
-    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-agent-"));
-    t.after(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
-
-    const specPath = path.join(tmpDir, "empty.agent.yaml");
-    fs.writeFileSync(specPath, "");
-
-    assert.throws(
-      () => parseAgentYaml(specPath),
-      (err: any) => {
-        assert.strictEqual(err.name, "AgentParseError");
-        assert.ok(err.message.includes("empty") || err.message.includes("does not contain"));
-        return true;
-      },
-    );
-  });
-
-  it("throws AgentParseError for file with only document markers", (t) => {
-    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-agent-"));
-    t.after(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
-
-    const specPath = path.join(tmpDir, "marker.agent.yaml");
-    fs.writeFileSync(specPath, "---\n---\n");
-
-    assert.throws(
-      () => parseAgentYaml(specPath),
-      (err: any) => {
-        assert.strictEqual(err.name, "AgentParseError");
-        return true;
-      },
-    );
-  });
-
-  it("throws AgentParseError for scalar YAML content", (t) => {
-    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-agent-"));
-    t.after(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
-
-    const specPath = path.join(tmpDir, "scalar.agent.yaml");
-    fs.writeFileSync(specPath, "just a string, not a mapping\n");
-
-    assert.throws(
-      () => parseAgentYaml(specPath),
-      (err: any) => {
-        assert.strictEqual(err.name, "AgentParseError");
-        assert.ok(err.message.includes("does not contain a YAML mapping"));
-        return true;
-      },
-    );
-  });
-});
-
-describe("createAgentLoader", () => {
-  it("finds .agent.yaml specs in .pi/agents/", (t) => {
-    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-agent-"));
-    t.after(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
-
-    const agentDir = path.join(tmpDir, ".pi", "agents");
-    fs.mkdirSync(agentDir, { recursive: true });
-    fs.writeFileSync(path.join(agentDir, "test.agent.yaml"), "name: test\nrole: sensor\ntools: [read]\n");
-
-    const loader = createAgentLoader(tmpDir);
-    const spec = loader("test");
-    assert.strictEqual(spec.name, "test");
-    assert.strictEqual(spec.role, "sensor");
-    assert.deepStrictEqual(spec.tools, ["read"]);
-  });
-
-  it("finds specs in builtin directory", (t) => {
-    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-agent-"));
-    const builtinDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-builtin-"));
-    t.after(() => {
-      fs.rmSync(tmpDir, { recursive: true, force: true });
-      fs.rmSync(builtinDir, { recursive: true, force: true });
-    });
-
-    fs.writeFileSync(path.join(builtinDir, "builtin.agent.yaml"), "name: builtin\nrole: quality\n");
-
-    const loader = createAgentLoader(tmpDir, builtinDir);
-    const spec = loader("builtin");
-    assert.strictEqual(spec.name, "builtin");
-    assert.strictEqual(spec.role, "quality");
-  });
-
-  it("throws AgentNotFoundError for missing agent", (t) => {
-    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-agent-"));
-    t.after(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
-
-    const loader = createAgentLoader(tmpDir, tmpDir);  // builtinDir also empty
-    assert.throws(
-      () => loader("nonexistent-agent"),
-      (err: any) => {
-        assert.strictEqual(err.name, "AgentNotFoundError");
-        assert.strictEqual(err.agentName, "nonexistent-agent");
-        assert.ok(Array.isArray(err.searchPaths));
-        assert.ok(err.searchPaths.length >= 2, "should list at least project and user search paths");
-        assert.ok(err.message.includes("nonexistent-agent"), "error message should include agent name");
-        assert.ok(err.message.includes("Searched"), "error message should indicate search was performed");
-        return true;
-      },
-    );
-  });
-
-  it("throws AgentParseError when found file has invalid YAML", (t) => {
-    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-agent-"));
-    t.after(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
-
-    const agentDir = path.join(tmpDir, ".pi", "agents");
-    fs.mkdirSync(agentDir, { recursive: true });
-    fs.writeFileSync(path.join(agentDir, "broken.agent.yaml"), "name: broken\ntools: [read\n");
-
-    const loader = createAgentLoader(tmpDir, tmpDir);
-    assert.throws(
-      () => loader("broken"),
-      (err: any) => {
-        assert.strictEqual(err.name, "AgentParseError");
-        assert.strictEqual(err.agentName, "broken");
-        assert.ok(err.filePath.includes("broken.agent.yaml"));
-        return true;
-      },
-    );
-  });
-});
-
-describe("compileAgentSpec", () => {
-  it("renders plain text system prompt unchanged", () => {
-    const env = createTemplateEnv("/nonexistent");
-    const spec = { name: "test", systemPrompt: "Plain text prompt." };
-    const result = compileAgentSpec(spec, {}, env);
-    assert.strictEqual(result.systemPrompt, "Plain text prompt.");
-  });
-
-  it("renders system prompt with template variables", () => {
-    const env = createTemplateEnv("/nonexistent");
-    const spec = { name: "test", systemPrompt: "Analyze {{ path }} for {{ concern }}." };
-    const result = compileAgentSpec(spec, { path: "src/index.ts", concern: "security" }, env);
-    assert.strictEqual(result.systemPrompt, "Analyze src/index.ts for security.");
-  });
-
-  it("renders system prompt from file template", (t) => {
-    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-tmpl-"));
-    t.after(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
-
-    fs.writeFileSync(path.join(tmpDir, "system.md"), "You analyze {{ focus }} code.");
-
-    const env = createTemplateEnv("/nonexistent", tmpDir);
-    const spec = { name: "test", promptTemplate: "system.md" };
-    const result = compileAgentSpec(spec, { focus: "TypeScript" }, env);
-    assert.strictEqual(result.systemPrompt, "You analyze TypeScript code.");
-    assert.strictEqual(result.promptTemplate, undefined);
-  });
-
-  it("renders task template from typed input", (t) => {
-    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-tmpl-"));
-    t.after(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
-
-    fs.writeFileSync(path.join(tmpDir, "task.md"), "Fix {{ diagnosis.rootCause }} in {{ diagnosis.file }}.");
-
-    const env = createTemplateEnv("/nonexistent", tmpDir);
-    const spec = { name: "test", taskTemplate: "task.md" };
-    const result = compileAgentSpec(spec, { diagnosis: { rootCause: "null ref", file: "auth.ts" } }, env);
-    assert.strictEqual(result.taskTemplate, "Fix null ref in auth.ts.");
-  });
-
-  it("returns spec unchanged when no templateEnv provided", () => {
-    const spec = { name: "test", systemPrompt: "Hello {{ name }}", taskTemplate: "task.md" };
-    const result = compileAgentSpec(spec, { name: "world" });
-    assert.strictEqual(result.systemPrompt, "Hello {{ name }}");
-    assert.strictEqual(result.taskTemplate, "task.md");
-  });
-});
-
-describe("verifier agent spec", () => {
-  const builtinDir = path.resolve(import.meta.dirname, "..", "agents");
-
-  it("parses verifier.agent.yaml correctly", () => {
-    const specPath = path.join(builtinDir, "verifier.agent.yaml");
-    const spec = parseAgentYaml(specPath);
-    assert.strictEqual(spec.name, "verifier");
-    assert.strictEqual(spec.role, "quality");
-    assert.strictEqual(spec.description, "Verifies step outputs against declared intent and success criteria");
-    assert.strictEqual(spec.model, undefined);  // model comes from .project/model-config.json, not agent spec
-    assert.strictEqual(spec.outputFormat, "json");
-    assert.strictEqual(spec.outputSchema, "schemas/verifier-output.schema.json");
-    assert.strictEqual(spec.taskTemplate, "verifier/task.md");
-  });
-
-  it("has correct tools for verification", () => {
-    const specPath = path.join(builtinDir, "verifier.agent.yaml");
-    const spec = parseAgentYaml(specPath);
-    assert.deepStrictEqual(spec.tools, ["read", "bash", "grep", "find"]);
-  });
-
-  it("output schema path resolves to a valid file", () => {
-    const specPath = path.join(builtinDir, "verifier.agent.yaml");
-    const spec = parseAgentYaml(specPath);
-    const schemaPath = path.resolve(path.dirname(specPath), "..", "schemas", spec.outputSchema!.replace("schemas/", ""));
-    assert.ok(fs.existsSync(schemaPath), `Schema file not found at ${schemaPath}`);
-  });
-});

package/src/agent-spec.ts

@@ -1,122 +0,0 @@
-/**
- * Agent spec loading — YAML specs are the source of truth.
- *
- * Agent specs are declarative YAML files that define typed functions:
- * InputSchema → OutputSchema, with template references for prompt
- * composition. The .md that pi consumes is compiled at dispatch time
- * from spec + templates + typed input. It exists in memory only.
- *
- * Search order (first match wins):
- *   1. .pi/agents/<name>.agent.yaml     (project)
- *   2. ~/.pi/agent/agents/<name>.agent.yaml  (user)
- *   3. <package>/agents/<name>.agent.yaml (builtin)
- */
-import fs from "node:fs";
-import path from "node:path";
-
-/** Check if a prompt.system value looks like a template file path vs inline text. */
-function isTemplatePath(value: string | undefined): boolean {
-  if (!value) return false;
-  return value.endsWith(".md") || value.endsWith(".txt") || (value.includes("/") && !value.includes("\n"));
-}
-import os from "node:os";
-import { parse as parseYaml } from "yaml";
-import type { AgentSpec } from "./types.ts";
-
-/**
- * Thrown when an agent spec file is not found in any search path.
- */
-export class AgentNotFoundError extends Error {
-  public readonly agentName: string;
-  public readonly searchPaths: string[];
-
-  constructor(agentName: string, searchPaths: string[]) {
-    const pathList = searchPaths.map(p => `  - ${p}`).join("\n");
-    super(`Agent '${agentName}' not found. Searched:\n${pathList}`);
-    this.name = "AgentNotFoundError";
-    this.agentName = agentName;
-    this.searchPaths = searchPaths;
-  }
-}
-
-/**
- * Thrown when an agent spec file exists but cannot be read or parsed.
- */
-export class AgentParseError extends Error {
-  public readonly agentName: string;
-  public readonly filePath: string;
-  public readonly cause: Error;
-
-  constructor(agentName: string, filePath: string, cause: Error) {
-    super(`Agent '${agentName}' at ${filePath}: ${cause.message}`);
-    this.name = "AgentParseError";
-    this.agentName = agentName;
-    this.filePath = filePath;
-    this.cause = cause;
-  }
-}
-
-/**
- * Parse a YAML agent spec file into an AgentSpec.
- */
-export function parseAgentYaml(filePath: string): AgentSpec {
-  const name = path.basename(filePath, ".agent.yaml");
-
-  let content: string;
-  try {
-    content = fs.readFileSync(filePath, "utf-8");
-  } catch (err) {
-    throw new AgentParseError(name, filePath, err instanceof Error ? err : new Error(String(err)));
-  }
-
-  let spec: any;
-  try {
-    spec = parseYaml(content);
-  } catch (err) {
-    throw new AgentParseError(name, filePath, err instanceof Error ? err : new Error(String(err)));
-  }
-
-  // Handle null/undefined from parsing empty file or non-mapping YAML
-  if (!spec || typeof spec !== "object") {
-    throw new AgentParseError(name, filePath, new Error("File is empty or does not contain a YAML mapping"));
-  }
-
-  return {
-    name: spec.name || name,
-    description: spec.description,
-    role: spec.role,
-    model: spec.model,
-    thinking: spec.thinking,
-    tools: spec.tools,
-    extensions: spec.extensions,
-    skills: spec.skills,
-    output: spec.output?.file,
-    promptTemplate: isTemplatePath(spec.prompt?.system) ? spec.prompt?.system : undefined,
-    systemPrompt: isTemplatePath(spec.prompt?.system) ? undefined : spec.prompt?.system,
-    taskTemplate: spec.prompt?.task,
-    inputSchema: spec.input,
-    outputFormat: spec.output?.format,
-    outputSchema: spec.output?.schema,
-  };
-}
-
-/**
- * Create an agent loader that finds .agent.yaml specs.
- */
-export function createAgentLoader(cwd: string, builtinDir?: string): (name: string) => AgentSpec {
-  const defaultBuiltinDir = builtinDir ?? path.resolve(import.meta.dirname, "..", "agents");
-
-  return (name: string): AgentSpec => {
-    const searchPaths = [
-      path.join(cwd, ".pi", "agents", `${name}.agent.yaml`),
-      path.join(os.homedir(), ".pi", "agent", "agents", `${name}.agent.yaml`),
-      path.join(defaultBuiltinDir, `${name}.agent.yaml`),
-    ];
-
-    for (const p of searchPaths) {
-      if (fs.existsSync(p)) return parseAgentYaml(p);
-    }
-
-    throw new AgentNotFoundError(name, searchPaths);
-  };
-}