@davidorex/pi-workflows 0.1.0

package/schemas/investigation-findings.schema.json

@@ -0,0 +1,45 @@
+{
+  "type": "object",
+  "required": ["affected_files", "constraints", "risks", "needs_research", "complexity", "summary"],
+  "properties": {
+    "affected_files": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["path", "role", "current_behavior"],
+        "properties": {
+          "path": { "type": "string" },
+          "role": { "type": "string", "description": "What this file does in the context of the gap" },
+          "current_behavior": { "type": "string", "description": "What it currently does that's relevant to the gap" }
+        }
+      }
+    },
+    "constraints": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Technical constraints, invariants, or requirements that the solution must respect"
+    },
+    "risks": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "What could go wrong, edge cases, regression risks"
+    },
+    "needs_research": {
+      "type": "boolean",
+      "description": "Whether the gap requires external knowledge beyond what codebase analysis and LLM training data provide"
+    },
+    "research_questions": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Specific questions for the research step to answer. Only meaningful if needs_research is true."
+    },
+    "complexity": {
+      "type": "string",
+      "enum": ["low", "medium", "high"]
+    },
+    "summary": {
+      "type": "string",
+      "description": "Concise summary of the investigation — what's the problem, what's involved, what's the path forward"
+    }
+  }
+}

package/schemas/pattern-analysis.schema.json

@@ -0,0 +1,43 @@
+{
+  "type": "object",
+  "required": ["patterns", "conventions", "recommendations"],
+  "properties": {
+    "patterns": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "usage", "files"],
+        "properties": {
+          "name": { "type": "string" },
+          "usage": { "type": "string" },
+          "files": { "type": "array", "items": { "type": "string" } },
+          "correct": { "type": "boolean" }
+        }
+      }
+    },
+    "conventions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["convention", "followed"],
+        "properties": {
+          "convention": { "type": "string" },
+          "followed": { "type": "boolean" },
+          "violations": { "type": "array", "items": { "type": "string" } }
+        }
+      }
+    },
+    "recommendations": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["pattern", "suggestion"],
+        "properties": {
+          "pattern": { "type": "string" },
+          "suggestion": { "type": "string" },
+          "priority": { "type": "string", "enum": ["high", "medium", "low"] }
+        }
+      }
+    }
+  }
+}

package/schemas/plan-breakdown.schema.json

@@ -0,0 +1,22 @@
+{
+  "type": "object",
+  "required": ["plans"],
+  "properties": {
+    "plans": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "intent", "tasks", "acceptance_criteria"],
+        "properties": {
+          "name": { "type": "string" },
+          "intent": { "type": "string" },
+          "tasks": { "type": "array", "items": { "type": "string" } },
+          "files_to_change": { "type": "array", "items": { "type": "string" } },
+          "acceptance_criteria": { "type": "array", "items": { "type": "string" } },
+          "context_needed": { "type": "array", "items": { "type": "string" } },
+          "parallel_group": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/schemas/quality-analysis.schema.json

@@ -0,0 +1,35 @@
+{
+  "type": "object",
+  "required": ["concerns", "testCoverage", "maintainability"],
+  "properties": {
+    "concerns": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["description", "severity"],
+        "properties": {
+          "description": { "type": "string" },
+          "severity": { "type": "string", "enum": ["info", "warning", "critical"] },
+          "file": { "type": "string" },
+          "suggestion": { "type": "string" }
+        }
+      }
+    },
+    "testCoverage": {
+      "type": "object",
+      "required": ["tested", "untested"],
+      "properties": {
+        "tested": { "type": "array", "items": { "type": "string" } },
+        "untested": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "maintainability": {
+      "type": "object",
+      "required": ["score", "factors"],
+      "properties": {
+        "score": { "type": "string", "enum": ["high", "medium", "low"] },
+        "factors": { "type": "array", "items": { "type": "string" } }
+      }
+    }
+  }
+}

package/schemas/research-findings.schema.json

@@ -0,0 +1,44 @@
+{
+  "type": "object",
+  "required": ["questions", "patterns", "recommendations"],
+  "properties": {
+    "questions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["question", "answer", "confidence"],
+        "properties": {
+          "question": { "type": "string" },
+          "answer": { "type": "string" },
+          "sources": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Where the answer came from — docs, other projects, known patterns"
+          },
+          "confidence": {
+            "type": "string",
+            "enum": ["high", "medium", "low"],
+            "description": "How confident the answer is — high = well-known pattern, low = best guess"
+          }
+        }
+      }
+    },
+    "patterns": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "description", "applicability"],
+        "properties": {
+          "name": { "type": "string" },
+          "description": { "type": "string" },
+          "applicability": { "type": "string", "description": "How this pattern applies to the specific gap" }
+        }
+      }
+    },
+    "recommendations": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Concrete recommendations based on research findings"
+    }
+  }
+}

package/schemas/structure-analysis.schema.json

@@ -0,0 +1,42 @@
+{
+  "type": "object",
+  "required": ["architecture", "modules", "dependencies"],
+  "properties": {
+    "architecture": {
+      "type": "object",
+      "required": ["patterns", "organization"],
+      "properties": {
+        "patterns": { "type": "array", "items": { "type": "string" } },
+        "organization": { "type": "string" }
+      }
+    },
+    "modules": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "responsibility", "files"],
+        "properties": {
+          "name": { "type": "string" },
+          "responsibility": { "type": "string" },
+          "files": { "type": "array", "items": { "type": "string" } }
+        }
+      }
+    },
+    "dependencies": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["from", "to", "type"],
+        "properties": {
+          "from": { "type": "string" },
+          "to": { "type": "string" },
+          "type": { "type": "string", "enum": ["import", "runtime", "config"] }
+        }
+      }
+    },
+    "entryPoints": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  }
+}

package/schemas/synthesis.schema.json

@@ -0,0 +1,33 @@
+{
+  "type": "object",
+  "required": ["summary", "findings", "recommendations"],
+  "properties": {
+    "summary": { "type": "string" },
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["category", "description", "severity"],
+        "properties": {
+          "category": { "type": "string", "enum": ["structure", "quality", "patterns"] },
+          "description": { "type": "string" },
+          "severity": { "type": "string", "enum": ["info", "warning", "critical"] },
+          "files": { "type": "array", "items": { "type": "string" } }
+        }
+      }
+    },
+    "recommendations": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["action", "rationale", "priority"],
+        "properties": {
+          "action": { "type": "string" },
+          "rationale": { "type": "string" },
+          "priority": { "type": "string", "enum": ["high", "medium", "low"] },
+          "affectedFiles": { "type": "array", "items": { "type": "string" } }
+        }
+      }
+    }
+  }
+}

package/schemas/verifier-output.schema.json

@@ -0,0 +1,96 @@
+{
+  "type": "object",
+  "required": ["status", "score", "truths", "criteria_results"],
+  "properties": {
+    "status": {
+      "type": "string",
+      "enum": ["passed", "gaps_found", "human_needed"]
+    },
+    "score": {
+      "type": "string",
+      "description": "Score in N/M format (e.g. '5/7')"
+    },
+    "truths": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["truth", "status", "evidence"],
+        "properties": {
+          "truth": { "type": "string" },
+          "status": { "type": "string", "enum": ["verified", "failed", "uncertain"] },
+          "evidence": { "type": "string" }
+        }
+      }
+    },
+    "artifacts": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["path", "status"],
+        "properties": {
+          "path": { "type": "string" },
+          "status": { "type": "string", "enum": ["verified", "stub", "missing"] },
+          "exists": { "type": "boolean" },
+          "substantive": { "type": "boolean" },
+          "wired": { "type": "boolean" },
+          "details": { "type": "string" }
+        }
+      }
+    },
+    "requirements_coverage": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["requirement_id", "status"],
+        "properties": {
+          "requirement_id": { "type": "string" },
+          "status": { "type": "string", "enum": ["satisfied", "blocked", "needs_human"] },
+          "supporting_truths": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        }
+      }
+    },
+    "criteria_results": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["criterion", "verify_method", "status"],
+        "properties": {
+          "criterion": { "type": "string" },
+          "verify_method": { "type": "string", "enum": ["command", "grep", "inspect"] },
+          "status": { "type": "string", "enum": ["passed", "failed", "uncertain", "skipped"] },
+          "expected_outcome": { "type": "string" },
+          "actual_outcome": { "type": "string" },
+          "evidence": { "type": "string" }
+        }
+      }
+    },
+    "human_verification": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "test", "expected", "why_human"],
+        "properties": {
+          "name": { "type": "string" },
+          "test": { "type": "string" },
+          "expected": { "type": "string" },
+          "why_human": { "type": "string" }
+        }
+      }
+    },
+    "gaps": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["truth", "status", "reason"],
+        "properties": {
+          "truth": { "type": "string" },
+          "status": { "type": "string" },
+          "reason": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/src/agent-spec.test.ts

@@ -0,0 +1,289 @@
+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}`);
+  });
+});