@interf/compiler 0.6.9 → 0.7.1

package/README.md

@@ -2,32 +2,55 @@
 
 Interf prepares portable context for your agents.
 
-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.
+Point an agent at a folder of files. It gets a partial picture. It picks up false hypotheses from a shallow read. Then it carries those into the work — missed evidence, links lost across files, confident answers that 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.
+The fix is structure: summarize the files, organize by category, link what belongs together. You tell Interf Compiler how. That's a compilation workflow.
 
-`Interf Compiler` is the local, open-source 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.
+`Interf Compiler` is a local runtime. It runs your compilation workflow on your files. Your local agent executes each stage. The output is portable context — a local folder your agent reads. If the first build misses your questions, Interf improves the workflow and builds again.
 
 ```text
 project-root/
   bristol-office-analysis/
-    report.pdf
+    report.md
     notes.md
     exports/
   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
 ```
 
 The project root is the control plane. Your agent starts from `interf/<work>/` when the source files are not enough.
 
+## What a Run Looks Like
+
+Same files, same questions. What changes is whether the context was prepared first.
+
+A recent public run — one market report, two questions, two agents on the same setup — produced:
+
+<!-- PUBLIC_BENCHMARK_TABLE:START -->
+| Agent | Source files | Portable context |
+| --- | --- | --- |
+| Codex (GPT-5.4, xhigh) | `2/2` | `2/2` |
+| Claude Code (Claude Opus 4.6, max) | `0/2` | `2/2` |
+<!-- PUBLIC_BENCHMARK_TABLE:END -->
+
+Codex passed on the raw files; Claude Code only passed after Interf prepared the portable context. Both numbers come from `interf test`, which scores the same questions against the source files and the portable context.
+
+That gives you a readiness signal for the work and a fair comparison on the same files.
+
+The table is a sample, not a leaderboard. Run it on your own files. If you run more than one local agent, the same pass gives you a fair comparison between them on the same files.
+
 ## Design Choices
 
+- `Local-first`: your files, your questions, and your agent stay on your machine. No cloud, no uploads.
+- `File over app`: the portable context is a local folder next to the source files. Inspect it, diff it, version it.
 - `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.
 
@@ -51,11 +74,11 @@ Requires Node.js 20+ and a local coding agent such as Claude Code or Codex. Run
 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>/`.
 
-By default, Interf uses the built-in `interf` compilation workflow. Create your own compilation workflow only when the built-in method is not enough for the work, or you need a different output.
+`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 Interf Compiler builds from your files — a context layer your agents navigate, not a replacement for your files. 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/
@@ -73,18 +96,16 @@ The portable context is a folder you can inspect, diff, version, or hand to a di
 
 ## Workflow Packages
 
-A compilation workflow is how you tell Interf Compiler to organize and structure your files so your agents can reliably work from them. The built-in `interf` workflow covers common cases. Create your own when you need a different method, a different output, or both.
-
-Run `interf create workflow` to draft a reusable workflow package.
+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 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/
@@ -92,8 +113,6 @@ interf/workflows/office-analysis/
   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: 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.
@@ -102,23 +121,6 @@ Think of it as method -> output shape.
 
 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.
 
-## What a Run Looks Like
-
-A recent public run — one PDF market report, two questions, two agents on the same setup — produced:
-
-<!-- PUBLIC_BENCHMARK_TABLE:START -->
-| Agent | Source files | Portable context |
-| --- | --- | --- |
-| Codex (GPT-5.4, xhigh) | `2/2` | `2/2` |
-| Claude Code (Claude Opus 4.6, max) | `0/2` | `2/2` |
-<!-- PUBLIC_BENCHMARK_TABLE:END -->
-
-Codex passed on the raw files; Claude Code only passed after Interf prepared the portable context. Both numbers come from `interf test`, which scores the same questions against the source files and the portable context.
-
-That gives you a readiness signal for the work and a fair comparison on the same files.
-
-The table is a sample, not a leaderboard. Run it on your own files. If you run more than one local agent, the same pass gives you a fair comparison between them on the same files.
-
 ## 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.
@@ -145,7 +147,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": "..." }
       ]
@@ -154,7 +156,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 compilation workflow you have authored. A different compilation workflow is a different method and a different output. 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
 

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,6 +1,6 @@
 {
   "name": "@interf/compiler",
-  "version": "0.6.9",
+  "version": "0.7.1",
   "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": {