@interf/compiler 0.18.0 → 0.21.0

package/public-repo/plugins/interf/skills/interf/SKILL.md

@@ -0,0 +1,477 @@
+---
+name: interf
+description: "Use when an agent needs to operate Interf from natural language: install or connect to the local Interf engine, manage Preparations, review Build Plans, compile source files into verifiable Artifacts, and read portable context for agent work."
+---
+
+# Interf
+
+Interf prepares data for agent work by compiling source files into verifiable Artifacts and writing portable context that agents can read, so agents work from a verified full picture instead of guessing. It runs locally, shows evidence that the data is ready, and writes portable context that agents can read.
+
+The model is **Instance + Preparation + Artifacts + Build Plan**:
+
+- **Instance** = the engine (a local `interf web` process, or a future cloud endpoint). Owns all preparation state. Same wire shape both ends.
+- **Source** = input files or data. A local folder is the current binding shape; Interf scans it by reference, not by copy.
+- **Preparation** = the durable wrapper for a Source, agent goal, user instructions, requested Artifacts, Build Plan, connected agents, compile runs, readiness evidence, and portable-context location. Lives inside an instance.
+- **Build Plan** = the user-facing plan for how Interf will compile the requested Artifacts from the Source. It can be a draft candidate, selected for one Preparation, or saved/promoted for reuse. The current CLI/API still stores this through `method_id`.
+- **Method package** = the saved reusable Build Plan implementation (`method.json` + Artifact declarations + stage docs). It can be applied to different Sources and Preparations when installed or promoted.
+- **Artifact** = a Build Plan output agents need, such as an atlas, index, timeline, summary set, claim set, or custom file.
+- **Compile run** = one execution of a Preparation. Append-only. Produces portable context.
+
+Agents should think in Artifacts: "what files do I need Interf to compile from this Source so I can do the user's job reliably?"
+
+There is **no workspace concept**. The CLI carries one piece of state: the active connection record.
+
+When Interf MCP tools are available, prefer them over shelling out to the CLI.
+They are API-backed and, in Cowork, can run from the user's device instead of
+the isolated VM shell. Use the CLI examples below as the fallback and as the
+source of command semantics.
+
+## Connection model
+
+The CLI is a thin authorized client of one connected instance. Every mutating command requires a reachable connection. If the active connection is missing or unreachable, the command exits non-zero with:
+
+```text
+Not connected to any Interf instance.
+Start one with `interf web` or `interf web start`, or set --url / `interf login` for a remote one.
+```
+
+There is no hidden auto-start inside mutating commands. Agents must verify a
+connection exists before running mutating commands.
+
+Use `interf` when it is installed. If the command is missing, try
+`npx -y @interf/compiler@latest` for this session. If neither works, stop
+before mutating work and say plainly that this runtime can inspect the source
+and propose Artifacts, but cannot create a Preparation or run Interf until the
+CLI is installed or a reachable Interf instance is connected. Do not probe
+machine-specific install paths in the skill flow.
+
+Be explicit about which runtime you are using:
+
+- **Claude Code local / local terminal**: shell commands run on the user's
+  machine. This is the best current path for full Interf execution.
+- **Claude Code remote / cloud session**: shell commands run in the provider's
+  cloud environment. It can run Interf only if the Source, CLI, engine, and
+  compile-time agent executor are available inside that environment.
+- **Claude Cowork**: shell/code execution may run inside an isolated VM.
+  `127.0.0.1` from that shell may refer to the VM, not the Mac/Windows host.
+  Do not treat VM shell failure as proof that the user's local Interf engine is
+  down. Use a local Interf MCP bridge only when the host has actually launched
+  it on the user's device; otherwise use a local Claude Code / Codex session
+  for execution.
+- **Computer use**: Claude may be able to operate the user's actual desktop
+  apps with permission, but do not rely on screen automation as the primary
+  Interf execution path.
+
+In Cowork, a plain Skill is guidance only. It can teach Claude when to use
+Interf and how to explain requested Artifacts, but it does not by itself give
+Claude a host-level Interf tool. For full Cowork execution, the host must launch
+a local MCP server or desktop extension whose tools call the Interf service on
+the user's machine. The local tool surface should be `interf mcp`, which
+forwards to the same Interf service API as the CLI and UI. A remote connector is
+useful for Interf Cloud or public HTTPS endpoints; it is not the default way to
+reach `127.0.0.1` on the user's machine.
+
+When Interf is unavailable in the current runtime, do not create helper
+scripts, driver files, shell files, or command files for the user to run later.
+Do not write anything into the Source folder. The Source is read-only input.
+Give a short limitation message and the smallest next action instead, such as
+continuing in a local Claude Code / Codex session that can reach the Interf
+engine.
+
+For local or containerized agent sessions:
+
+```sh
+interf web                       # local: foreground server in another terminal
+interf web start                 # local: managed background server for agent sessions
+interf login --url <...>         # remote: writes connection.json
+```
+
+When using the `npx` fallback, replace `interf` in examples with
+`npx -y @interf/compiler@latest`.
+
+## Agent flow
+
+1. **Confirm a connection** — call `interf status` or `interf prep ls`. If the
+   command is missing, try the `npx` fallback once. If the command returns
+   `Not connected...`, start a managed local engine with `interf web start`,
+   then call `interf status` again. If the user already has a visible
+   `interf web` terminal running, do not start another engine; just connect to
+   it. Track whether you started the engine in this turn. Before ending the
+   session, run `interf web stop` if you started it and no compile/test run is
+   still active. Do not run foreground `interf web` inside the agent loop
+   because it blocks.
+   In Cowork, only start or stop Interf from a trusted host-level Interf MCP
+   tool or local desktop extension. Do not ask the VM shell to start a local
+   Mac/Windows engine and then expect the VM's `127.0.0.1` to reach it.
+2. **Propose requested Artifacts in human language** — first inspect what you
+   can about the Source the user gave you: filenames, file types, obvious page
+   counts, section names, and anything that affects the user's question. Treat
+   that as an advisory source profile, not proof that Interf processed the
+   files. Then propose the Artifacts you need before answering.
+
+   Focus on what the agent needs Interf to prepare so it does not miss
+   important source evidence. Do not turn normal analysis choices into blocking
+   questions. If a term is ambiguous but the Source gives reasonable candidates,
+   state the assumption and record the ambiguity as an Artifact check. Ask a
+   clarification only when the Source or task cannot be identified, or when the
+   ambiguity makes the Artifact request impossible to draft.
+
+   If the user invoked `/interf` or explicitly said to use Interf for this
+   task, that is permission to inspect the Source and propose requested
+   Artifacts only. Stop after the proposal. Do not create the Preparation,
+   draft the Build Plan, or compile until the user explicitly says to create,
+   draft, proceed, or do the flow end-to-end.
+
+   Do not show JSON to the user. Do not copy example wording from this skill.
+   Do not use technical labels such as "scope resolver", "evidence map",
+   "market page relevance map", or "comparison evidence". Use short names a
+   knowledge worker understands. Prefer a few meaningful Artifacts, but do not
+   invent a fixed maximum.
+
+   Keep the first proposal compact enough to fit on one screen:
+
+   - one sentence naming the source and what you know about it
+   - one short sentence explaining why Interf helps for this task
+   - one short sentence for any important ambiguity, phrased as an assumption
+   - a compact numbered list of Artifacts
+   - one final line asking the user to approve or edit
+
+   Do not use markdown tables; some chat surfaces collapse them into unreadable
+   text. Do not write Artifact entries as paragraphs. For each Artifact, use a
+   readable mini-card:
+
+   - Artifact name as the numbered line, in bold
+   - `Why it helps:` one short sentence
+   - `Checks:` followed by two or three plain-English bullet points
+
+   Each check must be a complete human-readable sentence, not compressed
+   shorthand. Keep checks concrete enough that a user can say "yes, that is
+   what I wanted." Do not include extracted numbers, chart readings, JSON
+   fields, stage names, or commands in the human proposal. Detailed numbers
+   belong in the compiled Artifacts, not in the proposal.
+
+   Format shape. Replace the placeholders with the actual source and task; do
+   not output angle-bracket placeholders.
+
+   ```text
+   I found <source summary>. For <task>, I should prepare the source first because <risk>.
+   <Optional ambiguity or assumption in one sentence.>
+
+   1. **<Plain-English name>**
+      Why it helps: <short sentence>
+      Checks:
+      - <human-readable check>
+      - <human-readable check>
+
+   If this looks right, tell me to create the Preparation and draft the Build Plan for review. I will stop here until you approve it.
+   ```
+
+   Store the same proposal as structured
+   `requested_artifacts[]` on the Preparation. Store the advisory source
+   interpretation as `source_profile` when useful. `requested_artifacts[]`
+   requires only a `title`; include `purpose`, `checks[]`, and stable `id`
+   values when you know them. Only include exact `output.shape` / typed output
+   checks when you already know the required Build Plan output contract.
+3. **List or create a preparation after the user approves the Artifact proposal** —
+   ```sh
+   interf prep ls                                                    # see what exists
+   interf prep create <id> --source <path> [--about "<agent job>"] \
+     --requested-artifacts-json '<json-array>' \
+     --source-profile-json '<json-object>'
+   interf prep set-method <id> <method-id>                           # select later if needed
+   ```
+   Keep JSON out of the human proposal. Use compact JSON only in the command
+   or API request after the user confirms.
+4. **Draft the Build Plan after the user approves the Artifact proposal unless the user chose a saved one** — for real
+   analytical work, the recommended path is a custom Build Plan for this
+   Preparation. Do not silently bind `interf-default` as the final plan just
+   because it exists. Use `interf-default` only when the user explicitly asks
+   for the default/smoke-test flow or when you need a temporary fallback.
+
+   If the user has not chosen an existing Build Plan, say plainly:
+
+   ```text
+   I'll create the Preparation and draft a custom Build Plan for review. This may take a few minutes. I'll send the review link when the plan is ready; I will not compile until you approve it.
+   ```
+
+   Then run:
+
+   ```sh
+   interf method draft <prep-id> \
+     --task "<agent job>" \
+     --artifacts "<optional extra Artifact notes or change request>" \
+     --ready-when "<proof and coverage the user should trust>"
+   interf runs status <run-id>      # poll until the draft run is terminal
+   interf method show <method-id>   # summarize the drafted Build Plan headlessly
+   ```
+
+   Do not generate custom shell polling loops. In Cowork or any MCP-enabled
+   host, use the Interf MCP `runs_status` tool for status checks. In CLI-only
+   hosts, run `interf runs status <run-id>` as a single command when you need a
+   fresh status, or share the run link and continue without blocking. Avoid
+   asking the user to approve repeated polling commands.
+
+   `interf method draft` automatically receives saved `requested_artifacts[]`
+   and `source_profile` from the Preparation. If you already resolved exact
+   Build Plan output constraints, pass them with
+   `--artifact-requirements-json '<json-array>'`; otherwise let the Build Plan
+   draft agent decide the output paths and checks from the requested Artifacts.
+
+   While the Build Plan is being drafted, do not show the Preparation review
+   link as if the plan is ready. You may show the run link so the user can see
+   activity, but the review link comes after the draft run finishes and the
+   candidate Build Plan is available. After the draft finishes, show the user a
+   short text summary of the Build Plan Artifacts and stages from
+   `interf method show <method-id>` so review works even when they do not open
+   the UI.
+5. **Show the review link before compile by default** — after the Build Plan is
+   drafted, selected, or materially changed, send the user to the Preparation
+   Build Plan review:
+   ```text
+   http://127.0.0.1:4873/?section=preparations&preparation=<prep-id>&preparationTab=build-plan
+   ```
+   Build Plan drafting creates or updates a candidate plan with its own Activity
+   record. A successful draft run selects that Build Plan on the Preparation so
+   the review page is concrete; it still does not mean the user approved a
+   compile run.
+   The thing to review is the requested Artifacts and the Build Plan: which
+   Artifacts will be compiled, why the agent needs them, which stages will
+   build them, and what proof should show the Source was fully processed.
+   Include the same information in the chat as a compact summary: requested
+   Artifacts, stage names, and what each stage writes.
+   Unless the user explicitly asked you to handle the whole flow autonomously,
+   pause here so they can select, remove, or ask you to change the proposed
+   Artifacts, then select the candidate Build Plan for the Preparation before
+   you start a compile run. If the plan should be reused, save/promote it as a
+   Method package. If they ask for changes, draft/improve the Build Plan and
+   show the review link again. If they already granted autonomy, you may select
+   the candidate Build Plan and compile, but still print the Artifacts review
+   link and the compile run link so the user can inspect what happened.
+6. **Compile** — preparation id is positional:
+   ```sh
+   interf compile <prep-id> [--watch] [--quiet] [--idempotency-key <key>]
+   ```
+   Default is async-return: prints `run id`, the artifact `locator`, and current readiness. With `--quiet`, only the locator is printed. With `--watch`, the CLI tails events until the run reaches a terminal state.
+7. **Inspect runs** —
+   ```sh
+   interf runs status <run-id>
+   interf runs ls [--prep <id>]
+   interf runs fetch <run-id> --to <abs-path>
+   interf runs cancel <run-id>
+   ```
+8. **Read the portable context** — for a local engine the locator is a `local-path` you can open directly with any tool. For a remote engine it is a signed `remote-url`; `interf runs fetch` localizes it.
+9. **On `not ready`**, propose Build Plan improvement:
+   ```sh
+   interf method improve <prep-id> \
+     --task "<what needs to change>" \
+     --artifacts "<Artifact changes, if any>" \
+     --ready-when "<proof or coverage changes, if any>"
+   ```
+
+## Connected agents and the role map
+
+Interf treats the agents it can shell out to (Claude Code, Codex, custom CLIs) as a first-class primitive. `GET /v1/instance` reports `agent_count` and `default_agent`; if `agent_count` is `0`, **`interf compile` and `interf test` will hard-error** — install one or register a custom CLI before retrying.
+
+```sh
+interf agents ls                                       # list registered + detected agents
+interf agents use <name>                               # set the active agent (sweeps role map)
+interf agents register <name> --command "<cmd>"        # register a custom CLI
+interf agents unregister <name>                        # remove a custom CLI
+interf agents map <role> <agent>                       # pin a role to an agent
+interf agents unmap <role>                             # fall back to the active agent
+```
+
+Roles are: `extractor`, `summarizer`, `structurer`, `verifier`, `general` (Build Plans / Method packages may declare custom names; the engine treats unknown roles as `general`). Default behavior is single-active-agent — every role maps to the same agent — so existing agent flows do not change unless the user opts into per-role specialization.
+
+## Agent contract — flags every CLI run uses
+
+| Flag | What it controls | When the agent passes it |
+|---|---|---|
+| `--url <url>` | Override the active connection URL for one call. | When the user has multiple instances and wants to target a specific one without changing the active connection record. |
+| `--token <token>` | Override the active bearer token for one call. | Cloud / non-loopback connections only. |
+| `--watch` | Block until the run finishes and tail stages. | Only when the agent must wait inline. Default is async return-with-id. |
+| `--quiet` | Print only the artifact locator on success. | Scripting and agent handoff. |
+| `--idempotency-key <key>` | Sent as `X-Interf-Idempotency-Key`. The instance caches the key for an hour and returns the original run id on retries instead of starting a fresh run. | Whenever the agent might retry the same compile. |
+| `--to <abs-path>` | (`interf runs fetch`) Absolute destination to copy portable context into. | When the agent needs portable context outside the instance. |
+
+## Operating rules
+
+- Use exact preparation ids and Build Plan / Method-package ids returned by the API. Do not invent ids.
+- Always confirm a connection exists before running mutating commands. If no
+  instance is connected, explicitly run `interf web start` for an agent-owned
+  local/container session, ask the user to start foreground `interf web` when
+  they want to own the engine, or connect a remote instance. Do not call
+  foreground `interf web` inside the agent loop because it blocks.
+- For long-running work, use the async default and check status by id (`interf runs status <id>`). Only use `--watch` when the agent must wait inline.
+- Do not call the local HTTP API directly unless Interf explicitly gives an API-integration task. Use CLI commands for normal agent work.
+- If the user invoked `/interf` or explicitly asked to use Interf for a data
+  task, stop after the concise Artifact proposal. Do not create the
+  Preparation or start the Build Plan draft run until the user explicitly
+  approves the proposal or grants autonomy. Print run links only after a run
+  actually starts.
+- Do not create shell scripts or handoff files when the CLI is unavailable.
+  Never write helper files into the Source folder. If you cannot run Interf,
+  say that directly and stop after the Artifact proposal.
+- Treat requested-Artifact and Build Plan review as the default human trust
+  gate. Do not bury the proposed Artifacts in prose; link the user to the
+  Preparation Build Plan review before compile when the Build Plan was newly drafted or
+  materially changed. Drafted Build Plans are candidates until they are selected
+  for the Preparation by the user or by an agent acting under explicit autonomy.
+  Save/promote a useful plan as a Method package when reuse matters.
+- When the user asks for a new analysis over their data, prefer “create
+  Preparation → draft custom Build Plan → show review link → compile after
+  approval.” Only use `interf-default` as the selected Build Plan when the user
+  explicitly asks for the default, asks for a fast smoke test, or accepts that
+  fallback after you explain the tradeoff.
+- When drafting or improving a Build Plan, pass the user's requested Artifact
+  shape and change request in the UI/action form when available. From CLI,
+  pass the request through `--task`, `--artifacts`, and `--ready-when` so the
+  Build Plan run has the actual user intent, not just the Preparation id.
+- Separate proposal from proof. Before compile, you can say what Interf plans
+  to build and what coverage/proof it will check. After compile, you can say
+  which files/pages were processed, what evidence was produced, and whether
+  portable context is ready.
+- In review copy, lead with proposed Artifacts and the stage plan that will
+  build them. The Method package is the technical container; the user's decision
+  is whether those Artifacts and the Build Plan are the right portable context
+  for the agent work.
+- Ask one concise clarification only when the Source or agent goal is missing,
+  or when the ambiguity makes the requested Artifacts impossible to draft. For
+  normal domain ambiguity, state the assumption and make it a check in the
+  requested Artifacts / Build Plan.
+
+## Show your work — always print the run URL
+
+Interf Compiler UI is the user's verification surface. The agent does
+the work; the user clicks a URL to see live trace, events, readiness,
+and proof. **Whenever you kick off a run, print a deep-link to the run
+page in the same message as the run id.** The user should never have
+to navigate the UI manually to find what you just started.
+
+The base URL is whatever `interf status` reports as the connected
+instance (e.g. `http://127.0.0.1:4873` for a local engine,
+`https://api.interf.cloud/...` for cloud). Append query params:
+
+| Param | Value |
+|---|---|
+| `preparation` | the preparation id |
+| `run` | the run id returned by the CLI |
+| `runTab` | optional: `trace` (default), `events`, or `readiness` |
+
+**Example output after `interf compile <prep-id>`:**
+
+```text
+Started compile run <run-id>.
+Watch live: http://127.0.0.1:4873/?preparation=<prep-id>&run=<run-id>
+
+I'll check status in a moment with `interf runs status <run-id>`.
+```
+
+The same pattern applies to readiness-check, Build Plan improvement, and
+Build Plan authoring runs. When a run finishes, print the same URL with
+`runTab=readiness` so the user can click through to the readiness summary.
+
+The agent stays the executor; the URL is the user's "I can see what's
+happening" handle. It also makes failures self-explanatory — when a run
+errors, the user clicks through to the same trace the agent is reading.
+
+## Reading the artifact locator
+
+`interf compile <prep-id>` prints a short multi-line block by default. The portable-context locator looks like one of:
+
+```text
+Portable context: <local-path-returned-by-interf>
+```
+
+```text
+Portable context: https://api.interf.cloud/v1/runs/run_2x4abc.../portable-context
+```
+
+For `local-path`, use the agent's filesystem tools to read the directory. For `remote-url`, use HTTP or `interf runs fetch <run-id> --to <path>`.
+
+## Interf Compiler UI freeform proposal mode
+
+When Interf Compiler UI asks for a proposal, do not run CLI commands. Write a single JSON object to the requested output path. Structured UI controls call the local service directly; this mode is only for freeform planning.
+
+Use these action types:
+
+- `compile`
+- `test`
+- `readiness-check-draft`
+- `method-authoring`
+- `method-improvement`
+- `clarification`
+
+Use `compile` when the user asks to prepare data, build artifacts, refresh portable context, or compile source files for agent work. Set `method` to the selected Build Plan id, and, if the request named one, `preparation` to the preparation id. CLI equivalent: `interf compile <prep-id>`.
+
+Readiness-check proposals always run against the compiled portable context in 0.15+. The legacy `values.mode` field is gone — omit it from `test` proposals.
+
+Return this shape:
+
+```json
+{
+  "action_type": "compile",
+  "method": "method-id",
+  "preparation": "prep-id",
+  "title": "short approval card title",
+  "summary": "one sentence describing which artifacts will be compiled",
+  "assistant_message": "concise explanation for the user",
+  "command_preview": "interf compile prep-id"
+}
+```
+
+For Build Plan drafting proposals, keep requested Artifacts structured in
+`values.requested_artifacts[]` and keep the advisory source summary in
+`values.source_profile`. Do not flatten them into prose only:
+
+```json
+{
+  "action_type": "method-authoring",
+  "preparation": "prep-id",
+  "method": "prep-id-build-plan",
+  "title": "Draft Build Plan",
+  "summary": "Drafts the Build Plan for the requested Artifacts.",
+  "values": {
+    "method_id": "prep-id-build-plan",
+    "task_prompt": "London versus South West annual take-up",
+    "requested_artifacts": [
+      {
+        "title": "Guide to the report",
+        "purpose": "A short note for each page, so the agent knows what is where.",
+        "checks": ["Every page is listed.", "Each page has a plain-English summary."]
+      }
+    ],
+    "source_profile": {
+      "summary": "One 26-page office market report.",
+      "observations": ["No obvious section is called South West."]
+    }
+  }
+}
+```
+
+Use `clarification` only when the request cannot be mapped safely to one Interf action.
+
+## Reference
+
+For exact CLI syntax, run the installed command's help:
+
+```sh
+interf --help
+interf <command> --help
+interf <command> <subcommand> --help
+```
+
+The installed `interf` command is the source of truth. Do not rely on a copied
+command reference when the CLI is available.
+
+Use CLI read commands before asking the user to inspect the UI:
+
+```sh
+interf status
+interf prep show <prep-id>
+interf method show <method-id>
+interf runs status <run-id>
+```
+
+The UI link is for visual proof. The CLI output is for agent-readable status,
+Build Plan review, Artifact status, run errors, proof, and readiness summaries.