dot-agents 0.1.5 → 0.3.0

package/dist/lib/validation/index.js

@@ -0,0 +1,135 @@
+import { readdir, stat } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { createError, } from "./types.js";
+import { validateWorkflow, getWorkflowPersonaRef } from "./workflow.js";
+import { validatePersona } from "./persona.js";
+export * from "./types.js";
+export { validateWorkflow } from "./workflow.js";
+export { validatePersona } from "./persona.js";
+export { validateCron } from "./cron.js";
+const PERSONA_FILENAME = "PERSONA.md";
+const WORKFLOW_FILENAME = "WORKFLOW.md";
+/**
+ * Check if a directory contains a specific file
+ */
+async function hasFile(dirPath, filename) {
+    try {
+        const filePath = join(dirPath, filename);
+        const stats = await stat(filePath);
+        return stats.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Recursively find all directories containing a specific file
+ */
+async function findDirectoriesWithFile(root, filename) {
+    const results = [];
+    async function scanDir(dir) {
+        try {
+            const entries = await readdir(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (entry.isDirectory()) {
+                    const subDir = join(dir, entry.name);
+                    if (await hasFile(subDir, filename)) {
+                        results.push(subDir);
+                    }
+                    await scanDir(subDir);
+                }
+            }
+        }
+        catch {
+            // Directory doesn't exist or not readable
+        }
+    }
+    await scanDir(root);
+    return results;
+}
+/**
+ * Check if a persona path exists
+ */
+async function personaExists(personaRef, personasDir) {
+    const personaPath = join(personasDir, personaRef);
+    return hasFile(personaPath, PERSONA_FILENAME);
+}
+/**
+ * Determine if a persona is a root persona (no parent with PERSONA.md)
+ */
+async function isRootPersona(personaPath, personasRoot) {
+    const relativePath = relative(personasRoot, personaPath);
+    const parts = relativePath.split("/").filter(Boolean);
+    // If it's directly under personasRoot, it's a root persona
+    if (parts.length <= 1) {
+        return true;
+    }
+    // Check if any parent directory has a PERSONA.md
+    let currentPath = personasRoot;
+    for (let i = 0; i < parts.length - 1; i++) {
+        currentPath = join(currentPath, parts[i]);
+        if (await hasFile(currentPath, PERSONA_FILENAME)) {
+            return false; // Has a parent persona
+        }
+    }
+    return true;
+}
+/**
+ * Validate all workflows in a directory
+ */
+export async function validateAllWorkflows(workflowsDir, personasDir) {
+    const workflowPaths = await findDirectoriesWithFile(workflowsDir, WORKFLOW_FILENAME);
+    const results = [];
+    for (const workflowPath of workflowPaths) {
+        const result = await validateWorkflow(workflowPath);
+        // Cross-validate persona reference if personasDir provided
+        if (personasDir && result.valid) {
+            const personaRef = await getWorkflowPersonaRef(workflowPath);
+            if (personaRef && !(await personaExists(personaRef, personasDir))) {
+                result.issues.push(createError("reference_not_found", "persona", `Persona '${personaRef}' not found`, `Create persona at: ${join(personasDir, personaRef, PERSONA_FILENAME)}`));
+                result.valid = false;
+            }
+        }
+        results.push(result);
+    }
+    return results;
+}
+/**
+ * Validate all personas in a directory
+ */
+export async function validateAllPersonas(personasDir) {
+    const personaPaths = await findDirectoriesWithFile(personasDir, PERSONA_FILENAME);
+    const results = [];
+    for (const personaPath of personaPaths) {
+        const isRoot = await isRootPersona(personaPath, personasDir);
+        const result = await validatePersona(personaPath, isRoot);
+        results.push(result);
+    }
+    return results;
+}
+/**
+ * Validate entire .agents directory
+ */
+export async function validateAll(agentsDir) {
+    const personasDir = join(agentsDir, "personas");
+    const workflowsDir = join(agentsDir, "workflows");
+    const personaResults = await validateAllPersonas(personasDir);
+    const workflowResults = await validateAllWorkflows(workflowsDir, personasDir);
+    const validPersonas = personaResults.filter((r) => r.valid).length;
+    const validWorkflows = workflowResults.filter((r) => r.valid).length;
+    return {
+        personas: {
+            total: personaResults.length,
+            valid: validPersonas,
+            results: personaResults,
+        },
+        workflows: {
+            total: workflowResults.length,
+            valid: validWorkflows,
+            results: workflowResults,
+        },
+        valid: validPersonas === personaResults.length &&
+            validWorkflows === workflowResults.length,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/lib/validation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/validation/index.ts"],"names":[],"mappings":"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"}

package/dist/lib/validation/persona.d.ts

@@ -0,0 +1,9 @@
+import { ValidationResult } from "./types.js";
+/**
+ * Validate a persona file
+ *
+ * @param personaPath Path to the persona directory or PERSONA.md file
+ * @param isRootPersona Whether this is a root persona (requires cmd)
+ */
+export declare function validatePersona(personaPath: string, isRootPersona?: boolean): Promise<ValidationResult>;
+//# sourceMappingURL=persona.d.ts.map

package/dist/lib/validation/persona.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persona.d.ts","sourceRoot":"","sources":["../../../src/lib/validation/persona.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,gBAAgB,EAIjB,MAAM,YAAY,CAAC;AA4CpB;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,WAAW,EAAE,MAAM,EACnB,aAAa,GAAE,OAAc,GAC5B,OAAO,CAAC,gBAAgB,CAAC,CAyL3B"}

package/dist/lib/validation/persona.js

@@ -0,0 +1,143 @@
+import { readFile } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { createError, createWarning, } from "./types.js";
+const PERSONA_FILENAME = "PERSONA.md";
+/**
+ * Known persona frontmatter fields
+ */
+const KNOWN_FIELDS = new Set(["name", "description", "cmd", "env", "skills"]);
+/**
+ * Common legacy/misnamed fields and their correct names
+ */
+const FIELD_SUGGESTIONS = {
+    command: "cmd",
+    commands: "cmd",
+    skill: "skills",
+    environment: "env",
+    variables: "env",
+    model: "env.CLAUDE_MODEL or similar",
+};
+/**
+ * Parse frontmatter from markdown content without full validation
+ */
+function parseFrontmatter(content) {
+    const frontmatterRegex = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+    const match = content.match(frontmatterRegex);
+    if (!match) {
+        return null;
+    }
+    const [, yamlContent, body] = match;
+    try {
+        const frontmatter = parseYaml(yamlContent);
+        return { frontmatter, body: body.trim() };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Validate a persona file
+ *
+ * @param personaPath Path to the persona directory or PERSONA.md file
+ * @param isRootPersona Whether this is a root persona (requires cmd)
+ */
+export async function validatePersona(personaPath, isRootPersona = true) {
+    const filePath = personaPath.endsWith(PERSONA_FILENAME)
+        ? personaPath
+        : join(personaPath, PERSONA_FILENAME);
+    const issues = [];
+    let name;
+    try {
+        const content = await readFile(filePath, "utf-8");
+        const parsed = parseFrontmatter(content);
+        if (!parsed) {
+            issues.push(createError("invalid_value", "frontmatter", "No valid YAML frontmatter found", "File must start with --- followed by YAML and another ---"));
+            return {
+                path: filePath,
+                valid: false,
+                issues,
+            };
+        }
+        const { frontmatter } = parsed;
+        name = frontmatter.name;
+        // Check required fields
+        if (!frontmatter.name) {
+            issues.push(createError("missing_field", "name", "Missing required 'name' field", "Add: name: my-persona"));
+        }
+        else if (typeof frontmatter.name !== "string") {
+            issues.push(createError("invalid_type", "name", "'name' must be a string"));
+        }
+        // cmd is required for root personas, optional for child personas (inherited)
+        if (isRootPersona && !frontmatter.cmd) {
+            issues.push(createError("missing_field", "cmd", "Missing required 'cmd' field for root persona", "Add: cmd: \"claude --print\" or cmd: [\"claude --print\", \"claude -p\"]"));
+        }
+        // Validate cmd type if present
+        if (frontmatter.cmd !== undefined) {
+            if (typeof frontmatter.cmd !== "string" &&
+                !Array.isArray(frontmatter.cmd)) {
+                issues.push(createError("invalid_type", "cmd", "'cmd' must be a string or array of strings", "Use: cmd: \"claude --print\" or cmd: [\"claude --print\"]"));
+            }
+            else if (Array.isArray(frontmatter.cmd)) {
+                frontmatter.cmd.forEach((c, index) => {
+                    if (typeof c !== "string") {
+                        issues.push(createError("invalid_type", `cmd[${index}]`, "Command must be a string"));
+                    }
+                });
+            }
+        }
+        // Validate env if present
+        if (frontmatter.env !== undefined) {
+            if (typeof frontmatter.env !== "object" ||
+                Array.isArray(frontmatter.env) ||
+                frontmatter.env === null) {
+                issues.push(createError("invalid_type", "env", "'env' must be an object", "Use: env: { CLAUDE_MODEL: 'sonnet' }"));
+            }
+            else {
+                // Check that all env values are strings
+                const env = frontmatter.env;
+                for (const [key, value] of Object.entries(env)) {
+                    if (typeof value !== "string") {
+                        issues.push(createWarning("unknown_field", `env.${key}`, `Environment variable '${key}' should be a string, got ${typeof value}`, "Convert to string or use ${VAR} expansion"));
+                    }
+                }
+            }
+        }
+        // Validate skills if present
+        if (frontmatter.skills !== undefined) {
+            if (!Array.isArray(frontmatter.skills)) {
+                issues.push(createError("invalid_type", "skills", "'skills' must be an array of glob patterns", "Use: skills: [\"productivity/**\", \"!experimental/*\"]"));
+            }
+            else {
+                frontmatter.skills.forEach((skill, index) => {
+                    if (typeof skill !== "string") {
+                        issues.push(createError("invalid_type", `skills[${index}]`, "Skill pattern must be a string"));
+                    }
+                });
+            }
+        }
+        // Check for unknown/legacy fields
+        for (const key of Object.keys(frontmatter)) {
+            if (!KNOWN_FIELDS.has(key)) {
+                const suggestion = FIELD_SUGGESTIONS[key];
+                if (suggestion) {
+                    issues.push(createWarning("unknown_field", key, `Unknown field '${key}'`, `Did you mean '${suggestion}'?`));
+                }
+                else {
+                    issues.push(createWarning("unknown_field", key, `Unknown field '${key}'`));
+                }
+            }
+        }
+    }
+    catch (error) {
+        issues.push(createError("invalid_value", "file", `Failed to read persona: ${error.message}`));
+    }
+    const hasErrors = issues.some((i) => i.severity === "error");
+    return {
+        path: dirname(filePath),
+        name,
+        valid: !hasErrors,
+        issues,
+    };
+}
+//# sourceMappingURL=persona.js.map

package/dist/lib/validation/persona.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"persona.js","sourceRoot":"","sources":["../../../src/lib/validation/persona.ts"],"names":[],"mappings":"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"}

package/dist/lib/validation/types.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Severity levels for validation issues
+ */
+export type ValidationSeverity = "error" | "warning";
+/**
+ * Types of validation errors
+ */
+export type ValidationErrorType = "missing_field" | "invalid_type" | "invalid_value" | "reference_not_found";
+/**
+ * Types of validation warnings
+ */
+export type ValidationWarningType = "unknown_field" | "deprecated_field";
+/**
+ * A validation issue (error or warning)
+ */
+export interface ValidationIssue {
+    severity: ValidationSeverity;
+    type: ValidationErrorType | ValidationWarningType;
+    /** Path to the problematic field (e.g., "on.schedule[0].cron") */
+    path: string;
+    /** Human-readable error message */
+    message: string;
+    /** Suggestion for how to fix the issue */
+    suggestion?: string;
+}
+/**
+ * Result of validating a single resource
+ */
+export interface ValidationResult {
+    /** Path to the resource */
+    path: string;
+    /** Resource name (if available) */
+    name?: string;
+    /** Whether the resource is valid (no errors, warnings are ok) */
+    valid: boolean;
+    /** All issues found */
+    issues: ValidationIssue[];
+}
+/**
+ * Summary of validation across multiple resources
+ */
+export interface ValidationSummary {
+    workflows: {
+        total: number;
+        valid: number;
+        results: ValidationResult[];
+    };
+    personas: {
+        total: number;
+        valid: number;
+        results: ValidationResult[];
+    };
+    /** Overall validity (all resources valid) */
+    valid: boolean;
+}
+/**
+ * Helper to create an error issue
+ */
+export declare function createError(type: ValidationErrorType, path: string, message: string, suggestion?: string): ValidationIssue;
+/**
+ * Helper to create a warning issue
+ */
+export declare function createWarning(type: ValidationWarningType, path: string, message: string, suggestion?: string): ValidationIssue;
+//# sourceMappingURL=types.d.ts.map

package/dist/lib/validation/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/lib/validation/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,SAAS,CAAC;AAErD;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAC3B,eAAe,GACf,cAAc,GACd,eAAe,GACf,qBAAqB,CAAC;AAE1B;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,eAAe,GAAG,kBAAkB,CAAC;AAEzE;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,IAAI,EAAE,mBAAmB,GAAG,qBAAqB,CAAC;IAClD,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,KAAK,EAAE,OAAO,CAAC;IACf,uBAAuB;IACvB,MAAM,EAAE,eAAe,EAAE,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE;QACT,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,gBAAgB,EAAE,CAAC;KAC7B,CAAC;IACF,QAAQ,EAAE;QACR,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,gBAAgB,EAAE,CAAC;KAC7B,CAAC;IACF,6CAA6C;IAC7C,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;GAEG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,mBAAmB,EACzB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,UAAU,CAAC,EAAE,MAAM,GAClB,eAAe,CAQjB;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,qBAAqB,EAC3B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,UAAU,CAAC,EAAE,MAAM,GAClB,eAAe,CAQjB"}

package/dist/lib/validation/types.js

@@ -0,0 +1,25 @@
+/**
+ * Helper to create an error issue
+ */
+export function createError(type, path, message, suggestion) {
+    return {
+        severity: "error",
+        type,
+        path,
+        message,
+        suggestion,
+    };
+}
+/**
+ * Helper to create a warning issue
+ */
+export function createWarning(type, path, message, suggestion) {
+    return {
+        severity: "warning",
+        type,
+        path,
+        message,
+        suggestion,
+    };
+}
+//# sourceMappingURL=types.js.map

package/dist/lib/validation/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/lib/validation/types.ts"],"names":[],"mappings":"AAiEA;;GAEG;AACH,MAAM,UAAU,WAAW,CACzB,IAAyB,EACzB,IAAY,EACZ,OAAe,EACf,UAAmB;IAEnB,OAAO;QACL,QAAQ,EAAE,OAAO;QACjB,IAAI;QACJ,IAAI;QACJ,OAAO;QACP,UAAU;KACX,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAC3B,IAA2B,EAC3B,IAAY,EACZ,OAAe,EACf,UAAmB;IAEnB,OAAO;QACL,QAAQ,EAAE,SAAS;QACnB,IAAI;QACJ,IAAI;QACJ,OAAO;QACP,UAAU;KACX,CAAC;AACJ,CAAC"}

package/dist/lib/validation/workflow.d.ts

@@ -0,0 +1,10 @@
+import { ValidationResult } from "./types.js";
+/**
+ * Validate a workflow file
+ */
+export declare function validateWorkflow(workflowPath: string): Promise<ValidationResult>;
+/**
+ * Get the persona referenced by a workflow (for cross-validation)
+ */
+export declare function getWorkflowPersonaRef(workflowPath: string): Promise<string | null>;
+//# sourceMappingURL=workflow.d.ts.map

package/dist/lib/validation/workflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow.d.ts","sourceRoot":"","sources":["../../../src/lib/validation/workflow.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,gBAAgB,EAIjB,MAAM,YAAY,CAAC;AAgMpB;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,gBAAgB,CAAC,CAyM3B;AAED;;GAEG;AACH,wBAAsB,qBAAqB,CACzC,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAexB"}

package/dist/lib/validation/workflow.js

@@ -0,0 +1,242 @@
+import { readFile } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { createError, createWarning, } from "./types.js";
+import { validateCron, suggestCronFromHint } from "./cron.js";
+const WORKFLOW_FILENAME = "WORKFLOW.md";
+/**
+ * Known workflow frontmatter fields
+ */
+const KNOWN_FIELDS = new Set([
+    "name",
+    "description",
+    "persona",
+    "on",
+    "inputs",
+    "outputs",
+    "env",
+    "timeout",
+    "retry",
+    "working_dir",
+]);
+/**
+ * Common legacy/misnamed fields and their correct names
+ */
+const FIELD_SUGGESTIONS = {
+    goal: "description",
+    skills_used: "persona (skills belong in the persona definition)",
+    skills: "persona (skills belong in the persona definition)",
+    schedule: "on.schedule",
+    trigger: "on",
+    triggers: "on",
+    command: "persona (command belongs in the persona definition)",
+    cmd: "persona (command belongs in the persona definition)",
+};
+/**
+ * Parse frontmatter from markdown content without full validation
+ */
+function parseFrontmatter(content) {
+    const frontmatterRegex = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+    const match = content.match(frontmatterRegex);
+    if (!match) {
+        return null;
+    }
+    const [, yamlContent, body] = match;
+    try {
+        const frontmatter = parseYaml(yamlContent);
+        return { frontmatter, body: body.trim() };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Validate the 'on' trigger configuration
+ */
+function validateTriggers(on, issues) {
+    if (on === undefined || on === null) {
+        return; // 'on' is optional
+    }
+    if (typeof on !== "object" || Array.isArray(on)) {
+        issues.push(createError("invalid_type", "on", "'on' must be an object with trigger configurations", "Example: on: { manual: true, schedule: [{cron: '0 9 * * *'}] }"));
+        return;
+    }
+    const triggers = on;
+    // Validate schedule
+    if (triggers.schedule !== undefined) {
+        if (typeof triggers.schedule === "string") {
+            // Common mistake: using a string instead of array
+            const hint = suggestCronFromHint(triggers.schedule);
+            issues.push(createError("invalid_type", "on.schedule", "'schedule' must be an array of {cron: string} objects, got string", hint
+                ? `Use: schedule: [{ cron: "${hint}" }]`
+                : "Use: schedule: [{ cron: \"0 9 * * *\" }]"));
+        }
+        else if (!Array.isArray(triggers.schedule)) {
+            issues.push(createError("invalid_type", "on.schedule", "'schedule' must be an array", "Use: schedule: [{ cron: \"0 9 * * *\" }]"));
+        }
+        else {
+            // Validate each schedule entry
+            triggers.schedule.forEach((entry, index) => {
+                if (typeof entry !== "object" || entry === null) {
+                    issues.push(createError("invalid_type", `on.schedule[${index}]`, "Schedule entry must be an object with 'cron' field", "Use: { cron: \"0 9 * * *\" }"));
+                    return;
+                }
+                const scheduleEntry = entry;
+                if (typeof scheduleEntry.cron !== "string") {
+                    issues.push(createError("missing_field", `on.schedule[${index}].cron`, "Schedule entry missing required 'cron' field", "Add: cron: \"0 9 * * *\""));
+                    return;
+                }
+                // Validate cron expression
+                const cronResult = validateCron(scheduleEntry.cron);
+                if (!cronResult.valid) {
+                    issues.push(createError("invalid_value", `on.schedule[${index}].cron`, `Invalid cron expression: ${cronResult.error}`, "Format: minute hour day-of-month month day-of-week (e.g., \"30 9 * * 1-5\")"));
+                }
+            });
+        }
+    }
+    // Validate manual trigger
+    if (triggers.manual !== undefined) {
+        if (typeof triggers.manual !== "boolean" &&
+            typeof triggers.manual !== "object") {
+            issues.push(createError("invalid_type", "on.manual", "'manual' must be true/false or an object with input overrides", "Use: manual: true"));
+        }
+    }
+    // Check for unknown trigger types
+    const knownTriggers = new Set([
+        "schedule",
+        "manual",
+        "file_change",
+        "webhook",
+        "workflow_complete",
+        "git",
+        "github",
+    ]);
+    for (const key of Object.keys(triggers)) {
+        if (!knownTriggers.has(key)) {
+            issues.push(createWarning("unknown_field", `on.${key}`, `Unknown trigger type '${key}'`, `Known triggers: ${Array.from(knownTriggers).join(", ")}`));
+        }
+    }
+}
+/**
+ * Validate a workflow file
+ */
+export async function validateWorkflow(workflowPath) {
+    const filePath = workflowPath.endsWith(WORKFLOW_FILENAME)
+        ? workflowPath
+        : join(workflowPath, WORKFLOW_FILENAME);
+    const issues = [];
+    let name;
+    try {
+        const content = await readFile(filePath, "utf-8");
+        const parsed = parseFrontmatter(content);
+        if (!parsed) {
+            issues.push(createError("invalid_value", "frontmatter", "No valid YAML frontmatter found", "File must start with --- followed by YAML and another ---"));
+            return {
+                path: filePath,
+                valid: false,
+                issues,
+            };
+        }
+        const { frontmatter, body } = parsed;
+        name = frontmatter.name;
+        // Check required fields
+        if (!frontmatter.name) {
+            issues.push(createError("missing_field", "name", "Missing required 'name' field", "Add: name: my-workflow"));
+        }
+        else if (typeof frontmatter.name !== "string") {
+            issues.push(createError("invalid_type", "name", "'name' must be a string"));
+        }
+        if (!frontmatter.description) {
+            // Check if they used 'goal' instead
+            if (frontmatter.goal) {
+                issues.push(createError("missing_field", "description", "Missing required 'description' field", "Rename 'goal' to 'description'"));
+            }
+            else {
+                issues.push(createError("missing_field", "description", "Missing required 'description' field", "Add: description: What this workflow does"));
+            }
+        }
+        else if (typeof frontmatter.description !== "string") {
+            issues.push(createError("invalid_type", "description", "'description' must be a string"));
+        }
+        if (!frontmatter.persona) {
+            issues.push(createError("missing_field", "persona", "Missing required 'persona' field", "Add: persona: claude"));
+        }
+        else if (typeof frontmatter.persona !== "string") {
+            issues.push(createError("invalid_type", "persona", "'persona' must be a string"));
+        }
+        // Check for task body
+        if (!body) {
+            issues.push(createError("missing_field", "body", "Missing task body after frontmatter", "Add the task/prompt content after the --- delimiter"));
+        }
+        // Validate triggers
+        validateTriggers(frontmatter.on, issues);
+        // Check for unknown/legacy fields
+        for (const key of Object.keys(frontmatter)) {
+            if (!KNOWN_FIELDS.has(key)) {
+                const suggestion = FIELD_SUGGESTIONS[key];
+                if (suggestion) {
+                    issues.push(createWarning("unknown_field", key, `Unknown field '${key}'`, `Did you mean '${suggestion}'?`));
+                }
+                else {
+                    issues.push(createWarning("unknown_field", key, `Unknown field '${key}'`));
+                }
+            }
+        }
+        // Validate inputs if present
+        if (frontmatter.inputs !== undefined) {
+            if (!Array.isArray(frontmatter.inputs)) {
+                issues.push(createError("invalid_type", "inputs", "'inputs' must be an array", "Use: inputs: [{ name: 'myInput', type: 'string' }]"));
+            }
+            else {
+                frontmatter.inputs.forEach((input, index) => {
+                    if (typeof input !== "object" || input === null) {
+                        issues.push(createError("invalid_type", `inputs[${index}]`, "Input definition must be an object"));
+                        return;
+                    }
+                    const inputDef = input;
+                    if (!inputDef.name || typeof inputDef.name !== "string") {
+                        issues.push(createError("missing_field", `inputs[${index}].name`, "Input definition missing required 'name' field"));
+                    }
+                });
+            }
+        }
+        // Validate env if present
+        if (frontmatter.env !== undefined) {
+            if (typeof frontmatter.env !== "object" ||
+                Array.isArray(frontmatter.env) ||
+                frontmatter.env === null) {
+                issues.push(createError("invalid_type", "env", "'env' must be an object", "Use: env: { KEY: 'value' }"));
+            }
+        }
+    }
+    catch (error) {
+        issues.push(createError("invalid_value", "file", `Failed to read workflow: ${error.message}`));
+    }
+    const hasErrors = issues.some((i) => i.severity === "error");
+    return {
+        path: dirname(filePath),
+        name,
+        valid: !hasErrors,
+        issues,
+    };
+}
+/**
+ * Get the persona referenced by a workflow (for cross-validation)
+ */
+export async function getWorkflowPersonaRef(workflowPath) {
+    const filePath = workflowPath.endsWith(WORKFLOW_FILENAME)
+        ? workflowPath
+        : join(workflowPath, WORKFLOW_FILENAME);
+    try {
+        const content = await readFile(filePath, "utf-8");
+        const parsed = parseFrontmatter(content);
+        if (parsed && typeof parsed.frontmatter.persona === "string") {
+            return parsed.frontmatter.persona;
+        }
+    }
+    catch {
+        // Ignore errors
+    }
+    return null;
+}
+//# sourceMappingURL=workflow.js.map