@interf/compiler 0.6.3 → 0.6.4

package/dist/packages/workflow-package/context-interface.js

@@ -0,0 +1,146 @@
+import { existsSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { warnInterf } from "../shared/logger.js";
+import { readJsonFileUnchecked } from "../shared/parse.js";
+import { WorkflowCompiledSchemaSchema, WorkflowCompiledZoneSchema, WorkflowZoneIdSchema, WorkflowZoneRoleSchema, } from "../compiler/lib/schema.js";
+import { listBuiltinCompiledZoneSpecs, requiredCompiledZoneOwners, } from "./builtin-compiled-workflow.js";
+// Workflow packages define the context interface. The compiler persists the
+// same schema on disk, but higher layers should prefer this boundary when they
+// mean "the workflow-declared shape a compiled context must implement."
+export const CONTEXT_INTERFACE_FILE = "workflow.schema.json";
+export const ContextInterfaceSchema = WorkflowCompiledSchemaSchema;
+export const ContextInterfaceZoneSchema = WorkflowCompiledZoneSchema;
+export const ContextInterfaceZoneIdSchema = WorkflowZoneIdSchema;
+export const ContextInterfaceZoneRoleSchema = WorkflowZoneRoleSchema;
+// Package-owned input contract for authoring, review, and future Studio flows.
+// This does not change compiler execution semantics; it describes what data a
+// workflow expects to organize before the compiler materializes the context
+// interface on disk.
+export const WorkflowInputSpecSchema = z.object({
+    id: WorkflowZoneIdSchema,
+    label: z.string().min(1),
+    description: z.string().min(1),
+    required: z.boolean().default(false),
+    examples: z.array(z.string().min(1)).optional(),
+}).strict();
+export const WorkflowInputContractSchema = z.array(WorkflowInputSpecSchema);
+function normalizeContextInterface(contextInterface) {
+    return {
+        ...contextInterface,
+        kind: "workflow-schema",
+    };
+}
+function pushContextInterfaceZone(zones, zone) {
+    if (zones.some((existing) => existing.path === zone.path))
+        return;
+    zones.push(zone);
+}
+function titleCaseZoneId(zoneId) {
+    return zoneId
+        .split("-")
+        .filter(Boolean)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join(" ");
+}
+export function contextInterfaceFilePath(rootPath) {
+    return join(rootPath, CONTEXT_INTERFACE_FILE);
+}
+export function resolveContextInterfacePath(rootPath) {
+    const path = contextInterfaceFilePath(rootPath);
+    return existsSync(path) ? path : null;
+}
+export function contextInterfaceExists(rootPath) {
+    return existsSync(contextInterfaceFilePath(rootPath));
+}
+export function contextInterfaceRelativePath() {
+    return `workflow/${CONTEXT_INTERFACE_FILE}`;
+}
+export function listContextInterfaceZones(contextInterface) {
+    return [...contextInterface.zones];
+}
+export function findContextInterfaceZone(contextInterface, zoneId) {
+    return contextInterface.zones.find((zone) => zone.id === zoneId) ?? null;
+}
+export function contextInterfaceZoneAbsolutePath(compiledPath, zone) {
+    return join(compiledPath, zone.path);
+}
+export function contextInterfaceArtifactPath(zone) {
+    if (zone.kind === "file")
+        return zone.path;
+    return zone.path.endsWith("/") ? zone.path : `${zone.path}/`;
+}
+export function contextInterfaceArtifactPathsForZoneIds(contextInterface, zoneIds) {
+    return zoneIds.map((zoneId) => {
+        const zone = findContextInterfaceZone(contextInterface, zoneId);
+        if (!zone) {
+            throw new Error(`Context interface is missing declared zone "${zoneId}".`);
+        }
+        return contextInterfaceArtifactPath(zone);
+    });
+}
+export function summarizeContextInterface(contextInterface) {
+    return {
+        inputZones: contextInterface.zones.filter((zone) => zone.role === "input"),
+        workingZones: contextInterface.zones.filter((zone) => zone.role === "working"),
+        outputZones: contextInterface.zones.filter((zone) => zone.role === "output"),
+        runtimeZones: contextInterface.zones.filter((zone) => zone.role === "runtime"),
+    };
+}
+export function deriveWorkflowInputsFromContextInterface(contextInterface) {
+    if (!contextInterface)
+        return [];
+    return contextInterface.zones
+        .filter((zone) => zone.role === "input")
+        .map((zone) => ({
+        id: zone.id,
+        label: titleCaseZoneId(zone.id),
+        description: zone.description,
+        required: zone.required,
+    }));
+}
+export function buildContextInterface(stages, label = "Workflow context interface") {
+    const zones = [];
+    for (const zone of listBuiltinCompiledZoneSpecs()) {
+        pushContextInterfaceZone(zones, {
+            id: zone.id,
+            role: zone.role,
+            path: zone.path,
+            kind: zone.kind,
+            required: zone.required,
+            owned_by: requiredCompiledZoneOwners(stages, zone.id),
+            description: zone.description,
+        });
+    }
+    return {
+        kind: "workflow-schema",
+        version: 1,
+        target_type: "compiled",
+        label,
+        zones,
+    };
+}
+export function writeContextInterfaceFile(rootPath, stages, label) {
+    const contextInterface = buildContextInterface(stages, label);
+    writeContextInterface(rootPath, contextInterface);
+    return contextInterface;
+}
+export function writeContextInterface(rootPath, contextInterface) {
+    const normalized = normalizeContextInterface(contextInterface);
+    writeFileSync(contextInterfaceFilePath(rootPath), `${JSON.stringify(normalized, null, 2)}\n`);
+    return normalized;
+}
+export function readContextInterface(rootPath) {
+    const path = contextInterfaceFilePath(rootPath);
+    if (!existsSync(path))
+        return null;
+    const raw = readJsonFileUnchecked(path, "workflow context interface");
+    if (raw === null)
+        return null;
+    const parsed = ContextInterfaceSchema.safeParse(raw);
+    if (!parsed.success) {
+        warnInterf(`Warning: failed to validate workflow context interface at ${path}: ${parsed.error.issues.map((issue) => issue.message).join("; ")}`);
+        return null;
+    }
+    return normalizeContextInterface(parsed.data);
+}

package/dist/packages/workflow-package/index.d.ts

@@ -1,4 +1,5 @@
 export * as builtinWorkflow from "./builtin-compiled-workflow.js";
+export * as contextInterface from "./context-interface.js";
 export * as localWorkflows from "./local-workflows.js";
 export * as packageWriters from "./interf-workflow-package.js";
 export * as workflowDefinitions from "./workflow-definitions.js";
@@ -7,3 +8,4 @@ export * as workflowStagePolicy from "./workflow-stage-policy.js";
 export * as workflowStageRunner from "./workflow-stage-runner.js";
 export * as workflowReviewPaths from "./workflow-review-paths.js";
 export * as packageRoot from "./lib/package-root.js";
+export { CONTEXT_INTERFACE_FILE, ContextInterfaceSchema, ContextInterfaceZoneSchema, ContextInterfaceZoneIdSchema, ContextInterfaceZoneRoleSchema, WorkflowInputSpecSchema, WorkflowInputContractSchema, contextInterfaceFilePath, resolveContextInterfacePath, contextInterfaceExists, contextInterfaceRelativePath, listContextInterfaceZones, findContextInterfaceZone, contextInterfaceZoneAbsolutePath, contextInterfaceArtifactPath, contextInterfaceArtifactPathsForZoneIds, buildContextInterface, writeContextInterfaceFile, writeContextInterface, readContextInterface, type ContextInterface, type ContextInterfaceZone, type ContextInterfaceZoneId, type ContextInterfaceZoneRole, type ContextInterfaceStageLike, type WorkflowInputSpec, type ContextInterfaceSummary, summarizeContextInterface, deriveWorkflowInputsFromContextInterface, } from "./context-interface.js";

package/dist/packages/workflow-package/index.js

@@ -1,4 +1,5 @@
 export * as builtinWorkflow from "./builtin-compiled-workflow.js";
+export * as contextInterface from "./context-interface.js";
 export * as localWorkflows from "./local-workflows.js";
 export * as packageWriters from "./interf-workflow-package.js";
 export * as workflowDefinitions from "./workflow-definitions.js";
@@ -7,3 +8,4 @@ export * as workflowStagePolicy from "./workflow-stage-policy.js";
 export * as workflowStageRunner from "./workflow-stage-runner.js";
 export * as workflowReviewPaths from "./workflow-review-paths.js";
 export * as packageRoot from "./lib/package-root.js";
+export { CONTEXT_INTERFACE_FILE, ContextInterfaceSchema, ContextInterfaceZoneSchema, ContextInterfaceZoneIdSchema, ContextInterfaceZoneRoleSchema, WorkflowInputSpecSchema, WorkflowInputContractSchema, contextInterfaceFilePath, resolveContextInterfacePath, contextInterfaceExists, contextInterfaceRelativePath, listContextInterfaceZones, findContextInterfaceZone, contextInterfaceZoneAbsolutePath, contextInterfaceArtifactPath, contextInterfaceArtifactPathsForZoneIds, buildContextInterface, writeContextInterfaceFile, writeContextInterface, readContextInterface, summarizeContextInterface, deriveWorkflowInputsFromContextInterface, } from "./context-interface.js";

package/dist/packages/workflow-package/interf-workflow-package.js

@@ -1,10 +1,10 @@
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { renderCompiledQuerySkill } from "../agents/lib/shells.js";
-import { WORKFLOW_SCHEMA_FILE, writeWorkflowSchemaDocument, writeWorkflowSchemaFile, } from "../compiler/compiled-schema.js";
 import { copyWorkflowPackageDirectory, isPortableWorkflowPackage, patchWorkflowPackageMetadata, resolveWorkflowPackageSourcePath, workflowDefinitionPath, } from "./local-workflows.js";
 import { getCompiledWorkflow, } from "./workflow-definitions.js";
-import { workflowPackagePathForCompiled } from "../project-model/compiled-paths.js";
+import { CONTEXT_INTERFACE_FILE, deriveWorkflowInputsFromContextInterface, summarizeContextInterface, writeContextInterface, writeContextInterfaceFile, } from "./context-interface.js";
+import { workflowPackagePathForCompiled } from "../compiler/compiled-paths.js";
 import { mergeStagePolicyNotesForStages } from "./workflow-stage-policy.js";
 function workflowPackagePath(dirPath) {
     return workflowPackagePathForCompiled(dirPath);
@@ -22,6 +22,9 @@ function writeWorkflowPackageJson(rootPath, workflow, options) {
     const targetPath = join(rootPath, "workflow.json");
     if (!options.overwrite && existsSync(targetPath))
         return;
+    const inputs = workflow.inputs?.length
+        ? workflow.inputs
+        : deriveWorkflowInputsFromContextInterface(workflow.contextInterface ?? workflow.schema);
     writeFileSync(targetPath, `${JSON.stringify({
         id: workflow.id,
         type: "compiled",
@@ -37,6 +40,7 @@ function writeWorkflowPackageJson(rootPath, workflow, options) {
                 },
             }
             : {}),
+        ...(inputs.length > 0 ? { inputs } : {}),
         label: workflow.label,
         hint: workflow.hint,
         stages: workflow.stages.map((stage) => ({
@@ -53,14 +57,34 @@ function writeWorkflowPackageJson(rootPath, workflow, options) {
     }, null, 2)}\n`);
 }
 function renderWorkflowReadme(workflow) {
+    const contextInterface = workflow.contextInterface ?? workflow.schema ?? null;
     const stageLines = workflow.stages
         .map((stage) => `- \`${stage.id}\` — ${stage.description} (${stage.contractType}; reads: ${stage.reads.join(", ")}; writes: ${stage.writes.join(", ")})`)
         .join("\n");
-    const zoneLines = workflow.schema?.zones
-        ? workflow.schema.zones
-            .map((zone) => `- \`${zone.id}\` — ${zone.role} ${zone.kind} at \`${zone.path}\``)
+    const interfaceSummary = contextInterface
+        ? summarizeContextInterface(contextInterface)
+        : null;
+    const contextInterfaceLines = contextInterface?.zones
+        ? contextInterface.zones
+            .map((zone) => `- \`${zone.id}\` — ${zone.role} ${zone.kind} at \`${zone.path}\`: ${zone.description}`)
+            .join("\n")
+        : null;
+    const inputs = workflow.inputs?.length
+        ? workflow.inputs
+        : deriveWorkflowInputsFromContextInterface(contextInterface);
+    const inputLines = inputs.length > 0
+        ? inputs
+            .map((input) => `- \`${input.id}\` — ${input.label}: ${input.description}${input.required ? " (required)" : ""}${input.examples?.length ? ` Example inputs: ${input.examples.join("; ")}` : ""}`)
             .join("\n")
         : null;
+    const contextInterfaceSummaryLines = interfaceSummary
+        ? [
+            `- Input zones: ${interfaceSummary.inputZones.length > 0 ? interfaceSummary.inputZones.map((zone) => `\`${zone.id}\``).join(", ") : "none"}`,
+            `- Working zones: ${interfaceSummary.workingZones.length > 0 ? interfaceSummary.workingZones.map((zone) => `\`${zone.id}\``).join(", ") : "none"}`,
+            `- Output zones: ${interfaceSummary.outputZones.length > 0 ? interfaceSummary.outputZones.map((zone) => `\`${zone.id}\``).join(", ") : "none"}`,
+            `- Runtime zones: ${interfaceSummary.runtimeZones.length > 0 ? interfaceSummary.runtimeZones.map((zone) => `\`${zone.id}\``).join(", ") : "none"}`,
+        ].join("\n")
+        : null;
     return [
         `# ${workflow.label}`,
         "",
@@ -74,22 +98,38 @@ function renderWorkflowReadme(workflow) {
                 `- ${workflow.purpose.taskHint}`,
             ]
             : []),
+        ...(inputLines
+            ? [
+                "",
+                "## Inputs",
+                "",
+                inputLines,
+            ]
+            : []),
+        ...(contextInterfaceLines
+            ? [
+                "",
+                "## Context Interface",
+                "",
+                ...(contextInterfaceSummaryLines
+                    ? [
+                        contextInterfaceSummaryLines,
+                        "",
+                    ]
+                    : []),
+                "Zone map:",
+                "",
+                contextInterfaceLines,
+            ]
+            : []),
         "",
         "## Package",
         "",
         "- `workflow.json` = stage graph, compiler API target, and compile contract mapping",
-        "- `workflow.schema.json` = deterministic zone contract for the workflow package",
+        "- `workflow.schema.json` = deterministic context interface for the workflow package",
         "- `improve/`, `compile/stages/`, and `use/query/` = human-readable authoring docs",
         "- Portable workflow packages are standalone: explicit stages, schema, and docs live together in this folder",
         "- Interf projects native agent shells from these docs for query use, stage execution, and workflow-improvement loops",
-        ...(zoneLines
-            ? [
-                "",
-                "## Zones",
-                "",
-                zoneLines,
-            ]
-            : []),
         "",
         "## Stages",
         "",
@@ -105,9 +145,9 @@ function renderDerivedWorkflowReadme(options) {
         "",
         options.hint,
         "",
-        `This workflow package was copied from \`${options.baseWorkflowId}\` and materialized as a standalone package for this task.`,
+        `This workflow package was copied from \`${options.baseWorkflowId}\` and materialized as a standalone package for this kind of work.`,
         "",
-        "Interf runs the local copy of this package directly. Keep changes in this folder self-contained instead of relying on runtime inheritance or fallback.",
+        "Interf runs the local copy of this package directly. Keep purpose, inputs, context interface, and stage docs self-contained in this folder instead of relying on runtime inheritance or fallback.",
         "",
         "## Emphasis",
         "",
@@ -125,7 +165,7 @@ function renderSeedWorkflowReadme(options) {
         "",
         `This workflow package was seeded from \`${options.baseWorkflowId}\` as a standalone local draft.`,
         "",
-        "Interf runs the local copy of this package directly. Refine the workflow docs, stage instructions, and zone contract in this folder instead of relying on inheritance or runtime fallback.",
+        "Interf runs the local copy of this package directly. Refine purpose, inputs, context interface, and stage instructions in this folder instead of relying on inheritance or runtime fallback.",
         "",
     ].join("\n");
 }
@@ -141,13 +181,14 @@ function renderImproveSkill(workflow) {
         "Default loop:",
         "1. Read the loop context first.",
         "2. Review preserved stage shells, runtime logs, and saved test runs from failed attempts.",
-        "3. Edit only the local workflow package for this compiled context to create a better workflow variation for this task.",
-        `4. Keep \`workflow.json\`, \`${WORKFLOW_SCHEMA_FILE}\`, and any changed stage docs aligned.`,
+        "3. Edit only the local workflow package for this compiled context to create a better workflow variation for this kind of work.",
+        `4. Keep purpose, inputs, \`workflow.json\`, \`${CONTEXT_INTERFACE_FILE}\`, and any changed stage docs aligned.`,
         "",
         "Guardrails:",
         "- do not edit checks, test specs, or raw files",
         "- do not hardcode expected answers into workflow docs",
         "- keep this package standalone; do not add or rely on runtime `extends` or fallback behavior",
+        "- keep the workflow stack coherent: purpose, inputs, context interface, and stages should describe the same job",
         "- prefer small, defensible workflow changes over random churn",
         "",
     ].join("\n");
@@ -214,15 +255,16 @@ export function writeWorkflowPackageToDir(workflowDir, workflow, options = {}) {
         mkdirSync(join(workflowDir, "compile", "stages", stage.skillDir), { recursive: true });
     }
     writeWorkflowPackageJson(workflowDir, workflow, { overwrite });
-    if (overwrite || !existsSync(join(workflowDir, WORKFLOW_SCHEMA_FILE))) {
-        if (workflow.schema) {
-            writeWorkflowSchemaDocument(workflowDir, {
-                ...workflow.schema,
-                label: workflow.schema.label || `${workflow.label} workflow schema`,
+    if (overwrite || !existsSync(join(workflowDir, CONTEXT_INTERFACE_FILE))) {
+        const contextInterface = workflow.contextInterface ?? workflow.schema;
+        if (contextInterface) {
+            writeContextInterface(workflowDir, {
+                ...contextInterface,
+                label: contextInterface.label || `${workflow.label} workflow schema`,
             });
         }
         else {
-            writeWorkflowSchemaFile(workflowDir, workflow.stages, `${workflow.label} workflow schema`);
+            writeContextInterfaceFile(workflowDir, workflow.stages, `${workflow.label} workflow schema`);
         }
     }
     if (overwrite || !existsSync(join(workflowDir, "README.md"))) {
@@ -253,10 +295,14 @@ export function seedCompiledWorkflowPackage(options) {
         copyWorkflowPackageDirectory(sourceWorkflowPath, workflowPackagePath(options.compiledPath));
         patchWorkflowPackageMetadata(workflowPackagePath(options.compiledPath), {
             id: resolvedWorkflow.id,
+            inputs: resolvedWorkflow.inputs,
             label: resolvedWorkflow.label,
             hint: resolvedWorkflow.hint,
             stagePolicyNotes: resolvedWorkflow.stagePolicyNotes,
         });
+        if (resolvedWorkflow.scope === "builtin") {
+            writeFileSync(join(workflowPackagePath(options.compiledPath), "README.md"), renderWorkflowReadme(resolvedWorkflow));
+        }
         return;
     }
     // Legacy or partially-defined seed packages are resolved once and
@@ -296,6 +342,9 @@ export function createLocalWorkflowPackageFromTemplate(options) {
     return targetPath;
 }
 export function seedLocalWorkflowPackageFromBase(options) {
+    const baseWorkflow = getCompiledWorkflow(options.baseWorkflowId, {
+        sourcePath: options.sourcePath,
+    });
     const sourceWorkflowPath = resolveWorkflowPackageSourcePath(options.sourcePath, options.baseWorkflowId);
     const targetPath = workflowDefinitionPath(options.sourcePath, options.workflowId);
     if (sourceWorkflowPath && isPortableWorkflowPackage(sourceWorkflowPath)) {
@@ -303,6 +352,7 @@ export function seedLocalWorkflowPackageFromBase(options) {
         copyWorkflowPackageDirectory(sourceWorkflowPath, targetPath);
         patchWorkflowPackageMetadata(targetPath, {
             id: options.workflowId,
+            inputs: baseWorkflow.inputs,
             label: options.label,
             hint: options.hint,
         });
@@ -315,9 +365,6 @@ export function seedLocalWorkflowPackageFromBase(options) {
     }
     // Legacy or inherited base packages are materialized immediately so the new
     // local workflow package is standalone from its first write.
-    const baseWorkflow = getCompiledWorkflow(options.baseWorkflowId, {
-        sourcePath: options.sourcePath,
-    });
     const localWorkflow = {
         ...baseWorkflow,
         id: options.workflowId,

package/dist/packages/workflow-package/local-workflows.d.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
-import { WorkflowCompilerApiSchema, RuntimeContractTypeSchema, RuntimeStageAcceptanceSchema, WorkflowPurposeSchema, WorkflowStageZoneAccessSchema, type WorkflowCompiledSchema } from "../compiler/lib/schema.js";
+import { WorkflowCompilerApiSchema, RuntimeContractTypeSchema, RuntimeStageAcceptanceSchema, WorkflowPurposeSchema, WorkflowStageZoneAccessSchema } from "../compiler/lib/schema.js";
+import { WorkflowInputSpecSchema, type ContextInterface, type WorkflowInputSpec } from "./context-interface.js";
 export interface LocalWorkflowStarterDoc {
     relativePath: string;
     content: string;
@@ -19,12 +20,13 @@ export interface LocalWorkflowDefinition {
     type: "compiled";
     compiler_api?: z.infer<typeof WorkflowCompilerApiSchema>;
     purpose?: z.infer<typeof WorkflowPurposeSchema>;
+    inputs?: Array<z.infer<typeof WorkflowInputSpecSchema>>;
     label: string;
     hint: string;
     extends?: string;
     stages?: LocalWorkflowStageDefinition[];
     stage_policy_notes?: Record<string, string[]>;
-    workflow_schema: WorkflowCompiledSchema;
+    workflow_schema: ContextInterface;
     starter_docs: LocalWorkflowStarterDoc[];
     directoryPath: string;
     workflowPath: string;
@@ -38,6 +40,7 @@ export declare function resolveWorkflowPackageSourcePath(sourcePath: string, wor
 export declare function isWorkflowId(value: string): boolean;
 export declare function patchWorkflowPackageMetadata(dirPath: string, options?: {
     id?: string;
+    inputs?: WorkflowInputSpec[];
     label?: string;
     hint?: string;
     stagePolicyNotes?: Record<string, string[]>;

package/dist/packages/workflow-package/local-workflows.js

@@ -1,13 +1,13 @@
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { dirname, join, relative } from "node:path";
 import { z } from "zod";
-import { listFilesRecursive } from "../../lib/filesystem.js";
-import { warnInterf } from "../../lib/logger.js";
-import { readJsonFileUnchecked, readJsonFileWithSchema } from "../../lib/parse.js";
-import { isMarkdownFile } from "../../lib/util.js";
-import { WORKFLOW_SCHEMA_FILE as WORKFLOW_SCHEMA_FILENAME, workflowSchemaExists, writeWorkflowSchemaDocument, workflowSchemaFilePath, readWorkflowSchemaFile, } from "../compiler/compiled-schema.js";
+import { listFilesRecursive } from "../shared/filesystem.js";
+import { warnInterf } from "../shared/logger.js";
+import { readJsonFileUnchecked, readJsonFileWithSchema } from "../shared/parse.js";
+import { isMarkdownFile } from "../shared/file-types.js";
 import { WorkflowCompilerApiSchema, RuntimeContractTypeSchema, RuntimeStageAcceptanceSchema, WorkflowPurposeSchema, WorkflowStageZoneAccessSchema, WorkflowIdPattern, } from "../compiler/lib/schema.js";
 import { listBuiltinCompiledZoneSpecs, } from "./builtin-compiled-workflow.js";
+import { CONTEXT_INTERFACE_FILE, contextInterfaceExists, contextInterfaceFilePath, readContextInterface, WorkflowInputSpecSchema, writeContextInterface, } from "./context-interface.js";
 import { PACKAGE_ROOT } from "./lib/package-root.js";
 import { mergeStagePolicyNotesForStages } from "./workflow-stage-policy.js";
 const LocalWorkflowStageDefinitionSchema = z.object({
@@ -25,6 +25,7 @@ const LocalWorkflowDefinitionSchema = z.object({
     type: z.literal("compiled"),
     compiler_api: WorkflowCompilerApiSchema.optional(),
     purpose: WorkflowPurposeSchema.optional(),
+    inputs: z.array(WorkflowInputSpecSchema).min(1).optional(),
     label: z.string().min(1),
     hint: z.string().min(1),
     extends: z.string().regex(WorkflowIdPattern).optional(),
@@ -64,7 +65,7 @@ function collectStarterDocs(dirPath) {
 function workflowPackageCopyPaths(dirPath) {
     return [
         "workflow.json",
-        WORKFLOW_SCHEMA_FILENAME,
+        CONTEXT_INTERFACE_FILE,
         ...collectStarterDocs(dirPath).map((doc) => doc.relativePath),
     ];
 }
@@ -92,7 +93,7 @@ export function loadWorkflowDefinitionFromDir(dirPath) {
     const definition = readJsonFileWithSchema(workflowPath, "local workflow definition", LocalWorkflowDefinitionSchema);
     if (!definition)
         return null;
-    const workflowSchema = readWorkflowSchemaFile(dirPath);
+    const workflowSchema = readContextInterface(dirPath);
     if (!workflowSchema)
         return null;
     if (definition.type !== "compiled") {
@@ -105,7 +106,7 @@ export function loadWorkflowDefinitionFromDir(dirPath) {
         starter_docs: collectStarterDocs(dirPath),
         directoryPath: dirPath,
         workflowPath,
-        workflowSchemaPath: workflowSchemaFilePath(dirPath),
+        workflowSchemaPath: contextInterfaceFilePath(dirPath),
     };
 }
 export function listLocalWorkflowDefinitions(sourcePath) {
@@ -169,6 +170,7 @@ export function patchWorkflowPackageMetadata(dirPath, options = {}) {
         },
         stages: normalizedStages,
         ...(options.id ? { id: options.id } : {}),
+        ...(options.inputs && options.inputs.length > 0 ? { inputs: options.inputs } : {}),
         ...(options.label ? { label: options.label } : {}),
         ...(options.hint ? { hint: options.hint } : {}),
     };
@@ -182,11 +184,11 @@ export function patchWorkflowPackageMetadata(dirPath, options = {}) {
     }
     writeFileSync(workflowPath, JSON.stringify(nextWorkflowJson, null, 2) + "\n");
     const schemaLabel = `${String(nextWorkflowJson.label ?? workflowJson.label ?? options.id ?? "Workflow")} workflow schema`;
-    const existingSchema = readWorkflowSchemaFile(dirPath);
+    const existingSchema = readContextInterface(dirPath);
     if (!existingSchema) {
-        throw new Error(`Cannot patch workflow package at ${dirPath}: missing ${WORKFLOW_SCHEMA_FILENAME}. Restore or reseed the package instead of regenerating a schema from workflow.json.`);
+        throw new Error(`Cannot patch workflow package at ${dirPath}: missing ${CONTEXT_INTERFACE_FILE}. Restore or reseed the package instead of regenerating a schema from workflow.json.`);
     }
-    writeWorkflowSchemaDocument(dirPath, {
+    writeContextInterface(dirPath, {
         ...existingSchema,
         label: schemaLabel,
     });
@@ -196,7 +198,7 @@ function collectWorkflowPackageStructureIssues(dirPath, stages) {
     const workflowPath = join(dirPath, "workflow.json");
     if (!existsSync(workflowPath))
         issues.push("missing workflow.json");
-    if (!workflowSchemaExists(dirPath))
+    if (!contextInterfaceExists(dirPath))
         issues.push("missing workflow.schema.json");
     if (!existsSync(join(dirPath, "README.md")))
         issues.push("missing README.md");
@@ -323,7 +325,7 @@ export function validateWorkflowPackage(dirPath) {
             : issue;
         errors.push(formatted);
     }
-    const workflowSchema = readWorkflowSchemaFile(dirPath);
+    const workflowSchema = readContextInterface(dirPath);
     if (!workflowSchema) {
         errors.push("workflow.schema.json is missing or invalid.");
     }

package/dist/packages/workflow-package/workflow-definitions.d.ts

@@ -1,4 +1,5 @@
-import type { RuntimeContractType, RuntimeStageAcceptance, WorkflowCompilerApi, WorkflowCompiledSchema, WorkflowId, WorkflowZoneId } from "../compiler/lib/schema.js";
+import type { RuntimeContractType, RuntimeStageAcceptance, WorkflowCompilerApi, WorkflowId } from "../compiler/lib/schema.js";
+import { type ContextInterface, type ContextInterfaceZoneId, type WorkflowInputSpec } from "./context-interface.js";
 export interface WorkflowStarterDoc {
     relativePath: string;
     content: string;
@@ -9,8 +10,8 @@ export interface WorkflowStageDefinition {
     description: string;
     contractType: RuntimeContractType;
     skillDir: string;
-    reads: WorkflowZoneId[];
-    writes: WorkflowZoneId[];
+    reads: ContextInterfaceZoneId[];
+    writes: ContextInterfaceZoneId[];
     acceptance?: RuntimeStageAcceptance;
 }
 export interface WorkflowDefinition<TId extends string> {
@@ -20,10 +21,12 @@ export interface WorkflowDefinition<TId extends string> {
         label: string;
         taskHint: string;
     };
+    inputs?: WorkflowInputSpec[];
     label: string;
     hint: string;
     recommended?: boolean;
-    schema?: WorkflowCompiledSchema;
+    contextInterface?: ContextInterface;
+    schema?: ContextInterface;
     stages: WorkflowStageDefinition[];
     stagePolicyNotes?: Record<string, string[]>;
     starterDocs?: WorkflowStarterDoc[];
@@ -37,6 +40,7 @@ export declare function standaloneWorkflowDefinitionFromLocalPackage(local: {
         label: string;
         task_hint: string;
     };
+    inputs?: WorkflowInputSpec[];
     label: string;
     hint: string;
     stages?: Array<{
@@ -45,12 +49,12 @@ export declare function standaloneWorkflowDefinitionFromLocalPackage(local: {
         description?: string;
         contract_type: RuntimeContractType;
         skill_dir?: string;
-        reads: WorkflowZoneId[];
-        writes: WorkflowZoneId[];
+        reads: ContextInterfaceZoneId[];
+        writes: ContextInterfaceZoneId[];
         acceptance?: RuntimeStageAcceptance;
     }>;
     stage_policy_notes?: Record<string, string[]>;
-    workflow_schema?: WorkflowCompiledSchema;
+    workflow_schema?: ContextInterface;
     starter_docs: WorkflowStarterDoc[];
 }): WorkflowDefinition<string>;
 export declare function listCompiledWorkflowChoices(sourcePath?: string): WorkflowDefinition<string>[];

package/dist/packages/workflow-package/workflow-definitions.js

@@ -1,10 +1,11 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { isWorkflowId, listLocalWorkflowDefinitions, loadLocalWorkflowDefinition, loadWorkflowDefinitionFromDir, } from "./local-workflows.js";
-import { warnInterf } from "../../lib/logger.js";
-import { workflowPackagePathForCompiled } from "../project-model/compiled-paths.js";
+import { warnInterf } from "../shared/logger.js";
+import { workflowPackagePathForCompiled } from "../compiler/compiled-paths.js";
 import { resolveSourceControlPath } from "../project-model/interf.js";
 import { PACKAGE_ROOT } from "./lib/package-root.js";
+import { deriveWorkflowInputsFromContextInterface, } from "./context-interface.js";
 import { mergeStagePolicyNotesForStages } from "./workflow-stage-policy.js";
 let builtinInterfWorkflowCache = null;
 function toWorkflowStages(stages, fallbackStages) {
@@ -26,6 +27,10 @@ export function standaloneWorkflowDefinitionFromLocalPackage(local) {
         throw new Error(`Workflow package "${local.id}" is missing explicit stages. Compiled-local and portable workflow packages must be standalone.`);
     }
     const stages = toWorkflowStages(local.stages, []);
+    const contextInterface = local.workflow_schema;
+    const inputs = local.inputs?.length
+        ? [...local.inputs]
+        : deriveWorkflowInputsFromContextInterface(contextInterface);
     return {
         id: local.id,
         compilerApi: local.compiler_api ?? {
@@ -40,10 +45,12 @@ export function standaloneWorkflowDefinitionFromLocalPackage(local) {
                 },
             }
             : {}),
+        inputs,
         label: local.label,
         hint: local.hint,
         recommended: false,
-        ...(local.workflow_schema ? { schema: local.workflow_schema } : {}),
+        contextInterface,
+        ...(contextInterface ? { schema: contextInterface } : {}),
         stages,
         stagePolicyNotes: mergeStagePolicyNotesForStages(stages, undefined, local.stage_policy_notes),
         starterDocs: [...local.starter_docs],

package/dist/packages/workflow-package/workflow-helpers.js

@@ -1,10 +1,10 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join, relative, sep } from "node:path";
-import { listFilesRecursive } from "../../lib/filesystem.js";
-import { parseJsonFrontmatter } from "../../lib/parse.js";
-import { isMarkdownFile } from "../../lib/util.js";
+import { listFilesRecursive } from "../shared/filesystem.js";
+import { parseJsonFrontmatter } from "../shared/parse.js";
+import { isMarkdownFile } from "../shared/file-types.js";
 import { getCompiledWorkflow, } from "./workflow-definitions.js";
-import { workflowPackagePathForCompiled } from "../project-model/compiled-paths.js";
+import { workflowPackagePathForCompiled } from "../compiler/compiled-paths.js";
 const LOCAL_SKILL_READ_LIMIT = 50;
 export function workflowQueryDirectory() {
     return "workflow/use/query";

package/dist/packages/workflow-package/workflow-review-paths.js

@@ -1,5 +1,5 @@
 import { existsSync } from "node:fs";
-import { testRootForCompiled, targetTestRunsRootForCompiled, targetTestSandboxesRootForCompiled, stageExecutionShellsRoot, compiledRuntimeRoot, } from "../project-model/compiled-paths.js";
+import { testRootForCompiled, targetTestRunsRootForCompiled, targetTestSandboxesRootForCompiled, stageExecutionShellsRoot, compiledRuntimeRoot, } from "../compiler/compiled-paths.js";
 export function resolveWorkflowImprovementReviewSourcePaths(compiledPath) {
     const compiledRuntime = compiledRuntimeRoot(compiledPath);
     const testComparisons = testRootForCompiled(compiledPath);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@interf/compiler",
-  "version": "0.6.3",
-  "description": "Interf prepares task context for your agents by testing the files behind a task, building a local context folder, and using self-improving loops until checks pass.",
+  "version": "0.6.4",
+  "description": "Interf prepares context for your agents by checking your files first, building a local folder when needed, and using self-improving loops until more questions pass.",
   "type": "module",
   "bin": {
     "interf": "dist/bin.js"