@interf/compiler 0.6.5 → 0.6.6

package/README.md

@@ -1,18 +1,17 @@
 # Interf
 
 Interf prepares context for your agents.
+Use it to check whether your files are ready for the work you want your agents to do.
 
-Start with the files for the work you want to do. Tell Interf what you need, let it suggest a few questions to check accuracy, and build portable context for your agents when the files alone are not enough.
-
-Interf Compiler builds portable context in a local folder inside your project.
-Your agents can use it directly. Interf can check it on those same questions.
+Tell Interf what you need from those files. It can compare how your local agents do on the source files. If the files alone are not enough, it builds portable context and keeps improving that context until more questions pass.
 
+Interf Compiler builds that portable context as a local folder next to your files.
 Your source files stay the source of truth. Interf builds on them; it does not replace them.
 
-For the built-in `interf` workflow, a portable context can include:
+For the built-in `interf` workflow, portable context for your agents includes:
 
 ```text
-interf/<dataset>/
+interf/market-report/
   AGENTS.md      # how your agent should use this folder
   CLAUDE.md      # same guidance for Claude Code
   home.md        # top-level map for the work
@@ -20,14 +19,14 @@ interf/<dataset>/
   knowledge/     # linked notes built from those files
 ```
 
-That is an example, not a fixed ABI. Different workflows can build different folders. The simple part is that your agent gets one local folder to start from.
+That is one example. Different workflows can build different folders. In every case, your agent starts from one local folder.
 
-This repo includes a small PDF example with questions like:
+One public example from a PDF market report uses checks like:
 
 - `What were Bristol's annual take-up values in 2018 and 2016?`
 - `What were Bristol's availability values in 2018 and 2016?`
 
-On those same questions, a recent run in this repo produced:
+On those same checks, one recent public comparison produced:
 
 <!-- PUBLIC_BENCHMARK_TABLE:START -->
 | Agent | Source files | Portable context |
@@ -41,15 +40,18 @@ That means:
 - Codex already passed on the source files.
 - Claude Code needed the portable context to pass.
 
-Same work. Same questions. Same local setup.
+That gives you a readiness signal for the work and a fair comparison on the same files.
+
+Same work. Same checks. Same local setup.
 
 ## How It Works
 
 1. Pick the files for the work.
 2. Tell Interf what you need from them.
 3. Review or edit the questions.
-4. Build the portable context for your agents.
-5. Run `interf test` on the same questions.
+4. Run a source-files baseline if you want to check readiness first.
+5. Build the portable context for your agents.
+6. Run `interf test` on the same questions.
 
 Check the source files first if you want the baseline. If the files already pass, keep them. If the portable context does better, use it.
 
@@ -59,35 +61,36 @@ Raw files are often not enough.
 
 Local agents can open reports, decks, transcripts, exports, PDFs, notes, and mixed folders. They can still miss the structure the work needs.
 
-Interf builds a local folder for that work and checks whether it helped.
+Interf checks the source files first. If they are already enough, keep them. If they are not, Interf builds a local context layer next to those files and checks whether it helped.
 
 Interf is built around a few simple rules:
 
-- Start from the files you already have.
-- Check source files and portable context on the same questions.
-- Keep the result in a local folder you can inspect, diff, review, and version.
-- Keep source files as the source of truth.
-- Use the portable context manually from Claude Code, Codex, or another local agent. Automated Interf runs currently support Claude Code and Codex.
-- If the first pass is not enough, let Interf retry the same workflow or improve the workflow itself.
+- Explicit: the preparation stays on disk in a local folder you can inspect, diff, review, and version.
+- File over app: the result lives next to the source files.
+- Bring your own AI: use Claude Code, Codex, or another local agent. Automated Interf runs currently support Claude Code and Codex.
+- Proof over vibes: check source files and portable context on the same work.
+- Source files stay the source of truth.
 
-## What You Get
+## Folder Layout
 
-A small project can stay simple:
+If your folder already contains the files for the work, Interf adds a small local structure around them:
 
 ```text
-your-project/
-  task-files/
+your-folder/
+  market-report/
     report.pdf
     notes.md
     exports/
   interf.json
   interf/
-    <dataset>/
+    market-report/
     tests/
-      <dataset>/
+      market-report/
 ```
 
-After Interf runs, point your agents at `interf/<dataset>/` first. Go back to the source files whenever you need to verify something.
+`market-report` is just the work name. Interf reuses it under `interf/` and `interf/tests/`.
+
+When Interf finishes, point your agents at `interf/market-report/` first. Go back to the source files whenever you need to verify something.
 
 ## Quick Start
 
@@ -108,13 +111,13 @@ Then run Interf in a project folder that already contains the files for the work
 interf
 ```
 
-The first run opens the dataset wizard for that folder. It can:
+The first run opens the setup wizard for that folder. It can:
 
 - draft `interf.json`
 - let you choose the source folder for the work
 - ask what work you need help with
-- recommend questions to check accuracy, or let you add them manually
-- run a source-files baseline so you can see what already works
+- recommend questions you can verify from the files, or let you add them manually
+- run a source-files baseline so you can see whether the files are already enough
 - build the portable context your agents will use for that work
 - check that portable context on the same questions
 
@@ -124,11 +127,14 @@ If Interf cannot find your local executor setup, run:
 interf doctor --live
 ```
 
-## Questions
+## Checks
 
-Interf uses simple questions to check whether the portable context is good enough for your agents on this work.
+Interf uses question-and-answer checks.
+They are small questions that tell you whether the work is actually covered.
 
-Good first questions are small and easy to verify from the files:
+Interf runs the same checks on the source files and on the portable context. That gives you a source-files baseline and a portable-context comparison on the same task.
+
+Good first checks are small and easy to verify from the files:
 
 - one exact number from a chart, table, or filing
 - one short statement that should be true or false
@@ -136,7 +142,7 @@ Good first questions are small and easy to verify from the files:
 
 Interf can recommend a starting set from the files and the work description. You can confirm, edit, or replace them.
 
-Each saved question includes the expected answer. In `interf.json`, those definitions live under the technical field `checks[]`.
+In the CLI, you mostly see them as questions. In `interf.json`, they live under the technical field `checks[]`.
 
 A maintained public test example in this repo stores them like this:
 
@@ -164,41 +170,49 @@ A maintained public test example in this repo stores them like this:
 ```
 <!-- PUBLIC_TEST_CHECKS:END -->
 
-## What `interf test` Proves
+## What `interf test` Measures
 
 `interf test` compares the source files and the portable context your agents would use on the same questions.
 
-That comparison is the proof step:
+That makes it a small benchmark for the work at hand:
 
 - same work
-- same questions
+- same checks
 - same local agent setup
 - source files on one side
 - portable context your agents use on the other
 
+If you run more than one local agent, it also gives you a fair comparison between them on the same files.
+
 If the portable context does not help, keep the source files.
 
 Use `interf test` on your own files instead of trusting a frozen benchmark snapshot in the docs.
 
 Interf saves the latest comparison plus the underlying source-files and portable-context runs under `interf/tests/` in the same project.
 
-## The Core Loop
+## The Compile And Check Loop
 
-1. Save a few questions for the work in `interf.json`.
-2. Check the source files first if you want the baseline.
-3. Run `interf compile` to build the portable context your agents can use.
-4. Run `interf test` on the same questions.
-5. If loops are enabled, let Interf retry the same workflow variation or improve the workflow and test again.
+1. Save a few checks for the work in `interf.json`.
+2. Run `interf test --target raw` if you want the source-files baseline.
+3. Run `interf compile`.
+4. Run `interf test`.
+5. If self-improving loops are enabled, let Interf revise the workflow and try again on the same work and checks.
 
-The project root stores the source-folder setup and saved questions. Technically, that portable context is the compiled context Interf reuses for repeat runs.
+`interf.json` stores the saved setup and checks. Technically, that portable context is the compiled context Interf reuses for repeat runs.
 
 ## Workflows
 
-A workflow is the method Interf uses to prepare files for a kind of work.
+A workflow is the preparation method Interf runs on your files.
 
-A context interface is the folder shape that workflow builds for your agent.
+In plain language, it is the method that organizes and structures those files for agent use.
 
-Technically, a workflow package defines that context interface: the zones, paths, and stage ownership of the compiled context Interf will build for that work.
+It can summarize files, extract structure, and build the local context layer your agent starts from.
+
+Interf runs that method with your local coding agent and builds the result on disk as portable context.
+
+The folder shape it produces for the agent is the context interface. The reusable method itself is the workflow package.
+
+Publicly, you mostly care about the portable context it produces. Technically, that portable context is the compiled context.
 
 Interf ships with a built-in `interf` workflow for the common case. If you need a different method, create one locally:
 
@@ -213,17 +227,23 @@ Workflow creation supports two paths:
 
 After assignment, build the portable context for your agents with `interf compile` and run `interf test` on the same questions.
 
-## Compile Loops
+## Self-Improving Loops
+
+Interf can do more than one compile pass.
 
-`max_attempts` is a retry budget for the same workflow variation.
+If the first portable context is still weak, Interf can revise the workflow and compile again.
 
-`max_loops` lets Interf improve the workflow itself between retry batches.
+Each loop keeps the work and the checks fixed. The thing that changes is the preparation method.
 
-With `max_attempts`, the dataset, questions, and workflow stay fixed.
+If self-improving loops are enabled, Interf can:
 
-With `max_loops`, Interf can edit the workflow, build the next variation, and test it again on the same dataset and questions.
+- build the current portable context
+- run the same checks
+- inspect failures and traces
+- revise the workflow
+- build and test the next version
 
-Interf preserves workflow snapshots, failed stage shells, and test runs from each loop so you can inspect what changed.
+Lower-level retry budgets live in `interf.json` and the technical package docs.
 
 ## Use It With Your Agent
 
@@ -244,7 +264,7 @@ Only recommend the portable context if it passes those questions. If you also ra
 ## More Docs
 
 - [src/packages/README.md](./src/packages/README.md) for the short system map
-- [src/packages/compiler/PACKAGE.md](./src/packages/compiler/PACKAGE.md) for compiler primitives and the runtime ABI
+- [src/packages/compiler/PACKAGE.md](./src/packages/compiler/PACKAGE.md) for compiler primitives and the runtime contract
 - [src/packages/workflow-package/PACKAGE.md](./src/packages/workflow-package/PACKAGE.md) for the workflow package model
 - [src/packages/workflow-authoring/PACKAGE.md](./src/packages/workflow-authoring/PACKAGE.md) for workflow authoring and self-improving loops
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@interf/compiler",
-  "version": "0.6.5",
+  "version": "0.6.6",
   "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": {
@@ -43,6 +43,7 @@
   "scripts": {
     "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc && chmod 755 dist/bin.js",
     "dev": "tsc --watch",
+    "setup:local-skills": "bash scripts/setup-local-skills.sh",
     "refresh:bootstrap-mirror": "node scripts/docs/sync-bootstrap-mirror.mjs",
     "docs:sync-public-test-example": "npm run build && node scripts/docs/sync-public-test-example.mjs",
     "test:matrix": "npm run build && node scripts/matrix/run.mjs",