@interf/compiler 0.18.0 → 0.22.0

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

@@ -0,0 +1,376 @@
+---
+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, build verifiable context from source files, and read the returned context locator for agent work."
+---
+
+# Interf
+
+Agents miss things in files. Interf builds verifiable context for agents from
+your files. It turns hidden file discovery into traceable artifacts with proof
+of how they were built.
+
+Interf runs locally, shows evidence that the data is ready, and returns a
+context locator agents can read.
+
+## Core Model
+
+- **Instance** = the local engine started by `interf web`, or a future cloud
+  endpoint. It owns all Preparation state.
+- **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, selected Build Plan, Build runs, connected
+  agents, readiness checks, and latest verifiable context.
+- **Requested Artifact** = an output agents need Interf to build, such as an
+  atlas, index, timeline, summary set, claim set, or custom file.
+- **Build Plan** = the user-facing plan for how Interf will build requested
+  Artifacts from the Source. It can be drafted, selected, saved, or improved.
+- **Build run** = one execution of a Build Plan for a Preparation. It records
+  what was processed, what was built, what failed, and whether the output is
+  ready.
+- **verifiable context** = the built output agents use.
+
+Agents should think in requested Artifacts: "what do I need Interf to build
+from this Source so I can do the user's job reliably?"
+
+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 can run from the user's device in hosts that support
+local MCP. Use the CLI examples below as fallback and as the source of command
+semantics.
+
+## Connection Model
+
+Every mutating command requires a reachable Interf instance. 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 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 requested Artifacts, but cannot create a Preparation or run Interf
+until the CLI is installed or a reachable Interf instance is connected.
+
+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
+interf status                    # confirm the active connection
+```
+
+When using the `npx` fallback, replace `interf` in examples with
+`npx -y @interf/compiler@latest`.
+
+## Agent Flow
+
+1. **Confirm a connection**.
+
+   Run `interf status` or `interf prep ls`. If the command returns the
+   connection hint, 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. Track whether you started the
+   engine in this turn. Before ending the session, run `interf web stop` if you
+   started it and no Build run or check run is still active.
+
+2. **Propose requested Artifacts before mutating state**.
+
+   First inspect what you can about the Source: 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.
+
+   If the user invoked `/interf` or explicitly asked to use Interf, that is
+   permission to inspect the Source and propose requested Artifacts only. Stop
+   after the proposal unless the user explicitly says to create, draft, proceed,
+   or do the flow end-to-end.
+
+   Keep the proposal compact:
+
+   ```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 artifact 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.
+   ```
+
+   Do not show JSON to the user. Do not use markdown tables. Do not include
+   extracted numbers, chart readings, schema fields, stage names, or commands in
+   the human proposal. Detailed numbers belong in the built Artifacts.
+
+3. **Create the Preparation after approval**.
+
+   ```sh
+   interf prep ls
+   interf prep create <id> --source <path> [--about "<agent job>"] \
+     --requested-artifacts-json '<json-array>' \
+     --source-profile-json '<json-object>'
+   ```
+
+   Store the approved proposal as `requested_artifacts[]`. Store the advisory
+   source interpretation as `source_profile` when useful. Use compact JSON only
+   in the command or API request after the user confirms.
+
+4. **Draft or select a Build Plan**.
+
+   For real analytical work, prefer a custom Build Plan for the Preparation.
+   Use the default `interf-default` Build Plan only when the user explicitly
+   asks for the default/smoke-test flow or accepts it as a fallback.
+
+   ```sh
+   interf build-plan 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>
+   interf build-plan show <build-plan-id>
+   interf build-plan select <prep-id> <build-plan-id>
+   ```
+
+   Do not generate custom shell polling loops. In MCP-enabled hosts, use the
+   Interf MCP run-status tool. In CLI-only hosts, run `interf runs status
+   <run-id>` as a single command when you need fresh status.
+
+5. **Show the Build Plan review before building by default**.
+
+   After the Build Plan is drafted, selected, or materially changed, send the
+   user to:
+
+   ```text
+   http://127.0.0.1:4873/?section=preparations&preparation=<prep-id>&preparationTab=build-plan
+   ```
+
+   Include a compact chat summary: requested Artifacts, stage names, what each
+   stage writes, and the proof/readiness checks the user should expect. Unless
+   the user granted autonomy, pause here.
+
+6. **Build verifiable context**.
+
+   ```sh
+   interf build <prep-id> [--watch] [--quiet] [--idempotency-key <key>]
+   ```
+
+   Default is async-return: prints the Build 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 and readiness**.
+
+   ```sh
+   interf runs status <run-id>
+   interf runs ls [--prep <id>]
+   interf runs cancel <run-id>
+   interf test <prep-id>
+   ```
+
+8. **On `not ready`, improve the Build Plan**.
+
+   ```sh
+   interf build-plan improve <prep-id> \
+     --task "<what needs to change>" \
+     --artifacts "<Artifact changes, if any>" \
+     --ready-when "<proof or coverage changes, if any>"
+   ```
+
+## Connected Agents
+
+Interf treats the agents it can shell out to, such as Claude Code, Codex, and
+custom CLIs, as connected local agents. `GET /v1/instance` reports
+`agent_count` and `default_agent`. If `agent_count` is `0`, `interf build` and
+`interf test` hard-error until the user installs or registers an agent.
+
+```sh
+interf agents ls
+interf agents use <name>
+interf agents register <name> --command "<cmd>"
+interf agents unregister <name>
+interf agents map <role> <agent>
+interf agents unmap <role>
+```
+
+Roles are `extractor`, `summarizer`, `structurer`, `verifier`, and `general`.
+Build Plans may declare custom names; the engine treats unknown roles as
+`general`. Default behavior is single-active-agent.
+
+## CLI Flags
+
+| Flag | What it controls | When the agent passes it |
+|---|---|---|
+| `--url <url>` | Override the active connection URL for one call. | Multiple instances or remote target. |
+| `--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. |
+| `--quiet` | Print only the artifact locator on success. | Scripting and agent handoff. |
+| `--idempotency-key <key>` | Sent as `X-Interf-Idempotency-Key`. The instance returns the original run id on retries. | Whenever the agent might retry the same build. |
+
+## Operating Rules
+
+- Use exact Preparation ids and Build Plan ids returned by the API. Do not
+  invent ids.
+- Always confirm a connection exists before running mutating commands.
+- For long-running work, use the async default and check status by id. Use
+  `--watch` only 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 or Interf MCP tools for normal agent
+  work.
+- Never write helper files into the Source folder. The Source is read-only
+  input.
+- Treat requested-Artifact and Build Plan review as the default human trust
+  gate.
+- Separate proposal from proof. Before a Build run, you can say what Interf
+  plans to build and what coverage/proof it will check. After a Build run, you
+  can say which files/pages were processed, what evidence was produced, and
+  whether the verifiable context is ready.
+- Ask one concise clarification only when the Source or agent goal is missing,
+  or when ambiguity makes the requested Artifacts impossible to draft. For
+  normal domain ambiguity, state the assumption and make it a check.
+
+## Show Your Work
+
+Interf UI is the user's verification surface. Whenever you start a run, print a
+deep link to the run page in the same message as the run id.
+
+The base URL is whatever `interf status` reports as the connected instance.
+Append query params:
+
+| Param | Value |
+|---|---|
+| `preparation` | the Preparation id |
+| `run` | the run id returned by the CLI |
+| `runTab` | optional: `trace`, `events`, or `readiness` |
+
+Example output after `interf build <prep-id>`:
+
+```text
+Started Build 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>`.
+```
+
+When a run finishes, print the same URL with `runTab=readiness` so the user can
+click through to the readiness summary.
+
+## Reading The Context Locator
+
+`interf build <prep-id>` prints a short multi-line block by default. The context
+locator looks like one of:
+
+```text
+Context: <local-path-returned-by-interf>
+```
+
+```text
+Context: https://api.interf.cloud/v1/runs/run_2x4abc.../verifiable-context
+```
+
+For `local-path`, use the agent's filesystem tools to read the directory. For
+`remote-url`, use HTTP.
+
+## Interf UI Freeform Proposal Mode
+
+When Interf 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:
+
+- `build`
+- `test`
+- `readiness-check-draft`
+- `build-plan-draft`
+- `build-plan-improvement`
+- `clarification`
+
+Use `build` when the user asks to prepare data, build artifacts, or refresh
+verifiable context for agent work. Set `build_plan` to the selected Build Plan
+id if the request named one, and set `preparation` to the Preparation id if the
+request named one. CLI equivalent: `interf build <prep-id>`.
+
+Readiness-check proposals run against verifiable context unless the user asks
+for a source-files baseline.
+
+Return this shape:
+
+```json
+{
+  "action_type": "build",
+  "build_plan": "build-plan-id",
+  "preparation": "prep-id",
+  "title": "short approval card title",
+  "summary": "one sentence describing which artifacts will be built",
+  "assistant_message": "concise explanation for the user",
+  "command_preview": "interf build 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`:
+
+```json
+{
+  "action_type": "build-plan-draft",
+  "preparation": "prep-id",
+  "build_plan": "prep-id-build-plan",
+  "title": "Draft Build Plan",
+  "summary": "Drafts the Build Plan for the requested Artifacts.",
+  "values": {
+    "build_plan_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 build-plan show <build-plan-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.