The loop

This page explains Pilotage's end-to-end workflow for developers evaluating or integrating the extension.

The loop is the set of layers that turns an unfamiliar program-valued tool into a checkable run.

manifest → guides → catalog → validate + plan → execute → trace

Seven layers, five tools, one handshake. The arrow order is the order a zero-knowledge agent first meets the layers, not a pipeline the agent must march through. The agent sits at the center and decides what to call, and when: it may re-read a guide after a diagnostic, re-fetch the catalog after drift, or validate three drafts before executing one.

A schema can show that a tool accepts an object. It cannot, by itself, teach the language inside that object, list the names that exist today, show the effects of a proposed program, or record which branch ran. Pilotage keeps those jobs separate: each layer answers one simple question.

#	Layer	The question it answers
1	manifest	What is here, and where do I go? The welcome card read at the MCP handshake: Languages, capabilities, and loop-tool addresses.
2	guides	How is this language written? The navigable grammar of the target program language.
3	catalog	What names exist right now? The live, versioned vocabulary.
4	validate	Is this program acceptable? A side-effect-free check returning closed-code diagnostics.
5	plan	What would it do? Returned by validate: the pre-run picture of possible behavior, with per-step risk. The Host, not the Model, applies policy to that risk.
6	execute	Do it. Runs the validated program with the validated `catalog_version`.
7	trace	What actually happened? The structured account of the run, with branch decisions on the record.

Plan and trace are layers in their own right: the two halves of accountability. The plan is the promise before the run; the trace is the record after it. One trace, two doors: it rides the execute response; if the run was stored, the same trace can be fetched later by run_id.

Harborview declares its loop tools directly in its real manifest:

{
  "loop": {
    "validate": "validate_flow",
    "execute": "run_flow",
    "trace": "trace_run"
  }
}

Loop tool names are the server's own choice; the keys (validate, execute, trace) are the standard's.

The guide and catalog have fixed access tools: pilotage_get_guide and pilotage_catalog; the manifest itself is always reachable via pilotage_manifest.

The loop improves convergence, not intelligence. A weak program can still be valid. A successful run can still be irrelevant to the user's goal. Validation checks the server's rules; comparing the trace with the original task is what tells the agent the job was actually, and correctly, done. That verified outcome is the loop's product, not one of its layers.

Formal rules: Part II §7, Standard Client loop and Part III §4, Tool surface.

Next: Discovery and the manifest · Guides · The catalog · Execution and traces