@interf/compiler 0.6.8 → 0.7.0

package/README.md

@@ -1,15 +1,12 @@
 # Interf
 
 Interf prepares portable context for your agents.
-Check the source files first. Build portable context when the agent misses evidence, loses links across files, or sounds confident without seeing the full picture.
 
-**The files can be right. The agent can still be wrong.**
+Agents now run real work from folders of PDFs, exports, notes, and transcripts. They don't reliably assemble the full picture from them: missed evidence, links lost across files, or answers that sound confident but are wrong. A chart inside one PDF can be obvious to a human analyst and easy for an agent to miss.
 
-Agents now run real work from folders of PDFs, exports, notes, and transcripts. The failure often shows up late: missed evidence, shallow analysis, bad comparisons, or answers that sound confident but are wrong.
+The fix is structure: summarize the files, organize by category, link what belongs together. You tell Interf Compiler how — that's a compilation workflow.
 
-A chart inside one PDF can be obvious to a human analyst and easy for an agent to miss. Across the folder, the real problem is rarely one missing fact. The agent never assembles the full picture from the files on its own.
-
-`Interf Compiler` is the local, open-source runtime that runs context-preparation workflows on your files. A workflow tells Interf how to process, organize, and structure those files for agent use. Your local agent runs each stage. Interf Compiler runs the pipeline and enforces the output shape. `interf test` scores the result on your own questions. The portable context is a proof, not a promise.
+`Interf Compiler` is the local runtime that runs compilation workflows on your files. Your local agent executes each stage. The compiler builds portable context — a local folder your agent reads. If the first build misses your questions, Interf improves the compilation workflow and builds again.
 
 ```text
 project-root/
@@ -20,6 +17,9 @@ project-root/
   interf.json                   # main config: works, source paths, questions, workflow choices, and defaults
   interf/
     bristol-office-analysis/    # portable context your agent starts from
+    workflows/
+      interf-default/           # built-in compilation workflow, copied here on init — inspect, edit, or fork
+      your-custom-workflow/     # optional: your own, via `interf create workflow`
     tests/
       bristol-office-analysis/  # saved source-files vs portable-context comparisons
 ```
@@ -45,8 +45,8 @@ The table is a sample, not a leaderboard. Run it on your own files. If you run m
 
 ## Design Choices
 
-- `Check before build`: source files are sometimes already enough. Interf will say so.
-- `Prove the full picture`: every build is scored on your own questions. If the portable context does not help, `interf test` tells you.
+- `Check before build`: run `interf test --target raw` first — sometimes the source files already pass on your questions.
+- `Scored on your own questions`: every build is checked against questions you wrote from the files. If the portable context does not help, `interf test` tells you.
 - `File over app`: the portable context is a local folder next to the source files. Inspect it, diff it, version it.
 - `Bring your own AI`: use Claude Code, Codex, or another local agent.
 - `Explicit`: no hidden store, no hidden index. The portable context is plain files on disk.
@@ -63,19 +63,19 @@ Requires Node.js 20+ and a local coding agent such as Claude Code or Codex. Run
 ## Quick Start
 
 1. Run `interf` in the project root.
-2. Pick the source folder for one work.
+2. Pick the source folder for one piece of agent work.
 3. Describe what the agent should do with those files.
 4. Review the suggested questions.
-5. Run `interf test --target raw` to check the source files.
+5. Run `interf test --target raw` to score the source files.
 6. Run `interf compile` to build portable context.
 7. Run `interf test` again to compare source files and portable context on the same questions.
 8. If the portable context does better, point your agent at `interf/<work>/`.
 
-If the source files already pass, stop there. Interf is allowed to tell you that you do not need portable context for that work.
+`interf init` copies the built-in compilation workflow to `interf/workflows/interf-default/`. That folder is yours — inspect it, edit it, or fork it into a new compilation workflow with `interf create workflow`.
 
 ## Portable Context
 
-`interf/<work>/` is the local folder your agent starts from when the source files are not enough. For the built-in `interf` workflow, it includes:
+`interf/<work>/` is the local folder Interf Compiler builds from your files — a context layer your agents navigate, not a replacement for your files. For the built-in `interf-default`, it includes:
 
 ```text
 interf/bristol-office-analysis/
@@ -89,77 +89,55 @@ interf/bristol-office-analysis/
 
 The source files stay the source of truth. Interf builds next to them; it does not replace them.
 
-The portable context is a sibling folder you can inspect, diff, version, or hand to a different agent. The portable context carries its own `raw/` snapshot, so the evidence the agent works from stays attached to the result.
+The portable context is a folder you can inspect, diff, version, or hand to a different agent. The portable context carries its own `raw/` snapshot, so the evidence the agent works from stays attached to the result.
 
 ## Workflow Packages
 
-A workflow is Interf's preparation method for a kind of work. It tells the compiler how to process the source files and what folder shape to build for the agent. The workflow declares the compilation stages. Your local agent runs each one. The compiler writes the result as one folder on disk.
-
-A **context interface** is the shape of that output — the folder tree, the named files, and the rule that every one of them must exist on disk before the build is called done. The workflow defines the interface. The compiler enforces it.
-
-The built-in `interf` workflow is the default. Run `interf create workflow` to draft a reusable workflow package for a different kind of work — a different method, a different output shape, or both.
+A compilation workflow is how you tell Interf Compiler to organize and structure your files so your agents can reliably work from them. `interf init` copies the built-in `interf-default` into your project at `interf/workflows/interf-default/` — it is a real folder you can inspect and edit. Fork it with `interf create workflow` when you need a different method, a different output, or both.
 
 ```text
-interf/workflows/office-analysis/
+interf/workflows/interf-default/
   workflow.json         # method: how to process and organize the files
-  workflow.schema.json  # output contract: what folder shape the compiler must build
-  README.md             # what this workflow is for, for humans and agents
+  workflow.schema.json  # output contract: what files and folders the output must contain
+  README.md             # what this compilation workflow is for, for humans and agents
   compile/
     stages/
-      summarize/        # define your own stages here
+      summarize/        # stage instructions the compiler runs with your local agent
       structure/
       shape/
   use/
     query/              # how your agent reads the portable context
-  improve/              # how Interf revises this workflow if questions still fail
+  improve/              # how Interf revises this compilation workflow if questions still fail
 ```
 
 Think of it as method -> output shape.
 
 - `workflow.json` describes the method: expected inputs, stages, and how the files should be processed.
-- `workflow.schema.json` describes the output contract: the folder shape and outputs the compiler must build.
-- `compile/stages/<stage>/` is where you author one folder per stage — a small, specific job like `summarize` or `structure`. You write the instructions; the compiler runs them with your local agent.
+- `workflow.schema.json` describes the output contract: what files and folders the output must contain. Technically, this is the `context interface`, declared in `workflow.schema.json` and enforced by the compiler.
+- `compile/stages/<stage>/` is where you author one folder per stage — a small, specific phase like `summarize` or `structure`. You write the instructions; the compiler runs them with your local agent.
 - `use/query/` holds the instructions your agent follows when it reads the portable context for live work.
-- `improve/` holds the instructions Interf follows when the first build does not pass and the workflow itself needs editing.
-
-A workflow package is the reusable preparation method. Interf Compiler runs it on your files. Your local agent runs each stage. The result is a local folder your agents can read.
-
-## Compiler Primitives
-
-Every workflow runs on the same three primitives. Interf Compiler enforces the contract. The workflow chooses the method.
-
-### Input snapshot
-
-The workflow declares what source files it expects — one PDF, a folder of mixed exports, a tree of notes. Interf Compiler copies those inputs into `raw/` before any stage runs. The evidence stays attached to the result.
-
-### Context interface
-
-The workflow declares the folder shape the agent must read. Interf Compiler checks on disk that the shape holds before the build is called done. If a stage writes nothing, the build fails loudly.
-
-### Stage execution
-
-The workflow declares ordered compilation stages — small, specific jobs like `summarize`, `structure`, `shape`. You write the instructions per stage. Interf Compiler runs each one through your local agent and checks the output before moving to the next.
+- `improve/` holds the instructions Interf follows when the first build misses and the compilation workflow itself needs editing.
 
-The context interface is the key guarantee. The shape holds on disk, or `interf test` reports the gap on your own questions.
+A workflow package bundles a compilation workflow. Interf Compiler runs it on your files. Your local agent runs each stage. The result is a local folder your agents can read.
 
 ## Self-Improving Workflows
 
-When the first build still misses questions, Interf edits the workflow package itself and compiles again. Same files, same questions, different preparation. The workflow is the unit of improvement — not just the output folder.
+When the first build still misses questions, Interf edits the workflow package itself and compiles again. Same files, same questions, different preparation.
 
 Interf saves every scored run under `interf/tests/<work>/`. You can inspect what changed and why a later build did better.
 
 ## How the Pieces Fit
 
-- `interf.json` is the project control file. It names the work, points at the source files, saves the questions, and selects the workflow.
-- A workflow package is the reusable preparation method.
-- `workflow.json` defines that method.
+- `interf.json` is the project control file. It names the work, points at the source files, saves the questions, and selects the compilation workflow.
+- A workflow package bundles a compilation workflow.
+- `workflow.json` defines the method.
 - `workflow.schema.json` defines the output contract, or context interface, the compiler must build.
-- `Interf Compiler` is the local runtime. It runs the workflow, your agent runs each stage, and the portable context lands next to the source files.
+- `Interf Compiler` is the local runtime. It runs the compilation workflow, your agent runs each stage, and the portable context lands next to the source files.
 - The portable context is the local folder built for your agents. Technically, that folder is the compiled context.
 
 ## interf.json
 
-`interf.json` is the main config file in the project root. Each entry describes one work: the source path, the saved questions, the workflow that prepares the context, and optional defaults.
+`interf.json` is the main config file in the project root. Each entry describes one piece of agent work: the source path, the saved questions, the compilation workflow that prepares the context, and optional defaults.
 
 ```text
 {
@@ -168,7 +146,7 @@ Interf saves every scored run under `interf/tests/<work>/`. You can inspect what
       "name": "bristol-office-analysis",
       "path": "./bristol-office-analysis",
       "about": "Read the report and answer the saved questions.",
-      "workflow": "interf",
+      "workflow": "interf-default",
       "checks": [
         { "question": "...", "answer": "..." }
       ]
@@ -177,7 +155,7 @@ Interf saves every scored run under `interf/tests/<work>/`. You can inspect what
 }
 ```
 
-The `workflow` field is the key choice per work. Set it to `interf` for the built-in workflow, or to a workflow you have authored. A different workflow is a different method and a different output shape. Same files, different portable context.
+The `workflow` field is the key choice per work. It points to a folder id under `interf/workflows/`. Set it to `interf-default` (the built-in default, copied locally on init) or to a compilation workflow you have authored. A different compilation workflow is a different method and a different output. Same files, different portable context.
 
 ## Questions
 
@@ -219,7 +197,7 @@ A maintained public test example in this repo stores them like this:
 
 ## What Interf Is Not
 
-- Not a second brain or memory product. One local folder per work; nothing global.
+- Not a second brain or memory product. One local folder per piece of agent work; nothing global.
 - Not a vector store or RAG server. The portable context is plain files.
 - Not a hosted context layer. Interf runs locally and `interf/` is yours.
 - Not an agent harness. Interf prepares the folder; your existing agent reads it.

package/dist/cli/commands/create-workflow-wizard.js

@@ -3,7 +3,8 @@ import * as p from "@clack/prompts";
 import { resolve } from "node:path";
 import { listCompiledWorkflowChoices, getCompiledWorkflow, } from "../../packages/workflow-package/workflow-definitions.js";
 import { createLocalWorkflowPackageFromTemplate } from "../../packages/workflow-package/interf-workflow-package.js";
-import { isWorkflowId, } from "../../packages/workflow-package/local-workflows.js";
+import { rmSync } from "node:fs";
+import { isWorkflowId, loadWorkflowDefinitionFromDir, } from "../../packages/workflow-package/local-workflows.js";
 import { resolveOrConfigureLocalExecutor } from "./executor-flow.js";
 import { runWorkflowAuthoringDraft } from "../../packages/workflow-authoring/workflow-authoring.js";
 import { listSourceDatasetConfigs, loadSourceFolderConfig, resolveSourceDatasetPath, } from "../../packages/project-model/source-config.js";
@@ -214,9 +215,9 @@ export async function createCompiledWorkflowWizard(sourcePath, prompts = clackWo
             matchedDataset = matchedDataset ?? findMatchingDatasetConfig(sourcePath, datasetPath);
         }
         const taskPrompt = await prompts.text({
-            message: "What kind of work should this workflow help with?",
-            placeholder: "Example: chart reads, board prep, or latest planned launch status",
-            validate: (value) => (value.trim().length === 0 ? "Work focus is required" : undefined),
+            message: "How do you want to organize your files?",
+            placeholder: "Research interview transcripts. Agent produces per-interview summaries and a themes list with supporting quotes. Flow: summarize each, group by theme, collect evidence across interviews.",
+            validate: (value) => (value.trim().length === 0 ? "A description is required" : undefined),
         });
         if (prompts.isCancel(taskPrompt))
             return taskPrompt;
@@ -254,6 +255,26 @@ export async function createCompiledWorkflowWizard(sourcePath, prompts = clackWo
             preparePreview: true,
         });
         if (result.status === "updated") {
+            const draft = loadWorkflowDefinitionFromDir(result.workflowPath);
+            const stageList = draft?.stages?.map((stage) => stage.id).join(" → ") ?? "—";
+            prompts.log.info(`Draft ready at ${result.workflowPath}`);
+            prompts.log.info(`  Name: ${draft?.label ?? label}`);
+            prompts.log.info(`  Description: ${draft?.hint ?? hint.trim()}`);
+            if (draft?.purpose)
+                prompts.log.info(`  Purpose: ${draft.purpose}`);
+            prompts.log.info(`  Stages: ${stageList}`);
+            const confirmChoice = await prompts.select({
+                message: "Save this workflow?",
+                options: [
+                    { value: "save", label: "Save", hint: "Keep the draft as your new compilation workflow" },
+                    { value: "cancel", label: "Discard", hint: "Remove the draft folder and exit without saving" },
+                ],
+            });
+            if (prompts.isCancel(confirmChoice) || confirmChoice === "cancel") {
+                rmSync(result.workflowPath, { recursive: true, force: true });
+                prompts.log.info(`Discarded draft at ${result.workflowPath}`);
+                return null;
+            }
             prompts.log.info(`Saved local workflow: ${result.workflowPath}`);
             return workflowId;
         }

package/dist/cli/commands/init.js

@@ -5,6 +5,7 @@ import { detectInterf, readInterfConfig, resolveSourceControlPath, } from "../..
 import { SOURCE_FOLDER_CONFIG_FILE, syncCompiledInterfConfigFromSourceDatasetConfig, upsertSourceDatasetConfig, } from "../../packages/project-model/source-config.js";
 import { DEFAULT_COMPILED_NAME, describeCompileLoopSelection, promptSingleCompiledConfig, } from "./source-config-wizard.js";
 import { buildCompiledWorkflowOptions, chooseCompiledWorkflow, createWorkflowWizard, } from "./create-workflow-wizard.js";
+import { seedLocalDefaultWorkflow } from "../../packages/workflow-package/local-workflows.js";
 import { findBuiltCompiledPath, findSavedCompiledConfig, listSavedCompiledEntries, } from "./compiled-flow.js";
 import { readCurrentSavedTestComparison, } from "./test-flow.js";
 import { runCompileCommand } from "./compile.js";
@@ -219,7 +220,7 @@ async function chooseCompiledForWizard(options) {
     return findSavedCompiledConfig(options.sourcePath, String(selected));
 }
 async function promptCompiledSetup(options) {
-    let workflowId = options.initial?.workflow ?? "interf";
+    let workflowId = options.initial?.workflow ?? "interf-default";
     let workflowLabel = buildCompiledWorkflowOptions(options.sourcePath)
         .find((option) => option.value === workflowId)?.label ?? workflowId;
     if (options.introStyle === "edit") {
@@ -258,7 +259,7 @@ async function promptCompiledSetup(options) {
     console.log(chalk.dim(`  Project folder: ${options.sourcePath}`));
     console.log(chalk.dim(`  Setup: ${compiledConfigWithWorkflow.name}`));
     console.log(chalk.dim(`  Source folder: ${compiledConfigWithWorkflow.path}`));
-    console.log(chalk.dim(`  Workflow: ${workflowLabel}`));
+    console.log(chalk.dim(`  Workflow: ${workflowLabel} · interf/workflows/${workflowId}/`));
     console.log(chalk.dim(`  Compile mode: ${describeCompileLoopSelection({
         maxAttempts: compiledConfigWithWorkflow.max_attempts,
         maxLoops: compiledConfigWithWorkflow.max_loops,
@@ -456,13 +457,18 @@ export const initCommand = {
 };
 export async function runInitCommand() {
     p.intro(chalk.bold("Interf"));
-    p.log.info("Interf prepares portable context for your agents from the source folder you choose. Start with the work, review the suggested questions, check the source files first, and build a local folder when the files need more structure.");
+    p.log.info("Interf prepares portable context for your agents.");
+    p.log.info("Pick a source folder, review the suggested questions, and build when the files need more structure.");
     const cwd = process.cwd();
     const detected = detectInterf(cwd);
     const sourcePath = detected ? resolveSourceControlPath(detected.path) : cwd;
     if (detected) {
         p.log.info(`Working from the project folder: ${sourcePath}`);
     }
+    const seeded = seedLocalDefaultWorkflow({ sourcePath });
+    if (!seeded.alreadyExisted) {
+        p.log.info(`Copied built-in compilation workflow to interf/workflows/${seeded.workflowId}/ — inspect or fork it anytime.`);
+    }
     const savedEntries = listSavedCompiledEntries(sourcePath);
     if (savedEntries.length === 0) {
         const compiledConfig = await promptCompiledSetup({

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

@@ -37,6 +37,13 @@ export declare function loadWorkflowDefinitionFromDir(dirPath: string): LocalWor
 export declare function listLocalWorkflowDefinitions(sourcePath: string): LocalWorkflowDefinition[];
 export declare function loadLocalWorkflowDefinition(sourcePath: string, id: string): LocalWorkflowDefinition | null;
 export declare function resolveWorkflowPackageSourcePath(sourcePath: string, workflowId: string): string | null;
+export declare function seedLocalDefaultWorkflow(options: {
+    sourcePath: string;
+}): {
+    workflowId: string;
+    targetPath: string;
+    alreadyExisted: boolean;
+};
 export declare function isWorkflowId(value: string): boolean;
 export declare function patchWorkflowPackageMetadata(dirPath: string, options?: {
     id?: string;

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

@@ -131,16 +131,33 @@ export function loadLocalWorkflowDefinition(sourcePath, id) {
     return loadWorkflowDefinitionFromDir(workflowDefinitionPath(sourcePath, id));
 }
 export function resolveWorkflowPackageSourcePath(sourcePath, workflowId) {
-    const builtinPath = builtinWorkflowRootPath(workflowId);
-    if (workflowId === "interf" && existsSync(join(builtinPath, "workflow.json")))
-        return builtinPath;
     const localPath = workflowDefinitionPath(sourcePath, workflowId);
     if (existsSync(join(localPath, "workflow.json")))
         return localPath;
+    const builtinPath = builtinWorkflowRootPath(workflowId);
     if (existsSync(join(builtinPath, "workflow.json")))
         return builtinPath;
+    if (workflowId === "interf-default") {
+        const builtinInterfPath = builtinWorkflowRootPath("interf");
+        if (existsSync(join(builtinInterfPath, "workflow.json")))
+            return builtinInterfPath;
+    }
     return null;
 }
+export function seedLocalDefaultWorkflow(options) {
+    const workflowId = "interf-default";
+    const targetPath = workflowDefinitionPath(options.sourcePath, workflowId);
+    if (existsSync(join(targetPath, "workflow.json"))) {
+        return { workflowId, targetPath, alreadyExisted: true };
+    }
+    const builtinInterfPath = builtinWorkflowRootPath("interf");
+    if (!existsSync(join(builtinInterfPath, "workflow.json"))) {
+        throw new Error(`Built-in "interf" workflow not found at ${builtinInterfPath}.`);
+    }
+    copyWorkflowPackageDirectory(builtinInterfPath, targetPath);
+    patchWorkflowPackageMetadata(targetPath, { id: workflowId });
+    return { workflowId, targetPath, alreadyExisted: false };
+}
 export function isWorkflowId(value) {
     return WorkflowIdPattern.test(value);
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@interf/compiler",
-  "version": "0.6.8",
-  "description": "Interf prepares portable context for your agents by checking your files first, building a local folder when needed, and using self-improving loops until more questions pass.",
+  "version": "0.7.0",
+  "description": "Local, open-source context compiler for agent work. Build portable context from your files with a compilation workflow you define. Check on your own questions.",
   "type": "module",
   "bin": {
     "interf": "dist/bin.js"